@arbor-education/design-system.components 0.25.9 → 1.0.0

package/.gather/instructions/project-overview.md

@@ -186,7 +186,7 @@ These rules are non-negotiable. Read CONTRIBUTING.md for the full rationale.
 | 400–800                         | STOP — write a justification in the PR description, confirm with human |
 | > 800                           | STOP — split the PR before continuing                                  |
 
-Generated files, `yarn.lock`, and auto-generated types do NOT count toward these limits.
+Generated files, `yarn.lock`, auto-generated types, test files, Storybook stories, and SVGs do NOT count toward these limits. The limit is meant to flag changes that need careful behavioural review — focus it on user-facing or behaviour-altering code.
 
 ### Quality gates — all must pass before opening a PR
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- [#232](https://github.com/arbor-education/design-system.components/pull/232) [`a87b25b`](https://github.com/arbor-education/design-system.components/commit/a87b25bb585eb168f0ec8f6b7fa2b0ca4e79027a) Thanks [@AmeeMorris](https://github.com/AmeeMorris)! - MIS-72902 version 1.0.0! docs change around how we're using proper SemVer now
+
+### Minor Changes
+
+- [#215](https://github.com/arbor-education/design-system.components/pull/215) [`c0f59ca`](https://github.com/arbor-education/design-system.components/commit/c0f59ca99b1ce24e2ad96541fdaf0c9479e9ddd6) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - MIS-70550 ✨ make pill component controllable
+
+- [#206](https://github.com/arbor-education/design-system.components/pull/206) [`605f38f`](https://github.com/arbor-education/design-system.components/commit/605f38f40a041a76074937a89ae504f0d1dffe7e) Thanks [@danielpeplow](https://github.com/danielpeplow)! - MIS-71695 — Arrival of several 'Widgets' including a compound `Widget` used as the base for other Widgets. Also a reusable `EmptyState` component. Other Widgets include `WidgetFavourites`, `WidgetNotifications`, and `WidgetCalendar`. Created a reusable FavouriteButton that is now shared between Sidebar Nav and the Favourites Widget items.
+
+- [#228](https://github.com/arbor-education/design-system.components/pull/228) [`7d55ecd`](https://github.com/arbor-education/design-system.components/commit/7d55ecdc0410825e2c05f6b9bc0597fd9c4fb188) Thanks [@Alex-DN-SP](https://github.com/Alex-DN-SP)! - MIS-71902 Split Sidebar from side navigation and refactored
+
 ## 0.25.9
 
 ### Patch Changes

package/CONTRIBUTING.md

@@ -37,7 +37,7 @@ Small PRs get reviewed faster, get merged sooner, and carry far lower bug risk.
 
 ### What counts as "lines changed"?
 
-Generated files, lockfiles (`yarn.lock`), and auto-generated type definitions do not count. Focus on the meaningful code diff.
+Generated files, lockfiles (`yarn.lock`), auto-generated type definitions, test files, Storybook stories, and SVGs do not count. The limit exists to flag changes that need careful behavioural review, so focus it on user-facing or behaviour-altering code — not the tests, stories, and icon markup that surround it.
 
 ### How to split a large PR
 
@@ -197,11 +197,13 @@ See [CLAUDE.md](./CLAUDE.md) for the definitive reference. In summary:
 
 ## A Note on Versioning
 
-Generally we use semantic versioning (https://semver.org/), however, we are reserving version 1.0.0 for the first wide release of this project. Therefore, in the mean time, we follow the following convention with regards to change levels:
+This project follows semantic versioning (https://semver.org/). Given a version number `MAJOR.MINOR.PATCH`, change levels are determined as follows:
 
-- Major version bumps are reserved for the first wide release
-- Minor version bumps are for breaking changes
-- Patch version bumps are for all other changes (including added functionality)
+- **Major** version bumps are for breaking changes — anything that requires consumers to change their code (e.g. removing or renaming a prop, changing a component's default behaviour, dropping support for a peer dependency version)
+- **Minor** version bumps are for new, backwards-compatible functionality (e.g. a new component, a new optional prop, a new variant)
+- **Patch** version bumps are for backwards-compatible bug fixes and other non-breaking changes that don't add functionality (e.g. style fixes, accessibility fixes, dependency updates)
+
+When creating a changeset (`yarn changeset`), select the change level that matches the impact on consumers, not the size of the code change.
 
 ---
 

package/component-library.md

@@ -23,7 +23,8 @@ File: `src/tokens.scss` — Auto-generated CSS custom properties on `:root`.
 | **Chart colors** | red, blue, teal, green, orange, purple, yellow (1–4 variants each) |
 | **Extended colors** | blue, teal, green, orange, purple, salmon, yellow (050/100/500/800) |
 | **Gradient ramps** | diverging and sequential ramps (050–900) |
-| **Shadow** | `--shadow-small` |
+| **Shadow** | `--shadow-small`, `--shadow-medium` |
+| **Layers** | `--z-index-popup` (1), `--z-index-toast` (10) |
 | **Icon sizes** | `--icon-size-xsmall` (12px), `--icon-size-small` (16px), `--icon-size-medium` (24px) |
 | **Focus** | `--focus-color-focus: var(--color-brand-500)`, `--focus-border: 3px` |
 | **Avatar sizes** | `--avatar-small-size` (1.25rem), `--avatar-medium-size` (2rem), `--avatar-large-size` (3rem), `--avatar-extra-large-size` (6rem) |
@@ -875,6 +876,98 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 
 ---
 
+### 26a. EmptyState
+
+**File:** `src/components/emptyState/EmptyState.tsx` · **Public export:** Yes
+
+**Use case:** Centered empty-state layout for zero-data views. Supports optional illustration, heading, subheading, and a consumer-composed `actions` slot.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `ReactNode` | Yes | — | Primary heading text |
+| `subHeading` | `ReactNode` | No | — | Supporting description |
+| `illustration` | `ReactNode` | No | — | Decorative icon or image |
+| `orientation` | `'horizontal' \| 'vertical'` | No | `'horizontal'` | Action layout |
+| `actions` | `ReactNode` | No | — | Action buttons |
+| `live` | `boolean` | No | `false` | Sets `aria-live="polite"` when content updates dynamically |
+| `headingLevel` | `1 \| 2 \| 3 \| 4` | No | `4` | HTML heading level (default suits nested use inside `Widget`) |
+| `padding` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | No | `'md'` | Container padding |
+
+**Key features:**
+- Renders as `<section role="region">` with `aria-labelledby` pointing at the heading
+- Default `headingLevel` is `4` so nested use inside `Widget` (`h3` header) preserves document outline order
+
+---
+
+### 26b. Widget
+
+**File:** `src/components/widget/Widget.tsx` · **Public export:** Yes
+**Public types:** `Widget.Props`, `Widget.HeaderProps`, `Widget.BodyProps`, `Widget.RenderLinkArgs`, `Widget.LinkedProps`, `Widget.CollapsibleProps`, `Widget.StaticProps`
+
+**Use case:** Compound dashboard widget wrapping `Card` with header/body composition, optional link navigation, collapsible body, tooltip, and built-in loading/empty/busy body states.
+
+**Compound components:**
+
+| Sub-component | Description |
+|---|---|
+| `Widget` (root) | Card shell + context provider for state and header modes |
+| `Widget.Header` | Title row (`Heading` level `3`) with `slotStart`, `slotEnd`, heading, optional tooltip icon, and end chevron when linked |
+| `Widget.Body` | Main content; respects root loading/empty/busy flags |
+
+**Root props (common):**
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `tooltip` | `string` | No | — | Renders info icon + `TooltipWrapper` beside heading |
+| `isLoading` | `boolean` | No | `false` | Replaces body with loading indicator |
+| `isEmpty` | `boolean` | No | `false` | Renders `emptyState` instead of body children |
+| `emptyState` | `ReactNode` | No | — | Content when `isEmpty` (typically `<EmptyState />`) |
+| `isFloating` | `boolean` | No | `false` | Applies permanent `--shadow-medium` elevation |
+| `collapsible` | `boolean` | No | `false` | Makes header a collapse toggle (**mutually exclusive with `href`**) |
+
+**Linked variant:** `href` (required) + optional `renderLink` + `linkProps`. Auto-injects `chevron-right` at header end alongside optional `slotEnd`.
+
+**Invalid combination:** `href` + `collapsible: true` — TypeScript error plus dev runtime throw.
+
+---
+
+### 26c. WidgetFavourites
+
+**File:** `src/components/widgetFavourites/WidgetFavourites.tsx` · **Public export:** Yes
+**Also exports:** `WidgetFavourites.Item` compound component; types via `WidgetFavourites.Props`, `WidgetFavourites.ItemData`
+
+**Use case:** Pre-composed favourites dashboard widget — wraps `Widget` with a linked-item list where each row navigates via `href` and exposes a remove button when `onRemoveItem` is provided.
+
+**Props:**
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `ReactNode` | Yes | — | Widget header title |
+| `items` | `WidgetFavouritesItemData[]` | Yes | — | Favourite rows (`id`, `label`, `href`, optional `removeLabel`) |
+| `onRemoveItem` | `(id: string) => void` | No | — | Shows remove button; parent handles confirm/undo |
+| `emptyState` | `ReactNode` | No | built-in `EmptyState` | Shown when `items` is empty |
+
+**Item fields:** `id`, `label`, `href`, optional `removeLabel` (defaults to `FAVOURITE_TOOLTIP.remove`).
+
+**Shared utilities:** `FAVOURITE_*`, `getFavouriteTooltip`, `getFavouriteRemovedToastMessage`.
+
+**Key features:**
+- Remove button uses shared internal `FavouriteButton` with tooltip and `aria-label`
+- Override per-row tooltip via `items[].removeLabel`
+- Row link and remove button are siblings — remove does not nest inside the link
+
+### 26d. WidgetNotifications
+
+**File:** `src/components/widgetNotifications/WidgetNotifications.tsx` · **Public export:** Yes
+
+**Use case:** Pre-composed notifications dashboard widget with mark-all-as-read header action, read/unread row styling, clear buttons, and `<time>` timestamps.
+
+**Props:** `heading`, `items`, optional `onItemClick`, `onClearItem`, `onMarkAllAsRead`, `markAllAsReadLabel`, `emptyState`, `isFloating`, `tooltip`.
+
+**Item fields:** `id`, `title`, `description`, `dateTime` (ISO), `timeLabel`, `isRead`, `clearLabel`.
+
+---
+
 ### 27. Separator
 
 **File:** `src/components/separator/Separator.tsx` · **Public export:** Yes
@@ -1053,10 +1146,11 @@ Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--butt
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `variant` | `'information' \| 'danger' \| 'success' \| 'warning'` | No | `'information'` | Semantic variant |
-| `children` | `ReactNode` | No | — | Toast message content |
+| `toastContent` | `ReactNode` | Yes | — | Toast message content (rendered as `Toast.Title`) |
+| `toastActions` | `ReactNode` | No | — | Optional action controls (typically `Toast.Action`) |
 | `...rest` | `RadixToast.ToastProps` | No | — | Radix props (e.g. `open`, `onOpenChange`, `duration`) |
 
-**Static members:** `Toast.Provider`, `Toast.Viewport`
+**Static members:** `Toast.Provider`, `Toast.Viewport`, `Toast.Action`
 
 **Variant icon map:** `information` → `info`, `danger` → `circle-alert`, `success` → `circle-check`, `warning` → `triangle-alert`
 

package/dist/components/emptyState/EmptyState.d.ts

@@ -0,0 +1,22 @@
+import { Heading } from '../heading/Heading.js';
+import { type HTMLAttributes } from 'react';
+export type EmptyStatePadding = 'none' | 'xs' | 'sm' | 'md' | 'lg';
+export type EmptyStateHeadingLevel = Heading.Level;
+export type EmptyStateProps = {
+    heading: React.ReactNode;
+    subHeading?: React.ReactNode;
+    illustration?: React.ReactNode;
+    orientation?: 'horizontal' | 'vertical';
+    actions?: React.ReactNode;
+    live?: boolean;
+    headingLevel?: EmptyStateHeadingLevel;
+    padding?: EmptyStatePadding;
+    className?: string;
+} & Omit<HTMLAttributes<HTMLElement>, 'children'>;
+export declare const EmptyState: (props: EmptyStateProps) => React.JSX.Element;
+export declare namespace EmptyState {
+    type Props = EmptyStateProps;
+    type Padding = EmptyStatePadding;
+    type HeadingLevel = EmptyStateHeadingLevel;
+}
+//# sourceMappingURL=EmptyState.d.ts.map

package/dist/components/emptyState/EmptyState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../../../src/components/emptyState/EmptyState.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAS,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACnE,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,KAAK,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACxC,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;AAElD,eAAO,MAAM,UAAU,GAAI,OAAO,eAAe,KAAG,KAAK,CAAC,GAAG,CAAC,OA0D7D,CAAC;AAEF,yBAAiB,UAAU,CAAC;IAC1B,KAAY,KAAK,GAAG,eAAe,CAAC;IACpC,KAAY,OAAO,GAAG,iBAAiB,CAAC;IACxC,KAAY,YAAY,GAAG,sBAAsB,CAAC;CACnD"}

package/dist/components/emptyState/EmptyState.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import classNames from 'classnames';
+import { Heading } from '../heading/Heading.js';
+import { useId } from 'react';
+export const EmptyState = (props) => {
+    const { heading, subHeading, illustration, orientation = 'horizontal', actions, live = false, headingLevel = 4, padding = 'md', className, ...rest } = props;
+    const headingId = useId();
+    const hasActions = Boolean(actions);
+    return (_jsxs("section", { role: "region", "aria-live": live ? 'polite' : undefined, "aria-labelledby": headingId, className: classNames('ds-empty-state', padding !== 'none' && `ds-empty-state--padding-${padding}`, className), ...rest, children: [illustration && (_jsx("div", { className: "ds-empty-state__illustration", "aria-hidden": "true", children: illustration })), _jsx(Heading, { id: headingId, level: headingLevel, className: "ds-empty-state__heading", children: heading }), subHeading && (_jsx("p", { className: "ds-empty-state__sub-heading", children: subHeading })), hasActions && (_jsx("div", { className: classNames('ds-empty-state__actions', `ds-empty-state__actions--${orientation}`), children: actions }))] }));
+};
+//# sourceMappingURL=EmptyState.js.map

package/dist/components/emptyState/EmptyState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyState.js","sourceRoot":"","sources":["../../../src/components/emptyState/EmptyState.tsx"],"names":[],"mappings":";AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,KAAK,EAAuB,MAAM,OAAO,CAAC;AAiBnD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAsB,EAAqB,EAAE;IACtE,MAAM,EACJ,OAAO,EACP,UAAU,EACV,YAAY,EACZ,WAAW,GAAG,YAAY,EAC1B,OAAO,EACP,IAAI,GAAG,KAAK,EACZ,YAAY,GAAG,CAAC,EAChB,OAAO,GAAG,IAAI,EACd,SAAS,EACT,GAAG,IAAI,EACR,GAAG,KAAK,CAAC;IAEV,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;IAC1B,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpC,OAAO,CACL,mBACE,IAAI,EAAC,QAAQ,eACF,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,qBACrB,SAAS,EAC1B,SAAS,EAAE,UAAU,CACnB,gBAAgB,EAChB,OAAO,KAAK,MAAM,IAAI,2BAA2B,OAAO,EAAE,EAC1D,SAAS,CACV,KACG,IAAI,aAEP,YAAY,IAAI,CACf,cAAK,SAAS,EAAC,8BAA8B,iBAAa,MAAM,YAC7D,YAAY,GACT,CACP,EACD,KAAC,OAAO,IACN,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,YAAY,EACnB,SAAS,EAAC,yBAAyB,YAElC,OAAO,GACA,EACT,UAAU,IAAI,CACb,YAAG,SAAS,EAAC,6BAA6B,YACvC,UAAU,GACT,CACL,EACA,UAAU,IAAI,CACb,cACE,SAAS,EAAE,UAAU,CACnB,yBAAyB,EACzB,4BAA4B,WAAW,EAAE,CAC1C,YAEA,OAAO,GACJ,CACP,IACO,CACX,CAAC;AACJ,CAAC,CAAC"}

package/dist/components/emptyState/EmptyState.stories.d.ts

@@ -0,0 +1,117 @@
+import type { StoryObj } from '@storybook/react-vite';
+import { EmptyState } from './EmptyState.js';
+import type { ComponentProps } from 'react';
+declare function EmptyStateDocsPage(): import("react/jsx-runtime").JSX.Element;
+declare const meta: {
+    title: string;
+    component: (props: import("./EmptyState.js").EmptyStateProps) => React.JSX.Element;
+    parameters: {
+        layout: string;
+        docs: {
+            page: typeof EmptyStateDocsPage;
+        };
+    };
+    tags: string[];
+    argTypes: {
+        heading: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        subHeading: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        padding: {
+            control: "select";
+            options: string[];
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        orientation: {
+            control: "radio";
+            options: string[];
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        live: {
+            control: "boolean";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        headingLevel: {
+            control: {
+                type: "select";
+            };
+            options: number[];
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        illustration: {
+            control: false;
+        };
+        actions: {
+            control: false;
+        };
+        className: {
+            control: false;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof EmptyState>;
+export declare const Default: {
+    args: {
+        heading: string;
+        subHeading: string;
+        orientation: string;
+        live: boolean;
+        headingLevel: number;
+        padding: string;
+    };
+    render: (args: ComponentProps<typeof EmptyState>) => import("react/jsx-runtime").JSX.Element;
+};
+export declare const WithoutIllustrationTwoActions: Story;
+export declare const WithoutIllustrationTertiaryAction: Story;
+export declare const WithIllustrationNoActions: Story;
+export declare const WithInlineLinkInSubHeading: Story;
+export declare const PaddingVariants: Story;
+export declare const InsideWidget: Story;
+//# sourceMappingURL=EmptyState.stories.d.ts.map

package/dist/components/emptyState/EmptyState.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyState.stories.d.ts","sourceRoot":"","sources":["../../../src/components/emptyState/EmptyState.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAa5D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AA8E5C,iBAAS,kBAAkB,4CAmB1B;AAED,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DyB,CAAC;AAEpC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,UAAU,CAAC,CAAC;AAwGzC,eAAO,MAAM,OAAO;;;;;;;;;mBASH,cAAc,CAAC,OAAO,UAAU,CAAC;CAUjD,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,KAiC3C,CAAC;AAEF,eAAO,MAAM,iCAAiC,EAAE,KAgC/C,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,KAiCvC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,KAgCxC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAQ7B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAoC1B,CAAC"}