An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] InfoTip: the docs page gets worked examples, and hover, focus, pin, and Escape are proven in a browser (#9940)
Cindy Zhangd9a3da5fe635
diff --git a/.changeset/info-tip-audit-examples.md b/.changeset/info-tip-audit-examples.mdnew file mode 100644index 0000000000..6094b00c42--- /dev/null+++ b/.changeset/info-tip-audit-examples.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+---++[docs] InfoTip: the component page, `astryx component InfoTip --showcase`, and `astryx component InfoTip --blocks` now have worked examples — a showcase metric label, a row of metric definitions, and read-only settings with permission notes. InfoTip's docs list its anatomy (trigger button, info icon, help surface) and say it follows the toggletip pattern: the button reports `aria-expanded="true"` while the help is pinned, and a screen reader hears the help once when it pins.++@cixzhangdiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex c700f1bcdf..fdd806593e 100644--- a/apps/sandbox/scripts/next-export-routes.json+++ b/apps/sandbox/scripts/next-export-routes.json@@ -360,6 +360,9 @@"/templates/IconShowcase/","/templates/IconSizes/","/templates/IconStatusIcons/",+ "/templates/InfoTipMetricDefinitions/",+ "/templates/InfoTipPermissionNotes/",+ "/templates/InfoTipShowcase/","/templates/InputGroupBasic/","/templates/InputGroupShowcase/","/templates/InternationalizationProvider01ShippedLocale/",diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex f363844644..f14fd728b6 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -109,6 +109,16 @@"component": "core/IconButton","reason": "IconButton is a thin wrapper that renders Button with `isIconOnly`, adding no layout, no positioning, and no directional affordance of its own, so it inherits `core/Button`'s verification above exactly. Its single icon is centred in a square control, which has no reading direction to mirror."},+ {+ "component": "core/InfoTip",+ "reason": "InfoTip renders one round icon button holding the registry's `info` glyph, which is symmetric and has no reading direction to mirror; its padding and radius are uniform and it has no control order, scrolling, dragging, or horizontal keyboard behavior. Its help opens in Tooltip's layer on the block axis (above), owned by Tooltip. Under a coarse pointer its invisible hit area grows by insets the shared hit area measures from page rects on each physical side, so the growth follows the mirrored layout and nothing in InfoTip is fixed to left or right.",+ "evidence": {+ "apps/storybook/stories/InfoTip.stories.tsx": "sha256:d7c86b16106ac1fbc37e4cfccfbd108969bbfb7da9cbe0ad064943f11af8cb1e",+ "packages/core/src/InfoTip/InfoTip.tsx": "sha256:8d5ef827f1b5421d42ad420b4aeb1bac9afa617ff640fcdb5b6b37b508e6bd67",+ "packages/core/src/InfoTip/index.ts": "sha256:0470065a1a899926b2b627db5eaad0d43a41710b0f03ab977b0b8b53ed881ba4",+ "packages/core/src/utils/hitArea.ts": "sha256:4fccc868c405b1d9f514f0f1089f2ecb2d98de411349feb1b68d58724fc74928"+ }+ },{"component": "core/SelectableCard","reason": "SelectableCard renders content in normal flow inside a symmetric Card. Its hover overlay and selected ring cover all four edges equally, its source uses no physical left/right positioning or directional glyphs, and its checkbox interaction uses only pointer, Space, Enter, and Tab rather than inline-direction keys. Every current story therefore has no component-owned visual or behavioral RTL difference for the audit to measure.",diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.jsonindex d13f8d63dd..70936da26b 100644--- a/internal/shadcn-registry/routes.lock.json+++ b/internal/shadcn-registry/routes.lock.json@@ -2291,6 +2291,16 @@"path": "examples/icon/status-indicators","aliases": []},+ {+ "name": "example-info-tip-metric-definitions",+ "path": "examples/info-tip/metric-definitions",+ "aliases": []+ },+ {+ "name": "example-info-tip-permission-notes",+ "path": "examples/info-tip/permission-notes",+ "aliases": []+ },{"name": "example-input-group-basic","path": "examples/input-group/basic",@@ -4601,6 +4611,11 @@"path": "showcases/icon/default","aliases": []},+ {+ "name": "showcase-info-tip-default",+ "path": "showcases/info-tip/default",+ "aliases": []+ },{"name": "showcase-input-group-default","path": "showcases/input-group/default",diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.doc.mjs b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.doc.mjsnew file mode 100644index 0000000000..2c01de5c44--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'InfoTip',+ name: 'InfoTip — Metric Definitions',+ displayName: 'Info Tip — Metric Definitions',+ description:+ 'A row of metrics, each label followed by an InfoTip that defines how the value is counted.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['InfoTip', 'HStack', 'VStack', 'Text'],+};diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.tsx b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.tsxnew file mode 100644index 0000000000..8840bb13fb--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipMetricDefinitions.tsx@@ -0,0 +1,46 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {InfoTip} from '@astryxdesign/core/InfoTip';+import {HStack, VStack} from '@astryxdesign/core/Stack';+import {Text} from '@astryxdesign/core/Text';++const metrics = [+ {+ name: 'Active users',+ value: '48,210',+ definition: 'People who opened the app at least once in the last 28 days.',+ },+ {+ name: 'Retention',+ value: '62%',+ definition: 'Share of last month’s active users who returned this month.',+ },+ {+ name: 'Median session',+ value: '6m 40s',+ definition: 'Half of all sessions this week were shorter than this.',+ },+];++export default function InfoTipMetricDefinitions() {+ return (+ <HStack gap={6} wrap="wrap">+ {metrics.map(metric => (+ <VStack key={metric.name} gap={1}>+ <HStack gap={1} align="center">+ <Text type="label" color="secondary">+ {metric.name}+ </Text>+ <InfoTip+ content={metric.definition}+ label={`About ${metric.name.toLowerCase()}`}+ />+ </HStack>+ <Text type="large">{metric.value}</Text>+ </VStack>+ ))}+ </HStack>+ );+}diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.doc.mjs b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.doc.mjsnew file mode 100644index 0000000000..524d3e42f8--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'InfoTip',+ name: 'InfoTip — Permission Notes',+ displayName: 'Info Tip — Permission Notes',+ description:+ 'Read-only settings whose labels carry an InfoTip that says who can change each value.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['InfoTip', 'HStack', 'VStack', 'Text'],+};diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.tsx b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.tsxnew file mode 100644index 0000000000..030eb59867--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipPermissionNotes.tsx@@ -0,0 +1,41 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {InfoTip} from '@astryxdesign/core/InfoTip';+import {HStack, VStack} from '@astryxdesign/core/Stack';+import {Text} from '@astryxdesign/core/Text';++const fields = [+ {+ name: 'Owner',+ value: 'Design Systems',+ note: 'Only admins can change the owner.',+ },+ {+ name: 'Visibility',+ value: 'Everyone in the workspace',+ note: 'Editors can change this field; viewers cannot.',+ },+];++export default function InfoTipPermissionNotes() {+ return (+ <VStack gap={4}>+ {fields.map(field => (+ <VStack key={field.name} gap={1}>+ <HStack gap={1} align="center">+ <Text type="label">{field.name}</Text>+ <InfoTip+ content={field.note}+ label={`Who can change ${field.name.toLowerCase()}`}+ />+ </HStack>+ <Text type="body" color="secondary">+ {field.value}+ </Text>+ </VStack>+ ))}+ </VStack>+ );+}diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.doc.mjsnew file mode 100644index 0000000000..a0e5970e03--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.doc.mjs@@ -0,0 +1,13 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'InfoTip',+ name: 'InfoTip',+ displayName: 'Info Tip',+ isReady: true,+ aspectRatio: 1,+ isShowcase: true,+ componentsUsed: ['InfoTip', 'HStack', 'VStack', 'Text'],+};diff --git a/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.tsx b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.tsxnew file mode 100644index 0000000000..6f251da599--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/InfoTip/InfoTipShowcase.tsx@@ -0,0 +1,24 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {InfoTip} from '@astryxdesign/core/InfoTip';+import {HStack, VStack} from '@astryxdesign/core/Stack';+import {Text} from '@astryxdesign/core/Text';++export default function InfoTipShowcase() {+ return (+ <VStack gap={1}>+ <HStack gap={1} align="center">+ <Text type="label" color="secondary">+ Rolling average+ </Text>+ <InfoTip+ content="30-day rolling average, recomputed nightly."+ label="About this metric"+ />+ </HStack>+ <Text type="display-3">1,284</Text>+ </VStack>+ );+}diff --git a/packages/core/src/InfoTip/InfoTip.doc.mjs b/packages/core/src/InfoTip/InfoTip.doc.mjsindex be2dd58c24..4bceb9f887 100644--- a/packages/core/src/InfoTip/InfoTip.doc.mjs+++ b/packages/core/src/InfoTip/InfoTip.doc.mjs@@ -1,5 +1,27 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Trigger button',+ required: true,+ description:+ 'Small round native button, named by `label`, that previews and pins the help.',+ },+ {+ name: 'Info icon',+ required: true,+ description:+ "The icon registry's `info` artwork at `size`; a theme may replace it.",+ },+ {+ name: 'Help surface',+ required: true,+ description:+ 'Tooltip surface that shows `content` while the help is shown.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -50,8 +72,9 @@ export const docs = {},],usage: {+ anatomy,description:- 'An info icon that reveals help: a small "i" button. Hover and keyboard focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. Use it next to labels, values, and metrics for permission notes, metric definitions, and field help. Its value over hand-composing Icon inside Tooltip is the pre-wired accessible trigger: a real button with an aria-label, Tab-reachable, tooltip on hover AND focus AND tap, and Escape dismissal.',+ 'An info icon that reveals help: a small "i" button. Hover and keyboard focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. Use it next to labels, values, and metrics for permission notes, metric definitions, and field help. Its value over hand-composing Icon inside Tooltip is the pre-wired accessible trigger: a real button with an aria-label, Tab-reachable, tooltip on hover AND focus AND tap, and Escape dismissal. It follows the toggletip pattern: the button reports `aria-expanded="true"` while the help is pinned, and a screen reader hears the help once when it pins.',bestPractices: [{guidance: true,@@ -115,6 +138,7 @@ export const docsZh = {},],usage: {+ anatomy,description:'An info icon that reveals help: a small "i" button. Hover and keyboard focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. Use it next to labels, values, and metrics for permission notes, metric definitions, and field help.',bestPractices: [@@ -153,7 +177,7 @@ export const docsDense = {'Inline info-icon help affordance: accessible "i" button trigger pre-wired into a Tooltip.',usage: {description:- 'A small "i" button: hover and keyboard focus preview the help; a click, tap, Enter, or Space pins it open. Use next to labels, values, and metrics for permission notes, metric definitions, and field help. Pre-wired accessible trigger: real button, aria-label, Tab-reachable, tooltip on hover AND focus AND tap, Escape dismissal.',+ 'A small "i" button: hover and keyboard focus preview the help; a click, tap, Enter, or Space pins it open. Use next to labels, values, and metrics for permission notes, metric definitions, and field help. Pre-wired accessible trigger: real button, aria-label, Tab-reachable, tooltip on hover AND focus AND tap, Escape dismissal. Toggletip pattern: aria-expanded="true" while pinned; the help is announced once when it pins.',bestPractices: [{guidance: true,diff --git a/packages/core/src/InfoTip/InfoTip.test.tsx b/packages/core/src/InfoTip/InfoTip.test.tsxindex 1acd04767f..5f61601a51 100644--- a/packages/core/src/InfoTip/InfoTip.test.tsx+++ b/packages/core/src/InfoTip/InfoTip.test.tsx@@ -16,6 +16,7 @@ import * as stylex from '@stylexjs/stylex';import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';import userEvent from '@testing-library/user-event';+import {Icon} from '../Icon/Icon';import {InternationalizationProvider} from '../i18n';import type * as HitAreaModule from '../utils/hitArea';import type {HitInsets} from '../utils/hitArea';@@ -226,6 +227,36 @@ describe('InfoTip', () => {});});+ it('shows the registry info icon at each size, sm by default (FR1)', () => {+ const cases = [+ [undefined, 'sm'],+ ['xsm', 'xsm'],+ ['sm', 'sm'],+ ['md', 'md'],+ ['lg', 'lg'],+ ] as const;+ for (const [size, expected] of cases) {+ const {unmount} = render(+ <>+ <InfoTip content="Helpful context" size={size} />+ <span data-testid="reference">+ <Icon icon="info" size={expected} />+ </span>+ </>,+ );+ const icon = screen+ .getByRole('button', {name: 'More information'})+ .querySelector('.astryx-icon');+ const reference = screen+ .getByTestId('reference')+ .querySelector('.astryx-icon');+ expect(icon).toHaveAttribute('data-size', expected);+ expect(reference?.innerHTML).not.toBe('');+ expect(icon?.innerHTML).toBe(reference?.innerHTML);+ unmount();+ }+ });+it('renders ReactNode tooltip content', () => {render(<InfoTip content={<span data-testid="rich-content">Rich</span>} />);expect(screen.getByTestId('rich-content')).toBeInTheDocument();diff --git a/packages/core/src/InfoTip/InfoTip.tsx b/packages/core/src/InfoTip/InfoTip.tsxindex c352280339..34874bc8ca 100644--- a/packages/core/src/InfoTip/InfoTip.tsx+++ b/packages/core/src/InfoTip/InfoTip.tsx@@ -15,6 +15,7 @@* - /docs/specs/components/InfoTip/InfoTip.spec.md (contract)* - /packages/core/src/InfoTip/InfoTip.test.tsx (tests for new/changed behavior)* - /packages/core/src/InfoTip/index.ts (exports if types change)+ * - /packages/cli/assets/templates/blocks/components/InfoTip/ (showcase and example blocks)*/import {diff --git a/packages/core/src/InfoTip/__tests__/InfoTipAudit.a11y.chromium.spec.ts b/packages/core/src/InfoTip/__tests__/InfoTipAudit.a11y.chromium.spec.tsnew file mode 100644index 0000000000..a7b28cd3a9--- /dev/null+++ b/packages/core/src/InfoTip/__tests__/InfoTipAudit.a11y.chromium.spec.ts@@ -0,0 +1,637 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y audit InfoTip++/**+ * @file InfoTipAudit.a11y.chromium.spec.ts+ * @input Exact-head Core/InfoTip stories across sizes, states, themes, and modes+ * @output Screenshots and fail-closed sensor receipts for the InfoTip whole-component audit+ * @position Component-owned Night Watch browser evidence; CI runs it only for an InfoTip audit pull request+ */++import {createHash} from 'node:crypto';+import {execFileSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const OUTPUT = path.resolve('info-tip-audit-evidence');+const VIEWPORT = {width: 480, height: 320};+// The info icon's size per `size` at the neutral theme (component:InfoTip+// Public concepts).+const ICON_PX: Record<string, number> = {xsm: 12, sm: 16, md: 20, lg: 24};+// WCAG 2.5.8 minimum target, and the spacing-exception circle diameter.+const MIN_TARGET = 24;++type Mode = 'light' | 'dark';+type Theme = 'neutral' | 'butter';+type Story = 'default' | 'next-to-a-label' | 'sizes';+type Interaction =+ 'none' | 'hover' | 'focus' | 'click-pin' | 'key-pin' | 'escape';++type AuditCase = {+ key: string;+ story: Story;+ mode: Mode;+ theme: Theme;+ interaction: Interaction;+};++type AuditReceipt = {+ passed: boolean;+ expected: Record<string, unknown>;+ failures: string[];+};++// What each story renders.+const STORY: Record<Story, {label: string; content: string; sizes: string[]}> =+ {+ default: {+ label: 'More information',+ content: 'Editors can change this field; viewers cannot.',+ sizes: ['sm'],+ },+ 'next-to-a-label': {+ label: 'About this metric',+ content: '30-day rolling average, recomputed nightly.',+ sizes: ['sm'],+ },+ sizes: {+ label: 'More information',+ content: '',+ sizes: ['xsm', 'sm', 'md', 'lg'],+ },+ };++const cases: AuditCase[] = [];+function add(+ story: Story,+ options: {theme?: Theme; interaction?: Interaction; modes?: Mode[]} = {},+) {+ const theme = options.theme ?? 'neutral';+ const interaction = options.interaction ?? 'none';+ for (const mode of options.modes ?? ['light', 'dark']) {+ const parts: string[] = [story, theme];+ if (interaction !== 'none') {+ parts.push(interaction);+ }+ cases.push({+ key: `${parts.join('-')}-${mode}`,+ story,+ mode,+ theme,+ interaction,+ });+ }+}++add('default');+add('default', {theme: 'butter'});+add('sizes');+add('sizes', {theme: 'butter', modes: ['light']});+add('default', {interaction: 'hover'});+add('next-to-a-label', {interaction: 'focus'});+add('default', {interaction: 'click-pin'});+add('default', {theme: 'butter', interaction: 'click-pin', modes: ['light']});+add('next-to-a-label', {interaction: 'key-pin', modes: ['light']});+add('next-to-a-label', {interaction: 'escape', modes: ['light']});++test.describe.configure({retries: 0});+let server: StaticServer;+let checkoutSha: string;+let storybookSha: string;++function storyUrl(item: AuditCase) {+ return `${server.origin}/iframe.html?id=core-infotip--${item.story}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme}`;+}++async function settle(page: Page) {+ await holdMotionStill(page);+ await page.evaluate(async () => document.fonts.ready);+ await page.evaluate(+ async () =>+ new Promise<void>(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),+ ),+ );+ await page.waitForTimeout(40);+}++async function observe(page: Page) {+ return page.evaluate(() => {+ const round = (value: number) => Math.round(value * 10) / 10;+ function box(element: Element) {+ const rect = element.getBoundingClientRect();+ return {+ left: round(rect.left),+ top: round(rect.top),+ width: round(rect.width),+ height: round(rect.height),+ };+ }+ // Resolves any CSS color to sRGB channels and alpha through a canvas.+ const canvas = document.createElement('canvas');+ canvas.width = 1;+ canvas.height = 1;+ const context = canvas.getContext('2d', {willReadFrequently: true});+ function rgba(color: string) {+ if (context == null) {+ return null;+ }+ context.clearRect(0, 0, 1, 1);+ context.fillStyle = '#000';+ context.fillStyle = color;+ context.fillRect(0, 0, 1, 1);+ const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;+ return {r, g, b, a: a / 255};+ }+ function luminance(c: {r: number; g: number; b: number}) {+ const channel = (v: number) => {+ const s = v / 255;+ return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;+ };+ return (+ 0.2126 * channel(c.r) + 0.7152 * channel(c.g) + 0.0722 * channel(c.b)+ );+ }+ // The first painted background behind an element, else the canvas white.+ function backdrop(element: Element) {+ let node: Element | null = element;+ while (node) {+ const color = rgba(getComputedStyle(node).backgroundColor);+ if (color && color.a > 0.99) {+ return {+ color,+ source:+ node.tagName.toLowerCase() ++ (node.id ? `#${node.id}` : '') ++ (node.className && typeof node.className === 'string'+ ? `.${node.className.split(/\s+/).filter(Boolean).slice(0, 2).join('.')}`+ : ''),+ };+ }+ node = node.parentElement;+ }+ return {color: {r: 255, g: 255, b: 255, a: 1}, source: 'canvas'};+ }+ function contrast(foreground: string, element: Element) {+ const fg = rgba(foreground);+ const bg = backdrop(element);+ if (fg == null) {+ return null;+ }+ // Composite an alpha foreground over the backdrop first.+ const mixed = {+ r: fg.r * fg.a + bg.color.r * (1 - fg.a),+ g: fg.g * fg.a + bg.color.g * (1 - fg.a),+ b: fg.b * fg.a + bg.color.b * (1 - fg.a),+ };+ const l1 = luminance(mixed);+ const l2 = luminance(bg.color);+ return {+ foreground: fg,+ backdrop: bg.color,+ backdropSource: bg.source,+ ratio:+ Math.round(+ ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)) * 100,+ ) / 100,+ };+ }+ const buttons = Array.from(+ document.querySelectorAll<HTMLButtonElement>('button[aria-expanded]'),+ );+ const tooltip = Array.from(+ document.querySelectorAll<HTMLElement>('[role="tooltip"]'),+ ).find(element => element.checkVisibility());+ return {+ theme: document+ .querySelector('[data-astryx-theme]')+ ?.getAttribute('data-astryx-theme'),+ mode: document.documentElement.getAttribute('data-theme'),+ viewport: {width: innerWidth, height: innerHeight},+ dpr: devicePixelRatio,+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,+ finePointer: matchMedia('(pointer: fine)').matches,+ canHover: matchMedia('(hover: hover)').matches,+ fonts: document.fonts.status,+ storybookError:+ document.querySelector('.sb-show-errordisplay') != null ||+ document.body.classList.contains('sb-show-errordisplay'),+ buttons: buttons.map(button => {+ const style = getComputedStyle(button);+ const icon = button.querySelector('.astryx-icon');+ const iconStyle = icon ? getComputedStyle(icon) : null;+ const describedBy = button.getAttribute('aria-describedby') ?? '';+ const description = describedBy+ .split(/\s+/)+ .filter(Boolean)+ .map(id => document.getElementById(id)?.textContent?.trim() ?? '')+ .join(' ');+ const after = getComputedStyle(button, '::after');+ return {+ tagName: button.tagName,+ type: button.getAttribute('type'),+ ariaLabel: button.getAttribute('aria-label'),+ ariaExpanded: button.getAttribute('aria-expanded'),+ ariaControls: button.getAttribute('aria-controls'),+ describedBy,+ description,+ tabIndex: button.tabIndex,+ focused: document.activeElement === button,+ focusVisible: button.matches(':focus-visible'),+ hovered: button.matches(':hover'),+ outlineStyle: style.outlineStyle,+ outlineWidth: style.outlineWidth,+ outlineColor: style.outlineColor,+ outlineContrast: contrast(style.outlineColor, button),+ borderRadius: style.borderTopLeftRadius,+ padding: `${style.paddingBlockStart} ${style.paddingInlineEnd} ${style.paddingBlockEnd} ${style.paddingInlineStart}`,+ backgroundColor: style.backgroundColor,+ cursor: style.cursor,+ hitAreaInsets: [after.top, after.right, after.bottom, after.left],+ box: box(button),+ icon: icon+ ? {+ dataSize: icon.getAttribute('data-size'),+ ariaHidden: icon.getAttribute('aria-hidden'),+ color: iconStyle?.color ?? null,+ contrast: iconStyle ? contrast(iconStyle.color, button) : null,+ box: box(icon),+ }+ : null,+ };+ }),+ tooltip: tooltip+ ? {+ id: tooltip.id,+ text: (tooltip.textContent ?? '').trim(),+ box: box(tooltip),+ }+ : null,+ };+ });+}++type Observation = Awaited<ReturnType<typeof observe>>;+type ObservedButton = Observation['buttons'][number];++/**+ * WCAG 2.5.8 spacing exception: an undersized target passes when a 24 px+ * circle on its center clears every other target and every other undersized+ * target's circle.+ */+function spacingClears(target: ObservedButton, others: ObservedButton[]) {+ const radius = MIN_TARGET / 2;+ const cx = target.box.left + target.box.width / 2;+ const cy = target.box.top + target.box.height / 2;+ return others.every(other => {+ const nearestX = Math.max(+ other.box.left,+ Math.min(cx, other.box.left + other.box.width),+ );+ const nearestY = Math.max(+ other.box.top,+ Math.min(cy, other.box.top + other.box.height),+ );+ if (Math.hypot(cx - nearestX, cy - nearestY) < radius) {+ return false;+ }+ const otherUndersized =+ other.box.width < MIN_TARGET || other.box.height < MIN_TARGET;+ if (!otherUndersized) {+ return true;+ }+ const ox = other.box.left + other.box.width / 2;+ const oy = other.box.top + other.box.height / 2;+ return Math.hypot(cx - ox, cy - oy) >= MIN_TARGET;+ });+}++test.beforeAll(async () => {+ fs.mkdirSync(OUTPUT, {recursive: true});+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {+ encoding: 'utf8',+ }).trim();+ const expected = process.env.ASTRYX_HEAD_SHA;+ if (expected && expected !== checkoutSha) {+ throw new Error(+ `checkout ${checkoutSha} does not match expected head ${expected}`,+ );+ }+ server = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);+ if (!response.ok) {+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);+ }+ storybookSha = (await response.text()).trim();+ if (storybookSha !== checkoutSha) {+ throw new Error(+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,+ );+ }+});++test.afterAll(async () => {+ await server?.close();+});++for (const item of cases) {+ test(item.key, async ({browser}) => {+ const context = await browser.newContext({+ viewport: VIEWPORT,+ deviceScaleFactor: 2,+ colorScheme: item.mode,+ reducedMotion: 'reduce',+ });+ const page = await context.newPage();+ const pageErrors: string[] = [];+ page.on('pageerror', error => pageErrors.push(String(error)));+ await page.goto(storyUrl(item), {waitUntil: 'load'});+ const target = page+ .locator('#storybook-root button[aria-expanded]')+ .first();+ await target.waitFor();+ await settle(page);+ const rest = await observe(page);+ const tooltip = page.locator('[role="tooltip"]').first();++ if (item.interaction === 'hover') {+ await target.hover();+ await tooltip.waitFor({state: 'visible'});+ }+ if (item.interaction === 'click-pin') {+ await target.click();+ await tooltip.waitFor({state: 'visible'});+ }+ if (+ item.interaction === 'focus' ||+ item.interaction === 'key-pin' ||+ item.interaction === 'escape'+ ) {+ await page.keyboard.press('Tab');+ await tooltip.waitFor({state: 'visible'});+ }+ if (item.interaction === 'key-pin' || item.interaction === 'escape') {+ await page.keyboard.press('Enter');+ await expect(target).toHaveAttribute('aria-expanded', 'true');+ }+ if (item.interaction === 'escape') {+ await page.keyboard.press('Escape');+ await tooltip.waitFor({state: 'hidden'});+ }+ await settle(page);++ const first = await observe(page);+ await page.waitForTimeout(100);+ await settle(page);+ const observed = await observe(page);+ const geometryStable =+ JSON.stringify(first.buttons.map(button => button.box)) ===+ JSON.stringify(observed.buttons.map(button => button.box));++ const failures: string[] = [];+ const check = (condition: boolean, message: string) => {+ if (!condition) {+ failures.push(message);+ }+ };+ const near = (actual: number, expected: number, tolerance = 0.6) =>+ Math.abs(actual - expected) <= tolerance;+ const spec = STORY[item.story];++ check(storybookSha === checkoutSha, 'storybook build mismatch');+ check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);+ check(!observed.storybookError, 'storybook error display');+ check(observed.theme === item.theme, `theme ${observed.theme}`);+ check(observed.mode === item.mode, `mode ${observed.mode}`);+ check(+ observed.viewport.width === VIEWPORT.width &&+ observed.viewport.height === VIEWPORT.height,+ 'viewport mismatch',+ );+ check(observed.dpr === 2, `dpr ${observed.dpr}`);+ check(observed.reducedMotion, 'reduced motion not applied');+ check(observed.finePointer, 'primary pointer is not fine');+ check(observed.canHover, 'primary pointer cannot hover');+ check(observed.fonts === 'loaded', `fonts ${observed.fonts}`);+ check(geometryStable, 'geometry changed between samples');+ check(+ observed.buttons.length === spec.sizes.length,+ `${observed.buttons.length} info buttons, expected ${spec.sizes.length}`,+ );++ observed.buttons.forEach((button, index) => {+ const size = spec.sizes[index];+ const where = `button ${index} (${size})`;+ check(button.tagName === 'BUTTON', `${where} renders ${button.tagName}`);+ check(button.type === 'button', `${where} type ${button.type}`);+ check(button.tabIndex === 0, `${where} tabIndex ${button.tabIndex}`);+ check(+ button.ariaLabel === spec.label,+ `${where} aria-label ${button.ariaLabel}`,+ );+ check(button.describedBy !== '', `${where} has no aria-describedby`);+ check(+ button.hitAreaInsets.every(inset => Math.abs(parseFloat(inset)) === 0),+ `${where} grows under a fine pointer: ${button.hitAreaInsets.join(' ')}`,+ );+ const icon = button.icon;+ if (icon == null) {+ check(false, `${where} has no icon`);+ return;+ }+ check(icon.dataSize === size, `${where} icon size ${icon.dataSize}`);+ check(icon.ariaHidden === 'true', `${where} icon is not decorative`);+ check(+ near(+ icon.box.left + icon.box.width / 2,+ button.box.left + button.box.width / 2,+ ) &&+ near(+ icon.box.top + icon.box.height / 2,+ button.box.top + button.box.height / 2,+ ),+ `${where} icon is not centered`,+ );+ check(+ near(button.box.width, button.box.height),+ `${where} not round: ${button.box.width}x${button.box.height}`,+ );+ if (item.theme === 'neutral') {+ const expected = ICON_PX[size];+ check(+ near(icon.box.width, expected) && near(icon.box.height, expected),+ `${where} icon ${icon.box.width}x${icon.box.height}, expected ${expected}`,+ );+ }+ // A target under 24 px passes only through the spacing exception.+ if (button.box.width < MIN_TARGET || button.box.height < MIN_TARGET) {+ check(+ spacingClears(+ button,+ observed.buttons.filter(other => other !== button),+ ),+ `${where} is under 24 px and a neighbouring target is too close`,+ );+ }+ });++ const button = observed.buttons[0];+ const restButton = rest.buttons[0];+ if (button != null && restButton != null) {+ check(+ restButton.ariaExpanded === 'false',+ `rest aria-expanded ${restButton.ariaExpanded}`,+ );+ check(rest.tooltip == null, 'help shows at rest');+ check(+ restButton.ariaControls == null,+ `rest aria-controls ${restButton.ariaControls}`,+ );+ const helpShown =+ item.interaction === 'hover' ||+ item.interaction === 'focus' ||+ item.interaction === 'click-pin' ||+ item.interaction === 'key-pin';+ const pinned =+ item.interaction === 'click-pin' || item.interaction === 'key-pin';+ if (helpShown) {+ check(observed.tooltip != null, 'help is not shown');+ check(+ observed.tooltip?.text === spec.content,+ `help text ${observed.tooltip?.text}`,+ );+ check(+ button.description === spec.content,+ `description ${button.description}`,+ );+ check(+ button.ariaControls != null &&+ button.ariaControls === button.describedBy,+ `aria-controls ${button.ariaControls} vs ${button.describedBy}`,+ );+ } else {+ check(observed.tooltip == null, 'help is shown');+ check(+ button.ariaControls == null,+ `aria-controls ${button.ariaControls} while the help is hidden`,+ );+ }+ check(+ button.ariaExpanded === (pinned ? 'true' : 'false'),+ `aria-expanded ${button.ariaExpanded}`,+ );+ if (item.interaction === 'hover') {+ check(button.hovered, 'not hovered');+ check(+ button.icon?.color !== restButton.icon?.color,+ `hover does not change the icon color: ${button.icon?.color}`,+ );+ }+ if (+ item.interaction === 'focus' ||+ item.interaction === 'key-pin' ||+ item.interaction === 'escape'+ ) {+ check(button.focused && button.focusVisible, 'not keyboard focused');+ check(+ button.outlineStyle !== 'none' && button.outlineWidth !== '0px',+ `no focus outline: ${button.outlineStyle} ${button.outlineWidth}`,+ );+ }+ }++ const png = await page.screenshot({animations: 'disabled'});+ check(png.length > 1000, 'screenshot is empty');+ const image = `${item.key}.png`;+ const receipt = {+ schemaVersion: 1,+ expected: {+ build: checkoutSha,+ storyId: `core-infotip--${item.story}`,+ mode: item.mode,+ theme: item.theme,+ viewport: VIEWPORT,+ interaction: item.interaction,+ ...spec,+ anatomy:+ 'one native type="button" per InfoTip, in the tab order, named by aria-label, described by its help, holding the decorative registry info icon centered in a round box; no growth under a fine pointer',+ target:+ 'a box under 24 by 24 CSS px passes only when a 24 px circle on its center clears every other InfoTip target in the story, the only targets the stories render (WCAG 2.5.8 spacing exception); icon 12, 16, 20, 24 px per size at the neutral theme',+ state:+ 'rest: aria-expanded false, no aria-controls, no help; hover and focus: help shows with the content text, describes the button, aria-controls names it, aria-expanded stays false, hover changes the icon color; click or Enter: the same with aria-expanded true; Escape after a pin: help hidden, aria-expanded false, focus kept with an outline; icon and outline contrast recorded, not asserted',+ },+ observed: {+ build: storybookSha,+ rest,+ ...observed,+ geometryStable,+ pageErrors,+ },+ image: {+ file: image,+ sha256: createHash('sha256').update(png).digest('hex'),+ width: png.readUInt32BE(16),+ height: png.readUInt32BE(20),+ },+ failures,+ passed: failures.length === 0,+ };+ fs.writeFileSync(path.join(OUTPUT, image), png);+ fs.writeFileSync(+ path.join(OUTPUT, `${item.key}.sensors.json`),+ `${JSON.stringify(receipt, null, 2)}\n`,+ );+ await context.close();+ expect(failures).toEqual([]);+ });+}++test('manifest is complete', async () => {+ const receiptFiles = fs+ .readdirSync(OUTPUT)+ .filter(file => file.endsWith('.sensors.json'));+ const receipts = receiptFiles.map(+ (file): AuditReceipt =>+ JSON.parse(+ fs.readFileSync(path.join(OUTPUT, file), 'utf8'),+ ) as AuditReceipt,+ );+ fs.writeFileSync(+ path.join(OUTPUT, 'manifest.json'),+ `${JSON.stringify(+ {+ schemaVersion: 1,+ component: 'core/InfoTip',+ build: checkoutSha,+ frames: cases.map(item => ({+ key: item.key,+ image: `${item.key}.png`,+ receipt: `${item.key}.sensors.json`,+ })),+ },+ null,+ 2,+ )}\n`,+ );+ expect(receiptFiles).toHaveLength(cases.length);+ // A receipt left by an earlier build does not count.+ expect(+ receipts+ .filter(receipt => receipt.expected.build !== checkoutSha)+ .map(receipt => receipt.expected),+ ).toEqual([]);+ expect(+ receipts+ .filter(receipt => !receipt.passed)+ .map(receipt => ({frame: receipt.expected, failures: receipt.failures})),+ ).toEqual([]);+});