@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/CheckboxInput/CheckboxInput.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file CheckboxInput.tsx
- * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
+ * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip,
+ *   CheckboxRowPressContext (a row around the checkbox that owns its press)
  * @output Exports CheckboxInput component, CheckboxInputProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxInput.test.tsx
  *
@@ -17,6 +18,7 @@
  */
 
 import {
+  use,
   useId,
   useCallback,
   useOptimistic,
@@ -24,6 +26,8 @@ import {
   useTransition,
   type ChangeEvent,
   type FocusEvent,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -55,11 +59,14 @@ import {useIndicator} from '../Indicator/useIndicator';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useTouchHitArea} from '../utils/touchHitArea';
+import {touchHitAreaStyles} from '../utils/touchHitArea.stylex';
 import {
   registerEnglishFallback,
   useComponentTranslator,
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/CheckboxInput/CheckboxInput.generated';
+import {CheckboxRowPressContext} from './CheckboxRowPressContext';
 
 registerEnglishFallback(english);
 
@@ -83,10 +90,14 @@ const styles = stylex.create({
   containerLabelHidden: {
     gap: 0,
   },
+  // Under a coarse pointer the row contains its hit band.
+  hitAreaHost: {
+    position: {default: null, '@media (pointer: coarse)': 'relative'},
+  },
   // 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
+  // outer row hands down nothing, as for 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.
@@ -97,6 +108,12 @@ const styles = stylex.create({
       [PRESSED_FADING]: 'var(--_press-paint-image)',
     },
   },
+  // Under a row that owns the press (CheckboxRowPressContext), this row is
+  // never pressed. So it hands down that row's press paint, which the
+  // built-in box reads too.
+  indicatorRowPressImage: {
+    '--_indicator-press-image': 'var(--_checkbox-row-press-paint, none)',
+  },
   checkboxWrapper: {
     position: 'relative',
     display: 'flex',
@@ -108,11 +125,12 @@ const styles = stylex.create({
   // 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.
+  // so this layer stays off over it. A mouse keeps `:active` (see
+  // interactionOverlay.stylex.ts). Under a coarse pointer that arm is dropped.
+  // The touch press controller then writes the press attribute on the row.
+  // This layer reads it off the scope marker, as the hover tint does. Under a
+  // row that owns the press (CheckboxRowPressContext), the row's own checkbox
+  // paints that row's press paint instead (indicatorRowPressOverlay).
   indicatorPressOverlay: {
     '::after': {
       // `when.descendant` takes a pseudo-class; `:is(*)` matches any marked
@@ -149,6 +167,15 @@ const styles = stylex.create({
       },
     },
   },
+  // The row's own checkbox when its row owns the press
+  // (CheckboxRowPressContext). It paints only the paint that row declares
+  // (`--_checkbox-row-press-paint`). No outer row, card or fine pointer
+  // reaches it.
+  indicatorRowPressOverlay: {
+    '::after': {
+      backgroundImage: 'var(--_checkbox-row-press-paint, none)',
+    },
+  },
   // Holds only the indicator, so the focus ring has one unambiguous target.
   // `display: contents` adds no box of its own — the indicator keeps whatever
   // layout relationship it already had with the wrapper.
@@ -373,6 +400,13 @@ export function CheckboxInput({
   // The row is the pressable: the overlay's pressed arm reads the row's
   // scope marker, the way the indicator's hover tint does.
   const pressable = usePressFeedback();
+  // A row around the checkbox that answers a press anywhere on it (a
+  // CheckboxListItem) owns the touch press instead. The checkbox then carries
+  // no press marker of its own. So the controller's innermost-wins rule finds
+  // the row for a finger on the label, the description or the box. The
+  // overlay below paints that row's press.
+  const isRowPressSurface = use(CheckboxRowPressContext);
+  const ownsPress = !isDisabled && !isRowPressSurface;
   const generatedId = useId();
   const id = idProp || generatedId;
   const descriptionID = useId();
@@ -407,6 +441,55 @@ export function CheckboxInput({
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), indicatorRef);
   const {focusProps} = useIndicatorFocusRing(indicatorRef);
 
+  // Under a coarse pointer a labelled checkbox's row grows toward 44 px
+  // through an invisible band, and nothing changes size. A label-hidden
+  // checkbox is a marker in another component's row, which keeps its target.
+  const hasHitArea = !isLabelHidden && !isDisabled && !isReadOnly;
+  const inputRef = useRef<HTMLInputElement>(null);
+  // The band's insets stay live while the row takes taps, and clear when it
+  // stops.
+  const watchRowHitArea = useTouchHitArea(hasHitArea);
+  // The disabled-message tooltip listens for hover and focus on the whole
+  // row, a larger trigger. It anchors on the checkbox itself (below), so it
+  // shows next to the control. Its handlers check isEnabled, so the row
+  // always attaches them.
+  const rowRef = useMergedRefs(
+    disabledMessageTooltip.interactionRef,
+    watchRowHitArea,
+  );
+  // Where a press on the row itself began. A browser can move a tap's click
+  // onto the row's edge, so the band is judged from the press.
+  const pressPointRef = useRef<{x: number; y: number} | null>(null);
+  const handleRowPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+    pressPointRef.current =
+      event.target === event.currentTarget
+        ? {x: event.clientX, y: event.clientY}
+        : null;
+  };
+  // A press that began on the band, outside the row's box, toggles the
+  // checkbox, as a tap on the box does. A click from code has no press count
+  // (`detail` is 0), so it never toggles from here.
+  const handleRowClick = (event: ReactMouseEvent<HTMLDivElement>) => {
+    const press = pressPointRef.current;
+    pressPointRef.current = null;
+    if (
+      press == null ||
+      event.detail === 0 ||
+      event.target !== event.currentTarget
+    ) {
+      return;
+    }
+    const box = event.currentTarget.getBoundingClientRect();
+    const isOnBand =
+      press.x < box.left ||
+      press.x > box.right ||
+      press.y < box.top ||
+      press.y > box.bottom;
+    if (isOnBand) {
+      inputRef.current?.click();
+    }
+  };
+
   const isIndeterminate = optimisticValue === 'indeterminate';
   const isChecked = optimisticValue === true;
 
@@ -455,33 +538,34 @@ export function CheckboxInput({
         style,
       )}>
       <div
-        ref={el => {
-          // Interaction (hover/focus) listeners for the disabled-message
-          // tooltip attach to the whole row for a larger trigger target;
-          // positioning anchors on the checkbox itself (below) so the tooltip
-          // appears next to the control, not the far edge of the row.
-          // Handlers are gated internally by isEnabled, so attaching
-          // unconditionally is safe.
-          disabledMessageTooltip.interactionRef(el);
-        }}
-        {...(isDisabled ? undefined : pressable)}
+        ref={rowRef}
+        onPointerDown={hasHitArea ? handleRowPointerDown : undefined}
+        onClick={hasHitArea ? handleRowClick : undefined}
+        {...(ownsPress ? pressable : undefined)}
         {...stylex.props(
           styles.container,
           isLabelHidden && styles.containerLabelHidden,
+          hasHitArea && styles.hitAreaHost,
+          hasHitArea && touchHitAreaStyles.layer,
           // 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,
+          !isDisabled &&
+            (isRowPressSurface
+              ? styles.indicatorRowPressImage
+              : 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.
-          !isDisabled && interactionOverlayStyles.pressedAlpha,
+          // and paints it. Under a row that owns the press, the box inherits
+          // that row's strength instead.
+          ownsPress && interactionOverlayStyles.pressedAlpha,
         )}>
         <div
           {...stylex.props(
             styles.checkboxWrapper,
             wrapperSizeStyles[size],
             !isDisabled && styles.indicatorPressOverlay,
+            !isDisabled && isRowPressSurface && styles.indicatorRowPressOverlay,
           )}
           {...focusProps}>
           <input
@@ -490,6 +574,7 @@ export function CheckboxInput({
               ref,
               indeterminateRef,
               disabledMessageTooltip.positionRef,
+              inputRef,
             )}
             id={id}
             type="checkbox"

package/src/CheckboxInput/CheckboxRowPressContext.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file CheckboxRowPressContext.ts
+ * @input Uses the private layer-scoped context factory
+ * @output CheckboxRowPressContext: whether the row is its checkbox's press surface
+ * @position Internal; CheckboxListItem provides it, CheckboxInput reads it
+ *
+ * Such a row carries the shared press marker (utils/pressFeedback.ts). Its
+ * checkbox carries none, so a finger anywhere on the row presses the row.
+ * It is layer-scoped and wraps only the row's own checkbox.
+ *
+ * SYNC: When modified, update CheckboxInput.tsx and
+ * ../CheckboxList/CheckboxListItem.tsx.
+ */
+
+import {createLayerScopedContext} from '../Layer/layerScopedContext';
+
+export const CheckboxRowPressContext = createLayerScopedContext(false);
+CheckboxRowPressContext.displayName = 'CheckboxRowPressContext';

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -258,6 +258,15 @@ export const docs = {
   },
   theming: {
     targets: [{className: 'astryx-checkbox-list'}],
+    vars: [
+      {
+        name: '--_checkbox-row-press-paint',
+        description:
+          "The touch press paint a row that owns its checkbox's press hands that checkbox's box: none at rest, and the press paint at the press's strength while the touch press controller presses that row under a coarse pointer. Set on the row by its own press arms; the box reads its nearest row's value, so a list placed in a row's content keeps its own rows' paint.",
+        default: 'none',
+        private: true,
+      },
+    ],
   },
 };
 

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -8,7 +8,7 @@ export const docs = {
   displayName: 'Checkbox List Item',
   isHiddenFromOverview: true,
   description:
-    'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside a CheckboxList with a value array) or standalone mode (inside List, or inside a CheckboxList without value, such as a select-all item).',
+    'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside a CheckboxList with a value array) or standalone mode (inside List, or inside a CheckboxList without value, such as a select-all item). On a touch screen (a coarse primary pointer), a toggleable row is one press target: a touch on the label, the description or the box itself shows the pressed state on the row and its checkbox together. Where the primary pointer is fine, the box keeps its own press.',
   props: [
     {
       name: 'label',
@@ -105,7 +105,7 @@ export const docsZh = {
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
   description:
-    '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式（位于带 value 数组的 CheckboxList 内）或独立模式（位于 List 内，或位于不带 value 的 CheckboxList 内，例如“全选”选项）下使用。',
+    '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式（位于带 value 数组的 CheckboxList 内）或独立模式（位于 List 内，或位于不带 value 的 CheckboxList 内，例如“全选”选项）下使用。在触摸屏上，可切换的行是一个整体的按压目标：手指按在标签、描述或复选框本身上，行与其复选框会一起显示按下状态。主指针为精细指针时，复选框保留自己的按下效果。',
   props: [
     {
       name: 'label',
@@ -177,7 +177,7 @@ export const docsDense = {
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
   description:
-    'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value.',
+    'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value. On a touch screen a toggleable row presses as one target, box included; with a fine primary pointer the box keeps its own press.',
   propDescriptions: {
     align:
       "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",

package/src/CheckboxList/CheckboxListItem.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file CheckboxListItem.tsx
- * @input Uses React, CheckboxInput, ListItem, CheckboxListContext
+ * @input Uses React, CheckboxInput, ListItem, CheckboxListContext,
+ *   CheckboxRowPressContext, the touch presentation and the row press paint
  * @output Exports CheckboxListItem component, CheckboxListItemProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -25,6 +26,10 @@ import type {BaseProps} from '../BaseProps';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import type {CheckboxInputProps} from '../CheckboxInput/CheckboxInput';
 import type {InputStatus} from '../Field/types';
+import {CheckboxRowPressContext} from '../CheckboxInput/CheckboxRowPressContext';
+import {rowPressPaintStyles} from '../privateAttributes/press.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
+import {useTouchPresentation} from '../utils/touchPresentation';
 import {ListItem} from '../List/ListItem';
 import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
@@ -305,6 +310,12 @@ export function CheckboxListItem({
     registerWithRequiredGroup,
   );
 
+  // Under a finger, a delegating row is the option's only press surface. A
+  // touch anywhere on it presses the row. A fine pointer keeps the box's own
+  // press.
+  const {isTouch} = useTouchPresentation();
+  const rowOwnsPress = isTouch && hasRowInteraction && !effectiveDisabled;
+
   // A read-only checkbox carries aria-readonly, which the row's clickable
   // container treats as a non-interactive target, so a click on it would be
   // delegated straight back to the checkbox without end. Stop that click at
@@ -359,6 +370,12 @@ export function CheckboxListItem({
       aria-busy={isBusy || undefined}
       xstyle={
         [
+          // The row's own press paint, which the layer over its box reads.
+          rowOwnsPress && rowPressPaintStyles.checkboxRow,
+          // Item's row layer drops the strength's release, and the box paints
+          // at that strength. So the row brings the release back, and the box
+          // fades with the row.
+          rowOwnsPress && interactionOverlayStyles.pressedAlpha,
           resolvedChecked === true &&
             !effectiveDisabled &&
             !effectiveReadOnly &&
@@ -369,19 +386,23 @@ export function CheckboxListItem({
       className={className}
       style={style}
       startContent={
-        <DescribedCheckboxInput
-          ref={checkboxInputRef}
-          label={checkboxLabel}
-          aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
-          isLabelHidden
-          value={resolvedChecked}
-          onChange={() => handleToggle()}
-          onClick={handleCheckboxClick}
-          isDisabled={effectiveDisabled}
-          isReadOnly={effectiveReadOnly}
-          isLoading={isBusy}
-          size={checkboxSize}
-        />
+        // Only the row's own checkbox: a checkbox placed in the row's content
+        // keeps its own press.
+        <CheckboxRowPressContext value={rowOwnsPress}>
+          <DescribedCheckboxInput
+            ref={checkboxInputRef}
+            label={checkboxLabel}
+            aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
+            isLabelHidden
+            value={resolvedChecked}
+            onChange={() => handleToggle()}
+            onClick={handleCheckboxClick}
+            isDisabled={effectiveDisabled}
+            isReadOnly={effectiveReadOnly}
+            isLoading={isBusy}
+            size={checkboxSize}
+          />
+        </CheckboxRowPressContext>
       }
     />
   );

package/src/ClickableCard/ClickableCard.tsx

@@ -46,6 +46,7 @@ import {
 } from '../theme/tokens.stylex';
 import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
 import {mergeProps} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -314,6 +315,7 @@ export function ClickableCard({
   label,
   onClick: onClickProp,
   onMouseUp: onMouseUpProp,
+  onPointerDown: onPointerDownProp,
   href,
   target,
   isDisabled = false,
@@ -370,7 +372,7 @@ export function ClickableCard({
 
   const LinkComponent = useLinkComponent();
 
-  const {onClick, onMouseUp} = useClickableContainer({
+  const {onClick, onMouseUp, onPointerDown} = useClickableContainer({
     containerRef,
     interactiveRef,
     onClick: onClickProp,
@@ -427,6 +429,11 @@ export function ClickableCard({
       }
       onClick={!isDisabled ? onClick : undefined}
       onMouseUp={!isDisabled ? handleMouseUp : undefined}
+      onPointerDown={
+        !isDisabled
+          ? chainEventHandlers(onPointerDown, onPointerDownProp)
+          : onPointerDownProp
+      }
       {...props}>
       {isLink ? (
         <LinkRoot

package/src/ContextMenu/ContextMenu.tsx

@@ -59,6 +59,7 @@ import {useLayerInternal} from '../Layer/useLayer';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {currentGesture} from '../Layer/gestureCounter';
+import {noteOutsideDismissal} from '../Layer/outsidePress';
 import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionList';
 import {menuBottomSheetStyles} from '../DropdownMenu/menuBottomSheet.stylex';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
@@ -531,6 +532,7 @@ export function ContextMenu({
         return;
       }
       if (menu && !menu.contains(e.target as Node)) {
+        noteOutsideDismissal(menu.ownerDocument);
         closeMenu();
       }
     };

package/src/DateInput/DateInput.doc.mjs

@@ -101,7 +101,8 @@ export const docs = {
     {
       name: 'placeholder',
       type: 'string',
-      description: 'Placeholder text shown in the text input.',
+      description:
+        'Placeholder text shown in the text input. A caller placeholder replaces the calendar format hint.',
       default: "'Select a date'",
     },
     {
@@ -154,21 +155,28 @@ export const docs = {
       name: 'format',
       type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
       description:
-        "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
+        "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. 'date', 'date_long', and 'date_weekday' write the date in the field's calendar; 'system_date' stays the Gregorian ISO date. A function receives the ISO value and returns a custom string; the field cannot re-commit text it cannot read back. Applies only to the committed value, never to text being typed.",
       default: "'date_long'",
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        'The calendar the text field reads and writes dates in, and the calendar its popover and bottom sheet show. value, onChange, min, and max stay Gregorian ISO dates. People type a date the way the locale writes it in this calendar, in any decimal digits; the field reports a date only once it is complete, and names a date the calendar does not have. Years are years of this calendar: a Buddhist field reads 2026 as Buddhist year 2026, so set min and max on Buddhist and Minguo calendar fields to catch a Gregorian year typed by mistake. Calendars other than gregory, iso8601, buddhist, roc, and japanese need Temporal, native or a polyfill the application loads; without it the field shows Gregorian dates. With a calendar other than gregory or iso8601, a presentation that would show the native date control shows the popover on a fine pointer and the bottom sheet on a coarse pointer, because the native control is Gregorian; the bottom sheet shows the months, leap months, and era years of the calendar. A year in which the era changes is labeled with the era of the shown month, such as 平成31 in January 2019 and 令和元 in July.',
+      default: "the InternationalizationProvider's calendar, else 'gregory'",
+    },
     {
       name: 'presentation',
       type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
       description:
-        "Which surface draws the date picker. 'adaptive-native' (the default) uses Astryx's calendar popover on a fine pointer and the browser/OS picker (input type=date) on a coarse pointer, keeping Astryx fallbacks where a native control cannot express the value; 'native' always uses the browser/OS picker with no fallback; 'adaptive-bottom-sheet' uses the popover on a fine pointer and Astryx's bottom-sheet picker on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens a picker; a typed-only field is TimeInput's alone. Use a non-native presentation for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express.",
+        "Which surface draws the date picker. 'adaptive-native' (the default) uses Astryx's calendar popover on a fine pointer and the browser/OS picker (input type=date) on a coarse pointer, keeping Astryx fallbacks where a native control cannot express the value; 'native' always uses the browser/OS picker with no fallback; 'adaptive-bottom-sheet' uses the popover on a fine pointer and Astryx's bottom-sheet picker on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens a picker; a typed-only field is TimeInput's alone. Use a non-native presentation for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express. With a calendar other than gregory or iso8601, 'native' and 'adaptive-native' use the popover on a fine pointer and the bottom sheet on a coarse pointer, and an explicit 'native' warns in development.",
       default: "'adaptive-native'",
     },
     {
       name: 'nativePicker',
       type: "'touch' | 'always' | 'never'",
       description:
-        "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set.",
+        "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set. With a calendar other than gregory or iso8601, 'touch' and 'always' use the popover on a fine pointer and the bottom sheet on a coarse pointer.",
       default: "'touch'",
     },
     {
@@ -243,6 +251,11 @@ export const docs = {
         description:
           'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
       },
+      {
+        guidance: true,
+        description:
+          'Set min and max on a Buddhist or Minguo calendar field, so a Gregorian year typed by mistake shows an error instead of a date centuries away.',
+      },
       {
         guidance: true,
         description:
@@ -294,7 +307,7 @@ export const docs = {
         name: 'Text input',
         required: true,
         description:
-          'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.',
+          "A field where the user can type a date directly, written the way the locale writes it in the field's calendar.",
       },
       {
         name: 'Calendar icon',
@@ -346,6 +359,11 @@ export const docsZh = {
         description:
           'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
       },
+      {
+        guidance: true,
+        description:
+          'Set min and max on a Buddhist or Minguo calendar field, so a Gregorian year typed by mistake shows an error instead of a date centuries away.',
+      },
       {
         guidance: true,
         description:
@@ -462,7 +480,8 @@ export const docsZh = {
     {
       name: 'placeholder',
       type: 'string',
-      description: '文本输入框中显示的占位符文本。',
+      description:
+        '文本输入框中显示的占位符文本。调用方提供的占位符会替代日历格式提示。',
       default: "'Select a date'",
     },
     {
@@ -511,21 +530,28 @@ export const docsZh = {
       name: 'format',
       type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
       description:
-        "已选日期的显示格式。命名值复用 Timestamp 的格式词汇：'date' 显示 'Mar 21, 2026'，'date_long' 显示 'March 21, 2026'，'date_weekday' 显示 'Wed, Mar 21, 2026'，'system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值，不影响正在输入的文本。",
+        "已选日期的显示格式。命名值复用 Timestamp 的格式词汇：'date' 显示 'Mar 21, 2026'，'date_long' 显示 'March 21, 2026'，'date_weekday' 显示 'Wed, Mar 21, 2026'，'system_date' 显示 '2026-03-21'。'date'、'date_long' 与 'date_weekday' 按字段的历法书写日期；'system_date' 始终为公历 ISO 日期。函数接收 ISO 值并返回自定义字符串；字段无法读回的文本在编辑后不能重新提交。仅作用于已提交的值，不影响正在输入的文本。",
       default: "'date_long'",
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        '文本字段读写日期所用的历法，也是其弹出日历和底部选择器显示的历法。value、onChange、min 和 max 始终为公历 ISO 日期。用户按当前语言区域在该历法中的写法输入日期，可使用任意十进制数字；只有输入完整时字段才会报告日期，并会指出该历法中不存在的日期。年份是该历法的年份：佛历字段把 2026 读作佛历 2026 年，因此请为佛历和民国纪年字段设置 min 和 max，以发现误输入的公历年份。gregory、iso8601、buddhist、roc 和 japanese 以外的历法需要 Temporal（原生或由应用加载的 polyfill）；没有 Temporal 时字段显示公历日期。使用 gregory 或 iso8601 以外的历法时，原本显示原生日期控件的呈现会在精细指针上显示弹出层、在粗指针上显示底部选择器，因为原生控件只显示公历；底部选择器显示该历法的月份、闰月和带纪元的年份。年号更替的年份按所显示月份的年号标注，如 2019 年 1 月为“平成31”，7 月为“令和元”。',
+      default: "InternationalizationProvider 的历法，否则为 'gregory'",
+    },
     {
       name: 'presentation',
       type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
       description:
-        "由哪个界面绘制日期选择器。'adaptive-native'（默认）在精细指针上使用 Astryx 日历弹出层、在粗指针上使用浏览器/操作系统选择器（input type=date），且原生控件无法表达值时保留 Astryx 回退；'native' 始终使用浏览器/操作系统选择器且不回退；'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 底部选择器；'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器；仅输入字段的呈现只属于 TimeInput。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用非原生呈现，原生选择器无法表达这些。",
+        "由哪个界面绘制日期选择器。'adaptive-native'（默认）在精细指针上使用 Astryx 日历弹出层、在粗指针上使用浏览器/操作系统选择器（input type=date），且原生控件无法表达值时保留 Astryx 回退；'native' 始终使用浏览器/操作系统选择器且不回退；'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 底部选择器；'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器；仅输入字段的呈现只属于 TimeInput。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用非原生呈现，原生选择器无法表达这些。使用 gregory 或 iso8601 以外的历法时，'native' 与 'adaptive-native' 在精细指针上使用弹出层、在粗指针上使用底部选择器，显式的 'native' 会在开发环境中发出警告。",
       default: "'adaptive-native'",
     },
     {
       name: 'nativePicker',
       type: "'touch' | 'always' | 'never'",
       description:
-        "已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet'）。仍按已发布行为工作；同时设置时以 presentation 为准。",
+        "已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet'）。仍按已发布行为工作；同时设置时以 presentation 为准。使用 gregory 或 iso8601 以外的历法时，'touch' 与 'always' 在精细指针上使用弹出层、在粗指针上使用底部选择器。",
       default: "'touch'",
     },
     {
@@ -601,6 +627,11 @@ export const docsDense = {
         description:
           'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
       },
+      {
+        guidance: true,
+        description:
+          'Set min and max on a Buddhist or Minguo calendar field, so a Gregorian year typed by mistake shows an error instead of a date centuries away.',
+      },
       {
         guidance: true,
         description:
@@ -671,11 +702,13 @@ export const docsDense = {
     weekStartsOn:
       'first day of week in calendar (0=Sunday, or name e.g. "mon")',
     format:
-      "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
+      "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21, always Gregorian ISO), or (iso)=>string; reuses Timestamp vocabulary; named formats write the field's calendar. Committed value only, not while typing.",
+    calendar:
+      "calendar for typed + committed text, the popover, and the bottom sheet (months, leap months, era years; an era-change year follows the shown month, e.g. 平成31 in Jan 2019, 令和元 in Jul) (default: provider's, else 'gregory'); values stay Gregorian ISO; years are the calendar's, so set min/max on buddhist/roc fields; non-Gregorian-aligned calendars need Temporal (native or app-loaded polyfill), else Gregorian; non-gregory/iso8601 never shows the native control: popover fine / sheet coarse",
     presentation:
-      "which surface draws the picker: 'adaptive-native' (default) = Astryx popover on fine, browser/OS on coarse w/ Astryx fallbacks; 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popover fine / Astryx sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens a picker (no text-only value; that is TimeInput's). use non-native for weekStartsOn/numberOfMonths/dateConstraints.",
+      "which surface draws the picker: 'adaptive-native' (default) = Astryx popover on fine, browser/OS on coarse w/ Astryx fallbacks; 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popover fine / Astryx sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens a picker (no text-only value; that is TimeInput's). use non-native for weekStartsOn/numberOfMonths/dateConstraints. non-gregory/iso8601 calendar: native + adaptive-native become popover fine / sheet coarse; explicit 'native' warns in dev.",
     nativePicker:
-      "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
+      "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released, except that a calendar other than gregory or iso8601 never shows the native control; presentation wins if both set.",
     containerXstyle:
       'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
     containerClassName: