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.

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:

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:

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:

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:

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:

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.

APIMart AI generation

Create a .env file in the application root on the VM (copy .env.example):

APIMART_API_KEY=your_apimart_key

Restart the app after setting the key. No key goes in the browser or application configuration. The server calls https://api.apimart.ai/v1/chat/completions with model gpt-6-luna, bearer authentication, and stream: false, as described in https://docs.apimart.ai/en/api-reference/texts/general/chat-completions. Model access must be available on your APIMart account. No live provider call is part of the normal build or test suite.

Open /design-studio/ and follow the in-page guide:

In Guided design, enter what you are building and who will use it. Use Next to choose tone, geometry, spacing, surfaces and optional brand references.
Generate three directions. Review a direction, inspect its changes, then select Use reviewed proposal to save it as a recoverable draft revision.
Under Edit with words, request a change, for example “Make the buttons square, use blue as the primary color, and reduce shadows.” Lock colors, geometry or other decisions to keep them unchanged.
Preview the design at different sizes and in light/dark mode. Use Components for individual recipes and Foundations for exact token values.
Open Review & apply and export Theme config or Compiled CSS. Integrate one of those outputs into your application's theme/style configuration. This hosted Studio does not write to deployed application files.

AI generation sends the current design, brief and allowed component capabilities to APIMart when you request generation. The engine validates proposals and locks before offering them for review. Failed requests leave the draft unchanged. Requests allow two concurrent generations and ten starts per minute per server process, with two attempts, 4096 output tokens per attempt and a 20-second deadline. Without APIMART_API_KEY, generation uses local rules and reports that in the UI; local rules do not interpret arbitrary product descriptions. Drafts remain in browser storage; export before clearing browser data or moving to another origin.

The complete check includes mocked provider contract/error/lock tests and a compiled-server deployment check. A real APIMart completion requires your key and model access; it is not claimed by the mocked tests.

HTTPS proxy origin

The app defaults STUDIO_PUBLIC_ORIGIN to https://component.wrnexusjs.dev. If you host this app under another domain, set STUDIO_PUBLIC_ORIGIN to that HTTPS origin in .env. The Studio route normalizes internal HTTP requests to this explicitly configured origin before validating browser Origin headers. It does not derive an allowed origin from untrusted forwarded headers. Local loopback development remains supported. Requests from other origins still return 403.

The deployment check reproduces a browser module request carrying an HTTPS Origin while the proxy forwards it over HTTP, including missing/combined scheme headers. This prevents an apparently loaded editor with empty dropdowns when its module script is rejected before initialization. The browser also reports asset load failures instead of leaving the editor permanently at Checking.

Linux component previews

Studio is pinned to 0.1.1, which resolves component files through the UI registry instead of assuming a filename from the public component name. This fixes Linux lookups such as Input -> input.wrn. Install the committed lockfile before rebuilding and restarting; restarting a deployment still using Studio 0.1.0 cannot fix this error. Tests enforce exact casing for the installed package on all platforms, and the production check renders the composed preview plus every component gallery page.

7.7 KiB Raw Blame History