@astryxdesign/core 0.2.0-canary.ea693ac → 0.2.0-canary.fc53ff7

package/src/hooks/useContainerReveal.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useContainerReveal.ts
+ * @input Uses React, the generated marker pool, useDevWarning
+ * @output Exports useContainerReveal — a headless hover/focus reveal primitive
+ * @position Core hook. Consumed by any component that reveals (or conceals)
+ *   content when its container is hovered or focused — e.g. Thumbnail's remove
+ *   button, TreeList row actions.
+ *
+ * Gives a container a scoped hover/focus-within trigger that reveals or
+ * conceals content inside it, entirely in CSS (no hover state in JS, no
+ * re-render on hover). The caller authors NO StyleX: the hook hands out a
+ * marker + matching reveal styles from a pre-compiled pool.
+ *
+ * ACCESSIBILITY (WCAG 2.2 by construction):
+ * - Revealed content is visually hidden at rest via the clip recipe, so it
+ *   stays in the accessibility tree and tab order — never display:none.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Touch: always visible on coarse pointers; never gated behind hover.
+ * - Concealed (inverted) content is a mouse-only visual swap: it ignores
+ *   :focus-within (a keyboard user must never watch content vanish) and stays
+ *   visible on touch and in the a11y tree.
+ * - Motion: honors prefers-reduced-motion.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ */
+
+import {useState, useEffect, type CSSProperties} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {POOL, POOL_SIZE, type RevealSlot} from './containerReveal.pool.stylex';
+import {useDevWarning} from './useDevWarning';
+
+// Module-level free-list. Each mounted, enabled useContainerReveal claims a
+// distinct pool slot so that any two CONCURRENTLY mounted containers — in
+// particular a nested container inside another's revealed content — get
+// different markers and cannot leak hover/focus into one another. Slots are
+// returned on unmount. Sibling containers that would only ever collide when
+// the pool is exhausted are harmless (a sibling is never an ancestor), so the
+// pool only needs to cover the number of concurrently mounted containers, not
+// instances over time.
+const claimed: boolean[] = new Array(POOL_SIZE).fill(false);
+
+interface Claim {
+  /** Pool index to use. */
+  index: number;
+  /** True when the pool was full and this claim fell back to a shared slot. */
+  isExhausted: boolean;
+}
+
+function claimSlot(): Claim {
+  for (let i = 0; i < POOL_SIZE; i++) {
+    if (!claimed[i]) {
+      claimed[i] = true;
+      return {index: i, isExhausted: false};
+    }
+  }
+  // Exhausted: fall back to slot 0. Safe for siblings (a sibling is never an
+  // ancestor); only nesting deeper than POOL_SIZE could reintroduce a leak.
+  // Surfaced via useDevWarning so the pool can be grown.
+  return {index: 0, isExhausted: true};
+}
+
+function releaseSlot(index: number, isExhausted: boolean): void {
+  // A fallback claim never owned the slot exclusively; leave it as-is.
+  if (!isExhausted) {
+    claimed[index] = false;
+  }
+}
+
+export interface UseContainerRevealOptions {
+  /**
+   * When false the hook is inert: no marker is applied and content getters
+   * return no styles, so content is always shown. Lets a component gate on its
+   * own prop (e.g. `revealOn === 'hover'`).
+   * @default true
+   */
+  isEnabled?: boolean;
+}
+
+export interface ContentRevealOptions {
+  /**
+   * Conceal-on-hover instead of reveal-on-hover: content is visible at rest
+   * and fades out while the container is hovered. Mouse-only and visual —
+   * stays in the a11y tree, ignores focus-within, stays visible on touch.
+   * @default false
+   */
+  isRevealInverted?: boolean;
+  /**
+   * Reserve the content's layout box while hidden (opacity-only) instead of
+   * collapsing it, to avoid layout shift when it appears.
+   * @default false
+   */
+  isLayoutPreserved?: boolean;
+}
+
+export interface UseContainerRevealReturn {
+  /** Spread onto the container whose hover/focus-within drives the reveal. */
+  getContainerProps: () => {className?: string; style?: CSSProperties};
+  /** Spread onto each revealed / concealed child. */
+  getContentRevealProps: (
+    options?: ContentRevealOptions,
+  ) => {className?: string; style?: CSSProperties};
+}
+
+const EMPTY = Object.freeze({});
+
+/**
+ * Scoped, CSS-only hover/focus reveal for content inside a container.
+ *
+ * @example
+ * ```tsx
+ * const {getContainerProps, getContentRevealProps} = useContainerReveal({
+ *   isEnabled: revealOn === 'hover',
+ * });
+ *
+ * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ *   {label}
+ *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
+ *     {actions}
+ *   </span>
+ * </div>
+ * ```
+ */
+export function useContainerReveal(
+  options: UseContainerRevealOptions = {},
+): UseContainerRevealReturn {
+  const {isEnabled = true} = options;
+
+  // Claim a slot for this container's lifetime. Assigned in the initializer
+  // (not the render body) and released on unmount so the free-list stays
+  // effect-scoped and StrictMode-safe.
+  const [claim] = useState<Claim | null>(() =>
+    isEnabled ? claimSlot() : null,
+  );
+
+  useEffect(() => {
+    if (claim == null) {
+      return;
+    }
+    return () => releaseSlot(claim.index, claim.isExhausted);
+  }, [claim]);
+
+  useDevWarning(
+    'useContainerReveal',
+    `More than ${POOL_SIZE} reveal containers are mounted at once; nested ` +
+      `containers beyond the pool may share a marker. Add markers to ` +
+      `containerReveal.pool.stylex.ts and raise POOL_SIZE.`,
+    claim?.isExhausted ?? false,
+  );
+
+  if (claim == null) {
+    return {
+      getContainerProps: () => EMPTY,
+      getContentRevealProps: () => EMPTY,
+    };
+  }
+
+  const slot: RevealSlot = POOL[claim.index];
+
+  return {
+    getContainerProps: () => stylex.props(slot.marker),
+    getContentRevealProps: (contentOptions: ContentRevealOptions = {}) => {
+      const {isRevealInverted = false, isLayoutPreserved = false} =
+        contentOptions;
+      const style = isRevealInverted
+        ? isLayoutPreserved
+          ? slot.concealLayoutPreserved
+          : slot.conceal
+        : isLayoutPreserved
+          ? slot.revealLayoutPreserved
+          : slot.reveal;
+      return stylex.props(style);
+    },
+  };
+}

package/src/hooks/useInputStatusIcon.test.tsx

@@ -160,3 +160,62 @@ describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', ()
     expectNoDanglingDescribedBy(container);
   });
 });
+
+describe('useInputStatusIcon — input-status-icon theme target', () => {
+  // The stable theme target lands on the on-field status glyph itself, so a
+  // theme can restyle (e.g. resize) just this icon via `defineTheme`. It is
+  // rendered by the attached and tooltip variants; detached suppresses the
+  // on-field icon in favour of the detached message box's leading glyph.
+  const getStatusIcon = (root: HTMLElement): HTMLElement => {
+    const icon = root.querySelector('.astryx-input-status-icon');
+    if (icon == null) {
+      throw new Error('status icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  for (const variant of ['attached', 'tooltip'] as const) {
+    it(`renders the target on the on-field icon (statusVariant="${variant}")`, () => {
+      const {container} = render(
+        <TextInput
+          label="Field"
+          value=""
+          onChange={() => {}}
+          status={{type: 'warning', message: 'Message'}}
+          statusVariant={variant}
+        />,
+      );
+      const icon = getStatusIcon(container);
+      expect(icon).toHaveClass('astryx-input-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-size', 'md');
+      expect(icon).toHaveAttribute('data-status', 'warning');
+    });
+  }
+
+  it('reflects the status type per status', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'success', message: 'Message'}}
+        statusVariant="attached"
+      />,
+    );
+    expect(getStatusIcon(container)).toHaveAttribute('data-status', 'success');
+  });
+
+  it('does not render the on-field target for the detached variant', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-input-status-icon')).toBeNull();
+  });
+});

package/src/hooks/useInputStatusIcon.tsx

@@ -41,6 +41,7 @@ import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
+import {themeProps} from '../utils/themeProps';
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -194,7 +195,17 @@ export function useInputStatusIcon({
   }
 
   const icon = (
-    <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+    <Icon
+      icon={STATUS_ICON[status.type]}
+      size={size}
+      color={status.type}
+      // Stable theme target on the status glyph itself, so a theme can restyle
+      // just this icon (color, size) — and each status — via `defineTheme`.
+      // Same-element rules in @layer astryx-theme win over the icon's own base
+      // width/height/fontSize, which a field-level target could not reach.
+      // Shared by the attached and tooltip variants across all bordered inputs.
+      {...themeProps('input-status-icon', {size, status: status.type})}
+    />
   );
 
   // Attached (and tooltip-without-message) variants: plain, non-interactive

package/dist/Thumbnail/thumbnail.markers.stylex.d.ts

@@ -1,9 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export declare const thumbnailScope: ReturnType<typeof stylex.defineMarker>;
-//# sourceMappingURL=thumbnail.markers.stylex.d.ts.map

package/dist/Thumbnail/thumbnail.markers.stylex.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"thumbnail.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/Thumbnail/thumbnail.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC3C,CAAC"}

package/dist/Thumbnail/thumbnail.markers.stylex.js

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export const thumbnailScope = {
-  x9jk0ni: "x9jk0ni",
-  $$css: true
-};

package/src/Thumbnail/thumbnail.markers.stylex.ts

@@ -1,12 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Thumbnail ancestor selectors. Applied to the image
- * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
- * responds only to this thumbnail — not to hover/focus state from an outer
- * container the thumbnail happens to sit inside.
- */
-export const thumbnailScope: ReturnType<typeof stylex.defineMarker> =
-  stylex.defineMarker();