@keboola/design 2.0.1 → 2.1.0

package/README.md

@@ -72,7 +72,63 @@ 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.storybook.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
 

package/dist/icon-names.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Reads available FontAwesome solid icon names from the FA kit.
+ * Returns deduplicated, sorted kebab-case icon names (e.g. "chart-bar", "circle-check").
+ */
+declare const getAvailableIconNames: () => string[];
+
+export { getAvailableIconNames };

package/dist/icon-names.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads available FontAwesome solid icon names from the FA kit.
+ * Returns deduplicated, sorted kebab-case icon names (e.g. "chart-bar", "circle-check").
+ */
+declare const getAvailableIconNames: () => string[];
+
+export { getAvailableIconNames };

package/dist/icons.cjs

@@ -198,6 +198,10 @@ Object.defineProperty(exports, "CircleChevronUp", {
   enumerable: true,
   get: function () { return lucideReact.CircleChevronUp; }
 });
+Object.defineProperty(exports, "CircleDot", {
+  enumerable: true,
+  get: function () { return lucideReact.CircleDot; }
+});
 Object.defineProperty(exports, "CircleHelp", {
   enumerable: true,
   get: function () { return lucideReact.CircleHelp; }

package/dist/icons.d.cts

@@ -0,0 +1,6 @@
+import { LucideIcon } from 'lucide-react';
+export { AlertCircle, AlertTriangle, AlignCenter, AlignJustify, AlignLeft, AlignRight, ArrowBigUpDash, ArrowDown, ArrowDownToLine, ArrowLeft, ArrowLeftRight, ArrowLeftToLine, ArrowRight, ArrowRightLeft, ArrowUp, ArrowUpAZ, ArrowUpRight, Ban, Bell, BellRing, Bold, BookOpen, Box, Braces, Bug, Calendar, Camera, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, CircleAlert, CircleArrowDown, CircleArrowRight, CircleArrowUp, CircleCheck, CircleChevronDown, CircleChevronUp, CircleDot, CircleHelp, CirclePause, CirclePlay, CirclePlus, CircleUser, CircleX, Clock, CloudDownload, Code, Cog, Columns2, Columns3, Copy, CreditCard, Crosshair, Database, Diamond, Download, Ellipsis, EllipsisVertical, Expand, ExternalLink, Eye, EyeOff, File, FileDown, FileInput, FileSpreadsheet, FileText, Flag, Folder, FolderOpen, FolderTree, FolderUp, Gauge, Gift, GitBranch, GitCompare, GitMerge, GitPullRequest, Globe, GripVertical, Heading1, Heading2, Heading3, History, Hourglass, Image, Info, Italic, KanbanSquare, Key, Keyboard, Layers, LayoutGrid, LineChart, Link, List, ListChecks, ListFilter, ListOrdered, Loader2, Lock, LogIn, LucideIcon, LucideProps, Mail, Map, Maximize, Maximize2, Menu, MessageCircleQuestion, Minimize, Minimize2, Minus, Moon, MoveHorizontal, MoveVertical, OctagonAlert, PanelBottomClose, PanelBottomOpen, PanelLeft, PanelLeftClose, PanelLeftOpen, PartyPopper, Pause, Pencil, PencilLine, Pipette, Play, Plus, Quote, RefreshCw, Repeat, Repeat2, Reply, Rocket, RotateCcw, RotateCw, Rows3, ScanLine, Search, Send, Settings, Share, Share2, Slash, Sliders, SlidersHorizontal, Sparkle, Sparkles, Split, Square, SquareChevronRight, SquareCode, SquareKanban, SquarePen, SquareTerminal, Star, StickyNote, Strikethrough, Table, TableProperties, ThumbsDown, ThumbsUp, ToggleRight, Trash2, TriangleAlert, Type, Underline, Unlink, Upload, User, Users, Wand2, Warehouse, Webhook, Workflow, Wrench, X, XCircle, Zap } from 'lucide-react';
+
+declare const Keboola: LucideIcon;
+
+export { Keboola };

package/dist/icons.d.ts

@@ -0,0 +1,6 @@
+import { LucideIcon } from 'lucide-react';
+export { AlertCircle, AlertTriangle, AlignCenter, AlignJustify, AlignLeft, AlignRight, ArrowBigUpDash, ArrowDown, ArrowDownToLine, ArrowLeft, ArrowLeftRight, ArrowLeftToLine, ArrowRight, ArrowRightLeft, ArrowUp, ArrowUpAZ, ArrowUpRight, Ban, Bell, BellRing, Bold, BookOpen, Box, Braces, Bug, Calendar, Camera, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, CircleAlert, CircleArrowDown, CircleArrowRight, CircleArrowUp, CircleCheck, CircleChevronDown, CircleChevronUp, CircleDot, CircleHelp, CirclePause, CirclePlay, CirclePlus, CircleUser, CircleX, Clock, CloudDownload, Code, Cog, Columns2, Columns3, Copy, CreditCard, Crosshair, Database, Diamond, Download, Ellipsis, EllipsisVertical, Expand, ExternalLink, Eye, EyeOff, File, FileDown, FileInput, FileSpreadsheet, FileText, Flag, Folder, FolderOpen, FolderTree, FolderUp, Gauge, Gift, GitBranch, GitCompare, GitMerge, GitPullRequest, Globe, GripVertical, Heading1, Heading2, Heading3, History, Hourglass, Image, Info, Italic, KanbanSquare, Key, Keyboard, Layers, LayoutGrid, LineChart, Link, List, ListChecks, ListFilter, ListOrdered, Loader2, Lock, LogIn, LucideIcon, LucideProps, Mail, Map, Maximize, Maximize2, Menu, MessageCircleQuestion, Minimize, Minimize2, Minus, Moon, MoveHorizontal, MoveVertical, OctagonAlert, PanelBottomClose, PanelBottomOpen, PanelLeft, PanelLeftClose, PanelLeftOpen, PartyPopper, Pause, Pencil, PencilLine, Pipette, Play, Plus, Quote, RefreshCw, Repeat, Repeat2, Reply, Rocket, RotateCcw, RotateCw, Rows3, ScanLine, Search, Send, Settings, Share, Share2, Slash, Sliders, SlidersHorizontal, Sparkle, Sparkles, Split, Square, SquareChevronRight, SquareCode, SquareKanban, SquarePen, SquareTerminal, Star, StickyNote, Strikethrough, Table, TableProperties, ThumbsDown, ThumbsUp, ToggleRight, Trash2, TriangleAlert, Type, Underline, Unlink, Upload, User, Users, Wand2, Warehouse, Webhook, Workflow, Wrench, X, XCircle, Zap } from 'lucide-react';
+
+declare const Keboola: LucideIcon;
+
+export { Keboola };

package/dist/icons.js

@@ -1,4 +1,4 @@
-export { AlertCircle, AlertTriangle, AlignCenter, AlignJustify, AlignLeft, AlignRight, ArrowBigUpDash, ArrowDown, ArrowDownToLine, ArrowLeft, ArrowLeftRight, ArrowLeftToLine, ArrowRight, ArrowRightLeft, ArrowUp, ArrowUpAZ, ArrowUpRight, Ban, Bell, BellRing, Bold, BookOpen, Box, Braces, Bug, Calendar, Camera, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, CircleAlert, CircleArrowDown, CircleArrowRight, CircleArrowUp, CircleCheck, CircleChevronDown, CircleChevronUp, CircleHelp, CirclePause, CirclePlay, CirclePlus, CircleUser, CircleX, Clock, CloudDownload, Code, Cog, Columns2, Columns3, Copy, CreditCard, Crosshair, Database, Diamond, Download, Ellipsis, EllipsisVertical, Expand, ExternalLink, Eye, EyeOff, File, FileDown, FileInput, FileSpreadsheet, FileText, Flag, Folder, FolderOpen, FolderTree, FolderUp, Gauge, Gift, GitBranch, GitCompare, GitMerge, GitPullRequest, Globe, GripVertical, Heading1, Heading2, Heading3, History, Hourglass, Image, Info, Italic, KanbanSquare, Key, Keyboard, Layers, LayoutGrid, LineChart, Link, List, ListChecks, ListFilter, ListOrdered, Loader2, Lock, LogIn, Mail, Map, Maximize, Maximize2, Menu, MessageCircleQuestion, Minimize, Minimize2, Minus, Moon, MoveHorizontal, MoveVertical, OctagonAlert, PanelBottomClose, PanelBottomOpen, PanelLeft, PanelLeftClose, PanelLeftOpen, PartyPopper, Pause, Pencil, PencilLine, Pipette, Play, Plus, Quote, RefreshCw, Repeat, Repeat2, Reply, Rocket, RotateCcw, RotateCw, Rows3, ScanLine, Search, Send, Settings, Share, Share2, Slash, Sliders, SlidersHorizontal, Sparkle, Sparkles, Split, Square, SquareChevronRight, SquareCode, SquareKanban, SquarePen, SquareTerminal, Star, StickyNote, Strikethrough, Table, TableProperties, ThumbsDown, ThumbsUp, ToggleRight, Trash2, TriangleAlert, Type, Underline, Unlink, Upload, User, Users, Wand2, Warehouse, Webhook, Workflow, Wrench, X, XCircle, Zap } from 'lucide-react';
+export { AlertCircle, AlertTriangle, AlignCenter, AlignJustify, AlignLeft, AlignRight, ArrowBigUpDash, ArrowDown, ArrowDownToLine, ArrowLeft, ArrowLeftRight, ArrowLeftToLine, ArrowRight, ArrowRightLeft, ArrowUp, ArrowUpAZ, ArrowUpRight, Ban, Bell, BellRing, Bold, BookOpen, Box, Braces, Bug, Calendar, Camera, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, CircleAlert, CircleArrowDown, CircleArrowRight, CircleArrowUp, CircleCheck, CircleChevronDown, CircleChevronUp, CircleDot, CircleHelp, CirclePause, CirclePlay, CirclePlus, CircleUser, CircleX, Clock, CloudDownload, Code, Cog, Columns2, Columns3, Copy, CreditCard, Crosshair, Database, Diamond, Download, Ellipsis, EllipsisVertical, Expand, ExternalLink, Eye, EyeOff, File, FileDown, FileInput, FileSpreadsheet, FileText, Flag, Folder, FolderOpen, FolderTree, FolderUp, Gauge, Gift, GitBranch, GitCompare, GitMerge, GitPullRequest, Globe, GripVertical, Heading1, Heading2, Heading3, History, Hourglass, Image, Info, Italic, KanbanSquare, Key, Keyboard, Layers, LayoutGrid, LineChart, Link, List, ListChecks, ListFilter, ListOrdered, Loader2, Lock, LogIn, Mail, Map, Maximize, Maximize2, Menu, MessageCircleQuestion, Minimize, Minimize2, Minus, Moon, MoveHorizontal, MoveVertical, OctagonAlert, PanelBottomClose, PanelBottomOpen, PanelLeft, PanelLeftClose, PanelLeftOpen, PartyPopper, Pause, Pencil, PencilLine, Pipette, Play, Plus, Quote, RefreshCw, Repeat, Repeat2, Reply, Rocket, RotateCcw, RotateCw, Rows3, ScanLine, Search, Send, Settings, Share, Share2, Slash, Sliders, SlidersHorizontal, Sparkle, Sparkles, Split, Square, SquareChevronRight, SquareCode, SquareKanban, SquarePen, SquareTerminal, Star, StickyNote, Strikethrough, Table, TableProperties, ThumbsDown, ThumbsUp, ToggleRight, Trash2, TriangleAlert, Type, Underline, Unlink, Upload, User, Users, Wand2, Warehouse, Webhook, Workflow, Wrench, X, XCircle, Zap } from 'lucide-react';
 import { forwardRef } from 'react';
 import { jsxs, jsx } from 'react/jsx-runtime';