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

package/src/components/empty-state/empty-state.tsx

@@ -0,0 +1,84 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { type EmptyStateContextValue, EmptyStateProvider } from "./empty-state.context";
+import { type EmptyStateSize, type EmptyStateVariant, emptyStateVariants } from "./empty-state.variants";
+import { EmptyStateContent } from "./empty-state-content";
+import { EmptyStateDescription } from "./empty-state-description";
+import { EmptyStateHeader } from "./empty-state-header";
+import { EmptyStateMedia } from "./empty-state-media";
+import { EmptyStateTitle } from "./empty-state-title";
+
+export type EmptyStateProps = ViewProps & {
+	/** `default` grows into its parent; `card` is a self-contained dashed block. */
+	variant?: EmptyStateVariant;
+	/** Drives the padding, both gaps, the media, the glyph and both type scales. */
+	size?: EmptyStateSize;
+	className?: string;
+	children?: ReactNode;
+};
+
+function EmptyStateRoot({
+	variant = "default",
+	size = "md",
+	className,
+	children,
+	...props
+}: EmptyStateProps): ReactElement {
+	const context = useMemo<EmptyStateContextValue>(() => ({ size, variant }), [size, variant]);
+
+	return (
+		<EmptyStateProvider value={context}>
+			<View className={emptyStateVariants({ size, variant }).root({ className })} {...props}>
+				{children}
+			</View>
+		</EmptyStateProvider>
+	);
+}
+
+/**
+ * A placeholder for a list or a screen with nothing in it yet: a picture, a
+ * title, a line of explanation, and the action that fixes it.
+ *
+ * `size` and `variant` reach the parts through context, so the title picks its
+ * own type scale and a bare `Icon` in `EmptyState.Media` its own size and
+ * colour. Actions are composed — put a `Button` in `EmptyState.Content`.
+ *
+ * `default` grows to fill a bounded parent and centres itself there, without
+ * collapsing inside a `ScrollView`. `card` is a dashed block for an empty
+ * section sitting beside populated ones.
+ *
+ * @example
+ * <EmptyState>
+ *   <EmptyState.Header>
+ *     <EmptyState.Media variant="icon">
+ *       <Icon icon={IconInbox} />
+ *     </EmptyState.Media>
+ *     <EmptyState.Title>No messages</EmptyState.Title>
+ *     <EmptyState.Description>New conversations will show up here.</EmptyState.Description>
+ *   </EmptyState.Header>
+ *   <EmptyState.Content>
+ *     <Button onPress={compose}>New message</Button>
+ *   </EmptyState.Content>
+ * </EmptyState>
+ *
+ * @example
+ * <EmptyState size="sm" variant="card">
+ *   <EmptyState.Header>
+ *     <EmptyState.Title>No results</EmptyState.Title>
+ *     <EmptyState.Description>Try a different search.</EmptyState.Description>
+ *   </EmptyState.Header>
+ * </EmptyState>
+ */
+export const EmptyState = Object.assign(EmptyStateRoot, {
+	/** The centred column holding the media, the title and the description. */
+	Header: EmptyStateHeader,
+	/** The picture above the title. A bare `Icon` inside it inherits size and colour; `variant="icon"` tints a box behind it. */
+	Media: EmptyStateMedia,
+	/** The heading, announced as a header. Carries its own colour — a `View` cannot cascade one to a `Text`. */
+	Title: EmptyStateTitle,
+	/** The supporting line under the title, a step down in scale and on the muted token. */
+	Description: EmptyStateDescription,
+	/** The action slot under the header: a centred row that wraps. */
+	Content: EmptyStateContent,
+	displayName: "DelacourUI.EmptyState",
+});

package/src/components/empty-state/empty-state.types.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import type { TextProps, ViewProps } from "react-native";
+
+/**
+ * The shape of the header and content slots.
+ *
+ * Shared by `EmptyState.Header` and `EmptyState.Content`, and extended by
+ * `EmptyState.Media`, so it lives in a leaf rather than in one of them
+ * arbitrarily.
+ */
+export type EmptyStateSlotProps = ViewProps & { className?: string; children?: ReactNode };
+
+/** The shape of the two text parts, `EmptyState.Title` and `EmptyState.Description`. */
+export type EmptyStateTextProps = TextProps & { className?: string };

package/src/components/empty-state/empty-state.variants.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import { ICON_SIZE_TOKENS } from "../../styles/tokens";
+import {
+	EMPTY_STATE_MEDIA_FOREGROUND_TOKEN,
+	EMPTY_STATE_MEDIA_VARIANTS,
+	EMPTY_STATE_SIZES,
+	EMPTY_STATE_VARIANTS,
+	emptyStateVariants,
+} from "./empty-state.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** Tailwind's spacing step a class string sets a utility from, e.g. `p` or `gap`. */
+function step(cls: string, utility: string): number {
+	return Number(cls.match(new RegExp(`\\b${utility}-([\\d.]+)\\b`))?.[1]);
+}
+
+/**
+ * Position of a class string's font size on the type scale, largest last.
+ *
+ * Compared by step rather than points so a retune in `tokens.css` does not
+ * break a test that only means "bigger".
+ */
+const TEXT_SCALE = ["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl"] as const;
+function textStep(cls: string): number {
+	return TEXT_SCALE.findIndex((name) => new RegExp(`\\b${name}\\b`).test(cls));
+}
+
+/** Position of a slot's `size-icon-*` token on the shared icon scale. */
+function iconStep(cls: string): number {
+	const token = cls.match(/\bsize-(icon-[\w-]+)\b/)?.[1];
+	return ICON_SIZE_TOKENS.indexOf(token as (typeof ICON_SIZE_TOKENS)[number]);
+}
+
+/** Every slot that is a `View` — none of them may carry a text colour. */
+const VIEW_SLOTS = ["root", "header", "media", "content"] as const;
+
+/** A strictly ascending, all-distinct scale. */
+function expectAscending(scale: readonly number[]): void {
+	expect(scale.every(Number.isFinite)).toBe(true);
+	expect(new Set(scale).size).toBe(scale.length);
+	expect([...scale]).toEqual([...scale].sort((a, b) => a - b));
+}
+
+describe("the theme.css reader", () => {
+	test("finds both variants", () => {
+		expect(LIGHT.size).toBeGreaterThan(0);
+		expect(DARK.size).toBeGreaterThan(0);
+	});
+});
+
+describe("emptyStateVariants root slot", () => {
+	test("defaults to the md default variant", () => {
+		const cls = emptyStateVariants().root();
+		expect(cls).toContain("bg-transparent");
+		expect(cls).toContain(`p-${step(emptyStateVariants({ size: "md" }).root(), "p")}`);
+	});
+
+	test("centres its content on both axes, at every variant", () => {
+		for (const variant of EMPTY_STATE_VARIANTS) {
+			const cls = emptyStateVariants({ variant }).root();
+			expect(cls).toContain("items-center");
+			expect(cls).toContain("justify-center");
+		}
+	});
+
+	// `grow`, never `flex-1`. `flex-1` is a zero basis, so inside a ScrollView's
+	// content container — which has no height to grow into — the empty state
+	// collapses to nothing. `grow` keeps the content height as a floor and fills
+	// whatever a bounded parent has spare.
+	test("the default variant grows into its parent without a zero basis", () => {
+		const cls = emptyStateVariants({ variant: "default" }).root();
+		expect(cls).toMatch(/\bgrow\b/);
+		expect(cls).not.toMatch(/\bflex-1\b/);
+	});
+
+	test("the card variant is a card-shaped surface with a dashed border", () => {
+		const cls = emptyStateVariants({ variant: "card" }).root();
+		expect(cls).toContain("bg-card");
+		expect(cls).toContain("border-border");
+		expect(cls).toContain("border-dashed");
+		expect(cls).not.toMatch(/\bgrow\b/);
+	});
+
+	// The border is in the box on both variants, so switching to `card` changes
+	// a colour and not the layout.
+	test("reserves the border on every variant", () => {
+		for (const variant of EMPTY_STATE_VARIANTS) {
+			expect(emptyStateVariants({ variant }).root()).toMatch(/\bborder\b/);
+		}
+		expect(emptyStateVariants({ variant: "default" }).root()).toContain("border-transparent");
+	});
+
+	test("a card is rounded-lg at md and lg, and steps down to rounded-md at sm", () => {
+		expect(emptyStateVariants({ variant: "card", size: "sm" }).root()).toContain("rounded-md");
+		expect(emptyStateVariants({ variant: "card", size: "md" }).root()).toContain("rounded-lg");
+		expect(emptyStateVariants({ variant: "card", size: "lg" }).root()).toContain("rounded-lg");
+	});
+
+	test("gives the two variants distinct treatments", () => {
+		const seen = new Set(EMPTY_STATE_VARIANTS.map((variant) => emptyStateVariants({ variant }).root()));
+		expect(seen.size).toBe(EMPTY_STATE_VARIANTS.length);
+	});
+
+	test("merges an incoming className last", () => {
+		const cls = emptyStateVariants({ variant: "card" }).root({ className: "bg-muted" });
+		expect(cls).toContain("bg-muted");
+		expect(cls).not.toContain("bg-card");
+	});
+});
+
+describe("emptyStateVariants size axis", () => {
+	test("scales padding and the gap between header and content together", () => {
+		const roots = EMPTY_STATE_SIZES.map((size) => emptyStateVariants({ size }).root());
+		expectAscending(roots.map((cls) => step(cls, "p")));
+		expectAscending(roots.map((cls) => step(cls, "gap")));
+	});
+
+	test("scales the header's own gap", () => {
+		expectAscending(EMPTY_STATE_SIZES.map((size) => step(emptyStateVariants({ size }).header(), "gap")));
+	});
+
+	test("scales the title and description type together, title always the larger", () => {
+		const titles = EMPTY_STATE_SIZES.map((size) => textStep(emptyStateVariants({ size }).title()));
+		const descriptions = EMPTY_STATE_SIZES.map((size) => textStep(emptyStateVariants({ size }).description()));
+
+		expect(titles.every((index) => index >= 0)).toBe(true);
+		expect(descriptions.every((index) => index >= 0)).toBe(true);
+		expect([...titles]).toEqual([...titles].sort((a, b) => a - b));
+		expect([...descriptions]).toEqual([...descriptions].sort((a, b) => a - b));
+		expect(new Set(titles).size).toBe(EMPTY_STATE_SIZES.length);
+
+		for (const [index, title] of titles.entries()) {
+			expect(title).toBeGreaterThan(descriptions[index] ?? Number.POSITIVE_INFINITY);
+		}
+	});
+
+	// Padding, never a height. A fixed height clips the description at a large
+	// accessibility font step instead of letting the block grow.
+	test("takes no height", () => {
+		for (const size of EMPTY_STATE_SIZES) {
+			expect(emptyStateVariants({ size }).root()).not.toMatch(/\bh-/);
+		}
+	});
+});
+
+describe("emptyStateVariants header slot", () => {
+	test("is a centred column", () => {
+		const cls = emptyStateVariants().header();
+		expect(cls).toContain("items-center");
+		expect(cls).not.toContain("flex-row");
+	});
+});
+
+describe("emptyStateVariants media slot", () => {
+	test("the icon media is a tinted, rounded square that scales with size", () => {
+		const boxes = EMPTY_STATE_SIZES.map((size) => emptyStateVariants({ size, media: "icon" }).media());
+		for (const cls of boxes) {
+			expect(cls).toContain("bg-muted");
+			expect(cls).toMatch(/\brounded-/);
+		}
+		expectAscending(boxes.map((cls) => step(cls, "size")));
+	});
+
+	test("the default media paints nothing and takes no size, so an illustration sizes itself", () => {
+		for (const size of EMPTY_STATE_SIZES) {
+			const cls = emptyStateVariants({ size, media: "default" }).media();
+			expect(cls).not.toMatch(/\bbg-/);
+			expect(cls).not.toMatch(/\bsize-/);
+		}
+	});
+
+	// A glyph in an empty state has to sit on the scale `Icon`, `Spinner` and
+	// `Button` share rather than carry a private number.
+	test("gives every size a distinct icon token, increasing with it", () => {
+		for (const media of EMPTY_STATE_MEDIA_VARIANTS) {
+			const steps = EMPTY_STATE_SIZES.map((size) => iconStep(emptyStateVariants({ size, media }).mediaIcon()));
+			expect(steps.every((index) => index >= 0)).toBe(true);
+			expectAscending(steps);
+		}
+	});
+
+	// Media and title are one visual unit only if the glyph clears the title by
+	// more than the title clears its description.
+	test("sets the media apart from the title by more than the header gap", () => {
+		for (const size of EMPTY_STATE_SIZES) {
+			const slots = emptyStateVariants({ size });
+			expect(step(slots.media(), "mb")).toBeGreaterThan(0);
+		}
+	});
+});
+
+describe("text colour", () => {
+	test("lives on the title and description, never on a View slot", () => {
+		for (const variant of EMPTY_STATE_VARIANTS) {
+			for (const size of EMPTY_STATE_SIZES) {
+				const slots = emptyStateVariants({ variant, size });
+				for (const slot of VIEW_SLOTS) {
+					expect(slots[slot]()).not.toMatch(/\btext-(?!center\b)/);
+				}
+				expect(slots.title()).toContain("text-foreground");
+				expect(slots.description()).toContain("text-muted-foreground");
+			}
+		}
+	});
+
+	test("title and description are centred", () => {
+		const slots = emptyStateVariants();
+		expect(slots.title()).toContain("text-center");
+		expect(slots.description()).toContain("text-center");
+	});
+});
+
+describe("EMPTY_STATE_MEDIA_FOREGROUND_TOKEN", () => {
+	test("names a token for every media variant", () => {
+		for (const media of EMPTY_STATE_MEDIA_VARIANTS) {
+			expect(EMPTY_STATE_MEDIA_FOREGROUND_TOKEN[media]).toBeTruthy();
+		}
+	});
+
+	test("names only tokens both themes declare", () => {
+		for (const media of EMPTY_STATE_MEDIA_VARIANTS) {
+			const token = EMPTY_STATE_MEDIA_FOREGROUND_TOKEN[media];
+			expect(LIGHT.has(token)).toBe(true);
+			expect(DARK.has(token)).toBe(true);
+		}
+	});
+
+	// `muted-foreground` on `bg-muted` is two greys a step apart. The tinted box
+	// already says "decoration", so the glyph inside it takes full contrast.
+	test("draws the icon media's glyph at full contrast on its muted box", () => {
+		expect(EMPTY_STATE_MEDIA_FOREGROUND_TOKEN.icon).toBe("foreground");
+	});
+});
+
+describe("emptyStateVariants content slot", () => {
+	test("lays actions out in a centred, wrapping row", () => {
+		const cls = emptyStateVariants().content();
+		expect(cls).toContain("flex-row");
+		expect(cls).toContain("flex-wrap");
+		expect(cls).toContain("justify-center");
+	});
+});

package/src/components/empty-state/empty-state.variants.ts

@@ -0,0 +1,132 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** How the block sits on the screen: filling its parent, or as a self-contained card. */
+export const EMPTY_STATE_VARIANTS = ["default", "card"] as const;
+
+export const EMPTY_STATE_SIZES = ["sm", "md", "lg"] as const;
+
+/** What `EmptyState.Media` draws behind its content: nothing, or a tinted box for a glyph. */
+export const EMPTY_STATE_MEDIA_VARIANTS = ["default", "icon"] as const;
+
+export type EmptyStateVariant = (typeof EMPTY_STATE_VARIANTS)[number];
+export type EmptyStateSize = (typeof EMPTY_STATE_SIZES)[number];
+export type EmptyStateMediaVariant = (typeof EMPTY_STATE_MEDIA_VARIANTS)[number];
+
+/**
+ * Theme token an `Icon` composed into `EmptyState.Media` inherits.
+ *
+ * A colour that reaches an SVG paint prop cannot be a class, so it travels as a
+ * token through `IconDefaultsProvider` — the same route `Button` and `ListGroup`
+ * use. A bare glyph is `muted-foreground`, because an empty state's picture is
+ * decoration and must not outweigh the title. Inside the tinted box it takes
+ * full contrast: `muted-foreground` on `bg-muted` is two greys a step apart.
+ */
+export const EMPTY_STATE_MEDIA_FOREGROUND_TOKEN: Record<EmptyStateMediaVariant, string> = {
+	default: "muted-foreground",
+	icon: "foreground",
+};
+
+/**
+ * Styling for every part of an empty state.
+ *
+ * One slotted `tv()` because size is not decoration here: it drives the
+ * padding, both gaps, the media box, the glyph inside it and both type scales.
+ * Those belong on one axis rather than in seven numbers that drift apart.
+ *
+ * `default` uses `grow`, never `flex-1`. `flex-1` is a zero flex basis, so inside
+ * a `ScrollView`'s content container — which has no height to grow into — the
+ * block would collapse to nothing. `grow` keeps its content height as a floor
+ * and fills whatever spare height a bounded parent has, which is what "fills its
+ * container" has to mean on both.
+ *
+ * `card` is a dashed outline on the card surface. The dash is the conventional
+ * mark of a slot waiting for content, and it keeps an embedded empty state from
+ * reading as one more populated card beside real ones. Its corner follows the
+ * card step (`rounded-lg`), stepping down to `rounded-md` at `sm` the way
+ * `ListGroup` and `Accordion` do. The border is reserved on both variants, so
+ * switching to `card` changes a colour rather than the layout.
+ *
+ * A size is padding, never a height. The description respects OS font scaling,
+ * and a fixed height would clip it at a large accessibility step.
+ *
+ * The glyph steps with size on the shared icon scale, the same three steps
+ * inside the tinted box and out of it — the scale tops out at `icon-2xl`, so a
+ * bare glyph a step larger would leave `md` and `lg` identical.
+ *
+ * The media keeps a bottom margin on top of the header's gap, so the picture
+ * clears the title by more than the title clears its description — the two
+ * lines read as one unit and the glyph as something above them.
+ *
+ * No `View` slot carries a `text-*` utility: a React Native `View` does not
+ * cascade colour to a `Text` descendant, so colour lives on `title` and
+ * `description`, and a glyph's colour on {@link EMPTY_STATE_MEDIA_FOREGROUND_TOKEN}.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const emptyStateVariants = tv({
+	slots: {
+		root: "w-full items-center justify-center border",
+		header: "w-full max-w-sm items-center",
+		media: "items-center justify-center",
+		/** Edge length an `Icon` composed into the media inherits. */
+		mediaIcon: "",
+		title: "text-center font-semibold text-foreground",
+		description: "text-center text-muted-foreground",
+		content: "w-full max-w-sm flex-row flex-wrap items-center justify-center",
+	},
+	variants: {
+		variant: {
+			default: { root: "grow border-transparent bg-transparent" },
+			card: { root: "border-dashed border-border bg-card" },
+		},
+		size: {
+			sm: {
+				mediaIcon: "size-icon-lg",
+				root: "gap-4 p-4",
+				header: "gap-1",
+				media: "mb-2",
+				title: "text-base",
+				description: "text-sm",
+				content: "gap-2",
+			},
+			md: {
+				mediaIcon: "size-icon-xl",
+				root: "gap-5 p-6",
+				header: "gap-1.5",
+				media: "mb-3",
+				title: "text-lg",
+				description: "text-sm",
+				content: "gap-2.5",
+			},
+			lg: {
+				mediaIcon: "size-icon-2xl",
+				root: "gap-6 p-8",
+				header: "gap-2",
+				media: "mb-4",
+				title: "text-xl",
+				description: "text-base",
+				content: "gap-3",
+			},
+		},
+		media: {
+			default: {},
+			icon: { media: "bg-muted" },
+		},
+	},
+	compoundVariants: [
+		{ variant: "card", size: "sm", class: { root: "rounded-md" } },
+		{ variant: "card", size: ["md", "lg"], class: { root: "rounded-lg" } },
+		{ media: "icon", size: "sm", class: { media: "size-10 rounded-md" } },
+		{ media: "icon", size: "md", class: { media: "size-12 rounded-lg" } },
+		{ media: "icon", size: "lg", class: { media: "size-16 rounded-xl" } },
+	],
+	defaultVariants: {
+		variant: "default",
+		size: "md",
+		media: "default",
+	},
+});
+
+export type EmptyStateVariantProps = VariantProps<typeof emptyStateVariants>;

package/src/components/empty-state/index.ts

@@ -0,0 +1,20 @@
+export { EmptyState, type EmptyStateProps } from "./empty-state";
+export {
+	type EmptyStateContextValue,
+	EmptyStateProvider,
+	useEmptyState,
+	useEmptyStateContext,
+} from "./empty-state.context";
+export type { EmptyStateSlotProps, EmptyStateTextProps } from "./empty-state.types";
+export {
+	EMPTY_STATE_MEDIA_FOREGROUND_TOKEN,
+	EMPTY_STATE_MEDIA_VARIANTS,
+	EMPTY_STATE_SIZES,
+	EMPTY_STATE_VARIANTS,
+	type EmptyStateMediaVariant,
+	type EmptyStateSize,
+	type EmptyStateVariant,
+	type EmptyStateVariantProps,
+	emptyStateVariants,
+} from "./empty-state.variants";
+export type { EmptyStateMediaProps } from "./empty-state-media";

package/src/components/fab/AGENTS.md

@@ -0,0 +1,119 @@
+# Fab
+
+One primary action floating over the screen it belongs to — "New note" over a
+list — and, as `Fab.Group`, a dial of related actions that unfold out of it.
+Compound root plus `Fab.Label`, `Fab.Group` and `Fab.Action`.
+
+`import { Fab } from "@delacour/react-native-ui/fab";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/fab` |
+| `fab.tsx` | Root + the `Object.assign` compound surface |
+| `fab-label.tsx` | `Fab.Label` |
+| `fab-group.tsx` | `Fab.Group` — the trigger, the scrim and the dial's one spring |
+| `fab-action.tsx` | `Fab.Action` — one dial entry: a small round button and a label chip |
+| `fab.context.tsx` | `FabContext`, `FabGroupContext` and the per-action index context, with their hooks |
+| `fab.types.ts` | `FabSharedProps` — the axes `Fab` and `Fab.Group` both take |
+| `fab.variants.ts` | The slotted `tv()` and the pure resolvers, no RN imports |
+| `fab.variants.test.ts` | |
+
+## Design
+
+- **Sizes**: `sm`, `md` (default), `lg` — 44, 56 and 64pt, from
+  `--spacing-fab-*`. **Variants**: `primary` (default), `secondary`, `surface`,
+  `destructive`. **Placements**: `bottom-start`, `bottom-center`, `bottom-end`.
+- **The footprint is its own token, not the button's.** A fab sits over
+  content rather than in a row of controls, so it is a step larger than any
+  button, and a form retuning `--spacing-button-*` must not move the one thing
+  floating over its list. Declared in both `tokens.css` and theme.css's
+  `@variant native` block, per the package rule, and registered in
+  `styles/tokens.ts`; `tokens.test.ts` holds the floor at 44pt.
+- **Icons on `Fab` are composed; on `Fab.Group` and `Fab.Action` they are a
+  prop.** `Fab` matches `Button`: it publishes its icon step (`sm` → `icon-md`,
+  `md`/`lg` → `icon-lg`, `resolveFabIconSize`) and its variant's foreground
+  through `IconDefaultsProvider`, so a bare `<Icon />` comes out right. The
+  group renders and **rotates** its trigger glyph, and each action draws two
+  things — a round button and a label chip — from one icon and one label, so
+  both take an `icon` component and own how it is drawn.
+- **It casts a shadow, and nothing else in the kit does.** `shadow-lg` on the
+  fab and on each dial button. A fab is the one control floating above the
+  content; flat, it reads as a sticker on the list. The root carries no
+  `overflow-hidden`, which would clip that shadow on Android.
+- **`placement` pins; omitting it leaves the fab in flow.** Pinned, the fab sits
+  in a `pointerEvents="box-none"` box at `bottom = offset + insets.bottom` and
+  `start`/`end = offset` — logical edges, so RTL flips with no code.
+  `isSafeAreaAware` (default `true`) is what adds the inset; the inset is read
+  from `SafeAreaInsetsContext` directly, so a fab outside a safe-area provider
+  gets `0` rather than a throw.
+- **Centre spans the row instead of using `alignSelf`.** An absolute child's
+  `alignSelf` is read on the parent's *cross* axis — horizontal only in a
+  column — so a fab written into a `flex-row` would have centred vertically.
+  `resolveFabPlacementStyle` returns `start: 0, end: 0, alignItems: "center"`
+  instead. That is the one shape this resolver returns that the spec sketch
+  listed as `alignSelf`.
+- **One spring drives the dial.** `Fab.Group` holds a single `progress` shared
+  value, `withSpring` to 0 or 1 with a little overshoot. Each action derives
+  its own window on the UI thread with `resolveDialProgress` —
+  `clamp((open − i·0.08) / (1 − (n−1)·0.08), 0, 1)`, index 0 nearest the
+  trigger — so there are no per-action timers, and closing halfway through
+  opening simply runs the same cascade backwards. The window is floored so a
+  stagger too wide for the count degrades to a step, never a NaN.
+- **Actions are unmounted while closed, not hidden.** They mount in the render
+  that opens the dial and unmount from the close animation's `finished`
+  callback, so a screen reader cannot walk into invisible buttons. A reopen
+  mid-close cancels that animation, `finished` is false, and nothing unmounts.
+- **The glyph turns 45°, plus → cross**, read off the same spring and clamped
+  so the overshoot does not wobble it. `isRotatedOnOpen={false}` holds it still
+  for a glyph that is not a plus.
+- **Pressing an action runs it, then closes the dial.** The label chip presses
+  too — a finger aims at the words — but it is hidden from assistive technology
+  so a screen reader meets each action once, by its button.
+- **The chip sits on the side facing into the screen.** `resolveLabelSide`:
+  left of the button at `bottom-end`, right at `bottom-start`, above at
+  `bottom-center`. Each action's button sits in an anchor as wide as the
+  trigger (`w-fab-*`), so the small buttons share the trigger's centre line.
+- **The group is a layer, so write it in the screen's root container.** It
+  renders an `absolute inset-0` box holding the scrim and the pinned dial, and
+  covers whatever its parent is. Inside a scroll view's content it would cover
+  the content box, not the screen. The layer is `box-none`, so while closed it
+  takes no touches.
+- **The scrim is `bg-overlay`, faded by the spring.** The token carries its own
+  alpha, so the fade runs 0 → 1 and lands on the theme's overlay. Tapping it
+  closes; it is a button labelled "Close".
+- **Android back closes an open dial**, through a `BackHandler` subscription
+  that exists only while the dial is open.
+- **`testID` lands on what a finger presses.** `Fab.Group`'s goes on the
+  trigger, not the layer or the anchor — the layer covers the whole parent and
+  the anchor's centre is inside the dial once it opens, so neither is something
+  a test can tap. `Fab.Action`'s goes on its round button.
+- **`isOpen` / `defaultOpen` / `onOpenChange`** through `useControllableState`.
+- **Haptics are off by default.** `haptic` on `Fab` plays on press; on
+  `Fab.Group` it plays on the trigger and on every action.
+- **Reduced motion fades the dial in 150ms** with no rise, scale or stagger —
+  the dial still appears, because appearing is the information. The glyph
+  still turns, on the same timing.
+- **A11y.** Every fab and action is a `button`. The group trigger carries
+  `accessibilityState={{ expanded }}` and a required `accessibilityLabel`; the
+  layer is `accessibilityViewIsModal` while open. A round `Fab` with no
+  `accessibilityLabel` warns in development — there is no text to fall back on.
+- **The group trigger extends with `label` while closed.** Open, it is a
+  circle again: the label names what the dial is for, and the cross that
+  replaces the plus is the only thing the trigger does then.
+- **`Fab.Group` also takes `offset` and `isSafeAreaAware`**, which the spec
+  sketch listed only on `Fab`. Both are on `FabSharedProps`, so a group pinned
+  above a tab bar can clear it the same way a lone fab does.
+
+## Out of scope
+
+- **A glass material.** It needs a native peer the catalog does not carry.
+- **`layout="menu"` and `layout="native"`** — a menu panel out of the fab. A
+  follow-up once `Menu` has merged, reusing its rows.
+- **A blurred scrim.** It needs `expo-blur`, which is not a peer.
+- **Design-system styles do not retune the fab.** `@delacour/design-system`'s
+  `STYLES` write `spacing-fab-*` as the same 44/56/64 under every style
+  (`LIBRARY_FAB` in `styles.ts`), so a style switch moves the buttons and leaves
+  the fab where it is. Give a style its own numbers there when one needs a
+  different fab.