194 lines
9.4 KiB
Markdown
194 lines
9.4 KiB
Markdown
# 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.
|
||
|
||
## APIMart AI generation
|
||
|
||
Create a `.env` file in the application root on the VM (copy `.env.example`):
|
||
|
||
```dotenv
|
||
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:
|
||
|
||
1. 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.
|
||
2. Generate three directions. Review a direction, inspect its changes, then
|
||
select Use reviewed proposal to save it as a recoverable draft revision.
|
||
3. 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.
|
||
4. Preview the design at different sizes and in light/dark mode. Use Components
|
||
for individual recipes and Foundations for exact token values.
|
||
5. 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 total upstream requests (including repairs and temporary-failure retries), 8192 output tokens per attempt and a 60-second total deadline.
|
||
The Studio starts a background generation job and polls with short HTTP requests so the deployment gateway does not need to hold a connection open while APIMart responds. Cancel aborts the job. Results expire after five minutes; a server restart asks the user to generate again without changing their saved draft. Legacy API clients can still use synchronous requests.
|
||
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.
|
||
|
||
Studio 0.1.4 offers 13 presets and comparison choices: Square, Soft, Angular,
|
||
Swiss, Forest, Ocean, Rose, Violet, Ember, Editorial, Terminal, Brutalist and
|
||
Contrast. Each supports light and dark mode. The first valid generated proposal
|
||
appears in the large preview automatically; Review switches alternatives without
|
||
changing the draft. Show current draft returns to it, while Use reviewed proposal
|
||
creates an undoable revision. Create new starts with editable preset tokens.
|
||
|
||
Live APIMart verification on October 19 returned three distinct control-shape
|
||
alternatives in one attempt (0px, 8px and 16px). All three exported canonical
|
||
designs passed validation and compiled in both modes. Broader requests can still
|
||
fail provider or proposal validation; failures preserve the draft and candidates.
|
||
|
||
### 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.4, 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.
|
||
|
||
### Interactive Studio gallery
|
||
|
||
Choose Component gallery in the preview Content menu, then select pages 1–7. Each of the 104 entries has populated sample data and local icons. Controls use their shipped browser functions; charts and workflow graphs include their real runtimes. Sample events appear below each example. Preview links stay in the demo; forms and uploads do not submit data. Switch tracks stay rounded across presets and existing drafts. The editor reports when the preview is rendering, ready or unable to load.
|