@nextop-os/ui-system 0.0.19 → 0.0.20

package/AGENTS.md

@@ -86,6 +86,46 @@ Rules:
 - use the single `nextop-ui-system` skill for component reuse, extraction,
   base/business classification, metadata, and storyboard work
 
+## React Component Splitting Rules
+
+- default to one component per directory; keep the component file, tests,
+  stories, local styles, and tightly coupled implementation-detail helpers
+  colocated inside that directory
+- default to one React component per file; allow multiple small stateless
+  helpers in one file only when they are tightly coupled implementation detail
+  of the exported component
+- split presentational components away from host wiring; components promoted
+  into ui-system must receive data, labels, status, and callbacks through props
+  rather than owning side effects or app workflow
+- if a component does not need internal state or refs, prefer a plain function
+  component; introduce heavier component structure only when state, refs, or
+  lifecycle-like coordination is actually required
+- when behavior is reusable but host-owned, extract it into caller-owned hooks,
+  adapters, or controller code instead of embedding that logic in the ui-system
+  component body
+- do not use mixin-style reuse or implicit component coupling; prefer explicit
+  composition through child components, slots, helper modules, or narrow
+  wrappers
+- keep component APIs semantic and stable; do not repurpose DOM prop names such
+  as `style` or `className` to carry business meaning when a clearer prop like
+  `variant`, `tone`, `status`, or `layout` is intended
+- use spread props sparingly on public components; pass explicit props whenever
+  possible so the boundary stays readable and host-agnostic
+- list and collection components must render with stable identity from caller
+  data; do not rely on array index keys in promoted UI-system surfaces
+- when a component grows multiple visual regions or branches, first try to
+  split subparts into local render helpers or child components before adding
+  more mode booleans to one large component
+- avoid boolean-prop sprawl for mutually exclusive modes; prefer a finite
+  variant, discriminated union, explicit slot, or separate subcomponent when
+  states represent distinct rendering modes
+- keep user-visible copy caller-owned by default; if text changes by host,
+  locale, or workflow, expose it through props, labels, or children instead of
+  hardcoding it inside the shared component
+- use the filename as the component name and keep exported component names in
+  PascalCase so file boundaries stay obvious during promotion, review, and
+  migration
+
 ## Validation
 
 - Run `pnpm typecheck`

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

@@ -22,6 +22,12 @@ Treat these as hard requirements, not cleanup suggestions:
 - compose existing UI-system `base` primitives such as `Card`, `Button`,
   `Tooltip`, `Dialog`, and related vocabulary before creating custom panel,
   button, field, or overlay treatments
+- use icon components from `@nextop-os/ui-system/icons` for promoted
+  components and storyboard examples. Do not inline SVG/data URI assets, import
+  app-local icon files, or pull third-party icon packages directly from promoted
+  UI. If the source UI depends on an icon that is not in the UI system, promote
+  the source-derived icon into `packages/ui/system/src/icons` with metadata
+  first, then consume the UI-system icon export.
 - make storyboard examples render the real component surface and states; do not
   rely on surrounding docs chrome to hide component-level visual drift or to
   fake the final panel/surface language
@@ -89,11 +95,42 @@ alone. The promotion flow must also add or update a real renderable example in
 `apps/ui-storyboard` so the component is visible in navigation and can be
 visually reviewed in shared docs immediately after promotion.
 
-For business component promotion, derive the promoted component directly from
-the state matrix, proposed props boundary, and candidate source UI, then add
-storyboard coverage for the accepted states in the same promotion pass. Treat
-that evidence and boundary decision as the implementation blueprint for
-`packages/ui/system`, and use review only to verify the finished implementation.
+For business component promotion, use a copy-first workflow: move the existing
+business component structure as intact as possible, preserve the real DOM,
+visual hierarchy, state branches, and interaction layout, then progressively
+remove host dependencies and standardize the public API. Do not begin by
+inventing a cleaner abstraction or new visual treatment. The state matrix,
+props boundary, and candidate source UI define what to copy, what to keep
+caller-owned, and what to standardize after parity exists.
+
+Treat business component promotion as an iterative migration-review loop, not a
+single extraction pass:
+
+1. migrate the source UI copy-first
+2. recreate source-backed states in storyboard
+3. run independent review against the original source and screenshot
+4. migrate again to close review findings
+5. repeat review until source/design parity is acceptable
+
+Only after that loop should the API be generalized further. Do not report the
+component as complete after the first migration if review still shows material
+DOM, visual, token, state, icon, or storyboard coverage drift.
+
+The promoted UI must follow the original design exactly unless the user
+explicitly approves a visual change. Do not add new decoration, controls,
+icons, layout chrome, copy, motion, states, spacing, or visual hierarchy that
+does not exist in the source UI or provided screenshot. If UI-system token or
+primitive replacement is needed, it must preserve the observed design and
+interaction path rather than becoming a redesign.
+
+Copy-first also applies to dependent presentational subcomponents and
+third-party-library wrappers used by the candidate UI. Do not copy only the top
+level JSX and recreate nested behavior from memory. Trace the dependency tree:
+pure display helpers should move with the component; reusable wrappers around
+Radix, floating UI, resizable panels, virtualization, or similar libraries
+should be promoted or reused as `base` primitives first; host-coupled children
+must be split into caller-owned data, labels, callbacks, or slots before the
+business component is considered promoted.
 
 ## Design Foundation Verification
 

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

@@ -21,6 +21,9 @@ conflicting evidence or an unclear business meaning.
 Scan:
 
 - source component and nearby helpers
+- dependent presentational subcomponents imported by the source component
+- third-party-library wrappers used by the candidate UI, such as Radix,
+  floating UI, resizable panels, drag/drop, virtualization, or editor shells
 - call sites and conditional rendering branches
 - props, types, tests, mocks, fixtures, and sample data
 - relevant i18n keys and resolved labels
@@ -86,19 +89,82 @@ explicit variants, or keep the UI local.
 
 ## Implementation Blueprint
 
+Use a copy-first promotion workflow. The first implementation should be a
+props-driven copy of the source business UI, not a new abstraction designed from
+memory. Preserve the source DOM hierarchy, visual structure, spacing, state
+branches, slots, and interaction affordances until parity is visible in
+storyboard. Only after parity exists should the API be tightened and generalized.
+
+Run promotion as a loop: migrate, review, migrate, review. The first migration
+must make source-backed parity visible; review then measures drift against the
+original code and screenshot; the next migration closes those findings without
+redesigning. Continue until no material DOM, visual, token, state, icon, or
+storyboard coverage drift remains. Do not treat the first extracted abstraction
+as done if review still reports medium or high difference.
+
+The promoted UI must follow the original design. Do not introduce new visual
+ideas while promoting: no extra decoration, layout chrome, icons, controls,
+copy, motion, spacing, state branches, or hierarchy that cannot be traced to the
+source UI or the user's screenshot. Token replacement and primitive composition
+are allowed only when they preserve the observed design and interaction path.
+
+Icons are part of that source-derived visual contract and must still enter the
+shared package through the UI-system icon layer. When the source UI uses an
+icon, first reuse an existing `@nextop-os/ui-system/icons` export. If no
+matching icon exists, promote the source-derived SVG or mark into
+`packages/ui/system/src/icons`, add metadata, and consume that exported icon
+from the business component or storyboard. Do not leave inline SVG/data URI
+icons, app-local asset imports, or direct third-party icon imports in promoted
+components or storyboard examples.
+
+Copy and classify dependent subcomponents during the same migration. If a
+nested helper is pure display, move it with the business component and convert
+host data to props. If it wraps a third-party UI behavior that is reusable
+outside the business domain, promote or reuse it as a `base` primitive first and
+compose it from the business component. If it owns host state, i18n lookup,
+daemon calls, router/filesystem access, persistence, or workflow orchestration,
+leave that behavior in the caller and replace the nested region with data,
+labels, callbacks, or slots. Do not rewrite a new nested component from memory
+while the original source behavior still exists to copy.
+
 Implement the promoted component directly from three inputs:
 
 - the code-evidence state matrix
 - the proposed public props and callback boundary
 - the existing candidate source UI or visual surface being extracted
 
-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.
+The promoted component should start as 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.
+Do not add states, controls, copy, icons, animation, or visual wrappers that the
+source component did not have unless the user explicitly asks for that design
+change.
+
+Generalize in this order:
+
+1. Copy the existing component structure and nearby presentational helpers.
+2. Trace dependent subcomponents and third-party wrappers; move pure display
+   helpers with the component, promote reusable third-party wrappers to `base`
+   primitives, and mark host-coupled children as caller-owned slots or data.
+3. Replace host imports, data derivation, i18n lookup, store reads, side effects,
+   and daemon/router/filesystem calls with props, labels, callbacks, or slots.
+4. Recreate the original visual states in storyboard before simplifying the API.
+5. Run independent review against the source UI and close material drift before
+   simplifying the API.
+6. Standardize the API names and types around data, labels, actions, variants,
+   and slots while preserving visual and behavioral parity.
+7. Replace app-local styling with UI-system tokens and base primitives only when
+   the replacement does not change the observed UI or interaction path.
+8. Reject or remove any invented UI added during promotion unless it is backed
+   by source evidence or an explicit user-approved visual change.
+
+Do not skip directly to a polished abstraction. If the first promoted version
+cannot be compared against the source screenshot or source state, the promotion
+is incomplete.
 
 If the draft still needs app state, navigation, fetching, persistence, i18n key
 lookup, or host adapters to render, stop and revise the component boundary
@@ -161,14 +227,22 @@ Expected chain:
      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. **Implement the promoted component**
-   - Adapt the current candidate source into the final
-     `packages/ui/system/src/components/<component-file>.tsx` component.
+4. **Implement the promoted component with copy-first parity**
+   - Copy the current candidate source into the final
+     `packages/ui/system/src/components/<component-dir>/index.tsx` component.
+   - Copy dependent presentational helpers and classify any third-party
+     wrappers before changing behavior. Reuse or promote base primitives for
+     reusable library wrappers instead of rebuilding them in the business file.
+   - Route icons through `@nextop-os/ui-system/icons`: reuse existing exports or
+     promote source-derived icons into the package icon layer with metadata
+     before using them in the component or storyboard.
    - 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 component.
+     placement, empty state, nested display helpers, and disabled/error branches.
+   - Replace host behavior with props, labels, callbacks, and caller-owned
+     slots: i18n lookup, queue state, confirmation dialog decisions, daemon
+     calls, and install orchestration stay outside the component.
+   - Only after storyboard parity is visible, simplify the copied API toward
+     durable `items`, `labels`, `actions`, explicit variants, and slots.
    - Make only package integration edits: final exported prop types, imports,
      class cleanup, and package-local helpers.
    - Export it from stable barrels.
@@ -196,18 +270,22 @@ Expected chain:
 
 ## Implementation
 
-1. Implement the business component by composing `base` primitives.
-2. Keep all host-owned behavior in the caller.
-3. Preserve the API composition decision. Do not add new mode booleans or
+1. Copy the existing business component structure into `packages/ui/system`
+   before abstracting it.
+2. Keep all host-owned behavior in the caller by replacing it with props,
+   labels, callbacks, or caller-owned slots.
+3. Preserve the source visual and interaction shape until storyboard parity is
+   visible.
+4. Standardize the API incrementally. 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
+5. Add stable exports and metadata with `layer: "business"`.
+6. Add storyboard examples for normal, empty, disabled, loading, and error-like
    states when those states exist in the public contract.
-6. Migrate callers by replacing only the visual surface.
-7. Run the promotion review gate from
+7. Migrate callers by replacing only the visual surface.
+8. 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.
+9. Start the design-foundation review subagent and resolve any reported drift.
 
 ## Validation
 

package/dist/{chunk-LVHEV755.js → chunk-AJCTWBHN.js}

@@ -9,12 +9,12 @@ import {
   FailedFilledIcon,
   LoadingIcon,
   SuccessFilledIcon
-} from "./chunk-GE5YVRTV.js";
+} from "./chunk-TYJPBTBR.js";
 import {
   cn
 } from "./chunk-DGPY4WP3.js";
 
-// src/components/badge.tsx
+// src/components/badge/badge.tsx
 import { cva } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import { jsx } from "react/jsx-runtime";
@@ -54,7 +54,7 @@ function Badge({
   );
 }
 
-// src/components/button.tsx
+// src/components/button/button.tsx
 import { cva as cva2 } from "class-variance-authority";
 import { Slot as Slot2 } from "radix-ui";
 import { jsx as jsx2 } from "react/jsx-runtime";
@@ -116,7 +116,7 @@ function Button({
   );
 }
 
-// src/components/card.tsx
+// src/components/card/card.tsx
 import { jsx as jsx3 } from "react/jsx-runtime";
 function Card({
   className,
@@ -209,7 +209,7 @@ function CardFooter({ className, ...props }) {
   );
 }
 
-// src/components/checkbox.tsx
+// src/components/checkbox/checkbox.tsx
 import { Checkbox as CheckboxPrimitive } from "radix-ui";
 import { jsx as jsx4 } from "react/jsx-runtime";
 function Checkbox({
@@ -237,7 +237,7 @@ function Checkbox({
   );
 }
 
-// src/components/dialog.tsx
+// src/components/dialog/dialog.tsx
 import * as React from "react";
 import { Dialog as DialogPrimitive } from "radix-ui";
 import { Fragment, jsx as jsx5, jsxs } from "react/jsx-runtime";
@@ -435,7 +435,7 @@ function DialogDescription({
   );
 }
 
-// src/components/confirmation-dialog.tsx
+// src/components/confirmation-dialog/confirmation-dialog.tsx
 import { jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
 function confirmToneClassName(tone) {
   if (tone === "destructive") {
@@ -525,7 +525,7 @@ function ConfirmationDialog({
   ) });
 }
 
-// src/components/date-picker.tsx
+// src/components/date-picker/date-picker.tsx
 import * as React2 from "react";
 import { createPortal } from "react-dom";
 import { Fragment as Fragment2, jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
@@ -881,10 +881,10 @@ var DatePicker = React2.forwardRef(
 );
 DatePicker.displayName = "DatePicker";
 
-// src/components/dropdown-menu.tsx
+// src/components/dropdown-menu/dropdown-menu.tsx
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
 
-// src/components/menu-surface.tsx
+// src/components/menu-surface/menu-surface.tsx
 import * as React3 from "react";
 import { Slot as Slot3 } from "radix-ui";
 import { jsx as jsx8 } from "react/jsx-runtime";
@@ -914,7 +914,7 @@ var MenuSurface = React3.forwardRef(
 );
 MenuSurface.displayName = "MenuSurface";
 
-// src/components/dropdown-menu.tsx
+// src/components/dropdown-menu/dropdown-menu.tsx
 import { jsx as jsx9, jsxs as jsxs4 } from "react/jsx-runtime";
 function DropdownMenu({
   ...props
@@ -1180,7 +1180,7 @@ function DropdownMenuSubContent({
   );
 }
 
-// src/components/input.tsx
+// src/components/input/input.tsx
 import { jsx as jsx10 } from "react/jsx-runtime";
 function Input({ className, size = "default", type, ...props }) {
   return /* @__PURE__ */ jsx10(
@@ -1199,7 +1199,7 @@ function Input({ className, size = "default", type, ...props }) {
   );
 }
 
-// src/components/popover.tsx
+// src/components/popover/popover.tsx
 import { Popover as PopoverPrimitive } from "radix-ui";
 import { jsx as jsx11 } from "react/jsx-runtime";
 function Popover({
@@ -1249,7 +1249,7 @@ function PopoverAnchor({
   return /* @__PURE__ */ jsx11(PopoverPrimitive.Anchor, { "data-slot": "popover-anchor", ...props });
 }
 
-// src/components/resizable.tsx
+// src/components/resizable/resizable.tsx
 import * as ResizablePrimitive from "react-resizable-panels";
 import { jsx as jsx12 } from "react/jsx-runtime";
 function ResizablePanelGroup({
@@ -1293,7 +1293,7 @@ function ResizableHandle({
   );
 }
 
-// src/components/scroll-area.tsx
+// src/components/scroll-area/scroll-area.tsx
 import { ScrollArea as ScrollAreaPrimitive } from "radix-ui";
 import { jsx as jsx13, jsxs as jsxs5 } from "react/jsx-runtime";
 function ScrollArea({
@@ -1349,7 +1349,7 @@ function ScrollBar({
   );
 }
 
-// src/components/select.tsx
+// src/components/select/select.tsx
 import { Select as SelectPrimitive } from "radix-ui";
 import { jsx as jsx14, jsxs as jsxs6 } from "react/jsx-runtime";
 function Select({
@@ -1607,7 +1607,7 @@ function SelectScrollDownButton({
   );
 }
 
-// src/components/separator.tsx
+// src/components/separator/separator.tsx
 import { Separator as SeparatorPrimitive } from "radix-ui";
 import { jsx as jsx15 } from "react/jsx-runtime";
 function Separator2({
@@ -1631,7 +1631,7 @@ function Separator2({
   );
 }
 
-// src/components/spinner.tsx
+// src/components/spinner/spinner.tsx
 import { jsx as jsx16 } from "react/jsx-runtime";
 function Spinner({
   className,
@@ -1659,7 +1659,7 @@ function Spinner({
   );
 }
 
-// src/components/status-dot.tsx
+// src/components/status-dot/status-dot.tsx
 import { cva as cva3 } from "class-variance-authority";
 import { jsx as jsx17 } from "react/jsx-runtime";
 var statusDotVariants = cva3("inline-flex shrink-0 rounded-full", {
@@ -1711,7 +1711,7 @@ function StatusDot({
   );
 }
 
-// src/components/switch.tsx
+// src/components/switch/switch.tsx
 import { Switch as SwitchPrimitive } from "radix-ui";
 import { jsx as jsx18 } from "react/jsx-runtime";
 function Switch({
@@ -1740,7 +1740,7 @@ function Switch({
   );
 }
 
-// src/components/textarea.tsx
+// src/components/textarea/textarea.tsx
 import { jsx as jsx19 } from "react/jsx-runtime";
 function Textarea({ className, ...props }) {
   return /* @__PURE__ */ jsx19(
@@ -1756,7 +1756,7 @@ function Textarea({ className, ...props }) {
   );
 }
 
-// src/components/toast.tsx
+// src/components/toast/toast.tsx
 import * as React4 from "react";
 import { Toast as ToastPrimitive } from "radix-ui";
 import { cva as cva4 } from "class-variance-authority";
@@ -1922,7 +1922,7 @@ function ToastViewport({
   );
 }
 
-// src/components/tooltip.tsx
+// src/components/tooltip/tooltip.tsx
 import { Tooltip as TooltipPrimitive } from "radix-ui";
 import { jsx as jsx21 } from "react/jsx-runtime";
 function TooltipProvider({
@@ -1975,7 +1975,7 @@ function TooltipContent({
   ) });
 }
 
-// src/components/underline-tabs.tsx
+// src/components/underline-tabs/underline-tabs.tsx
 import { useEffect as useEffect3, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState as useState3 } from "react";
 import { jsx as jsx22, jsxs as jsxs8 } from "react/jsx-runtime";
 function UnderlineTabs({
@@ -2174,7 +2174,7 @@ function UnderlineTabs({
   );
 }
 
-// src/components/viewport-menu-surface.tsx
+// src/components/viewport-menu-surface/viewport-menu-surface.tsx
 import * as React5 from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx23 } from "react/jsx-runtime";
@@ -2550,4 +2550,4 @@ export {
   UnderlineTabs,
   ViewportMenuSurface
 };
-//# sourceMappingURL=chunk-LVHEV755.js.map
+//# sourceMappingURL=chunk-AJCTWBHN.js.map