@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Layout/Layout.tsx

@@ -26,7 +26,7 @@ import {stack} from '../Stack/stack.stylex';
 import {stackItem} from '../Stack/stackItem.stylex';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
-import type {SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {
   layoutPaddingOuterXVarStyles,
@@ -76,12 +76,12 @@ const styles = stylex.create({
 });
 
 const dynamicStyles = stylex.create({
-  contentWidthVar: (width: number) => ({
-    '--layout-content-width': `${width}px`,
+  contentWidthVar: (width: SizeValue) => ({
+    '--layout-content-width': typeof width === 'number' ? `${width}px` : width,
   }),
-  contentWidth: (width: number) => ({
+  contentWidth: (width: SizeValue) => ({
     width: '100%',
-    maxWidth: width,
+    maxWidth: typeof width === 'number' ? `${width}px` : width,
     marginInline: 'auto',
   }),
 });
@@ -102,11 +102,12 @@ export interface LayoutProps extends Omit<BaseProps, 'content'> {
    * panels). Dividers remain full-bleed. Content is centered with
    * `margin-inline: auto` when narrower than the available space.
    *
-   * Accepts any pixel value. Common page widths from internal patterns:
+   * Numbers are treated as pixels, strings are used as-is (e.g., '60ch').
+   * Common page widths:
    * - `640` — forms, settings, text-focused pages
    * - `960` — content pages, component demos, wider layouts
    */
-  contentWidth?: number;
+  contentWidth?: SizeValue;
 
   /**
    * End panel slot (right in LTR, left in RTL).
@@ -149,15 +150,6 @@ export interface LayoutProps extends Omit<BaseProps, 'content'> {
    */
   defaultHasDividers?: boolean;
 
-  /**
-   * CSS class name(s) appended to the root element.
-   */
-  className?: string;
-  /**
-   * Inline styles to apply to the root element.
-   */
-  style?: React.CSSProperties;
-
   /**
    * Children are a shorthand for the `content` slot:
    * `<Layout>{main}</Layout>` is equivalent to `<Layout content={main} />`.

package/src/Layout/LayoutFooter.doc.mjs

@@ -22,8 +22,8 @@ export const docs = {
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: 'Footer height.',
+      type: 'SizeValue',
+      description: 'Footer height. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'label',
@@ -57,8 +57,8 @@ export const docsZh = {
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: '页脚高度。',
+      type: 'SizeValue',
+      description: '页脚高度。数字类型会被解释为像素值，字符串类型按原样使用。',
     },
     {
       name: 'label',

package/src/Layout/LayoutFooter.tsx

@@ -22,7 +22,7 @@ import * as stylex from '@stylexjs/stylex';
 import {LayoutDividerContext} from './LayoutDividerContext';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import type {SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {
   paddingStyles,
@@ -71,7 +71,7 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (height: number | string | null) => ({
+  sizing: (height: SizeValue | null) => ({
     height,
   }),
 });
@@ -95,7 +95,7 @@ export interface LayoutFooterProps extends BaseProps<HTMLDivElement> {
    * Height of the footer.
    * Numbers are treated as pixels, strings are used as-is.
    */
-  height?: number | string;
+  height?: SizeValue;
 
   /**
    * Internal padding of the footer using the spacing scale.

package/src/Layout/LayoutHeader.doc.mjs

@@ -22,8 +22,8 @@ export const docs = {
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: 'Header height.',
+      type: 'SizeValue',
+      description: 'Header height. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'label',
@@ -57,8 +57,8 @@ export const docsZh = {
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: '页眉高度。',
+      type: 'SizeValue',
+      description: '页眉高度。数字类型会被解释为像素值，字符串类型按原样使用。',
     },
     {
       name: 'label',

package/src/Layout/LayoutHeader.tsx

@@ -22,7 +22,7 @@ import * as stylex from '@stylexjs/stylex';
 import {LayoutDividerContext} from './LayoutDividerContext';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import type {SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {
   paddingStyles,
@@ -71,7 +71,7 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (height: number | string | null) => ({
+  sizing: (height: SizeValue | null) => ({
     height,
   }),
 });
@@ -95,7 +95,7 @@ export interface LayoutHeaderProps extends BaseProps<HTMLDivElement> {
    * Height of the header.
    * Numbers are treated as pixels, strings are used as-is.
    */
-  height?: number | string;
+  height?: SizeValue;
 
   /**
    * Internal padding of the header using the spacing scale.

package/src/Layout/LayoutPanel.tsx

@@ -23,7 +23,7 @@ import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {LayoutAreaContext} from './LayoutAreaContext';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
 import {mergeProps} from '../utils';
-import type {SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep} from '../utils/types';
 import type {ResizableProps} from '../Resizable/useResizable';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -102,7 +102,7 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (width: number | string | null) => ({
+  sizing: (width: SizeValue | null) => ({
     width,
   }),
 });
@@ -158,7 +158,7 @@ export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {
    * Numbers are treated as pixels, strings are used as-is.
    * When `resizable` is provided, this is ignored — the hook controls width.
    */
-  width?: number | string;
+  width?: SizeValue;
 
   /**
    * Resize props from `useResizable()`. When provided, the panel width

package/src/Layout/padding.stylex.ts

@@ -220,6 +220,58 @@ export const layoutPaddingOuterYVarStyles = stylex.create({
   10: {'--layout-padding-outer-y': spacingVars['--spacing-10']},
 });
 
+/**
+ * Inline-only padding styles.
+ * Use when a component needs to set inline (horizontal) padding independently
+ * of block padding — e.g. the `paddingX` prop on Stack.
+ */
+export const paddingInlineStyles = stylex.create({
+  0: {
+    paddingInlineStart: spacingVars['--spacing-0'],
+    paddingInlineEnd: spacingVars['--spacing-0'],
+  },
+  0.5: {
+    paddingInlineStart: spacingVars['--spacing-0-5'],
+    paddingInlineEnd: spacingVars['--spacing-0-5'],
+  },
+  1: {
+    paddingInlineStart: spacingVars['--spacing-1'],
+    paddingInlineEnd: spacingVars['--spacing-1'],
+  },
+  1.5: {
+    paddingInlineStart: spacingVars['--spacing-1-5'],
+    paddingInlineEnd: spacingVars['--spacing-1-5'],
+  },
+  2: {
+    paddingInlineStart: spacingVars['--spacing-2'],
+    paddingInlineEnd: spacingVars['--spacing-2'],
+  },
+  3: {
+    paddingInlineStart: spacingVars['--spacing-3'],
+    paddingInlineEnd: spacingVars['--spacing-3'],
+  },
+  4: {
+    paddingInlineStart: spacingVars['--spacing-4'],
+    paddingInlineEnd: spacingVars['--spacing-4'],
+  },
+  5: {
+    paddingInlineStart: spacingVars['--spacing-5'],
+    paddingInlineEnd: spacingVars['--spacing-5'],
+  },
+  6: {
+    paddingInlineStart: spacingVars['--spacing-6'],
+    paddingInlineEnd: spacingVars['--spacing-6'],
+  },
+  8: {
+    paddingInlineStart: spacingVars['--spacing-8'],
+    paddingInlineEnd: spacingVars['--spacing-8'],
+  },
+  10: {
+    paddingInlineStart: spacingVars['--spacing-10'],
+    paddingInlineEnd: spacingVars['--spacing-10'],
+  },
+});
+
 /**
  * Block-only padding override styles.
  * Use when a component needs to override block padding independently

package/src/Lightbox/Lightbox.doc.mjs

@@ -30,7 +30,6 @@ export const docs = {
       name: 'index',
       type: 'number',
       description: 'Current index in gallery mode (when media is an array).',
-      default: '0',
     },
     {
       name: 'onIndexChange',
@@ -65,6 +64,15 @@ export const docs = {
       { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
     ],
   },
+  playground: {
+    defaults: {
+      media: {
+        src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+        alt: 'Coastal shoreline with ocean waves',
+        caption: 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
+      },
+    },
+  },
 };
 
 /** @type {import('../docs-types').ComponentDoc} */
@@ -94,7 +102,6 @@ export const docsZh = {
       name: 'index',
       type: 'number',
       description: '画廊模式中当前索引。',
-      default: '0',
     },
     {
       name: 'onIndexChange',

package/src/Lightbox/Lightbox.test.tsx

@@ -177,7 +177,7 @@ describe('Lightbox', () => {
       expect(screen.getByLabelText('Next')).toBeInTheDocument();
     });
 
-    it('hides prev button on first item', () => {
+    it('keeps prev mounted and disabled on first item', () => {
       render(
         <Lightbox
           isOpen={true}
@@ -186,11 +186,16 @@ describe('Lightbox', () => {
           index={0}
         />,
       );
-      expect(screen.queryByLabelText('Previous')).not.toBeInTheDocument();
-      expect(screen.getByLabelText('Next')).toBeInTheDocument();
+      // The Prev button stays mounted at the range boundary (disabled) rather
+      // than unmounting, so navigating to the first item never removes the
+      // focused control and drops focus to <body>.
+      const prev = screen.getByLabelText('Previous');
+      expect(prev).toBeInTheDocument();
+      expect(prev).toBeDisabled();
+      expect(screen.getByLabelText('Next')).not.toBeDisabled();
     });
 
-    it('hides next button on last item', () => {
+    it('keeps next mounted and disabled on last item', () => {
       render(
         <Lightbox
           isOpen={true}
@@ -199,8 +204,51 @@ describe('Lightbox', () => {
           index={2}
         />,
       );
+      const next = screen.getByLabelText('Next');
+      expect(next).toBeInTheDocument();
+      expect(next).toBeDisabled();
+      expect(screen.getByLabelText('Previous')).not.toBeDisabled();
+    });
+
+    it('does not drop focus to <body> when navigating to the last item', () => {
+      const {rerender} = render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+        />,
+      );
+      // Simulate arriving at the final item (Next becomes disabled).
+      rerender(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={2}
+        />,
+      );
+      // Both nav buttons remain in the DOM; the dialog stays available so
+      // keyboard gallery navigation isn't dead-ended.
       expect(screen.getByLabelText('Previous')).toBeInTheDocument();
-      expect(screen.queryByLabelText('Next')).not.toBeInTheDocument();
+      expect(screen.getByLabelText('Next')).toBeInTheDocument();
+      const dialog = document.querySelector('dialog');
+      expect(dialog).toBeInTheDocument();
+      // Arrow handling is on the dialog, so navigation still works at the edge.
+      const onIndexChange = vi.fn();
+      rerender(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={2}
+          onIndexChange={onIndexChange}
+        />,
+      );
+      if (dialog instanceof HTMLElement) {
+        fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+      }
+      expect(onIndexChange).toHaveBeenCalledWith(1);
     });
 
     it('calls onIndexChange when next is clicked', () => {

package/src/Lightbox/Lightbox.tsx

@@ -496,13 +496,16 @@ export function Lightbox({
           />
         </div>
 
-        {/* Gallery nav: prev */}
-        {isGallery && canPrev && (
+        {/* Gallery nav: prev — stays mounted and is disabled at the start of
+            the range so pressing/arrowing to the boundary doesn't unmount the
+            focused control and drop focus to <body>. */}
+        {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navPrev)}>
             <IconButton
               icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
               label="Previous"
               variant="ghost"
+              isDisabled={!canPrev}
               onClick={goToPrev}
               xstyle={styles.controlButton}
             />
@@ -549,13 +552,15 @@ export function Lightbox({
           )}
         </div>
 
-        {/* Gallery nav: next */}
-        {isGallery && canNext && (
+        {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
+            the end of the range instead of unmounting. */}
+        {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navNext)}>
             <IconButton
               icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
               label="Next"
               variant="ghost"
+              isDisabled={!canNext}
               onClick={goToNext}
               xstyle={styles.controlButton}
             />

package/src/Link/Link.doc.mjs

@@ -59,6 +59,13 @@ export const docs = {
             'Opens in new tab with external icon and safe rel tokens',
           default: 'false',
         },
+        {
+          name: 'newTabLabel',
+          type: 'string',
+          description:
+            'Screen-reader text announcing that an external link opens in a new tab. Override for localization.',
+          default: "'(opens in new tab)'",
+        },
         {
           name: 'target',
           type: 'string',
@@ -185,6 +192,12 @@ export const docsZh = {
           description: '在新标签页中打开，带外部图标和安全 rel 标记',
           default: 'false',
         },
+        {
+          name: 'newTabLabel',
+          type: 'string',
+          description: '向屏幕阅读器announce外部链接将在新标签页打开的文本。可覆盖以本地化。',
+          default: "'(opens in new tab)'",
+        },
         {
           name: 'target',
           type: 'string',
@@ -296,6 +309,7 @@ export const docsDense = {
         hasUnderline: 'Always show underline',
         isDisabled: 'Disables link',
         isExternalLink: 'Opens new tab w/ external icon and safe rel tokens',
+        newTabLabel: 'SR text announcing an external link opens in a new tab',
         target:
           'Where to open linked document. target="_blank" auto-adds noopener noreferrer.',
         rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',

package/src/Link/Link.test.tsx

@@ -99,8 +99,8 @@ describe('Link', () => {
 
   it('renders with different color values', () => {
     const {rerender} = render(
-      <Link href="/test" color="active">
-        Active
+      <Link href="/test" color="accent">
+        Accent
       </Link>,
     );
     expect(screen.getByRole('link')).toBeInTheDocument();
@@ -120,6 +120,24 @@ describe('Link', () => {
     expect(screen.getByRole('link')).toBeInTheDocument();
   });
 
+  it('defaults the inner text type to body', () => {
+    render(<Link href="/test">Body link</Link>);
+    expect(screen.getByText('Body link')).toHaveClass('astryx-text', 'body');
+  });
+
+  it('forwards type="inherit" so the link adopts the surrounding text type', () => {
+    render(
+      <Link href="/test" type="inherit">
+        Inline link
+      </Link>,
+    );
+    // The inner Text renders with the `inherit` type, so font-size/line-height
+    // inherit from the surrounding text rather than imposing the body type.
+    const text = screen.getByText('Inline link');
+    expect(text).toHaveClass('astryx-text', 'inherit');
+    expect(text).not.toHaveClass('body');
+  });
+
   it('applies hasUnderline style when true', () => {
     render(
       <Link href="/test" hasUnderline>
@@ -152,6 +170,38 @@ describe('Link', () => {
     expect(link.querySelector('svg')).toBeInTheDocument();
   });
 
+  it('announces the new-tab context via screen-reader text (obs-4)', () => {
+    render(
+      <Link href="https://example.com" isExternalLink>
+        Docs
+      </Link>,
+    );
+    // The link's accessible name includes the new-tab hint (the icon is
+    // decorative).
+    expect(
+      screen.getByRole('link', {name: 'Docs (opens in new tab)'}),
+    ).toBeInTheDocument();
+  });
+
+  it('supports a custom newTabLabel for localization', () => {
+    render(
+      <Link
+        href="https://example.com"
+        isExternalLink
+        newTabLabel="(new window)">
+        Docs
+      </Link>,
+    );
+    expect(
+      screen.getByRole('link', {name: 'Docs (new window)'}),
+    ).toBeInTheDocument();
+  });
+
+  it('does not add new-tab text to non-external links', () => {
+    render(<Link href="/internal">Internal</Link>);
+    expect(screen.getByRole('link', {name: 'Internal'})).toBeInTheDocument();
+  });
+
   it('renders external link with existing rel merged', () => {
     render(
       <Link href="https://example.com" isExternalLink rel="sponsored">

package/src/Link/Link.tsx

@@ -30,6 +30,7 @@ import {
 import {Icon} from '../Icon';
 import {Tooltip} from '../Tooltip';
 import {Text} from '../Text';
+import {VisuallyHidden} from '../VisuallyHidden';
 import type {
   TextType,
   TextSize,
@@ -106,10 +107,20 @@ const styles = stylex.create({
  */
 const linkColorStyles = stylex.create({
   primary: {
-    color: colorVars['--color-text-primary'],
+    color: {
+      default: colorVars['--color-text-primary'],
+      ':hover': {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-primary']}, ${colorVars['--color-tint-hover']} 15%)`,
+      },
+    },
   },
   secondary: {
-    color: colorVars['--color-text-secondary'],
+    color: {
+      default: colorVars['--color-text-secondary'],
+      ':hover': {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-secondary']}, ${colorVars['--color-tint-hover']} 15%)`,
+      },
+    },
   },
   disabled: {
     color: colorVars['--color-text-disabled'],
@@ -117,8 +128,13 @@ const linkColorStyles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
-  active: {
-    color: colorVars['--color-text-accent'],
+  accent: {
+    color: {
+      default: colorVars['--color-text-accent'],
+      ':hover': {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
+      },
+    },
   },
   inherit: {
     color: 'inherit',
@@ -167,6 +183,12 @@ export interface LinkProps extends BaseProps<
    * @default false
    */
   isExternalLink?: boolean;
+  /**
+   * Screen-reader text appended to an external link to announce that it opens
+   * in a new tab (the visual icon is decorative). Override for localization.
+   * @default '(opens in new tab)'
+   */
+  newTabLabel?: string;
   /**
    * Where to open the linked document.
    * Overridden to "_blank" when isExternalLink is true.
@@ -203,6 +225,10 @@ export interface LinkProps extends BaseProps<
   isStandalone?: boolean;
   /**
    * Semantic text type for Text. Determines base typography.
+   *
+   * Use `type="inherit"` for inline links inside an existing `Text` element so
+   * the link adopts the surrounding text's size and line-height instead of
+   * imposing its own (e.g. a link within a `large` paragraph).
    * @default 'body'
    */
   type?: TextType;
@@ -216,7 +242,7 @@ export interface LinkProps extends BaseProps<
   weight?: TextWeight;
   /**
    * Text color. Forwarded to Text.
-   * @default 'active'
+   * @default 'accent'
    */
   color?: TextColor;
   /**
@@ -248,6 +274,11 @@ export interface LinkProps extends BaseProps<
  * <Link href="/settings" color="secondary">Settings</Link>
  * <Link href="/privacy" hasUnderline>Privacy Policy</Link>
  * <Link label="Close dialog" href="/home"><Icon icon="x" /></Link>
+ *
+ * // Inline link inside text — inherits the surrounding type/size:
+ * <Text type="large">
+ *   Read our <Link href="/terms" type="inherit">terms</Link> first.
+ * </Text>
  * ```
  */
 export function Link({
@@ -257,6 +288,7 @@ export function Link({
   hasUnderline = false,
   isDisabled = false,
   isExternalLink = false,
+  newTabLabel = '(opens in new tab)',
   target: targetFromProps,
   onClick,
   tooltip,
@@ -264,7 +296,7 @@ export function Link({
   type = 'body',
   size,
   weight,
-  color = 'active',
+  color = 'accent',
   display = 'inline',
   maxLines = 0,
   children,
@@ -300,7 +332,10 @@ export function Link({
         {children}
       </Text>
       {isExternalLink && !renderAsButton && (
-        <Icon icon="externalLink" size="xsm" color="inherit" />
+        <>
+          <Icon icon="externalLink" size="xsm" color="inherit" />
+          <VisuallyHidden>{newTabLabel}</VisuallyHidden>
+        </>
       )}
     </>
   );

package/src/Link/LinkProvider.tsx

@@ -23,6 +23,7 @@
  * - /packages/core/src/Link/index.ts
  * - /packages/core/src/Link/Link.doc.mjs
  * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/templates/blocks/components/LinkProvider/ (example blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';

package/src/List/List.doc.mjs

@@ -61,6 +61,13 @@ export const docs = {
       description: "List marker style. 'decimal' renders an <ol> element instead of <ul>.",
       default: "'none'",
     },
+    {
+      name: 'start',
+      type: 'number',
+      description:
+        "Starting number for ordered lists (listStyle='decimal'). Sets the CSS counter to begin at this value.",
+      default: '1',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Markdown/Markdown.doc.mjs

@@ -75,6 +75,7 @@ export const docs = {
       type: 'number | string',
       description:
         'Max width for prose content (paragraphs, headings, lists, blockquotes). Tables and code blocks are unconstrained and can expand to the full container width. Use for readable line lengths in wide layouts.',
+      default: '680',
     },
     {
       name: 'contentAlign',
@@ -245,6 +246,7 @@ export const docsZh = {
       type: 'number | string',
       description:
         '正文内容的最大宽度（段落、标题、列表、引用块）。表格和代码块不受限制，可扩展到完整容器宽度。用于在宽布局中保持可读行长。',
+      default: '680',
     },
     {
       name: 'contentAlign',