@keboola/design 2.0.1 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @keboola/design
 
-The Keboola design system — shadcn-aligned, Radix-underneath, FontAwesome icons.
+The Keboola design system — shadcn-aligned, Radix-underneath, Lucide icons.
 
 [![npm version](https://img.shields.io/npm/v/@keboola/design.svg)](https://www.npmjs.com/package/@keboola/design)
 [![Storybook](https://img.shields.io/badge/Storybook-live-FF4785)](https://design-hh9143njj-keboola.vercel.app)
@@ -10,6 +10,7 @@ The Keboola design system — shadcn-aligned, Radix-underneath, FontAwesome icon
 <!-- TODO (UT-3991 follow-up, Wave D-2): replace with canonical production URL once design Storybook hosting is confirmed -->
 
 📖 **Decision tree:** [`AGENTS.md`](./AGENTS.md) — which component to use when.
+🎨 **Tokens:** [`DESIGN.md`](./DESIGN.md) — canonical token surface in [google-labs-code/design.md](https://github.com/google-labs-code/design.md) format; validated by `yarn lint --filter=@keboola/design`.
 🎨 **Branding:** [`../../docs/branding.md`](../../docs/branding.md) (lands with PR #5674).
 
 ## Install
@@ -64,7 +65,7 @@ This is the cheap, low-flakiness base layer for testing stories. Screenshot/visu
 
 **How it's wired:**
 
-- `vitest.storybook.config.ts` — a separate Vitest config (browser mode, Playwright Chromium provider) so `yarn test` stays jsdom-only and browser-free; story tests are opt-in via `test:stories`.
+- `vitest.config.ts` — a separate Vitest config (browser mode, Playwright Chromium provider) so `yarn test` stays jsdom-only and browser-free; story tests are opt-in via `test:stories`. It is named `vitest.config.ts` (not `vitest.storybook.config.ts`) so the Storybook "Run tests" button (`@storybook/addon-vitest`) can discover it — the addon only scans `vitest.workspace.*` / `vitest.config.*` / `vite.config.*` names; under any other name it falls back to `vite.config.ts` and crashes the dev server (UT-4243). The jsdom `test` script therefore pins `--config vite.config.ts` explicitly.
 - `.storybook/vitest.setup.ts` — applies the Storybook `preview` annotations (decorators, globals) so tests render exactly like Storybook.
 - `optimizeDeps.entries` crawls every story up front so Vite optimizes all story dependencies in one pass — without it, a heavy dep (mermaid, codemirror, …) discovered mid-run makes Vite re-optimize and 404 in-flight imports.
 
@@ -72,10 +73,68 @@ This is the cheap, low-flakiness base layer for testing stories. Screenshot/visu
 
 **Adding coverage:** nothing to do — every CSF `*.stories.tsx` is picked up automatically. Add a `play()` to a story to turn it into an interaction test. (MDX docs pages — `src/**/*.mdx` — are not executed as tests; the addon only runs CSF stories.)
 
-**Runs locally only for now.** There's no CI workflow yet — in CI (2-core runner) browser mode costs ~35 s per story file, so the suite needs a CI-viability pass (browser `isolate: false`, cached Vite deps, sharding, or nightly) before it's wired in. Tracked in UT-4191. Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
+#### Writing `play()` interaction tests
+
+Any story with real user-driven behaviour (click, type, open/close, select, focus) should carry a `play()`. Purely presentational stories (Alert, Badge, Skeleton, layout, …) should not — there is nothing to drive.
+
+**Import everything test-related from `storybook/test`** — Storybook 10 re-exports Testing Library, `userEvent`, and a Vitest-flavoured `expect` from this single entry point (the old `@storybook/test` / `@storybook/testing-library` paths are gone):
+
+```tsx
+import { expect, fn, screen, userEvent, within } from 'storybook/test';
+```
+
+A `play()` follows **render → act → assert**:
+
+```tsx
+export const ClickInvokesHandler: Story = {
+  args: { onClick: fn(), children: 'Button' },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement); // scope queries to this story's DOM
+    await userEvent.click(canvas.getByRole('button', { name: 'Button' }));
+    await expect(args.onClick).toHaveBeenCalledTimes(1);
+  },
+};
+```
+
+Rules of the road:
+
+- **Scope with `within(canvasElement)`.** Query the story's own DOM through `canvasElement`, not `document` — except for content that **portals out** of it.
+- **Portalled overlays use `screen`.** Modal/Sheet dialogs, Combobox/Select listboxes, Popover, and DropdownMenu render into `document.body`. Query them with `screen.findByRole('dialog')` / `getByRole('option')`, not the canvas.
+- **Drive with `userEvent`, query by role.** Prefer `getByRole`/`findByRole` (`button`, `dialog`, `option`, `combobox`, …) over CSS selectors — it asserts accessibility for free.
+- **Wait with `findBy*` / `waitFor`, never fixed waits.** The `expect` from `storybook/test` is Vitest-flavoured — it asserts the **current** state synchronously and does **not** poll, so `expect(el).toBeVisible()` is only safe once the element has settled. For anything asynchronous, do the waiting first: `findBy*` for elements that appear, `waitFor(() => expect(...))` for state that updates in place (focus, removal, debounced text). There is no `waitForTimeout`.
+- **Spy on handlers with `fn()`** and assert `toHaveBeenCalled…` rather than relying on side effects you cannot see.
+- **Add a dedicated story for an interaction** (with the args/handlers it needs) rather than bolting a `play()` onto an existing presentational story.
+
+Worked examples: `src/components/Button/Button.stories.tsx` (click + disabled), `src/components/Combobox/Combobox.stories.tsx` (open → filter → select), `src/components/Modal/Modal.stories.tsx` (open → focus → close).
+
+**Coverage so far:** the interactive surface is covered — Button, ButtonInline, Combobox, MultiCombobox, CreatableMultiCombobox, Select, Modal, Sheet, Popover, Popconfirm, DropdownMenu, SplitButton, Tooltip, HoverCard, InfoTooltip, Switch, Checkbox, RadioGroup, Slider, Tabs, PageHeaderTabs, Collapsible, PanelWithDetails, Toast, TextInput, NumberInput, SearchInput, SearchInputWithNavigation, PasswordInput, Textarea, AutoSaveTextarea, AlertWithAction, ListDetail, FilterToolbar, ConfirmDialog. Add a `play()` to new interactive stories by default.
+
+**Known gaps (not yet driven headlessly):** `Command` (cmdk input value isn't reflected on the DOM node under the test runner), `CollapsiblePanel` (collapses via CSS height, so `toBeVisible()` can't see the state change), `Calendar`/`DateInput`/`TimeInput` (day/segment targeting is brittle), `ColorInput`, `Clipboard`/`ClipboardButton` (clipboard API), and `MultiActionButton`/`Tagger` (stories use `alert()` / `onClick` side effects that block a headless run). `ModalForm` currently throws `formContext only works within a formComponent` when its modal opens (`FormBody` is outside `form.AppForm`) — a story-wiring fix, tracked separately. `Search` is deprecated and intentionally untested.
+
+**Timing-sensitive:** `HoverCard` is the only test driven by a real `userEvent.hover` past a 200 ms open delay (its `findByText` carries a raised timeout). It passes headlessly today, but it's the most likely flake if CI is slow — `Tooltip` deliberately opens via keyboard focus to avoid this. Watch it when wiring CI.
+
+**Runs in CI per-PR (non-blocking).** The `.github/workflows/storybook-component-tests.yml` workflow runs the full suite, wired into `branch.yml` (the `story-tests` job) and gated on the same `detect-affected` design signal as the Storybook deploy — so it only runs when this package (or something it depends on) changes. It is non-blocking: a red run surfaces in the PR Checks tab but doesn't gate the merge. Browser mode isolates per file by default (~35 s/file on a 2-core runner, ~60 min for all 104), so `vitest.config.ts` sets `isolate: false` + `fileParallelism: false` + `maxWorkers: 1` to reuse one browser context across files, and the workflow caches Vite's optimized deps to skip the ~27 s dep pre-bundling on warm runs — bringing the run down to a few minutes. If the suite ever exceeds ~5-6 min, the documented fallback is sharding across a job matrix (and/or full-suite nightly + changed-stories-only on PR). Tracked in UT-4191. Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
+
+#### Story-test coverage (UT-4189)
+
+Coverage is **measured, not gated** — it gives a baseline for the story suite. The default `test:stories` run stays coverage-free and fast; coverage only loads when you opt in:
+
+```bash
+yarn workspace @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`.
+
+**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 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()` (e.g. `Tagger`). 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.
 
 ### Icons
 
-All icons should use the `Icon` component, which is a wrapper around `FontAwesomeIcon`. Browse the available icons in the Storybook `Icons` page.
+Import icons directly from `@keboola/design/icons` — a wildcard re-export of [lucide-react](https://lucide.dev) plus Keboola-custom inline-SVG icons. See `AGENTS.md` for the full mapping and conventions.
 
-When using custom icons (prefix `fak`), pass the icon as a tuple: `<Icon icon={['fak', 'custom-icon']} />`.
+```tsx
+import { ChevronDown, Keboola } from '@keboola/design/icons';
+```