@arbor-education/design-system.components 2.0.1 → 2.2.0

package/src/components/breadcrumbs/BreadcrumbDropdown.tsx

@@ -1,7 +1,37 @@
 import { Dropdown } from 'Components/dropdown/Dropdown';
-import type { BreadcrumbDropdownProps } from './types.js';
+import type { BreadcrumbDropdownProps, BreadcrumbItem } from './types.js';
 import { BreadcrumbLink } from './BreadcrumbLink.js';
 
+const renderOption = (option: BreadcrumbItem, index: number) => {
+  const key = `${option.label}-${index}`;
+  const hasNestedOptions = Boolean(option.dropdownOptions?.length);
+
+  if (hasNestedOptions) {
+    if (process.env.NODE_ENV !== 'production' && (option.href || option.onClick)) {
+      console.warn(
+        `BreadcrumbDropdown: option "${option.label}" has dropdownOptions as well as an href/onClick. It will render as a submenu trigger only — its own href/onClick will not be used.`,
+      );
+    }
+
+    return (
+      <Dropdown.Sub key={key}>
+        <Dropdown.SubTrigger>{option.label}</Dropdown.SubTrigger>
+        <Dropdown.SubContent>
+          {option.dropdownOptions?.map(renderOption)}
+        </Dropdown.SubContent>
+      </Dropdown.Sub>
+    );
+  }
+
+  return (
+    <Dropdown.Item asChild key={key}>
+      <a href={option.href} onClick={() => option.onClick?.()}>
+        {option.label}
+      </a>
+    </Dropdown.Item>
+  );
+};
+
 export const BreadcrumbDropdown = (props: BreadcrumbDropdownProps) => {
   const { item } = props;
   return (
@@ -14,13 +44,7 @@ export const BreadcrumbDropdown = (props: BreadcrumbDropdownProps) => {
         />
       </Dropdown.Trigger>
       <Dropdown.Content>
-        {item.dropdownOptions?.map((option, index) => (
-          <Dropdown.Item asChild key={`${option.label}-${index}`}>
-            <a href={option.href} onClick={() => option.onClick?.()}>
-              {option.label}
-            </a>
-          </Dropdown.Item>
-        ))}
+        {item.dropdownOptions?.map(renderOption)}
       </Dropdown.Content>
     </Dropdown>
   );

package/src/components/breadcrumbs/Breadcrumbs.stories.tsx

@@ -150,7 +150,7 @@ const meta = {
         'Array of `BreadcrumbItem` objects that define the trail.',
         'Each item has: `label` (string, required — also used as the clipboard copy text),',
         '`href` (string, optional — used for all items except the last, which is always non-navigable regardless of whether `href` is set),',
-        '`dropdownOptions` (array of `BreadcrumbItem`, optional — renders a dropdown trigger; items may themselves have `dropdownOptions` for nested menus),',
+        '`dropdownOptions` (array of `BreadcrumbItem`, optional — renders a dropdown trigger; items may themselves have `dropdownOptions` for nested menus). If an item has `dropdownOptions`, its own `href`/`onClick` are not used — it renders as a submenu trigger only, not a link,',
         '`isEllipsis` (boolean, optional — renders an icon-only ellipsis button),',
         '`onClick` (function, optional — forwarded to the ellipsis button; use to expand a collapsed trail).',
       ].join(' '),
@@ -516,6 +516,73 @@ export default WithDropdownBreadcrumb;
   ].join(' '),
 );
 
+export const NestedDropdownOptions: Story = withDescription(
+  {
+    render: () => (
+      <Breadcrumbs
+        breadcrumbLabel="Breadcrumb"
+        items={[
+          { label: 'Home', href: '/' },
+          {
+            label: 'Students',
+            href: '/students',
+            dropdownOptions: [
+              { label: 'All students', href: '/students' },
+              {
+                label: 'Tutor groups',
+                dropdownOptions: [
+                  { label: 'Group A', href: '/students/tutor-group/a' },
+                  { label: 'Group B', href: '/students/tutor-group/b' },
+                ],
+              },
+            ],
+          },
+          { label: 'Current page', href: '/current' },
+        ]}
+      />
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function NestedDropdownOptionsBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        {
+          label: 'Students',
+          href: '/students',
+          dropdownOptions: [
+            { label: 'All students', href: '/students' },
+            {
+              label: 'Tutor groups',
+              dropdownOptions: [
+                { label: 'Group A', href: '/students/tutor-group/a' },
+                { label: 'Group B', href: '/students/tutor-group/b' },
+              ],
+            },
+          ],
+        },
+        { label: 'Current page', href: '/current' },
+      ]}
+    />
+  );
+}
+export default NestedDropdownOptionsBreadcrumb;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Any `dropdownOptions` entry can itself have `dropdownOptions` — here "Tutor groups" renders as a submenu trigger that cascades into a nested popover on hover or click. A nested entry\'s own `href`/`onClick` are not used — it is a pure submenu trigger, not a link.',
+);
+
 export const MultipleDropdowns: Story = withDescription(
   {
     render: () => (

package/src/components/breadcrumbs/Breadcrumbs.test.tsx

@@ -1,5 +1,6 @@
 import { describe, expect, test, vi, beforeEach } from 'vitest';
 import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import '@testing-library/jest-dom/vitest';
 import { Breadcrumbs } from './Breadcrumbs.js';
 
@@ -182,4 +183,80 @@ describe('Breadcrumbs', () => {
       expect(screen.getByRole('button', { name: 'Students' })).toHaveAttribute('tabindex', '0');
     });
   });
+
+  describe('nested dropdown item', () => {
+    const itemsWithNestedDropdown = [
+      { label: 'Home', href: '/' },
+      {
+        label: 'Students',
+        href: '/students',
+        dropdownOptions: [
+          { label: 'All students', href: '/students' },
+          {
+            label: 'Tutor groups',
+            dropdownOptions: [
+              { label: 'Group A', href: '/students/tutor-group/a' },
+              { label: 'Group B', href: '/students/tutor-group/b' },
+            ],
+          },
+        ],
+      },
+      { label: 'Current page', href: '/current' },
+    ];
+
+    test('renders a nested option as a submenu trigger, not a link', async () => {
+      render(<Breadcrumbs items={itemsWithNestedDropdown} breadcrumbLabel="Breadcrumb" />);
+
+      await userEvent.click(screen.getByRole('button', { name: 'Students' }));
+
+      const subTrigger = await screen.findByText('Tutor groups');
+      expect(subTrigger.closest('a')).not.toBeInTheDocument();
+      expect(subTrigger.closest('[role="menuitem"]')).toHaveAttribute('aria-haspopup', 'menu');
+    });
+
+    test('reveals second-level options when the nested trigger is clicked', async () => {
+      render(<Breadcrumbs items={itemsWithNestedDropdown} breadcrumbLabel="Breadcrumb" />);
+
+      await userEvent.click(screen.getByRole('button', { name: 'Students' }));
+      await userEvent.click(await screen.findByText('Tutor groups'));
+
+      expect(await screen.findByRole('menuitem', { name: 'Group A' })).toHaveAttribute('href', '/students/tutor-group/a');
+      expect(screen.getByRole('menuitem', { name: 'Group B' })).toHaveAttribute('href', '/students/tutor-group/b');
+    });
+
+    test('leaf-level dropdown options without nested dropdownOptions still render as links', async () => {
+      render(<Breadcrumbs items={itemsWithNestedDropdown} breadcrumbLabel="Breadcrumb" />);
+
+      await userEvent.click(screen.getByRole('button', { name: 'Students' }));
+
+      expect(await screen.findByRole('menuitem', { name: 'All students' })).toHaveAttribute('href', '/students');
+    });
+
+    test('warns in development when a nested option also has an href', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const itemsWithHrefAndNestedOptions = [
+        { label: 'Home', href: '/' },
+        {
+          label: 'Students',
+          href: '/students',
+          dropdownOptions: [
+            {
+              label: 'Tutor groups',
+              href: '/tutor-groups',
+              dropdownOptions: [
+                { label: 'Group A', href: '/students/tutor-group/a' },
+              ],
+            },
+          ],
+        },
+      ];
+
+      render(<Breadcrumbs items={itemsWithHrefAndNestedOptions} breadcrumbLabel="Breadcrumb" />);
+      await userEvent.click(screen.getByRole('button', { name: 'Students' }));
+
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Tutor groups'));
+
+      warnSpy.mockRestore();
+    });
+  });
 });

package/src/components/dropdown/Dropdown.stories.tsx

@@ -20,7 +20,7 @@ const TRIGGER_PROPS = `
 const CONTENT_PROPS = `
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| \`children\` | \`React.ReactNode\` | — | The menu content — \`Dropdown.Item\`, \`Dropdown.SelectItem\`, \`Dropdown.Separator\`, and \`Dropdown.Group\` elements. |
+| \`children\` | \`React.ReactNode\` | — | The menu content — \`Dropdown.Item\`, \`Dropdown.SelectItem\`, \`Dropdown.Separator\`, \`Dropdown.Group\`, and \`Dropdown.Sub\` elements. |
 | \`contentProps\` | \`DropdownMenuContentProps\` | — | Passed to the Radix \`DropdownMenu.Content\`. Key values: \`align\` (\`'start' \\| 'center' \\| 'end'\`, default \`'start'\`), \`side\` (\`'top' \\| 'right' \\| 'bottom' \\| 'left'\`, default \`'bottom'\`), \`sideOffset\` (gap in px), \`avoidCollisions\` (auto-flip when clipped, default \`true\`). |
 | \`portalProps\` | \`DropdownMenuPortalProps\` | — | Passed to the Radix \`DropdownMenu.Portal\`. Rarely needed — content already renders via \`PopupParentContext\`. |
 | \`className\` | \`string\` | \`''\` | Additional CSS class for the content panel. |
@@ -60,6 +60,35 @@ const SEPARATOR_PROPS = `
 | \`className\` | \`string\` | \`''\` | Additional CSS class. The separator renders as a zero-config horizontal rule with no configurable content. |
 `.trim();
 
+const SUB_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | The submenu tree — a \`Dropdown.SubTrigger\` and a \`Dropdown.SubContent\`. |
+| \`open\` | \`boolean\` | — | Controlled open state for the submenu. Pair with \`onOpenChange\` to drive it externally. |
+| \`onOpenChange\` | \`(open: boolean) => void\` | — | Callback fired when the submenu's open state changes. |
+| \`defaultOpen\` | \`boolean\` | \`false\` | Initial open state for uncontrolled mode. |
+
+\`Dropdown.Sub\` accepts the standard Radix \`DropdownMenuSubProps\` — it has no custom props of its own and wraps its \`children\` in a Radix \`DropdownMenu.Sub\`.
+`.trim();
+
+const SUB_TRIGGER_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | Submenu trigger label. A trailing chevron-right icon is always rendered automatically — there is no separate icon prop. |
+| \`disabled\` | \`boolean\` | \`false\` | Prevents the submenu from opening. |
+
+Accepts the standard Radix \`DropdownMenuSubTriggerProps\`.
+`.trim();
+
+const SUB_CONTENT_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | **Required.** The submenu content — \`Dropdown.Item\`, \`Dropdown.SelectItem\`, \`Dropdown.Separator\`, \`Dropdown.Group\`, and further nested \`Dropdown.Sub\` elements. |
+| \`contentProps\` | \`DropdownMenuSubContentProps\` | — | Passed to the Radix \`DropdownMenu.SubContent\`. |
+| \`portalProps\` | \`DropdownMenuPortalProps\` | — | Passed to the Radix \`DropdownMenu.Portal\`. Rarely needed — content already renders via \`PopupParentContext\`. |
+| \`className\` | \`string\` | \`''\` | Additional CSS class for the submenu panel. |
+`.trim();
+
 const DESCRIPTION_INTRO = [
   'A **non-blocking popup menu** built on [Radix UI\'s DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) primitive.',
   '`modal={false}` is hardcoded — the background is never blocked, letting users continue interacting with the rest of the page while the menu is open.',
@@ -100,6 +129,12 @@ const USAGE_GUIDANCE = [
   '        Year 7',
   '      </Dropdown.SelectItem>',
   '    </Dropdown.Group>',
+  '    <Dropdown.Sub>',
+  '      <Dropdown.SubTrigger>More options</Dropdown.SubTrigger>',
+  '      <Dropdown.SubContent>',
+  '        <Dropdown.Item onSelect={fn}>Settings</Dropdown.Item>',
+  '      </Dropdown.SubContent>',
+  '    </Dropdown.Sub>',
   '  </Dropdown.Content>',
   '</Dropdown>',
   '```',
@@ -134,6 +169,9 @@ const DEVELOPER_NOTES = [
   '- **Trigger**: Radix sets `aria-expanded` on the trigger automatically.',
   '- **Disabled items**: rendered with `aria-disabled="true"` and `pointer-events: none` — still readable by',
   '  screen readers but cannot be activated.',
+  '- **Submenus**: `Dropdown.SubTrigger` carries `aria-haspopup="menu"` and `aria-expanded`, and opens on',
+  '  click or hover. When focused, `ArrowRight` opens the submenu and `ArrowLeft` closes it and returns',
+  '  focus to the trigger — standard Radix `DropdownMenu.Sub` behaviour.',
 ].join('\n');
 
 const RELATED_COMPONENTS = [
@@ -166,6 +204,12 @@ function DropdownDocsPage() {
       <Markdown>{GROUP_PROPS}</Markdown>
       <Subheading>Dropdown.Separator props</Subheading>
       <Markdown>{SEPARATOR_PROPS}</Markdown>
+      <Subheading>Dropdown.Sub props</Subheading>
+      <Markdown>{SUB_PROPS}</Markdown>
+      <Subheading>Dropdown.SubTrigger props</Subheading>
+      <Markdown>{SUB_TRIGGER_PROPS}</Markdown>
+      <Subheading>Dropdown.SubContent props</Subheading>
+      <Markdown>{SUB_CONTENT_PROPS}</Markdown>
       <Heading>Usage guidance</Heading>
       <Markdown>{USAGE_GUIDANCE}</Markdown>
       <Heading>Developer notes</Heading>
@@ -875,6 +919,63 @@ export default RecordOptionsDropdown;`,
   'You can mix `Dropdown.Item` (one-shot actions) and `Dropdown.SelectItem` (toggles) in the same content panel, separated by `Dropdown.Separator`. Here the top section has navigational actions, the middle has export format toggles (multi-select, stays open), and the bottom has a final action. This mirrors real Arbor pages where you might want both "go somewhere" and "configure how you export" in one menu.',
 );
 
+export const NestedDropdowns: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)' }}>
+        <Dropdown>
+          <Dropdown.Trigger>
+            <Button variant="secondary">Open menu</Button>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item onSelect={() => console.log('profile')}>Profile</Dropdown.Item>
+            <Dropdown.Sub>
+              <Dropdown.SubTrigger>More options</Dropdown.SubTrigger>
+              <Dropdown.SubContent>
+                <Dropdown.Item onSelect={() => console.log('settings')}>Settings</Dropdown.Item>
+                <Dropdown.Item onSelect={() => console.log('help')}>Help</Dropdown.Item>
+              </Dropdown.SubContent>
+            </Dropdown.Sub>
+            <Dropdown.Item onSelect={() => console.log('logout')}>Log out</Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown>
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function NestedOptionsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Open menu</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item onSelect={() => console.log('profile')}>Profile</Dropdown.Item>
+        <Dropdown.Sub>
+          <Dropdown.SubTrigger>More options</Dropdown.SubTrigger>
+          <Dropdown.SubContent>
+            <Dropdown.Item onSelect={() => console.log('settings')}>Settings</Dropdown.Item>
+            <Dropdown.Item onSelect={() => console.log('help')}>Help</Dropdown.Item>
+          </Dropdown.SubContent>
+        </Dropdown.Sub>
+        <Dropdown.Item onSelect={() => console.log('logout')}>Log out</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default NestedOptionsDropdown;`,
+        },
+      },
+    },
+  },
+  '`Dropdown.Sub`, `Dropdown.SubTrigger`, and `Dropdown.SubContent` render a cascading submenu — hover or focus "More options" to open a second-level menu without leaving the parent. Use nested submenus sparingly, for secondary actions that would otherwise clutter the top-level menu (e.g. burying rarely-used settings behind a "More options" item).',
+);
+
 export const WithIcons: Story = withDescription(
   {
     render: () => (

package/src/components/dropdown/Dropdown.test.tsx

@@ -365,4 +365,51 @@ describe('Dropdown component', () => {
       expect(item).toBeInTheDocument();
     });
   });
+
+  describe('nested dropdown (Sub)', () => {
+    const renderNestedDropdown = (itemProps: Partial<Dropdown.ItemProps> = {}) => render(
+      <Dropdown>
+        <Dropdown.Trigger>
+          <Button>Open Menu</Button>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Sub>
+            <Dropdown.SubTrigger>More options</Dropdown.SubTrigger>
+            <Dropdown.SubContent>
+              <Dropdown.Item {...itemProps}>Nested item</Dropdown.Item>
+            </Dropdown.SubContent>
+          </Dropdown.Sub>
+        </Dropdown.Content>
+      </Dropdown>,
+    );
+
+    test('renders sub trigger with a chevron-right icon', async () => {
+      renderNestedDropdown();
+
+      await userEvent.click(screen.getByText('Open Menu'));
+
+      const subTrigger = await screen.findByText('More options');
+      expect(subTrigger.closest('[role="menuitem"]')?.querySelector('.ds-icon-chevron-right')).toBeInTheDocument();
+    });
+
+    test('opens sub content when the sub trigger is clicked', async () => {
+      renderNestedDropdown();
+
+      await userEvent.click(screen.getByText('Open Menu'));
+      await userEvent.click(await screen.findByText('More options'));
+
+      expect(await screen.findByText('Nested item')).toBeInTheDocument();
+    });
+
+    test('fires click handler on a nested item inside sub content', async () => {
+      const handleClick = vi.fn();
+      renderNestedDropdown({ onClick: handleClick });
+
+      await userEvent.click(screen.getByText('Open Menu'));
+      await userEvent.click(await screen.findByText('More options'));
+      await userEvent.click(await screen.findByText('Nested item'));
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/components/dropdown/Dropdown.tsx

@@ -5,6 +5,9 @@ import { DropdownItem } from './items/DropdownItem.js';
 import { DropdownSelectItem, type DropdowSelectItemProps } from './items/DropdownSelectItem.js';
 import { DropdownSeparator } from './items/DropdownSeparator.js';
 import { DropdownGroup } from './items/DropdownGroup.js';
+import { DropdownSub, type DropdownSubProps } from './DropdownSub.js';
+import { DropdownSubTrigger, type DropdownSubTriggerProps } from './items/DropdownSubTrigger.js';
+import { DropdownSubContent, type DropdownSubContentProps } from './DropdownSubContent.js';
 
 export const Dropdown = (props: DropdownMenu.DropdownMenuProps) => {
   const { children, ...rest } = props;
@@ -21,6 +24,9 @@ Dropdown.Item = DropdownItem;
 Dropdown.SelectItem = DropdownSelectItem;
 Dropdown.Separator = DropdownSeparator;
 Dropdown.Group = DropdownGroup;
+Dropdown.Sub = DropdownSub;
+Dropdown.SubTrigger = DropdownSubTrigger;
+Dropdown.SubContent = DropdownSubContent;
 
 export namespace Dropdown {
   export type Props = DropdownMenu.DropdownMenuProps;
@@ -30,4 +36,7 @@ export namespace Dropdown {
   export type SelectItemProps = DropdowSelectItemProps;
   export type SeparatorProps = DropdownMenu.DropdownMenuSeparatorProps;
   export type GroupProps = DropdownMenu.DropdownMenuGroupProps;
+  export type SubProps = DropdownSubProps;
+  export type SubTriggerProps = DropdownSubTriggerProps;
+  export type SubContentProps = DropdownSubContentProps;
 }

package/src/components/dropdown/DropdownSub.tsx

@@ -0,0 +1,5 @@
+import { DropdownMenu } from 'radix-ui';
+
+export type DropdownSubProps = DropdownMenu.DropdownMenuSubProps;
+
+export const DropdownSub = (props: DropdownSubProps) => <DropdownMenu.Sub {...props} />;

package/src/components/dropdown/DropdownSubContent.tsx

@@ -0,0 +1,24 @@
+import classNames from 'classnames';
+import { DropdownMenu } from 'radix-ui';
+import { useContext } from 'react';
+import { PopupParentContext } from 'Utils/popupParent/PopupParentContext';
+
+export type DropdownSubContentProps = {
+  children: React.ReactNode;
+  portalProps?: DropdownMenu.DropdownMenuPortalProps;
+  contentProps?: DropdownMenu.DropdownMenuSubContentProps;
+  className?: string;
+};
+
+export const DropdownSubContent = (props: DropdownSubContentProps) => {
+  const { children, portalProps, contentProps, className = '' } = props;
+  const popupParentRef = useContext(PopupParentContext);
+
+  return (
+    <DropdownMenu.Portal {...portalProps} container={popupParentRef.current}>
+      <DropdownMenu.SubContent {...contentProps} className={classNames('ds-dropdown__content', className)}>
+        {children}
+      </DropdownMenu.SubContent>
+    </DropdownMenu.Portal>
+  );
+};

package/src/components/dropdown/dropdown.scss

@@ -53,3 +53,18 @@
     width: 100%;
     background-color: var(--color-grey-200);
 }
+
+.ds-dropdown__sub-trigger {
+    &[data-state="open"] {
+        background: var(--form-dropdown-form-drop-item-hover-color-background);
+
+        &:focus-visible {
+            background: var(--form-dropdown-form-drop-item-hover-color-background);
+            outline: none;
+        }
+    }
+
+    .ds-dropdown__sub-trigger-icon {
+        margin-left: auto;
+    }
+}

package/src/components/dropdown/items/DropdownSubTrigger.tsx

@@ -0,0 +1,18 @@
+import classNames from 'classnames';
+import { DropdownMenu } from 'radix-ui';
+import { Icon } from 'Components/icon/Icon';
+
+export type DropdownSubTriggerProps = DropdownMenu.DropdownMenuSubTriggerProps;
+
+export const DropdownSubTrigger = (props: DropdownSubTriggerProps) => {
+  const { children, className = '', ...rest } = props;
+  return (
+    <DropdownMenu.SubTrigger
+      className={classNames('ds-dropdown__item ds-dropdown__sub-trigger', className)}
+      {...rest}
+    >
+      {children}
+      <Icon className="ds-dropdown__sub-trigger-icon" name="chevron-right" size={16} />
+    </DropdownMenu.SubTrigger>
+  );
+};