@arbor-education/design-system.components 0.9.0 → 0.11.0

package/src/components/combobox/Combobox.test.tsx

@@ -147,6 +147,30 @@ describe('Combobox', () => {
     expect(search).toHaveFocus();
   });
 
+  test('button trigger keeps popover with search input when filter matches nothing', async () => {
+    const user = userEvent.setup();
+    render(<Combobox options={people} triggerVariant="button" placeholder="Students" />);
+    await user.click(screen.getByRole('button', { name: 'Open suggestions' }));
+
+    const search = screen.getByRole('combobox');
+    await user.type(search, 'zzz');
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(screen.queryAllByRole('option')).toHaveLength(0);
+
+    await user.clear(search);
+    expect(within(screen.getByRole('listbox')).getAllByRole('option')).toHaveLength(people.length);
+  });
+
+  test('button trigger closes popover after single-select option click', async () => {
+    const user = userEvent.setup();
+    render(<Combobox options={people} triggerVariant="button" placeholder="Students" />);
+    await user.click(screen.getByRole('button', { name: 'Open suggestions' }));
+    await user.click(screen.getByText('Alice Johnson'));
+
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+  });
+
   test('button trigger single-select does not show selection count badge', () => {
     render(
       <Combobox
@@ -353,20 +377,22 @@ describe('Combobox', () => {
   });
 
   test('Ctrl+A selects all chips when input is focused', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Control>}a{/Control}');
+    await user.keyboard('{Control>}a{/Control}');
 
     const selectedTags = document.querySelectorAll('.ds-tag--selected');
     expect(selectedTags).toHaveLength(2);
   });
 
   test('Cmd+A selects all chips in single-select mode', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} defaultValue={['alice']} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
     fireEvent.keyDown(input, { key: 'a', metaKey: true });
 
@@ -375,54 +401,58 @@ describe('Combobox', () => {
   });
 
   test('Backspace clears all selected chips after select-all', async () => {
+    const user = userEvent.setup();
     const onValueChange = vi.fn();
     render(
       <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
     );
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Control>}a{/Control}');
-    await userEvent.keyboard('{Backspace}');
+    await user.keyboard('{Control>}a{/Control}');
+    await user.keyboard('{Backspace}');
 
     expect(onValueChange).toHaveBeenLastCalledWith([]);
     expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
   });
 
   test('Delete clears all selected chips after select-all', async () => {
+    const user = userEvent.setup();
     const onValueChange = vi.fn();
     render(
       <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
     );
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Control>}a{/Control}');
-    await userEvent.keyboard('{Delete}');
+    await user.keyboard('{Control>}a{/Control}');
+    await user.keyboard('{Delete}');
 
     expect(onValueChange).toHaveBeenLastCalledWith([]);
     expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
   });
 
   test('typing after chip select-all clears selected chip styling', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Control>}a{/Control}');
+    await user.keyboard('{Control>}a{/Control}');
     expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(2);
 
-    await userEvent.type(input, 'c');
+    await user.type(input, 'c');
 
     expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
   });
 
   test('Ctrl+A with no chips keeps native input behavior and does not crash', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Control>}a{/Control}');
+    await user.keyboard('{Control>}a{/Control}');
 
     expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
   });
@@ -582,21 +612,23 @@ describe('Combobox', () => {
   });
 
   test('keyboard: ArrowDown opens the listbox', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{ArrowDown}');
+    await user.keyboard('{ArrowDown}');
 
     expect(screen.getByRole('listbox')).toBeInTheDocument();
   });
 
   test('keyboard: Alt+ArrowDown opens the listbox', async () => {
+    const user = userEvent.setup();
     render(<Combobox options={people} />);
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Alt>}{ArrowDown}{/Alt}');
+    await user.keyboard('{Alt>}{ArrowDown}{/Alt}');
 
     expect(screen.getByRole('listbox')).toBeInTheDocument();
   });
@@ -639,14 +671,15 @@ describe('Combobox', () => {
   });
 
   test('keyboard: Backspace on empty input removes last chip', async () => {
+    const user = userEvent.setup();
     const onValueChange = vi.fn();
     render(
       <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
     );
     const input = screen.getByRole('combobox');
-    input.focus();
+    await user.click(input);
 
-    await userEvent.keyboard('{Backspace}');
+    await user.keyboard('{Backspace}');
 
     expect(onValueChange).toHaveBeenCalledWith(['alice']);
   });
@@ -722,7 +755,7 @@ describe('Combobox', () => {
 
     expect(onCreateNew).toHaveBeenCalledWith('Taylor');
     expect(onValueChange).toHaveBeenCalledWith(['new-taylor']);
-    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
   });
 
   test('allowCreate duplicate prevention selects existing option', async () => {
@@ -1044,131 +1077,141 @@ describe('Combobox', () => {
   });
 
   describe('chip keyboard navigation', () => {
-    test('ArrowLeft at caret 0 focuses the last chip', () => {
+    test('ArrowLeft at caret 0 focuses the last chip', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
 
       const tags = document.querySelectorAll('.ds-tag');
       expect(tags[1]).toHaveClass('ds-tag--selected');
       expect(tags[0]).not.toHaveClass('ds-tag--selected');
     });
 
-    test('ArrowLeft navigates through chips from right to left', () => {
+    test('ArrowLeft navigates through chips from right to left', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob', 'charlie']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowLeft}');
 
       const tags = document.querySelectorAll('.ds-tag');
       expect(tags[1]).toHaveClass('ds-tag--selected');
       expect(tags[2]).not.toHaveClass('ds-tag--selected');
     });
 
-    test('ArrowLeft does not go past the first chip', () => {
+    test('ArrowLeft does not go past the first chip', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowLeft}');
 
       const tags = document.querySelectorAll('.ds-tag');
       expect(tags[0]).toHaveClass('ds-tag--selected');
     });
 
-    test('ArrowRight past the last chip returns focus to input (exits chip nav)', () => {
+    test('ArrowRight past the last chip returns focus to input (exits chip nav)', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
 
-      fireEvent.keyDown(input, { key: 'ArrowRight' });
+      await user.keyboard('{ArrowRight}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
     });
 
-    test('Backspace on focused chip removes it', () => {
+    test('Backspace on focused chip removes it', async () => {
+      const user = userEvent.setup();
       const onValueChange = vi.fn();
       render(
         <Combobox options={people} multiple defaultValue={['alice', 'bob', 'charlie']} onValueChange={onValueChange} />,
       );
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'Backspace' });
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{Backspace}');
 
       expect(onValueChange).toHaveBeenCalledWith(['alice', 'charlie']);
     });
 
-    test('Delete on focused chip removes it', () => {
+    test('Delete on focused chip removes it', async () => {
+      const user = userEvent.setup();
       const onValueChange = vi.fn();
       render(
         <Combobox options={people} multiple defaultValue={['alice', 'bob']} onValueChange={onValueChange} />,
       );
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'Delete' });
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{Delete}');
 
       expect(onValueChange).toHaveBeenCalledWith(['bob']);
     });
 
-    test('Backspace on first chip focuses next or exits', () => {
+    test('Backspace on first chip focuses next or exits', async () => {
+      const user = userEvent.setup();
       const onValueChange = vi.fn();
       render(
         <Combobox options={people} multiple defaultValue={['alice']} onValueChange={onValueChange} />,
       );
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
-      fireEvent.keyDown(input, { key: 'Backspace' });
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{Backspace}');
 
       expect(onValueChange).toHaveBeenCalledWith([]);
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
     });
 
     test('typing exits chip nav mode', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
 
-      await userEvent.type(input, 'c');
+      await user.type(input, 'c');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
     });
 
-    test('Escape exits chip nav mode', () => {
+    test('Escape exits chip nav mode', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
 
-      fireEvent.keyDown(input, { key: 'Escape' });
+      await user.keyboard('{Escape}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(0);
     });
 
-    test('Cmd+A during chip nav enters bulk-select-all mode', () => {
+    test('Cmd+A during chip nav enters bulk-select-all mode', async () => {
+      const user = userEvent.setup();
       render(<Combobox options={people} multiple defaultValue={['alice', 'bob']} />);
       const input = screen.getByRole('combobox');
-      input.focus();
+      await user.click(input);
 
-      fireEvent.keyDown(input, { key: 'ArrowLeft' });
+      await user.keyboard('{ArrowLeft}');
       expect(document.querySelectorAll('.ds-tag--selected')).toHaveLength(1);
 
       fireEvent.keyDown(input, { key: 'a', metaKey: true });

package/src/components/combobox/Combobox.tsx

@@ -108,6 +108,8 @@ const ComboboxRoot = (props: ComboboxProps): React.JSX.Element => {
     exitChipNav,
   } = useChipSelection(chipKeyboardEnabled ? selectedValues : []);
 
+  const renderSearchInputInListbox = triggerVariant === 'button';
+
   const {
     shouldRenderPopoverContent,
     shouldShowPopover,
@@ -139,6 +141,7 @@ const ComboboxRoot = (props: ComboboxProps): React.JSX.Element => {
     clearChipSelection,
     exitChipNav,
     triggerContainsInput: triggerVariant === 'input',
+    renderSearchInputInListbox,
   });
 
   const optionGroups = useMemo(() => buildOptionGroups(filteredOptions), [filteredOptions]);
@@ -250,7 +253,6 @@ const ComboboxRoot = (props: ComboboxProps): React.JSX.Element => {
   const preventMouseDefault = useCallback((e: React.MouseEvent) => {
     e.preventDefault();
   }, []);
-  const renderSearchInputInListbox = triggerVariant === 'button';
 
   const handlePopoverOpenAutoFocus = useCallback(
     (e: Event) => {

package/src/components/combobox/useComboboxPopoverBehavior.ts

@@ -26,6 +26,8 @@ type UseComboboxPopoverBehaviorParams = {
   clearChipSelection: () => void;
   exitChipNav: () => void;
   triggerContainsInput?: boolean;
+  /** Search field is inside the popover (button trigger); keep shell mounted while open even with zero matches. */
+  renderSearchInputInListbox: boolean;
 };
 
 export type UseComboboxPopoverBehaviorReturn = {
@@ -61,10 +63,13 @@ export const useComboboxPopoverBehavior = ({
   clearChipSelection,
   exitChipNav,
   triggerContainsInput = true,
+  renderSearchInputInListbox,
 }: UseComboboxPopoverBehaviorParams): UseComboboxPopoverBehaviorReturn => {
-  const shouldRenderPopoverContent = loading || totalItems > 0;
+  const shouldRenderPopoverContent
+    = loading || totalItems > 0 || (renderSearchInputInListbox && isOpen);
   const shouldShowPopover = isOpen && shouldRenderPopoverContent;
   const showListboxLoading = Boolean(loading && shouldShowPopover);
+  const canOpenPopover = loading || totalItems > 0 || renderSearchInputInListbox;
 
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -110,10 +115,10 @@ export const useComboboxPopoverBehavior = ({
 
   const requestOpen = useCallback(() => {
     if (disabled) return;
-    if (shouldRenderPopoverContent) {
+    if (canOpenPopover) {
       openPopover();
     }
-  }, [disabled, openPopover, shouldRenderPopoverContent]);
+  }, [disabled, openPopover, canOpenPopover]);
 
   const handleTriggerClick = useCallback(() => {
     if (disabled) return;
@@ -148,11 +153,11 @@ export const useComboboxPopoverBehavior = ({
       if (triggerContainsInput) {
         inputRef.current?.focus();
       }
-      if (shouldRenderPopoverContent) {
+      if (canOpenPopover) {
         openPopover();
       }
     },
-    [disabled, inputRef, openPopover, shouldRenderPopoverContent, triggerContainsInput],
+    [disabled, inputRef, openPopover, canOpenPopover, triggerContainsInput],
   );
 
   const handlePopoverInteractOutside = useCallback(

package/src/components/combobox/useComboboxState.ts

@@ -129,8 +129,11 @@ export const useComboboxState = (params: UseComboboxStateParams): UseComboboxSta
         : [optionValue];
       updateValue(next);
       setQuery('');
+      if (!multiple) {
+        setIsOpen(false);
+      }
     },
-    [multiple, selectedValues, selectedValuesSet, updateValue],
+    [multiple, selectedValues, selectedValuesSet, setIsOpen, updateValue],
   );
 
   const removeValue = useCallback(

package/src/components/datePicker/DatePicker.stories.tsx

@@ -5,17 +5,35 @@ import { DatePicker } from './DatePicker';
 const meta = {
   title: 'Components/DatePicker',
   component: DatePicker,
+  decorators: [
+    Story => (
+      <div style={{ maxWidth: '220px', width: '100%' }}>
+        <Story />
+      </div>
+    ),
+  ],
   parameters: {
     layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '`DatePicker` uses a native `type="date"` input (`yyyy-MM-dd`) with a synced calendar popover. When empty, hint copy uses a decorative span (browsers do not reliably show `placeholder` on native date fields). `displayFormat` controls that hint (`DD/MM/YYYY` vs `Pick a date`). The custom month/year header uses the design-system select control.',
+      },
+    },
   },
   tags: ['autodocs'],
   args: {
     onChange: fn(),
   },
   argTypes: {
-    dateFormat: {
+    displayFormat: {
+      control: 'inline-radio',
+      options: ['default', 'friendly'],
+      description: 'Controls the empty-state hint text (`DD/MM/YYYY` vs `Pick a date`). The field value is always native ISO `yyyy-MM-dd`.',
+    },
+    placeholder: {
       control: 'text',
-      description: 'Date format string using date-fns tokens (e.g. "dd/MM/yyyy", "MM/dd/yyyy", "yyyy-MM-dd")',
+      description: 'Optional override for the empty-state hint (defaults from `displayFormat`).',
     },
     className: {
       control: 'text',
@@ -30,18 +48,58 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = {};
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Empty field shows hint **DD/MM/YYYY** (`displayFormat="default"`).',
+      },
+    },
+  },
+};
 
-export const USDateFormat: Story = {
-  name: 'US Date Format (MM/dd/yyyy)',
+export const FriendlyFormat: Story = {
+  name: 'Friendly Format',
   args: {
-    dateFormat: 'MM/dd/yyyy',
+    displayFormat: 'friendly',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Empty field shows hint **Pick a date**.',
+      },
+    },
   },
 };
 
-export const ISOFormat: Story = {
-  name: 'ISO Format (yyyy-MM-dd)',
+/** `placeholder` overrides the default empty-state hint. */
+export const PlaceholderCustomOverride: Story = {
+  name: 'Placeholder · custom copy',
   args: {
-    dateFormat: 'yyyy-MM-dd',
+    displayFormat: 'default',
+    placeholder: 'e.g. 25/12/2024',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The optional `placeholder` prop replaces the default hint.',
+      },
+    },
+  },
+};
+
+/** Friendly format with custom hint copy. */
+export const PlaceholderFriendlyWithCustomCopy: Story = {
+  name: 'Placeholder · friendly format, custom hint',
+  args: {
+    displayFormat: 'friendly',
+    placeholder: 'Choose a date…',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: '`displayFormat="friendly"` with a custom hint instead of **Pick a date**.',
+      },
+    },
   },
 };