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

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

@@ -1,24 +1,360 @@
-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 { TooltipWrapper } from './TooltipWrapper';
 import { Button } from 'Components/button/Button';
-import { TooltipWrapper as TooltipWrapperComponent } from './TooltipWrapper';
+import { Icon } from 'Components/icon/Icon';
 
-const meta: Meta<typeof TooltipWrapperComponent> = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`TooltipWrapper` is a convenience wrapper around the `Tooltip` compound component.',
+  'Pass your trigger as `children` and your tooltip text as `tooltipContent` — the wiring is done for you.',
+  'For full control over placement, arrow, or portal behaviour, use',
+  '[`Tooltip`](?path=/docs/components-tooltip--docs) directly.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Drop-in tooltip for **any focusable element** — no composition required',
+  '- When you just need a simple label string or short phrase above the trigger',
+  '- Preferred over raw `Tooltip` when no custom content or placement tweaking is needed',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Custom placement, alignment, or sideOffset | [`Tooltip`](?path=/docs/components-tooltip--docs) directly |',
+  '| Rich structured tooltip content (headings, lists) | [`Tooltip`](?path=/docs/components-tooltip--docs) directly |',
+  '| No arrow needed | [`Tooltip`](?path=/docs/components-tooltip--docs) with `shouldShowArrow={false}` |',
+  '',
+  '---',
+  '',
+  '### Props',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | The trigger element. Must be focusable. |',
+  '| `tooltipContent` | `ReactNode` | — | Content rendered inside the tooltip bubble |',
+  '| `delayDuration` | `number` | `400` | Milliseconds before the tooltip appears on hover |',
+  '| `triggerProps` | `TooltipTriggerProps` | — | Extra props forwarded to `Tooltip.Trigger` |',
+  '| `contentProps` | `Omit<ContentProps, "children">` | — | Extra props forwarded to `Tooltip.Content` (e.g. `side`, `sideOffset`, `shouldShowArrow`) |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Forwarding content props',
+  '',
+  'Pass any `Tooltip.Content` prop (such as `side`, `sideOffset`, `shouldShowArrow`) through `contentProps`:',
+  '',
+  '```tsx',
+  '<TooltipWrapper',
+  '  tooltipContent="Filter by term"',
+  '  contentProps={{ side: "right", shouldShowArrow: false }}',
+  '>',
+  '  <button type="button">Filter</button>',
+  '</TooltipWrapper>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The trigger child must be focusable — keyboard users navigate by Tab and expect the tooltip to appear on focus.',
+  '- Both `aria-label` on the trigger **and** `tooltipContent` serve the same purpose for accessible icon buttons.',
+  '  Provide both for the best experience across input methods.',
+  '- Keep `tooltipContent` short — one line is ideal.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import type { TooltipWrapper } from '@arbor-education/design-system.components';",
+  '',
+  'type Props = TooltipWrapper.Props;',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Tooltip](?path=/docs/components-tooltip--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 TooltipWrapperDocsPage() {
+  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/TooltipWrapper',
-  component: TooltipWrapperComponent,
+  component: TooltipWrapper,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      page: TooltipWrapperDocsPage,
+    },
+  },
+  argTypes: {
+    tooltipContent: {
+      control: 'text',
+      description: 'Content rendered inside the tooltip bubble. Typically a short string.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    children: {
+      control: false,
+      description: 'The trigger element. Must be a focusable element or a component that forwards its ref.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    delayDuration: {
+      control: 'number',
+      description: 'Milliseconds to wait before the tooltip appears on hover.',
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: '400' },
+      },
+    },
+    triggerProps: {
+      control: false,
+      description: 'Extra props forwarded to `Tooltip.Trigger`.',
+      table: {
+        type: { summary: 'TooltipTriggerProps' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    contentProps: {
+      control: false,
+      description: [
+        'Extra props forwarded to `Tooltip.Content`.',
+        'Use this to control `side`, `sideOffset`, `shouldShowArrow`, etc.',
+      ].join(' '),
+      table: {
+        type: { summary: "Omit<ContentProps, 'children'>" },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+} satisfies Meta<typeof TooltipWrapper>;
+
+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: 'Instead of manually creating a tooltip (using Tooltip, Tooltip.TooltipTrigger, Tooltip.TooltipContent), you can use this wrapper to easily create a tooltip.',
+        story: description,
       },
-    } },
-  tags: ['autodocs'],
-};
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const WithIconTriggerTemplate = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-small)' }}>
+    <TooltipWrapper tooltipContent="Download report" delayDuration={0}>
+      <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>
+    </TooltipWrapper>
+
+    <TooltipWrapper tooltipContent="Share" delayDuration={0}>
+      <button
+        type="button"
+        aria-label="Share"
+        style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 'var(--spacing-xsmall)', display: 'flex' }}
+      >
+        <Icon name="share" size={24} />
+      </button>
+    </TooltipWrapper>
+
+    <TooltipWrapper tooltipContent="Settings" delayDuration={0}>
+      <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>
+    </TooltipWrapper>
+  </div>
+);
 
-export const Default = {
+const WithContentPropsTemplate = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-large)', padding: 'var(--spacing-xxlarge)' }}>
+    <TooltipWrapper
+      tooltipContent="Appears on the right"
+      contentProps={{ side: 'right' }}
+      delayDuration={0}
+    >
+      <Button type="secondary">Side: right</Button>
+    </TooltipWrapper>
+
+    <TooltipWrapper
+      tooltipContent="No arrow here"
+      contentProps={{ shouldShowArrow: false }}
+      delayDuration={0}
+    >
+      <Button type="secondary">No arrow</Button>
+    </TooltipWrapper>
+
+    <TooltipWrapper
+      tooltipContent="Extra offset"
+      contentProps={{ sideOffset: 16 }}
+      delayDuration={0}
+    >
+      <Button type="secondary">sideOffset=16</Button>
+    </TooltipWrapper>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
   args: {
-    tooltipContent: 'Tooltip content',
-    children: <Button type="primary">Click me!</Button>,
+    tooltipContent: 'This is the tooltip content',
+    delayDuration: 400,
+    children: <Button type="primary">Hover or focus me</Button>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          'Pass the trigger as `children` and the label as `tooltipContent`.',
+          '`TooltipWrapper` handles all the `Tooltip.Trigger` / `Tooltip.Content` wiring.',
+          'Adjust `delayDuration` and `tooltipContent` in the **Controls** panel.',
+        ].join(' '),
+      },
+    },
   },
 };
 
-export default meta;
+export const WithIconTrigger: Story = withDescription(
+  {
+    render: WithIconTriggerTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon, TooltipWrapper } from '@arbor-education/design-system.components';
+
+// The most common pattern: icon-only toolbar buttons with accessible labels.
+function TooltipWrapperWithIconTriggerExample() {
+  return (
+    <TooltipWrapper tooltipContent="Download report" delayDuration={0}>
+      <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>
+    </TooltipWrapper>
+  );
+}
+export default TooltipWrapperWithIconTriggerExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The most common pattern: icon-only toolbar buttons with accessible labels.',
+    'Provide both `aria-label` on the button (screen readers) and `tooltipContent` (sighted mouse users).',
+  ].join(' '),
+);
+
+export const WithContentProps: Story = withDescription(
+  {
+    render: WithContentPropsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { TooltipWrapper } from '@arbor-education/design-system.components';
+
+function TooltipWrapperWithContentPropsExample() {
+  return (
+    <TooltipWrapper
+      tooltipContent="Appears on the right"
+      contentProps={{ side: 'right', shouldShowArrow: false }}
+      delayDuration={0}
+    >
+      <button type="button">Hover me</button>
+    </TooltipWrapper>
+  );
+}
+export default TooltipWrapperWithContentPropsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Forward any `Tooltip.Content` prop via `contentProps` — including `side`, `sideOffset`, and `shouldShowArrow`.',
+    'This keeps the convenience of `TooltipWrapper` while allowing placement control.',
+  ].join(' '),
+);

package/src/docs/Contributing.mdx

@@ -0,0 +1,241 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Contributing" />
+
+# Contributing to the Design System
+
+← [Back to Welcome](/?path=/docs/getting-started-welcome--docs)
+
+This guide is for developers working on the design system itself — adding new components, fixing bugs, or improving docs. If you're just looking to use components in a product, see [Using the Components](/?path=/docs/getting-started-using-the-components--docs).
+
+---
+
+## Local setup
+
+**Prerequisites:** [nvm](https://github.com/nvm-sh/nvm) and [yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
+
+```bash
+nvm use
+yarn install
+yarn storybook
+```
+
+Storybook starts on port 6006 with hot reloading. Make a change to a component or story file and it'll update immediately in the browser.
+
+---
+
+## Creating a new component
+
+Use the scaffolding script to generate all the necessary files at once:
+
+```bash
+yarn create-component <ComponentName>
+```
+
+This creates four files inside `src/components/<componentName>/`:
+
+<table>
+  <thead>
+    <tr><th>File</th><th>Purpose</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>Component.tsx</code></td><td>The component itself</td></tr>
+    <tr><td><code>Component.test.tsx</code></td><td>Unit tests</td></tr>
+    <tr><td><code>Component.stories.tsx</code></td><td>Storybook stories and docs</td></tr>
+    <tr><td><code>component.scss</code></td><td>Styles</td></tr>
+  </tbody>
+</table>
+
+It also automatically adds the component's exports to `src/index.ts` and `src/index.scss` — no manual wiring needed.
+
+---
+
+## Key conventions
+
+### File and directory naming
+
+<table>
+  <thead>
+    <tr><th>Thing</th><th>Convention</th><th>Example</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Component file</td><td>PascalCase</td><td><code>Button.tsx</code></td></tr>
+    <tr><td>Test file</td><td>PascalCase + <code>.test.tsx</code></td><td><code>Button.test.tsx</code></td></tr>
+    <tr><td>Story file</td><td>PascalCase + <code>.stories.tsx</code></td><td><code>Button.stories.tsx</code></td></tr>
+    <tr><td>Stylesheet</td><td>camelCase matching directory</td><td><code>button.scss</code></td></tr>
+    <tr><td>Directory</td><td>camelCase</td><td><code>button/</code></td></tr>
+  </tbody>
+</table>
+
+### CSS class naming
+
+All classes use the `ds-` prefix with BEM-style modifiers:
+
+```scss
+.ds-button { }            // base class
+.ds-button--primary { }   // modifier
+```
+
+Use the `classnames` library for conditional classes.
+
+### Path aliases
+
+Always use these aliases in imports — not relative paths:
+
+```ts
+import { Button } from 'Components/button/Button';  // ✓
+import { Button } from '../../components/button/Button';  // ✗
+```
+
+<table>
+  <thead>
+    <tr><th>Alias</th><th>Resolves to</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>{'Components/*'}</code></td><td><code>{'./src/components/*'}</code></td></tr>
+    <tr><td><code>{'Utils/*'}</code></td><td><code>{'./src/utils/*'}</code></td></tr>
+  </tbody>
+</table>
+
+---
+
+## Design principles
+
+Before writing any component logic, it's worth internalising how we think about components here. These principles should shape every decision.
+
+### Dumb components
+
+Components must have **no business logic** and **no knowledge of the data layer**. A component should render what it receives via props and emit events back to the consumer — that's it. If you find yourself fetching data, transforming API responses, or encoding product-specific rules inside a component, stop and move that logic to the consumer.
+
+### Brand agnostic
+
+Components shouldn't know they're in an Arbor product. They should be general enough that they could — in theory — be dropped into any React app. This keeps them reusable, testable in isolation, and free from product churn.
+
+### Delegate to the consumer (DTC)
+
+This is the most important principle. **Empower consumers, don't constrain them.**
+
+Rather than encoding every possible use case into a component's internals, expose the right props and hooks to let the consumer drive behaviour. When you're unsure whether to handle something inside the component or leave it to the consumer, default to leaving it to the consumer.
+
+The Table component is the clearest example of this in practice. Rather than building a full data-grid from scratch, Table is a thin wrapper over [AG Grid](https://www.ag-grid.com/) — it applies Arbor's defaults and design tokens, then gets out of the way. Consumers get the full power of AG Grid's API directly. We don't abstract it away.
+
+Ask yourself: *"Am I solving a problem that every consumer will always have, or am I solving one specific consumer's problem?"* Only the former belongs in the component.
+
+### Compound components
+
+Where a component has meaningful sub-parts, we favour the **compound component pattern** over a single monolithic component with a pile of props.
+
+Rather than:
+
+```tsx
+<Dropdown
+  trigger="Open"
+  items={[{ label: 'Edit', onClick: handleEdit }]}
+  header="Options"
+/>
+```
+
+We prefer:
+
+```tsx
+<Dropdown>
+  <Dropdown.Trigger>Open</Dropdown.Trigger>
+  <Dropdown.Content>
+    <Dropdown.Label>Options</Dropdown.Label>
+    <Dropdown.Item onClick={handleEdit}>Edit</Dropdown.Item>
+  </Dropdown.Content>
+</Dropdown>
+```
+
+This keeps each sub-part simple and independently composable. Consumers can mix, omit, or extend parts without needing the parent component to support every combination via props. Dropdown and Table are the clearest examples of this in the codebase — both expose sub-components that consumers assemble themselves.
+
+When building a new component that has headers, footers, items, triggers, or other distinct sections, reach for this pattern first.
+
+### Prop passthrough
+
+For wrapper components — anything that wraps AG Grid, a Radix UI primitive, or another third-party library — always spread `...rest` onto the underlying element or component. This ensures consumers are never cut off from the full API of whatever we're wrapping.
+
+```tsx
+function Table({ className, ...rest }: TableProps) {
+  return <AgGridReact className={cx('ds-table', className)} {...rest} />;
+}
+```
+
+The rule is simple: **never let our wrapper be the reason a consumer can't do something the underlying library supports.** If they need an AG Grid prop we haven't explicitly typed, `...rest` means it still works. The same applies to any Radix primitive we build on top of (Dropdown, Tooltip, etc.).
+
+---
+
+## Quality gates
+
+All three must pass before opening a PR:
+
+```bash
+yarn check-types      # zero TypeScript errors
+yarn test:coverage    # 100% of tests passing
+yarn style-lint       # zero SCSS linting errors
+```
+
+Run lint with `--fix` to auto-correct issues:
+
+```bash
+yarn eslint --fix src/
+yarn style-lint --fix
+```
+
+---
+
+## Branch and commit conventions
+
+```bash
+# Branch format
+feature/MIS-12345-short-description
+bugfix/MIS-12345-fix-the-thing
+
+# Commit format (no colon after ticket ID)
+MIS-12345 Add disabled state to Button
+```
+
+Never push directly to `main` — all work goes through a branch and PR.
+
+---
+
+## PR rules (the important bit)
+
+- **One PR = one Jira ticket.** No bundling unrelated changes.
+- **Under 400 lines** of meaningful code change — if it's bigger, split it.
+- **Fill in the PR template** — every section, no placeholders.
+
+For the full details and the reasoning behind these rules, see [CONTRIBUTING.md](https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md) on GitHub.
+
+---
+
+## Local development with a consumer project
+
+The library uses [Yalc](https://github.com/wclr/yalc) for local linking to consumer projects.
+
+```bash
+# Install Yalc globally (first time only)
+npm i yalc -g
+
+# In this repo — build and publish to the local Yalc store
+yarn build
+yalc publish
+
+# In the consumer project — add the local package
+yalc add @arbor-education/design-system.components
+```
+
+For active development with automatic updates on file save, use watch mode instead:
+
+```bash
+# Rebuilds and pushes to Yalc automatically on every change
+yarn watch
+```
+
+---
+
+## Useful links
+
+- [GitHub repository](https://github.com/arbor-education/design-system.components)
+- [CONTRIBUTING.md](https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md) — the full contribution guide
+- [NPM package](https://www.npmjs.com/package/@arbor-education/design-system.components)