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

package/src/components/tooltip/Tooltip.stories.tsx

@@ -1,35 +1,626 @@
-import type { Meta } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { Tooltip } from './Tooltip';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 
-const meta: Meta<typeof Tooltip> = {
-  title: 'Components/Tooltip/DestructuredTooltip',
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Tooltip` is a compound component that shows a floating label when a trigger element is hovered or focused.',
+  'It wraps [Radix UI Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip) and exposes',
+  '`Tooltip.Trigger` and `Tooltip.Content` for full compositional control.',
+  '',
+  '> **Tip:** Most use cases don\'t need full composition control.',
+  '> [`TooltipWrapper`](?path=/docs/components-tooltip-tooltipwrapper--docs) handles the wiring in a single component —',
+  '> pass your trigger as `children` and your label as `tooltipContent`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Icon-only controls** — any clickable icon without visible text needs a tooltip label',
+  '- **Abbreviations and truncated text** — reveal the full value on hover',
+  '- **Contextual hints** — brief supplementary info about a field or action that doesn\'t fit inline',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Information is essential to complete the task | Put it inline — don\'t hide critical guidance |',
+  '| Content is longer than ~2 lines | Use a [`Section`](?path=/docs/components-section--docs) or expand the UI |',
+  '| The trigger has no visible focus state | Fix the focusability first — keyboard users won\'t see the tooltip |',
+  '| Touch / mobile-primary surfaces | Tooltips only trigger on hover — mobile users never see them |',
+  '',
+  '---',
+  '',
+  '### Sub-component API',
+  '',
+  '#### `Tooltip`',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `delayDuration` | `number` | `400` | Milliseconds before the tooltip appears after hover |',
+  '| `open` | `boolean` | — | Controlled open state |',
+  '| `onOpenChange` | `(open: boolean) => void` | — | Callback for controlled mode |',
+  '| `defaultOpen` | `boolean` | — | Initial open state (uncontrolled) |',
+  '| `disableHoverableContent` | `boolean` | — | Prevents hovering over the tooltip content itself |',
+  '| `children` | `ReactNode` | — | Must include `Tooltip.Trigger` and `Tooltip.Content` |',
+  '',
+  '#### `Tooltip.Trigger`',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | The element that opens the tooltip. Must be focusable. |',
+  '| `className` | `string` | — | Extra CSS class merged onto the trigger child |',
+  '',
+  '#### `Tooltip.Content`',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | The tooltip body |',
+  '| `shouldShowArrow` | `boolean` | `true` | Whether to render the pointing arrow |',
+  '| `side` | `"top" \\| "right" \\| "bottom" \\| "left"` | `"top"` | Preferred placement side |',
+  '| `sideOffset` | `number` | — | Distance (px) between tooltip and trigger |',
+  '| `align` | `"start" \\| "center" \\| "end"` | `"center"` | Alignment along the side |',
+  '| `portalProps` | `TooltipPortalProps` | — | Props forwarded to `Radix.Portal` |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### `asChild` is built in',
+  '',
+  '`Tooltip.Trigger` always renders with `asChild` — the Radix trigger props are merged directly onto the child element.',
+  'The child must be a focusable element (`<button>`, `<a>`, etc.) or a custom component that forwards its ref.',
+  'Wrapping a `<div>` or `<span>` without `tabIndex` will cause keyboard users to miss the tooltip.',
+  '',
+  '---',
+  '',
+  '### Portal rendering',
+  '',
+  '`Tooltip.Content` renders via a Radix portal, controlled by `PopupParentContext`.',
+  'Do **not** place containing elements with `overflow: hidden` — the tooltip will be clipped.',
+  'If you need to re-parent the portal (e.g. inside a Modal), wrap the tree with',
+  '`<PopupParentContext.Provider value={containerRef}>` — see',
+  '[`PopupParentContext`](?path=/docs/utils-popupparentcontext--docs).',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Radix automatically sets `role="tooltip"` on the content and wires `aria-describedby` on the trigger — no manual ARIA needed.',
+  '- The tooltip is announced by screen readers when the trigger receives focus.',
+  '- `delayDuration={0}` is recommended for keyboard-triggered tooltips (focus shouldn\'t require a wait).',
+  '- Never put interactive content (buttons, links) inside a tooltip — use a Popup or Dropdown instead.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import type { Tooltip } from '@arbor-education/design-system.components';",
+  '',
+  'type Props        = Tooltip.Props;         // Tooltip root — extends Radix TooltipProps',
+  'type ContentProps = Tooltip.ContentProps;  // Tooltip.Content',
+  'type TriggerProps = Tooltip.TriggerProps;  // Tooltip.Trigger — extends Radix TooltipTriggerProps',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[TooltipWrapper](?path=/docs/components-tooltip-tooltipwrapper--docs) · [Button](?path=/docs/components-button--docs) · [Icon](?path=/docs/components-icon--docs)',
+].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.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function TooltipDocsPage() {
+  return (
+    <>
+      <Title />
+      <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>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Tooltip',
   component: Tooltip,
   tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      page: TooltipDocsPage,
+    },
+  },
+  argTypes: {
+    delayDuration: {
+      control: 'number',
+      description: 'Milliseconds to wait before the tooltip appears after the trigger is hovered or focused.',
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: '400' },
+      },
+    },
+    open: {
+      control: false,
+      description: 'Controlled open state. When provided, pair with `onOpenChange` to manage state externally.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onOpenChange: {
+      control: false,
+      description: 'Callback fired when the open state changes. Required for controlled mode.',
+      table: {
+        type: { summary: '(open: boolean) => void' },
+      },
+    },
+    defaultOpen: {
+      control: false,
+      description: 'Initial open state for uncontrolled usage.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    children: {
+      control: false,
+      description: 'Must include `Tooltip.Trigger` and `Tooltip.Content` sub-components.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+  },
+} satisfies Meta<typeof Tooltip>;
 
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Omit<Story, 'args'>, description: string): Story => ({
+  ...(story as Story),
   parameters: {
+    ...story.parameters,
     docs: {
+      ...story.parameters?.docs,
       description: {
-        component: 'A composable set of components (Tooltip, Tooltip.Trigger, Tooltip.Content) that you can use to create a tooltip.',
+        story: description,
       },
     },
   },
-};
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const AllPlacementsTemplate = () => (
+  <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 'var(--spacing-xxlarge)', padding: 'var(--spacing-xxlarge)' }}>
+    {(['top', 'right', 'bottom', 'left'] as const).map(side => (
+      <div key={side} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }}>{`side="${side}"`}</span>
+        <Tooltip delayDuration={0}>
+          <Tooltip.Trigger>
+            <Button type="secondary">Hover me</Button>
+          </Tooltip.Trigger>
+          <Tooltip.Content side={side}>
+            Tooltip on the
+            {' '}
+            {side}
+          </Tooltip.Content>
+        </Tooltip>
+      </div>
+    ))}
+  </div>
+);
+
+const WithoutArrowTemplate = () => (
+  <Tooltip delayDuration={0}>
+    <Tooltip.Trigger>
+      <Button type="secondary">Hover me</Button>
+    </Tooltip.Trigger>
+    <Tooltip.Content shouldShowArrow={false}>
+      No arrow on this tooltip
+    </Tooltip.Content>
+  </Tooltip>
+);
+
+const WithRichContentTemplate = () => (
+  <Tooltip delayDuration={0}>
+    <Tooltip.Trigger>
+      <Button type="secondary">Assessment period</Button>
+    </Tooltip.Trigger>
+    <Tooltip.Content>
+      <div>
+        <strong>Autumn 1 2024–25</strong>
+        <div>Sep 2 – Oct 25</div>
+      </div>
+    </Tooltip.Content>
+  </Tooltip>
+);
+
+const WithIconTriggerTemplate = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-small)' }}>
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button
+          type="button"
+          aria-label="Download report"
+          style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 'var(--spacing-xsmall)', display: 'flex' }}
+        >
+          <Icon name="download" size={24} />
+        </button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Download report</Tooltip.Content>
+    </Tooltip>
+
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button
+          type="button"
+          aria-label="Export data"
+          style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 'var(--spacing-xsmall)', display: 'flex' }}
+        >
+          <Icon name="share" size={24} />
+        </button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Export data</Tooltip.Content>
+    </Tooltip>
+
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button
+          type="button"
+          aria-label="Settings"
+          style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 'var(--spacing-xsmall)', display: 'flex' }}
+        >
+          <Icon name="settings" size={24} />
+        </button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Settings</Tooltip.Content>
+    </Tooltip>
+  </div>
+);
+
+const SlowDelayTemplate = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }}>
+        delayDuration=
+        {0}
+      </span>
+      <Tooltip delayDuration={0}>
+        <Tooltip.Trigger>
+          <Button type="secondary">Instant</Button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows immediately on hover</Tooltip.Content>
+      </Tooltip>
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }}>
+        delayDuration=
+        {400}
+        {' '}
+        (default)
+      </span>
+      <Tooltip delayDuration={400}>
+        <Tooltip.Trigger>
+          <Button type="secondary">Default delay</Button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows after 400ms</Tooltip.Content>
+      </Tooltip>
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }}>
+        delayDuration=
+        {1000}
+      </span>
+      <Tooltip delayDuration={1000}>
+        <Tooltip.Trigger>
+          <Button type="secondary">Slow</Button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows after 1 second</Tooltip.Content>
+      </Tooltip>
+    </div>
+  </div>
+);
 
-export const Default = {
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
   args: {
-    children: [
-      <>
+    delayDuration: 400,
+  },
+  render: args => (
+    <Tooltip {...args}>
+      <Tooltip.Trigger>
+        <Button type="primary">Hover or focus me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        This is a tooltip
+      </Tooltip.Content>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          'The `Tooltip` compound component requires `Tooltip.Trigger` and `Tooltip.Content` as children.',
+          'The trigger element must be focusable — `Tooltip.Trigger` uses `asChild` to merge props onto the child.',
+          'Use the **Controls** panel to adjust `delayDuration`.',
+        ].join(' '),
+      },
+    },
+  },
+};
+
+export const AllPlacements: Story = withDescription(
+  {
+    render: AllPlacementsTemplate,
+    parameters: {
+      controls: { disable: true },
+      layout: 'centered',
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tooltip } from '@arbor-education/design-system.components';
+
+function TooltipAllPlacementsExample() {
+  return (
+    <>
+      <Tooltip delayDuration={0}>
+        <Tooltip.Trigger>
+          <button type="button">Top (default)</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content side="top">
+          Tooltip on the top
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delayDuration={0}>
+        <Tooltip.Trigger>
+          <button type="button">Right</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content side="right">
+          Tooltip on the right
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delayDuration={0}>
         <Tooltip.Trigger>
-          <Button type="primary">Click me!</Button>
+          <button type="button">Bottom</button>
         </Tooltip.Trigger>
+        <Tooltip.Content side="bottom">
+          Tooltip on the bottom
+        </Tooltip.Content>
+      </Tooltip>
 
-        <Tooltip.Content>
-          <div>Content</div>
+      <Tooltip delayDuration={0}>
+        <Tooltip.Trigger>
+          <button type="button">Left</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content side="left">
+          Tooltip on the left
         </Tooltip.Content>
-      </>,
-    ],
+      </Tooltip>
+    </>
+  );
+}
+export default TooltipAllPlacementsExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Use the `side` prop on `Tooltip.Content` to control which side the tooltip appears on.',
+    'Radix will automatically flip to the opposite side if there\'s not enough viewport space.',
+  ].join(' '),
+);
 
-export default meta;
+export const WithoutArrow: Story = withDescription(
+  {
+    render: WithoutArrowTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tooltip } from '@arbor-education/design-system.components';
+
+function TooltipWithoutArrowExample() {
+  return (
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button type="button">Hover me</button>
+      </Tooltip.Trigger>
+      <Tooltip.Content shouldShowArrow={false}>
+        No arrow on this tooltip
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+export default TooltipWithoutArrowExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Set `shouldShowArrow={false}` on `Tooltip.Content` to hide the pointing arrow.',
+    'Useful when the tooltip is positioned far from the trigger or inside a dense UI.',
+  ].join(' '),
+);
+
+export const WithRichContent: Story = withDescription(
+  {
+    render: WithRichContentTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tooltip } from '@arbor-education/design-system.components';
+
+function TooltipWithRichContentExample() {
+  return (
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button type="button">Assessment period</button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <div>
+          <strong>Autumn 1 2024–25</strong>
+          <div>Sep 2 – Oct 25</div>
+        </div>
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+export default TooltipWithRichContentExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`Tooltip.Content` accepts any `ReactNode` — use structured markup for richer labels.',
+    'Keep content short: tooltips should clarify, not teach.',
+    'Never put interactive elements (buttons, links) inside a tooltip.',
+  ].join(' '),
+);
+
+export const WithIconTrigger: Story = withDescription(
+  {
+    render: WithIconTriggerTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon, Tooltip } from '@arbor-education/design-system.components';
+
+// Icon-only controls must have both aria-label (for screen readers)
+// and a Tooltip (for sighted users who hover).
+function TooltipWithIconTriggerExample() {
+  return (
+    <Tooltip delayDuration={0}>
+      <Tooltip.Trigger>
+        <button
+          type="button"
+          aria-label="Download report"
+          style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 'var(--spacing-xsmall)', display: 'flex' }}
+        >
+          <Icon name="download" size={24} />
+        </button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Download report</Tooltip.Content>
+    </Tooltip>
+  );
+}
+export default TooltipWithIconTriggerExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Icon-only buttons must have both an `aria-label` (for screen readers) and a `Tooltip` (for sighted mouse users).',
+    'The two convey the same information through different channels — they\'re complementary, not redundant.',
+  ].join(' '),
+);
+
+export const HoverDelay: Story = withDescription(
+  {
+    render: SlowDelayTemplate,
+    parameters: {
+      controls: { disable: true },
+      layout: 'centered',
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tooltip } from '@arbor-education/design-system.components';
+
+// delayDuration={0} is best for keyboard-triggered tooltips (focus shouldn't wait).
+// The default 400ms prevents flicker when the user is just moving the cursor past buttons.
+function TooltipHoverDelayExample() {
+  return (
+    <>
+      <Tooltip delayDuration={0}>
+        <Tooltip.Trigger>
+          <button type="button">Instant (0ms)</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows immediately on hover</Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delayDuration={400}>
+        <Tooltip.Trigger>
+          <button type="button">Default (400ms)</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows after 400ms</Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delayDuration={1000}>
+        <Tooltip.Trigger>
+          <button type="button">Slow (1000ms)</button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>Shows after 1 second</Tooltip.Content>
+      </Tooltip>
+    </>
+  );
+}
+export default TooltipHoverDelayExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`delayDuration` controls how long the user must hover before the tooltip appears.',
+    'The default 400ms prevents noise when the cursor moves across the page.',
+    'Use `delayDuration={0}` for icon-only controls where the label is the primary way to understand the action.',
+  ].join(' '),
+);