pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/composer/Composer.js

@@ -0,0 +1,156 @@
+"use strict";
+
+/**
+ * Composer — chat message input row with multiline field and send affordance.
+ *
+ * The focus ring is its only motion: it crossfades on focus/blur, never while the message list
+ * below it scrolls, so `core/motion`'s per-row rule still holds. Same offset-ring pattern as Input —
+ * a `border.focus` ring a small gap outside the field, on the canvas, where that token is the one
+ * proven ≥ 3:1.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { ActivityIndicator, Animated, Platform, Pressable, StyleSheet, TextInput, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { composerFieldStructure, composerInputStructure, composerSendStructure, composerStructure } from "./Composer.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const ICON_SIZE = 18;
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
+const FIELD_STYLE = composerFieldStructure();
+/** Split out so the icon/spinner subtree survives the parent's per-keystroke `value` re-render. */
+const ComposerSend = /*#__PURE__*/memo(function ComposerSend({
+  canSend,
+  sending,
+  onPress,
+  testID
+}) {
+  const theme = useTheme();
+  const sendStyle = useMemo(() => [composerSendStructure(theme), {
+    backgroundColor: canSend ? theme.colors.accent.solid : theme.colors.bg.sunken
+  }], [theme, canSend]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    testID: testID,
+    accessibilityRole: "button",
+    accessibilityLabel: "Send message",
+    "aria-disabled": !canSend,
+    disabled: !canSend,
+    onPress: onPress,
+    style: sendStyle,
+    children: sending ? /*#__PURE__*/_jsx(ActivityIndicator, {
+      color: theme.colors.accent.onSolid
+    }) : /*#__PURE__*/_jsx(Icon, {
+      name: "send",
+      size: ICON_SIZE,
+      color: canSend ? theme.colors.accent.onSolid : theme.colors.fg.muted,
+      strokeWidth: ICON_STROKE
+    })
+  });
+});
+export const Composer = /*#__PURE__*/memo(function Composer({
+  value,
+  onChangeText,
+  onSend,
+  placeholder = "Message",
+  accessibilityLabel,
+  disabled = false,
+  sending = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const editable = !disabled && !sending;
+  const canSend = editable && value.trim().length > 0;
+  const handleSend = useCallback(() => {
+    if (!canSend) return;
+    onSend();
+  }, [canSend, onSend]);
+  const ringOpacity = useAnimatedValue(0);
+  const ringAnimation = useRef(null);
+  const setRingVisible = useCallback(visible => {
+    ringAnimation.current?.stop();
+    const to = visible ? 1 : 0;
+    if (!motion.enabled) {
+      ringOpacity.setValue(to);
+      return;
+    }
+    ringAnimation.current = motion.timing(ringOpacity, to, {
+      duration: "fast"
+    });
+    ringAnimation.current.start();
+  }, [motion, ringOpacity]);
+  useEffect(() => () => ringAnimation.current?.stop(), []);
+  const handleFocus = useCallback(() => {
+    if (editable) setRingVisible(true);
+  }, [editable, setRingVisible]);
+  const handleBlur = useCallback(() => setRingVisible(false), [setRingVisible]);
+  const rootStyle = useMemo(() => [composerStructure(theme), {
+    borderTopColor: theme.colors.border.default,
+    backgroundColor: theme.colors.bg.surface
+  }, style], [theme, style]);
+  const inputStyle = useMemo(() => [composerInputStructure(theme), theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    // `border.interactive`, NOT `border.default` — the same substitution Card, Switch and
+    // FileUpload each document. This border is the field's ONLY boundary (its fill measures
+    // 1.00–1.09:1 against the row behind it, identical on 8 of 18 palettes), and
+    // `border.default` is a decorative token that reaches only 1.08–1.43:1 on every brand ×
+    // mode, so the field had no ≥3:1 edge anywhere (WCAG 1.4.11).
+    borderColor: theme.colors.border.interactive,
+    backgroundColor: theme.colors.bg.canvas
+  }, Platform.OS === "web" && styles.webOutlineReset], [theme]);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.lg + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  }), [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: FIELD_STYLE,
+      children: [/*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        testID: "composer-focus-ring",
+        style: [focusRingStyle, {
+          opacity: ringOpacity
+        }]
+      }), /*#__PURE__*/_jsx(TextInput, {
+        testID: testID ? `${testID}-input` : undefined,
+        value: value,
+        onChangeText: onChangeText,
+        placeholder: placeholder,
+        placeholderTextColor: theme.colors.fg.muted,
+        editable: editable,
+        accessibilityLabel: accessibilityLabel ?? placeholder,
+        "aria-disabled": !editable,
+        multiline: true,
+        onFocus: handleFocus,
+        onBlur: handleBlur,
+        style: inputStyle
+      })]
+    }), /*#__PURE__*/_jsx(ComposerSend, {
+      canSend: canSend,
+      sending: sending,
+      onPress: handleSend,
+      testID: testID ? `${testID}-send` : undefined
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  // RNW renders the field as a real `<textarea>`, whose UA outline paints over the themed ring.
+  // No `borderWidth: 0` unlike Input — here the visible border is the field's own, not a wrapper's.
+  webOutlineReset: {
+    outlineStyle: "solid",
+    outlineWidth: 0
+  }
+});
+//# sourceMappingURL=Composer.js.map

package/lib/module/modules/composer/Composer.variants.js

@@ -0,0 +1,42 @@
+"use strict";
+
+import { createThemedVariants, createVariants } from "../../core/style/index.js";
+export const composerStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "flex-end",
+    columnGap: theme.space[2],
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderTopWidth: theme.borderWidths.thin
+  }
+}));
+
+/** Carries the row's `flex: 1` so the focus ring can be an absolute sibling of the `TextInput`. */
+export const composerFieldStructure = createVariants({
+  base: {
+    flex: 1,
+    position: "relative"
+  }
+});
+export const composerInputStructure = createThemedVariants(theme => ({
+  base: {
+    minHeight: 40,
+    maxHeight: 120,
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderRadius: theme.radii.lg,
+    borderWidth: theme.borderWidths.thin,
+    fontSize: theme.fontSizes.md
+  }
+}));
+export const composerSendStructure = createThemedVariants(theme => ({
+  base: {
+    width: 40,
+    height: 40,
+    borderRadius: theme.radii.full,
+    alignItems: "center",
+    justifyContent: "center"
+  }
+}));
+//# sourceMappingURL=Composer.variants.js.map

package/lib/module/modules/composer/MODULE.md

@@ -0,0 +1,70 @@
+# composer/ — chat message input row
+
+Multiline `TextInput` plus a send affordance. `sending` swaps the send icon for an
+`ActivityIndicator`; send is disabled while `disabled`, while `sending`, or when `value` is
+whitespace-only.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Composer.tsx` | The component, plus the internal memo'd `ComposerSend` child. |
+| `Composer.variants.ts` | Structural resolvers (root row, field wrapper, input, send circle). No colour resolver — every colour here is a single non-branching role lookup, read at the component. |
+| `index.ts` | Public surface: `Composer`, `ComposerProps`. |
+| `__tests__/Composer.render.test.tsx` | Send fires with text present, stays inert when empty; focus-ring opacity on focus/blur/disabled/sending; web outline reset. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `string` | — | Required, controlled. |
+| `onChangeText` | `(text: string) => void` | — | Required. |
+| `onSend` | `() => void` | — | Required. Never fires while send is disabled. |
+| `placeholder` | `string` | `"Message"` | Falls back into the field's `accessibilityLabel`. |
+| `accessibilityLabel` | `string` | `placeholder` | Names the field. Previously absent — `ComposerProps` exposed no label prop at all, so a consumer with more than one composer on screen (or a placeholder unsuited as a name) could not give it an accessible name. |
+| `disabled` | `boolean` | `false` | Blocks typing and sending. |
+| `sending` | `boolean` | `false` | Blocks typing and sending; shows the spinner. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Roots `${testID}-input`, `${testID}-send`. |
+
+## Accessibility
+
+- **Focus ring (WCAG 2.4.7 / 2.4.11).** Same offset-ring pattern as Input: a `border.focus` ring
+  2px wide, 2px outside the field, crossfaded on the field's `onFocus`/`onBlur` through
+  `useMotion()`. It is always mounted at opacity 0 (`testID="composer-focus-ring"`,
+  `pointerEvents="none"`) and never raised while `disabled` or `sending`. The ring is an absolutely
+  positioned sibling of the `TextInput` inside a `composerFieldStructure` wrapper — that wrapper
+  carries the row's `flex: 1`.
+- **`webOutlineReset`** (web only) sets `outlineStyle: "solid"` + `outlineWidth: 0` on the field, so
+  RNW's `<textarea>` UA outline doesn't paint over the themed ring. It deliberately does **not** zero
+  `borderWidth` (Input's does) — here the visible field border lives on the `TextInput` itself.
+- **No Enter-to-send.** `multiline` with no `onSubmitEditing` is operable as-is; adding it is a
+  product decision, not an accessibility fix.
+- **1.4.11 — CORRECTED, the field border was under 3:1 on every brand × mode.** The field's border
+  read `border.default` (a decorative token, measured 1.08–1.43:1 against the canvas here) and was
+  the field's ONLY boundary — its own fill measures 1.00–1.09:1 against the row behind it on several
+  brands, so there was no boundary anywhere near 3:1. Fixed by switching to `border.interactive`
+  (the same substitution `Card`/`Switch`/`FileUpload` already document), measured directly against
+  the library's own `contrastRatio()` across all 9 brands × 2 modes.
+- Flat `aria-disabled` on the field and the send button, not `accessibilityState={{…}}` —
+  react-native-web drops the object form entirely.
+
+## Motion — the focus ring only
+
+Composer sits directly above a message list, so any animation it owned would run while that list
+scrolls — exactly what `core/motion`'s per-row rule forbids. The focus-ring crossfade is the one
+exception: it fires on focus/blur, never during a scroll. The send affordance changes state
+instantly.
+
+## Performance
+
+Wrapped in `React.memo`. The parent re-renders this component on **every keystroke** (`value` is
+controlled), so:
+
+- The send affordance is split into a memo'd `ComposerSend`. Its props are primitives (`canSend`,
+  `sending`) plus a stable `onPress`, so the `Icon`/`ActivityIndicator` subtree is skipped on the
+  keystrokes that don't flip `canSend`.
+- The root, input and send style arrays are `useMemo`'d, and `handleSend` is `useCallback`'d — a
+  fresh literal per keystroke would defeat the memo above. `aria-disabled={!canSend}` is a primitive,
+  not an object, so it needs no memo of its own.
+- `ComposerSend` reads `useTheme()` itself rather than taking a `theme` prop.

package/lib/module/modules/composer/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { Composer } from "./Composer.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/copy-button/CopyButton.js

@@ -0,0 +1,156 @@
+"use strict";
+
+/**
+ * CopyButton — copies a string to the clipboard with brief success feedback. Three closed
+ * variants: icon-only, outlined button, or menu-row shape.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AccessibilityInfo, Animated, Pressable, Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { usePressMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { COPY_BUTTON_SIZES, copyButtonMenuRowStructure, copyButtonOutlineStructure, COPY_FEEDBACK_MS, resolveCopyButtonColors, writeClipboard } from "./CopyButton.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+// The focus ring sits a small gap OUTSIDE the control, on the canvas, because `border.focus` is the
+// role token proven ≥ 3:1 against the canvas (WCAG 2.4.11) — drawn over a fill it could fail.
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
+export const CopyButton = /*#__PURE__*/memo(function CopyButton({
+  value,
+  variant = "icon",
+  label = "Copy",
+  copiedLabel = "Copied!",
+  failedLabel = "Copy failed",
+  size = "sm",
+  onCopy,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const press = usePressMotion();
+  const colors = resolveCopyButtonColors(theme.colors);
+  const [status, setStatus] = useState("idle");
+  // Keyboard / external-keyboard / assistive-tech focus (no-op on pure touch, correct everywhere else).
+  const [focused, setFocused] = useState(false);
+  const timer = useRef(null);
+  useEffect(() => {
+    return () => {
+      if (timer.current !== null) clearTimeout(timer.current);
+    };
+  }, []);
+  const handlePress = useCallback(async () => {
+    const ok = await writeClipboard(value);
+    setStatus(ok ? "copied" : "failed");
+    // The label swap lands on a control nothing is focused on, so no reader would ever read it —
+    // this imperative call reaches VoiceOver and TalkBack (same reason as `Toast`'s `show()`).
+    AccessibilityInfo.announceForAccessibility(ok ? copiedLabel : failedLabel);
+    if (ok) onCopy?.(value);
+    if (timer.current !== null) clearTimeout(timer.current);
+    timer.current = null;
+    // WCAG 2.2.1: only the SUCCESS state self-clears. A failure is an error the user has to act on,
+    // and reverting the label 1.5s later took the only notice of it off the screen — so the failed
+    // state now stays until the next press (which re-runs this and re-decides).
+    if (ok) timer.current = setTimeout(() => setStatus("idle"), COPY_FEEDBACK_MS);
+  }, [value, onCopy, copiedLabel, failedLabel]);
+  const onFocus = useCallback(() => setFocused(true), []);
+  const onBlur = useCallback(() => setFocused(false), []);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    pointerEvents: "none",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  }), [theme.colors.border.focus, theme.radii.base]);
+  const spec = COPY_BUTTON_SIZES[size];
+  const iconName = status === "copied" ? "check" : status === "failed" ? "triangle-alert" : "link";
+  const ink = status === "copied" ? colors.success : status === "failed" ? colors.danger : colors.default;
+  const currentLabel = status === "copied" ? copiedLabel : status === "failed" ? failedLabel : label;
+  const focusRing = focused ? /*#__PURE__*/_jsx(View, {
+    testID: "copy-button-focus-ring",
+    style: focusRingStyle
+  }) : null;
+  if (variant === "menu-item") {
+    return /*#__PURE__*/_jsxs(Pressable, {
+      testID: testID,
+      accessibilityRole: "button",
+      accessibilityLabel: currentLabel,
+      onPress: handlePress,
+      onFocus: onFocus,
+      onBlur: onBlur,
+      style: ({
+        pressed
+      }) => [copyButtonMenuRowStructure(theme), pressed ? {
+        backgroundColor: theme.colors.bg.sunken
+      } : null, style],
+      children: [focusRing, /*#__PURE__*/_jsx(Icon, {
+        name: iconName,
+        size: spec.iconSize,
+        color: ink,
+        strokeWidth: ICON_STROKE
+      }), /*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+          fontSize: theme.fontSizes.sm,
+          color: ink
+        }],
+        children: currentLabel
+      })]
+    });
+  }
+  if (variant === "button") {
+    return /*#__PURE__*/_jsxs(Pressable, {
+      testID: testID,
+      accessibilityRole: "button",
+      accessibilityLabel: currentLabel,
+      onPress: handlePress,
+      onFocus: onFocus,
+      onBlur: onBlur,
+      style: ({
+        pressed
+      }) => [copyButtonOutlineStructure(theme), {
+        borderColor: status === "copied" ? colors.success : status === "failed" ? colors.danger : colors.border,
+        backgroundColor: pressed ? theme.colors.bg.sunken : theme.colors.bg.surface
+      }, style],
+      children: [focusRing, /*#__PURE__*/_jsx(Icon, {
+        name: iconName,
+        size: spec.iconSize,
+        color: ink,
+        strokeWidth: ICON_STROKE
+      }), /*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+          fontSize: theme.fontSizes.sm,
+          color: ink
+        }],
+        children: currentLabel
+      })]
+    });
+  }
+  return /*#__PURE__*/_jsxs(Pressable, {
+    testID: testID,
+    accessibilityRole: "button",
+    accessibilityLabel: currentLabel,
+    onPress: handlePress,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    onFocus: onFocus,
+    onBlur: onBlur,
+    hitSlop: spec.hitSlop,
+    style: style,
+    children: [focusRing, /*#__PURE__*/_jsx(Animated.View, {
+      testID: "copy-button-glyph",
+      style: press.style,
+      children: /*#__PURE__*/_jsx(Icon, {
+        name: iconName,
+        size: spec.iconSize,
+        color: ink,
+        strokeWidth: ICON_STROKE
+      })
+    })]
+  });
+});
+//# sourceMappingURL=CopyButton.js.map

package/lib/module/modules/copy-button/CopyButton.variants.js

@@ -0,0 +1,86 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const COPY_FEEDBACK_MS = 1500;
+
+/**
+ * Same touch-target floor as `Button`/`Checkbox` (44dp — Apple HIG minimum, WCAG 2.5.5 AAA).
+ * Duplicated rather than imported — modules never import across `src/modules/*`.
+ */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+/**
+ * CopyButton-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
+ * test can assert `iconSize + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.
+ */
+export const COPY_BUTTON_SIZES = {
+  sm: {
+    iconSize: 14,
+    hitSlop: slopFor(14)
+  },
+  md: {
+    iconSize: 16,
+    hitSlop: slopFor(16)
+  }
+};
+export function resolveCopyButtonColors(colors) {
+  return {
+    default: colors.fg.muted,
+    success: colors.status.success.text,
+    danger: colors.status.danger.text,
+    border: colors.border.interactive
+  };
+}
+
+/** The row shapes reach 44dp with `minHeight`, not `hitSlop` — the `MENU_ROW_MIN_HEIGHT` /
+ *  `MULTI_SELECT_ROW_MIN_HEIGHT` precedent: a row is already its own full-width touch target. */
+export const copyButtonMenuRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: MIN_TOUCH_TARGET,
+    columnGap: theme.space[2],
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderRadius: theme.radii.base
+  }
+}));
+export const copyButtonOutlineStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: MIN_TOUCH_TARGET,
+    columnGap: theme.space[1],
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderRadius: theme.radii.base,
+    borderWidth: theme.borderWidths.thin
+  }
+}));
+export async function writeClipboard(value) {
+  try {
+    if (typeof globalThis !== "undefined") {
+      const nav = globalThis.navigator;
+      if (nav?.clipboard?.writeText) {
+        await nav.clipboard.writeText(value);
+        return true;
+      }
+    }
+    try {
+      // Optional peer — consumers on native typically install this package.
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const mod = require("@react-native-clipboard/clipboard");
+      const api = mod.default ?? mod;
+      if (typeof api.setString === "function") {
+        api.setString(value);
+        return true;
+      }
+    } catch {
+      /* optional dependency absent */
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+//# sourceMappingURL=CopyButton.variants.js.map

package/lib/module/modules/copy-button/MODULE.md

@@ -0,0 +1,73 @@
+# copy-button/
+
+Copies `value` to the clipboard. Variants: `icon`, `button`, `menu-item`. Brief copied state with check icon.
+
+## Files
+
+| File | Role |
+|------|------|
+| `CopyButton.tsx` | The component. Variant composition, copy/failure state machine, a11y wiring, focus ring, press motion. |
+| `CopyButton.variants.ts` | Pure resolvers (`COPY_BUTTON_SIZES`, `resolveCopyButtonColors`, `writeClipboard`) + the themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `CopyButton`, `CopyButtonProps`, `CopyButtonSize`, `CopyButtonVariant`. |
+| `__tests__/CopyButton.test.ts` | Pure: WCAG contrast (all brands × modes) + the 44dp touch-target arithmetic. |
+| `__tests__/CopyButton.render.test.tsx` | Render: copy feedback, the failure path (incl. the WCAG 2.2.1 regression — a failed copy stays up past `COPY_FEEDBACK_MS`, a successful one still self-clears), the announcement, rendered `minHeight`/`hitSlop`, focus ring. |
+| `__tests__/CopyButton.motion.test.tsx` | Reduce-motion: the press dip comes from `MOTION_TRANSFORM`, never a local number. |
+
+## Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `value` | `string` | — |
+| `variant` | `icon \| button \| menu-item` | `icon` |
+| `label` | `string` | `Copy` |
+| `copiedLabel` | `string` | `Copied!` |
+| `failedLabel` | `string` | `Copy failed` |
+| `size` | `sm \| md` | `sm` |
+| `onCopy` | `(value) => void` | — |
+
+Native clipboard uses optional `@react-native-clipboard/clipboard`; web uses `navigator.clipboard`.
+A failed write is **not** silent: the control switches to `failedLabel` with the `triangle-alert`
+glyph in `status.danger.text` and announces it. `onCopy` fires only on success.
+
+**WCAG 2.2.1 — only a successful copy self-clears.** `COPY_FEEDBACK_MS` (1500ms) times out the
+`copied` state back to idle; a `failed` state does not arm that timer at all and stays up until the
+next press re-decides it. Previously both states shared the same timer, so "Copy failed" — the
+message a user most needs to actually read — vanished the fastest of anything in this catalogue.
+**Consumer-visible change:** a failed copy no longer reverts to the idle label on its own; the
+control now visibly stays in the failed state (icon + label + `border.danger` on the `button`
+variant) until the user retries.
+
+## Accessibility contract (WCAG)
+
+- `accessibilityRole="button"`; the accessible name is the current label (`label` → `copiedLabel` /
+  `failedLabel` while the feedback state is showing).
+- **2.2.1 (timing adjustable)** — see "Props" above: a failed copy no longer times out.
+- **4.1.3 (status messages)** — the copy result is announced with
+  `AccessibilityInfo.announceForAccessibility`, the cross-platform imperative API (VoiceOver +
+  TalkBack), same call site pattern as `Toast`'s `show()`. The label swap alone announces nothing:
+  it lands on a control that is not focused. No `accessibilityLiveRegion` is set — it is Android-only
+  and would double-announce alongside the imperative call.
+- **2.5.5 / 2.5.8 target size** — the `icon` variant's glyph (14/16dp) reaches ≥ 44dp via the
+  `hitSlop` derived from `COPY_BUTTON_SIZES` (`slopFor`, the `Button`/`Checkbox` idiom). The `button`
+  and `menu-item` row shapes reach it with `minHeight: MIN_TOUCH_TARGET` instead — the row-shaped
+  control precedent (`MENU_ROW_MIN_HEIGHT`, `MULTI_SELECT_ROW_MIN_HEIGHT`): a row is already its own
+  full-width target, so it grows rather than being expanded around.
+- **1.4.3** — the idle glyph/label is `fg.muted`, the copied state `status.success.text` and the
+  failed state `status.danger.text`, all measured ≥ 4.5:1 on the canvas for every brand × mode.
+- **1.4.11** — the `button` variant's outline is `border.interactive` (≥ 3:1 on the canvas).
+- **2.4.7 / 2.4.11** — a visible `border.focus` ring appears on focus and is removed on blur
+  (`onFocus`/`onBlur`) in all three variants, offset outside the control for the same reason
+  `Button`'s ring sits outside its fill: `border.focus`'s ≥ 3:1 proof is against the canvas.
+- **2.3.3** — the `icon` variant's press dip is `usePressMotion` (`MOTION_TRANSFORM.pressOpacity` /
+  `pressScale`, native driver, `opacity`/`transform` only), so reduce-motion snaps it instead of
+  tweening. The `button`/`menu-item` press feedback is a background-colour change, not motion.
+
+## Known gaps
+
+- The `copied` state still reverts on a fixed `COPY_FEEDBACK_MS` timer with no way to extend or turn
+  it off — acceptable under WCAG 2.2.1 because it is a success acknowledgement the user can re-trigger
+  at will (press again), not information they need to finish reading before it disappears.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`).

package/lib/module/modules/copy-button/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { CopyButton } from "./CopyButton.js";
+//# sourceMappingURL=index.js.map