First commit

.gitignore

@@ -0,0 +1 @@
+node_modules/

CODE_OF_CONDUCT.md

@@ -0,0 +1,105 @@
+# Salesforce Open Source Community Code of Conduct
+
+## About the Code of Conduct
+
+Equality is a core value at Salesforce. We believe a diverse and inclusive
+community fosters innovation and creativity, and are committed to building a
+culture where everyone feels included.
+
+Salesforce open-source projects are committed to providing a friendly, safe, and
+welcoming environment for all, regardless of gender identity and expression,
+sexual orientation, disability, physical appearance, body size, ethnicity, nationality, 
+race, age, religion, level of experience, education, socioeconomic status, or 
+other similar personal characteristics.
+
+The goal of this code of conduct is to specify a baseline standard of behavior so
+that people with different social values and communication styles can work
+together effectively, productively, and respectfully in our open source community.
+It also establishes a mechanism for reporting issues and resolving conflicts.
+
+All questions and reports of abusive, harassing, or otherwise unacceptable behavior
+in a Salesforce open-source project may be reported by contacting the Salesforce
+Open Source Conduct Committee at [email protected].
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of gender 
+identity and expression, sexual orientation, disability, physical appearance, 
+body size, ethnicity, nationality, race, age, religion, level of experience, education, 
+socioeconomic status, or other similar personal characteristics.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy toward other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Personal attacks, insulting/derogatory comments, or trolling
+* Public or private harassment
+* Publishing, or threatening to publish, others' private information—such as
+a physical or electronic address—without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+* Advocating for or encouraging any of the above behaviors
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned with this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project email
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the Salesforce Open Source Conduct Committee 
+at [email protected]. All complaints will be reviewed and investigated 
+and will result in a response that is deemed necessary and appropriate to the 
+circumstances. The committee is obligated to maintain confidentiality with 
+regard to the reporter of an incident. Further details of specific enforcement 
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership and the Salesforce Open Source Conduct 
+Committee.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant-home],
+version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html. 
+It includes adaptions and additions from [Go Community Code of Conduct][golang-coc], 
+[CNCF Code of Conduct][cncf-coc], and [Microsoft Open Source Code of Conduct][microsoft-coc].
+
+This Code of Conduct is licensed under the [Creative Commons Attribution 3.0 License][cc-by-3-us].
+
+[contributor-covenant-home]: https://www.contributor-covenant.org (https://www.contributor-covenant.org/)
+[golang-coc]: https://golang.org/conduct
+[cncf-coc]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
+[microsoft-coc]: https://opensource.microsoft.com/codeofconduct/
+[cc-by-3-us]: https://creativecommons.org/licenses/by/3.0/us/

LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright (c) 2020, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,214 @@
-# storybook
+# LWC Storybook
+
+## What is Storybook?
+According to the docuemntation, [Storybook](https://storybook.js.org/), Storybook is a user interface development environment and playground for UI components. The tool enables developers to create components independently and showcase components interactively in an isolated development environment.  
+
+![./docs/screenshot.png](./docs/screenshot.png)
+
+
+## About
+This project offers a sample LWC application, with a library, that shows how to integrate with Storybook. It covers differet aspects of Storybook:  
+
+- Components showcase  
+  Shows the components in action in a dedicated, simple UI (stories).  
+- Components documentation  
+  Provide the full components documentation, which can be generated out of the component source code and/or manually written.  
+- Composition  
+  The application Storybook aggregates the components provided by the dependencies (libraries).  
+- Static deployment  
+  The resulting Storybook instance is deployed to a static server, typically on Github pages, so it becomes easily available.  
+- Testing  
+- Others  
+  There are much more capabilities, like accessibility reporting, ...
+
+
+## Demo project layout
+This project is a mono repo, powered by learna, which currently contains two packages:  
+
+- A reusable library of components, lwc-library  
+- An application, lwc-app, consuming the library  
+
+The demo is based on Storybook version 6.0+ version which implements the composition mechanism, and thus allows the main app to render the stories coming from the library.
+
+
+## Getting started
+
+The sample application is very basic, and not that exiting, but you can execute it with the following commands:  
+
+```sh
+yarn
+yarn build 
+yarn start
+```
+
+More interesting in the Storybook. You can execute the library one, only showing the stories part of the library:  
+
+```sh
+cd packages/lwc-library/
+yarn storybook
+```
+
+Or you can execute it from the application, which will include both the library and the aplication stories:  
+
+```sh
+cd packages/lwc-app/
+yarn storybook
+```
+
+Note: in order for the composition to work, the library's Storybook must be deployed as a static site. If you create your own library, make sure to deploy it using the following commands:  
+
+```sh
+cd packages/lwc-app/
+yarn storybook:deploy-static
+```
+
+### Project commands
+A series of commands is defined for each project within `package.json`. The 2 main commands to know are:  
+
+- `storybook`
+  Generate all the meta-data files, compile the LWC components and run the development server.  
+  This is the command to use at least when running Storybook for the first time. Going forward, and dependening on what changes were made to the project, more optimized commands can be used.  
+- `storybook:deploy`  
+  Build the project, build the static site, and deploy it to Github pages.
+
+
+Here are the other ones:  
+
+- `storybook:build`
+    Generate all the meta-data files, compile the LWC components.  
+- `storybook:meta`
+  Generate the component meta-data files `custom-elements.json`
+- `storybook:buildlwc`
+    Compiles the LWC components and generates `.storybook/build/main-storybook.js`.  
+- `storybook:start`
+  Start the component the Storybook server, assuming that the necessary build steps were completed.
+- `build-storybook`
+  Build the the static site, including the generation of `stories.json`.
+- `deploy-storybook`
+  Deploy the previously generated static site to Github pages.
+
+
+## Projects Setup
+
+### Application bundler
+Storybook is using Webpack as the application bundler. Unfortunately, LWC is generally using Rollup and there is no supported Webpack plugin. As a result, we'll use Rollup to build the components and Webpack to run the application. This has several consequences:  
+
+- There are 2 build steps, one for the components and one for Storybook itself  
+  The `.storybook/` folder contains a rollup configuration that is used to compile the LWC components. The result is a single JS files, generated to `.storybook/build`, that is loaded by Webpack.  
+- The components displayed as part of a story must be custom elements.  
+  Custom elements limit the values to be passed to the components, as HTML only allow string literals as attributes. To pass more complex values, the developer must create wrappers.  
+
+### Storybook folders
+Both the library (lwc-library) and the application (lwc-app) feature 2 new directories:  
+
+- `.storybook`  
+  Contains the Storybook configuration files (main.js, preview.js...) as well as the LWC files needed for Storybook, like the rollup configuration.  
+- `.stories`  
+  Contain all the stories, for all the components. After several discussions, we decided to isolate the stories in their own folder rather than co-locating them with the components. It makes it easier for a developer to find the stories when working on them.  
+  Note that this folder also contains an `index.js` file that loads and register all the components as custom elements.
+
+### Composition
+The main application is exposing the stories defined in the library through the [composition](https://medium.com/storybookjs/storybook-composition-af0da9084fba) mechanism. To enable the composition, the library must be deployed as a static site with a properly generated `stories.json` file. Then, the application can either explicitely include it (see: `main.js - refs`) or imnplicitly if the library it includes features an entry in its `package.json` (automatic loading). This sample project uses the later.
+
+
+## Implementing Storybook
+
+### Creating a story for a component
+As there is no particular support for LWC in Storybook, this project uses the generic Web Component integration. As such, all the components that are exposed within the stories must be registered as custom elements. This is done in `/stories/index.js`.  
+Stories use the [CSF](https://storybook.js.org/docs/formats/component-story-format/) format, using the `html` tag from LitHtml when including the markup. Omitting the tag could change the rendering, particularly in the documentation.
+
+Here is an example:  
+
+``` js
+import { html } from 'lit-html';
+export const default_ = () => html`
+    <hello-greetings></hello-greetings>
+`;
+```
+
+### Documenting Web Components
+Documentation which is a great strengh of Storybook, can be at least partially generated. The WebComponent organization comes with a meta-data format to desbribe web components: [custom-elements.json](https://github.com/webcomponents/custom-elements-json).Warn: this format is not yet a standard and can evolve in the near future. It currently contains enough information to describe a components, its attributes and properties, events, CSS variables...  
+
+Writting or maintaining such a file manually is cumbersome, so we better generate it from the component source files. This tasks is achieved by a third party library: [web-component-analyzer](https://github.com/runem/web-component-analyzer#readme). As Javascript doesn't describe all the meta-data that we need, the source code must be enriched with [JSDoc](https://jsdoc.app/) information. In particular, it supports some web components specific tags describes [here](https://www.npmjs.com/package/web-component-analyzer#%E2%9E%A4-how-to-document-your-components-using-jsdoc). 
+
+**Note**: In order for web components to be recognized by web-component-analyzer, it currently must feature an element tag in its header, like:
+
+```js
+/**
+ * The simpliest, possible Hello World component.
+ * 
+ * @element hello-world
+ */
+export default class World extends LightningElement {
+}
+```
+
+### Story types
+This sample application shows different story types.  
+
+#### Component story
+
+#### Documentation story
+
+#### Static content
+
+### Provided add-ons
+The sample app configures a set of add-ons
+
+- [@storybook/addon-docs](https://www.npmjs.com/package/@storybook/addon-docs)  
+   Docs transforms your Storybook stories into world-class component documentation.
+- [@storybook/addon-knobs](https://www.npmjs.com/package/@storybook/addon-knobs)  
+  Knobs allow you to edit props dynamically using the Storybook UI.  
+- [@storybook/addon-a11y](https://www.npmjs.com/package/@storybook/addon-a11y)  
+  Check the accessibility of a component. It shows any potential issue in a panel.  
+- [@storybook/addon-storysource](https://www.npmjs.com/package/@storybook/addon-storysource)  
+  Storysource show stories source in the addon panel
+- [@storybook/addon-actions](https://www.npmjs.com/package/@storybook/addon-actions)  
+  Display data received by event handlers.  
+- [@storybook/addon-controls](https://www.npmjs.com/package/@storybook/addon-controls)  
+  Controls gives you UI to interact with a component's inputs dynamically, without needing to code.    
+- [@storybook/addon-events](https://www.npmjs.com/package/@storybook/addon-events)  
+  Events allows you to add events for your stories.    
+- [@storybook/addon-jest](https://www.npmjs.com/package/@storybook/addon-jest)  
+  Brings Jest results in storybook.
+- [@storybook/addon-viewport](https://www.npmjs.com/package/@storybook/addon-viewport)  
+  Viewport allows your stories to be displayed in different sizes and layouts in Storybook.
+- [@storybook/addon-backgrounds](https://www.npmjs.com/package/@storybook/addon-backgrounds)  
+  Let a user change the background color within the preview window.  
+- [@storybook/addon-storyshots](https://www.npmjs.com/package/@storybook/addon-storyshots)  
+  StoryShots adds automatic Jest Snapshot Testing for Storybook.
+- [@storybook/addon-links](https://www.npmjs.com/package/@storybook/addon-links)  
+  Links can be used to create links that navigate between stories in Storybook.
+
+
+The WebComponent organization is also coming with some add-ons, like [storybook-addon-web-components-knobs](https://www.npmjs.com/package/storybook-addon-web-components-knobs), but they have not been integrated with this sample project yet.
+
+
+### Testing
+***TODO ...***
+
+
+### Mocking data services
+***TODO ...***
+
+
+### Deploying a static site
+The deployment is done by default to Gihub pages, using [storybook-deployer](https://github.com/storybookjs/storybook-deployer). 
+
+## TODOs
+Yes there are TODOs...  
+
+- Decrease the build time  
+  One solution is to provide a prebuilt-version of Storybook, see: [https://github.com/open-wc/storybook-prebuilt](https://github.com/open-wc/storybook-prebuilt)
+
+- Use the LWC compiler to extract meta-data  
+  The Stencil compiler provides such a feature, although it missed some of the meta-data. The LWC has an RFC for a canonical meta-data format: [https://github.com/salesforce/lwc-rfcs/pull/33/files?short_path=2648c38#diff-2648c38fced96da2e0c183fd293d54eb](https://github.com/salesforce/lwc-rfcs/pull/33/files?short_path=2648c38#diff-2648c38fced96da2e0c183fd293d54eb).  
+
+- Extend web-component-analyzer to better support LWC  
+  [https://github.com/runem/web-component-analyzer/issues/150 ](https://github.com/runem/web-component-analyzer/issues/150)
+  - Deduce the elemebtr name from the directory  
+  - Handle @api and other decorators  
+  - ...
+
+
+

index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html>
+  <head>
+    <title>LWC/Storybook Integration demo</title>
+  </head>
+  <body>
+    Application: <a href="lwc-app">lwc-app</a>
+    Library: <a href="lwc-library">lwc-library</a>
+  </body>
+</html>

lerna.json

@@ -0,0 +1,16 @@
+{
+    "lerna": "2.11.0",
+    "exact": true,
+    "version": "0.18.23",
+    "npmClient": "yarn",
+    "command": {
+        "init": {
+            "exact": true
+        },
+        "version": {
+            "conventionalCommits": true,
+            "message": "chore(release): publish %s @skip-ci@"
+        }
+    },
+    "useWorkspaces": true
+}

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "lwc-wca",
+  "version": "1.6.0",
+  "description": "Sample LWC project to integrate with Web Component Analyzer",
+  "private": true,
+  "license": "BSD-3-Clause",
+  "scripts": {
+    "build": "lerna run build --stream",
+    "start": "lerna run start --scope lwc-app --stream",
+    "clean": "lerna run clean --stream",
+    "test": "lerna run test --stream",
+    "build-static": "lerna run storybook:build-static --stream",
+    "deploy-static": "gh-pages -d static-site"
+  },
+  "devDependencies": {
+    "gh-pages": "3.1.0"
+  },
+  "workspaces": {
+    "packages": [
+      "packages/lwc-library",
+      "packages/lwc-app"
+    ]
+  }
+}