@praxiis/ui 0.0.1

package/src/primitives/content/Card/Card.types.ts

@@ -0,0 +1,95 @@
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { ReactNode } from "react";
+import { AccessibilityState, GestureResponderEvent, PressableProps, StyleProp, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+
+/**
+ * Visual variant for the Card component.
+ *
+ * - `outlined`: Card with border and background
+ * - `flat`: Card with background only, no border
+ */
+export type CardVariant = Exclude<
+  keyof RestyleTheme["cardVariants"],
+  "defaults"
+>;
+
+export type BaseCardProps = VariantProps<RestyleTheme, "cardVariants", "variant"> &
+  BoxProps<RestyleTheme> &
+  PressableProps;
+
+/**
+ * Props for the Card component.
+ *
+ * @example
+ * // Basic usage
+ * <Card>
+ *   <Text>Card content</Text>
+ * </Card>
+ *
+ * @example
+ * // Pressable card
+ * <Card
+ *   variant="outlined"
+ *   onPress={handlePress}
+ *   accessibilityLabel="Product card"
+ * >
+ *   <Text>Tap to view details</Text>
+ * </Card>
+ */
+export interface CardProps extends Omit<BaseCardProps, "variant"> {
+  children?: ReactNode;
+  /** Visual variant of the card (supports responsive values) */
+  variant?: ResponsiveValue<CardVariant, RestyleTheme["breakpoints"]>;
+  /** Whether the card is disabled (only applies when onPress is provided) */
+  disabled?: boolean;
+  /** Container style overrides */
+  style?: StyleProp<ViewStyle>;
+  /** Test ID for testing */
+  testID?: string;
+  /** Accessibility label */
+  accessibilityLabel?: string;
+  /** Accessibility hint */
+  accessibilityHint?: string;
+}
+
+/**
+ * Parameters for generating card accessibility props.
+ */
+export interface CardA11yParams {
+  /** Label for screen readers (required for pressable cards) */
+  accessibilityLabel?: string;
+  /** Whether the card is disabled */
+  disabled: boolean;
+  /** Press handler (presence determines if card is pressable) */
+  onPress?: ((event: GestureResponderEvent) => void) | null;
+}
+
+/**
+ * Accessibility props returned by getCardA11y.
+ */
+export interface CardA11yProps {
+  accessibilityRole?: "button" | "none";
+  accessibilityLabel?: string;
+  accessibilityState?: AccessibilityState;
+}
+
+/**
+ * Parameters for the useCardLogic hook.
+ */
+export interface UseCardLogicParams {
+  disabled?: boolean;
+  onPress?: ((event: GestureResponderEvent) => void) | null;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from the useCardLogic hook.
+ */
+export interface UseCardLogicReturn {
+  isDisabled: boolean;
+  isPressable: boolean;
+  opacity: number;
+  handlePress: (event: GestureResponderEvent) => void;
+  a11yProps: CardA11yProps;
+}

package/src/primitives/content/Card/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Card Module
+ *
+ * Molecule component for content grouping with optional press behavior.
+ *
+ * ## Variants
+ * - `outlined`: Border with background (default)
+ * - `flat`: Background only, no border
+ *
+ * @example
+ * import { Card } from "@/design-system/primitives/content/Card";
+ *
+ * <Card padding="lg" onPress={handlePress} accessibilityLabel="View details">
+ *   <Text>Card content</Text>
+ * </Card>
+ */
+
+export { Card } from "./Card";
+export type { CardProps, CardVariant } from "./Card.types";
+export * from "./Card.a11y";

package/src/primitives/content/Card/useCardLogic.ts

@@ -0,0 +1,48 @@
+import { useCallback, useMemo } from "react";
+import { GestureResponderEvent } from "react-native";
+import { getCardA11y } from "./Card.a11y";
+import { UseCardLogicParams, UseCardLogicReturn } from "./Card.types";
+
+/**
+ * Orchestrates Card rendering logic and state management.
+ * 
+ * Handles:
+ * - Pressable state determination
+ * - Disabled state management
+ * - Opacity calculation for disabled state
+ * - Press handler with disabled check
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for card behavior
+ * @returns Computed values for rendering Card
+ */
+export function useCardLogic({
+  disabled = false,
+  onPress,
+  accessibilityLabel,
+}: UseCardLogicParams): UseCardLogicReturn {
+  const isPressable = !!onPress;
+  const isDisabled = isPressable && disabled;
+  const opacity = isDisabled ? 0.5 : 1;
+
+  const handlePress = useCallback(
+    (event: GestureResponderEvent) => {
+      if (isDisabled || !onPress) return;
+      onPress(event);
+    },
+    [isDisabled, onPress],
+  );
+
+  const a11yProps = useMemo(
+    () => getCardA11y({ accessibilityLabel, disabled: isDisabled, onPress }),
+    [accessibilityLabel, isDisabled, onPress],
+  );
+
+  return {
+    isDisabled,
+    isPressable,
+    opacity,
+    handlePress,
+    a11yProps,
+  };
+}

package/src/primitives/content/Chip/Chip.helpers.ts

@@ -0,0 +1,304 @@
+/**
+ * Chip Component Helpers
+ *
+ * Pure functions for computing Chip styles, sizes, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ *
+ * ## Size Scale
+ * | Size | Height | Icon  | Text Variant | Padding |
+ * |------|--------|-------|--------------|---------|
+ * | sm   | 24px   | xs    | captionSmall | xs (4px)|
+ * | md   | 32px   | sm    | labelSmall   | sm (8px)|
+ * | lg   | 40px   | md    | labelMedium  | md (12px)|
+ *
+ * ## Color Support
+ * Accepts any theme color token. Preset configurations exist for semantic colors:
+ * - accentPrimary, accentSecondary
+ * - feedbackSuccess, feedbackWarning, feedbackError, feedbackInfo
+ *
+ * Any other theme color will use sensible defaults for filled/outlined variants.
+ */
+
+import { RestyleColor } from "../../../types";
+import { IconSize } from "../Icon";
+import {
+  ChipColorTokens,
+  ChipSize,
+  ChipStyleResult,
+  ChipTextVariant,
+  ChipVariant,
+  ResolveChipStyleParams,
+} from "./Chip.types";
+
+// =============================================================================
+// THEME VARIANT KEY MAPPING
+// =============================================================================
+
+/**
+ * Theme variant key mapping.
+ * Maps component variant names to theme variant keys.
+ */
+type ThemeVariantKey = "filled" | "outlined";
+
+const VARIANT_TO_THEME_KEY: Record<ChipVariant, ThemeVariantKey> = {
+  filled: "filled",
+  outlined: "outlined",
+} as const;
+
+/**
+ * Get theme variant key from component variant.
+ *
+ * @param variant - The component variant
+ * @returns The theme variant key
+ */
+export function getThemeVariantKey(variant: ChipVariant): ThemeVariantKey {
+  return VARIANT_TO_THEME_KEY[variant];
+}
+
+// =============================================================================
+// SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Chip icon size mapping.
+ *
+ * | Chip Size | Icon Size |
+ * |-----------|-----------|
+ * | sm        | xs (12px) |
+ * | md        | sm (16px) |
+ * | lg        | md (20px) |
+ */
+export const CHIP_ICON_SIZE: Record<ChipSize, IconSize> = {
+  sm: "xs",
+  md: "sm",
+  lg: "md",
+} as const;
+
+/**
+ * Chip text variant mapping.
+ *
+ * | Chip Size | Text Variant |
+ * |-----------|--------------|
+ * | sm        | captionSmall |
+ * | md        | labelSmall   |
+ * | lg        | labelMedium  |
+ */
+export const CHIP_TEXT_VARIANT: Record<ChipSize, ChipTextVariant> = {
+  sm: "captionSmall",
+  md: "labelSmall",
+  lg: "labelMedium",
+} as const;
+
+/**
+ * Get icon size based on chip size.
+ *
+ * @param size - The chip size
+ * @returns The icon size key
+ */
+export function getChipIconSize(size: ChipSize): IconSize {
+  return CHIP_ICON_SIZE[size];
+}
+
+/**
+ * Get text variant based on chip size.
+ *
+ * @param size - The chip size
+ * @returns The text variant for Text
+ */
+export function getChipTextVariant(size: ChipSize): ChipTextVariant {
+  return CHIP_TEXT_VARIANT[size];
+}
+
+// =============================================================================
+// COLOR RESOLUTION
+// =============================================================================
+
+/**
+ * Preset color configurations for common semantic colors.
+ * These provide optimized backgrounds and text colors.
+ */
+const PRESET_COLORS: Record<string, ChipColorTokens> = {
+  accentPrimary: {
+    filled: "accentPrimary",
+    accent: "accentPrimary",
+    filledText: "textInverse",
+    accentText: "accentPrimary",
+  },
+  accentSecondary: {
+    filled: "accentSecondary",
+    accent: "accentSecondary",
+    filledText: "textInverse",
+    accentText: "accentSecondary",
+  },
+  feedbackSuccess: {
+    filled: "feedbackSuccess",
+    accent: "feedbackSuccess",
+    filledText: "textInverse",
+    accentText: "feedbackSuccessDark",
+  },
+  feedbackWarning: {
+    filled: "feedbackWarning",
+    accent: "feedbackWarning",
+    filledText: "textPrimary",
+    accentText: "feedbackWarningDark",
+  },
+  feedbackError: {
+    filled: "feedbackError",
+    accent: "feedbackError",
+    filledText: "textInverse",
+    accentText: "feedbackErrorDark",
+  },
+  feedbackInfo: {
+    filled: "feedbackInfo",
+    accent: "feedbackInfo",
+    filledText: "textInverse",
+    accentText: "feedbackInfoDark",
+  },
+} as const;
+
+/**
+ * Get color tokens for a chip color.
+ * Uses preset configurations for semantic colors, or generates tokens for any theme color.
+ *
+ * @param color - Any theme color token
+ * @returns Color tokens for the chip
+ */
+export function getChipColorTokens(color: RestyleColor): ChipColorTokens {
+  // Check if we have a preset for this color
+  if (color in PRESET_COLORS) {
+    return PRESET_COLORS[color];
+  }
+
+  // For any other color, use it directly with sensible defaults
+  return {
+    filled: color,
+    accent: color,
+    filledText: "textInverse",
+    accentText: color,
+  };
+}
+
+/**
+ * Get text color based on variant, color, and state.
+ *
+ * | Variant  | Normal       | Selected     | Disabled     |
+ * |----------|--------------|--------------|--------------|
+ * | filled   | textInverse  | textInverse  | textDisabled |
+ * | outlined | accent color | textInverse  | textDisabled |
+ *
+ * @param variant - Visual variant
+ * @param color - Any theme color token
+ * @param selected - Whether chip is selected
+ * @param disabled - Whether chip is disabled
+ * @returns Computed text color token
+ */
+export function getChipTextColor(
+  variant: ChipVariant,
+  color: RestyleColor,
+  selected: boolean,
+  disabled: boolean
+): RestyleColor {
+  if (disabled) {
+    return "textDisabled";
+  }
+
+  const tokens = getChipColorTokens(color);
+
+  // When selected (for outlined), use filled text color
+  if (selected && variant !== "filled") {
+    return tokens.filledText;
+  }
+
+  if (variant === "filled") {
+    return tokens.filledText;
+  }
+
+  return tokens.accentText;
+}
+
+/**
+ * Get icon color based on variant, color, and state.
+ * Follows the same logic as text color for visual consistency.
+ *
+ * @param variant - Visual variant
+ * @param color - Any theme color token
+ * @param selected - Whether chip is selected
+ * @param disabled - Whether chip is disabled
+ * @returns Computed icon color token
+ */
+export function getChipIconColor(
+  variant: ChipVariant,
+  color: RestyleColor,
+  selected: boolean,
+  disabled: boolean
+): RestyleColor {
+  return getChipTextColor(variant, color, selected, disabled);
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the Chip container.
+ *
+ * Static styles (borderRadius, padding) come from theme variants.
+ * This function handles dynamic state-based values:
+ * - backgroundColor based on variant, color, and selected state
+ * - borderColor based on variant and color
+ * - opacity based on disabled state
+ *
+ * Returns token keys instead of resolved hex values to let Restyle handle resolution.
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object with token keys
+ */
+export function resolveChipStyle(
+  params: Omit<ResolveChipStyleParams, "theme">
+): ChipStyleResult {
+  const { variant, color, selected, disabled } = params;
+
+  const tokens = getChipColorTokens(color);
+
+  let backgroundColor: RestyleColor | "transparent";
+  let borderColor: RestyleColor | "transparent";
+  let borderWidth: number;
+
+  if (disabled) {
+    switch (variant) {
+      case "filled":
+        backgroundColor = "interactiveDisabled";
+        borderColor = "transparent";
+        borderWidth = 0;
+        break;
+      case "outlined":
+        backgroundColor = selected ? "interactiveDisabled" : "transparent";
+        borderColor = "borderDefault";
+        borderWidth = 1;
+        break;
+      default:
+        backgroundColor = "interactiveDisabled";
+        borderColor = "transparent";
+        borderWidth = 0;
+    }
+  } else {
+    switch (variant) {
+      case "filled":
+        backgroundColor = tokens.filled;
+        borderColor = "transparent";
+        borderWidth = 0;
+        break;
+      case "outlined":
+        backgroundColor = selected ? tokens.filled : "transparent";
+        borderColor = tokens.accent;
+        borderWidth = 1;
+        break;
+      default:
+        backgroundColor = tokens.filled;
+        borderColor = "transparent";
+        borderWidth = 0;
+    }
+  }
+
+  return { backgroundColor, borderColor, borderWidth, opacity: 1 };
+}

package/src/primitives/content/Chip/Chip.tsx

@@ -0,0 +1,205 @@
+/**
+ * Chip Component
+ *
+ * @description Compact element for tags, filters, and selections - Atom
+ *
+ * Chip displays compact elements used for tags, categories, filters,
+ * and selection groups. Supports interactive (selectable/dismissible)
+ * and static display modes.
+ *
+ * ## Size Scale
+ * | Size | Height | Icon  | Text Variant | Padding |
+ * |------|--------|-------|--------------|---------|
+ * | sm   | 24px   | xs    | captionSmall | xs (4px)|
+ * | md   | 32px   | sm    | labelSmall   | sm (8px)|
+ * | lg   | 40px   | md    | labelMedium  | md (12px)|
+ *
+ * ## Variants
+ * - `filled`: Solid background (default)
+ * - `outlined`: Border only, transparent background
+ *
+ * ## Features
+ * - Responsive size prop (phone/tablet breakpoints)
+ * - Optional leading icon
+ * - Selectable with visual feedback
+ * - Dismissible with close button
+ * - Five color options (primary, secondary, success, warning, error)
+ * - Full accessibility support
+ * - Memoized for performance
+ *
+ * @see Chip.types.ts - Type definitions
+ * @see Chip.helpers.ts - Pure calculation functions
+ * @see Chip.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic tag
+ * <Chip label="JavaScript" />
+ *
+ * @example
+ * // Selectable chip
+ * <Chip
+ *   label="Option A"
+ *   onPress={() => setSelected(!selected)}
+ *   selected={selected}
+ *   variant="outlined"
+ * />
+ *
+ * @example
+ * // Dismissible filter chip
+ * <Chip
+ *   label="Category: Tech"
+ *   iconName="filter-list"
+ *   onDelete={() => removeFilter()}
+ *   color="primary"
+ * />
+ *
+ * @example
+ * // Status chip
+ * <Chip
+ *   label="Active"
+ *   variant="outlined"
+ *   color="success"
+ *   size="sm"
+ * />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo, useCallback } from "react";
+import { Pressable } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import { IconButton } from "../../actions/IconButton";
+import { Text } from "../../typography";
+import { Icon } from "../Icon";
+import { BaseChipProps, ChipProps } from "./Chip.types";
+import { useChipLogic } from "./useChipLogic";
+
+/** Narrow extended color tokens for Restyle interop (safe at runtime). */
+const asBase = (c: RestyleColor | "transparent") => c as BaseThemeColor;
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseChipContainer = createRestyleComponent<BaseChipProps, RestyleTheme>(
+  [
+    createVariant({ themeKey: "chipVariants" }),
+    createVariant({ themeKey: "chipSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+function ChipComponent({
+  label,
+  onPress,
+  onDelete,
+  variant = "filled",
+  size = "md",
+  color = "accentPrimary",
+  selected = false,
+  disabled = false,
+  iconName,
+  testID,
+  accessibilityHint,
+  accessibilityLabel,
+  style,
+  ...rest
+}: ChipProps) {
+  const {
+    themeVariantKey,
+    textVariant,
+    textColor,
+    iconSize,
+    iconColor,
+    containerStyle,
+    a11yProps,
+    isInteractive,
+    showDeleteIcon,
+    deleteIconColor,
+    deleteHint,
+  } = useChipLogic({
+    label,
+    variant,
+    size,
+    color,
+    selected,
+    disabled,
+    onPress,
+    onDelete,
+    accessibilityLabel,
+    accessibilityHint,
+  });
+
+  const handlePress = useCallback(() => {
+    if (!disabled && onPress) {
+      onPress();
+    }
+  }, [disabled, onPress]);
+
+  const handleDelete = useCallback(() => {
+    if (!disabled && onDelete) {
+      onDelete();
+    }
+  }, [disabled, onDelete]);
+
+  return (
+    <BaseChipContainer
+      variant={themeVariantKey}
+      size={size}
+      onPress={isInteractive ? handlePress : undefined}
+      disabled={disabled}
+      testID={testID}
+      flexDirection="row"
+      alignItems="center"
+      justifyContent="center"
+      gap="xs"
+      backgroundColor={asBase(containerStyle.backgroundColor)}
+      borderColor={asBase(containerStyle.borderColor)}
+      borderWidth={containerStyle.borderWidth}
+      opacity={containerStyle.opacity}
+      style={style}
+      {...a11yProps}
+      {...rest}
+    >
+      {iconName && (
+        <Icon
+          name={iconName}
+          size={iconSize}
+          color={asBase(iconColor)}
+          accessibilityLabel={iconName}
+        />
+      )}
+      <Text variant={textVariant} color={asBase(textColor)}>
+        {label}
+      </Text>
+      {showDeleteIcon && (
+        <IconButton
+          iconName="close"
+          onPress={handleDelete}
+          variant="ghost"
+          size="sm"
+          disabled={disabled}
+          color={asBase(deleteIconColor)}
+          accessibilityLabel={`Remove ${label}`}
+          accessibilityHint={deleteHint}
+        />
+      )}
+    </BaseChipContainer>
+  );
+}
+
+export const Chip = memo(ChipComponent);
+Chip.displayName = "Chip";