pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/chip/Chip.js

@@ -0,0 +1,200 @@
+"use strict";
+
+/**
+ * Chip — an interactive token: press to select/toggle, and optionally press a separate trailing "x"
+ * to remove it. Distinct from `Badge` (`../badge`), which is documented, by its own file-level
+ * comment, as non-interactive ("no press, focus, loading, or disabled state" — a `View`, never a
+ * `Pressable`). Badge displays a status/label; Chip is the touchable counterpart for filter chips,
+ * selectable tags, and removable tokens — always `accessibilityRole="button"`, always a 44dp touch
+ * target, never icon-only (`label` is required).
+ */
+
+import { memo, useCallback, useMemo } from "react";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { removeAccessibilityLabel } from "../../core/a11y/labels.js";
+import { AccentGradientFill } from "../../core/gradient/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { Icon } from "../../core/icon/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { MediaImage } from "../../core/media/index.js";
+import { rippleColor as androidRippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
+import { elevation, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { CHIP_AVATAR_SIZE, CHIP_REMOVE_HIT_SLOP, CHIP_REMOVE_ICON_SIZE, chipRemoveSlotStructure, chipRemoveTouchStructure, CHIP_SIZES, chipStructure, resolveChipAccessibility, resolveChipColors } from "./Chip.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+export const Chip = /*#__PURE__*/memo(function Chip(props) {
+  const {
+    label,
+    variant = "subtle",
+    tone = "neutral",
+    customColors,
+    size = "md",
+    selected = false,
+    onPress,
+    onRemove,
+    icon,
+    avatarUri,
+    disabled = false,
+    style,
+    testID
+  } = props;
+  const theme = useTheme();
+  const haptics = useHaptics();
+  const spec = CHIP_SIZES[size];
+  const colors = resolveChipColors(theme.colors, tone, variant, selected, customColors);
+  const press = usePressState(disabled);
+  const removePress = usePressState(disabled);
+  const a11y = resolveChipAccessibility({
+    selected: props.selected,
+    disabled
+  });
+  const handlePress = useCallback(() => {
+    haptics.selection();
+    onPress?.();
+  }, [haptics, onPress]);
+  const overlayColor = useMemo(() => stateLayerScrim(theme.mode), [theme.mode]);
+  const selectedDepth = useMemo(() => {
+    if (!selected) return undefined;
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.sm);
+    void theme.elevatedSurfaces;
+    return floatingSurfaceStyle(theme, "sm");
+  }, [selected, theme]);
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: overlayColor,
+    borderRadius: theme.radii.full,
+    borderCurve: "continuous"
+  }), [overlayColor, theme.radii.full]);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android" || disabled) return undefined;
+    return {
+      color: androidRippleColor(theme.mode),
+      borderless: false
+    };
+  }, [disabled, theme.mode]);
+  const removeRipple = useMemo(() => {
+    if (Platform.OS !== "android" || disabled) return undefined;
+    return {
+      color: androidRippleColor(theme.mode),
+      borderless: true
+    };
+  }, [disabled, theme.mode]);
+  const avatarBox = CHIP_AVATAR_SIZE[size];
+  const avatarStyle = useMemo(() => ({
+    width: avatarBox,
+    height: avatarBox,
+    borderRadius: theme.radii.full,
+    borderCurve: "continuous",
+    overflow: "hidden"
+  }), [avatarBox, theme.radii.full]);
+  const leading = avatarUri !== undefined ? /*#__PURE__*/_jsx(MediaImage, {
+    testID: testID ? `${testID}-avatar` : undefined,
+    source: {
+      uri: avatarUri
+    },
+    contentFit: "cover"
+    // Without this a recycled chip row shows the previous subject's face until the new URI
+    // decodes — the bug `Avatar`'s file header documents.
+    ,
+    recyclingKey: avatarUri,
+    style: avatarStyle
+  }) : icon !== undefined ? /*#__PURE__*/_jsx(Icon, {
+    name: icon,
+    size: spec.iconSize,
+    color: colors.text,
+    strokeWidth: ICON_STROKE
+  }) : null;
+  const removable = onRemove !== undefined;
+  const chip = /*#__PURE__*/_jsxs(AnimatedPressable, {
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: label,
+    "aria-disabled": a11y["aria-disabled"],
+    "aria-pressed": a11y["aria-pressed"],
+    accessibilityState: a11y.accessibilityState,
+    disabled: a11y.disabled,
+    onPress: a11y.disabled ? undefined : onPress === undefined ? undefined : handlePress,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    hitSlop: spec.hitSlop,
+    android_ripple: androidRipple,
+    style: [chipStructure(theme, {
+      size,
+      variant
+    }), {
+      borderColor: colors.border,
+      overflow: "hidden"
+    }, !selected && {
+      backgroundColor: colors.background
+    }, selectedDepth, removable ? chipRemoveSlotStructure(theme, {
+      size
+    }) : null, press.animatedStyle, removable ? null : disabled && styles.dimmed, removable ? null : style],
+    children: [selected && /*#__PURE__*/_jsx(AccentGradientFill, {
+      color: colors.background
+    }), /*#__PURE__*/_jsx(Animated.View, {
+      pointerEvents: "none",
+      testID: testID ? `${testID}-press-overlay` : undefined,
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+    }), leading, /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: [theme.fontStyleForWeight(theme.fontWeights[selected ? "semibold" : "medium"]), {
+        fontSize: spec.fontSize,
+        color: colors.text,
+        flexShrink: 1
+      }],
+      children: label
+    })]
+  });
+  if (!removable) return chip;
+
+  // The remove control is a SIBLING of the chip's press target, never a descendant: a `Pressable`
+  // defaults to `accessible`, which collapses its whole subtree into one element, so a nested "x"
+  // can be touched but never focused or activated by VoiceOver/TalkBack (WCAG 4.1.2 / 2.1.1) —
+  // the same rule `charts` states for its pressable bars. It overlays the slot the chip reserves.
+  return (
+    /*#__PURE__*/
+    // The wrapper repeats the chip's `hitSlop`: a touch outside a view's own hit region is never
+    // dispatched into its children, so without it this node would clip the chip back to 32dp.
+    _jsxs(View, {
+      hitSlop: spec.hitSlop,
+      style: [disabled && styles.dimmed, style],
+      children: [chip, /*#__PURE__*/_jsxs(AnimatedPressable, {
+        testID: testID ? `${testID}-remove` : undefined,
+        accessibilityRole: "button",
+        accessibilityLabel: removeAccessibilityLabel(label),
+        disabled: disabled,
+        onPress: disabled ? undefined : onRemove,
+        onPressIn: removePress.handlers.onPressIn,
+        onPressOut: removePress.handlers.onPressOut,
+        onLayout: removePress.onLayout,
+        hitSlop: CHIP_REMOVE_HIT_SLOP,
+        android_ripple: removeRipple,
+        style: [chipRemoveTouchStructure(theme, {
+          size
+        }), {
+          overflow: "hidden"
+        }, removePress.animatedStyle],
+        children: [/*#__PURE__*/_jsx(Animated.View, {
+          pointerEvents: "none",
+          style: [StyleSheet.absoluteFill, overlayStaticStyle, removePress.overlayStyle]
+        }), /*#__PURE__*/_jsx(Icon, {
+          name: "x",
+          size: CHIP_REMOVE_ICON_SIZE,
+          color: colors.text,
+          strokeWidth: ICON_STROKE
+        })]
+      })]
+    })
+  );
+});
+const styles = StyleSheet.create({
+  dimmed: {
+    opacity: 0.5
+  }
+});
+//# sourceMappingURL=Chip.js.map

package/lib/module/modules/chip/Chip.variants.js

@@ -0,0 +1,290 @@
+"use strict";
+
+/**
+ * Chip's style + behaviour resolution — same split as every sibling module:
+ *  - STRUCTURE (sizing/spacing off the theme scale) lives in the `createThemedVariants` resolvers
+ *    below — static per (brand, mode), registered once.
+ *  - COLOUR is resolved from the theme's ROLE colours (never a raw ramp, never a hardcoded hex) by
+ *    `resolveChipColors` — `tone`/`variant` are closed unions for the same reason Button's `tone` is.
+ *  - ACCESSIBILITY prop derivation is `resolveChipAccessibility`, kept pure so the "selected is only
+ *    announced when the caller controls it" contract is unit-testable without rendering React Native.
+ *
+ * Free of React and of any lucide/Pressable import, so the WCAG + behaviour tests import it directly
+ * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** `accent`/`neutral` are brand-driven emphasis; the rest mirror the theme's status roles — same
+ *  shape `Badge`'s own `BadgeTone` uses. */
+
+/** Same touch-target floor as every interactive control in this library (44dp — Apple HIG minimum,
+ *  WCAG 2.5.5 AAA). */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+/**
+ * Chip-specific dimensions. Visibly smaller than Button (a chip is a token, not a call-to-action)
+ * but every size still reaches the 44dp floor via `hitSlop`, exactly like Button/Select do for
+ * their own short sizes.
+ */
+export const CHIP_SIZES = {
+  sm: {
+    height: 28,
+    fontSize: 12,
+    iconSize: 14,
+    hitSlop: slopFor(28)
+  },
+  md: {
+    height: 32,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(32)
+  }
+};
+
+/** Leading `avatarUri` diameter per chip size — a few dp inside the chip's own height so it never
+ *  clips the pill's vertical padding. */
+export const CHIP_AVATAR_SIZE = {
+  sm: 18,
+  md: 22
+};
+
+/** Horizontal gutter per size. Shared by `chipStructure`, the reserved remove slot, and the remove
+ *  control's own offset, so the "x" lands exactly where the pill's padding says it should. */
+const chipPaddingX = (theme, size) => size === "sm" ? theme.space[2] : theme.space[3];
+
+/** The trailing "x" remove affordance. Fixed — independent of `size`, the same stance Select's row
+ *  "check" glyph and Menu's row icon take (a fixed-purpose glyph is not a caller-facing choice). */
+export const CHIP_REMOVE_ICON_SIZE = 12;
+/** Visual touch box for the remove glyph — small on purpose (it sits inside an already-small chip);
+ *  `CHIP_REMOVE_HIT_SLOP` is what actually carries it to the 44dp floor. */
+export const CHIP_REMOVE_TOUCH_BOX = 18;
+export const CHIP_REMOVE_HIT_SLOP = slopFor(CHIP_REMOVE_TOUCH_BOX);
+/**
+ * Maps a `tone` onto the theme's role colours — the reason the prop is a closed union and not
+ * `color?: string`, same reasoning as Button/Badge. The four status tones read `StatusColors.text`
+ * for the outline border, never `.border` — the exact measured substitution `Badge.variants.ts`
+ * documents (`StatusColors.border` clears neither 3:1 against the canvas nor against its own
+ * `subtle` fill, on any brand × mode).
+ */
+function resolveChipToneColors(colors, tone, customColors) {
+  if (tone === "custom") {
+    if (!customColors) {
+      throw new Error('Chip tone="custom" requires customColors={{ bg, fg }}.');
+    }
+    return {
+      solidFill: customColors.bg,
+      onSolid: customColors.fg,
+      mutedText: customColors.fg,
+      subtleFill: customColors.bg,
+      border: customColors.fg
+    };
+  }
+  switch (tone) {
+    case "accent":
+      return {
+        solidFill: colors.accent.solid,
+        onSolid: colors.accent.onSolid,
+        mutedText: colors.accent.text,
+        subtleFill: colors.accent.subtle,
+        border: colors.border.interactive
+      };
+    case "neutral":
+      return {
+        solidFill: colors.fg.default,
+        onSolid: colors.bg.canvas,
+        mutedText: colors.fg.default,
+        subtleFill: colors.bg.sunken,
+        border: colors.border.interactive
+      };
+    default:
+      {
+        const status = colors.status[tone];
+        return {
+          solidFill: status.solid,
+          onSolid: status.onSolid,
+          mutedText: status.text,
+          subtleFill: status.subtle,
+          border: status.text
+        };
+      }
+  }
+}
+
+/**
+ * Resolves one (tone, variant, selected) combination's fill/text/border. `selected` renders the
+ * filled/accented look regardless of `variant` (spec) by reusing the SAME `solidFill`/`onSolid`
+ * pair `variant="solid"` reads — so "selected outline chip" and "solid chip" render identically
+ * instead of introducing a third, separately-measured filled pairing.
+ */
+export function resolveChipColors(colors, tone, variant, selected, customColors) {
+  const t = resolveChipToneColors(colors, tone, customColors);
+  if (selected || variant === "solid") {
+    return {
+      background: t.solidFill,
+      text: t.onSolid,
+      border: t.solidFill
+    };
+  }
+  if (variant === "outline") {
+    return {
+      background: "transparent",
+      text: t.mutedText,
+      border: t.border
+    };
+  }
+  return {
+    background: t.subtleFill,
+    text: t.mutedText,
+    border: "transparent"
+  };
+}
+
+/** Whether a (variant, selected) combination renders the filled/accented look — the same predicate
+ *  `resolveChipColors` and `Chip.tsx`'s own press-feedback branch both key off. */
+export function isChipFilled(variant, selected) {
+  return selected || variant === "solid";
+}
+
+/**
+ * A resting (non-filled) chip's pressed-state background — `bg.sunken`, the exact precedent
+ * `Menu.variants.ts`'s `resolveMenuRowPressedBackground` sets (a pale neutral tint keeps the label
+ * ≥ 4.5:1, unlike the saturated `bg.hover` mid-tone). Not used for a filled chip (`variant="solid"`
+ * or `selected`): swapping a coloured fill to a flat neutral tint on every press would erase the
+ * tone/selection cue for the moment a finger is down, so a filled chip dims instead
+ * (`Chip.tsx`'s `styles.filledPressed`) — the same "disabled is a uniform dim, exempt from the
+ * contrast minimum" reasoning this library already applies, extended to a transient press.
+ */
+export function resolveChipPressedBackground(colors) {
+  return colors.bg.sunken;
+}
+/**
+ * Derives the chip's accessibility surface once, purely. `selected` is only exposed when the CALLER
+ * actually passed the prop: a plain removable-token chip (never supplies `selected`) has no
+ * selection concept and shouldn't announce "not selected" as if it were part of a toggle group,
+ * while a filter chip that IS controlled (`selected` passed, even `false`) gets the full toggle
+ * semantics (WCAG 4.1.2 — a widget's state is only exposed when the widget actually has that state).
+ */
+export function resolveChipAccessibility(input) {
+  const disabled = input.disabled === true;
+  return {
+    accessibilityRole: "button",
+    "aria-disabled": disabled,
+    "aria-pressed": input.selected,
+    accessibilityState: input.selected === undefined ? undefined : {
+      selected: input.selected
+    },
+    disabled
+  };
+}
+
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (tone/selected
+ * driven, applied inline over this), so this compiles once per theme identity via the themed
+ * resolver. `variant` controls border WIDTH the same way Button's own `variant` does: a hairline for
+ * `outline`, zero for `solid`/`subtle` — `resolveChipColors` supplies the border COLOUR, so
+ * `outline` is the only variant that ever draws a visible ring (`solid`/`subtle`/selected set the
+ * colour to match their own fill, or to `"transparent"`, regardless of this width).
+ */
+export const chipStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[1],
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      sm: {
+        height: CHIP_SIZES.sm.height,
+        paddingHorizontal: chipPaddingX(theme, "sm")
+      },
+      md: {
+        height: CHIP_SIZES.md.height,
+        paddingHorizontal: chipPaddingX(theme, "md")
+      }
+    },
+    variant: {
+      solid: {
+        borderWidth: 0
+      },
+      outline: {
+        borderWidth: theme.borderWidths.thin
+      },
+      subtle: {
+        borderWidth: 0
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md",
+    variant: "subtle"
+  }
+}));
+
+/**
+ * The pill's own trailing gutter, widened to hold the remove control's slot. The control itself is
+ * a SIBLING of the chip's `Pressable` (it would be unreachable to a screen reader nested inside
+ * one — see `Chip.tsx`), so nothing in flow reserves its space; this padding does. The arithmetic
+ * reproduces the old in-flow layout exactly: gutter + touch box + the chip's own `columnGap`.
+ */
+export const chipRemoveSlotStructure = createThemedVariants(theme => ({
+  variants: {
+    size: {
+      sm: {
+        paddingRight: chipPaddingX(theme, "sm") + CHIP_REMOVE_TOUCH_BOX + theme.space[1]
+      },
+      md: {
+        paddingRight: chipPaddingX(theme, "md") + CHIP_REMOVE_TOUCH_BOX + theme.space[1]
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/** Vertically centres the remove control's box in the pill — a static number per size (5 / 7dp),
+ *  since both the pill height and the touch box are fixed. */
+const chipRemoveTop = size => (CHIP_SIZES[size].height - CHIP_REMOVE_TOUCH_BOX) / 2;
+
+/**
+ * The remove glyph's own small touch box — a circle, so its pressed-state fill (see `Chip.tsx`)
+ * reads as a rounded affordance rather than a square patch inside the pill. Absolutely positioned
+ * over the slot `chipRemoveSlotStructure` reserves, which is what lets it be a sibling of the chip's
+ * `Pressable` while still sitting inside the pill: the chip's own background (and its pressed tint)
+ * keeps running underneath it, exactly as when it was a child.
+ */
+export const chipRemoveTouchStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    width: CHIP_REMOVE_TOUCH_BOX,
+    height: CHIP_REMOVE_TOUCH_BOX,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      sm: {
+        right: chipPaddingX(theme, "sm"),
+        top: chipRemoveTop("sm")
+      },
+      md: {
+        right: chipPaddingX(theme, "md"),
+        top: chipRemoveTop("md")
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/** Resolves `ChipGroup`'s `gap` prop onto the theme's spacing scale — a direct value, not its own
+ *  `createThemedVariants` sheet, since `ChipGroup` has no other structural variant to compile
+ *  alongside it (see `ChipGroup.tsx`). */
+export function resolveChipGroupGap(theme, gap) {
+  return gap === "sm" ? theme.space[1] : theme.space[2];
+}
+//# sourceMappingURL=Chip.variants.js.map

package/lib/module/modules/chip/ChipGroup.js

@@ -0,0 +1,48 @@
+"use strict";
+
+/**
+ * ChipGroup — a thin layout wrapper for a row of `Chip`s: wraps onto multiple lines by default, or
+ * scrolls horizontally (`scrollable`) for a filter rail. Owns no chip state of its own — selection/
+ * removal stay on each `Chip`'s own `onPress`/`onRemove`, the same "props in, events out" stance
+ * every layout-only wrapper in this library takes.
+ */
+
+import { memo } from "react";
+import { ScrollView, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveChipGroupGap } from "./Chip.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const ChipGroup = /*#__PURE__*/memo(function ChipGroup({
+  children,
+  wrap = true,
+  gap = "md",
+  scrollable = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const gapValue = resolveChipGroupGap(theme, gap);
+  if (scrollable) {
+    return /*#__PURE__*/_jsx(ScrollView, {
+      testID: testID,
+      horizontal: true,
+      showsHorizontalScrollIndicator: false,
+      bounces: false,
+      contentContainerStyle: [{
+        flexDirection: "row",
+        gap: gapValue
+      }, style],
+      children: children
+    });
+  }
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: [{
+      flexDirection: "row",
+      flexWrap: wrap ? "wrap" : "nowrap",
+      gap: gapValue
+    }, style],
+    children: children
+  });
+});
+//# sourceMappingURL=ChipGroup.js.map