@olympusoss/canvas 4.0.0 → 5.0.0

package/src/molecules/stats/stats.md

@@ -0,0 +1,166 @@
+# Stats
+
+Single value, grouped row, with sparkline, with comparison. Used for dashboards and overview pages.
+
+## Usage
+
+```tsx
+<Stats
+  items={[
+    { label: "Active users", value: "71,897", delta: "+12.3% vs. last 30 days" }
+  ]}
+/>
+```
+
+## Variants
+
+### Variant - group
+
+```tsx
+<Stats
+  items={[
+    { label: "Total users", value: "12,847", delta: "+12.5%" },
+    { label: "Active sessions", value: "1,024", delta: "+3.2%" },
+    { label: "Error rate", value: "0.12%", delta: "+0.03%", down: true }
+  ]}
+/>
+```
+
+### Variant - plain
+
+```tsx
+<Stats
+  plain
+  title="Key metrics"
+  items={[
+    { label: "Revenue", value: "$48.2k" },
+    { label: "Orders", value: "842" },
+    { label: "Avg. value", value: "$57.24" },
+    { label: "Conversion", value: "3.6%" }
+  ]}
+/>
+```
+
+### Variant - sparkline
+
+```tsx
+<Stats
+  items={[
+    { label: "Requests", value: "24.5k", delta: "+8.2%" },
+    { label: "Latency", value: "142ms", delta: "+12ms", down: true }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Single
+
+**Do** — Name the comparison and the period so the delta is unambiguous.
+
+```tsx
+<Stats style={{ maxWidth: 280 }} items={[
+    { label: "Active users", value: "71,897", delta: "+12.3% vs. last 30 days" }
+  ]} />
+```
+
+**Don't** — A bare delta with no baseline leaves the reader asking: up against what, and over what window?
+
+```tsx
+<Stats style={{ maxWidth: 280 }} items={[
+    { label: "Active users", value: "71,897", delta: "+12.3%" }
+  ]} />
+```
+
+### Group
+
+**Do** — Use the auto-fit grid and round headline numbers so cards wrap and stay scannable.
+
+```tsx
+<Stats items={[
+    { label: "Revenue", value: "$48.2k", delta: "+12.5%" },
+    { label: "Orders", value: "842", delta: "+3.2%" },
+    { label: "Conversion", value: "3.6%", delta: "+0.4%" }
+  ]} />
+```
+
+**Don't** — A fixed flex row of full-precision numbers overflows on narrow viewports and crowds the cards.
+
+```tsx
+<Stats items={[
+    { label: "Revenue", value: "$48,250.00", delta: "+12.5%" },
+    { label: "Orders", value: "842", delta: "+3.2%" },
+    { label: "Conversion", value: "3.6%", delta: "+0.4%" }
+  ]} />
+```
+
+### Plain (no border)
+
+**Do** — On a parent surface drop the border and radius; let the number stacks stand on their own.
+
+```tsx
+<Stats plain items={[
+    { label: "Revenue", value: "$48.2k" },
+    { label: "Orders", value: "842" }
+  ]} />
+```
+
+**Don't** — Bordered cards inside a card surface double the chrome: a box drawn around boxes.
+
+```tsx
+<View style={{ borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, ...shadow("sm"), padding: 24 }}>
+  <Stats items={[
+    { label: "Revenue", value: "$48.2k" },
+    { label: "Orders", value: "842" }
+  ]} />
+</View>
+```
+
+### With sparkline
+
+**Do** — Pair the sparkline with an explicit delta so the headline reads without decoding the curve.
+
+```tsx
+<View style={{ borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, ...shadow("sm"), maxWidth: 220, padding: 20 }}>
+  <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>Requests</Text>
+  <View style={{ marginTop: 4, flexDirection: "row", alignItems: "baseline", justifyContent: "space-between" }}>
+    <Text style={{ fontSize: 24, lineHeight: 32, fontWeight: "600", letterSpacing: -0.4, color: tokens.foreground }}>24.5k</Text>
+    <Text style={{ fontFamily: "monospace", fontSize: 11, color: palette["emerald-600"] }}>+8.2%</Text>
+  </View>
+  <View style={{ marginTop: 12, flexDirection: "row", alignItems: "flex-end", gap: 2, height: 24 }}>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 4 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 8 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 6 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 12 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 10 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 16 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 14 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 18 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 16 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 20 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 24 }} />
+  </View>
+</View>
+```
+
+**Don't** — A trend line with no current delta makes you eyeball the slope to guess the direction.
+
+```tsx
+<View style={{ borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, ...shadow("sm"), maxWidth: 220, padding: 20 }}>
+  <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>Requests</Text>
+  <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "600", letterSpacing: -0.4, color: tokens.foreground }}>24.5k</Text>
+  <View style={{ marginTop: 12, flexDirection: "row", alignItems: "flex-end", gap: 2, height: 24 }}>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 4 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 8 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 6 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 12 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 10 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 16 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 14 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 18 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 16 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 20 }} />
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", borderRadius: 2, backgroundColor: alpha(tokens.primary, 0.7), height: 24 }} />
+  </View>
+</View>
+```

package/src/molecules/stats/stats.styles.ts

@@ -0,0 +1,91 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, palette, shadow } from "../../style/index.js";
+
+// Co-located Stats styles. Layout-only fragments are static objects; anything
+// that reads a color is a function of the active tokens (so the surfaces follow
+// light/dark and read as glass when the ThemeProvider's surface is "glass",
+// since tokens.card is swapped translucent at the theming level). The delta tone
+// uses the Tailwind palette (a 600 hue in light, a 400 hue in dark), branched on
+// the active scheme.
+
+export type Surface = "card" | "plain";
+
+// The bordered card surface, mirroring the docs `cardCls` plus its padding
+// (rounded-lg border border-border bg-card shadow-sm p-5).
+export function cardSurface(tokens: ColorTokens): ViewStyle {
+  return {
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+    padding: 20,
+    ...shadow("sm"),
+  };
+}
+
+// The parent surface the plain variant nests on
+// (rounded-lg border border-border bg-card shadow-sm p-6).
+export function plainContainer(tokens: ColorTokens): ViewStyle {
+  return {
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+    padding: 24,
+    ...shadow("sm"),
+  };
+}
+
+// A wrapping row: items flow left to right and wrap to the next line when they
+// run out of room (flex-row flex-wrap).
+export const row: ViewStyle = { flexDirection: "row", flexWrap: "wrap" };
+
+// Row gap by surface: plain stacks sit roomier (gap-6), cards pack tighter
+// (gap-3.5).
+export const rowGap: Record<Surface, ViewStyle> = {
+  card: { gap: 14 },
+  plain: { gap: 24 },
+};
+
+// Per-item minimum width and growth, by surface. Card items hold a wider floor
+// and grow (flex-1 min-w-48); plain stacks pack tighter (min-w-28).
+export const item: Record<Surface, ViewStyle> = {
+  card: { flexGrow: 1, flexShrink: 1, flexBasis: "0%", minWidth: 192 },
+  plain: { minWidth: 112 },
+};
+
+// Title type by surface (card: text-sm mb-3, plain: text-base mb-4).
+export function title(tokens: ColorTokens, surface: Surface): TextStyle {
+  return surface === "card"
+    ? { fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground, marginBottom: 12 }
+    : { fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground, marginBottom: 16 };
+}
+
+// --- one metric: label, value, optional delta -------------------------------
+
+// text-sm text-muted-foreground
+export function labelText(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}
+
+// mt-1 text-2xl font-semibold tracking-tight text-foreground
+export function valueText(tokens: ColorTokens): TextStyle {
+  return {
+    marginTop: 4,
+    fontSize: 24,
+    lineHeight: 32,
+    fontWeight: "600",
+    letterSpacing: -0.4,
+    color: tokens.foreground,
+  };
+}
+
+// mt-1 text-xs font-medium, with the tone color applied on top.
+export const deltaBase: TextStyle = { marginTop: 4, fontSize: 12, lineHeight: 16, fontWeight: "500" };
+
+// Delta tone: a rise reads green (text-green-600 dark:text-green-400), a decline
+// reads red (text-red-600 dark:text-red-400).
+export function deltaTone(dark: boolean, down: boolean): TextStyle {
+  const hue = down ? "red" : "green";
+  return { color: dark ? palette[`${hue}-400`] : palette[`${hue}-600`] };
+}

package/src/molecules/stats/stats.tsx

@@ -0,0 +1,88 @@
+import { type ReactNode } from "react";
+import { View, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import * as s from "./stats.styles.js";
+import { type Surface } from "./stats.styles.js";
+
+// Stats: a row/grid of metric items, each a small label, a large headline value,
+// and an optional delta (e.g. +12.5% in green, -3% in red). Used for dashboard
+// and overview surfaces.
+//
+// Two surfaces, one axis (`plain` vs the default card):
+//
+// 1. Card (default): each metric sits in its own bordered, shadowed card. Good
+//    for a standalone metric or a free-standing group on a bare page.
+// 2. Plain (`plain`): the metric stacks sit borderless on a shared parent
+//    surface, so you don't draw boxes inside a box. Pair with a parent card.
+//
+// Layout is responsive by default: items lay out in a wrapping row, each holding
+// a sensible minimum width, so a group reflows from a single row on desktop down
+// to a stack on a phone without any per-breakpoint props.
+//
+// Boolean-prop API: one boolean per option, first-match precedence within an
+// axis (mirrors Button's intentOf). `items` carries the plain data; each item's
+// `down` flag colors its delta red instead of the default green.
+
+export interface StatItem {
+  /** Small caption above the value (e.g. "Total users"). */
+  label: string;
+  /** The headline figure, pre-formatted (e.g. "12,847", "$48.2k", "3.6%"). */
+  value: string;
+  /** Optional change indicator (e.g. "+12.5%"). Omit to hide. */
+  delta?: string;
+  /** Color the delta red (a decline) instead of the default green (a rise). */
+  down?: boolean;
+}
+
+export interface StatsProps {
+  /** The metrics to render, in order. */
+  items: StatItem[];
+  // Surface (pick one; default is bordered cards).
+  /** Borderless metric stacks on a shared surface, for nesting inside a card. */
+  plain?: boolean;
+  /** Optional heading shown above the metrics (mainly for the plain surface). */
+  title?: string;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Surface precedence when more than one is passed: first match wins.
+function surfaceOf(p: StatsProps): Surface {
+  if (p.plain) return "plain";
+  return "card";
+}
+
+// One metric: label, value, optional delta.
+function StatItemView({ item, surface }: { item: StatItem; surface: Surface }): ReactNode {
+  const { tokens, dark } = useTheme();
+  return (
+    <View style={[surface === "card" ? s.cardSurface(tokens) : null, s.item[surface]]}>
+      <Text style={s.labelText(tokens)}>{item.label}</Text>
+      <Text style={s.valueText(tokens)}>{item.value}</Text>
+      {item.delta != null && item.delta !== "" ? (
+        <Text style={[s.deltaBase, s.deltaTone(dark, !!item.down)]}>{item.delta}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+export function Stats(props: StatsProps) {
+  const { items, title, style } = props;
+  const { tokens } = useTheme();
+  const surface = surfaceOf(props);
+
+  // The card surface lays cards directly in a wrapping, gapped row. The plain
+  // surface wraps the stacks in a shared parent card so the borderless metrics
+  // have something to sit on.
+  const isPlain = surface === "plain";
+
+  return (
+    <View style={[isPlain ? s.plainContainer(tokens) : null, style]}>
+      {title != null && title !== "" ? <Text style={s.title(tokens, surface)}>{title}</Text> : null}
+      <View style={[s.row, s.rowGap[surface]]}>
+        {items.map((item, i) => (
+          <StatItemView key={i} item={item} surface={surface} />
+        ))}
+      </View>
+    </View>
+  );
+}

package/src/organisms/calendar/calendar.android.tsx

@@ -0,0 +1,6 @@
+import { createCalendar } from "./calendar.shared.js";
+import { androidSkin } from "./calendar.styles.js";
+
+// Material 3 date picker Calendar. Metro resolves this file on Android; the docs import it for preview.
+export const Calendar = createCalendar(androidSkin);
+export type { CalendarProps } from "./calendar.shared.js";

package/src/organisms/calendar/calendar.ios.tsx

@@ -0,0 +1,6 @@
+import { createCalendar } from "./calendar.shared.js";
+import { iosSkin } from "./calendar.styles.js";
+
+// iOS (HIG date picker) Calendar. Metro resolves this file on iOS; the docs import it for preview.
+export const Calendar = createCalendar(iosSkin);
+export type { CalendarProps } from "./calendar.shared.js";

package/src/organisms/calendar/calendar.md

@@ -0,0 +1,114 @@
+# Calendars
+
+Date picker, event list. Production: wrap react-day-picker.
+
+## Usage
+
+```tsx
+<Calendar
+  month="May 2026"
+  today={23}
+  selected={24}
+  daysInMonth={31}
+  startWeekday={4}
+/>
+```
+
+## Variants
+
+### Variant - events
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "flex-start", gap: 24 }}>
+  <Calendar month="May 2026" today={23} selected={24} daysInMonth={31} startWeekday={4} />
+  <Card style={{ minWidth: 240, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+    <View style={{ borderBottomWidth: 1, borderColor: tokens.border, paddingHorizontal: 20, paddingVertical: 12 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens["card-foreground"] }}>May 24</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 16, paddingVertical: 10, borderBottomWidth: 1, borderColor: tokens.border }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Sprint planning</Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>9:00 AM</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 16, paddingVertical: 10, borderBottomWidth: 1, borderColor: tokens.border }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Design review</Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>11:30 AM</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 16, paddingVertical: 10 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>1:1 with manager</Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>2:00 PM</Text>
+    </View>
+  </Card>
+</View>
+```
+
+## Do & Don't
+
+### Single date
+
+**Do** — Exactly one selected day (primary), with today marked separately in the accent tone.
+
+```tsx
+<View style={{ width: "auto", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, padding: 12 }}>
+  <View style={{ flexDirection: "row", gap: 2 }}>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>8</Text>
+    </Pressable>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6, backgroundColor: tokens.accent }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["accent-foreground"] }}>23</Text>
+    </Pressable>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6, backgroundColor: tokens.primary }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["primary-foreground"] }}>24</Text>
+    </Pressable>
+  </View>
+</View>
+```
+
+**Don't** — Painting several days with the primary selected style makes a single-date picker look like a multi-select.
+
+```tsx
+<View style={{ width: "auto", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, padding: 12 }}>
+  <View style={{ flexDirection: "row", gap: 2 }}>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6, backgroundColor: tokens.primary }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["primary-foreground"] }}>8</Text>
+    </Pressable>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6, backgroundColor: tokens.primary }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["primary-foreground"] }}>14</Text>
+    </Pressable>
+    <Pressable style={{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6, backgroundColor: tokens.primary }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["primary-foreground"] }}>23</Text>
+    </Pressable>
+  </View>
+</View>
+```
+
+### With event list
+
+**Do** — Keep the panel header and rows in sync with the selected day so the two views always agree.
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "flex-start", gap: 24 }}>
+  <Calendar month="May 2026" today={23} selected={24} daysInMonth={31} startWeekday={4} />
+  <Card style={{ minWidth: 240, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+    <View style={{ borderBottomWidth: 1, borderColor: tokens.border, paddingHorizontal: 20, paddingVertical: 12 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens["card-foreground"] }}>May 24</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 16, paddingVertical: 10 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Sprint planning</Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>9:00 AM</Text>
+    </View>
+  </Card>
+</View>
+```
+
+**Don't** — Selecting May 24 but leaving the panel on a placeholder breaks the link between the grid and its day.
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "flex-start", gap: 24 }}>
+  <Calendar month="May 2026" today={23} selected={24} daysInMonth={31} startWeekday={4} />
+  <Card style={{ minWidth: 240, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+    <View style={{ paddingHorizontal: 16, paddingVertical: 12 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Pick a date to see events.</Text>
+    </View>
+  </Card>
+</View>
+```

package/src/organisms/calendar/calendar.shared.tsx

@@ -0,0 +1,146 @@
+import { type GestureResponderEvent } from "react-native";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { type CalendarSkin, type Density } from "./calendar.styles.js";
+
+// Shared Calendar shell. The structure (header with prev/next chevrons + month
+// label, a weekday label row, and a 6x7 grid of day cells), the density
+// precedence, the leading-blank padding, the accessibility, and the press
+// handlers live here once; a platform file supplies only its skin (the native
+// container/header/cell shape, weekday-label style, selected/today day treatment,
+// and press feedback) and calls createCalendar.
+//
+// A month calendar: a header (month/year label flanked by prev/next chevrons),
+// a weekday label row, and a 6x7 grid of day cells. Today and the selected day
+// are highlighted; leading blanks pad the first row to the correct weekday.
+//
+// There is no CSS grid, so the day grid is a `flex-row flex-wrap` of fixed-width
+// cells. Seven cells per row times the cell width gives the grid a fixed width,
+// set explicitly so wrapping lands exactly seven-per-row (width supplied by the
+// skin's per-density metrics).
+
+export interface CalendarProps {
+  /** Month + year label shown in the header, e.g. "June 2026". */
+  month?: string;
+  /** The day number currently selected (primary highlight). */
+  selected?: number;
+  /** The day number that is today (primary highlight when unselected). */
+  today?: number;
+  /** Number of days in the month. */
+  daysInMonth?: number;
+  /** Weekday (0=Sun .. 6=Sat) the 1st falls on; sets leading blank cells. */
+  startWeekday?: number;
+  /** Fired with the day number when a day cell is pressed. */
+  onSelect?: (day: number) => void;
+  /** Fired when the previous-month chevron is pressed. */
+  onPrev?: (event: GestureResponderEvent) => void;
+  /** Fired when the next-month chevron is pressed. */
+  onNext?: (event: GestureResponderEvent) => void;
+
+  // Density (pick one; default is the comfortable cell).
+  /** Tighter cells and smaller type, for dense surfaces. */
+  compact?: boolean;
+
+  /** Escape hatch for layout/positioning composition (width, margins). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Density precedence: `compact` wins, otherwise the default cell.
+function densityOf(p: CalendarProps): Density {
+  if (p.compact) return "compact";
+  return "default";
+}
+
+/** Build a Calendar component from a platform skin. */
+export function createCalendar(skin: CalendarSkin) {
+  return function Calendar(props: CalendarProps) {
+    const {
+      month = "June 2026",
+      selected,
+      today,
+      daysInMonth = 30,
+      startWeekday = 0,
+      onSelect,
+      onPrev,
+      onNext,
+      style,
+    } = props;
+
+    const { tokens } = useTheme();
+    const density = densityOf(props);
+    const m = skin.metrics[density];
+    const lead = ((startWeekday % 7) + 7) % 7;
+    const days = Array.from({ length: daysInMonth }, (_, i) => i + 1);
+    const ripple = skin.ripple ? skin.ripple(tokens) : undefined;
+
+    return (
+      <View style={[skin.containerBase, skin.containerSurface(tokens), style]}>
+        {/* Header: month label between two ghost chevron buttons. */}
+        <View style={skin.header}>
+          <Pressable
+            style={({ pressed }) => [
+              skin.chevron,
+              skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+            ]}
+            android_ripple={ripple ? { ...ripple, borderless: true } : undefined}
+            onPress={onPrev}
+            accessibilityRole="button"
+            accessibilityLabel="Previous month"
+          >
+            <Text style={skin.chevronText(tokens)}>{"‹"}</Text>
+          </Pressable>
+          <Text style={skin.monthLabel(tokens)}>{month}</Text>
+          <Pressable
+            style={({ pressed }) => [
+              skin.chevron,
+              skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+            ]}
+            android_ripple={ripple ? { ...ripple, borderless: true } : undefined}
+            onPress={onNext}
+            accessibilityRole="button"
+            accessibilityLabel="Next month"
+          >
+            <Text style={skin.chevronText(tokens)}>{"›"}</Text>
+          </Pressable>
+        </View>
+
+        {/* Weekday label row. */}
+        <View style={[skin.grid, { width: m.gridWidth }]}>
+          {skin.weekdays.map((wd, i) => (
+            <View key={`wd-${i}`} style={[skin.headCell, m.head]}>
+              <Text style={skin.weekdayLabel(tokens)}>{wd}</Text>
+            </View>
+          ))}
+        </View>
+
+        {/* Day grid: leading blanks, then one cell per day. */}
+        <View style={[skin.grid, { width: m.gridWidth }]}>
+          {Array.from({ length: lead }, (_, i) => (
+            <View key={`blank-${i}`} style={[skin.headCell, m.cell]} />
+          ))}
+          {days.map((day) => {
+            const isSelected = selected != null && day === selected;
+            const isToday = today != null && day === today;
+            const state = { selected: isSelected, today: isToday };
+            return (
+              <Pressable
+                key={day}
+                style={({ pressed }) => [
+                  skin.dayCellBase,
+                  m.cell,
+                  skin.dayCellState(tokens, state),
+                  skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+                ]}
+                android_ripple={ripple}
+                onPress={() => onSelect?.(day)}
+                accessibilityRole="button"
+                accessibilityState={{ selected: isSelected }}
+              >
+                <Text style={[m.label, skin.dayLabel(tokens, state)]}>{day}</Text>
+              </Pressable>
+            );
+          })}
+        </View>
+      </View>
+    );
+  };
+}