# 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 one production server. Design Studio is mounted directly at
`/design-studio/` by `app/middleware/design-studio.ts`, so the same route works
with `bun dist/server.js` and with the development server. No extra port or
Studio-specific proxy rule is needed. Your existing reverse proxy should forward
all paths to the normal app port and preserve Host, Origin and X-Forwarded-Proto.
If you installed the older Studio-only nginx location pointing to port 4320,
remove it so `/design-studio/` follows the app's normal proxy route. Validate with
`nginx -t`, then reload nginx. Rebuild and restart the application after updating.
The optional `bun run studio` command is only for running a separate demo server.

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.