tuix-webcomponents 0.0.25 → 0.0.27

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
 
@@ -71,25 +71,46 @@ is enough. To start the request earlier, add the link to the document head:
 There is no `loadFonts()` helper any more: injecting the stylesheet from
 JavaScript reflowed the page once the face arrived.
 
+## 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
-cd docs
-npm install
-npm run dev     # http://localhost:3000/en/developers
-npm run build   # static export into docs/dist
+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`.
 
-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
 
@@ -108,17 +129,44 @@ which is what `npm publish` ships (`files: ["dist"]`):
 
 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.
+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.
 
-`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
 
@@ -152,11 +200,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.
 
-Three builds, three folders, so none of them clears another: the site into
-`dist/` (`scripts/build.sh` — Storybook under `dist/storybook`, the docs export
-at the root), the npm package into `package-build/` (`npm run build`), and the
-dev compile into `build/` (`npm start`). `dist/` is reused for the package only
-by `npm run stage:package`, which runs in the publish job.
+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
@@ -164,12 +212,3 @@ by `npm run stage:package`, which runs in the publish job.
 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`
-