@arbor-education/design-system.components 0.15.0 → 0.16.0

package/component-library.md

@@ -2,7 +2,7 @@
 
 > Auto-generated reference for AI agents (Sophia, analyze-design, etc.)
 > Source: `src/components/` · Public API: `src/index.ts`
-> Last updated: 2026-04-22
+> Last updated: 2026-05-05
 
 ---
 
@@ -180,27 +180,86 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 ### 5. Card
 
 **File:** `src/components/card/Card.tsx` · **Public export:** Yes
+**Also exports:** `CardProps`, `Card.Props`, `Card.AccessibleNameProps`, `Card.InteractiveProps`, `Card.InteractionProps` types; `getCardInteractionProps` utility
 
-**Use case:** Navigational or informational content block for module selection, settings pages, or pick-from-a-list UIs.
+**Use case:** Surface component for grouping related content into a visually distinct container. Two modes: **static** (read-only content display) and **interactive** (clickable, `role="button"`, keyboard support, chevron→arrow icon). Foundation for `ArticleCard` and `KPICard`.
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `title` | `string` | No | — | Card heading |
-| `paragraph` | `string` | No | — | Descriptive text |
+| `children` | `ReactNode` | No | — | Content rendered inside card body |
+| `spacing` | `'default' \| 'dense'` | No | `'default'` | Padding variant. `'dense'` uses `--spacing-small` |
+| `disabled` | `boolean` | No | `false` | Disables interactive card (no-op on static cards) |
+| `onClick` | `(e: MouseEvent<HTMLElement>) => void` | No | — | Switches card to interactive mode |
+| `onKeyDown` | `(e: KeyboardEvent<HTMLElement>) => void` | No | — | Additional keydown handler (interactive only) |
+| `aria-label` | `string` | **Required on interactive cards** | — | Accessible name |
+| `aria-labelledby` | `string` | **Required on interactive cards** | — | Alternative to `aria-label` |
+| `className` | `string` | No | — | Additional CSS class on root `<figure>` |
+
+**Variants:** static (no `onClick`) / interactive (`onClick` provided, renders `role="button"`) / disabled interactive
+
+**Key features:**
+- Renders as `<figure>`
+- Interactive cards: `role="button"`, `tabIndex={0}`, chevron-right icon (swaps to arrow-right on hover)
+- `aria-label` or `aria-labelledby` **required** when `onClick` provided — throws in dev, console.error in prod without one
+- `disabled` only has effect when `onClick` is also provided; sets `aria-disabled={true}`, suppresses click/keyboard
+- Never nest interactive elements (`Button`, `a`, `input`) inside a clickable card — WCAG 2.1 violation
+
+> **MANIFEST CORRECTION (2026-05-05):** Card was fully rewritten. Old props `title`, `paragraph`, `icon`, `tagText`, `tagColor`, etc. are GONE. Use `ArticleCard` or `KPICard` for those use cases.
+
+---
+
+### 5a. ArticleCard
+
+**File:** `src/components/articleCard/ArticleCard.tsx` · **Public export:** Yes
+**Also exports:** `ArticleCardProps` type
+
+**Use case:** Card variant for article/content listings — combines an icon, heading, paragraph, and optional tag. Supports two modes: linked (heading wraps an `<a>`) or interactive shell (passes `onClick` through to `Card`).
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | `ReactNode` | No | — | Card heading |
+| `paragraph` | `ReactNode` | No | — | Descriptive text |
 | `icon` | `IconName` | No | — | Leading icon |
-| `iconColor` | `string` | No | — | Icon color override |
+| `iconColor` | `IcoTextIconProps['color']` | No | — | Icon color |
 | `iconScreenReaderText` | `string` | No | — | SR text for icon |
-| `tagText` | `string` | No | — | Tag label inside card |
+| `tagText` | `string` | No | — | Tag label |
 | `tagColor` | `TagColor` | No | — | Tag color |
-| `onClick` | `(e: React.MouseEvent<HTMLElement>) => void` | No | — | Makes card clickable |
-| `disabled` | `boolean` | No | — | Disables interaction |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+| `href` | `string` | Mutually exclusive with `onClick` | — | **Linked mode**: heading becomes `<a href>` |
+| `onClick` | `(e: MouseEvent<HTMLElement>) => void` | Mutually exclusive with `href` | — | **Interactive shell mode** |
+| `aria-label` | `string` | No | — | Accessible name override |
+| `aria-labelledby` | `string` | No | — | Alternative accessible name |
+| `className` | `string` | No | — | Additional CSS class |
+
+**Key features:**
+- Wraps `Card` + `IcoText` composite
+- Linked mode: uses `href` on heading `<a>`, card shell is non-interactive
+- Interactive shell mode: passes `onClick`/`disabled` to `Card`
+
+---
+
+### 5b. KPICard
 
-**Variants:** clickable (chevron + arrow icons, cursor pointer) / static / disabled
+**File:** `src/components/kpiCard/KPICard.tsx` · **Public export:** Yes
+**Also exports:** `KPICardProps` type
+
+**Use case:** Dense KPI metric tile — label above, prominent value below with optional % suffix and optional children (e.g. a trend indicator). Uses `Card`'s `dense` spacing. Supports optional `onClick` for interactive KPI tiles.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `ReactNode` | Yes | — | Metric label (e.g. "Attendance rate") |
+| `value` | `ReactNode` | Yes | — | Metric value (e.g. `94`) |
+| `isPercentage` | `boolean` | No | `false` | Appends `%` suffix after value |
+| `children` | `ReactNode` | No | — | Additional content (e.g. trend indicator) |
+| `disabled` | `boolean` | No | `false` | Disabled state (interactive only) |
+| `onClick` | `(e: MouseEvent<HTMLElement>) => void` | No | — | Makes card interactive |
+| `aria-label` | `string` | Required with `onClick` | — | Accessible name |
+| `aria-labelledby` | `string` | Required with `onClick` | — | Alternative accessible name |
+| `className` | `string` | No | — | Additional CSS class |
 
 **Key features:**
-- Renders as `<article>`
-- Clickable cards get `tabIndex={0}` for keyboard access
-- `aria-label="Card"` hardcoded — consider overriding via `...rest`
+- Wraps `Card` with `spacing="dense"`; passes interaction props via `getCardInteractionProps`
+- CSS: `ds-kpi-card`, `ds-kpi-card__label`, `ds-kpi-card__value`, `ds-kpi-card__suffix`
 
 ---
 
@@ -574,6 +633,74 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 
 ---
 
+### 21b. IcoText
+
+**File:** `src/components/icoText/IcoText.tsx` · **Public export:** Yes
+**Also exports:** `IcoTextProps`, `IcoTextHeadingProps`, `IcoTextParagraphProps`, `IcoTextIconProps` types
+
+**Use case:** Composite layout pattern — icon on the left, heading and paragraph on the right. Used internally by `ArticleCard`. Use directly when you need an icon + text block without a card shell.
+
+**Compound components:**
+
+| Sub-component | Renders as | Description |
+|---|---|---|
+| `IcoText` (root) | `<div class="ds-ico-text">` | Container; separates icon children from content children |
+| `IcoText.Icon` | `<Icon>` | Leading icon with `ds-ico-text__icon` class |
+| `IcoText.Heading` | `<h4 class="ds-ico-text__heading">` | Heading text |
+| `IcoText.Paragraph` | `<p class="ds-ico-text__paragraph">` | Body text |
+
+**`IcoText.Icon` props:**
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `IconName` | Yes | — | Icon identifier |
+| `color` | `string` | No | — | Icon color |
+| `screenReaderText` | `string` | No | — | SR-only text for icon |
+| `size` | `12 \| 16 \| 24` | No | `24` | Icon size |
+| `className` | `string` | No | — | Additional CSS class |
+
+**Key features:**
+- Root separates `IcoText.Icon` children into a flex-left slot; all other children go into `ds-ico-text__content`
+- `IcoText.Heading` and `IcoText.Paragraph` accept all standard HTML heading/paragraph attributes
+
+---
+
+### 21c. KVPList
+
+**File:** `src/components/kvpList/KVPList.tsx` · **Public export:** Yes
+**Also exports:** `KVPListProps`, `KVPListRowProps`, `KVPListTermProps`, `KVPListDefinitionProps` types
+
+**Use case:** Key/value pair list for detail panels, profiles, and data summary displays. Uses semantic `<dl>`/`<dt>`/`<dd>` markup for accessibility. Supports vertical and horizontal row layouts, bold/neutral value prominence, and optional `%` suffix.
+
+**Compound components:**
+
+| Sub-component | Renders as | Description |
+|---|---|---|
+| `KVPList` (root) | `<div class="ds-kvp-list">` | Container; auto-adds `role="group"` when `aria-label`/`aria-labelledby` provided |
+| `KVPList.Row` | `<dl class="ds-kvp-list__row">` | Single key/value row |
+| `KVPList.Term` | `<dt class="ds-kvp-list__term">` | The key/label |
+| `KVPList.Definition` | `<dd class="ds-kvp-list__description">` | The value |
+
+**`KVPList.Row` props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Stacking direction of term + definition |
+
+**`KVPList.Definition` props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `isRow` | `boolean` | `false` | Adds `ds-kvp-list__description--row` modifier |
+| `isPercentage` | `boolean` | `false` | Appends `%` suffix in `<span class="ds-kvp-list__suffix">` |
+| `prominence` | `'neutral' \| 'strong'` | `'neutral'` | Controls text weight/color emphasis |
+
+**Key features:**
+- All sub-components accept `className` and standard HTML element attributes via `...rest`
+- `KVPList` root adds `role="group"` automatically when `aria-label` or `aria-labelledby` is present
+
+---
+
 ### 22. Modal
 
 **Files:** `src/components/modal/Modal.tsx` + `src/components/modal/modalManager/ModalManager.tsx` · **Public export:** Yes (both)
@@ -1086,7 +1213,9 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 | `AvatarGroup` | Yes | ascending/descending; overflow count; items or children API | — |
 | `Banner` | Yes | level: info/neutral/warning/destructive | CVA |
 | `Button` | Yes | 7 variants; 2 sizes; icon-only; borderless; error | — |
-| `Card` | Yes | clickable/static/disabled; optional tag | — |
+| `Card` | Yes | static/interactive (`onClick`)/disabled; `spacing`: default/dense | — |
+| `ArticleCard` | Yes | linked (`href`) or interactive shell (`onClick`); icon/title/paragraph/tag | — |
+| `KPICard` | Yes | label+value metric tile; `isPercentage`; optional interactive | — |
 | `DatePicker` | Yes | any date-fns format; error state | Radix Popover, react-day-picker |
 | `Dropdown` | Yes | compound: Trigger/Content/Item/SelectItem/Separator/Group | Radix DropdownMenu |
 | `EditableText` | Yes | single-line/multiline; controlled editing | — |
@@ -1103,6 +1232,8 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 | `ColourPickerDropdown` | Yes | error state; controlled color | @uiw/react-color |
 | `Heading` | Yes | level: 1–4 (h1–h4) | — |
 | `Icon` | Yes | ~100 icons; sizes 12/16/24; custom color | lucide-react |
+| `IcoText` | Yes | compound: Icon/Heading/Paragraph; icon-left layout | — |
+| `KVPList` | Yes | compound: Row/Term/Definition; `orientation`; `prominence`; `isPercentage` | — |
 | `Modal` + `ModalManager` | Yes | compound sub-components; PubSub imperative control | Radix Dialog |
 | `Pill` | Yes | toggle / checkbox modes | — |
 | `Progress` | Yes | value/max controlled | Radix Progress |

package/dist/components/articleCard/ArticleCard.stories.d.ts

@@ -1,18 +1,144 @@
 import type { StoryObj } from '@storybook/react-vite';
+import { ArticleCard } from './ArticleCard';
+declare function ArticleCardDocsPage(): import("react/jsx-runtime").JSX.Element;
 declare const meta: {
     title: string;
     component: (props: import("./ArticleCard").ArticleCardProps) => React.JSX.Element;
+    tags: string[];
+    parameters: {
+        layout: string;
+        docs: {
+            page: typeof ArticleCardDocsPage;
+        };
+    };
+    argTypes: {
+        title: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        paragraph: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        icon: {
+            control: {
+                type: "select";
+            };
+            options: (string | undefined)[];
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        iconColor: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        iconScreenReaderText: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        tagText: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        tagColor: {
+            control: {
+                type: "select";
+            };
+            options: (string | undefined)[];
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        disabled: {
+            control: "boolean";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        onClick: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        'aria-label': {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        href: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        className: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+    };
 };
-type Story = StoryObj<typeof meta>;
-export declare const CardWithTitleAndParagraph: Story;
-export declare const CardWithTitleParagraphAndIcon: Story;
-export declare const TheEverythingCard: Story;
-export declare const CardWithTitleParagraphAndTag: Story;
-export declare const CardWithTitleAndIcon: Story;
-export declare const CardWithParagraph: Story;
-export declare const ClickableDisabledCard: Story;
-export declare const UnclickableCard: Story;
-export declare const TextOnly: Story;
-export declare const LinkedArticle: Story;
 export default meta;
+type Story = StoryObj<typeof ArticleCard>;
+export declare const Default: Story;
+export declare const Static: Story;
+export declare const WithTag: Story;
+export declare const FullComposition: Story;
+export declare const LinkedMode: Story;
+export declare const InteractiveShell: Story;
+export declare const Disabled: Story;
+export declare const LinkedDisabled: Story;
 //# sourceMappingURL=ArticleCard.stories.d.ts.map

package/dist/components/articleCard/ArticleCard.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ArticleCard.stories.d.ts","sourceRoot":"","sources":["../../../src/components/articleCard/ArticleCard.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAI5D,QAAA,MAAM,IAAI;;;CAG0B,CAAC;AAErC,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,yBAAyB,EAAE,KASvC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,KAU3C,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAY/B,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,KAW1C,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KASlC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAQ/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,KAYnC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAQ7B,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KAKtB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAgB3B,CAAC;AAEF,eAAe,IAAI,CAAC"}
+{"version":3,"file":"ArticleCard.stories.d.ts","sourceRoot":"","sources":["../../../src/components/articleCard/ArticleCard.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAW5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiF5C,iBAAS,mBAAmB,4CAmB3B;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwE0B,CAAC;AAErC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,WAAW,CAAC,CAAC;AAkD1C,eAAO,MAAM,OAAO,EAAE,KAiBrB,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,KAmCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,KAuCrB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KA6C7B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAyCxB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAuC9B,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KAyCtB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KA+B5B,CAAC"}