@alleninstitute/cortex-ui 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,16 @@
 
 A reusable web components library built with [Stencil.js](https://stenciljs.com/), documented with [Storybook](https://storybook.js.org/).
 
-## Getting Started
+- **Using the library in your app?** Start with
+  [Getting Started](https://alleninstitute.github.io/cortex-ui/?path=/docs/getting-started--docs) in the deployed
+  Storybook — React, HTML/other frameworks, CDN, and AI-agent setup.
+- **Contributing a component or a fix?** See [CONTRIBUTING.md](CONTRIBUTING.md). AI agents working in this repo should
+  read [AGENTS.md](AGENTS.md).
+
+## Development Setup
+
+Working on the library itself starts here; [CONTRIBUTING.md](CONTRIBUTING.md) covers the rest of the flow — adding a
+component, the Definition of Done, commit conventions, and opening a PR.
 
 ### Prerequisites
 
@@ -100,11 +109,26 @@ component's maturity is also included in the machine-readable docs below so agen
 
 ## Using the Library
 
-### Script tag
+### Script tag (CDN, no build step)
+
+The package is on the public npm registry, so unpkg and jsDelivr already mirror it. One module script registers every
+component:
+
+```html
+<script
+    type="module"
+    src="https://unpkg.com/@alleninstitute/cortex-ui/dist/cortex-ui/cortex-ui.esm.js"
+></script>
+<link
+    rel="stylesheet"
+    href="https://unpkg.com/@alleninstitute/cortex-ui/dist/fonts.css"
+/>
+```
 
-Add the following to your HTML:
+The stylesheet registers the Allen Institute typefaces — see [Fonts](#fonts).
 
-TBD process
+Pin a version in production (`.../cortex-ui@0.2.0/dist/...`) — an unpinned URL follows the latest release. jsDelivr
+serves the same file from `https://cdn.jsdelivr.net/npm/@alleninstitute/cortex-ui/dist/cortex-ui/cortex-ui.esm.js`.
 
 Then use the components anywhere in your HTML:
 
@@ -128,6 +152,19 @@ import { defineCustomElements } from '@alleninstitute/cortex-ui/loader';
 defineCustomElements();
 ```
 
+#### Fonts
+
+The package bundles the Allen Institute typefaces as WOFF2 — both families, weights 300–700, with italics. Register
+them once, wherever the app imports its global CSS:
+
+```js
+import '@alleninstitute/cortex-ui/fonts.css';
+```
+
+This has to happen at the document level, because a `@font-face` rule declared inside a component's shadow DOM is
+ignored. Once it has, every component picks the font up, since `--cui-font-family-base` already names it (with
+`--cui-font-family-headline` available for titles). Skip the import and the tokens fall back to a system font stack.
+
 #### TypeScript support
 
 The package ships with full type definitions. Import the generated types:
@@ -189,11 +226,18 @@ server by hand with the MCP inspector.
 
 ### Machine-readable docs
 
-Every build regenerates agent-consumable docs, which are also served from the deployed Storybook site root:
+Every build regenerates agent-consumable docs, which are also served from the deployed Storybook site root — so an
+agent with no MCP client can just fetch them:
+
+| File                                                                          | What it is                                                                   |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [llms.txt](https://alleninstitute.github.io/cortex-ui/llms.txt)               | [llms.txt](https://llmstxt.org) index: one line per component, with maturity |
+| [llms-full.txt](https://alleninstitute.github.io/cortex-ui/llms-full.txt)     | Complete plain-text component API and token reference                        |
+| [components.json](https://alleninstitute.github.io/cortex-ui/components.json) | Stencil docs-json component manifest                                         |
+| [tokens.json](https://alleninstitute.github.io/cortex-ui/tokens.json)         | Structured `--cui-*` design tokens with light/dark values                    |
 
-- `docs/llms.txt` / `docs/llms-full.txt` — [llms.txt](https://llmstxt.org) index and full plain-text API reference
-- `docs/components.json` — Stencil docs-json component manifest
-- `docs/tokens.json` — structured `--cui-*` design tokens with light/dark values
+Pointing an agent at the `llms.txt` URL from your project's `AGENTS.md` / `CLAUDE.md` is usually enough to keep it from
+inventing props.
 
 ### Storybook MCP addon
 
@@ -266,90 +310,74 @@ pnpm install
 - **Types or components look stale / missing exports** — the `dist/` output is out of date. Re-run `pnpm build:all` in this repo (or use `pnpm dev:react` + `pnpm dev:stencil` to watch). Nothing works until `dist/` exists.
 - **Do not commit the `link:` lines** in the consuming app — they only make sense on your machine. Swap back to a normal version range before committing.
 
-## Releasing
-
-All three packages are versioned and published **in lockstep** under a single `v<semver>` git tag. They are not
-independently versioned: the React wrappers are generated from the Stencil build and the MCP server bundles a snapshot
-of the generated docs, so a component change ripples through all three. `@alleninstitute/cortex-ui-react` depends on
-`@alleninstitute/cortex-ui` via `workspace:*`, which pnpm rewrites to the exact matching version as it packs.
+## Changelog
 
-Versions and release notes come from [git-cliff](https://git-cliff.org), driven by
-[conventional commit](https://www.conventionalcommits.org) messages, configured in [cliff.toml](cliff.toml).
+`CHANGELOG.md` is generated from [conventional commit](https://www.conventionalcommits.org) messages by
+[git-cliff](https://git-cliff.org), configured in [cliff.toml](cliff.toml). **Commit messages are the release notes**, so
+a sloppy subject line ships to consumers. `chore(release):` commits are skipped, and commits that aren't conventional
+are dropped from the changelog entirely.
 
-### Cutting a release
-
-Releasing is a deliberate, manual step — merging to `main` does not publish.
-
-1. Run the **Release** workflow (`Actions` → `Release` → `Run workflow`) from `main`. Tick **dry-run** first if you want
-   to preview the version and changelog without touching anything.
-2. It derives the next version from the commits since the last tag, verifies the build and tests, bumps every
-   publishable `package.json`, regenerates `CHANGELOG.md`, then commits and pushes `chore(release): v<semver>` plus the
-   `v<semver>` tag.
-3. Pushing that tag triggers the **Publish to npm** workflow, which builds all three packages, publishes them to npm
-   (root first, since the others depend on it) with [provenance](https://docs.npmjs.com/generating-provenance-statements),
-   and opens a GitHub Release with the generated notes.
-
-To preview locally what the next release would be:
+Storybook renders the same file as a top-level **Release Notes** page (`src/docs/ReleaseNotes.mdx`), imported raw from
+`CHANGELOG.md` so the published docs can't drift from the repo.
 
 ```bash
-pnpm release:version      # the version git-cliff would pick
-pnpm changelog:unreleased # the notes for the unreleased commits
-pnpm changelog            # rewrite CHANGELOG.md in full
+pnpm release:version      # the version git-cliff would pick next
+pnpm changelog:unreleased # the notes for the commits since the last tag
+pnpm changelog            # regenerate CHANGELOG.md in full
 ```
 
-### Version numbers
+Versions stay pre-1.0 while components are still `experimental` / `beta`: `cliff.toml` sets
+`breaking_always_bump_major = false`, so while the major is `0` a breaking change bumps the **minor** (`0.1.0` → `0.2.0`)
+rather than jumping to `1.0.0`.
+
+### Prepublish safety
 
-The library is pre-1.0 while components are still tagged `experimental` / `beta`, so `cliff.toml` sets
-`breaking_always_bump_major = false`: while the major is `0`, a breaking change bumps the **minor** (`0.1.0` → `0.2.0`)
-rather than jumping to `1.0.0`. Cutting `1.0.0` is intentional — pass it via the workflow's `version` input.
+Every publishable package runs its own build in `prepack`, so `dist/`, the generated React source, and the MCP server's
+bundled docs snapshot can never be packed or published stale — including from a hand-run `pnpm publish`.
 
-### One-time setup
+## Releasing
 
-Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers): GitHub mints a short-lived OIDC
-token that npm exchanges for publish credentials, so **there is no `NPM_TOKEN` secret**. Requires npm >= 11.5.1 and
-Node >= 22.14.0, which the publish job asserts up front.
+All three packages are versioned and published **in lockstep** under a single `v<semver>` git tag. They are not
+independently versioned: the React wrappers are generated from the Stencil build and the MCP server bundles a snapshot
+of the generated docs, so a component change ripples through all three. `@alleninstitute/cortex-ui-react` depends on
+`@alleninstitute/cortex-ui` via `workspace:*`, which pnpm rewrites to the exact matching version as it packs.
 
-The catch is bootstrapping. npm's trusted-publisher config lives in a package's settings page, so the package has to
-exist before it can be configured — unlike PyPI, npm cannot pre-authorize a name that has never been published
-([npm/cli#8544](https://github.com/npm/cli/issues/8544)). Each of the three packages therefore needs one manual publish
-first:
+Both the version and the release notes are derived from conventional commits — see [Changelog](#changelog).
 
-```bash
-npm login                       # an account with publish rights on @alleninstitute
-pnpm build:all
-pnpm publish --access public --no-git-checks                              # @alleninstitute/cortex-ui
-pnpm --filter @alleninstitute/cortex-ui-react publish --access public --no-git-checks
-pnpm --filter @alleninstitute/cortex-ui-mcp   publish --access public --no-git-checks
-```
+### Cutting a release
 
-Then, for **each** of the three packages, on npmjs.com → package `Settings` → `Trusted Publisher`, select GitHub Actions
-and set:
+Releasing is a deliberate, manual step — merging to `main` does not publish.
 
-| Field             | Value            |
-| ----------------- | ---------------- |
-| Organization      | `AllenInstitute` |
-| Repository        | `cortex-ui`      |
-| Workflow filename | `publish.yml`    |
-| Environment       | _(leave blank)_  |
+1. Run the **Release** workflow (`Actions` → `Release` → `Run workflow`) from `main`. It takes no inputs — the version
+   is always derived from the commits.
+2. It works out the next version from the commits since the last tag, bumps every publishable `package.json`,
+   regenerates `CHANGELOG.md`, then commits and pushes `chore(release): v<semver>` plus the `v<semver>` tag.
+3. Pushing that tag triggers the **Publish to npm** workflow, which builds all three packages, publishes them to npm
+   (root first, since the others depend on it), and opens a GitHub Release with the generated notes.
 
-After that the Release → Publish pipeline runs unattended, and the manual step never has to happen again.
+Preview what a release would produce before running it with `pnpm release:version` and `pnpm changelog:unreleased`.
 
-The one secret that _is_ required:
+### How publishing is authenticated
 
-- **`SERVICE_ACCOUNT_SSH_KEY`** — an SSH deploy key with write access, so the release commit and tag can land on the
-  protected `main` branch. Same secret name and service account as the other Allen Institute repos.
+Already configured; here for when something needs rotating.
 
-### Provenance and repository visibility
+- **npm** — [trusted publishing](https://docs.npmjs.com/trusted-publishers). GitHub mints a short-lived OIDC token that
+  npm exchanges for publish credentials, so **there is no `NPM_TOKEN`**. Each of the three packages has a trusted
+  publisher pointing at `AllenInstitute/cortex-ui` + `publish.yml`, with no environment. Don't add a token.
+- **git** — `SERVICE_ACCOUNT_SSH_KEY` holds the private half of a **write-enabled deploy key** on this repo. Deploy keys
+  can't be shared between repos, so the team Bitwarden entry _"public github ssh keys for github service user"_ keeps
+  one keypair per repo named `<repo>_deploy_key`; `cortex-ui`'s lives there. It can't be `GITHUB_TOKEN` — see the
+  comment in `release.yml`.
+- **branch rules** — `main` requires pull requests, with `DeployKey` as a bypass actor so the release commit can land.
+  This intentionally differs from other repos that bypass via the admin role: scoping it to the deploy key means humans
+  still can't push to `main`.
 
-Trusted publishing works regardless of repository visibility, but
-[provenance attestations require a **public source repository**](https://github.blog/changelog/2023-07-26-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/) —
-npm dropped support for private ones in 2023. `cortex-ui` is currently private, so the publish job sets
-`NPM_CONFIG_PROVENANCE=false` and ships without attestations.
+### Provenance
 
-This is derived from `github.event.repository.private` at run time, not hardcoded: **make the repo public and the next
-release gets provenance automatically**, with no change to the workflow. It is set explicitly in both directions on
-purpose — OIDC otherwise auto-enables provenance based on _package_ visibility, and since these packages are public
-while the repo is not, it would enable provenance and then fail the publish.
+We don't publish provenance attestations. The publish job sets `NPM_CONFIG_PROVENANCE=false`, which is load-bearing
+rather than cosmetic: trusted publishing **auto-enables** provenance, and
+[provenance requires a public source repository](https://github.blog/changelog/2023-07-26-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/) —
+so on this private repo npm would turn it on and then fail the publish. Drop that line only when the repo goes public.
 
 ### If a publish fails partway
 
@@ -359,12 +387,6 @@ re-run Release**; that would only try to cut a second version. Fix the cause, th
 run. The publish step skips any package whose version is already on npm, so a re-run picks up exactly the packages that
 did not make it.
 
-### Prepublish safety
-
-Every package runs its own build in `prepack`, so `dist/`, the generated React source, and the MCP docs snapshot can
-never be published stale — including from a hand-run `pnpm publish`. The publish workflow additionally runs
-`pnpm build:all` up front so a build failure stops the release before any package reaches npm.
-
 ## Project Structure
 
 ```

package/dist/cjs/cortex-ui.cjs.js

@@ -1,10 +1,10 @@
 'use strict';
 
-var index = require('./index-Rxdz0vyq.js');
+var index = require('./index-RBrlguTk.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /*
- Stencil Client Patch Browser v4.43.5 | MIT Licensed | https://stenciljs.com
+ Stencil Client Patch Browser v4.44.0 | MIT Licensed | https://stenciljs.com
  */
 
 var patchBrowser = () => {
@@ -18,7 +18,7 @@ var patchBrowser = () => {
 
 patchBrowser().then(async (options) => {
   await index.globalScripts();
-  return index.bootstrapLazy([["cui-tag.cjs",[[1,"cui-tag",{"label":[1],"variant":[1],"size":[1]}]]]], options);
+  return index.bootstrapLazy([["cui-divider.cjs",[[1,"cui-divider",{"orientation":[513],"spacing":[513],"variant":[1],"importance":[1]}]]],["cui-icon.cjs",[[257,"cui-icon",{"icon":[1],"variant":[1],"importance":[1],"size":[1],"label":[1]},null,{"icon":[{"onIconChange":0}],"label":[{"onLabelChange":0}]}]]],["cui-progress.cjs",[[1,"cui-progress",{"label":[1],"value":[2],"max":[2],"indeterminate":[4],"size":[1],"showValue":[4,"show-value"]}]]],["cui-tag.cjs",[[1,"cui-tag",{"label":[1],"variant":[1],"size":[1]}]]]], options);
 });
 
 exports.setNonce = index.setNonce;

package/dist/cjs/cui-divider.cjs.entry.js

@@ -0,0 +1,49 @@
+'use strict';
+
+var index = require('./index-RBrlguTk.js');
+
+const cuiDividerCss = () => `:host{display:block;--cui-divider-gap:var(--cui-spacing-m);margin-block:var(--cui-divider-gap)}:host([hidden]){display:none}:host([spacing=none]){--cui-divider-gap:0}:host([spacing=small]){--cui-divider-gap:var(--cui-spacing-s)}:host([spacing=large]){--cui-divider-gap:var(--cui-spacing-l)}:host([orientation=vertical]){display:inline-flex;align-self:stretch;min-height:var(--cui-spacing-l);margin-block:0;margin-inline:var(--cui-divider-gap)}.cui-divider{box-sizing:border-box;margin:0;border:none}.cui-divider--horizontal{width:100%;height:var(--cui-border-width-s)}.cui-divider--vertical{width:var(--cui-border-width-s);height:auto;align-self:stretch}.cui-divider--base{background-color:var(--cui-base-divider-primary)}.cui-divider--base.cui-divider--secondary{background-color:var(--cui-base-divider-secondary)}.cui-divider--accent{background-color:var(--cui-accent-divider-primary-default)}.cui-divider--accent.cui-divider--secondary{background-color:var(--cui-accent-divider-secondary-default)}.cui-divider--highlight{background-color:var(--cui-highlight-divider-primary-default)}.cui-divider--highlight.cui-divider--secondary{background-color:var(--cui-highlight-divider-secondary-default)}.cui-divider--info{background-color:var(--cui-info-divider-primary-default)}.cui-divider--info.cui-divider--secondary{background-color:var(--cui-info-divider-secondary-default)}.cui-divider--negative{background-color:var(--cui-negative-divider-primary-default)}.cui-divider--negative.cui-divider--secondary{background-color:var(--cui-negative-divider-secondary-default)}.cui-divider--neutral{background-color:var(--cui-neutral-divider-primary-default)}.cui-divider--neutral.cui-divider--secondary{background-color:var(--cui-neutral-divider-secondary-default)}.cui-divider--positive{background-color:var(--cui-positive-divider-primary-default)}.cui-divider--positive.cui-divider--secondary{background-color:var(--cui-positive-divider-secondary-default)}.cui-divider--warning{background-color:var(--cui-warning-divider-primary-default)}.cui-divider--warning.cui-divider--secondary{background-color:var(--cui-warning-divider-secondary-default)}`;
+
+const CuiDivider = class {
+    constructor(hostRef) {
+        index.registerInstance(this, hostRef);
+        // `orientation` and `spacing` are reflected because they size and space the host's own
+        // box, and only an attribute can reach `:host()` from the stylesheet. `variant` and
+        // `importance` are not: they only colour the rule, which the modifier classes handle.
+        /**
+         * Which way the rule runs. A vertical divider stretches to the height of the flex row
+         * it sits in.
+         */
+        this.orientation = 'horizontal';
+        /** Space reserved on either side of the rule, along the axis it separates. */
+        this.spacing = 'medium';
+        /**
+         * Which intent's `divider` colour the rule is drawn in. `base` is the intent-free rule for
+         * ordinary page chrome; the seven intents tint a divider that sits inside a component
+         * already carrying that intent, such as a rule between rows of a negative-intent alert.
+         */
+        this.variant = 'base';
+        /**
+         * Which of the two `divider` importances the rule is drawn from. Match it to the importance of
+         * the surface the divider sits on — `secondary` on a quiet tint, `primary` on a saturated fill —
+         * rather than treating it as a loudness control: on a secondary surface the primary rule is the
+         * *less* perceivable of the two. For `base`, whose surface is the page itself, `primary` is
+         * simply the stronger of the two rules.
+         */
+        this.importance = 'primary';
+    }
+    render() {
+        return (
+        // A native <hr> carries the separator role to assistive technology for free, and
+        // is the one element that means "boundary" rather than "a box that looks like one".
+        index.h("hr", { key: 'd33f3260a5f708f379428a7d338e6329248f23ff', part: "base", class: {
+                'cui-divider': true,
+                [`cui-divider--${this.orientation}`]: true,
+                [`cui-divider--${this.variant}`]: true,
+                [`cui-divider--${this.importance}`]: true,
+            }, "aria-orientation": this.orientation === 'vertical' ? 'vertical' : undefined }));
+    }
+};
+CuiDivider.style = cuiDividerCss();
+
+exports.cui_divider = CuiDivider;

package/dist/cjs/cui-icon.cjs.entry.js

@@ -0,0 +1,100 @@
+'use strict';
+
+var index = require('./index-RBrlguTk.js');
+
+const cuiIconCss = () => `@charset "UTF-8";:host{display:inline-flex}:host([hidden]){display:none}.cui-icon{display:inline-flex;align-items:center;justify-content:center;line-height:1}::slotted(:not([data-cui-icon-glyph])){display:none}.cui-icon--xxs{font-size:var(--cui-icon-size, var(--cui-font-size-xxs))}.cui-icon--xs{font-size:var(--cui-icon-size, var(--cui-font-size-xs))}.cui-icon--s{font-size:var(--cui-icon-size, var(--cui-font-size-s))}.cui-icon--m{font-size:var(--cui-icon-size, var(--cui-font-size-m))}.cui-icon--l{font-size:var(--cui-icon-size, var(--cui-font-size-l))}.cui-icon--xl{font-size:var(--cui-icon-size, var(--cui-font-size-xl))}.cui-icon--xxl{font-size:var(--cui-icon-size, var(--cui-font-size-xxl))}.cui-icon--display-s{font-size:var(--cui-icon-size, var(--cui-font-size-display-s))}.cui-icon--display-m{font-size:var(--cui-icon-size, var(--cui-font-size-display-m))}.cui-icon--display-l{font-size:var(--cui-icon-size, var(--cui-font-size-display-l))}.cui-icon--base.cui-icon--primary{color:var(--cui-icon-color, var(--cui-base-text-primary))}.cui-icon--base.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-base-text-secondary))}.cui-icon--accent.cui-icon--primary{color:var(--cui-icon-color, var(--cui-accent-text-primary-default))}.cui-icon--accent.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-accent-text-secondary-default))}.cui-icon--highlight.cui-icon--primary{color:var(--cui-icon-color, var(--cui-highlight-text-primary-default))}.cui-icon--highlight.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-highlight-text-secondary-default))}.cui-icon--info.cui-icon--primary{color:var(--cui-icon-color, var(--cui-info-text-primary-default))}.cui-icon--info.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-info-text-secondary-default))}.cui-icon--negative.cui-icon--primary{color:var(--cui-icon-color, var(--cui-negative-text-primary-default))}.cui-icon--negative.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-negative-text-secondary-default))}.cui-icon--neutral.cui-icon--primary{color:var(--cui-icon-color, var(--cui-neutral-text-primary-default))}.cui-icon--neutral.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-neutral-text-secondary-default))}.cui-icon--positive.cui-icon--primary{color:var(--cui-icon-color, var(--cui-positive-text-primary-default))}.cui-icon--positive.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-positive-text-secondary-default))}.cui-icon--warning.cui-icon--primary{color:var(--cui-icon-color, var(--cui-warning-text-primary-default))}.cui-icon--warning.cui-icon--secondary{color:var(--cui-icon-color, var(--cui-warning-text-secondary-default))}`;
+
+const CuiIcon = class {
+    constructor(hostRef) {
+        index.registerInstance(this, hostRef);
+        /**
+         * Semantic colour set. `base` is the intent-free choice for ordinary content and is correct on
+         * a plain page background; the intents are for an icon that sits on that intent's surface.
+         * This is styling, not semantics — never let colour be the only thing conveying meaning.
+         */
+        this.variant = 'base';
+        /**
+         * Which rung of the `text` token family to use. It tracks the surface the icon sits on:
+         * `primary` belongs on that variant's primary surface, `secondary` on its secondary surface or
+         * on a plain background. Pairing an intent's `primary` text with a plain page background is
+         * outside the token system's design and will not be legible.
+         */
+        this.importance = 'secondary';
+        /** Size of the glyph, from the font-size token scale. */
+        this.size = 'm';
+    }
+    connectedCallback() {
+        // Both the glyph and the host's ARIA are applied here rather than from render(): the
+        // glyph has to live in the light DOM for the consumer's document-level Font Awesome CSS
+        // to match it (selectors do not cross a shadow boundary, though @font-face and custom
+        // properties do), and setting the host's ARIA imperatively keeps it out of reach of the
+        // vdom, which on first render would otherwise overwrite a <Host> attribute with the
+        // same-named host *property* whenever a consumer also wrote that attribute in markup.
+        this.syncGlyph();
+        this.syncAria();
+    }
+    onIconChange() {
+        this.syncGlyph();
+    }
+    onLabelChange() {
+        this.syncAria();
+    }
+    /**
+     * Creates or updates the light-DOM glyph. Queries rather than caching a node reference, so it
+     * is idempotent: connectedCallback fires again every time the host is moved in the DOM, and a
+     * cached reference can also go stale (see below).
+     */
+    syncGlyph() {
+        var _a;
+        const existing = this.el.querySelector(':scope > [data-cui-icon-glyph]');
+        // Font Awesome's SVG-and-JS build rewrites our <i> into an <svg> that it owns, and
+        // rebuilds the class list while doing so. Rewriting that node's classes would do nothing,
+        // so drop it and let Font Awesome convert a fresh <i> instead.
+        if (existing && existing.tagName !== 'I') {
+            existing.remove();
+        }
+        let glyph = this.el.querySelector(':scope > i[data-cui-icon-glyph]');
+        if (!glyph) {
+            glyph = document.createElement('i');
+            glyph.setAttribute('data-cui-icon-glyph', '');
+            // The glyph is always hidden in its own right; the host carries the accessible name.
+            glyph.setAttribute('aria-hidden', 'true');
+            this.el.appendChild(glyph);
+        }
+        glyph.className = (_a = this.icon) !== null && _a !== void 0 ? _a : '';
+    }
+    /** An icon is either named or hidden — never both, and never named with an empty string. */
+    syncAria() {
+        var _a;
+        const name = (_a = this.label) === null || _a === void 0 ? void 0 : _a.trim();
+        if (name) {
+            this.el.setAttribute('role', 'img');
+            this.el.setAttribute('aria-label', name);
+            this.el.removeAttribute('aria-hidden');
+            return;
+        }
+        this.el.setAttribute('aria-hidden', 'true');
+        this.el.removeAttribute('role');
+        this.el.removeAttribute('aria-label');
+    }
+    render() {
+        return (index.h("span", { key: '76b54ef28027419bfbb5500c5cf4a88a7d01131e', part: "base", class: {
+                'cui-icon': true,
+                [`cui-icon--${this.variant}`]: true,
+                [`cui-icon--${this.importance}`]: true,
+                [`cui-icon--${this.size}`]: true,
+            } }, index.h("slot", { key: '8c4d13ffa3b1cfe3e4d7d47c29127784d62381ff' })));
+    }
+    get el() { return index.getElement(this); }
+    static get watchers() { return {
+        "icon": [{
+                "onIconChange": 0
+            }],
+        "label": [{
+                "onLabelChange": 0
+            }]
+    }; }
+};
+CuiIcon.style = cuiIconCss();
+
+exports.cui_icon = CuiIcon;

package/dist/cjs/cui-progress.cjs.entry.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var index = require('./index-RBrlguTk.js');
+
+const cuiProgressCss = () => `:host{display:block;--cui-progress-track-color:var(--cui-base-bg-level-2);--cui-progress-indicator-color:var(--cui-accent-surface-primary-default)}:host([hidden]){display:none}.cui-progress{font-family:var(--cui-font-family-base);display:flex;align-items:center;gap:var(--cui-spacing-s)}.cui-progress__bar{flex:1 1 auto;display:block;width:100%;border:none;-webkit-appearance:none;appearance:none;border-radius:var(--cui-border-radius-full);background-color:var(--cui-progress-track-color);box-shadow:inset 0 0 0 var(--cui-border-width-s) var(--cui-base-border-secondary)}.cui-progress__bar::-webkit-progress-bar{border-radius:var(--cui-border-radius-full);background-color:var(--cui-progress-track-color);box-shadow:inset 0 0 0 var(--cui-border-width-s) var(--cui-base-border-secondary)}.cui-progress__bar::-webkit-progress-value{border-radius:var(--cui-border-radius-full);background-color:var(--cui-progress-indicator-color);transition:width var(--cui-transition-base)}.cui-progress__bar::-moz-progress-bar{border-radius:var(--cui-border-radius-full);background-color:var(--cui-progress-indicator-color)}.cui-progress__bar:indeterminate{background-image:linear-gradient(to right, var(--cui-progress-indicator-color), var(--cui-progress-indicator-color));background-repeat:no-repeat;background-size:40% 100%;animation:cui-progress-sweep 1.5s linear infinite}.cui-progress__bar:indeterminate::-webkit-progress-bar{background-image:linear-gradient(to right, var(--cui-progress-indicator-color), var(--cui-progress-indicator-color));background-repeat:no-repeat;background-size:40% 100%;animation:cui-progress-sweep 1.5s linear infinite}.cui-progress__bar:indeterminate::-webkit-progress-value{display:none}.cui-progress__bar:indeterminate::-moz-progress-bar{background-color:transparent}.cui-progress__value{flex:0 0 auto;color:var(--cui-base-text-secondary);font-size:var(--cui-font-size-s);font-weight:var(--cui-font-weight-medium);font-variant-numeric:tabular-nums}.cui-progress--small .cui-progress__bar{height:var(--cui-spacing-xs)}.cui-progress--medium .cui-progress__bar{height:var(--cui-spacing-s)}.cui-progress--large .cui-progress__bar{height:var(--cui-spacing-m)}@keyframes cui-progress-sweep{from{background-position-x:-66.67%}to{background-position-x:166.67%}}@media (prefers-reduced-motion: reduce){.cui-progress__bar::-webkit-progress-value{transition:none}.cui-progress__bar:indeterminate{animation-duration:3s}.cui-progress__bar:indeterminate::-webkit-progress-bar{animation-duration:3s}}`;
+
+const CuiProgress = class {
+    constructor(hostRef) {
+        index.registerInstance(this, hostRef);
+        /** How much of the task is done, clamped to the range `0`–`max`. */
+        this.value = 0;
+        /** The value that counts as complete. */
+        this.max = 100;
+        /**
+         * Animates continuously instead of showing a value. Use it only while the total amount
+         * of work is genuinely unknown — prefer a real `value` whenever the work reports one.
+         */
+        this.indeterminate = false;
+        /** Thickness of the bar. */
+        this.size = 'medium';
+        /** Renders the completed percentage as text beside the bar. Ignored when indeterminate. */
+        this.showValue = false;
+    }
+    /** `max` is only meaningful above zero; anything else falls back to a percentage scale. */
+    get resolvedMax() {
+        return Number.isFinite(this.max) && this.max > 0 ? this.max : 100;
+    }
+    get clampedValue() {
+        if (!Number.isFinite(this.value))
+            return 0;
+        return Math.min(Math.max(this.value, 0), this.resolvedMax);
+    }
+    get percent() {
+        return (this.clampedValue / this.resolvedMax) * 100;
+    }
+    render() {
+        const { indeterminate, showValue } = this;
+        return (index.h("div", { key: '546c0fb27b6e91a1d153d01ae154c272be633b14', part: "base", class: {
+                'cui-progress': true,
+                [`cui-progress--${this.size}`]: true,
+            } }, index.h("progress", { key: '313a769b9ea6c2059816e40c744a74749a55c07b', part: "bar", class: "cui-progress__bar", "aria-label": this.label, max: this.resolvedMax, value: indeterminate ? undefined : this.clampedValue }), showValue && !indeterminate && (index.h("span", { key: '1a2edab01738734b397b426d826cfa2dcd4cf89b', part: "value", class: "cui-progress__value" }, Math.round(this.percent), "%"))));
+    }
+};
+CuiProgress.style = cuiProgressCss();
+
+exports.cui_progress = CuiProgress;

package/dist/cjs/cui-tag.cjs.entry.js

@@ -1,18 +1,18 @@
 'use strict';
 
-var index = require('./index-Rxdz0vyq.js');
+var index = require('./index-RBrlguTk.js');
 
-const cuiTagCss = () => `:host{display:inline-block}.cui-tag{font-family:var(--cui-font-family-base);display:inline-flex;align-items:center;justify-content:center;border-radius:var(--cui-radius-sm);font-weight:var(--cui-font-weight-semibold);white-space:nowrap}.cui-tag--small{padding:var(--cui-spacing-xxs) var(--cui-spacing-sm);font-size:var(--cui-font-size-xs)}.cui-tag--medium{padding:var(--cui-spacing-xs) var(--cui-spacing-md);font-size:var(--cui-font-size-sm)}.cui-tag--default{background-color:var(--cui-accent-bg);color:var(--cui-accent-text)}.cui-tag--highlight{background-color:var(--cui-highlight-bg);color:var(--cui-highlight-text)}.cui-tag--info{background-color:var(--cui-info-bg);color:var(--cui-info-text)}.cui-tag--negative{background-color:var(--cui-negative-bg);color:var(--cui-negative-text)}.cui-tag--neutral{background-color:var(--cui-neutral-bg);color:var(--cui-neutral-text)}.cui-tag--positive{background-color:var(--cui-positive-bg);color:var(--cui-positive-text)}.cui-tag--warning{background-color:var(--cui-warning-bg);color:var(--cui-warning-text)}`;
+const cuiTagCss = () => `:host{display:inline-block}.cui-tag{font-family:var(--cui-font-family-base);display:inline-flex;align-items:center;justify-content:center;border-radius:var(--cui-border-radius-m);font-weight:var(--cui-font-weight-semibold);white-space:nowrap}.cui-tag--small{padding:var(--cui-spacing-xxs) var(--cui-spacing-s);font-size:var(--cui-font-size-xs)}.cui-tag--medium{padding:var(--cui-spacing-xs) var(--cui-spacing-m);font-size:var(--cui-font-size-s)}.cui-tag--accent{background-color:var(--cui-accent-surface-secondary-default);color:var(--cui-accent-text-secondary-default)}.cui-tag--highlight{background-color:var(--cui-highlight-surface-secondary-default);color:var(--cui-highlight-text-secondary-default)}.cui-tag--info{background-color:var(--cui-info-surface-secondary-default);color:var(--cui-info-text-secondary-default)}.cui-tag--negative{background-color:var(--cui-negative-surface-secondary-default);color:var(--cui-negative-text-secondary-default)}.cui-tag--neutral{background-color:var(--cui-neutral-surface-secondary-default);color:var(--cui-neutral-text-secondary-default)}.cui-tag--positive{background-color:var(--cui-positive-surface-secondary-default);color:var(--cui-positive-text-secondary-default)}.cui-tag--warning{background-color:var(--cui-warning-surface-secondary-default);color:var(--cui-warning-text-secondary-default)}`;
 
 const CuiTag = class {
     constructor(hostRef) {
         index.registerInstance(this, hostRef);
         this.label = '';
-        this.variant = 'default';
+        this.variant = 'neutral';
         this.size = 'medium';
     }
     render() {
-        return (index.h("span", { key: 'd2bab55fc1472bb8f004ef648103478070bb4723', class: {
+        return (index.h("span", { key: '35b8ea2176d1923abcda801fee775a9cd46a2fec', class: {
                 'cui-tag': true,
                 [`cui-tag--${this.variant}`]: true,
                 [`cui-tag--${this.size}`]: true,