@astryxdesign/core 0.4.6 → 0.4.7-canary.29be96d

package/src/Dialog/Dialog.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When Dialog.tsx changes, update tests to match new behavior
  */
 
+import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Dialog, resolveDialogPositionOffsets} from './Dialog';
@@ -184,6 +185,76 @@ describe('Dialog', () => {
     });
   });
 
+  describe('responsive sizing', () => {
+    it('keeps the requested width but clamps standard dialogs to container and dynamic viewport gutters', () => {
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={() => {}}
+          width={600}
+          maxHeight="70dvh"
+          aria-label="Sized dialog">
+          Content
+        </Dialog>,
+      );
+
+      const dialog = screen.getByRole('dialog');
+      const inlineStyle = dialog.getAttribute('style') ?? '';
+      expect(inlineStyle).toContain('--x-width: 600px');
+      expect(inlineStyle).toContain(
+        '--x-maxWidth: min(100%, calc(100dvw - var(--spacing-4) - var(--spacing-4)))',
+      );
+      expect(inlineStyle).toContain('--x-maxHeight: 70dvh');
+    });
+
+    it('uses a fullscreen-specific fade animation instead of centered dialog movement', () => {
+      const source = readFileSync(
+        'packages/core/src/Dialog/Dialog.tsx',
+        'utf8',
+      );
+      const standardOpen = source.slice(
+        source.indexOf('  open: {'),
+        source.indexOf('  // Backdrop using ::backdrop'),
+      );
+      const fullscreenOpen = source.slice(
+        source.indexOf('  fullscreenOpen: {'),
+        source.indexOf('  fullscreenSafeArea: {'),
+      );
+      const modalStyleOrder = source.slice(
+        source.indexOf('focusOutlineProps.focusVisible('),
+        source.indexOf(
+          '          xstyle,',
+          source.indexOf('focusOutlineProps.focusVisible('),
+        ),
+      );
+
+      expect(standardOpen).toContain('enterDirectional');
+      expect(fullscreenOpen).toContain('enterFullscreen');
+      expect(fullscreenOpen).not.toContain('enterDirectional');
+      expect(modalStyleOrder.indexOf('styles.open')).toBeLessThan(
+        modalStyleOrder.indexOf('styles.fullscreenOpen'),
+      );
+    });
+
+    it('protects fullscreen content with safe-area padding', () => {
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={() => {}}
+          variant="fullscreen"
+          aria-label="Fullscreen dialog">
+          <div data-testid="child">Content</div>
+        </Dialog>,
+      );
+
+      const wrapper = screen.getByTestId('child').parentElement!;
+      const computed = window.getComputedStyle(wrapper);
+      expect(computed.paddingInlineStart).toContain('safe-area-inset-left');
+      expect(computed.paddingInlineEnd).toContain('safe-area-inset-right');
+      expect(wrapper.parentElement!.tagName).toBe('DIALOG');
+    });
+  });
+
   describe('position prop', () => {
     it('accepts position configuration', () => {
       render(

package/src/Dialog/Dialog.tsx

@@ -8,6 +8,12 @@
  * @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
  * @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
  *
+ * The standard variant treats `width` as the preferred surface width, then
+ * clamps it to the dynamic viewport with spacing-token gutters so narrow
+ * viewports keep content and controls on screen without changing the public API.
+ * Fullscreen dialogs preserve the same padding floor while honoring safe-area
+ * insets, and fade in without the centered-dialog translate/scale motion.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
@@ -35,6 +41,7 @@ import {
   durationVars,
   easeVars,
   shadowVars,
+  spacingVars,
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
@@ -118,6 +125,11 @@ const enterDirectional = stylex.keyframes({
   to: {opacity: 1, transform: 'translate(0, 0) scale(1)'},
 });
 
+const enterFullscreen = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
 /**
  * Dialog styles using native <dialog> element
  * Uses ::backdrop pseudo-element for overlay
@@ -171,6 +183,22 @@ const styles = stylex.create({
     margin: 0,
     inset: 0,
   },
+  fullscreenOpen: {
+    animationName: {
+      default: enterFullscreen,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+  },
+  fullscreenSafeArea: {
+    paddingBlockStart:
+      'max(var(--container-padding-block-start), env(safe-area-inset-top, 0px))',
+    paddingBlockEnd:
+      'max(var(--container-padding-block-end), env(safe-area-inset-bottom, 0px))',
+    paddingInlineStart:
+      'max(var(--container-padding-inline-start), env(safe-area-inset-left, 0px))',
+    paddingInlineEnd:
+      'max(var(--container-padding-inline-end), env(safe-area-inset-right, 0px))',
+  },
   inner: {
     display: 'flex',
     flexDirection: 'column',
@@ -194,12 +222,30 @@ const styles = stylex.create({
   },
 });
 
-// Dynamic styles for width, maxHeight, and position
+const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
+const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;
+
+function formatSizeValue(value: number | string): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+function resolveDialogSizing(
+  width: number | string,
+  maxHeight: number | string,
+) {
+  return {
+    width: formatSizeValue(width),
+    maxWidth: STANDARD_DIALOG_MAX_WIDTH,
+    maxHeight: formatSizeValue(maxHeight),
+  };
+}
+
 const dynamicStyles = stylex.create({
-  sizing: (width: number | string, maxHeight: number | string) => ({
-    width: typeof width === 'number' ? `${width}px` : width,
-    maxWidth: '90vw',
-    maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
+  sizing: (width: string, maxWidth: string, maxHeight: string) => ({
+    width,
+    maxWidth,
+    maxHeight,
   }),
   position: (
     top: string,
@@ -288,7 +334,7 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
    * The actual height will be the height of its content.
    * Numbers are treated as pixels, strings are used as-is.
    * Ignored when variant is 'fullscreen'.
-   * @default '75vh'
+   * @default '75dvh'
    */
   maxHeight?: number | string;
 
@@ -356,7 +402,7 @@ export function Dialog({
   isInline = false,
   onOpenChange,
   width = 400,
-  maxHeight = '75vh',
+  maxHeight = '75dvh',
   position,
   variant = 'standard',
   purpose = 'info',
@@ -374,6 +420,9 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
+  const standardSizing = isFullscreen
+    ? null
+    : resolveDialogSizing(width, maxHeight);
 
   // Default accessible name: publish a title id through DialogContext so a
   // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
@@ -550,7 +599,6 @@ export function Dialog({
     }
   };
 
-  // Shared inner content wrapper
   const innerContent = (
     <div
       {...stylex.props(
@@ -559,22 +607,14 @@ export function Dialog({
           useThemeDefault
             ? {
                 useThemeDefault: 'dialog',
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               }
             : {
                 paddingInnerX: paddingToken,
                 paddingInnerY: paddingToken,
                 paddingOuterX: paddingToken,
                 paddingOuterY: paddingToken,
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               },
         ),
         !useThemeDefault &&
@@ -589,6 +629,7 @@ export function Dialog({
         !useThemeDefault &&
           effectivePadding !== 4 &&
           containerPaddingBlockEndVarStyles[effectivePadding],
+        isFullscreen && styles.fullscreenSafeArea,
       )}>
       <DialogContext value={dialogContextValue}>{children}</DialogContext>
     </div>
@@ -612,7 +653,12 @@ export function Dialog({
           stylex.props(
             styles.inlineWrapper,
             overlayPaddingReset.reset,
-            !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+            standardSizing &&
+              dynamicStyles.sizing(
+                standardSizing.width,
+                standardSizing.maxWidth,
+                standardSizing.maxHeight,
+              ),
             isFullscreen && styles.fullscreen,
             xstyle,
           ),
@@ -641,7 +687,12 @@ export function Dialog({
           overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
-          !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+          standardSizing &&
+            dynamicStyles.sizing(
+              standardSizing.width,
+              standardSizing.maxWidth,
+              standardSizing.maxHeight,
+            ),
           hasPosition &&
             (() => {
               const o = resolveDialogPositionOffsets(position);
@@ -653,6 +704,7 @@ export function Dialog({
               );
             })(),
           isFullscreen && styles.fullscreen,
+          isFullscreen && isOpen && styles.fullscreenOpen,
           xstyle,
         ),
         className,

package/src/Field/Field.doc.mjs

@@ -60,6 +60,17 @@ export const docs = {
       description: 'ID for the input element (used for the label htmlFor attribute).',
       required: true,
     },
+    {
+      name: 'labelID',
+      type: 'string',
+      description: 'ID applied to the label element itself for group accessibility.',
+    },
+    {
+      name: 'isGroupLabel',
+      type: 'boolean',
+      description: 'Renders the label as a span for control groups (radiogroup, checkbox list).',
+      default: 'false',
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/Heading/Heading.test.tsx

@@ -6,7 +6,7 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {Heading} from './Heading';
 
 describe('Heading', () => {
@@ -16,6 +16,28 @@ describe('Heading', () => {
       expect(screen.getByText('Page Title')).toBeInTheDocument();
     });
 
+    it('keeps a forwarded ref attached across rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Heading ref={ref} level={1}>
+          Before
+        </Heading>,
+      );
+
+      const element = screen.getByText('Before');
+      expect(ref).toHaveBeenLastCalledWith(element);
+      ref.mockClear();
+
+      rerender(
+        <Heading ref={ref} level={1}>
+          After
+        </Heading>,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByText('After')).toBe(element);
+    });
+
     it('renders h1 for level 1', () => {
       render(<Heading level={1}>H1</Heading>);
       const element = screen.getByText('H1');

package/src/Heading/Heading.tsx

@@ -43,7 +43,8 @@ import {
 import {useTruncation} from '../Text/useTruncation';
 import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -242,13 +243,16 @@ export function Heading({
   // Ref for the heading element (used as tooltip anchor)
   const headingRef = useRef<HTMLHeadingElement>(null);
 
+  // Keep the merged ref stable across rerenders.
+  const mergedRef = useMergedRefs(ref, truncation.ref, headingRef);
+
   // Build inline style for -webkit-line-clamp (dynamic value)
   const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;
 
   return (
     <>
       <Component
-        ref={mergeRefs(ref, truncation.ref, headingRef)}
+        ref={mergedRef}
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(

package/src/Kbd/Kbd.test.tsx

@@ -23,6 +23,7 @@ describe('Kbd', () => {
       value: originalPlatform,
       configurable: true,
     });
+    delete (navigator as {userAgentData?: unknown}).userAgentData;
   });
 
   it('renders a single key', () => {
@@ -54,6 +55,22 @@ describe('Kbd', () => {
     expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Mac', () => {
+    // Builds that rewrite their client-hints identity expose the key with an
+    // empty value; navigator.platform is the only surface left that answers.
+    Object.defineProperty(navigator, 'userAgentData', {
+      value: {platform: ''},
+      configurable: true,
+    });
+    Object.defineProperty(navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true,
+    });
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('\u2318')).toBeInTheDocument();
+  });
+
   it('maps modifier keys to symbols', () => {
     render(<Kbd keys="ctrl+alt+shift+k" />);
     expect(screen.getByText('\u2303')).toBeInTheDocument(); // \u2303

package/src/Kbd/Kbd.tsx

@@ -124,8 +124,9 @@ function getServerPlatformSnapshot(): boolean {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  */
 function detectMac(): boolean {
   if (typeof navigator === 'undefined') {
@@ -134,7 +135,13 @@ function detectMac(): boolean {
   // Prefer User-Agent Client Hints API (not deprecated)
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   // Fallback: navigator.platform (deprecated but still shipped everywhere)
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');

package/src/Link/Link.doc.mjs

@@ -78,6 +78,17 @@ export const docs = {
           description:
             'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',
         },
+        {
+          name: 'download',
+          type: 'string | boolean',
+          description:
+            'Causes the browser to download the linked URL. A string specifies the suggested filename.',
+        },
+        {
+          name: 'referrerPolicy',
+          type: 'HTMLAttributeReferrerPolicy',
+          description: 'Referrer policy for the link.',
+        },
         {
           name: 'onClick',
           type: 'MouseEventHandler',

package/src/Markdown/index.ts

@@ -25,6 +25,7 @@ export {
 export type {
   BlockNode,
   InlineNode,
+  SourceRange,
   ListItemNode,
   TableCellNode,
   TableAlignment,

package/src/Markdown/parser.perf.test.ts

@@ -6,7 +6,7 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
 } from './parser';
-import type {BlockNode} from './parser';
+import type {BlockNode, ParseOptions} from './parser';
 
 function generateAIResponse(paragraphs: number): string {
   const sections: string[] = [];
@@ -69,6 +69,42 @@ function simulateStreamingIncremental(
   return parseMarkdownIncremental(fullText, state);
 }
 
+/**
+ * How many blocks each chunk of a streamed document had to build.
+ *
+ * A block the parser kept in its settled cache is handed back as the very same
+ * object, so a returned block that is not one of the previous chunk's is one
+ * this chunk built. That makes the cache countable without reaching into the
+ * parser's internals.
+ */
+function blocksBuiltPerChunk(
+  fullText: string,
+  chunkSize: number,
+  options?: ParseOptions,
+): number[] {
+  const state = createIncrementalState();
+  let previous: ReadonlySet<BlockNode> = new Set();
+  const built: number[] = [];
+  const step = (text: string) => {
+    const blocks =
+      options == null
+        ? parseMarkdownIncremental(text, state)
+        : parseMarkdownIncremental(text, state, options);
+    built.push(blocks.reduce((n, b) => (previous.has(b) ? n : n + 1), 0));
+    previous = new Set(blocks);
+  };
+  for (let i = chunkSize; i <= fullText.length; i += chunkSize) {
+    step(fullText.slice(0, i));
+  }
+  step(fullText);
+  return built;
+}
+
+const median = (values: number[]): number =>
+  [...values].sort((a, b) => a - b)[Math.floor((values.length - 1) / 2)];
+
+const sum = (values: number[]): number => values.reduce((a, b) => a + b, 0);
+
 // A single wall-clock measurement is flaky when the whole suite runs in
 // parallel forks: scheduler contention can inflate a millisecond-scale
 // sample well past a tight budget (observed 30.9ms against the 20ms Small
@@ -204,3 +240,37 @@ describe('parseMarkdown performance', () => {
     expect(incrElapsed).toBeLessThanOrEqual(fullElapsed * 1.1);
   });
 });
+
+// What the incremental parser exists for is a cache, so these assert the cache:
+// integers that come out the same on a loaded CI box as on an idle laptop,
+// unlike the wall-clock budgets above.
+describe('parseMarkdownIncremental cache', () => {
+  it('builds a bounded number of blocks per chunk however long the document is', () => {
+    const chunkSize = 50;
+    const medians = [50, 200, 500].map(paragraphs =>
+      median(blocksBuiltPerChunk(generateAIResponse(paragraphs), chunkSize)),
+    );
+    console.log(
+      `  median blocks built per chunk (50/200/500 paragraphs): ${medians.join('/')}`,
+    );
+    // A chunk re-parses its unsettled tail, not the document — so the typical
+    // chunk's cost is a constant, and a 10x longer document does not move it.
+    expect(medians).toEqual([2, 2, 2]);
+  });
+
+  it('keeps the cache when source ranges are asked for', () => {
+    const text = generateAIResponse(200);
+    const chunkSize = 50;
+    const without = sum(blocksBuiltPerChunk(text, chunkSize));
+    const withRanges = sum(
+      blocksBuiltPerChunk(text, chunkSize, {sourceRanges: true}),
+    );
+    console.log(
+      `  blocks built streaming ${text.length} chars: ${without} without ranges, ${withRanges} with`,
+    );
+    // Stamping offsets must not cost a cache entry. An implementation that
+    // tracked positions by invalidating the settled cache each chunk would
+    // still pass any time budget generous enough not to flake; it fails here.
+    expect(withRanges).toBe(without);
+  });
+});