@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/src/components/chart/AGENTS.md

@@ -87,6 +87,14 @@ knows nothing about tokens.
   tailwind-merge is what lets a caller's `className="aspect-video h-auto"`
   cleanly win when they want that instead.
 
+- **`frameClassName` resizes the frame, not the root.** The canvas fills the
+  frame, and the frame carries the size's height, so a `className` on the root
+  cannot shorten the plot — the frame would overflow it. `frameClassName` is
+  merged after the size's `h-chart-*`, and the tokens are registered with
+  tailwind-merge, so `h-16` cleanly replaces it. `Kpi.Sparkline` is the reason
+  it exists: a sparkline is a chart with no axes a third the height of the
+  smallest one.
+
 - **The tooltip is a React Native view even though it floats over the canvas.**
   It wants `popover`, `border`, the radius scale and the type scale, none of
   which exist in Skia, and it is the part a caller most wants to restyle —

package/src/components/chart/chart.tsx

@@ -72,6 +72,12 @@ export type ChartProps = {
 	/** How the scrub coexists with a scrolling parent. Defaults to holding. */
 	scrubConfig?: ScrubConfig;
 	className?: string;
+	/**
+	 * Merged onto the frame — the view the canvas fills — after the size's
+	 * height. `frameClassName="h-16"` is a sparkline; the three `size` heights
+	 * are for a chart someone reads with axes.
+	 */
+	frameClassName?: string;
 	/** Named on the frame, so a capture flow or a test can find the plot. */
 	testID?: string;
 	children?: ReactNode;
@@ -106,6 +112,7 @@ function ChartRoot({
 	orientation = "vertical",
 	scrubConfig,
 	className,
+	frameClassName,
 	testID,
 	children,
 }: ChartProps): ReactElement {
@@ -231,7 +238,7 @@ function ChartRoot({
 	return (
 		<ChartProvider value={value}>
 			<View className={slots.root({ className })}>
-				<View className={slots.frame()} onLayout={onLayout} testID={testID}>
+				<View className={slots.frame({ className: frameClassName })} onLayout={onLayout} testID={testID}>
 					<CartesianChart
 						curve={curve}
 						data={data}

package/src/components/chip/AGENTS.md

@@ -0,0 +1,113 @@
+# Chip
+
+An interactive pill — a filter that is on or off, a tag, or a token that can be
+removed. Compound root plus `Chip.Label`, `Chip.StartContent`, `Chip.EndContent`
+and `Chip.CloseButton`.
+
+`import { Chip } from "@delacour/react-native-ui/chip";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/chip` |
+| `chip.tsx` | Root + the `Object.assign` compound surface |
+| `chip-label.tsx` | `Chip.Label` |
+| `chip-start-content.tsx` | `Chip.StartContent` |
+| `chip-end-content.tsx` | `Chip.EndContent` |
+| `chip-close-button.tsx` | `Chip.CloseButton`, the remove pressable |
+| `chip.context.tsx` | `ChipContext`, `useChip()`, `useChipContext()`, `useChipPart()` |
+| `chip.types.ts` | Prop types shared by two or more parts |
+| `chip.variants.ts` | Pure `tv()` slots, the foreground map, hit slops, `resolveChipMode` / `resolveChipSurface` / `resolveChipForegroundToken` — no RN imports |
+| `chip.variants.test.ts` | |
+
+## Design
+
+- **What a chip does is read from its props, never from a `type` flag.**
+  `resolveChipMode` returns `static`, `button` or `toggle`. No handler is a tag,
+  rendered as a plain `View` — a detector under every tag in a list of fifty
+  would announce each as a button with no action, the same reason
+  [`Badge`](../badge/AGENTS.md) stays inert. `onPress` or `onLongPress` is a
+  button. **Any** selection prop — `isSelected` even when `false`,
+  `defaultSelected`, `onSelectedChange` — is a toggle, and it outranks a bare
+  press handler, because a chip with an on state that is announced as a plain
+  button leaves a screen-reader user unable to tell which chips are on. A
+  toggle still calls `onPress` after flipping.
+- **Selection is announced as `selected`, with the `button` role.** That is the
+  native idiom for a filter on both platforms — VoiceOver reads "Selected",
+  TalkBack "selected" — and it matches what a system segmented filter reports.
+  `checkbox` would promise a box that is not drawn. A caller's own
+  `accessibilityState` is merged under it, and `Pressable` merges `disabled` on
+  top.
+- **Controlled or uncontrolled, through `useControllableState`**, the same hook
+  and the same prop shape as [`Checkbox`](../checkbox/AGENTS.md):
+  `isSelected` / `defaultSelected` / `onSelectedChange`. A toggle ticks a
+  `selection` haptic by default; a button plays none, as a badge does. Pass
+  `haptic` to override either.
+- **Tone is Badge's, not a copy of it.** `CHIP_COLORS` and `CHIP_SIZES` *are*
+  `BADGE_COLORS` and `BADGE_SIZES`, and the resting entries of
+  `CHIP_FOREGROUND_TOKEN` are Badge's own objects. The class strings in
+  `chipVariants` are restated (Tailwind's scanner is static, so a class has to
+  appear literally somewhere), and a test pins every resting cell's `bg-*`,
+  `border-*` and label colour to the badge of the same variant and colour. A
+  soft `success` chip beside a soft `success` badge is one shade by
+  construction.
+- **Two resting variants, `soft` and `outline`.** `solid` is what selection
+  paints, so a resting solid chip would read as already on; `ghost` has neither
+  fill nor border, so there is no edge to aim at. `soft` is the default.
+- **Selection is a surface, not a modifier.** `CHIP_SURFACES` is the two resting
+  variants plus `selected`, and a selected chip looks the same whichever it rests
+  on — a solid fill and matching border in its colour. The `isSelected`
+  compound variants sit after the resting ones, so tailwind-merge lets them win.
+- **A selected `default` chip inverts** to `bg-foreground` / `text-background`.
+  Badge's solid default is `secondary`, which this theme sets a hair from
+  `muted` — the soft default — so a selected default chip would look unselected.
+  A test asserts all eighteen surface-and-colour cells are distinct.
+- **The border is reserved in every state.** A chip toggles in place inside a
+  wrapping row; a box that grew two points on selection would reflow every chip
+  after it. `overflow-hidden` keeps the pressed fade inside the capsule.
+- **Roomier than a badge, and still never a height.** A chip is aimed at and a
+  badge is only read, so each size pads at least as generously as the badge of
+  that size — a test asserts it. There is no `h-*`, so the label grows with OS
+  font scaling. The icon step is Badge's, so a glyph moves between the two
+  without changing size.
+- **Hit slop is vertical and capped at four points.** Chips wrap with `gap-2`;
+  slop past half that gap reaches into the neighbouring row and makes a tap
+  between two chips ambiguous. `CHIP_HIT_SLOP` is never horizontal for the same
+  reason. The close glyph gets `CHIP_CLOSE_HIT_SLOP` on every side instead — it
+  is 14–18 points, and its slop only reaches into its own chip's padding.
+- **`onClose` is its own pressable, never a mode of the root.** The remove
+  control is a `Chip.CloseButton` composed in last, so its tap is claimed by the
+  inner detector and never also toggles the chip. It presses with `fade` —
+  a spring on a glyph that small reads as a jitter — and inherits the current
+  surface's colour, so it turns with the label on selection.
+- **On a pressable chip, removal is an accessibility action, not a second
+  element.** iOS folds every descendant of an accessible view into one element,
+  so a close control inside a button or toggle chip was unreachable by swipe and
+  its label was read as part of the chip's — "React Native, Remove React
+  Native". `resolveChipCloseExposure` decides: a static chip leaves the close
+  control as its own element; a pressable one hides it
+  (`accessibilityElementsHidden`, `no-hide-descendants`) and adds a `remove`
+  action, labelled by `closeAccessibilityLabel`, that calls `onClose` —
+  VoiceOver's Actions rotor, TalkBack's actions menu. A caller's own
+  `accessibilityActions` are kept beside it.
+- **`closeTestID` reaches the composed close control.** The root's own `testID`
+  names the chip; the close part is a separate pressable with no id of its own
+  unless the root forwards one, so a flow or test could only find it by its label.
+  `closeTestID` is named like `closeAccessibilityLabel`, the other prop the root
+  passes through to it.
+- **`self-start` is Badge's, and beside a taller sibling in a row it top-aligns
+  the chip.** It is what keeps a chip content-sized in a column, which is the
+  common case; in a `flex-row items-center` holding something taller — a
+  `Switch` — pass `className="self-center"`, which tailwind-merge lets win. The
+  playground's `controlled-and-uncontrolled` demo does exactly this.
+- **Icons are composed, never passed as props.** The root wraps its subtree in an
+  `IconDefaultsProvider` and a `TextClassProvider` resolved from the *current*
+  surface, so a bare `<Icon>` or `<Text>` follows the chip into and out of
+  selection. `useChip()` exposes `isSelected` for a custom child that needs more.
+- **String children** are wrapped in a `Chip.Label` automatically, consecutive
+  strings collapsing into one — the same rule as [`Badge`](../badge/AGENTS.md).
+- **No group, yet.** Single- and multi-select filter rows are composed from
+  controlled chips (the playground's `filter-row` demo). A `Chip.Group` owning
+  the value, as `Checkbox.Group` does, is the obvious next step once a second
+  caller needs it.

package/src/components/chip/chip-close-button.tsx

@@ -0,0 +1,48 @@
+import type { ReactElement } from "react";
+import { IconCrossSmall } from "../../icons/central";
+import { Icon } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { useChipPart } from "./chip.context";
+import { CHIP_CLOSE_HIT_SLOP, chipVariants } from "./chip.variants";
+
+export type ChipCloseButtonProps = Omit<PressableProps, "asChild" | "busy" | "children" | "disabled">;
+
+/**
+ * The chip's trailing remove control.
+ *
+ * A pressable of its own rather than a mode of the root, which is what keeps a
+ * removal from also toggling the chip or firing its `onPress`: the two gestures
+ * belong to two detectors, and the inner one claims the tap.
+ *
+ * The root composes one in whenever `onClose` is set, so reach for this by hand
+ * only to place it somewhere other than last.
+ *
+ * The glyph is left bare: it inherits the chip's icon size and its current
+ * surface's colour from the root's `IconDefaultsProvider`, so it turns with the
+ * label when the chip is selected. `CHIP_CLOSE_HIT_SLOP` grows a 14–18 point
+ * glyph into something a thumb can find.
+ */
+export function ChipCloseButton({
+	accessibilityLabel = "Remove",
+	className,
+	feedback = "fade",
+	hitSlop,
+	...props
+}: ChipCloseButtonProps): ReactElement {
+	const { size, isDisabled } = useChipPart("Chip.CloseButton");
+
+	return (
+		<Pressable
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole="button"
+			className={chipVariants({ size }).closeButton({ className })}
+			disabled={isDisabled}
+			feedback={feedback}
+			hitSlop={hitSlop ?? CHIP_CLOSE_HIT_SLOP[size]}
+			{...props}
+		>
+			<Icon icon={IconCrossSmall} />
+		</Pressable>
+	);
+}
+ChipCloseButton.displayName = "DelacourUI.Chip.CloseButton";

package/src/components/chip/chip-end-content.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ChipSlotProps } from "./chip.types";
+import { chipVariants } from "./chip.variants";
+
+/**
+ * A centred wrapper for trailing content that is not an `Icon` — a count.
+ *
+ * An `Icon` needs no wrapper: it inherits the chip's icon size and its
+ * surface's colour from the root's `IconDefaultsProvider`.
+ */
+export function ChipEndContent({ className, ...props }: ChipSlotProps): ReactElement {
+	return <View className={chipVariants().endContent({ className })} {...props} />;
+}
+ChipEndContent.displayName = "DelacourUI.Chip.EndContent";

package/src/components/chip/chip-label.tsx

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import type { TextProps } from "react-native";
+import { Text } from "../text";
+import { useChipPart } from "./chip.context";
+import { chipVariants } from "./chip.variants";
+
+export type ChipLabelProps = TextProps & { className?: string };
+
+/**
+ * The chip's text.
+ *
+ * Reads the chip's variant, colour and selected state itself, so an
+ * icon-plus-text chip changes colour on selection without the caller threading
+ * anything through: a React Native `View` does not cascade colour to a `Text`
+ * descendant, so a colour set on the root would be lost.
+ */
+export function ChipLabel({ className, ...props }: ChipLabelProps): ReactElement {
+	const { variant, color, size, isSelected } = useChipPart("Chip.Label");
+	return <Text className={chipVariants({ color, isSelected, size, variant }).label({ className })} {...props} />;
+}
+ChipLabel.displayName = "DelacourUI.Chip.Label";

package/src/components/chip/chip-start-content.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ChipSlotProps } from "./chip.types";
+import { chipVariants } from "./chip.variants";
+
+/**
+ * A centred wrapper for leading content that is not an `Icon` — an avatar, a
+ * status dot.
+ *
+ * An `Icon` needs no wrapper: it inherits the chip's icon size and its
+ * surface's colour from the root's `IconDefaultsProvider`.
+ */
+export function ChipStartContent({ className, ...props }: ChipSlotProps): ReactElement {
+	return <View className={chipVariants().startContent({ className })} {...props} />;
+}
+ChipStartContent.displayName = "DelacourUI.Chip.StartContent";

package/src/components/chip/chip.context.tsx

@@ -0,0 +1,66 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { ChipColor, ChipSize, ChipVariant } from "./chip.variants";
+
+export type ChipContextValue = {
+	/** Size of the chip. */
+	size: ChipSize;
+	/** How the chip is painted while unselected. */
+	variant: ChipVariant;
+	/** What the chip means. */
+	color: ChipColor;
+	/** Whether the chip is selected. Always `false` for a chip that cannot be. */
+	isSelected: boolean;
+	/** Whether the chip is disabled. */
+	isDisabled: boolean;
+};
+
+const ChipContext = createContext<ChipContextValue | null>(null);
+
+/**
+ * Supplies the enclosing chip's variant, colour, size and state to its subtree.
+ *
+ * Lives in its own module, importing nothing but `chip.variants`, so a part can
+ * read it without importing `./chip`. That import would close a cycle, and Metro
+ * serves a partially initialised module for a cycle — leaving the context
+ * `undefined` at import time and red-boxing the app on a cold start.
+ */
+export function ChipProvider({ value, children }: { value: ChipContextValue; children: ReactNode }): ReactElement {
+	return <ChipContext value={value}>{children}</ChipContext>;
+}
+ChipProvider.displayName = "DelacourUI.Chip.Provider";
+
+/** The enclosing chip's context, or null outside a `<Chip>`. */
+export function useChipContext(): ChipContextValue | null {
+	return use(ChipContext);
+}
+
+/**
+ * Reads the enclosing chip's variant, colour, size and state.
+ *
+ * Lets a custom child restyle itself when the chip is selected without the chip
+ * passing props down through every slot. Throws outside a `<Chip>` — use
+ * {@link useChipContext} where the enclosing chip is optional.
+ */
+export function useChip(): ChipContextValue {
+	const context = useChipContext();
+	if (!context) {
+		throw new Error("useChip must be called inside a <Chip>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing chip's context, for a compound part that cannot work without
+ * one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useChip}, whose error message names the hook rather than
+ * a part.
+ */
+export function useChipPart(component: string): ChipContextValue {
+	const context = useChipContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Chip>.`);
+	}
+	return context;
+}

package/src/components/chip/chip.tsx

@@ -0,0 +1,268 @@
+import { Children, type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { type AccessibilityActionEvent, View } from "react-native";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { TextClassProvider } from "../text/text.context";
+import { type ChipContextValue, ChipProvider } from "./chip.context";
+import {
+	CHIP_HIT_SLOP,
+	type ChipColor,
+	type ChipSize,
+	type ChipVariant,
+	chipVariants,
+	resolveChipCloseExposure,
+	resolveChipForegroundToken,
+	resolveChipMode,
+} from "./chip.variants";
+import { ChipCloseButton } from "./chip-close-button";
+import { ChipEndContent } from "./chip-end-content";
+import { ChipLabel } from "./chip-label";
+import { ChipStartContent } from "./chip-start-content";
+
+export type ChipProps = Omit<PressableProps, "asChild" | "busy" | "children" | "disabled"> & {
+	/** How the chip is painted while unselected. */
+	variant?: ChipVariant;
+	/** What the chip means. Also the fill it takes when selected. */
+	color?: ChipColor;
+	size?: ChipSize;
+	/**
+	 * Controlled selected state. Setting it — even to `false` — makes the chip a
+	 * toggle, announced with its state; a tap reports the flip through
+	 * `onSelectedChange`.
+	 */
+	isSelected?: boolean;
+	/** Starting selected state while uncontrolled. Also makes the chip a toggle. */
+	defaultSelected?: boolean;
+	onSelectedChange?: (isSelected: boolean) => void;
+	isDisabled?: boolean;
+	/** Composes a trailing remove control in. Its press never toggles the chip or reaches `onPress`. */
+	onClose?: () => void;
+	/** Name a screen reader gives the remove control. Defaults to `Remove`. */
+	closeAccessibilityLabel?: string;
+	/** `testID` for the remove control, so a test or automation can press it. */
+	closeTestID?: string;
+	children?: ReactNode;
+};
+
+function ChipRoot({
+	variant = "soft",
+	color = "default",
+	size = "md",
+	isSelected,
+	defaultSelected,
+	onSelectedChange,
+	isDisabled = false,
+	onClose,
+	closeAccessibilityLabel,
+	closeTestID,
+	onPress,
+	onLongPress,
+	haptic,
+	feedback = "scale",
+	pressedScale,
+	pressedOpacity,
+	accessibilityState,
+	accessibilityActions,
+	onAccessibilityAction,
+	className,
+	children,
+	...props
+}: ChipProps): ReactElement {
+	const mode = resolveChipMode({ defaultSelected, isSelected, onLongPress, onPress, onSelectedChange });
+	const closeExposure = resolveChipCloseExposure({ hasClose: onClose !== undefined, mode });
+
+	const [ownSelected, setSelected] = useControllableState({
+		defaultValue: defaultSelected ?? false,
+		onChange: onSelectedChange,
+		value: isSelected,
+	});
+	const selected = mode === "toggle" && ownSelected;
+
+	const handlePress = useCallback(() => {
+		if (mode === "toggle") setSelected(!selected);
+		onPress?.();
+	}, [mode, onPress, selected, setSelected]);
+
+	const context = useMemo<ChipContextValue>(
+		() => ({ color, isDisabled, isSelected: selected, size, variant }),
+		[color, isDisabled, selected, size, variant]
+	);
+
+	const slots = chipVariants({ color, isDisabled, isSelected: selected, size, variant });
+
+	// Icons composed into the chip adopt these unless told otherwise, and turn
+	// with the label when the chip is selected.
+	const iconClassName = slots.icon();
+	const foregroundToken = resolveChipForegroundToken({ color, isSelected: selected, variant });
+	const iconDefaults = useMemo(
+		() => ({ className: iconClassName, color: foregroundToken }),
+		[iconClassName, foregroundToken]
+	);
+
+	const content = useMemo(() => wrapTextChildren(children), [children]);
+	const rootClassName = slots.root({ className });
+
+	// Inside a pressable chip the close control is folded into the chip's own
+	// accessibility element, so it is hidden there and offered as the `remove`
+	// action below instead — see `resolveChipCloseExposure`.
+	const closeHidden = closeExposure === "action";
+	const inner = (
+		<IconDefaultsProvider value={iconDefaults}>
+			<TextClassProvider value={slots.label()}>
+				{content}
+				{onClose ? (
+					<ChipCloseButton
+						accessibilityElementsHidden={closeHidden}
+						accessible={!closeHidden}
+						accessibilityLabel={closeAccessibilityLabel}
+						importantForAccessibility={closeHidden ? "no-hide-descendants" : "auto"}
+						onPress={onClose}
+						testID={closeTestID}
+					/>
+				) : null}
+			</TextClassProvider>
+		</IconDefaultsProvider>
+	);
+
+	const actions =
+		closeExposure === "action"
+			? [...(accessibilityActions ?? []), { label: closeAccessibilityLabel ?? "Remove", name: "remove" }]
+			: accessibilityActions;
+
+	const handleAccessibilityAction = (event: AccessibilityActionEvent) => {
+		if (closeExposure === "action" && event.nativeEvent.actionName === "remove" && !isDisabled) {
+			onClose?.();
+			return;
+		}
+		onAccessibilityAction?.(event);
+	};
+
+	// A chip with nothing to do stays a plain box — see `resolveChipMode`.
+	if (mode === "static") {
+		return (
+			<ChipProvider value={context}>
+				<View
+					accessibilityActions={accessibilityActions}
+					className={rootClassName}
+					onAccessibilityAction={onAccessibilityAction}
+					{...props}
+				>
+					{inner}
+				</View>
+			</ChipProvider>
+		);
+	}
+
+	// A toggle reports `selected`, which VoiceOver reads as "Selected" and
+	// TalkBack as "selected" — the native idiom for a filter — and a plain
+	// button reports nothing extra. Pressable merges `disabled` in on top.
+	const state = mode === "toggle" ? { ...accessibilityState, selected } : accessibilityState;
+
+	return (
+		<ChipProvider value={context}>
+			<Pressable
+				accessibilityActions={actions}
+				accessibilityRole="button"
+				accessibilityState={state}
+				className={rootClassName}
+				disabled={isDisabled}
+				feedback={feedback}
+				haptic={haptic ?? (mode === "toggle" ? "selection" : false)}
+				hitSlop={CHIP_HIT_SLOP[size]}
+				onAccessibilityAction={handleAccessibilityAction}
+				onLongPress={onLongPress}
+				onPress={handlePress}
+				pressedOpacity={pressedOpacity}
+				pressedScale={pressedScale}
+				{...props}
+			>
+				{inner}
+			</Pressable>
+		</ChipProvider>
+	);
+}
+
+/**
+ * Wraps bare text children in a `Chip.Label`.
+ *
+ * React Native cannot render a string outside a `<Text>`, so `<Chip>Design</Chip>`
+ * would otherwise crash. Consecutive strings and numbers are collected into a
+ * single label rather than one each — `{count} open` is one piece of text, and
+ * wrapping the parts separately would space them apart by the chip's gap.
+ */
+function wrapTextChildren(children: ReactNode): ReactNode {
+	const items = Children.toArray(children);
+	const output: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		output.push(<ChipLabel key={`label-${output.length}`}>{run.join("")}</ChipLabel>);
+		run = [];
+	};
+
+	for (const child of items) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output;
+}
+
+/**
+ * An interactive pill — a filter that is on or off, a tag, or a token that can
+ * be removed.
+ *
+ * What it does is decided by the props it is given, never by a `type` flag:
+ *
+ * - **Nothing** — a tag. A plain `View`, not announced as a control.
+ * - **`onPress` / `onLongPress`** — a button.
+ * - **`isSelected`, `defaultSelected` or `onSelectedChange`** — a filter. A tap
+ *   flips the state, a `selection` haptic ticks, and a screen reader hears
+ *   whether it is selected. Controlled or uncontrolled, like `Checkbox`.
+ * - **`onClose`** — adds a trailing remove control, a pressable of its own, so
+ *   removing a chip never also toggles it. Combines with any of the above; on
+ *   a pressable chip a screen reader reaches it as a `remove` action.
+ *
+ * Shares Badge's `color` and `size` axes and its tones: an unselected chip is
+ * painted exactly as the badge of the same `variant` and `color`. Selection
+ * replaces that with a solid fill in the chip's colour, and a selected
+ * `default` chip inverts. The border is reserved in every state, so selecting a
+ * chip never reflows the row it sits in.
+ *
+ * Icons are composed in, not passed as props. Anything in the subtree inherits
+ * the chip's icon size and its current surface's colour, and follows it when
+ * the chip is selected.
+ *
+ * @example
+ * <Chip color="success">Shipped</Chip>
+ *
+ * @example
+ * const [open, setOpen] = useState(false);
+ * <Chip isSelected={open} onSelectedChange={setOpen}>
+ *   <Icon icon={IconFilter} />
+ *   <Chip.Label>Open only</Chip.Label>
+ * </Chip>
+ *
+ * @example
+ * <Chip onClose={() => remove(tag)} variant="outline">
+ *   {tag}
+ * </Chip>
+ */
+export const Chip = Object.assign(ChipRoot, {
+	/** The chip's text. Picks its colour and type scale from the chip's variant, colour, size and selection. */
+	Label: ChipLabel,
+	/** A centred wrapper for leading content that is not an `Icon` — an avatar, a status dot. */
+	StartContent: ChipStartContent,
+	/** A centred wrapper for trailing content that is not an `Icon` — a count. */
+	EndContent: ChipEndContent,
+	/** The trailing remove control. Composed in automatically whenever `onClose` is set. */
+	CloseButton: ChipCloseButton,
+	displayName: "DelacourUI.Chip",
+});

package/src/components/chip/chip.types.ts

@@ -0,0 +1,10 @@
+import type { ViewProps } from "react-native";
+
+/**
+ * The shape of a chip's leading and trailing slots.
+ *
+ * Shared by `Chip.StartContent` and `Chip.EndContent`, which are identical apart
+ * from where the root places them, so it lives in a leaf rather than in one of
+ * the two files arbitrarily.
+ */
+export type ChipSlotProps = ViewProps & { className?: string };