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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/docs/specs/components/CheckboxInput/CheckboxInput.spec.md b/docs/specs/components/CheckboxInput/CheckboxInput.spec.mdindex 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.jsonindex 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.mjsindex 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.tsxindex 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.tsxindex 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.generregisterEnglishFallback(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.tsindex 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/selectorPreseimport * 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.tsnew file mode 100644index 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.tsindex 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 themediff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex 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',];