@keboola/design 3.2.0 → 4.0.0

package/AGENTS.md

@@ -0,0 +1,447 @@
+# @keboola/design
+
+Consumer usage contract for the Keboola design system — shadcn-aligned React primitives (Radix underneath), Keboola-branded blocks, Lucide icons, and TanStack-Form bindings.
+
+This file ships **inside the npm tarball** and is version-pinned to the package you installed — it is the source of truth for **which** component to use and how to wire theming. For the exact **prop signature** of the most-used components, see the generated [`COMPONENT-API.md`](./COMPONENT-API.md) (also shipped in the tarball).
+
+Working **on** the package (commands, layer boundary, token surface, the FA→Lucide table, enforcement)? Those live in `MAINTAINING.md` in the repo — internal, not shipped with this package.
+
+## Import surface
+
+- **Always** import from the package root: `import { Button } from '@keboola/design'`.
+- App entry points **must** import styles. Two paths, pick by build setup:
+  - `import '@keboola/design/styles'` — Tailwind-extending consumers. Your PostCSS+Tailwind processes `@tailwind` directives plus design's `dist/` in your content scan. Avoids duplicate preflights/utilities. **Default for any Keboola app.**
+  - `import '@keboola/design/styles/compiled'` — drop-in pre-compiled CSS (~176 KB minified). No Tailwind setup required. Use only when you genuinely cannot run Tailwind.
+- Icons: `import { ChevronDown } from '@keboola/design/icons'`.
+- Code editors: `import { CodeEditor, SqlEditor, MergeEditor } from '@keboola/design/editors'`. These pull the full CodeMirror bundle (~1.3 MB), so they ship from a dedicated subpath — keeping the root barrel CodeMirror-free for apps that don't edit code.
+
+## Decision tree
+
+This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-API.md) carries the exact prop signatures.
+
+### Buttons
+
+| Use                  | When                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| `Button`             | Primary, secondary, danger, outline, or invisible actions with optional label + icon |
+| `Button size="icon"` | Icon-only button — no separate `IconButton`                                          |
+| `ButtonInline`       | Inline text-link-style action inside body copy                                       |
+| `SplitButton`        | Primary action + secondary dropdown of related actions                               |
+| `Link`               | Navigational anchor that opens a URL (defaults `target="_blank"`)                    |
+| `ButtonGroup`        | Two or more related buttons rendered as a segmented row                              |
+
+**Never** use raw `<button>` or `<a>` — always through `Button`, `ButtonInline`, or `Link`.
+
+### Overlays
+
+| Use            | When                                                                     |
+| -------------- | ------------------------------------------------------------------------ |
+| `Modal`        | Blocking dialog (confirmation, form, detail view)                        |
+| `Sheet`        | Slide-in panel for contextual editing without leaving the page           |
+| `Popconfirm`   | Lightweight inline confirmation anchored to the trigger (delete actions) |
+| `Popover`      | Non-modal floating panel for arbitrary rich content                      |
+| `HoverCard`    | Read-only preview panel on hover; no interactive controls                |
+| `DropdownMenu` | Contextual list of actions or navigation items on click                  |
+
+**Never** use `Popover` for destructive confirmations (use `Popconfirm`) or hover-only previews (use `HoverCard`).
+
+### Inputs
+
+| Use                     | When                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `TextInput`             | Bare text input with no surrounding label / help — rare on its own |
+| `FormGroup.TextInput`   | Text field with help text + error state from `FormGroup state`     |
+| `useAppForm`            | Full form layouts with validation (see Forms below)                |
+| `useAppForm` connectors | Picking between `TextField` / `NumberField` / `SelectField` / …    |
+| `InputOtp`              | Fixed-length verification code (MFA, email confirm, sudo step-up)  |
+| `FileUpload`            | Argo-only drag-and-drop file picker; caller owns the file array    |
+
+**Never** build custom label + input combinations — compose `Label` + `FormGroup.TextInput` + `FormGroup.Help` inside `FormGroup`.
+
+### Status surfaces
+
+| Use                           | When                                                  |
+| ----------------------------- | ----------------------------------------------------- |
+| `toast()` / `useNotification` | Transient auto-dismissing feedback for background ops |
+| `Toaster`                     | Mount once at app root                                |
+| `Alert`                       | Persistent contextual message in page layout          |
+| `FormGroup state="error"`     | Field-level validation errors inline below input      |
+
+**Never** use `Alert` for ephemeral success (use `toast()`) or `toast()` for blocking errors (use `Alert`).
+
+### Loading
+
+| Use                | When                                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `Skeleton`         | Layout-aware placeholder shown in the slot the real content will occupy (initial load, refetch) |
+| `SkeletonList`     | Pre-composed list shell (icon + row, repeated) for Table / Card-list pages                      |
+| `Button isLoading` | In-flight action on a known button — swaps the icon for a spinner and disables the button       |
+| `DotsLoader`       | Indeterminate background work without a layout slot (small inline progress signal)              |
+
+**Never** build a new "Loader" / "BoxLoader" / "ActionLoader" wrapper component. Compose `Skeleton` directly into the slot the real content will occupy.
+
+### Tooltips
+
+| Use         | When                                                  |
+| ----------- | ----------------------------------------------------- |
+| `Tooltip`   | Short plain-text label (icon-button aria description) |
+| `HoverCard` | Rich preview content (multi-line, structured)         |
+
+**Never** put interactive elements inside a `Tooltip` — use `HoverCard` or `Popover`.
+
+### Data display
+
+| Use         | When                                                               |
+| ----------- | ------------------------------------------------------------------ |
+| `Table`     | Tabular data with columns, sortable headers, row actions           |
+| `Card` list | Small heterogeneous collections needing their own visual container |
+
+**Never** reach for raw `<ul>/<li>` for entities — use `Table` for columnar data.
+
+### Layout
+
+**No** `Stack` / `Flex` / `Box` component exists, by design — shadcn doesn't ship them, and adding wrappers creates a third way to do layout. Use Tailwind utility classes directly.
+
+| Use              | When                                                                     |
+| ---------------- | ------------------------------------------------------------------------ |
+| Tailwind classes | All ad-hoc layout: `tw-flex tw-flex-col tw-gap-4`, `tw-grid …`, `tw-p-6` |
+| `AppShell`       | App-root shell that follows the active brand (sidebar vs top-nav)        |
+| `PageLayout`     | Top-level page shape: header, tabs, toolbar, content, footer             |
+| `PageToolbar`    | Index-page toolbar: search + filters / sort / actions / view + chips row |
+| `Card`           | Semantic content surface with header / content / footer slots            |
+| `Sidebar`        | App-shell left navigation rail (host inside `AppShell.Sidebar`)          |
+
+Vertical rhythm: prefer `tw-gap-*` on a flex column parent over `tw-mt-*` on children — avoids margin-collapse. Page-level max width: use `PageLayout`'s `maxWidth` prop (`narrow` / `default` / `wide` / `full`), not `tw-max-w-[…]` literals.
+
+**Page gutter is consumer-owned.** `AppShell.Main` and `PageLayout` impose **no** page gutter by design — content renders flush against the sidebar/header unless you add one. Put the padding on the content region yourself (the `AppShell` story wraps Main content in `tw-p-6`):
+
+```tsx
+<AppShell.Main>
+  <div className="tw-flex tw-flex-col tw-gap-4 tw-px-6 tw-py-6">{/* page content */}</div>
+</AppShell.Main>
+```
+
+### Navigation / flow
+
+| Use        | When                                                                                                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Stepper`  | Linear progress through an ordered, finite sequence (multi-step form / wizard / pipeline). Argo-only. Set `onStepClick` for navigable flows |
+| `Tabs`     | Switching between sibling views of the same context                                                                                         |
+| `Timeline` | Unordered chronological log of events                                                                                                       |
+| `Progress` | Single percentage value of an in-flight task                                                                                                |
+
+**Never** use `Stepper` for branching navigation (use `Tabs`) or an unordered status list (use `Timeline`).
+
+### Separators
+
+| Use                        | When                                                                  |
+| -------------------------- | --------------------------------------------------------------------- |
+| `Separator`                | Plain horizontal or vertical line between sections                    |
+| `<Separator label="OR" />` | Centered text divider between two options (sign-in flows, form forks) |
+
+The `label` prop implies `orientation="horizontal"` — labels are not rendered vertically.
+
+### Date/time, color, multi-select, code
+
+| Use               | When                                                          |
+| ----------------- | ------------------------------------------------------------- |
+| `DatePicker`      | Single calendar date                                          |
+| `DateRangePicker` | Selecting a date range                                        |
+| `TimePicker`      | Time-of-day                                                   |
+| `Calendar`        | Raw calendar grid (embed in custom range pickers)             |
+| `ColorInput`      | Design-token-driven brand color picker                        |
+| `Combobox`        | Single selection from a searchable list                       |
+| `MultiCombobox`   | Multiple selections from a searchable list                    |
+| `Select`          | Single selection from a short enum (≤ ~10 options, no search) |
+| `Tagger`          | Free-form chip/tag entry                                      |
+| `CodeEditor`      | Generic code editing (JSON, YAML, shell)                      |
+| `SqlEditor`       | SQL editing (syntax + autocomplete)                           |
+
+`Select` is wrong above ~10 items — use `Combobox`. `Combobox` is wrong for free-form values — use `Tagger`. `CodeEditor`/`SqlEditor` load the full CodeMirror bundle and ship from the `@keboola/design/editors` subpath (not the root); reserve for real code editing.
+
+## Composition recipes
+
+The platform ships **no** `EntityList` / `ModalForm` / `ConfirmDialog` wrapper — these are compositions, not components. Copy the recipe; see [`COMPONENT-API.md`](./COMPONENT-API.md) for the exact props.
+
+**Modal form** — `Modal` + `useAppForm`. The submit button lives in the footer and targets the form by `id`:
+
+```tsx
+import { Button, Modal, useAppForm } from '@keboola/design';
+
+const FORM_ID = 'new-bucket-form';
+
+const form = useAppForm({
+  defaultValues: { name: '', description: '' },
+  onSubmit: async ({ value }) => {
+    /* … */
+  },
+});
+
+<Modal open={open} onOpenChange={setOpen}>
+  <Modal.Content size="medium">
+    <Modal.Header title="New bucket" />
+    <Modal.Body>
+      <form.AppForm>
+        <form.FormBody id={FORM_ID}>
+          <form.AppField name="name">
+            {(field) => <field.TextField label="Name" required />}
+          </form.AppField>
+        </form.FormBody>
+      </form.AppForm>
+    </Modal.Body>
+    <Modal.Footer>
+      <Modal.Close asChild>
+        <Button type="button" variant="secondary">
+          Cancel
+        </Button>
+      </Modal.Close>
+      <form.AppForm>
+        <form.SubmitButton form={FORM_ID}>Create</form.SubmitButton>
+      </form.AppForm>
+    </Modal.Footer>
+  </Modal.Content>
+</Modal>;
+```
+
+**Confirm dialog** — `Modal size="small"` + `Modal.Icon` + a danger action with `isLoading` while the async confirm runs:
+
+```tsx
+<Modal open={open} onOpenChange={setOpen}>
+  <Modal.Content size="small">
+    <Modal.Icon color="red" icon={<AlertTriangle />} />
+    <Modal.Header title="Delete bucket?" description="This action cannot be undone." />
+    <Modal.Footer>
+      <ButtonGroup variant="block">
+        <Modal.Close asChild>
+          <Button type="button" variant="secondary" disabled={isDeleting}>
+            Cancel
+          </Button>
+        </Modal.Close>
+        <Button type="button" variant="danger" isLoading={isDeleting} onClick={handleConfirm}>
+          Delete bucket
+        </Button>
+      </ButtonGroup>
+    </Modal.Footer>
+  </Modal.Content>
+</Modal>
+```
+
+**Card with empty state** — branch on the collection length inside `Card.Content`:
+
+```tsx
+<Card bordered padding="none">
+  <Card.Header className="tw-flex tw-items-center tw-justify-between tw-p-4">
+    <Card.Title>Tokens</Card.Title>
+    <Button size="small">
+      <Plus className="tw-size-4" /> New token
+    </Button>
+  </Card.Header>
+  <Card.Content className="tw-p-0">
+    {tokens.length === 0 ? (
+      <EmptyState variant="compact">
+        <EmptyState.Title>No tokens yet</EmptyState.Title>
+        <EmptyState.Actions>
+          <Button size="small">Create token</Button>
+        </EmptyState.Actions>
+      </EmptyState>
+    ) : (
+      <Table>{/* rows */}</Table>
+    )}
+  </Card.Content>
+</Card>
+```
+
+**Entity list** — `SearchInput` + `Table` + `Pagination` + `EmptyState`. Keep query/page in local state, filter then slice:
+
+```tsx
+<div className="tw-flex tw-flex-col tw-gap-4">
+  <SearchInput
+    allowClear
+    placeholder="Search…"
+    value={query}
+    onValueChange={setQuery}
+    className="tw-w-72"
+  />
+  {filtered.length === 0 ? (
+    <EmptyState>
+      <EmptyState.Icon>
+        <Search />
+      </EmptyState.Icon>
+      <EmptyState.Title>No results match your search</EmptyState.Title>
+    </EmptyState>
+  ) : (
+    <>
+      <Table bordered>{/* pageRows */}</Table>
+      <Pagination>{/* Pagination.Previous / .Button active={…} / .Next */}</Pagination>
+    </>
+  )}
+</div>
+```
+
+**Data card with skeleton** — render `Skeleton` / `SkeletonList` in the exact slot the real content will occupy:
+
+```tsx
+<Card bordered>
+  <Card.Header>
+    <Card.Title>{isLoading ? <Skeleton height="md" className="tw-w-32" /> : 'Storage'}</Card.Title>
+  </Card.Header>
+  <Card.Content>{isLoading ? <SkeletonList groups={2} rowHeight="sm" /> : <Stats />}</Card.Content>
+</Card>
+```
+
+**Alert with action** — pass the action node to `Alert`'s `actions` prop; the variant stays categorical (see brand-neutrality contract):
+
+```tsx
+<Alert
+  variant="warning"
+  title="Trial ends in 3 days"
+  actions={
+    <Button size="small" variant="outline" onClick={onExtend}>
+      Extend
+    </Button>
+  }
+>
+  Add a payment method to keep your project active.
+</Alert>
+```
+
+**Disabled-button tooltip** — a disabled `Button` fires no events, so wrap it in a `span` that carries the trigger and `pointer-events-none` the button:
+
+```tsx
+<Tooltip tooltip={canSave ? null : reason} placement="top" triggerAsChild>
+  <span className={canSave ? undefined : 'tw-inline-block tw-cursor-not-allowed'}>
+    <Button disabled={!canSave} className={canSave ? undefined : 'tw-pointer-events-none'}>
+      Save
+    </Button>
+  </span>
+</Tooltip>
+```
+
+**Info tooltip** — an icon-only `Button variant="inline"` next to a `Label`, with the hint on a `Tooltip`:
+
+```tsx
+<div className="tw-flex tw-items-center tw-gap-1">
+  <Label htmlFor={id}>{label}</Label>
+  <Tooltip tooltip={hint} placement="right" triggerAsChild>
+    <Button
+      variant="inline"
+      size="icon-3xs"
+      aria-label={`More info about ${label}`}
+      className="tw-text-muted-foreground"
+    >
+      <Info className="tw-size-3" />
+    </Button>
+  </Tooltip>
+</div>
+```
+
+**Page header with tabs** — `PageLayout.Header` hosting `PageHeader.Index`, with `Tabs` passed to `headerNav`:
+
+```tsx
+<PageLayout>
+  <PageLayout.Header>
+    <PageHeader.Index
+      title="Storage"
+      metadata="3 buckets and 39 tables"
+      headerNav={
+        <Tabs triggers={TABS} defaultValue={activeTab} onValueChange={setActiveTab}>
+          {/* TabsContent */}
+        </Tabs>
+      }
+    />
+  </PageLayout.Header>
+</PageLayout>
+```
+
+**Creatable combobox** — `Combobox` with `allowCreate` accepts values not in `items`:
+
+```tsx
+<Combobox
+  items={TAGS}
+  value={tag}
+  onValueChange={setTag}
+  allowCreate
+  allowClear
+  placeholder="Pick or create a tag"
+/>
+```
+
+**Sheet** — use `Sheet.Header title="…" description="…"` for a styled title + close icon; do **not** hand-roll with the raw `Sheet.Title`, which renders an unstyled `<h2>`. `Sheet.Body` provides horizontal padding only (`tw-px-4`) — add your own vertical rhythm/gap:
+
+```tsx
+<Sheet open={open} onOpenChange={setOpen}>
+  <Sheet.Content>
+    <Sheet.Header title="Edit table" description="Adjust the table metadata." />
+    <Sheet.Body className="tw-flex tw-flex-col tw-gap-4 tw-py-4">{/* fields */}</Sheet.Body>
+  </Sheet.Content>
+</Sheet>
+```
+
+## Icons
+
+Canonical icon surface is `@keboola/design/icons` — a wildcard re-export of [lucide-react](https://lucide.dev) plus Keboola-custom inline-SVG icons. Follow **shadcn convention**: import named icons directly, no wrapper component. Every Lucide icon is available without any package edit.
+
+```tsx
+import { ChevronDown, Keboola, Loader2 } from '@keboola/design/icons';
+
+<button>Toggle <ChevronDown className="tw-size-4" /></button>
+<Loader2 className="tw-size-4 tw-animate-spin" />
+<Keboola className="tw-size-6" />
+```
+
+- **One import surface**: Lucide icons and Keboola-custom icons (e.g. `Keboola`) both export from `@keboola/design/icons` and share the `LucideIcon` type, so they're interchangeable in any API typed `icon: LucideIcon` (Button, etc.).
+- **Sizing**: prefixed Tailwind `tw-size-*` utility — `tw-size-4` = 16px (default for inline icons), `tw-size-5` = 20px, `tw-size-6` = 24px.
+- **Spinner animation**: explicit via `tw-animate-spin`.
+
+**FontAwesome is fully removed.** Every `icon` prop takes a Lucide `ReactNode`. (Maintainers: the canonical FA→Lucide mapping table lives in `MAINTAINING.md`.)
+
+## Brand-neutrality contract (Layer 0)
+
+Layer-0 components split into two categories. The contract applies to chrome only.
+
+**Chrome — follows the brand.** Surface, structure, navigation: Card body, Modal frame, Input border, Button outline, focus rings, Sidebar, generic text. Re-skins when a customer brand is applied. **Rule:** use semantic tokens (`tw-bg-background`, `tw-text-foreground`, `tw-border-border`, `tw-bg-muted`, `tw-text-muted-foreground`, `tw-bg-accent`, `tw-bg-destructive`, …). Customers override these via `@keboola/brand-registry`.
+
+**Categorical — stays fixed across brands.** Badge `color`, Alert `variant`, ModalIcon status, decorative tag palette. Colors encode meaning; the prop API (`color="green"`, `variant="error"`) is a semantic contract with the consumer. **Rule:** keep using primitive scales (`primary-500`, `error-500`, etc.). A customer's "error" alert stays red regardless of brand — that is correct.
+
+**Heuristic.** If a component exposes a `variant` / `color` / `status` prop encoding meaning, it is categorical. Otherwise it is chrome.
+
+Layer-1 blocks (`src/blocks/`) are allowed to be Keboola-opinionated — the contract only applies to Layer-0 primitives.
+
+## Forms
+
+```ts
+import { useAppForm, withForm, setServerFieldErrors } from '@keboola/design';
+```
+
+`useAppForm` is a TanStack Form `createFormHook` binding with typed field connectors (`field.TextField`, `field.NumberField`, …). The schema library (`zod`, `valibot`, …) lives in your app — the block accepts any [Standard Schema](https://standardschema.dev/)-compatible validator. See the Modal-form recipe above for the composite case, and the per-connector signatures in [`COMPONENT-API.md`](./COMPONENT-API.md).
+
+## Theming (brand + colorScheme)
+
+Wrap your app once in `<ThemeProvider>` from `@keboola/design`. It reads a `Brand` from `@keboola/brand-registry`, sets `data-brand` on `<html>`, and injects the matching `--color-*` / `--radius-*` CSS variables.
+
+```tsx
+import { ThemeProvider } from '@keboola/design';
+
+<ThemeProvider brand={brand} colorScheme="system">
+  <App />
+</ThemeProvider>;
+```
+
+- **`brand`** — the active brand decides the chrome. **argo styling is brand-driven**: any non-`keboola-legacy` brand renders argo chrome automatically (`renderArgo = !isLegacy`), so a default `keboola` / `example-customer` brand needs no per-component flags. The `keboola-legacy` brand renders the pre-modernization chrome. With no `brand` prop, `ThemeProvider` defaults to the canonical `keboola` brand.
+- **`colorScheme`** — `"light"` (default) / `"dark"` / `"system"`. Dark mode is set **here, on the root provider** — not per component. `"system"` follows the OS preference.
+
+The per-call-site `argo` / `variant="argo"` prop is a **transitional escape hatch** (force argo on one component regardless of brand), **not** the primary switch — prefer driving the whole tree from the brand. Two escape-hatch forms exist:
+
+- **Boolean prop:** `<Button argo>`, `<Alert argo>` — swaps the entire variant family.
+- **String variant:** `<Select variant="argo">`, `<MultiCombobox variant="argo">`, `<DropdownMenu variant="argo">` — for components whose `variant` union already encodes `'argo'`.
+
+Define a custom brand with `@keboola/brand-registry`'s `brandSchema` (Zod) and pass it to `ThemeProvider`; or override the `--color-*` / `--radius-*` CSS variables directly on `:root`.
+
+## Common Tailwind patterns
+
+```
+not-disabled:hover:tw-bg-accent
+disabled:tw-opacity-40 tw-cursor-not-allowed
+focus-visible:tw-ring-2 tw-ring-primary
+[&_svg]:tw-text-muted-foreground
+```