@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

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,13 @@ 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: 'density',
       type: "'compact' | 'balanced' | 'spacious'",

package/src/CheckboxList/CheckboxList.tsx

@@ -65,6 +65,13 @@ export interface CheckboxListProps extends Omit<
    * Description text displayed below the label.
    */
   description?: string;
+  /**
+   * 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
+   */
+  isOptional?: boolean;
   /**
    * Status indicator for the checkbox group.
    * When set with a message, displays a colored message box below the group.
@@ -153,6 +160,7 @@ export function CheckboxList({
   label,
   isLabelHidden = false,
   description,
+  isOptional = false,
   status,
   value,
   onChange,
@@ -270,6 +278,7 @@ export function CheckboxList({
       inputID={inputID}
       labelID={labelID}
       isGroupLabel
+      isOptional={isOptional}
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
       status={

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -51,10 +51,18 @@ export const docs = {
       description: 'Show a line number gutter.',
       default: 'false',
     },
+    {
+      name: 'startLineNumber',
+      type: 'number',
+      description:
+        'First line number shown in the gutter. The gutter shows file coordinates (startLineNumber + index) so a code excerpt reads with its real line numbers. highlightLines uses the same file coordinates. Values below 1 clamp to 1.',
+      default: '1',
+    },
     {
       name: 'highlightLines',
       type: 'number[]',
-      description: '1-indexed line numbers to highlight.',
+      description:
+        '1-indexed line numbers to highlight, in the same file coordinates as the gutter (see startLineNumber). Out-of-range entries render no highlight.',
     },
     {
       name: 'isDiff',

package/src/CodeBlock/CodeBlock.tsx

@@ -456,6 +456,7 @@ const LINE_CHUNK_THRESHOLD = 100;
 const CodeChunk = React.memo(function CodeChunk({
   lines,
   startIndex,
+  startLineNumber,
   highlightSet,
   diffKinds,
   renderLineContent,
@@ -463,6 +464,7 @@ const CodeChunk = React.memo(function CodeChunk({
 }: {
   lines: string[];
   startIndex: number;
+  startLineNumber: number;
   highlightSet: Set<number> | null;
   diffKinds: ReadonlyArray<DiffLineKind> | null;
   renderLineContent: (line: string, lineIndex: number) => React.ReactNode;
@@ -472,11 +474,12 @@ const CodeChunk = React.memo(function CodeChunk({
     <>
       {lines.map((line, j) => {
         const i = startIndex + j;
+        const lineNumber = startLineNumber + i;
         const diffKind = diffKinds?.[i];
         return (
           <div
             key={i}
-            data-line={i + 1}
+            data-line={lineNumber}
             data-diff={diffKind === 'context' ? undefined : diffKind}
             {...stylex.props(
               styles.line,
@@ -488,7 +491,8 @@ const CodeChunk = React.memo(function CodeChunk({
               diffKind === 'header' && styles.lineDiffHeader,
               // Last on purpose: a highlight replaces a diff tint rather than
               // stacking on it, so tokens keep their single-paint contrast.
-              (highlightSet?.has(i + 1) ?? false) && styles.lineHighlighted,
+              (highlightSet?.has(lineNumber) ?? false) &&
+                styles.lineHighlighted,
             )}>
             {renderLineContent(line, i)}
           </div>
@@ -504,6 +508,7 @@ function renderLines(
   diffKinds: ReadonlyArray<DiffLineKind> | null,
   renderLineContent: (line: string, lineIndex: number) => React.ReactNode,
   lineNumbers: boolean,
+  startLineNumber: number,
   chunkSize: number = LINE_CHUNK_SIZE,
 ): React.ReactNode {
   chunkSize = Math.max(1, Math.floor(chunkSize));
@@ -513,6 +518,7 @@ function renderLines(
       <CodeChunk
         lines={lines}
         startIndex={0}
+        startLineNumber={startLineNumber}
         highlightSet={highlightSet}
         diffKinds={diffKinds}
         renderLineContent={renderLineContent}
@@ -536,6 +542,7 @@ function renderLines(
         <CodeChunk
           lines={chunkLines}
           startIndex={start}
+          startLineNumber={startLineNumber}
           highlightSet={highlightSet}
           diffKinds={diffKinds}
           renderLineContent={renderLineContent}
@@ -566,6 +573,15 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
   title?: string;
   hasLanguageLabel?: boolean;
   hasLineNumbers?: boolean;
+  /**
+   * First line's number in the source file. The gutter shows file
+   * coordinates (`startLineNumber + index`) instead of starting at 1, so a
+   * code excerpt reads with its real line numbers. `highlightLines` uses the
+   * same file coordinates. Values below 1 clamp to 1.
+   * @default 1
+   */
+  startLineNumber?: number;
+  /** 1-indexed line numbers to highlight, in the same file coordinates as the gutter (see `startLineNumber`). Out-of-range entries render no highlight. */
   highlightLines?: number[];
   /**
    * Render the code as a unified diff over `language`: lines starting with
@@ -792,6 +808,7 @@ function SpanCodeContent({
   sizeStyle,
   hasLineNumbers,
   maxDigits,
+  startLineNumber,
 }: {
   lines: string[];
   tokenLines: TokenLine[];
@@ -802,7 +819,10 @@ function SpanCodeContent({
   sizeStyle: stylex.StyleXStyles;
   hasLineNumbers: boolean;
   maxDigits: number;
+  startLineNumber: number;
 }) {
+  // Syncs the document's ::highlight() stylesheet. The rules go in one time,
+  // before layout reads.
   useInsertionEffect(() => {
     ensureHighlightStyles();
   }, []);
@@ -861,6 +881,7 @@ function SpanCodeContent({
         diffKinds,
         renderLineContent,
         hasLineNumbers,
+        startLineNumber,
       )}
     </code>
   );
@@ -879,6 +900,7 @@ function RangeCodeContent({
   sizeStyle,
   hasLineNumbers,
   maxDigits,
+  startLineNumber,
 }: {
   lines: string[];
   tokenLines: TokenLine[];
@@ -888,6 +910,7 @@ function RangeCodeContent({
   sizeStyle: stylex.StyleXStyles;
   hasLineNumbers: boolean;
   maxDigits: number;
+  startLineNumber: number;
 }) {
   const codeRef = useRef<HTMLElement>(null);
 
@@ -902,6 +925,8 @@ function RangeCodeContent({
     }
   }, []);
 
+  // Syncs the CSS.highlights registry with the token ranges. It applies them in
+  // chunks.
   useEffect(() => {
     if (!hasHighlightAPI()) {
       return;
@@ -939,6 +964,7 @@ function RangeCodeContent({
         diffKinds,
         renderLineContent,
         hasLineNumbers,
+        startLineNumber,
       )}
     </code>
   );
@@ -963,6 +989,7 @@ export function CodeBlock({
   title,
   hasLanguageLabel = true,
   hasLineNumbers = false,
+  startLineNumber = 1,
   highlightLines,
   isDiff = false,
   hasCopyButton = true,
@@ -1019,6 +1046,12 @@ export function CodeBlock({
     customTokenizer,
   );
   const diffKinds = diff?.kinds ?? null;
+  // File coordinates for the gutter and highlights. Values below 1 clamp to
+  // 1 so the gutter never shows a 0 or negative line number.
+  const effectiveStartLineNumber =
+    Number.isFinite(startLineNumber) && startLineNumber > 1
+      ? Math.floor(startLineNumber)
+      : 1;
   const highlightSet = useMemo(
     () => (highlightLines ? new Set(highlightLines) : null),
     [highlightLines],
@@ -1032,8 +1065,10 @@ export function CodeBlock({
   }, [code, copy, onCopy]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
-  // Digits in the largest line number — sizes the gutter column width.
-  const maxLineDigits = String(lines.length).length;
+  // Digits in the largest visible line number — sizes the gutter column width.
+  const maxLineDigits = String(
+    effectiveStartLineNumber + lines.length - 1,
+  ).length;
   // With the diff layer on, the label and viewport name say so: `diff` over
   // plaintext, `tsx diff` over a language — so a diff keeps its header,
   // collapse control, and a name that still matches a `diff` fence.
@@ -1219,6 +1254,7 @@ export function CodeBlock({
             sizeStyle={sizeStyle}
             hasLineNumbers={hasLineNumbers}
             maxDigits={maxLineDigits}
+            startLineNumber={effectiveStartLineNumber}
           />
         ) : (
           <RangeCodeContent
@@ -1230,6 +1266,7 @@ export function CodeBlock({
             sizeStyle={sizeStyle}
             hasLineNumbers={hasLineNumbers}
             maxDigits={maxLineDigits}
+            startLineNumber={effectiveStartLineNumber}
           />
         )}
       </div>

package/src/CommandPalette/CommandPalette.tsx

@@ -509,6 +509,7 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const runSearchRef = useRef(runSearch);
   runSearchRef.current = runSearch;
 
+  // Syncs the search source with `isOpen`. An open runs the empty-query search.
   useEffect(() => {
     if (isOpen) {
       runSearchRef.current('');

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -155,6 +155,7 @@ export function CommandPaletteItem({
     (ctx ? ctx.highlightedIndex === itemIndex && itemIndex >= 0 : false);
   const isSelected = controlledSelected ?? (ctx ? ctx.value === value : false);
 
+  // Syncs the scroll position of a standalone item with `isHighlighted`.
   useEffect(() => {
     // Inside CommandPalette the shared useHighlightedOptionScroll (via
     // useCombobox) is the single scrollIntoView owner (#6077); a second owner

package/src/ComplexSelector/ComplexSelector.tsx

@@ -35,6 +35,7 @@ import {
 } from '../Field/fieldParts';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {mergeRefs} from '../utils/mergeRefs';
+import {isFocusLost} from '../utils/focusReturn';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {Field, inputWrapperStyles} from '../Field';
@@ -347,7 +348,10 @@ export interface ComplexSelectorRenderState {
 export interface ComplexSelectorHandle {
   /** Open the selector surface. No-op when disabled or already open. */
   open(): void;
-  /** Close the selector surface. Restores focus to the trigger. */
+  /**
+   * Close the selector surface. Focus returns to the trigger only when it
+   * would otherwise be lost; a caller-rendered trigger always gets it back.
+   */
   close(): void;
   /** Toggle the selector surface open or closed. */
   toggle(): void;
@@ -630,12 +634,22 @@ export function ComplexSelector<Value>({
     onOpenChange?.(true);
   }, [onOpenChange]);
 
+  // The popup's content element, read when it closes.
+  const popupContentRef = useRef<HTMLElement | null>(null);
+  const hasCallerTrigger = renderTrigger != null;
   const handlePopoverHide = useCallback(() => {
-    // Focus is restored first so a consumer that moves focus elsewhere from
-    // the callback wins, instead of being overwritten a line later.
-    triggerRef.current?.focus();
+    const trigger = triggerRef.current;
+    // A press that moved focus to another control keeps it there. A caller's
+    // control always gets focus back. Focus moves before the callback, so a
+    // consumer that moves it from the callback wins.
+    if (
+      hasCallerTrigger ||
+      isFocusLost(popupContentRef.current, trigger?.ownerDocument)
+    ) {
+      trigger?.focus();
+    }
     onOpenChange?.(false);
-  }, [onOpenChange]);
+  }, [hasCallerTrigger, onOpenChange]);
 
   const popover = usePopover({
     dialogLabel: label,
@@ -645,6 +659,7 @@ export function ComplexSelector<Value>({
     onShow: handlePopoverShow,
     onHide: handlePopoverHide,
   });
+  popupContentRef.current = popover.contentRef.current;
 
   const isOpen = popover.isOpen;
 

package/src/ContextMenu/ContextMenu.tsx

@@ -712,14 +712,14 @@ export function ContextMenu({
   );
   const handleTriggerTouchEnd = useCallback(
     (event: React.TouchEvent<HTMLElement>) => {
-      handleLongPressTouchEnd();
+      handleLongPressTouchEnd(event);
       onTouchEndProp?.(event);
     },
     [handleLongPressTouchEnd, onTouchEndProp],
   );
   const handleTriggerTouchCancel = useCallback(
     (event: React.TouchEvent<HTMLElement>) => {
-      handleLongPressTouchCancel();
+      handleLongPressTouchCancel(event);
       onTouchCancelProp?.(event);
     },
     [handleLongPressTouchCancel, onTouchCancelProp],

package/src/DateInput/MonthScroller.tsx

@@ -51,7 +51,10 @@ import {
   borderVars,
 } from '../theme/tokens.stylex';
 import {focusOutlineStyles} from '../utils';
-import {plainDateFormatStandaloneMonthYear} from '../utils/plainDate';
+import {
+  plainDateFormatDayNumber,
+  plainDateFormatStandaloneMonthYear,
+} from '../utils/plainDate';
 import {
   type DayOfWeek,
   type ISODateString,
@@ -591,6 +594,7 @@ export function MonthScroller({
    * it cannot oscillate.
    */
   const settleFrameRef = useRef<number | undefined>(undefined);
+  // Releases the settle frame on unmount.
   useEffect(
     () => () => {
       if (settleFrameRef.current != null) {
@@ -663,6 +667,8 @@ export function MonthScroller({
   // rAF-throttled: a touch scroll fires far more scroll events than frames,
   // and all this does is move a label and widen a window.
   const frameRef = useRef<number | undefined>(undefined);
+  // Syncs scroll, touch and wheel listeners on the scroller with its measured
+  // height.
   useEffect(() => {
     const scroller = scrollerRef.current;
     // Not before the height is known. A listener attached while it was zero
@@ -1012,7 +1018,7 @@ function MonthPane({
                       isToday && styles.puckToday,
                       isSelected && styles.puckSelected,
                     )}>
-                    {day.dayNumber}
+                    {plainDateFormatDayNumber(day.dayNumber, locale)}
                   </span>
                 </button>
               </div>