@plastic-js/tsumiki 0.1.22 → 0.1.24

package/docs/component-api-pattern.md

@@ -0,0 +1,362 @@
+# Tsumiki Component Guide
+
+A single reference for `@plastic-js/tsumiki` covering the component inventory & status (Classification) and the canonical component API pattern (API Pattern).
+
+---
+
+## Part 1 — Component Classification
+
+All 51 components are classified along two orthogonal axes.
+
+### Axis 1: Development Lifecycle
+
+Whether the component is ready for production use or still under active development.
+
+| Stage | Definition |
+|-------|------------|
+| **Completed** | Production-ready; API stable. |
+| **In Development** | Still being built; API may change. |
+
+### Axis 2: Architectural Foundation
+
+Whether the component is built on top of a same-named Ark primitive, or implemented independently.
+
+| Foundation | Definition |
+|------------|------------|
+| **Ark-Backed** | Directly wraps a corresponding `@plastic-js/ark` primitive of the same name. |
+| **Custom-Built** | Uses no Ark primitive; implemented with `@plastic-js/plastic`, `@emotion/css`, or the Web platform directly. |
+
+### Component Matrix
+
+#### Completed · Ark-Backed (30)
+
+| Component | Ark Primitive |
+|-----------|---------------|
+| Avatar | `ArkAvatar` |
+| Button | `ark("button")` via factory |
+| Checkbox | `ArkCheckbox` |
+| Collapsible | `ArkCollapsible` |
+| ColorPicker | `ArkColorPicker` |
+| Dialog | `ArkDialog` |
+| Drawer | `ArkDrawer` |
+| FileUpload | `ArkFileUpload` |
+| FocusTrap | `ArkFocusTrap` |
+| Input | `ark("input")` via factory |
+| Menu | `ArkMenu` |
+| NumberInput | `ArkNumberInput` |
+| Pagination | `ArkPagination` |
+| Popover | `ArkPopover` |
+| Portal | `ArkPortal` |
+| Presence | `ArkPresence` |
+| Progress | `ArkProgress` |
+| RadioGroup | `ArkRadioGroup` |
+| RatingGroup | `ArkRatingGroup` |
+| SelectPc | `ArkSelect` |
+| SignaturePad | `ArkSignaturePad` |
+| Slider | `ArkSlider` |
+| Splitter | `ArkSplitter` |
+| Steps | `ArkSteps` |
+| Switch | `ArkSwitch` |
+| Tabs | `ArkTabs` |
+| TagsInput | `ArkTagsInput` |
+| Toast | `ArkToast` |
+| Toggle | `ArkToggle` |
+| ToggleGroup | `ArkToggleGroup` |
+
+#### Completed · Custom-Built (15)
+
+| Component | Built With |
+|-----------|------------|
+| BottomSheet | `@plastic-js/plastic` + `Portal` |
+| CardNumberInput | Composes `Input` |
+| Clipboard | Web Clipboard API |
+| CloseButton | `@emotion/css` |
+| ConfirmDialog | Composes `Dialog` |
+| DateInput | `DateWheel` utility |
+| Field | `@emotion/css` |
+| Fieldset | `@emotion/css` |
+| Icon | `@emotion/css` |
+| MoneyInput | Composes `Input` |
+| SearchInput | Composes `Input` |
+| Select | Custom state machine with `Loop` |
+| Skeleton | Pure CSS |
+| Spinner | Pure CSS |
+| SwipeReveal | Touch event gestures |
+
+#### In Development · Ark-Backed (6)
+
+| Component | Ark Primitive |
+|-----------|---------------|
+| Accordion | `ArkAccordion` |
+| Carousel | `ArkCarousel` |
+| Combobox | `ArkCombobox` |
+| Listbox | `ArkListbox` |
+| Tour | `ArkTour` |
+| TreeView | `ArkTreeView` |
+
+#### In Development · Custom-Built (0)
+
+*No components currently in this quadrant.*
+
+### Summary
+
+```
+                    Ark-Backed          Custom-Built
+                  ┌─────────────────┬─────────────────┐
+    Completed     │       30        │       15        │  45
+                  ├─────────────────┼─────────────────┤
+ In Development   │        6        │        0        │   6
+                  └─────────────────┴─────────────────┘
+                        36                   15          51
+```
+
+---
+
+## Part 2 — Component API Pattern
+
+This section defines the canonical component API pattern for `@plastic-js/tsumiki`.
+
+### Design Goals
+
+1. **Simplify Ark APIs** — tsumiki wraps `@plastic-js/ark` components with theme styling, default props, and opinionated presets
+2. **Unified consumer experience** — all components follow the same access pattern
+3. **Escape hatch** — consumers can always reach the raw Ark component when needed
+4. **Controlled-only** — all tsumiki components are controlled; uncontrolled mode (`defaultValue`, `defaultOpen`, `defaultChecked`, etc.) is NOT supported even if the underlying Ark component supports it
+
+### Core Rules
+
+#### Rule 0: Controlled-Only — No Uncontrolled Mode
+
+Tsumiki does not support uncontrolled mode. Every component that manages state (`value`, `open`, `checked`, etc.) must receive it as a controlled signal prop and report changes via a callback. No `defaultValue`, `defaultOpen`, `defaultChecked`, or similar props exist on tsumiki components.
+
+```jsx
+// CORRECT: Controlled — consumer owns the state signal
+const isOpen = createSignal(false)
+<Dialog open={isOpen} onOpenChange={v => isOpen(v.open)} />
+
+// WRONG: Uncontrolled (not supported)
+<Dialog defaultOpen />
+```
+
+If a consumer wants an initial value, they set it in their own `createSignal()` call. No tsumiki component creates internal state for uncontrolled usage.
+
+**Rationale:**
+- State ownership is explicit and predictable
+- Components are easier to test and debug
+- The entire API follows a uniform `value`/`onValueChange` contract
+- While Ark primitives may technically accept `default*` props internally, consumers must not rely on this — tsumiki reserves the right to break uncontrolled usage
+
+#### Rule 1: The default export IS the render component
+
+```jsx
+import { Comp as ArkComp } from '@plastic-js/ark'
+
+const Comp = (props = {}) => (
+  <ArkComp.Root className={styles} {...rest}>
+    {/* tsumiki theme styling */}
+  </ArkComp.Root>
+)
+
+export default Comp
+```
+
+The default export is always a **renderable component**. It wraps Ark's root with:
+- CSS-in-JS via `@emotion/css`
+- `var(--tsu-*)` design tokens
+- `splitProps` / `mergeProps` for prop defaults
+- Simplified, opinionated default behavior
+
+#### Rule 2: `.origin` maps to raw Ark components
+
+```js
+Comp.origin = {
+  Root: ArkComp.Root,
+  Label: ArkComp.Label,
+  Control: ArkComp.Control,
+}
+```
+
+- **`.origin`** (lowercase) is the **only** static property on the component
+- It maps tsumiki-friendly names to their raw `@plastic-js/ark` counterparts
+- Only mount what exists on the Ark component — if Ark has no `Label` sub-part, don't add it
+- The `origin` object serves as the **escape hatch** for consumers who need direct access to Ark's full API
+
+#### Rule 3: No other static properties
+
+```js
+// ❌ WRONG — do not attach sub-components as direct properties
+Comp.Root = Comp
+Comp.Trigger = SomeTrigger
+Comp.Content = SomeContent
+
+// ❌ WRONG — do not use Object.assign to spread sub-components
+const Comp = Object.assign(CompRoot, { Root: CompRoot, Trigger, Content })
+
+// ✅ CORRECT — only .origin
+Comp.origin = { Root: ArkComp.Root, Trigger: ArkComp.Trigger, Content: ArkComp.Content }
+```
+
+The component function itself carries **nothing** except `.origin`.
+
+#### Rule 4: Components without an Ark counterpart have no `.origin`
+
+```js
+// Fully custom component (no Ark import at all)
+import { css } from '@emotion/css'
+
+const Spinner = (props = {}) => <div>...</div>
+
+// No .origin — there is no Ark counterpart
+export default Spinner
+```
+
+#### Rule 5: Sub-components (when needed) are named exports
+
+For components that have meaningful, tsumiki-wrapped sub-components (see [Multi-Part Component Pattern](#multi-part-component-pattern)), sub-components are exported as **named exports** from the module, NOT attached to the default export.
+
+#### Rule 6: Dual export (default + named)
+
+Every component module **must** export both a default and a named export for the top-level component:
+
+```js
+export default Comp
+export { Comp }
+```
+
+This ensures consumers can import using either style:
+
+```js
+import Comp from '@plastic-js/tsumiki/components/Comp.jsx'
+import { Comp } from '@plastic-js/tsumiki/components/Comp.jsx'
+```
+
+When the internal variable name differs from the component name, use an alias:
+
+```js
+export default Root
+export { Root as FileUpload }
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Ark import alias | `Ark` + PascalCase name | `import { Dialog as ArkDialog }` |
+| Component function | PascalCase, same as default export name | `const Dialog = (props) => ...` |
+| origin keys | PascalCase, matching Ark sub-part names | `{ Root, Trigger, Content }` |
+| `.origin` property | lowercase `origin` | `Dialog.origin = { ... }` |
+| CSS class variables | `camelCase` + `Class` suffix | `rootClass`, `contentClass` |
+
+### Consumer Usage
+
+#### Simple component (single wrapper)
+
+```jsx
+import { Button } from '@plastic-js/tsumiki'
+
+// Primary usage: tsumiki-styled
+<Button solid>Click me</Button>
+
+// Escape hatch: raw Ark API
+<Button.origin.Root>...</Button.origin.Root>
+```
+
+#### Simple component wrapping multiple Ark sub-parts
+
+```jsx
+import { Checkbox } from '@plastic-js/tsumiki'
+
+// Primary usage: tsumiki-styled (wraps Root + Control + Indicator + Label + HiddenInput)
+<Checkbox>Accept terms</Checkbox>
+
+// Escape hatch: individual raw Ark sub-parts
+<Checkbox.origin.Root>
+  <Checkbox.origin.Control>
+    <Checkbox.origin.Indicator />
+  </Checkbox.origin.Control>
+</Checkbox.origin.Root>
+```
+
+#### Multi-part component (see below)
+
+```jsx
+import Menu, { MenuTrigger, MenuContent, MenuItem } from '@plastic-js/tsumiki'
+
+<Menu>
+  <MenuTrigger>Open</MenuTrigger>
+  <MenuContent>
+    <MenuItem>Action</MenuItem>
+  </MenuContent>
+</Menu>
+
+// Escape hatch
+<Menu.origin.Root>
+  <Menu.origin.Trigger>...</Menu.origin.Trigger>
+  <Menu.origin.Content>...</Menu.origin.Content>
+</Menu.origin.Root>
+```
+
+### Multi-Part Component Pattern
+
+For components that have meaningful tsumiki-wrapped sub-components (e.g., Menu, Dialog, Accordion), each sub-component is a named export:
+
+```jsx
+import { Menu as ArkMenu } from '@plastic-js/ark'
+
+// Default export: the root wrapper
+const Menu = (props = {}) => (
+  <ArkMenu.Root className={rootClass} {...rest}>
+    {children}
+  </ArkMenu.Root>
+)
+
+// Named exports: tsumiki-wrapped sub-components
+export const MenuTrigger = (props = {}) => (
+  <ArkMenu.Trigger className={triggerClass} {...rest}>
+    {children}
+  </ArkMenu.Trigger>
+)
+
+export const MenuContent = (props = {}) => (
+  <ArkMenu.Content className={contentClass} {...rest}>
+    {children}
+  </ArkMenu.Content>
+)
+
+Menu.origin = {
+  Root: ArkMenu.Root,
+  Trigger: ArkMenu.Trigger,
+  Content: ArkMenu.Content,
+}
+
+export default Menu
+```
+
+#### Barrel exports for multi-part components
+
+In `src/index.js`, both default and named exports are re-exported:
+
+```js
+export {
+  default as Menu,
+  MenuTrigger,
+  MenuContent,
+  MenuItem,
+  MenuSeparator,
+} from './components/Menu.jsx'
+```
+
+### File Structure
+
+```
+src/components/Comp.jsx
+├── imports (@emotion/css, @plastic-js/ark, @plastic-js/plastic)
+├── CSS class definitions (rootClass, triggerClass, etc.)
+├── Component function (default export)
+├── [Named exports for sub-components, if multi-part]
+├── .origin assignment
+├── export default Comp
+└── export { Comp }
+```
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plastic-js/tsumiki",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "A UI component library for Plastic JS.",
   "license": "MIT",
   "author": "tigre",
@@ -27,10 +27,15 @@
     ".": {
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./styles": "./dist/tsumiki.css",
+    "./tsumiki.css": "./dist/tsumiki.css",
+    "./styles/*": "./src/styles/*"
   },
   "files": [
     "dist",
+    "src/styles",
+    "docs",
     "LICENSE",
     "README.md"
   ],
@@ -40,23 +45,28 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "vite build && npm run build:styles",
+    "build:styles": "vite build --config vite.styles.config.js && cp dist-styles/*.css dist/tsumiki.css && rm -rf dist-styles",
     "prepublishOnly": "npm run build",
     "preview": "vite preview",
+    "theme": "node scripts/theme.js",
     "e2e:repro": "node e2e/dlgcbx-repro.mjs"
   },
   "dependencies": {
     "@emotion/css": "^11.13.5",
-    "@plastic-js/ark": "^1.0.12",
-    "@plastic-js/plastic": "^1.0.22",
+    "@zag-js/select": "1.40.0",
     "popmotion": "^11.0.5"
   },
   "peerDependencies": {
-    "@zag-js/combobox": "1.40.0"
+    "@plastic-js/ark": "^1.0.16",
+    "@plastic-js/plastic": "^1.0.22"
   },
   "devDependencies": {
     "@babel/core": "^7.29.7",
+    "@plastic-js/ark": "^1.0.16",
     "@plastic-js/babel-preset-plastic": "^0.1.11",
+    "@plastic-js/plastic": "^1.0.22",
+    "@radix-ui/colors": "^3.0.0",
     "@zag-js/combobox": "1.40.0",
     "puppeteer-core": "^25.1.0",
     "vite": "^8.0.15"

package/src/styles/color.css

@@ -0,0 +1,112 @@
+@import './theme.css';
+@import '@radix-ui/colors/red.css';
+@import '@radix-ui/colors/red-alpha.css';
+@import '@radix-ui/colors/red-dark.css';
+@import '@radix-ui/colors/red-dark-alpha.css';
+@import '@radix-ui/colors/green.css';
+@import '@radix-ui/colors/green-alpha.css';
+@import '@radix-ui/colors/green-dark.css';
+@import '@radix-ui/colors/green-dark-alpha.css';
+@import '@radix-ui/colors/amber.css';
+@import '@radix-ui/colors/amber-alpha.css';
+@import '@radix-ui/colors/amber-dark.css';
+@import '@radix-ui/colors/amber-dark-alpha.css';
+
+:root {
+  --tsu-bg: var(--tsu-neutral-1);
+  --tsu-fg: var(--tsu-neutral-12);
+
+  /* Info (accent) — full 12-step palette */
+  --tsu-info-1: var(--tsu-accent-1);
+  --tsu-info-2: var(--tsu-accent-2);
+  --tsu-info-3: var(--tsu-accent-3);
+  --tsu-info-4: var(--tsu-accent-4);
+  --tsu-info-5: var(--tsu-accent-5);
+  --tsu-info-6: var(--tsu-accent-6);
+  --tsu-info-7: var(--tsu-accent-7);
+  --tsu-info-8: var(--tsu-accent-8);
+  --tsu-info-9: var(--tsu-accent-9);
+  --tsu-info-10: var(--tsu-accent-10);
+  --tsu-info-11: var(--tsu-accent-11);
+  --tsu-info-12: var(--tsu-accent-12);
+
+  /* Danger (red) */
+  --tsu-danger-1: var(--red-1);
+  --tsu-danger-2: var(--red-2);
+  --tsu-danger-3: var(--red-3);
+  --tsu-danger-4: var(--red-4);
+  --tsu-danger-5: var(--red-5);
+  --tsu-danger-6: var(--red-6);
+  --tsu-danger-7: var(--red-7);
+  --tsu-danger-8: var(--red-8);
+  --tsu-danger-9: var(--red-9);
+  --tsu-danger-10: var(--red-10);
+  --tsu-danger-11: var(--red-11);
+  --tsu-danger-12: var(--red-12);
+
+  /* Success (green) */
+  --tsu-success-1: var(--green-1);
+  --tsu-success-2: var(--green-2);
+  --tsu-success-3: var(--green-3);
+  --tsu-success-4: var(--green-4);
+  --tsu-success-5: var(--green-5);
+  --tsu-success-6: var(--green-6);
+  --tsu-success-7: var(--green-7);
+  --tsu-success-8: var(--green-8);
+  --tsu-success-9: var(--green-9);
+  --tsu-success-10: var(--green-10);
+  --tsu-success-11: var(--green-11);
+  --tsu-success-12: var(--green-12);
+
+  /* Warning (amber) */
+  --tsu-warning-1: var(--amber-1);
+  --tsu-warning-2: var(--amber-2);
+  --tsu-warning-3: var(--amber-3);
+  --tsu-warning-4: var(--amber-4);
+  --tsu-warning-5: var(--amber-5);
+  --tsu-warning-6: var(--amber-6);
+  --tsu-warning-7: var(--amber-7);
+  --tsu-warning-8: var(--amber-8);
+  --tsu-warning-9: var(--amber-9);
+  --tsu-warning-10: var(--amber-10);
+  --tsu-warning-11: var(--amber-11);
+  --tsu-warning-12: var(--amber-12);
+
+  /* Neutral Alpha Overlay (used for shadows/elevation) */
+  --tsu-neutral-alpha-1: var(--olive-a1);
+  --tsu-neutral-alpha-2: var(--olive-a2);
+  --tsu-neutral-alpha-3: var(--olive-a3);
+  --tsu-neutral-alpha-4: var(--olive-a4);
+  --tsu-neutral-alpha-5: var(--olive-a5);
+  --tsu-neutral-alpha-6: var(--olive-a6);
+  --tsu-neutral-alpha-7: var(--olive-a7);
+  --tsu-neutral-alpha-8: var(--olive-a8);
+  --tsu-neutral-alpha-9: var(--olive-a9);
+  --tsu-neutral-alpha-10: var(--olive-a10);
+  --tsu-neutral-alpha-11: var(--olive-a11);
+  --tsu-neutral-alpha-12: var(--olive-a12);
+
+  /* Disabled State */
+  --tsu-disabled-bg: var(--tsu-neutral-3);
+  --tsu-disabled-fg: var(--tsu-neutral-9);
+  --tsu-disabled-border: var(--tsu-neutral-7);
+
+  /* Focus State */
+  --tsu-focus-bg: var(--tsu-neutral-2);
+  --tsu-focus-border: var(--tsu-accent-8);
+
+  /* Legacy Aliases — map old variable names to new token system */
+  --ink: var(--tsu-fg);
+  --muted: var(--tsu-neutral-11);
+  --accent: var(--tsu-accent-9);
+  --surface: var(--tsu-bg);
+  --bg: var(--tsu-neutral-2);
+  --border: var(--tsu-neutral-7);
+  --danger: var(--tsu-danger-9);
+}
+
+/* Dark mode: use a lighter page background */
+:root.dark {
+  --tsu-bg: var(--tsu-neutral-3);
+  --tsu-fg: #ffffff;
+}

package/src/styles/index.css

@@ -0,0 +1 @@
+@import './reset.css';

package/src/styles/radius.css

@@ -0,0 +1,27 @@
+:root {
+  --tsu-radius-round: 9999px;
+
+  --tsu-radius-l3-xs: 16px;
+  --tsu-radius-l2-xs: 8px;
+  --tsu-radius-l1-xs: 2px;
+
+  --tsu-radius-l3-sm: 16px;
+  --tsu-radius-l2-sm: 8px;
+  --tsu-radius-l1-sm: 2px;
+
+  --tsu-radius-l3-md: 16px;
+  --tsu-radius-l2-md: 8px;
+  --tsu-radius-l1-md: 4px;
+
+  --tsu-radius-l3-lg: 16px;
+  --tsu-radius-l2-lg: 8px;
+  --tsu-radius-l1-lg: 6px;
+
+  --tsu-radius-l3-xl: 16px;
+  --tsu-radius-l2-xl: 8px;
+  --tsu-radius-l1-xl: 8px;
+
+  --tsu-radius-l3-xxl: 16px;
+  --tsu-radius-l2-xxl: 8px;
+  --tsu-radius-l1-xxl: 16px;
+}

package/src/styles/reset.css

@@ -0,0 +1,111 @@
+@import './tokens.css';
+
+/* ── Modern CSS Reset ─────────────────────────────────────────────── */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -moz-text-size-adjust: none;
+  -webkit-text-size-adjust: none;
+  text-size-adjust: none;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  -webkit-tap-highlight-color: rgba(0,0,0,0);
+}
+
+body {
+  min-height: 100vh;
+  font-family: var(--tsu-font-family);
+  font-size: var(--tsu-font-size-md);
+  line-height: var(--tsu-line-height);
+  color: var(--tsu-fg);
+  background-color: var(--tsu-bg);
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-inline-size: 100%;
+}
+
+input,
+button,
+textarea,
+select {
+  font: inherit;
+  color: inherit;
+}
+
+p,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}
+
+p {
+  text-wrap: pretty;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  text-wrap: balance;
+  font-weight: 600;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+textarea:not([rows]) {
+  min-height: 10em;
+}
+
+:target {
+  scroll-margin-block: 5ex;
+}
+
+:where(ul, ol) {
+  list-style: none;
+}
+
+:where(table) {
+  border-collapse: collapse;
+  border-spacing: 0;
+}
+
+:where(button) {
+  appearance: none;
+  background: none;
+  border: none;
+  cursor: pointer;
+}
+
+:where([hidden]) {
+  display: none;
+}
+
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-ms-clear {
+  display: none;
+}

package/src/styles/shadow.css

@@ -0,0 +1,5 @@
+:root {
+  --tsu-shadow-sm: 0 1px 2px var(--tsu-neutral-alpha-6);
+  --tsu-shadow-md: 0 4px 12px var(--tsu-neutral-alpha-8);
+  --tsu-shadow-lg: 0 8px 24px var(--tsu-neutral-alpha-10);
+}