feat(analytics dashboard): expose committed render lifecycle

[zygisS22]

Summary

Add two generic host contracts to F0AnalyticsDashboard:

• consumer-owned neutral widget-header badges, rendered as accessible native buttons only when actionable;
• committed metric/chart render lifecycle events scoped by an opaque consumer renderCycleKey.

F0 contains no last-view, comparison, analytics-domain, or persistence logic. Collections deliberately emit no lifecycle events in this slice, so consumers that require a full render receipt fail closed.

Contract

onItemRenderStateChange emits { itemId, renderCycleKey, state } only after loading, ready, or error UI commits. A changing cycle key refreshes item data, and stale asynchronous responses cannot emit ready/error for a newer cycle. Grid and fullscreen mounts are mutually exclusive and covered by regression tests.

itemBadge returns compact label/accessibility metadata. F0 owns neutral styling and keyboard behavior; the host owns meaning and click behavior. No health or positive/negative semantics are inferred.

Validation

• 202 focused F0AnalyticsDashboard tests
• TypeScript, oxlint/lint, format and pre-commit checks
• package build completed
• Storybook starts; stories and MDX cover lifecycle, badge, fullscreen, stale-response, and unsupported collection behavior
• manual code/accessibility review completed

The installed Storybook test runner currently exits on its own Vite migration notice and does not honor the documented path filter, so the full runner is the remaining local validation limitation.

Rollout / compatibility

This is additive and has no feature flag. Factorial must consume a released F0 package version before enabling its saved-dashboard comparison UI.

Consumer draft: Factorial #111763.

[github-actions]

🔍 Review policy: Feature

The PR title starts with feat, so this is a feature: it needs one approval from f0-devs AND one from f0-designers (rule 3).

Required approvals

Team	Why	Status
@factorialco/f0-devs	Features need a dev approval	⏳ pending
@factorialco/f0-designers	Features need a design approval	⏳ pending

How this was decided

• PRs touching only sds/ modules require their owners and nothing else.
• Otherwise, docs-only changes (*.md, *.mdx, *.stories.tsx, anything in __stories__/) → one f0-general approval.
• Otherwise, feat: titles → one f0-devs and one f0-designers approval. Not a feature? Fix the title prefix.
• Anything else → one f0-devs approval.
• Add the needs-design-review label to also request a design approval on any PR.
• Creating a new sds/ module (new package.yml) additionally requires an f0-general approval.

Policy source: ownership/review-policy.ts · Team members: ownership/teams.yml

[github-actions]

✅ No untranslated copy added

Every user-visible string in this PR comes from the i18n layer. Codebase total unchanged at 133.

[github-actions]

✅ Storybook docs — no pages lost

Every page reachable on main is still reachable here.

✏️ 5 updated

✏️ Updated — 5 page(s)/story/stories across 2 file(s)

The source file behind each of these changed. Detection is per file, so editing one story flags its siblings too.

• src/patterns/F0AnalyticsDashboard/__stories__/index.mdx
  • Patterns/AnalyticsDashboard
• src/patterns/F0AnalyticsDashboard/__stories__/index.stories.tsx
  • Patterns/AnalyticsDashboard › Item Filters Applied
  • Patterns/AnalyticsDashboard › Metric Height Variants
  • Patterns/AnalyticsDashboard › Mixed Dashboard
  • Patterns/AnalyticsDashboard › With Item Filters

🔇 Added but not in the sidebar — 1

Expected for snapshot-only and internal stories (no-sidebar / !dev). Listed in case one was meant to be visible.

• Patterns/AnalyticsDashboard › Badge And Render Lifecycle — experimental

Links point at this PR's Storybook build — browse the full Storybook.

Snapshot of the Storybook index (docs pages + stories) compared against main. Non-blocking.

[github-actions]

🔍 Visual review for your branch is published 🔍

Here are the links to:

• the Visual Review Page

• the latest build on chromatic

• the full storybook

[github-actions]

📦 Alpha Package Version Published

Use pnpm i github:factorialco/f0#npm/alpha-pr-5286 to install the package

Use pnpm i github:factorialco/f0#c6ef17741642891fb4ba18e08eb147329f93374b to install this specific commit

[github-actions]

✅ No New Circular Dependencies

No new circular dependencies detected. Current count: 0

[github-actions]

♿ Accessibility (axe) — components changed in this PR

4 issues across 4 stories — all non-blocking (todo).

Story	Rule	WCAG	Impact	Nodes	Mode
Patterns/AnalyticsDashboard / Mixed Dashboard	aria-prohibited-attr	WCAG 4.1.2 A (2.0)	serious	14	🟡 todo
Patterns/AnalyticsDashboard / One Salary Dynamics Report	aria-prohibited-attr	WCAG 4.1.2 A (2.0)	serious	6	🟡 todo
Patterns/AnalyticsDashboard / With Item Filters	scrollable-region-focusable	WCAG 2.1.1 A (2.0)	serious	1	🟡 todo
Patterns/AnalyticsDashboard / Item Filters Applied	scrollable-region-focusable	WCAG 2.1.1 A (2.0)	serious	1	🟡 todo

_{Scope: only stories in the files/component folders this PR changed. It can't yet flag downstream ripple from shared-code/token changes, or diff against main (planned: base-vs-head delta).}

[github-actions]

✅ No breaking public API changes

No public exports were removed, renamed, or had existing props/types changed in a breaking way compared to main.

Comparing f0, experimental and ai against main. Adding components, types, or optional props is safe. This check is non-blocking.

➕ Additive changes (safe) — 4

• f0: DashboardItemBadge, DashboardItemRenderState, DashboardItemRenderStateChange, dashboardItemRenderStates

⚠️ Could not analyze component-status (no-base) — a build may have failed; results may be incomplete.

[github-actions]

Coverage Report for packages/react

Status	Category	Percentage	Covered / Total
🔵	Lines	69.06%	29196 / 42275
🔵	Statements	68.02%	30893 / 45416
🔵	Functions	61.92%	6971 / 11258
🔵	Branches	61.74%	21891 / 35455

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/react/src/patterns/F0AnalyticsDashboard/F0AnalyticsDashboard.tsx	73.07%	70%	100%	72%	74-81, 110-111
packages/react/src/patterns/F0AnalyticsDashboard/index.ts	0%	100%	100%	0%	41-44
packages/react/src/patterns/F0AnalyticsDashboard/types.ts	0%	100%	100%	0%	472
packages/react/src/patterns/F0AnalyticsDashboard/components/ChartItem/ChartItem.tsx	83.21%	73.03%	81.81%	85.6%	217, 246, 263, 270, 302, 319, 328, 373, 555, 654-685, 691-694, 724-776, 953, 1064, 1082-1103, 1155-1160
packages/react/src/patterns/F0AnalyticsDashboard/components/CollectionItem/CollectionItem.tsx	92.3%	78.57%	88.88%	92%	115, 175
packages/react/src/patterns/F0AnalyticsDashboard/components/DashboardGrid/DashboardGrid.tsx	80.68%	70.22%	82.19%	82.16%	150-151, 158, 160-161, 171, 179-195, 228-236, 281-294, 342, 349-350, 361, 366, 368, 375-376, 389, 406, 429, 531-534, 616-623, 671, 801, 813, 825, 934, 961-983, 1025, 1051, 1085, 1198-1210
packages/react/src/patterns/F0AnalyticsDashboard/components/DashboardItem/DashboardItem.tsx	80.7%	87.96%	60%	84%	209, 230, 459-484, 536-537
packages/react/src/patterns/F0AnalyticsDashboard/components/DashboardItem/DashboardItemBadge.tsx	87.5%	87.5%	50%	85.71%	25
packages/react/src/patterns/F0AnalyticsDashboard/components/MetricItem/MetricItem.tsx	88.46%	83.33%	100%	88%	63-74
packages/react/src/patterns/F0AnalyticsDashboard/hooks/useDashboardItemData.ts	96.66%	63.63%	83.33%	96.66%	101
packages/react/src/patterns/F0AnalyticsDashboard/hooks/useDashboardItemRenderState.ts	100%	100%	100%	100%

Generated in workflow #17586 for commit c81c46a by the Vitest Coverage Report Action