@arbor-education/design-system.components 0.10.0 → 0.11.1

package/.claude/figma-assessment-UKQfcxnT4rlHHNuiumt4o1-551-43094.md

@@ -0,0 +1,462 @@
+# Figma Design Feasibility Assessment
+## Design: Node 551:43094 — Daily Attendance Page
+**Written by:** Sophia Petrillo, Componentspert, age none-of-your-business
+**Fact-checked by:** Dorothy Zbornak, QA Expert
+**Date**: 2026-04-10
+
+---
+
+## What Is This Thing, Anyway?
+
+Picture it: Sicily, 1952. My Aunt Lucia was the attendance secretary at the village school. Every morning she stood at the gate with a ledger, ticking off children as they arrived. Messy, slow, and she always smelled of aniseed.
+
+THIS is what Arbor built to replace that. The Daily Attendance page is the command centre for tracking which children are in which registers, which lessons they belong to, and whether their marks have been filled. It's a full-desktop layout — 1366px wide — featuring a top navigation bar, a collapsible left sidebar, breadcrumb navigation, a page heading, a filter info bar, and a very large, very capable AG Grid data table. Nineteen distinct UI elements. Some map beautifully to our library. Some do not exist at all. Pull up a chair.
+
+---
+
+## Design Overview
+
+**Daily Attendance | Desktop 1366px** — A full application page layout for school attendance management.
+
+### UI Elements Identified
+
+- Top navigation bar (logo, nav links with dropdowns, global search, Ask Arbor AI button, user avatar dropdown, org logo)
+- Left side navigation panel (collapsible sections, active items, favorites star icons, notification badge)
+- Breadcrumbs (Students / Attendance / Registers / Daily Attendance + link icon)
+- Page heading H1 "Daily Attendance" with right-aligned primary action button
+- Filter info bar (colored square indicators + info text summary + secondary Edit button)
+- Table toolbar: Actions dropdown, Undo/Redo buttons, Hide columns dropdown
+- Table toolbar: Icon-only buttons (search, comment/message, download, settings, expand)
+- AG Grid table: checkbox selection column
+- AG Grid table: column definitions (Time, Lesson/Event, Year Group, Event Type, Teacher, Marks)
+- AG Grid table: marks status indicators cell (✓ count / ⏱ count / ✗ count)
+- AG Grid table: "(No Students)" placeholder text
+- Pagination footer (first/prev/page input/next/last + "Showing X of Y results")
+- Expand table button
+- UserDropdown (top right of nav bar)
+
+---
+
+## Section 1: What We Already Have — Use These As-Is, Don't Reinvent Them
+
+### Page Heading + Right-Aligned Action Button (`src/components/heading/Heading.tsx`)
+
+Oh, this one is a gift. `Heading` with TWO `Heading.InnerContainer` children is precisely the flex layout pattern that splits a title left and an action button right. This is not improvisation — this is the component doing exactly what it was built for.
+
+**Key features:**
+- `level={1}` → renders as `<h1>`
+- `Heading.InnerContainer` → `<span class="ds-heading__inner-container">`, one per side
+- No custom flex/justify CSS needed — `Heading` handles it
+
+**Example:**
+```tsx
+<Heading level={1}>
+  <Heading.InnerContainer>Daily Attendance</Heading.InnerContainer>
+  <Heading.InnerContainer>
+    <Button variant="primary">Button Text</Button>
+  </Heading.InnerContainer>
+</Heading>
+```
+
+---
+
+### Table — Actions Dropdown (`src/components/table/Table.tsx`)
+
+`Table.BulkActionsDropdown` was built for exactly this "Actions (0)" pattern. It reads the selected row count from `GridApiContext` internally and renders a `Button variant="dropdown"` with the count automatically.
+
+**Key features:**
+- Must be rendered INSIDE the `Table` component tree (uses `GridApiContext`)
+- Receives an `actions` array of `{ displayName, callback }` objects
+- Pass via `headerContent` prop on `Table`
+
+**Example:**
+```tsx
+<Table
+  headerContent={
+    <Table.BulkActionsDropdown
+      actions={[
+        { displayName: 'Mark Present', callback: (api) => { /* ... */ } },
+      ]}
+    />
+  }
+/>
+```
+
+---
+
+### Table — Hide Columns Dropdown (`src/components/table/Table.tsx`)
+
+`Table.HideColumnsDropdown` is purpose-built. It reads current column state from `GridApiContext` and renders a multi-select dropdown for toggling visibility. Also lives in `headerContent`.
+
+**Example:**
+```tsx
+<Table headerContent={<Table.HideColumnsDropdown />} />
+```
+
+---
+
+### Table — Pagination Footer (`src/components/table/Table.tsx`)
+
+`Table.PaginationPanel` + `Table.RowCountInfo` in `footerContent`. The "Showing X of Y results" text and all pagination controls are covered.
+
+**Key features:**
+- `Table.PaginationPanel` → first/prev/page input/next/last controls
+- `Table.RowCountInfo` → "Showing X of Y results" text
+- All use `GridApiContext` — must be inside `Table`'s tree
+- Enable pagination: `pagination={true}` + `paginationPageSize={100}` on `Table`
+
+**Example:**
+```tsx
+<Table
+  pagination={true}
+  paginationPageSize={100}
+  footerContent={
+    <>
+      <Table.RowCountInfo />
+      <Table.PaginationPanel />
+    </>
+  }
+/>
+```
+
+---
+
+### Table — AG Grid Checkbox Selection
+
+Native AG Grid. No custom component needed. Pass `checkboxSelection` and `headerCheckboxSelection` in the first column definition:
+
+```tsx
+const columnDefs = [
+  {
+    checkboxSelection: true,
+    headerCheckboxSelection: true,
+    width: 50,
+    pinned: 'left',
+  },
+  { field: 'time', headerName: 'Time' },
+  // etc.
+];
+<Table rowSelection="multiple" columnDefs={columnDefs} />
+```
+
+AG Grid Enterprise handles the indeterminate header state automatically.
+
+---
+
+### Table — Empty State "(No Students)"
+
+Native AG Grid via `noRowsOverlayComponent`:
+
+```tsx
+<Table
+  noRowsOverlayComponent={() => (
+    <span className="ds-daily-attendance__empty">No Students</span>
+  )}
+/>
+```
+
+---
+
+### Undo / Redo Toolbar Buttons (`src/components/button/Button.tsx`)
+
+`Button variant="secondary" size="S"` with verified icon names. Dorothy confirmed `'undo'` and `'redo'` BOTH exist in the allowed icons set.
+
+**Example:**
+```tsx
+<Button variant="secondary" size="S" iconLeftName="undo" iconLeftScreenReaderText="Undo" />
+<Button variant="secondary" size="S" iconLeftName="redo" iconLeftScreenReaderText="Redo" />
+```
+
+---
+
+### Icon-Only Toolbar Buttons (`src/components/button/Button.tsx`)
+
+`Button` in icon-only mode (auto-applied when `iconLeftName` is set and `children` is absent). Use `variant="tertiary"` for the toolbar ghost style. ALWAYS wrap in `TooltipWrapper` — icon-only buttons without tooltips fail WCAG 2.1 AA.
+
+**Dorothy-verified icon names:**
+- Search: `'search'` ✅
+- Download: `'download'` ✅
+- Settings: use `Table.TableSettingsDropdown` instead (see below)
+- Expand: `'expand'` ✅
+- Comment/Message: `'message-square-more'` ✅ — **`'comment'` does NOT exist**
+
+**Example:**
+```tsx
+<TooltipWrapper tooltipContent="Download">
+  <Button variant="tertiary" size="S" iconLeftName="download" iconLeftScreenReaderText="Download registers" />
+</TooltipWrapper>
+```
+
+---
+
+### Table — Settings Button (`src/components/table/Table.tsx`)
+
+`Table.TableSettingsDropdown` is the right component — not a raw icon button. It provides the settings icon trigger and the full settings panel (row spacing, borders, cell colours).
+
+```tsx
+<Table.TableSettingsDropdown onTableSettingsChanged={handleSettingsChange} />
+```
+
+---
+
+### Table — Expand Table Button
+
+`Button variant="secondary" size="S"` in the `footerContent` slot:
+
+```tsx
+footerContent={
+  <>
+    <Table.RowCountInfo />
+    <div className="ds-daily-attendance__footer-right">
+      <Table.PaginationPanel />
+      <Button variant="secondary" size="S">Expand table</Button>
+    </div>
+  </>
+}
+```
+
+---
+
+### UserDropdown — Top Right User Menu (`src/components/userDropdown/UserDropdown.tsx`)
+
+`UserDropdown` handles the entire top-right user avatar trigger, name, role, linked apps, and sign-out in one component. Use `variant="dark"` for a dark navigation bar.
+
+**Example:**
+```tsx
+<UserDropdown
+  variant="dark"
+  user={{ name: 'Amee Morris', subtitle: 'Administrator', avatarSrc: '/path/to/avatar.jpg' }}
+  onSignOut={handleSignOut}
+  logoSrc="/path/to/org-logo.png"
+  sections={[
+    {
+      label: 'Switch product',
+      items: [{ label: 'Arbor', href: '...', logo: ArborLogo }],
+    },
+  ]}
+/>
+```
+
+---
+
+## Section 2: Almost There — Minor Issues or Gotchas
+
+### Filter Info Bar
+
+**What exists:** No single `FilterInfoBar` component. `Banner` LOOKS superficially similar but is wrong here — it has rigid semantic styling (info/warning/destructive) and an opinionated layout that doesn't match the filter summary pattern.
+
+**What's needed:** A horizontal strip with colored square/circle indicators, a text summary, and a secondary action button.
+
+**The fix — compose from primitives:**
+```tsx
+<div className="ds-daily-attendance__filter-bar">
+  <Tag text="AM" color="blue" dotColour="blue" />
+  <Tag text="Internal Exclusions" color="orange" dotColour="orange" />
+  <span className="ds-daily-attendance__filter-text">
+    Select Date Wed, 05 Feb 2025 AM Showing Attendance Registers...
+  </span>
+  <Button variant="secondary" size="S" iconLeftName="pencil">Edit</Button>
+</div>
+```
+
+Note: `Tag dotColour` produces circles. If the design requires literal squares, that's a bespoke `<span>` with CSS. `'pencil'` is the correct icon name — Dorothy confirmed `'edit'` does NOT exist.
+
+**Effort:** Low — composable from primitives.
+
+---
+
+### Marks Status Indicators Cell (`src/components/icon/Icon.tsx`)
+
+**What exists:** No registered cell renderer handles the "✓ 24 ⏱ 1 ✗ 3" pattern. `dsInlineTextCellRenderer` is text-only. `dsButtonCellRenderer` renders a single button.
+
+**What's needed:** A custom `cellRenderer` component for the Marks column. This is expected AG Grid architecture.
+
+**The fix:**
+```tsx
+const MarksSummaryCellRenderer = ({ value }) => (
+  <span className="ds-daily-attendance__marks-summary">
+    <Icon name="check" size={16} color="var(--color-success-500)" />
+    <span>{value.present}</span>
+    <Icon name="clock" size={16} color="var(--color-caution-500)" />
+    <span>{value.pending}</span>
+    <Icon name="x" size={16} color="var(--color-destructive-500)" />
+    <span>{value.absent}</span>
+  </span>
+);
+
+// in columnDefs:
+{ field: 'marks', headerName: 'Marks', cellRenderer: MarksSummaryCellRenderer }
+```
+
+**Not a library gap** — this is correct pluggable AG Grid architecture. **Effort:** Low.
+
+---
+
+### Breadcrumbs
+
+**What exists:** No `Breadcrumbs` component. Must be composed from `Button variant="text-link"`, `Separator orientation="vertical"`, and semantic HTML.
+
+**The fix:**
+```tsx
+<nav aria-label="Breadcrumb">
+  <ol className="ds-daily-attendance__breadcrumbs">
+    <li><Button variant="text-link">Students</Button></li>
+    <li aria-hidden="true"><Separator orientation="vertical" decorative={true} /></li>
+    <li><Button variant="text-link">Attendance</Button></li>
+    <li aria-hidden="true"><Separator orientation="vertical" decorative={true} /></li>
+    <li><Button variant="text-link">Registers</Button></li>
+    <li aria-hidden="true"><Separator orientation="vertical" decorative={true} /></li>
+    <li><span aria-current="page">Daily Attendance</span></li>
+  </ol>
+</nav>
+```
+
+**Effort:** Low for this instance. But this pattern appears on every Arbor MIS page — it needs a library component.
+
+---
+
+## Section 3: Build It From Scratch — These Don't Exist Yet
+
+### Top Navigation Bar (Layout Shell)
+
+The layout chrome — dark background, logo slot, horizontal nav link row, layout structure — does not exist as a component. The interactive pieces ARE available (`UserDropdown`, `SearchBar`, `Button`, `Icon`) but the container shell is bespoke.
+
+**What would need building:** `TopNavigationBar` with logo slot, nav links slot, search slot, right-aligned actions slot. Nav link items are `Button` + `Dropdown` composites.
+
+**Effort:** High. Should be a shared library component, not inline page code.
+
+---
+
+### Left Side Navigation Panel
+
+No `SideNavigation` or sidebar component exists. The design shows collapsible section groups, individual nav items with active state, favourites (`'favourite-outline'` / `'favourite-filled'` — `'star'` does NOT exist per Dorothy), and notification badges.
+
+`Section` is NOT the answer — it's a page-layout card, not a slim sidebar nav item.
+
+**What would need building:** `SideNavigation` shell, `SideNavigation.Section` for collapsible groups, `SideNavigation.Item` for individual links.
+
+**Effort:** High. Single most impactful missing component for Arbor MIS page fidelity.
+
+---
+
+### Notification Badge
+
+The circular count badge overlaying nav items has no library equivalent. `Tag` is rectangular. No `Badge` component exists.
+
+**What would need building:** Small circular `Badge` component with count/dot variants and colour options. Absolute overlay or inline positioning.
+
+**Effort:** Low. Small, focused, immediately reusable across nav, avatars, icons.
+
+---
+
+## Section 4: Tricky Bits — Pay Attention Here
+
+### 1. `headerContent` Must Be Truthy for Search/Toolbar to Render
+
+Dorothy caught a critical gotcha: `TableHeader` only renders when `headerContent` is truthy. Passing `hasSearch={true}` alone does NOTHING if `headerContent` is `null`. You must pass truthy `headerContent` to get any header (including the search bar). If the design uses a custom toolbar, pass `hasSearch={false}` and wire search state yourself.
+
+### 2. `CheckboxInput` is NOT in the Public API
+
+Dorothy confirmed `CheckboxInput` and `CheckboxGroup` are NOT exported from `src/index.ts`. Use the Table's native AG Grid `checkboxSelection` for row selection (the correct approach). If standalone checkboxes are needed elsewhere on this page, raise a ticket to export these.
+
+### 3. Tooltip Every Icon-Only Button
+
+Every icon-only toolbar button MUST be wrapped in `TooltipWrapper`. WCAG 2.1 AA requirement. Not optional.
+
+### 4. Verify Icon Names Before Committing
+
+Dorothy's caught hallucinations:
+- `'comment'` → **DOES NOT EXIST** → use `'message-square-more'`
+- `'star'` → **DOES NOT EXIST** → use `'favourite-outline'` or `'favourite-filled'`
+- `'edit'` → **DOES NOT EXIST** → use `'pencil'`
+- `'ghost'` → **NOT a Button variant** → use `'tertiary'`
+
+TypeScript will catch these at compile time, but verify upfront against `src/components/icon/allowedIcons.tsx`.
+
+---
+
+## Section 5: The Verdict
+
+Picture it: Sicily, 1967. My cousin Giacomo spent three days building a barn without a blueprint. Half the walls fell down. The other half ended up where the chicken coop was supposed to go. The chickens were confused for months.
+
+Don't be Giacomo.
+
+### Is It Buildable With Our Existing Components?
+
+**Mostly YES. High confidence for the table. Bespoke work required for navigation chrome.**
+
+The data table — the heart of this page — maps almost perfectly to our `Table` component and its sub-components. AG Grid Enterprise handles the heavy lifting. Toolbar, pagination, bulk actions, settings, hide columns are all pre-built. The navigation chrome (top nav, side nav) is genuine bespoke work — but if this page lives inside an existing Arbor app shell that already renders navigation, those concerns are already solved at the host application level.
+
+### Summary Table
+
+| Design Element | Library Component | Status |
+|---|---|---|
+| Page H1 + right button | `Heading` + `Heading.InnerContainer` | ✅ Ready |
+| Actions dropdown | `Table.BulkActionsDropdown` | ✅ Ready |
+| Undo/Redo buttons | `Button` with `iconLeftName="undo/redo"` | ✅ Ready |
+| Hide columns | `Table.HideColumnsDropdown` | ✅ Ready |
+| Settings button | `Table.TableSettingsDropdown` | ✅ Ready |
+| Icon toolbar buttons | `Button` icon-only + `TooltipWrapper` | ✅ Ready |
+| Checkbox column | AG Grid native `checkboxSelection` | ✅ Ready |
+| Column definitions | AG Grid `columnDefs` | ✅ Ready |
+| Empty state "(No Students)" | `noRowsOverlayComponent` prop | ✅ Ready |
+| Pagination | `Table.PaginationPanel` + `Table.RowCountInfo` | ✅ Ready |
+| Expand table button | `Button variant="secondary"` | ✅ Ready |
+| UserDropdown | `UserDropdown variant="dark"` | ✅ Ready |
+| Filter info bar | Compose: `Tag` + `Button` + layout | 🔧 Minor work |
+| Marks status cell | Custom `cellRenderer` with `Icon` | 🔧 Minor work |
+| Breadcrumbs | Compose: `Button text-link` + `Separator` + semantic HTML | 🔧 Minor work |
+| Top navigation bar | `UserDropdown`/`SearchBar`/`Button` for parts; chrome is bespoke | 🆕 New component |
+| Side navigation panel | No equivalent exists | 🆕 New component |
+| Notification badge | No `Badge` component exists | 🆕 New component |
+
+### What Actually Needs Work
+
+| Item | Where It Lives | Effort |
+|---|---|---|
+| Marks status cell renderer | Page-level component | Low |
+| Breadcrumbs (this instance) | Page-level composition | Low |
+| Filter info bar | Page-level composition | Low |
+| Breadcrumbs (library component) | New library component | Medium |
+| Notification Badge component | New library component | Low |
+| Top Navigation Bar | New library component (or host app) | High |
+| Side Navigation Panel | New library component (or host app) | High |
+
+### Summary Verdict
+
+**12 out of 18 elements** can be built directly with current library components. 3 elements need minor composition work (filter bar, breadcrumbs instance, marks cell renderer). 3 require new library components (top nav, side nav, notification badge).
+
+**Recommendation:** Highly feasible for the table and content area. The data table is essentially already built. The navigation chrome gaps are structural — either build as shared library components (high value, high effort) or deliver inside the host app's existing nav shell.
+
+---
+
+## Appendix: Files Referenced in This Assessment
+
+*Every file Dorothy read to verify claims. This assessment is grounded in actual source code.*
+
+- `src/index.ts`
+- `src/components/table/Table.tsx`
+- `src/components/table/TableHeader.tsx`
+- `src/components/table/useTableSettings.ts`
+- `src/components/table/BulkActionsDropdown.tsx`
+- `src/components/table/HideColumnsDropdown.tsx`
+- `src/components/button/Button.tsx`
+- `src/components/heading/Heading.tsx`
+- `src/components/section/Section.tsx`
+- `src/components/banner/Banner.tsx`
+- `src/components/icon/Icon.tsx`
+- `src/components/icon/allowedIcons.tsx`
+- `src/components/dropdown/Dropdown.tsx`
+- `src/components/dropdown/DropdownTrigger.tsx`
+- `src/components/dropdown/DropdownContent.tsx`
+- `src/components/dropdown/items/DropdownItem.tsx`
+- `src/components/dropdown/items/DropdownSelectItem.tsx`
+- `src/components/dropdown/items/DropdownGroup.tsx`
+- `src/components/searchBar/SearchBar.tsx`
+- `src/components/pill/Pill.tsx`
+- `src/components/tag/Tag.tsx`
+
+---
+
+*Analysis by Sophia Petrillo, Componentspert 👜, fact-checked by Dorothy Zbornak 🔍*
+*Powered by Claude Code 🐺*