@momoi-labs/kiso 0.1.0

package/kiso/docs/patterns/command-palette.md

@@ -0,0 +1,142 @@
+# Command palette
+
+Keyboard-driven global navigation and actions. This pattern composes the
+[CommandPalette](../components/command-palette.md) component as the app-wide
+"do or go anywhere" surface, invoked by a documented shortcut, filtering
+commands and destinations as the person types.
+
+User story #23.
+
+## Purpose
+
+The command palette lets a person run frequent actions and jump to destinations
+without hunting through menus: open a query editor, jump to a replica, switch
+project, run a saved action. It is keyboard-first, invoked by a shortcut, and
+filters a command list as the person types.
+
+It is **not** list [Search](search.md) (which filters content in view) and not
+a [DropdownMenu](../components/dropdown-menu.md) (which is contextual to one
+trigger). The palette is global.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Overlay | [CommandPalette](../components/command-palette.md) dialog surface | Modal or non-modal elevated panel |
+| Filter input | CommandPalette Input (autofocused) | Filters commands as the person types |
+| Command list | CommandPalette List with Groups + Items | Actions and destinations, grouped |
+| Empty | CommandPalette in-palette empty message | "No commands match 'xyz'" — not page-level EmptyState |
+| Footer hints | optional keyboard legend | Reminds the person of `Enter`, `↑↓`, `Esc` |
+| Explicit trigger | [Button](../components/button.md) or [IconButton](../components/icon-button.md) in [Header](../components/header.md) | Opens the same palette for non-keyboard users |
+
+## Flow
+
+1. Person presses `⌘K` (macOS) / `Ctrl+K` (Windows/Linux), or activates the
+   explicit trigger in the header.
+2. The palette opens; focus moves to the Input. The list shows all commands
+   (or a default group).
+3. Person types. The list filters as they type (search-as-you-type).
+4. Person navigates with `↑` / `↓` across groups; the highlighted item is the
+   active descendant.
+5. Person activates with `Enter` (or click). The command runs or navigation
+   occurs, and the palette closes.
+6. `Escape` closes without activating. Focus returns to the previously focused
+   element (or the trigger).
+
+If the chosen command is a [destructive action](destructive-actions.md), the
+palette closes and a [confirmation](confirmations.md) dialog opens — the palette
+is acceleration, not a bypass for the gate.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed | Palette not in tree (or inert). Shortcut and explicit trigger available. |
+| open | Input focused; list visible; focus trapped within the palette (if modal). |
+| filtering | List updates as the person types. Active descendant resets to the first match. |
+| no matches | In-palette empty message: "No commands match 'xyz'". Not the page-level [EmptyState](../components/empty-state.md). |
+| loading | Optional [Spinner](../components/spinner.md) in the list while command providers resolve. Input stays usable. `aria-busy` on the list. |
+| error | Provider failure: short in-palette message or [Alert](../components/alert.md) pattern inside the panel. Do not fail silently to an empty list that looks like "no matches". |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────┐
+│  ⌘K  Type a command or destination…          │
+├──────────────────────────────────────────────┤
+│  Navigation                                  │
+│  ▸ Queries                                   │
+│    Replicas                                  │
+│    Settings                                  │
+│  Replicas                                    │
+│  ▸ Open prod-eu                              │
+│    Open staging                              │
+│    Open analytics                            │
+│  Actions                                     │
+│  ▸ New query                                 │
+│    Switch project                            │
+│    Refresh all replicas                      │
+├──────────────────────────────────────────────┤
+│  ↑↓ navigate   ↵ run   esc close             │
+└──────────────────────────────────────────────┘
+```
+
+The palette is centered or top-anchored, elevated (`--color-elevated-surface`,
+`--shadow-sm`, `--radius-lg`). The active (highlighted) item uses a quiet
+`--color-surface` or `--color-primary` indicator — not a filled primary row.
+
+## Rules
+
+- **Invocation:** default `⌘K` / `Ctrl+K`, documented in product chrome. Do
+  not bind list [Search](search.md) fields to this shortcut.
+- **One app-level palette.** Do not ship separate palettes per page unless the
+  product truly scopes commands. Default is one palette with groups
+  (Navigation, Replicas, Actions, Settings).
+- **Commands vs destinations.** Both live in the palette. Destinations navigate
+  (open a route); commands run an action (new query, switch project). Group
+  them so the person can scan.
+- **Shortcut hints** in items are decorative unless they document real bindings.
+  If an item shows `⌘N`, that binding must work even when the palette is closed.
+- **Destructive commands still confirm.** A "Delete replica" command closes the
+  palette and opens a [confirmation](confirmations.md) dialog — it does not
+  delete on `Enter` from the palette.
+- **Discoverability:** the palette is acceleration, not the only path. Critical
+  actions still need a visible control somewhere (header, page action, row
+  menu). Do not hide a primary action only in the palette.
+- **Explicit trigger:** provide a [Button](../components/button.md) or
+  [IconButton](../components/icon-button.md) in the
+  [Header](../components/header.md) ("Search commands…") that opens the same
+  palette, so non-keyboard users can reach it.
+- Do not use the palette for form data entry. It is not a form.
+
+## Accessibility
+
+- Prefer a modal dialog pattern (`role="dialog"`, `aria-modal="true"`) with
+  an accessible name ("Command palette").
+- Input has a visible or programmatically associated label.
+- List uses `role="listbox"` (or cmdk's list semantics) with items as options;
+  the active item is exposed via `aria-activedescendant` on the Input — do not
+  invent a broken tab-per-item list.
+- Focus moves to the Input on open; on close, focus returns to the previously
+  focused element (or the trigger).
+- `Escape` closes without running a command.
+- Reduced motion: no gratuitous entrance animation beyond token durations.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `⌘K` / `Ctrl+K` | Toggle open/close. |
+| Printable keys | Filter commands (input focused). |
+| `↑` / `↓` | Move highlight through items (and across groups). |
+| `Enter` | Activate highlighted item. |
+| `Escape` | Close without activating. |
+| `Tab` | Stays within the palette (focus trap) while open; do not tab into the page behind a modal palette. |
+
+## Related patterns
+
+- [Search](search.md) — filters content in view; the palette is global actions.
+- [Keyboard shortcuts](keyboard-shortcuts.md) — the palette's `⌘K` is one
+  shortcut; this pattern covers the rest.
+- [Destructive actions](destructive-actions.md) — palette commands that are
+  destructive still confirm.

package/kiso/docs/patterns/confirmations.md

@@ -0,0 +1,158 @@
+# Confirmations
+
+Explain risk and require explicit acknowledgment before a consequential action.
+This pattern is the dialog spec for any confirmation — destructive or not —
+covering copy structure, focus, and the acknowledgment model. Destructive
+actions ([destructive-actions](destructive-actions.md)) always use this pattern;
+not every confirmation is destructive.
+
+User story #12.
+
+## Purpose
+
+A confirmation interrupts the person before an action whose consequence is
+non-obvious, delayed, or hard to reverse: disconnect a live connection, apply a
+config change to production, revoke access, overwrite a resource. The
+confirmation makes the consequence explicit and requires a deliberate choice.
+
+It is not a courtesy "are you sure?" for routine actions. Over-confirming
+trains the person to click through without reading; reserve confirmations for
+genuine risk.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Dialog | [Modal / Dialog](../components/modal-dialog.md) | Blocks the page; focused task |
+| Title | Dialog Title | Names the action in product language ("Disconnect 'staging-db'?") |
+| Consequence | Dialog Description | What will happen, in plain language |
+| Confirm action | [Button](../components/button.md) — variant matches stakes | Commits the action |
+| Cancel action | [Button](../components/button.md) `default` or `ghost` | Closes without committing; always available |
+| Acknowledgment (high-stakes) | [Checkbox](../components/checkbox.md) or type-to-confirm [Input](../components/input.md) | Required before confirm is enabled |
+| Progress | [Spinner](../components/spinner.md) inside confirm Button | While the action is in flight |
+
+## Flow
+
+1. Person activates a trigger that opens the confirmation.
+2. [Modal / Dialog](../components/modal-dialog.md) opens with focus on the first
+   meaningful element (usually Cancel).
+3. The dialog states the action and its consequence. For high-stakes actions, an
+   acknowledgment step (checkbox or type-to-confirm) gates the confirm Button.
+4. Person confirms or cancels.
+   - **Cancel** / `Escape` / overlay click (when safe): dialog closes, focus
+     returns to trigger, nothing changes.
+   - **Confirm**: Button enters loading; action runs.
+5. On success, dialog closes and feedback follows ([Toast](../components/toast.md)
+   for brief confirmation, navigation if the context changed). On failure,
+   error [Alert](../components/alert.md) inside the dialog with recovery.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed | Trigger available. |
+| open | Page inert; focus trapped. Cancel available; confirm available or gated. |
+| gated | High-stakes: confirm Button disabled until acknowledgment complete (checkbox checked, or typed name matches). |
+| submitting | Confirm Button loading ([Spinner](../components/spinner.md), `aria-busy`). Cancel available unless uninterruptible. |
+| error | Recoverable error as [Alert](../components/alert.md) inside dialog; dialog stays open. |
+| success | Dialog closes; [Toast](../components/toast.md) or navigation. |
+
+## Copy structure
+
+Confirmation copy follows [voice-and-tone](../voice-and-tone.md):
+
+- **Title:** Name the action and the object. "Disconnect 'staging-db'?" — not
+  "Warning" or "Confirm".
+- **Consequence:** What will happen, in one or two sentences. State the
+  irreversibility or side effect directly: "Active queries will be
+  terminated." Do not say "Are you absolutely sure?" — state the fact.
+- **Match weight to stakes.** A low-stakes action (leave a draft unsaved) gets
+  a neutral dialog. A high-stakes action (drop database) gets type-to-confirm.
+  Do not wrap a low-stakes action in danger color, and do not under-state a
+  high-stakes one.
+
+Anti-patterns (from voice-and-tone):
+- "Are you absolutely sure?"
+- "Oops! Are you sure you want to..."
+- Danger color on a low-stakes confirmation.
+- No consequence stated, only "Confirm / Cancel".
+
+## Layout sketch
+
+### Standard confirmation
+
+```text
+┌──────────────────────────────────────────┐
+│ Disconnect "staging-db"?                 │
+│                                          │
+│ Active queries to this database will be  │
+│ terminated. The connection can be        │
+│ re-established later.                    │
+│                                          │
+│              [Cancel]  [Disconnect]      │
+└──────────────────────────────────────────┘
+```
+
+### High-stakes (type-to-confirm)
+
+```text
+┌──────────────────────────────────────────┐
+│ Drop database "production"?              │
+│                                          │
+│ All tables, data, and replicas in this   │
+│ database will be permanently deleted.    │
+│ This cannot be undone.                   │
+│                                          │
+│ Type the database name to confirm:       │
+│ [production                       ]      │
+│                                          │
+│              [Cancel]  [Drop database]   │
+└──────────────────────────────────────────┘
+```
+
+`Drop database` stays disabled until "production" is typed exactly. The
+confirm Button is the only destructive-styled control.
+
+## Rules
+
+- Confirm only when there is genuine consequence. Routine saves, toggles, and
+  navigation do not need confirmation; over-confirmation trains click-through.
+- State the consequence, not a question. "Active queries will be terminated"
+  beats "Are you sure you want to disconnect?"
+- The confirm Button's variant matches the stakes:
+  - Destructive (delete, drop, purge) → `destructive` variant.
+  - Consequential but not destructive (disconnect, revoke, apply to production)
+    → `default` variant, possibly with a warning tone in the copy.
+  - Low-stakes (discard draft) → `default`.
+- Cancel is always available and is the safe default. Prefer focusing Cancel on
+  open.
+- High-stakes actions use acknowledgment:
+  - **Checkbox:** "I understand this cannot be undone" — for actions where the
+    person must consciously accept irreversibility.
+  - **Type-to-confirm:** type the exact resource name — for the highest-stakes
+    actions (drop database, delete workspace). Reserve sparingly; overuse makes
+    it friction without safety.
+- Do not use [Toast](../components/toast.md) as a confirmation. Toast is
+  transient and cannot require a decision. If a decision is needed, it is a
+  dialog.
+- Do not auto-confirm after a timeout. The person must explicitly choose.
+
+## Accessibility
+
+- Dialog: `role="dialog"`, `aria-modal="true"`, `aria-labelledby`,
+  `aria-describedby` (consequence).
+- Focus to first meaningful element on open (usually Cancel). `Tab` /
+  `Shift+Tab` cycle inside; `Escape` closes when safe.
+- Confirm Button accessible name includes the action: "Disconnect", "Drop
+  database" — not "Confirm".
+- Gated confirm: the disabled Button has an accessible explanation ("Type the
+  database name to enable Drop database"). The acknowledgment
+  [Checkbox](../components/checkbox.md) or [Input](../components/input.md) has a
+  [Label](../components/label.md).
+- On error, move focus to the error [Alert](../components/alert.md) so the
+  person lands on the recovery path.
+
+## Related patterns
+
+- [Destructive actions](destructive-actions.md) — the specific gate for
+  irreversible actions; always uses this confirmation spec.

package/kiso/docs/patterns/crud.md

@@ -0,0 +1,139 @@
+# CRUD
+
+Create, read/update, and delete flows for a single entity type. Covers form
+layout, validation, and the create / edit / delete states without inventing
+one-off form kits.
+
+User stories #9 and #10.
+
+## Purpose
+
+Make every Momoi resource editable the same way: labeled fields, predictable
+primary/secondary actions, field-level validation, and clear success or failure
+feedback. This layout pattern places create/edit surfaces and delete entry
+points; confirmation copy and acknowledgment for irreversible deletes are
+specified separately and must still run before destruction.
+
+## Component composition
+
+| Concern | Compose with | Role |
+| --- | --- | --- |
+| Page framing | [PageHeader](../components/page-header.md) | Title ("New connection", "Edit connection"); optional cancel secondary action |
+| Fields | [FormField](../components/form-field.md) | Each field = [Label](../components/label.md) + control ([Input](../components/input.md), [Textarea](../components/textarea.md), [Select](../components/select.md), [Checkbox](../components/checkbox.md), …) + optional [HelperText](../components/helper-text.md) + [ValidationMessage](../components/validation-message.md) |
+| Grouping | [Card](../components/card.md) or section headings | Related field groups (connection, credentials, advanced) |
+| Primary actions | [Button](../components/button.md) | Save / Create (primary); Cancel (secondary/ghost) |
+| Overlays | [Modal / Dialog](../components/modal-dialog.md) or [Drawer](../components/drawer.md) | Compact create/edit; Drawer preferred on small viewports for the same task |
+| Inline errors | [ValidationMessage](../components/validation-message.md) on FormField | Field-level recovery; page [Alert](../components/alert.md) is for non-field failures |
+| Form / load errors | [Alert](../components/alert.md) | Submit or load failures that are not field-local (what / why / now) |
+| Success | [Toast](../components/toast.md) | Brief "Saved" / "Created"; do not rely on Toast alone for blocking failures |
+| Delete entry | Button or [DropdownMenu](../components/dropdown-menu.md) item | Opens confirmation flow; danger styling on the destructive control |
+| Read context | [Badge](../components/badge.md), [Tabs](../components/tabs.md) | Status and sections on edit/detail surfaces |
+| Shell | [Application shell](application-shell.md) | Authenticated framing |
+
+Tokens: form surfaces `--color-surface`, canvas `--color-background`, borders
+`--color-border`, text `--color-foreground` / `--color-muted-foreground`,
+invalid fields and ValidationMessage use `--color-danger`, focus
+`--color-focus`, destructive Buttons use `--color-danger` per the Button
+contract.
+
+## Flow
+
+### Create
+
+1. Person activates Create from PageHeader or EmptyState.
+2. Open full-page form, Modal, or Drawer with empty FormFields.
+3. Person submits; invalid fields show ValidationMessage and receive focus on
+   the first error.
+4. On success: Toast (optional), navigate to the new entity's detail or list
+   selection; close overlay if used.
+5. On failure: keep the form open; Alert for non-field errors; preserve input.
+
+### Edit
+
+1. Person opens Edit from list-detail actions or a detail PageHeader.
+2. Form loads current values; read-only identifiers stay visible but not
+   editable when the API forbids changes.
+3. Save enables when the form is dirty (product may also allow explicit Save
+   always — be consistent within a product).
+4. Validation and error handling match Create.
+5. Cancel discards unsaved changes (confirm only if dirty and loss is material).
+
+### Delete
+
+1. Person chooses Delete from entity actions.
+2. An explicit confirmation step runs before destruction (Modal/Dialog with
+   clear consequences); this layout requires that step, not its microcopy.
+3. On success: Toast or list refresh; navigate away from a deleted detail.
+4. On failure: Alert with recovery; entity remains.
+
+Prefer Modal/Drawer for short create/edit. Use a full main-page form when the
+field set is long, multi-section, or needs side-by-side reference content.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| loading (edit) | Skeleton for known field layout inside the form surface; do not flash empty Inputs. |
+| empty (create from empty collection) | EmptyState on the list offers Create; CRUD form is the next step — do not reinvent empty handling inside the form. |
+| invalid | ValidationMessage per field; first invalid control focused; do not clear other fields. |
+| submitting | Primary Button loading (Spinner in Button); prevent double submit; Cancel remains available when safe. |
+| error (load) | Alert in the form region (what / why / now); offer retry; Cancel/back remains. |
+| error (submit) | Field errors via ValidationMessage; server/business errors via Alert; form stays open with values preserved. |
+| success | Toast or inline success only as confirmation; navigate or refresh per flow above. |
+
+## Layout sketch
+
+Full-page create/edit:
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Edit connection                         [Cancel] [Save]  │
+├──────────────────────────────────────────────────────────────────────┤
+│ Alert (only if submit/load error — what / why / now)                 │
+│                                                                      │
+│ Card: Connection                                                     │
+│   FormField  Name                                                    │
+│   FormField  Host                                                    │
+│   FormField  Port                                                    │
+│                                                                      │
+│ Card: Credentials                                                    │
+│   FormField  User                                                    │
+│   FormField  Password                                                │
+│   FormField  SSL          [Select]                                   │
+│                                                                      │
+│                                              [Cancel]  [Save]        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+Modal create (compact):
+
+```text
+          ┌─────────────────────────────────┐
+          │ New connection            [✕]   │
+          │                                 │
+          │ FormField Name                  │
+          │ FormField Host                  │
+          │ FormField Port                  │
+          │                                 │
+          │          [Cancel]  [Create]     │
+          └─────────────────────────────────┘
+```
+
+## When to use
+
+- Any resource with create and/or edit forms.
+- Delete entry points on list rows or detail headers.
+
+## When NOT to use
+
+- Immediate boolean preferences without a Save affordance — prefer Switch
+  inside [Settings](settings.md).
+- Bulk multi-entity editors — extend list-detail selection + confirmed bulk
+  actions instead of a single CRUD form.
+
+## Related patterns
+
+- [List-detail](list-detail.md) — where Create and row actions usually live.
+  List EmptyState still follows the canonical rule: do not reinvent search,
+  filters, pagination, or empty state on the way into Create.
+- [Settings](settings.md) — preference forms with explicit save sections.

package/kiso/docs/patterns/dashboard.md

@@ -0,0 +1,102 @@
+# Dashboard
+
+A scan-first overview of several related metrics or summaries on one page.
+Widgets share density and hierarchy rules; the page is not a junk drawer of
+unrelated Cards.
+
+User story #30.
+
+## Purpose
+
+Orient the person quickly: what needs attention, what is healthy, and where to
+go next. Dashboards summarize; deep investigation happens in list-detail,
+tables, or dedicated tool routes.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Page framing | [PageHeader](../components/page-header.md) | Dashboard title; optional time-range or environment [Select](../components/select.md); optional refresh [IconButton](../components/icon-button.md) / [Button](../components/button.md) |
+| Widget unit | [Card](../components/card.md) | One concern per Card (metric cluster, short table, status list) |
+| Status | [Badge](../components/badge.md) | Compact health/severity labels inside Cards |
+| Dense lists | [Table / DataTable](../components/table.md) | Short "needs attention" tables — still compose Search/EmptyState/Pagination only when those behaviors are truly present |
+| Alerts | [Alert](../components/alert.md) | Page-level degraded conditions that outrank widgets |
+| Navigation out | [Link](../components/link.md) | "View all" from a widget into list-detail or a tool |
+| Shell | [Application shell](application-shell.md) | Header + Sidebar + main |
+
+**Canonical rule (when a widget is a list):** A list screen must not reinvent
+search, filters, pagination, and empty state. A dashboard widget that embeds a
+mini-list still uses EmptyState and Table composition — it does not invent a
+third list pattern.
+
+Tokens: page canvas `--color-background`, widgets `--color-surface` with
+`--color-border`, titles `--color-foreground`, supporting
+`--color-muted-foreground`, emphasis `--color-primary`, status via Badge
+semantic colors, focus `--color-focus`. Prefer quiet surfaces and strong
+hierarchy ([principles](../principles.md)).
+
+Charts are out of scope for this epic; when charts exist later, they sit inside
+Card like any other widget payload.
+
+## Flow
+
+1. Person opens Overview / Dashboard from Sidebar.
+2. PageHeader establishes scope (product area, optional range/environment).
+3. Widgets load independently when possible so one slow tile does not block the
+   whole page.
+4. Person scans Badges and summary numbers, then follows a Link into a deeper
+   list-detail or tool view.
+5. Refresh updates widget data without remounting the application shell.
+
+Keep widget count deliberate. If a Card has no job beyond decoration, remove
+it.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| loading | Per-widget Skeleton that preserves Card size; PageHeader stays. Avoid a single full-page Spinner unless the dashboard has no known layout yet. |
+| empty (no data in a widget) | EmptyState inside that Card only ("No failing checks") with optional Link; other widgets remain. |
+| empty (product not configured) | One page-level [EmptyState](../components/empty-state.md) with a clear next action instead of a grid of hollow Cards. |
+| error (one widget) | Alert or error content inside that Card with retry; siblings keep working. |
+| error (page) | Alert under PageHeader (what / why / now); widgets may still show last-known content if labeled stale. |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Overview                    [Environment▾] [Refresh]     │
+├──────────────────────────────────────────────────────────────────────┤
+│ Alert (optional page-level condition)                                │
+│                                                                      │
+│ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────────────┐│
+│ │ Card: Health  │ │ Card: Lag     │ │ Card: Connections             ││
+│ │ [Badge ok]    │ │ 18 ms         │ │ active 12 · idle 3            ││
+│ │ 4 / 4 up      │ │ p95           │ │ [View connections →]          ││
+│ └───────────────┘ └───────────────┘ └───────────────────────────────┘│
+│                                                                      │
+│ ┌──────────────────────────────────────────────────────────────────┐ │
+│ │ Card: Needs attention                                            │ │
+│ │ Table: Name | Issue | Since                                      │ │
+│ │        … short rows …                                            │ │
+│ │ EmptyState if none                                               │ │
+│ └──────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## When to use
+
+- Product home / overview routes.
+- Operator glance surfaces that link into deeper tools.
+
+## When NOT to use
+
+- The primary working surface for one entity — use [List-detail](list-detail.md).
+- Long configuration forms — use [Settings](settings.md) or [CRUD](crud.md).
+- A single full-height operational table — use list-detail / DataTable, not a
+  one-widget "dashboard".
+
+## Related patterns
+
+- [Application shell](application-shell.md)
+- [List-detail](list-detail.md) — drill-down target for "View all"