@cdx-ui/components 0.0.1-beta.6 → 0.0.1-beta.61

package/src/components/CLAUDE.md

@@ -0,0 +1,90 @@
+# Components — authoring & styling conventions
+
+Auto-loaded when working in `packages/components/src/components/**`. Covers both the
+styled component files (`index.tsx`) and their co-located CVA variant files (`styles.ts`).
+
+---
+
+## Component Authoring (`index.tsx`)
+
+Styled components in `@cdx-ui/components` follow a consistent pattern. Read the full guides before making changes:
+
+- `docs/internal/practices/composition.md` — compound component pattern, naming conventions
+- `docs/internal/practices/types.md` — prop types, `I*Props` vs `*Props`, exporting
+- `docs/internal/practices/styling.md` — `cn()`, CVA, token classes, `Platform.select()`
+- `docs/internal/practices/state.md` — `useControllableState`, `composeEventHandlers`
+- `docs/internal/practices/data-attributes.md` — `data-[state]` and `data-slot`
+
+### Pattern summary
+
+Each component follows this structure (see `Button/index.tsx` as the canonical example):
+
+1. **Imports** — RN base components, primitive from `@cdx-ui/primitives`, `cn` + style context from `@cdx-ui/utils`, variant functions from `./styles`
+2. **Scope constant** — `const SCOPE = 'COMPONENT_NAME'` for `withStyleContext` / `useStyleContext`
+3. **Root wrapping** — `const Root = withStyleContext(BaseRNComponent, SCOPE)`
+4. **Primitive instantiation** — `const Primitive = createComponent({ Root, Text, ... })` using the primitive factory
+5. **Styled sub-components** — each wraps a single element, uses `forwardRef`, destructures variant props with defaults, computes `cn(variantFn({ ...variants }), className)`, passes `context` to the primitive root
+6. **Compound export** — `Object.assign(RootComponent, { Sub1, Sub2 }) as CompoundType`
+
+### Key rules
+
+- Props interface extends RN base props + primitive `I*Props` + CVA `VariantProps` + `{ className?: string }`
+- Always accept and spread `style` alongside `className`
+- Variant defaults in destructuring must match CVA `defaultVariants`
+- `displayName` set on every exported sub-component
+- `className` is merged last via `cn()` so consumer overrides always win
+- Never hardcode colors — use semantic token classes (`bg-surface-*`, `text-content-*`, `border-stroke-*`)
+- Event handlers composed via `composeEventHandlers` from `@cdx-ui/utils`
+- Third-party libraries fully abstracted — no adopted library types leak to consumers
+
+---
+
+## Styling Conventions (`styles.ts`)
+
+Variant definitions live in co-located `styles.ts` files using CVA. Read the full guides before making changes:
+
+- `docs/internal/practices/styling.md` — `cn()`, CVA, token architecture, dark mode, `Platform.select()`
+- `docs/internal/practices/data-attributes.md` — `data-[state]` selectors for interaction states
+
+### Pattern summary
+
+Each `styles.ts` exports CVA variant functions and their derived `VariantProps` types (see `Button/styles.ts` as the canonical example):
+
+```ts
+import { Platform } from 'react-native';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { DISABLED_CURSOR, TRANSITION_COLORS } from '../../styles/primitives';
+
+export const componentRootVariants = cva(
+  [
+    /* base classes */
+  ],
+  {
+    variants: {
+      /* variant axes */
+    },
+    compoundVariants: [
+      /* variant × variant combinations */
+    ],
+    defaultVariants: {
+      /* defaults matching the component's destructured defaults */
+    },
+  },
+);
+
+export type ComponentVariantProps = VariantProps<typeof componentRootVariants>;
+```
+
+### Key rules
+
+- **Semantic token classes only** — use `bg-surface-action-strong`, `text-content-primary`, `border-stroke-primary`, etc. Never hardcode hex colors, `bg-white`, `text-black`, or raw Tailwind color scales for themed values.
+- **`data-[state]` selectors** — use `data-[disabled=true]:`, `data-[hover=true]:`, `data-[active=true]:`, `data-[focus-visible=true]:` for interaction states. Primitives emit these data attributes.
+- **`Platform.select()`** for platform-specific classes — web gets `data-[hover=true]` styles (hover exists on web); native responds only to `data-[active=true]` (press). Always set `default` (native) and `web` keys.
+- **Shared style primitives** — import `DISABLED_CURSOR`, `TRANSITION_COLORS`, etc. from `../../styles/primitives` for cross-component consistency.
+- **`web:` prefix** for web-only utilities — e.g., `web:outline-none`, `web:focus-visible:ring-2`.
+- **`compoundVariants`** for variant × variant combinations where simple variant merging is insufficient.
+- **`defaultVariants`** must match the destructured defaults in the component's `index.tsx`.
+- **One `cva()` per sub-component** — root, text, icon, spinner, etc. each get their own variant function.
+- **Export `VariantProps` types** — derived via `VariantProps<typeof variantFn>` for the component layer to consume.
+- **No dynamic string construction** — all Tailwind class names must be statically detectable by the Tailwind scanner.
+- **CSS variables for token values** — use `rounded-[var(--border-radius-button)]` syntax when referencing design tokens not mapped to Tailwind utilities.

package/src/components/Card/index.tsx

@@ -1,31 +1,48 @@
 import { forwardRef, type ReactNode } from 'react';
 import { View, type ViewProps } from 'react-native';
-import { cn } from '@cdx-ui/utils';
+import { cn, useStyleContext, withStyleContext } from '@cdx-ui/utils';
 import {
   cardContentVariants,
   cardFooterVariants,
   cardHeaderVariants,
   cardRootVariants,
+  type CardContentVariantProps,
+  type CardFooterVariantProps,
+  type CardVariantProps,
 } from './styles';
 
 // =============================================================================
 // STYLED ROOT COMPONENT
 // =============================================================================
 
-export interface CardProps extends ViewProps {
+const SCOPE = 'CARD';
+
+const Root = withStyleContext(View, SCOPE);
+
+const useCardStyleContext = () => useStyleContext(SCOPE) as CardVariantProps;
+
+export interface CardProps extends ViewProps, CardVariantProps {
   className?: string;
   children?: ReactNode;
 }
 
-const CardRoot = forwardRef<View, CardProps>(({ className, children, style, ...props }, ref) => {
-  const computedClassName = cn(cardRootVariants(), className);
+const CardRoot = forwardRef<View, CardProps>(
+  ({ className, children, style, fullBleed, ...props }, ref) => {
+    const computedClassName = cn(cardRootVariants(), className);
 
-  return (
-    <View ref={ref} className={computedClassName} style={style} {...props}>
-      {children}
-    </View>
-  );
-});
+    return (
+      <Root
+        ref={ref}
+        className={computedClassName}
+        style={style}
+        context={{ fullBleed }}
+        {...props}
+      >
+        {children}
+      </Root>
+    );
+  },
+);
 
 CardRoot.displayName = 'Card';
 
@@ -56,14 +73,18 @@ CardHeader.displayName = 'Card.Header';
 // STYLED CONTENT COMPONENT
 // =============================================================================
 
-export interface CardContentProps extends ViewProps {
+export interface CardContentProps extends ViewProps, CardContentVariantProps {
   className?: string;
   children?: ReactNode;
 }
 
 const CardContent = forwardRef<View, CardContentProps>(
-  ({ className, children, style, ...props }, ref) => {
-    const computedClassName = cn(cardContentVariants(), className);
+  ({ className, children, style, fullBleed, ...props }, ref) => {
+    const { fullBleed: fullBleedFromContext } = useCardStyleContext();
+    const computedClassName = cn(
+      cardContentVariants({ fullBleed: fullBleed ?? fullBleedFromContext }),
+      className,
+    );
 
     return (
       <View ref={ref} className={computedClassName} style={style} {...props}>
@@ -79,14 +100,18 @@ CardContent.displayName = 'Card.Content';
 // STYLED FOOTER COMPONENT
 // =============================================================================
 
-export interface CardFooterProps extends ViewProps {
+export interface CardFooterProps extends ViewProps, CardFooterVariantProps {
   className?: string;
   children?: ReactNode;
 }
 
 const CardFooter = forwardRef<View, CardFooterProps>(
-  ({ className, children, style, ...props }, ref) => {
-    const computedClassName = cn(cardFooterVariants(), className);
+  ({ className, children, style, fullBleed, ...props }, ref) => {
+    const { fullBleed: fullBleedFromContext } = useCardStyleContext();
+    const computedClassName = cn(
+      cardFooterVariants({ fullBleed: fullBleed ?? fullBleedFromContext }),
+      className,
+    );
 
     return (
       <View ref={ref} className={computedClassName} style={style} {...props}>

package/src/components/Card/styles.ts

@@ -1,20 +1,31 @@
-import { cva } from 'class-variance-authority';
+import { cva, VariantProps } from 'class-variance-authority';
 
 // ── Root ────────────────────────────────────────────────────
 
-export const cardRootVariants = cva([
-  'bg-surface-primary',
-  'border border-stroke-secondary',
-  'rounded-[var(--border-radius-default)]',
-  'overflow-hidden',
-]);
+export const cardRootVariants = cva(
+  [
+    'bg-surface-primary',
+    'border border-stroke-secondary',
+    'rounded-[var(--border-radius-default)]',
+    'overflow-hidden',
+  ],
+  {
+    variants: {
+      fullBleed: {
+        true: '',
+        false: '',
+      },
+    },
+  },
+);
 
 // ── Header ──────────────────────────────────────────────────
 
 export const cardHeaderVariants = cva([
-  'flex-row items-center justify-between p-4',
   'border-t-8 border-t-surface-brand-strong',
-  'border-b border-b-solid border-b-stroke-secondary',
+  'border-b border-solid border-b-stroke-secondary',
+  'flex-row items-center justify-between gap-0.5',
+  'px-5 py-3',
 ]);
 
 // ── Title ───────────────────────────────────────────────────
@@ -23,12 +34,28 @@ export const cardTitleVariants = cva(['flex-1']);
 
 // ── Content ─────────────────────────────────────────────────
 
-export const cardContentVariants = cva(['text-content-primary', 'p-4']);
+export const cardContentVariants = cva(['text-content-primary', 'p-5'], {
+  variants: {
+    fullBleed: {
+      true: 'p-0',
+    },
+  },
+});
 
 // ── Footer ──────────────────────────────────────────────────
 
-export const cardFooterVariants = cva([
-  'p-4 border-t',
-  'border-stroke-secondary',
-  'flex-row items-center gap-2',
-]);
+export const cardFooterVariants = cva(['flex-col items-stretch gap-2'], {
+  variants: {
+    fullBleed: {
+      true: 'p-5',
+      false: 'px-5 pb-5 pt-0',
+    },
+  },
+  defaultVariants: {
+    fullBleed: false,
+  },
+});
+
+export type CardVariantProps = VariantProps<typeof cardRootVariants>;
+export type CardContentVariantProps = VariantProps<typeof cardContentVariants>;
+export type CardFooterVariantProps = VariantProps<typeof cardFooterVariants>;

package/src/components/Checkbox/index.tsx

@@ -2,10 +2,9 @@ import { forwardRef, type ReactNode } from 'react';
 import { Pressable, Text, type TextProps, View, type ViewProps } from 'react-native';
 import { Check, CheckIndeterminateSmall } from '@cdx-ui/icons';
 import { createCheckbox, type ICheckboxProps } from '@cdx-ui/primitives';
-import { cn, useStyleContext, withStyleContext } from '@cdx-ui/utils';
+import { cn } from '@cdx-ui/utils';
 import { Icon, IconProps } from '../Icon';
 import {
-  type CheckboxVariantProps,
   checkboxGroupVariants,
   checkboxIconVariants,
   checkboxIndicatorVariants,
@@ -13,14 +12,8 @@ import {
   checkboxRootVariants,
 } from './styles';
 
-const SCOPE = 'CHECKBOX';
-
-const Root = withStyleContext(Pressable, SCOPE);
-
-const useCheckboxStyleContext = () => useStyleContext(SCOPE) as CheckboxVariantProps;
-
 const CheckboxPrimitive = createCheckbox({
-  Root,
+  Root: Pressable,
   Indicator: View,
   Icon: View,
   Label: Text,
@@ -31,14 +24,14 @@ const CheckboxPrimitive = createCheckbox({
 // CHECKBOX ROOT
 // =============================================================================
 
-export interface CheckboxProps extends ICheckboxProps, CheckboxVariantProps {
+export interface CheckboxProps extends ICheckboxProps {
   className?: string;
   children?: ReactNode;
 }
 
 const CheckboxRoot = forwardRef<View, CheckboxProps>(
-  ({ size = 'default', className, isIndeterminate, children, style, ...props }, ref) => {
-    const computedClassName = cn(checkboxRootVariants({ size }), className);
+  ({ className, isIndeterminate, children, style, ...props }, ref) => {
+    const computedClassName = cn(checkboxRootVariants(), className);
 
     return (
       <CheckboxPrimitive
@@ -46,7 +39,6 @@ const CheckboxRoot = forwardRef<View, CheckboxProps>(
         className={computedClassName}
         isIndeterminate={isIndeterminate}
         style={style}
-        context={{ size }}
         {...props}
       >
         <CheckboxIndicator>
@@ -73,8 +65,7 @@ export interface CheckboxIndicatorProps extends ViewProps {
 
 const CheckboxIndicator = forwardRef<View, CheckboxIndicatorProps>(
   ({ className, children, style, ...props }, ref) => {
-    const { size } = useCheckboxStyleContext();
-    const computedClassName = cn(checkboxIndicatorVariants({ size }), className);
+    const computedClassName = cn(checkboxIndicatorVariants(), className);
 
     return (
       <CheckboxPrimitive.Indicator
@@ -98,8 +89,7 @@ CheckboxIndicator.displayName = 'Checkbox.Indicator';
 export interface CheckboxIconProps extends Omit<IconProps, 'children'> {}
 
 const CheckboxIcon = ({ className, style, ...props }: CheckboxIconProps) => {
-  const { size } = useCheckboxStyleContext();
-  const computedClassName = cn(checkboxIconVariants({ size }), className);
+  const computedClassName = cn(checkboxIconVariants(), className);
 
   return <Icon className={computedClassName} style={style} {...props} />;
 };
@@ -117,8 +107,7 @@ export interface CheckboxLabelProps extends TextProps {
 
 const CheckboxLabel = forwardRef<Text, CheckboxLabelProps>(
   ({ className, children, style, ...props }, ref) => {
-    const { size } = useCheckboxStyleContext();
-    const computedClassName = cn(checkboxLabelVariants({ size }), className);
+    const computedClassName = cn(checkboxLabelVariants(), className);
 
     return (
       <CheckboxPrimitive.Label

package/src/components/Checkbox/styles.ts

@@ -1,92 +1,92 @@
 import { Platform } from 'react-native';
-import { cva, type VariantProps } from 'class-variance-authority';
-import {
-  COLOR_BG_PRIMARY,
-  COLOR_BORDER_STRONG,
-  COLOR_TEXT_PRIMARY,
-  DISABLED_CURSOR,
-  DISABLED_OPACITY,
-  TRANSITION_COLORS,
-} from '../../styles/primitives';
+import { cva } from 'class-variance-authority';
+import { DISABLED_CURSOR, DISABLED_OPACITY, TRANSITION_COLORS } from '../../styles/primitives';
 
-export const checkboxRootVariants = cva(
-  ['flex-row items-center', DISABLED_OPACITY, DISABLED_CURSOR],
-  {
-    variants: {
-      size: {
-        small: 'gap-2',
-        default: 'gap-2.5',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+// TODO: Handle text wrapping in the label
 
-export const checkboxIndicatorVariants = cva(
-  [
-    'items-center justify-center',
-    'rounded',
-    'border-2',
-    COLOR_BORDER_STRONG,
-    COLOR_BG_PRIMARY,
-    'data-[checked=true]:bg-slate-900 data-[checked=true]:border-slate-900',
-    'data-[indeterminate=true]:bg-slate-900 data-[indeterminate=true]:border-slate-900',
-    'data-[disabled=true]:opacity-50',
-    'data-[invalid=true]:border-red-500',
-    'data-[checked=true]:data-[invalid=true]:bg-red-500 data-[checked=true]:data-[invalid=true]:border-red-500',
-    'data-[indeterminate=true]:data-[invalid=true]:bg-red-500 data-[indeterminate=true]:data-[invalid=true]:border-red-500',
-    Platform.select({
-      web: [
-        TRANSITION_COLORS,
-        'data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:border-slate-400 data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:bg-slate-50',
-        'data-[focus-visible=true]:ring-2 data-[focus-visible=true]:ring-slate-400/50 data-[focus-visible=true]:ring-offset-2',
-        'data-[invalid=true]:data-[hover=true]:border-red-400',
-        'data-[invalid=true]:data-[focus-visible=true]:ring-red-400/50',
-      ].join(' '),
-      default: '',
-    }),
-  ],
-  {
-    variants: {
-      size: {
-        small: 'h-4 w-4',
-        default: 'h-5 w-5',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+export const checkboxRootVariants = cva([
+  'flex-row items-center gap-2.5',
+  DISABLED_OPACITY,
+  DISABLED_CURSOR,
+  // 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',
+]);
 
-export const checkboxIconVariants = cva(['text-white'], {
-  variants: {
-    size: {
-      small: 'h-3 w-3',
-      default: 'h-3.5 w-3.5',
-    },
-  },
-  defaultVariants: {
-    size: 'default',
-  },
-});
+export const checkboxIndicatorVariants = cva([
+  'items-center justify-center',
+  'h-5 w-5',
+  'rounded',
+  'border-2 border-solid',
+  'data-[disabled=true]:opacity-50',
+  // Background — layered by specificity. checked=false acts as an explicit reset so the base bg
+  // reasserts when transitioning from checked/indeterminate on native (where absent attributes
+  // break data-[attr=false] selectors).
+  // IMPORTANT: On native (Uniwind), only the LAST data-[] condition in a compound chain is
+  // effectively evaluated. Place the most discriminating condition last to avoid false matches.
+  'data-[checked=false]:bg-surface-primary',
+  'data-[checked=true]:bg-surface-action-strong',
+  'data-[indeterminate=true]:bg-surface-action-strong',
+  // Border — invalid (later) beats checked/indeterminate.
+  'data-[checked=false]:border-content-secondary',
+  'data-[checked=true]:border-stroke-action',
+  'data-[indeterminate=true]:border-stroke-action',
+  'data-[invalid=true]:border-stroke-danger',
+  Platform.select({
+    web: [
+      // 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',
+      TRANSITION_COLORS,
+      // Hover — unchecked (Figma: border unchanged, bg overlay at opacity/hover)
+      'data-[hover=true]:data-[checked=false]:data-[indeterminate=false]:bg-content-secondary/[0.08]',
+      // Hover — unchecked + invalid (overlay uses danger token)
+      '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-[indeterminate=true]:bg-surface-action-strong-hover',
+      'data-[hover=true]:data-[indeterminate=true]:border-[--color-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-[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]',
+      // 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).
+      '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-[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-[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-[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:data-[focus-visible=true]:outline-none',
+      'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-[--color-stroke-ring] 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',
+    ].join(' '),
+  }),
+]);
 
-export const checkboxLabelVariants = cva(
-  [COLOR_TEXT_PRIMARY, 'data-[disabled=true]:text-slate-400'],
-  {
-    variants: {
-      size: {
-        small: 'text-sm',
-        default: 'text-base',
-      },
-    },
-    defaultVariants: {
-      size: 'default',
-    },
-  },
-);
+export const checkboxIconVariants = cva(['text-white', 'h-5 w-5']);
+
+export const checkboxLabelVariants = cva([
+  'text-content-primary text-base',
+  'data-[disabled=true]:text-content-tertiary',
+]);
 
 export const checkboxGroupVariants = cva([], {
   variants: {
@@ -99,5 +99,3 @@ export const checkboxGroupVariants = cva([], {
     direction: 'column',
   },
 });
-
-export type CheckboxVariantProps = VariantProps<typeof checkboxRootVariants>;