Skip to content

feat(storybook): show component status + DoD checklist on docs pages#4724

Merged
sauldom102 merged 18 commits into
mainfrom
feat/component-status-docs-panel
Jul 17, 2026
Merged

feat(storybook): show component status + DoD checklist on docs pages#4724
sauldom102 merged 18 commits into
mainfrom
feat/component-status-docs-panel

Conversation

@sauldom102

@sauldom102 sauldom102 commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

Description

Surfaces each component's maturity status and Definition-of-Done checklist as a reusable, self-consistent UI. All display text (badge label, summary line, checklist labels and remediation hints) is now part of the component-status data, and a single exported ComponentStability component renders it — so the Storybook docs page and any consuming app (e.g. a factorial-composer page) show identical content. Reuses the API from #4719; renders nothing on non-component pages.

Screenshots (if applicable)

Rendered on every component docs page under the title: a "Status" heading, a maturity badge, a one-line summary, and the checklist with per-item detail for unmet requirements. (Verified in a live Storybook — Card, Alert, and a non-component page.)

Implementation details

  • feat: export a ComponentStability component — <ComponentStability componentName="F0Card" /> — that looks up the status and renders the badge, summary, and checklist; renders nothing for unknown names. Accepts an optional components dataset override for testing
  • feat: move all display text into the component-status data — label (badge), summary (top line), and showChecklist now come from evaluateComponentStatus, next to the existing per-requirement label/detail — so text lives in one place and stays consistent across Storybook and consumers
  • feat: inject the panel into every component docs page via the docs container (thin wrapper that resolves the current component from the docs context and portals ComponentStability in under the title)
  • refactor: make getComponentStatus name matching tiered (exact full-name → leaf-level → suffix) so fully-qualified titles (Data Collection/Visualizations/Card) and prefixed autodocs titles (Components/F0Card) resolve to the correct entry
  • test: unit tests for the new presentation text (label/summary/showChecklist), the title-resolution tiers, and a render test for ComponentStability

Usage from another repo:

import { ComponentStability } from "@factorialco/f0-react/dist/component-status"

;<ComponentStability componentName="F0Card" />

Injects the maturity status and Definition-of-Done checklist (from the
component-status API) into every component docs page via the docs container.
Also makes getComponentStatus matching tiered so fully-qualified or prefixed
Storybook titles resolve to the correct entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@sauldom102
sauldom102 requested a review from a team as a code owner July 16, 2026 15:53
@github-actions github-actions Bot added feat react Changes affect packages/react labels Jul 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

✅ No New Circular Dependencies

No new circular dependencies detected. Current count: 0

@github-actions

github-actions Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

📦 Alpha Package Version Published

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

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

@github-actions

github-actions Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

🔍 Visual review for your branch is published 🔍

Here are the links to:

@github-actions

Copy link
Copy Markdown
Contributor

✅ 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.

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

@github-actions

github-actions Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Coverage Report for packages/react

Status Category Percentage Covered / Total
🔵 Lines 59.34% 20795 / 35039
🔵 Statements 58.39% 21805 / 37341
🔵 Functions 51.52% 4834 / 9382
🔵 Branches 52.09% 15026 / 28841
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
packages/react/src/component-status/ComponentStability.tsx 100% 100% 100% 100%
packages/react/src/component-status/component-status.ts 98.57% 98.03% 96.42% 98.3% 410
packages/react/src/component-status/exports.ts 100% 100% 100% 100%
Generated in workflow #15747 for commit 3511db9 by the Vitest Coverage Report Action

sauldom102 and others added 17 commits July 17, 2026 10:24
…ponentStability

The badge label, summary line, and checklist visibility now come from the
component-status data (alongside the existing requirement labels/hints), so
Storybook and any consuming app render identical content. Adds an exported
ComponentStability component that takes a componentName prop and renders the
status; the Storybook docs panel is now a thin wrapper around it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…izontal padding

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Use text-lg (16px) for the status title and summary, and add an h2
section heading. text-md is not a defined f0 utility, so text-lg is used.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove the redundant "Status" label; "Maturity level" and "Importing this
component" are now h3 section headings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a `criteria` list to the docQuality requirement (in the API, so it stays
consistent everywhere) and render it under the checklist item instead of an
abstract sentence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add an effective status: a component is stable only if tagged stable AND it
  meets the full checklist; otherwise (untagged, below bar, or meeting the bar
  without the tag) it is experimental. The badge shows effective status.
- Add a play-function check and raise the doc-quality bar to "good" per the
  lifecycle Definition of Done (PR #4253).
- Show the subtitle for every checklist point (met and unmet), for stable and
  experimental alike.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Emit granular MDX doc signals from the generator and mark each doc-quality
sub-criterion (sections+props, DoDonts, when-not-to-use, 3+ examples) with its
own check/cross instead of a plain bullet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…iner

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The manager (esbuild bundle) can't run the Vite virtual module, so main.ts
computes the effectively-experimental set at startup and writes a generated,
gitignored file the manager imports for its sidebar renderLabel. A drift test
keeps the generator's effective-status helper in sync with the TS policy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… after sidebar label

- Component Status table now shows effective status + declared tag + the full
  requirement checks (tests, play, MDX, good docs), matching the panel/sidebar.
  Summary cards count effective stable and tagged-but-below-bar.
- Move the sidebar experimental warning dot to after the component name.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…mental marker

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…eclared-tag column

- Extract the story meta title from the meta object, not the first title: in the
  file (sample-data/args objects with a title: were surfacing as components,
  e.g. 'Cannot access payroll documents').
- Exclude internal (ui/, lib/, or the internal tag) — internal is not a maturity
  level per the Definition of Done.
- Drop the 'Declared tag' column from the status table and remove Internal from
  the status filter.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Generate a leaf → effective-status map at startup (experimental + deprecated)
and render 🚧 for experimental and ❌ for deprecated in the sidebar.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Maturity level panel (ComponentStability) now conveys the status and DoD,
superseding the old 'don't use experimental components in production' F0Alert.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@sauldom102
sauldom102 merged commit f46f4ae into main Jul 17, 2026
24 checks passed
@sauldom102
sauldom102 deleted the feat/component-status-docs-panel branch July 17, 2026 11:27
@eliseo-juan eliseo-juan mentioned this pull request Jul 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feat react Changes affect packages/react

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant