@cdx-ui/components 0.0.1-beta.15 → 0.0.1-beta.150

package/src/components/Button/styles.ts

@@ -1,6 +1,6 @@
 import { Platform } from 'react-native';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { DISABLED_CURSOR, TRANSITION_COLORS } from '../../styles/primitives';
+import { cva, type VariantProps } from '@cdx-ui/utils';
+import { DISABLED_CURSOR, TRANSITION_COLORS } from '../../styles/constants';
 
 // TODO: Validate that `dark:` syntax works with Uniwind `ScopedTheme`
 
@@ -12,12 +12,12 @@ export const buttonRootVariants = cva(
     TRANSITION_COLORS,
     'data-[disabled=true]:opacity-[var(--opacity-disabled)]',
     DISABLED_CURSOR,
-    'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-[--color-stroke-focus] web:data-[focus-visible=true]:ring-offset-2',
+    'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-stroke-focus web:data-[focus-visible=true]:ring-offset-2',
   ],
   {
     variants: {
       variant: {
-        strong: ['border-b-1 border-black/75'], // TODO: Replace with token
+        solid: ['border-b-1 border-black/75'], // TODO: Replace with token
         outline: ['bg-transparent', 'border border-stroke-primary'],
         ghost: ['bg-transparent'],
       },
@@ -29,7 +29,7 @@ export const buttonRootVariants = cva(
         info: [],
       },
       size: {
-        default: 'h-10 px-4 gap-2',
+        default: 'h-11 px-4 gap-2',
         small: 'h-8 px-3 gap-1.5',
       },
       fullWidth: {
@@ -38,9 +38,9 @@ export const buttonRootVariants = cva(
       },
     },
     compoundVariants: [
-      // ── strong × color (filled surface) ──────────────────────────────
+      // ── solid × color (filled surface) ──────────────────────────────
       {
-        variant: 'strong',
+        variant: 'solid',
         color: 'action',
         className: [
           'bg-surface-action-strong',
@@ -51,7 +51,7 @@ export const buttonRootVariants = cva(
         ],
       },
       {
-        variant: 'strong',
+        variant: 'solid',
         color: 'danger',
         className: [
           'bg-surface-danger-strong',
@@ -62,7 +62,7 @@ export const buttonRootVariants = cva(
         ],
       },
       {
-        variant: 'strong',
+        variant: 'solid',
         color: 'warning',
         className: [
           'bg-surface-warning-strong',
@@ -73,7 +73,7 @@ export const buttonRootVariants = cva(
         ],
       },
       {
-        variant: 'strong',
+        variant: 'solid',
         color: 'success',
         className: [
           'bg-surface-success-strong',
@@ -84,7 +84,7 @@ export const buttonRootVariants = cva(
         ],
       },
       {
-        variant: 'strong',
+        variant: 'solid',
         color: 'info',
         className: [
           'bg-surface-info-strong',
@@ -205,7 +205,7 @@ export const buttonRootVariants = cva(
       },
     ],
     defaultVariants: {
-      variant: 'strong',
+      variant: 'solid',
       color: 'action',
       size: 'default',
       fullWidth: false,
@@ -216,7 +216,7 @@ export const buttonRootVariants = cva(
 export const buttonTextVariants = cva(['font-medium', 'text-center'], {
   variants: {
     variant: {
-      strong: [],
+      solid: [],
       outline: [],
       ghost: [],
     },
@@ -233,12 +233,12 @@ export const buttonTextVariants = cva(['font-medium', 'text-center'], {
     },
   },
   compoundVariants: [
-    // ── strong × color (filled foreground text) ──────────────────────
-    { variant: 'strong', color: 'action', className: 'text-content-action-on-strong' },
-    { variant: 'strong', color: 'danger', className: 'text-content-danger-on-strong' },
-    { variant: 'strong', color: 'warning', className: 'text-content-warning-on-strong' },
-    { variant: 'strong', color: 'success', className: 'text-content-success-on-strong' },
-    { variant: 'strong', color: 'info', className: 'text-content-info-on-strong' },
+    // ── solid × color (filled foreground text) ──────────────────────
+    { variant: 'solid', color: 'action', className: 'text-content-action-on-strong' },
+    { variant: 'solid', color: 'danger', className: 'text-content-danger-on-strong' },
+    { variant: 'solid', color: 'warning', className: 'text-content-warning-on-strong' },
+    { variant: 'solid', color: 'success', className: 'text-content-success-on-strong' },
+    { variant: 'solid', color: 'info', className: 'text-content-info-on-strong' },
 
     // ── outline/ghost × color (transparent foreground text) ──────────
     { variant: ['outline', 'ghost'], color: 'action', className: 'text-content-action' },
@@ -248,16 +248,25 @@ export const buttonTextVariants = cva(['font-medium', 'text-center'], {
     { variant: ['outline', 'ghost'], color: 'info', className: 'text-content-info' },
   ],
   defaultVariants: {
-    variant: 'strong',
+    variant: 'solid',
     color: 'action',
     size: 'default',
   },
 });
 
-export const buttonSpinnerVariants = cva([], {
+export const buttonSpinnerVariants = cva([
+  'data-[icon=inline-start]:me-1.5',
+  'data-[icon=inline-end]:ms-1.5',
+]);
+
+// Spinner color is set via Uniwind's `colorClassName` prop (maps to the native
+// `color` prop on `ActivityIndicator`). `accent-*` utilities ONLY take effect
+// when passed through `colorClassName` — putting them on `className` is a no-op
+// because the underlying `color` prop is not part of the `style` object.
+export const buttonSpinnerColorVariants = cva([], {
   variants: {
     variant: {
-      strong: [],
+      solid: [],
       outline: [],
       ghost: [],
     },
@@ -270,29 +279,29 @@ export const buttonSpinnerVariants = cva([], {
     },
   },
   compoundVariants: [
-    // ── strong × color ───────────────────────────────────────────────
+    // ── solid × color ───────────────────────────────────────────────
     {
-      variant: 'strong',
+      variant: 'solid',
       color: 'action',
       className: 'accent-[var(--color-content-action-on-strong)]',
     },
     {
-      variant: 'strong',
+      variant: 'solid',
       color: 'danger',
       className: 'accent-[var(--color-content-danger-on-strong)]',
     },
     {
-      variant: 'strong',
+      variant: 'solid',
       color: 'warning',
       className: 'accent-[var(--color-content-warning-on-strong)]',
     },
     {
-      variant: 'strong',
+      variant: 'solid',
       color: 'success',
       className: 'accent-[var(--color-content-success-on-strong)]',
     },
     {
-      variant: 'strong',
+      variant: 'solid',
       color: 'info',
       className: 'accent-[var(--color-content-info-on-strong)]',
     },
@@ -325,7 +334,7 @@ export const buttonSpinnerVariants = cva([], {
     },
   ],
   defaultVariants: {
-    variant: 'strong',
+    variant: 'solid',
     color: 'action',
   },
 });
@@ -349,17 +358,49 @@ export const buttonGroupVariants = cva([], {
   },
 });
 
-export const buttonIconVariants = cva([], {
-  variants: {
-    size: {
-      default: 'size-5',
-      small: 'size-4',
+export const buttonIconVariants = cva(
+  ['data-[icon=inline-start]:me-1.5', 'data-[icon=inline-end]:ms-1.5'],
+  {
+    variants: {
+      variant: {
+        solid: [],
+        outline: [],
+        ghost: [],
+      },
+      color: {
+        action: [],
+        danger: [],
+        warning: [],
+        success: [],
+        info: [],
+      },
+      size: {
+        default: 'size-5',
+        small: 'size-4',
+      },
+    },
+    compoundVariants: [
+      // ── solid × color (filled foreground icon) ──────────────────────
+      { variant: 'solid', color: 'action', className: 'text-content-action-on-strong' },
+      { variant: 'solid', color: 'danger', className: 'text-content-danger-on-strong' },
+      { variant: 'solid', color: 'warning', className: 'text-content-warning-on-strong' },
+      { variant: 'solid', color: 'success', className: 'text-content-success-on-strong' },
+      { variant: 'solid', color: 'info', className: 'text-content-info-on-strong' },
+
+      // ── outline/ghost × color (transparent foreground icon) ──────────
+      { variant: ['outline', 'ghost'], color: 'action', className: 'text-content-action' },
+      { variant: ['outline', 'ghost'], color: 'danger', className: 'text-content-danger' },
+      { variant: ['outline', 'ghost'], color: 'warning', className: 'text-content-warning' },
+      { variant: ['outline', 'ghost'], color: 'success', className: 'text-content-success' },
+      { variant: ['outline', 'ghost'], color: 'info', className: 'text-content-info' },
+    ],
+    defaultVariants: {
+      variant: 'solid',
+      color: 'action',
+      size: 'default',
     },
   },
-  defaultVariants: {
-    size: 'default',
-  },
-});
+);
 
 export type ButtonVariantProps = VariantProps<typeof buttonRootVariants>;
 export type ButtonGroupVariantProps = VariantProps<typeof buttonGroupVariants>;

package/src/components/CLAUDE.md

@@ -0,0 +1,195 @@
+# 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]`, `data-slot`, and `data-icon` conventions
+- `docs/internal/practices/as-child.md` — styled-layer `asChild` via re-exported `Slot`
+
+## Six standards (Standards 4–6 apply here)
+
+Standards 1–3 govern primitive-layer authoring (see `packages/primitives/src/CLAUDE.md`).
+Standards 4–6 govern the styled layer:
+
+### Standard 4 — `data-slot` attributes
+
+Every public styled slot emits a stable `data-slot="<component>-<part>"` attribute on its outermost rendered element. The convention is lowercase, kebab-case, `<component>` then `-<slot>` if not the root.
+
+| Slot               | Attribute                    |
+| ------------------ | ---------------------------- |
+| `<Button>` root    | `data-slot="button"`         |
+| `<Button.Label>`   | `data-slot="button-label"`   |
+| `<Button.Icon>`    | `data-slot="button-icon"`    |
+| `<Button.Spinner>` | `data-slot="button-spinner"` |
+| `<Button.Group>`   | `data-slot="button-group"`   |
+| `<IconButton>`     | `data-slot="icon-button"`    |
+| `<Dialog.Content>` | `data-slot="dialog-content"` |
+
+Use `dataAttributes({ slot: '<component>-<part>' })` from `@cdx-ui/primitives` so the helper handles native (flat `data-*` keys) and web (RNW `dataSet`) correctly.
+
+#### Combining multiple data-attribute sources — use `mergeDataAttributes`
+
+When the same element receives `data-*` from more than one source (e.g. a slot identifier plus a position hint, or consumer-supplied data attrs flowing in through props), do **not** chain multiple `{...dataAttributes(...)}` spreads — on web each call returns `{ dataSet: {...} }` and a plain JSX spread replaces the `dataSet` key entirely, so the second source wipes out the first. Use `mergeDataAttributes(...)` from `@cdx-ui/primitives` to combine sources; later args win on key conflicts:
+
+```tsx
+import { dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+
+<Element
+  ref={ref}
+  className={...}
+  style={style}
+  {...props}
+  {...mergeDataAttributes(
+    props,                 // pulls in any consumer-supplied data attrs
+    dataAttributes({ slot: '<component>-<part>' }),
+    positionToDataIcon(position),                      // optional, may be undefined
+  )}
+/>
+```
+
+Spread `{...props}` first, then the merge — so any keys that `mergeDataAttributes` produces overwrite their counterparts in props with the merged values.
+
+When the styled component renders a primitive Root, the primitive Root applies the same pattern internally — incoming data attrs (slot from the styled layer) are merged with the primitive's own interaction-state data attrs and emitted once. The styled layer doesn't need to do anything special; just pass `data-slot` through and the primitive's merge does the rest.
+
+### Standard 5 — Static design variants vs. interaction state
+
+Variant functions take only static design inputs (`variant`/`color`/`size`/`fullWidth`/etc.). Interaction states (`hover`/`focus`/`active`/`disabled`/`focus-visible`) are expressed as `data-[...]:` selectors **inside** CVA variant strings, never as variant inputs.
+
+- CSS-layer state changes are free of React work: when the primitive flips `data-hover=true`, the CSS engine (web) and Uniwind's native style layer reconcile styles without re-rendering React, re-running CVA, or invoking `cn()`/`tailwind-merge`.
+- Variant-input state changes cascade React work: CVA re-runs, `cn()` re-merges, and className-prop reconciliation cascades through the tree.
+- Sub-slots can react to root state via parent selectors (`data-[hover=true]:`) without each slot subscribing to context (per Standard 1).
+- **Native compound conditions** — on native, prefer single-condition `data-[field-state=...]` selectors backed by a primitive-derived compound-state attribute over compound `data-[]:data-[]` chains (Uniwind matches only the last condition). Web may keep compound chains. See `Input/styles.ts` and `Select/styles.ts`; full practice in `docs/internal/practices/data-attributes.md` § "Compound state on native".
+
+### Standard 6 — Position hints (`data-icon="inline-start|inline-end"`)
+
+Icon-/spinner-bearing styled slots accept an optional `position?: 'leading' | 'trailing'` prop that emits `data-icon="inline-start|inline-end"`. Spacing rules in CVA target the `data-icon` attribute via logical-property utilities (`me-*`/`ms-*`) so RTL is handled for free.
+
+Mapping (via the shared `positionToDataIcon` helper at `packages/components/src/utils/positionToDataIcon.ts`):
+
+- `position="leading"` → `data-icon="inline-start"`
+- `position="trailing"` → `data-icon="inline-end"`
+- `position` omitted → no `data-icon` attribute, baseline spacing applies
+
+```tsx
+import { positionToDataIcon, type IconSlotPosition } from '../../utils/positionToDataIcon';
+
+interface ButtonIconProps {
+  position?: IconSlotPosition;
+  // ...
+}
+
+<Icon {...positionToDataIcon(position)} {...props} />;
+```
+
+```tsx
+<Button>
+  <Button.Icon as={CheckIcon} position="leading" />
+  <Button.Label>Confirm</Button.Label>
+</Button>
+```
+
+CVA expresses padding via logical-property selectors:
+
+```ts
+cva(['data-[icon=inline-start]:me-1.5 data-[icon=inline-end]:ms-1.5'], { ... });
+```
+
+Where: **styled layer.** Pure styling hint with no behavior or a11y semantics — fails Standard 3, so no primitive involvement.
+
+## Canonical reference
+
+`packages/components/src/components/Button/index.tsx` + `Button/styles.ts` is the canonical example for Standards 4–6:
+
+- `data-slot` on `Button`, `Button.Label`, `Button.Icon`, `Button.Spinner`, `Button.Group`
+- `asChild` re-uses `Slot` from `@cdx-ui/primitives` — no new primitive needed for sub-slots
+- `buttonIconVariants` / `buttonSpinnerVariants` carry `data-[icon=inline-start]:me-1.5 data-[icon=inline-end]:ms-1.5` so leading/trailing padding works without per-call overrides
+
+`packages/components/src/components/QuickActionButton/index.tsx` shows the second axis of Standard 1: a styled-layer sub-slot (the Indicator) opts into `useButtonContext()` when its styling reacts to interaction state. The pattern is the same as the primitive Root — call `useButtonContext()`, spread `mergeDataAttributes(props, dataAttributes({ ... }))` — only it lives in the styled layer.
+
+### Pattern summary
+
+Each component follows this structure (see `Button/index.tsx`):
+
+1. **Imports** — RN base components, primitive `Root` and `Slot` from `@cdx-ui/primitives`, `cn` + style context from `@cdx-ui/utils`, variant functions from `./styles`
+2. **Scope constant** — `const SCOPE = 'COMPONENT_NAME'` for `useStyleContext` with a `ParentContext.Provider` wrapper for static variant context
+3. **Root component** — renders the primitive Root (or a host element directly when no primitive exists), spreads `dataAttributes({ slot: '<component>' })`
+4. **Sub-slots** — each accepts `asChild`, renders a host element via `const Comp = asChild ? Slot : DefaultElement`, spreads `dataAttributes({ slot: '<component>-<slot>' })`. Sub-slots **do not** call `useButtonContext()` (or its equivalent) unless their own styling reacts to interaction state.
+5. **Position-aware sub-slots** — icon/spinner-style slots accept `position?: 'leading' | 'trailing'` and emit `data-icon` via `dataAttributes({ icon: '...' })`.
+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
+- **`data-slot`** emitted on every styled slot via `dataAttributes({ slot: '<component>-<part>' })`
+- **`asChild`** supported on every styled slot — `const Comp = asChild ? Slot : DefaultElement`
+- **`position`** prop on icon/spinner-style slots maps to `data-icon="inline-start|inline-end"`
+
+---
+
+## 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]` and `data-icon` selectors
+
+### 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 '@cdx-ui/utils';
+import { DISABLED_CURSOR, TRANSITION_COLORS } from '../../styles/constants';
+
+export const componentRootVariants = cva(
+  [
+    /* base classes + interaction state selectors (data-[hover=true]:..., data-[active=true]:...) */
+  ],
+  {
+    variants: {
+      /* static design axes only — variant, color, size, fullWidth, etc. */
+    },
+    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 (Standard 1). **Interaction state is never a CVA variant input** (Standard 5). On native, prefer single-condition `data-[field-state=...]` selectors backed by a primitive-derived compound-state attribute over compound `data-[]:data-[]` chains (which only match the last condition); web may keep compound chains. See `Input/styles.ts` / `Select/styles.ts`.
+- **`data-[icon=inline-start|inline-end]` selectors** for icon/spinner position spacing (Standard 6) — pair with logical-property utilities (`me-*`/`ms-*`) so RTL flips automatically.
+- **`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/constants` 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/Calendar/CalendarMonthHeader.tsx

@@ -0,0 +1,124 @@
+import { forwardRef, useCallback, useMemo, type ComponentRef } from 'react';
+import { Pressable, Text, View, type ViewProps } from 'react-native';
+import {
+  formatCalendarMonthYear,
+  formatMonthId,
+  parseMonthId,
+  resolveDateComponentLabels,
+  type DateComponentLabels,
+  type MonthId,
+} from '@cdx-ui/formatters';
+import { cn } from '@cdx-ui/utils';
+import { ChevronLeft, ChevronRight, KeyboardArrowDown } from '@cdx-ui/icons';
+import { Icon } from '../Icon';
+import { IconButton } from '../IconButton';
+import {
+  calendarMonthHeaderIconVariants,
+  calendarMonthHeaderLabelVariants,
+  calendarMonthHeaderNavVariants,
+  calendarMonthHeaderToggleVariants,
+  calendarMonthHeaderVariants,
+} from './styles';
+
+export type CalendarNavigationView = 'month' | 'year';
+
+export interface CalendarMonthHeaderProps extends ViewProps {
+  monthId: MonthId;
+  onMonthIdChange: (monthId: MonthId) => void;
+  disabled?: boolean;
+  view: CalendarNavigationView;
+  onViewChange: (view: CalendarNavigationView) => void;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+}
+
+export const CalendarMonthHeader = forwardRef<ComponentRef<typeof View>, CalendarMonthHeaderProps>(
+  (
+    {
+      monthId,
+      onMonthIdChange,
+      disabled = false,
+      view,
+      onViewChange,
+      locale = 'en-US',
+      labels: labelsProp,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const label = formatCalendarMonthYear(monthId, { locale });
+    const isYearView = view === 'year';
+
+    const shiftMonth = useCallback(
+      (delta: number) => {
+        const parts = parseMonthId(monthId);
+        if (!parts) {
+          return;
+        }
+        const date = new Date(parts.year, parts.month - 1 + delta, 1);
+        onMonthIdChange(formatMonthId({ year: date.getFullYear(), month: date.getMonth() + 1 }));
+      },
+      [monthId, onMonthIdChange],
+    );
+
+    const toggleYearView = useCallback(() => {
+      if (disabled) {
+        return;
+      }
+      onViewChange(isYearView ? 'month' : 'year');
+    }, [disabled, isYearView, onViewChange]);
+
+    return (
+      <View
+        ref={ref}
+        className={cn(calendarMonthHeaderVariants(), className)}
+        style={style}
+        {...props}
+      >
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={isYearView ? labels.showCalendar : labels.showYearPicker}
+          disabled={disabled}
+          onPress={toggleYearView}
+          className={calendarMonthHeaderToggleVariants()}
+        >
+          <Text className={calendarMonthHeaderLabelVariants({ isYearView })} numberOfLines={1}>
+            {label}
+          </Text>
+          <Icon
+            as={isYearView ? KeyboardArrowDown : ChevronRight}
+            className={calendarMonthHeaderIconVariants({ isYearView })}
+          />
+        </Pressable>
+
+        {!isYearView ? (
+          <View className={calendarMonthHeaderNavVariants()}>
+            <IconButton
+              as={ChevronLeft}
+              variant="ghost"
+              color="neutral"
+              size="small"
+              accessibilityLabel={labels.previousMonth}
+              isDisabled={disabled}
+              onPress={() => shiftMonth(-1)}
+            />
+            <IconButton
+              as={ChevronRight}
+              variant="ghost"
+              color="neutral"
+              size="small"
+              accessibilityLabel={labels.nextMonth}
+              isDisabled={disabled}
+              onPress={() => shiftMonth(1)}
+            />
+          </View>
+        ) : null}
+      </View>
+    );
+  },
+);
+
+CalendarMonthHeader.displayName = 'CalendarMonthHeader';

package/src/components/Calendar/CalendarYearPickerGrid.tsx

@@ -0,0 +1,101 @@
+import { forwardRef, useCallback, useMemo, type ComponentRef } from 'react';
+import { Pressable, Text, View, type ViewProps } from 'react-native';
+import {
+  formatMonthId,
+  formatSelectYear,
+  parseMonthId,
+  resolveDateComponentLabels,
+  type DateComponentLabels,
+  type MonthId,
+} from '@cdx-ui/formatters';
+import { cn } from '@cdx-ui/utils';
+import type { CalendarNavigationView } from './CalendarMonthHeader';
+import {
+  calendarPillCellTextVariants,
+  calendarPillCellVariants,
+  calendarYearPickerGridVariants,
+} from './styles';
+
+const YEAR_RANGE_BEFORE = 9;
+const YEAR_RANGE_AFTER = 11;
+
+export interface CalendarYearPickerGridProps extends ViewProps {
+  monthId: MonthId;
+  onMonthIdChange: (monthId: MonthId) => void;
+  disabled?: boolean;
+  onViewChange: (view: CalendarNavigationView) => void;
+  labels?: Partial<DateComponentLabels>;
+}
+
+export const CalendarYearPickerGrid = forwardRef<
+  ComponentRef<typeof View>,
+  CalendarYearPickerGridProps
+>(
+  (
+    {
+      monthId,
+      onMonthIdChange,
+      disabled = false,
+      onViewChange,
+      labels: labelsProp,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const parts = parseMonthId(monthId);
+    const currentYear = parts?.year ?? new Date().getFullYear();
+    const currentMonth = parts?.month ?? 1;
+
+    const years = useMemo(
+      () =>
+        Array.from(
+          { length: YEAR_RANGE_BEFORE + YEAR_RANGE_AFTER + 1 },
+          (_, i) => currentYear - YEAR_RANGE_BEFORE + i,
+        ),
+      [currentYear],
+    );
+
+    const selectYear = useCallback(
+      (year: number) => {
+        if (disabled) {
+          return;
+        }
+        onMonthIdChange(formatMonthId({ year, month: currentMonth }));
+        onViewChange('month');
+      },
+      [currentMonth, disabled, onMonthIdChange, onViewChange],
+    );
+
+    return (
+      <View
+        ref={ref}
+        className={cn(calendarYearPickerGridVariants(), className)}
+        style={style}
+        accessibilityRole="none"
+        {...props}
+      >
+        {years.map((year) => {
+          const selected = year === currentYear;
+          return (
+            <Pressable
+              key={year}
+              accessibilityRole="button"
+              accessibilityState={{ selected, disabled }}
+              accessibilityLabel={formatSelectYear(labels, year)}
+              disabled={disabled}
+              onPress={() => selectYear(year)}
+              className={calendarPillCellVariants({ selected, disabled })}
+            >
+              <Text className={calendarPillCellTextVariants({ selected })}>{String(year)}</Text>
+            </Pressable>
+          );
+        })}
+      </View>
+    );
+  },
+);
+
+CalendarYearPickerGrid.displayName = 'CalendarYearPickerGrid';