themelia-react-ui 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,83 @@
+# Installed package and skill setup
+
+Run from the consuming app or one of its subdirectories. Resolve a public
+entrypoint rather than guessing a hoisted node_modules path or importing
+`themelia-react-ui/package.json`, which is not an exported entrypoint. The following
+read-only Node recipe finds the physical package and checks the guidance identity.
+It requires no repository checkout or extra dependency.
+
+```sh
+node --input-type=module <<'JS'
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let root = path.dirname(fileURLToPath(import.meta.resolve('themelia-react-ui')));
+const readJson = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+let manifest;
+while (true) {
+  const file = path.join(root, 'package.json');
+  if (fs.existsSync(file) && (manifest = readJson(file)).name === 'themelia-react-ui') break;
+  const parent = path.dirname(root);
+  assert(parent !== root, 'Cannot locate the installed themelia-react-ui package');
+  root = parent;
+}
+const installedSkill = path.join(root, 'docs/consumer-skill');
+const selectedSkill = process.env.THEMELIA_SKILL_DIR ?? installedSkill;
+for (const file of ['public-api.json', 'tokens.json']) {
+  const installed = readJson(path.join(installedSkill, 'references', file));
+  assert.equal(installed.package, manifest.name, 'Installed guidance package mismatch');
+  assert.equal(installed.version, manifest.version, 'Installed guidance version mismatch');
+  const selected = readJson(path.join(selectedSkill, 'references', file));
+  assert.deepEqual(selected, installed, 'Copied skill is stale; refresh the complete folder');
+}
+if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
+  function compareAssets(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === '.DS_Store') continue;
+      const installed = path.join(directory, entry.name);
+      const selected = path.join(selectedSkill, path.relative(installedSkill, installed));
+      const info = fs.lstatSync(installed);
+      assert(!info.isSymbolicLink(), 'Installed guidance must contain real assets');
+      assert(fs.existsSync(selected) && !fs.lstatSync(selected).isSymbolicLink(), 'Copied skill is stale; missing or linked asset');
+      if (info.isDirectory()) compareAssets(installed);
+      else assert(fs.readFileSync(installed).equals(fs.readFileSync(selected)), 'Copied skill is stale; refresh the complete folder');
+    }
+  }
+  compareAssets(installedSkill);
+}
+console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
+JS
+```
+
+Use the reported root for the bundled finder, stylesheet paths and published
+declarations. Install required peers from that manifest and optional peers for
+the exact imported families from `references/public-api.json`. A copied skill's
+finder reports its own metadata version; it does not inspect the app installation.
+
+To check a copied skill, set `THEMELIA_SKILL_DIR` to its complete directory when
+running the recipe. The comparison checks metadata contents as well as version,
+so stale copies with the same development version are caught. Every installed
+guidance/script/example asset is also compared byte-for-byte; extra app-owned
+files or publisher markers in the copy are not checked. Keep local product policy
+outside the package guidance. Recopy the complete folder after upgrades, and
+read declarations from the installed package.
+
+## Manual skill copying
+
+1. Choose an agent skill destination in the user's configured skills directory,
+   named `themelia-react-ui-consumer`. For Codex the usual destination is
+   `~/.codex/skills/themelia-react-ui-consumer`; honor a configured alternative.
+2. Copy the **entire** installed `docs/consumer-skill` directory, including
+   references, scripts and examples. Do not copy only SKILL.md or merge files from
+   different releases. Preserve an existing user-customized copy before replacing it.
+3. Run the identity recipe with `THEMELIA_SKILL_DIR` pointing to that copy. Invoke
+   `$themelia-react-ui-consumer` or let the agent select it by task context.
+
+Copying into an agent's global skill directory is a separate user-requested
+action; reading these instructions does not perform or authorize it. The npm
+package does not install a skill automatically. Run the consuming app's own
+type/lint/test/build scripts after integration; repository check scripts are not
+installed consumer commands. See [integration](integration.md) for workflow and
+opened-surface verification.

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

@@ -0,0 +1,69 @@
+# Integration
+
+Install required peers from the installed package.json; public-api.json records required/optional peers. Install optional peers for the imported families, including base families such as charts and QR code. Whole-family declaration requirements can exceed a tree-shaken runtime graph; follow the exact family's index and declarations. Import style.css once before overrides; it omits preflight, so the app supplies its reset. Basic controls must not pull in unrelated map/editor/chart dependencies.
+
+Put global resets in the lower-priority `base` layer, or use your framework's layered preflight. The package uses the `theme, base, components, utilities` layer order. Unlayered rules outrank layered component styles regardless of import order; a global `button { font: inherit }` can replace the library's control size and weight. For an app-owned reset:
+
+```css
+@layer theme, base, components, utilities;
+
+@layer base {
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; }
+  button, input, textarea, select { font: inherit; }
+}
+```
+
+Load intentional, scoped app overrides after the package stylesheet. Keep broad resets in `base` so shared control recipes retain ownership of typography and geometry.
+
+UIProvider supplies stable mount-time defaults: explicit prop, provider default, fallback. Per-mount requests/data/callbacks stay on components. ThemeScope from themelia-react-ui/ui-provider places descendant portals inside its CSS boundary. A styled div does not relocate body portals; explicit Base UI portal containers take precedence.
+
+For RTL, pair the native DOM direction with `DirectionProvider` from the same
+entrypoint. Native `dir` owns text flow and logical CSS geometry; the provider
+owns Base UI keyboard navigation and popup positioning. It does not set `dir`.
+Both boundaries must include the controls and their themed portal host:
+
+```tsx
+import { DirectionProvider, ThemeScope } from 'themelia-react-ui/ui-provider';
+
+<DirectionProvider direction="rtl">
+  <ThemeScope dir="rtl"><App /></ThemeScope>
+</DirectionProvider>
+```
+
+Use an app-owned direction value for both. DirectionProvider may be scoped and
+does not replace the single mount-time UIProvider configuration boundary.
+
+Routing comes through href, callbacks or Base UI render composition. React Router is not required. Component chunks preserve client boundaries; pure utilities remain separate.
+
+Use ActionDialog, ActionDrawer, ConfirmDialog and useOverlayVisibility from features/overlays. Pass overlayProps for visibility. onAsyncConfirm awaits the operation; onError reports failure. Do not also pass onConfirm, which takes precedence. Sheet is structural infrastructure, not another workflow API.
+
+PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Supply a stable or useCallback-memoized searchPlaces: PlaceSearchCallback to use your geocoder; it receives PlaceSearchOptions and an AbortSignal and returns Promise<PlaceFeature[]>. Adapt provider results to the existing place shape and OSM identifiers (duplicates are removed by osm_id). Changing provider identity or search options cancels the old lookup and searches the current query. Respect the signal; superseded responses are ignored even if a provider cannot cancel. Keep provider identity stable during ordinary renders. Notification callbacks may be inline. onSearchError reports current failures; the built-in Retry action repeats the lookup and strings.retry localizes its label.
+
+Verify callbacks update actual app state. Cover relevant loading, empty, error, invalid/disabled, cancel/retry and success behavior. Check keyboard entry, dismissal and focus return. Inspect opened content in light/dark and narrow/wide layouts; a closed trigger screenshot cannot approve its popup.
+
+EmailComposer from `themelia-react-ui/features/email-composer` requires the Tiptap optional peers and composes our controls, Card/overlays and editor toolbar. Keep the structured draft separate from prepared delivery output: `onChange` persists an immutable draft proposal; `onSend` receives resolved, sanitized HTML/plain text. Supply pure placeholder resolvers and immutable context, and keep delivery/authentication in the app. Imported HTML retains supported email layout in preview until explicit rich-text conversion. See the [typed email recipe](../examples/email-composer.tsx) and the family catalogue for commands, strings and placement examples.
+Empty recipient groups show our input immediately; the inline plus adds another address, and Cc/Bcc reveal inputs. Template registries, placeholder sets and per-field recipient options accept application-owned `loading`, `error` and `onRetry`; templates additionally expose `onOpenChange` for lazy loading. Loading/error replace stale data. Required recipient/variable resources block preparation and sending until ready; an optional template registry does not block ordinary composing. Preserve the selected template in the supplied registry and let your data client cancel or ignore stale requests.
+
+Keep `value` authoritative and accept `onChange` proposals in the controlled parent. Keep controlled/uncontrolled mode fixed while mounted; remount with a new key for a different message and discard baseline. Callback proposals and delivery payloads are detached from the local draft and from one another. Recipient modes and subject read-only flags constrain user editing; application API commands may still replace these fields. Commit recipient input with Enter, the plus, or blur before an imperative preparation command.
+
+`api.prepare()` rejects validation failures. `api.send()` and `api.discard()` report failures through the alert and `onError` and resolve after handling them; use `onSent` to observe delivery success. `onBeforeSend` may cancel with false or transform the payload under your application's validation policy. Success neither closes nor resets the composer. Unmounting during review prevents delivery; once your `onSend` starts, cancellation belongs to your transport. Unmounting suppresses success/reset/close completion, while failures still reach `onError`.
+
+Server code imports pure helpers from `themelia-react-ui/features/email-composer/engine`, which has no React/editor runtime or client directive. The UI family remains a client boundary; in server-component frameworks, mount it from an app client wrapper and pass callbacks there. `renderEmail` returns sanitized output and unresolved keys; call `validate` before delivering it and enforce your server policy. The optional `createHttpSender` uses JSON POST, same-origin credentials, supplied headers and a timeout; use an app-owned `onSend` transport for other authentication, cancellation or cross-origin requirements. Rich document declarations reference Tiptap types even though the pure engine does not require its runtime.
+
+
+Maintainer enforcement uses @shadcn/lint through Oxlint plus AST/contract checks. These are not runtime dependencies or a published consumer audit CLI. Configure app lint using published utilities/imports; do not copy repository migration-debt allowances. There is no Sass/SASSC pipeline in this Tailwind package.
+
+For opt-in import/anatomy checks, the package now includes a read-only Node script
+using the app's TypeScript dev dependency; see [review and checks](review.md).
+It is not a global CLI or a complete visual auditor. Keep product policies and
+current adapter/page examples in an app-owned reference, separate from this skill.
+
+The maintainer installed-tarball harness proves the basic provider/control/overlay SSR and hydration fixture, pure email preparation without editor peers, controlled table and email-composer workflows, and optional client module initialization. It checks hydration diagnostics and real callbacks in light/dark at narrow/wide widths. Optional module initialization alone does not prove its complete workflow or server-rendering support; verify the features your app uses. `check:all` runs the serial package and curated browser gates; evidence collection is a separate `collect:browser` command. Both are repository maintainer commands, not installed consumer CLIs.
+
+The scoped directory fixture also runs the packaged recipe's query/clear,
+fixed-scope, loading/error/retry, empty and keyboard row-menu callbacks. It checks
+both container content edges without global preflight; Container and DataTable
+own border-box sizing. Stabilize lifecycle inputs as explained in
+[workflows](workflows.md#scoped-directory). These are example/runtime proofs,
+not evidence of an independent agent choosing the same composition.