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

package/src/components/label/label.variants.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test";
+import { fieldVariants, resolveFieldTextColor } from "../field/field.variants";
+import { TEXT_COLORS } from "../text/text.variants";
+import {
+	LABEL_REQUIRED_MARK,
+	LABEL_REQUIRED_MARK_COLOR,
+	labelText,
+	labelVariants,
+	resolveLabelAccessibilityLabel,
+	resolveLabelColor,
+} from "./label.variants";
+
+/**
+ * A slot's class string, with `tv`'s empty-slot `undefined` flattened.
+ *
+ * Both slots are handed to a `Text` and carry state only, so they are empty most
+ * of the time — and a bare `not.toMatch()` throws on `undefined` rather than
+ * passing.
+ */
+function cls(value: string | undefined): string {
+	return value ?? "";
+}
+
+const SLOTS = ["root", "requiredMark"] as const;
+
+describe("the slots", () => {
+	// The type scale belongs to `Text.Label`. A size or a weight here would be a
+	// second definition of it that could drift from the preset.
+	test("restate no type scale in any state", () => {
+		for (const isDisabled of [false, true]) {
+			for (const isInvalid of [false, true]) {
+				const slots = labelVariants({ isDisabled, isInvalid });
+				for (const slot of SLOTS) {
+					expect(cls(slots[slot]())).not.toMatch(/\btext-(xs|sm|base|lg|xl|2xl|3xl)\b/);
+					expect(cls(slots[slot]())).not.toMatch(/\bfont-(normal|medium|semibold|bold)\b/);
+				}
+			}
+		}
+	});
+
+	// Colour rides `Text`'s own axis, so a caller's `color` beats it through the
+	// same channel rather than through a tailwind-merge race.
+	test("carry no colour, since that rides the preset's own axis", () => {
+		for (const isInvalid of [false, true]) {
+			const slots = labelVariants({ isInvalid });
+			for (const slot of SLOTS) {
+				expect(cls(slots[slot]())).not.toMatch(/\btext-\w+-?\w*\b/);
+			}
+		}
+	});
+
+	test("merge an incoming className last", () => {
+		expect(labelVariants({ isDisabled: true }).root({ className: "opacity-80" })).toContain("opacity-80");
+		expect(labelVariants({ isDisabled: true }).root({ className: "opacity-80" })).not.toContain("opacity-50");
+		expect(labelVariants().requiredMark({ className: "ml-1" })).toContain("ml-1");
+	});
+});
+
+describe("a disabled label", () => {
+	test("fades", () => {
+		expect(cls(labelVariants({ isDisabled: true }).root())).toContain("opacity-50");
+		expect(cls(labelVariants({ isDisabled: false }).root())).not.toContain("opacity-50");
+	});
+
+	// The mark is a nested run inside the label's own text, so the root's opacity
+	// already reaches it. Fading it again would square the fade.
+	test("does not fade the required mark a second time", () => {
+		expect(cls(labelVariants({ isDisabled: true }).requiredMark())).not.toContain("opacity");
+	});
+
+	test("is enabled by default", () => {
+		expect(labelVariants().root()).toBe(labelVariants({ isDisabled: false }).root());
+	});
+});
+
+describe("resolveLabelColor", () => {
+	test("turns destructive only while invalid", () => {
+		expect(resolveLabelColor(true)).toBe("destructive");
+		expect(resolveLabelColor(false)).toBeUndefined();
+	});
+
+	// `undefined` means "leave the preset's own colour alone" — `Text`'s colour
+	// axis emits nothing when it is not named.
+	test("names a colour Text actually has", () => {
+		expect(TEXT_COLORS).toContain(resolveLabelColor(true) ?? "default");
+	});
+});
+
+describe("the required mark", () => {
+	test("is an asterisk", () => {
+		expect(LABEL_REQUIRED_MARK).toBe("*");
+	});
+
+	// Required is a warning about what the form will refuse, so it is drawn in
+	// the colour of the refusal whether or not the field is currently wrong.
+	test("is destructive, and a colour Text has", () => {
+		expect(LABEL_REQUIRED_MARK_COLOR).toBe("destructive");
+		expect(TEXT_COLORS).toContain(LABEL_REQUIRED_MARK_COLOR);
+	});
+});
+
+describe("labelText", () => {
+	test("reads a string or a number", () => {
+		expect(labelText("Email")).toBe("Email");
+		expect(labelText(42)).toBe("42");
+	});
+
+	test("joins an array of strings, the shape `{name} address` compiles to", () => {
+		expect(labelText(["Work", " ", "email"])).toBe("Work email");
+		expect(labelText(["Line ", 2])).toBe("Line 2");
+	});
+
+	// The holes a conditional child leaves behind are not text.
+	test("skips null, undefined and booleans inside an array", () => {
+		expect(labelText(["Email", null, undefined, false, true])).toBe("Email");
+	});
+
+	// An element could be anything — an icon, a link — and guessing at its text
+	// would put words in a screen reader's mouth the caller never wrote.
+	test("gives up on anything it cannot read as text", () => {
+		expect(labelText({ type: "Icon" })).toBeUndefined();
+		expect(labelText(["Email", { type: "Icon" }])).toBeUndefined();
+		expect(labelText(undefined)).toBeUndefined();
+		expect(labelText(null)).toBeUndefined();
+	});
+
+	test("treats empty text as nothing to read", () => {
+		expect(labelText("")).toBeUndefined();
+		expect(labelText(["", null])).toBeUndefined();
+	});
+});
+
+describe("resolveLabelAccessibilityLabel", () => {
+	// A nested asterisk reads as "star" — so a required label is announced by
+	// what it means instead of by its punctuation.
+	test("reads a required label as required, not as an asterisk", () => {
+		expect(resolveLabelAccessibilityLabel({ children: "Email", isRequired: true })).toBe("Email, required");
+	});
+
+	test("leaves an optional label to the text itself", () => {
+		expect(resolveLabelAccessibilityLabel({ children: "Email", isRequired: false })).toBeUndefined();
+	});
+
+	test("lets the caller's own label win", () => {
+		expect(
+			resolveLabelAccessibilityLabel({ accessibilityLabel: "Work email", children: "Email", isRequired: true })
+		).toBe("Work email");
+		expect(
+			resolveLabelAccessibilityLabel({ accessibilityLabel: "Work email", children: "Email", isRequired: false })
+		).toBe("Work email");
+	});
+
+	// With children it cannot read, the text stays whatever the platform makes
+	// of it rather than becoming a bare "required" with the name dropped.
+	test("says nothing when it cannot read the children", () => {
+		expect(resolveLabelAccessibilityLabel({ children: { type: "Icon" }, isRequired: true })).toBeUndefined();
+	});
+});
+
+// `Field.Label` is the field-aware counterpart of `Label`, styled from
+// `fieldVariants`. A label in a field and a label outside one must not read as
+// two different components, so the decision written twice is held together by a
+// test rather than by a comment hoping it stays so.
+describe("parity with Field", () => {
+	test("colours the label the way Field's resolver does", () => {
+		for (const isInvalid of [false, true]) {
+			expect(resolveLabelColor(isInvalid)).toBe(resolveFieldTextColor("label", isInvalid));
+		}
+	});
+
+	test("fades the label the way Field's slot does", () => {
+		for (const isDisabled of [false, true]) {
+			expect(cls(labelVariants({ isDisabled }).root())).toBe(cls(fieldVariants({ isDisabled }).label()));
+		}
+	});
+});

package/src/components/label/label.variants.ts

@@ -0,0 +1,123 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { TextColor } from "../text/text.variants";
+
+/** What a required label appends. */
+export const LABEL_REQUIRED_MARK = "*";
+
+/**
+ * The required mark's colour, in every state.
+ *
+ * Required is a warning about what the form will refuse, so it is drawn in the
+ * colour of that refusal whether or not the value is wrong right now.
+ */
+export const LABEL_REQUIRED_MARK_COLOR: TextColor = "destructive";
+
+/**
+ * State for a form label and the required mark inside it.
+ *
+ * Two slots because the mark is a second `Text` nested in the label's own, not
+ * because either carries a style of its own: **no slot here holds a type scale
+ * or a colour.** The label renders `Text.Label` and passes a colour through
+ * {@link resolveLabelColor}, so the scale lives in exactly one place — a
+ * `text-sm font-medium` written here would be a second definition of
+ * `Text.Label` that could drift from it. The mark inherits that scale by
+ * nesting.
+ *
+ * Only the root fades. The mark is a run inside the root's text, so the root's
+ * opacity already reaches it; fading it again would square the fade.
+ *
+ * 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 labelVariants = tv({
+	slots: {
+		root: "",
+		requiredMark: "",
+	},
+	variants: {
+		// The empty `false` branches are load-bearing typing, not placeholders.
+		// `tv` derives the prop type from the declared keys, so a map with only
+		// `true` types the prop as `true` rather than `boolean`. See the note in
+		// button.variants.ts.
+		isInvalid: { true: {}, false: {} },
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	defaultVariants: {
+		isInvalid: false,
+		isDisabled: false,
+	},
+});
+
+/**
+ * The `Text` colour a label takes.
+ *
+ * Returning `undefined` is meaningful rather than lazy: `Text`'s `color` axis
+ * emits nothing when it is not named, so the label falls through to
+ * `Text.Label`'s own `text-foreground` without this module knowing which token
+ * the preset chose.
+ *
+ * Pure, so the matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveLabelColor(isInvalid: boolean): TextColor | undefined {
+	return isInvalid ? "destructive" : undefined;
+}
+
+/**
+ * The plain text a label's children spell, or `undefined` when they are
+ * anything but text.
+ *
+ * Strings and numbers are read, and an array of them is joined — that is what
+ * `{name} address` compiles to. The `null`, `undefined` and booleans a
+ * conditional child leaves behind are skipped. An element is not guessed at: it
+ * could be an icon or a link, and inventing its words would put something in a
+ * screen reader's mouth the caller never wrote.
+ *
+ * Typed on `unknown` rather than `ReactNode` so this module takes not even a
+ * type import from React, which is what keeps it reachable from `bun test`.
+ */
+export function labelText(children: unknown): string | undefined {
+	const parts = Array.isArray(children) ? children : [children];
+	let text = "";
+
+	for (const part of parts) {
+		if (part === null || part === undefined || typeof part === "boolean") continue;
+		if (typeof part === "string" || typeof part === "number") {
+			text += String(part);
+			continue;
+		}
+		return undefined;
+	}
+
+	return text === "" ? undefined : text;
+}
+
+/**
+ * What a screen reader announces for a label.
+ *
+ * The caller's own `accessibilityLabel` always wins. Otherwise a required label
+ * whose children are text is announced as `"Email, required"`: the mark is a
+ * nested `Text`, and React Native reads a `Text` and its nested runs as one
+ * string, so without this VoiceOver says "Email, star". An optional label, or
+ * one whose children cannot be read as text, returns `undefined` and is left to
+ * the platform.
+ *
+ * Pure, so the matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveLabelAccessibilityLabel({
+	accessibilityLabel,
+	children,
+	isRequired,
+}: {
+	accessibilityLabel?: string;
+	children: unknown;
+	isRequired: boolean;
+}): string | undefined {
+	if (accessibilityLabel !== undefined) return accessibilityLabel;
+	if (!isRequired) return undefined;
+
+	const text = labelText(children);
+	return text === undefined ? undefined : `${text}, required`;
+}
+
+export type LabelVariantProps = VariantProps<typeof labelVariants>;

package/src/components/menu/AGENTS.md

@@ -0,0 +1,176 @@
+# Menu
+
+A list of **verbs** dropped from a control that exists to open it — a ⋯ button,
+a toolbar item. Rename, duplicate, share, delete. A menu is not a select: its
+rows run actions, they never become the trigger's value. Compound root plus
+`Menu.Trigger`, `Menu.Content`, `Menu.Background`, `Menu.Label`, `Menu.Item`,
+`Menu.CheckboxItem`, `Menu.RadioGroup`, `Menu.RadioItem`, `Menu.Separator`,
+`Menu.Sub`, `Menu.SubTrigger` and `Menu.SubContent`.
+
+`import { Menu } from "@delacour/react-native-ui/menu";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/menu` |
+| `menu.tsx` | Root — `useMenuRootValue` into `MenuRootProvider`; the `Object.assign` |
+| `menu-trigger.tsx` | `Menu.Trigger` — measures itself and toggles; `asChild` donates the press |
+| `menu-content.tsx` | `Menu.Content` — the transparent `Modal`, the outside-tap layer, the placed and animated panel, the scroller |
+| `menu-background.tsx` | `Menu.Background` — the `bg-popover` surface behind the scroller |
+| `menu-label.tsx` | `Menu.Label` — a section heading |
+| `menu-item.tsx` | `MenuRow`, the row every row is built on, and `Menu.Item` |
+| `menu-checkbox-item.tsx` | `Menu.CheckboxItem` |
+| `menu-radio-group.tsx` | `Menu.RadioGroup` — holds the value |
+| `menu-radio-item.tsx` | `Menu.RadioItem` |
+| `menu-separator.tsx` | `Menu.Separator` — `Separator` with `my-1` |
+| `menu-sub.tsx` | `Menu.Sub` — the submenu's open state, `progress` and measured height |
+| `menu-sub-trigger.tsx` | `Menu.SubTrigger` — the row with the turning chevron |
+| `menu-sub-content.tsx` | `Menu.SubContent` — the measured clip |
+| `menu.context.tsx` | The menu, submenu and radio-group contexts; `useMenu`, `useMenuRootValue`, `MenuRootProvider` |
+| `menu.types.ts` | `MenuItemProps`, shared by every row |
+| `menu.variants.ts` | The slotted `tv()`, the constants and the pure resolvers — no RN imports |
+| `menu.variants.test.ts` | Placement (flip, cap, clamp, RTL, the zero-size anchor), width, close rules, accessibility, tokens |
+
+## The panel
+
+- **It is a minimal anchored panel built here, not a Popover.** There is no
+  Popover in the package yet. `Menu.Content` renders inside a transparent RN
+  `Modal` — top-most layer, Android back through `onRequestClose`, screen-reader
+  containment — so it needs no new peer. **When Popover lands, Menu.Content moves
+  onto it and `resolveMenuPlacement` moves with it.** The resolver is exported
+  for exactly that.
+- **Placement takes a rect, never a ref.** `resolveMenuPlacement({ anchor, content,
+  window, insets, placement, align, offset, isRTL })` places against
+  `{ x, y, width, height }`, so a zero-size point — ContextMenu's long-press —
+  goes through the same arithmetic with no special case, and a test proves it.
+- **Flip, then cap.** The requested side wins when the content fits; otherwise
+  the other side if it fits there; otherwise the larger side, and `maxHeight`
+  caps it so the rows scroll. Room is measured inside the safe area plus an 8pt
+  margin, and the panel is clamped horizontally inside the same bounds. `align`
+  start and end swap under RTL.
+- **Measure, place, show.** The panel's first frame is at opacity 0; the
+  scroller's `onContentSizeChange` reports the rows' height, placement runs with
+  it, and only then does the enter start — there is no jump.
+- **The side is locked for the visit.** A submenu expanding mid-visit must not
+  flip the panel under the finger. A panel above the anchor is positioned by
+  its **bottom** edge (`MenuPlacementResult.bottom`), so it grows upward, away
+  from the anchor, with nothing re-placed; past the cap the rows scroll.
+- **Its surface is `bg-popover`, never `bg-overlay`.** `overlay` is the
+  translucent scrim colour (`oklch(0 0 0 / 45%)`); a panel in it is a
+  see-through card. `hasScrim` (ContextMenu sets it) draws `bg-overlay` behind
+  the panel, fading with it.
+- **The shadow is on an outer layer with no clip.** iOS clips a shadow to a
+  clipping view's bounds, so `panel` casts `shadow-lg` and the inner `content`
+  slot carries the corner, the hairline and `overflow-hidden`.
+- **A caller's `Menu.Background` is lifted out by type** and drawn behind the
+  scroller, so it stays put while the rows scroll. The default is drawn when
+  there is none.
+- **Enter 160ms, exit 120ms**, opacity with a 0.96 scale from the anchor's side.
+  React Native has no animatable transform origin on both platforms, so
+  `resolveMenuOrigin` approximates it with a translate that falls to zero as the
+  panel arrives. Under reduced motion it is opacity alone — the panel still
+  appears, so the information is not lost. The `Modal` unmounts when the exit's
+  timing finishes; a reopen mid-exit cancels it and runs the enter instead.
+- **Gesture Handler needs its own root inside a `Modal`.** On Android a `Modal`
+  is a separate window the app's root view cannot see into, so every tap in the
+  panel would be dead. `Menu.Content` wraps its tree in a `GestureHandlerRootView`.
+
+## Rows
+
+- **One row, `MenuRow`, under every row kind.** `Menu.Item`, `CheckboxItem`,
+  `RadioItem` and `SubTrigger` are `MenuRow` with a `kind`, a leading override
+  and an `accessibilityState`. Four hand-rolled rows would be four press fills
+  that drift.
+- **The press fill is the row's background.** An absolute `bg-accent` layer
+  (`bg-destructive-soft` on a destructive row) fades in over 90ms and out over
+  160ms while the row dips to 0.98 — one shared value for both. There is no
+  wash or ripple on top. A row is built on its own Gesture Handler tap rather
+  than `Pressable`, because `Pressable` owns its `pressed` value privately and
+  the fill has to read it.
+- **Under reduced motion the fill snaps and the scale does not run.** The
+  scale is movement and goes; the fill is colour, and it is what says the tap
+  landed, so it stays — instantly.
+- **A tap that travels is a scroll.** The tap fails past 10pt
+  (`MENU_TAP_MAX_DISTANCE`), so a long menu scrolls without choosing the row the
+  finger started on.
+- **Rows take `ViewProps`, not `PressableProps`.** The spec sketched
+  `Omit<PressableProps, …>`, but a row ignores `feedback`, `asChild`, `busy` and
+  the rest; a type that accepts props it drops is a quiet bug. `isDisabled` is
+  the row's own.
+- **Close rules live in one resolver.** `resolveCloseOnSelect(kind, explicit?)`:
+  item and radio close, checkbox and sub-trigger stay open; an explicit
+  `isClosedOnSelect` wins. `resolveRadioNext` pins that re-choosing a selected
+  radio keeps it — a radio never clears.
+- **A checkbox's tick and a radio's mark take the leading icon column**, so the
+  labels of every row line up; an `icon` on those rows moves to the trailing
+  edge. `isInset` reserves the same column on a plain row, and on a `Menu.Label`.
+- **The icon column is 18pt, `size-icon-md`.** The spec named `size-icon-sm`,
+  which is 16pt in `tokens.css`; the 18pt it also named wins, since that is the
+  footprint `isInset` and the label's `ps-[42px]` (12 + 18 + 12) are built on.
+- **Haptics are the root's `haptic`, played on select**, from the tap's worklet,
+  and off by default.
+
+## Submenus
+
+- **They expand in place, never fly out.** A phone has no room beside the
+  panel, and a second layer over the first hides where the user came from.
+  `Menu.SubContent` is `Collapsible.Content`'s measured clip — restated, not
+  imported, so `delacour add menu` copies one folder — and `MENU_SUB_SPRING` is
+  `Collapsible`'s spring.
+- **The chevron turns 90° off the submenu's own `progress`**, so it and the
+  height cannot drift. Under RTL it is mirrored with `scaleX: -1` on a wrapper
+  view, so it points to the trailing edge and still turns downward; the
+  rotation lives on the inner view.
+- **Nothing on the JS thread reads `contentHeight.value`** — the accordion's
+  Release-build bug. "Measured" is React state.
+
+## State
+
+- **`isOpen` / `defaultOpen` / `onOpenChange` through `useControllableState`**,
+  in `useMenuRootValue`. `open(anchor?)` opens at a rect, or measures the
+  trigger first; `close()`; `toggle()`. Callbacks are ref-backed so the context
+  keeps its identity.
+- **A controlled open is measured too.** A parent flipping `isOpen` to `true`
+  without a trigger press still gets the trigger measured, by an effect that
+  tells such an open from one `open()` started.
+- **`Menu.Trigger asChild` donates the press**, `BottomSheet.Trigger`'s rule: a
+  `Button` wrapped in a pressable trigger would win the touch and the menu
+  would never open. The child gets `onPress`, the measured ref and the
+  accessibility props through `Slot`.
+
+## Accessibility
+
+- Content: `accessibilityRole="menu"`, `accessibilityViewIsModal`.
+- Rows: `accessibilityRole="menuitem"`; checkbox → `checked`, radio →
+  `selected`, sub-trigger → `expanded`, all → `disabled`. One source:
+  `resolveMenuItemAccessibility`, a discriminated union on `kind`.
+- Trigger: `accessibilityState={{ expanded }}`, hint "Opens a menu".
+- A closed submenu is out of the accessibility tree, not just clipped.
+
+## Reuse contract for ContextMenu
+
+ContextMenu renders this component's rows and panel rather than a copy:
+
+- **Import leaves, never `../menu`.** `../menu/menu-item` (`MenuRow`,
+  `MenuItem`), `../menu/menu-content`, `../menu/menu.context` and
+  `../menu/menu.variants` are each importable on their own. None imports
+  `./menu`, so no cycle can close (rule 3).
+- **Drive the state with your own anchor.** Build a value with
+  `useMenuRootValue(...)`, wrap your tree in `MenuRootProvider`, and call
+  `open({ x, y, width: 0, height: 0 })` from the long-press. Or pass
+  `anchor` straight to `Menu.Content`.
+- **`hasScrim`** tints the screen behind the panel; **`iconPlacement="trailing"`**
+  puts a row's icon at its end.
+- **`backdrop`** draws a node inside the `Modal`, over the scrim and behind the
+  panel, fading with them and taking no touches. A `Modal` covers everything,
+  so anything meant to show above the scrim — ContextMenu's lifted preview — has
+  to be inside it; outside, it would sit under the tint.
+
+## Out of scope
+
+- **`presentation="bottom-sheet"`.** Importing `../bottom-sheet` would force the
+  optional sheet engine and `react-native-teleport` on every Menu consumer. A
+  follow-up.
+- **Keyboard navigation and focus return on web.**
+- **Typeahead, and rows that open a second panel.**

package/src/components/menu/index.ts

@@ -0,0 +1,44 @@
+export { Menu, type MenuProps } from "./menu";
+export {
+	type MenuContextValue,
+	type MenuMeasurable,
+	MenuRootProvider,
+	type UseMenuRootValueOptions,
+	useMenu,
+	useMenuRootValue,
+} from "./menu.context";
+export type { MenuItemProps } from "./menu.types";
+export {
+	MENU_ALIGNS,
+	MENU_DEFAULT_MIN_WIDTH,
+	MENU_DEFAULT_OFFSET,
+	MENU_EDGE_MARGIN,
+	MENU_ITEM_VARIANTS,
+	MENU_PLACEMENTS,
+	MENU_RADIO_INDICATORS,
+	type MenuAlign,
+	type MenuAnchorRect,
+	type MenuInsets,
+	type MenuItemVariant,
+	type MenuPlacement,
+	type MenuPlacementInput,
+	type MenuPlacementResult,
+	type MenuRadioIndicator,
+	type MenuVariantProps,
+	menuVariants,
+	resolveCloseOnSelect,
+	resolveMenuPlacement,
+	resolveMenuWidth,
+	resolveRadioNext,
+} from "./menu.variants";
+export type { MenuBackgroundProps } from "./menu-background";
+export type { MenuCheckboxItemProps } from "./menu-checkbox-item";
+export type { MenuContentProps } from "./menu-content";
+export type { MenuLabelProps } from "./menu-label";
+export type { MenuRadioGroupProps } from "./menu-radio-group";
+export type { MenuRadioItemProps } from "./menu-radio-item";
+export type { MenuSeparatorProps } from "./menu-separator";
+export type { MenuSubProps } from "./menu-sub";
+export type { MenuSubContentProps } from "./menu-sub-content";
+export type { MenuSubTriggerProps } from "./menu-sub-trigger";
+export type { MenuTriggerProps } from "./menu-trigger";

package/src/components/menu/menu-background.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { menuVariants } from "./menu.variants";
+
+export type MenuBackgroundProps = ViewProps & { className?: string };
+
+/**
+ * The panel's surface: an absolute-fill layer in `bg-popover`, behind the rows.
+ *
+ * `Menu.Content` draws one by default. Pass your own as a child of
+ * `Menu.Content` to repaint it — the content lifts it out of the children and
+ * renders it outside the scroller, where it stays put while the rows scroll.
+ */
+export function MenuBackground({ className, ...props }: MenuBackgroundProps): ReactElement {
+	return <View className={menuVariants().background({ className })} pointerEvents="none" {...props} />;
+}
+MenuBackground.displayName = "DelacourUI.Menu.Background";

package/src/components/menu/menu-checkbox-item.tsx

@@ -0,0 +1,57 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { IconCheckmark1 } from "../../icons/central";
+import { Icon } from "../icon";
+import type { MenuItemProps } from "./menu.types";
+import { MENU_INDICATOR_TOKEN, menuVariants, resolveMenuItemAccessibility } from "./menu.variants";
+import { MenuRow } from "./menu-item";
+
+export type MenuCheckboxItemProps = Omit<MenuItemProps, "onSelect" | "isClosedOnSelect"> & {
+	isChecked?: boolean;
+	defaultChecked?: boolean;
+	onCheckedChange?: (isChecked: boolean) => void;
+	/** Whether choosing the row closes the menu. Default `false` — several are usually toggled in one visit. */
+	isClosedOnSelect?: boolean;
+};
+
+/**
+ * A row that toggles a setting, with a tick in the icon column while it is on.
+ *
+ * Stays open on select by default. The tick takes the leading column, so an
+ * `icon` moves to the row's end. Announced as `checked`.
+ *
+ * @example
+ * <Menu.CheckboxItem isChecked={showDone} onCheckedChange={setShowDone}>Completed</Menu.CheckboxItem>
+ */
+export function MenuCheckboxItem({
+	isChecked: isCheckedProp,
+	defaultChecked = false,
+	onCheckedChange,
+	isDisabled = false,
+	...props
+}: MenuCheckboxItemProps): ReactElement {
+	const [isChecked, setChecked] = useControllableState<boolean>({
+		defaultValue: defaultChecked,
+		onChange: onCheckedChange,
+		value: isCheckedProp,
+	});
+	const slots = menuVariants();
+
+	return (
+		<MenuRow
+			accessibilityState={resolveMenuItemAccessibility({ isChecked, isDisabled, kind: "checkbox" })}
+			isDisabled={isDisabled}
+			kind="checkbox"
+			leading={
+				<View className={slots.indicator()}>
+					{isChecked ? <Icon className={slots.itemIcon()} color={MENU_INDICATOR_TOKEN} icon={IconCheckmark1} /> : null}
+				</View>
+			}
+			onSelect={() => setChecked(!isChecked)}
+			{...props}
+			iconPlacement="trailing"
+		/>
+	);
+}
+MenuCheckboxItem.displayName = "DelacourUI.Menu.CheckboxItem";