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

package/src/components/button/button.context.tsx

@@ -76,6 +76,10 @@ export type ButtonGroupContextValue = {
 	isDisabled?: boolean;
 	/** Press treatment for members. Unset falls back to `fade` — see `resolveButtonFeedback`. */
 	feedback?: PressableFeedback;
+	/** Members join into one shape. False, each keeps its own corner and the run takes a gap. */
+	isAttached: boolean;
+	/** The group spans its parent. Horizontal members then split it — see `isStretched`. */
+	isFullWidth: boolean;
 };
 
 export type ButtonGroupItemContextValue = ButtonGroupContextValue & {
@@ -83,6 +87,12 @@ export type ButtonGroupItemContextValue = ButtonGroupContextValue & {
 	position: ButtonGroupPosition;
 	/** Overlap the member before it, so the shared edge is drawn once. */
 	isSeamed: boolean;
+	/**
+	 * Take an equal share of a full-width horizontal run — `flex-1 basis-0`.
+	 * A custom member that should split the run reads this; one that should
+	 * keep its content width ignores it, as `Button.Group.Text` does.
+	 */
+	isStretched: boolean;
 };
 
 const ButtonGroupContext = createContext<ButtonGroupContextValue | null>(null);

package/src/components/button/button.tsx

@@ -7,6 +7,7 @@ import { type ButtonContextValue, ButtonProvider, useButtonGroupItemContext } fr
 import {
 	BUTTON_FOREGROUND_TOKEN,
 	type ButtonLayout,
+	type ButtonMaterial,
 	type ButtonSize,
 	type ButtonSpinnerPlacement,
 	type ButtonVariant,
@@ -23,6 +24,8 @@ import { ButtonStartContent } from "./button-start-content";
 
 export type ButtonProps = Omit<PressableProps, "busy" | "children" | "disabled" | "pressedOpacity" | "pressedScale"> & {
 	variant?: ButtonVariant;
+	/** `flat` by default; `etched` sets a highlight into the fill's edge. */
+	material?: ButtonMaterial;
 	/** Height, label step, icon step, corner and padding on one axis. `icon-*` is a square. */
 	size?: ButtonSize;
 	isDisabled?: boolean;
@@ -37,6 +40,7 @@ export type ButtonProps = Omit<PressableProps, "busy" | "children" | "disabled"
 
 function ButtonRoot({
 	variant,
+	material = "flat",
 	size,
 	isDisabled,
 	isLoading = false,
@@ -74,6 +78,8 @@ function ButtonRoot({
 		isDisabled: resolvedIsDisabled,
 		isLoading,
 		isSeamed: item?.isSeamed ?? false,
+		isStretched: item?.isStretched ?? false,
+		material,
 		orientation: item?.orientation ?? "horizontal",
 		size: resolvedSize,
 		variant: resolvedVariant,
@@ -96,7 +102,7 @@ function ButtonRoot({
 				busy={isLoading}
 				className={slots.root({ className })}
 				disabled={resolvedIsDisabled}
-				feedback={resolveButtonFeedback(feedback, item?.feedback, item !== null)}
+				feedback={resolveButtonFeedback(feedback, item?.feedback, item !== null, item?.isAttached)}
 				{...props}
 			>
 				<IconDefaultsProvider value={iconDefaults}>

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

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { cn } from "../../lib/cn";
 import { BUTTON_RADIUS_TOKENS, ICON_SIZE_TOKENS } from "../../styles/tokens";
 import {
 	BUTTON_FOREGROUND_TOKEN,
@@ -7,6 +8,7 @@ import {
 	BUTTON_GROUP_SEPARATOR_ORIENTATION,
 	BUTTON_ICON_SIZES,
 	BUTTON_LABEL_SIZES,
+	BUTTON_MATERIALS,
 	BUTTON_SIZES,
 	BUTTON_SPINNER_PLACEMENTS,
 	BUTTON_VARIANTS,
@@ -16,6 +18,7 @@ import {
 	resolveButtonFeedback,
 	resolveButtonLayout,
 	resolveGroupedButtonSize,
+	resolveGroupMemberStretch,
 	resolveGroupPositions,
 	resolveGroupSeams,
 	resolveSpinnerSwapIndex,
@@ -809,3 +812,190 @@ describe("resolveGroupedButtonSize", () => {
 		}
 	});
 });
+
+describe("the etched button material", () => {
+	test("flat is the default and adds no shadow", () => {
+		for (const variant of BUTTON_VARIANTS) {
+			expect(buttonVariants({ variant }).root()).toBe(buttonVariants({ variant, material: "flat" }).root());
+			expect(buttonVariants({ variant }).root()).not.toMatch(/shadow/);
+		}
+	});
+
+	test("etched primary carries the white inset highlight", () => {
+		const cls = buttonVariants({ material: "etched", variant: "primary" }).root();
+		expect(cls).toContain("shadow-etched-primary");
+		expect(cls).not.toContain("shadow-etched ");
+	});
+
+	test("etched filled and outlined buttons carry the light and dark edge", () => {
+		for (const variant of ["secondary", "tertiary", "outline"] as const) {
+			const cls = buttonVariants({ material: "etched", variant }).root();
+			expect(cls).toContain("shadow-etched");
+			expect(cls).toContain("dark:shadow-etched-dark");
+		}
+	});
+
+	// A ghost has no surface to lift, and a destructive fill is a signal colour
+	// whose highlight would read as a second state.
+	test("ghost and destructive variants stay flat", () => {
+		for (const variant of ["ghost", "destructive", "destructive-soft"] as const) {
+			expect(buttonVariants({ material: "etched", variant }).root()).not.toMatch(/shadow/);
+		}
+	});
+
+	test("lists every material", () => {
+		expect(BUTTON_MATERIALS).toEqual(["flat", "etched"]);
+	});
+});
+
+describe("a detached group", () => {
+	test("places every member on its own", () => {
+		// `only` is the lone member's position and draws the lone button's corner,
+		// so a spaced run is a row of whole buttons rather than a joined shape with
+		// gaps punched in it.
+		expect(resolveGroupPositions([true, true, true], { isAttached: false })).toEqual(["only", "only", "only"]);
+		expect(resolveGroupPositions([true, false, true], { isAttached: false })).toEqual(["only", null, "only"]);
+	});
+
+	test("still skips a separator", () => {
+		expect(resolveGroupPositions([false, true, false], { isAttached: false })).toEqual([null, "only", null]);
+	});
+
+	test("joins by default", () => {
+		expect(resolveGroupPositions([true, true], { isAttached: true })).toEqual(["first", "last"]);
+		expect(resolveGroupPositions([true, true], {})).toEqual(["first", "last"]);
+	});
+
+	test("overlaps nothing", () => {
+		// There is no shared edge to draw once, and a point of overlap would eat
+		// into the gap instead.
+		for (const shape of SHAPES) {
+			expect(resolveGroupSeams(shape, { isAttached: false }).every((seamed) => !seamed)).toBe(true);
+		}
+		expect(resolveGroupSeams([true, true, true], { isAttached: true })).toEqual([false, true, true]);
+	});
+
+	test("draws each member's own corner", () => {
+		for (const size of BUTTON_SIZES) {
+			const step = size.startsWith("icon-") ? size.slice("icon-".length) : size;
+			const cls = buttonVariants({ groupPosition: "only", size }).root();
+			expect(cls).toContain(`rounded-button-${step}`);
+			expect(cls).not.toMatch(/\brounded-[sebt]-/);
+		}
+	});
+
+	test("spaces its members with a gap on either axis", () => {
+		for (const orientation of BUTTON_GROUP_ORIENTATIONS) {
+			expect(buttonVariants({ isAttached: false, orientation }).group()).toMatch(/\bgap-2\b/);
+		}
+	});
+
+	test("an attached group still holds no gap", () => {
+		for (const orientation of BUTTON_GROUP_ORIENTATIONS) {
+			expect(buttonVariants({ isAttached: true, orientation }).group()).not.toMatch(/\bgap-/);
+		}
+	});
+});
+
+describe("resolveButtonFeedback in a detached group", () => {
+	test("falls back to the lone button's scale", () => {
+		// Tearing a seam is impossible with no seam, so the group rung is dropped.
+		expect(resolveButtonFeedback(undefined, undefined, true, false)).toBe("scale");
+	});
+
+	test("still fades when attached", () => {
+		expect(resolveButtonFeedback(undefined, undefined, true, true)).toBe("fade");
+	});
+
+	test("defaults to attached, which is what a group is", () => {
+		expect(resolveButtonFeedback(undefined, undefined, true)).toBe("fade");
+	});
+
+	test("honours an explicit `none` either way", () => {
+		for (const isAttached of [true, false]) {
+			expect(resolveButtonFeedback("none", undefined, true, isAttached)).toBe("none");
+			expect(resolveButtonFeedback(undefined, "none", true, isAttached)).toBe("none");
+		}
+	});
+
+	test("still lets the group or the member name a treatment", () => {
+		expect(resolveButtonFeedback(undefined, "fade", true, false)).toBe("fade");
+		expect(resolveButtonFeedback("scale-fade", "fade", true, false)).toBe("scale-fade");
+	});
+});
+
+describe("a full-width group", () => {
+	test("spans its parent instead of hugging its content", () => {
+		const cls = buttonVariants({ isFullWidth: true, orientation: "horizontal" }).group();
+		expect(cls).toMatch(/\bw-full\b/);
+		expect(cls).toMatch(/\bself-stretch\b/);
+		expect(cls).not.toMatch(/\bself-start\b/);
+	});
+
+	test("fills the width when vertical too", () => {
+		const cls = buttonVariants({ isFullWidth: true, orientation: "vertical" }).group();
+		expect(cls).toMatch(/\bw-full\b/);
+		expect(cls).toMatch(/\bself-stretch\b/);
+	});
+
+	test("hugs its content by default", () => {
+		const cls = buttonVariants({ orientation: "horizontal" }).group();
+		expect(cls).toMatch(/\bself-start\b/);
+		expect(cls).not.toMatch(/\bw-full\b/);
+	});
+
+	test("keeps a gap when it is also detached", () => {
+		const cls = buttonVariants({ isAttached: false, isFullWidth: true }).group();
+		expect(cls).toMatch(/\bgap-2\b/);
+		expect(cls).toMatch(/\bw-full\b/);
+	});
+});
+
+describe("a stretched member", () => {
+	test("splits the run equally rather than by content", () => {
+		// `basis-0` is the half that matters: with `flex-1` alone Yoga shares out
+		// only the space left over, and the widths still follow the labels.
+		const cls = buttonVariants({ isStretched: true }).root();
+		expect(cls).toMatch(/\bflex-1\b/);
+		expect(cls).toMatch(/\bbasis-0\b/);
+	});
+
+	test("does not stretch by default", () => {
+		const cls = buttonVariants().root();
+		expect(cls).not.toMatch(/\bflex-1\b/);
+		expect(cls).not.toMatch(/\bbasis-0\b/);
+	});
+
+	test("yields to a caller's flex", () => {
+		const slot = buttonVariants({ isStretched: true }).root({ className: "flex-none" });
+		expect(slot).toMatch(/\bflex-none\b/);
+		expect(slot).not.toMatch(/\bflex-1\b/);
+		const merged = cn(buttonVariants({ isStretched: true }).root(), "flex-none");
+		expect(merged).toMatch(/\bflex-none\b/);
+		expect(merged).not.toMatch(/\bflex-1\b/);
+	});
+
+	test("keeps its own corner and height", () => {
+		const cls = buttonVariants({ groupPosition: "first", isStretched: true, size: "md" }).root();
+		expect(cls).toContain("h-button-md");
+		expect(cls).toContain("rounded-s-button-md");
+	});
+});
+
+describe("resolveGroupMemberStretch", () => {
+	test("stretches members of a full-width horizontal run", () => {
+		expect(resolveGroupMemberStretch({ isFullWidth: true, orientation: "horizontal" })).toBe(true);
+	});
+
+	test("leaves a vertical run to the cross axis it already stretches on", () => {
+		// `basis-0` on the main axis of a column with no definite height would
+		// collapse every member to nothing.
+		expect(resolveGroupMemberStretch({ isFullWidth: true, orientation: "vertical" })).toBe(false);
+	});
+
+	test("stretches nothing by default", () => {
+		for (const orientation of BUTTON_GROUP_ORIENTATIONS) {
+			expect(resolveGroupMemberStretch({ isFullWidth: false, orientation })).toBe(false);
+		}
+	});
+});

package/src/components/button/button.variants.ts

@@ -13,6 +13,14 @@ export const BUTTON_VARIANTS = [
 ] as const;
 
 /** Sizes that hold a label. Horizontal padding; the width comes from the content. */
+/**
+ * `flat` is the library default. `etched` sets the highlight into the fill's
+ * edge — a white inset top edge on `primary`, the light/dark edge on the quiet
+ * fills. Ghost and destructive buttons stay flat: a ghost has no surface to
+ * lift, and a signal colour does not take a second highlight.
+ */
+export const BUTTON_MATERIALS = ["flat", "etched"] as const;
+
 export const BUTTON_LABEL_SIZES = ["sm", "md", "lg"] as const;
 
 /** Sizes with a square footprint, for a button whose only content is an icon. */
@@ -33,6 +41,7 @@ export const BUTTON_GROUP_ORIENTATIONS = ["horizontal", "vertical"] as const;
 
 export const BUTTON_GROUP_POSITIONS = ["first", "middle", "last", "only"] as const;
 
+export type ButtonMaterial = (typeof BUTTON_MATERIALS)[number];
 export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
 export type ButtonLabelSize = (typeof BUTTON_LABEL_SIZES)[number];
 export type ButtonIconSize = (typeof BUTTON_ICON_SIZES)[number];
@@ -41,6 +50,11 @@ export type ButtonSpinnerPlacement = (typeof BUTTON_SPINNER_PLACEMENTS)[number];
 export type ButtonGroupOrientation = (typeof BUTTON_GROUP_ORIENTATIONS)[number];
 export type ButtonGroupPosition = (typeof BUTTON_GROUP_POSITIONS)[number];
 
+/** How a group shapes its run. Omitted, a group joins — that is what a group is. */
+export type ButtonGroupShapeOptions = {
+	isAttached?: boolean;
+};
+
 /** A member's place in its group, or `none` for a button standing on its own. */
 export type ButtonGroupSlotPosition = ButtonGroupPosition | "none";
 
@@ -135,8 +149,9 @@ export const buttonVariants = tv({
 		/**
 		 * A `Button.Group`'s box.
 		 *
-		 * Holds no `gap` and no `overflow-hidden`, and both absences are
-		 * load-bearing. A gap is the seam this component exists to close. A clip
+		 * Holds no `gap` while attached and no `overflow-hidden` ever, and both
+		 * absences are load-bearing. A gap is the seam a joined run exists to
+		 * close — only `isAttached: false` adds one, where there is no seam. A clip
 		 * would square off the very corners the position compounds just rounded,
 		 * and would have to restate the group's own corner to avoid it — while the
 		 * members already square themselves, which is the whole point.
@@ -192,10 +207,26 @@ export const buttonVariants = tv({
 			horizontal: { group: "flex-row self-start" },
 			vertical: { group: "flex-col" },
 		},
+		// Declared after `orientation` on purpose: `tv` merges in declaration
+		// order, so `self-stretch` here replaces the horizontal run's `self-start`
+		// rather than losing to it.
+		/** A `Button.Group` that spans its parent. The members split it — see `isStretched`. */
+		isFullWidth: { true: { group: "w-full self-stretch" }, false: {} },
+		/** A `Button.Group` whose members join into one shape. Detached, they stand apart by a gap. */
+		isAttached: { true: {}, false: { group: "gap-2" } },
+		/**
+		 * A member of a full-width horizontal run, taking an equal share of it.
+		 *
+		 * `basis-0` is the half that matters. With `flex-1` alone Yoga shares out
+		 * only the space left over after each member's content width, so the
+		 * widths still follow the labels; from a zero basis every share is equal.
+		 */
+		isStretched: { true: { root: "flex-1 basis-0" }, false: {} },
 		// `middle` is the one position whose corner needs neither the size nor the
 		// orientation, so it lands here rather than in six compound cells that
 		// would all say the same word.
 		groupPosition: { none: {}, first: {}, middle: { root: "rounded-none" }, last: {}, only: {} },
+		material: { flat: {}, etched: {} },
 		// 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` and rejects
@@ -208,6 +239,12 @@ export const buttonVariants = tv({
 		isDimmedWhileLoading: { true: {}, false: {} },
 	},
 	compoundVariants: [
+		{ material: "etched", variant: "primary", class: { root: "shadow-etched-primary" } },
+		{
+			material: "etched",
+			variant: ["secondary", "tertiary", "outline"],
+			class: { root: "shadow-etched dark:shadow-etched-dark" },
+		},
 		// Loading is not a disabled state. The button keeps full contrast — the
 		// spinner already says the press landed — unless the caller opts in.
 		{ isLoading: true, isDimmedWhileLoading: true, class: { root: "opacity-50" } },
@@ -304,6 +341,9 @@ export const buttonVariants = tv({
 		orientation: "horizontal",
 		groupPosition: "none",
 		isSeamed: false,
+		isFullWidth: false,
+		isAttached: true,
+		isStretched: false,
 		isDisabled: false,
 		isLoading: false,
 		isDimmedWhileLoading: false,
@@ -413,9 +453,18 @@ export function resolveGroupedButtonSize(own: ButtonSize | undefined, group: But
  * trade {@link resolveSpinnerSwapIndex} already makes. React Native has no
  * sibling selector, so this is the only place a member's corner can be decided.
  *
+ * A detached run (`isAttached: false`) places every member `only` — the lone
+ * position, which draws the lone button's corner — rather than minting a fourth
+ * sentinel: a spaced member *is* a button on its own that happens to share props.
+ *
  * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
  */
-export function resolveGroupPositions(isMember: readonly boolean[]): (ButtonGroupPosition | null)[] {
+export function resolveGroupPositions(
+	isMember: readonly boolean[],
+	{ isAttached = true }: ButtonGroupShapeOptions = {}
+): (ButtonGroupPosition | null)[] {
+	if (!isAttached) return isMember.map((member) => (member ? "only" : null));
+
 	const count = isMember.reduce((total, member) => (member ? total + 1 : total), 0);
 	let seen = 0;
 
@@ -445,9 +494,16 @@ export function resolveGroupPositions(isMember: readonly boolean[]): (ButtonGrou
  * `isMember[-1]` is `undefined`, so the first child falls out as `false` without
  * a case of its own.
  *
+ * A detached run has no shared edge, so nothing overlaps: a point of overlap
+ * there would only eat into the gap.
+ *
  * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
  */
-export function resolveGroupSeams(isMember: readonly boolean[]): boolean[] {
+export function resolveGroupSeams(
+	isMember: readonly boolean[],
+	{ isAttached = true }: ButtonGroupShapeOptions = {}
+): boolean[] {
+	if (!isAttached) return isMember.map(() => false);
 	return isMember.map((member, index) => member && isMember[index - 1] === true);
 }
 
@@ -463,6 +519,10 @@ export function resolveGroupSeams(isMember: readonly boolean[]): boolean[] {
  * while its neighbours hold still, so the seam the group exists to close tears
  * open for the length of the press. `fade` moves no geometry.
  *
+ * Only while the group is *attached*. A detached run has no seam to tear, so
+ * its members fall back to the lone button's `scale`. `isAttached` defaults to
+ * `true`, because joining is what a group does when it says nothing.
+ *
  * A caller still gets `scale` by asking for it, on one button or on a whole
  * group. `pressedScale` beats both, because `resolvePressedState` lets an
  * explicit value win on the axis it names — see `pressable.variants.ts`.
@@ -472,9 +532,30 @@ export function resolveGroupSeams(isMember: readonly boolean[]): boolean[] {
 export function resolveButtonFeedback(
 	own: PressableFeedback | undefined,
 	group: PressableFeedback | undefined,
-	isGrouped: boolean
+	isGrouped: boolean,
+	isAttached = true
 ): PressableFeedback {
-	return own ?? group ?? (isGrouped ? BUTTON_GROUP_FEEDBACK : BUTTON_FEEDBACK);
+	return own ?? group ?? (isGrouped && isAttached ? BUTTON_GROUP_FEEDBACK : BUTTON_FEEDBACK);
+}
+
+/**
+ * Whether a group's members take an equal share of its width.
+ *
+ * Horizontal only. A vertical run already stretches its members on the cross
+ * axis, and `basis-0` on the main axis of a column with no definite height
+ * would collapse every member to nothing — so `isFullWidth` on a vertical group
+ * widens the group and does nothing further.
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveGroupMemberStretch({
+	isFullWidth,
+	orientation,
+}: {
+	isFullWidth: boolean;
+	orientation: ButtonGroupOrientation;
+}): boolean {
+	return isFullWidth && orientation === "horizontal";
 }
 
 export type ButtonVariantProps = VariantProps<typeof buttonVariants>;

package/src/components/button/index.ts

@@ -28,6 +28,7 @@ export {
 	BUTTON_VARIANTS,
 	type ButtonGroupOrientation,
 	type ButtonGroupPosition,
+	type ButtonGroupShapeOptions,
 	type ButtonGroupSlotPosition,
 	type ButtonIconSize,
 	type ButtonLabelSize,
@@ -41,6 +42,7 @@ export {
 	resolveButtonLayout,
 	resolveButtonSizeStep,
 	resolveGroupedButtonSize,
+	resolveGroupMemberStretch,
 	resolveGroupPositions,
 	resolveGroupSeams,
 } from "./button.variants";

package/src/components/calendar/AGENTS.md

@@ -0,0 +1,142 @@
+# Calendar
+
+An always-visible month grid for picking one day, several days or a range. Compound root plus
+`Calendar.Header`, `Calendar.Nav`, `Calendar.Caption`, `Calendar.Weekdays`, `Calendar.Grid`,
+`Calendar.Day` and `Calendar.Picker`. Used inline on a screen, and as the body of the date pickers'
+sheets.
+
+`import { Calendar } from "@delacour/react-native-ui/calendar";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/calendar`; also re-exports every date helper and type |
+| `calendar.tsx` | Root: selection and month state, bounds, the context value, the `Object.assign` surface |
+| `calendar-header.tsx` | `Calendar.Header` — prev arrow, caption, next arrow by default |
+| `calendar-nav.tsx` | `Calendar.Nav` — a ghost `Button` that disables itself at a bound |
+| `calendar-caption.tsx` | `Calendar.Caption` — label, or the button that cycles days → months → years |
+| `calendar-weekdays.tsx` | `Calendar.Weekdays` — short names shown, full names spoken |
+| `calendar-grid.tsx` | `Calendar.Grid` — six weeks, the paging pan and slide, hosts the picker |
+| `calendar-day.tsx` | `Calendar.Day` — one cell: band, circle, number or custom content |
+| `calendar-picker.tsx` | `Calendar.Picker` — the months and years jump views |
+| `calendar.context.tsx` | `CalendarContext`, `useCalendar()`, `useCalendarContext()`, `useCalendarPart()` |
+| `calendar.types.ts` | `CalendarSelection` (the mode union), `CalendarProps`, `CalendarCaptionLayout` |
+| `calendar.date.ts` | **Shared leaf.** `CalendarDate` maths, matchers, grid, selection rules, `Intl` formatters. No React Native |
+| `calendar.date.test.ts` | |
+| `calendar.variants.ts` | Slotted `tv()`, the day-state, range-role, bounds, axes and page-direction resolvers |
+| `calendar.variants.test.ts` | |
+
+## The date leaf
+
+- **A day is `{ year, month, day }` and nothing else.** No `Date`, no time zone, no UTC
+  round-trip — a `Date` built at midnight in Auckland is the previous day in UTC, and that is the
+  bug every calendar built on `Date` ships once. `toDate`/`fromDate` cross over by **local**
+  fields, at the edge only.
+- **`weekdayOf` is Sakamoto's method**, not `new Date().getDay()`, so the leaf never touches the
+  device clock or zone. A test checks it against the platform for every day of a leap year.
+- **`calendar.date.ts` is the only module another folder may import from here.** `date-picker`
+  and `date-time-picker` reach `../calendar/calendar.date` — never `../calendar`, which would pull
+  the whole compound in (package rule 3).
+- **`resolveWeekStart` prefers `Intl.Locale#getWeekInfo`/`weekInfo`** and falls back to a region
+  table, because Hermes support for either is not guaranteed. Unknown is Monday (ISO 8601).
+- **Formatters never throw.** An unknown locale falls back to `en`; a formatter that throws inside
+  render takes the screen down for a typo.
+- **`parseDate` is strict** — `YYYY-MM-DD` and a real day, or `null`. A lenient parser turns
+  `2026-02-31` into 3 March, which is a different booking.
+
+## Selection
+
+- **`mode` is the discriminant** of `CalendarSelection`, so `selected` and `onSelect` are typed for
+  the mode named. Internally one `CalendarSelectionState` union flows through
+  `useControllableState`, and `emitSelection` narrows back to the caller's shape.
+- **Single:** a tap on the selected day clears it. **Multiple:** toggles; always sorted, deduped.
+- **Range** (`applyRangeTap`): empty → start; start + any day → complete, in either direction,
+  with the earlier day as `start` (`normaliseRange`); complete + tap → a new start. Backwards
+  completes rather than moving the start, because tapping check-out first is as common as
+  check-in first and a tap that silently discards the first one reads as a bug. A range that would contain a disabled day
+  (`rangeContainsDisabled`) restarts at the tapped day instead of completing — a stay that spans a
+  closed night is not bookable, and silently accepting it is worse than making the user tap again.
+- **Disabled vs read-only.** `isDisabled` makes everything inert and fades the root. `isReadOnly`
+  ignores day taps and leaves paging working — looking at another month changes nothing.
+
+## Layout
+
+- **Always six weeks** (`CALENDAR_WEEKS`). A month that fits in four or five rows still draws six,
+  so height and column positions never shift while paging. An outside day with
+  `showOutsideDays={false}` is an empty cell of the same height, never a missing one.
+- **The whole cell is the target**, not the circle. A column on a phone is wider than the circle
+  is tall, and the gap belongs to whichever day it sits beside.
+- **The cell is on the input scale** (`h-input-*`, `size-input-*`, `text-input-*`): sm 36, md 44,
+  lg 52. `md` and `lg` meet 44pt.
+- **The jump view sits over the grid** (`absolute inset-0`) while the weeks are hidden with
+  `opacity-0`, not unmounted, so opening it never changes the calendar's height. The weekday row
+  hides the same way.
+
+## Drawing
+
+- **A day is three layers:** `band` (absolute, edge to edge, behind), `dayBase` (the circle) and
+  the label. The band spans the full cell so adjacent days join into one strip.
+- **The band ends at the centre of each end cell, and the circle is the cap.** Start runs from its
+  cell's centre to the right edge, end from the left edge to its centre, middle spans the cell; none
+  is rounded. A cell is wider than its circle, so the first version — a band rounded across the
+  whole end cell — showed a crescent of band beside the circle at both ends. A lone `only` day
+  draws no band. At a week's edge the strip simply stops and resumes on the next row.
+- **Today is a ring (`border-ring`) and `text-primary`, never a fill**, so it cannot be mistaken
+  for a selection.
+- **Variant:** `primary` fills `bg-primary`, band `bg-primary/15`; `secondary` fills
+  `bg-primary/25` under `text-foreground`, band `bg-primary/10`. The primary band is a tint of the selection colour, not
+  `bg-accent`: light `--accent` is 0.97 on a 0.985 page, so the band all but vanished in light
+  while reading fine in dark. A tint of `primary` reads in both themes and joins the end caps
+  as one shape. `secondary` is tinted from `primary` for the same reason — `bg-secondary`
+  and `bg-muted` are 0.97 on the same 0.985 page, and the recorded preview showed a soft
+  selection with no visible circle at all. `isInvalid` overrides both with `bg-destructive` / `bg-destructive-soft`.
+- **Colour is on the text slots only** (rule 1): `dayLabel`, `weekdayLabel`, `captionText`,
+  `pickerItemLabel`. A test holds every `View` slot to carrying no `text-*` colour.
+- **Custom day content** gets `labelClassName` in its render props, so a price under the number
+  takes the selected colour with it rather than reimplementing the tone table.
+
+## Paging
+
+- **A Gesture Handler pan on `Calendar.Grid`**, `activeOffsetX` ±12 and `failOffsetY` ±12: it
+  claims a sideways drag and gives up a vertical one, so the calendar lives inside a `ScrollView`
+  or a sheet without stealing its scroll.
+- **`resolvePageDirection` is pure and tested.** A quarter of the width, or a release faster than
+  500 pt/s, pages; a flick against the drag settles back; it never pages past a bound or on an
+  unmeasured grid.
+- **Slide out, swap, slide in.** The old month slides off, the month changes on the JS thread, and
+  the new one slides in from the opposite side — the same entrance the arrows give. The grid
+  clips (`overflow-hidden`) so the swap frame is never seen.
+- **Calm motion skips both slides.** The page change is behaviour and always happens.
+- **A drag toward a bound resists** (20% travel) and settles back with a `light` haptic — the edge
+  is felt rather than the month silently refusing to turn.
+- **Tapping an outside day** (with `selectOutsideDays`) selects it and pages to its month.
+
+## Accessibility
+
+- Each day is a button labelled with the full date (`formatDate(…, { style: "full" })`), hinted
+  "Today" / "Range start" / "Range end", with `selected` and `disabled` state.
+- The grid is `role="grid"`, named by an enclosing `Field.Label` or else the month.
+- **Paging for screen readers lives on the caption**, as increment/decrement actions. An
+  adjustable grid would fold its child buttons into itself on both platforms and make the days
+  unreachable.
+- A month change is announced with `AccessibilityInfo.announceForAccessibility` — on change only,
+  never on mount, because the caption already says it.
+- Today is re-read on `AppState` → `active`, so a calendar left open overnight marks the right day.
+
+- **Parts derive their `testID` from the root's** (`resolvePartTestID`): `testID="booking"`
+  names the days `booking-day-2026-10-05`, the arrows `booking-prev`/`booking-next`, the caption
+  `booking-caption` and the jump-view items `booking-month-10`/`booking-year-2026`. The default
+  anatomy renders forty-odd parts no caller writes, and an end-to-end test or a recorded preview
+  flow has to reach one particular day all the same. No root `testID`, no part ids.
+
+## Field
+
+`resolveCalendarAxes` is the nearest-wins chain: the calendar's own `isDisabled` / `isInvalid` /
+`isReadOnly` / `size` / `variant`, else the `Field`'s. The field's label names the grid. It does
+not `registerPress` — there is no single focus target for a row tap to reach.
+
+## Not here
+
+Non-Gregorian calendars, side-by-side months, week numbers, drag-to-select ranges, time. The
+anchored presentation belongs to `DatePicker`.