@momoi-labs/kiso 0.1.0

package/kiso/docs/patterns/onboarding.md

@@ -0,0 +1,94 @@
+# Onboarding
+
+Onboarding guides a new person through the minimum setup required to reach a
+useful product state. It is a finite task flow, not a product tour, marketing
+carousel, or substitute for clear everyday UI.
+
+## Component composition
+
+- [Card](../components/card.md) groups each setup task or the active task.
+- [Button](../components/button.md) performs setup actions; at most one primary
+  Button advances the current step.
+- [Link](../components/link.md) opens optional documentation or a route that
+  must remain navigable.
+- [FormField](../components/form-field.md), [Input](../components/input.md),
+  [Select](../components/select.md), and their existing validation composition
+  collect setup data.
+- [Alert](../components/alert.md) and
+  [ValidationMessage](../components/validation-message.md) handle failures at
+  their proper scope. Skeleton or a loading Button handles pending work.
+
+The issue calls the progress composition “Steps”, but Kiso has no Steps
+component. Represent progress as a semantic ordered list with current and
+completed text states; do not invent a new component in this pattern.
+
+Cards use `--color-surface`, `--color-border`, `--radius-lg`, and semantic
+spacing. Current-step emphasis uses `--color-primary`; completed status may use
+`--color-success`; primary and secondary copy use `--color-foreground` and
+`--color-muted-foreground`. Keyboard focus uses `--color-focus`.
+
+## Flow
+
+1. Define the first useful outcome and include only setup steps required to
+   reach it.
+2. Show the total sequence and identify the current step in text.
+3. Explain why the current input or permission is needed before asking for it.
+4. Preserve valid input while an action loads or fails. Advance only after the
+   step succeeds.
+5. Let the person go back without losing completed work. Offer **Skip** only
+   for genuinely optional steps and state the consequence.
+6. Finish in the useful product view, not a celebration screen that blocks the
+   next task. Keep a way to resume incomplete setup later.
+
+Do not force onboarding when the required state already exists. Returning
+people resume at the first incomplete required step; they do not replay the
+whole flow.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| New / incomplete | Show ordered progress, the current Card, and one primary advance action. |
+| Loading | Preserve fields and progress; the active Button shows Spinner or known Card content uses Skeleton. |
+| Empty dependency | Explain the missing prerequisite and offer the action that creates or connects it; do not show a generic empty dashboard. |
+| Validation error | Keep the step open and show ValidationMessage at the field. |
+| Operation error | Keep the step open, show an actionable Alert using what/why/now, and allow retry. |
+| Permission denied | Explain the blocked setup task and access path with the permission-denied pattern; do not call the whole onboarding failed. |
+| Complete | Mark required steps complete and navigate to the useful destination. |
+
+## Layout sketch
+
+```text
+PageHeader: Set up your workspace
+
+1. Workspace details     Complete
+2. Connect database      Current
+3. Invite team           Optional
+
+┌─ Card: Connect database ────────────────────────────────┐
+│ Add a connection to run your first query.               │
+│                                                         │
+│ Connection name                                         │
+│ [production___________________________________________]  │
+│ Database URL                                             │
+│ [postgres://__________________________________________]  │
+│                                                         │
+│ Docs                              [Back] [Test connection]│
+└─────────────────────────────────────────────────────────┘
+```
+
+`Docs` is a Link. `Back` and `Test connection` are Buttons; only **Test
+connection** is primary. The ordered list communicates “2 of 3” and current,
+completed, and optional states in text rather than color alone.
+
+## Accessibility and copy
+
+- Use an ordered list for progress and expose the current item with text and
+  `aria-current="step"`. Announce step changes politely and move focus to the
+  new step heading.
+- Keep native form order and visible labels. Back navigation must not discard
+  input without warning.
+- Do not use disabled future steps as the only explanation of prerequisites.
+  State what is needed beside the active task.
+- Keep copy direct and task-oriented. Avoid tours, jargon without context,
+  playful filler, and terminal flourish in functional text.

package/kiso/docs/patterns/pagination.md

@@ -0,0 +1,121 @@
+# Pagination
+
+Explicit page navigation for known or meaningfully bounded datasets. This
+pattern composes the [Pagination](../components/pagination.md) component below a
+[Table / DataTable](../components/table.md) and governs when paging is the right
+model versus [large-data-tables](large-data-tables.md) virtualization or
+incremental loading.
+
+User story #3.
+
+## Purpose
+
+Pagination exposes position and direct page navigation when page numbers help
+the person reason about a dataset: "page 7 of 40", "show me the next 20
+replicas". It composes with [Search](search.md), [filtering](filtering.md), and
+[sorting](sorting.md) — those narrow and order the set; Pagination pages it.
+
+**Canonical rule:** A list screen must not reinvent search, filters,
+pagination, and empty state. Compose [Pagination](../components/pagination.md)
+— do not invent a per-list pager.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Page navigation | [Pagination](../components/pagination.md) | Previous / page numbers / Next below the table |
+| Position summary | text line or Pagination result summary | "Page 3 of 12 · 41–60 of 230 replicas" |
+| Page size control | [Select](../components/select.md) (optional) | "20 / 50 / 100 per page" |
+| Loading state | [Skeleton](../components/skeleton.md) rows in the body | While a page fetch runs |
+
+Pagination is a sibling below the table, not a table row. It is a navigation
+region: `<nav aria-label="Pagination">`.
+
+## Flow
+
+1. Person views page 1 of the result set (already narrowed by Search/filters
+   and ordered by sort).
+2. Person activates a page number, Previous, or Next.
+3. The results region enters loading: [Skeleton](../components/skeleton.md)
+   rows replace the body, `aria-busy` on the region. Pagination controls stay
+   visible and the current page is still indicated.
+4. The new page arrives; body swaps to populated rows.
+5. If the page is empty (e.g. filters changed and the set shrank), show
+   [EmptyState](../components/empty-state.md) `no-results` and reset to page 1.
+
+Changing [Search](search.md) query, [filters](filtering.md), or
+[sort](sorting.md) resets to page 1 — the person expects the top of the new
+result set.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| idle | Page loaded; Pagination shows current position. |
+| loading | Body shows Skeleton rows; `aria-busy` on the region. Controls remain; duplicate page requests are prevented. Previous/Next at a boundary are disabled with `--color-disabled`. |
+| boundary | Previous disabled on page 1; Next disabled on last page. Page Links are never disabled — they are omitted or replaced by ellipsis. |
+| empty | Set shrank to zero → [EmptyState](../components/empty-state.md) `no-results`; reset to page 1. |
+| error | Page fetch failed → [Alert](../components/alert.md) with retry. Do not leave Skeleton rows up after failure. |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Toolbar                                                              │
+│ [🔍 Search replicas...] [Status▾]                                   │
+│ 230 replicas · Page 3 of 12                                          │
+├──────────────────────────────────────────────────────────────────────┤
+│ Table / DataTable                                                    │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name ▲      Host            Status     Lag ▼      Region       │  │
+│ │ replica-41  db.eu.example   ok          12 ms     eu            │  │
+│ │ replica-42  db.eu.backup    ok           8 ms     eu            │  │
+│ │ ...                                                            │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│ Page 3 of 12 · 41–60 of 230        [20 / page ▾]                    │
+│ ←  1  2  [3]  4  5  …  12  →                                       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Rules
+
+- Use Pagination when the dataset size is **known or meaningfully bounded** and
+  page position helps the person. For unbounded activity streams, use
+  incremental loading instead.
+- Do not use Pagination to hide a missing [Search](search.md) or
+  [filtering](filtering.md) capability. If the person must page through 200
+  pages to find one row, the list is missing Search.
+- Changing Search, filters, or sort resets to page 1.
+- Selection policy across pages must be explicit: either clear selection on
+  page change, or keep a cross-page selection model with a visible count
+  ("3 selected across pages"). Pick one per surface and document it.
+- Page size, if configurable, is a [Select](../components/select.md) with a
+  small set of sensible options. Changing page size resets to page 1.
+- For very large client-side sets (thousands of rows) where paging is not the
+  task, prefer virtualization — see [large-data-tables](large-data-tables.md).
+  Pagination is for known, page-shaped sets; virtualization is for scrolling
+  one large loaded set.
+- Do not combine Pagination and infinite scroll on the same table. Pick one
+  model per surface.
+
+## Accessibility
+
+- Use `<nav aria-label="Pagination">`. Give controls names such as "Go to
+  page 4", "Previous page", "Next page"; the visible numeral alone is not
+  enough.
+- Current page has `aria-current="page"`. Ellipses are not focusable.
+- After a page change, move focus to the results heading or announce the
+  updated range in a polite live region ("Showing 41 to 60 of 230 replicas").
+- Previous/Next at a boundary use `--color-disabled` and `aria-disabled`;
+  page Links are never disabled.
+- Native Link or Button keyboard behavior applies; `Tab` moves through
+  controls.
+
+## Related patterns
+
+- [Search](search.md) — narrows the set before paging.
+- [Filtering](filtering.md) — narrows the set before paging.
+- [Sorting](sorting.md) — orders the set before paging.
+- [Large data tables](large-data-tables.md) — when virtualization is the
+  better model than paging.

package/kiso/docs/patterns/permission-denied.md

@@ -0,0 +1,84 @@
+# Permission denied
+
+Permission denied is a distinct product state: the requested resource or action
+exists, and the system has determined that the current person cannot access it.
+It is not a generic error, an empty collection, or a failed request.
+
+## Component composition
+
+- Use [Alert](../components/alert.md) with `info` semantics when a denied action
+  sits inside otherwise available content.
+- Use [EmptyState](../components/empty-state.md) as a dedicated locked state
+  when denial replaces an entire bounded region or page. Its title and
+  description explain access, never emptiness.
+- Use [Link](../components/link.md) to open access documentation, workspace
+  settings, or a request-access route.
+- Use [Button](../components/button.md) only when the product can submit an
+  access request directly. Do not present a retry action unless permissions may
+  genuinely have changed.
+
+Permission-denied content uses `--color-foreground` and
+`--color-muted-foreground` on `--color-surface` or `--color-background`.
+An informational Alert may use `--color-info`. **Do not use
+`--color-danger`: denied access is not an error severity.** Link and focus
+treatments use `--color-primary` and `--color-focus`.
+
+## Flow
+
+1. Identify exactly which resource or action is blocked.
+2. State the applicable access rule or required role when known.
+3. Offer the shortest real route to access: request access, contact a named
+   role, or open access settings/documentation.
+4. Preserve navigation and any safe surrounding context. Hide protected data
+   rather than rendering redacted fragments that reveal its shape.
+5. If access is granted, re-check authorization and replace the denied state
+   with loading, then the authorized result.
+
+Copy follows **blocked / why / access path**:
+
+> You can't edit this query. Only the query author and workspace admins can
+> edit it. Ask a workspace admin to grant you access.
+
+This resembles the clarity of what/why/now, but it does not label the condition
+as a failure and does not use error severity.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| Checking access | Show the loading pattern without protected content. Do not flash a denied state before authorization resolves. |
+| Action denied | Keep available content and place an informational Alert beside the blocked action. Explain why the control is absent or unavailable. |
+| Region/page denied | Replace protected content with a dedicated locked EmptyState composition and one access path when available. |
+| Requesting access | The request Button shows its loading state; keep the explanation visible and prevent duplicates. |
+| Request sent | Confirm in context with the expected next step; do not imply access is already granted. |
+| Access granted | Re-enter loading, then show authorized content. |
+| Access check failed | Use the errors pattern. An inability to determine permission is a system failure, not a denial. |
+
+## Layout sketch
+
+```text
+PageHeader: Production workspace
+Breadcrumb and safe workspace navigation remain visible
+┌─────────────────────────────────────────────────────────┐
+│                    Restricted query                     │
+│ You can't view this query. It is limited to members     │
+│ of the Production Operators group.                      │
+│                                                         │
+│ [Request access]        Access policy                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+`Request access` is a Button because it submits an action. `Access policy` is a
+Link because it navigates. If neither path exists, say whom to contact and omit
+the action rather than showing a disabled control.
+
+## Accessibility and copy
+
+- Name the denied region from its title. Use a polite status for a denial that
+  appears after interaction; reserve assertive alerts for actual urgent errors.
+- Move focus to the explanation when denial follows activation and the person
+  would otherwise land on removed content.
+- Do not disclose protected names, counts, field values, or membership beyond
+  what the person is allowed to know.
+- Avoid “Access denied,” “unauthorized,” blame, corporate language, and false
+  retry actions. State what is blocked, why, and how to request access.

package/kiso/docs/patterns/search.md

@@ -0,0 +1,150 @@
+# Search
+
+Search-driven interaction for narrowing a visible collection by query. This
+pattern composes the [Search](../components/search.md) component into a list or
+table toolbar and governs when, how, and where filtering by query happens.
+
+User story #6.
+
+## Purpose
+
+Search lets the person type a query to narrow what they already see — rows in a
+[Table / DataTable](../components/table.md), items in a list-detail master, or
+entries in a panel. The collection owns the data; Search only supplies the query
+string. It is **not** global navigation or command execution — that is the
+[command palette](command-palette.md).
+
+**Canonical rule:** A list screen must not reinvent search, filters,
+pagination, and empty state. Compose [Search](../components/search.md) — do not
+invent a parallel query field per list.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Query field | [Search](../components/search.md) | Live-filter or submit-filter the collection; scoped to this list |
+| Clear control | Search's built-in Clear [IconButton](../components/icon-button.md) | Resets query; keeps focus in the field |
+| Pending indicator | [Spinner](../components/spinner.md) inside Search | Results are resolving (server-side or slow index) |
+| Result count | polite live region or toolbar text | "12 of 40 replicas" after results settle |
+| No matches | [EmptyState](../components/empty-state.md) `no-results` | Replaces the collection body, not a Search error |
+| Invalid query | [ValidationMessage](../components/validation-message.md) via [FormField](../components/form-field.md) | Only when the query syntax itself is invalid (regex, etc.) |
+
+Search sits in the list toolbar, beside [filtering](filtering.md) controls and
+above [Pagination](../components/pagination.md). It is a sibling of those
+controls, not nested inside the table.
+
+## Flow
+
+### Instant (client-side or fast index)
+
+1. Person types into the Search field.
+2. Query is debounced (product-defined; short enough to feel live).
+3. Collection re-filters. Result count updates in a polite live region.
+4. If the query matches nothing, the collection body shows
+   [EmptyState](../components/empty-state.md) `no-results` with a
+   "Clear search" action.
+5. Clearing the query restores the full collection; focus stays in the field.
+
+### Submit (expensive server query)
+
+1. Person types the query. Results do not change yet.
+2. Person presses `Enter` or activates a visible "Search" [Button](../components/button.md).
+3. The results region enters loading ([Skeleton](../components/skeleton.md)
+   rows), and `aria-busy` is set on the region.
+4. Results arrive; region swaps to populated or no-matches EmptyState.
+
+Do not mix instant and submit behavior on the same Search field without making
+the mode obvious. Pick one per surface and keep it consistent.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| idle | Empty query; full collection visible. Field is ready to type. |
+| typing (instant) | Debounced; results update without focus leaving the field. |
+| resolving | Query submitted; [Spinner](../components/spinner.md) inside Search; region `aria-busy`. Query value stays visible — do not clear it. |
+| no matches | Collection body → [EmptyState](../components/empty-state.md) `no-results`. Offer "Clear search". The Search field keeps the query so the person can edit it. |
+| error | Results failed to load. Show [Alert](../components/alert.md) (what/why/now) above or in place of the body with a retry [Button](../components/button.md). Do not show an EmptyState for a failure. |
+| invalid query | Rare. Only when the query syntax is invalid (e.g. malformed regex). `aria-invalid` + [ValidationMessage](../components/validation-message.md). Zero hits is **not** invalid. |
+
+Loading, empty, and error must never be ambiguous: Skeleton rows ≠ EmptyState
+no-results ≠ Alert.
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Queries                       [Create query]             │
+├──────────────────────────────────────────────────────────────────────┤
+│ Toolbar                                                              │
+│ [🔍 Search queries..............] [Status▾] [Clear filters]          │
+│                                                                      │
+│ 12 of 40 queries                                                     │
+├──────────────────────────────────────────────────────────────────────┤
+│ Table / DataTable                                                    │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name              Author     Status    Modified                 │  │
+│ │ slow-join         ada        warn      2d ago                  │  │
+│ │ index-health      sam        ok        5d ago                  │  │
+│ │ ...                                                            │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+│ ← 1 2 3 … →                                                         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+When the query matches nothing:
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Toolbar                                                              │
+│ [🔍 no matching..............] [Clear filters]                       │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│             No queries match "no matching"                           │
+│             Try a different search or clear filters.                 │
+│                              [Clear search]                          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Rules
+
+- Search is scoped to **one collection**. Do not make a single Search field
+  filter two independent tables on the same screen; give each its own field.
+- Zero hits is an empty state, not a Search error. Never show
+  [ValidationMessage](../components/validation-message.md) for "no results".
+- Keep the query visible during loading and no-matches. Clearing the query is
+  the person's action, not a side effect of a failed fetch.
+- `Escape` clears the query if non-empty (pick one behavior per surface and
+  keep it consistent). `Escape` does **not** open the
+  [command palette](command-palette.md) — that is `⌘K` / `Ctrl+K`.
+- After clearing, keep focus in the Search field and refresh results.
+- Do not move focus into the table on every keystroke.
+- Highlight matched query terms in results by default. Highlighting is
+  reinforcement; the filtered set is the real signal. A product may opt out
+  only when highlighting is impractical (e.g. server-side search with no
+  match offsets) and must document the opt-out. Keep highlighted text readable
+  — use `--color-primary` as a background tint, never as text color that
+  drops below contrast.
+- Search composes with [filtering](filtering.md): the active query and active
+  filters narrow the collection together. Clearing Search does not clear
+  filters unless the surface defines that as its single clear action.
+
+## Accessibility
+
+- Accessible name always present (`label` / `aria-label` / `aria-labelledby`).
+  Placeholder is not the name.
+- Use native `type="search"` so platform clear and semantics work.
+- Debounced instant search updates results without trapping focus. Use a polite
+  status region ("12 of 40 replicas") only when the change would otherwise be
+  silent.
+- No-matches EmptyState must be announced or discoverable; do not leave the
+  region visually and accessibly empty.
+
+## Related patterns
+
+- [Filtering](filtering.md) — structured filters that compose with Search.
+- [Sorting](sorting.md) — order of the filtered set.
+- [Pagination](pagination.md) — paging the filtered set.
+- [Command palette](command-palette.md) — global actions and navigation, not
+  list filtering.

package/kiso/docs/patterns/settings.md

@@ -0,0 +1,100 @@
+# Settings
+
+Configuration pages with predictable form layout and explicit save behavior.
+Settings are preferences and product configuration — not entity CRUD for a
+list of resources.
+
+User story #31.
+
+## Purpose
+
+Let the person change durable product or workspace options with clear grouping,
+immediate vs deferred persistence, and unambiguous save feedback.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Page framing | [PageHeader](../components/page-header.md) | "Settings" or section title; optional save actions when the page uses explicit save |
+| Section nav | [Tabs](../components/tabs.md) or Sidebar sub-nav [Link](../components/link.md)s | Split General / Notifications / API, etc. |
+| Groups | [Card](../components/card.md) | One settings group per Card |
+| Text / choice fields | [FormField](../components/form-field.md) | [Label](../components/label.md) + [Input](../components/input.md) / [Select](../components/select.md) / [Textarea](../components/textarea.md) + [HelperText](../components/helper-text.md) + [ValidationMessage](../components/validation-message.md) |
+| Booleans | [Switch](../components/switch.md) (immediate) or [Checkbox](../components/checkbox.md) inside FormField (part of a saved form) | Switch for single immediate preferences; Checkbox when the value submits with Save |
+| Actions | [Button](../components/button.md) | Save (primary), Reset/Cancel (secondary) for explicit-save sections |
+| Feedback | [Toast](../components/toast.md), [Alert](../components/alert.md), [ValidationMessage](../components/validation-message.md) | Saved confirmation; section errors; field errors |
+| Shell | [Application shell](application-shell.md) | Authenticated framing |
+
+Tokens: `--color-background` canvas, `--color-surface` Cards, `--color-border`
+separators, `--color-foreground` / `--color-muted-foreground` copy,
+`--color-primary` for current section/nav, `--color-focus` on controls.
+
+## Flow
+
+### Explicit save (default for multi-field sections)
+
+1. Person opens Settings and optionally a section Tab.
+2. Edits FormFields; Save stays disabled until dirty (recommended) or remains
+   available — pick one rule per product and keep it.
+3. Save validates; ValidationMessage on fields; Alert for section-level
+   failures (what / why / now).
+4. On success: Toast "Settings saved" (or equivalent); clear dirty state.
+5. Leaving a dirty section prompts only when unsaved loss is material.
+
+### Immediate Switch
+
+1. Person toggles Switch.
+2. Value persists immediately; failure reverts the Switch and shows Toast or
+   inline Alert with recovery.
+3. Do not also require Save for that same boolean.
+
+Do not mix both persistence models inside one Card without labeling which
+controls save immediately.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| loading | Skeleton for known Card/field layout; keep section nav visible. |
+| empty | Rare; if a section has no configurable options yet, short explanatory copy — not a collection EmptyState. |
+| dirty | Visual cue that Save applies; warn on navigate-away when appropriate. |
+| invalid | Field ValidationMessage; focus first error; preserve other values. |
+| saving | Save Button loading; prevent duplicate submits. |
+| error | Alert with what / why / now; values preserved; Switch failures revert. |
+| success | Toast or quiet confirmation; do not block the page. |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Settings                                                 │
+│ Tabs: [General]  Notifications  API                                  │
+├──────────────────────────────────────────────────────────────────────┤
+│ Card: Workspace                                                      │
+│   FormField  Display name                                            │
+│   FormField  Default region     [Select]                             │
+│                                                                      │
+│ Card: Query defaults                                                 │
+│   Switch     Persist query history                                   │
+│   FormField  Statement timeout                                       │
+│                                                                      │
+│                                      [Reset]  [Save changes]         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## When to use
+
+- Product, workspace, or user preference screens.
+- Multi-section configuration that is not a resource list.
+
+## When NOT to use
+
+- Creating/editing listed resources (connections, users as entities) —
+  [CRUD](crud.md) + [List-detail](list-detail.md).
+- One-off destructive operations — confirmation / destructive-action patterns.
+
+## Related patterns
+
+- [CRUD](crud.md) — entity forms vs preference forms.
+- [Application shell](application-shell.md)
+- [Login / authentication](login-authentication.md) — account recovery and
+  auth entry, not general settings.