@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -9,10 +9,11 @@
  * SYNC: When ComplexSelector.tsx API changes, update these tests.
  */
 
-import React from 'react';
+import React, {useLayoutEffect} from 'react';
 import {beforeEach, describe, expect, it, vi} from 'vitest';
 import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {Button} from '../Button/Button';
 import {ComplexSelector, type ComplexSelectorHandle} from './ComplexSelector';
 
 const originalMatches = HTMLElement.prototype.matches;
@@ -151,13 +152,13 @@ describe('ComplexSelector', () => {
       />,
     );
 
-    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit blend'}));
     await user.click(
       screen.getByRole('gridcell', {name: 'Banana Juicy', ...h}),
     );
 
     expect(onChange).toHaveBeenCalledWith({fruit: 'Banana', ripeness: 'Juicy'});
-    expect(screen.getByRole('button', {name: 'Fruit blend'})).toHaveAttribute(
+    expect(screen.getByRole('combobox', {name: 'Fruit blend'})).toHaveAttribute(
       'aria-expanded',
       'false',
     );
@@ -171,7 +172,7 @@ describe('ComplexSelector', () => {
         onChange={() => {}}
       />,
     );
-    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit blend'}));
     const popup = document.querySelector('[popover]') as HTMLElement;
     expect(popup).not.toBeNull();
     // The clearance rides the edge facing the trigger and the viewport gutter
@@ -198,7 +199,7 @@ describe('ComplexSelector', () => {
       />,
     );
 
-    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit blend'}));
     await user.click(
       screen.getByRole('gridcell', {name: 'Banana Crisp', ...h}),
     );
@@ -212,6 +213,121 @@ describe('ComplexSelector', () => {
     });
   });
 
+  it('blocks a commit helper kept from an enabled render once disabled', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const kept: {current: ((value: string) => void) | null} = {current: null};
+    const renderSelector = (isDisabled: boolean) => (
+      <ComplexSelector
+        label="Fruit"
+        value="Apple"
+        isDisabled={isDisabled}
+        onChange={onChange}>
+        {(_value, commit) => {
+          kept.current ??= commit;
+          return <span>Choices</span>;
+        }}
+      </ComplexSelector>
+    );
+    const {rerender} = render(renderSelector(false));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit'}));
+    expect(kept.current).not.toBeNull();
+    rerender(renderSelector(true));
+    act(() => kept.current?.('Banana'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('blocks a commit from content in the render that disables it', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    function CommitOnDisable({
+      isDisabled,
+      commit,
+    }: {
+      isDisabled: boolean;
+      commit: (value: string) => void;
+    }) {
+      useLayoutEffect(() => {
+        if (isDisabled) {
+          commit('Banana');
+        }
+      }, [isDisabled, commit]);
+      return <span>Choices</span>;
+    }
+    const renderSelector = (isDisabled: boolean) => (
+      <ComplexSelector
+        label="Fruit"
+        value="Apple"
+        isDisabled={isDisabled}
+        onChange={onChange}>
+        {(_value, commit) => (
+          <CommitOnDisable isDisabled={isDisabled} commit={commit} />
+        )}
+      </ComplexSelector>
+    );
+    const {rerender} = render(renderSelector(false));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit'}));
+    rerender(renderSelector(true));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('commits through a helper kept from a disabled render once enabled', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const kept: {current: ((value: string) => void) | null} = {current: null};
+    const renderSelector = (isDisabled: boolean) => (
+      <ComplexSelector
+        label="Fruit"
+        value="Apple"
+        isDisabled={isDisabled}
+        onChange={onChange}>
+        {(_value, commit) => {
+          kept.current ??= commit;
+          return <span>Choices</span>;
+        }}
+      </ComplexSelector>
+    );
+    const {rerender} = render(renderSelector(true));
+    expect(kept.current).not.toBeNull();
+    rerender(renderSelector(false));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit'}));
+    act(() => kept.current?.('Banana'));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith('Banana');
+  });
+
+  it('blocks commits when disabled while open and allows them after re-enabling', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const changeAction = vi.fn();
+    const renderSelector = (isDisabled: boolean) => (
+      <ComplexSelector
+        label="Fruit"
+        value="Apple"
+        isDisabled={isDisabled}
+        onChange={onChange}
+        changeAction={changeAction}>
+        {(_value, commit) => (
+          <button type="button" onClick={() => commit('Banana')}>
+            Select Banana
+          </button>
+        )}
+      </ComplexSelector>
+    );
+    const {rerender} = render(renderSelector(false));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit'}));
+    const choice = screen.getByRole('button', {name: 'Select Banana', ...h});
+
+    rerender(renderSelector(true));
+    await user.click(choice);
+    expect(onChange).not.toHaveBeenCalled();
+    expect(changeAction).not.toHaveBeenCalled();
+
+    rerender(renderSelector(false));
+    await user.click(choice);
+    expect(onChange).toHaveBeenCalledExactlyOnceWith('Banana');
+    expect(changeAction).toHaveBeenCalledExactlyOnceWith('Banana');
+  });
+
   it('passes a close helper to composed content', async () => {
     const user = userEvent.setup();
 
@@ -225,7 +341,7 @@ describe('ComplexSelector', () => {
       </ComplexSelector>,
     );
 
-    const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+    const trigger = screen.getByRole('combobox', {name: 'Fruit blend'});
     await user.click(trigger);
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
 
@@ -329,7 +445,7 @@ describe('ComplexSelector', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const trigger = screen.getByRole('button', {name: 'View options'});
+    const trigger = screen.getByRole('combobox', {name: 'View options'});
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
     expect(handleRef.current?.isOpen()).toBe(false);
 
@@ -375,7 +491,7 @@ describe('ComplexSelector', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const trigger = screen.getByRole('button', {name: 'View options'});
+    const trigger = screen.getByRole('combobox', {name: 'View options'});
 
     act(() => {
       handleRef.current?.open();
@@ -394,7 +510,7 @@ describe('ComplexSelector', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const trigger = screen.getByRole('button', {name: 'View options'});
+    const trigger = screen.getByRole('combobox', {name: 'View options'});
 
     await user.click(trigger);
     const popover = screen
@@ -425,7 +541,7 @@ describe('ComplexSelector popup theme target', () => {
         {() => <button type="button">Done</button>}
       </ComplexSelector>,
     );
-    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit blend'}));
 
     const popup = document.querySelector(
       '.astryx-complex-selector-popup',
@@ -461,7 +577,7 @@ describe('ComplexSelector popup theme target', () => {
         {() => <button type="button">Done</button>}
       </ComplexSelector>,
     );
-    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(screen.getByRole('combobox', {name: 'Fruit blend'}));
 
     expect(
       document.querySelector('.astryx-complex-selector-popup'),
@@ -475,7 +591,7 @@ describe('ComplexSelector popup theme target', () => {
         {() => <button type="button">Done</button>}
       </ComplexSelector>,
     );
-    const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+    const trigger = screen.getByRole('combobox', {name: 'Fruit blend'});
     await user.click(trigger);
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
 
@@ -514,7 +630,7 @@ describe('ComplexSelector trigger render prop', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const opener = screen.getByRole('button', {name: 'Options'});
+    const opener = screen.getByRole('combobox', {name: 'View options'});
     expect(opener).toHaveAttribute('aria-haspopup', 'dialog');
     expect(opener).toHaveAttribute('aria-expanded', 'false');
     expect(opener).toHaveAttribute('aria-controls');
@@ -542,7 +658,7 @@ describe('ComplexSelector trigger render prop', () => {
         )}
       </ComplexSelector>,
     );
-    const opener = screen.getByRole('button', {name: 'Options'});
+    const opener = screen.getByRole('combobox', {name: 'View options'});
     await user.click(opener);
     expect(opener).toHaveAttribute('aria-expanded', 'true');
     expect(handleRef.current?.isOpen()).toBe(true);
@@ -576,7 +692,7 @@ describe('ComplexSelector trigger render prop', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const opener = screen.getByRole('button', {name: 'Options'});
+    const opener = screen.getByRole('combobox', {name: 'View options'});
     fireEvent.keyDown(opener, {key: 'ArrowDown'});
     await waitFor(() => {
       expect(opener).toHaveAttribute('aria-expanded', 'true');
@@ -584,6 +700,109 @@ describe('ComplexSelector trigger render prop', () => {
   });
 });
 
+describe('ComplexSelector trigger semantics', () => {
+  it('exposes the built-in trigger as a combobox that carries required state', () => {
+    render(
+      <ComplexSelector label="Destination" value={[]} isRequired>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('combobox', {name: /Destination/});
+    expect(trigger).toHaveAttribute('aria-required', 'true');
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+  });
+
+  it('names the built-in trigger with the field label when the caller gives no name', () => {
+    render(
+      <ComplexSelector label="Destination" value={[]}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Destination'});
+    const labelId = trigger.getAttribute('aria-labelledby');
+    expect(labelId).toBeTruthy();
+    expect(document.getElementById(labelId!)).toHaveTextContent('Destination');
+    expect(trigger).not.toHaveAttribute('aria-label');
+  });
+
+  it("lets a caller's aria-label name the built-in trigger instead of the field label (family:input-fields FR10)", () => {
+    render(
+      <ComplexSelector
+        label="Destination"
+        aria-label="Trip destination"
+        value={[]}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Trip destination'});
+    expect(trigger).toHaveAttribute('aria-label', 'Trip destination');
+    expect(trigger).not.toHaveAttribute('aria-labelledby');
+  });
+
+  it("lets a caller's aria-labelledby replace the field label on the built-in trigger (family:input-fields FR10)", () => {
+    render(
+      <>
+        <span id="trip-heading">Where to next</span>
+        <ComplexSelector
+          label="Destination"
+          aria-labelledby="trip-heading"
+          value={[]}>
+          {() => <button type="button">Apply</button>}
+        </ComplexSelector>
+      </>,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Where to next'});
+    expect(trigger).toHaveAttribute('aria-labelledby', 'trip-heading');
+  });
+
+  it('spreads the combobox role, required, and disabled state onto a caller control', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <ComplexSelector
+        label="Assignee"
+        value={[]}
+        isRequired
+        isDisabled
+        onClick={onClick}
+        renderTrigger={props => (
+          <button type="button" {...props}>
+            Assign
+          </button>
+        )}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const opener = screen.getByRole('combobox', {name: 'Assignee'});
+    expect(opener).toHaveAttribute('aria-required', 'true');
+    expect(opener).toHaveAttribute('aria-disabled', 'true');
+    expect(opener).not.toHaveAttribute('disabled');
+    await user.click(opener);
+    opener.focus();
+    await user.keyboard('{ArrowDown}');
+    expect(opener).toHaveAttribute('aria-expanded', 'false');
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+
+describe('ComplexSelector trigger semantics with a Button control', () => {
+  it('keeps the disabled and busy state on an Astryx Button control', () => {
+    render(
+      <ComplexSelector
+        label="Assignee"
+        value={[]}
+        isDisabled
+        isLoading
+        renderTrigger={props => <Button label="Assign" {...props} />}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const opener = screen.getByRole('combobox', {name: 'Assignee'});
+    expect(opener).toHaveAttribute('aria-disabled', 'true');
+    expect(opener).toHaveAttribute('aria-busy', 'true');
+  });
+});
+
 describe('ComplexSelector onOpenChange', () => {
   function renderSelector(onOpenChange: (isOpen: boolean) => void) {
     render(
@@ -598,7 +817,7 @@ describe('ComplexSelector onOpenChange', () => {
         )}
       </ComplexSelector>,
     );
-    return screen.getByRole('button', {name: 'View options'});
+    return screen.getByRole('combobox', {name: 'View options'});
   }
 
   it('reports the open and the close of a trigger toggle', async () => {
@@ -724,7 +943,7 @@ describe('ComplexSelector onOpenChange', () => {
         {() => <button type="button">Apply</button>}
       </ComplexSelector>,
     );
-    const trigger = screen.getByRole('button', {name: 'View options'});
+    const trigger = screen.getByRole('combobox', {name: 'View options'});
 
     act(() => handleRef.current?.close());
     expect(onOpenChange).not.toHaveBeenCalled();

package/src/ComplexSelector/ComplexSelector.tsx

@@ -20,6 +20,7 @@ import React, {
   useCallback,
   useId,
   useImperativeHandle,
+  useInsertionEffect,
   useOptimistic,
   useRef,
   useTransition,
@@ -248,10 +249,14 @@ export interface ComplexSelectorRenderTriggerProps extends Omit<
   | 'id'
   | 'onClick'
   | 'onKeyDown'
+  | 'role'
+  | 'aria-label'
   | 'aria-haspopup'
   | 'aria-expanded'
   | 'aria-controls'
   | 'aria-busy'
+  | 'aria-required'
+  | 'aria-disabled'
 > {
   /**
    * Attaches the control as the popup's anchor and focus-return target, and
@@ -267,6 +272,24 @@ export interface ComplexSelectorRenderTriggerProps extends Omit<
   'aria-expanded': boolean;
   'aria-controls': string;
   'aria-busy': boolean | undefined;
+  /**
+   * The control is the selector's field: a combobox whose popup is a dialog,
+   * as on the built-in trigger.
+   */
+  role: 'combobox';
+  /**
+   * The field's `label`, unless the selector was given `aria-label` or
+   * `aria-labelledby`: a combobox takes no name from its content, so the
+   * label names the control as it names the built-in trigger.
+   */
+  'aria-label': string | undefined;
+  /** `'true'` when the field is required. */
+  'aria-required': 'true' | undefined;
+  /**
+   * `'true'` when the selector is disabled. The control keeps its tab stop
+   * and the popup does not open (`spec:AST-085`).
+   */
+  'aria-disabled': 'true' | undefined;
 }
 
 export interface ComplexSelectorRenderState {
@@ -356,7 +379,7 @@ export interface ComplexSelectorProps<Value> extends Omit<
   isOptional?: boolean;
   /** Marks the field required. */
   isRequired?: boolean;
-  /** Disables the selector. */
+  /** Blocks opening and value commits, including from an already-open popup. */
   isDisabled?: boolean;
   /** Shows loading state on the trigger. */
   isLoading?: boolean;
@@ -665,8 +688,24 @@ export function ComplexSelector<Value>({
     [isDisabled, popover],
   );
 
+  // The helper reads the selector's availability when it runs, not the
+  // render it came from: content may keep a helper from an earlier render
+  // (after an await, say) across a change either way. The insertion effect
+  // runs before any layout effect of the content, so a commit from the
+  // content's own layout effect in the render that changes it sees the new
+  // availability too.
+  const isDisabledRef = useRef(isDisabled);
+  useInsertionEffect(() => {
+    isDisabledRef.current = isDisabled;
+  }, [isDisabled]);
+
   const commitValue = useCallback(
     (nextValue: Value) => {
+      // Caller-owned popup controls may remain mounted after disablement.
+      // Guard the supplied commit boundary, not just the trigger.
+      if (isDisabledRef.current) {
+        return;
+      }
       onChange?.(nextValue);
       if (changeAction) {
         startTransition(async () => {
@@ -719,12 +758,29 @@ export function ComplexSelector<Value>({
       id: triggerId,
       // This path never forwarded caller handlers before, so the newly
       // forwarded ones compose component first and cannot cancel opening.
-      onClick: composeEventHandlers(handleTriggerClick, onClickProp),
-      onKeyDown: composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
+      // A disabled control keeps its tab stop but invokes no callback
+      // (`spec:AST-085` FR2), as on the built-in trigger.
+      onClick: isDisabled
+        ? swallowDisabledPress
+        : composeEventHandlers(handleTriggerClick, onClickProp),
+      onKeyDown: isDisabled
+        ? handleTriggerKeyDown
+        : composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
+      // The caller's control is the field, so it carries the field's role
+      // and state as the built-in trigger does.
+      role: 'combobox',
+      // A combobox takes no name from its content, so the field's label
+      // names the control, as it names the built-in trigger and the popup.
+      // A name passed to the selector wins.
+      'aria-label':
+        rest['aria-label'] ??
+        (rest['aria-labelledby'] != null ? undefined : label),
       'aria-haspopup': 'dialog',
       'aria-expanded': isOpen,
       'aria-controls': contentId,
       'aria-busy': isBusy || undefined,
+      'aria-required': isEffectivelyRequired ? 'true' : undefined,
+      'aria-disabled': isDisabled ? 'true' : undefined,
     };
     return (
       <>
@@ -773,6 +829,9 @@ export function ComplexSelector<Value>({
           ref={triggerButtonRef}
           id={triggerId}
           type="button"
+          // The trigger is the field's control: a combobox whose popup is a
+          // dialog, so required and disabled state are valid on it.
+          role="combobox"
           aria-haspopup="dialog"
           aria-expanded={isOpen}
           aria-controls={contentId}
@@ -781,7 +840,13 @@ export function ComplexSelector<Value>({
             [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
             undefined
           }
-          aria-labelledby={labelId}
+          // The field's label names the trigger unless the selector was
+          // given a name: a caller's `aria-label` or `aria-labelledby`
+          // replaces it (family:input-fields FR10), as on `renderTrigger`.
+          aria-labelledby={
+            rest['aria-labelledby'] ??
+            (rest['aria-label'] != null ? undefined : labelId)
+          }
           aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}