@auto-engineer/component-implementor-react 1.95.0 → 1.97.0

package/improvement-prompt.md

@@ -0,0 +1,208 @@
+# Component Implementor React — Evaluation & Improvement Prompt
+
+## Your Persona
+
+You are a **Staff Frontend Engineer and Tech Lead** — the kind who wrote the component library used by 200 engineers, ran the migration from class components to hooks, and has personally blocked PRs for missing ARIA attributes. You've reviewed thousands of component PRs and you can spot a bad prop interface, a fragile test, or a hollow Storybook story in seconds. You've also seen what happens when AI generates code that "looks right" but falls apart under real usage — tests that pass but don't test anything meaningful, components with prop names that don't match the spec, stories that only cover the happy path.
+
+You are allergic to:
+- **Props that don't match the spec language** — if the spec says "loading", the prop must be `loading`, not `isLoading` or `showSpinner`. Inconsistency between spec, component, test, and story is the #1 cause of reconciliation failures.
+- **Tests that don't test behavior** — a test that renders the component and asserts it exists is worthless. Every test must simulate what a user does and assert what a user sees.
+- **Missing ARIA roles** — if the test queries `getByRole('button')` and the component renders a `<div onClick>`, it fails. Semantic HTML is non-negotiable.
+- **Stories that only show the default state** — if the spec has 8 styling variants and 3 rendering states, you'd better see at least 10 stories, not 2.
+- **Component/test misalignment** — different export names, different prop names, different ARIA surfaces. This is exactly what the reconciler exists to fix, but if the initial generation is too far off, reconciliation can't save it.
+
+When you score, you score like you're signing off on code that ships to production tomorrow. If a junior engineer would come back with questions, the score goes down. If they'd build something wrong because the code was ambiguous, the score goes way down.
+
+---
+
+## What You're Evaluating
+
+A **Component Implementor agent** that transforms spec deltas into three files: a React component, a vitest test file, and a Storybook story file, followed by a reconciliation step that aligns the component and story to the tests. You will be given:
+
+1. **The Spec Deltas** (input) — structured arrays of structure, rendering, interaction, and styling requirements.
+2. **The Generated Component** (output) — the `.tsx` component file.
+3. **The Generated Test** (output) — the `.test.tsx` vitest file.
+4. **The Generated Story** (output) — the `.stories.tsx` Storybook file.
+5. **The Agent's System Prompts** (the prompts to improve) — the instructions each agent received.
+
+---
+
+## Scoring Rubric (100 points total)
+
+Score each category independently. Be strict — a score of 90+ means you'd merge this PR without requesting changes.
+
+### 1. Spec Coverage (20 points)
+
+Every spec delta string must be traceable to implementation in the component, a test case, and a story. This is the table-stakes check.
+
+| Score | Criteria |
+|-------|----------|
+| 20 | Every structure, rendering, interaction, and styling spec is implemented in the component, tested by at least one test case, and demonstrated by at least one story. You can draw a line from each spec string to code in all three files. |
+| 15 | All specs implemented and tested, but 1-3 specs lack a corresponding story. |
+| 10 | Most specs covered but 2-4 specs are missing from the component or tests. |
+| 5 | Multiple specs are missing across component, tests, and stories. |
+| 0 | Majority of specs not covered. |
+
+**How to check:** Walk through each spec delta string. For each one, find: (a) the implementation in the component, (b) the test that validates it, (c) the story that demonstrates it. If any is missing, it's a gap.
+
+### 2. Prop Interface Quality (15 points)
+
+The props interface is the component's API. It must be tight, correctly typed, and use names that match the spec language exactly.
+
+| Score | Criteria |
+|-------|----------|
+| 15 | Props type is exported. Every prop name matches spec language verbatim (spec says "loading" → prop is `loading`). Types are precise (not `any` or overly loose unions). Optional props have sensible defaults. Callback props use correct signatures. All four files (component, test, story, reconciled) use identical prop names. |
+| 12 | Props are well-typed but 1-2 names diverge from spec language, or one optional prop lacks a default. |
+| 8 | Props exist but several names don't match spec language, or types are loose (e.g., `string` where a union of literals is appropriate). |
+| 3 | Props are poorly typed, names are inconsistent across files, or the type is not exported. |
+| 0 | No exported props type, or props are `any`. |
+
+**How to check:** Read the spec deltas and note every implied prop (nouns become props: "loading", "variant", "size", "onClick", "disabled"). Then check: Does the component's Props type have that exact name? Does the test pass that exact name? Does the story use that exact name in args?
+
+### 3. Test Quality (20 points)
+
+Tests are the source of truth. They must be precise, behavioral, and comprehensive.
+
+| Score | Criteria |
+|-------|----------|
+| 20 | One test per spec delta (or more for complex specs). Semantic queries used everywhere (`getByRole`, `getByText`, `getByLabelText`). No `getByTestId`. Mock callbacks use `vi.fn()` with argument assertions. Test descriptions mirror spec language. Each test is isolated. Tests cover both positive and negative cases for interaction specs (e.g., "calls onClick" AND "does not call onClick when disabled"). |
+| 15 | Good tests but 1-2 use `getByTestId` unnecessarily, or 1-2 specs lack negative case coverage. |
+| 10 | Tests exist for most specs but several use implementation-detail queries, or test descriptions are generic rather than mirroring specs. |
+| 5 | Tests are shallow — many just render and check existence without testing behavior. |
+| 0 | Tests are missing or trivial. |
+
+**How to check:** For each test: (a) Does the description match a spec string? (b) Does it use semantic queries? (c) Does it assert a user-visible behavior, not an implementation detail? (d) For interaction specs, is there both a "fires" and "doesn't fire when guarded" test?
+
+### 4. Component Quality (15 points)
+
+The component must be production-ready — correct semantics, proper accessibility, clean composition.
+
+| Score | Criteria |
+|-------|----------|
+| 15 | Semantic HTML used (button, article, nav — not div for everything). ARIA roles match what tests expect. Named export with exported Props type. Tailwind classes for all styling. No dead code. Conditional rendering is clean (not nested ternaries). Event handlers are properly wired. No unnecessary useState. |
+| 12 | Good component but 1-2 semantic HTML opportunities missed (e.g., div instead of button). |
+| 8 | Component works but has semantic issues, missing ARIA attributes, or messy conditional logic. |
+| 3 | Component has structural problems — wrong exports, missing handlers, broken conditionals. |
+| 0 | Component would not render or has fundamental errors. |
+
+### 5. Story Quality (10 points)
+
+Stories must cover the full visual surface and serve as documentation.
+
+| Score | Criteria |
+|-------|----------|
+| 10 | CSF3 format. Default story present. One story per rendering state (loading, empty, error). One story per styling variant (primary, secondary, destructive). One story per size. Stories use `args` over custom `render`. Story names are descriptive PascalCase. Meta has correct component reference. |
+| 7 | Good stories but missing 2-3 variant/state stories, or some use unnecessary `render` functions. |
+| 4 | Only Default and 1-2 other stories. Major visual states uncovered. |
+| 0 | No stories or stories are broken. |
+
+### 6. Cross-File Alignment (10 points)
+
+After reconciliation, the three files must agree perfectly — same exports, same prop names, same ARIA surface.
+
+| Score | Criteria |
+|-------|----------|
+| 10 | Component export name matches test import. All prop names identical across component, test, and story. ARIA roles in component match test queries. Text content in component matches test assertions. Story imports and args match component. |
+| 7 | Minor misalignment — 1-2 prop name inconsistencies or one import path issue. |
+| 4 | Multiple misalignments — tests would fail against the component as written. |
+| 0 | Files are fundamentally misaligned — different export names, different prop interfaces. |
+
+### 7. Code Hygiene (10 points)
+
+Clean, idiomatic code that follows modern React/TypeScript conventions.
+
+| Score | Criteria |
+|-------|----------|
+| 10 | No unused imports. No `any` types. Consistent formatting. No commented-out code. No console.log statements. TypeScript strict-compatible. ESLint-clean patterns (no shadowed variables, no implicit returns in complex functions). Imports are minimal and correct. |
+| 7 | Minor issues — 1-2 unused imports or one loose type. |
+| 4 | Multiple hygiene issues — unused code, `any` types, inconsistent patterns. |
+| 0 | Code is messy — significant dead code, type errors, or formatting issues. |
+
+---
+
+## Output Format
+
+Respond with EXACTLY this JSON structure:
+
+```json
+{
+  "totalScore": <number 0-100>,
+  "categories": {
+    "specCoverage": {
+      "score": <number>,
+      "maxScore": 20,
+      "findings": ["<specific finding 1>", "<specific finding 2>"]
+    },
+    "propInterfaceQuality": {
+      "score": <number>,
+      "maxScore": 15,
+      "findings": ["..."]
+    },
+    "testQuality": {
+      "score": <number>,
+      "maxScore": 20,
+      "findings": ["..."]
+    },
+    "componentQuality": {
+      "score": <number>,
+      "maxScore": 15,
+      "findings": ["..."]
+    },
+    "storyQuality": {
+      "score": <number>,
+      "maxScore": 10,
+      "findings": ["..."]
+    },
+    "crossFileAlignment": {
+      "score": <number>,
+      "maxScore": 10,
+      "findings": ["..."]
+    },
+    "codeHygiene": {
+      "score": <number>,
+      "maxScore": 10,
+      "findings": ["..."]
+    }
+  },
+  "promptImprovements": [
+    {
+      "priority": "critical | high | medium | low",
+      "category": "<which scoring category this addresses>",
+      "currentBehavior": "<what the prompt currently produces>",
+      "desiredBehavior": "<what it should produce instead>",
+      "suggestedPromptChange": "<specific text to add, modify, or remove from the system prompt>"
+    }
+  ]
+}
+```
+
+## CRITICAL: Generalization & Anti-Leakage Rules
+
+You are evaluating against specific component scenarios, but the prompts you are improving must work for ANY component — a button, a data table, a modal dialog, a checkout form, a dashboard widget. The prompts are general-purpose instruction sets. They must never become coupled to the examples they were tested on.
+
+**The cardinal sin is component-specific leakage.** If the test input is a button component and you suggest adding "always include a spinner for loading states" — you've leaked that specific component's behavior into a general-purpose prompt. Not every component has a spinner.
+
+### What you MUST NOT do in prompt improvements:
+
+1. **Never reference specific component names** from the test input (e.g., "Button", "Card", "SearchInput"). The prompt must not contain the vocabulary of any specific component.
+2. **Never reference specific prop names** from the test input (e.g., "variant", "loading", "onClear"). The prompt should describe patterns for handling props, not name specific props.
+3. **Never add rules that only make sense for one component type** (e.g., "always add a clear button to inputs" — this is a search input concern, not universal).
+
+### What you MUST do instead:
+
+1. **Express improvements as structural patterns.** Bad: "Add a spinner when loading." Good: "For every rendering spec that describes a conditional element, ensure the component has the corresponding conditional render branch and the test asserts both the visible and hidden states."
+2. **Use abstract categories, not instances.** Bad: "Handle button variants." Good: "For every styling spec that describes variant-dependent classes, derive a union type prop and apply Tailwind classes conditionally per variant value."
+3. **Test your suggestion mentally.** Before proposing a change, ask: "Would this rule make sense for a data table? A modal? A tooltip?" If the answer is no, the rule is too specific.
+
+---
+
+## Rules for Prompt Improvements
+
+1. **Be surgical** — suggest specific additions/modifications to the system prompt, not vague advice.
+2. **Prioritize by impact** — `critical` = tests would fail or specs are uncovered. `high` = poor accessibility or broken cross-file alignment. `medium` = missing stories or weak test descriptions. `low` = code hygiene or style.
+3. **Never suggest removing existing rules** unless they directly cause a scoring failure.
+4. **Suggest additions as insertable text blocks** — provide the exact wording that should be added to the prompt, including which section (e.g., "Add to RULES in the Tester Agent:" or "Add to QUALITY CHECKLIST in the Frontend Agent:").
+5. **Maximum 10 improvements per evaluation** — focus on highest-impact changes.
+6. **Each improvement must map to a specific scoring deduction** — no speculative improvements.
+7. **Every improvement must pass the generalization test** — zero component-specific vocabulary from the test input.
+8. **Specify which agent's prompt to modify** — Frontend Agent, Tester Agent, Story Agent, or Reconciler. Each has its own system prompt.

package/inputs/action-button/spec.json

@@ -0,0 +1,50 @@
+{
+  "componentName": "ActionButton",
+  "specDeltas": {
+    "structure": [
+      "Renders a <button> element as the root",
+      "Contains a leading icon slot before the label content",
+      "Contains a trailing icon slot after the label content",
+      "Contains a Spinner element that replaces all content when loading",
+      "Accepts children as the primary label content",
+      "Contains a tooltip wrapper that shows on hover when tooltip prop is provided"
+    ],
+    "rendering": [
+      "Displays children as the button text",
+      "Shows the leading icon when leadingIcon prop is provided",
+      "Shows the trailing icon when trailingIcon prop is provided",
+      "Shows Spinner and hides label and both icons when loading is true",
+      "Renders as disabled when disabled is true",
+      "Renders as disabled when loading is true",
+      "Shows a brief checkmark icon replacing the label on success, then reverts to label after 1.5 seconds",
+      "Shows tooltip text on hover after a 300ms delay when tooltip prop is provided",
+      "Renders a badge count indicator overlaying the trailing position when badgeCount is greater than zero",
+      "Hides the badge indicator when badgeCount is zero or not provided"
+    ],
+    "interaction": [
+      "Calls onClick handler when clicked",
+      "Does not call onClick when disabled is true",
+      "Does not call onClick when loading is true",
+      "Supports keyboard activation via Enter and Space keys",
+      "Calls onKeyDown handler when a key is pressed while focused",
+      "Focuses the button programmatically when autoFocus is true on mount",
+      "Supports ref forwarding for external focus management"
+    ],
+    "styling": [
+      "Applies primary filled style when variant is primary",
+      "Applies secondary outlined style when variant is secondary",
+      "Applies destructive red style when variant is destructive",
+      "Applies ghost transparent style when variant is ghost",
+      "Applies link underline style when variant is link",
+      "Applies compact padding and small text when size is sm",
+      "Applies standard padding and medium text when size is md",
+      "Applies generous padding and large text when size is lg",
+      "Applies icon-only square aspect ratio when size is icon",
+      "Applies full-width layout stretching to container when fullWidth is true",
+      "Reduces opacity to 50% when disabled",
+      "Applies press-down scale transform on active state",
+      "Applies focus-visible ring outline for keyboard navigation",
+      "Applies subtle hover brightness change per variant"
+    ]
+  }
+}

package/inputs/command-palette/spec.json

@@ -0,0 +1,62 @@
+{
+  "componentName": "CommandPalette",
+  "specDeltas": {
+    "structure": [
+      "Renders as a modal overlay covering the full viewport with a centered dialog",
+      "Contains a search input at the top of the dialog with an auto-focused text field",
+      "Contains a scrollable results list below the search input",
+      "Results list is divided into named sections with section header labels",
+      "Each result item contains an icon, a primary label, an optional description, and an optional keyboard shortcut hint",
+      "Contains a footer bar with contextual hint text showing available keyboard shortcuts",
+      "Contains a backdrop overlay behind the dialog that dims the page content",
+      "Search input contains a search icon on the leading side and a loading spinner on the trailing side when searching"
+    ],
+    "rendering": [
+      "Shows the dialog when open prop is true",
+      "Hides the dialog when open prop is false",
+      "Displays all items grouped by section when the search query is empty",
+      "Filters items by matching the query against the item label and description using fuzzy matching",
+      "Shows only sections that have at least one matching item after filtering",
+      "Hides sections that have zero matching items",
+      "Highlights the matching characters in item labels with a distinct style",
+      "Shows a no-results message with the current query when no items match",
+      "Shows the loading spinner in the search input when loading is true",
+      "Displays the first item as the active highlighted item by default when results appear",
+      "Shows the item description text in a muted style below the primary label",
+      "Shows the keyboard shortcut hint right-aligned within each item when provided",
+      "Shows a recently used section at the top when recentItems prop is provided and query is empty",
+      "Updates the footer hint text based on the currently active item"
+    ],
+    "interaction": [
+      "Calls onClose when the backdrop overlay is clicked",
+      "Calls onClose when Escape key is pressed",
+      "Calls onSelect with the active item when Enter is pressed",
+      "Calls onSelect with the clicked item when a result item is clicked",
+      "Navigates the active highlight down with ArrowDown key",
+      "Navigates the active highlight up with ArrowUp key",
+      "Wraps navigation from the last item to the first and first to the last",
+      "Scrolls the active item into view when navigating with keyboard",
+      "Calls onQueryChange with the current search text when the input changes",
+      "Focuses the search input automatically when the dialog opens",
+      "Restores focus to the previously focused element when the dialog closes",
+      "Traps focus within the dialog while open so Tab cycles between search input and close area",
+      "Does not propagate keyboard events to elements behind the backdrop",
+      "Calls onClose when the user selects an item by default unless keepOpenOnSelect is true"
+    ],
+    "styling": [
+      "Backdrop uses a semi-transparent dark overlay with backdrop-blur effect",
+      "Dialog has rounded-xl corners with a shadow-2xl drop shadow",
+      "Dialog is centered horizontally and positioned in the upper third vertically",
+      "Dialog has a max-width of 640px and max-height of 60vh",
+      "Active item has a distinct highlighted background color",
+      "Hovered items have a subtle background different from the active highlight",
+      "Section headers use uppercase text with muted color and small font size",
+      "Search input has no visible border and uses a large font size for prominence",
+      "Keyboard shortcut hints render as inline code-style badges with monospace font",
+      "Matching characters in fuzzy search results use bold font weight",
+      "Dialog entrance uses a scale-up and fade-in animation",
+      "Dialog exit uses a scale-down and fade-out animation",
+      "Results list applies a subtle top border separating it from the search input"
+    ]
+  }
+}

package/inputs/data-card/spec.json

@@ -0,0 +1,59 @@
+{
+  "componentName": "DataCard",
+  "specDeltas": {
+    "structure": [
+      "Renders an <article> element as the root",
+      "Contains an optional media region above the header for images or video thumbnails",
+      "Contains a header region with title, optional subtitle, and optional action menu",
+      "Contains a metadata row below the header for key-value pairs",
+      "Contains a content region as the main body accepting children",
+      "Contains an optional footer region with primary and secondary action buttons",
+      "Contains an optional overlay region for status banners positioned over the media",
+      "Action menu renders as a dropdown triggered by a three-dot icon button in the header"
+    ],
+    "rendering": [
+      "Displays the title prop in the header with text truncation after 2 lines",
+      "Displays the subtitle prop below the title when provided",
+      "Hides the subtitle area entirely when subtitle is not provided",
+      "Displays the media element in the media region when media prop is provided",
+      "Shows a placeholder gradient background in the media region when media is not provided and showMediaPlaceholder is true",
+      "Hides the media region entirely when media is not provided and showMediaPlaceholder is false",
+      "Displays metadata items as label-value pairs in a horizontal row",
+      "Shows the action menu trigger when menuItems prop has at least one item",
+      "Displays footer content with primaryAction and secondaryAction buttons when provided",
+      "Hides the footer region when neither primaryAction nor secondaryAction is provided",
+      "Shows a Skeleton placeholder for each region when loading is true",
+      "Hides all real content and shows only skeletons when loading is true",
+      "Shows the overlay banner text positioned over the media region when overlayText is provided",
+      "Renders children inside the content region",
+      "Shows an empty state message when children are not provided and emptyText is given"
+    ],
+    "interaction": [
+      "Calls onClick handler when the card body is clicked",
+      "Does not call onClick when a button or link inside the card is clicked",
+      "Does not call onClick when the action menu is interacted with",
+      "Applies focusable behavior with tabindex and role when onClick is provided",
+      "Supports keyboard activation via Enter when clickable",
+      "Calls onMenuItemClick with the item id when a dropdown menu item is selected",
+      "Closes the action menu dropdown when clicking outside",
+      "Closes the action menu dropdown when pressing Escape",
+      "Calls primaryAction.onClick when the primary footer button is clicked",
+      "Calls secondaryAction.onClick when the secondary footer button is clicked"
+    ],
+    "styling": [
+      "Applies elevated shadow when variant is elevated",
+      "Applies outlined border with no shadow when variant is outlined",
+      "Applies flat style with subtle background and no border or shadow when variant is flat",
+      "Applies compact spacing with tight padding when size is sm",
+      "Applies standard spacing with normal padding when size is md",
+      "Applies generous spacing with relaxed padding when size is lg",
+      "Applies hover shadow increase when clickable and variant is elevated",
+      "Applies hover border color change when clickable and variant is outlined",
+      "Applies rounded-lg corners to the card container",
+      "Applies overflow-hidden to clip media content at card borders",
+      "Applies a semi-transparent dark overlay gradient on the media region when overlayText is present",
+      "Overlay text is white and positioned at the bottom-left of the media region",
+      "Action menu trigger appears with reduced opacity and becomes full opacity on card hover"
+    ]
+  }
+}

package/inputs/editable-data-table/spec.json

@@ -0,0 +1,70 @@
+{
+  "componentName": "EditableDataTable",
+  "specDeltas": {
+    "structure": [
+      "Renders a <div> container wrapping a toolbar, table, and pagination footer",
+      "Toolbar contains a search input, column visibility toggle dropdown, bulk action bar, and row count display",
+      "Table renders a <table> element with <thead> and <tbody> sections",
+      "Each header cell contains the column label and a sort indicator icon",
+      "Each body row contains data cells matching the column definitions",
+      "Editable cells render an inline input that activates on double-click",
+      "Contains a checkbox column as the first column for row selection",
+      "Header checkbox selects or deselects all visible rows",
+      "Bulk action bar appears above the table when at least one row is selected",
+      "Pagination footer contains page size selector, page number buttons, and total row count"
+    ],
+    "rendering": [
+      "Displays column headers from the columns prop array in order",
+      "Renders one row per item in the data prop array",
+      "Shows a skeleton table with shimmer rows when loading is true",
+      "Shows an empty state illustration and message when data is empty and loading is false",
+      "Shows the empty state message from emptyMessage prop",
+      "Displays the sort indicator as ascending arrow when column is sorted ascending",
+      "Displays the sort indicator as descending arrow when column is sorted descending",
+      "Hides the sort indicator on columns that are not currently sorted",
+      "Displays only columns where visible is true in the column definition",
+      "Hides columns where visible is false in the column definition",
+      "Shows the active search query as highlighted text within matching cells",
+      "Shows the bulk action bar with a count of selected rows when selection is non-empty",
+      "Hides the bulk action bar when no rows are selected",
+      "Displays the current page range and total count in the pagination footer",
+      "Renders cell content using the column renderCell function when provided",
+      "Falls back to displaying the raw field value when renderCell is not provided",
+      "Shows an inline validation error below an editable cell when editValidation returns an error",
+      "Shows a saving spinner in the cell being edited during optimistic save"
+    ],
+    "interaction": [
+      "Calls onSort with column id and direction when a sortable header is clicked",
+      "Toggles sort direction on repeated clicks of the same header (asc -> desc -> none)",
+      "Calls onSearch with the query string when the toolbar search input changes",
+      "Debounces onSearch calls by 300ms after the user stops typing",
+      "Calls onRowSelect with the row id and selected state when a row checkbox is toggled",
+      "Calls onSelectAll with the selected state when the header checkbox is toggled",
+      "Activates inline edit mode on a cell when the cell is double-clicked and the column is editable",
+      "Commits the edit and calls onCellEdit with row id, column id, and new value when Enter is pressed",
+      "Cancels the edit and reverts to the original value when Escape is pressed during inline edit",
+      "Commits the edit when the inline input loses focus",
+      "Calls onBulkAction with action id and selected row ids when a bulk action button is clicked",
+      "Calls onPageChange with the new page number when a pagination button is clicked",
+      "Calls onPageSizeChange with the new size when the page size selector changes",
+      "Navigates between editable cells with Tab key while in edit mode",
+      "Calls onRowClick with the row data when a row is clicked and the click is not on a checkbox or editable cell"
+    ],
+    "styling": [
+      "Applies alternating row background colors for visual separation (striped)",
+      "Applies hover background highlight on rows when hoverable is true",
+      "Applies selected background highlight on rows that are checked",
+      "Applies sticky positioning to the header row so it remains visible on scroll",
+      "Applies compact row height and smaller text when density is compact",
+      "Applies standard row height when density is normal",
+      "Applies relaxed row height with more padding when density is comfortable",
+      "Applies a bottom border to each row",
+      "Applies a focused ring to the currently editing cell",
+      "Applies truncation with ellipsis to cell content that overflows the column width",
+      "Applies a right-aligned style to columns where align is right",
+      "Applies a center-aligned style to columns where align is center",
+      "Applies a muted text style to the pagination and row count footer elements",
+      "Bulk action bar has a distinct info-colored background to indicate active selection mode"
+    ]
+  }
+}

package/inputs/multi-step-form/spec.json

@@ -0,0 +1,66 @@
+{
+  "componentName": "MultiStepForm",
+  "specDeltas": {
+    "structure": [
+      "Renders a container div wrapping a progress stepper, step content area, and navigation footer",
+      "Progress stepper displays a horizontal bar with numbered step circles connected by lines",
+      "Each step circle contains the step number or a checkmark icon when the step is completed",
+      "Step content area renders only the active step's content as provided by the steps prop",
+      "Navigation footer contains a Back button, a Next or Submit button, and an optional Skip link",
+      "Contains an optional sidebar summary panel that shows a live preview of accumulated form data",
+      "Contains a discard confirmation dialog that appears when the user attempts to navigate away with unsaved changes",
+      "Each step can contain an optional step-level error alert below the step title"
+    ],
+    "rendering": [
+      "Displays the current step title and optional description above the step content",
+      "Shows the step number inside uncompleted step circles in the progress stepper",
+      "Shows a checkmark icon inside completed step circles in the progress stepper",
+      "Highlights the active step circle with a distinct ring and color",
+      "Shows completed step circles with a filled success style",
+      "Shows future step circles in a muted disabled style",
+      "Shows connecting lines between steps as filled when the preceding step is completed",
+      "Shows connecting lines as unfilled when the preceding step is not completed",
+      "Renders the Back button as disabled on the first step",
+      "Renders a Submit button instead of Next on the final step",
+      "Shows the Skip link only when the current step has optional set to true",
+      "Shows a loading spinner on the Submit button when submitting is true",
+      "Disables all navigation buttons when submitting is true",
+      "Shows the sidebar summary panel when showSummary is true and the viewport is wide enough",
+      "Hides the sidebar summary panel on narrow viewports regardless of showSummary",
+      "Shows the discard confirmation dialog when hasUnsavedChanges is true and the user clicks a navigation link outside the form",
+      "Shows a step-level validation error alert when stepErrors contains an error for the current step index",
+      "Clears the step-level error when the user modifies any field in the current step"
+    ],
+    "interaction": [
+      "Calls onNext with the current step index when the Next button is clicked and validation passes",
+      "Does not advance to the next step when onValidateStep returns errors for the current step",
+      "Calls onBack with the current step index when the Back button is clicked",
+      "Calls onSkip with the current step index when the Skip link is clicked",
+      "Calls onSubmit with the accumulated form data when the Submit button is clicked on the final step",
+      "Calls onStepClick with the step index when a completed step circle is clicked to navigate back",
+      "Does not allow clicking on future incomplete step circles to jump forward",
+      "Calls onDiscard when the user confirms the discard dialog",
+      "Calls onCancelDiscard when the user cancels the discard dialog and returns to the form",
+      "Focuses the first focusable element in the new step content when transitioning between steps",
+      "Supports Ctrl+Enter as a keyboard shortcut to advance to the next step or submit",
+      "Calls onStepChange with the new step index whenever the active step changes",
+      "Prevents browser back navigation from leaving the form and shows the discard dialog instead when hasUnsavedChanges is true"
+    ],
+    "styling": [
+      "Active step circle has a ring-2 border with a primary color fill",
+      "Completed step circles have a success green background with white checkmark",
+      "Future step circles have a gray border and muted gray background",
+      "Completed connecting lines use a solid primary color",
+      "Incomplete connecting lines use a dashed muted gray style",
+      "Step content area has a slide-left entrance animation when advancing forward",
+      "Step content area has a slide-right entrance animation when navigating backward",
+      "Submit button uses primary variant styling",
+      "Back button uses ghost variant styling",
+      "Skip link uses a text-only muted style with underline on hover",
+      "Sidebar summary panel has a subtle background and a left border accent",
+      "Discard dialog uses a destructive styling on the confirm button",
+      "Step-level error alert uses a destructive banner style with an icon",
+      "Progress stepper is horizontally scrollable on narrow viewports when there are many steps"
+    ]
+  }
+}

package/inputs/notification-center/spec.json

@@ -0,0 +1,67 @@
+{
+  "componentName": "NotificationCenter",
+  "specDeltas": {
+    "structure": [
+      "Renders as a popover panel anchored to a trigger button",
+      "Trigger button contains a bell icon and an unread count badge",
+      "Panel contains a header with a title, a filter tab bar, and a mark-all-read button",
+      "Panel contains a scrollable notification list below the header",
+      "Each notification item contains an icon, a title, a body preview, a relative timestamp, and an unread dot indicator",
+      "Each notification item contains a hover-revealed action menu with mark-read and dismiss buttons",
+      "Panel contains a footer with a view-all link and notification preferences link",
+      "Panel contains an empty state illustration and message when there are no notifications for the active filter",
+      "Notification items are grouped by date sections (Today, Yesterday, Earlier)"
+    ],
+    "rendering": [
+      "Shows the unread badge on the trigger when unreadCount is greater than zero",
+      "Hides the unread badge when unreadCount is zero",
+      "Displays unread count as 99+ when unreadCount exceeds 99",
+      "Shows the panel when open is true",
+      "Hides the panel when open is false",
+      "Displays notifications filtered by the active tab (all, unread, mentions)",
+      "Shows the unread dot indicator on notifications where read is false",
+      "Hides the unread dot on notifications where read is true",
+      "Displays relative timestamps (just now, 5m ago, 2h ago, yesterday) using the timestamp field",
+      "Shows a loading skeleton list when loading is true",
+      "Shows the empty state with a filter-specific message when the filtered list is empty",
+      "Shows the date section headers (Today, Yesterday, Earlier) based on notification timestamps",
+      "Hides date sections that contain no notifications after filtering",
+      "Truncates notification body text to two lines with ellipsis overflow",
+      "Shows the hover action menu when the user hovers over a notification item",
+      "Hides the hover action menu when the cursor leaves the notification item",
+      "Applies a pulse animation to the trigger bell icon when a new notification arrives via the onNewNotification callback"
+    ],
+    "interaction": [
+      "Calls onToggle to open or close the panel when the trigger button is clicked",
+      "Calls onClose when clicking outside the panel while it is open",
+      "Calls onClose when Escape is pressed while the panel is open",
+      "Calls onNotificationClick with the notification id when a notification item is clicked",
+      "Calls onMarkRead with the notification id when the mark-read action is clicked",
+      "Calls onDismiss with the notification id when the dismiss action is clicked",
+      "Calls onMarkAllRead when the mark-all-read header button is clicked",
+      "Calls onFilterChange with the new tab value when a filter tab is selected",
+      "Calls onViewAll when the view-all footer link is clicked",
+      "Calls onPreferencesClick when the preferences footer link is clicked",
+      "Loads more notifications by calling onLoadMore when the list is scrolled to the bottom",
+      "Does not close the panel when interacting with notification action menus",
+      "Traps focus within the panel when open and navigates items with ArrowUp and ArrowDown",
+      "Marks a notification as read automatically when it is clicked via onNotificationClick"
+    ],
+    "styling": [
+      "Trigger button applies a subtle bounce animation on the bell when a new notification arrives",
+      "Unread badge is positioned at the top-right of the trigger with a red background and white text",
+      "Panel has a rounded-xl shadow with a fixed width of 400px and max-height of 500px",
+      "Panel appears with a slide-down and fade-in animation from the trigger position",
+      "Panel disappears with a slide-up and fade-out animation",
+      "Active filter tab has a bold text weight and a colored bottom border indicator",
+      "Inactive filter tabs have muted text and no bottom border",
+      "Unread notification items have a subtle highlighted background",
+      "Read notification items have a standard background",
+      "Notification timestamps use a muted and small text style",
+      "Unread dot indicator is a small colored circle positioned at the leading edge of the item",
+      "Hover action menu appears with a short fade-in transition on the trailing side of the item",
+      "Date section headers use uppercase small text with extra top margin for visual separation",
+      "Mark-all-read button uses a ghost style with muted text that becomes prominent on hover"
+    ]
+  }
+}