Test & Story Coverage Analysis

Play Function Convention: Step DSL

New play functions should use the Storybook step() DSL available via the play context. This provides named, collapsible steps in the Storybook interactions panel and integrates with the test runner.

Current pattern (flat, no steps):

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement);
  await userEvent.click(canvas.getByRole('button'));
  await storyStepDelay();
  await expect(canvas.getByText('Result')).toBeInTheDocument();
};

New pattern (step DSL):

play: async ({ canvasElement, step }) => {
  const canvas = within(canvasElement);

  await step('Click the action button', async () => {
    await userEvent.click(canvas.getByRole('button'));
  });

  await storyStepDelay();

  await step('Verify result appears', async () => {
    await expect(canvas.getByText('Result')).toBeInTheDocument();
  });
};

The storyStepDelay() utility (skips delay under navigator.webdriver) is compatible with the step DSL and should continue to be used between major interaction steps for human observation.

All new play functions in this project must use the step DSL. Existing play functions can be migrated opportunistically but are not required to change.

Current Coverage Summary

What we inherit (well-covered)

Component	Stories	Tests	Play Functions	MDX
Grid cell atoms (8 types)	3-4 variants each	Yes	Yes	No
DataGrid molecule	8+ variants	Yes	Yes	No
EntityDataGrid factory	9 variants	14 unit tests	Yes	No
EntityDataGridShim	9 variants	Yes	No	No
Sidebar organism	4 variants	Yes	Yes (Default)	Yes
AppHeader organism	6 variants	8 tests	No	Yes
ItemGrid organism	8 variants	6 tests	Yes (Empty, WithSearch)	Yes
ItemDetails organism	4 variants	9 tests	No	No
New canary atoms (badge, button, drawer, etc.)	100% pairing	100% pairing	Minimal	No
Sidebar molecules (5 sub-components)	100% pairing	~80% pairing	No	No

Known existing gaps (pre-consolidation)

OverflowToolbar: story exists, no unit test
ItemGridMolecules: story exists, no unit test
AppHeader: no play functions (static composition only)
ItemDetails: no play functions, no MDX docs
Most molecules lack play functions

Location Convention

Each story is assigned a location:

Component — next to the component source (e.g., src/components/canary/organisms/shared/entity-data-grid/)
Use Cases — in src/use-cases/ mapped to a documented product use case
Other — doesn’t fit either category (build verification, developer reference)

Use case references follow the documented taxonomy in documentation/src/content/docs/product/use-cases/.

Gaps Introduced by Consolidation

1. Entity-data-grid new capabilities

These are promoted from item-grid or newly created. None exist at the entity-data-grid level today.

Row-auto-publish lifecycle

Artifact	Description	Priority	Location
Story: `RowAutoPublish`	Show row editing → blur → saving state → success. Demonstrate pending changes accumulating across multiple cells in same row.	High	Component: `entity-data-grid/`
Story: `RowAutoPublishError`	Show row editing → blur → saving → error state. Verify row stays dirty with error visual.	High	Component: `entity-data-grid/`
Story: `SaveAllDrafts`	Show imperative `saveAll()` triggered by a toolbar button, publishing all dirty rows at once.	Medium	Component: `entity-data-grid/`
Story: `DiscardAllDrafts`	Show imperative `discardAll()` restoring original values.	Medium	Component: `entity-data-grid/`
Unit test	Verify: pending changes accumulate per row; `onRowPublish` fires on blur with batched changes; dirty state tracking; save/discard ref API; visual CSS class injection (saving/error).	High	Component: `entity-data-grid/`
Play function	Interact: edit cell → edit another cell in same row → click different row → verify saving callback fired with both changes.	High	Component: `entity-data-grid/`

Client-side pagination

Artifact	Description	Priority	Location
Story: `ClientPagination`	Show `pageSize` config in StaticConfig, AG Grid handling pages internally.	Medium	Component: `entity-data-grid/`
Story: `ServerPagination`	Existing — verify it still works alongside new mode.	Medium	Component: `entity-data-grid/`
Unit test	Verify both modes produce correct grid config; modes are mutually exclusive at design time.	Medium	Component: `entity-data-grid/`

Actions column (ColDef pattern)

Artifact	Description	Priority	Location
Story: `WithActionsColumn`	Show mount-time `actionsColumn` ColDef with 2-3 action buttons, auto-width from `actionCount`.	Medium	Component: `entity-data-grid/`
Unit test	Verify pinned-right column injected; width calculation correct; action callbacks fire.	Medium	Component: `entity-data-grid/`
Play function	Click action button in row, verify callback receives correct row data.	Medium	Component: `entity-data-grid/`

themeQuartz with design-system tokens

Artifact	Description	Priority	Location
Story: `ThemedGrid`	Visual story showing grid with Arda token styling — row heights, fonts, colors, borders.	High (visual)	Component: `molecules/data-grid/`
VRT baseline	Capture baseline after theme migration. Before/after comparison critical.	High	VRT config

Artifact	Description	Priority	Location
Story: `WithToolbar`	Show custom ReactNode toolbar above grid (buttons, dropdowns).	Low	Component: `entity-data-grid/`
Unit test	Verify toolbar renders in correct position.	Low	Component: `entity-data-grid/`

Auto-height mode

Artifact	Description	Priority	Location
Story: `AutoHeight`	Show grid growing to fit 3 rows, then 20 rows.	Low	Component: `entity-data-grid/`
Unit test	Verify `domLayout: 'autoHeight'` passed to AG Grid.	Low	Component: `entity-data-grid/`

Artifact	Description	Priority	Location
Story: `WithSearch`	Show search bar with configurable fields, debounced filtering, count display (“3 of 12 items”).	Medium	Component: `entity-data-grid/`
Story: `WithSearchAndSelection`	Show count switching to “3 of 12 selected” when rows are selected.	Medium	Component: `entity-data-grid/`
Unit test	Verify debounce timing; filter predicate applies to configured fields; count updates.	Medium	Component: `entity-data-grid/`
Play function	Type in search box, verify row count changes after debounce.	Medium	Component: `entity-data-grid/`

Drag-to-scroll

Artifact	Description	Priority	Location
Story: `DragToScroll`	Wide grid demonstrating horizontal drag-scroll. Hard to test visually in static story.	Low	Component: `entity-data-grid/`
Play function	Simulate pointer drag on grid body, verify horizontal scroll position changed.	Low (fragile in CI)	Component: `entity-data-grid/`

2. SelectCellEditor (new canary atom, replaces EnumCellEditor)

Artifact	Description	Priority	Location
Story: `Default`	Fixed list dropdown with checkmark on selected item.	High	Component: `atoms/grid/select/`
Story: `WithManyOptions`	Verify scroll behavior with max-height 240px.	Medium	Component: `atoms/grid/select/`
Story: `KeyboardNavigation`	Document Arrow Up/Down cycling, Enter to select, Escape to cancel.	High	Component: `atoms/grid/select/`
Story: `BothFormats`	Show `SelectOption[]` and `Record<string, string>` both accepted.	Medium	Component: `atoms/grid/select/`
Unit test	Verify: highlight cycling wraps around; Enter selects highlighted; Escape cancels; `isCancelAfterEnd` returns true on Escape; checkmark renders for current value; ARIA listbox/option roles present.	High	Component: `atoms/grid/select/`
Play function	Open editor → Arrow Down 3 times → Enter → verify value changed.	High	Component: `atoms/grid/select/`
VRT baseline	Capture popup appearance (replaces native `<select>`).	Medium	VRT config

3. Primitives layer verification

Artifact	Description	Priority	Location
Integration story: `PrimitivesImportCheck`	One story importing from `@/components/canary/primitives/sheet`, `primitives/tooltip`, etc. and rendering a composed example. Proves import paths resolve.	Medium	Other: `src/components/canary/primitives/primitives.stories.tsx` (build verification, not a component or use case)
No unit tests needed	Primitives are stock shadcn — tested upstream.	—	—

4. Composition stories (page-level)

These are the acceptance test for the consolidation — proving canary components can reproduce dev-witness page layouts. Mapped to documented product use cases where applicable.

Items management page

Artifact	Description	Priority	Location	Use Case Refs
Story: `BrowseItems`	Sidebar + AppHeader + EntityDataGrid (item columns) with search, column toggle, multi-select actions.	High	Use Cases: `use-cases/reference/items/browse-and-search/`	REF::ITM::0001 — Browse and Search Items
Story: `ViewItemDetails`	Click row → ItemDetails drawer opens with fields, card preview tab.	High	Use Cases: `use-cases/reference/items/view-details/`	REF::ITM::0002 — View Item Details
Story: `EditItemInline`	Double-click cell → edit → blur row → auto-publish with visual feedback.	High	Use Cases: `use-cases/reference/items/edit-item/`	REF::ITM::0004 — Edit and Publish Item; GEN::LST::0007 — Edit Entity In Place
Play function	Search items → verify filter; click row → verify drawer; edit cell → blur → verify save.	High	Use Cases: `use-cases/reference/items/browse-and-search/`	—
VRT baseline	Full items page screenshot.	High	VRT config	—

Suppliers management page

Artifact	Description	Priority	Location	Use Case Refs
Story: `BrowseSuppliers`	Sidebar + AppHeader + EntityDataGrid (supplier columns) with server-side search. Demonstrates generic factory works for a different entity.	Medium	Use Cases: `use-cases/reference/business-affiliates/browse-and-search/` (canary variant alongside existing extras stories)	REF::BA::0001 — Browse and Search Business Affiliates
Story: `ViewSupplierDetails`	Click row → detail panel with Details/Roles/Items tabs.	Medium	Use Cases: `use-cases/reference/business-affiliates/view-details/` (canary variant)	REF::BA::0002 — View Business Affiliate Details
Play function	Basic: verify grid renders with supplier columns; click row → verify callback.	Medium	Use Cases: `use-cases/reference/business-affiliates/browse-and-search/`	—

List view general behaviors

Artifact	Description	Priority	Location	Use Case Refs
Story: `ColumnConfiguration`	Toggle column visibility, reorder, resize, pin.	Medium	Use Cases: `use-cases/general-behaviors/list-views/`	GEN::LST::0002 — Configure List Column Display
Story: `SortAndFilter`	Single/multi-column sort, global + per-column filter.	Medium	Use Cases: `use-cases/general-behaviors/list-views/`	GEN::LST::0003, GEN::LST::0004 — Filter/Sort Entity List
Story: `RowSelection`	Single, multi, shift-click range, select-all, selection-driven toolbar actions.	Medium	Use Cases: `use-cases/general-behaviors/list-views/`	GEN::LST::0006 — Select Rows and Trigger Actions

EntityDataGrid kitchen sink

Artifact	Description	Priority	Location
Story: `KitchenSink`	One story exercising all promoted capabilities: auto-publish + search + toolbar + actions + drag-to-scroll + pagination (client-side).	High	Component: `entity-data-grid/` (developer reference co-located with the organism)
Purpose	Developer reference: “here’s everything the grid can do.”	—	—

5. VRT coverage

Trigger	What to capture	Priority	Expected Variances	Location
DataGrid theme change (`legacy` → `themeQuartz`)	Before/after grid appearance — row heights, fonts, colors, borders. This is the highest-risk visual change.	Critical	All grid stories will diff. Row height changes (default → 48px), header height (default → 36px), font changes (system → Geist Sans 14px), cell padding (default → 12px), border styling, color mapping from blue-slate to Arda orange tokens. Baselines must be regenerated — old baselines are invalid.	VRT project config
Row visual states	`.ag-row-saving` (primary background), `.ag-row-error` (destructive background) — new CSS classes.	High	New baselines only — no prior state to compare against. Saving rows should show light orange tint; error rows should show light red tint.	VRT project config
SelectCellEditor popup	New custom dropdown replacing native `<select>`.	Medium	New baselines only — replaces native browser dropdown (which VRT never captured because native dropdowns are OS-rendered). Custom popup should show styled list with checkmark indicator, highlight state, and design-system tokens.	VRT project config
New atoms (badge, button, drawer, etc.)	Baseline snapshots for all new components entering the library.	Medium	New baselines only — no prior state. These are the first VRT captures for components coming from the callil branch. Any future consolidation changes will diff against these baselines.	VRT project config
Composition pages	Full-page screenshots for items page and suppliers page.	High	New baselines only. However, these pages should be visually compared against `dev-witness` equivalents manually during review — automated diff is not possible since the component trees are different (canary vs vendored), but the visual output should be recognizably similar.	VRT project config

Recommended Phasing

Stories and tests should be added alongside the implementation, not as a separate phase. Each consolidation step produces its own verifiable artifacts:

Phase 1: Foundation (primitives, atoms, styles)

Run existing tests — verify nothing broke by file moves
Add PrimitivesImportCheck integration story (Other)
Generate VRT baselines for new atoms
Add SelectCellEditor stories + tests + play functions (Component)

Phase 2: DataGrid molecule retrofit (theme change)

Add ThemedGrid story (Component: data-grid molecule)
Generate VRT before/after for theme change — critical gate
Run existing DataGrid tests — verify no regressions

Phase 3: Entity-data-grid capability promotion

For each capability promoted (in order of risk), stories go Component-local:

Row-auto-publish (highest risk, most complex)
- Add RowAutoPublish, RowAutoPublishError, SaveAllDrafts, DiscardAllDrafts stories
- Add unit tests for pending changes, publish lifecycle, ref API
- Add play functions for edit-blur-save flow
- Generate VRT for row visual states
Actions column → story + test + play function
Search/filter → story + test + play function
Pagination modes → story + test
Toolbar slot → story + test
Auto-height → story + test
Drag-to-scroll → story (play function optional, fragile in CI)

Phase 4: Composition stories (acceptance)

Stories go in Use Cases, mapped to product use case documentation:

Add items browse/view/edit stories (Use Cases: reference/items/)
- REF::ITM::0001, REF::ITM::0002, REF::ITM::0004
Add suppliers browse/view stories (Use Cases: reference/business-affiliates/, canary variant)
- REF::BA::0001, REF::BA::0002
Add list view general behavior stories (Use Cases: general-behaviors/list-views/)
- GEN::LST::0002, GEN::LST::0003, GEN::LST::0004, GEN::LST::0006
Add KitchenSink developer reference (Component: entity-data-grid)
Generate VRT baselines for all composition pages

Phase 5: canary-refactor adaptation (follow-on)

Per canary-refactor.md decision — adapt existing canary-refactor stories to use consolidated components. Divergences found here drive fixes back into the component library.

Coverage Metrics Target

Metric	Target
Every new/modified component has a story file	100%
Every new/modified component has a unit test file	100%
Organisms have at least one play function	100%
Organisms have MDX documentation	100%
VRT baselines for all visual changes	100%
Composition stories covering `dev-witness` equivalence	2-3 pages