@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

package/src/Citation/Citation.test.tsx

@@ -36,6 +36,23 @@ function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
 describe('Citation', () => {
   const source = {title: 'Example Source', url: 'https://example.com'};
 
+  it.each([
+    'javascript:alert(1)',
+    'vbscript:MsgBox(1)',
+    'data:text/html,<b>x</b>',
+    'java\nscript:alert(1)',
+  ])('renders rejected citation URL %s without navigation', url => {
+    const {container} = render(
+      <>
+        <Citation source={{title: 'Source', url}} number={1} />
+        <Citation source={{title: 'Source', url}} number={1} variant="number" />
+      </>,
+    );
+    expect(container.querySelector('a')).toBeNull();
+    expect(container.querySelector('[href]')).toBeNull();
+    expect(container.textContent).toBe('Source1');
+  });
+
   it('renders the source title as a link in the label variant', () => {
     render(<Citation source={source} number={1} data-testid="citation" />);
     const el = screen.getByTestId('citation');

package/src/Citation/Citation.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Citation.tsx
- * @input Uses React, StyleX, theme tokens
+ * @input Uses React, StyleX, theme tokens, and the shared navigation policy
  * @output Exports Citation component for inline citation references
  * @position Core implementation; consumed by index.ts
  *
@@ -30,6 +30,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {isSafeUrl} from '../utils/safeUrl';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -189,7 +190,8 @@ export function Citation({
 }: CitationProps): React.ReactElement {
   const t = useTranslator();
   const title = source.title ?? String(number);
-  const href = source.url;
+  const href =
+    source.url != null && isSafeUrl(source.url) ? source.url : undefined;
 
   // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
   // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -22,7 +22,7 @@ export const docs = {
   props: [
     {name: 'label', type: 'string', description: 'Accessibility label.', required: true},
     {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},
-    {name: 'href', type: 'string', description: 'Navigation URL.'},
+    {name: 'href', type: 'string', description: 'Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.'},
     {name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},
     {name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
@@ -69,7 +69,7 @@ export const docsDense = {
   propDescriptions: {
     label: 'accessibility label',
     onClick: 'click handler: fires on card surface only',
-    href: 'navigation URL',
+    href: 'navigation URL; every activation follows the shared navigation rule (see Link href)',
     target: 'link target',
     isDisabled: 'disables card',
     padding: 'inner padding',

package/src/ClickableCard/ClickableCard.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
 
 describe('ClickableCard', () => {
@@ -47,6 +48,47 @@ describe('ClickableCard', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('calls onClick once when the accessible control itself is clicked', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // Pointer activation aimed at the element carrying the role — what
+    // speech input, assistive technology, and automation dispatch.
+    fireEvent.click(screen.getByRole('button', {name: 'Test card'}));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the card surface as currentTarget for surface clicks', () => {
+    const seen: EventTarget[] = [];
+    render(
+      <ClickableCard
+        label="Test card"
+        onClick={e => seen.push(e.currentTarget)}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByText('Content'));
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toBe(screen.getByText('Content').parentElement);
+  });
+
+  it('calls onClick exactly once when the surface of an href card is clicked without preventDefault', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Nav card" href="/settings" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // The container hook proxies the surface click to the link with
+    // `link.click()`; that synthetic click bubbles back through the card and
+    // must not run the consumer callback a second time.
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
   it('does NOT call onClick when a nested button is clicked', () => {
     const handleCardClick = vi.fn();
     const handleButtonClick = vi.fn();
@@ -86,25 +128,80 @@ describe('ClickableCard', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-  it('disabled button is disabled', () => {
+  it('disabled button is disabled and the surface runs nothing', () => {
     const handleClick = vi.fn();
     render(
       <ClickableCard label="Disabled" onClick={handleClick} isDisabled>
-        Content
+        <span>Content</span>
       </ClickableCard>,
     );
     const button = screen.getByRole('button', {name: 'Disabled'});
     expect(button).toBeDisabled();
+    fireEvent.click(screen.getByText('Content'));
+    fireEvent.click(button);
+    expect(handleClick).not.toHaveBeenCalled();
   });
 
-  it('disabled link has aria-disabled', () => {
+  it('disabled link has aria-disabled, leaves the tab order, and the surface runs nothing', () => {
+    const handleClick = vi.fn();
     render(
-      <ClickableCard label="Disabled link" href="/settings" isDisabled>
-        Content
+      <ClickableCard
+        label="Disabled link"
+        href="/settings"
+        onClick={handleClick}
+        isDisabled>
+        <span>Content</span>
       </ClickableCard>,
     );
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveAttribute('tabindex', '-1');
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('runs onClick once from the keyboard via the hidden button', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'Test card'})).toHaveFocus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(handleClick).toHaveBeenCalledTimes(2);
+  });
+
+  it('does NOT call onClick when a nested input is clicked', () => {
+    const handleCardClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleCardClick}>
+        <input aria-label="Quantity" readOnly value="1" />
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByRole('textbox', {name: 'Quantity'}));
+    expect(handleCardClick).not.toHaveBeenCalled();
+  });
+
+  it('does NOT call onClick when text inside the card is selected', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Selectable body text</span>
+      </ClickableCard>,
+    );
+    const text = screen.getByText('Selectable body text');
+    const range = document.createRange();
+    range.selectNodeContents(text);
+    const selection = document.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    fireEvent.click(text);
+    expect(handleClick).not.toHaveBeenCalled();
+    selection.removeAllRanges();
   });
 
   describe('elevation', () => {

package/src/CodeBlock/highlightRanges.test.ts

@@ -4,14 +4,18 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import type {TokenLine} from './tokenizer';
 
-// Mock CSS Highlight API
+// Mock CSS Highlight API. `escape` is real behavior, not a mock: the code
+// under test escapes generated names with it, so jsdom's implementation is
+// carried over when the CSS global is replaced.
 class MockHighlight extends Set<Range> {}
 const mockHighlightsMap = new Map<string, MockHighlight>();
+const realCssEscape = globalThis.CSS.escape;
 
 beforeEach(() => {
   mockHighlightsMap.clear();
 
   globalThis.CSS = {
+    escape: realCssEscape,
     highlights: {
       get: (name: string) => mockHighlightsMap.get(name),
       set: (name: string, h: MockHighlight) => mockHighlightsMap.set(name, h),
@@ -44,6 +48,30 @@ function createCodeElement(lines: string[]): HTMLElement {
   return code;
 }
 
+/**
+ * The dynamic stylesheet is module-level state shared by every test in this
+ * file, so each test drives unique token types and looks its rules up by the
+ * escaped name rather than by position.
+ */
+function dynamicRules(): CSSStyleRule[] {
+  const dynamicSheet = document.querySelector<HTMLStyleElement>(
+    'style[data-astryx-highlight-dynamic]',
+  );
+  return Array.from(dynamicSheet?.sheet?.cssRules ?? []) as CSSStyleRule[];
+}
+
+/**
+ * Exactly the two highlight selectors and nothing else: an escaped ident may
+ * contain any character, but only behind a backslash, so an unescaped `)`
+ * that closed the function early (and the `, body` after it) cannot match.
+ */
+const HIGHLIGHT_ONLY_SELECTOR =
+  /^\.astryx-code-block code::highlight\((?:[^()\\]|\\.)+\), \.astryx-codeeditor code::highlight\((?:[^()\\]|\\.)+\)$/;
+
+function highlightRule(name: string): string {
+  return `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name})`;
+}
+
 describe('applyHighlightRangesChunked', () => {
   it('creates ranges for tokens on each line', () => {
     const codeEl = createCodeElement(['const x = 1;', 'let y = 2;']);
@@ -67,6 +95,120 @@ describe('applyHighlightRangesChunked', () => {
     expect(kwHighlight!.size).toBe(0);
   });
 
+  it('keeps every parser-accepted tokenizer type coloured under its raw name', () => {
+    // The dotted type that crashed the block, plus names a narrow allowlist
+    // would wrongly reject even though the CSS parser accepts them all.
+    const types = ['keyword.control.sql', '_private', 'キーワード', '9start'];
+    const codeEl = createCodeElement(types.map(() => 'line'));
+    const tokenLines: TokenLine[] = types.map(type => [
+      {type, start: 0, end: 4},
+    ]);
+
+    const mockStyle = document.createElement('style');
+    mockStyle.setAttribute('data-astryx-highlight-styles', '');
+    document.head.appendChild(mockStyle);
+    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
+
+    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
+
+    // Ranges register under the RAW names: a ::highlight() selector matches
+    // by ident value, so the escaped rule below still paints them.
+    for (const type of types) {
+      expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
+    }
+
+    // One rule per type, with only the characters that need it escaped.
+    expect(insertRule.mock.calls.map(([rule]) => rule)).toEqual([
+      `${highlightRule('astryx-keyword\\.control\\.sql')} { color: var(--color-syntax-keyword\\.control\\.sql, currentColor); }`,
+      `${highlightRule('astryx-_private')} { color: var(--color-syntax-_private, currentColor); }`,
+      `${highlightRule('astryx-キーワード')} { color: var(--color-syntax-キーワード, currentColor); }`,
+      `${highlightRule('astryx-9start')} { color: var(--color-syntax-9start, currentColor); }`,
+    ]);
+
+    cleanup();
+  });
+
+  it('escapes the highlight name so a token type cannot leave its ::highlight() selector', () => {
+    // Unescaped, this type closes ::highlight() early and the CSS parser
+    // accepts what follows as a valid second selector plus a declaration
+    // block, with the trailing comment opener swallowing the rest of the
+    // generated rule text. The result is a rule that styles <body>.
+    const type = 'sel), body { background: red } /*';
+    const escapedName =
+      'astryx-sel\\)\\,\\ body\\ \\{\\ background\\:\\ red\\ \\}\\ \\/\\*';
+    const codeEl = createCodeElement(['line']);
+    const tokenLines: TokenLine[] = [[{type, start: 0, end: 4}]];
+
+    const mockStyle = document.createElement('style');
+    mockStyle.setAttribute('data-astryx-highlight-styles', '');
+    document.head.appendChild(mockStyle);
+    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
+
+    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
+
+    expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
+
+    // The exact rule text handed to the engine: both generated names fully
+    // escaped, one colour declaration, nothing of the payload's making.
+    expect(insertRule).toHaveBeenCalledTimes(1);
+    expect(insertRule).toHaveBeenCalledWith(
+      `${highlightRule(escapedName)} { color: var(--color-syntax-sel\\)\\,\\ body\\ \\{\\ background\\:\\ red\\ \\}\\ \\/\\*, currentColor); }`,
+    );
+
+    // And as parsed: the rule for this type keeps the payload inside the
+    // ident, and no rule in the sheet has any selector beyond the two
+    // highlight selectors.
+    const rules = dynamicRules();
+    const rule = rules.find(r => r.selectorText.includes('astryx-sel'));
+    expect(rule?.selectorText).toBe(highlightRule(escapedName));
+    for (const r of rules) {
+      expect(r.selectorText).toMatch(HIGHLIGHT_ONLY_SELECTOR);
+    }
+
+    cleanup();
+  });
+
+  it('escapes the custom property so a token type cannot add declarations', () => {
+    // Unescaped, this type closes var() early and the CSS parser accepts
+    // what follows as two more valid declarations.
+    const type = 'p); background: red; --x: var(--y';
+    const escapedName =
+      'astryx-p\\)\\;\\ background\\:\\ red\\;\\ --x\\:\\ var\\(--y';
+    const escapedColor =
+      'var(--color-syntax-p\\)\\;\\ background\\:\\ red\\;\\ --x\\:\\ var\\(--y, currentColor)';
+    const codeEl = createCodeElement(['line']);
+    const tokenLines: TokenLine[] = [[{type, start: 0, end: 4}]];
+
+    const mockStyle = document.createElement('style');
+    mockStyle.setAttribute('data-astryx-highlight-styles', '');
+    document.head.appendChild(mockStyle);
+    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
+
+    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
+
+    expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
+
+    expect(insertRule).toHaveBeenCalledTimes(1);
+    expect(insertRule).toHaveBeenCalledWith(
+      `${highlightRule(escapedName)} { color: ${escapedColor}; }`,
+    );
+
+    // As parsed: exactly one declaration, `color`, whose value is the
+    // escaped custom property with its fallback.
+    const rule = dynamicRules().find(r => r.selectorText.includes('astryx-p'));
+    expect(rule).toBeDefined();
+    expect(rule!.selectorText).toBe(highlightRule(escapedName));
+    const declared = Array.from({length: rule!.style.length}, (_, i) =>
+      rule!.style.item(i),
+    );
+    expect(declared).toEqual(['color']);
+    expect(rule!.style.getPropertyValue('color')).toBe(escapedColor);
+    expect(rule!.style.getPropertyValue('background')).toBe('');
+    expect(rule!.style.getPropertyValue('--x')).toBe('');
+
+    cleanup();
+  });
+
   it('handles empty token lines', () => {
     const codeEl = createCodeElement(['', 'const x = 1;']);
     const tokenLines: TokenLine[] = [[], [{type: 'keyword', start: 0, end: 5}]];

package/src/CodeBlock/highlightRanges.ts

@@ -64,11 +64,21 @@ function ensureDynamicHighlightType(tokenType: string): void {
     }
   }
 
-  const name = `astryx-${tokenType}`;
-  const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;
-  dynamicStyleSheet.insertRule(
-    `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
-  );
+  // CSS.escape both generated names before they land in rule text: the
+  // registry key stays the raw string (a ::highlight() selector matches by
+  // ident VALUE, escapes and all), so dotted, non-ASCII, `_private`, and
+  // digit-led token types keep their colours — while nothing a token stream
+  // carries can step outside its ident and shape the rule.
+  const name = CSS.escape(`astryx-${tokenType}`);
+  const colorVar = `var(${CSS.escape(`--color-syntax-${tokenType}`)}, currentColor)`;
+  try {
+    dynamicStyleSheet.insertRule(
+      `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
+    );
+  } catch {
+    // An engine that still refuses the rule costs that type its colour
+    // (ranges paint with currentColor) — never the whole code block.
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/Collapsible/Collapsible.doc.mjs

@@ -82,6 +82,17 @@ export const docs = {
     {name: 'CollapsibleGroup'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Trigger label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Pointer down'],
+        description:
+          'The trigger text must have at least 4.5:1 contrast with the surface behind it. For Pointer down, measure against the pressed overlay the trigger row paints while it is pressed.',
+      },
+    ],
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
       { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },

package/src/Collapsible/Collapsible.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {Collapsible} from './Collapsible';
 import {CollapsibleGroup} from './CollapsibleGroup';
 
@@ -615,3 +616,23 @@ describe('Collapsible', () => {
     });
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on the trigger row while it is pressed', () => {
+    render(
+      <Collapsible trigger="Details">
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(true);
+  });
+
+  it('does not press a disabled trigger', () => {
+    render(
+      <Collapsible trigger="Details" isDisabled>
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(false);
+  });
+});

package/src/Collapsible/Collapsible.tsx

@@ -48,6 +48,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 const styles = stylex.create({
   root: {
@@ -411,6 +412,10 @@ export function Collapsible({
           focusOutlineProps.focusVisible(
             styles.trigger,
             density != null && triggerDensity[density],
+            // The system's pressed overlay on the disclosure row. The trigger
+            // has no hover surface of its own, so this is the one background
+            // it paints, and only while it is pressed.
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             isDisabled && styles.triggerDisabled,
           ),
         )}>

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -73,9 +73,14 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     padding: 0,

package/src/ComplexSelector/ComplexSelector.tsx

@@ -65,9 +65,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-3'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/DateInput.doc.mjs

@@ -156,11 +156,18 @@ 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: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+      description:
+        "Which surface draws the date picker. 'adaptive-native' (the default) uses Astryx's calendar popover on a fine pointer and the browser/OS picker (input type=date) on a coarse pointer, keeping Astryx fallbacks where a native control cannot express the value; 'native' always uses the browser/OS picker with no fallback; 'adaptive-bottom-sheet' uses the popover on a fine pointer and Astryx's bottom-sheet picker on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens a picker; a typed-only field is TimeInput's alone. Use a non-native presentation for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express.",
+      default: "'adaptive-native'",
+    },
     {
       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).",
+        "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set.",
       default: "'touch'",
     },
     {
@@ -178,9 +185,16 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-date-input', visualProps: ['size', 'status'], states: ['disabled']},
+      {
+        className: 'astryx-date-input',
+        visualProps: ['size', 'status'],
+        states: ['disabled'],
+      },
       {className: 'astryx-date-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
+      {
+        className: 'astryx-date-input-clear-icon',
+        deprecatedFor: 'input-clear-icon',
+      },
     ],
   },
   usage: {
@@ -434,7 +448,8 @@ export const docsZh = {
     {
       name: 'weekStartsOn',
       type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
-      description: '日历弹出层中每周的起始日。可为数字（0=周日……6=周六）或三字母星期缩写。',
+      description:
+        '日历弹出层中每周的起始日。可为数字（0=周日……6=周六）或三字母星期缩写。',
       default: '0',
     },
     {
@@ -444,11 +459,18 @@ 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: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+      description:
+        "由哪个界面绘制日期选择器。'adaptive-native'（默认）在精细指针上使用 Astryx 日历弹出层、在粗指针上使用浏览器/操作系统选择器（input type=date），且原生控件无法表达值时保留 Astryx 回退；'native' 始终使用浏览器/操作系统选择器且不回退；'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 底部选择器；'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器；仅输入字段的呈现只属于 TimeInput。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用非原生呈现，原生选择器无法表达这些。",
+      default: "'adaptive-native'",
+    },
     {
       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 上仍可选中超出范围的日期，会在提交时被拒绝，而不是变灰）。",
+        "已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet'）。仍按已发布行为工作；同时设置时以 presentation 为准。",
       default: "'touch'",
     },
     {
@@ -466,7 +488,10 @@ export const docsZh = {
         states: ['disabled'],
       },
       {className: 'astryx-date-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
+      {
+        className: 'astryx-date-input-clear-icon',
+        deprecatedFor: 'input-clear-icon',
+      },
     ],
   },
 };
@@ -544,15 +569,19 @@ export const docsDense = {
     placeholder: 'placeholder text in input',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
-    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+    statusVariant:
+      'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'tooltip text via info icon at label end',
     hasClear: 'Shows clear button when date is set. Clears value on click.',
     numberOfMonths: 'months shown simultaneously in calendar popover',
-    weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
+    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.",
+    presentation:
+      "which surface draws the picker: 'adaptive-native' (default) = Astryx popover on fine, browser/OS on coarse w/ Astryx fallbacks; 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popover fine / Astryx sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens a picker (no text-only value; that is TimeInput's). use non-native for weekStartsOn/numberOfMonths/dateConstraints.",
     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.",
+      "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
     xstyle: 'StyleX styles for layout; must be stylex.create() value',
   },
 };