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

package/src/Button/Button.tsx

@@ -53,6 +53,7 @@ import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
+import {PressGroupContext} from '../hooks/pressGroupContext';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import {
@@ -77,6 +78,12 @@ import {isRenderable} from '../utils/isRenderable';
 
 registerEnglishFallback(english);
 
+/**
+ * Written by the press controller or a group's tracker while a press is
+ * believed. Typed `string`, so StyleX reads it as a computed key.
+ */
+const PRESSED_ON: string = '[data-astryx-press="on"]';
+
 /**
  * Base button styles
  * Pseudo-classes are nested within properties per StyleX recommendation:
@@ -138,7 +145,19 @@ const styles = stylex.create({
         default: 'scale(0.98)',
         '@media (pointer: coarse)': 'scale(1)',
       },
-      '[data-astryx-press="on"]': 'scale(0.98)',
+      [PRESSED_ON]: 'scale(0.98)',
+    },
+  },
+  // A tracked action's own `:active` image paints nothing: the tracker paints
+  // the action under the pointer, which need not be the one pressed first.
+  trackedOverlay: {
+    backgroundSize: {default: null, [`:active:not(${PRESSED_ON})`]: '0 0'},
+  },
+  // A tracked action's press is painted by its group's tracker alone.
+  pressableTracked: {
+    transform: {
+      default: 'scale(1)',
+      [PRESSED_ON]: 'scale(0.98)',
     },
   },
   inactive: {
@@ -147,7 +166,7 @@ const styles = stylex.create({
     transform: {
       default: 'none',
       ':active': 'none',
-      '[data-astryx-press="on"]': 'none',
+      [PRESSED_ON]: 'none',
     },
   },
   disabled: {
@@ -160,7 +179,7 @@ const styles = stylex.create({
     backgroundImage: {
       default: 'none',
       ':active': 'none',
-      '[data-astryx-press="on"]': 'none',
+      [PRESSED_ON]: 'none',
     },
   },
   iconOnly: {
@@ -632,6 +651,7 @@ export function Button({
   const t = useComponentTranslator();
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
+  const isGroupTracked = use(PressGroupContext);
   const inputGroup = useInputGroup();
 
   const [isPending, startTransition] = useTransition();
@@ -760,11 +780,13 @@ export function Button({
     sizeStyles[size],
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
+    isGroupTracked && styles.trackedOverlay,
     buttonDisabled && styles.inactive,
     isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
-    !buttonGroup && styles.pressable,
+    !buttonGroup &&
+      (isGroupTracked ? styles.pressableTracked : styles.pressable),
     buttonGroup &&
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.horizontal

package/src/Calendar/Calendar.tsx

@@ -61,7 +61,10 @@ 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';
@@ -104,8 +107,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 +521,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;
         }
@@ -961,20 +965,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 +1166,7 @@ function MonthGrid({
                 <div
                   role="rowheader"
                   {...stylex.props(monthGridStyles.weekNumber)}>
-                  {weekNum}
+                  {plainDateFormatDayNumber(weekNum, locale)}
                 </div>
               )}
               {week.map((day, dayIndex) => {
@@ -1422,7 +1433,7 @@ function DayCell({
             state.effectivelyDisabled && dayCellTheme.dayDisabled,
           ),
         )}>
-        {dayNumber}
+        {plainDateFormatDayNumber(dayNumber, locale)}
       </button>
     </div>
   );

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

@@ -529,6 +529,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 +651,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/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