@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/dist/utils/triggerFocus.js

@@ -34,14 +34,21 @@ export function isFocusableTrigger(element) {
  * too, so a plain wrapper ignores its children's focus.
  */
 export function isFocusForTrigger(event, mode) {
+  return isFocusOnTrigger(event.target, event.currentTarget, mode);
+}
+
+/**
+ * `isFocusForTrigger` for focus already on `target`, inside `trigger`: the
+ * same rule, read when a trigger attaches with focus inside it.
+ */
+export function isFocusOnTrigger(target, trigger, mode) {
   if (mode === 'always') {
     return true;
   }
   if (mode === 'never') {
     return false;
   }
-  const trigger = event.currentTarget;
-  return trigger != null && (event.target === trigger || isFocusableTrigger(trigger));
+  return trigger != null && (target === trigger || isFocusableTrigger(trigger));
 }
 
 /** Remembers whether a trigger's current focus counted when it arrived. */

package/locales/en.json

@@ -1323,6 +1323,10 @@
     "defaultMessage": "Loading",
     "description": "Screen-reader-only default name for a standalone Spinner's role=\"status\" element, used when the consumer supplies neither `aria-label` nor a visible string label; also announced once when a busy input or selector starts loading, in place of its decorative Spinner. Present-progressive form. Kept separate from `button.loading` and `typeahead.loading` — translations may diverge."
   },
+  "@astryx.scrollRegion.label": {
+    "defaultMessage": "Content",
+    "description": "Accessible name of a scrolling content region (LayoutContent, LayoutPanel or StackItem) when the caller gives none. A screen reader announces it with the region's group role while the region scrolls."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."

package/locales/pseudo.json

@@ -992,6 +992,9 @@
   "@astryx.spinner.loading": {
     "defaultMessage": "⟦Łóàðíñĝ⟧"
   },
+  "@astryx.scrollRegion.label": {
+    "defaultMessage": "⟦Çóñţéñţ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.8",
+  "version": "0.7.9-canary.07992bb",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -838,6 +838,11 @@
       "source": "./src/internal/selectable-card.ts",
       "types": "./dist/internal/selectable-card.d.ts",
       "default": "./dist/internal/selectable-card.js"
+    },
+    "./internal/spinner-rotor": {
+      "source": "./src/internal/spinner-rotor.ts",
+      "types": "./dist/internal/spinner-rotor.d.ts",
+      "default": "./dist/internal/spinner-rotor.js"
     }
   },
   "files": [
@@ -870,6 +875,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.9-canary.07992bb",
+    "@astryxdesign/cli": "0.7.9-canary.07992bb",
+    "@astryxdesign/interaction-harness": "0.7.9-canary.07992bb",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -881,9 +889,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
     "tailwindcss": "^4.3.2",
-    "@astryxdesign/cli": "0.7.8",
-    "@astryxdesign/interaction-harness": "0.0.0",
-    "@astryxdesign/a11y-spec": "0.0.0"
+    "temporal-polyfill": "^1.0.6"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/observeMainOverflow.ts

@@ -4,20 +4,23 @@
 
 /**
  * @file observeMainOverflow.ts
- * @input AppShell's main region under `height="fill"`: its own scroll
- *   container, holding its content as direct children with no wrapper
+ * @input A scroll container that holds its content as direct children with
+ *   no wrapper: AppShell's main region under `height="fill"`, or a scrolling
+ *   LayoutContent, LayoutPanel or StackItem
  * @output observeMainOverflow(main, onChange): reports whether main's content
  *   overflows it on either axis, once at the start and on every change, and
  *   returns the function that stops observing
- * @position Internal to AppShell and never exported. AppShell makes main a
+ * @position Internal and never exported. AppShell makes main a
  *   keyboard stop only while it overflows (`spec:AST-025` FR12,
- *   `component:AppShell` FR4 and PR1). Main has no inner content box, so its
- *   content grows inside it without resizing it: its direct children's sizes
- *   are watched instead.
+ *   `component:AppShell` FR4 and PR1). useScrollRegionProps names a
+ *   scrolling region only while it overflows. Main has no inner content
+ *   box, so its content grows inside it without resizing it: its direct
+ *   children's sizes are watched instead.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/AppShell/AppShell.tsx
  * - /packages/core/src/AppShell/observeMainOverflow.test.ts
+ * - /packages/core/src/hooks/useScrollRegionProps.ts
  */
 
 import {

package/src/BottomSheet/BottomSheet.tsx

@@ -81,6 +81,7 @@ import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {useModalOutlet} from '../Layer/modalOutlet';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {useFocusRegionContainment} from '../hooks/useFocusTrap';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {
@@ -444,6 +445,10 @@ function StandaloneBottomSheet({
     false,
   );
   const isEntrySettled = settledOpen && isOpen;
+  // Only a modal sheet contains Tab; a non-modal one leaves the page's focus
+  // order alone. A closing sheet stops containing as soon as it starts to
+  // leave.
+  useFocusRegionContainment(dialogRef, isOpen && hasScrim);
   // Presentation outlives the controlled prop: a closing sheet stays mounted
   // and in its native host through its exit, and only its motion completion
   // (or a replace finishing) clears it. The open flip is derived during

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -26,6 +26,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
+  useSyncExternalStore,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -60,6 +61,7 @@ import {
   paddingStyles,
   spacingStepToToken,
 } from '../Layout/padding.stylex';
+import {subscribeInput} from '../utils/inputStream';
 import type {SpacingStep} from '../utils/types';
 import {
   isValidSnapPoint,
@@ -82,8 +84,20 @@ const HEIGHT_BUDGETS = {
 export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
 export type {BottomSheetSnapPoint};
 
-// SYNC: must match OVERSCROLL_MAX in useSheetGestures.ts.
-const OVERSCROLL_PADDING = 48;
+// The reserve: how far the sheet's surface reaches below the screen, so a
+// pull past the top never shows the page under it.
+// SYNC: OVERSCROLL_MAX in useSheetGestures.ts must not exceed MIN_RESERVE.
+const MIN_RESERVE = 48;
+// A finger can pull past the top by at most the viewport's height. The rubber
+// band over a sheet as tall as the viewport then shows 35.5% of it.
+const RESERVE_VIEWPORT_SHARE = 0.4;
+
+function sheetReserve(viewportHeight: number): number {
+  return Math.max(
+    MIN_RESERVE,
+    Math.ceil(viewportHeight * RESERVE_VIEWPORT_SHARE),
+  );
+}
 const MOBILE_KEYBOARD_BOTTOM_CLEARANCE = 48;
 const TRANSITION_BACKSTOP_BUFFER_MS = 50;
 // The floating handle bar's height. The bar is out of flow, so this is not
@@ -92,6 +106,22 @@ const TRANSITION_BACKSTOP_BUFFER_MS = 50;
 // padding already provides.
 const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];
 
+const BLOCK_SIZE_PROPERTIES = [
+  'height',
+  'minHeight',
+  'maxHeight',
+  'blockSize',
+  'minBlockSize',
+  'maxBlockSize',
+] as const;
+
+/** Whether StyleX styles hold any style: they can nest in arrays. */
+function hasStyles(xstyle: unknown): boolean {
+  return Array.isArray(xstyle)
+    ? xstyle.some(hasStyles)
+    : xstyle != null && typeof xstyle === 'object';
+}
+
 // Measure the viewport that the height budgets use. They are `dvh`, which
 // the virtual keyboard does not shrink, so `visualViewport` would differ by
 // the keyboard's height. `useMobileKeyboard` handles the keyboard and does
@@ -100,6 +130,14 @@ function layoutViewportHeight(): number {
   return typeof window === 'undefined' ? 0 : window.innerHeight;
 }
 
+function subscribeToResize(onChange: () => void): () => void {
+  return subscribeInput(window, 'resize', onChange);
+}
+
+function subscribeToNothing(): () => void {
+  return () => {};
+}
+
 /**
  * A stable identity for a set of snap points. Type-tagged, so the fraction
  * `0.5` and the (invalid) string `'0.5'` cannot collide on one key.
@@ -159,8 +197,8 @@ const styles = stylex.create({
     boxShadow: shadowVars['--shadow-high'],
     outline: 'none',
     overflow: 'hidden',
-    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + ${OVERSCROLL_PADDING}px)`,
-    marginBlockEnd: `${-OVERSCROLL_PADDING}px`,
+    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
+    marginBlockEnd: `calc(-1 * var(--_sheet-reserve, ${MIN_RESERVE}px))`,
     // Under reduced motion no transform runs. On a coarse primary pointer the
     // entrance is an opacity cross-fade of at most 200 ms. A fine pointer gets
     // the change at once (the 0.01s collapse).
@@ -340,11 +378,11 @@ const styles = stylex.create({
     },
   }),
   budget: {
-    height: `calc(var(--_sheet-budget) + ${OVERSCROLL_PADDING}px)`,
+    height: `calc(var(--_sheet-budget) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
   },
   hugHeight: {
     height: 'fit-content',
-    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + ${OVERSCROLL_PADDING}px)`,
+    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
   },
 });
 
@@ -649,6 +687,24 @@ export function BottomSheetPanel({
 
   // A caller's height owns the element's height: the drag never writes it.
   const consumerHeight = style?.height;
+  // StyleX styles and a class name can size the sheet too. Their rules are
+  // only class names here, so any of them counts as a size.
+  const isSizedByCaller =
+    BLOCK_SIZE_PROPERTIES.some(property => style?.[property] != null) ||
+    hasStyles(xstyle) ||
+    (className != null && className !== '');
+  // Only a finger stretches the sheet past MIN_RESERVE, so a device with no
+  // touch pointer keeps the smallest reserve. So does a sheet the caller
+  // sizes, which nothing extends by the reserve; the stretch stops at it.
+  const hasTouchPointer = useMediaQuery('(any-pointer: coarse)');
+  const tracksViewport = isPresented && hasTouchPointer && !isSizedByCaller;
+  const viewportHeight = useSyncExternalStore(
+    tracksViewport ? subscribeToResize : subscribeToNothing,
+    () => (tracksViewport ? layoutViewportHeight() : 0),
+    () => 0,
+  );
+  const reserve =
+    viewportHeight > 0 ? sheetReserve(viewportHeight) : MIN_RESERVE;
   const {
     contentProps,
     handleProps,
@@ -668,7 +724,7 @@ export function BottomSheetPanel({
     isOpen: isInteractive,
     isOpenRequested: isOpenRequested ?? isInteractive,
     canDismiss: isSwipeDismissAllowed,
-    offscreenBlockEndInset: OVERSCROLL_PADDING,
+    offscreenBlockEndInset: reserve,
     onDismiss,
     snapHeights,
     onTravelStart: () => {
@@ -931,6 +987,7 @@ export function BottomSheetPanel({
         className,
         {
           ['--_sheet-budget' as string]: budget,
+          ['--_sheet-reserve' as string]: `${reserve}px`,
           ...(isInteractive
             ? gestureStyle
             : isRetained || isClosing

package/src/BottomSheet/useSheetGestures.ts

@@ -64,6 +64,8 @@ import {
   type UIEvent as ReactUIEvent,
 } from 'react';
 
+import {rubberBand} from '../motion/rubberBand';
+import {scroll} from '../motion/uikit/scroll';
 import {
   computeDetentOffsets,
   peekOffsetFor,
@@ -112,12 +114,19 @@ function isSyntheticTouch(event: ReactPointerEvent): boolean {
   return (event as SyntheticTouchPointer).syntheticTouch === true;
 }
 
-// Rubber-band factor for dragging up past fully-open, capped at OVERSCROLL_MAX
-// (the sheet reserves that much bottom padding for the lift to reveal).
+type StylusTouch = Touch & {touchType?: string};
+
+// An Apple Pencil raises touch events too, marked `stylus`. Its drag is a
+// pen's, as on the grabber, where WebKit reports it as a pen.
+function touchPointerType(touch: Touch): string {
+  return (touch as StylusTouch).touchType === 'stylus' ? 'pen' : 'touch';
+}
+
+// A mouse's stretch past fully open: a resisted fraction of the drag, capped
+// at OVERSCROLL_MAX.
 const OVERSCROLL_RESISTANCE = 0.35;
-// SYNC: must match OVERSCROLL_PADDING in BottomSheetPanel.tsx (the reserved
-// bottom padding the lift reveals). Kept as a local const rather than a shared
-// import so it can be used inside stylex.create there.
+// SYNC: must not exceed MIN_RESERVE in BottomSheetPanel.tsx, the smallest
+// reserve the sheet keeps below the screen.
 const OVERSCROLL_MAX = 48;
 // Travel past the point where a scrolling gesture ran out of content before it
 // hands the sheet the rest of the pull. Small enough to feel continuous with
@@ -308,6 +317,36 @@ function chainAtBottom(chain: ReadonlyArray<HTMLElement>): boolean {
   return chain.every(elementAtBottom);
 }
 
+function chainScrolls(chain: ReadonlyArray<HTMLElement>): boolean {
+  return chain.some(element => element.scrollHeight - element.clientHeight > 1);
+}
+
+/**
+ * iOS rubber-bands a scroller past its end even under `overscroll-behavior:
+ * contain`. While the content sits at its end mid-pull, `none` holds it still,
+ * so only the sheet moves. Returns the undo.
+ */
+function holdAtEnd(chain: ReadonlyArray<HTMLElement>): () => void {
+  const previous = chain.map(element => element.style.overscrollBehaviorY);
+  for (const element of chain) {
+    element.style.overscrollBehaviorY = 'none';
+  }
+  return () => {
+    chain.forEach((element, index) => {
+      element.style.overscrollBehaviorY = previous[index];
+    });
+  };
+}
+
+function releaseContentHold(
+  armed: {releaseContentHold: (() => void) | null} | null,
+): void {
+  if (armed?.releaseContentHold != null) {
+    armed.releaseContentHold();
+    armed.releaseContentHold = null;
+  }
+}
+
 function visibleHeightForOffset(
   sheetHeight: number,
   offset: number,
@@ -690,6 +729,8 @@ export function useSheetGestures({
     samples: {t: number; y: number}[];
     velocity: number;
     height: number;
+    /** The surface kept below the screen when the drag began. */
+    reserve: number;
     baseOffset: number;
     baseLayoutOffset: number;
     renderedOffset: number;
@@ -1171,7 +1212,7 @@ export function useSheetGestures({
       const baseLayoutOffset = settledLayoutOffsetRef.current;
       dragStateRef.current = {
         syntheticTouch,
-        pointerType: syntheticTouch ? 'touch' : event.pointerType,
+        pointerType: event.pointerType,
         pointerId: event.pointerId,
         startCoord: start,
         lastCoord: event.clientY,
@@ -1179,6 +1220,7 @@ export function useSheetGestures({
         samples: [{t: event.timeStamp, y: event.clientY}],
         velocity: 0,
         height: sheetHeight,
+        reserve: offscreenBlockEndInsetRef.current,
         baseOffset: settledOffset,
         baseLayoutOffset,
         renderedOffset: settledOffset,
@@ -1279,8 +1321,19 @@ export function useSheetGestures({
       const maxDetentOffset = offsets[offsets.length - 1];
       let next: number;
       if (raw < 0) {
-        // Up past fully-open: damped + capped rubber-band; springs back on release.
-        next = Math.max(-OVERSCROLL_MAX, raw * OVERSCROLL_RESISTANCE);
+        // A touch device's reserve covers the whole stretch. The clamp binds
+        // only where the reserve is short.
+        next =
+          state.pointerType === 'touch'
+            ? Math.max(
+                -state.reserve,
+                rubberBand(
+                  raw,
+                  state.height - state.reserve,
+                  scroll.rubberBand.coefficient,
+                ),
+              )
+            : Math.max(-OVERSCROLL_MAX, raw * OVERSCROLL_RESISTANCE);
       } else if (raw > maxDetentOffset) {
         // In the dismiss zone: no magnet, so it doesn't fight a drag-to-close.
         next = raw;
@@ -1482,6 +1535,8 @@ export function useSheetGestures({
     // armed at `touchstart`. That drag never cancelled the native scroll, so
     // it has to yield again if the finger comes back down.
     promotedAtContentEnd: boolean;
+    // Null while no hold is set.
+    releaseContentHold: (() => void) | null;
   } | null>(null);
   const previousTouchHandlersRef = useRef<{
     start: (e: TouchEvent) => void;
@@ -1495,6 +1550,7 @@ export function useSheetGestures({
   // the gesture; the sheet returns to its detent.
   const yieldToPinch = useCallback(
     (target?: HTMLElement) => {
+      releaseContentHold(touchDragRef.current);
       touchDragRef.current = null;
       armedBodyRef.current = null;
       cancelDrag(target);
@@ -1522,6 +1578,7 @@ export function useSheetGestures({
       ({
         syntheticTouch: true,
         pointerId: touch.identifier,
+        pointerType: touchPointerType(touch),
         clientY: touch.clientY,
         timeStamp: Date.now(),
         currentTarget: target,
@@ -1542,21 +1599,21 @@ export function useSheetGestures({
       // scroll, but it is tracked all the same: the scroller can run out of
       // content while the finger is still down (see onTouchMove). A touch
       // inside a layer this sheet hosts is that layer's, never tracked here.
+      releaseContentHold(touchDragRef.current);
       if (!touch || isInsideNestedLayer(event.target, body)) {
         touchDragRef.current = null;
         return;
       }
       const scrollers = scrollChainUnder(event.target, body);
       const top = chainAtTop(scrollers);
-      // The bottom edge hands off so the sheet can EXPAND, so it is only a
-      // handoff when a taller detent exists. Already at the tallest, an
-      // upward pull has nowhere to travel: promoting it would trade the
-      // user's scroll for a rubber-band the release throws straight back, and
-      // — because promotion preventDefault()s the rest of the gesture — would
-      // strand the scroller for as long as the finger stays down, so reversing
-      // downward to scroll back would collapse the sheet instead. Leave the
-      // gesture with the content.
-      const bottom = chainAtBottom(scrollers) && activeOffsetRef.current > 0;
+      // Claiming a pull up from its first move blocks the content's scroll for
+      // the whole touch. So it is claimed here only below the tallest detent,
+      // or over content that cannot scroll. At the tallest detent, a list at
+      // its end keeps its touch. Its pull reaches the sheet through the
+      // content-end hand-off below, and a reversal hands it back.
+      const bottom =
+        chainAtBottom(scrollers) &&
+        (activeOffsetRef.current > 0 || !chainScrolls(scrollers));
       touchDragRef.current = {
         id: touch.identifier,
         startY: touch.clientY,
@@ -1565,6 +1622,7 @@ export function useSheetGestures({
         bottom,
         contentEndY: null,
         promotedAtContentEnd: false,
+        releaseContentHold: null,
       };
     };
 
@@ -1594,6 +1652,7 @@ export function useSheetGestures({
             // at once; a later pull past the end promotes again.
             armed.contentEndY = null;
             armed.promotedAtContentEnd = false;
+            releaseContentHold(armed);
             cancelDragRef.current(scroller);
             return;
           }
@@ -1627,6 +1686,7 @@ export function useSheetGestures({
         chainAtBottom(armed.scrollers);
       if (pullDownAtTop || pullUpAtBottom) {
         event.preventDefault();
+        releaseContentHold(armed);
         touchDragRef.current = null;
         beginDragRef.current(
           asPointer(t, scroller),
@@ -1646,13 +1706,14 @@ export function useSheetGestures({
       // cannot see this, and re-arming for a preventDefault() promotion would
       // be useless anyway: once the browser has committed the gesture to
       // scrolling, every remaining touchmove is non-cancelable. Nothing needs
-      // cancelling either — the scroller is clamped at its maximum, so further
-      // upward travel scrolls nothing. Anchor at the point where the content
+      // cancelling either: the hold clamps the scroller at its maximum, so
+      // further upward travel scrolls nothing. Anchor at the point where the content
       // ran out and give the sheet everything past it, so the pull continues
       // into the sheet with no jump and no lost scrolling.
-      if (activeOffsetRef.current > 0 && chainAtBottom(armed.scrollers)) {
+      if (chainAtBottom(armed.scrollers)) {
         if (armed.contentEndY == null) {
           armed.contentEndY = t.clientY;
+          armed.releaseContentHold ??= holdAtEnd(armed.scrollers);
         } else if (armed.contentEndY - t.clientY >= CONTENT_END_HANDOFF_SLOP) {
           armed.promotedAtContentEnd = true;
           beginDragRef.current(
@@ -1664,10 +1725,12 @@ export function useSheetGestures({
         }
       } else {
         armed.contentEndY = null;
+        releaseContentHold(armed);
       }
     };
 
     const onTouchEnd = (event: TouchEvent) => {
+      releaseContentHold(touchDragRef.current);
       touchDragRef.current = null;
       const pointerId = dragStateRef.current?.pointerId;
       if (pointerId == null) {

package/src/Calendar/Calendar.doc.mjs

@@ -39,6 +39,11 @@ export const docs = {
         description:
           'Show two months side by side when the user frequently selects dates that span a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'For a custom month view, use useCalendarNavigation and useCalendarDays from @astryxdesign/core/Calendar. To show another calendar system, pass the same calendar to both and feed visibleCalendarMonths into useCalendarDays. The hooks default to gregory and never read the InternationalizationProvider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -169,13 +174,15 @@ export const docs = {
     {
       name: 'hasWeekNumbers',
       type: 'boolean',
-      description: 'Show ISO week numbers.',
+      description:
+        'Show ISO 8601 week numbers. They are ISO 8601 week numbers in every calendar system.',
       default: 'false',
     },
     {
       name: 'hasVariableRowCount',
       type: 'boolean',
-      description: 'Variable vs fixed 6-row grid.',
+      description:
+        'Give each month only the rows it needs. The default fixed 6-row grid keeps the same height from month to month; a variable row count trades that fixed height for a more compact grid.',
       default: 'false',
     },
     {
@@ -185,6 +192,48 @@ export const docs = {
         'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
       default: '0',
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        "Calendar system the grid shows, such as 'persian', 'hebrew', or 'islamic-umalqura'. It sets the months, their names, and month and year navigation. value, min, max, focusDate, and every callback stay Gregorian ISO dates. Calendars other than gregory, iso8601, buddhist, roc, and japanese need Temporal; where the runtime lacks it, load a polyfill such as temporal-polyfill/full/global on the server and in the browser, or the grid shows Gregorian months. Month starts in the Chinese and Dangi calendars come from the runtime's Temporal, and some polyfills start a few months one day apart from native Temporal; when server and browser markup must match, use one implementation on both sides, such as installImplementation() from temporal-polyfill/full/shim, which replaces a native Temporal.",
+      default: 'the InternationalizationProvider calendar, else gregory',
+    },
+  ],
+  examples: [
+    {
+      label: 'A custom month view in the Persian calendar',
+      code: `import {Button} from '@astryxdesign/core/Button';
+import {
+  useCalendarDays,
+  useCalendarNavigation,
+} from '@astryxdesign/core/Calendar';
+
+function PersianMonth() {
+  const {monthYearLabel, visibleCalendarMonths, navigateMonth} =
+    useCalendarNavigation({initialValue: '2026-10-30', calendar: 'persian'});
+  // visibleCalendarMonths[0] is {year: 1405, month: 8}: Aban 1405.
+  const {weeks} = useCalendarDays({
+    ...visibleCalendarMonths[0],
+    calendar: 'persian',
+  });
+  return (
+    <section aria-label={monthYearLabel}>
+      <Button label="Previous month" onClick={() => navigateMonth(-1)} />
+      <Button label="Next month" onClick={() => navigateMonth(1)} />
+      {weeks.map(week => (
+        <div key={week[0].iso}>
+          {week.map(day => (
+            <span key={day.iso} data-date={day.iso}>
+              {day.isOutside ? '' : day.dayNumber}
+            </span>
+          ))}
+        </div>
+      ))}
+    </section>
+  );
+}`,
+    },
   ],
   theming: {
     targets: [
@@ -230,6 +279,11 @@ export const docsZh = {
         description:
           'Show two months side by side when the user frequently selects dates that span a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'For a custom month view, use useCalendarNavigation and useCalendarDays from @astryxdesign/core/Calendar. To show another calendar system, pass the same calendar to both and feed visibleCalendarMonths into useCalendarDays. The hooks default to gregory and never read the InternationalizationProvider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -311,13 +365,14 @@ export const docsZh = {
     {
       name: 'hasWeekNumbers',
       type: 'boolean',
-      description: '显示 ISO 周数。',
+      description: '显示 ISO 8601 周数。在任何历法中都是 ISO 8601 周数。',
       default: 'false',
     },
     {
       name: 'hasVariableRowCount',
       type: 'boolean',
-      description: '可变行数与固定 6 行网格。',
+      description:
+        '每个月只显示所需的行数。默认的固定 6 行网格使每个月高度相同；可变行数以固定高度换取更紧凑的网格。',
       default: 'false',
     },
     {
@@ -327,6 +382,13 @@ export const docsZh = {
         '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。',
       default: '0',
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        "网格显示的历法，如 'persian'、'hebrew' 或 'islamic-umalqura'。它决定月份、月份名称以及按月和按年的导航。value、min、max、focusDate 和所有回调仍为公历 ISO 日期。gregory、iso8601、buddhist、roc 和 japanese 以外的历法需要 Temporal；运行环境没有 Temporal 时，请在服务端和浏览器中加载 polyfill（如 temporal-polyfill/full/global），否则网格显示公历月份。农历（chinese）和檀纪历（dangi）的月初取自运行环境的 Temporal，部分 polyfill 与原生 Temporal 有少数月份的月初相差一天；服务端渲染且需要两端标记一致时，请在两端使用同一种实现，例如 temporal-polyfill/full/shim 的 installImplementation()，它会替换原生 Temporal。",
+      default: 'InternationalizationProvider 的历法，否则为 gregory',
+    },
   ],
   theming: {
     targets: [
@@ -374,6 +436,11 @@ export const docsDense = {
         description:
           'Show two months side by side when user frequently selects dates spanning a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'Custom month view: useCalendarNavigation + useCalendarDays; pass the same calendar to both, feed visibleCalendarMonths into useCalendarDays. Default gregory; never read the provider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -400,8 +467,11 @@ export const docsDense = {
     onFocusDateChange: 'navigation callback',
     handleRef: 'imperative navigation handle',
     hasOutsideDays: 'show days from adjacent months',
-    hasWeekNumbers: 'show ISO week numbers',
-    hasVariableRowCount: 'variable vs fixed 6-row grid',
+    hasWeekNumbers: 'show ISO 8601 week numbers, in every calendar system',
+    hasVariableRowCount:
+      'only the rows each month needs; trades the fixed 6-row height for a compact grid',
     weekStartsOn: 'first day of week (0=Sunday, or name e.g. "mon")',
+    calendar:
+      'calendar system shown (default: provider calendar, else gregory); values stay Gregorian ISO; non-Gregorian-aligned calendars need Temporal',
   },
 };