@astryxdesign/core 0.1.6 → 0.1.7-canary.0a6de96

package/src/Icon/Icon.tsx

@@ -111,51 +111,64 @@ const colorStyles = stylex.create({
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = stylex.create({
   xsm: {
-    width: 12,
-    height: 12,
+    width: '0.75rem',
+    height: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
+    width: '1rem',
+    height: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
+    width: '1.25rem',
+    height: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
+    width: '1.5rem',
+    height: '1.5rem',
   },
 });
 
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = stylex.create({
+  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
+     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
+     the 14px-anchored textSizeVars type scale. Values are rem so icons track
+     the root font-size. */
   xsm: {
-    width: 12,
-    height: 12,
-    fontSize: 12,
+    width: '0.75rem',
+    height: '0.75rem',
+    fontSize: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
-    fontSize: 16,
+    width: '1rem',
+    height: '1rem',
+    fontSize: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
-    fontSize: 20,
+    width: '1.25rem',
+    height: '1.25rem',
+    fontSize: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
-    fontSize: 24,
+    width: '1.5rem',
+    height: '1.5rem',
+    fontSize: '1.5rem',
   },
+  /* eslint-enable @astryx/no-hardcoded-styles */
 });
 
 // =============================================================================
@@ -194,10 +207,10 @@ export interface IconProps extends Omit<
   color?: IconColor;
   /**
    * The size of the icon.
-   * - 'xsm': 12px
-   * - 'sm': 16px
-   * - 'md': 20px
-   * - 'lg': 24px
+   * - 'xsm': 0.75rem (12px at a 16px root)
+   * - 'sm': 1rem (16px at a 16px root)
+   * - 'md': 1.25rem (20px at a 16px root)
+   * - 'lg': 1.5rem (24px at a 16px root)
    * @default 'md'
    */
   size?: IconSize;

package/src/InputGroup/InputGroup.doc.mjs

@@ -76,7 +76,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator applied to the group border.',
     },
     {

package/src/Kbd/Kbd.test.tsx

@@ -119,4 +119,30 @@ describe('Kbd', () => {
     expect(screen.getByText('⇧')).toBeInTheDocument();
     expect(screen.getByText('+')).toBeInTheDocument();
   });
+
+  it('keeps the computed role and aria-label when unrelated rest props are spread', () => {
+    render(<Kbd keys="mod+k" data-testid="kbd" id="shortcut" />);
+    const el = screen.getByTestId('kbd');
+    // Pass-through attributes land on the wrapper...
+    expect(el).toHaveAttribute('id', 'shortcut');
+    // ...without disturbing the computed accessibility contract.
+    expect(el).toHaveAttribute('role', 'img');
+    expect(el).toHaveAttribute('aria-label', 'Control + K');
+  });
+
+  it('computed role and aria-label win over consumer-passed overrides', () => {
+    // Contract props the component computes must not be clobbered by
+    // pass-through attributes: {...rest} is spread before role/aria-label.
+    render(
+      <Kbd
+        keys="mod+k"
+        role="presentation"
+        aria-label="custom"
+        data-testid="kbd"
+      />,
+    );
+    const el = screen.getByTestId('kbd');
+    expect(el).toHaveAttribute('role', 'img');
+    expect(el).toHaveAttribute('aria-label', 'Control + K');
+  });
 });

package/src/Kbd/Kbd.tsx

@@ -188,10 +188,10 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
 
   return (
     <span
+      {...rest}
       ref={ref}
       role="img"
       aria-label={accessibleName}
-      {...rest}
       {...mergeProps(
         themeProps('kbd'),
         stylex.props(styles.wrapper, xstyle),

package/src/Layer/useLayer.doc.mjs

@@ -72,13 +72,14 @@ export const docs = {
     {
       name: 'id',
       type: 'string',
-      description: 'Unique ID for aria-describedby or other ARIA relationships.',
+      description:
+        'Unique ID for aria-describedby or other ARIA relationships.',
     },
     {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles — including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
     },
   ],
   usage: {
@@ -130,7 +131,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring — yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
+    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
   },
   usage: {
     description:
@@ -138,11 +139,13 @@ export const docsDense = {
     bestPractices: [
       {
         guidance: true,
-        description: 'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
+        description:
+          'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
       },
       {
         guidance: true,
-        description: 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
+        description:
+          'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
       },
       {
         guidance: true,

package/src/Layer/useLayer.test.tsx

@@ -12,7 +12,7 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useLayer} from './useLayer';
+import {useLayer, getPositionTryFallbacks} from './useLayer';
 import type {
   LayerPlacement,
   LayerAlignment,
@@ -33,6 +33,141 @@ function LayerHarness({
   return <>{layer.render(<span>Layer content</span>, {x: 0, y: 0})}</>;
 }
 
+/**
+ * Context-mode harness: renders a trigger plus the layer so tests can assert
+ * on the anchor-positioning styles applied to the popover element.
+ */
+function ContextLayerHarness({
+  placement,
+  alignment,
+}: {
+  placement?: LayerPlacement;
+  alignment?: LayerAlignment;
+}) {
+  const layer = useLayer({mode: 'context'});
+  return (
+    <>
+      <button type="button" ref={layer.ref}>
+        Trigger
+      </button>
+      {layer.render(<span>Layer content</span>, {placement, alignment})}
+    </>
+  );
+}
+
+describe('getPositionTryFallbacks (issue #3671)', () => {
+  const FLIPS = 'flip-block, flip-inline, flip-block flip-inline';
+
+  it('appends inline span fallbacks for centered above/below layers so inline overflow can resolve (flip-inline is a no-op on center)', () => {
+    expect(getPositionTryFallbacks('above', 'center')).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+    expect(getPositionTryFallbacks('below', 'center')).toBe(
+      `${FLIPS}, bottom span-left, bottom span-right, top span-left, top span-right`,
+    );
+  });
+
+  it('appends block span fallbacks for centered start/end layers so block overflow can resolve (flip-block is a no-op on center)', () => {
+    expect(getPositionTryFallbacks('start', 'center')).toBe(
+      `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+    );
+    expect(getPositionTryFallbacks('end', 'center')).toBe(
+      `${FLIPS}, right span-top, right span-bottom, left span-top, left span-bottom`,
+    );
+  });
+
+  it('keeps flip-only fallbacks for non-centered alignments (flips already resolve overflow there)', () => {
+    const nonCentered: [LayerPlacement, LayerAlignment][] = [
+      ['above', 'start'],
+      ['above', 'end'],
+      ['below', 'start'],
+      ['below', 'end'],
+      ['start', 'start'],
+      ['start', 'end'],
+      ['end', 'start'],
+      ['end', 'end'],
+    ];
+    for (const [placement, alignment] of nonCentered) {
+      expect(getPositionTryFallbacks(placement, alignment)).toBe(FLIPS);
+    }
+  });
+
+  it('defaults to above/center when called without arguments (matches renderContext defaults)', () => {
+    expect(getPositionTryFallbacks()).toBe(
+      getPositionTryFallbacks('above', 'center'),
+    );
+    expect(getPositionTryFallbacks(undefined, undefined)).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+  });
+
+  it('produces well-formed, duplicate-free lists with flips first and axis-correct spans for every placement/alignment combo', () => {
+    const placements: LayerPlacement[] = ['above', 'below', 'start', 'end'];
+    const alignments: LayerAlignment[] = ['start', 'center', 'end'];
+    const spanPattern: Record<LayerPlacement, RegExp> = {
+      above: /^(top|bottom) span-(left|right)$/,
+      below: /^(top|bottom) span-(left|right)$/,
+      start: /^(left|right) span-(top|bottom)$/,
+      end: /^(left|right) span-(top|bottom)$/,
+    };
+
+    for (const placement of placements) {
+      for (const alignment of alignments) {
+        const list = getPositionTryFallbacks(placement, alignment);
+        const items = list.split(', ');
+
+        expect(items.slice(0, 3)).toEqual([
+          'flip-block',
+          'flip-inline',
+          'flip-block flip-inline',
+        ]);
+        expect(new Set(items).size).toBe(items.length);
+        for (const item of items.slice(3)) {
+          expect(item).toMatch(spanPattern[placement]);
+        }
+        expect(items.length).toBe(alignment === 'center' ? 7 : 3);
+      }
+    }
+  });
+
+  it('updates the fallback list when placement/alignment props change on re-render', () => {
+    const {container, rerender} = render(
+      <ContextLayerHarness placement="above" alignment="center" />,
+    );
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl.style.positionTryFallbacks).toContain('top span-left');
+
+    rerender(<ContextLayerHarness placement="above" alignment="start" />);
+    expect(layerEl.style.positionTryFallbacks).toBe(FLIPS);
+
+    rerender(<ContextLayerHarness placement="start" alignment="center" />);
+    expect(layerEl.style.positionTryFallbacks).toBe(
+      `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+    );
+  });
+
+  it('does not apply anchor fallbacks in fixed mode (manual coordinates)', () => {
+    function FixedHarness() {
+      const layer = useLayer({mode: 'fixed'});
+      return <>{layer.render(<span>Fixed content</span>, {x: 10, y: 20})}</>;
+    }
+    const {container} = render(<FixedHarness />);
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl.style.positionTryFallbacks ?? '').toBeFalsy();
+    expect(layerEl.style.left).toBe('10px');
+    expect(layerEl.style.top).toBe('20px');
+  });
+
+  it('applies span fallbacks to the rendered popover for the default (above/center) layer', () => {
+    const {container} = render(<ContextLayerHarness />);
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl).not.toBeNull();
+    expect(layerEl.style.positionTryFallbacks).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+  });
+});
+
 describe('useLayer', () => {
   const originalShowPopover = HTMLElement.prototype.showPopover;
   const originalHidePopover = HTMLElement.prototype.hidePopover;

package/src/Layer/useLayer.tsx

@@ -320,6 +320,36 @@ function getPositionArea(
   return inline; // center
 }
 
+/**
+ * Compute the `position-try-fallbacks` list for a placement/alignment pair.
+ *
+ * Flips alone cannot rescue a centered layer — flipping along the alignment
+ * axis maps center → center, so overflow on that axis renders clipped
+ * (#3671). Centered alignments therefore append span-based fallbacks letting
+ * the browser slide the layer along the alignment axis as a last resort
+ * (same-side spans first). Flips already resolve non-centered alignments.
+ */
+export function getPositionTryFallbacks(
+  placement: LayerPlacement = 'above',
+  alignment: LayerAlignment = 'center',
+): string {
+  const flips = 'flip-block, flip-inline, flip-block flip-inline';
+
+  if (alignment !== 'center') {
+    return flips;
+  }
+
+  if (placement === 'above' || placement === 'below') {
+    const [same, opposite] =
+      placement === 'above' ? ['top', 'bottom'] : ['bottom', 'top'];
+    return `${flips}, ${same} span-left, ${same} span-right, ${opposite} span-left, ${opposite} span-right`;
+  }
+
+  const [same, opposite] =
+    placement === 'start' ? ['left', 'right'] : ['right', 'left'];
+  return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
+}
+
 /**
  * Core layer hook that handles popover behavior and positioning.
  *
@@ -512,8 +542,10 @@ export function useLayer(
           : {
               positionAnchor: anchorId,
               positionArea: getPositionArea(placement, alignment),
-              positionTryFallbacks:
-                'flip-block, flip-inline, flip-block flip-inline',
+              positionTryFallbacks: getPositionTryFallbacks(
+                placement,
+                alignment,
+              ),
             };
 
       const stylexResult = stylex.props(styles.base, xstyle);

package/src/Lightbox/Lightbox.doc.mjs

@@ -22,8 +22,13 @@ export const docs = {
     },
     {
       name: 'media',
+      // Left as the named type on purpose: the shape carries `caption?:
+      // ReactNode`, so spelling it out makes the docsite playground parse the
+      // whole prop as an editable *string*, which would feed the preview text
+      // where a media object belongs. The shape and its legal values live in
+      // the description instead (#1645).
       type: 'LightboxMedia | LightboxMedia[]',
-      description: 'Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item has src, alt, optional caption and type.',
+      description: "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
       required: true,
     },
     {
@@ -100,7 +105,7 @@ export const docsZh = {
     {
       name: 'media',
       type: 'LightboxMedia | LightboxMedia[]',
-      description: '要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。',
+      description: "要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。每项为 {src, alt, caption?, type?: 'image' | 'video'}；type 默认为 'image'，'video' 禁用缩放/平移。",
       required: true,
     },
     {

package/src/Lightbox/Lightbox.tsx

@@ -35,6 +35,7 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 /**
  * Media type for lightbox items.
@@ -282,6 +283,7 @@ export function Lightbox({
   onKeyDown: onKeyDownProp,
   ...props
 }: LightboxProps) {
+  const t = useTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);
@@ -504,7 +506,7 @@ export function Lightbox({
         handleKeyDown(e);
         onKeyDownProp?.(e);
       }}
-      aria-label={currentItem.alt || 'Media viewer'}
+      aria-label={currentItem.alt || t('@astryx.lightbox.mediaViewer')}
       {...mergeProps(
         themeProps('lightbox'),
         stylex.props(styles.dialog, xstyle),
@@ -517,7 +519,7 @@ export function Lightbox({
         <div {...stylex.props(styles.closeButton)}>
           <IconButton
             icon={<Icon icon="close" size="sm" color="inherit" />}
-            label="Close"
+            label={t('@astryx.lightbox.close')}
             variant="ghost"
             onClick={handleClose}
             xstyle={styles.controlButton}
@@ -531,7 +533,7 @@ export function Lightbox({
           <div {...stylex.props(styles.navButton, styles.navPrev)}>
             <IconButton
               icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
-              label="Previous"
+              label={t('@astryx.lightbox.previous')}
               variant="ghost"
               isDisabled={!canPrev}
               onClick={goToPrev}
@@ -586,7 +588,7 @@ export function Lightbox({
           <div {...stylex.props(styles.navButton, styles.navNext)}>
             <IconButton
               icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
-              label="Next"
+              label={t('@astryx.lightbox.next')}
               variant="ghost"
               isDisabled={!canNext}
               onClick={goToNext}

package/src/Link/Link.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Link} from './Link';
 import {LinkProvider} from './LinkProvider';
@@ -153,9 +153,81 @@ describe('Link', () => {
         Disabled Link
       </Link>,
     );
-    const link = screen.getByRole('link');
+    // An href-less anchor has no implicit `link` role, so query by text.
+    const link = screen.getByText('Disabled Link').closest('a');
+    expect(link).not.toBeNull();
     expect(link).toHaveAttribute('aria-disabled', 'true');
     expect(link).toHaveAttribute('tabIndex', '-1');
+    // Visual classes are preserved in the disabled state.
+    expect(link?.className).toContain('astryx-link');
+  });
+
+  it('disabled link has no href attribute', () => {
+    render(
+      <Link href="/test" isDisabled>
+        Disabled Link
+      </Link>,
+    );
+    const link = screen.getByText('Disabled Link').closest('a');
+    expect(link).not.toBeNull();
+    expect(link).not.toHaveAttribute('href');
+  });
+
+  it('clicking a disabled link cancels default navigation', () => {
+    render(
+      <Link href="/test" isDisabled>
+        Disabled Link
+      </Link>,
+    );
+    const link = screen.getByText('Disabled Link').closest('a');
+    expect(link).not.toBeNull();
+    // fireEvent bypasses pointer-events, simulating programmatic/AT
+    // activation. It returns false when preventDefault was called, i.e.
+    // any default navigation behavior is cancelled.
+    const notCancelled = fireEvent.click(link as HTMLAnchorElement);
+    expect(notCancelled).toBe(false);
+  });
+
+  it('disabled link with onClick fires neither navigation nor the consumer onClick', () => {
+    const handleClick = vi.fn();
+    const {container} = render(
+      <Link href="/test" isDisabled onClick={handleClick}>
+        Disabled Link
+      </Link>,
+    );
+    // With onClick present, a disabled Link renders as a disabled <button>
+    // (useInteractiveRole excludes a disabled href). Either way the rendered
+    // root must carry no live href and never invoke the consumer handler.
+    const el = container.firstElementChild as HTMLElement;
+    expect(el).not.toHaveAttribute('href');
+    fireEvent.click(el);
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('disabled link omits target and rel', () => {
+    render(
+      <Link href="https://example.com" isDisabled isExternalLink>
+        Disabled External
+      </Link>,
+    );
+    const link = screen.getByText('Disabled External').closest('a');
+    expect(link).not.toBeNull();
+    expect(link).not.toHaveAttribute('target');
+    expect(link).not.toHaveAttribute('rel');
+  });
+
+  it('disabled link renders a plain anchor, not the custom LinkComponent', () => {
+    render(
+      <LinkProvider component={CustomLink}>
+        <Link href="/custom" as={CustomLink} isDisabled>
+          Disabled Custom
+        </Link>
+      </LinkProvider>,
+    );
+    const link = screen.getByText('Disabled Custom').closest('a');
+    expect(link).not.toBeNull();
+    expect(link).not.toHaveAttribute('data-custom-link');
+    expect(link).not.toHaveAttribute('href');
   });
 
   it('renders external link with icon and target="_blank"', () => {

package/src/Link/Link.tsx

@@ -44,6 +44,7 @@ import {mergeProps} from '../utils';
 import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 /**
  * Base link styles
@@ -174,6 +175,10 @@ export interface LinkProps extends BaseProps<
   hasUnderline?: boolean;
   /**
    * Whether the link is disabled.
+   * A disabled link renders as a plain anchor without an href (and without
+   * target/rel/onClick), so it cannot be focused or activated — no
+   * navigation and no onClick, even via programmatic focus or assistive
+   * technology activation.
    * @default false
    */
   isDisabled?: boolean;
@@ -261,6 +266,15 @@ export interface LinkProps extends BaseProps<
   children: ReactNode;
 }
 
+/**
+ * Click handler for disabled links. The disabled anchor renders without an
+ * href, so there is no navigation to block in practice; preventDefault is a
+ * defensive guard against synthetic/programmatic clicks.
+ */
+function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
+  event.preventDefault();
+}
+
 /**
  * A styled anchor link component.
  *
@@ -286,7 +300,7 @@ export function Link({
   hasUnderline = false,
   isDisabled = false,
   isExternalLink = false,
-  newTabLabel = '(opens in new tab)',
+  newTabLabel: newTabLabelFromProps,
   target: targetFromProps,
   onClick,
   tooltip,
@@ -305,6 +319,8 @@ export function Link({
   ref,
   ...props
 }: LinkProps) {
+  const t = useTranslator();
+  const newTabLabel = newTabLabelFromProps ?? t('@astryx.link.newTab');
   const LinkComponent = useLinkComponent(as);
   const role = useInteractiveRole({href, onClick, isDisabled});
   // Determine target and rel based on isExternalLink
@@ -368,6 +384,37 @@ export function Link({
         {sharedContent}
       </button>
     );
+  } else if (isDisabled) {
+    // A disabled link renders as a plain <a> with no href: an href-less
+    // anchor is not focusable and exposes no link affordance, so programmatic
+    // focus + Enter, AT activation commands, and middle-click cannot navigate
+    // or fire the consumer onClick. The router LinkComponent is deliberately
+    // skipped — a disabled link performs no navigation, and custom router
+    // links may require a live href. target/rel are omitted with the href.
+    linkElement = (
+      <a
+        ref={ref as React.Ref<HTMLAnchorElement>}
+        onClick={preventDefaultClick}
+        aria-label={label || undefined}
+        aria-disabled={true}
+        tabIndex={-1}
+        {...mergeProps(
+          themeProps('link', {color}),
+          stylex.props(
+            styles.base,
+            linkColorStyles[color],
+            hasUnderline && styles.hasUnderline,
+            isStandalone && styles.standalone,
+            styles.disabled,
+            xstyle,
+          ),
+          className,
+          style,
+        )}
+        {...props}>
+        {sharedContent}
+      </a>
+    );
   } else {
     linkElement = (
       <LinkComponent