tuix-webcomponents 0.91.0 → 0.92.0

package/README.md

@@ -12,41 +12,159 @@ npm i tuix-webcomponents
 
 ### Webbundle version
 
-Webbundle Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-2c60320@0.91.0.js  
-Styles Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-2c60320@0.91.0.css
+Webbundle Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-b6e1565@0.92.0.js  
+Styles Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-b6e1565@0.92.0.css
 
-### React .tsx with SSR
+### React
 
-```typescript jsx
-import { loadFonts } from 'tuix-webcomponents';
+The package ships generated [@lit/react](https://lit.dev/docs/frameworks/react/)
+wrappers, one per element, so nothing has to be wrapped by hand. `@lit/react` is
+a peer dependency:
+
+```bash
+npm i tuix-webcomponents @lit/react
+```
+
+```tsx
+import 'tuix-webcomponents/dist/assets/tuix-styles.css';
+import { TuixButton, TuixText } from 'tuix-webcomponents/react';
+import { IconName, MainVariant, TextSize } from 'tuix-webcomponents';
 
 function App() {
-  
-  // load fonts for SSR and CSR
-  useEffect(() => {
-    loadFonts()
-  }, [])
-  
   return (
-    <tuix-text size="xl" color="primary">Test text</tuix-text>
-  )
+    <>
+      <TuixText size={TextSize.XL}>Test text</TuixText>
+      <TuixButton
+        variant={MainVariant.PRIMARY}
+        iconLeft={IconName.SAVE}
+        onCustomClick={() => console.log('clicked')}
+      >
+        Save
+      </TuixButton>
+    </>
+  );
 }
 ```
 
-### React .tsx without SSR
+The props are the element's own properties, so objects and arrays pass through
+untouched, and each custom event arrives as an `on*` prop. Because those
+properties are typed with the exported enums, pass `MainVariant.PRIMARY` rather
+than the string `'primary'`.
 
-```typescript jsx
-import { loadFonts } from 'tuix-webcomponents';
-loadFonts()
+The wrappers are generated by `scripts/build-react.ts` during `npm run build`
+and land in `package-build/src/react`; `src/react/` is gitignored. Nothing
+about them is hand-kept: the generator reads `src/`, so every element with a
+`@customElement` decorator gets a wrapper, and every event it dispatches gets
+its `on*` prop, typed with the detail type written at the dispatch site.
 
-function App() {
-  
-  return (
-    <tuix-text size="xl" color="primary">Test text</tuix-text>
-  )
-}
+### Fonts
+
+The components render in Rubik, served from the Tuix CDN. The design tokens
+stylesheet imports it, so `import 'tuix-webcomponents/dist/assets/tuix-styles.css'`
+is enough. To start the request earlier, add the link to the document head:
+
+```html
+<link rel="preconnect" href="https://hccdn.tuix.ch" />
+<link rel="stylesheet" href="https://hccdn.tuix.ch/rubik_d444e2375d.css" />
 ```
 
+## Repository setup
+
+```bash
+npm install          # the package
+npm run docs:install # the documentation site, which is its own npm project
+```
+
+`docs/` carries its own `package.json` and lockfile, so a root `npm install`
+does not reach it, and `npm run docs:dev` and `npm run docs:build` fail until
+`docs:install` has run once. `scripts/build.sh` runs it for the same reason
+before it builds the site in CI. Nothing else needs a second install: the
+package build and Storybook run off the root dependencies, and `docs/` resolves
+`lit` and the component sources through them.
+
+## Documentation
+
+The developer documentation site (Fumadocs, statically exported) lives in
+`docs/` as its own npm project:
+
+```bash
+npm run docs:install # once, and whenever docs/package-lock.json changes
+npm run docs:dev     # http://localhost:3000/en/developers
+npm run docs:build   # static export into docs/dist
+```
+
+All three are `npm --prefix docs`, so the same commands run from inside `docs/`
+do the same thing, with one difference: `docs:install` is `npm ci`, a clean
+install of exactly what `docs/package-lock.json` pins. Adding or bumping a
+dependency therefore means an `npm install` inside `docs/`, to write the
+lockfile that `docs:install` then reproduces.
+
+It carries step-by-step integration guides for React/Next.js, Vue and Angular,
+and a page per component with live previews of every variant, in English and
+German. Pages are MDX files in `docs/content/docs/` (`*.mdx` English,
+`*.de.mdx` German), ordered by `meta.json` and `meta.de.json`.
+
+The site is public-facing: it shows and documents the components, and carries no
+contributor workflow. That lives here and in `docs/src/modules/docs/README.md`,
+which covers how the site is put together: content locations, the live previews,
+the framework selector and the locales.
+
+## Building the package
+
+```bash
+npm run build
+```
+
+writes `package-build/`, and `npm run stage:package` copies that into `dist/`,
+which is what `npm publish` ships (`files: ["dist"]`):
+
+| Path                          | Entry point                                                         |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `dist/src/index.js` + `.d.ts` | `tuix-webcomponents`, the custom elements                           |
+| `dist/src/react/index.js`     | `tuix-webcomponents/react`, the wrappers                            |
+| `dist/assets/tuix-styles.css` | `tuix-webcomponents/dist/assets/tuix-styles.css`, the design tokens |
+
+The two steps are separate on purpose: `dist/` is also where the site is
+assembled, so the package build never writes it. Only the staging step does, and
+that runs in `bin/publish.sh`, i.e. in the publish job, after the site has
+already been uploaded from its own job.
+
+The steps behind it: `cem analyze` refreshes `custom-elements.json`,
+`scripts/build-react.ts` regenerates `src/react/`, `tsc -p tsconfig.publish.json`
+compiles both entry points with their declarations, `build:css` renders the
+tokens, and `tsc-esm-fix` adds the `.js` extensions Node's ESM resolver needs.
+
+## Releases
+
+Releases are automatic, from CircleCI. `bin/publish.sh` takes the newest
+`feat(`, `feat!(` or `fix(` subject out of the last ten commits and derives the
+version from it:
+
+| Commit prefix | Bump  |
+| ------------- | ----- |
+| `feat!(`      | major |
+| `feat(`       | minor |
+| anything else | patch |
+
+Commit subjects are linted by commitlint against
+[Conventional Commits](https://www.conventionalcommits.org), so the prefix is
+not optional.
+
+The branch decides the dist-tag, and the two paths differ:
+
+| Branch       | Dist-tag  | Version                                       | Also does                                                                   |
+| ------------ | --------- | --------------------------------------------- | --------------------------------------------------------------------------- |
+| `master`     | `latest`  | bumped from the commit subject, per the table | uploads the web bundle to S3, rewrites the two links below, tags `v<version>` |
+| anything else| `staging` | always a patch bump off `staging`             | uploads the web bundle to S3                                                |
+
+Both paths build the bundle as `build-<short hash>@<version>.{js,css}` and
+upload it, so every deployment is immutable. Only `latest` rewrites the
+`Webbundle Link:` and `Styles Link:` lines under [Usage](#usage) and commits
+them, which is why those two lines are the one place in the repository that
+tracks the current bundle. `docs/scripts/build-bundle-links.ts` reads them at
+docs build time rather than copying the URLs into a page, so the documentation
+cannot fall a release behind.
+
 ## Linting and formatting
 
 To scan the project for linting and formatting errors, run
@@ -75,18 +193,19 @@ To build a production version of Storybook, run
 npm run storybook:build
 ```
 
+That writes `dist/storybook`, which is where the deployed site serves it from.
+The site root is the documentation, and the Storybook sidebar brand links back
+to it. `scripts/build.sh` is what assembles both into `dist/` for CI.
+
+Two builds, two folders, so neither clears the other: the site into `dist/`
+(`scripts/build.sh`: Storybook under `dist/storybook`, the docs export at the
+root) and the npm package into `package-build/` (`npm run build`). `dist/` is
+reused for the package only by `npm run stage:package`, which `bin/publish.sh`
+runs in the publish job.
+
 
 ## Tooling configs
 
 For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project.
 
 If you customize the configuration a lot, you can consider moving them to individual files.
-
-## Local Demo with `web-dev-server`
-
-```bash
-npm start
-```
-
-To run a local development server that serves the basic demo located in `demo/index.html`
-