@alleninstitute/cortex-ui 0.1.0

package/README.md

@@ -0,0 +1,390 @@
+# Cortex UI – Web Components Library
+
+A reusable web components library built with [Stencil.js](https://stenciljs.com/), documented with [Storybook](https://storybook.js.org/).
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 24
+- pnpm >= 11
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+### Development
+
+Start the Stencil dev server and Storybook as preview playground (live-reload):
+
+```bash
+pnpm dev
+```
+
+#### Stencil only:
+
+```bash
+pnpm dev:stencil
+```
+
+#### Storybook only:
+
+```bash
+pnpm dev:storybook
+```
+
+### Build
+
+Build the component library for production:
+
+```bash
+pnpm build
+```
+
+Build the React wrapper library (`@alleninstitute/cortex-ui-react`):
+
+```bash
+pnpm build:react
+```
+
+Build everything (web components first, then the React wrappers and MCP server that depend on them):
+
+```bash
+pnpm build:all
+```
+
+### Test
+
+Run unit tests:
+
+```bash
+pnpm test
+```
+
+Watch mode:
+
+```bash
+pnpm test:watch
+```
+
+### Lint & Format
+
+```bash
+pnpm lint
+pnpm fmt
+```
+
+### Generate a new component
+
+```bash
+pnpm generate
+```
+
+## Component Maturity
+
+Every component publishes a maturity label — the stability promise its public API makes — shown as a badge at the top
+of its Storybook docs page:
+
+| Label          | What it promises                                                  |
+| -------------- | ----------------------------------------------------------------- |
+| `experimental` | New and unproven; may change or be removed without notice.        |
+| `beta`         | In real use and settling, but may still shift in a minor release. |
+| `stable`       | Committed API; breaking changes require a major version.          |
+| `deprecated`   | Scheduled for removal, with the replacement named in its docs.    |
+
+Check the label before you build against a component. The full explanation lives on the
+[Component Maturity](https://alleninstitute.github.io/cortex-ui/?path=/docs/component-maturity--docs) page, and each
+component's maturity is also included in the machine-readable docs below so agents can read it too.
+
+## Using the Library
+
+### Script tag
+
+Add the following to your HTML:
+
+TBD process
+
+Then use the components anywhere in your HTML:
+
+```html
+<cui-tag
+    variant="positive"
+    label="Active"
+></cui-tag>
+```
+
+### NPM package
+
+```bash
+npm install @alleninstitute/cortex-ui
+```
+
+#### Vanilla JS / framework-agnostic
+
+```js
+import { defineCustomElements } from '@alleninstitute/cortex-ui/loader';
+defineCustomElements();
+```
+
+#### TypeScript support
+
+The package ships with full type definitions. Import the generated types:
+
+```ts
+import { Components } from '@alleninstitute/cortex-ui';
+```
+
+#### React
+
+React consumers should use the dedicated wrapper package `@alleninstitute/cortex-ui-react`, which provides typed React components (with JSX prop/event bindings) generated from the web components.
+
+```bash
+npm install @alleninstitute/cortex-ui-react
+# peer deps: react, react-dom (>= 18)
+```
+
+```tsx
+import { CuiTag } from '@alleninstitute/cortex-ui-react';
+
+function Example() {
+    return (
+        <CuiTag
+            variant="positive"
+            label="Active"
+        />
+    );
+}
+```
+
+## AI Tooling
+
+Cortex UI is built to be agent-friendly. If you (or your coding agent) are building UIs with this library:
+
+### MCP server
+
+`@alleninstitute/cortex-ui-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
+agents list and search components, read full component APIs and design tokens, fetch framework setup guides, and
+validate generated `cui-*` markup before shipping it.
+
+```sh
+# Claude Code
+claude mcp add cortex-ui -- npx @alleninstitute/cortex-ui-mcp
+```
+
+Agents working **inside this repo** get the server from the checked-in [.mcp.json](.mcp.json) instead — no client
+config needed, but it runs from a local build, so build it once first:
+
+```bash
+pnpm build      # writes docs/ (component manifest + tokens + llms*.txt)
+pnpm build:mcp  # compiles packages/mcp/dist and snapshots docs/ into it
+```
+
+That config sets `CORTEX_UI_DOCS_DIR=docs`, so the server reads the generated docs live: a plain `pnpm build` picks up
+your component changes, with no `pnpm build:mcp` and no client restart needed.
+
+See [packages/mcp](packages/mcp/README.md) for the full tool list, config for other MCP clients, and how to drive the
+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:
+
+- `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
+
+### Storybook MCP addon
+
+`pnpm dev` runs Storybook with [`@storybook/addon-mcp`](https://storybook.js.org/addons/@storybook/addon-mcp), which
+exposes a live MCP endpoint at `http://localhost:6001/mcp` for story-aware tooling during development.
+
+## Developing Locally Against a Consuming App
+
+This repo is a **pnpm workspace** with three published packages:
+
+| Package                           | Location                 | What it is                   |
+| --------------------------------- | ------------------------ | ---------------------------- |
+| `@alleninstitute/cortex-ui`       | repo root                | the Stencil web components   |
+| `@alleninstitute/cortex-ui-react` | `packages/react-library` | the generated React wrappers |
+| `@alleninstitute/cortex-ui-mcp`   | `packages/mcp`           | the MCP server for AI agents |
+
+When you want to develop against these packages from another local app (before publishing), link them with pnpm's [`link:` protocol](https://pnpm.io/cli/link). The key gotcha: **`link:` takes a directory path, not the package name** — and the React package's folder is `packages/react-library`, _not_ `cortex-ui-react`.
+
+### 1. Build the packages first
+
+The `link:` targets point at the built `dist/` output, so build before (and after) consuming:
+
+```bash
+# in the cortex-ui repo
+pnpm install
+pnpm build:all
+```
+
+While actively iterating, keep the wrappers rebuilding on change:
+
+```bash
+pnpm dev:react      # tsc --watch for the React wrappers
+# and, in another terminal, rebuild the web components on change:
+pnpm dev:stencil
+```
+
+### 2. Add the `link:` dependencies in the consuming app
+
+In the **consuming app's** `package.json`, add relative paths from that app to each package's directory:
+
+```jsonc
+{
+    "dependencies": {
+        // path to the repo root (the web components package)
+        "@alleninstitute/cortex-ui": "link:<relative-path>/cortex-ui",
+        // path to the React wrapper package directory
+        "@alleninstitute/cortex-ui-react": "link:<relative-path>/cortex-ui/packages/react-library",
+    },
+}
+```
+
+To compute the correct relative path, run this from the consuming app's directory:
+
+```bash
+# web components (repo root)
+node -p "require('path').relative(process.cwd(), '/absolute/path/to/cortex-ui')"
+# React wrappers (note the packages/react-library suffix)
+node -p "require('path').relative(process.cwd(), '/absolute/path/to/cortex-ui/packages/react-library')"
+```
+
+Then install in the consuming app:
+
+```bash
+pnpm install
+```
+
+### Troubleshooting
+
+- **`Failed to resolve ... @alleninstitute/cortex-ui-react`** — the `link:` path is wrong. It must end in `.../cortex-ui/packages/react-library` (the folder), not `.../cortex-ui-react` (the package name). The folder name and package name differ.
+- **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.
+
+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).
+
+### 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:
+
+```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
+```
+
+### Version numbers
+
+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.
+
+### One-time setup
+
+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.
+
+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:
+
+```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
+```
+
+Then, for **each** of the three packages, on npmjs.com → package `Settings` → `Trusted Publisher`, select GitHub Actions
+and set:
+
+| Field             | Value            |
+| ----------------- | ---------------- |
+| Organization      | `AllenInstitute` |
+| Repository        | `cortex-ui`      |
+| Workflow filename | `publish.yml`    |
+| Environment       | _(leave blank)_  |
+
+After that the Release → Publish pipeline runs unattended, and the manual step never has to happen again.
+
+The one secret that _is_ required:
+
+- **`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.
+
+### Provenance and repository visibility
+
+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.
+
+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.
+
+### If a publish fails partway
+
+npm versions are immutable, so a failure between packages leaves the release half-published — say `cortex-ui` at the new
+version but `cortex-ui-react` still at the old one. The tag and changelog are already correct at that point, so **do not
+re-run Release**; that would only try to cut a second version. Fix the cause, then re-run the failed **Publish to npm**
+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
+
+```
+src/
+  components/         # Stencil web components
+    cui-tag/          # Example tag component
+  utils/              # Internal dev helpers
+  index.ts            # Library entry point
+  index.html          # Dev server preview page
+packages/
+  react-library/      # @alleninstitute/cortex-ui-react — generated React wrappers
+    src/
+      components/
+        stencil-generated/  # auto-generated by the Stencil React output target
+      index.ts
+  mcp/                # @alleninstitute/cortex-ui-mcp — MCP server for AI agents
+docs/                 # generated component manifest + AI docs (llms.txt, tokens.json)
+scripts/              # build helpers (generate-ai-docs.mjs)
+.storybook/           # Storybook configuration
+.mcp.json             # registers the MCP server for agents working in this repo
+stencil.config.ts     # Stencil build configuration (incl. React output target)
+pnpm-workspace.yaml   # pnpm workspace definition
+```

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

@@ -0,0 +1,24 @@
+'use strict';
+
+var index = require('./index-Rxdz0vyq.js');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/*
+ Stencil Client Patch Browser v4.43.5 | MIT Licensed | https://stenciljs.com
+ */
+
+var patchBrowser = () => {
+  const importMeta = (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cortex-ui.cjs.js', document.baseURI).href));
+  const opts = {};
+  if (importMeta !== "") {
+    opts.resourcesUrl = new URL(".", importMeta).href;
+  }
+  return index.promiseResolve(opts);
+};
+
+patchBrowser().then(async (options) => {
+  await index.globalScripts();
+  return index.bootstrapLazy([["cui-tag.cjs",[[1,"cui-tag",{"label":[1],"variant":[1],"size":[1]}]]]], options);
+});
+
+exports.setNonce = index.setNonce;

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

@@ -0,0 +1,24 @@
+'use strict';
+
+var index = require('./index-Rxdz0vyq.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 CuiTag = class {
+    constructor(hostRef) {
+        index.registerInstance(this, hostRef);
+        this.label = '';
+        this.variant = 'default';
+        this.size = 'medium';
+    }
+    render() {
+        return (index.h("span", { key: 'd2bab55fc1472bb8f004ef648103478070bb4723', class: {
+                'cui-tag': true,
+                [`cui-tag--${this.variant}`]: true,
+                [`cui-tag--${this.size}`]: true,
+            } }, this.label));
+    }
+};
+CuiTag.style = cuiTagCss();
+
+exports.cui_tag = CuiTag;