Skip to content

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

TypeScript

feat(lab): CircleCheckIndicator, the iOS multiple-selection circle (#9723)

Christopher Chedeau6f3befa82994
diff --git a/.changeset/cli-discover-circle-check-indicator.md b/.changeset/cli-discover-circle-check-indicator.md
new file mode 100644
index 0000000000..54dd8fdef8
--- /dev/null
+++ b/.changeset/cli-discover-circle-check-indicator.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx discover` lists the experimental CircleCheckIndicator component from `@astryxdesign/lab`.
+
+@vjeux
diff --git a/apps/storybook/stories/CircleCheckIndicator.stories.tsx b/apps/storybook/stories/CircleCheckIndicator.stories.tsx
new file mode 100644
index 0000000000..8b5eac6f82
--- /dev/null
+++ b/apps/storybook/stories/CircleCheckIndicator.stories.tsx
@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {CircleCheckIndicator} from '@astryxdesign/lab/CircleCheckIndicator';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
+
+const meta: Meta<typeof CircleCheckIndicator> = {
+ title: 'Lab/CircleCheckIndicator',
+ component: CircleCheckIndicator,
+ tags: ['autodocs'],
+ argTypes: {
+ state: {
+ control: 'inline-radio',
+ options: ['unchecked', 'checked', 'indeterminate'],
+ },
+ size: {control: 'inline-radio', options: ['sm', 'md']},
+ isDisabled: {control: 'boolean'},
+ },
+ args: {state: 'checked', size: 'md', isDisabled: false},
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'The iOS multiple-selection circle. Decorative: map it to `checkbox` in a theme so CheckboxInput and CheckboxList draw it and keep their semantics.',
+ },
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof CircleCheckIndicator>;
+
+export const Default: Story = {};
+
+export const States: Story = {
+ render: () => (
+ <VStack gap={3}>
+ {(['md', 'sm'] as const).map(size => (
+ <HStack key={size} gap={4} vAlign="center">
+ <Text type="supporting" color="secondary">
+ {size}
+ </Text>
+ <CircleCheckIndicator state="unchecked" size={size} />
+ <CircleCheckIndicator state="checked" size={size} />
+ <CircleCheckIndicator state="indeterminate" size={size} />
+ <CircleCheckIndicator state="unchecked" size={size} isDisabled />
+ <CircleCheckIndicator state="checked" size={size} isDisabled />
+ </HStack>
+ ))}
+ </VStack>
+ ),
+};
+
+const circleTheme = defineTheme({
+ name: 'circle-check-indicator-demo',
+ indicators: {checkbox: CircleCheckIndicator},
+});
+
+/**
+ * A theme maps the circle to `checkbox`: the list keeps its group, its
+ * checkboxes, its focus ring and its press, and draws circles.
+ */
+export const MappedCheckboxList: Story = {
+ render: function MappedCheckboxListStory(_args, context) {
+ const [value, setValue] = useState<string[]>(['beach']);
+ return (
+ <Theme
+ theme={circleTheme}
+ mode={context.globals.colorMode === 'dark' ? 'dark' : 'light'}>
+ <CheckboxList label="Photos to share" value={value} onChange={setValue}>
+ <CheckboxListItem label="Beach" value="beach" />
+ <CheckboxListItem label="Mountains" value="mountains" />
+ <CheckboxListItem label="City at night" value="city" />
+ <CheckboxListItem label="Forest trail" value="forest" />
+ </CheckboxList>
+ </Theme>
+ );
+ },
+};
+
+export const MappedCheckboxInput: Story = {
+ render: function MappedCheckboxInputStory(_args, context) {
+ const [value, setValue] = useState(false);
+ return (
+ <Theme
+ theme={circleTheme}
+ mode={context.globals.colorMode === 'dark' ? 'dark' : 'light'}>
+ <VStack gap={3}>
+ <CheckboxInput
+ label="Include location"
+ value={value}
+ onChange={setValue}
+ />
+ <CheckboxInput label="Partly selected" value="indeterminate" />
+ <CheckboxInput label="Disabled" value={true} isDisabled />
+ </VStack>
+ </Theme>
+ );
+ },
+};
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 70936da26b..d934cfc0ca 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -567,6 +567,11 @@
"path": "components/lab/chat-unread-divider",
"aliases": []
},
+ {
+ "name": "component-lab-circle-check-indicator",
+ "path": "components/lab/circle-check-indicator",
+ "aliases": []
+ },
{
"name": "component-lab-circular-progress",
"path": "components/lab/circular-progress",
diff --git a/packages/cli/assets/discover/official-packages.json b/packages/cli/assets/discover/official-packages.json
index 3a1276fa7d..5999288565 100644
--- a/packages/cli/assets/discover/official-packages.json
+++ b/packages/cli/assets/discover/official-packages.json
@@ -100,6 +100,10 @@
"kind": "component",
"name": "ChatUnreadDivider"
},
+ {
+ "kind": "component",
+ "name": "CircleCheckIndicator"
+ },
{
"kind": "component",
"name": "CircularProgress"
diff --git a/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.doc.mjs b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.doc.mjs
new file mode 100644
index 0000000000..b49313f6d1
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.doc.mjs
@@ -0,0 +1,215 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docs = {
+ name: 'CircleCheckIndicator',
+ displayName: 'Circle Check Indicator',
+ category: 'Form Controls',
+ keywords: [
+ 'indicator',
+ 'checkbox',
+ 'circle',
+ 'check',
+ 'multiselect',
+ 'selection',
+ 'edit mode',
+ 'ios',
+ 'mark',
+ ],
+ description:
+ 'The iOS multiple-selection mark: an empty circle, a filled circle with a checkmark, or a filled circle with a bar for the partial state. A checkbox-family indicator: map it to `checkbox` with defineTheme({indicators}) and every CheckboxInput and CheckboxList draws it. Decorative (aria-hidden); the owning control keeps the input, role, accessible name, focus, and keyboard behavior. Its colors fade over the theme duration on every pointer and change at once under Reduce Motion.',
+ props: [
+ {
+ name: 'state',
+ type: "'unchecked' | 'checked' | 'indeterminate'",
+ description:
+ 'Which state to draw. The unchecked circle is an empty ring, not nothing.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description:
+ 'Control size. The circle draws at UIKit’s diameters, 18px (sm) or 21.8px (md), centred in the host’s 20px or 24px slot.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Draws the disabled look. Purely visual; the owning control keeps the disabled semantics.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Content drawn inside the circle instead of the mark, e.g. the loading Spinner CheckboxInput passes while a change is pending.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+ },
+ ],
+ theming: {
+ targets: [
+ {
+ className: 'astryx-circle-check-indicator',
+ visualProps: ['size', 'checked', 'disabled'],
+ },
+ {className: 'astryx-circle-check-indicator-check', visualProps: ['size']},
+ {className: 'astryx-circle-check-indicator-dash', visualProps: ['size']},
+ ],
+ },
+ usage: {
+ description:
+ 'Use it where iOS shows a selection circle: the rows of a list in edit mode, and multiple-choice sets whose product follows iOS. Map it to `checkbox` in a theme to change every checkbox at once, or render it in a row you lay out yourself.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Map it with defineTheme({indicators: {checkbox: CircleCheckIndicator}}) so CheckboxInput and CheckboxList keep their semantics and focus ring.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Map it only in a theme meant for iOS. It draws the circle on every platform, and Android marks multiple choice with a square box.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Keep a visible label beside it; the circle is decorative and announces nothing.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use it for a single choice; a radio, or a checkmark on the chosen row, says "one of these".',
+ },
+ {
+ guidance: false,
+ description:
+ 'Give it a role, a label or a tab stop; the owning control has those.',
+ },
+ ],
+ },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
+ name: 'CircleCheckIndicator',
+ displayName: 'Circle Check Indicator',
+ description:
+ 'iOS 的多选标记:空心圆、带对勾的实心圆,或表示部分选中的带横线实心圆。属于复选框家族的指示器:通过 defineTheme({indicators}) 映射到 `checkbox` 后,所有 CheckboxInput 和 CheckboxList 都会绘制它。仅作装饰(aria-hidden);输入、角色、无障碍名称、焦点和键盘行为由所属控件负责。颜色在任何指针下都按主题时长渐变,开启减弱动态效果时立即切换。',
+ props: [
+ {
+ name: 'state',
+ type: "'unchecked' | 'checked' | 'indeterminate'",
+ description: '要绘制的状态。未选中时是一个空心圆环,而不是什么都不画。',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description:
+ '控件尺寸。圆圈按 UIKit 的直径绘制:sm 为 18px,md 为 21.8px,居中于宿主 20px 或 24px 的位置。',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '绘制禁用外观。仅影响视觉;禁用语义由所属控件负责。',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ '绘制在圆内、替代标记的内容,例如 CheckboxInput 在变更进行中传入的加载 Spinner。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ },
+ ],
+ theming: {
+ targets: [
+ {
+ className: 'astryx-circle-check-indicator',
+ visualProps: ['size', 'checked', 'disabled'],
+ },
+ {className: 'astryx-circle-check-indicator-check', visualProps: ['size']},
+ {className: 'astryx-circle-check-indicator-dash', visualProps: ['size']},
+ ],
+ },
+ usage: {
+ description:
+ '用在 iOS 显示选择圆圈的地方:编辑模式下的列表行,以及遵循 iOS 的多选集合。在主题中将其映射到 `checkbox` 可一次替换所有复选框,也可以在自行布局的行中直接渲染。',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ '使用 defineTheme({indicators: {checkbox: CircleCheckIndicator}}) 映射,使 CheckboxInput 和 CheckboxList 保留其语义和焦点环。',
+ },
+ {
+ guidance: true,
+ description:
+ '只在面向 iOS 的主题中映射它。它在所有平台上都绘制圆圈,而 Android 用方形复选框表示多选。',
+ },
+ {
+ guidance: true,
+ description: '在旁边保留可见标签;圆圈仅作装饰,不会被朗读。',
+ },
+ {
+ guidance: false,
+ description: '用于单选;单选按钮或所选行上的对勾表示“其中之一”。',
+ },
+ {
+ guidance: false,
+ description: '为其添加角色、标签或 Tab 停靠点;这些属于所属控件。',
+ },
+ ],
+ },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+ description:
+ 'iOS multiselect circle: empty ring / filled circle + check / filled circle + bar. Checkbox-family indicator; map to `checkbox` via defineTheme({indicators}).',
+ usage: {
+ description:
+ 'For iOS-style selection circles: edit-mode list rows and multiple-choice sets. Map it to `checkbox` in a theme, or render it in your own row.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Map via defineTheme({indicators: {checkbox: CircleCheckIndicator}}); hosts keep semantics + focus ring.',
+ },
+ {
+ guidance: true,
+ description: 'Keep a visible label; the circle is decorative.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for a single choice (radio or row checkmark instead).',
+ },
+ {
+ guidance: false,
+ description:
+ 'Add role, label or tabIndex; the owning control has them.',
+ },
+ ],
+ },
+ propDescriptions: {
+ state:
+ "'unchecked' (empty ring) | 'checked' (check) | 'indeterminate' (bar).",
+ size: "'sm' an 18px circle | 'md' a 21.8px circle (in a 20px or 24px slot).",
+ isDisabled: 'Disabled look only; owner keeps semantics.',
+ children: 'Drawn inside the circle instead of the mark (e.g. Spinner).',
+ xstyle: 'StyleX layout styles; must be stylex.create() value.',
+ },
+};
diff --git a/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.test.tsx b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.test.tsx
new file mode 100644
index 0000000000..a6da9e5dde
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.test.tsx
@@ -0,0 +1,134 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircleCheckIndicator.test.tsx
+ * @input vitest, Testing Library, CircleCheckIndicator, and core's
+ * CheckboxInput and CheckboxList with a theme that maps `checkbox`
+ * @output Unit tests for the theme target and its state attributes, and the
+ * mark drawn per state (a ring, a check, a bar). They also cover children
+ * that replace the mark, the decorative semantics and the theme mapping
+ * into core's checkbox hosts.
+ * @position Testing; validates CircleCheckIndicator.tsx. The touch clock is
+ * circleCheck.test.tsx; the real-engine proof is
+ * __tests__/CircleCheckIndicator.interaction.browser.spec.ts
+ *
+ * SYNC: When CircleCheckIndicator.tsx changes, update tests to match.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useState} from 'react';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
+import {CircleCheckIndicator} from './CircleCheckIndicator';
+
+const circleTheme = defineTheme({
+ name: 'circle-check-test',
+ indicators: {checkbox: CircleCheckIndicator},
+});
+
+/** The visible mark: whether the check and the bar display. */
+function marks(root: Element) {
+ const check = root.querySelector('.astryx-circle-check-indicator-check');
+ const dash = root.querySelector('.astryx-circle-check-indicator-dash');
+ if (check == null || dash == null) {
+ throw new Error('the mark elements are missing');
+ }
+ return {
+ check: getComputedStyle(check).display !== 'none',
+ dash: getComputedStyle(dash).display !== 'none',
+ };
+}
+
+describe('CircleCheckIndicator', () => {
+ it('renders its theme target with state and size, decoratively', () => {
+ render(<CircleCheckIndicator state="checked" size="sm" />);
+ const circle = document.querySelector('.astryx-circle-check-indicator');
+ expect(circle).toHaveAttribute('data-checked', 'checked');
+ expect(circle).toHaveAttribute('data-size', 'sm');
+ expect(circle).toHaveAttribute('aria-hidden', 'true');
+ });
+
+ it('draws an empty ring unchecked, a check when checked, a bar when partial', () => {
+ const {rerender} = render(<CircleCheckIndicator state="unchecked" />);
+ const circle = document.querySelector('.astryx-circle-check-indicator');
+ if (circle == null) {
+ throw new Error('no circle');
+ }
+ // The unchecked circle still renders: an indicator draws in every state.
+ expect(circle).not.toHaveAttribute('data-checked');
+ expect(marks(circle)).toEqual({check: false, dash: false});
+ rerender(<CircleCheckIndicator state="checked" />);
+ expect(marks(circle)).toEqual({check: true, dash: false});
+ rerender(<CircleCheckIndicator state="indeterminate" />);
+ expect(circle).toHaveAttribute('data-checked', 'indeterminate');
+ expect(marks(circle)).toEqual({check: false, dash: true});
+ });
+
+ it('reflects the disabled state for theme targeting', () => {
+ render(<CircleCheckIndicator state="unchecked" isDisabled />);
+ expect(
+ document.querySelector('.astryx-circle-check-indicator'),
+ ).toHaveAttribute('data-disabled', 'disabled');
+ });
+
+ it('renders children instead of the mark', () => {
+ render(
+ <CircleCheckIndicator state="checked">
+ <span data-testid="busy" />
+ </CircleCheckIndicator>,
+ );
+ expect(screen.getByTestId('busy')).toBeInTheDocument();
+ expect(
+ document.querySelector('.astryx-circle-check-indicator-check'),
+ ).toBeNull();
+ });
+
+ it('stays aria-hidden even when a caller passes false', () => {
+ render(<CircleCheckIndicator state="unchecked" aria-hidden={false} />);
+ expect(
+ document.querySelector('.astryx-circle-check-indicator'),
+ ).toHaveAttribute('aria-hidden', 'true');
+ });
+});
+
+describe('CircleCheckIndicator mapped to `checkbox` by a theme', () => {
+ it('draws the circle in a CheckboxInput, which keeps the checkbox semantics', () => {
+ function Controlled() {
+ const [value, setValue] = useState(false);
+ return (
+ <Theme theme={circleTheme}>
+ <CheckboxInput
+ label="Select photo"
+ value={value}
+ onChange={setValue}
+ />
+ </Theme>
+ );
+ }
+ render(<Controlled />);
+ const input = screen.getByRole('checkbox', {name: 'Select photo'});
+ const circle = document.querySelector('.astryx-circle-check-indicator');
+ expect(circle).toBeInTheDocument();
+ expect(document.querySelector('.astryx-checkbox-indicator')).toBeNull();
+ fireEvent.click(input);
+ expect(input).toBeChecked();
+ expect(circle).toHaveAttribute('data-checked', 'checked');
+ });
+
+ it('draws one circle per CheckboxList row', () => {
+ render(
+ <Theme theme={circleTheme}>
+ <CheckboxList label="Photos" value={['a']} onChange={() => {}}>
+ <CheckboxListItem label="Beach" value="a" />
+ <CheckboxListItem label="Mountains" value="b" />
+ </CheckboxList>
+ </Theme>,
+ );
+ const circles = document.querySelectorAll('.astryx-circle-check-indicator');
+ expect(circles).toHaveLength(2);
+ expect(circles[0]).toHaveAttribute('data-checked', 'checked');
+ expect(circles[1]).not.toHaveAttribute('data-checked');
+ });
+});
diff --git a/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.tsx b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.tsx
new file mode 100644
index 0000000000..28ef550973
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/CircleCheckIndicator.tsx
@@ -0,0 +1,248 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircleCheckIndicator.tsx
+ * @input Indicator state props, the theme's colour and radius tokens, Core's
+ * indicator press marker, and the circle's styles (circleCheck.stylex.ts)
+ * @output Exports CircleCheckIndicator, the iOS multiple-selection mark
+ * @position Lab. A multiSelection-family indicator that a theme maps to
+ * `checkbox`
+ *
+ * SYNC: When modified, update CircleCheckIndicator.doc.mjs,
+ * CircleCheckIndicator.test.tsx, index.ts and the story.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import type {IndicatorProps} from '@astryxdesign/core/Indicator';
+import {indicatorScope} from '@astryxdesign/core/Indicator/indicator.markers.stylex';
+import {indicatorPressScope} from '@astryxdesign/core/internal/indicatorPress.stylex';
+import {colorVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
+import {isRenderable, mergeProps, themeProps} from '@astryxdesign/core/utils';
+import {
+ circleCheckMotionStyles,
+ circleCheckSizeStyles,
+} from './circleCheck.stylex';
+
+const styles = stylex.create({
+ circle: {
+ boxSizing: 'border-box',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ flexShrink: 0,
+ borderRadius: radiusVars['--radius-full'],
+ // Forced colors drops the inset-shadow ring, so a system-coloured border
+ // draws it there.
+ borderStyle: {default: 'none', '@media (forced-colors: active)': 'solid'},
+ borderWidth: {default: 0, '@media (forced-colors: active)': '1px'},
+ borderColor: {
+ default: 'transparent',
+ '@media (forced-colors: active)': 'CanvasText',
+ },
+ },
+ // The empty circle is a ring with a clear centre, as UIKit's is. A selected
+ // edit-mode row keeps its background behind the mark.
+ unchecked: {
+ boxShadow: {
+ default: `inset 0 0 0 var(--_circle-stroke) ${colorVars['--color-border-emphasized']}`,
+ [stylex.when.ancestor(':hover', indicatorScope)]: {
+ '@media (hover: hover)': `inset 0 0 0 var(--_circle-stroke) color-mix(in srgb, ${colorVars['--color-border-emphasized']}, ${colorVars['--color-tint-hover']} 20%)`,
+ },
+ },
+ backgroundColor: 'transparent',
+ },
+ checked: {
+ // An inherit-shade loading spinner reads this colour as currentColor.
+ color: colorVars['--color-on-accent'],
+ boxShadow: 'none',
+ backgroundColor: {
+ default: colorVars['--color-accent'],
+ [stylex.when.ancestor(':hover', indicatorScope)]: {
+ '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
+ },
+ },
+ },
+ disabled: {
+ opacity: 0.5,
+ },
+ // The press paints on the circle itself. The host's rounded-square layer
+ // would tint past the circle, so the host leaves it off here. A touch
+ // press arrives as `--_indicator-press-image`, which only a CheckboxInput
+ // row declares, so a menu row's own press never paints twice.
+ ownPress: {
+ position: 'relative',
+ '::after': {
+ content: '""',
+ position: 'absolute',
+ inset: 0,
+ borderRadius: radiusVars['--radius-full'],
+ pointerEvents: 'none',
+ backgroundColor: {
+ default: 'transparent',
+ [stylex.when.ancestor(':active', indicatorScope)]: {
+ default: colorVars['--color-overlay-pressed'],
+ '@media (pointer: coarse)': 'transparent',
+ },
+ },
+ // The image paints under a coarse pointer only, as CheckboxInput's own
+ // layer does. A held pen on a fine-pointer page already draws the
+ // `:active` fill, and the image would paint a second press. StyleX puts
+ // a constant media key in a later priority layer than a literal one. So
+ // the key stays literal.
+ backgroundImage: {
+ default: null,
+ '@media (pointer: coarse)': 'var(--_indicator-press-image, none)',
+ },
+ },
+ },
+ checkmark: {
+ display: 'none',
+ flexShrink: 0,
+ overflow: 'visible',
+ color: {
+ default: colorVars['--color-on-accent'],
+ // Forced colors flattens the fill to Canvas and may not force an SVG
+ // stroke drawn with currentColor. CanvasText keeps the check visible on
+ // it (WCAG 1.4.11).
+ '@media (forced-colors: active)': 'CanvasText',
+ },
+ },
+ checkmarkVisible: {
+ display: 'block',
+ },
+ bar: {
+ display: 'none',
+ flexShrink: 0,
+ backgroundColor: {
+ default: colorVars['--color-on-accent'],
+ '@media (forced-colors: active)': 'CanvasText',
+ },
+ borderRadius: radiusVars['--radius-full'],
+ },
+ barVisible: {
+ display: 'block',
+ },
+});
+
+const CIRCLE = {
+ sm: circleCheckSizeStyles.smCircle,
+ md: circleCheckSizeStyles.mdCircle,
+} as const;
+const CHECK = {
+ sm: circleCheckSizeStyles.smCheck,
+ md: circleCheckSizeStyles.mdCheck,
+} as const;
+const BAR = {
+ sm: circleCheckSizeStyles.smBar,
+ md: circleCheckSizeStyles.mdBar,
+} as const;
+
+/**
+ * The iOS multiple-selection mark. It shows an empty circle when unchecked
+ * and a filled circle with a checkmark when checked. The partial state fills
+ * the circle with a bar.
+ *
+ * Decorative and non-interactive, like every indicator: it renders
+ * `aria-hidden` and owns no input, role, or focus behavior. Map it to
+ * `checkbox` in a theme, and every CheckboxInput and CheckboxList draws it.
+ * The owning control keeps its semantics and paints its focus ring on the
+ * circle. Its colours fade over the theme duration on every pointer, and
+ * change at once under Reduce Motion. It draws the circle everywhere, so
+ * map it only in a theme meant for iOS.
+ *
+ * @example
+ * ```
+ * const theme = defineTheme({
+ * name: 'circle-checks',
+ * indicators: {checkbox: CircleCheckIndicator},
+ * });
+ * ```
+ */
+export function CircleCheckIndicator({
+ state,
+ size = 'md',
+ isDisabled = false,
+ children,
+ ref,
+ className,
+ style,
+ xstyle,
+ ...rest
+}: IndicatorProps<'multiSelection'>) {
+ const isChecked = state === 'checked';
+ const isIndeterminate = state === 'indeterminate';
+ const isFilled = isChecked || isIndeterminate;
+
+ return (
+ <span
+ // `{...rest}` goes first, so a caller cannot un-hide this decorative
+ // element (see IndicatorProps).
+ {...rest}
+ ref={ref}
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('circle-check-indicator', {
+ size,
+ checked: isChecked
+ ? 'checked'
+ : isIndeterminate
+ ? 'indeterminate'
+ : null,
+ disabled: isDisabled ? 'disabled' : null,
+ }),
+ stylex.props(
+ // Marks the circle as painting its own press (styles.ownPress), so
+ // the host leaves its square layer off.
+ indicatorPressScope,
+ styles.circle,
+ !isDisabled && styles.ownPress,
+ circleCheckMotionStyles.mark,
+ CIRCLE[size],
+ isFilled ? styles.checked : styles.unchecked,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {isRenderable(children) ? (
+ children
+ ) : (
+ <>
+ {/* The check's ink fills its box: the round caps reach the edges. */}
+ <svg
+ viewBox="0 0 10 10"
+ {...mergeProps(
+ themeProps('circle-check-indicator-check', {size}),
+ stylex.props(
+ styles.checkmark,
+ CHECK[size],
+ isChecked && styles.checkmarkVisible,
+ ),
+ )}>
+ <path
+ d="M0.75 5.25L3.75 9.25L9.25 0.75"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ fill="none"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ <span
+ {...mergeProps(
+ themeProps('circle-check-indicator-dash', {size}),
+ stylex.props(
+ styles.bar,
+ BAR[size],
+ isIndeterminate && styles.barVisible,
+ ),
+ )}
+ />
+ </>
+ )}
+ </span>
+ );
+}
+
+CircleCheckIndicator.displayName = 'CircleCheckIndicator';
diff --git a/packages/lab/src/CircleCheckIndicator/__tests__/CircleCheckIndicator.interaction.browser.spec.ts b/packages/lab/src/CircleCheckIndicator/__tests__/CircleCheckIndicator.interaction.browser.spec.ts
new file mode 100644
index 0000000000..47514f1a97
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/__tests__/CircleCheckIndicator.interaction.browser.spec.ts
@@ -0,0 +1,567 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircleCheckIndicator.interaction.browser.spec.ts
+ * @input The built Lab CircleCheckIndicator "Mapped Checkbox List" story, in
+ * which a theme maps the circle to `checkbox`. Real touch input (Chromium
+ * CDP, WebKit's tap) and the interaction harness drive it.
+ * @output Proofs that a finger and a mouse both fade the circle over the
+ * theme's duration. Under Reduce Motion both change it at once.
+ * A storyboard shows a tap's blended frames. The row keeps its checkbox
+ * semantics.
+ * @position Real-engine layer of CircleCheckIndicator; the stylesheet layer
+ * is circleCheck.test.tsx
+ */
+
+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
+import {
+ castStoryboard,
+ frames,
+ openStory,
+ startScreencast,
+ touchDriver,
+ withStorybook,
+} from '@astryxdesign/interaction-harness';
+
+const storybook = withStorybook(test);
+
+const STORY = 'lab-circlecheckindicator--mapped-checkbox-list';
+
+/** What the page saw in the microtask after the circle's class changed. */
+interface CircleRead {
+ first: string;
+ transitions: {property: string; duration: number}[];
+}
+
+/** The circle of the row labelled `name`. */
+const CIRCLE = '.astryx-circle-check-indicator';
+
+async function watchCircle(page: Page, name: string): Promise<void> {
+ await page.getByRole('checkbox', {name}).evaluate(
+ (input, {selector, key}) => {
+ const circle = input
+ .closest('li, .astryx-item')
+ ?.querySelector<HTMLElement>(selector);
+ if (circle == null) {
+ throw new Error(`no circle for ${key}`);
+ }
+ const reads = ((
+ window as unknown as Record<string, unknown>
+ ).__circleMarkReads ??= {}) as Record<string, unknown>;
+ const observer = new MutationObserver(() => {
+ if (reads[key] != null) {
+ return;
+ }
+ reads[key] = {
+ first: getComputedStyle(circle).backgroundColor,
+ transitions: circle
+ .getAnimations()
+ .filter(animation => 'transitionProperty' in animation)
+ .map(animation => ({
+ property: (animation as CSSTransition).transitionProperty,
+ duration: Number(animation.effect?.getTiming().duration ?? 0),
+ })),
+ };
+ observer.disconnect();
+ });
+ observer.observe(circle, {attributes: true, attributeFilter: ['class']});
+ },
+ {selector: CIRCLE, key: name},
+ );
+}
+
+async function readCircle(page: Page, name: string): Promise<CircleRead> {
+ await page.waitForFunction(
+ key =>
+ ((window as unknown as Record<string, Record<string, unknown>>)
+ .__circleMarkReads ?? {})[key] != null,
+ name,
+ );
+ return page.evaluate(
+ key =>
+ (window as unknown as Record<string, Record<string, CircleRead>>)
+ .__circleMarkReads[key],
+ name,
+ );
+}
+
+async function circleColour(page: Page, name: string): Promise<string> {
+ return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
+ const circle = input.closest('li, .astryx-item')?.querySelector(selector);
+ if (circle == null) {
+ throw new Error('no circle');
+ }
+ return getComputedStyle(circle).backgroundColor;
+ }, CIRCLE);
+}
+
+/** How many animations the circle of the row labelled `name` runs. */
+async function runningOn(page: Page, name: string): Promise<number> {
+ return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
+ const circle = input.closest('li, .astryx-item')?.querySelector(selector);
+ if (circle == null) {
+ throw new Error('no circle');
+ }
+ return circle.getAnimations().length;
+ }, CIRCLE);
+}
+
+/**
+ * Waits until the circle runs no animation. The two frames first let the
+ * last input's transition start.
+ */
+async function untilStill(page: Page, name: string): Promise<void> {
+ await frames(page, 2);
+ await expect.poll(() => runningOn(page, name)).toBe(0);
+}
+
+/** The circle's colour once it is still, held for two more frames. */
+async function settledColour(page: Page, name: string): Promise<string> {
+ await untilStill(page, name);
+ const colour = await circleColour(page, name);
+ await frames(page, 2);
+ expect(await circleColour(page, name), 'two frames later').toBe(colour);
+ return colour;
+}
+
+/** The centre of the circle of the row labelled `name`: a mouse there is on the checkbox. */
+async function circleCentreOf(page: Page, name: string) {
+ const box = await page
+ .getByRole('checkbox', {name})
+ .evaluate((input, selector) => {
+ const circle = input.closest('li, .astryx-item')?.querySelector(selector);
+ if (circle == null) {
+ throw new Error('no circle');
+ }
+ const r = circle.getBoundingClientRect();
+ return {x: r.x + r.width / 2, y: r.y + r.height / 2};
+ }, CIRCLE);
+ return {x: Math.round(box.x), y: Math.round(box.y)};
+}
+
+async function centreOf(page: Page, name: string) {
+ const box = await page.getByRole('checkbox', {name}).evaluate(input => {
+ const row = input.closest('li, .astryx-item');
+ if (row == null) {
+ throw new Error('no row');
+ }
+ const r = row.getBoundingClientRect();
+ return {x: r.x + r.width / 2, y: r.y + r.height / 2};
+ });
+ return {x: Math.round(box.x), y: Math.round(box.y)};
+}
+
+/** The circle's background on every animation frame for `ms`. */
+async function traceCircle(
+ page: Page,
+ name: string,
+ ms: number,
+): Promise<{t: number; colour: string}[]> {
+ return page.getByRole('checkbox', {name}).evaluate(
+ async (input, {selector, ms}) => {
+ const circle = input.closest('li, .astryx-item')?.querySelector(selector);
+ if (circle == null) {
+ throw new Error('no circle');
+ }
+ const samples: {t: number; colour: string}[] = [];
+ const end = performance.now() + ms;
+ return new Promise<{t: number; colour: string}[]>(resolve => {
+ const tick = () => {
+ samples.push({
+ t: Date.now(),
+ colour: getComputedStyle(circle).backgroundColor,
+ });
+ if (performance.now() < end) {
+ requestAnimationFrame(tick);
+ } else {
+ resolve(samples);
+ }
+ };
+ requestAnimationFrame(tick);
+ });
+ },
+ {selector: CIRCLE, ms},
+ );
+}
+
+test.describe('CircleCheckIndicator under a finger', () => {
+ // One touch model on every touch device: a coarse primary pointer. The
+ // touch page here is the engine's own touch emulation; real iOS Safari and
+ // Android Chrome are the simulator and emulator recordings.
+
+ test('a tap fades the circle over the theme’s duration, and the row stays a checkbox', async ({
+ page,
+ }) => {
+ await openStory(page, storybook(), STORY);
+ await watchCircle(page, 'Mountains');
+ const driver = await touchDriver(page);
+ await driver.tap(await centreOf(page, 'Mountains'));
+ await expect(page.getByRole('checkbox', {name: 'Mountains'})).toBeChecked();
+ const read = await readCircle(page, 'Mountains');
+ expect(
+ read.transitions.some(
+ ({property, duration}) =>
+ property === 'background-color' && duration > 0,
+ ),
+ ).toBe(true);
+ expect(read.first).not.toBe(await settledColour(page, 'Mountains'));
+ });
+
+ test('a tap’s fade, filmed: the transition runs from the start colour @storyboard', async ({
+ page,
+ }, testInfo) => {
+ await openStory(page, storybook(), STORY);
+ const driver = await touchDriver(page);
+ const at = await centreOf(page, 'Mountains');
+ const before = await circleColour(page, 'Mountains');
+ await watchCircle(page, 'Mountains');
+ const cast = await startScreencast(page);
+ await frames(page, 4);
+ const tapAt = Date.now();
+ const [trace] = await Promise.all([
+ traceCircle(page, 'Mountains', 500),
+ driver.tap(at),
+ ]);
+ const shot = await cast.stop();
+ const after = trace.at(-1)?.colour;
+ const nearest = (t: number) =>
+ trace.reduce((best, sample) =>
+ Math.abs(sample.t - t) < Math.abs(best.t - t) ? sample : best,
+ );
+ // The evidence is written first, so a failing run shows its blend.
+ const storyboard = await castStoryboard(page, shot, {
+ name: 'circle-check-tap',
+ zero: tapAt,
+ cellScale: 0.5,
+ columns: 4,
+ data: t => ({circle: nearest(t).colour}),
+ });
+ await storyboard.write(testInfo, {
+ claim:
+ 'under a finger the circle fades in over the theme duration, as with a mouse',
+ before,
+ after,
+ });
+ expect(after).not.toBe(before);
+ // The frames are evidence only: a busy main thread can skip every blended
+ // frame. The transition itself is read from the first style after the change.
+ const read = await readCircle(page, 'Mountains');
+ expect(
+ read.transitions.some(
+ ({property, duration}) =>
+ property === 'background-color' && duration > 0,
+ ),
+ ).toBe(true);
+ expect(read.first).toBe(before);
+ });
+
+ test('a mouse fades the circle the same way', async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: {width: 1024, height: 768},
+ hasTouch: false,
+ isMobile: false,
+ });
+ const page = await context.newPage();
+ try {
+ await openStory(page, storybook(), STORY);
+ // A fine-pointer case proves nothing under a coarse primary pointer.
+ expect(
+ await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
+ ).toBe(false);
+ await watchCircle(page, 'Mountains');
+ const at = await centreOf(page, 'Mountains');
+ await page.mouse.move(at.x, at.y);
+ await untilStill(page, 'Mountains');
+ await page.mouse.click(at.x, at.y);
+ const read = await readCircle(page, 'Mountains');
+ expect(
+ read.transitions.some(
+ ({property, duration}) =>
+ property === 'background-color' && duration > 0,
+ ),
+ ).toBe(true);
+ await untilStill(page, 'Mountains');
+ expect(read.first).not.toBe(await circleColour(page, 'Mountains'));
+ } finally {
+ await context.close();
+ }
+ });
+});
+
+test.describe('CircleCheckIndicator under Reduce Motion', () => {
+ test('a finger changes the circle at once', async ({page}) => {
+ await page.emulateMedia({reducedMotion: 'reduce'});
+ await openStory(page, storybook(), STORY);
+ await watchCircle(page, 'Mountains');
+ const driver = await touchDriver(page);
+ await driver.tap(await centreOf(page, 'Mountains'));
+ await expect(page.getByRole('checkbox', {name: 'Mountains'})).toBeChecked();
+ const read = await readCircle(page, 'Mountains');
+ expect(read.transitions).toEqual([]);
+ expect(read.first).toBe(await settledColour(page, 'Mountains'));
+ });
+
+ test('a mouse changes at once (design:reduced-motion DR3)', async ({
+ browser,
+ }) => {
+ const context = await browser.newContext({
+ viewport: {width: 1024, height: 768},
+ hasTouch: false,
+ isMobile: false,
+ reducedMotion: 'reduce',
+ });
+ const page = await context.newPage();
+ try {
+ await openStory(page, storybook(), STORY);
+ // A fine-pointer case proves nothing under a coarse primary pointer.
+ expect(
+ await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
+ ).toBe(false);
+ await watchCircle(page, 'Mountains');
+ const at = await circleCentreOf(page, 'Mountains');
+ await page.mouse.move(at.x, at.y);
+ await untilStill(page, 'Mountains');
+ await page.mouse.click(at.x, at.y);
+ await expect(
+ page.getByRole('checkbox', {name: 'Mountains'}),
+ ).toBeChecked();
+ const read = await readCircle(page, 'Mountains');
+ expect(read.transitions).toEqual([]);
+ expect(read.first).toBe(await circleColour(page, 'Mountains'));
+ } finally {
+ await context.close();
+ }
+ });
+});
+
+/** The host's press layer and the circle's own, while the row is pressed. */
+async function readPress(page: Page, name: string) {
+ return page.getByRole('checkbox', {name}).evaluate((input, selector) => {
+ const wrapper = input.parentElement;
+ const circle = input
+ .closest('li, .astryx-item')
+ ?.querySelector<HTMLElement>(selector);
+ if (wrapper == null || circle == null) {
+ throw new Error('no circle');
+ }
+ const host = getComputedStyle(wrapper, '::after');
+ const own = getComputedStyle(circle, '::after');
+ return {
+ hostContent: host.content,
+ circleContent: own.content,
+ circleImage: own.backgroundImage,
+ circleColour: own.backgroundColor,
+ circleLayerRadius: own.borderRadius,
+ circleRadius: getComputedStyle(circle).borderRadius,
+ };
+ }, CIRCLE);
+}
+
+/** Whether the list row that holds the named checkbox carries a press. */
+async function rowPressed(page: Page, name: string): Promise<boolean> {
+ return page
+ .getByRole('checkbox', {name})
+ .evaluate(
+ input => input.closest('li')?.hasAttribute('data-astryx-press') ?? false,
+ );
+}
+
+test.describe('CircleCheckIndicator press', () => {
+ test('a held circle presses the row and paints round; the host’s square layer stays off', async ({
+ page,
+ }) => {
+ await openStory(page, storybook(), STORY);
+ const at = await circleCentreOf(page, 'Mountains');
+ const driver = await touchDriver(page);
+ // At rest the circle paints no press image.
+ const rest = await readPress(page, 'Mountains');
+ let read: Awaited<ReturnType<typeof readPress>> | null = null;
+ let pressedRow = false;
+ await driver.play(
+ [
+ {t: 0, fingers: [{id: 1, ...at}]},
+ {t: 600, fingers: []},
+ ],
+ {
+ onEvent: async step => {
+ if (step.type !== 'touchStart') {
+ return;
+ }
+ // The press paints after the content-touch delay, inside the hold.
+ await expect
+ .poll(
+ async () => {
+ read = await readPress(page, 'Mountains');
+ return read.circleImage;
+ },
+ {timeout: 500},
+ )
+ .not.toBe(rest.circleImage);
+ pressedRow = await rowPressed(page, 'Mountains');
+ },
+ },
+ );
+ if (read == null) {
+ throw new Error('the press was not read');
+ }
+ const held: Awaited<ReturnType<typeof readPress>> = read;
+ // Under a finger the row is the one press surface; the circle paints it.
+ expect(pressedRow).toBe(true);
+ expect(held.hostContent).toBe('none');
+ expect(held.circleContent).not.toBe('none');
+ expect(held.circleImage).not.toBe(rest.circleImage);
+ expect(held.circleLayerRadius).toBe(held.circleRadius);
+ });
+
+ test('a held label presses the row, and the circle paints with it', async ({
+ page,
+ }) => {
+ await openStory(page, storybook(), STORY);
+ const at = await centreOf(page, 'Mountains');
+ const driver = await touchDriver(page);
+ const rest = await readPress(page, 'Mountains');
+ let held: Awaited<ReturnType<typeof readPress>> | null = null;
+ await driver.play(
+ [
+ {t: 0, fingers: [{id: 1, ...at}]},
+ {t: 600, fingers: []},
+ ],
+ {
+ onEvent: async step => {
+ if (step.type !== 'touchStart') {
+ return;
+ }
+ // The row's own press proves the hold landed. The circle is read then.
+ await expect
+ .poll(async () => rowPressed(page, 'Mountains'), {timeout: 500})
+ .toBe(true);
+ held = await readPress(page, 'Mountains');
+ },
+ },
+ );
+ if (held == null) {
+ throw new Error('the hold was not read');
+ }
+ const read: Awaited<ReturnType<typeof readPress>> = held;
+ // The row hands its own checkbox the press, wherever the finger lands, and
+ // the circle paints it round while the host's square layer stays off.
+ expect(read.circleImage).not.toBe(rest.circleImage);
+ expect(read.circleContent).not.toBe('none');
+ expect(read.hostContent).toBe('none');
+ });
+
+ test('a mouse press tints the circle, not a square around it', async ({
+ browser,
+ }) => {
+ const context = await browser.newContext({
+ viewport: {width: 1024, height: 768},
+ hasTouch: false,
+ isMobile: false,
+ });
+ const page = await context.newPage();
+ try {
+ await openStory(page, storybook(), STORY);
+ // A fine-pointer case proves nothing under a coarse primary pointer.
+ expect(
+ await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
+ ).toBe(false);
+ const at = await circleCentreOf(page, 'Mountains');
+ await page.mouse.move(at.x, at.y);
+ await page.mouse.down();
+ const held = await readPress(page, 'Mountains');
+ await page.mouse.up();
+ expect(held.hostContent).toBe('none');
+ expect(held.circleColour).not.toBe('rgba(0, 0, 0, 0)');
+ expect(held.circleLayerRadius).toBe(held.circleRadius);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('a mouse hovering the checkbox tints the circle', async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: {width: 1024, height: 768},
+ hasTouch: false,
+ isMobile: false,
+ });
+ const page = await context.newPage();
+ try {
+ await openStory(page, storybook(), STORY);
+ // A fine-pointer case proves nothing under a coarse primary pointer.
+ expect(
+ await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
+ ).toBe(false);
+ const ring = async () =>
+ page
+ .getByRole('checkbox', {name: 'Mountains'})
+ .evaluate(
+ (input, selector) =>
+ getComputedStyle(
+ input
+ .closest('li, .astryx-item')
+ ?.querySelector(selector) as Element,
+ ).boxShadow,
+ CIRCLE,
+ );
+ await page.mouse.move(1, 1);
+ const rest = await ring();
+ const at = await circleCentreOf(page, 'Mountains');
+ await page.mouse.move(at.x, at.y);
+ await expect.poll(ring).not.toBe(rest);
+ } finally {
+ await context.close();
+ }
+ });
+});
+
+test.describe('CircleCheckIndicator in forced colors', () => {
+ test('the ring falls back to a 1px system-coloured border, and the check stays visible', async ({
+ page,
+ }) => {
+ /** The circle and check of the first row whose checkbox is `checked`. */
+ const read = async (checked: boolean) =>
+ page.evaluate(
+ ({want, circleSelector}) => {
+ const input = Array.from(
+ document.querySelectorAll<HTMLInputElement>(
+ '#storybook-root input[type="checkbox"]',
+ ),
+ ).find(el => el.checked === want);
+ const row = input?.closest('li, .astryx-item');
+ const circle = row?.querySelector<HTMLElement>(circleSelector);
+ const check = row?.querySelector<SVGElement>(
+ '.astryx-circle-check-indicator-check',
+ );
+ if (circle == null || check == null) {
+ return null;
+ }
+ const ring = getComputedStyle(circle);
+ const mark = getComputedStyle(check);
+ return {
+ borderStyle: ring.borderTopStyle,
+ borderWidth: ring.borderTopWidth,
+ boxShadow: ring.boxShadow,
+ checkDisplay: mark.display,
+ checkVisibility: mark.visibility,
+ };
+ },
+ {want: checked, circleSelector: CIRCLE},
+ );
+ await openStory(page, storybook(), STORY);
+ // Default: the empty circle's ring is the inset shadow, with no border.
+ const normal = await read(false);
+ expect(normal).not.toBeNull();
+ expect(normal?.borderStyle).toBe('none');
+ expect(normal?.boxShadow).toContain('inset');
+ // Forced colors drops shadows: the ring comes back as a 1px border.
+ await page.emulateMedia({forcedColors: 'active'});
+ const forced = await read(false);
+ expect(forced?.borderStyle).toBe('solid');
+ expect(forced?.borderWidth).toBe('1px');
+ // A checked circle still shows its check.
+ const checked = await read(true);
+ expect(checked).not.toBeNull();
+ expect(checked?.checkDisplay).not.toBe('none');
+ expect(checked?.checkVisibility).toBe('visible');
+ });
+});
diff --git a/packages/lab/src/CircleCheckIndicator/circleCheck.stylex.ts b/packages/lab/src/CircleCheckIndicator/circleCheck.stylex.ts
new file mode 100644
index 0000000000..893620e70d
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/circleCheck.stylex.ts
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file circleCheck.stylex.ts
+ * @input The theme's duration and easing tokens
+ * @output Exports `circleCheckConsts`, the build-time mirror of
+ * circleCheck.table.ts, and the circle's motion and size styles
+ * @position Internal to CircleCheckIndicator
+ *
+ * StyleX cannot read the table at build time, so these constants mirror it,
+ * and circleCheck.test.tsx fails if they drift. StyleX inlines a
+ * `defineConsts` value only in its own file, so the styles live here too.
+ *
+ * SYNC: When modified, update circleCheck.test.tsx.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, easeVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+/**
+ * `md` is UIKit's circle at the Large text size, and `sm` at xSmall. Two `sm`
+ * values derive from their Large proportions: the check stroke and its offset.
+ * The partial state's bar has no UIKit counterpart, so it takes the
+ * checkmark's width and stroke.
+ */
+export const circleCheckConsts = stylex.defineConsts({
+ /** `circleCheckTable.large.diameter`. */
+ mdDiameter: '21.8px',
+ /** `circleCheckTable.large.stroke`. */
+ mdStroke: '1.54px',
+ /** `circleCheckTable.large.checkSize`. */
+ mdCheckSize: '9px',
+ /** `circleCheckTable.large.checkStroke`. */
+ mdCheckStroke: '1.35px',
+ /** `circleCheckTable.large.checkOffsetY`. */
+ mdCheckOffsetY: '1px',
+ /** `circleCheckTable.xSmall.diameter`. */
+ smDiameter: '18px',
+ /** `circleCheckTable.xSmall.stroke`. */
+ smStroke: '1.27px',
+ /** `circleCheckTable.xSmall.checkSize`. */
+ smCheckSize: '8px',
+ /** Derived: the Large check stroke, scaled by the check size (9 → 8). */
+ smCheckStroke: '1.2px',
+ /** Derived: the Large offset, scaled by the diameter (21.8 → 18). */
+ smCheckOffsetY: '0.83px',
+});
+
+export const circleCheckMotionStyles = stylex.create({
+ mark: {
+ transitionProperty: 'background-color, box-shadow',
+ // Core's indicators time their marks the same way.
+ transitionDuration: {
+ default: durationVars['--duration-fast'],
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+});
+
+export const circleCheckSizeStyles = stylex.create({
+ // The ring is an inset shadow, not a border. Engines snap a border to whole
+ // device pixels: 1.54 px becomes 1.33 px at 3×. A shadow keeps its exact
+ // width, antialiased like UIKit's symbol.
+ mdCircle: {
+ width: circleCheckConsts.mdDiameter,
+ height: circleCheckConsts.mdDiameter,
+ '--_circle-stroke': circleCheckConsts.mdStroke,
+ },
+ smCircle: {
+ width: circleCheckConsts.smDiameter,
+ height: circleCheckConsts.smDiameter,
+ '--_circle-stroke': circleCheckConsts.smStroke,
+ },
+ mdCheck: {
+ width: circleCheckConsts.mdCheckSize,
+ height: circleCheckConsts.mdCheckSize,
+ translate: `0 ${circleCheckConsts.mdCheckOffsetY}`,
+ },
+ smCheck: {
+ width: circleCheckConsts.smCheckSize,
+ height: circleCheckConsts.smCheckSize,
+ translate: `0 ${circleCheckConsts.smCheckOffsetY}`,
+ },
+ mdBar: {
+ width: circleCheckConsts.mdCheckSize,
+ height: circleCheckConsts.mdCheckStroke,
+ },
+ smBar: {
+ width: circleCheckConsts.smCheckSize,
+ height: circleCheckConsts.smCheckStroke,
+ },
+});
diff --git a/packages/lab/src/CircleCheckIndicator/circleCheck.table.ts b/packages/lab/src/CircleCheckIndicator/circleCheck.table.ts
new file mode 100644
index 0000000000..7a7220d2a9
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/circleCheck.table.ts
@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file circleCheck.table.ts
+ * @input UIKit measurements on the iOS 26.2 simulator
+ * @output Exports `circleCheckTable`: the circle's geometry at two text sizes
+ * (pt)
+ * @position Internal to CircleCheckIndicator; circleCheck.stylex.ts mirrors it
+ *
+ * The circle is a Lab component, so its measurements live beside it. Core's
+ * UIKit table holds only what Core's own components play.
+ */
+
+/**
+ * UIKit's multiple-selection circle, in a table row's edit mode
+ * (UITableViewCellEditControl) and a list's `.multiselect()` accessory. It is
+ * the SF Symbols `circle` and `checkmark.circle.fill` in a 25.67 pt control at
+ * the Large text size. It grows and thickens with the text size. Lengths are
+ * in pt.
+ */
+export const circleCheckTable = {
+ /** At the Large text size, the default. */
+ large: {
+ /**
+ * The circle's outer diameter.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, view frames and 3× pixels read (table edit mode and
+ * list multiselect, light and dark), Oct 24 2026
+ */
+ diameter: 21.8,
+ /**
+ * The empty circle's stroke; its interior is clear.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read, Oct 24 2026
+ */
+ stroke: 1.54,
+ /**
+ * The white checkmark's ink box in the filled circle, square.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read, Oct 24 2026
+ */
+ checkSize: 9,
+ /**
+ * The checkmark's stroke.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read, Oct 24 2026
+ */
+ checkStroke: 1.35,
+ /**
+ * How far below the circle's centre the checkmark's ink sits.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read, Oct 24 2026
+ */
+ checkOffsetY: 1,
+ },
+ /** At the xSmall text size, the smallest. */
+ xSmall: {
+ /**
+ * The circle's outer diameter.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, view frames and 3× pixels read at the xSmall text
+ * size, Oct 24 2026
+ */
+ diameter: 18,
+ /**
+ * The empty circle's stroke.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read at the xSmall text size, Oct 24 2026
+ */
+ stroke: 1.27,
+ /**
+ * The checkmark's ink box, square.
+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+ * iPhone 17 Pro, 3× pixels read at the xSmall text size, Oct 24 2026
+ */
+ checkSize: 8,
+ },
+} as const;
diff --git a/packages/lab/src/CircleCheckIndicator/circleCheck.test.tsx b/packages/lab/src/CircleCheckIndicator/circleCheck.test.tsx
new file mode 100644
index 0000000000..4b7ed57006
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/circleCheck.test.tsx
@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file circleCheck.test.tsx
+ * @input vitest, Testing Library, CircleCheckIndicator, its build-time
+ * mirror and its measured table (circleCheck.table.ts)
+ * @output Holds the mirror to the table: the multiselect circle's geometry
+ * with the two derived xSmall values. Asserts what the circle ships. Its
+ * colour change takes the theme's duration token on every pointer and is
+ * immediate under Reduce Motion. Its diameter and stroke are UIKit's at
+ * each size.
+ * @position Unit test beside circleCheck.stylex.ts. It renders the indicator
+ * alone: the stylesheet it reads is the one StyleX injects for this
+ * component.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {render} from '@testing-library/react';
+import {circleCheckTable} from './circleCheck.table';
+import {CircleCheckIndicator} from './CircleCheckIndicator';
+import {circleCheckConsts} from './circleCheck.stylex';
+
+const {large, xSmall} = circleCheckTable;
+
+/**
+ * Every declaration on `el`'s own classes, keyed by property, per enclosing
+ * media and supports conditions (outermost first, " | "-joined; null at the
+ * top level).
+ */
+function declarationsOf(el: Element): Map<string, Map<string | null, string>> {
+ const classes = el.className
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(name => `.${name}`);
+ const out = new Map<string, Map<string | null, string>>();
+ const walk = (rules: CSSRuleList, conditions: string[]) => {
+ for (const rule of Array.from(rules)) {
+ if (rule instanceof CSSMediaRule) {
+ walk(rule.cssRules, [...conditions, rule.media.mediaText]);
+ } else if (rule instanceof CSSSupportsRule) {
+ walk(rule.cssRules, [...conditions, rule.conditionText]);
+ } else if (
+ rule instanceof CSSStyleRule &&
+ classes.some(cls => rule.selectorText.startsWith(cls))
+ ) {
+ const media = conditions.length === 0 ? null : conditions.join(' | ');
+ for (const property of Array.from(rule.style)) {
+ const byMedia = out.get(property) ?? new Map();
+ byMedia.set(media, rule.style.getPropertyValue(property).trim());
+ out.set(property, byMedia);
+ }
+ }
+ }
+ };
+ for (const sheet of Array.from(document.styleSheets)) {
+ walk(sheet.cssRules, []);
+ }
+ return out;
+}
+
+/** A CSS length or duration as a number (px, or ms; `0s` is written so). */
+function toNumber(value: string | undefined): number {
+ if (value == null) {
+ return Number.NaN;
+ }
+ if (value.endsWith('ms') || value.endsWith('px')) {
+ return parseFloat(value);
+ }
+ return value.endsWith('s') ? parseFloat(value) * 1000 : parseFloat(value);
+}
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+/** The Reduce Motion key that Core's indicators use. */
+const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+
+describe('circleCheckConsts mirror the constants table', () => {
+ it('takes the circle at the Large text size for md', () => {
+ expect(toNumber(circleCheckConsts.mdDiameter)).toBe(large.diameter);
+ expect(toNumber(circleCheckConsts.mdStroke)).toBe(large.stroke);
+ expect(toNumber(circleCheckConsts.mdCheckSize)).toBe(large.checkSize);
+ expect(toNumber(circleCheckConsts.mdCheckStroke)).toBe(large.checkStroke);
+ expect(toNumber(circleCheckConsts.mdCheckOffsetY)).toBe(large.checkOffsetY);
+ });
+
+ it('takes the circle at the xSmall text size for sm, deriving what was not measured there', () => {
+ expect(toNumber(circleCheckConsts.smDiameter)).toBe(xSmall.diameter);
+ expect(toNumber(circleCheckConsts.smStroke)).toBe(xSmall.stroke);
+ expect(toNumber(circleCheckConsts.smCheckSize)).toBe(xSmall.checkSize);
+ expect(toNumber(circleCheckConsts.smCheckStroke)).toBe(
+ round2((large.checkStroke * xSmall.checkSize) / large.checkSize),
+ );
+ expect(toNumber(circleCheckConsts.smCheckOffsetY)).toBe(
+ round2((large.checkOffsetY * xSmall.diameter) / large.diameter),
+ );
+ });
+});
+
+describe('CircleCheckIndicator ships the table', () => {
+ function circle(size: 'sm' | 'md'): Element {
+ render(<CircleCheckIndicator state="checked" size={size} />);
+ const el = document.querySelector(
+ `.astryx-circle-check-indicator[data-size="${size}"]`,
+ );
+ if (el == null) {
+ throw new Error('no circle');
+ }
+ return el;
+ }
+
+ it('paints the touch press image only under a coarse pointer, so a held pen draws its press once', () => {
+ // A pen on a fine-pointer page draws the mouse `:active` fill; the press
+ // image as well would paint the press twice. CheckboxInput's own layer
+ // gates its image the same way.
+ const images = [
+ ...(declarationsOf(circle('md')).get('background-image') ??
+ new Map<string | null, string>()),
+ ];
+ expect(images.length).toBeGreaterThan(0);
+ for (const [media, value] of images) {
+ expect(media).toContain('(pointer: coarse)');
+ expect(value).toContain('--_indicator-press-image');
+ }
+ });
+
+ it("reads only the touch press image a CheckboxInput row hands down, so a mapped menu row's own press paints once", () => {
+ const images = [
+ ...(declarationsOf(circle('md')).get('background-image') ??
+ new Map<string | null, string>()),
+ ];
+ expect(images.length).toBeGreaterThan(0);
+ for (const [, value] of images) {
+ expect(value).not.toContain('--_press-paint-image');
+ }
+ });
+
+ it('fades over the theme’s duration on every pointer and changes at once under Reduce Motion', () => {
+ const durations = [
+ ...(declarationsOf(circle('md')).get('transition-duration') ??
+ new Map<string | null, string>()),
+ ];
+ // No pointer gets a timing of its own.
+ expect(durations.filter(([media]) => media?.includes('pointer'))).toEqual(
+ [],
+ );
+ const byMedia = new Map(durations);
+ expect(byMedia.get(null)).toMatch(/^var\(--duration-fast/);
+ expect(byMedia.get(REDUCED_MOTION)).toBe('0s');
+ });
+
+ it.each([
+ ['md', large],
+ ['sm', xSmall],
+ ] as const)(
+ 'draws the %s circle at UIKit’s diameter and stroke',
+ (size, row) => {
+ const declared = declarationsOf(circle(size));
+ expect(toNumber(declared.get('width')?.get(null))).toBe(row.diameter);
+ expect(toNumber(declared.get('height')?.get(null))).toBe(row.diameter);
+ // The ring is an inset shadow of this width (a border would snap to
+ // whole device pixels).
+ expect(toNumber(declared.get('--_circle-stroke')?.get(null))).toBe(
+ row.stroke,
+ );
+ },
+ );
+
+ it('draws the empty ring as an inset shadow of the stroke, and the filled circle without one', () => {
+ render(<CircleCheckIndicator state="unchecked" size="md" />);
+ const empty = document.querySelector(
+ '.astryx-circle-check-indicator:not([data-checked])',
+ );
+ if (empty == null) {
+ throw new Error('no empty circle');
+ }
+ expect(declarationsOf(empty).get('box-shadow')?.get(null)).toMatch(
+ /^inset 0 0 0 var\(--_circle-stroke\)/,
+ );
+ render(<CircleCheckIndicator state="checked" size="md" />);
+ const filled = document.querySelector(
+ '.astryx-circle-check-indicator[data-checked="checked"]',
+ );
+ if (filled == null) {
+ throw new Error('no filled circle');
+ }
+ expect(declarationsOf(filled).get('box-shadow')?.get(null)).toBe('none');
+ });
+});
diff --git a/packages/lab/src/CircleCheckIndicator/index.ts b/packages/lab/src/CircleCheckIndicator/index.ts
new file mode 100644
index 0000000000..1e73d0d31d
--- /dev/null
+++ b/packages/lab/src/CircleCheckIndicator/index.ts
@@ -0,0 +1,7 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CircleCheckIndicator component barrel export
+ */
+
+export {CircleCheckIndicator} from './CircleCheckIndicator';
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index 92178abd14..201a394c14 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -33,6 +33,10 @@ export {
type SelectableCardGroupItemProps,
} from './SelectableCardGroup';
+// CircleCheckIndicator — the iOS multiple-selection circle, a checkbox-family
+// indicator a theme can map to `checkbox`
+export {CircleCheckIndicator} from './CircleCheckIndicator';
+
// EmojiPicker — standalone searchable emoji panel
export {
EmojiPicker,