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

package/skills/monkey-mini-app/references/examples/scrollspy/scrollspy-01.tsx

@@ -0,0 +1,29 @@
+/**
+ * @exampleOf Scrollspy
+ * @title Scrollspy
+ * @scenario Section nav that highlights whichever section is currently in view — long settings/docs pages; wire it to element ids.
+ */
+import { Scrollspy } from "@monkey-mini-app/ui";
+
+export default function Scrollspy01Example() {
+  return (
+    <>
+      <div className="grid grid-cols-[8rem_1fr] gap-4">
+        <Scrollspy
+          sections={[
+            { id: "alpha", label: "Alpha" },
+            { id: "beta", label: "Beta" },
+          ]}
+        />
+        <div className="h-32 overflow-auto text-sm">
+          <div id="alpha" className="h-24">
+            Alpha section
+          </div>
+          <div id="beta" className="h-24">
+            Beta section
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/separator/separator-01.tsx

@@ -0,0 +1,10 @@
+/**
+ * @exampleOf Separator
+ * @title Separator
+ * @scenario Horizontal or vertical rule that inherits theme spacing, for splitting toolbar groups and metadata rows.
+ */
+import { Separator } from "@monkey-mini-app/ui";
+
+export default function Separator01Example() {
+  return <Separator />;
+}

package/skills/monkey-mini-app/references/examples/settings-split/settings-split-01.tsx

@@ -0,0 +1,84 @@
+/**
+ * @exampleOf SettingsSplit
+ * @title SettingsSplit
+ * @scenario A settings page in a fixed-height panel: the jump list tracks the section you are reading, each side scrolls on its own, and the unsaved bar stays pinned to the content pane.
+ * @hint Scroll the sections — the nav highlight follows; edit a field and the save bar appears without the layout moving
+ */
+import * as React from "react";
+
+import { Button, Input, NativeSelect, SettingsSplit } from "@monkey-mini-app/ui";
+
+const GROUPS = [
+  {
+    id: "general",
+    label: "General",
+    description: "Name, timezone, first day of week",
+    rows: ["Display name", "Timezone"],
+  },
+  {
+    id: "notify",
+    label: "Notifications",
+    description: "Where events land",
+    rows: ["Email", "Webhook URL"],
+  },
+  {
+    id: "data",
+    label: "Data",
+    description: "Retention and exports",
+    rows: ["Retention days", "Export format"],
+  },
+  {
+    id: "danger",
+    label: "Danger zone",
+    description: "Irreversible, on purpose",
+    rows: ["Workspace slug"],
+  },
+];
+
+export default function SettingsSplit01Example() {
+  const [dirty, setDirty] = React.useState(false);
+  const edit = () => setDirty(true);
+
+  return (
+    <div className="h-[460px]">
+      <SettingsSplit
+        nav={<p className="text-sm font-medium">Workspace settings</p>}
+        sections={GROUPS.map((g) => ({
+          id: g.id,
+          label: g.label,
+          description: g.description,
+          content: (
+            <div className="flex flex-col gap-3">
+              {g.rows.map((r) => (
+                <label key={r} className="flex flex-col items-start gap-1 text-sm">
+                  <span className="text-muted-foreground text-xs">{r}</span>
+                  {r === "Export format" ? (
+                    <NativeSelect onChange={edit}>
+                      <option value="csv">CSV</option>
+                      <option value="json">JSON</option>
+                    </NativeSelect>
+                  ) : (
+                    <Input defaultValue={r.toLowerCase().replace(/ /g, "-")} onChange={edit} />
+                  )}
+                </label>
+              ))}
+            </div>
+          ),
+        }))}
+        footer={
+          dirty ? (
+            <div className="flex items-center gap-3">
+              <span className="text-muted-foreground text-sm">Unsaved changes</span>
+              <Button size="sm" onClick={() => setDirty(false)}>
+                Save
+              </Button>
+              <Button size="sm" variant="ghost" onClick={() => setDirty(false)}>
+                Discard
+              </Button>
+            </div>
+          ) : undefined
+        }
+      />
+    </div>
+  );
+}

package/skills/monkey-mini-app/references/examples/shared/jira-wiki-sample.ts

@@ -0,0 +1,38 @@
+export const JIRA_WIKI_SAMPLE = [
+  "h2. Expected Behavior",
+  "",
+  "Users manage bonded parts in LX with full lifecycle support and standard bonded part attributes (part number, effective dates, active flag, audit fields as applicable).",
+  "",
+  "MOCK UI: [^bonded-parts-prototype.html]",
+  "",
+  "h2. Acceptance Criteria",
+  "",
+  "URL: [https://wd-stg.teslamotors.com/warpgt/gt/warpglobaltrade]",
+  "* UI supports: create, update, delete, and review bonded parts records.",
+  "* UI supports: download bonded parts list to Excel.",
+  "* UI supports: bulk upload to add, update, and delete records (per defined template and validation rules).",
+  "* Search/filter by: Part Number, Active Flag, Effective From, Effective To.",
+  "* Role/permission model aligns with existing LX Warp Trade maintenance patterns (confirm with PM if new roles are needed).",
+  "",
+  "h2. Validation",
+  "",
+  "* Create/update/review: bonded parts records can be managed end-to-end in the LX UI.",
+  "* Excel download matches grid/filter selection; bulk upload succeeds for add/update/delete scenarios and surfaces validation errors clearly.",
+  "* Search filters return expected subsets for Part Number, Active Flag, Effective From, Effective To.",
+  "",
+  "h3. Open Questions",
+  "",
+  "-pending UI mockup and review the implementation detail-",
+  "",
+  "how to manage the user permissions?",
+  "",
+  "From Coco:",
+  "",
+  "_Just talked to Hailin, it's better to have a separate role and permission for this UI because very limited people in China Trade team will have edit permission. This also prevents from trade team members from other regions accidentally modify the record in this UI._",
+  "",
+  "|Role|Role Owner Approval?|Permission|",
+  "|WarpTradeBonedPartEdit|YES|Creation Delete Modification|",
+  "|WarpTradeBonedPartView|YES|Read Only|",
+  "",
+  "You can put me, Hailin, and Elaine Xie (谢靜芳) as the role owner for approval.",
+].join("\n");

package/skills/monkey-mini-app/references/examples/skeleton/skeleton-01.tsx

@@ -0,0 +1,10 @@
+/**
+ * @exampleOf Skeleton
+ * @title Skeleton
+ * @scenario Loading placeholder shaped like the content that will replace it (cards/rows), avoiding layout jump on first paint.
+ */
+import { Skeleton } from "@monkey-mini-app/ui";
+
+export default function Skeleton01Example() {
+  return <Skeleton className="h-6 w-48" />;
+}

package/skills/monkey-mini-app/references/examples/slider/slider-01.tsx

@@ -0,0 +1,22 @@
+/**
+ * @exampleOf Slider
+ * @title Slider / SliderRange
+ * @scenario One-handle range for 'pick a value' (thresholds, limits); SliderRange beside it for min–max filter pairs.
+ */
+import * as React from "react";
+
+import { Slider, SliderRange } from "@monkey-mini-app/ui";
+
+export default function Slider01Example() {
+  const [range, setRange] = React.useState([20, 80]);
+  const [slider, setSlider] = React.useState([40]);
+
+  return (
+    <>
+      <div className="flex max-w-sm flex-col gap-4">
+        <Slider value={slider} onValueChange={(v) => setSlider(Array.from(v as number[]))} />
+        <SliderRange value={range} onChange={setRange} />
+      </div>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/sortable-list/sortable-list-01.tsx

@@ -0,0 +1,18 @@
+/**
+ * @exampleOf SortableList
+ * @title SortableList
+ * @scenario Reorder by drag with the new order pushed back to state — priorities, playbooks, column order.
+ */
+import * as React from "react";
+
+import { type SortableItem, SortableList } from "@monkey-mini-app/ui";
+
+export default function SortableList01Example() {
+  const [items, setItems] = React.useState<SortableItem[]>([
+    { id: "1", label: "Alpha" },
+    { id: "2", label: "Bravo" },
+    { id: "3", label: "Charlie" },
+  ]);
+
+  return <SortableList items={items} onChange={setItems} />;
+}

package/skills/monkey-mini-app/references/examples/spinner/spinner-01.tsx

@@ -0,0 +1,10 @@
+/**
+ * @exampleOf Spinner
+ * @title Spinner
+ * @scenario Unknown-duration busy indicator inline in a button or row; prefer Progress when you can report percent.
+ */
+import { Spinner } from "@monkey-mini-app/ui";
+
+export default function Spinner01Example() {
+  return <Spinner />;
+}

package/skills/monkey-mini-app/references/examples/stepper/stepper-01.tsx

@@ -0,0 +1,41 @@
+/**
+ * @exampleOf Stepper
+ * @title Stepper
+ * @scenario Multi-step flow (draft → review → ship) with completed/active/pending states, vertical and horizontal.
+ * @hint Vertical and horizontal
+ */
+import * as React from "react";
+
+import { Stepper, StepperItem } from "@monkey-mini-app/ui";
+
+export default function Stepper01Example() {
+  const [step, setStep] = React.useState(1);
+
+  return (
+    <>
+      <div className="flex flex-col gap-6">
+        <Stepper>
+          <StepperItem
+            title="Draft"
+            description="Write the change"
+            status={step > 0 ? "completed" : "active"}
+          />
+          <StepperItem
+            title="Review"
+            description="QA sign-off"
+            status={step > 1 ? "completed" : step === 1 ? "active" : "default"}
+          />
+          <StepperItem title="Done" description="Shipped" status={step >= 2 ? "active" : "default"} />
+        </Stepper>
+        <Stepper orientation="horizontal">
+          <StepperItem title="Draft" status={step > 0 ? "completed" : "active"} />
+          <StepperItem title="Review" status={step > 1 ? "completed" : step === 1 ? "active" : "default"} />
+          <StepperItem title="Done" status={step >= 2 ? "active" : "default"} />
+        </Stepper>
+      </div>
+      <button type="button" className="mt-2 text-sm underline" onClick={() => setStep((s) => (s + 1) % 3)}>
+        Next step
+      </button>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/table/table-01.tsx

@@ -0,0 +1,25 @@
+/**
+ * @exampleOf Table
+ * @title Table
+ * @scenario Static, semantic table you lay out by hand — small fixed datasets; switch to DataGrid the moment you need sort/filter/pagination.
+ */
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@monkey-mini-app/ui";
+
+export default function Table01Example() {
+  return (
+    <>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Col</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableCell>Row</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/table-page/table-page-01.tsx

@@ -0,0 +1,103 @@
+/**
+ * @exampleOf TablePage
+ * @title TablePage
+ * @scenario A wide table as the whole product: the filter bar stays pinned, only the grid scrolls, and ticking rows floats a bulk bar over the bottom without moving a single row.
+ * @hint Scroll the table — the toolbar stays put; select rows — the bar floats over the grid, it never pushes rows down
+ */
+import * as React from "react";
+
+import { Checkbox, type ColumnDef, DataGrid, Input, TablePage } from "@monkey-mini-app/ui";
+
+type Part = { sku: string; name: string; bin: string; qty: number };
+
+const PARTS: Part[] = Array.from({ length: 60 }, (_, i) => ({
+  sku: `SKU-${2400 - i}`,
+  name: [
+    "Bracket, left-hand",
+    "Seal kit, 40 mm",
+    "Harness, 2 m shielded",
+    "Bearing, sealed 6204",
+    "Label cartridge, black",
+  ][i % 5],
+  bin: `${String.fromCharCode(65 + (i % 6))}-${(i % 24) + 1}`,
+  qty: ((i * 37) % 480) + 4,
+}));
+
+export default function TablePage01Example() {
+  const [query, setQuery] = React.useState("");
+  const [picked, setPicked] = React.useState<Record<string, boolean>>({});
+
+  const rows = PARTS.filter(
+    (p) => !query || p.name.toLowerCase().includes(query.toLowerCase()) || p.sku.includes(query),
+  );
+  const count = Object.values(picked).filter(Boolean).length;
+  const allPicked = rows.length > 0 && rows.every((p) => picked[p.sku]);
+
+  const columns: ColumnDef<Part>[] = React.useMemo(
+    () => [
+      {
+        id: "pick",
+        header: () => (
+          <Checkbox
+            checked={allPicked}
+            onCheckedChange={(v) =>
+              setPicked(v === true ? Object.fromEntries(rows.map((p) => [p.sku, true])) : {})
+            }
+            aria-label="Select all"
+          />
+        ),
+        cell: ({ row }) => (
+          <Checkbox
+            checked={Boolean(picked[row.original.sku])}
+            onCheckedChange={(v) => setPicked((s) => ({ ...s, [row.original.sku]: v === true }))}
+            aria-label={`Pick ${row.original.sku}`}
+          />
+        ),
+      },
+      { accessorKey: "sku", header: "SKU", meta: { sort: true } },
+      { accessorKey: "name", header: "Part" },
+      { accessorKey: "bin", header: "Bin", meta: { sort: true } },
+      { accessorKey: "qty", header: "Qty", meta: { sort: true } },
+    ],
+    [allPicked, picked, rows],
+  );
+
+  return (
+    <div className="h-[440px]">
+      <TablePage
+        toolbar={
+          <div className="flex items-center gap-2 border-b px-3 py-2">
+            <Input
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder="Filter by part or SKU…"
+              className="h-8 max-w-xs"
+            />
+            <span className="text-muted-foreground text-xs tabular-nums">{rows.length} rows</span>
+          </div>
+        }
+        grid={<DataGrid columns={columns} data={rows} pageSize={12} features={{ pagination: true }} />}
+        bulk={
+          count > 0 ? (
+            <div className="bg-card border-border flex items-center gap-3 rounded-full border px-4 py-2 text-sm shadow-lg">
+              <span className="tabular-nums font-medium">{count} selected</span>
+              <button
+                type="button"
+                className="text-muted-foreground hover:text-foreground text-xs underline-offset-4 hover:underline"
+              >
+                Export
+              </button>
+              <button
+                type="button"
+                className="text-muted-foreground hover:text-foreground text-xs underline-offset-4 hover:underline"
+                onClick={() => setPicked({})}
+              >
+                Clear
+              </button>
+            </div>
+          ) : undefined
+        }
+      />
+    </div>
+  );
+}

package/skills/monkey-mini-app/references/examples/time-picker/time-picker-01.tsx

@@ -0,0 +1,19 @@
+/**
+ * @exampleOf TimePicker
+ * @title TimePicker
+ * @scenario Time-of-day only (no date) for windows like a daily cron or shift start.
+ */
+import * as React from "react";
+
+import { TimePicker } from "@monkey-mini-app/ui";
+
+export default function TimePicker01Example() {
+  const [time, setTime] = React.useState("09:30");
+
+  return (
+    <>
+      <TimePicker value={time} onChange={setTime} />
+      <p className="text-muted-foreground mt-2 text-xs">{time || "empty"}</p>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/time-range-picker/time-range-picker-01.tsx

@@ -0,0 +1,14 @@
+/**
+ * @exampleOf TimeRangePicker
+ * @title TimeRangePicker
+ * @scenario Start/end time-of-day pair, e.g. a maintenance window inside one day.
+ */
+import * as React from "react";
+
+import { TimeRangePicker } from "@monkey-mini-app/ui";
+
+export default function TimeRangePicker01Example() {
+  const [timeRange, setTimeRange] = React.useState({ start: "09:00", end: "18:00" });
+
+  return <TimeRangePicker value={timeRange} onChange={setTimeRange} />;
+}

package/skills/monkey-mini-app/references/examples/timeline/timeline-01.tsx

@@ -0,0 +1,18 @@
+/**
+ * @exampleOf Timeline
+ * @title Timeline
+ * @scenario Chronological feed of events with actor + timestamp — deploy history, audit trail (compare RunTimeline for one job's steps).
+ */
+import { Timeline } from "@monkey-mini-app/ui";
+
+export default function Timeline01Example() {
+  return (
+    <Timeline
+      items={[
+        { id: "1", title: "Opened", time: "10:00" },
+        { id: "2", title: "Running", time: "10:02" },
+        { id: "3", title: "Passed", time: "10:04" },
+      ]}
+    />
+  );
+}

package/skills/monkey-mini-app/references/examples/timezone-select/timezone-select-01.tsx

@@ -0,0 +1,15 @@
+/**
+ * @exampleOf TimezoneSelect
+ * @title TimezoneSelect
+ * @scenario IANA timezone chosen from common zones first, searchable — pair with DateTimePicker when schedules cross regions.
+ * @hint Common zones first; type to search the rest
+ */
+import * as React from "react";
+
+import { TimezoneSelect } from "@monkey-mini-app/ui";
+
+export default function TimezoneSelect01Example() {
+  const [zone, setZone] = React.useState("Asia/Shanghai");
+
+  return <TimezoneSelect value={zone} onChange={setZone} />;
+}

package/skills/monkey-mini-app/references/examples/toggle/toggle-01.tsx

@@ -0,0 +1,20 @@
+/**
+ * @exampleOf Toggle
+ * @title Toggle
+ * @scenario Single pressed/unpressed icon button (bold, mute) — one binary view option, not a form value; use Switch for settings on/off.
+ */
+import * as React from "react";
+
+import { Toggle } from "@monkey-mini-app/ui";
+
+export default function Toggle01Example() {
+  const [pressed, setPressed] = React.useState(false);
+
+  return (
+    <>
+      <Toggle pressed={pressed} onPressedChange={setPressed}>
+        Bold
+      </Toggle>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/toggle-group/toggle-group-01.tsx

@@ -0,0 +1,22 @@
+/**
+ * @exampleOf ToggleGroup
+ * @title ToggleGroup
+ * @scenario Mutually exclusive set of Toggle buttons for a view choice (alignment, density) held as one value.
+ */
+import * as React from "react";
+
+import { ToggleGroup, ToggleGroupItem } from "@monkey-mini-app/ui";
+
+export default function ToggleGroup01Example() {
+  const [align, setAlign] = React.useState("left");
+
+  return (
+    <>
+      <ToggleGroup value={[align]} onValueChange={(v) => v[0] && setAlign(v[0])}>
+        <ToggleGroupItem value="left">Left</ToggleGroupItem>
+        <ToggleGroupItem value="center">Center</ToggleGroupItem>
+        <ToggleGroupItem value="right">Right</ToggleGroupItem>
+      </ToggleGroup>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/tree-view/tree-view-01.tsx

@@ -0,0 +1,25 @@
+/**
+ * @exampleOf TreeView
+ * @title TreeView
+ * @scenario Nested hierarchy with expand/collapse and selection — file tree, org chart, category taxonomy.
+ */
+import { TreeView } from "@monkey-mini-app/ui";
+
+export default function TreeView01Example() {
+  return (
+    <>
+      <TreeView
+        nodes={[
+          {
+            id: "src",
+            label: "src",
+            children: [
+              { id: "app", label: "App.tsx" },
+              { id: "ui", label: "ui.ts" },
+            ],
+          },
+        ]}
+      />
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/wizard-shell/wizard-shell-01.tsx

@@ -0,0 +1,58 @@
+/**
+ * @exampleOf WizardShell
+ * @title WizardShell
+ * @scenario 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.
+ * @hint Step 2 starts invalid — Next is disabled until the mapping is filled in
+ */
+import * as React from "react";
+
+import { Button, Input, WizardShell } from "@monkey-mini-app/ui";
+
+export default function WizardShell01Example() {
+  const [step, setStep] = React.useState(0);
+  const [file, setFile] = React.useState("");
+  const [mapped, setMapped] = React.useState("");
+
+  const steps = [
+    { id: "pick", label: "Choose file", valid: file.trim().length > 0 },
+    { id: "map", label: "Map columns", valid: mapped.trim().length > 0 },
+    { id: "run", label: "Import", valid: true },
+  ];
+
+  const body =
+    step === 0 ? (
+      <div className="flex flex-col gap-3">
+        <p className="text-muted-foreground text-sm">A workbook already on this machine.</p>
+        <Input placeholder="ledger-2026-09.xlsx" value={file} onChange={(e) => setFile(e.target.value)} />
+      </div>
+    ) : step === 1 ? (
+      <div className="flex flex-col gap-3">
+        <p className="text-muted-foreground text-sm">
+          Which column is the account id? Required before the import can run.
+        </p>
+        <Input placeholder="account_id" value={mapped} onChange={(e) => setMapped(e.target.value)} />
+      </div>
+    ) : (
+      <div className="flex flex-col gap-3">
+        <p className="text-sm">
+          Import <b>{file}</b>, mapping account from <b>{mapped}</b>.
+        </p>
+        <Button variant="outline" size="sm" className="w-fit">
+          Advanced options
+        </Button>
+      </div>
+    );
+
+  return (
+    <div className="h-[420px]">
+      <WizardShell
+        steps={steps}
+        index={step}
+        body={body}
+        onBack={() => setStep((s) => Math.max(0, s - 1))}
+        onNext={() => setStep((s) => Math.min(steps.length - 1, s + 1))}
+        onSubmit={() => setStep(0)}
+      />
+    </div>
+  );
+}

package/skills/monkey-mini-app/references/history.md

@@ -1,10 +1,26 @@
-# 版控
+# Versioning (one lightweight history per app)
 
-每 app 一份轻量历史（类git）。
+The host keeps a per-app commit tree via isomorphic-git (`runtime/apps/<appId>/.git`).
 
-- `mini_app_history_commit` 全量保留，不要靠清快照 ≈ git commit
-- list commits 是树 ≈ git log
-- revert ≈ 从某 commit **分叉**，旁支还在
-- 单分支，不要做 merge
+## When a commit happens
 
-生成或改完 app 后都 commit 一次，方便 AI 误操作后找回。
+`mini_app_edit` / `mini_app_write` / `mini_app_delete` **auto-commit** by default; a successful `mini_app_reload` with a dirty worktree commits too. So the normal flow needs no manual commit.
+
+Explicit control:
+
+| Tool | Purpose |
+|---|---|
+| `mini_app_history_commit({ appId, message })` | Close out a batch you made with `commit: false`; `message` is required |
+| `mini_app_history_list({ appId })` | List the commit tree (nodes + parentIds) — like `git log` |
+| `mini_app_history_revert({ appId, commitId })` | **Forward** commit undoing an older one (`git revert` semantics); history stays |
+| `mini_app_history_reset({ appId, commitId })` | Point main back at a commit and keep a backup ref — like `git reset`; **does not delete objects** |
+
+Commit once after each round of work on an app (especially after a large AI-driven change) so a bad edit is recoverable.
+
+## Differences from git (don't apply git instincts)
+
+- **Single branch**: main only. Do not expect merge / rebase / cherry-pick.
+- **Full snapshots**: `mini_app_history_commit` keeps the whole tree; do not treat "delete snapshots" as `git gc`.
+- After `reset`, the old commits still exist (visible as a backup tip) — nothing was erased.
+- `revert` creates a **new** commit, so the tree grows a side branch; that is not "history removed".
+- Snapshots exclude `storage/`, `.git/`, `node_modules/` (they were never source files).