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

package/src/components/widgetCalendar/WidgetCalendar.stories.tsx

@@ -1,17 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Controls,
   Heading as DocHeading,
-  Primary as DocPrimary,
   Markdown,
+  Primary as DocPrimary,
   Stories,
   Subtitle,
   Title,
 } from '@storybook/addon-docs/blocks';
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
 import { Widget } from 'Components/widget/Widget';
 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',
@@ -88,11 +93,77 @@ const overflowItems: WidgetCalendar.ItemData[] = [
   ...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 (
@@ -101,25 +172,135 @@ function WidgetCalendarDocsPage() {
       <Subtitle />
       <Markdown>{DESCRIPTION_INTRO}</Markdown>
       <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
       <DocPrimary />
       <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
       <DocHeading>Examples</DocHeading>
       <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
     </>
   );
 }
 
-const withDescription = (story: StoryObj, description: string): StoryObj => ({
+// ---------------------------------------------------------------------------
+// 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' },
+      },
+    },
+  },
+} satisfies Meta<typeof WidgetCalendar>;
+
+export default meta;
+// Use StoryObj<typeof WidgetCalendar> (not typeof meta) so render-only stories are
+// not forced to provide required args — template components handle their own instances.
+type Story = StoryObj<typeof WidgetCalendar>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
   ...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,
@@ -141,101 +322,393 @@ function FixedHeightWidgetContainer({
   );
 }
 
-const DefaultTemplate = () => (
-  <WidgetCalendar
-    heading="Calendar"
-    headingHref="/calendar"
-    isFloating
-    items={initialItems}
-    onItemClick={fn()}
-  />
+const InteractiveTemplate = () => {
+  const [lastClickedId, setLastClickedId] = useState<string | null>(null);
+
+  const lastClickedLabel = lastClickedId
+    ? initialItems.find(item => item.id === lastClickedId)?.eventPrimaryDefinition
+    : null;
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetCalendar
+        heading="Calendar"
+        isFloating
+        items={initialItems}
+        onItemClick={setLastClickedId}
+      />
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+        {lastClickedLabel
+          ? (
+              <>
+                Last clicked:
+                {' '}
+                {lastClickedLabel}
+              </>
+            )
+          : 'Click an event to see its id captured here.'}
+      </span>
+    </div>
+  );
+};
+
+const handleComposableItemClick = fn();
+
+const ComposableTemplate = () => (
+  <Widget isFloating>
+    <Widget.Header>Calendar</Widget.Header>
+    <Widget.Body>
+      <ul className="ds-widget-calendar__list">
+        {initialItems.slice(0, 2).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}
+            onItemClick={() => handleComposableItemClick(item.id)}
+          />
+        ))}
+      </ul>
+    </Widget.Body>
+  </Widget>
 );
 
-const EmptyTemplate = () => (
-  <WidgetCalendar heading="Calendar" isFloating items={[]} />
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      headingHref: '/calendar',
+      isFloating: true,
+      items: initialItems,
+      onItemClick: fn(),
+    },
+    render: args => <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: Story = 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(' '),
 );
 
-const FixedHeightOverflowTemplate = () => (
-  <FixedHeightWidgetContainer>
-    <WidgetCalendar
-      heading="Calendar"
-      isFloating
-      items={overflowItems}
-      onItemClick={fn()}
-    />
-  </FixedHeightWidgetContainer>
+export const PrimaryEventType: Story = 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 => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Isolates `eventType="primary"` — the brand-green type bar. This is also the default when',
+    '`eventType` is omitted entirely.',
+  ].join(' '),
 );
 
-const meta = {
-  title: 'Components/Widget/WidgetCalendar',
-  component: WidgetCalendar,
-  parameters: {
-    layout: 'padded',
-    docs: { page: WidgetCalendarDocsPage },
+export const SecondaryEventType: Story = 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 => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
   },
-  tags: ['autodocs'],
-  args: {
-    heading: 'Calendar',
-    isFloating: true,
-    items: initialItems,
-    onItemClick: fn(),
+  'Isolates `eventType="secondary"` — the neutral grey type bar, used for lower-priority or generic events.',
+);
+
+export const NonInteractiveItems: Story = 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 => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
   },
-} satisfies Meta<typeof WidgetCalendar>;
+  [
+    '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 default meta;
+export const WithoutLocation: Story = 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 => <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(' '),
+);
 
-type Story = StoryObj<typeof meta>;
+export const CustomSecondaryContent: Story = 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 => <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 Default: Story = withDescription(
+export const WithTooltip: Story = withDescription(
   {
-    render: DefaultTemplate,
+    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 => <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.',
+  'Adding `tooltip` shows supplementary context alongside the heading. A single event keeps the focus on the tooltip.',
 );
 
 export const Empty: Story = withDescription(
   {
-    render: EmptyTemplate,
+    args: {
+      heading: 'Calendar',
+      items: [],
+    },
+    render: args => <WidgetCalendar {...args} />,
     parameters: { controls: { disable: true } },
   },
-  'Empty items array shows the default EmptyState inside the Widget body.',
+  'An empty `items` array shows the default built-in EmptyState — a date icon, "Nothing scheduled", and "There are no upcoming events."',
 );
 
-export const FixedHeightOverflow: Story = withDescription(
+export const CustomEmptyState: Story = withDescription(
   {
-    render: FixedHeightOverflowTemplate,
+    args: {
+      heading: 'Calendar',
+      items: [],
+      emptyState: (
+        <div style={{ padding: 'var(--spacing-large)', textAlign: 'center' }}>
+          <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+            No events for the rest of term. Enjoy the break!
+          </p>
+        </div>
+      ),
+    },
+    render: args => <WidgetCalendar {...args} />,
     parameters: { controls: { disable: true } },
   },
-  'Parent container constrains height; the header stays pinned while the event list scrolls inside Widget.Body.',
+  'Overrides the default EmptyState with custom content via the `emptyState` prop when the default copy does not fit the context.',
 );
 
-export const Composable: Story = withDescription(
+export const FixedHeightOverflow: Story = withDescription(
   {
-    render: () => (
-      <Widget isFloating>
-        <Widget.Header>Calendar</Widget.Header>
-        <Widget.Body>
-          <ul className="ds-widget-calendar__list">
-            {initialItems.slice(0, 2).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}
-                onItemClick={fn()}
-              />
-            ))}
-          </ul>
-        </Widget.Body>
-      </Widget>
+    args: {
+      heading: 'Calendar',
+      items: overflowItems,
+      onItemClick: fn(),
+    },
+    render: args => (
+      <FixedHeightWidgetContainer>
+        <WidgetCalendar {...args} />
+      </FixedHeightWidgetContainer>
     ),
     parameters: { controls: { disable: true } },
   },
-  'Compose manually with `WidgetCalendar.Item` inside `Widget.Body` when you need custom list logic beyond the `items` prop.',
+  [
+    '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: Story = withDescription(
+  {
+    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(' '),
 );