@jini-ai/ui-kit 0.0.0-stage → 0.1.0

package/docs/spec/behavior.spec.md

@@ -0,0 +1,49 @@
+Spec ID: SPEC-JINI-UI-KIT-BEHAVIOR
+Version: 1.0.0
+Last Edited: 2026-10-03
+Hash: sha256:782897964f3356bc26f737eaa2be50dcd68cd3258d8a7802990211ae09e79cb5
+spec_mode: implementation_spec
+
+# UI-kit behavior
+
+## Resolution and requirements
+
+Every implemented component resolves to an injected override or its native default. Missing providers use native defaults. Partial kit creation ignores explicit undefined and preserves defaults. Strict kit creation requires all 16 components. Extension carries forward base overrides; unrelated components keep their native implementation. Requirements validate contract compatibility and implemented status before rendering provider children.
+
+Duplicate package copies share the actual React context object through `Symbol.for('@jini-ai/ui-kit/react/context@1')` on globalThis. Development version skew produces a warning. The host supplies a compatible React runtime.
+
+## Attrs and controls
+
+Opaque attrs are forwarded to the declared focus target, preserving host agent metadata, labels, and part identity. Core control state still governs disabled/value behavior. Button pending or disabled suppresses presses. Text and checked controls are controlled and notify changes through their supplied ports. Select preserves native select semantics through an HTMLSelectElement; a custom adapter may keep a synchronized native select.
+
+Tabs use roving tab focus, skip disabled tabs, and implement left/right/Home/End navigation with labelled panels. Menu uses enabled items for up/down/Home/End navigation; Escape restores trigger focus, Tab closes, and pointer interaction outside closes. Tooltip opens on focus/hover, closes on blur/leave/Escape, and associates its content with the trigger. Notices and toasts expose status/alert roles according to tone. Spinners have an accessible loading label.
+
+## Dialog and confirmation
+
+Native Dialog opens with showModal where supported, associates its title, and restores the connected opener when closed. The non-browser fallback sets an open attribute. Pending Dialog blocks close button, native cancel, and backdrop dismissal.
+
+Confirmation safety is framework-free. Each invocation reads current policy; stale callbacks cannot bypass a subsequent pending/open update. Confirmation sets executing synchronously before invoking the action, preventing duplicate calls in the same render frame. While executing or pending, confirmation and all dismissal reasons are refused. Closed confirmation refuses actions. Agent confirmation is refused when agentMayConfirm is false.
+
+The React facade supplies guarded handlers and prop bags to the chosen view. Default actions use the host's Button override. Cancel receives initial focus. Cancel labels communicate that no action occurs. Confirmation's accessible label includes action, title, and consequence. Danger defaults to "cannot be undone"; warning defaults to "changes access, but is reversible"; a supplied consequence replaces the default. Human-only confirmation withholds its agent handle while leaving human action available.
+
+A rejected async action shows the facade's errorLabel or a generic retry message. Execution clears in finally; the host retains control of open state and closing after success.
+
+## Development guard
+
+When a ConfirmDialog or Button override is used, the development guard inspects committed DOM after effects: frame presence/overlay ownership, alertdialog and title semantics, visible focusable action parts, forwarded attrs, pending disabled state, cancel-first focus, human-only agent metadata, and consequence label. Violations are recorded and logged. Default fallback marks ConfirmDialog failed and renders the native frame with native actions, so a broken Button override cannot break the fallback again. Warn mode retains the override; off mode bypasses checks and fallback. Checks are not run in production.
+
+The guard observes the mounted implementation; a shape-compatible TypeScript component is insufficient evidence of conformance. jsdom cannot prove top-layer, layout, or native browser focus trapping.
+
+## Overlays and toast lifetime
+
+A provider uses its supplied overlayContainer or creates an owned body child and removes it on unmount. Dialog, ConfirmDialog, and ToastRegion render into the resolved overlay. Before a container exists, Overlay renders inline.
+
+A toast service owns a queue, stable snapshots between updates, subscribers, and dismissal timers. Pushing an existing id replaces its prior message/timer. The default duration is 5000 ms; zero or negative duration disables auto-dismissal. Dismissal removes the message and timer. Disposal cancels all timers, clears messages, emits the cleared snapshot, then clears listeners. Services never share a global queue. Providers dispose only services they created. Hosts mount ToastRegion explicitly.
+
+## Conformance evidence
+
+Conformance scenarios are data with a React driver. Default execution skips tagged browser-only cases and reports those skips. This behavior contract does not claim that tests or a browser runner passed; delivery evidence must name actual commands/results separately.
+
+## Handoff
+
+Inputs: root controller/toast rules and React/native implementation. Output: v1 resolution, safety, navigation, overlay, and lifetime behavior. Risks: custom library adapters and browser modal behavior require host/browser validation. Next assignee: consumer migration owner, then browser validation owner.

package/docs/spec/errors.spec.md

@@ -0,0 +1,41 @@
+Spec ID: SPEC-JINI-UI-KIT-ERRORS
+Version: 1.0.0
+Last Edited: 2026-10-03
+Hash: sha256:5bd54392775eefa59554cb54e724b629ab7e60bcbc33c44b4317d4de01786fd9
+spec_mode: implementation_spec
+
+# UI-kit errors and refusals
+
+## Configuration errors
+
+`KitConfigError` extends Error, sets name `KitConfigError`, code `KIT_CONFIG`, and retains readonly string issues. Its message begins `Invalid UI kit:` and joins issues with semicolons.
+
+| Trigger | Outcome |
+|---|---|
+| Incompatible contract or unsupported range syntax | KitConfigError from assertKitContract/needs/factories/provider requirement validation |
+| Planned or unknown required component | KitConfigError from needs or provider requirement validation |
+| Override value is neither a function nor a recognized React exotic component | KitConfigError from createKit |
+| Strict kit misses an implemented component | Compile-time error for typed callers; KitConfigError at runtime |
+| useToast without a provider service | KitConfigError |
+| ToastRegion without a supplied or provider service | KitConfigError |
+| push after toast disposal | Error with message `Toast service is disposed` |
+| Default React conformance driver without DOM | Error with message `React conformance requires a DOM environment` |
+| includeBrowser with default React driver | Error with message `Browser cases require a real browser driver` |
+
+Factory validation checks component shape at a coarse level; it does not prove mounted behavior. This is why conformance scenarios and the development confirmation guard exist.
+
+## Action refusals and callback failures
+
+A blocked confirmation or dismissal returns false and invokes no action callback. Pending, executing, and closed states fail closed. Agent confirmation additionally requires agentMayConfirm permission. These are policy refusals, not thrown errors.
+
+The pure controller propagates an onConfirm rejection while releasing its executing latch in finally. The React facade catches that rejection, renders errorLabel or `The action failed. Please try again.`, and releases React pending state while mounted. The host owns remediation and retries. The pure dismissal path invokes the onCancel port directly; a thrown callback error propagates.
+
+## Guard diagnostics
+
+Mounted confirmation violations append a component/reasons record to the kit and log a conformance error. Default guard fallback replaces the confirmation frame and actions with native implementations. Warn retains the faulty view while recording diagnostics. Off suppresses guard inspection and replacement. Development version skew emits console.warn; it does not silently create a separate provider context.
+
+No guard mode changes server-side authorization or action-port permissions. Runtime diagnostics do not represent a production security boundary.
+
+## Handoff
+
+Inputs: needs.ts, toast.ts, pure confirmation controller, React confirmation hooks/guard/context. Output: actual throw/refusal/diagnostic surface. Risk: host port exceptions outside the facade remain host responsibilities. Next assignee: consumer integration owner.

package/docs/spec/state.spec.md

@@ -0,0 +1,45 @@
+Spec ID: SPEC-JINI-UI-KIT-STATE
+Version: 1.0.0
+Last Edited: 2026-10-03
+Hash: sha256:da582ff8b4eb325d546c0abf1bc4e497612350cc83a39ed6cf9f527ab9e12c73
+spec_mode: implementation_spec
+
+# UI-kit state and ownership
+
+## Contract and kit state
+
+The const spec is the source for implemented component names and parts. Contract 1.0.0 is independent of package 0.1.0. Component maps, overrides, and top-level kit objects are frozen. Each ResolvedKit retains mutable violations and failed-component collections for diagnostics. describeKit copies violation reasons into its report.
+
+The global context slot stores one React context and the set of observed package versions for contract major 1. Providers supply per-tree kit/agent/overlay/toast/cancel-label/guard values. Absent providers use native component defaults without an available toast service.
+
+## Confirmation transition model
+
+| Current policy/state | Request | Result |
+|---|---|---|
+| Closed | Confirm/dismiss | Refused |
+| Open, ready | Dismiss any reason | Invoke cancel and return true |
+| Open, ready | Confirm human | Set executing; invoke action; release in finally |
+| Open, ready, agentMayConfirm false | Confirm agent | Refused |
+| Open, pending | Confirm/dismiss | Refused |
+| Executing | Confirm/dismiss | Refused |
+| Action rejects | React facade completion | Error visible, execution released |
+
+The pure controller stores only the executing latch; current policy arrives through read on every request. The React layer stores execution/error presentation and keeps the latest props in a ref. Public open/pending props remain host-owned. The controller does not close a dialog after success or mutate host policy.
+
+Opening captures the opener and focuses cancel. Closing attempts focus restoration to a still-connected opener. A development violation records kit diagnostic state; fallback chooses native frame/actions on rerender. Off mode ignores failed-kit fallback state.
+
+## Local navigation
+
+Tabs selected value is host-owned; the native implementation derives its active enabled item and notifies value changes. Menu and Tooltip open state is local to each mounted component. Text/checked controls are controlled by their host values and change ports.
+
+## Toast state
+
+Each service owns immutable message snapshots, listeners, timers, sequence ids, and disposed state. Push/remove emits changes; a same-id push replaces the existing message. The injected scheduler owns timing. dispose clears owned timers and messages; future push throws. A provider-created service follows provider lifetime. Injected services follow host lifetime, including disposal.
+
+## Overlay ownership
+
+A supplied overlay node is host-owned and never removed by the provider. A generated overlay node is provider-owned and removed on cleanup. Provider overlay state starts null unless supplied; portal rendering becomes available after mounting. Root operations require no DOM.
+
+## Handoff
+
+Inputs: root state rules, kit/context/provider/confirmation/navigation hooks. Output: state ownership and transitions. Risks: hosts must synchronize controlled values and manage injected service/container lifetimes. Next assignee: consumer migration owner.

package/docs/spec/ui.spec.md

@@ -0,0 +1,49 @@
+Spec ID: SPEC-JINI-UI-KIT-UI
+Version: 1.0.0
+Last Edited: 2026-10-03
+Hash: sha256:d216284ad80f3e37d8d728888a5edece24bbf0c4a64bc8567518e5b05f683be4
+spec_mode: implementation_spec
+
+# UI-kit UI contract
+
+## Implemented surface and focus targets
+
+| Component | Required target and semantics |
+|---|---|
+| Button, IconButton | Button; disabled/pending blocks action; IconButton has accessible label |
+| TextField | Labelled input with controlled value |
+| TextArea | Labelled textarea with controlled value |
+| Select | Labelled HTMLSelectElement, visible or synchronized in an adapter |
+| Checkbox | Labelled checkbox input |
+| Switch | Labelled checkbox input with switch role |
+| Dialog | Titled dialog; close action; pending blocks dismissal; opener restoration |
+| ConfirmDialog | Alertdialog; initial cancel focus; guarded actions; consequence label |
+| Tabs | Active tab receives attrs; tablist/tab/labelled panel semantics and roving focus |
+| Menu | Trigger receives attrs; menu/menuitem semantics and roving focus |
+| Toast | Status or alert root; optional dismiss button; ToastRegion is a polite live region |
+| Tooltip | Focusable trigger receives attrs and described-by association |
+| Notice | Status or alert root |
+| Spinner | Labelled status root |
+| Badge | Text root |
+
+Opaque attrs must reach the documented target, not a decorative wrapper. They can carry data-agent-* and aria-* metadata. Structural attrs and state remain semantically correct when native implementations add ids, values, roles, disabled, variant, or state attributes. Ref forwarding is required for native control targets and cancel-first confirmation focus.
+
+## Parts and styling
+
+kitSpec.parts and kitParts are the canonical part inventory. Native CSS is opt-in through `@jini-ai/ui-kit/react/native/styles.css`, scoped under `@layer jini.kit`, and keyed on data-jini-part. It does not reset the host page. Variables include --jini-kit-fg, --jini-kit-bg, --jini-kit-danger, --jini-kit-warning, and --jini-kit-focus. Native buttons emit data-jini-variant and data-jini-state; tones select message variants. Spinner motion respects prefers-reduced-motion.
+
+Confirmation parts are confirm.dialog, confirm.title, confirm.body, confirm.actions, confirm.cancel, confirm.confirm. Both actions must remain visible and operable when ready; both must expose disabled state while pending. Cancel comes first. A human-only confirm target publishes no agent metadata. Overrides receive guarded controller bags and must preserve their labels/attrs/ref/handlers. Every component, including ConfirmDialog, is replaceable.
+
+## Overlay and browser limits
+
+Dialog and confirmation frames live in the resolved overlay container. Native dialogs use browser showModal when available. ToastRegion portals into the overlay and must be explicitly mounted by the host. Tooltip and Menu are local in-tree composites in v1.
+
+The current browser-only scenario data tags native Escape and modal initial focus. The default React driver reports these skipped; includeBrowser requires an external real browser driver. Native dialog top-layer behavior, actual focus trapping, and geometry need further browser validation. Source-level semantics and jsdom results are not evidence of browser accessibility completion; no Playwright coverage is claimed in these docs.
+
+## Planned components
+
+Link, Icon, RadioGroup, Field, Card, Table, Popover, Combobox, Stack, Grid, ShellLayout, Sidebar, NavItem, PageHeader, Section, EmptyState, and OverlayHost are planned entries only. Their parts and behavior are not yet contracted. The existing Overlay utility and provider overlay root do not implement a planned OverlayHost component. Vue/Angular adapters, UI-library adapters, and motif loading remain deferred.
+
+## Handoff
+
+Inputs: kit.spec.ts, native component hooks/markup/CSS, confirmation guard and provider. Output: v1 semantics, parts, customization obligations, browser limitations. Risk: replacement libraries must be verified against conformance and real browsers. Next assignee: adapter or consumer migration owner.

package/package.json

@@ -1,6 +1,98 @@
 {
   "name": "@jini-ai/ui-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-free UI contract, injected React facades and native defaults.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AINSEP/Jini.git",
+    "directory": "packages/ui-kit"
+  },
+  "jini": {
+    "domain": "ui",
+    "kind": "state",
+    "runtime": "universal",
+    "entries": {
+      ".": "universal",
+      "./react": "browser",
+      "./react/native": "browser",
+      "./react/native/styles.css": "browser",
+      "./react/testing": "browser"
+    }
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./react/native": {
+      "types": "./dist/react/native/index.d.ts",
+      "import": "./dist/react/native/index.js",
+      "default": "./dist/react/native/index.js"
+    },
+    "./react/native/styles.css": "./src/react/native/styles.css",
+    "./react/testing": {
+      "types": "./dist/react/testing/index.d.ts",
+      "import": "./dist/react/testing/index.js",
+      "default": "./dist/react/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/react/native/styles.css",
+    "README.md",
+    "docs",
+    "LICENSE",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.typecheck.*"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@testing-library/react": "^16.3.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vue": "^3.5.0",
+    "vitest": "^2.1.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:headless": "pnpm run build && node scripts/headless-smoke.mjs"
+  }
 }

package/src/react/native/styles.css

@@ -0,0 +1,4 @@
+/* Native views expose jini- classes; hosts own all visual rules. */
+  /* Scoped hidden wins over native-kit display rules without resetting the host page. */
+  [data-jini-part][hidden] { display: none; }
+