@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Chat/ChatMessageList.tsx

@@ -10,7 +10,8 @@
  *
  * Renders a container with role="log" for chat message histories.
  * Handles density context, configurable gap, empty state,
- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
+ * a configurable spacer (align) that pushes messages to the bottom,
+ * and an infinite scroll sentinel.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
  * ChatLayout. When used standalone (without a layout), the list
@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    */
   gap?: SpacingStep;
 
+  /**
+   * Vertical alignment of messages when the list is shorter than its
+   * container.
+   *
+   * - `'bottom'` (default): a spacer fills the free space and pushes
+   *   messages to the bottom, so a short conversation sits just above the
+   *   composer — the familiar messaging-app layout.
+   * - `'top'`: the spacer is omitted, so messages start at the top and grow
+   *   downward — better for document-style or log-style lists.
+   *
+   * This only changes the resting position of a non-full list. Once messages
+   * overflow the container the spacer collapses to zero in both modes, so
+   * ChatLayout auto-scroll-to-bottom behavior is identical either way.
+   *
+   * @default 'bottom'
+   */
+  align?: 'top' | 'bottom';
+
   /**
    * Whether an assistant message is actively streaming into the list.
    *
@@ -183,7 +202,8 @@ const gapStyles = stylex.create({
  *
  * Renders messages in a flex column with density-based spacing.
  * Override gap to tune row spacing separately from density.
- * A spacer pushes content to the bottom when the list isn't full.
+ * By default a spacer pushes content to the bottom when the list isn't full;
+ * set `align='top'` to start messages at the top instead.
  * Supports loading older messages via `scrollToTopAction`.
  *
  * Auto-scroll and the scroll-to-bottom button are owned by
@@ -204,6 +224,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  align = 'bottom',
   isStreaming = false,
   xstyle,
   className,
@@ -291,8 +312,11 @@ export function ChatMessageList({
             </div>
           )}
 
-          {/* Spacer pushes messages to bottom when list isn't full */}
-          <div {...stylex.props(styles.spacer)} aria-hidden />
+          {/* Spacer pushes messages to bottom when the list isn't full.
+              Omitted for top alignment so messages start at the top. */}
+          {align === 'bottom' && (
+            <div {...stylex.props(styles.spacer)} aria-hidden />
+          )}
 
           {/* Messages or empty state */}
           {hasChildren ? (

package/src/Chat/ChatTokenizedText.tsx

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts
+ * - /packages/core/src/Chat/ChatComposerInput.tsx (token alignment must match,
+ *   or a token moves when the message is sent)
  * - /packages/cli/assets/templates/blocks/components/ChatTokenizedText/ (block examples)
  */
 
@@ -33,6 +35,10 @@ const styles = stylex.create({
   root: {
     display: 'inline',
   },
+  token: {
+    display: 'inline-flex',
+    verticalAlign: 'middle',
+  },
 });
 
 // =============================================================================
@@ -156,16 +162,17 @@ function renderTokens(text: string, tokens: ChatComposerToken[]): ReactNode[] {
     const token = tokenMap.get(matched);
     if (token) {
       parts.push(
-        isCustomToken(token) ? (
-          <span key={`${matched}-${match.index}`}>{token.render()}</span>
-        ) : (
-          <Badge
-            key={`${matched}-${match.index}`}
-            label={token.label}
-            variant={token.variant}
-            icon={token.icon}
-          />
-        ),
+        <span key={`${matched}-${match.index}`} {...stylex.props(styles.token)}>
+          {isCustomToken(token) ? (
+            token.render()
+          ) : (
+            <Badge
+              label={token.label}
+              variant={token.variant}
+              icon={token.icon}
+            />
+          )}
+        </span>,
       );
     }
 

package/src/Chat/useChatComposerTokens.ts

@@ -120,7 +120,7 @@ export function useChatComposerTokens({
       span.setAttribute('data-astryx-token-id', id);
       span.contentEditable = 'false';
       span.style.display = 'inline-flex';
-      span.style.verticalAlign = 'baseline';
+      span.style.verticalAlign = 'middle';
 
       range.deleteContents();
       range.insertNode(span);

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -133,6 +133,7 @@ export const docs = {
       {className: 'astryx-checkbox-input', visualProps: ['size']},
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
   usage: {
@@ -209,6 +210,7 @@ export const docsZh = {
       },
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
 };

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -719,3 +719,18 @@ describe('focus ring ownership (WCAG 2.4.7)', () => {
     expect(indicatorOf(container).style.outlineStyle).toBe('');
   });
 });
+
+describe('label theme target', () => {
+  it('names its own label so a theme can style it apart from a field label', () => {
+    // The control knows this label shares a row with it; the label does not.
+    // Both classes land on the one element, so a theme reaches every label
+    // through `astryx-field-label` and only this kind through
+    // `astryx-checkbox-label`.
+    render(
+      <CheckboxInput label="Notify me" value={false} onChange={() => {}} />,
+    );
+    const label = screen.getByText('Notify me').closest('label');
+    expect(label).toHaveClass('astryx-field-label');
+    expect(label).toHaveClass('astryx-checkbox-label');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -44,7 +44,7 @@ import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
@@ -52,6 +52,7 @@ import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
 import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   container: {
     display: 'flex',
@@ -409,7 +410,7 @@ export function CheckboxInput({
           {...focusProps}>
           <input
             {...rest}
-            ref={mergeRefs(
+            ref={useMergedRefs(
               ref,
               indeterminateRef,
               disabledMessageTooltip.positionRef,
@@ -477,6 +478,11 @@ export function CheckboxInput({
         </div>
         <div {...stylex.props(styles.labelWrapper)}>
           <FieldLabel
+            // A checkbox's label shares a row with its control, unlike a form
+            // field's label above its input. Naming the label rather than the
+            // arrangement means a theme asks for the thing it wants, and the
+            // component that actually knows what this is says so.
+            {...themeProps('checkbox-label')}
             label={label}
             inputID={id}
             isLabelHidden={isLabelHidden}

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',
@@ -141,10 +147,16 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-code', visualProps: ['color']},
-      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
-      {className: 'astryx-codeblock-copy-button'},
+      {className: 'astryx-code-block', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-header', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-title', visualProps: ['size', 'language']},
+      {className: 'astryx-code-block-copy-button'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block'},
+      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block-header'},
+      {className: 'astryx-codeblock-title', visualProps: ['size', 'language'], deprecatedFor: 'code-block-title'},
+      {className: 'astryx-codeblock-copy-button', deprecatedFor: 'code-block-copy-button'},
     ],
     vars: [
       {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},

package/src/CodeBlock/CodeBlock.test.tsx

@@ -396,3 +396,40 @@ describe('CodeBlock', () => {
     });
   });
 });
+
+describe('CodeBlock theme target names', () => {
+  it('renders the deprecated classes beside the current ones', () => {
+    const {container} = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        title="example.js"
+      />,
+    );
+    expect(container.querySelector('.astryx-code-block')).toHaveClass(
+      'astryx-codeblock',
+    );
+    expect(container.querySelector('.astryx-code-block-header')).toHaveClass(
+      'astryx-codeblock-header',
+    );
+    expect(container.querySelector('.astryx-code-block-title')).toHaveClass(
+      'astryx-codeblock-title',
+    );
+    expect(screen.getByRole('button', {name: 'Copy code'})).toHaveClass(
+      'astryx-code-block-copy-button',
+    );
+  });
+
+  it('reaches the header and title through the current defineTheme keys', () => {
+    const theme = defineTheme({
+      name: 'code-block-header-target-test',
+      components: {
+        'code-block-header': {base: {paddingBlock: 'var(--spacing-1)'}},
+        'code-block-title': {base: {fontSize: 'var(--text-body-size)'}},
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-code-block-header');
+    expect(css).toContain('.astryx-code-block-title');
+  });
+});

package/src/CodeBlock/CodeBlock.tsx

@@ -810,14 +810,20 @@ export function CodeBlock({
         void handleCopy();
       }}
       xstyle={[styles.copyButton, !showHeader && styles.copyButtonAbsolute]}
-      {...themeProps('codeblock-copy-button')}
+      {...themeProps('code-block-copy-button', undefined, {
+        legacyNames: ['codeblock-copy-button'],
+      })}
     />
   ) : null;
 
   const headerEl = showHeader ? (
     <div
       {...mergeProps(
-        themeProps('codeblock-header', {size, language, container}),
+        themeProps(
+          'code-block-header',
+          {size, language, container},
+          {legacyNames: ['codeblock-header']},
+        ),
         stylex.props(
           styles.headerRow,
           hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
@@ -845,7 +851,11 @@ export function CodeBlock({
         )}>
         <span
           {...mergeProps(
-            themeProps('codeblock-title', {size, language}),
+            themeProps(
+              'code-block-title',
+              {size, language},
+              {legacyNames: ['codeblock-title']},
+            ),
             stylex.props(styles.headerTitle),
           )}>
           {canCollapse && (
@@ -917,7 +927,13 @@ export function CodeBlock({
     <pre
       ref={ref}
       {...mergeProps(
-        themeProps('codeblock', {size, language, container}),
+        themeProps(
+          'code-block',
+          {size, language, container},
+          // `codeblock` ran the compound name together; themes styling it keep
+          // working until the next major.
+          {legacyNames: ['codeblock']},
+        ),
         stylex.props(
           styles.root,
           dynamicStyles.width(widthProp),

package/src/CodeBlock/highlightRanges.ts

@@ -67,7 +67,7 @@ function ensureDynamicHighlightType(tokenType: string): void {
   const name = `astryx-${tokenType}`;
   const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;
   dynamicStyleSheet.insertRule(
-    `.astryx-codeblock code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
+    `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
   );
 }
 

package/src/CodeBlock/highlightStyles.ts

@@ -30,31 +30,31 @@ const FALLBACK_TOKENS = `:root {\n${Object.entries(syntaxTokenDefaults)
 const HIGHLIGHT_STYLES = `
 ${FALLBACK_TOKENS}
 
-.astryx-codeblock code::highlight(astryx-keyword),
+.astryx-code-block code::highlight(astryx-keyword),
 .astryx-codeeditor code::highlight(astryx-keyword) { color: var(--color-syntax-keyword); }
-.astryx-codeblock code::highlight(astryx-string),
+.astryx-code-block code::highlight(astryx-string),
 .astryx-codeeditor code::highlight(astryx-string) { color: var(--color-syntax-string); }
-.astryx-codeblock code::highlight(astryx-comment),
+.astryx-code-block code::highlight(astryx-comment),
 .astryx-codeeditor code::highlight(astryx-comment) { color: var(--color-syntax-comment); }
-.astryx-codeblock code::highlight(astryx-number),
+.astryx-code-block code::highlight(astryx-number),
 .astryx-codeeditor code::highlight(astryx-number) { color: var(--color-syntax-number); }
-.astryx-codeblock code::highlight(astryx-function),
+.astryx-code-block code::highlight(astryx-function),
 .astryx-codeeditor code::highlight(astryx-function) { color: var(--color-syntax-function); }
-.astryx-codeblock code::highlight(astryx-type),
+.astryx-code-block code::highlight(astryx-type),
 .astryx-codeeditor code::highlight(astryx-type) { color: var(--color-syntax-type); }
-.astryx-codeblock code::highlight(astryx-tag),
+.astryx-code-block code::highlight(astryx-tag),
 .astryx-codeeditor code::highlight(astryx-tag) { color: var(--color-syntax-tag); }
-.astryx-codeblock code::highlight(astryx-attribute),
+.astryx-code-block code::highlight(astryx-attribute),
 .astryx-codeeditor code::highlight(astryx-attribute) { color: var(--color-syntax-attribute); }
-.astryx-codeblock code::highlight(astryx-property),
+.astryx-code-block code::highlight(astryx-property),
 .astryx-codeeditor code::highlight(astryx-property) { color: var(--color-syntax-property); }
-.astryx-codeblock code::highlight(astryx-operator),
+.astryx-code-block code::highlight(astryx-operator),
 .astryx-codeeditor code::highlight(astryx-operator) { color: var(--color-syntax-operator); }
-.astryx-codeblock code::highlight(astryx-constant),
+.astryx-code-block code::highlight(astryx-constant),
 .astryx-codeeditor code::highlight(astryx-constant) { color: var(--color-syntax-constant); }
-.astryx-codeblock code::highlight(astryx-punctuation),
+.astryx-code-block code::highlight(astryx-punctuation),
 .astryx-codeeditor code::highlight(astryx-punctuation) { color: var(--color-syntax-punctuation); }
-.astryx-codeblock code::highlight(astryx-variable),
+.astryx-code-block code::highlight(astryx-variable),
 .astryx-codeeditor code::highlight(astryx-variable) { color: var(--color-syntax-variable); }
 
 /* Span-based fallback classes — used when highlightMode='spans' or

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/ComplexSelector/ComplexSelector.test.tsx

@@ -353,6 +353,7 @@ describe('ComplexSelector', () => {
       .closest('[popover]');
     expect(popover).not.toBeNull();
 
+    fireEvent.pointerDown(trigger);
     const closeEvent = new Event('toggle');
     Object.defineProperty(closeEvent, 'newState', {value: 'closed'});
     fireEvent(popover as HTMLElement, closeEvent);
@@ -417,4 +418,35 @@ describe('ComplexSelector popup theme target', () => {
       document.querySelector('.astryx-complex-selector-popup'),
     ).not.toBeNull();
   });
+
+  it('stays closed when the trigger click follows its own light dismiss (#5004)', async () => {
+    const user = userEvent.setup();
+    render(
+      <ComplexSelector label="Fruit blend" value="Apple" triggerLabel="Apple">
+        {() => <button type="button">Done</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    // The browser dismissed the popup on pointerup and queued the toggle. When
+    // that event lands before the click — WebKit, or any engine under load —
+    // the click used to read a closed popup and reopen it.
+    fireEvent.pointerDown(trigger);
+    const popover = document.querySelector('[popover]') as HTMLElement;
+    act(() => {
+      popover.dispatchEvent(
+        Object.assign(new Event('toggle'), {
+          oldState: 'open',
+          newState: 'closed',
+        }),
+      );
+    });
+    // Synchronously: the click falls inside the one gesture the guard covers,
+    // as it does in a browser a few milliseconds behind the dismissal.
+    fireEvent.click(trigger);
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
 });

package/src/ComplexSelector/ComplexSelector.tsx

@@ -373,14 +373,12 @@ export function ComplexSelector<Value>({
       .join(' ') || undefined;
 
   const triggerRef = useRef<HTMLButtonElement>(null);
-  const lastHideTimeRef = useRef(0);
 
   const [isPending, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || isPending;
 
   const handlePopoverHide = useCallback(() => {
-    lastHideTimeRef.current = Date.now();
     triggerRef.current?.focus();
   }, []);
 
@@ -395,7 +393,7 @@ export function ComplexSelector<Value>({
   const isOpen = popover.isOpen;
 
   const handleTriggerClick = useCallback(() => {
-    if (isDisabled || Date.now() - lastHideTimeRef.current < 50) {
+    if (isDisabled) {
       return;
     }
     if (popover.isOpen) {

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.doc.mjs

@@ -156,6 +156,13 @@ export const docs = {
         "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
       default: "'date_long'",
     },
+    {
+      name: 'nativePicker',
+      type: "'touch' | 'always' | 'never'",
+      description:
+        "Which surface draws the date picker. 'touch' (the default) hands a touch device to the browser/OS: the field becomes an input type=date and the platform draws the picker (the iOS wheel, the Android calendar dialog); 'always' does that wherever the browser supports input type=date; 'never' keeps Astryx's own pickers everywhere (the bottom-sheet picker on a finger, the calendar popover on a mouse). Use 'never' for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express. format and placeholder still apply in native mode; min and max are forwarded, but a native picker may not show them (on iOS an out-of-range date can be selected and is refused on commit rather than greyed out).",
+      default: "'touch'",
+    },
     {
       name: 'width',
       type: 'SizeValue',
@@ -437,6 +444,13 @@ export const docsZh = {
         "已选日期的显示格式。命名值复用 Timestamp 的格式词汇：'date' 显示 'Mar 21, 2026'，'date_long' 显示 'March 21, 2026'，'date_weekday' 显示 'Wed, Mar 21, 2026'，'system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值，不影响正在输入的文本。",
       default: "'date_long'",
     },
+    {
+      name: 'nativePicker',
+      type: "'touch' | 'always' | 'never'",
+      description:
+        "由哪个界面绘制日期选择器。'touch'（默认）在触摸设备上交给浏览器/操作系统：字段变为 input type=date，由平台绘制选择器（iOS 滚轮、Android 日历对话框）；'always' 在所有支持 input type=date 的浏览器上都这样做；'never' 始终使用 Astryx 自带的选择器（触摸设备用底部弹出选择器，鼠标设备用日历弹出层）。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用 'never'，原生选择器无法表达这些。原生模式下 format 和 placeholder 仍然生效；min 和 max 会传递给原生控件，但原生选择器可能不会显示这些限制（在 iOS 上仍可选中超出范围的日期，会在提交时被拒绝，而不是变灰）。",
+      default: "'touch'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -537,6 +551,8 @@ export const docsDense = {
     weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
     format:
       "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
+    nativePicker:
+      "which surface draws the picker: 'touch' (default) = browser/OS on a coarse pointer, 'always', 'never' = Astryx's own everywhere. use 'never' for weekStartsOn/numberOfMonths/dateConstraints. format+placeholder still apply; min/max forwarded but not necessarily shown by the OS picker, refused on commit instead.",
     xstyle: 'StyleX styles for layout; must be stylex.create() value',
   },
 };