@keboola/design 9.1.0 → 10.1.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # @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.
+Consumer usage contract for the Keboola design system — shadcn-aligned React primitives (Radix under most, Base UI for newer ones such as `Combobox`), 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).
 
@@ -8,6 +8,7 @@ Working **on** the package (commands, layer boundary, token surface, the FA→Lu
 
 ## Import surface
 
+- **ESM only.** The package ships no CommonJS build — no `*.cjs` and no `require` condition in the `exports` map. Consume it from an ESM-capable bundler (Vite, webpack, Rollup, esbuild) or `import` it from Node. A `require()` resolves to the ESM entry, so it works only where the runtime can require ESM (Node ≥ 22.12) and throws `ERR_REQUIRE_ESM` on older ones.
 - **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.**
@@ -43,7 +44,7 @@ The API is "shadcn-shaped" enough to invite copy-paste but different enough to b
 | `Select`              | composed children `<Select><SelectTrigger/><SelectContent><SelectItem/></SelectContent></Select>` | data-driven — `Select` takes **`items`**, and the form connector `SelectField` delegates to it, so both take the same `items`: flat `{ value, label, icon?, disabled? }` or groups of them (`{ label?, items }`) |
 | `Sidebar.SearchInput` | `asChild`-wrappable trigger                                                                       | concrete `<input>` (`ComponentProps<'input'>`), **no `asChild`** — put a custom search affordance in a plain element inside `Sidebar.Header`                                                                     |
 
-Other compound (not named-export) components in the barrel: `Modal.*`, `Sheet.*`, `Card.*`, `Sidebar.*`, `PageHeader.Index` / `.Detail`, `EmptyState.*`, `Pagination.*`, `Popover.*` — reach for the dotted sub-parts, not flat `XContent` / `XTrigger` named imports. (The root `SearchInput` block is distinct from `Sidebar.SearchInput` and is fully composable.)
+Other compound (not named-export) components in the barrel: `Modal.*`, `Sheet.*`, `Card.*`, `Sidebar.*`, `PageHeader.Index` / `.Detail`, `EmptyState.*`, `Pagination.*`, `Popover.*`, `Workbench.*` — reach for the dotted sub-parts, not flat `XContent` / `XTrigger` named imports. (The root `SearchInput` block is distinct from `Sidebar.SearchInput` and is fully composable.)
 
 ## Decision tree
 
@@ -85,10 +86,13 @@ This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-A
 | `useAppForm`            | Full form layouts with validation (see Forms below)                |
 | `useAppForm` connectors | Picking between `TextField` / `NumberField` / `SelectField` / …    |
 | `OtpInput`              | Fixed-length verification code (MFA, email confirm, sudo step-up)  |
-| `FileUpload`            | Argo-only drag-and-drop file picker; caller owns the file array    |
+| `FileUpload`            | Drag-and-drop file picker box; caller owns the file array          |
+| `useFileDropTarget`     | Make an existing subtree a drop target, styled by you              |
 
 **Never** build custom label + input combinations — compose `Label` + `FormGroup.TextInput` + `FormGroup.Help` inside `FormGroup`.
 
+`FileUpload` composes `FileUpload.DropZone` (the dashed box, owning the drag / error visuals) with `FileUpload.FileList` (selected files; `invalid` tints the rows). It deliberately ships **no** rejection copy — the wording is product copy, so read the current rejections with `useFileUploadRejections()` inside `FileUpload` and write the sentence yourself. Reach for `useFileDropTarget` only when there is no box to render: it returns `getRootProps()` / `isDragActive` for an affordance you style, and `noClick` / `noKeyboard` keep an already-interactive subtree (a composer, a form) from opening the file dialog on every click.
+
 ### Status surfaces
 
 | Use                           | When                                                  |
@@ -143,23 +147,36 @@ Charts ship from the **`@keboola/design/charts`** subpath (recharts under the ho
 
 `data: {…}[]` rows; `xKey` + `series: [{ dataKey, name?, color? }]` (cartesian) or `nameKey` + `dataKey` (pie). Each chart is self-contained (mounts its own responsive container) — give it a `height` (default 300). Pin a series to a palette slot with `color: 1..5`; otherwise it follows series order.
 
+**Y-axis baseline — `yDomain`, on `LineChart` only.** Every chart starts the value axis at zero by default. `LineChart` takes `yDomain={[min, max]}` to move it: explicit numbers, `'auto'`, or padded data extremes — `['dataMin - 500', 'dataMax + 500']` (recharts pads the low end DOWN and the high end UP, so `'dataMax - 500'` is not a thing and won't type-check). It works with `showYAxis={false}` too.
+
+```tsx
+// Credits used vs budgeted — both ~8,000, so a 0–10,000 axis hides the crossover.
+<LineChart data={data} xKey="month" series={series} yDomain={['dataMin - 500', 'dataMax + 500']} />
+```
+
+Reach for it when **two or more series of similar magnitude sit far from zero** and their difference is the story — actual vs target, used vs quota. Don't reach for it for a **single series whose magnitude the reader is meant to judge**: zooming the axis turns ordinary noise into a dramatic trend. And it is deliberately absent from `BarChart` / `AreaChart` — a line encodes value by position, so the baseline is just a viewport, but a bar's length and an area's fill are measured _from_ the baseline, and truncating those makes the geometry misstate the ratios. If an area chart needs a non-zero baseline, it is a line chart. (`ChartContainer` + a raw recharts chart remains the escape hatch for anything the wrappers don't model.)
+
 ### 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`                                                     |
+| 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                                                                |
+| `Card`           | Semantic content surface with `Card.Header` / `Card.Title` / `Card.Content` slots                                            |
 | `Sidebar`        | App-shell left navigation rail (host inside `AppShell.Sidebar`)                                                              |
+| `SectionNav`     | In-page navigation for **one page's** grouped sections (host in `PageLayout.Content nav`) — tree, dropdown when narrow       |
 | `Navbar`         | Top navigation bar (host inside `AppShell.Header`) — brand mark, primary nav, search / account. Pairs with the top-nav shell |
+| `Workbench`      | Bottom status rail plus a panel that expands over the page — VS Code's bottom dock, for tooling that outlives one page       |
 
-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.
+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: `AppShell.Main` owns it, with an opinionated default.** `AppShell.Main` applies a default page gutter (`tw-p-6`) so content looks right out of the box. Because `cn` is tailwind-merge, override it from the call site when the app owns its own gutter — e.g. `className="tw-p-0"` (kbc-ui does this; it centralizes the gutter on its own shell wrapper). `PageLayout` still adds **no** gutter of its own, so header and content align inside whatever gutter `AppShell.Main` provides.
+**`Card` padding: the root owns it, or the slots do — never both.** `Card padding` (default `small`) pads the root and gaps its slots, which is right for a plain content card. Set `padding="none"` when a slot must bleed to the card edge — a table, an `EmptyState`, or a header with a rule under it — and the root also drops its gap so the bands sit flush. In that mode the slots pad themselves: `Card.Header divider` becomes its own padded band with a full-bleed bottom rule, and `Card.Content padded` takes the standard body padding. `Card.Header` distributes its children by `layout`: **`row`** (default) pushes them apart, title left and actions right; **`inline`** keeps them together for a title with an icon or badge; **`stack`** puts a description under the title. Don't hand-roll these with `className` — `cva` here concatenates rather than tailwind-merges, so a `tw:justify-start` in `className` will not reliably beat the `row` default. Use the prop.
+
+**Page gutter: `AppShell.Main` owns it, with an opinionated default.** `AppShell.Main` applies a default page gutter (`tw:p-6`) so content looks right out of the box. Because `cn` is tailwind-merge, override it from the call site when the app owns its own gutter — e.g. `className="tw:p-0"` (kbc-ui does this; it centralizes the gutter on its own shell wrapper). `PageLayout` still adds **no** gutter of its own, so header and content align inside whatever gutter `AppShell.Main` provides.
 
 ```tsx
 // Default gutter — nothing to add:
@@ -168,11 +185,21 @@ Vertical rhythm: prefer `tw-gap-*` on a flex column parent over `tw-mt-*` on chi
 </AppShell.Main>
 
 // Own your gutter — opt out and add your own:
-<AppShell.Main className="tw-p-0">
-  <div className="tw-px-8 tw-py-6">{/* custom gutter */}</div>
+<AppShell.Main className="tw:p-0">
+  <div className="tw:px-8 tw:py-6">{/* custom gutter */}</div>
 </AppShell.Main>
 ```
 
+**Header width: `headerSpan` picks the row template — don't hand-roll `gridTemplateAreas`.** By default the sidebar geometry gives the header the middle column only (`"sidebar header aside"`), so both rails sit beside it and run the full height. Pass `headerSpan="full"` for a full-bleed header row above both rails (`"header header header" / "sidebar main aside"`), so the brand mark aligns to the viewport's left edge. Reach for it when the header carries app-wide identity — brand mark, project switcher, account menu — rather than page-level navigation. It is a no-op under the top-nav geometry, whose header already spans the width.
+
+```tsx
+<AppShell headerSpan="full">
+  <AppShell.Header flush>{/* Navbar: brand mark, project switcher, account */}</AppShell.Header>
+  <AppShell.Sidebar>{/* left rail, below the header */}</AppShell.Sidebar>
+  <AppShell.Main>{/* … */}</AppShell.Main>
+</AppShell>
+```
+
 ### Navigation / flow
 
 | Use        | When                                                                                                                                        |
@@ -184,6 +211,8 @@ Vertical rhythm: prefer `tw-gap-*` on a flex column parent over `tw-mt-*` on chi
 
 **Never** use `Stepper` for branching navigation (use `Tabs`) or an unordered status list (use `Timeline`).
 
+**`SectionNav` is not `Sidebar`.** `Sidebar` is the app's left rail — global, one per shell, outside `PageLayout`, with `SidebarProvider` state and icon-collapse. `SectionNav` is scoped to a single page's sections, lives in `PageLayout.Content nav`, and holds nothing but an open/closed flag per group. Reach for `SectionNav` when a page has more sections than a tab row can hold, or sections that group; `Tabs` when they don't.
+
 ### Separators
 
 | Use                        | When                                                                  |
@@ -260,7 +289,7 @@ const form = useAppForm({
 <AlertModal onConfirm={() => deleteBucket(bucketId)}>
   <AlertModal.Trigger asChild>
     <Button variant="danger">
-      <Trash2 className="tw-size-4" /> Delete bucket
+      <Trash2 className="tw:size-4" /> Delete bucket
     </Button>
   </AlertModal.Trigger>
   <AlertModal.Content variant="danger" title="Delete bucket?" confirmLabel="Delete bucket">
@@ -271,17 +300,19 @@ const form = useAppForm({
 
 Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` to `AlertModal` (it honors `defaultOpen` too).
 
+A host that tracks the request itself rather than returning a promise passes `isLoading` to `AlertModal` for the same locked, spinning state; `AlertModal.Content` takes `confirmDisabled` to block the confirm action alone while a precondition is unmet. The children stay the description — reach for `Modal` when the dialog needs a form, a table, or anything else that isn't phrasing content.
+
 **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.Header divider>
     <Card.Title>Tokens</Card.Title>
     <Button size="small">
-      <Plus className="tw-size-4" /> New token
+      <Plus className="tw:size-4" /> New token
     </Button>
   </Card.Header>
-  <Card.Content className="tw-p-0">
+  <Card.Content>
     {tokens.length === 0 ? (
       <EmptyState variant="compact">
         <EmptyState.Title>No tokens yet</EmptyState.Title>
@@ -299,13 +330,13 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 **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">
+<div className="tw:flex tw:flex-col tw:gap-4">
   <SearchInput
     allowClear
     placeholder="Search…"
     value={query}
     onValueChange={setQuery}
-    className="tw-w-72"
+    className="tw:w-72"
   />
   {filtered.length === 0 ? (
     <EmptyState>
@@ -330,7 +361,7 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 ```tsx
 <Card bordered>
   <Card.Header>
-    <Card.Title>{isLoading ? <Skeleton height="md" className="tw-w-32" /> : 'Storage'}</Card.Title>
+    <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>
@@ -356,8 +387,8 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 
 ```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'}>
+  <span className={canSave ? undefined : 'tw:inline-block tw:cursor-not-allowed'}>
+    <Button disabled={!canSave} className={canSave ? undefined : 'tw:pointer-events-none'}>
       Save
     </Button>
   </span>
@@ -367,16 +398,16 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 **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">
+<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"
+      className="tw:text-muted-foreground"
     >
-      <Info className="tw-size-3" />
+      <Info className="tw:size-3" />
     </Button>
   </Tooltip>
 </div>
@@ -400,6 +431,33 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 </PageLayout>
 ```
 
+**Page with a section nav** — `PageLayout.Header sticky` + `PageLayout.Content nav={<SectionNav …/>}`. The block and the slot are shipped; the **group model**, **visibility / permission filtering** and **all routing** are the composition and stay in your app. Build the model once and feed both the nav and any flat tab row from it, so the two can never disagree about what exists. `renderItem` is the router seam — return your router's link and spread `itemProps`:
+
+```tsx
+<PageLayout>
+  <PageLayout.Header sticky>
+    <PageHeader.Index title="Settings" />
+  </PageLayout.Header>
+  <PageLayout.Content
+    nav={
+      <SectionNav
+        groups={groups} // already filtered for this user
+        activeId={pathname}
+        renderItem={({ targetId, children, itemProps }) => (
+          <Link to={targetId} {...itemProps}>
+            {children}
+          </Link>
+        )}
+      />
+    }
+  >
+    {page}
+  </PageLayout.Content>
+</PageLayout>
+```
+
+Both router wirings (TanStack Router, and a custom named router) are in [`RECIPES.md`](./RECIPES.md#section-nav).
+
 **Creatable combobox** — `Combobox` with `allowCreate` accepts values not in `items`:
 
 ```tsx
@@ -413,13 +471,13 @@ Controlled (opened from elsewhere, no `Trigger`): pass `open` + `onOpenChange` t
 />
 ```
 
-**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:
+**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.Body className="tw:flex tw:flex-col tw:gap-4 tw:py-4">{/* fields */}</Sheet.Body>
   </Sheet.Content>
 </Sheet>
 ```
@@ -431,14 +489,15 @@ Canonical icon surface is `@keboola/design/icons` — a re-export of every [luci
 ```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" />
+<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`.
+- **Vendor marks** also ship from `@keboola/design/icons` — `Aws`, `Azure`, `ChatGpt`, `Claude`, `Cursor`, `Devin`, `Gcp`, `Google`, `Keboola`, `Make`, `Microsoft` — in their own brand colours by default; pass **`mono`** to render one in `currentColor` instead. The `Eu` / `Us` flags are colour-only.
+- **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`.)
 
@@ -446,9 +505,9 @@ import { ChevronDown, Keboola, Loader2 } from '@keboola/design/icons';
 
 Layer-0 colour usage splits into three buckets.
 
-**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`.
+**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`.
 
-**Status — themeable under argo, with AA-legible defaults.** The four semantic states — `success`, `warning`, `info`, and `destructive` (used for "error") — are brand-overridable tokens, not fixed scales. Alert `variant`, `HelpBlock` / field-error state, `ErrorState`, and `Stepper` status read them, so a brand recolours every status surface at once. **Rule:** consume the token as **tint + text/icon** — `tw-bg-<role>/10` for the surface, `tw-text-<role>` / `tw-border-<role>/25` for the mark. The default token values ship dark enough to be AA (≥4.5:1) as text/icon on their own tint, in light **and** dark mode — a brand overriding them should preserve that. Avoid solid fills with a white foreground (`tw-bg-<role>` + white): the token flips light in dark mode, so white-on-token fails there. A brand _can_ recolour "error" away from red — that is now allowed; the accessible-on-tint contract is what must hold, not the hue. **Legacy exception:** the themeable treatment is gated to argo (`data-[argo=true]:` / `group-data-[argo=true]/…:`). Under legacy chrome (`useArgoDesign()` → `false`) Alert and `ErrorState` keep their original fixed status scales (`blue-*`/`green-*`/`warning-*`/`error-*`), and the legacy brand retains its original status token hues — so legacy status colour is unchanged.
+**Status — themeable under argo, with AA-legible defaults.** The four semantic states — `success`, `warning`, `info`, and `destructive` (used for "error") — are brand-overridable tokens, not fixed scales. Alert `variant`, `HelpBlock` / field-error state, `ErrorState`, and `Stepper` status read them, so a brand recolours every status surface at once. **Rule:** consume the token as **tint + text/icon** — `tw:bg-<role>/10` for the surface, `tw:text-<role>` / `tw:border-<role>/25` for the mark. The default token values ship dark enough to be AA (≥4.5:1) as text/icon on their own tint, in light **and** dark mode — a brand overriding them should preserve that. Avoid solid fills with a white foreground (`tw:bg-<role>` + white): the token flips light in dark mode, so white-on-token fails there. A brand _can_ recolour "error" away from red — that is now allowed; the accessible-on-tint contract is what must hold, not the hue. **Legacy exception:** the themeable treatment is gated to argo (`data-[argo=true]:` / `group-data-[argo=true]/…:`). Under legacy chrome (`useArgoDesign()` → `false`) Alert and `ErrorState` keep their original fixed status scales (`blue-*`/`green-*`/`warning-*`/`error-*`), and the legacy brand retains its original status token hues — so legacy status colour is unchanged.
 
 **Decorative — stays fixed across brands.** The non-semantic palette that encodes category rather than state: `Badge` decorative colours (`purple`, `cyan`, `teal`, `blue`, …), chart colours, decorative tag palette. **Rule:** keep using primitive scales (`purple-500`, `cyan-500`, …). These are an identity/category contract with the consumer and do not re-skin.
 
@@ -466,22 +525,38 @@ import { useAppForm, withForm, setServerFieldErrors } from '@keboola/design';
 
 ## 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.
+Wrap your app once in `<ThemeProvider>` from `@keboola/design`. You give it the set of `Brand`s it may activate and the id of the active one; it sets `data-brand` and `data-theme` on `<html>` and injects the matching `--color-*` / `--radius-*` CSS variables.
 
 ```tsx
 import { ThemeProvider } from '@keboola/design';
+import { keboola } from '@keboola/brand-registry';
 
-<ThemeProvider brand={brand} colorScheme="system">
+<ThemeProvider brands={[keboola]} defaultBrandId={keboola.id} defaultScheme="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. Render the user-facing light/dark/system control with the **`ColorModeSwitch`** block (`<ColorModeSwitch value={scheme} onValueChange={setScheme} />`) — a controlled icon-button + dropdown; feed the same state to `ThemeProvider`'s `colorScheme`.
+- **`brands`** — the brands this provider knows about; the active id resolves against them. Defaults to an empty list, in which case the active brand falls back to a `design-system` sentinel whose empty theme injects nothing, so the stylesheet's own `:root` defaults provide every token.
+- **`brandId` / `defaultBrandId` / `onBrandIdChange`** — the active brand, controlled or uncontrolled. An unknown id (including the sentinel) falls back to that same empty theme rather than throwing.
+- **`scheme` / `defaultScheme` / `onSchemeChange`** — `"light"` (default) / `"dark"` / `"system"`, controlled or uncontrolled. Dark mode is set **here, on the root provider** — not per component. `"system"` follows `prefers-color-scheme` and resolves reactively. Render the user-facing control with the **`ColorModeSwitch`** block (`<ColorModeSwitch value={scheme} onValueChange={setScheme} />`) and feed the same state back in.
 
-Chrome is driven **entirely** by the active brand — there is no per-call-site `argo` prop or `variant="argo"` escape hatch. To render a subtree under a different brand (e.g. an argo section inside a `keboola-legacy` app), wrap it in a nested `<ThemeProvider brand={…}>`; `useIsLegacyBrand()` reads the nearest provider, so the override is scoped to that subtree.
+Read the resolved values with `useTheme()` (`brandId`, `currentTheme`, `themes`, `scheme`, `resolvedScheme`, and the setters). With no provider above it, it answers the defaults rather than throwing.
 
-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`.
+### The argo/legacy switch is separate from the brand
+
+`ThemeProvider` does **not** decide whether a subtree renders the argo design language — that is a kbc-ui migration concern, so it rides its own context:
+
+```tsx
+import { ArgoDesignContext, useArgoDesign } from '@keboola/design';
+
+<ArgoDesignContext value={false}>{/* legacy chrome for this subtree */}</ArgoDesignContext>;
+```
+
+`ArgoDesignContext` defaults to `true` (argo — the modern default; legacy chrome is the exception), so an app that never provides it gets argo everywhere. kbc-ui provides `false` for its legacy brands and overrides per subtree as pages are migrated; components read it with `useArgoDesign()`. It is **temporary** and will be deleted once every kbc-ui surface is migrated — don't build on it in a new app.
+
+Because the value is read from the nearest provider, a nested override scopes to that subtree. The build ships a single instance of both contexts across every subpath entry, so a provider mounted from the root barrel is visible to components that ship in `@keboola/design/rjsf`, `/markdown-editor`, `/mermaid` and `/editors` too.
+
+Define a custom brand with `@keboola/brand-registry`'s `brandSchema` (Zod) and pass it in `brands`; or override the `--color-*` / `--radius-*` CSS variables directly on `:root`.
 
 ## Testing (Vitest)
 
@@ -514,8 +589,10 @@ pnpm exec ui-gen-bench eval --serve dist --route /tokens --brief "Tokens list wi
 ## 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
+tw:not-disabled:hover:bg-accent
+tw:disabled:opacity-40 tw:cursor-not-allowed
+tw:focus-visible:ring-2 tw:ring-primary
+tw:[&_svg]:text-muted-foreground
 ```
+
+The `tw:` prefix always comes **first**, ahead of every variant — `tw:not-disabled:hover:bg-accent`, never `not-disabled:hover:tw-bg-accent`. Tailwind v4 makes the prefix a variant of its own, so it leads the chain and the utility keeps its bare name.

package/COMPONENT-API.md

@@ -382,9 +382,12 @@ Source: `src/components/Card/Card.tsx`
 
 Source: `src/components/Card/CardHeader.tsx`
 
-> Native `<div>` attributes only.
+> Own props below, plus native `<div>` attributes.
 
-_No own props — see note above for passthrough attributes._
+| Prop      | Type                           | Required | Default | Description                                                                                                                                                                                                                                           |
+| --------- | ------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `divider` | `boolean`                      | no       | `false` | Adds a bottom rule, the header's own padding, and a 64px height floor so the band stays the same height with or without an action button. The rule spans the full card width — pair with `Card padding="none"`; on a padded root it is inset.         |
+| `layout`  | `"inline" \| "row" \| "stack"` | no       | `row`   | How the header distributes its children. `row` (default) pushes them apart — title left, actions right. `inline` keeps them together on one line, for a title with an adornment such as an icon or badge. `stack` puts a description under the title. |
 
 ### `Card.Title`
 
@@ -400,9 +403,11 @@ Source: `src/components/Card/CardTitle.tsx`
 
 Source: `src/components/Card/CardContent.tsx`
 
-> Native `<div>` attributes only.
+> Own props below, plus native `<div>` attributes.
 
-_No own props — see note above for passthrough attributes._
+| Prop     | Type      | Required | Default | Description                                                                                                                     |
+| -------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `padded` | `boolean` | no       | `false` | Applies the standard body padding. Use with `Card padding="none"`, where the root adds none — otherwise the padding is doubled. |
 
 ## Theming
 
@@ -415,7 +420,7 @@ Source: `src/components/ThemeProvider/ThemeProvider.tsx`
 | Prop              | Type                                                                                                                                                                                                                                                                                                            | Required | Default | Description                                                                                                                                                                                                      |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `brandId`         | `string`                                                                                                                                                                                                                                                                                                        | no       | —       | Controlled active brand id. When set, the parent owns the value and `setBrand` only notifies via `onBrandIdChange` (it does not mutate internal state).                                                          |
-| `brands`          | `readonly { id: string; name: string; theme: { colors?: { foreground?: string; background?: string; muted?: string \| undefined; mutedForeground?: string \| undefined; border?: string \| undefined; ... 22 more ...; sidebar?: { ...; } \| undefined; } \| undefined; ... 6 more ...; gradient?: { ...; }...` | no       | `[]`    | Brands this provider knows about; the active brand id resolves against these.                                                                                                                                    |
+| `brands`          | `readonly { id: string; name: string; theme: { colors?: { foreground?: string; background?: string; muted?: string \| undefined; mutedForeground?: string \| undefined; border?: string \| undefined; ... 23 more ...; sidebar?: { ...; } \| undefined; } \| undefined; ... 6 more ...; gradient?: { ...; }...` | no       | `[]`    | Brands this provider knows about; the active brand id resolves against these.                                                                                                                                    |
 | `defaultBrandId`  | `string`                                                                                                                                                                                                                                                                                                        | no       | —       | Initial active brand id for uncontrolled use. Defaults to the design-system sentinel (`DEFAULT_BRAND_ID`) — no brand tokens injected, so the stylesheet defaults apply.                                          |
 | `defaultScheme`   | `ColorScheme`                                                                                                                                                                                                                                                                                                   | no       | —       | Initial colour scheme for uncontrolled use. Defaults to `light` (`DEFAULT_COLOR_SCHEME`).                                                                                                                        |
 | `onBrandIdChange` | `((brandId: string) => void)`                                                                                                                                                                                                                                                                                   | no       | —       | Called with the next id whenever `setBrand` runs — required to persist the choice in controlled mode.                                                                                                            |
@@ -439,19 +444,21 @@ Source: `src/components/BrandLogo/BrandLogo.tsx`
 
 Source: `src/blocks/AppShell/AppShell.tsx`
 
-> Compound app-root shell that follows the active brand (sidebar vs top-nav). Subcomponents: `AppShell.Sidebar`, `AppShell.Header`, `AppShell.Main`. `AppShell.Main` owns the default page gutter (`tw-p-6`) — override with `className="tw-p-0"`. Native `<div>` attributes.
+> Compound app-root shell that follows the active brand (sidebar vs top-nav). Subcomponents: `AppShell.Sidebar`, `AppShell.Header`, `AppShell.Aside`, `AppShell.Main`. `AppShell.Main` owns the default page gutter (`tw:p-6`) — override with `className="tw:p-0"`. `AppShell.Header` and `AppShell.Aside` take `flush` — pass it when the slot hosts a chrome component that paints itself (`Navbar`, `Sidebar side="right"`), so the slot drops its own padding, background and border instead of insetting the child. Native `<div>` attributes.
 
-_No own props — see note above for passthrough attributes._
+| Prop         | Type                 | Required | Default   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------ | -------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `headerSpan` | `AppShellHeaderSpan` | no       | `content` | How far the header row stretches. `content` (default) gives it the middle column only, with both rails beside it; `full` spans all three columns and drops the rails below it, so the brand mark aligns to the viewport edge. No-op under the top-nav geometry, whose header is already full width. Reach for `full` when the header carries app-wide identity (brand mark, project switcher, account menu) rather than page-level navigation. |
 
 ### `PageLayout`
 
 Source: `src/blocks/PageLayout/PageLayout.tsx`
 
-> Compound page shape: header, tabs, toolbar, content, footer. Subcomponents: `PageLayout.Header`, `PageLayout.Content`, `PageLayout.Footer`. `maxWidth` is `narrow` | `default` | `wide` | `full`. Adds no gutter of its own. Native `<div>` attributes.
+> Compound page shape: header, tabs, toolbar, content, footer. Subcomponents: `PageLayout.Header`, `PageLayout.Content`, `PageLayout.Footer`. `maxWidth` is `narrow` | `default` | `wide` | `full`. Adds no gutter of its own. `PageLayout.Header` takes `sticky` (pins + paints the header, and publishes its measured height as `--page-header-height` on the root); `PageLayout.Content` takes `nav` (a `SectionNav`) for the two-column in-page-navigation layout, and behaves exactly as before without it. Native `<div>` attributes.
 
 | Prop       | Type                                        | Required | Default | Description |
 | ---------- | ------------------------------------------- | -------- | ------- | ----------- |
-| `maxWidth` | `"default" \| "narrow" \| "wide" \| "full"` | no       | `full`  |             |
+| `maxWidth` | `"default" \| "full" \| "narrow" \| "wide"` | no       | `full`  |             |
 
 ### `PageHeader.Index`
 
@@ -507,6 +514,21 @@ Source: `src/components/Sidebar/Sidebar.tsx`
 | `side`        | `SidebarSide`   | no       | `left`  |             |
 | `style`       | `CSSProperties` | no       | —       |             |
 
+### `SectionNav`
+
+Source: `src/blocks/SectionNav/SectionNav.tsx`
+
+> In-page navigation for one page's grouped sections — a tree above the container breakpoint, a dropdown below it. **Not** `Sidebar`: page-scoped, hosted in `PageLayout.Content nav`, no global state. Router-agnostic — `renderItem` returns your router's link and receives `{ targetId, isActive, children, itemProps }`; spread `itemProps` whole. Visibility / permission filtering and the group model stay in the app (see RECIPES.md#section-nav).
+
+| Prop               | Type                                              | Required | Default    | Description                                                                                                                                                                               |
+| ------------------ | ------------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `groups`           | `SectionNavGroup[]`                               | yes      | —          | The sections to show, already filtered. Visibility, permissions and feature flags stay in the app — this block renders exactly what it is handed, in order.                               |
+| `renderItem`       | `(props: SectionNavItemRenderProps) => ReactNode` | yes      | —          | Renders the clickable element for one row, so routing never enters the design system. Return a `NavLink` / TanStack `Link` / `<a>` pointing at `targetId` and spread `itemProps` onto it. |
+| `activeId`         | `string`                                          | no       | —          | `id` of the current section: a child's, or a childless group's.                                                                                                                           |
+| `className`        | `string`                                          | no       | —          | Applied to the tree's `<nav>`. The column's own geometry belongs to `PageLayout.Content nav`.                                                                                             |
+| `label`            | `string`                                          | no       | `Sections` | Accessible name for the tree's `<nav>`, and the collapsed label with nothing active.                                                                                                      |
+| `showDescriptions` | `boolean`                                         | no       | `false`    | Print each section's `description` under its title. Off — the tree stays scannable without it.                                                                                            |
+
 ### `Navbar`
 
 Source: `src/components/Navbar/Navbar.tsx`

package/README.md

@@ -130,13 +130,13 @@ Coverage is **measured, not gated** — it gives a baseline for the story suite.
 pnpm --filter @keboola/design test:stories:coverage
 ```
 
-Same prerequisites as `test:stories` (build workspace deps, install Chromium). Reports land in `packages/design/coverage/` (gitignored): a `text` summary in the console and a browsable `html` report at `coverage/index.html`.
+Same prerequisites as `test:stories` (build workspace deps, install Chromium). Reports land in `packages/design/coverage/stories/` (gitignored): a `text` summary in the console and a browsable `html` report at `coverage/stories/index.html`. The jsdom unit lane reports separately into `coverage/unit/` — it uses the shared v8 preset (`@keboola/vitest-config`), so the two providers don't overwrite each other.
 
 **Why istanbul, not v8:** this is a browser-mode Vitest project. v8 coverage relies on Node's inspector, which isn't available in a Playwright-driven browser, so the [istanbul provider](https://vitest.dev/guide/coverage#coverage-providers) (`@vitest/coverage-istanbul`, pinned to the Vitest version) instruments the source at transform time and works in both Node and the browser.
 
-**What's covered:** `src/**` component source, excluding stories (`*.stories.tsx`), unit tests (`*.test.{ts,tsx}`), barrels (`index.ts`), type decls, `src/docs/**`, and `src/icons/**` (curated lucide re-exports plus custom SVG marks like `Keboola` — trivial visual surface, no logic to gate).
+**What's covered:** `src/**` component source, excluding stories (`*.stories.tsx`), unit tests (`*.test.{ts,tsx}`), type decls, `src/docs/**`, and `src/icons/**` (curated lucide re-exports plus custom SVG marks like `Keboola` — trivial visual surface, no logic to gate).
 
-**What the numbers reflect:** only some story files carry a `play()` interaction test; the rest contribute just their render/smoke path, so branch coverage trails statement coverage. The lowest-covered areas are the interaction-heavy blocks that still lack a `play()`. Run `test:stories:coverage` and open `coverage/index.html` for the current per-file numbers — they're not pinned here because they drift with every story and `play()` added.
+**What the numbers reflect:** only some story files carry a `play()` interaction test; the rest contribute just their render/smoke path, so branch coverage trails statement coverage. The lowest-covered areas are the interaction-heavy blocks that still lack a `play()`. Run `test:stories:coverage` and open `coverage/stories/index.html` for the current per-file numbers — they're not pinned here because they drift with every story and `play()` added.
 
 ### Icons
 

package/dist/MermaidDiagram-EOKJHQQV.js

@@ -0,0 +1,10 @@
+export { MermaidDiagram } from './chunk-KPNAW5MU.js';
+import './chunk-IJTHFNNJ.js';
+import './chunk-VPPM7UUQ.js';
+import './chunk-L37JJ6MR.js';
+import './chunk-CTCFYWJC.js';
+import './chunk-BOHNXTMM.js';
+import './chunk-63NSN2VL.js';
+import './chunk-JP7PNHLH.js';
+//# sourceMappingURL=MermaidDiagram-EOKJHQQV.js.map
+//# sourceMappingURL=MermaidDiagram-EOKJHQQV.js.map

package/dist/MermaidDiagram-EOKJHQQV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"MermaidDiagram-EOKJHQQV.js"}

package/dist/charts.d.ts

@@ -75,6 +75,17 @@ type ChartSeries = {
     /** Pin to a specific palette token (1–5). Defaults to the series position. */
     color?: ChartColorToken;
 };
+/**
+ * One end of a value-axis domain: an explicit number, `'auto'` (let the axis
+ * pick), or a data extreme with an optional padding offset.
+ *
+ * The offset forms mirror what recharts actually parses — it pads the low end
+ * DOWN (`'dataMin - 500'`) and the high end UP (`'dataMax + 500'`); the mirrored
+ * spellings are silently ignored there, so they are not typed here either.
+ */
+type ChartAxisBound = number | 'auto' | 'dataMin' | 'dataMax' | `dataMin - ${number}` | `dataMax + ${number}`;
+/** `[min, max]` bounds for a value axis. */
+type ChartAxisDomain = readonly [ChartAxisBound, ChartAxisBound];
 /** Props shared by the cartesian charts (line / bar / area). */
 type CartesianChartProps = {
     /** The rows to plot. */
@@ -100,6 +111,21 @@ type CartesianChartProps = {
     className?: string;
 };
 
+type LineChartProps = CartesianChartProps & {
+    /**
+     * `[min, max]` bounds for the value (y) axis — numbers, `'auto'`, or padded
+     * data extremes (`['dataMin - 500', 'dataMax + 500']`). Defaults to a zero
+     * baseline.
+     *
+     * Only the line chart takes this. A line encodes value by POSITION, so moving
+     * the baseline rescales it without misstating it; bars and areas encode by
+     * length and filled area from the baseline, and truncating those makes the
+     * geometry lie about the ratios. Use it to compare two series of similar
+     * magnitude far from zero — not for a single series whose magnitude the
+     * reader is meant to judge.
+     */
+    yDomain?: ChartAxisDomain;
+};
 /**
  * A themed multi-series line chart. Each series' color comes from the semantic
  * `--chart-*` palette (by order, or pinned via `series[].color`), which
@@ -112,8 +138,11 @@ type CartesianChartProps = {
  *   xKey="month"
  *   series={[{ dataKey: 'revenue', name: 'Revenue' }, { dataKey: 'cost' }]}
  * />
+ *
+ * @example Two close-but-high series, on a baseline that shows the gap
+ * <LineChart data={data} xKey="month" series={series} yDomain={[7000, 9000]} />
  */
-declare const LineChart: ({ data, xKey, series, height, width, className, ...chrome }: CartesianChartProps) => react_jsx_runtime.JSX.Element;
+declare const LineChart: ({ data, xKey, series, height, width, className, ...chrome }: LineChartProps) => react_jsx_runtime.JSX.Element;
 
 type BarChartProps = CartesianChartProps & {
     /** Stack the series into a single bar per category. Defaults to grouped. */
@@ -178,4 +207,4 @@ type PieChartProps = {
  */
 declare const PieChart: ({ data, nameKey, dataKey, innerRadius, height, width, className, showLegend, showTooltip, valueFormatter, }: PieChartProps) => react_jsx_runtime.JSX.Element;
 
-export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, type CartesianChartProps, type ChartColorToken, ChartContainer, type ChartContainerProps, type ChartDatum, type ChartDimension, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipProps, LineChart, PieChart, type PieChartProps, chartTokenColor };
+export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, type CartesianChartProps, type ChartAxisBound, type ChartAxisDomain, type ChartColorToken, ChartContainer, type ChartContainerProps, type ChartDatum, type ChartDimension, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipProps, LineChart, type LineChartProps, PieChart, type PieChartProps, chartTokenColor };

package/dist/charts.js

@@ -1,13 +1,7 @@
+import { cn } from './chunk-JP7PNHLH.js';
 import { ResponsiveContainer, Tooltip, LineChart as LineChart$1, Line, BarChart as BarChart$1, Bar, AreaChart as AreaChart$1, Area, PieChart as PieChart$1, Legend, Pie, Cell, CartesianGrid, XAxis, YAxis } from 'recharts';
-import { clsx } from 'clsx';
-import { extendTailwindMerge } from 'tailwind-merge';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
-// src/blocks/Charts/ChartContainer.tsx
-var twMerge = extendTailwindMerge({
-  prefix: "tw"
-});
-var cn = (...classes) => twMerge(clsx(...classes));
 var ChartContainer = ({
   height = 300,
   width = "100%",
@@ -111,13 +105,16 @@ var cartesianChrome = ({
   showYAxis = true,
   showLegend = false,
   showTooltip = true,
-  valueFormatter
+  valueFormatter,
+  yDomain
 }) => /* @__PURE__ */ jsxs(Fragment, { children: [
   showGrid && /* @__PURE__ */ jsx(CartesianGrid, { strokeDasharray: "3 3", vertical: false }),
   /* @__PURE__ */ jsx(XAxis, { dataKey: xKey, ...AXIS_PROPS }),
-  showYAxis && /* @__PURE__ */ jsx(
+  (showYAxis || yDomain !== void 0) && /* @__PURE__ */ jsx(
     YAxis,
     {
+      hide: !showYAxis,
+      domain: yDomain,
       width: 48,
       ...AXIS_PROPS,
       tickFormatter: valueFormatter ? (value) => formatValue(value, valueFormatter) : void 0