@nextop-os/ui-system 0.0.16 → 0.0.17

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

@@ -0,0 +1,352 @@
+# Promote Business Component
+
+Use this reference when business-side UI should become a reusable
+host-agnostic display component.
+
+## Business Criteria
+
+Proceed only if the component can render from props with no host side effects.
+Business components may expose domain display props such as workspace, file,
+task, agent, run, project, account, status, permission, labels, and callbacks.
+
+Do not promote UI that owns daemon, Electron, router, store, query, persistence,
+polling, filesystem access, or workflow orchestration.
+
+## Agent-Owned Analysis
+
+The agent must automatically analyze the candidate from code evidence. Do not
+ask the user to provide the state matrix or props boundary unless the code has
+conflicting evidence or an unclear business meaning.
+
+Scan:
+
+- source component and nearby helpers
+- call sites and conditional rendering branches
+- props, types, tests, mocks, fixtures, and sample data
+- relevant i18n keys and resolved labels
+- existing UI-system metadata and components
+
+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
+- 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:
+
+- component `id` and `layer: "business"`
+- source usage being replaced
+- intended reuse surfaces
+- public props and callbacks
+- host-owned state and side effects that remain outside
+- states that will appear in storyboard
+- stable export path and metadata entry
+
+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:
+
+- 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
+```
+
+Use `--out-dir`, `--server-url`, or `--force` only when the default temporary
+directory or server URL is unsuitable.
+
+## Preview Code Generation Prompt
+
+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
+
+Example request:
+
+```text
+Promote the managed agent settings table into @nextop-os/ui-system.
+```
+
+Expected chain:
+
+1. **Analyze source evidence**
+   - Read the source table, settings panel call sites, tests, mocks, and i18n
+     labels.
+   - Check existing metadata for reusable table, badge, button, dialog, and
+     icon primitives.
+2. **Build the state matrix**
+
+   ```text
+   normal
+   - Evidence: settings table renders installed agents with status and actions.
+   - Props/data: rows, status labels, action labels, icon slots, callbacks.
+   - Host-owned: install/uninstall orchestration, queue state derivation, i18n.
+   - Contract: yes.
+
+   empty
+   - Evidence: settings surface renders no configured agents.
+   - Props/data: empty title/body.
+   - Host-owned: deciding whether inventory is empty.
+   - Contract: yes.
+
+   disabled
+   - Evidence: actions disabled while an operation is pending.
+   - Props/data: disabled rows or disabled actions.
+   - Host-owned: permission and pending-operation calculation.
+   - Contract: yes.
+
+   error-like
+   - Evidence: row can show install failure or unavailable status.
+   - Props/data: tone, status label, supporting text.
+   - Host-owned: failure classification and retry behavior.
+   - Contract: yes.
+   ```
+
+3. **Decide the boundary before preview**
+   - `id`: a stable kebab-case business component id, for example
+     `example-business-component`
+   - `layer`: `business`
+   - Export: a matching PascalCase component name, for example
+     `ExampleBusinessComponent`
+   - Public props: rows, labels, icon render slots, action callbacks, disabled
+     flags, status/tone fields, empty-state copy.
+   - 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.
+   - 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`.
+   - 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.
+   - Replace the original app UI with `@nextop-os/ui-system` imports while
+     leaving host-owned behavior in the caller.
+7. **Validate and report**
+   - Run metadata, boundary, storyboard, and relevant package checks.
+   - Report the state matrix summary, reviewed preview URL, final boundary,
+     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
+   states when those states exist in the public contract.
+5. Migrate callers by replacing only the visual surface.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+pnpm --filter @nextop-os/ui-system typecheck
+```
+
+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
+- validation commands and results
+- remaining risks or uncovered states

package/agent/nextop-ui-system/references/use-existing-component.md

@@ -0,0 +1,37 @@
+# Use Existing Component
+
+Use this reference when replacing local UI with `@nextop-os/ui-system` or when
+answering what shared components exist.
+
+## Workflow
+
+1. Read component metadata first by `id`, `name`, `export`, `layer`, and
+   `useCases`.
+2. Prefer an existing component before creating, extracting, or promoting a new
+   one.
+3. Read the selected component source and props type before using it.
+4. Import through stable public entrypoints only.
+5. Replace only the visual surface.
+
+## Caller-Owned Work
+
+Keep these in the caller:
+
+- host state and derived business state
+- data loading, cache mutation, and persistence
+- routing, daemon calls, Electron calls, and filesystem access
+- i18n key lookup and user-visible product copy selection
+- confirmation dialogs, queueing, install or uninstall flows, and navigation
+
+The UI-system component should receive resolved props, labels, callbacks,
+status values, icons, and children.
+
+## Validation
+
+Run the smallest relevant checks:
+
+```bash
+pnpm check:ui-boundaries
+```
+
+If the consumer code changed, also run the relevant consumer typecheck or build.