@cdx-ui/primitives 0.0.1-beta.9 → 0.0.1-beta.91

package/lib/typescript/tile/index.d.ts

@@ -0,0 +1,5 @@
+export type { ITileContextValue, ITileGroupMultipleProps, ITileGroupProps, ITileGroupSingleProps, ITileGroupContextValue, ITileIndicatorProps, ITileLeadingSlotProps, ITilePressablePassthrough, ITileProps, ITileTrailingSlotProps, TileGroupType, TileGroupValue, } from './types';
+export { TileProvider, useTileContext } from './context';
+export { TileRoot, type TileRootProps } from './TileRoot';
+export { TileGroup, type TileGroupProps } from './TileGroup';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/tile/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tile/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,UAAU,EACV,sBAAsB,EACtB,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/lib/typescript/tile/types.d.ts

@@ -0,0 +1,108 @@
+import type { PressableProps, ViewProps } from 'react-native';
+export type TileGroupType = 'single' | 'multiple';
+export type TileGroupValue = string | string[] | undefined;
+interface ITileGroupBaseProps extends ViewProps {
+    /** Merge group props onto a single child instead of rendering the default View. */
+    asChild?: boolean;
+    /** Disables the whole group. */
+    isDisabled?: boolean;
+    /** Accessible name for the group (radiogroup / group). */
+    'aria-label'?: string;
+}
+export interface ITileGroupSingleProps extends ITileGroupBaseProps {
+    /** Single-select (radio semantics). One value at a time. */
+    type: 'single';
+    /** Controlled selected value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Called when selection changes. */
+    onValueChange?: (value: string) => void;
+}
+export interface ITileGroupMultipleProps extends ITileGroupBaseProps {
+    /** Multi-select (checkbox semantics). Zero to `max` values at a time. */
+    type: 'multiple';
+    /** Controlled selected values. */
+    value?: string[];
+    /** Uncontrolled initial values. */
+    defaultValue?: string[];
+    /** Called when selection changes. */
+    onValueChange?: (value: string[]) => void;
+    /** Maximum selections allowed. @default Infinity */
+    max?: number;
+}
+/**
+ * Discriminated union: `type` narrows `value` / `defaultValue` / `onValueChange`,
+ * and `max` is only valid on `type="multiple"`.
+ */
+export type ITileGroupProps = ITileGroupSingleProps | ITileGroupMultipleProps;
+export interface ITileGroupContextValue {
+    type: TileGroupType;
+    /** Current selection (string for single, array for multiple). */
+    value: string | string[] | undefined;
+    toggleValue: (tileValue: string) => void;
+    isSelected: (tileValue: string) => boolean;
+    /** Group-level disabled or multi-select at max (unselected tiles). */
+    isTileDisabledByGroup: (tileValue: string) => boolean;
+    isGroupDisabled: boolean;
+    max: number;
+}
+export interface ITileContextValue {
+    /** This tile's `value`. */
+    value: string;
+    isSelected: boolean;
+    /** Effective disabled (group rules + tile `disabled`). */
+    isDisabled: boolean;
+    selectionType: TileGroupType;
+}
+export type ITilePressablePassthrough = Partial<Pick<PressableProps, 'onPressIn' | 'onPressOut' | 'onHoverIn' | 'onHoverOut'>>;
+export interface ITileProps extends PressableProps, ITilePressablePassthrough {
+    /** Merge tile props onto a single child instead of rendering the default Pressable. */
+    asChild?: boolean;
+    /**
+     * Identifies this tile within `Tile.Group`. Must be unique within the group.
+     * Standalone tiles still require a value (useful for form submission, analytics, etc.).
+     */
+    value: string;
+    /**
+     * Disables this tile (in addition to group rules such as multi-select max).
+     */
+    disabled?: boolean;
+    /**
+     * Controlled selected state for **standalone** usage (no parent `Tile.Group`).
+     * Ignored when the tile is rendered inside a `Tile.Group` — selection is owned by the group.
+     */
+    isSelected?: boolean;
+    /**
+     * Initial selected state for **standalone**, uncontrolled usage.
+     */
+    defaultSelected?: boolean;
+    /**
+     * Called when standalone selection state changes. Group context overrides this — when inside
+     * a `Tile.Group`, use the group's `onValueChange` instead.
+     */
+    onSelectedChange?: (isSelected: boolean) => void;
+}
+export interface ITileLeadingSlotProps extends ViewProps {
+    /**
+     * Leading content is decorative by default for screen readers.
+     * @default true
+     */
+    'aria-hidden'?: boolean;
+}
+export interface ITileIndicatorProps extends ViewProps {
+    /**
+     * Explicit indicator visual. When inside a `Tile.Group`, auto-infers from `type`
+     * (`single` → radio, `multiple` → checkbox). For standalone tiles, defaults to `'checkbox'`
+     * to match the standalone `checkbox` ARIA role; override with `indicatorType="radio"` if
+     * a radio-style visual is needed.
+     */
+    indicatorType?: 'radio' | 'checkbox';
+}
+/**
+ * Generic trailing content slot. Use for chevrons, amounts, chips, status text — anything that
+ * is **not** the radio/checkbox selection affordance. For that, use `Tile.Indicator`.
+ */
+export type ITileTrailingSlotProps = ViewProps;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/tile/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tile/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/toast/ToastRoot.d.ts

@@ -0,0 +1,7 @@
+import { View } from 'react-native';
+import type { IToastProps } from './types';
+export interface ToastRootProps extends IToastProps {
+    asChild?: boolean;
+}
+export declare const ToastRoot: import("react").ForwardRefExoticComponent<ToastRootProps & import("react").RefAttributes<View>>;
+//# sourceMappingURL=ToastRoot.d.ts.map

package/lib/typescript/toast/ToastRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToastRoot.d.ts","sourceRoot":"","sources":["../../../src/toast/ToastRoot.tsx"],"names":[],"mappings":"AACA,OAAO,EAAY,IAAI,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,SAAS,iGA0BrB,CAAC"}

package/lib/typescript/toast/context.d.ts

@@ -0,0 +1,6 @@
+import type { IToastContextValue } from './types';
+export declare const ToastProvider: import("react").FunctionComponent<{
+    children: import("react").ReactNode;
+    value: IToastContextValue;
+}>, useToastContext: () => IToastContextValue;
+//# sourceMappingURL=context.d.ts.map

package/lib/typescript/toast/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/toast/context.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,eAAO,MAAO,aAAa;;;IAAE,eAAe,0BAAqD,CAAC"}

package/lib/typescript/toast/index.d.ts

@@ -0,0 +1,3 @@
+export { ToastProvider, useToastContext } from './context';
+export { ToastRoot, type ToastRootProps } from './ToastRoot';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/toast/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/toast/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/lib/typescript/toast/types.d.ts

@@ -0,0 +1,16 @@
+import type { ViewProps } from 'react-native';
+export interface IToastContextValue {
+    /** Unique identifier for the toast */
+    nativeID: string;
+}
+export interface IToastProps extends ViewProps {
+    /** Unique identifier for the toast */
+    id?: string;
+    /**
+     * ARIA role for the toast element.
+     * Use `'alert'` for urgent/danger toasts that require assertive announcements.
+     * @default 'status'
+     */
+    role?: 'status' | 'alert';
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/toast/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/toast/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC3B"}

package/lib/typescript/utils/dataAttributes.d.ts

@@ -1,14 +1,8 @@
 /**
- * Produces platform-specific props for data attributes.
+ * Produces `data-*` props for native platforms (consumed by Uniwind).
+ * Web (.web.ts): returns a `dataSet` object consumed by React Native Web instead.
  *
- * Native: individual `data-*` props consumed by Uniwind.
- * Web (.web.ts): a `dataSet` object consumed by React Native Web.
- *
- * Boolean values serialize to `"true"` / `"false"` strings.
- * String values pass through as-is.
- * Undefined values are omitted.
+ * Delegates to `domDataAttributes` so the conversion logic has a single source of truth.
  */
-type DataAttributeValue = boolean | string | undefined;
-export declare function dataAttributes(attrs: Record<string, DataAttributeValue>): Record<string, string>;
-export {};
+export { domDataAttributes as dataAttributes, mergeDomDataAttributes as mergeDataAttributes, } from './domDataAttributes';
 //# sourceMappingURL=dataAttributes.d.ts.map

package/lib/typescript/utils/dataAttributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataAttributes.d.ts","sourceRoot":"","sources":["../../../src/utils/dataAttributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAMvD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUhG"}
+{"version":3,"file":"dataAttributes.d.ts","sourceRoot":"","sources":["../../../src/utils/dataAttributes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,iBAAiB,IAAI,cAAc,EACnC,sBAAsB,IAAI,mBAAmB,GAC9C,MAAM,qBAAqB,CAAC"}

package/lib/typescript/utils/dataAttributes.web.d.ts

@@ -12,5 +12,21 @@ type DataAttributeValue = boolean | string | undefined;
 export declare function dataAttributes(attrs: Record<string, DataAttributeValue>): {
     dataSet: Record<string, boolean | string>;
 };
+/**
+ * Merges multiple sources of data attributes into a single `{ dataSet }` prop
+ * on web. Each source may be a `dataAttributes()` output (`{ dataSet: {...} }`)
+ * or any props object that contains a `dataSet` key — other keys are ignored.
+ * Later sources override earlier sources on inner-key conflicts.
+ *
+ * Required when an element receives data attributes from more than one source:
+ * a plain prop spread merges by replacing the `dataSet` key entirely, so e.g.
+ * `{...dataAttributes({ slot })} {...dataAttributes({ hover })}` keeps only the
+ * second `dataSet`. Use `mergeDataAttributes(...)` to combine them safely.
+ */
+export declare function mergeDataAttributes(...sources: ({
+    dataSet?: Record<string, unknown>;
+} | Record<string, unknown> | undefined)[]): {
+    dataSet: Record<string, unknown>;
+};
 export {};
 //# sourceMappingURL=dataAttributes.web.d.ts.map

package/lib/typescript/utils/dataAttributes.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataAttributes.web.d.ts","sourceRoot":"","sources":["../../../src/utils/dataAttributes.web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC3C,CAQA"}
+{"version":3,"file":"dataAttributes.web.d.ts","sourceRoot":"","sources":["../../../src/utils/dataAttributes.web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC3C,CAQA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,OAAO,EAAE,CAAC;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,GAC1F;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAStC"}

package/lib/typescript/utils/domDataAttributes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Produces `data-*` DOM attribute props for use on raw HTML elements (e.g. `<button>`).
+ *
+ * Unlike `dataAttributes`, which has a platform-specific `.web.ts` sibling that returns a
+ * `dataSet` object for React Native Web components, this file has no platform variant.
+ * The bundler therefore always resolves to this single implementation, making it safe to
+ * import from `.web.tsx` host components that render native DOM elements directly.
+ *
+ * Boolean values serialize to `"true"` / `"false"` strings.
+ * String values pass through as-is.
+ * Undefined values are omitted.
+ */
+export type DomDataAttributeValue = boolean | string | undefined;
+export declare function domDataAttributes(attrs: Record<string, DomDataAttributeValue>): Record<string, string>;
+/**
+ * Merges multiple sources of DOM data attributes into a single flat object of
+ * `data-*` keys. Each source can be a `domDataAttributes()` output or any props
+ * object — non-`data-*` keys are ignored. Later sources override earlier sources
+ * on key conflicts.
+ *
+ * Use this when an element receives `data-*` attributes from more than one
+ * source (e.g. a styled layer's `data-slot` and a primitive's interaction-state
+ * `data-hover`/`data-focus` etc.) and a plain prop spread would otherwise be
+ * fine on native but lose attributes on web (where `dataAttributes()` returns
+ * `{ dataSet }` — see the `.web.ts` sibling for the web merge).
+ */
+export declare function mergeDomDataAttributes(...sources: (Record<string, unknown> | undefined)[]): Record<string, string>;
+//# sourceMappingURL=domDataAttributes.d.ts.map

package/lib/typescript/utils/domDataAttributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domDataAttributes.d.ts","sourceRoot":"","sources":["../../../src/utils/domDataAttributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAMjE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/primitives",
-  "version": "0.0.1-beta.9",
+  "version": "0.0.1-beta.91",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -51,13 +51,16 @@
     }
   },
   "dependencies": {
+    "@react-aria/utils": "^3.33.0",
     "@react-aria/visually-hidden": "3.8.30",
     "@react-native-aria/checkbox": "0.2.10",
     "@react-native-aria/focus": "^0.2.9",
     "@react-native-aria/interactions": "^0.2.16",
+    "@react-native-aria/radio": "0.2.13",
     "@react-stately/checkbox": "3.7.4",
+    "@react-stately/radio": "3.12.0",
     "@react-stately/toggle": "3.9.4",
-    "@cdx-ui/utils": "0.0.1-beta.9"
+    "@cdx-ui/utils": "0.0.1-beta.91"
   },
   "devDependencies": {
     "@types/react": "*",

package/src/CLAUDE.md

@@ -0,0 +1,84 @@
+# Primitive Authoring
+
+Auto-loaded when working in `packages/primitives/src/**`.
+
+Primitives in `@cdx-ui/primitives` are unstyled behavioral components that handle accessibility and interactions. Read the full guides before making changes:
+
+- `docs/internal/practices/composition.md` — compound component structure
+- `docs/internal/practices/types.md` — `I*Props` convention, extending RN base types
+- `docs/internal/practices/accessibility.md` — ARIA roles, keyboard nav, screen reader support
+- `docs/internal/practices/as-child.md` — `asChild` prop pattern
+- `docs/internal/practices/data-attributes.md` — `data-state` and `data-slot` conventions
+
+## Six standards
+
+Forge UI primitives and their styled counterparts follow six standards. The first three govern primitive-layer authoring; the last three govern the styled layer (see `packages/components/src/components/CLAUDE.md`).
+
+### Standard 1 — Data attributes for interaction states
+
+Root primitives emit `data-*` attributes for the interaction state they own and expose that state via context. Sub-slots **do not** subscribe to context and **do not** emit interaction `data-*` attributes — they opt in only when their own styling or behavior reacts to that state.
+
+- **Root** — emits + provides context. Always.
+- **Sub-slot** — does not subscribe, does not emit. Opt in only when the styled layer (or the slot's own behavior) demonstrably reacts to the state.
+
+Pointlessly emitting on every sub-slot multiplies bridge writes (native) and DOM attribute writes (web) for no consumer benefit. A sub-slot that calls `useButtonContext()` becomes a subscriber — every interaction re-renders it even when nothing visually changes.
+
+`useButtonContext()` stays exported so styled-layer slots and external consumers can opt in when they actually need it.
+
+### Standard 2 — `asChild` support
+
+Every public primitive supports `asChild` via `Slot` (re-exported from `packages/primitives/src/slot`). The runtime cost when `asChild` is `false` is a single boolean check; consumers who opt in pay the merge cost themselves.
+
+```tsx
+const Comp = asChild ? Slot : DefaultElement;
+```
+
+### Standard 3 — When to create a primitive (the primitive-existence test)
+
+Create a primitive **only** when the slot owns behavior. A slot earns a primitive if it has at least one of:
+
+1. **Behavioral state machinery** — interaction hooks (`useFocus`, `useFocusRing`, `useHover`, `usePress`), controlled/uncontrolled state, open/closed/checked/value management.
+2. **Non-host accessibility semantics** — ARIA role/state beyond what the host element provides natively, custom keyboard handling, screen-reader announcements, focus traps.
+3. **Cross-platform host abstraction** — different host element per platform (e.g., a `.web.tsx` / `.native.tsx` split).
+4. **Compound contract ownership** — defines the compound's state surface and is the context provider (i.e., the Root).
+
+A slot does **not** earn a primitive if it only:
+
+- Wraps a host element with `className`/`style`.
+- Reads context for styling (the styled layer reads it directly via `useButtonContext`, `useStyleContext`, etc.).
+- Wants `asChild` (the styled layer uses `Slot` directly — it is re-exported from `@cdx-ui/primitives`).
+
+This eliminates the "factory pass-through" anti-pattern (e.g., a `ButtonIcon` primitive whose body is `<View {...props} ref={ref} />`). Such wrappers add nothing and force every consumer through a useless layer.
+
+## Canonical reference
+
+`packages/primitives/src/button/ButtonRoot.tsx` is the canonical concrete primitive. It demonstrates every Standard 1–3 requirement: concrete `forwardRef` component over `Pressable`, `asChild` via `Slot`, `dataAttributes()` for interaction state, `ButtonProvider` for context, function-as-children, ARIA defaults, and composed event handlers.
+
+`packages/primitives/src/button/` only ships `ButtonRoot` + `useButtonContext` + types. There is intentionally no `ButtonLabel`/`ButtonIcon`/`ButtonSpinner`/`ButtonGroup` primitive — those slots fail the primitive-existence test, so they live in `@cdx-ui/components` only.
+
+The styled-layer Indicator inside `packages/components/src/components/QuickActionButton/index.tsx` is the canonical example of a sub-slot that legitimately opts into interaction state. When (and only when) its own styling reacts to hover/focus/press, it reads `useButtonContext()` and emits `data-*` via `mergeDataAttributes(props, dataAttributes({ ... }))` — the same pattern external consumers use.
+
+## Pattern summary
+
+Each concrete primitive is a `forwardRef` component that hardcodes its default RN base element and supports `asChild` via `Slot`:
+
+1. **Concrete component** — `export const ComponentRoot = forwardRef<View, Props>(...)` hardcodes `View`/`Pressable`/`Text` as the default; uses `const Comp = asChild ? Slot : View` for the escape hatch
+2. **Interaction hooks** — `useFocus`, `useFocusRing`, `useHover`, `usePress` from `@react-native-aria/*`
+3. **Data attributes** — `dataAttributes({ hover, focus, active, disabled, focusVisible })` emitted on the rendered element for Uniwind `data-[state]` selectors
+4. **Context provider** — interaction state exposed via context so sub-slots and external consumers can opt in
+5. **Barrel export** — `index.ts` re-exports the concrete components, context, and types
+6. **`displayName`** — set on every exported component
+
+## Key rules
+
+- **Unstyled** — no visual styling (no `className`, no color/spacing classes). Only behavioral and a11y concerns.
+- **`asChild` via `Slot`** — import `Slot` from `../slot`; use `const Comp = asChild ? Slot : DefaultElement`.
+- **`I*Props` convention** — public prop types are aliased with `I` prefix (e.g., `IButtonProps`), exported from `types.ts`.
+- **`Interface*Props` pattern** — the full interface (e.g., `InterfaceButtonProps`) extends the appropriate RN base type (`PressableProps`, `ViewProps`, etc.) with interaction state booleans (`isHovered`, `isActive`, `isFocused`, `isFocusVisible`, `isDisabled`); re-exported as `I*Props`.
+- **`dataAttributes()` helper** — always use the helper from `../utils/dataAttributes` to emit `data-*` props; it handles platform differences (native vs web).
+- **`mergeDataAttributes(...sources)` helper** — when a primitive Root receives data attrs through `props` from its styled layer (e.g. `data-slot`) AND emits its own data attrs (e.g. interaction state), combine them via `mergeDataAttributes(props, dataAttributes({...}))`. A plain `{...dataAttributes({...})} {...props}` spread chain wipes out one side on web — `dataAttributes` returns `{ dataSet }`, so back-to-back spreads replace each other. The merge helper preserves both. `ButtonRoot.tsx` shows the canonical pattern.
+- **`composeEventHandlers`** from `@cdx-ui/utils` — merge consumer handlers with internal handlers; never silently override.
+- **`forwardRef`** on every component — refs forwarded to the underlying host element.
+- **ARIA roles** — set `role` with a sensible default (e.g., `role={props?.role || 'button'}`).
+- **Render children as function** — support `children` as `(state: InteractionState) => ReactNode` for state-driven rendering where the Root exposes interaction state.
+- **Consumable independently** of `@cdx-ui/components` — no imports from the styled layer.

package/src/avatar/AvatarRoot.tsx

@@ -0,0 +1,39 @@
+import type React from 'react';
+import { forwardRef, useMemo, useState } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { Slot } from '../slot';
+import { AvatarProvider } from './context';
+import type { IAvatarProps, IAvatarContextValue } from './types';
+
+export interface AvatarRootProps extends IAvatarProps {
+  asChild?: boolean;
+}
+
+export const AvatarRoot = forwardRef<React.ComponentRef<typeof View>, AvatarRootProps>(
+  ({ asChild, children, ...props }, ref) => {
+    const [imageLoaded, setImageLoaded] = useState(false);
+    const [imageError, setImageError] = useState(false);
+
+    const contextValue = useMemo<IAvatarContextValue>(
+      () => ({ imageLoaded, imageError, setImageLoaded, setImageError }),
+      [imageLoaded, imageError],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <AvatarProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          role={props.role || 'img'}
+          accessibilityRole="image"
+          {...(props as ViewProps)}
+        >
+          {children}
+        </Comp>
+      </AvatarProvider>
+    );
+  },
+);
+
+AvatarRoot.displayName = 'AvatarRoot';

package/src/avatar/index.ts

@@ -1,43 +1,3 @@
-import type React from 'react';
-import { createAvatarBadge } from './createAvatarBadge';
-import { createAvatarIcon } from './createAvatarIcon';
-import { createAvatarText } from './createAvatarText';
-import { createAvatarImage } from './createAvatarImage';
-import { createAvatarRoot } from './createAvatarRoot';
-import type { IAvatarComponentType } from './types';
-
-export type {
-  IAvatarBadgeProps,
-  IAvatarComponentType,
-  IAvatarIconProps,
-  IAvatarTextProps,
-  IAvatarImageProps,
-  IAvatarProps,
-} from './types';
-
-export function createAvatar<Root, Image, Text, Icon, Badge>(BaseComponents: {
-  Root: React.ComponentType<Root>;
-  Image: React.ComponentType<Image>;
-  Text: React.ComponentType<Text>;
-  Icon: React.ComponentType<Icon>;
-  Badge: React.ComponentType<Badge>;
-}) {
-  const Avatar = createAvatarRoot(BaseComponents.Root);
-  const AvatarImage = createAvatarImage(BaseComponents.Image);
-  const Text = createAvatarText(BaseComponents.Text);
-  const AvatarIcon = createAvatarIcon(BaseComponents.Icon);
-  const Badge = createAvatarBadge(BaseComponents.Badge);
-
-  Avatar.displayName = 'AvatarPrimitive';
-  AvatarImage.displayName = 'AvatarPrimitive.Image';
-  Text.displayName = 'AvatarPrimitive.Text';
-  AvatarIcon.displayName = 'AvatarPrimitive.Icon';
-  Badge.displayName = 'AvatarPrimitive.Badge';
-
-  return Object.assign(Avatar, {
-    Image: AvatarImage,
-    Text,
-    Icon: AvatarIcon,
-    Badge,
-  }) as unknown as IAvatarComponentType<Root, Image, Text, Icon, Badge>;
-}
+export type { IAvatarContextValue, IAvatarImageProps, IAvatarProps } from './types';
+export { useAvatarContext } from './context';
+export { AvatarRoot, type AvatarRootProps } from './AvatarRoot';

package/src/avatar/types.ts

@@ -1,4 +1,4 @@
-import type { ImageProps, TextProps, ViewProps } from 'react-native';
+import type { ImageProps, ViewProps } from 'react-native';
 
 // =============================================================================
 // AVATAR ROOT
@@ -19,31 +19,6 @@ export interface IAvatarImageProps extends Omit<ImageProps, 'source'> {
   alt?: string;
 }
 
-// =============================================================================
-// AVATAR FALLBACK TEXT
-// =============================================================================
-
-export interface IAvatarTextProps extends TextProps {
-  /** Full name — initials will be derived automatically */
-  children?: React.ReactNode;
-}
-
-// =============================================================================
-// AVATAR ICON (fallback icon — hidden when image loads)
-// =============================================================================
-
-export interface IAvatarIconProps extends ViewProps {
-  children?: React.ReactNode;
-}
-
-// =============================================================================
-// AVATAR BADGE
-// =============================================================================
-
-export interface IAvatarBadgeProps extends ViewProps {
-  children?: React.ReactNode;
-}
-
 // =============================================================================
 // CONTEXT
 // =============================================================================
@@ -54,24 +29,3 @@ export interface IAvatarContextValue {
   setImageLoaded: (loaded: boolean) => void;
   setImageError: (error: boolean) => void;
 }
-
-// =============================================================================
-// COMPOUND COMPONENT TYPE
-// =============================================================================
-
-export type IAvatarComponentType<Root, Image, Text, Icon, Badge> = React.ForwardRefExoticComponent<
-  React.RefAttributes<Root> & React.PropsWithoutRef<Root> & IAvatarProps
-> & {
-  Image: React.ForwardRefExoticComponent<
-    React.RefAttributes<Image> & React.PropsWithoutRef<Image> & IAvatarImageProps
-  >;
-  Text: React.ForwardRefExoticComponent<
-    React.RefAttributes<Text> & React.PropsWithoutRef<Text> & IAvatarTextProps
-  >;
-  Icon: React.ForwardRefExoticComponent<
-    React.RefAttributes<Icon> & React.PropsWithoutRef<Icon> & IAvatarIconProps
-  >;
-  Badge: React.ForwardRefExoticComponent<
-    React.RefAttributes<Badge> & React.PropsWithoutRef<Badge> & IAvatarBadgeProps
-  >;
-};

package/src/button/ButtonRoot.tsx

@@ -0,0 +1,115 @@
+import type React from 'react';
+import { forwardRef, useMemo } from 'react';
+import { Pressable, type PressableProps } from 'react-native';
+import { composeEventHandlers } from '@cdx-ui/utils';
+import { useFocus, useFocusRing } from '@react-native-aria/focus';
+import { useHover, usePress } from '@react-native-aria/interactions';
+import type { InteractionState } from '../types';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { ButtonProvider } from './context';
+import type { IButtonProps } from './types';
+
+export interface ButtonRootProps extends Omit<IButtonProps, 'children'> {
+  asChild?: boolean;
+  children?: ((state: InteractionState) => React.ReactNode) | React.ReactNode;
+}
+
+export const ButtonRoot = forwardRef<React.ComponentRef<typeof Pressable>, ButtonRootProps>(
+  (
+    {
+      asChild,
+      children,
+      isDisabled,
+      isHovered: isHoveredProp,
+      isActive: isActiveProp,
+      isFocused: isFocusedProp,
+      isFocusVisible: isFocusVisibleProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const { isFocused, focusProps } = useFocus();
+    const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+      isFocusVisible: boolean;
+      focusProps: typeof focusProps;
+    };
+    const { pressProps: pressableProps, isPressed: isActive } = usePress({
+      isDisabled,
+    });
+    const { isHovered, hoverProps } = useHover();
+
+    const contextValue = useMemo(() => {
+      return {
+        hover: isHoveredProp || isHovered,
+        focus: isFocusedProp || isFocused,
+        active: isActiveProp || isActive,
+        disabled: !!isDisabled,
+        focusVisible: isFocusVisibleProp || isFocusVisible,
+      };
+    }, [
+      isHovered,
+      isHoveredProp,
+      isFocused,
+      isFocusedProp,
+      isActive,
+      isActiveProp,
+      isDisabled,
+      isFocusVisible,
+      isFocusVisibleProp,
+    ]);
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <ButtonProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          role={props?.role || 'button'}
+          disabled={isDisabled}
+          {...(props as PressableProps)}
+          {...mergeDataAttributes(
+            props,
+            dataAttributes({
+              hover: isHoveredProp || isHovered,
+              focus: isFocusedProp || isFocused,
+              active: isActiveProp || isActive,
+              disabled: !!isDisabled,
+              focusVisible: isFocusVisibleProp || isFocusVisible,
+            }),
+          )}
+          onPressIn={composeEventHandlers(props?.onPressIn, pressableProps.onPressIn)}
+          onPressOut={composeEventHandlers(props?.onPressOut, pressableProps.onPressOut)}
+          onHoverIn={composeEventHandlers(props?.onHoverIn, hoverProps.onHoverIn)}
+          onHoverOut={composeEventHandlers(props?.onHoverOut, hoverProps.onHoverOut)}
+          onFocus={composeEventHandlers(
+            composeEventHandlers(
+              props?.onFocus as (...args: unknown[]) => unknown,
+              focusProps.onFocus,
+            ),
+            focusRingProps.onFocus,
+          )}
+          onBlur={composeEventHandlers(
+            composeEventHandlers(
+              props?.onBlur as (...args: unknown[]) => unknown,
+              focusProps.onBlur,
+            ),
+            focusRingProps.onBlur,
+          )}
+        >
+          {typeof children === 'function'
+            ? children({
+                hover: isHoveredProp || isHovered,
+                focus: isFocusedProp || isFocused,
+                active: isActiveProp || isActive,
+                disabled: !!isDisabled,
+                focusVisible: isFocusVisibleProp || isFocusVisible,
+              })
+            : children}
+        </Comp>
+      </ButtonProvider>
+    );
+  },
+);
+
+ButtonRoot.displayName = 'ButtonRoot';

package/src/button/index.ts

@@ -0,0 +1,3 @@
+export type { IButtonProps } from './types';
+export { useButtonContext } from './context';
+export { ButtonRoot, type ButtonRootProps } from './ButtonRoot';