167 lines
7.2 KiB
Markdown
167 lines
7.2 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 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.
|