Skip to content

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

TypeScript

feat(core): a first-party indicator can paint its own press (#9716)

Christopher Chedeaua814877379a5
diff --git a/.changeset/indicator-own-press.md b/.changeset/indicator-own-press.md
new file mode 100644
index 0000000000..80e3852174
--- /dev/null
+++ b/.changeset/indicator-own-press.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] CheckboxInput can leave its rounded-square press layer off over a first-party replacement indicator that paints its own press. Indicators in this release are unchanged.
+
+@vjeux
diff --git a/docs/specs/components/CheckboxInput/CheckboxInput.spec.md b/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
index 2c3be8f40b..8f22d17de1 100644
--- a/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
+++ b/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
@@ -52,7 +52,7 @@ system_specs: [spec:AST-021, spec:AST-085, spec:AST-086]
| Area | Contract |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public contract | `CheckboxInput` is a controlled native checkbox with a required `label` and `value`; it supports synchronous and transition-backed change handlers, loading, disabled, disabled-reason, read-only, validation, sizing, and field content. |
-| Behavior | The native input owns role, state, focus, form participation, and activation. A replaceable CheckboxIndicator owns the visible box while CheckboxInput owns its focus ring and pressed overlay. |
+| Behavior | The native input owns role, state, focus, form participation, and activation. A replaceable CheckboxIndicator owns the visible box while CheckboxInput owns its focus ring and pressed overlay, except where a first-party indicator paints its own press (AV1). |
| End-user impact | People can identify and operate available choices, review inert values as read-only, discover disabled reasons from the keyboard, and perceive busy, validation, focus, and pressed states. |
| Builder impact | None. Builders control the value and may use `onChange`, `changeAction`, or both; the meaning of omitting both stays an open question (OQ1). |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A handlerless checkbox declares no read-only state, a mixed value can lose its native mixed state on activation, and caller key handlers run while disabled; all are listed under Current-state impact. |
@@ -79,7 +79,7 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
- Native checkbox role, checked/mixed state, label, description/status relationships, focus, activation, availability, read-only state, required/invalid/busy state, and form participation.
-- Composition of the resolved checkbox indicator, owner-painted focus ring and pressed overlay, disabled-reason tooltip, field label, description, and detached status.
+- Composition of the resolved checkbox indicator, owner-painted focus ring and pressed overlay (except where a first-party indicator paints its own press; AV1), disabled-reason tooltip, field label, description, and detached status.
- Ordering between `onChange`, `preventDefault`, optimistic pending state, and `changeAction`.
**Does not own / non-goals**
@@ -115,13 +115,13 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR8 | Caller DOM props MUST reach the input, while component-owned type, checked, disabled, read-only, required, busy, invalid, description, ref, and styling values retain precedence. | `architecture:public-component-api/INV5–INV8`; component tests |
| FR9 | The outer field MUST retain `checkbox-input`, the label MUST retain `checkbox-label`, and the built-in CheckboxIndicator path MUST retain its canonical targets. Replacement indicators are not required to accept target classes. | source/docs target inventory; replacement component tests; `architecture:component-theming-surface/INV4–INV8,INV12` |
| FR10 | Keyboard/programmatic focus on the hidden native input MUST paint the shared focus-visible outline on the resolved indicator element, including a replacement indicator that forwards no props. | `architecture:interaction-modality/INV1–INV3`; component tests |
-| FR11 | CheckboxInput applies `design:user-states` DR1 and DR2 for the pressed overlay, painting it on the indicator while the row is pressed. | `design:user-states/DR1–DR5` |
+| FR11 | CheckboxInput applies `design:user-states` DR1 and DR2 for the pressed overlay, painting it on the indicator while the row is pressed, except over an indicator that paints its own press (AV1). | `design:user-states/DR1–DR5` |
| FR12 | `sm` and `md` MUST keep the native input, indicator, focus paint, and row geometry aligned; field `width` MUST size the whole field rather than only the input. | shipped source, tests, and stories |
| FR13 | With neither `onChange` nor `changeAction`, activation changes nothing the caller can observe. Implementation gap: the checkbox declares no read-only or unavailable state; its meaning is OQ1 (Current-state impact). | shared checkbox known-failure record |
### Allowed variation
-- **AV1 — Indicator replacement.** A theme may replace the named checkbox indicator if it preserves the Indicator prop and decorative ownership contracts; CheckboxInput still paints focus and pressed feedback on the resolved root.
+- **AV1 — Indicator replacement.** A theme may replace the named checkbox indicator if it preserves the Indicator prop and decorative ownership contracts; CheckboxInput still paints focus and pressed feedback on the resolved root. The one exception: a first-party replacement indicator may paint its own press from the row's hover and press (an internal marker; not public API), while CheckboxInput still paints focus.
- **AV2 — Theme paint.** Canonical component targets and semantic tokens may change admitted visual properties without changing native semantics, state precedence, or interaction ownership.
- **AV3 — Caller field content.** Label, description, status text, icon/content, and width may vary within their public types.
@@ -187,7 +187,7 @@ The consumer record includes composed targets owned by CheckboxIndicator, FieldL
| FR8 | `CheckboxInput.test.tsx` passthrough, id, ref, and rest-precedence cases | Caller `id`, `data-*`, ref | A caller prop overriding `checked`, `disabled`, or `type` fails. | `audit:CheckboxInput/api` |
| FR9 | `CheckboxInput.test.tsx` label-target case; `themingTargets.test.ts` | Label; built-in indicator | A missing label target, or a rendered class absent from the documented targets, fails. Evidence gap: no test asserts the root `checkbox-input` target. | `audit:CheckboxInput/theming` |
| FR10, AR3 | `CheckboxInput.test.tsx` focus-ring ownership suite | Built-in and prop-dropping replacement indicators; blur | A ring on the wrong element, or none, fails. | `audit:CheckboxInput/a11y` |
-| FR11 | `CheckboxInput.test.tsx` pressed-state suite | Enabled press; disabled; touch fade | A missing overlay, or one on a disabled box, fails. | `audit:CheckboxInput/visual` |
+| FR11 | `CheckboxInput.test.tsx` pressed-state suite and its suite for an indicator that paints its own press | Enabled press; disabled; touch fade | A missing overlay, or one on a disabled box, fails. | `audit:CheckboxInput/visual` |
| FR12, AR5 | `CheckboxInput.test.tsx` coarse-pointer, RTL, and forced-colors suites | `sm`, `md`; RTL; forced colors | A misplaced hit target or a mark lost in forced colors fails. Evidence gap: no test asserts field `width`. | `audit:CheckboxInput/layout` |
| ORD1–ORD4, PR1 | ORD4 is covered by the FR8 rest-precedence case and ORD3 by the shared accessibility suite's disabled, disabled-reason, and read-only states. Evidence gap: no test asserts the optimistic value between `value` and the indicator (ORD1), the `preventDefault` check before `changeAction` (ORD2), or the absence of global listeners | — | — | `audit:CheckboxInput/behavior` |
diff --git a/packages/core/package.json b/packages/core/package.json
index 4f14c57f6b..914c879912 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -824,6 +824,11 @@
"types": "./dist/Markdown/remark.d.ts",
"default": "./dist/Markdown/remark.js"
},
+ "./internal/indicatorPress.stylex": {
+ "source": "./src/internal/indicatorPress.stylex.ts",
+ "types": "./dist/internal/indicatorPress.stylex.d.ts",
+ "default": "./dist/internal/indicatorPress.stylex.js"
+ },
"./internal/touch": {
"source": "./src/internal/touch.ts",
"types": "./dist/internal/touch.d.ts",
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 67108fc97b..7faefaa61a 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -151,6 +151,15 @@ export const docs = {
},
{className: 'astryx-checkbox-label'},
],
+ vars: [
+ {
+ name: '--_indicator-press-image',
+ description:
+ "The row's touch press image, handed down to a first-party indicator that paints its own press. Set from the press paint only while the row itself is pressed; only this row declares it.",
+ default: 'none',
+ private: true,
+ },
+ ],
},
usage: {
accessibility: [
@@ -390,6 +399,15 @@ export const docsZh = {
},
{className: 'astryx-checkbox-label'},
],
+ vars: [
+ {
+ name: '--_indicator-press-image',
+ description:
+ '复选框行的触摸按下图像,传递给自行绘制按下效果的第一方指示器。仅在该行自身被按下时根据按下涂层设置,只有该行声明它。',
+ default: 'none',
+ private: true,
+ },
+ ],
},
};
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
index 73b712af8c..28eaecd9ba 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
@@ -12,6 +12,7 @@
* SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
*/
+import {readFileSync} from 'node:fs';
import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
@@ -19,8 +20,11 @@ import {
hasPressedArm,
hasReleaseFade,
readsPressStrength,
+ rulesDeclaredFor,
+ rulesWithSelector,
} from '../__tests__/pressState';
import {CheckboxInput} from './CheckboxInput';
+import * as publicMarkers from '../Indicator/indicator.markers.stylex';
import {Theme} from '../theme/Theme';
import {defineTheme} from '../theme/defineTheme';
import {getForcedColorsRules} from '../__tests__/forcedColors';
@@ -924,3 +928,83 @@ describe('pressed state', () => {
expect(readsPressStrength(wrapper)).toBe(true);
});
});
+
+describe('an indicator that paints its own press', () => {
+ it('keeps its marker internal: no public entry exports it, and the API report has no row', () => {
+ expect(Object.keys(publicMarkers)).not.toContain('indicatorPressScope');
+ const report = readFileSync('packages/core/api-report.md', 'utf8');
+ expect(report).not.toContain('indicatorPressScope');
+ });
+
+ const partsOf = (container: HTMLElement) => {
+ const box = container.querySelector('.astryx-checkbox-indicator');
+ const wrapper = box?.parentElement?.parentElement;
+ const row = wrapper?.parentElement;
+ if (wrapper == null || row == null) {
+ throw new Error('the checkbox has no indicator wrapper or row');
+ }
+ return {wrapper, row};
+ };
+
+ it('hands its touch press image down only in its own press states, as a private property only the row declares', () => {
+ const {container} = render(
+ <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+ );
+ const {row} = partsOf(container);
+ const rules = rulesDeclaredFor(row).filter(rule =>
+ rule.includes('--_indicator-press-image'),
+ );
+ const handing = rules.filter(rule =>
+ /--_indicator-press-image:\s*var\(--_press-paint-image\)/.test(rule),
+ );
+ expect(handing.length).toBeGreaterThan(0);
+ // A pressed ancestor row hands nothing down: only the row's own states do.
+ expect(
+ handing.every(rule => /\[data-astryx-press="(on|fading)"\]/.test(rule)),
+ ).toBe(true);
+ // No default of its own: a layered stylesheet ranks a default above arms.
+ expect(
+ rules.every(rule => /\[data-astryx-press="(on|fading)"\]/.test(rule)),
+ ).toBe(true);
+ });
+
+ it('hands nothing down from a disabled checkbox', () => {
+ const {container} = render(
+ <CheckboxInput
+ label="Unavailable"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ const {row} = partsOf(container);
+ expect(
+ rulesDeclaredFor(row).some(rule =>
+ rule.includes('--_indicator-press-image'),
+ ),
+ ).toBe(false);
+ });
+
+ it('leaves its rounded-square press layer off over an indicator marked as painting its own press', () => {
+ const {container} = render(
+ <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+ );
+ const {wrapper} = partsOf(container);
+ // The layer reads the marked indicator as a descendant (`:has()`).
+ const off = rulesWithSelector(wrapper, ':has(');
+ expect(
+ off.some(
+ rule => rule.includes('::after') && /content:\s*none/.test(rule),
+ ),
+ ).toBe(true);
+ // Without such an indicator the layer stays on.
+ expect(
+ rulesDeclaredFor(wrapper).some(
+ rule =>
+ rule.includes('::after') &&
+ !rule.includes(':has(') &&
+ /content:\s*("")/.test(rule),
+ ),
+ ).toBe(true);
+ });
+});
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index e8d527650c..86f58346c5 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx
@@ -46,6 +46,7 @@ import {useTooltip} from '../Tooltip/useTooltip';
import {mergeProps} from '../utils/mergeProps';
import {rtlStyles} from '../utils/rtlStyles';
import {indicatorScope} from '../Indicator/indicator.markers.stylex';
+import {indicatorPressScope} from '../internal/indicatorPress.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
@@ -63,6 +64,11 @@ import english from '../i18n/generated-english/CheckboxInput/CheckboxInput.gener
registerEnglishFallback(english);
+/** Written by the touch press controller while the row is pressed. */
+const PRESSED_ON = '[data-astryx-press="on"]';
+/** Written by the touch press controller for the press's release. */
+const PRESSED_FADING = '[data-astryx-press="fading"]';
+
// The touch press's paint, declared by the shared overlay styles on the
// element the controller writes to (`pressedAlpha`) at the press's strength,
// 1 while on and 1 → 0 over the release, and inherited resolved by the layer
@@ -78,6 +84,20 @@ const styles = stylex.create({
containerLabelHidden: {
gap: 0,
},
+ // An indicator in another package may not name this row's private press
+ // attribute. So the row hands its touch press image down to an indicator
+ // that paints its own press, but only in its own press states. A pressed
+ // ancestor row reaches it no more than it reaches the built-in box. The
+ // property has no default: a layered stylesheet ranks a default above the
+ // arms. Only this row declares it. A menu item paints its own press, so a
+ // mapped indicator there paints none.
+ indicatorPressImage: {
+ '--_indicator-press-image': {
+ default: null,
+ [PRESSED_ON]: 'var(--_press-paint-image)',
+ [PRESSED_FADING]: 'var(--_press-paint-image)',
+ },
+ },
checkboxWrapper: {
position: 'relative',
display: 'flex',
@@ -86,15 +106,22 @@ const styles = stylex.create({
flexShrink: 0,
isolation: 'isolate',
},
- // The owner paints this layer over the resolved indicator, so a theme
- // replacement cannot accidentally drop the component's pressed contract.
+ // The owner paints this layer over the resolved indicator, so a plain theme
+ // replacement keeps the pressed feedback. An indicator with
+ // `indicatorPressScope` paints its own press from what the row hands down,
+ // so this layer stays off over it.
// Two pointers, two press models (see interactionOverlay.stylex.ts): a
// mouse keeps `:active`; under a coarse pointer that arm is dropped and the
// touch press controller writes `data-astryx-press` on the row, which this layer
// reads off the same scope marker as the hover tint.
indicatorPressOverlay: {
'::after': {
- content: '""',
+ // `when.descendant` takes a pseudo-class; `:is(*)` matches any marked
+ // indicator.
+ content: {
+ default: '""',
+ [stylex.when.descendant(':is(*)', indicatorPressScope)]: 'none',
+ },
position: 'absolute',
inset: 0,
borderRadius: radiusVars['--radius-inner'],
@@ -112,15 +139,14 @@ const styles = stylex.create({
// what moves. Coarse pointers only, like the drop above.
backgroundImage: {
default: null,
- [stylex.when.ancestor('[data-astryx-press="on"]', indicatorScope)]: {
+ [stylex.when.ancestor(PRESSED_ON, indicatorScope)]: {
+ default: null,
+ '@media (pointer: coarse)': pressedOverlayImage,
+ },
+ [stylex.when.ancestor(PRESSED_FADING, indicatorScope)]: {
default: null,
'@media (pointer: coarse)': pressedOverlayImage,
},
- [stylex.when.ancestor('[data-astryx-press="fading"]', indicatorScope)]:
- {
- default: null,
- '@media (pointer: coarse)': pressedOverlayImage,
- },
},
},
},
@@ -450,6 +476,7 @@ export function CheckboxInput({
// Hover and focus reach the checkbox visual through this ancestor
// marker rather than props, so the whole row drives it.
!isDisabled && indicatorScope,
+ !isDisabled && styles.indicatorPressImage,
// The touch press's strength and release live on the row the
// controller writes to; the layer over the checkbox box inherits
// and paints it.
diff --git a/packages/core/src/__tests__/publicStyleXNamespaces.test.ts b/packages/core/src/__tests__/publicStyleXNamespaces.test.ts
index dca496a44c..4faf6c3cc4 100644
--- a/packages/core/src/__tests__/publicStyleXNamespaces.test.ts
+++ b/packages/core/src/__tests__/publicStyleXNamespaces.test.ts
@@ -30,6 +30,7 @@ import * as selectorPresentation from '@astryxdesign/core/Selector/selectorPrese
import * as stack from '@astryxdesign/core/Stack/stack.stylex';
import * as stackItem from '@astryxdesign/core/Stack/stackItem.stylex';
import * as text from '@astryxdesign/core/Text/text.stylex';
+import * as indicatorPress from '@astryxdesign/core/internal/indicatorPress.stylex';
import * as dataTokens from '@astryxdesign/core/theme/dataTokens.stylex';
import * as tokens from '@astryxdesign/core/theme/tokens.stylex';
import * as focusOutline from '@astryxdesign/core/utils/focusOutline.stylex';
@@ -136,7 +137,7 @@ type StylexPropsArgument = stylex.StyleXArray<
type NoKeys<Namespaces> = {[Name in keyof Namespaces]: never};
/**
- * The public `.stylex` subpaths, each with the exports that `stylex.create`
+ * The exported `.stylex` subpaths, each with the exports that `stylex.create`
* made. A subpath with no style namespace exports only variables, constants,
* a marker or style builders.
*/
@@ -188,6 +189,7 @@ const styleNamespacesBySubpath = {
'weightStyles',
'wordBreakStyles',
],
+ './internal/indicatorPress.stylex': [],
'./theme/dataTokens.stylex': [],
'./theme/tokens.stylex': [],
'./utils/focusOutline.stylex': ['focusOutlineStyles'],
@@ -211,6 +213,7 @@ const modulesBySubpath: Readonly<
'./Stack/stack.stylex': stack,
'./Stack/stackItem.stylex': stackItem,
'./Text/text.stylex': text,
+ './internal/indicatorPress.stylex': indicatorPress,
'./theme/dataTokens.stylex': dataTokens,
'./theme/tokens.stylex': tokens,
'./utils/focusOutline.stylex': focusOutline,
diff --git a/packages/core/src/internal/indicatorPress.stylex.ts b/packages/core/src/internal/indicatorPress.stylex.ts
new file mode 100644
index 0000000000..2b39050f09
--- /dev/null
+++ b/packages/core/src/internal/indicatorPress.stylex.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file indicatorPress.stylex.ts
+ * @input Uses StyleX
+ * @output Exports `indicatorPressScope`, the marker of a first-party
+ * indicator that paints its own press
+ * @position Internal entry for Astryx's own replacement indicators;
+ * CheckboxInput reads it
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Marks a first-party replacement indicator that paints its own press, for
+ * a shape that CheckboxInput's rounded-square press layer would tint past,
+ * such as a circle. CheckboxInput leaves that layer off over an indicator
+ * with this marker.
+ *
+ * @internal Not public API: the touch press reaches the indicator through a
+ * private property.
+ */
+export const indicatorPressScope: ReturnType<typeof stylex.defineMarker> =
+ stylex.defineMarker();
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index 0bd9f307dc..d8a0cccef2 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -351,6 +351,9 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
// by whatever paints it. A theme sets `--color-overlay-pressed`, not this.
'--_press-paint',
'--_press-paint-image',
+ // A checkbox row's touch press image, which an indicator that paints its
+ // own press inherits. The row writes it from the press paint above.
+ '--_indicator-press-image',
'--_input-clear-hit-content',
'--_power-search-sheet-hit-content',
// Placement and swipe lifecycle values are private Toast behavior. A theme
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index d9d8dabb44..dca2c64c1f 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -237,6 +237,7 @@ const FILE_MODULE_SUBPATH_EXPORTS = [
// Internal entries for Astryx's own packages: undocumented, outside the
// public API, and allowed by lint only in Core and Lab
// (architecture:react-component-runtime INV13).
+ 'internal/indicatorPress.stylex',
'internal/touch',
'internal/touch-sheet',
];