@cdx-ui/components 0.0.1-beta.98 → 0.1.0

package/src/components/Carousel/navButton.tsx

@@ -0,0 +1,160 @@
+import { useCallback } from 'react';
+import type { RefObject } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+import type { ICarouselInstance } from 'react-native-reanimated-carousel';
+import {
+  ChevronLeft,
+  ChevronRight,
+  KeyboardArrowDown,
+  KeyboardArrowUp,
+  type ForgeIcon,
+} from '@cdx-ui/icons';
+import { dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import { cn } from '@cdx-ui/utils';
+import { IconButton, type IconButtonProps } from '../IconButton';
+import { useCarouselProgressContext } from './context';
+import { carouselNavButtonIconVariants, carouselNavButtonRootVariants } from './styles';
+import { useCarouselActiveIndex } from './useCarouselActiveIndex';
+
+export interface CarouselNavButtonProps extends Omit<
+  IconButtonProps,
+  'as' | 'variant' | 'onPress' | 'disabled' | 'isDisabled'
+> {
+  /** Mirrors `Carousel`'s `data.length` — only required when rendered outside `<Carousel>`. */
+  itemCount?: number;
+  /** Explicit progress value — only required when rendered outside `<Carousel>`. */
+  progress?: SharedValue<number>;
+  /** Explicit carousel ref — only required outside `<Carousel>` (unless `onPress` is provided). */
+  carouselRef?: RefObject<ICarouselInstance | null>;
+  /**
+   * Mirrors `Carousel`'s `loop` prop for bounds-aware disabled state.
+   * Defaults to `true` (same as `Carousel`) when omitted outside context.
+   */
+  loop?: boolean;
+  /**
+   * Mirrors `Carousel`'s `vertical` prop for default icons and accessibility labels.
+   * Defaults to `false` when omitted outside context.
+   */
+  vertical?: boolean;
+  /** Overrides the default press-to-navigate behavior (`prev` / `next` with `{ animated: true }`). */
+  onPress?: () => void;
+  /** Manual override; when omitted, derived from `loop` and `progress` at bounds. */
+  disabled?: boolean;
+  /** Forge icon component — defaults to direction-appropriate chevrons or arrows. */
+  as?: ForgeIcon;
+  /** Overrides default `"Previous slide"` / `"Next slide"` (or item labels when `vertical`). */
+  accessibilityLabel?: string;
+}
+
+interface CarouselNavButtonInternalProps extends CarouselNavButtonProps {
+  direction: 'prev' | 'next';
+}
+
+function resolveDefaultIcon(vertical: boolean, direction: 'prev' | 'next'): ForgeIcon {
+  if (vertical) {
+    return direction === 'prev' ? KeyboardArrowUp : KeyboardArrowDown;
+  }
+  return direction === 'prev' ? ChevronLeft : ChevronRight;
+}
+
+function resolveDefaultAccessibilityLabel(vertical: boolean, direction: 'prev' | 'next'): string {
+  if (vertical) {
+    return direction === 'prev' ? 'Previous item' : 'Next item';
+  }
+  return direction === 'prev' ? 'Previous slide' : 'Next slide';
+}
+
+function CarouselNavButton({
+  direction,
+  progress: progressProp,
+  carouselRef: carouselRefProp,
+  itemCount: itemCountProp,
+  loop: loopProp,
+  vertical: verticalProp,
+  onPress,
+  disabled: disabledProp,
+  as,
+  accessibilityLabel,
+  color = 'neutral',
+  size = 'default',
+  className,
+  iconClassName,
+  ...iconButtonProps
+}: CarouselNavButtonInternalProps) {
+  const context = useCarouselProgressContext();
+  const progress = progressProp ?? context?.progress;
+  const carouselRef = carouselRefProp ?? context?.carouselRef;
+  const itemCount = itemCountProp ?? context?.itemCount;
+  const loop = loopProp ?? context?.loop ?? true;
+  const vertical = verticalProp ?? context?.vertical ?? false;
+
+  if (!progress) {
+    throw new Error(
+      `Carousel.${direction === 'prev' ? 'PrevButton' : 'NextButton'} must be rendered inside <Carousel> or receive an explicit \`progress\` prop.`,
+    );
+  }
+
+  if (!onPress && !carouselRef) {
+    throw new Error(
+      `Carousel.${direction === 'prev' ? 'PrevButton' : 'NextButton'} must be rendered inside <Carousel> or receive an explicit \`carouselRef\` prop (or a custom \`onPress\`).`,
+    );
+  }
+
+  if (itemCount == null) {
+    throw new Error(
+      `Carousel.${direction === 'prev' ? 'PrevButton' : 'NextButton'} must be rendered inside <Carousel> or receive an explicit \`itemCount\` prop.`,
+    );
+  }
+
+  const activeIndex = useCarouselActiveIndex(progress);
+  const atStart = activeIndex <= 0;
+  const atEnd = activeIndex >= itemCount - 1;
+  const autoDisabled = !loop && (direction === 'prev' ? atStart : atEnd);
+  const disabled = disabledProp ?? autoDisabled;
+
+  const handlePress = useCallback(() => {
+    if (onPress) {
+      onPress();
+      return;
+    }
+
+    if (direction === 'prev') {
+      carouselRef?.current?.prev({ animated: true });
+    } else {
+      carouselRef?.current?.next({ animated: true });
+    }
+  }, [onPress, carouselRef, direction]);
+
+  const dataSlot = direction === 'prev' ? 'carousel-prev-button' : 'carousel-next-button';
+
+  return (
+    <IconButton
+      as={as ?? resolveDefaultIcon(vertical, direction)}
+      variant="ghost"
+      color={color}
+      size={size}
+      isDisabled={disabled}
+      onPress={handlePress}
+      accessibilityLabel={
+        accessibilityLabel ?? resolveDefaultAccessibilityLabel(vertical, direction)
+      }
+      accessibilityState={{ disabled }}
+      className={cn(carouselNavButtonRootVariants({ disabled }), className)}
+      iconClassName={cn(carouselNavButtonIconVariants({ disabled }), iconClassName)}
+      {...iconButtonProps}
+      {...mergeDataAttributes(iconButtonProps, dataAttributes({ slot: dataSlot }))}
+    />
+  );
+}
+
+export function CarouselPrevButton(props: CarouselNavButtonProps) {
+  return <CarouselNavButton direction="prev" {...props} />;
+}
+
+CarouselPrevButton.displayName = 'Carousel.PrevButton';
+
+export function CarouselNextButton(props: CarouselNavButtonProps) {
+  return <CarouselNavButton direction="next" {...props} />;
+}
+
+CarouselNextButton.displayName = 'Carousel.NextButton';

package/src/components/Carousel/paginationNavigation.ts

@@ -0,0 +1,32 @@
+import type { ICarouselInstance } from 'react-native-reanimated-carousel';
+
+type CarouselPaginationScrollAction = NonNullable<Parameters<ICarouselInstance['scrollTo']>[0]>;
+
+/**
+ * Resolves the shortest `scrollTo` action for pagination dot presses.
+ *
+ * In loop mode the library's absolute `scrollTo({ index })` can animate through every
+ * slide when the current index is past the halfway point of the loop buffer (e.g. index 2 → 3
+ * with four items). Relative `count` navigation avoids that wrap-around path.
+ */
+export function resolveCarouselPaginationScrollAction(
+  currentIndex: number,
+  targetIndex: number,
+  dataLength: number,
+  loop: boolean,
+): CarouselPaginationScrollAction | null {
+  if (currentIndex === targetIndex) return null;
+
+  if (!loop) {
+    return { index: targetIndex, animated: true };
+  }
+
+  const forwardDelta = (targetIndex - currentIndex + dataLength) % dataLength;
+  const backwardDelta = (currentIndex - targetIndex + dataLength) % dataLength;
+
+  if (forwardDelta <= backwardDelta) {
+    return { count: forwardDelta, animated: true };
+  }
+
+  return { count: -backwardDelta, animated: true };
+}

package/src/components/Carousel/styles.ts

@@ -0,0 +1,45 @@
+import { cva, type VariantProps } from '@cdx-ui/utils';
+
+/** Small default gap between dots — the library ships no default spacing between pagination items. */
+export const carouselPaginationContainerClassName = 'gap-2 py-1';
+
+export const carouselPaginationDotVariants = cva('rounded-full', {
+  variants: {
+    active: {
+      true: 'bg-surface-neutral-strong',
+      false: 'bg-surface-neutral-subtle',
+    },
+  },
+  defaultVariants: {
+    active: false,
+  },
+});
+
+export type CarouselPaginationDotVariants = VariantProps<typeof carouselPaginationDotVariants>;
+
+/** Overrides IconButton's default disabled opacity so tertiary icon color reads clearly at bounds. */
+export const carouselNavButtonRootVariants = cva([], {
+  variants: {
+    disabled: {
+      true: 'data-[disabled=true]:opacity-100',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    disabled: false,
+  },
+});
+
+export const carouselNavButtonIconVariants = cva([], {
+  variants: {
+    disabled: {
+      true: 'text-content-tertiary',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    disabled: false,
+  },
+});
+
+export type CarouselNavButtonVariants = VariantProps<typeof carouselNavButtonRootVariants>;

package/src/components/Carousel/useCarouselActiveIndex.ts

@@ -0,0 +1,54 @@
+import { useEffect, useRef, useState } from 'react';
+import { useAnimatedReaction, type SharedValue } from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+
+let nextListenerId = 1;
+
+/**
+ * Syncs `Math.round(progress)` into React state for bounds-aware disabled state.
+ * Do not call `getCurrentIndex()` during render — the adopted library warns against it.
+ *
+ * Uses both:
+ * - `useAnimatedReaction` + `scheduleOnRN` (native / Babel-transformed web worklets)
+ * - SharedValue `addListener` (JS-thread fallback for web hosts that serve bob-built
+ *   `lib/` without the Reanimated Babel plugin — e.g. the docs Vite SPA)
+ */
+export function useCarouselActiveIndex(progress: SharedValue<number>): number {
+  const [activeIndex, setActiveIndex] = useState(() => Math.round(progress.get()));
+  const setActiveIndexRef = useRef(setActiveIndex);
+  setActiveIndexRef.current = setActiveIndex;
+
+  useAnimatedReaction(
+    () => Math.round(progress.get()),
+    (current, previous) => {
+      if (current !== previous) {
+        scheduleOnRN(setActiveIndexRef.current, current);
+      }
+    },
+  );
+
+  useEffect(() => {
+    const listenerId = nextListenerId++;
+    const onChange = (value: number) => {
+      const next = Math.round(value);
+      setActiveIndexRef.current((prev) => (prev === next ? prev : next));
+    };
+
+    try {
+      progress.addListener(listenerId, onChange);
+    } catch {
+      // Native JS runtime rejects addListener — the worklet path above handles it.
+      return;
+    }
+
+    return () => {
+      try {
+        progress.removeListener(listenerId);
+      } catch {
+        // ignore
+      }
+    };
+  }, [progress]);
+
+  return activeIndex;
+}

package/src/components/Checkbox/index.tsx

@@ -57,6 +57,22 @@ CheckboxRoot.displayName = 'Checkbox';
 // CHECKBOX INDICATOR (styled-only, reads context for data-* styling)
 // =============================================================================
 
+/** Compound check × invalid × active state for native Uniwind selectors (single data-field-state). */
+const INDICATOR_STATES = {
+  'unchecked:false:false': 'idle',
+  'unchecked:true:false': 'invalid',
+  'unchecked:false:true': 'active',
+  'unchecked:true:true': 'invalid-active',
+  'checked:false:false': 'checked',
+  'checked:true:false': 'checked-invalid',
+  'checked:false:true': 'checked-active',
+  'checked:true:true': 'checked-invalid-active',
+  'indeterminate:false:false': 'indeterminate',
+  'indeterminate:true:false': 'indeterminate-invalid',
+  'indeterminate:false:true': 'indeterminate-active',
+  'indeterminate:true:true': 'indeterminate-invalid-active',
+} as const;
+
 export interface CheckboxIndicatorProps extends ViewProps {
   asChild?: boolean;
   className?: string;
@@ -77,6 +93,13 @@ const CheckboxIndicator = forwardRef<View, CheckboxIndicatorProps>(
       isFocusVisible,
     } = useCheckboxContext();
 
+    const checkState = isIndeterminate ? 'indeterminate' : isChecked ? 'checked' : 'unchecked';
+    const fieldState = isReadOnly
+      ? (`readonly-${checkState}${isInvalid ? '-invalid' : ''}` as const)
+      : INDICATOR_STATES[
+          `${checkState}:${isInvalid ? 'true' : 'false'}:${isPressed ? 'true' : 'false'}`
+        ];
+
     const computedClassName = cn(checkboxIndicatorVariants(), className);
     const Comp = asChild ? Slot : View;
 
@@ -99,6 +122,7 @@ const CheckboxIndicator = forwardRef<View, CheckboxIndicatorProps>(
             active: isPressed,
             focused: isFocused,
             indeterminate: isIndeterminate,
+            fieldState,
           }),
         )}
       >
@@ -117,6 +141,7 @@ CheckboxIndicator.displayName = 'Checkbox.Indicator';
 export interface CheckboxIconProps extends Omit<IconProps, 'children'> {}
 
 const CheckboxIcon = ({ className, style, ...props }: CheckboxIconProps) => {
+  const { isReadOnly } = useCheckboxContext();
   const computedClassName = cn(checkboxIconVariants(), className);
 
   return (
@@ -124,7 +149,13 @@ const CheckboxIcon = ({ className, style, ...props }: CheckboxIconProps) => {
       className={computedClassName}
       style={style}
       {...props}
-      {...mergeDataAttributes(props, dataAttributes({ slot: 'checkbox-icon' }))}
+      {...mergeDataAttributes(
+        props,
+        dataAttributes({
+          slot: 'checkbox-icon',
+          readonly: isReadOnly,
+        }),
+      )}
     />
   );
 };
@@ -159,7 +190,7 @@ export interface CheckboxLabelProps extends TextProps {
 
 const CheckboxLabel = forwardRef<Text, CheckboxLabelProps>(
   ({ asChild, className, children, style, ...props }, ref) => {
-    const { isDisabled } = useCheckboxContext();
+    const { isDisabled, isReadOnly } = useCheckboxContext();
     const computedClassName = cn(checkboxLabelVariants(), className);
     const Comp = asChild ? Slot : Text;
 
@@ -174,6 +205,7 @@ const CheckboxLabel = forwardRef<Text, CheckboxLabelProps>(
           dataAttributes({
             slot: 'checkbox-label',
             disabled: isDisabled,
+            readonly: isReadOnly,
           }),
         )}
       >
@@ -198,6 +230,8 @@ export interface CheckboxGroupProps extends ViewProps {
   isInvalid?: boolean;
   isReadOnly?: boolean;
   direction?: 'column' | 'row';
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
 }
 
 const CheckboxGroup = forwardRef<View, CheckboxGroupProps>(
@@ -228,6 +262,7 @@ const CheckboxGroup = forwardRef<View, CheckboxGroupProps>(
         isDisabled={isDisabled}
         isInvalid={isInvalid}
         isReadOnly={isReadOnly}
+        {...viewProps}
         {...mergeDataAttributes(viewProps, dataAttributes({ slot: 'checkbox-group' }))}
       >
         {children}

package/src/components/Checkbox/styles.ts

@@ -1,6 +1,6 @@
 import { Platform } from 'react-native';
-import { cva } from 'class-variance-authority';
-import { DISABLED_CURSOR, DISABLED_OPACITY, TRANSITION_COLORS } from '../../styles/primitives';
+import { cva } from '@cdx-ui/utils';
+import { DISABLED_CURSOR, DISABLED_OPACITY, TRANSITION_COLORS } from '../../styles/constants';
 
 // TODO: Handle text wrapping in the label
 
@@ -8,6 +8,7 @@ export const checkboxRootVariants = cva([
   'flex-row items-center gap-2.5',
   DISABLED_OPACITY,
   DISABLED_CURSOR,
+  'data-[readonly=true]:cursor-default',
   // Suppress stray outline on the Pressable/label wrapper; focus ring is drawn on Checkbox.Indicator (Radio pattern).
   'web:outline-none web:focus:outline-none web:focus-visible:outline-none',
 ]);
@@ -33,6 +34,12 @@ export const checkboxIndicatorVariants = cva([
   'data-[invalid=true]:border-stroke-danger',
   Platform.select({
     web: [
+      // Read-only — compound selectors evaluate correctly on web.
+      'data-[readonly=true]:bg-surface-secondary',
+      'data-[readonly=true]:data-[checked=true]:border-stroke-action',
+      'data-[readonly=true]:data-[indeterminate=true]:border-stroke-action',
+      'data-[readonly=true]:data-[checked=true]:bg-surface-secondary',
+      'data-[readonly=true]:data-[indeterminate=true]:bg-surface-secondary',
       // Invalid bg — compound selectors evaluate correctly on web.
       'data-[invalid=true]:data-[checked=true]:bg-surface-danger-strong',
       'data-[invalid=true]:data-[indeterminate=true]:bg-surface-danger-strong',
@@ -43,49 +50,74 @@ export const checkboxIndicatorVariants = cva([
       'data-[hover=true]:data-[invalid=true]:data-[checked=false]:data-[indeterminate=false]:bg-surface-danger-strong/[0.08]',
       // Hover — checked / indeterminate (bg + border darken together)
       'data-[hover=true]:data-[checked=true]:bg-surface-action-strong-hover',
-      'data-[hover=true]:data-[checked=true]:border-[--color-surface-action-strong-hover]',
+      'data-[hover=true]:data-[checked=true]:border-surface-action-strong-hover',
       'data-[hover=true]:data-[indeterminate=true]:bg-surface-action-strong-hover',
-      'data-[hover=true]:data-[indeterminate=true]:border-[--color-surface-action-strong-hover]',
+      'data-[hover=true]:data-[indeterminate=true]:border-surface-action-strong-hover',
       'data-[hover=true]:data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong-hover',
-      'data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-[--color-surface-danger-strong-hover]',
+      'data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-surface-danger-strong-hover',
       'data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:bg-surface-danger-strong-hover',
-      'data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-[--color-surface-danger-strong-hover]',
+      'data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-surface-danger-strong-hover',
       // Active — CSS :active pseudo-class (web root does not track press via data-active).
       // data-[hover=true] guard ensures active beats hover by specificity (0,3,0 > 0,2,0).
+      // Unchecked — border only (Radio pattern)
+      'web:active:data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:border-stroke-hover',
+      'web:active:data-[hover=true]:data-[invalid=true]:data-[checked=false]:data-[indeterminate=false]:border-surface-danger-strong-active',
       'web:active:data-[hover=true]:data-[checked=true]:bg-surface-action-strong-active',
-      'web:active:data-[hover=true]:data-[checked=true]:border-[--color-surface-action-strong-active]',
+      'web:active:data-[hover=true]:data-[checked=true]:border-surface-action-strong-active',
       'web:active:data-[hover=true]:data-[indeterminate=true]:bg-surface-action-strong-active',
-      'web:active:data-[hover=true]:data-[indeterminate=true]:border-[--color-surface-action-strong-active]',
+      'web:active:data-[hover=true]:data-[indeterminate=true]:border-surface-action-strong-active',
       'web:active:data-[hover=true]:data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong-active',
-      'web:active:data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-[--color-surface-danger-strong-active]',
+      'web:active:data-[hover=true]:data-[checked=true]:data-[invalid=true]:border-surface-danger-strong-active',
       'web:active:data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:bg-surface-danger-strong-active',
-      'web:active:data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-[--color-surface-danger-strong-active]',
-      // Focus ring
+      'web:active:data-[hover=true]:data-[indeterminate=true]:data-[invalid=true]:border-surface-danger-strong-active',
+      // Focus ring — applies to read-only as well (focusable + aria-readonly).
       'web:data-[focus-visible=true]:outline-none',
       'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-stroke-focus web:data-[focus-visible=true]:ring-offset-2',
     ].join(' '),
     default: [
-      // Invalid bg is NOT styled on native. Compound data-[] selectors cannot express
-      // "invalid AND checked" without false-matching other states (Uniwind only evaluates
-      // the last condition). Invalid state is communicated via border-stroke-danger (single
-      // condition, always correct). The fill stays action-strong for checked/indeterminate.
-      //
-      // Active — native tracks press via data-[active] from usePress.
-      // Place data-[active=true] last so the rule only fires during press.
-      // 'data-[checked=false]:data-[invalid=true]:bg-transparent',
-      'data-[checked=true]:data-[invalid=true]:bg-surface-danger-strong',
-      'data-[checked=true]:data-[active=true]:bg-surface-action-strong-active',
-      'data-[checked=true]:data-[active=true]:data-[invalid=true]:bg-surface-danger-strong-active',
-      'data-[indeterminate=true]:data-[active=true]:bg-surface-action-strong-active',
+      // Native: Uniwind only evaluates the last data-[] condition in a compound chain.
+      // Use single-condition data-[field-state=...] selectors (emitted by CheckboxIndicator).
+      // Read-only — derived field-state encodes check × readonly (no active/hover on readonly).
+      'data-[field-state=readonly-unchecked]:bg-surface-secondary',
+      'data-[field-state=readonly-checked]:bg-surface-secondary',
+      'data-[field-state=readonly-checked]:border-stroke-action',
+      'data-[field-state=readonly-indeterminate]:bg-surface-secondary',
+      'data-[field-state=readonly-indeterminate]:border-stroke-action',
+      'data-[field-state=readonly-unchecked-invalid]:bg-surface-secondary',
+      'data-[field-state=readonly-checked-invalid]:bg-surface-secondary',
+      'data-[field-state=readonly-checked-invalid]:border-stroke-action',
+      'data-[field-state=readonly-indeterminate-invalid]:bg-surface-secondary',
+      'data-[field-state=readonly-indeterminate-invalid]:border-stroke-action',
+      // checked/indeterminate + invalid → danger bg
+      'data-[field-state=checked-invalid]:bg-surface-danger-strong',
+      'data-[field-state=indeterminate-invalid]:bg-surface-danger-strong',
+      // unchecked + active → border only (Radio pattern)
+      'data-[field-state=active]:border-stroke-hover',
+      'data-[field-state=invalid-active]:border-surface-danger-strong-active',
+      // checked/indeterminate + active → action active bg + matching border
+      'data-[field-state=checked-active]:bg-surface-action-strong-active',
+      'data-[field-state=checked-active]:border-surface-action-strong-active',
+      'data-[field-state=indeterminate-active]:bg-surface-action-strong-active',
+      'data-[field-state=indeterminate-active]:border-surface-action-strong-active',
+      // checked/indeterminate + invalid + active → danger active bg + matching border
+      'data-[field-state=checked-invalid-active]:bg-surface-danger-strong-active',
+      'data-[field-state=checked-invalid-active]:border-surface-danger-strong-active',
+      'data-[field-state=indeterminate-invalid-active]:bg-surface-danger-strong-active',
+      'data-[field-state=indeterminate-invalid-active]:border-surface-danger-strong-active',
     ].join(' '),
   }),
 ]);
 
-export const checkboxIconVariants = cva(['text-white', 'h-5 w-5']);
+export const checkboxIconVariants = cva([
+  'text-white',
+  'data-[readonly=true]:text-content-action',
+  'h-5 w-5',
+]);
 
 export const checkboxLabelVariants = cva([
   'text-content-primary text-base',
   'data-[disabled=true]:text-content-tertiary',
+  'data-[readonly=true]:cursor-default',
 ]);
 
 export const checkboxGroupVariants = cva([], {

package/src/components/Chip/index.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, useMemo, type ReactNode } from 'react';
+import { forwardRef, useEffect, useMemo, type ReactNode } from 'react';
 import { Text, View, type TextProps } from 'react-native';
 import {
   ChipRoot as ChipRootPrimitive,
@@ -27,16 +27,74 @@ const useChipStyleContext = () => useStyleContext(SCOPE) as ChipVariantProps;
 // ROOT
 // =============================================================================
 
-export interface ChipProps extends IChipProps, ChipVariantProps {
+export type ChipVariant = 'subtle' | 'outline';
+
+/** @deprecated Use {@link ChipVariant} (`'subtle'`) instead. */
+export type ChipVariantTint = 'tint';
+
+export type ChipColor = 'neutral' | 'action' | 'danger' | 'warning' | 'success' | 'info';
+
+/** @deprecated Use {@link ChipColor} (`'neutral'`) instead. */
+export type ChipColorDefault = 'default';
+
+let hasWarnedChipTintVariant = false;
+let hasWarnedChipDefaultColor = false;
+
+export interface ChipProps extends IChipProps, Omit<ChipVariantProps, 'variant' | 'color'> {
+  /**
+   * Visual style variant.
+   * @default 'subtle'
+   */
+  variant?:
+    | ChipVariant
+    /** @deprecated Use `'subtle'` instead. */
+    | 'tint';
+  /**
+   * Color theme applied to the chip surface and content.
+   * @default 'neutral'
+   */
+  color?:
+    | ChipColor
+    /** @deprecated Use `'neutral'` instead. */
+    | 'default';
   className?: string;
   children?: ReactNode;
 }
 
 const ChipRoot = forwardRef<View, ChipProps>(
   (
-    { children, variant = 'tint', size = 'default', color = 'default', className, style, ...props },
+    {
+      children,
+      variant: variantProp = 'subtle',
+      size = 'default',
+      color: colorProp = 'neutral',
+      className,
+      style,
+      ...props
+    },
     ref,
   ) => {
+    useEffect(() => {
+      if (__DEV__ && variantProp === 'tint' && !hasWarnedChipTintVariant) {
+        hasWarnedChipTintVariant = true;
+        console.warn(
+          '[Chip] The `tint` variant is deprecated and will be removed in a future major release. Use `subtle` instead.',
+        );
+      }
+    }, [variantProp]);
+
+    useEffect(() => {
+      if (__DEV__ && colorProp === 'default' && !hasWarnedChipDefaultColor) {
+        hasWarnedChipDefaultColor = true;
+        console.warn(
+          '[Chip] The `default` color is deprecated and will be removed in a future major release. Use `neutral` instead.',
+        );
+      }
+    }, [colorProp]);
+
+    const variant = variantProp === 'tint' ? 'subtle' : variantProp;
+    const color = colorProp === 'default' ? 'neutral' : colorProp;
+
     const parent = useParentContext();
     const ctx = useMemo(
       () => ({ ...parent, [SCOPE]: { variant, size, color } }),