tuix-webcomponents 0.0.24 → 0.0.26

package/README.md

@@ -12,8 +12,8 @@ npm i tuix-webcomponents
 
 ### Webbundle version
 
-Webbundle Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-bf814e0@0.89.0.js  
-Styles Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-bf814e0@0.89.0.css
+Webbundle Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-22f6faf@0.91.1.js  
+Styles Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/build-22f6faf@0.91.1.css
 
 ### React
 
@@ -52,10 +52,10 @@ properties are typed with the exported enums, pass `MainVariant.PRIMARY` rather
 than the string `'primary'`.
 
 The wrappers are generated by `scripts/build-react.ts` during `npm run build`
-and land in `dist/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.
+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.
 
 ### Fonts
 
@@ -88,8 +88,10 @@ 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`.
 
-See `docs/src/modules/docs/README.md` for how the site is put together, and
-[the contributing page](docs/content/docs/contributing.mdx) for the workflow.
+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
 
@@ -97,7 +99,8 @@ See `docs/src/modules/docs/README.md` for how the site is put together, and
 npm run build
 ```
 
-writes `dist/`, which is exactly what `npm publish` ships (`files: ["dist"]`):
+writes `package-build/`, and `npm run stage:package` copies that into `dist/`,
+which is what `npm publish` ships (`files: ["dist"]`):
 
 | Path                             | Entry point                                  |
 | -------------------------------- | -------------------------------------------- |
@@ -105,14 +108,50 @@ writes `dist/`, which is exactly what `npm publish` ships (`files: ["dist"]`):
 | `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 inside `prepublishOnly` and `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.
 
-`npm publish` re-runs it through `prepublishOnly`, so a release cannot ship a
-stale `dist/`. `npm run publish:local` packs the same output into a linkable
-`local/` folder for trying it in another project.
+`npm publish` re-runs build and staging through `prepublishOnly`, so a release
+cannot ship a stale `dist/`. `npm run publish:local` packs the same output into
+a linkable `local/` folder for trying it in another project.
+
+## 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
 
@@ -146,10 +185,11 @@ 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.
 
-Note that `dist/` carries two different products, one per CI job: the site
-(`scripts/build.sh`, deployed to S3) and the npm package (`npm run build`, what
-`files` publishes). Both start by clearing it, so locally the last one to run
-wins.
+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 runs in the
+publish job.
 
 
 ## Tooling configs
@@ -157,12 +197,3 @@ wins.
 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`
-