@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/src/ClickableCard/ClickableCard.tsx

@@ -39,7 +39,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -48,6 +48,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
 // =============================================================================
@@ -297,7 +298,7 @@ export function ClickableCard({
 
   return (
     <Card
-      ref={mergeRefs(ref, containerRef)}
+      ref={useMergedRefs(ref, containerRef)}
       width={width}
       height={height}
       maxWidth={maxWidth}

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -95,6 +95,12 @@ export const docs = {
       type: 'SyntaxThemeDefinition',
       description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
     },
+    {
+      name: 'highlightMode',
+      type: "'auto' | 'ranges' | 'spans'",
+      description: 'Syntax highlighting rendering mode.',
+      default: "'auto'",
+    },
     {
       name: 'isCollapsible',
       type: 'boolean',

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -16,7 +16,7 @@ import {useCallback, useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {
   colorVars,
   typeScaleVars,
@@ -29,6 +29,7 @@ import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   wrapper: {
     display: 'flex',
@@ -216,7 +217,7 @@ export function CommandPaletteInput({
         <Icon icon="search" size="sm" color="inherit" />
       </span>
       <input
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         type="text"
         role="combobox"
         aria-expanded={ctx?.isOpen ?? true}

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -14,7 +14,7 @@
 import {useCallback, useEffect, useMemo, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {
   colorVars,
@@ -27,6 +27,7 @@ import {useCommandPaletteContext} from './CommandPaletteContext';
 import {useDialogContext} from '../Dialog/DialogContext';
 import {themeProps} from '../utils/themeProps';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const HOVER_HOVER = '@media (hover: hover)';
 
 const styles = stylex.create({
@@ -191,7 +192,7 @@ export function CommandPaletteItem({
 
   return (
     <div
-      ref={mergeRefs(ref, itemRef)}
+      ref={useMergedRefs(ref, itemRef)}
       {...props}
       id={ctx && itemIndex >= 0 ? ctx.getItemId(itemIndex) : undefined}
       role="option"

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -58,6 +58,11 @@ export const docs = {
       description: 'Accessible name for the menu surface, announced when it opens.',
       default: "'Context menu'",
     },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description: 'Callback fired when the menu opens or closes.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/ContextMenu/ContextMenu.tsx

@@ -63,7 +63,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs, isImeKeyEvent} from '../utils';
+import {mergeProps, isImeKeyEvent} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -75,6 +75,7 @@ import type {
   DropdownMenuSection,
 } from '../DropdownMenu/DropdownMenu';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   // Trigger wrapper: suppress the iOS long-press callout/selection so the
   // long-press opens our context menu instead of the native text/callout UI.
@@ -467,7 +468,7 @@ export function ContextMenu({
   return (
     <>
       <div
-        ref={mergeRefs(ref, triggerRef)}
+        ref={useMergedRefs(ref, triggerRef)}
         {...triggerProps}
         onContextMenu={handleContextMenu}
         {...longPressHandlers}
@@ -482,7 +483,7 @@ export function ContextMenu({
         )}>
         {children}
         <span
-          ref={mergeRefs(cursorAnchorRef, layer.ref)}
+          ref={useMergedRefs(cursorAnchorRef, layer.ref)}
           aria-hidden="true"
           {...mergeProps(stylex.props(styles.cursorAnchor), {
             style: {

package/src/DateInput/DateInput.tsx

@@ -161,7 +161,7 @@ export type {
   InputStatus as DateInputStatus,
   InputStatusType as DateInputStatusType,
 } from '../Field';
-import {mergeProps, mergeRefs, isFocusDetached} from '../utils';
+import {mergeProps, isFocusDetached} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -169,6 +169,7 @@ import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {stableClassName} from '../naming';
 import {useTranslator, InternationalizationContext} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export interface DateInputProps extends Omit<
   BaseProps,
   'onChange' | 'defaultValue'
@@ -739,7 +740,7 @@ function PointerDateField({
         />
       </button>
       <input
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         id={id}
         type="text"
         role="combobox"

package/src/DateInput/DateInputTouch.test.tsx

@@ -419,6 +419,42 @@ describe('DateInput — field parity', () => {
     expect(onChange).toHaveBeenCalledWith(undefined);
   });
 
+  it('returns focus to the field without letting the page scroll', async () => {
+    // Clearing unmounts the clear button, and focusing another element in the
+    // same task as that unmount makes iOS Safari scroll the document to the
+    // top. Measured on the iOS 26 simulator against the live docsite, field at
+    // scrollY 2055: synchronous focus lands at 0, deferred focus stays at
+    // 2055. `preventScroll` alone does not fix it, so both halves are
+    // asserted: the focus is deferred past the unmount, and it is passed
+    // preventScroll. jsdom implements no scrolling, so the guard is asserted
+    // at the call.
+    vi.useFakeTimers();
+    try {
+      render(
+        <DateInput
+          label="Ship date"
+          value="2026-03-21"
+          hasClear
+          onChange={() => {}}
+        />,
+      );
+      const input = field();
+      const focus = vi.spyOn(input, 'focus');
+
+      fireEvent.click(screen.getByRole('button', {name: /Clear Ship date/}));
+
+      // Not synchronous — that is the whole point.
+      expect(focus).not.toHaveBeenCalled();
+
+      vi.runAllTimers();
+
+      expect(focus).toHaveBeenCalledWith({preventScroll: true});
+      focus.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('does not open the picker until the field is tapped', () => {
     withLayout(() => {
       render(<DateInput label="Ship date" onChange={() => {}} />);

package/src/DateInput/TouchDateField.tsx

@@ -67,7 +67,7 @@ import {
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
 } from '../Field';
-import {useInputStatusIcon} from '../hooks';
+import {useInputStatusIcon, useMergedRefs} from '../hooks';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {Icon} from '../Icon';
 import {IconButton} from '../IconButton';
@@ -96,7 +96,6 @@ import {
   getInputARIA,
   isImeKeyEvent,
   mergeProps,
-  mergeRefs,
   rtlStyles,
   themeProps,
   formatSharedDate,
@@ -557,6 +556,7 @@ export function TouchDateField({
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const mergedInputRef = useMergedRefs(ref, inputRef);
   const inputGroup = useInputGroup();
 
   const [, startTransition] = useTransition();
@@ -599,6 +599,16 @@ export function TouchDateField({
   const [isSheetOpen, setIsSheetOpen] = useState(false);
   const [isWheelOpen, setIsWheelOpen] = useState(false);
   const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
+  // Pending focus handoff from the clear button; see handleClear.
+  const clearFocusTimerRef = useRef<number | null>(null);
+  useEffect(
+    () => () => {
+      if (clearFocusTimerRef.current != null) {
+        clearTimeout(clearFocusTimerRef.current);
+      }
+    },
+    [],
+  );
 
   const today = useMemo(() => plainDateToday(), []);
   const selectedDate = useMemo(
@@ -708,7 +718,31 @@ export function TouchDateField({
 
   const handleClear = useCallback(() => {
     fireChange(undefined);
-    inputRef.current?.focus();
+    // Focus goes back to the field on the NEXT task, not synchronously.
+    //
+    // Clearing unmounts this button (it only renders while there is a value),
+    // and focusing another element in the same task as that unmount makes iOS
+    // Safari scroll the whole document to the top — the user is thrown from
+    // wherever the field sat to the start of the page. Measured on the iOS 26
+    // simulator against the live docsite, field at scrollY 2055: synchronous
+    // focus lands at 0, deferred focus stays at 2055.
+    //
+    // `preventScroll` alone does NOT fix it (verified: still 0) — this is not
+    // the browser's ordinary scroll-the-focused-element-into-view step, so the
+    // deferral is the load-bearing half. It is kept because the reveal scroll
+    // is real too, and unwanted for the same reason: the field the user just
+    // tapped is already on screen (+12px on a plain page without it).
+    //
+    // Skipping the focus entirely would also stop the scroll, but then focus
+    // dies with the unmounting button and lands on <body>.
+    const field = inputRef.current;
+    if (field == null) {
+      return;
+    }
+    clearFocusTimerRef.current = window.setTimeout(() => {
+      clearFocusTimerRef.current = null;
+      field.focus({preventScroll: true});
+    }, 0);
   }, [fireChange]);
 
   /**
@@ -1135,7 +1169,7 @@ export function TouchDateField({
         />
       </button>
       <input
-        ref={mergeRefs(ref, inputRef)}
+        ref={mergedInputRef}
         id={id}
         type="text"
         role="combobox"

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -123,6 +123,12 @@ export const docs = {
         'Minutes to add or subtract when using arrow keys in the time input.',
       default: '1',
     },
+    {
+      name: 'timeOptionInterval',
+      type: '5 | 10 | 15 | 30 | 60',
+      description:
+        'Minute cadence for a dropdown of preset times on the time portion. Set it to turn the time field into a combobox listing every valid time at that cadence (60 gives a 12 AM to 11 PM list). Omitted, the time field stays a plain text input and gains no combobox semantics. Typed entry keeps working either way, so a time between two options is still reachable. Independent of timeIncrement, which governs arrow-key stepping.',
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -206,6 +212,8 @@ export const docs = {
       },
       {className: 'astryx-date-time-input-toggle-icon', states: ['state']},
       {className: 'astryx-date-time-input-clock-icon'},
+      {className: 'astryx-date-time-input-time-listbox'},
+      {className: 'astryx-date-time-input-time-option'},
     ],
   },
   usage: {
@@ -283,6 +291,12 @@ export const docs = {
         description:
           'A text input for entering the time, displayed beside the date input.',
       },
+      {
+        name: 'Time options popover',
+        required: false,
+        description:
+          'A list of preset times at the timeOptionInterval cadence, shown when that prop is set and the time input is clicked or opened with Alt+ArrowDown.',
+      },
       {
         name: 'Clear button',
         required: false,
@@ -512,6 +526,8 @@ export const docsZh = {
       },
       {className: 'astryx-date-time-input-toggle-icon', states: ['state']},
       {className: 'astryx-date-time-input-clock-icon'},
+      {className: 'astryx-date-time-input-time-listbox'},
+      {className: 'astryx-date-time-input-time-option'},
     ],
   },
 };
@@ -585,6 +601,8 @@ export const docsDense = {
     hasSeconds: 'include seconds in time portion',
     hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
     timeIncrement: 'minutes to add/subtract on arrow keys in time input',
+    timeOptionInterval:
+      'minute cadence for a preset-time dropdown on the time input; omitted = plain text input, no combobox. typed entry still works',
     hasClear: 'Shows clear button when datetime is set',
     placeholder: 'date-portion placeholder when empty',
     timePlaceholder: 'time-portion placeholder when empty',