@monkey-mini-app/dsh-mini-app 0.1.0 → 0.1.4

package/skills/monkey-mini-app/references/contracts/textarea.md

@@ -0,0 +1,25 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Textarea (L1 primitive)
+
+Multi-line text input.
+
+**when** Notes/prompts. Code → `CodeEditor`; markdown → `MarkdownEditor`.
+
+`import { Textarea } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/textarea.tsx` · family: Form · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Textarea` | — |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+<Textarea rows={4} value={v} onChange={(e) => set(e.target.value)} />
+```

package/skills/monkey-mini-app/references/contracts/time-picker.md

@@ -1,12 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TimePicker
 
 `value` is `HH:mm` (24h).
 
+**when** Clock-only fields. `value` is a string, not a Date.
+
 `import { TimePicker } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/time-picker.tsx` · composites
+`packages/ui/src/composites/time-picker.tsx` · family: Calendar & date · type: composite
 
 ## Props
 
@@ -16,3 +18,17 @@
 | `disabled` | `boolean \| undefined` |  |  |
 | `onChange` | `((value: string) => void) \| undefined` |  |  |
 | `value` | `string \| undefined` |  |  |
+
+## Example
+
+```tsx
+<TimePicker value="09:30" onChange={(v) => set(v)} />
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[time-picker-01.tsx](../examples/time-picker/time-picker-01.tsx)** — TimePicker — Time-of-day only (no date) for windows like a daily cron or shift start.

package/skills/monkey-mini-app/references/contracts/time-range-picker.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TimeRangePicker
 
+From/to time of day.
+
+**when** Daily windows (maintenance 02:00–04:00).
+
 `import { TimeRangePicker, TimeRange } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/time-range-picker.tsx` · composites
+`packages/ui/src/composites/time-range-picker.tsx` · family: Calendar & date · type: composite
 
 ## Props
 
@@ -21,3 +25,17 @@
 |---|---|:---:|---|
 | `end` | `string` | ✓ |  |
 | `start` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<TimeRangePicker onChange={(r) => set(r)} />
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[time-range-picker-01.tsx](../examples/time-range-picker/time-range-picker-01.tsx)** — TimeRangePicker — Start/end time-of-day pair, e.g. a maintenance window inside one day.

package/skills/monkey-mini-app/references/contracts/time-wheel.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TimeWheel
 
+Column wheel for picking a time value.
+
+**when** Inside a time picker where tapping a list beats typing. Prefer `TimePicker` for a normal field.
+
 `import { TimeWheel, TimePickerProps } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/time-picker.tsx` · composites
+`packages/ui/src/composites/time-picker.tsx` · family: Calendar & date · type: composite
 
 ## Props
 

package/skills/monkey-mini-app/references/contracts/timeline.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # Timeline
 
+Vertical ordered events.
+
+**when** Statuses/history without durations. Durations → `RunTimeline`.
+
 `import { Timeline, TimelineItem } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/products/timeline.tsx` · products
+`packages/ui/src/products/timeline.tsx` · family: Realtime · type: product
 
 ## Props
 
@@ -22,3 +26,17 @@
 | `id` | `string` | ✓ |  |
 | `time` | `string \| undefined` |  |  |
 | `title` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<Timeline items={[{ id: "1", title: "已创建", time: "09:00" }]} />
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[timeline-01.tsx](../examples/timeline/timeline-01.tsx)** — Timeline — Chronological feed of events with actor + timestamp — deploy history, audit trail (compare RunTimeline for one job's steps).

package/skills/monkey-mini-app/references/contracts/timezone-select.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TimezoneSelect
 
+IANA timezone dropdown.
+
+**when** Pair with `DateTimePicker` when data is UTC.
+
 `import { TimezoneSelect, ZoneInfo } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/timezone-select.tsx` · composites
+`packages/ui/src/composites/timezone-select.tsx` · family: Calendar & date · type: composite
 
 ## Props
 
@@ -25,3 +29,17 @@
 | `offset` | `string` | ✓ |  |
 | `region` | `string` | ✓ |  |
 | `search` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<TimezoneSelect value={tz} onChange={(v) => set(v)} />
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[timezone-select-01.tsx](../examples/timezone-select/timezone-select-01.tsx)** — TimezoneSelect — IANA timezone chosen from common zones first, searchable — pair with DateTimePicker when schedules cross regions. — _*Common zones first; type to search the rest*_

package/skills/monkey-mini-app/references/contracts/toast.md

@@ -0,0 +1,39 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Toast (L1 primitive)
+
+Transient notification (provider + viewport + `toast()`).
+
+**when** Confirm/save failures. The host already mounts the provider — call `toast(...)`.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { Toast, ToastAction, ToastClose, ToastContent, ToastDescription, ToastPortal, ToastProvider, ToastTitle, ToastViewport, Toaster, createToastManager, toast, useToastManager } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/toast.tsx` · family: Feedback & status · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Toast` | `render?` `swipeDirection?` `toast` |
+| `ToastAction` | `nativeButton?` `render?` |
+| `ToastClose` | `nativeButton?` `render?` |
+| `ToastContent` | `render?` |
+| `ToastDescription` | `render?` |
+| `ToastPortal` | `container?` `render?` |
+| `ToastProvider` | `limit?` `timeout?` `toastManager?` |
+| `ToastTitle` | `render?` |
+| `ToastViewport` | `render?` |
+| `Toaster` | `limit?` `timeout?` `toastManager?` |
+| `createToastManager` (hook/util) | — |
+| `toast` (hook/util) | — |
+| `useToastManager` (hook/util) | — |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+toast({ title: "已保存", description: "2 条更新" })
+```

package/skills/monkey-mini-app/references/contracts/toggle-group.md

@@ -0,0 +1,28 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# ToggleGroup (L1 primitive)
+
+**when** Multiple independent on/off buttons; exclusive selection → `Tabs`/`ButtonGroup`.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { ToggleGroup, ToggleGroupItem } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/toggle-group.tsx` · family: Form · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `ToggleGroup` | `disabled?` `loopFocus?` `multiple?` `onValueChange?` `orientation?=vertical/horizontal` `render?` `size?=default/sm/lg` `spacing?` `value?` `variant?=default/outline` |
+| `ToggleGroupItem` | `defaultPressed?` `disabled?` `nativeButton?` `onPressedChange?` `pressed?` `render?` `size?=default/sm/lg` `value?` `variant?=default/outline` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[toggle-group-01.tsx](../examples/toggle-group/toggle-group-01.tsx)** — ToggleGroup — Mutually exclusive set of Toggle buttons for a view choice (alignment, density) held as one value.

package/skills/monkey-mini-app/references/contracts/toggle.md

@@ -0,0 +1,26 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Toggle (L1 primitive)
+
+**when** Binary formatting switch (bold, filters on).
+
+`import { Toggle, toggleVariants } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/toggle.tsx` · family: Form · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Toggle` | `defaultPressed?` `disabled?` `nativeButton?` `onPressedChange?` `pressed?` `render?` `size?=default/sm/lg` `value?` `variant?=default/outline` |
+| `toggleVariants` (hook/util) | `class?` `size?=default/sm/lg` `variant?=default/outline` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[toggle-01.tsx](../examples/toggle/toggle-01.tsx)** — Toggle — Single pressed/unpressed icon button (bold, mute) — one binary view option, not a form value; use Switch for settings on/off.

package/skills/monkey-mini-app/references/contracts/tooltip.md

@@ -0,0 +1,30 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Tooltip (L1 primitive)
+
+Hover/focus hint on an icon or truncated label.
+
+**when** Explaining an icon-only button. Never put an action in it.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/tooltip.tsx` · family: Surface · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Tooltip` | `actionsRef?` `defaultOpen?` `defaultTriggerId?` `disabled?` `disableHoverablePopup?` `handle?` `onOpenChange?` `onOpenChangeComplete?` `open?` `trackCursorAxis?=none/both/x/y` `triggerId?` |
+| `TooltipContent` | `align?` `alignOffset?` `render?` `side?` `sideOffset?` |
+| `TooltipProvider` | `closeDelay?` `delay?` `timeout?` |
+| `TooltipTrigger` | `closeDelay?` `closeOnClick?` `delay?` `disabled?` `handle?` `payload?` `render?` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+<Tooltip><TooltipTrigger asChild><Button size="icon" aria-label="刷新"><Icon.RefreshCw /></Button></TooltipTrigger><TooltipContent>刷新</TooltipContent></Tooltip>
+```

package/skills/monkey-mini-app/references/contracts/transfer.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # Transfer
 
+Two-panel move-between-lists picker.
+
+**when** Selecting many items from a known pool (assign users to a shift).
+
 `import { Transfer, TransferItem } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/transfer.tsx` · composites
+`packages/ui/src/composites/transfer.tsx` · family: Form · type: composite
 
 ## Props
 
@@ -22,3 +26,9 @@
 |---|---|:---:|---|
 | `id` | `string` | ✓ |  |
 | `label` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<Transfer items={[{ id: "u1", label: "张三" }]} onChange={(ids) => set(ids)} />
+```

package/skills/monkey-mini-app/references/contracts/tree-view.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TreeView
 
+Generic expandable node list.
+
+**when** Any hierarchy without file semantics. Files → `FileTree`.
+
 `import { TreeView, TreeNode } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/products/tree-view.tsx` · products
+`packages/ui/src/products/tree-view.tsx` · family: Data & tables · type: product
 
 ## Props
 
@@ -21,3 +25,17 @@
 | `children` | `TreeNode[] \| undefined` |  |  |
 | `id` | `string` | ✓ |  |
 | `label` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<TreeView nodes={[{ id: "a", label: "华东" }]} />
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[tree-view-01.tsx](../examples/tree-view/tree-view-01.tsx)** — TreeView — Nested hierarchy with expand/collapse and selection — file tree, org chart, category taxonomy.

package/skills/monkey-mini-app/references/contracts/trend-card.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # TrendCard
 
+KPI card with a trend series.
+
+**when** Metric + direction over time. Metric only → `StatCard`.
+
 `import { TrendCard, TrendPoint } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/blocks/trend-card.tsx` · blocks
+`packages/ui/src/blocks/trend-card.tsx` · family: Chart & data · type: block
 
 ## Props
 
@@ -24,3 +28,9 @@
 |---|---|:---:|---|
 | `label` | `string` | ✓ |  |
 | `value` | `number` | ✓ |  |
+
+## Example
+
+```tsx
+<TrendCard title="请求数" value="1.2k" trend="up" data={[{ value: 9 }, { value: 12 }]} />
+```

package/skills/monkey-mini-app/references/contracts/user-picker.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # UserPicker
 
+Pick a user from a list (avatar + name).
+
+**when** Assignee/owner fields; you supply the user list.
+
 `import { UserPicker, UserOption } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/composites/user-picker.tsx` · composites
+`packages/ui/src/composites/user-picker.tsx` · family: Form · type: composite
 
 ## Props
 
@@ -22,3 +26,9 @@
 |---|---|:---:|---|
 | `id` | `string` | ✓ |  |
 | `name` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<UserPicker users={[{ id: "u1", name: "张三" }]} onChange={(id) => set(id)} />
+```

package/skills/monkey-mini-app/references/contracts/wizard-shell.md

@@ -0,0 +1,56 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# WizardShell
+
+Multi-step flow: step rail on top, scrolling body, action row that never moves. Hand-rolled, a wizard's footer rides along inside the scrolling column, so every step change jumps the buttons to a different height and the user chases them with the cursor; and Next is enabled into an invalid step because the validity check lives in the form and the button lives outside it. Here the footer is a `shrink-0` sibling of the scroller, and Next/Finish are disabled straight from `steps[index].valid`, which is the only place that can know.
+
+**when** Page shape: create / import / onboarding, one step at a time with validation per step
+
+`import { WizardShell, WizardStep } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/blocks/wizard-shell.tsx` · family: Layout & structure · type: block
+
+## Props
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `body` | `ReactNode` | ✓ | Current step's content. The only scrolling area. |
+| `className` | `string \| undefined` |  |  |
+| `footer` | `ReactNode` |  | Replaces the generated Back/Next/Finish row (a preview pane, a second action…). |
+| `index` | `number` | ✓ | Which step is showing. The app owns it — the preset never navigates on its own. |
+| `onBack` | `(() => void) \| undefined` |  |  |
+| `onNext` | `(() => void) \| undefined` |  |  |
+| `onSubmit` | `(() => void) \| undefined` |  | Fires on the last step's primary action. Without it the last step still shows Next. |
+| `steps` | `WizardStep[]` | ✓ | The steps, in order. The rail is generated from this, so it cannot disagree with the body. |
+| `submitting` | `boolean \| undefined` |  | Greys the primary action and swaps in the busy label. |
+
+## Types
+
+### `WizardStep`
+
+| field | type | required | note |
+|---|---|:---:|---|
+| `id` | `string` | ✓ |  |
+| `label` | `string` | ✓ |  |
+| `valid` | `boolean \| undefined` |  | Pass `false` while the step's form is incomplete — Next disables itself. Omit to allow. |
+
+## Example
+
+```tsx
+<WizardShell
+  steps={[{ id: "pick", label: "Choose file", valid: Boolean(file) }, { id: "map", label: "Map columns", valid: mapped }]}
+  index={step}
+  body={<StepBody />}
+  onBack={() => setStep((s) => s - 1)}
+  onNext={() => setStep((s) => s + 1)}
+  onSubmit={() => void run()}
+/>
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[wizard-shell-01.tsx](../examples/wizard-shell/wizard-shell-01.tsx)** — WizardShell — Three-step import in a fixed-height panel: the step rail tracks progress, the body scrolls, and Back/Next stay exactly where they were across every step change. — _*Step 2 starts invalid — Next is disabled until the mapping is filled in*_