@nextop-os/ui-system 0.0.17 → 0.0.18

package/agent/nextop-ui-system/references/promote-business-component.md

@@ -31,18 +31,22 @@ Build a state matrix from that evidence. For each candidate state, record:
 - state name
 - source file or branch proving the state
 - props or data needed to render it
+- variation axes and whether each axis is visual, structural, behavioral, or
+  host-owned
 - host-owned behavior that must stay outside the shared component
 - whether the state belongs in the shared component contract
 
 ## Agent-Owned Boundary Decision
 
-The agent decides the proposed component boundary before asking for preview
-review:
+The agent decides the proposed component boundary before implementation:
 
 - component `id` and `layer: "business"`
 - source usage being replaced
 - intended reuse surfaces
 - public props and callbacks
+- API shape decision: variants, discriminated unions, slots, children, explicit
+  component variants, compound subcomponents, provider state, and host-owned
+  caller logic
 - host-owned state and side effects that remain outside
 - states that will appear in storyboard
 - stable export path and metadata entry
@@ -50,174 +54,57 @@ review:
 If the candidate is not reusable or cannot stay host-agnostic, do not promote
 it. Prefer using existing components or keeping the UI local.
 
-## Temporary Preview Gate
-
-Before writing the component into `packages/ui/system`, generate a temporary
-preview outside the repository.
-
-The preview is an early confirmation of the component that will be promoted,
-not a loose mockup. Build it from three inputs:
+## API Composition Gate
+
+Before writing the promoted component, convert the state matrix into a public
+API deliberately:
+
+1. List every visual, structural, and behavioral variation found in source
+   evidence.
+2. Keep only standard state booleans such as `disabled`, `loading`, `selected`,
+   `open`, `required`, or `invalid` when they represent real states and do not
+   create impossible combinations.
+3. Replace mode booleans such as `isFoo`, `showBar`, and `withBaz` with a
+   finite variant, discriminated union, explicit component variant, slot, or
+   composed child.
+4. Prefer `children` or named slots for caller-owned visual regions. Use render
+   props only when the shared component needs to pass data back to the caller.
+5. Use compound components and context only when consumers need to assemble
+   subparts while sharing state. A simple row, card, badge, toolbar, or display
+   panel should stay as a direct props-driven component.
+6. If shared state is necessary, define a narrow injectable context contract as
+   `state`, `actions`, and `meta`. Providers may adapt caller state, but daemon,
+   Electron, router, store, query, persistence, filesystem, i18n lookup, and
+   workflow orchestration remain outside `@nextop-os/ui-system`.
+7. For new React components, use the repository's React 19 baseline, including
+   `ref` as a prop when needed. Do not rewrite shadcn or Radix-acquired
+   internals solely to normalize API style.
+
+Stop promotion if the only way to represent the source states is a broad bag of
+unrelated boolean props or leaked host state. Narrow the boundary, create
+explicit variants, or keep the UI local.
+
+## Implementation Blueprint
+
+Implement the promoted component directly from three inputs:
 
 - the code-evidence state matrix
 - the proposed public props and callback boundary
-- the existing candidate UI source or visual surface being extracted
-
-The draft component inside the preview should be a props-driven version of the
-candidate source with host-owned behavior removed. Once the user confirms the
-preview, the promoted component should be copied from the confirmed draft with
-only package integration edits such as final file placement, exports, metadata,
-storyboard wiring, and type tightening. Do not confirm a placeholder preview and
-then reimplement a materially different component in `packages/ui/system`.
-
-1. Create the preview under
-   `$TMPDIR/nextop-ui-system-preview-<component-id>/`.
-2. Start the UI-system dev server:
-
-   ```bash
-   pnpm --filter @nextop-os/ui-system dev:server
-   ```
-
-   If a server may already be running, probe `/health` first.
-
-3. Configure the temporary Vite app with
-   `nextopUISystemDev({ serverUrl })` from
-   `@nextop-os/ui-system/dev-vite`.
-4. Import UI-system components, icons, styles, and utilities through stable
-   public entrypoints.
-5. Render every accepted state from the state matrix using the props-driven
-   draft component adapted from the candidate source.
-6. Start the preview app and give the user a local URL.
-7. Wait for the user to confirm the state set, visual behavior, and props
-   boundary before promoting the component into `packages/ui/system`.
-
-The preview is a review gate, not package source. Do not put draft preview
-files in the Nextop checkout.
-
-## Preview Scaffold Script
-
-Prefer the bundled script when creating the temporary preview scaffold:
-
-```bash
-node packages/ui/system/agent/nextop-ui-system/scripts/create-business-preview.mjs \
-  --component-id <component-id> \
-  --component-name <ComponentName> \
-  --state-matrix /path/to/state-matrix.json
-```
-
-The state matrix JSON may be either an array or an object with a `states` array:
-
-```json
-{
-  "states": [
-    {
-      "name": "normal",
-      "description": "Installed agents with status and actions.",
-      "evidence": ["apps/desktop/src/.../AgentSettings.tsx normal branch"],
-      "propsData": ["rows", "status labels", "action labels"],
-      "hostOwnedBehavior": ["install queue", "i18n lookup"],
-      "boundaryNotes": ["callbacks are host-provided"],
-      "includedInContract": true
-    }
-  ]
-}
-```
-
-The script writes a Vite React app scaffold to
-`$TMPDIR/nextop-ui-system-preview-<component-id>/` by default. The generated
-app includes:
-
-- `vite.config.ts` with `nextopUISystemDev({ serverUrl })`
-- `src/stateMatrix.ts` from the code-evidence state matrix
-- `src/Preview.tsx` with a draft component and state cards
-- `src/style.css` with Tailwind source hints for the dev cache and installed
-  package
-
-Treat the generated `src/Preview.tsx` as a scaffold. Replace the generic draft
-component with a props-driven adaptation of the candidate source before asking
-for user confirmation. The confirmed preview component is the implementation
-blueprint for `packages/ui/system`.
-
-After generation, run the printed commands from the preview directory:
-
-```bash
-pnpm install
-pnpm dev -- --host 127.0.0.1
-```
+- the existing candidate source UI or visual surface being extracted
 
-Use `--out-dir`, `--server-url`, or `--force` only when the default temporary
-directory or server URL is unsuitable.
+The promoted component should be a props-driven version of the candidate source
+with host-owned behavior removed. Preserve the real visual structure, component
+composition, class names, spacing, icons, and state-specific branches unless
+they depend on host-owned behavior. Replace host-owned behavior with public
+props, callbacks, caller-owned slots, or explicit variants. Add storyboard
+examples for every accepted public state in the same change so the review can
+inspect the finished implementation instead of a preflight draft.
 
-## Preview Code Generation Prompt
+If the draft still needs app state, navigation, fetching, persistence, i18n key
+lookup, or host adapters to render, stop and revise the component boundary
+instead of promoting it.
 
-Use a prompt like this to turn the candidate source into the high-fidelity draft
-inside the temporary preview. Fill the inputs from code evidence and the
-proposed boundary; do not ask the user to write the preview code.
-
-```text
-Generate a temporary Vite React preview for a proposed Nextop UI-system business
-component promotion.
-
-Inputs:
-- Component id: <component-id>
-- Proposed export name: <ComponentName>
-- Proposed layer: business
-- Source usage being replaced: <source file paths and call sites>
-- Candidate source excerpt or file paths: <component/helper files to adapt>
-- Proposed props and callbacks: <TypeScript interface or bullet list>
-- Host-owned behavior to exclude: <daemon/router/store/i18n/data loading/etc.>
-- State matrix:
-  <state name | source evidence | required props/data | host-owned behavior |
-  included in component contract>
-
-Requirements:
-1. Create all preview files under
-   `$TMPDIR/nextop-ui-system-preview-<component-id>/`; do not write draft
-   preview files inside the Nextop checkout.
-2. Start from the generated files produced by
-   `scripts/create-business-preview.mjs` unless there is a specific reason to
-   hand-author the preview.
-3. Adapt the candidate UI source into a props-driven draft component. Preserve
-   the real visual structure, component composition, class names, spacing,
-   icons, and state-specific branches unless they depend on host-owned
-   behavior.
-4. Replace host-owned behavior with props, static sample data, no-op handlers,
-   or console logging. Do not keep daemon, Electron, router, store, query,
-   filesystem, polling, i18n key lookup, or workflow orchestration in the
-   preview component.
-5. Create or update a minimal Vite React app with `package.json`,
-   `index.html`, `src/main.tsx`, `src/Preview.tsx`, `src/stateMatrix.ts`, and
-   `src/style.css`.
-6. Configure `vite.config.ts` with
-   `nextopUISystemDev({ serverUrl: "http://127.0.0.1:4100" })` from
-   `@nextop-os/ui-system/dev-vite`.
-7. Import UI-system components, icons, utilities, and styles only through
-   stable public entrypoints:
-   `@nextop-os/ui-system`, `@nextop-os/ui-system/components`,
-   `@nextop-os/ui-system/icons`, `@nextop-os/ui-system/styles.css`, and
-   `@nextop-os/ui-system/utils`.
-8. Render every accepted state from the state matrix in one screen. Each state
-   card must show the state name, source evidence, included/excluded boundary
-   notes, and the rendered draft component.
-9. Keep copy, labels, permissions, statuses, and formatting as props in the
-   preview so the component boundary is reviewable.
-10. Do not import from `@nextop-os/ui-system/src/*`, app internals, daemon,
-   Electron, router, stores, query clients, or checkout-relative paths.
-11. Print the commands needed to run the preview and the expected local URL.
-
-Output:
-- File list with complete contents.
-- Run commands.
-- Short review checklist for the user: state coverage, visual behavior, props
-  boundary, and host-owned behavior.
-- A note identifying which preview component file should be copied into
-  `packages/ui/system` after user confirmation.
-```
-
-The generated preview should make boundary mistakes visible. If the draft needs
-app state, navigation, fetching, or host adapters to render, stop and revise the
-component boundary instead of promoting it.
-
-## Preview Chain Demo
+## Promotion Chain Demo
 
 Example request:
 
@@ -260,7 +147,7 @@ Expected chain:
    - Contract: yes.
    ```
 
-3. **Decide the boundary before preview**
+3. **Decide the boundary before implementation**
    - `id`: a stable kebab-case business component id, for example
      `example-business-component`
    - `layer`: `business`
@@ -268,67 +155,59 @@ Expected chain:
      `ExampleBusinessComponent`
    - Public props: rows, labels, icon render slots, action callbacks, disabled
      flags, status/tone fields, empty-state copy.
+   - API shape: row status as finite tone values, callbacks as host-provided
+     actions, empty state copy as labels, and no install/uninstall mode
+     booleans. If the table later needs caller-owned row adornments, prefer a
+     named slot or composed child over a broad render prop.
    - Host-owned behavior: i18n lookup, daemon calls, install queue,
      confirmation dialogs, persistence, routing, and state derivation.
-4. **Generate a high-fidelity preview component**
-   - Write the state matrix to a temporary JSON file.
-   - Generate the preview scaffold:
-
-     ```bash
-     node packages/ui/system/agent/nextop-ui-system/scripts/create-business-preview.mjs \
-       --component-id example-business-component \
-       --component-name ExampleBusinessComponent \
-       --state-matrix /tmp/example-business-component-state-matrix.json \
-       --force
-     ```
-
-   - Adapt the current candidate source into `src/Preview.tsx` as a props-driven
-     business component draft.
+4. **Implement the promoted component**
+   - Adapt the current candidate source into the final
+     `packages/ui/system/src/components/<component-file>.tsx` component.
    - Keep the real table layout, status cells, action affordances, icon
      placement, empty state, and disabled/error branches.
    - Replace host behavior with props and local callback stubs: i18n-resolved
      labels, queue state, confirmation dialog decisions, daemon calls, and
-     install orchestration stay outside the draft.
-   - Start or verify the UI-system dev server:
-
-     ```bash
-     pnpm --filter @nextop-os/ui-system dev:server
-     curl http://127.0.0.1:4100/health
-     ```
-
-   - Start the preview app and give the user the local URL.
-
-5. **User review gate**
-   - Ask the user to review state coverage, visual behavior, and props
-     boundary in the preview.
-   - If the user finds a missing state or boundary leak, update the state
-     matrix and regenerate the temporary preview.
-   - Only proceed after the user confirms the preview.
-6. **Promote after confirmation**
-   - Copy the confirmed preview draft into
-     `packages/ui/system/src/components/<component-file>.tsx`.
+     install orchestration stay outside the component.
    - Make only package integration edits: final exported prop types, imports,
      class cleanup, and package-local helpers.
    - Export it from stable barrels.
    - Add metadata with `layer: "business"` and storyboard coverage for the
-     confirmed states.
+     accepted states.
    - Replace the original app UI with `@nextop-os/ui-system` imports while
      leaving host-owned behavior in the caller.
-7. **Validate and report**
+5. **Validate and report**
+   - Review the finished implementation through the storyboard states and the
+     migrated consumer surface.
+   - Start an independent design-foundation review subagent. Give it the
+     promoted files, original source usage, selected state matrix, storyboard
+     entry, metadata entry, and `ui-system.md`.
+   - Include the API shape review in the handoff: accepted booleans, variants,
+     slots or children, explicit variants, provider state if any, and
+     host-owned behavior kept in the caller.
+   - Resolve any subagent-reported design drift before reporting completion.
+   - Run the promotion review gate: Frictionless task path and action hierarchy,
+     Quality Craft visual parity and token/state coverage, and Trustworthy
+     labels, recovery, policy, and provenance behavior.
    - Run metadata, boundary, storyboard, and relevant package checks.
-   - Report the state matrix summary, reviewed preview URL, final boundary,
-     validation results, and uncovered risks.
+   - Report the state matrix summary, final boundary, promotion review result,
+     subagent design-foundation result, validation results, and uncovered
+     risks.
 
 ## Implementation
 
-After preview confirmation:
-
 1. Implement the business component by composing `base` primitives.
 2. Keep all host-owned behavior in the caller.
-3. Add stable exports and metadata with `layer: "business"`.
-4. Add storyboard examples for normal, empty, disabled, loading, and error-like
+3. Preserve the API composition decision. Do not add new mode booleans or
+   host-owned state while moving the candidate UI into the shared package.
+4. Add stable exports and metadata with `layer: "business"`.
+5. Add storyboard examples for normal, empty, disabled, loading, and error-like
    states when those states exist in the public contract.
-5. Migrate callers by replacing only the visual surface.
+6. Migrate callers by replacing only the visual surface.
+7. Run the promotion review gate from
+   `ui-system.md` against the promoted component
+   and migrated consumer.
+8. Start the design-foundation review subagent and resolve any reported drift.
 
 ## Validation
 
@@ -346,7 +225,14 @@ If a consumer was migrated, also run that consumer's typecheck or build.
 Report:
 
 - state matrix summary
-- preview URL reviewed by the user
 - component boundary decision
+- API composition decision and any rejected boolean or state combinations
+- promotion review result with Frictionless / Quality Craft / Trustworthy
+  pillar status and blocking/major/minor issues
+- design-foundation subagent result
 - validation commands and results
 - remaining risks or uncovered states
+
+Do not report full design-foundation compliance unless the subagent review ran
+and found no unresolved drift. If subagents are unavailable, report the
+verification as blocked.