@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Layer/outsidePress.ts

@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file outsidePress.ts
+ * @input Listens for pointerdown, pointerup and pointercancel on a document
+ * @output Exports watchOutsidePress and useOutsidePress, which owns one watch
+ *   for a component: start on show, stop on hide, stop on unmount; and the
+ *   inside tests a text field's owner runs: isPressInsideOwnedLayer for a
+ *   press, isFocusInsideOwnedLayer for a blur
+ * @position Internal to Layer; the outside-press dismissal for a manual
+ *   popover whose owner decides what counts as inside (a combobox's field
+ *   and its list). Not exported from the package.
+ *
+ * A press closes the layer only when it starts and ends outside, as native
+ * light dismiss does: a pointerdown outside is remembered, the pointerup that
+ * follows closes the layer if it is outside too, and a pointercancel (the
+ * browser took the gesture for a scroll or a pinch) forgets it. Inside is
+ * judged on the event's composed path, so a field or list inside an open
+ * shadow root, which the document sees as its shadow host, is still inside.
+ */
+
+import {useCallback, useEffect, useMemo, useRef} from 'react';
+
+/**
+ * Watch the owner's document for a press outside, until the returned function
+ * is called. The caller stops it when its layer hides and when it unmounts.
+ *
+ * @param owner - The element that owns the layer (the field); its document is
+ *   watched.
+ * @param isInside - Whether a press with this composed path is inside.
+ * @param onOutside - Called once for each press that starts and ends outside.
+ * @returns Stops watching.
+ */
+export function watchOutsidePress(
+  owner: Element,
+  isInside: (path: ReadonlyArray<EventTarget>) => boolean,
+  onOutside: () => void,
+): () => void {
+  const doc = owner.ownerDocument;
+  let startedOutside = false;
+
+  // Capture phase, so a press whose target stops propagation is still seen.
+  const handleDown = (event: PointerEvent) => {
+    startedOutside = !isInside(event.composedPath());
+  };
+  const handleUp = (event: PointerEvent) => {
+    const wasOutside = startedOutside;
+    startedOutside = false;
+    if (wasOutside && !isInside(event.composedPath())) {
+      onOutside();
+    }
+  };
+  const handleCancel = () => {
+    startedOutside = false;
+  };
+
+  doc.addEventListener('pointerdown', handleDown, true);
+  doc.addEventListener('pointerup', handleUp, true);
+  doc.addEventListener('pointercancel', handleCancel, true);
+  return () => {
+    doc.removeEventListener('pointerdown', handleDown, true);
+    doc.removeEventListener('pointerup', handleUp, true);
+    doc.removeEventListener('pointercancel', handleCancel, true);
+  };
+}
+
+export interface OutsidePressWatch {
+  /** Start watching, replacing any watch already running. */
+  start: (
+    owner: Element,
+    isInside: (path: ReadonlyArray<EventTarget>) => boolean,
+    onOutside: () => void,
+  ) => void;
+  /** Stop watching; does nothing when no watch is running. */
+  stop: () => void;
+}
+
+/**
+ * One outside-press watch for a component: it calls `start` when its layer
+ * shows and `stop` when it hides, and the watch's document listeners (an
+ * external system) are removed when the component unmounts with it running.
+ * Both functions are stable.
+ */
+export function useOutsidePress(): OutsidePressWatch {
+  const stopRef = useRef<(() => void) | null>(null);
+  const stop = useCallback(() => {
+    stopRef.current?.();
+    stopRef.current = null;
+  }, []);
+  const start = useCallback<OutsidePressWatch['start']>(
+    (owner, isInside, onOutside) => {
+      stopRef.current?.();
+      stopRef.current = watchOutsidePress(owner, isInside, onOutside);
+    },
+    [],
+  );
+  useEffect(() => stop, [stop]);
+  return useMemo(() => ({start, stop}), [start, stop]);
+}
+
+// Node, Element and ShadowRoot are checked by nodeType, not instanceof: a
+// node from a same-origin iframe or a Picture-in-Picture window belongs to
+// another realm, where instanceof against this window's classes is false.
+function isNode(target: unknown): target is Node {
+  return (
+    typeof target === 'object' &&
+    target !== null &&
+    typeof (target as {nodeType?: unknown}).nodeType === 'number'
+  );
+}
+
+function isElement(node: Node): node is Element {
+  return node.nodeType === 1;
+}
+
+function isShadowRoot(node: Node): node is ShadowRoot {
+  return node.nodeType === 11 && 'host' in node;
+}
+
+/** Whether `node` is the layer with this id, or inside it across shadow roots. */
+function isWithinLayer(node: Node, layerId: string): boolean {
+  for (
+    let current: Node | null = node;
+    current != null;
+    current =
+      current.parentNode ?? (isShadowRoot(current) ? current.host : null)
+  ) {
+    if (isElement(current) && current.id === layerId) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a press with this composed path is on a text field or in the
+ * field's own layer, which may be hosted outside the field.
+ *
+ * @param path - The press's composed path.
+ * @param field - The field that owns the layer.
+ * @param layerId - The layer element's id.
+ */
+export function isPressInsideOwnedLayer(
+  path: ReadonlyArray<EventTarget>,
+  field: Element,
+  layerId: string,
+): boolean {
+  return path.some(
+    target =>
+      target === field ||
+      (layerId !== '' &&
+        isNode(target) &&
+        isElement(target) &&
+        target.id === layerId),
+  );
+}
+
+/**
+ * Whether focus moving to `next` stays with a text field's own layer: on the
+ * field, or in the layer, which may be hosted outside the field or inside a
+ * shadow root. Each owner decides what a blur that fails this means,
+ * including when `next` is null.
+ *
+ * @param next - The blur's `relatedTarget`.
+ * @param field - The field that owns the layer.
+ * @param layerId - The layer element's id.
+ */
+export function isFocusInsideOwnedLayer(
+  next: EventTarget | null,
+  field: Element | null | undefined,
+  layerId: string,
+): boolean {
+  return (
+    isNode(next) &&
+    (field?.contains(next) === true || isWithinLayer(next, layerId))
+  );
+}

package/src/Layer/useLayer.tsx

@@ -29,6 +29,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {createPortal} from 'react-dom';
 import {LayerContentBoundary} from './layerScopedContext';
+import {layerClickBoundary} from './layerClickBoundary';
 import {addAnchorName, removeAnchorName} from './anchorName';
 import {currentGesture, currentGestureHasClicked} from './gestureCounter';
 import {resolveLayerPortalTarget} from './layerHost';
@@ -443,6 +444,14 @@ interface InternalContextLayerOptions extends ContextLayerOptions {
    * its trigger keeps open.
    */
   keepsAnchorClear?: boolean;
+  /**
+   * With `lazyMount`, the layer stays mounted once its first `show()` mounted
+   * it: hiding leaves it in place, so its close plays out and every later
+   * `show()` opens it at once. A layer never shown still mounts only its inert
+   * marker. For a component with many triggers that each own a layer (a
+   * context menu on every table cell).
+   */
+  keepsMountAfterShow?: boolean;
 }
 
 type InternalContextLayerReturn = ContextLayerReturn & InternalLayerFields;
@@ -1151,6 +1160,10 @@ function useLayerImplementation(
 ): InternalContextLayerReturn | InternalFixedLayerReturn {
   const {mode, onShow, onHide, lightDismiss = false} = options;
   const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false;
+  const keepsMountAfterShow =
+    lazyMount && mode === 'context'
+      ? (options.keepsMountAfterShow ?? false)
+      : false;
   const keepsAnchorClear =
     mode === 'context' ? (options.keepsAnchorClear ?? false) : false;
   const id = useId();
@@ -1360,12 +1373,12 @@ function useLayerImplementation(
   );
 
   const clearContextMount = useCallback(() => {
-    if (mode !== 'context' || !lazyMount) {
+    if (mode !== 'context' || !lazyMount || keepsMountAfterShow) {
       return;
     }
     contextMountRef.current = null;
     mountStore.set(null);
-  }, [mode, lazyMount, mountStore]);
+  }, [mode, lazyMount, keepsMountAfterShow, mountStore]);
 
   const show = useCallback(() => {
     // Every caller lands here, so this is where the dismissing press is
@@ -1682,14 +1695,21 @@ function useLayerImplementation(
   const sentinelRefCallback = useCallback(
     (el: HTMLTemplateElement | null) => {
       sentinelRef.current = el;
-      if (el && (!lazyMount || pendingShowRef.current || isOpenRef.current)) {
+      // A layer that keeps its mount re-resolves it too once it has one.
+      if (
+        el &&
+        (!lazyMount ||
+          pendingShowRef.current ||
+          isOpenRef.current ||
+          (keepsMountAfterShow && contextMountRef.current != null))
+      ) {
         // The render call may have moved while the hook stayed mounted.
         // Resolve again from the newly attached marker rather than reusing a
         // portal target from its previous JSX position.
         requestContextMount();
       }
     },
-    [lazyMount, requestContextMount],
+    [lazyMount, keepsMountAfterShow, requestContextMount],
   );
 
   // Re-bind when the handler identity changes while the element stays mounted,
@@ -1890,7 +1910,10 @@ function useLayerImplementation(
             ...extraStyle,
           }}
           onMouseEnter={onMouseEnter}
-          onMouseLeave={onMouseLeave}>
+          onMouseLeave={onMouseLeave}
+          // Presses inside the layer do not reach handlers around where it
+          // is written.
+          {...layerClickBoundary()}>
           <LayerContentBoundary>{children}</LayerContentBoundary>
         </Container>
       );
@@ -1951,7 +1974,10 @@ function useLayerImplementation(
           id={id}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
-          style={{...stylexResult.style, ...positionStyle, ...extraStyle}}>
+          style={{...stylexResult.style, ...positionStyle, ...extraStyle}}
+          // Presses inside the layer do not reach handlers around where it
+          // is written.
+          {...layerClickBoundary()}>
           <LayerContentBoundary>{children}</LayerContentBoundary>
         </div>
       );

package/src/Layer/useTouchTrigger.ts

@@ -5,11 +5,14 @@
 /**
  * @file useTouchTrigger.ts
  * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
- * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type
+ * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
+ *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
+ *   not re-exported from index)
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/hooks/useClickableContainer.ts (innermostInteractive)
  *
  * Hover is the one trigger a touch screen cannot express. A tap synthesizes
  * `mouseenter`, so an untreated hover layer either opens on every tap and
@@ -23,7 +26,10 @@
  * action — an info icon, an abbreviation, a truncated label — has nothing to
  * lose, so the tap opens the layer and the next tap outside dismisses it. That
  * is `auto`; `tap` and `none` state the choice outright, which is what an
- * icon-button whose only job is to reveal the layer needs.
+ * icon-button whose only job is to reveal the layer needs. An `aria-disabled`
+ * control performs no action: a tap that lands in one, or on a label for a
+ * disabled control, opens the layer, so its reason has a touch path. (A
+ * natively `disabled` control receives no click at all.)
  *
  * A touch decides nothing until it is a tap. A finger landing on the trigger
  * may be starting a scroll, a pinch or a long press, and only the browser
@@ -37,12 +43,21 @@
  * which is when UIKit dismisses a popover.
  */
 
-import {useCallback, useEffect, useRef, type RefObject} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+} from 'react';
 import {currentGesture} from './gestureCounter';
 import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+  innermostInteractive,
+  matchesInteractiveSelectors,
+} from '../hooks/useClickableContainer';
+import {isDisabledControl} from '../utils/pressDisabled';
+import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 
 /**
  * How a hover layer behaves on a touch pointer.
@@ -63,6 +78,30 @@ export type LayerTouchTrigger = 'auto' | 'tap' | 'none';
  */
 export const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
 
+export function useTapStop(event: 'click'): {
+  onPointerDown: (event: ReactPointerEvent<Element>) => void;
+  onClick: (event: ReactMouseEvent<Element>) => void;
+};
+export function useTapStop(event: 'mousedown'): {
+  onPointerDown: (event: ReactPointerEvent<Element>) => void;
+  onMouseDown: (event: ReactMouseEvent<Element>) => void;
+};
+export function useTapStop(event: 'click' | 'mousedown') {
+  const pressIsTapRef = useRef(false);
+  const onPointerDown = (pointer: ReactPointerEvent<Element>) => {
+    pressIsTapRef.current = TOUCH_POINTER_TYPES.has(pointer.pointerType);
+  };
+  const cancel = (mouse: ReactMouseEvent<Element>) => {
+    if (pressIsTapRef.current) {
+      mouse.preventDefault();
+    }
+    pressIsTapRef.current = false;
+  };
+  return event === 'click'
+    ? {onPointerDown, onClick: cancel}
+    : {onPointerDown, onMouseDown: cancel};
+}
+
 /**
  * ARIA roles that make an element do something when activated. An explicit
  * role wins over the tag: `<button role="presentation">` is scenery, and a
@@ -99,15 +138,25 @@ const ACTION_ROLES = new Set([
  * with no role) gets both: the layer opens and the handler runs.
  */
 export function isActionTrigger(element: HTMLElement): boolean {
+  // A disabled control performs no action: its tap is free to open the layer
+  // that explains why it is disabled.
+  if (isDisabledControl(element)) {
+    return false;
+  }
   const role = element.getAttribute('role');
   if (role != null && role !== '') {
     return ACTION_ROLES.has(role);
   }
 
   switch (element.tagName) {
+    case 'LABEL': {
+      // A label acts by operating its control, so a label for a disabled one
+      // performs none.
+      const control = (element as HTMLLabelElement).control;
+      return control == null || !isDisabledControl(control);
+    }
     case 'BUTTON':
     case 'INPUT':
-    case 'LABEL':
     case 'SELECT':
     case 'SUMMARY':
     case 'TEXTAREA':
@@ -120,6 +169,41 @@ export function isActionTrigger(element: HTMLElement): boolean {
   }
 }
 
+/**
+ * Whether this element takes a tap itself, as a disabled control does: an
+ * `aria-disabled` (or `:disabled`) control, or a label for one.
+ */
+function isDisabledTarget(element: Element): boolean {
+  if (isDisabledControl(element)) {
+    return true;
+  }
+  if (element.tagName === 'LABEL') {
+    const control = (element as HTMLLabelElement).control;
+    return control != null && isDisabledControl(control);
+  }
+  return false;
+}
+
+/**
+ * Whether a tap landed in a disabled control: walking out from the tapped
+ * element on the clickable containers' own walk (`innermostInteractive`),
+ * with labels counted, the innermost interactive element is an
+ * `aria-disabled` control or a label for a disabled control. That element
+ * takes the tap: the layer opens with its reason, and nothing activates.
+ * Every other tap is left to the trigger (`isActionTrigger`).
+ */
+export function tapLandsOnDisabledControl(tapped: Element): boolean {
+  const innermost = innermostInteractive(
+    tapped,
+    null,
+    element =>
+      matchesInteractiveSelectors(element) ||
+      element.tagName === 'LABEL' ||
+      isDisabledControl(element),
+  );
+  return innermost != null && isDisabledTarget(innermost);
+}
+
 /**
  * Whether typing into this element edits it. Reads the attribute as well as
  * the property: jsdom does not implement `isContentEditable`, and an editor
@@ -252,7 +336,7 @@ export function useTouchTrigger(
   // waiting. The next press, a cancel, the tap itself or unmounting calls it.
   const forgetPendingTapRef = useRef<(() => void) | null>(null);
 
-  useInteractionModalityTracking();
+  const readModality = useInteractionModalityTrackingFor(triggerRef);
 
   const disarmOutsideDismiss = useCallback(() => {
     isTapOpenRef.current = false;
@@ -307,8 +391,8 @@ export function useTouchTrigger(
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(
-    () => isTouchPointerRef.current && getInteractionModality() === 'pointer',
-    [],
+    () => isTouchPointerRef.current && readModality() === 'pointer',
+    [readModality],
   );
 
   const handlePointerEnter = useCallback((event: PointerEvent) => {
@@ -321,14 +405,19 @@ export function useTouchTrigger(
 
   // What a tap on the trigger does. It runs from the tap's `click`, after the
   // render that armed it, so it reads the latest props through this ref.
-  const answerTapRef = useRef<() => void>(() => {});
-  answerTapRef.current = () => {
+  const answerTapRef = useRef<(tapEvent: Event) => void>(() => {});
+  answerTapRef.current = (tapEvent: Event) => {
     const trigger = triggerRef.current;
+    // A tap that landed in a disabled control is that control's: its reason
+    // opens. Every other tap is the trigger's to decide.
+    const tapped = tapEvent.target instanceof Element ? tapEvent.target : null;
     const mode =
       touchTrigger === 'auto'
-        ? trigger != null && isActionTrigger(trigger)
-          ? 'none'
-          : 'tap'
+        ? tapped != null && tapLandsOnDisabledControl(tapped)
+          ? 'tap'
+          : trigger != null && isActionTrigger(trigger)
+            ? 'none'
+            : 'tap'
         : touchTrigger;
 
     if (mode === 'none' || !isEnabled) {
@@ -380,10 +469,10 @@ export function useTouchTrigger(
           forgetPendingTapRef.current = null;
         }
       };
-      const handleTap = () => {
+      const handleTap = (tapEvent: Event) => {
         forget();
         if (currentGesture() === gesture) {
-          answerTapRef.current();
+          answerTapRef.current(tapEvent);
         }
       };
       trigger.addEventListener('click', handleTap);

package/src/Layout/LayoutSlotsContext.ts

@@ -34,7 +34,8 @@ export interface LayoutSlots {
 /**
  * Default slot state - no slots filled.
  */
-const defaultSlots: LayoutSlots = {
+/** The slots outside any Layout: none rendered (a layout root resets to it). */
+export const DEFAULT_LAYOUT_SLOTS: LayoutSlots = {
   hasHeader: false,
   hasFooter: false,
   hasStart: false,
@@ -46,5 +47,6 @@ const defaultSlots: LayoutSlots = {
  * Content area components use this to determine if they are at an edge
  * (for applying outer padding).
  */
-export const LayoutSlotsContext = createContext<LayoutSlots>(defaultSlots);
+export const LayoutSlotsContext =
+  createContext<LayoutSlots>(DEFAULT_LAYOUT_SLOTS);
 LayoutSlotsContext.displayName = 'LayoutSlotsContext';

package/src/Layout/layoutReset.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layoutReset.ts
+ * @input The layout custom properties Layout, its regions, Section and the
+ *   container styles publish to their descendants.
+ * @output `layoutReset`: the StyleX styles that stop every one of them at an
+ *   element, so what renders inside lays out as it does at a page root.
+ * @position Layout owns the reset (`component:Layout` FR8). A layout root
+ *   applies it, as AppShell does at its root (`component:AppShell` FR18).
+ *   Internal: no package entry exports it. `layoutReset.test.tsx` fails when
+ *   Layout writes a custom property this reset does not cover.
+ *
+ * SYNC: the docsite's example root composes `overlayPaddingReset` and
+ * mirrors the rest of this list (apps/docsite/src/components/component-detail/
+ * ExampleBlock.tsx); apps/docsite/src/__tests__/example-layout-root.test.ts
+ * fails when they differ.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {overlayPaddingReset} from './padding.stylex';
+
+const resetBeyondOverlays = stylex.create({
+  root: {
+    // Added by descendants, beyond what an overlay root resets: each reader
+    // falls back to its own default.
+    '--layout-content-width': 'initial',
+    '--layout-alignment-width': 'initial',
+    '--_layout-flush-block-start': 'initial',
+    '--_layout-flush-block-end': 'initial',
+    '--container-max-height': 'initial',
+  },
+});
+
+/**
+ * The full layout reset, for `stylex.props(...)`: `overlayPaddingReset` (the
+ * published container padding to `0px`; Layout insets and Section padding
+ * propagation to `initial`) plus the Layout widths, flush values and height
+ * cap. The shared declarations keep one owner, so a fix to either reaches
+ * every root that applies them.
+ */
+export const layoutReset = [
+  overlayPaddingReset.reset,
+  resetBeyondOverlays.root,
+] as const;

package/src/Lightbox/Lightbox.tsx

@@ -41,14 +41,21 @@ import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
+import {layerClickBoundary} from '../Layer/layerClickBoundary';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
-import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {isRtlElement} from '../hooks/isRtlElement';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/Lightbox/Lightbox.generated';
+
+registerEnglishFallback(english);
 /**
  * Media type for lightbox items.
  */
@@ -329,7 +336,7 @@ export function Lightbox({
   onKeyDown: onKeyDownProp,
   ...props
 }: LightboxProps) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
   const mergedDialogRef = useMergedRefs(ref, dialogRef);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -642,10 +649,6 @@ export function Lightbox({
     <dialog
       ref={mergedDialogRef}
       onCancel={handleCancel}
-      onClick={e => {
-        handleBackdropClick(e);
-        onClickProp?.(e);
-      }}
       onKeyDown={e => {
         handleKeyDown(e);
         onKeyDownProp?.(e);
@@ -663,7 +666,16 @@ export function Lightbox({
         className,
         style,
       )}
-      {...props}>
+      {...props}
+      // Presses inside the lightbox do not reach handlers around where it is
+      // written.
+      {...layerClickBoundary({
+        ...props,
+        onClick: (e: React.MouseEvent<HTMLDialogElement>) => {
+          handleBackdropClick(e);
+          onClickProp?.(e);
+        },
+      })}>
       <LayerDepthProvider>
         <ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen}>
           <LayerContentBoundary>

package/src/Link/Link.tsx

@@ -47,8 +47,14 @@ import {themeDataAttributes, themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
-import {useTranslator} from '../i18n';
 import {disabledInteractionProps} from '../utils/disabledInteraction';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/Link/Link.generated';
+
+registerEnglishFallback(english);
 
 /**
  * Base link styles
@@ -320,7 +326,7 @@ export function Link({
   // document controller once, so the link's output stays a pure function of
   // its props.
   const pressable = usePressFeedback();
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const newTabLabel = newTabLabelFromProps ?? t('@astryx.link.newTab');
   const LinkComponent = useLinkComponent(as);
   const role = useInteractiveRole({href, onClick, isDisabled});

package/src/Markdown/Markdown.tsx

@@ -98,7 +98,14 @@ import {
   headingLinksHeadingStyle,
 } from './plugins/HeadingLinksRenderer';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator, type TranslatorFn} from '../i18n';
+import type {TranslatorFn} from '../i18n';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/Markdown/Markdown.generated';
+
+registerEnglishFallback(english);
 
 type SyncReactNode = Exclude<React.ReactNode, Promise<unknown>>;
 type RenderExtensionNode = MarkdownExtensionNode;
@@ -1592,6 +1599,7 @@ function renderBlock(
       }
       try {
         const rendered = renderer.render({node: proposal.node});
+        // eslint-disable-next-line @astryx/no-nullish-jsx-guard -- a plugin renderer's '' is its output; only null, undefined or a boolean asks for the readable fallback
         if (rendered == null || typeof rendered === 'boolean') {
           return fallback;
         }
@@ -2165,7 +2173,7 @@ export function Markdown<
   'data-testid': testId,
   ...props
 }: MarkdownProps<Plugins>): React.ReactElement {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   // Keep one list while it names the same values, so an inline
   // `codeLanguages={[…]}` does not re-render every block on each parent
   // render (adjusting state during render, not in an Effect).