@arbor-education/design-system.components 3.2.0 → 3.3.0

package/dist/components/widgetCalendar/WidgetCalendar.stories.d.ts

@@ -1,4 +1,5 @@
 import type { StoryObj } from '@storybook/react-vite';
+import { WidgetCalendar } from './WidgetCalendar.js';
 declare function WidgetCalendarDocsPage(): import("react").JSX.Element;
 declare const meta: {
     title: string;
@@ -33,28 +34,99 @@ declare const meta: {
         };
     };
     tags: string[];
-    args: {
-        heading: string;
-        isFloating: true;
+    argTypes: {
+        heading: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        tooltip: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        headingHref: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
         items: {
-            id: string;
-            eventType?: import("./WidgetCalendarItem.js").WidgetCalendarEventType;
-            eventPrimaryTerm: React.ReactNode;
-            eventPrimaryDefinition: React.ReactNode;
-            eventSecondaryTerm: React.ReactNode;
-            eventDateTime: string;
-            eventTimeLabel: string;
-            eventLocation?: string;
-            eventSecondaryDefinition?: React.ReactNode;
-            buttonA11yText?: string;
-        }[];
-        onItemClick: import("vitest").Mock<(...args: any[]) => any>;
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        isFloating: {
+            control: "boolean";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        onItemClick: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        emptyState: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        className: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
     };
 };
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof WidgetCalendar>;
 export declare const Default: Story;
+export declare const Interactive: Story;
+export declare const PrimaryEventType: Story;
+export declare const SecondaryEventType: Story;
+export declare const NonInteractiveItems: Story;
+export declare const WithoutLocation: Story;
+export declare const CustomSecondaryContent: Story;
+export declare const WithTooltip: Story;
 export declare const Empty: Story;
+export declare const CustomEmptyState: Story;
 export declare const FixedHeightOverflow: Story;
 export declare const Composable: Story;
 //# sourceMappingURL=WidgetCalendar.stories.d.ts.map

package/dist/components/widgetCalendar/WidgetCalendar.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetCalendar.stories.d.ts","sourceRoot":"","sources":["../../../src/components/widgetCalendar/WidgetCalendar.stories.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAuF5D,iBAAS,sBAAsB,gCAa9B;AA2DD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc6B,CAAC;AAExC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAMrB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAMnB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,KAMjC,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KA4BxB,CAAC"}
+{"version":3,"file":"WidgetCalendar.stories.d.ts","sourceRoot":"","sources":["../../../src/components/widgetCalendar/WidgetCalendar.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAa5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA0JrD,iBAAS,sBAAsB,gCAmB9B;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiF6B,CAAC;AAExC,eAAe,IAAI,CAAC;AAGpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,cAAc,CAAC,CAAC;AA0G7C,eAAO,MAAM,OAAO,EAAE,KAgBrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAsCzB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KA6B9B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,KA6BhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,KA6BjC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAwB7B,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,KA0BpC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAoBzB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAUnB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAiB9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,KAmBjC,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAkDxB,CAAC"}

package/dist/components/widgetCalendar/WidgetCalendar.stories.js

@@ -1,8 +1,12 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Controls, Heading as DocHeading, Primary as DocPrimary, Markdown, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
 import { Widget } from '../widget/Widget.js';
 import { fn } from 'storybook/test';
 import { WidgetCalendar } from './WidgetCalendar.js';
+// ---------------------------------------------------------------------------
+// Fixture data
+// ---------------------------------------------------------------------------
 const classEventTime = {
     eventSecondaryTerm: 'Time and location',
     eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
@@ -76,24 +80,181 @@ const overflowItems = [
     ...initialItems,
     ...initialItems.map((item, index) => ({ ...item, id: `${item.id}-overflow-${index}` })),
 ];
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
 const DESCRIPTION_INTRO = [
-    '`WidgetCalendar` is a pre-composed dashboard widget for upcoming calendar events.',
-    'It wraps [`Widget`](?path=/docs/components-widget--docs) with event rows, type indicators, and optional navigation.',
-    'Pass ISO `eventDateTime` and a formatted `eventTimeLabel` for each item — the component renders a semantic `<time>` element, matching the pattern used by `WidgetNotifications`.',
-].join(' ');
+    '`WidgetCalendar` is a pre-composed dashboard widget for date/time-anchored calendar events.',
+    'It wraps [`Widget`](?path=/docs/components-widget--docs) with an event list, primary/secondary type indicators, and',
+    'optional heading navigation. Each item renders a semantic `<time>` element from an ISO `eventDateTime` and a',
+    'human-readable `eventTimeLabel`.',
+].join('\n');
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- Date/time-anchored list items — events, appointments, or timetable entries — that need a semantic `<time>` element',
+    '- Optional location context alongside the time (classroom, hall, room number)',
+    '- A dashboard widget where rows may optionally navigate somewhere on click',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Situation | Use instead |',
+    '|---|---|',
+    '| Favourite/shortcut links with no date fields, needing a remove action | [`WidgetFavourites`](?path=/docs/components-widget-widgetfavourites--docs) (link + remove pattern) |',
+    '| Read/unread notification feed with a mark-all-as-read action | [`WidgetNotifications`](?path=/docs/components-widget-widgetnotifications--docs) |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**`onItemClick` signature differs between `WidgetCalendar` and `WidgetCalendar.Item`.** The parent\'s',
+    '`onItemClick` is `(id: string) => void` — it receives the clicked item\'s id. `WidgetCalendar.Item`\'s own',
+    '`onItemClick` prop takes **no arguments** (`() => void`). When composing manually (see the Composable',
+    'story), you must close over the id yourself: `onItemClick={() => handleClick(item.id)}`.',
+    '',
+    '**`buttonA11yText` fallback only fires for plain strings.** When `onItemClick` makes a row interactive,',
+    'the accessible label defaults to `Open ${eventPrimaryDefinition}` — but only when `eventPrimaryDefinition`',
+    'is a plain string. Pass a JSX node as the primary definition and the fallback silently degrades to the',
+    'generic `\'Open event\'`. Always supply `buttonA11yText` explicitly when `eventPrimaryDefinition` is rich content.',
+    '',
+    '**`eventSecondaryDefinition` is an all-or-nothing override.** When provided, it entirely replaces the',
+    'default time + location composition — `eventLocation` becomes dead data with no warning. Never pass both',
+    'in the same item.',
+    '',
+    '**The type-bar colour is semantic, not decorative.** `eventType="primary"` renders the brand-green bar',
+    '(`--widget-calendar-type-primary-color`), `"secondary"` renders neutral grey',
+    '(`--widget-calendar-type-secondary-color`). Choose deliberately — don\'t treat it as a purely visual toggle.',
+    '',
+    '**No loading, disabled, or error state exists on this component.** Handle those states in the consumer',
+    '(e.g. render a Skeleton in place of `WidgetCalendar` while data loads).',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- Each item renders a `<dl>` with `sr-only` `<dt>` terms and visible `<dd>` definitions, pairing both the',
+    '  primary and secondary content for screen readers.',
+    '- `eventDateTime` must be a valid ISO datetime string — it is passed directly to the `<time dateTime>` attribute.',
+    '- Interactive rows (`onItemClick` provided) get `role="button"`, `tabIndex={0}`, and respond to both',
+    '  Enter and Space, matching the standard button-role keyboard contract.',
+    '- Rows without `onItemClick` render as plain, non-interactive `<li>` elements — no button semantics are added.',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Widget](?path=/docs/components-widget--docs) · [WidgetFavourites](?path=/docs/components-widget-widgetfavourites--docs) · [WidgetNotifications](?path=/docs/components-widget-widgetnotifications--docs)',
+].join('\n');
 function WidgetCalendarDocsPage() {
-    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
 }
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+const meta = {
+    title: 'Components/Widget/WidgetCalendar',
+    component: WidgetCalendar,
+    parameters: {
+        layout: 'padded',
+        docs: {
+            page: WidgetCalendarDocsPage,
+        },
+    },
+    tags: ['autodocs'],
+    argTypes: {
+        heading: {
+            control: 'text',
+            description: 'Content rendered in the widget header. Usually a plain string, but accepts any `React.ReactNode`.',
+            table: {
+                type: { summary: 'React.ReactNode' },
+            },
+        },
+        tooltip: {
+            control: 'text',
+            description: 'Optional tooltip text shown alongside the heading, for supplementary context.',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        headingHref: {
+            control: 'text',
+            description: 'When provided, renders the heading as a link to this URL (e.g. a full calendar page).',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        items: {
+            control: false,
+            description: [
+                'Array of `WidgetCalendar.ItemData` objects rendered as event rows. Each item requires `id`,',
+                '`eventPrimaryTerm`, `eventPrimaryDefinition`, `eventSecondaryTerm`, `eventDateTime`, and `eventTimeLabel`.',
+                '`eventType`, `eventLocation`, `eventSecondaryDefinition`, and `buttonA11yText` are optional.',
+            ].join(' '),
+            table: {
+                type: { summary: 'WidgetCalendar.ItemData[]' },
+            },
+        },
+        isFloating: {
+            control: 'boolean',
+            description: 'Applies the floating (elevated/shadowed) widget style. Defaults to `false`.',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        onItemClick: {
+            control: false,
+            description: [
+                'Called with the clicked item\'s `id` when a row is activated (click, Enter, or Space).',
+                'Rows with no `onItemClick` render as plain, non-interactive list items.',
+            ].join(' '),
+            table: {
+                type: { summary: '(id: string) => void' },
+            },
+        },
+        emptyState: {
+            control: false,
+            description: [
+                'Custom content rendered in place of the event list when `items` is empty.',
+                'Defaults to a built-in EmptyState with a date icon, "Nothing scheduled" heading, and',
+                '"There are no upcoming events." sub-heading.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+                defaultValue: { summary: 'Built-in EmptyState ("Nothing scheduled")' },
+            },
+        },
+        className: {
+            control: false,
+            description: 'Additional CSS class names on the root Widget element. Use sparingly.',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 const withDescription = (story, description) => ({
     ...story,
     parameters: {
         ...story.parameters,
         docs: {
             ...story.parameters?.docs,
-            description: { story: description },
+            description: {
+                story: description,
+            },
         },
     },
 });
+// ---------------------------------------------------------------------------
+// Template components for composition and stateful stories.
+// Named components avoid react-hooks lint issues — the react-hooks ESLint
+// plugin is NOT configured in this project, so do NOT add eslint-disable.
+// ---------------------------------------------------------------------------
 function FixedHeightWidgetContainer({ children, height = 280, }) {
     return (_jsx("div", { style: {
             height,
@@ -102,39 +263,291 @@ function FixedHeightWidgetContainer({ children, height = 280, }) {
             border: '1px dashed var(--color-grey-300)',
         }, children: children }));
 }
-const DefaultTemplate = () => (_jsx(WidgetCalendar, { heading: "Calendar", headingHref: "/calendar", isFloating: true, items: initialItems, onItemClick: fn() }));
-const EmptyTemplate = () => (_jsx(WidgetCalendar, { heading: "Calendar", isFloating: true, items: [] }));
-const FixedHeightOverflowTemplate = () => (_jsx(FixedHeightWidgetContainer, { children: _jsx(WidgetCalendar, { heading: "Calendar", isFloating: true, items: overflowItems, onItemClick: fn() }) }));
-const meta = {
-    title: 'Components/Widget/WidgetCalendar',
-    component: WidgetCalendar,
-    parameters: {
-        layout: 'padded',
-        docs: { page: WidgetCalendarDocsPage },
-    },
-    tags: ['autodocs'],
+const InteractiveTemplate = () => {
+    const [lastClickedId, setLastClickedId] = useState(null);
+    const lastClickedLabel = lastClickedId
+        ? initialItems.find(item => item.id === lastClickedId)?.eventPrimaryDefinition
+        : null;
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(WidgetCalendar, { heading: "Calendar", isFloating: true, items: initialItems, onItemClick: setLastClickedId }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: lastClickedLabel
+                    ? (_jsxs(_Fragment, { children: ["Last clicked:", ' ', lastClickedLabel] }))
+                    : 'Click an event to see its id captured here.' })] }));
+};
+const handleComposableItemClick = fn();
+const ComposableTemplate = () => (_jsxs(Widget, { isFloating: true, children: [_jsx(Widget.Header, { children: "Calendar" }), _jsx(Widget.Body, { children: _jsx("ul", { className: "ds-widget-calendar__list", children: initialItems.slice(0, 2).map(item => (_jsx(WidgetCalendar.Item, { id: item.id, eventType: item.eventType, eventPrimaryTerm: item.eventPrimaryTerm, eventPrimaryDefinition: item.eventPrimaryDefinition, eventSecondaryTerm: item.eventSecondaryTerm, eventDateTime: item.eventDateTime, eventTimeLabel: item.eventTimeLabel, eventLocation: item.eventLocation, onItemClick: () => handleComposableItemClick(item.id) }, item.id))) }) })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
         heading: 'Calendar',
+        headingHref: '/calendar',
         isFloating: true,
         items: initialItems,
         onItemClick: fn(),
     },
-};
-export default meta;
-export const Default = withDescription({
-    render: DefaultTemplate,
+    render: args => _jsx(WidgetCalendar, { ...args }),
+}, [
+    'The interactive canvas — every prop is wired to the Controls panel below.',
+    'A linked header, floating style, a realistic mix of primary (green) and secondary (grey) event types,',
+    'and clickable rows. This is the only story where combining every prop together is the point.',
+].join(' '));
+export const Interactive = withDescription({
+    render: InteractiveTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { WidgetCalendar } from '@arbor-education/design-system.components';
+
+function InteractiveCalendarExample() {
+  const [lastClickedId, setLastClickedId] = useState<string | null>(null);
+
+  return (
+    <>
+      <WidgetCalendar
+        heading="Calendar"
+        isFloating
+        items={items}
+        onItemClick={setLastClickedId}
+      />
+      <span>Last clicked id: {lastClickedId ?? 'none yet'}</span>
+    </>
+  );
+}
+export default InteractiveCalendarExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'Demonstrates `onItemClick(id)` behaviourally: clicking a row calls back with that item\'s `id`,',
+    'tracked here in a named template component\'s `useState` and displayed below the widget as',
+    '"Last clicked: {label}". In a real consumer, use the id to navigate or open a detail view.',
+].join(' '));
+export const PrimaryEventType = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [
+            {
+                id: 'year-10-10g',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Year 10: 10G',
+                ...classEventTime,
+            },
+            {
+                id: 'maths-year-10',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Maths: Year 10: 10x/Ma3',
+                ...classEventTime,
+            },
+        ],
+        onItemClick: fn(),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
     parameters: { controls: { disable: true } },
-}, 'Linked header with primary (green) and secondary (grey) event type indicators. Rows are keyboard-focusable when `onItemClick` is provided.');
+}, [
+    'Isolates `eventType="primary"` — the brand-green type bar. This is also the default when',
+    '`eventType` is omitted entirely.',
+].join(' '));
+export const SecondaryEventType = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [
+            {
+                id: 'class-generic',
+                eventType: 'secondary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Class',
+                ...classEventTime,
+            },
+            {
+                id: 'class-generic-2',
+                eventType: 'secondary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Class',
+                eventDateTime: '2026-06-08T10:15/2026-06-08T11:00',
+                eventTimeLabel: '10:15 – 11:00',
+                eventLocation: 'Hall',
+                eventSecondaryTerm: 'Time and location',
+            },
+        ],
+        onItemClick: fn(),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, 'Isolates `eventType="secondary"` — the neutral grey type bar, used for lower-priority or generic events.');
+export const NonInteractiveItems = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [
+            {
+                id: 'year-10-10g',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Year 10: 10G',
+                ...classEventTime,
+            },
+            {
+                id: 'maths-year-10',
+                eventType: 'secondary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Maths: Year 10: 10x/Ma3',
+                ...classEventTime,
+            },
+        ],
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, [
+    'No `onItemClick` is passed. Rows render as plain, non-interactive `<li>` elements —',
+    'no `role="button"`, no `tabIndex`, no hover chevron-to-arrow swap. The absence of interactivity',
+    'is exactly what this story demonstrates.',
+].join(' '));
+export const WithoutLocation = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [
+            {
+                id: 'staff-briefing',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Meeting',
+                eventPrimaryDefinition: 'Staff briefing',
+                eventSecondaryTerm: 'Time',
+                eventDateTime: '2026-06-08T08:00/2026-06-08T08:15',
+                eventTimeLabel: '08:00 – 08:15',
+            },
+        ],
+        onItemClick: fn(),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, [
+    '`eventLocation` is omitted and `eventSecondaryDefinition` is not set, so the secondary line',
+    'renders as time-only — no trailing comma fragment where the location would otherwise appear.',
+].join(' '));
+export const CustomSecondaryContent = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [
+            {
+                id: 'exam-window',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Exam',
+                eventPrimaryDefinition: 'GCSE Maths: Paper 2',
+                eventSecondaryTerm: 'Details',
+                eventDateTime: '2026-06-08T09:00/2026-06-08T10:30',
+                eventTimeLabel: '09:00 – 10:30',
+                eventSecondaryDefinition: 'Silent conditions — no calculators permitted',
+            },
+        ],
+        onItemClick: fn(),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, [
+    '`eventSecondaryDefinition` replaces the default time + location line entirely with custom content.',
+    'Note that `eventLocation` is deliberately not passed alongside it here — the two are an all-or-nothing',
+    'pair, and passing both would silently drop the location, which would be misleading to show in a story.',
+].join(' '));
+export const WithTooltip = withDescription({
+    args: {
+        heading: 'Calendar',
+        tooltip: 'Shows your next 5 scheduled events',
+        items: [
+            {
+                id: 'year-10-10g',
+                eventType: 'primary',
+                eventPrimaryTerm: 'Class',
+                eventPrimaryDefinition: 'Year 10: 10G',
+                ...classEventTime,
+            },
+        ],
+        onItemClick: fn(),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, 'Adding `tooltip` shows supplementary context alongside the heading. A single event keeps the focus on the tooltip.');
 export const Empty = withDescription({
-    render: EmptyTemplate,
+    args: {
+        heading: 'Calendar',
+        items: [],
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
+    parameters: { controls: { disable: true } },
+}, 'An empty `items` array shows the default built-in EmptyState — a date icon, "Nothing scheduled", and "There are no upcoming events."');
+export const CustomEmptyState = withDescription({
+    args: {
+        heading: 'Calendar',
+        items: [],
+        emptyState: (_jsx("div", { style: { padding: 'var(--spacing-large)', textAlign: 'center' }, children: _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "No events for the rest of term. Enjoy the break!" }) })),
+    },
+    render: args => _jsx(WidgetCalendar, { ...args }),
     parameters: { controls: { disable: true } },
-}, 'Empty items array shows the default EmptyState inside the Widget body.');
+}, 'Overrides the default EmptyState with custom content via the `emptyState` prop when the default copy does not fit the context.');
 export const FixedHeightOverflow = withDescription({
-    render: FixedHeightOverflowTemplate,
+    args: {
+        heading: 'Calendar',
+        items: overflowItems,
+        onItemClick: fn(),
+    },
+    render: args => (_jsx(FixedHeightWidgetContainer, { children: _jsx(WidgetCalendar, { ...args }) })),
     parameters: { controls: { disable: true } },
-}, 'Parent container constrains height; the header stays pinned while the event list scrolls inside Widget.Body.');
+}, [
+    'A parent container with a fixed 280px height constrains the widget — the header stays pinned while',
+    'the 14-item event list scrolls inside `Widget.Body`. The dashed border marks the constraining wrapper,',
+    'not part of the widget itself.',
+].join(' '));
 export const Composable = withDescription({
-    render: () => (_jsxs(Widget, { isFloating: true, children: [_jsx(Widget.Header, { children: "Calendar" }), _jsx(Widget.Body, { children: _jsx("ul", { className: "ds-widget-calendar__list", children: initialItems.slice(0, 2).map(item => (_jsx(WidgetCalendar.Item, { id: item.id, eventType: item.eventType, eventPrimaryTerm: item.eventPrimaryTerm, eventPrimaryDefinition: item.eventPrimaryDefinition, eventSecondaryTerm: item.eventSecondaryTerm, eventDateTime: item.eventDateTime, eventTimeLabel: item.eventTimeLabel, eventLocation: item.eventLocation, onItemClick: fn() }, item.id))) }) })] })),
-    parameters: { controls: { disable: true } },
-}, 'Compose manually with `WidgetCalendar.Item` inside `Widget.Body` when you need custom list logic beyond the `items` prop.');
+    render: ComposableTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Widget, WidgetCalendar } from '@arbor-education/design-system.components';
+
+function ComposableCalendarExample() {
+  return (
+    <Widget isFloating>
+      <Widget.Header>Calendar</Widget.Header>
+      <Widget.Body>
+        <ul className="ds-widget-calendar__list">
+          {items.map(item => (
+            <WidgetCalendar.Item
+              key={item.id}
+              id={item.id}
+              eventType={item.eventType}
+              eventPrimaryTerm={item.eventPrimaryTerm}
+              eventPrimaryDefinition={item.eventPrimaryDefinition}
+              eventSecondaryTerm={item.eventSecondaryTerm}
+              eventDateTime={item.eventDateTime}
+              eventTimeLabel={item.eventTimeLabel}
+              eventLocation={item.eventLocation}
+              // WidgetCalendar.Item's onItemClick takes NO id argument, unlike
+              // WidgetCalendar's own onItemClick — close over the id yourself.
+              onItemClick={() => handleItemClick(item.id)}
+            />
+          ))}
+        </ul>
+      </Widget.Body>
+    </Widget>
+  );
+}
+export default ComposableCalendarExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'Composes `Widget` and `WidgetCalendar.Item` manually — bypassing the `items` prop entirely — to prove',
+    '`WidgetCalendar.Item` is genuine public API for custom list logic. Note the closure: `WidgetCalendar.Item`\'s',
+    'own `onItemClick` takes no id argument, so each item must close over its own `id` (`() => handleClick(item.id)`),',
+    'unlike the parent `WidgetCalendar`\'s `onItemClick(id)`.',
+].join(' '));
 //# sourceMappingURL=WidgetCalendar.stories.js.map