@nextop-os/ui-system 0.0.15 → 0.0.17

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Scope
+
+This file applies to `packages/ui/system/*`.
+
+`packages/ui/system` is the source package for `@nextop-os/ui-system`, the
+shared Nextop UI component library. It owns shared CSS tokens, theme styles,
+icon exports, presentation primitives, reusable host-agnostic business display
+components, component metadata, storyboard inventory, and the bundled
+`nextop-ui-system` agent skill.
+
+Before changing components, icons, metadata, styles, storyboard examples, or
+the bundled skill, read
+[UI_SYSTEM_GUIDELINES.md](/Users/zhengweibin/Desktop/team-shell/nextop/packages/ui/system/UI_SYSTEM_GUIDELINES.md).
+
+## Public API
+
+Stable public imports are:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-os/ui-system/utils`
+
+Rules:
+
+- prefer adding exports to an existing public barrel before introducing a new
+  public subpath
+- do not expose `src/*` layout as public API
+- do not encourage per-file deep imports such as
+  `@nextop-os/ui-system/components/button`
+- if package exports change intentionally, update both the package exports and
+  the UI-boundary check script
+
+## Component Library Rules
+
+- keep `base` components low-level, generic, and
+  frontend-foundation-focused
+- allow `business` components only when they are reusable business display
+  components that remain host-agnostic and side-effect-free
+- business components may expose domain display props such as workspace, file,
+  task, agent, status, permission, and callbacks, but must not own daemon,
+  Electron, router, store, query, filesystem, persistence, or workflow calls
+- before promoting a business component, scan source usage, build a
+  code-evidence state matrix, and generate a temporary preview outside the
+  repository for user review
+- business components should compose `base` primitives instead of recreating
+  buttons, fields, dialogs, cards, icons, or overlays
+- treat this package as the shared shadcn and Radix host package
+- when a primitive exists in the shadcn registry, acquire it through shadcn CLI
+  targeted at this package instead of handwriting the component body
+- keep `components.json` and package aliases usable enough that CLI download
+  remains the default path for shared primitives
+- after CLI acquisition, limit edits to narrow package-specific adaptation such
+  as icon routing, import aliases, stable exports, and boundary-check fixes
+- keep CSS variables as the source of truth for token values
+- prefer semantic token naming over raw palette leakage in public APIs
+- keep helper exports minimal and tied to primitive support, not general
+  convenience reuse
+- build primitives for a calm workbench shell, not for marketing-card theatrics
+- every public component, icon, utility, or style entry must have metadata with
+  a stable readable `id` and `layer`
+- use the single `nextop-ui-system` skill for component reuse, extraction,
+  base/business classification, metadata, and storyboard work
+
+## Validation
+
+- Run `pnpm typecheck`
+- Run `pnpm check:ui-boundaries`
+- If component metadata changed, run `node tools/scripts/check-ui-metadata.mjs`
+- If storyboard inventory changed, run
+  `pnpm --filter @nextop-os/ui-storyboard typecheck`
+- If a change affects desktop integration, also run
+  `pnpm --filter @nextop-os/desktop build`
+
+## Related Docs
+
+- [UI_SYSTEM_GUIDELINES.md](/Users/zhengweibin/Desktop/team-shell/nextop/packages/ui/system/UI_SYSTEM_GUIDELINES.md)
+- [docs/conventions/ui-system.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/ui-system.md)
+- [docs/conventions/desktop-visual-language.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/desktop-visual-language.md)
+- [docs/conventions/local-git-hooks.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/local-git-hooks.md)

package/README.md

@@ -12,3 +12,89 @@ import "@nextop-os/ui-system/styles.css";
 
 Application code should prefer the root package export and the documented stable
 subpaths over deep imports from internal files.
+
+## External Development
+
+External consumers should install the package normally:
+
+```bash
+pnpm add @nextop-os/ui-system
+```
+
+For local source sync from a Nextop checkout, start the UI system dev server:
+
+```bash
+pnpm --filter @nextop-os/ui-system dev:server
+```
+
+Then add the Vite plugin in the external app:
+
+```ts
+import { nextopUISystemDev } from "@nextop-os/ui-system/dev-vite";
+
+export default defineConfig({
+  plugins: [nextopUISystemDev()]
+});
+```
+
+When the dev server is reachable, the plugin mirrors the allowed UI-system
+source files into `.nextop-ui-system-dev/` and aliases the stable package
+entrypoints to that cache. When the dev server is unavailable, resolution falls
+back to the installed package in `node_modules`.
+
+Temporary agent previews should use this same dev-server path instead of
+hardcoding local checkout paths. Generate the preview outside the repository,
+configure its Vite app with `nextopUISystemDev({ serverUrl })`, and import
+components, icons, styles, and utilities through the stable public entrypoints.
+
+Add the generated cache to the external app's `.gitignore`:
+
+```text
+.nextop-ui-system-dev/
+```
+
+If the external app uses Tailwind CSS, include both the installed package output
+and the generated dev cache in the app's Tailwind source scan:
+
+```css
+@source "../node_modules/@nextop-os/ui-system/dist";
+@source "../.nextop-ui-system-dev";
+```
+
+## Agent Usage
+
+Coding agents should read component metadata before creating or promoting UI:
+
+```ts
+import { uiSystemMetadata } from "@nextop-os/ui-system/metadata";
+```
+
+When promoting business UI into this package, use the bundled
+`agent/nextop-ui-system/SKILL.md` skill when it is available. In the source
+checkout, also read `AGENTS.md` and `UI_SYSTEM_GUIDELINES.md`. The durable rules
+are:
+
+1. prefer existing metadata entries before creating a component
+2. classify the component as `base` or `business`
+3. keep business components host-agnostic and side-effect-free
+4. before promoting a business component, scan source usage and generate a
+   temporary preview outside the repository for user review
+5. compose business components from base primitives
+6. add metadata, stable exports, and storyboard examples for public UI
+7. run metadata and boundary validation before shipping
+
+External repositories can install the bundled skill into their local Codex
+skill directory with one command:
+
+```bash
+pnpm exec nextop-ui-system-install-skill
+```
+
+This copies the package skill into:
+
+```text
+.codex/skills/nextop-ui-system/SKILL.md
+```
+
+The installer does not overwrite a locally modified skill unless `--force` is
+provided.

package/UI_SYSTEM_GUIDELINES.md

@@ -0,0 +1,148 @@
+# Nextop UI System Guidelines
+
+This document is the shared component-library rulebook for
+`@nextop-os/ui-system`. Both `packages/ui/system/AGENTS.md` and the bundled
+`packages/ui/system/agent/nextop-ui-system` skill should point here before
+component extraction, reuse, metadata, or storyboard work.
+
+## Role
+
+`@nextop-os/ui-system` owns host-agnostic UI foundations:
+
+- CSS tokens and theme styles
+- icon exports
+- shadcn-derived and Radix-backed base primitives
+- reusable business display components
+- component metadata and storyboard inventory
+- small utilities that directly support primitives
+
+It does not own business logic, app-specific workflows, daemon or Electron
+calls, routing, persistence, query/cache mutation, filesystem access, global
+store ownership, or workflow orchestration.
+
+## Stable Public Imports
+
+Use only these public imports from consumers:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-os/ui-system/utils`
+
+Do not import from `@nextop-os/ui-system/src/*` or per-file component paths.
+When a new export is needed, prefer an existing barrel before adding a new
+public subpath. If public exports change, update package exports and the
+UI-boundary check script together.
+
+## Component Layers
+
+`base` components are low-level presentation or interaction primitives. Their
+public API should avoid domain nouns and focus on variants, refs, slots,
+children, class names, accessibility, and generic interaction.
+
+`business` components are reusable display surfaces for shared business
+concepts. They may expose domain display props such as workspace, file, task,
+agent, run, status, permission, labels, and callbacks. They must stay
+host-agnostic and side-effect-free.
+
+Business components should compose `base` primitives instead of recreating
+buttons, fields, dialogs, cards, icons, menus, or overlays.
+
+## Primitive Acquisition
+
+Treat this package as the shared shadcn and Radix host package.
+
+- When a primitive exists in the shadcn registry, acquire it through shadcn CLI
+  targeted at `packages/ui/system`.
+- Keep `components.json` and package aliases usable enough that CLI download
+  remains the default path for shared primitives.
+- After CLI acquisition, limit edits to package-specific adaptation such as
+  icon routing, import aliases, stable exports, token alignment, metadata, and
+  boundary-check fixes.
+
+## Visual And Token Rules
+
+- Keep CSS variables as the source of truth for token values.
+- Prefer semantic token names over raw palette leakage in public APIs.
+- Build primitives for a calm workbench shell, not for marketing-card
+  theatrics.
+- Reusable packages outside `packages/ui/*` should consume
+  `@nextop-os/ui-system` primitives and token-backed Tailwind utilities before
+  adding package-local CSS.
+- If repeated package-local CSS needs emerge, move the shared foundation into
+  `@nextop-os/ui-system`.
+
+## Metadata And Storyboard
+
+Every public UI-system component, icon, utility, or style entry must have
+metadata with:
+
+- stable readable `id`
+- `layer` as `base` or `business`
+- `source` under `packages/ui/system/src`
+- stable public `from` entrypoint
+
+Keep component ids globally unique and kebab-case. Storyboard inventory should
+stay grouped by `Foundation`, `Base Components`, and `Business Components`.
+Visible component stories should support copying the component id.
+
+For business components, add storyboard examples for normal, empty, disabled,
+loading, and error-like states when those states exist in the public contract.
+
+## Promotion Checklist
+
+Before promoting local UI into this package, scan the source usage and create a
+preflight state preview:
+
+- inspect the source component, call sites, conditional rendering, props, types,
+  tests, mocks, and relevant i18n keys
+- build a state matrix from code evidence; for each state, record the state
+  name, source file or branch, props or data needed, host-owned behavior, and
+  whether it belongs in the shared component contract
+- generate a temporary preview outside the repository, such as under
+  `$TMPDIR/nextop-ui-system-preview-<component-id>/`
+- start the UI-system dev server with
+  `pnpm --filter @nextop-os/ui-system dev:server`, or verify an existing server
+  by probing `/health`
+- configure the temporary Vite preview with
+  `nextopUISystemDev({ serverUrl })` from `@nextop-os/ui-system/dev-vite`
+  instead of hardcoding checkout paths
+- import UI-system components, icons, styles, and utilities through stable
+  public entrypoints; use the local state matrix file or `/components` for
+  metadata context
+- render all candidate states in that preview using a draft component or copied
+  visual surface
+- start a local preview URL and get user confirmation before writing the
+  component into `packages/ui/system`
+
+Do not put draft preview files in the Nextop checkout. The temporary preview is
+a visual review gate, not part of the package source.
+
+Before promotion, identify:
+
+- component `id` and `layer`
+- source usage being replaced
+- intended reuse surfaces
+- public props and callbacks
+- host-owned state and side effects that remain outside the component
+- state matrix summary and temporary preview URL
+- export path, metadata entry, storyboard states, and validation commands
+
+Prefer existing metadata entries before creating a component. Replace only the
+visual surface with stable UI-system imports; keep host state, data loading,
+routing, daemon calls, i18n keys, and business transforms in the caller.
+
+## Validation
+
+Run the smallest relevant checks and report exact commands and results:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+```
+
+If runtime component code changed, also run the relevant package typecheck or
+build for the consumer that was migrated.

package/agent/install-skill.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+import { constants } from "node:fs";
+import {
+  access,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  stat
+} from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const sourceDirectory = join(packageRoot, "agent", "nextop-ui-system");
+const skillName = "nextop-ui-system";
+
+const options = parseArgs(process.argv.slice(2));
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const targetRoot = resolve(options.cwd, ".codex", "skills");
+const targetDirectory = join(targetRoot, skillName);
+
+await assertReadableDirectory(sourceDirectory);
+await mkdir(targetRoot, { recursive: true });
+
+if (await pathExists(targetDirectory)) {
+  const targetStats = await stat(targetDirectory);
+
+  if (!targetStats.isDirectory()) {
+    throw new Error(`Target exists and is not a directory: ${targetDirectory}`);
+  }
+
+  if (!options.force) {
+    if (await directoriesMatch(sourceDirectory, targetDirectory)) {
+      console.log(
+        `nextop-ui-system skill already configured at ${targetDirectory}`
+      );
+      process.exit(0);
+    }
+
+    throw new Error(
+      `Target skill already exists with local changes: ${targetDirectory}\n` +
+        "Run with --force to replace it."
+    );
+  }
+
+  await rm(targetDirectory, { recursive: true, force: true });
+}
+
+await cp(sourceDirectory, targetDirectory, {
+  errorOnExist: false,
+  force: true,
+  recursive: true
+});
+
+console.log(`Installed nextop-ui-system skill to ${targetDirectory}`);
+console.log(
+  "Agents can now load it from .codex/skills/nextop-ui-system/SKILL.md"
+);
+
+function parseArgs(args) {
+  const parsed = {
+    cwd: process.cwd(),
+    force: false,
+    help: false
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--force") {
+      parsed.force = true;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === "--cwd") {
+      const cwd = args[index + 1];
+      if (!cwd) {
+        throw new Error("--cwd requires a directory path");
+      }
+      parsed.cwd = resolve(cwd);
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage: nextop-ui-system-install-skill [options]
+
+Copies the bundled Nextop UI System skill into the current repository.
+
+Options:
+  --cwd <path>  Repository root to configure. Defaults to the current directory.
+  --force       Replace an existing .codex/skills/nextop-ui-system directory.
+  -h, --help    Show this help message.`);
+}
+
+async function assertReadableDirectory(path) {
+  await access(path, constants.R_OK);
+  const pathStats = await stat(path);
+
+  if (!pathStats.isDirectory()) {
+    throw new Error(`Expected directory: ${path}`);
+  }
+}
+
+async function pathExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function directoriesMatch(leftDirectory, rightDirectory) {
+  const leftEntries = await listFiles(leftDirectory, leftDirectory);
+  const rightEntries = await listFiles(rightDirectory, rightDirectory);
+
+  if (leftEntries.length !== rightEntries.length) {
+    return false;
+  }
+
+  for (let index = 0; index < leftEntries.length; index += 1) {
+    if (leftEntries[index] !== rightEntries[index]) {
+      return false;
+    }
+
+    const leftFile = join(leftDirectory, leftEntries[index]);
+    const rightFile = join(rightDirectory, rightEntries[index]);
+
+    const [leftContent, rightContent] = await Promise.all([
+      readFile(leftFile),
+      readFile(rightFile)
+    ]);
+
+    if (!leftContent.equals(rightContent)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function listFiles(rootDirectory, directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        return listFiles(rootDirectory, absolutePath);
+      }
+
+      if (!entry.isFile()) {
+        return [];
+      }
+
+      return relative(rootDirectory, absolutePath);
+    })
+  );
+
+  return files.flat().sort((left, right) => left.localeCompare(right));
+}

package/agent/nextop-ui-system/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: nextop-ui-system
+description: Use when working with @nextop-os/ui-system components, replacing local UI with shared components, querying component ids or metadata, promoting UI into shared base or business components, or maintaining UI-system storyboard inventory.
+---
+
+# Nextop UI System
+
+Use this skill as the single entrypoint for `@nextop-os/ui-system` component
+reuse, extraction, promotion, metadata, and storyboard work.
+
+## Source Of Truth
+
+Read these before editing:
+
+1. nearest `AGENTS.md` for the target code
+2. `packages/ui/system/AGENTS.md`
+3. `packages/ui/system/UI_SYSTEM_GUIDELINES.md`
+4. `docs/conventions/ui-system.md`
+5. component metadata from the first available source:
+   - `GET http://127.0.0.1:4100/components`
+   - `packages/ui/system/src/metadata/components.json`
+   - `@nextop-os/ui-system/metadata` from the installed package
+
+Use stable public imports only:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-os/ui-system/utils`
+
+Never deep import `@nextop-os/ui-system/src/*` or per-file component paths.
+
+## Route The Task
+
+Read only the reference file that matches the task.
+
+- Using or querying existing components:
+  `references/use-existing-component.md`
+- Extracting a low-level base primitive:
+  `references/extract-base-component.md`
+- Promoting reusable business UI into a shared component:
+  `references/promote-business-component.md`
+- Maintaining ids, metadata, exports, or storyboard inventory:
+  `references/maintain-inventory.md`
+
+## Global Boundaries
+
+Keep these outside `@nextop-os/ui-system` components:
+
+- daemon, Electron, filesystem, router, or host adapter calls
+- data fetching, cache mutation, persistence, polling, and global store
+  ownership
+- workflow orchestration such as onboarding, workspace registration, install or
+  uninstall flows, confirmation dialogs, queueing, or navigation
+- i18n key lookup and business-specific copy derivation unless supplied by
+  props, children, or labels
+
+For any promoted public component, add stable exports, metadata, and storyboard
+coverage that match the chosen reference workflow.
+
+For business component promotion, the temporary preview must be built from the
+state matrix, proposed props boundary, and candidate source UI. Treat the
+confirmed preview draft as the implementation blueprint for
+`packages/ui/system`, not as a disposable mockup.
+
+## Validation Commands
+
+Run the smallest relevant checks from the selected reference. Common checks are:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+```
+
+If runtime component code changed, also run the relevant package typecheck or
+consumer build.

package/agent/nextop-ui-system/references/extract-base-component.md

@@ -0,0 +1,43 @@
+# Extract Base Component
+
+Use this reference when the target is a low-level visual primitive.
+
+## Base Criteria
+
+Proceed only if the public API has no domain noun and props describe generic UI
+concerns:
+
+- presentation and variants
+- interaction and accessibility
+- refs, slots, class names, and children
+- controlled or uncontrolled primitive state
+
+If the component represents a workspace, file, task, agent, run, project,
+account, or other business concept, use `promote-business-component.md`
+instead.
+
+## Workflow
+
+1. Check metadata and existing exports first.
+2. If the primitive exists in the shadcn registry, acquire it through shadcn CLI
+   targeted at `packages/ui/system`.
+3. Adapt only package aliases, icon routing, tokens, stable exports, metadata,
+   storyboard examples, and boundary-check issues.
+4. Keep helper exports minimal and directly tied to primitive support.
+5. Add metadata with `layer: "base"`.
+6. Add storyboard coverage for the public states and variants exposed by the
+   primitive.
+7. Replace duplicated local UI only after the shared primitive exists.
+
+## 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.

package/agent/nextop-ui-system/references/maintain-inventory.md

@@ -0,0 +1,40 @@
+# Maintain Inventory
+
+Use this reference when changing component ids, metadata, exports, or storyboard
+inventory without promoting a new component.
+
+## Metadata Rules
+
+Every public UI-system entry must have metadata with:
+
+- stable readable `id`
+- globally unique kebab-case id
+- `layer` as `base` or `business`
+- `source` under `packages/ui/system/src`
+- stable public `from` entrypoint
+
+Do not expose `src/*` layout as public API and do not encourage per-file deep
+imports.
+
+## Storyboard Rules
+
+Keep storyboard grouped by:
+
+- `Foundation`
+- `Base Components`
+- `Business Components`
+
+Visible component stories should support copying the component id.
+
+When changing metadata or storyboard inventory, keep ids stable unless the
+rename is intentional and callers or docs are updated together.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+```