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

package/src/docs/UsingComponents.mdx

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Using the Components" />
+
+# Using the Components
+
+← [Back to Welcome](/?path=/docs/getting-started-welcome--docs)
+
+This guide covers how to get Arbor Design System components into your project. If you're looking to contribute to the design system itself, head over to [Contributing](/?path=/docs/getting-started-contributing--docs).
+
+---
+
+## Already using `arbor-fe-library`?
+
+The package and stylesheet are already installed and configured in `arbor-fe-library` — you can skip straight to [importing components](#using-the-components) below.
+
+---
+
+## Installing the package
+
+The design system is published as a public NPM package. Add it to your project with:
+
+```bash
+yarn add @arbor-education/design-system.components
+```
+
+Or with npm:
+
+```bash
+npm install @arbor-education/design-system.components
+```
+
+---
+
+## Importing the stylesheet
+
+Once the package is installed, import the base component styles once at the root of your app. The stylesheet lives at:
+
+```
+@arbor-education/design-system.components/dist/index.css
+```
+
+**In a Sass file** (recommended — this is how `arbor-fe-library` does it):
+
+```scss
+@import '@arbor-education/design-system.components/dist/index.css';
+```
+
+**In a TypeScript/JavaScript entry point:**
+
+```ts
+import '@arbor-education/design-system.components/dist/index.css';
+```
+
+Without this stylesheet, components will render without their styles — so don't skip this step!
+
+---
+
+## Using the components
+
+All components are exported as named exports from the package. Browse the sidebar to find the component you need, then import it by name:
+
+```tsx
+import { Button } from '@arbor-education/design-system.components';
+
+function SaveButton() {
+  return <Button variant="primary">Save changes</Button>;
+}
+```
+
+Every component page in this Storybook has:
+
+- A **live interactive preview** — tweak props with the Controls panel and see changes in real time
+- **Full prop documentation** — every prop, its type, and its default
+- **Usage examples** — real-world scenarios with copy-pasteable code
+
+---
+
+## Finding the right component
+
+Not sure which component to reach for? A few tips:
+
+- Browse the sidebar — components are listed alphabetically under **Components**, with complex ones (Table, FormField, Modals) having nested sub-sections
+- Check the **When to use** and **When not to use** sections on each component's Docs page — they'll point you in the right direction
+- If nothing fits, drop a message in [#frontend-support](https://arbor-education.slack.com/archives/C08AZT15KH7) first — the team can point you in the right direction or help scope a new component
+
+---
+
+## Useful links
+
+- [NPM package](https://www.npmjs.com/package/@arbor-education/design-system.components)
+- [GitHub repository](https://github.com/arbor-education/design-system.components)
+- [Confluence consuming guide](https://orchard.atlassian.net/wiki/spaces/SATD/pages/2500591662/Consuming+the+design+system+NPM+package)

package/src/docs/Welcome.mdx

@@ -0,0 +1,68 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Welcome" />
+
+# Welcome to the Arbor Design System
+
+The Arbor Design System is a shared component library that helps teams across Arbor ship consistent, accessible, and well-crafted UI — without reinventing the wheel every time. Whether you're here to use components in a product, contribute new ones, or just explore what's available, you're in the right place.
+
+---
+
+## What is the design system?
+
+The design system is the single source of truth for Arbor's UI. It brings together:
+
+- **Components** — reusable React components with consistent styling, behaviour, and accessibility baked in
+- **Design tokens** — a shared set of colours, spacing, and typography values that keep everything visually cohesive
+- **Documentation** — guidance on when and how to use each component (that's this Storybook!)
+- **Figma** — the design counterpart, where designers and PMs work
+
+Rather than every team solving the same UI problems from scratch, the design system gives everyone a shared foundation to build on. Developers can focus on product logic; designers can focus on user experience and flows.
+
+---
+
+## Our philosophy
+
+Arbor's design system components are intentionally **simple and flexible**. A few principles guide everything:
+
+- **Dumb components** — components have no business logic and no opinion about your data. They render what you give them, nothing more.
+- **Brand agnostic** — components are built around structure and behaviour, not Arbor-specific product context. They could work in any product.
+- **Delegate to the consumer (DTC)** — rather than dictating how a component should be used, we aim to empower consumers to bend components to their own needs. If you need custom behaviour, you should be able to get there without fighting the component.
+- **Thin wrappers over great tools** — where a best-in-class library already solves a problem well, we wrap it rather than reinvent it. The Table component is a good example: it's a thin layer over AG Grid, giving you all of AG Grid's power with Arbor's defaults applied on top. Consumers always have access to the full API of whatever we're wrapping — we never get in the way.
+
+---
+
+## What is Storybook?
+
+Storybook is a tool for browsing, interacting with, and learning about UI components in isolation — completely outside of any real product page. Think of it as a living catalogue for the design system.
+
+Here's how to get the most out of it:
+
+- **Browse components** using the sidebar on the left, organised by category
+- **Interact with props** via the Controls panel at the bottom of the screen — change a value and watch the component update live
+- **Read the docs** on each component's Docs page — you'll find when to use it, when *not* to use it, accessibility notes, and the full prop API
+- **Copy code snippets** from any story — every example shows production-ready import and usage code, ready to paste
+
+---
+
+## Where to go next
+
+<table>
+  <thead>
+    <tr><th>I want to...</th><th>Go here</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Use Arbor components in a project</td><td><a href="/?path=/docs/getting-started-using-the-components--docs">Using the Components</a></td></tr>
+    <tr><td>Work on the design system itself</td><td><a href="/?path=/docs/getting-started-contributing--docs">Contributing</a></td></tr>
+    <tr><td>Browse all components</td><td>Use the sidebar on the left</td></tr>
+  </tbody>
+</table>
+
+---
+
+## Useful links
+
+- [NPM package](https://www.npmjs.com/package/@arbor-education/design-system.components) — `@arbor-education/design-system.components`
+- [GitHub repository](https://github.com/arbor-education/design-system.components)
+- [Figma design system](https://www.figma.com/file/2GNa44f89PatHEF49n5DaO/Arbor-DSM?node-id=1%3A2)
+- [Confluence docs](https://orchard.atlassian.net/wiki/spaces/SATD/pages/2500591662/Consuming+the+design+system+NPM+package)

package/src/global.scss

@@ -34,3 +34,10 @@
   font-weight: var(--font-weight-regular);
   box-sizing: border-box;
 }
+
+// The wrapper covers the viewport so ag grid's outside-click detection sees
+// it as the click target instead of <html> (whose null parentElement trips
+// ag grid's isElementWithinCustomPopup check). Only intercept clicks while a
+// popup is actually mounted; otherwise let clicks pass through.
+#ds-popup-parent { pointer-events: auto; }
+#ds-popup-parent:empty { pointer-events: none; }

package/src/utils/PopupParentContext.stories.tsx

@@ -0,0 +1,367 @@
+import { useRef } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Heading as DocHeading,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { PopupParentContext } from 'Utils/PopupParentContext';
+import { Button } from 'Components/button/Button';
+import { Dropdown } from 'Components/dropdown/Dropdown';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`PopupParentContext` is a React context that controls where portalled floating elements',
+  '— dropdowns, tooltips, date pickers, comboboxes — are rendered in the DOM.',
+  'In most applications you do **not** need to configure this: the default behaviour portals all floating',
+  'content to a shared `<div id="ds-popup-parent">` appended to `document.body`.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When you need PopupParentContext',
+  '',
+  '- **Custom virtualised panels** — when your layout clips content with `overflow: hidden` AND you need',
+  '  popups to appear inside that container (not body), provide a ref to a container element inside the',
+  '  clip boundary',
+  '- **Non-Arbor modals and drawers** — if you wrap Arbor components inside a third-party modal, floating',
+  '  elements may render beneath the modal overlay due to z-index stacking. Provide a container inside the',
+  '  modal to keep popups on top',
+  '- **Custom stacking contexts** — when `transform`, `isolation`, or `will-change` creates a stacking',
+  '  context above `z-index: 1` (the default popup parent z-index), popups may appear beneath fixed UI',
+  '  chrome. Move the container inside the stacking context',
+  '',
+  '---',
+  '',
+  '### When you do NOT need PopupParentContext',
+  '',
+  '| Situation | Why you are safe |',
+  '|---|---|',
+  '| `Dropdown`, `Tooltip`, `Combobox` in a standard page layout | Default context portals to `document.body` — no clipping |',
+  '| Floating elements inside Arbor `Modal` | Modal provides its overlay as the popup parent automatically |',
+  '| `Table` column filters | `BooleanFilter` and `TimeFilter` wrap their children in a provider automatically |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Components that consume PopupParentContext',
+  '',
+  '| Component | What gets portalled |',
+  '|---|---|',
+  '| `Dropdown` | `Dropdown.Content` panel |',
+  '| `Tooltip` | Tooltip bubble |',
+  '| `Combobox` | Options listbox |',
+  '| `DatePicker` | Calendar popup |',
+  '| `DateTimePicker` | Calendar + time popup |',
+  '| `Modal` | Modal overlay (also provides itself as parent for any floating elements inside) |',
+  '| `SlideoverManager` | Slideover panel |',
+  '| `Table` column filters | `BooleanFilter`, `TimeFilter` (wraps automatically) |',
+  '',
+  '---',
+  '',
+  '### Usage',
+  '',
+  '```tsx',
+  'import { useRef } from \'react\';',
+  'import { PopupParentContext, Dropdown } from \'@arbor-education/design-system.components\';',
+  '',
+  'function ClippedPanel() {',
+  '  // ref points to the container that should receive portalled content',
+  '  const popupContainerRef = useRef<HTMLDivElement>(null);',
+  '',
+  '  return (',
+  '    <div style={{ position: \'relative\', overflow: \'hidden\', maxHeight: 300 }}>',
+  '      {/*',
+  '        This div sits OUTSIDE the overflow:hidden clip boundary.',
+  '        Floating elements portal here instead of document.body.',
+  '      */}',
+  '      <div ref={popupContainerRef} style={{ position: \'fixed\', zIndex: 100 }} />',
+  '',
+  '      <PopupParentContext.Provider value={popupContainerRef}>',
+  '        <Dropdown>',
+  '          <Dropdown.Trigger>',
+  '            <Button variant="dropdown">Actions</Button>',
+  '          </Dropdown.Trigger>',
+  '          <Dropdown.Content>',
+  '            <Dropdown.Item>Edit record</Dropdown.Item>',
+  '            <Dropdown.Item>Delete record</Dropdown.Item>',
+  '          </Dropdown.Content>',
+  '        </Dropdown>',
+  '      </PopupParentContext.Provider>',
+  '    </div>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### Default behaviour',
+  '',
+  'When no provider wraps your component tree, `PopupParentContext` falls back to a ref pointing to',
+  '`div#ds-popup-parent`. This element is created once and appended to `document.body` with',
+  '`position: fixed; z-index: 1`. All floating elements on the page share it.',
+  '',
+  'You can pre-create this element for SSR environments:',
+  '```html',
+  '<div id="ds-popup-parent" style="position: fixed; z-index: 1;"></div>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Portalling to `document.body` or a fixed container does not break focus management — Radix UI',
+  '  and the DS components handle focus trapping and restoration internally',
+  '- Ensure the portal container has no `aria-hidden` ancestor — this would hide portalled content from',
+  '  assistive technology even if it is visible on screen',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Dropdown](?path=/docs/components-dropdown--docs) · [Tooltip](?path=/docs/components-tooltip--docs) · [Combobox](?path=/docs/components-combobox--docs) · [DatePicker](?path=/docs/components-datepicker--docs) · [Modal](?path=/docs/components-modal--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function PopupParentContextDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <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: 'Utils/PopupParentContext',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: PopupParentContextDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = () => (
+  <div
+    style={{
+      border: 'var(--border-weight) solid var(--color-grey-200)',
+      borderRadius: 'var(--border-radius-small)',
+      padding: 'var(--spacing-medium)',
+      overflow: 'hidden',
+      maxHeight: '120px',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-small)',
+    }}
+  >
+    <p style={{ margin: 0, fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-700)' }}>
+      This panel has
+      {' '}
+      <code>overflow: hidden</code>
+      {' '}
+      — yet the dropdown opens correctly.
+    </p>
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="dropdown">Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>View pupil profile</Dropdown.Item>
+        <Dropdown.Item>Edit enrolment</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item>Remove from group</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  </div>
+);
+
+const WithCustomContainerTemplate = () => {
+  const popupContainerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <div style={{ position: 'relative', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <p style={{ margin: 0, fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-700)' }}>
+        The dropdown portals into
+        {' '}
+        <code>popupContainerRef</code>
+        {' '}
+        (the pink border below) instead of
+        {' '}
+        <code>document.body</code>
+        .
+      </p>
+
+      {/* This element receives portalled content */}
+      <div
+        ref={popupContainerRef}
+        style={{
+          position: 'relative',
+          zIndex: 10,
+          border: '2px dashed var(--color-semantic-destructive-300)',
+          borderRadius: 'var(--border-radius-small)',
+          padding: 'var(--spacing-xsmall)',
+          minHeight: '2rem',
+        }}
+        aria-label="Custom popup container"
+      />
+
+      <PopupParentContext.Provider value={popupContainerRef}>
+        <Dropdown>
+          <Dropdown.Trigger>
+            <Button variant="dropdown">Actions</Button>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>View pupil profile</Dropdown.Item>
+            <Dropdown.Item>Edit enrolment</Dropdown.Item>
+            <Dropdown.Separator />
+            <Dropdown.Item>Remove from group</Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown>
+      </PopupParentContext.Provider>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+// No PopupParentContext setup needed — the dropdown portals to document.body automatically.
+function PupilActionsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="dropdown">Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>View pupil profile</Dropdown.Item>
+        <Dropdown.Item>Edit enrolment</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item>Remove from group</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+export default PupilActionsDropdown;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The default behaviour — no `PopupParentContext` setup required.',
+    'The dropdown portals its content to `div#ds-popup-parent` in `document.body` via the context default.',
+    'Even inside an `overflow: hidden` container, the popup appears correctly because it exits the clip',
+    'boundary by rendering in the body.',
+  ].join(' '),
+);
+
+export const WithCustomContainer: Story = withDescription(
+  {
+    render: WithCustomContainerTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useRef } from 'react';
+import { PopupParentContext, Dropdown, Button } from '@arbor-education/design-system.components';
+
+function ClippedPanel() {
+  const popupContainerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <div style={{ position: 'relative' }}>
+      {/*
+        This container receives portalled popups.
+        Place it outside any overflow:hidden ancestor,
+        with a z-index high enough to appear above surrounding content.
+      */}
+      <div ref={popupContainerRef} style={{ position: 'fixed', zIndex: 100 }} />
+
+      <PopupParentContext.Provider value={popupContainerRef}>
+        <Dropdown>
+          <Dropdown.Trigger>
+            <Button variant="dropdown">Actions</Button>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>View pupil profile</Dropdown.Item>
+            <Dropdown.Item>Edit enrolment</Dropdown.Item>
+            <Dropdown.Separator />
+            <Dropdown.Item>Remove from group</Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown>
+      </PopupParentContext.Provider>
+    </div>
+  );
+}
+export default ClippedPanel;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Override the popup container with `PopupParentContext.Provider`. The `value` prop accepts a',
+    '`RefObject<HTMLElement | null>` pointing to the element that should receive portalled content.',
+    'Open the dropdown to see it appear inside the dashed container (highlighted in pink) instead of',
+    '`document.body`. In production you would omit the visual indicator and size/position the container',
+    'as needed for your layout.',
+  ].join(' '),
+);

package/src/utils/getDefaultPopupParent.ts

@@ -8,6 +8,12 @@ export const getDefaultPopupParent = () => {
   newContainer.id = 'ds-popup-parent';
   newContainer.style.zIndex = '1';
   newContainer.style.position = 'fixed';
+  // ag grid has clamping behaviour for floating elements - it clamps the area
+  // to whichever has the largest boundingRect between its own main container
+  // and whatever is passed to the popupParent prop. without this inset here
+  // the container ends up with a height and width of zero so they get clamped
+  // to the ag container instead of the viewport (most heinous).
+  newContainer.style.inset = '0';
   document.body.appendChild(newContainer);
 
   return newContainer as HTMLElement;