themelia-react-ui 2.0.3 → 2.0.4

package/docs/consumer-skill/examples/rhf-transport.tsx

@@ -0,0 +1,28 @@
+/** App-owned result: a callback transport reports an outcome before it finishes. */
+export type SaveOutcome<TValues> =
+  | { ok: true; values: TValues }
+  | { ok: false; errors: Record<string, string | readonly string[]>; message?: string };
+export interface SaveVisitCallbacks<TValues> {
+  onSuccess: (saved: TValues) => void;
+  onError: (errors: Record<string, string | readonly string[]>) => void;
+  onCancel: () => void;
+  onFinish: () => void;
+}
+
+/** Inertia adapter calls onFinish only when its complete visit lifecycle ends. */
+export function awaitCallbackSave<TValues>(
+  values: TValues,
+  visit: (values: TValues, callbacks: SaveVisitCallbacks<TValues>) => void,
+): Promise<SaveOutcome<TValues>> {
+  return new Promise((resolve, reject) => {
+    let outcome: SaveOutcome<TValues> = { ok: false, errors: {}, message: 'The request finished without a saved result.' };
+    try {
+      visit(values, {
+        onSuccess: saved => { outcome = { ok: true, values: saved }; },
+        onError: errors => { outcome = { ok: false, errors }; },
+        onCancel: () => { outcome = { ok: false, errors: {}, message: 'Saving was cancelled. Your draft is kept.' }; },
+        onFinish: () => resolve(outcome),
+      });
+    } catch (error) { reject(error); }
+  });
+}

package/docs/consumer-skill/references/agents-md.md

@@ -6,20 +6,30 @@ Claude Code read; in a project that has only `CLAUDE.md`, paste it there. It
 points agents at this installed skill and states when UI work is done.
 
 ```md
-<!-- themelia-react-ui:start 2.0.3 -->
+<!-- themelia-react-ui:start 2.0.4 -->
 ## UI built with themelia-react-ui
-Before writing UI, read node_modules/themelia-react-ui/docs/consumer-skill/SKILL.md and the
-installed declarations; prefer them over memory. Find the owner for a task with:
+Read the matching node_modules/themelia-react-ui/docs/consumer-skills/<name>/SKILL.md:
+themelia-components: setup, discovery, typed components/forms/workflows;
+themelia-tokenization: semantic themes, typography, spacing/density and portals;
+themelia-composition: business hierarchy, responsive screens and visual repair.
+They share docs/consumer-skill assets. Read installed declarations over memory.
+Find owners, map cooperating subjects, then inspect exact APIs:
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>
-Rules: one Page per route, whose title is the h1. Commands go in header.primaryAction
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <symbol> --import <exact import>
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs <role or root>
+When using Page, it owns the route h1/gutters. Its commands use header.primaryAction
 (one) and ordered header.secondaryActions; destructive ones confirm with ConfirmDialog.
-A record's sections go in header.tabs. Space siblings with Stack/Grid gap; write copy
+Use header.tabs for selected/routed sections; continuous detail sections can stay in
+the body. Space siblings with Stack/Grid gap; write copy
 with Heading/Text and values with Money/Date/Number; use semantic colors; badges stay
 neutral unless they state status; dialogs come only from themelia-react-ui/features/overlays.
 Done means: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
 reports no errors (fix and re-run, at most three rounds), then the app's typecheck, lint
-and tests pass. Hand back each check as run or not run, and every kept warning with
-file:line and its reason.
+and tests pass. Completion also requires inspected narrow/wide light/dark appearance
+and executed relevant interactions, including open/focus/error states. Report source,
+rendered and interaction evidence separately; missing proof is unverified. Give kept
+warnings with file:line and reason.
 <!-- themelia-react-ui:end -->
 ```
 

package/docs/consumer-skill/references/authentication.md

@@ -0,0 +1,42 @@
+# Authentication composition
+
+## Authentication pages
+
+Use `AuthShell` from `themelia-react-ui/layout/auth` for login, sign-in,
+registration, recovery and verification screens. It already renders the main
+landmark, an AuthCard and the title as the page's h1. Give it `title` and
+`description`; adding Page, another main, AuthCard or a repeated heading around
+its form duplicates those owners. `variant="bare"` keeps the shell's rhythm
+on the page surface; `split` adds contextual content through `splitPanel`.
+Use standalone AuthCard only when the application already owns the surrounding
+layout and landmark.
+
+The [password sign-in recipe](../examples/authentication.tsx) exports
+`PasswordSignIn`. It composes AuthForm, FormField, Input and PasswordInput,
+one explicit primary submit action, and AuthFormRow for remember-device and
+recovery controls. FormField associates labels through the control IDs.
+The horizontal Stack renders a native label around Checkbox and its copy:
+the whole label is clickable, and `direction="horizontal"` plus `gap="md"`
+keeps the square beside the text. Do not give that checkbox a separate
+vertical FormField label. AuthFormRow wraps auxiliary controls at narrow widths.
+
+AuthShell footerLinks and AuthFooterLinks accept `renderLink` for the app's
+router. Supply only destinations available to the anonymous visitor and useful
+for this flow, such as recovery or return to the originating application.
+Choose a return destination from trusted application context. Workspace,
+account and administration navigation belongs to the corresponding signed-in
+experience. An application without a relevant return destination can omit it.
+Translations and additional supported authentication methods remain app choices.
+
+The recipe delegates authentication and successful navigation to `onSignIn`.
+It guards duplicate submissions, exposes `aria-busy`, disables editable controls
+while pending, and announces a retryable failure without discarding the input.
+Required email/password controls retain native validation and autocomplete.
+The app owns server validation, field error associations, redirects, session
+handling, cancellation and any superseded-request policy its transport needs.
+Install `react-hook-form` to resolve the imported forms family's declarations
+under strict checking; this recipe does not require its runtime form adapter.
+
+Verify keyboard submit, native labels and password reveal, pending and failed
+sign-in, retry, and the actual anonymous destinations. Inspect the form at narrow
+and desktop widths in light/dark; source checks do not establish wrapping or focus.