Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
25.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file window-splitter.ts
 * @input WCAG 2.2 A/AA success criteria and the APG Window Splitter pattern's role, value, name, relationship, and keyboard requirements
 * @output WINDOW_SPLITTER_PATTERN — the reusable contract a focusable resize separator binds to when it adopts the pattern (ResizeHandle under component:Resizable AR1, `spec:AST-020/FR15`)
 * @position Pattern contract; bound by ResizeHandle and the components that render it
 */

import {
  definePattern,
  type ApgRequirement,
  type PatternContract,
  type WcagCriterion,
} from '../contract';
import type {Key, Subject} from '../harness';

const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/';
const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';

const WCAG_1_3_1: WcagCriterion = {
  standard: 'wcag',
  id: '1.3.1',
  name: 'Info and Relationships',
  level: 'A',
  url: `${UNDERSTANDING}/info-and-relationships.html`,
};
const WCAG_2_1_1: WcagCriterion = {
  standard: 'wcag',
  id: '2.1.1',
  name: 'Keyboard',
  level: 'A',
  url: `${UNDERSTANDING}/keyboard.html`,
};
const WCAG_4_1_2: WcagCriterion = {
  standard: 'wcag',
  id: '4.1.2',
  name: 'Name, Role, Value',
  level: 'A',
  url: `${UNDERSTANDING}/name-role-value.html`,
};

const apgReq = (requirement: string, anchor: string): ApgRequirement => ({
  standard: 'apg',
  pattern: 'windowsplitter',
  requirement,
  url: `${APG_URL}#${anchor}`,
});
const A = 'wai-ariaroles,states,andproperties';
const K = 'keyboardinteraction';
const APG_ROLE = apgReq(
  'The element that serves as the focusable splitter has role separator.',
  A,
);
const APG_VALUES = apgReq(
  'The separator element has the aria-valuenow property set to a decimal value representing the current position of the separator; aria-valuemin set to the position where the primary pane has its minimum size; aria-valuemax set to the position where the primary pane has its maximum size.',
  A,
);
const APG_NAME = apgReq(
  'If the primary pane has a visible label, it is referenced by aria-labelledby on the separator element. Otherwise, the separator element has a label provided by aria-label.',
  A,
);
const APG_CONTROLS = apgReq(
  'The separator element has aria-controls referring to the primary pane.',
  A,
);
const APG_ARROWS = apgReq(
  'Left Arrow: Moves a vertical splitter to the left. Right Arrow: Moves a vertical splitter to the right. Up Arrow: Moves a horizontal splitter up. Down Arrow: Moves a horizontal splitter down.',
  K,
);
const APG_ENTER = apgReq(
  'Enter: If the primary pane is not collapsed, collapses the pane. If the pane is collapsed, restores the splitter to its previous position.',
  K,
);
const APG_HOME_END = apgReq(
  'Home (Optional): Moves splitter to the position that gives the primary pane its smallest allowed size. End (Optional): Moves splitter to the position that gives the primary pane its largest allowed size.',
  K,
);

/**
 * What a binding knows about one focusable splitter (the subject). Positions
 * are the pixel sizes the separator exposes; `increaseKey` is the arrow that
 * grows `aria-valuenow` in this binding's layout (direction, reversal, and
 * reading direction decide it); `step` is that key's pixel step.
 */
export interface WindowSplitterStateFacts {
  readonly valueNow: number;
  readonly valueMin: number;
  /** The maximum the separator exposes, or null when the binding sets none (a recorded gap). */
  readonly valueMax: number | null;
  /** The axis the separator LIES along: a left/right pane handle is `vertical`. */
  readonly orientation: 'horizontal' | 'vertical';
  readonly increaseKey: 'ArrowRight' | 'ArrowLeft' | 'ArrowUp' | 'ArrowDown';
  readonly step: number;
  /** Whether the user is meant to be able to move the separator. */
  readonly operable: boolean;
  /** Whether Enter collapses and restores the primary pane. */
  readonly collapsible: boolean;
  /**
   * Whether the pane starts collapsed. The collapse-and-restore row assumes
   * an open pane, so it does not run here; the arrow row still does, since a
   * collapsed pane must still answer the keyboard.
   */
  readonly startsCollapsed?: boolean;
}

const ALWAYS = {
  condition: 'the binding designates a focusable splitter',
  test: () => true,
};

const OPPOSITE: Record<WindowSplitterStateFacts['increaseKey'], Key> = {
  ArrowRight: 'ArrowLeft',
  ArrowLeft: 'ArrowRight',
  ArrowUp: 'ArrowDown',
  ArrowDown: 'ArrowUp',
};

async function numericAttribute(
  subject: Subject,
  name: string,
): Promise<number> {
  const raw = await subject.attribute(name);
  const parsed = raw == null ? Number.NaN : Number(raw);
  if (!Number.isFinite(parsed)) {
    throw new Error(`${name} is ${raw ?? 'absent'}, not a number`);
  }
  return parsed;
}

async function valueNow(subject: Subject): Promise<number> {
  return numericAttribute(subject, 'aria-valuenow');
}

async function focusOrFail(subject: Subject, forWhat: string): Promise<void> {
  await subject.focus();
  if (!(await subject.isFocused())) {
    throw new Error(
      `the splitter did not take focus, so ${forWhat} never reaches it`,
    );
  }
}

async function expectValue(
  subject: Subject,
  expected: number,
  after: string,
): Promise<void> {
  const now = await valueNow(subject);
  if (Math.abs(now - expected) > 0.5) {
    throw new Error(`${after} left aria-valuenow at ${now}, not ${expected}`);
  }
}

function clampTo(facts: WindowSplitterStateFacts, target: number): number {
  const upper = facts.valueMax ?? Number.POSITIVE_INFINITY;
  return Math.min(upper, Math.max(facts.valueMin, target));
}

export const WINDOW_SPLITTER_PATTERN: PatternContract<WindowSplitterStateFacts> =
  definePattern<WindowSplitterStateFacts>({
    pattern: 'windowsplitter',
    url: APG_URL,
    scope:
      "A focusable splitter's role and name, its position and bounds, the pane it controls, its orientation, and the arrow, Enter, Home and End keys.",
    expectations: [
      {
        id: 'windowsplitter.separator.role-and-name',
        outcome:
          'The browser exposes the splitter as a named separator, so a user hears which pane they are resizing.',
        sources: [WCAG_4_1_2, APG_ROLE, APG_NAME],
        covers: [
          '4.1.2-name-role-value',
          '2.4.6-headings-and-labels',
          'apg-interaction',
        ],
        appliesWhen: ALWAYS,
        evidenceLayer: 'accessibility-tree',
        enforcement: 'required',
        run: async ({subject}) => {
          const {role, name} = await subject.computed();
          if (role !== 'separator' && role !== 'splitter') {
            throw new Error(
              `the browser exposes this splitter as ${role == null ? 'no role' : `"${role}"`}, not as a separator`,
            );
          }
          if (!name || name.trim() === '') {
            throw new Error(
              'the browser computes no accessible name for this splitter',
            );
          }
        },
      },
      {
        id: 'windowsplitter.separator.position-and-minimum',
        outcome:
          'The splitter states where it is and the smallest size the pane can take, so a user hears their position in the range.',
        sources: [WCAG_4_1_2, APG_VALUES],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject, facts}) => {
          const now = await valueNow(subject);
          const min = await numericAttribute(subject, 'aria-valuemin');
          if (now !== facts.valueNow || min !== facts.valueMin) {
            throw new Error(
              `the splitter exposes now/min ${now}/${min}, not ${facts.valueNow}/${facts.valueMin}`,
            );
          }
          if (now < min) {
            throw new Error('aria-valuenow lies below aria-valuemin');
          }
        },
      },
      {
        id: 'windowsplitter.separator.maximum',
        outcome:
          'The splitter states the largest size the pane can take, so a user hears where the range ends.',
        sources: [WCAG_4_1_2, APG_VALUES],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject, facts}) => {
          const raw = await subject.attribute('aria-valuemax');
          if (raw == null) {
            throw new Error('the splitter exposes no aria-valuemax');
          }
          const max = Number(raw);
          if (!Number.isFinite(max)) {
            throw new Error(`aria-valuemax is "${raw}", not a number`);
          }
          if (facts.valueMax != null && max !== facts.valueMax) {
            throw new Error(`aria-valuemax is ${max}, not ${facts.valueMax}`);
          }
          if (max < facts.valueMin) {
            throw new Error('aria-valuemax lies below aria-valuemin');
          }
          const now = await valueNow(subject);
          if (now > max) {
            throw new Error('aria-valuenow lies above aria-valuemax');
          }
        },
      },
      {
        id: 'windowsplitter.separator.orientation',
        outcome:
          'The splitter says which axis it lies along, so a user knows which arrows move it.',
        sources: [WCAG_4_1_2, APG_ARROWS],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({subject, facts}) => {
          const orientation = await subject.attribute('aria-orientation');
          // A separator's default is horizontal; the bar that divides
          // left/right panes must say vertical.
          const actual = orientation ?? 'horizontal';
          if (actual !== facts.orientation) {
            throw new Error(
              `aria-orientation is ${orientation ?? 'absent (horizontal)'}, not ${facts.orientation}`,
            );
          }
        },
      },
      {
        id: 'windowsplitter.separator.controls-pane',
        outcome:
          'The splitter names the pane it resizes, so assistive technology can relate the control to its target.',
        sources: [WCAG_1_3_1, APG_CONTROLS],
        covers: ['1.3.1-info-and-relationships', 'apg-interaction'],
        appliesWhen: ALWAYS,
        evidenceLayer: 'dom',
        enforcement: 'required',
        run: async ({harness, subject}) => {
          const controls = await subject.attribute('aria-controls');
          if (controls == null || controls.trim() === '') {
            throw new Error('the splitter carries no aria-controls');
          }
          const pane = await harness.related('pane');
          if (!(await harness.references(subject, 'aria-controls', pane))) {
            throw new Error(
              `aria-controls points at "${controls}", not at the pane the binding designates`,
            );
          }
        },
      },
      {
        id: 'windowsplitter.keys.arrows-move',
        outcome:
          'One arrow moves the splitter so the pane grows by a step and the opposite arrow moves it back.',
        sources: [WCAG_2_1_1, APG_ARROWS],
        covers: ['2.1.1-keyboard', 'apg-interaction'],
        appliesWhen: {
          condition: 'the splitter can be moved',
          test: facts => facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          await focusOrFail(subject, 'the arrow keys');
          await harness.press(facts.increaseKey);
          await expectValue(
            subject,
            clampTo(facts, facts.valueNow + facts.step),
            `${facts.increaseKey} (grow)`,
          );
          await harness.press(OPPOSITE[facts.increaseKey]);
          await expectValue(
            subject,
            facts.valueNow,
            `${OPPOSITE[facts.increaseKey]} (shrink)`,
          );
        },
      },
      {
        id: 'windowsplitter.keys.enter-collapses-and-restores',
        outcome:
          'Enter collapses the pane and announces it; Enter again restores the splitter to where it was.',
        sources: [WCAG_2_1_1, APG_ENTER],
        covers: ['2.1.1-keyboard', '4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: {
          condition:
            'the pane is collapsible, starts open, and the splitter can be moved',
          test: facts =>
            facts.collapsible && facts.operable && !facts.startsCollapsed,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          await focusOrFail(subject, 'Enter');
          await harness.press('Enter');
          const text = await subject.attribute('aria-valuetext');
          if (text == null || text.trim() === '') {
            throw new Error(
              'Enter did not collapse the pane (no aria-valuetext announces the collapsed state)',
            );
          }
          await harness.press('Enter');
          const after = await subject.attribute('aria-valuetext');
          if (after != null) {
            throw new Error(
              'a second Enter did not restore the pane (aria-valuetext still announces it collapsed)',
            );
          }
          await expectValue(subject, facts.valueNow, 'Enter (restore)');
        },
      },
      {
        id: 'windowsplitter.keys.home-end',
        outcome:
          'Home gives the pane its smallest allowed size and End its largest.',
        sources: [WCAG_2_1_1, APG_HOME_END],
        covers: ['2.1.1-keyboard', 'apg-interaction'],
        appliesWhen: {
          condition: 'the splitter can be moved',
          test: facts => facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'advisory',
        advisoryBecause:
          "Home and End are optional in the APG pattern; this becomes required once the binding's component record adopts them as current (AST-020 FR9).",
        run: async ({harness, subject, facts}) => {
          await focusOrFail(subject, 'Home and End');
          await harness.press('Home');
          await expectValue(subject, facts.valueMin, 'Home');
          await harness.press('End');
          // End should reach the maximum the separator exposes. Without a
          // configured maximum that is the reported stand-in (or, when none is
          // exposed, there is nowhere for End to go: it stays at the minimum
          // Home just reached). The row reports what End does rather than
          // skipping the state.
          const exposedMax = await subject.attribute('aria-valuemax');
          const endTarget =
            facts.valueMax ??
            (exposedMax != null && Number.isFinite(Number(exposedMax))
              ? Number(exposedMax)
              : facts.valueMin);
          await expectValue(subject, endTarget, 'End');
        },
      },
      {
        id: 'windowsplitter.separator.unavailable-keeps-position',
        outcome:
          'An unavailable splitter says so and keeps its position on every key, so a locked layout never moves under the keyboard.',
        sources: [WCAG_4_1_2, APG_ARROWS],
        covers: ['4.1.2-name-role-value', 'apg-interaction'],
        appliesWhen: {
          condition: 'the splitter cannot be moved',
          test: facts => !facts.operable,
        },
        evidenceLayer: 'real-browser',
        alsoNeeds: ['dom'],
        enforcement: 'required',
        run: async ({harness, subject, facts}) => {
          if ((await subject.attribute('aria-disabled')) !== 'true') {
            throw new Error(
              'an unavailable splitter does not carry aria-disabled="true"',
            );
          }
          await subject.focus();
          if (!(await subject.isFocused())) {
            // Out of the Tab order: nothing can reach it, so nothing moves.
            return;
          }
          for (const key of [facts.increaseKey, 'Home', 'Enter'] as const) {
            await harness.press(key);
            await expectValue(
              subject,
              facts.valueNow,
              `${key} on an unavailable splitter`,
            );
          }
        },
      },
    ],
    exemptions: {
      '1.1.1-non-text-content': {
        owner: 'the binding component',
        verifiedBy:
          "the component's decorative-icon tests and the repository axe audit, `pnpm a11y:audit`",
        reason:
          "This contract owns the splitter's semantics and keys. The grip pill and divider line the binding paints are decorative composition.",
      },
      '1.3.1-info-and-relationships': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "the component's pane structure tests and page-level relationship review",
        reason:
          "This contract proves the splitter names the pane it controls. The panes themselves and their landmarks are the binding's and the page's.",
        coversRemainderOnly: true,
      },
      '1.3.2-meaningful-sequence': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "the component's DOM-order tests and page-level reading-order review",
        reason:
          "Where the splitter sits between its panes, and the panes' reading order, is composition.",
      },
      '1.3.5-identify-input-purpose': {
        owner: 'the binding component',
        verifiedBy:
          "this contract's role row (the separator carries role, name and value properties and no input purpose) and the component's render tests",
        reason:
          "A splitter collects a layout position, not information about the user that autofill could supply; the binding's separator is the only control it renders.",
      },
      '1.4.1-use-of-color': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's hover, focus and disabled state tests plus rendered review",
        reason:
          'Hover, drag and disabled cues on the handle are paint results owned by the binding and theme; this contract proves the programmatic position and state.',
      },
      '1.4.3-contrast-minimum': {
        owner: 'the binding component and theme',
        verifiedBy: 'the repository axe audit plus rendered contrast review',
        reason:
          'A splitter paints no text; the collapsed announcement is programmatic.',
      },
      '1.4.11-non-text-contrast': {
        owner: 'the binding component and theme',
        verifiedBy:
          'the repository axe audit plus rendered review of the divider, grip and focus indicator',
        reason:
          'Divider, grip and focus indicator contrast are paint outcomes owned by the binding and theme.',
      },
      '2.1.1-keyboard': {
        owner: 'the composing page',
        verifiedBy: 'page-level keyboard review',
        reason:
          "This contract encodes the splitter's arrow, Enter, Home and End keys. Reaching the splitter, F6 pane cycling, and other page keyboard paths remain with the composition.",
        coversRemainderOnly: true,
      },
      '2.1.2-no-keyboard-trap': {
        owner: 'the binding component and composing page',
        verifiedBy: "the component's Tab tests and page-level keyboard review",
        reason:
          'A splitter adds no focus trap; Tab entry and exit are generic focus behavior.',
      },
      '2.4.2-page-titled': {
        owner: 'the page',
        verifiedBy: 'page-level review',
        reason: 'A splitter rendered in isolation owns no document title.',
      },
      '2.4.3-focus-order': {
        owner: 'the composing page',
        verifiedBy: 'page-level focus-order review',
        reason:
          "The splitter's place among surrounding controls depends on composition.",
      },
      '2.4.4-link-purpose': {
        owner: 'the binding component',
        verifiedBy:
          "this contract's role row and the component's render tests (the handle renders a separator and a grab zone, no anchor)",
        reason:
          'A splitter renders no link; the composing page owns any link placed around it.',
      },
      '2.4.6-headings-and-labels': {
        owner: 'the binding component and caller content',
        verifiedBy: "the component's name tests and caller content review",
        reason:
          'This contract proves the splitter has a name; whether that label is descriptive is caller content.',
        coversRemainderOnly: true,
      },
      '2.4.7-focus-visible': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's focus-outline tests and rendered focus review",
        reason:
          "The focused splitter's indicator is a paint result owned by the binding and theme.",
      },
      '2.4.11-focus-not-obscured': {
        owner: 'the composing page',
        verifiedBy: 'page-level layout review',
        reason:
          'Whether another surface covers the focused splitter depends on composition.',
      },
      '2.5.2-pointer-cancellation': {
        owner: 'the binding component',
        verifiedBy:
          "the component's pointer suites: capture on the grab zone, moves from a pointer that does not own the drag are ignored, a drag that ends normally reports no cancel, pointercancel and lost capture end the gesture, and double-click collapse/restore",
        reason:
          "A splitter moves through the drag itself (the down event starts a reversible gesture; releasing ends it), so the pointer model is the binding's and outside this keyboard contract. The handle has no Escape cancel; the browser's pointercancel and lost capture are what end an interrupted drag.",
      },
      '2.5.3-label-in-name': {
        owner: 'the binding component',
        verifiedBy: "the component's accessible-name tests",
        reason:
          'A splitter has no visible text label; its name is authored by the binding.',
      },
      '2.5.8-target-size': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the repository axe audit's target-size rule over the grab zone",
        reason:
          "The grab zone's hit area is geometry owned by the binding and theme.",
      },
      '3.1.1-language-of-page': {
        owner: 'the page',
        verifiedBy: 'page-level review',
        reason: 'A splitter owns no document language.',
      },
      '3.2.2-on-input': {
        owner: 'the caller and composing page',
        verifiedBy:
          'integration review of what a caller does with onSizeChange and onCollapseChange',
        reason:
          "Resizing or collapsing a pane is the splitter's own purpose; any further context change a caller makes is the caller's action.",
      },
      '3.2.4-consistent-identification': {
        owner: 'the composing page',
        verifiedBy:
          'this shared contract across bindings plus content review of repeated splitter labels',
        reason:
          'Consistency is a property of the full set of repeated functions, not one isolated splitter.',
      },
      '3.3.1-error-identification': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "this contract's value rows (aria-valuenow stays within aria-valuemin/aria-valuemax, so no entry can be in error) and the composing page's form checks",
        reason:
          'A splitter has no free entry to validate: its value is clamped to its bounds as it changes; a form around it reports its own errors.',
      },
      '3.3.2-labels-or-instructions': {
        owner: 'the binding component and composing page',
        verifiedBy:
          "this contract's name row (every separator is labelled) and the composing page's review of any instructions around it",
        reason:
          "The separator is named by its label; a splitter needs no entry instructions, and any guidance about the layout is the composing page's.",
      },
      '4.1.2-name-role-value': {
        owner: 'the binding component',
        verifiedBy: "the component's collapsed-state and disabled tests",
        reason:
          "This contract encodes the splitter's role, name, position, bounds, orientation, collapsed text and disabled state. The panes' own roles are the binding's and the page's.",
        coversRemainderOnly: true,
      },
      '4.1.3-status-messages': {
        owner:
          'the caller and the assistive-technology verification record, spec:AST-009',
        verifiedBy:
          'the status-message pattern and real-AT evidence under AST-009 when a change claims spoken or braille output',
        reason:
          'A size change is not a status-message contract; the collapsed state is exposed through aria-valuetext, not a live region.',
      },
      'apg-interaction': {
        owner: "the binding component's record",
        verifiedBy:
          'component:Resizable AR1 and its decision entry, which adopt the pattern as one composite control and name the gaps',
        reason:
          "This contract encodes the splitter role, position, bounds, name, relationship and keys. F6 pane cycling is not adopted; the pointer drag model is the binding's.",
        coversRemainderOnly: true,
      },
      'forced-colors': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's forced-colors tests plus rendered Windows High Contrast review",
        reason:
          'Forced-colors output is a paint result owned by the binding and theme.',
      },
      'reduced-motion': {
        owner: 'the binding component and theme',
        verifiedBy:
          "the component's reduced-motion source tests and rendered motion review",
        reason:
          'Pane and handle motion is binding-specific paint over time and is not part of splitter semantics.',
      },
      'at-facing-strings': {
        owner: 'the binding component and caller content',
        verifiedBy:
          'the repository i18n catalog check and source review of authored labels',
        reason:
          "The splitter contract introduces no string; the label and the collapsed text come from the binding's catalog.",
      },
    },
  });