@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/Calendar/Calendar.tsx

@@ -61,12 +61,16 @@ import {
   plainDateWeekFieldName,
   DATE_FORMAT_WITH_WEEKDAY,
 } from '../utils/plainDate';
-import {plainDateFormatStandaloneMonthYear} from '../utils/plainDate';
+import {
+  plainDateFormatDayNumber,
+  plainDateFormatStandaloneMonthYear,
+} from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {getInitialFocusDate} from './getInitialFocusDate';
+import {getWeekdayHeaders} from './getWeekdayHeaderNames';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -104,8 +108,8 @@ import english from '../i18n/generated-english/Calendar/Calendar.generated';
 
 registerEnglishFallback(english);
 
-/** How a month navigation moves the focused day: by its row offset in days, or by whole months. */
-type NavigationUnit = 'days' | 'months';
+/** How a month navigation moves the focused day: by its row offset in days, or by whole months or years. */
+type NavigationUnit = 'days' | 'months' | 'years';
 
 /** Imperative handle for Calendar handleRef */
 export interface CalendarHandle {
@@ -518,13 +522,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
         !(minDateForKeys && plainDateIsBefore(pd, minDateForKeys)) &&
         !(maxDateForKeys && plainDateIsAfter(pd, maxDateForKeys));
       let targetPd: PlainDate;
-      if (unit === 'months') {
-        // A page targets the same day of the month a month away (clamped to
-        // that month's length). Past `min`/`max` nothing moves; a month with
-        // no enabled day is no destination either, the same as an arrow with
-        // no enabled day in its direction; a target disabled by a constraint
-        // lands on that month's first enabled day instead.
-        const candidate = plainDateAddMonths(currentPd, delta);
+      if (unit === 'months' || unit === 'years') {
+        // A page or a year step keeps the day of the month and clamps it to the
+        // target month's length. A month with no enabled day is no target, the
+        // same as for an arrow.
+        const candidate = plainDateAddMonths(
+          currentPd,
+          unit === 'years' ? delta * 12 : delta,
+        );
         if (!inRange(candidate)) {
           return;
         }
@@ -851,19 +856,15 @@ function MonthGrid({
   const year = month.year;
 
   // Use hooks for days generation and constraints
-  const {days, weeks, dayNames} = useCalendarDays({
+  const {days, weeks} = useCalendarDays({
     year,
     month: month.month,
     weekStartsOn,
     hasVariableRowCount,
   });
   const dayNameHeaders = useMemo(
-    () =>
-      dayNames.map((name, offset) => ({
-        dayOfWeek: ((weekStartsOn + offset) % 7) as DayOfWeek,
-        name,
-      })),
-    [dayNames, weekStartsOn],
+    () => getWeekdayHeaders(locale, weekStartsOn),
+    [locale, weekStartsOn],
   );
 
   const rangeAnchor = useMemo(
@@ -961,20 +962,27 @@ function MonthGrid({
     [getFocusedDate, onNavigateNext],
   );
 
-  // Handle PageUp/PageDown
-  const handlePageUp = useCallback(() => {
-    const focusedDate = getFocusedDate();
-    if (focusedDate) {
-      onNavigatePrevious?.(focusedDate, 1, 'months');
-    }
-  }, [getFocusedDate, onNavigatePrevious]);
+  // PageUp/PageDown move by a month, and with Shift by a year (APG date
+  // picker dialog).
+  const handlePageUp = useCallback(
+    (e: React.KeyboardEvent) => {
+      const focusedDate = getFocusedDate();
+      if (focusedDate) {
+        onNavigatePrevious?.(focusedDate, 1, e.shiftKey ? 'years' : 'months');
+      }
+    },
+    [getFocusedDate, onNavigatePrevious],
+  );
 
-  const handlePageDown = useCallback(() => {
-    const focusedDate = getFocusedDate();
-    if (focusedDate) {
-      onNavigateNext?.(focusedDate, 1, 'months');
-    }
-  }, [getFocusedDate, onNavigateNext]);
+  const handlePageDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      const focusedDate = getFocusedDate();
+      if (focusedDate) {
+        onNavigateNext?.(focusedDate, 1, e.shiftKey ? 'years' : 'months');
+      }
+    },
+    [getFocusedDate, onNavigateNext],
+  );
 
   // Grid focus navigation.
   //
@@ -1155,7 +1163,7 @@ function MonthGrid({
                 <div
                   role="rowheader"
                   {...stylex.props(monthGridStyles.weekNumber)}>
-                  {weekNum}
+                  {plainDateFormatDayNumber(weekNum, locale)}
                 </div>
               )}
               {week.map((day, dayIndex) => {
@@ -1422,7 +1430,7 @@ function DayCell({
             state.effectivelyDisabled && dayCellTheme.dayDisabled,
           ),
         )}>
-        {dayNumber}
+        {plainDateFormatDayNumber(dayNumber, locale)}
       </button>
     </div>
   );

package/src/Calendar/getWeekdayHeaderNames.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getWeekdayHeaderNames.ts
+ * @input Generated CLDR weekday header table and the shared date formatter
+ * @output Private resolver for one locale's weekday header row
+ * @position Package-internal pure utility for the Calendar grid and the
+ *   DateInput and DateTimeInput bottom sheets; not exported from the package
+ */
+
+import {characterCount} from '../utils/characters';
+import type {DayOfWeek} from '../utils/dateTypes';
+import {plainDateWeekdayNames} from '../utils/plainDate';
+import {
+  weekdayHeaderNamesByLocale,
+  type WeekdayHeaderNames,
+} from './weekdayHeaderNames.generated';
+
+const weekdayNamesByLocale: Readonly<Record<string, WeekdayHeaderNames>> =
+  weekdayHeaderNamesByLocale;
+const englishWeekdayNames = weekdayNamesByLocale.en;
+
+/** The longest abbreviated name a header row takes; the generator uses the same. */
+export const MAX_ABBREVIATED_HEADER_LENGTH = 4;
+
+function fitsHeader(names: ReadonlyArray<string>): boolean {
+  return names.every(
+    name => characterCount(name) <= MAX_ABBREVIATED_HEADER_LENGTH,
+  );
+}
+
+/**
+ * A language with no generated row keeps its own words. `Intl` has no CLDR
+ * short width, so names too long for the column fall to the narrow width.
+ */
+function sundayFirstNames(locale: string): ReadonlyArray<string> {
+  let parsed: Intl.Locale;
+  try {
+    parsed = new Intl.Locale(locale);
+  } catch {
+    return englishWeekdayNames;
+  }
+  const generated =
+    weekdayNamesByLocale[parsed.baseName] ??
+    weekdayNamesByLocale[parsed.language];
+  if (generated != null) {
+    return generated;
+  }
+  const abbreviated = plainDateWeekdayNames(parsed.baseName);
+  if (abbreviated == null) {
+    return englishWeekdayNames;
+  }
+  if (fitsHeader(abbreviated)) {
+    return abbreviated;
+  }
+  return (
+    plainDateWeekdayNames(parsed.baseName, 'narrow') ?? englishWeekdayNames
+  );
+}
+
+/** One weekday header cell: its day of week (a stable key, since narrow names repeat) and its name. */
+export interface WeekdayHeader {
+  dayOfWeek: DayOfWeek;
+  name: string;
+}
+
+/**
+ * The seven weekday headers for a locale, in column order for the week that
+ * starts on `weekStartsOn`. Unicode extensions are ignored.
+ */
+export function getWeekdayHeaders(
+  locale: string,
+  weekStartsOn: DayOfWeek = 0,
+): WeekdayHeader[] {
+  const names = sundayFirstNames(locale);
+  return Array.from({length: 7}, (_, offset) => {
+    const dayOfWeek = ((weekStartsOn + offset) % 7) as DayOfWeek;
+    return {dayOfWeek, name: names[dayOfWeek]};
+  });
+}
+
+/** The names alone, in the same order as `getWeekdayHeaders`. */
+export function getWeekdayHeaderNames(
+  locale: string,
+  weekStartsOn: DayOfWeek = 0,
+): string[] {
+  return getWeekdayHeaders(locale, weekStartsOn).map(header => header.name);
+}

package/src/Calendar/hooks/useCalendarDays.ts

@@ -22,7 +22,7 @@ import {
   plainDateAddDays,
 } from '../../utils/plainDate';
 import {useLocale} from '../../i18n';
-import {getStandaloneShortWeekdayNames} from '../getStandaloneShortWeekdayNames';
+import {getWeekdayHeaderNames} from '../getWeekdayHeaderNames';
 
 /**
  * Represents a single day in the calendar grid.
@@ -111,15 +111,10 @@ export function useCalendarDays(
     };
   }, [year, month, weekStartsOn, hasVariableRowCount]);
 
-  // Generated strings avoid Date anchors, so weekday headers cannot shift with
-  // the runtime timezone. Keep numeric indices as the rotation source of truth.
-  const dayNames = useMemo(() => {
-    const names = getStandaloneShortWeekdayNames(locale);
-    return Array.from(
-      {length: 7},
-      (_, index) => names[(index + weekStartsOn) % 7],
-    );
-  }, [locale, weekStartsOn]);
+  const dayNames = useMemo(
+    () => getWeekdayHeaderNames(locale, weekStartsOn),
+    [locale, weekStartsOn],
+  );
 
   // Generate days array
   const days = useMemo(() => {

package/src/Calendar/{standaloneShortWeekdayNames.generated.ts → weekdayHeaderNames.generated.ts}

@@ -5,7 +5,7 @@
  * Do not edit by hand. Run `pnpm generate:cldr-weekdays` instead.
  */
 
-export type StandaloneShortWeekdayNames = readonly [
+export type WeekdayHeaderNames = readonly [
   string,
   string,
   string,
@@ -15,36 +15,36 @@ export type StandaloneShortWeekdayNames = readonly [
   string,
 ];
 
-export const standaloneShortWeekdayNamesByLocale = {
+export const weekdayHeaderNamesByLocale = {
   af: ['So.', 'Ma.', 'Di.', 'Wo.', 'Do.', 'Vr.', 'Sa.'],
   ar: ['أحد', 'إثنين', 'ثلاثاء', 'أربعاء', 'خميس', 'جمعة', 'سبت'],
   'ar-SA': ['أحد', 'إثنين', 'ثلاثاء', 'أربعاء', 'خميس', 'جمعة', 'سبت'],
   ca: ['dg.', 'dl.', 'dt.', 'dc.', 'dj.', 'dv.', 'ds.'],
   cs: ['ne', 'po', 'út', 'st', 'čt', 'pá', 'so'],
   da: ['sø.', 'ma.', 'ti.', 'on.', 'to.', 'fr.', 'lø.'],
-  de: ['So.', 'Mo.', 'Di.', 'Mi.', 'Do.', 'Fr.', 'Sa.'],
-  el: ['Κυ', 'Δε', 'Τρ', 'Τε', 'Πέ', 'Πα', 'Σά'],
-  en: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
-  es: ['DO', 'LU', 'MA', 'MI', 'JU', 'VI', 'SA'],
+  de: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
+  el: ['Κυρ', 'Δευ', 'Τρί', 'Τετ', 'Πέμ', 'Παρ', 'Σάβ'],
+  en: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
+  es: ['dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb'],
   fi: ['su', 'ma', 'ti', 'ke', 'to', 'pe', 'la'],
-  fr: ['di', 'lu', 'ma', 'me', 'je', 've', 'sa'],
+  fr: ['dim.', 'lun.', 'mar.', 'mer.', 'jeu.', 'ven.', 'sam.'],
   he: ['א׳', 'ב׳', 'ג׳', 'ד׳', 'ה׳', 'ו׳', 'ש׳'],
   hu: ['V', 'H', 'K', 'Sze', 'Cs', 'P', 'Szo'],
   it: ['dom', 'lun', 'mar', 'mer', 'gio', 'ven', 'sab'],
   ja: ['日', '月', '火', '水', '木', '金', '土'],
   ko: ['일', '월', '화', '수', '목', '금', '토'],
   nl: ['zo', 'ma', 'di', 'wo', 'do', 'vr', 'za'],
-  no: ['sø.', 'ma.', 'ti.', 'on.', 'to.', 'fr.', 'lø.'],
+  no: ['søn.', 'man.', 'tir.', 'ons.', 'tor.', 'fre.', 'lør.'],
   pl: ['nie', 'pon', 'wto', 'śro', 'czw', 'pią', 'sob'],
   pt: ['dom.', 'seg.', 'ter.', 'qua.', 'qui.', 'sex.', 'sáb.'],
   'pt-PT': ['dom.', 'seg.', 'ter.', 'qua.', 'qui.', 'sex.', 'sáb.'],
-  ro: ['du.', 'lu.', 'ma.', 'mi.', 'joi', 'vi.', 'sâ.'],
+  ro: ['dum.', 'lun.', 'mar.', 'mie.', 'joi', 'vin.', 'sâm.'],
   ru: ['вс', 'пн', 'вт', 'ср', 'чт', 'пт', 'сб'],
-  sr: ['не', 'по', 'ут', 'ср', 'че', 'пе', 'су'],
-  sv: ['sö', 'må', 'ti', 'on', 'to', 'fr', 'lö'],
-  tr: ['Pa', 'Pt', 'Sa', 'Ça', 'Pe', 'Cu', 'Ct'],
+  sr: ['нед', 'пон', 'уто', 'сре', 'чет', 'пет', 'суб'],
+  sv: ['sön', 'mån', 'tis', 'ons', 'tors', 'fre', 'lör'],
+  tr: ['Paz', 'Pzt', 'Sal', 'Çar', 'Per', 'Cum', 'Cmt'],
   uk: ['нд', 'пн', 'вт', 'ср', 'чт', 'пт', 'сб'],
   vi: ['CN', 'T2', 'T3', 'T4', 'T5', 'T6', 'T7'],
   zh: ['周日', '周一', '周二', '周三', '周四', '周五', '周六'],
-  'zh-TW': ['日', '一', '二', '三', '四', '五', '六'],
-} as const satisfies Readonly<Record<string, StandaloneShortWeekdayNames>>;
+  'zh-TW': ['週日', '週一', '週二', '週三', '週四', '週五', '週六'],
+} as const satisfies Readonly<Record<string, WeekdayHeaderNames>>;

package/src/Carousel/Carousel.tsx

@@ -369,6 +369,7 @@ export function Carousel({
     lightDismiss: false,
   });
 
+  // Syncs the layer with `hasButtons`.
   useEffect(() => {
     if (hasButtons) {
       layer.show();

package/src/Chat/ChatComposerInput.tsx

@@ -68,6 +68,7 @@ import {
 import {Badge, type BadgeProps} from '../Badge';
 import {useChatComposerContext} from './ChatContext';
 import {themeProps} from '../utils/themeProps';
+import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import type {EnterKeyHint} from '../Field/textEntryTraits';
 import {
   registerEnglishFallback,
@@ -390,13 +391,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
   } = props;
   // Keep focus/blur observation available, but do not forward activation or
   // editing callbacks from the disabled root (including capture handlers).
-  const rootProps = isDisabled
-    ? Object.fromEntries(
-        Object.entries(rest).filter(
-          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
-        ),
-      )
-    : rest;
+  const rootProps = withholdCallerHandlers(rest, isDisabled);
   const label = labelFromProps ?? t('@astryx.chat.composerInput.label');
   const placeholder =
     placeholderFromProps ??
@@ -529,6 +524,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     };
   }, [inputControlRef, focusEditableAtEnd]);
 
+  // Syncs the contentEditable DOM with the controlled `value`.
   useEffect(() => {
     if (controlledValue === undefined || !editableRef.current) {
       return;
@@ -650,6 +646,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
         }
       : triggerMenu.ariaProps;
 
+  // Syncs the trigger menu's pending searches with `isDisabled`.
   useEffect(() => {
     if (isDisabled && triggerMenu.state.isActive) {
       // Reset also cancels pending searches, so late results cannot reopen

package/src/Chat/ChatMessageList.tsx

@@ -265,7 +265,8 @@ export function ChatMessageList({
     children !== false &&
     !(Array.isArray(children) && children.length === 0);
 
-  // IntersectionObserver for scroll-to-top infinite scroll
+  // Syncs an IntersectionObserver on the top sentinel with `scrollToTopAction`.
+  // The action runs when the sentinel comes into view.
   useEffect(() => {
     const scrollContainer = layoutContext?.scrollContainerRef?.current;
     if (!scrollToTopAction || !sentinelRef.current) {

package/src/Chat/useChatDictation.ts

@@ -395,6 +395,7 @@ export function useChatDictation(
     [userTransform],
   );
 
+  // Releases the audio analyser and the animation frame on unmount.
   useEffect(() => {
     return () => {
       analyserRef.current?.cleanup();

package/src/Chat/useChatNewMessages.ts

@@ -121,7 +121,7 @@ export function useChatNewMessages({
     [attach, detach],
   );
 
-  // Cleanup on unmount
+  // Releases the new-message tracking on unmount.
   useEffect(() => {
     return () => detach();
   }, [detach]);

package/src/Chat/useChatStreamScroll.ts

@@ -358,6 +358,8 @@ export function useChatStreamScroll({
 
   // --- Event listeners ---
 
+  // Syncs scroll and scrollend listeners on the stream container with
+  // `enabled`.
   useEffect(() => {
     const el = scrollRef.current;
     if (!el || !enabled) {

package/src/Chat/useSpeechRecognition.ts

@@ -317,6 +317,8 @@ export function useSpeechRecognition(
     transformTranscript,
   };
 
+  // Releases speech recognition, the audio analyser and the animation frame on
+  // unmount.
   useEffect(() => {
     return () => {
       recognitionRef.current?.abort();

package/src/Chat/useTriggerMenu.tsx

@@ -452,7 +452,7 @@ export function useTriggerMenu(
   });
   const {show: showPopover, hide: hidePopover} = popover;
 
-  // Cleanup on unmount
+  // Releases the search timer and the anchor span on unmount.
   useEffect(() => {
     return () => {
       if (searchTimeoutRef.current) {

package/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,
+      },
+    ],
   },
 };
 

package/src/CheckboxInput/CheckboxInput.tsx

@@ -46,11 +46,11 @@ 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';
 import {usePressFeedback} from '../hooks/usePressFeedback';
-import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useIndicator} from '../Indicator/useIndicator';
 import {themeProps} from '../utils/themeProps';
 
@@ -63,6 +63,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 +83,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 +105,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 +138,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,
-          },
       },
     },
   },
@@ -352,10 +377,6 @@ export function CheckboxInput({
   const id = idProp || generatedId;
   const descriptionID = useId();
   const statusMessageID = useId();
-  // Announce the effective required state (form default included) while the
-  // native `required` stays bound to the explicit `isRequired` so a layout
-  // default never switches on browser validation.
-  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -450,6 +471,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.
@@ -484,7 +506,8 @@ export function CheckboxInput({
             onClick={isDisabled ? undefined : rest.onClick}
             readOnly={isReadOnly}
             required={isRequired}
-            aria-required={isEffectivelyRequired ? 'true' : undefined}
+            // A form's required default sets nothing here: an unchecked box is an answer.
+            aria-required={isRequired ? 'true' : undefined}
             onChange={e => {
               if (isDisabled || isBusy || isReadOnly) {
                 // Activation clears the native mixed state; React restores

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -127,6 +127,20 @@ export const docs = {
       type: 'string',
       description: 'Description text displayed below the label.',
     },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description:
+        'Whether the group is optional. Shows the optional indicator after the group label, unless a surrounding FormLayout already makes fields optional by default.',
+      default: 'false',
+    },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description:
+        'Whether the group needs at least one checked box. Shows the required indicator after the group label by the same rules as every input field. While no box is checked, the browser blocks submit and moves focus to the first box that is neither disabled nor read-only, with its own message. A disabled or read-only group requires nothing. Show your own error text through status. Mutually exclusive with isOptional.',
+      default: 'false',
+    },
     {
       name: 'density',
       type: "'compact' | 'balanced' | 'spacious'",