@keboola/design 11.0.1 → 11.3.0

package/AGENTS.md

@@ -20,18 +20,20 @@ Working **on** the package (commands, layer boundary, token surface, the FA→Lu
 
 The root barrel (`@keboola/design`) is **not** the whole package. These live only at their subpath — an agent scanning the barrel (or `dist/index.d.ts`) misses them and wrongly concludes the capability is absent. The "always import from the package root" rule above holds for everything in the barrel; the rows below are the **deliberate exceptions** — import them from the subpath, not the root.
 
-| Subpath                           | Exports                                                            | Reach for it when                                                |
-| --------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
-| `@keboola/design`                 | Components, blocks, hooks, `ThemeProvider`, forms                  | Default — everything below the listed exceptions                 |
-| `@keboola/design/icons`           | Lucide re-export + Keboola-custom SVG icons                        | Any icon (`import { ChevronDown } from '@keboola/design/icons'`) |
-| `@keboola/design/editors`         | `CodeEditor`, `SqlEditor`, `MergeEditor`                           | Real code editing — pulls the ~1.3 MB CodeMirror bundle          |
-| `@keboola/design/charts`          | `LineChart`, `BarChart`, `AreaChart`, `PieChart`, `ChartContainer` | Data-viz — themed recharts wrappers; **not** in the root barrel  |
-| `@keboola/design/mermaid`         | `MermaidDiagram` (`{ code }`)                                      | Render a Mermaid diagram — **not** in the root barrel            |
-| `@keboola/design/markdown-editor` | `MarkdownEditor`                                                   | Markdown editing — **not** in the root barrel                    |
-| `@keboola/design/rjsf`            | `RjsfSchemaEditor`, `useRootFormData`                              | JSON-Schema-driven config forms (RJSF) — pulls `@rjsf/*` + ajv   |
-| `@keboola/design/testing`         | `renderWithTheme`                                                  | Unit tests that need a component wrapped in `ThemeProvider`      |
-| `@keboola/design/styles`          | Tailwind-extending stylesheet                                      | App entry, Tailwind consumers (**default**)                      |
-| `@keboola/design/styles/compiled` | Pre-compiled CSS (~176 KB)                                         | App entry, when you cannot run Tailwind                          |
+| Subpath                           | Exports                                                            | Reach for it when                                                         |
+| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| `@keboola/design`                 | Components, blocks, hooks, `ThemeProvider`, forms                  | Default — everything below the listed exceptions                          |
+| `@keboola/design/icons`           | Lucide re-export + Keboola-custom SVG icons                        | Any icon (`import { ChevronDown } from '@keboola/design/icons'`)          |
+| `@keboola/design/editors`         | `CodeEditor`, `SqlEditor`, `MergeEditor`                           | Real code editing — pulls the ~1.3 MB CodeMirror bundle                   |
+| `@keboola/design/charts`          | `LineChart`, `BarChart`, `AreaChart`, `PieChart`, `ChartContainer` | Data-viz — themed recharts wrappers; **not** in the root barrel           |
+| `@keboola/design/mermaid`         | `MermaidDiagram` (`{ code }`)                                      | Render a Mermaid diagram — **not** in the root barrel                     |
+| `@keboola/design/flint`           | `FlintChart` (`{ code }`)                                          | Render a Flint chart (JSON spec, Vega-Lite) — **not** in the root barrel  |
+| `@keboola/design/vega`            | `vegaTheme(scheme)`, `useVegaTheme()`                              | Brand + scheme aware Vega-Lite `Config` for any chart you render yourself |
+| `@keboola/design/markdown-editor` | `MarkdownEditor`                                                   | Markdown editing — **not** in the root barrel                             |
+| `@keboola/design/rjsf`            | `RjsfSchemaEditor`, `useRootFormData`                              | JSON-Schema-driven config forms (RJSF) — pulls `@rjsf/*` + ajv            |
+| `@keboola/design/testing`         | `renderWithTheme`                                                  | Unit tests that need a component wrapped in `ThemeProvider`               |
+| `@keboola/design/styles`          | Tailwind-extending stylesheet                                      | App entry, Tailwind consumers (**default**)                               |
+| `@keboola/design/styles/compiled` | Pre-compiled CSS (~176 KB)                                         | App entry, when you cannot run Tailwind                                   |
 
 ### design ≠ shadcn — API deltas
 
@@ -156,6 +158,15 @@ Charts ship from the **`@keboola/design/charts`** subpath (recharts under the ho
 
 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.)
 
+**Rendering a Vega-Lite spec yourself?** Take the config from **`@keboola/design/vega`** instead of hand-writing colours — `useVegaTheme()` in a component, `vegaTheme(scheme)` outside one. It carries the transparent background, the semantic axis/legend/title chrome, and `range.category` = `--chart-1..5` in series order, so a spec from anywhere lands on the same palette as the recharts wrappers and follows the active scheme and brand. Pass it as the compile/render `config`; a range set on the spec's own scale still wins.
+
+```tsx
+const config = useVegaTheme();
+const { spec } = compile(vegaLiteSpec, { config });
+```
+
+The config holds resolved `rgb(…)` strings, not `var()` references — vega does its colour maths in JS and never consults the stylesheet. So a chart rendered once must be re-rendered when the config identity changes; `useVegaTheme` gives you a new one on every scheme or brand switch.
+
 ### 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.
@@ -176,7 +187,7 @@ Vertical rhythm: prefer `tw:gap-*` on a flex column parent over `tw:mt-*` on chi
 
 **`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.
+**Page gutter: `AppShell.Main` owns it, on a wrapper inside its scroll container.** `AppShell.Main` applies a default page gutter (`tw:p-6`) so content looks right out of the box. Override it from the call site through **`contentClassName`** — e.g. `contentClassName="tw:p-0"` (kbc-ui does this; it centralizes the gutter on its own shell wrapper). **Never put a `p-*` in `className`**: that lands on the scroll container, and sticky insets resolve against the nearest scrollport's _padding box_, so it parks every `position: sticky` descendant — `Table.Header` included — one gutter below the visible top edge, with scrolled content showing through the strip above. `className` is still the right place for the scroll behaviour itself (`tw:overflow-visible`). `PageLayout` adds **no** gutter of its own, so header and content align inside whatever gutter `AppShell.Main` provides.
 
 ```tsx
 // Default gutter — nothing to add:
@@ -185,7 +196,7 @@ 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">
+<AppShell.Main contentClassName="tw:p-0">
   <div className="tw:px-8 tw:py-6">{/* custom gutter */}</div>
 </AppShell.Main>
 ```
@@ -458,7 +469,7 @@ A host that tracks the request itself rather than returning a promise passes `is
 
 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`:
+**Creatable combobox** — `Combobox` with `allowCreate` accepts values not in `items`. Add `canCreate` when the free-form value has a format: it gates the create row on the typed query, so an unparseable one shows the `empty` state instead of an "Add …" row the app would have to reject afterwards.
 
 ```tsx
 <Combobox
@@ -467,10 +478,25 @@ Both router wirings (TanStack Router, and a custom named router) are in [`RECIPE
   onValueChange={setTag}
   allowCreate
   allowClear
+  canCreate={(query) => /^[a-z0-9-]+$/.test(query)}
   placeholder="Pick or create a tag"
 />
 ```
 
+**Adder combobox** — a picker that hands each selection to something else (a list, an API) rather than holding it. Pin `value` to `null`: the input clears after every pick, ready for the next one, and the chosen items live in whatever you render below.
+
+```tsx
+<Combobox
+  items={colleagues}
+  value={null}
+  onValueChange={(email) => email && addRecipient(email)}
+  allowCreate
+  canCreate={isEmailValid}
+  empty="Enter a valid email address"
+  placeholder="Choose a colleague or enter an email address"
+/>
+```
+
 **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