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

package/src/CheckboxList/CheckboxList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file CheckboxList.tsx
- * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext
+ * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext, requiredGroup
  * @output Exports CheckboxList component, CheckboxListProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -43,6 +43,7 @@ import {
   CheckboxListContext,
   type CheckboxListContextValue,
 } from './CheckboxListContext';
+import {createRequiredGroup} from './requiredGroup';
 
 const EMPTY_ARRAY: string[] = [];
 
@@ -65,6 +66,24 @@ 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;
+  /**
+   * Whether the group needs at least one checked box. Shows the required
+   * indicator after the group label by the same rules as every input field.
+   * While no box is checked, the browser blocks submit and moves focus to
+   * the first box that is neither disabled nor read-only. A disabled or
+   * read-only group requires nothing. Show your own error text through
+   * `status`.
+   * Mutually exclusive with isOptional.
+   * @default false
+   */
+  isRequired?: boolean;
   /**
    * Status indicator for the checkbox group.
    * When set with a message, displays a colored message box below the group.
@@ -153,6 +172,8 @@ export function CheckboxList({
   label,
   isLabelHidden = false,
   description,
+  isOptional = false,
+  isRequired = false,
   status,
   value,
   onChange,
@@ -185,6 +206,18 @@ export function CheckboxList({
   const descriptionID = useId();
   const statusMessageID = useId();
 
+  const requiredGroup = useMemo(
+    () => (isRequired ? createRequiredGroup() : undefined),
+    [isRequired],
+  );
+  const observeRequiredGroup = useCallback(
+    (container: HTMLDivElement | null) =>
+      container != null && requiredGroup != null
+        ? requiredGroup.observe(container)
+        : undefined,
+    [requiredGroup],
+  );
+
   const [, startTransition] = useTransition();
   const isCollectionMode = value !== undefined;
   const effectiveValue = value ?? EMPTY_ARRAY;
@@ -248,6 +281,7 @@ export function CheckboxList({
       isReadOnly,
       isInvalid: status?.type === 'error',
       loadingValues,
+      requiredGroup,
     }),
     [
       isCollectionMode,
@@ -259,6 +293,7 @@ export function CheckboxList({
       isReadOnly,
       status?.type,
       loadingValues,
+      requiredGroup,
     ],
   );
 
@@ -270,6 +305,8 @@ export function CheckboxList({
       inputID={inputID}
       labelID={labelID}
       isGroupLabel
+      isOptional={isOptional}
+      isRequired={isRequired}
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
       status={
@@ -293,7 +330,11 @@ export function CheckboxList({
           {...rest}
           // The disabled-message tooltip anchors here; its handlers are gated
           // internally by isEnabled, so attaching unconditionally is safe.
-          ref={useMergedRefs(ref, disabledMessageTooltip.ref)}
+          ref={useMergedRefs(
+            ref,
+            disabledMessageTooltip.ref,
+            observeRequiredGroup,
+          )}
           {...mergeProps(
             stylex.props(controlXstyle),
             controlClassName,

package/src/CheckboxList/CheckboxListContext.tsx

@@ -4,12 +4,14 @@
 
 /**
  * @file CheckboxListContext.tsx
- * @input Uses the private layer-scoped context factory
+ * @input Uses the private layer-scoped context factory and the RequiredGroup
+ *   type
  * @output Exports CheckboxListContext for parent-child communication
  * @position Internal context; consumed by CheckboxList.tsx and CheckboxListItem.tsx
  */
 
 import {createLayerScopedContext} from '../Layer/layerScopedContext';
+import type {RequiredGroup} from './requiredGroup';
 
 export interface CheckboxListContextValue {
   value?: string[];
@@ -49,6 +51,12 @@ export interface CheckboxListContextValue {
    * when idle.
    */
   loadingValues?: ReadonlyArray<string>;
+  /**
+   * Present when the list is `isRequired`. Each item registers its checkbox,
+   * so that while no box is checked the first enabled box carries native
+   * `required`.
+   */
+  requiredGroup?: RequiredGroup;
 }
 
 export const CheckboxListContext =

package/src/CheckboxList/CheckboxListItem.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, useId, useRef, type ReactNode} from 'react';
+import {use, useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
@@ -30,6 +30,7 @@ import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
 import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
 import {joinAriaIDs} from '../utils/inputAria';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {ItemAlign} from '../Item';
 import {
   registerEnglishFallback,
@@ -284,6 +285,26 @@ export function CheckboxListItem({
   const checkboxRef = useRef<HTMLInputElement | null>(null);
   const hasRowInteraction = isInteractive || onClickProp != null;
 
+  // A required group decides which box carries native `required` from the
+  // state of every box. A change to this box's state registers it again.
+  const requiredGroup = ctx?.requiredGroup;
+  const isBoxChecked = resolvedChecked === true;
+  const isBoxEnabled = !effectiveDisabled && !effectiveReadOnly;
+  const registerWithRequiredGroup = useCallback(
+    (input: HTMLInputElement | null) =>
+      input != null && requiredGroup != null
+        ? requiredGroup.register(input, {
+            isChecked: isBoxChecked,
+            isEnabled: isBoxEnabled,
+          })
+        : undefined,
+    [requiredGroup, isBoxChecked, isBoxEnabled],
+  );
+  const checkboxInputRef = useMergedRefs(
+    checkboxRef,
+    registerWithRequiredGroup,
+  );
+
   // 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
@@ -349,7 +370,7 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <DescribedCheckboxInput
-          ref={checkboxRef}
+          ref={checkboxInputRef}
           label={checkboxLabel}
           aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
           isLabelHidden

package/src/CheckboxList/requiredGroup.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file requiredGroup.ts
+ * @input The checkbox inputs of a required CheckboxList and each box's state;
+ *   Core's shared mutation observer
+ * @output Exports createRequiredGroup, RequiredGroup, and RequiredGroupBox
+ * @position Internal to CheckboxList; CheckboxList creates one for an
+ *   `isRequired` group and CheckboxListItem registers its checkbox with it
+ *
+ * The browser has no required state for a group of checkboxes. While no box
+ * is checked, the first enabled box carries native `required`. The browser
+ * then blocks submit and moves focus to that box with its own message. Once
+ * any box is checked, no box carries `required`.
+ */
+
+import {observeMutations} from '../utils/sharedMutationObserver';
+
+/** The state of one box that decides which box carries `required`. */
+export interface RequiredGroupBox {
+  isChecked: boolean;
+  /** False for a disabled or read-only box, which the user cannot check. */
+  isEnabled: boolean;
+}
+
+export interface RequiredGroup {
+  /**
+   * Adds a checkbox with its state and updates `required` on every box.
+   * Returns a function that removes the checkbox, clears its `required`, and
+   * updates the rest. An item registers again when its state changes.
+   */
+  register: (input: HTMLInputElement, box: RequiredGroupBox) => () => void;
+  /**
+   * Updates `required` when the group's options move, for example after a
+   * keyed reorder, which registers no box again. Returns a function that
+   * stops it.
+   */
+  observe: (container: HTMLElement) => () => void;
+}
+
+const MOVE_OPTIONS: MutationObserverInit = {childList: true, subtree: true};
+
+function byDocumentOrder(a: HTMLInputElement, b: HTMLInputElement): number {
+  return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
+    ? -1
+    : 1;
+}
+
+export function createRequiredGroup(): RequiredGroup {
+  const boxes = new Map<HTMLInputElement, RequiredGroupBox>();
+
+  function update() {
+    const ordered = [...boxes.keys()].sort(byDocumentOrder);
+    const isEmpty = ![...boxes.values()].some(box => box.isChecked);
+    const target = isEmpty
+      ? ordered.find(input => boxes.get(input)?.isEnabled === true)
+      : undefined;
+    for (const input of ordered) {
+      input.required = input === target;
+    }
+  }
+
+  return {
+    register(input, box) {
+      boxes.set(input, box);
+      update();
+      return () => {
+        boxes.delete(input);
+        input.required = false;
+        update();
+      };
+    },
+    observe(container) {
+      return observeMutations(container, MOVE_OPTIONS, update);
+    },
+  };
+}

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>