# WRNexus UI component showcase

The showcase is generated from `packages/ui/component-reference.json`. It stays
synchronized with the current component source rather than maintaining a second
hand-written catalog.

```bash
bun run --cwd examples/component-showcase dev
```

Open `http://localhost:3000`.

## Detail-page coverage

Every current UI component receives a dedicated detail page with:

- an interactive server-rendered playground for every declared prop
- typed boolean, number, array, and object controls
- public component-tag syntax with single-quoted dynamic WRN expressions
- component-specific production use cases when a profile exists
- responsive fallback examples for every remaining component
- copyable `.wrn` source beside every live preview
- complete props, slots, and explicitly declared public events
- live `event.detail` output for interactive components
- previous and next component navigation

The specialized profiles for new and recently repaired components live in:

```text
scripts/showcase-profiles.mjs
```

Update that file to add product-quality examples or public enum options. Do not
infer allowed prop values from implementation comparisons; unrestricted values
such as icon classes, labels, IDs, and URLs must remain free-form inputs.

## Generated files

The generator creates:

```text
app/layouts/showcase.wrn
app/layouts/document.wrn
app/pages/*.wrn
app/pages/components/*.wrn
showcase-manifest.json
```

`showcase-manifest.json` records component, category, demo, prop, slot, and event
coverage and is used by the test suite. Do not hand-edit generated pages.

## Validation

After changing UI components, metadata, profiles, the playground, or showcase
styles, run:

```bash
bun run scripts/generate-ui-component-reference.mjs
bun run --cwd examples/component-showcase generate
bun run --cwd examples/component-showcase test
bun run --cwd examples/component-showcase build
```

The complete local check is:

```bash
bun run --cwd examples/component-showcase check
```

Review representative component pages at mobile, tablet, and desktop widths and
in light, dark, keyboard-only, and reduced-motion modes before publishing.

## Design Studio on the deployed site

The navigation opens `/design-studio/`. It includes guided alternatives, decision
locks, natural-language edits, component recipes, previews and portable exports.
Drafts and incomplete source edits remain in each browser's local storage; use
Export raw draft before clearing browser data or changing the site's origin.
The hosted demo uses local rule generation, needs no AI credentials, and cannot
apply designs to server files or access agent workspaces.

On the VM, pull this repository and use Bun 1.3 or newer:

```sh
git pull --ff-only
bun install --frozen-lockfile
bun run check
PORT=3000 bun run start
```

`start` runs the production component site and an export-only Studio sidecar
bound to loopback port 4320. Include `deploy/nginx-design-studio.conf` inside your
existing nginx server block, retain its existing component-site proxy, validate
with `nginx -t`, then reload nginx. The proxy must preserve `/design-studio/` and
Host, and pass Origin unchanged. If port 4320 is occupied, set DESIGN_STUDIO_PORT
and update the proxy upstream to the same port. Manage the `bun run start`
process using your existing service manager and restart it after each build.

The private `@wrnexus` registry is configured in `.npmrc`. Supply registry
credentials on the VM through its user configuration or secret store; no tokens
are committed. Dependencies are pinned and bun.lock is the deployment lock.
A refreshed package-lock.json is retained for npm tooling, but Bun runs the app.

After deployment, check `/`, a component playground and `/design-studio/`.
Create a draft, generate alternatives, open a preview, export JSON, then reload
and confirm draft recovery. Existing Studio drafts on other origins remain there.