@olympusoss/canvas 4.0.0 → 5.0.0

package/src/atoms/pagination/pagination.shared.tsx

@@ -0,0 +1,289 @@
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle, type ColorTokens } from "../../style/index.js";
+import * as s from "./pagination.styles.js";
+import { type Size, type PaginationSkin } from "./pagination.styles.js";
+
+// Shared Pagination shell. The structure (numbered / compact / with-size
+// variants, the windowing math, the clamp + go handler, the size-selector
+// cycling), the accessibility, and the variant/size precedence live here once; a
+// platform file supplies only its skin (the cell shape, the active-page fill,
+// the label color, and the press feedback) and calls createPagination.
+//
+// Pagination is page-of-N navigation for tables and lists: a horizontal row of
+// page-number buttons flanked by Prev/Next controls, with the current page
+// highlighted. When there are too many pages to show at once, the middle is
+// truncated with an ellipsis glyph, keeping the first page, the last page, and a
+// small window around the current page.
+//
+// The brand survives on every platform (the indigo `primary` token fills the
+// active page); only the native SHAPE (cell radius) and press feedback change:
+//   - iOS (HIG page controls): pill-rounded cells (radius ~8), the active page
+//     filled `primary`; press = opacity dim 0.8.
+//   - Android (M3): flat cells (radius ~8), active page a tonal alpha(primary)
+//     fill with a brand label; press = android_ripple.
+//   - Web: the established Canvas look (bordered boxes, radius 6, solid primary
+//     fill on the active page), lifted verbatim.
+//
+// Boolean-prop API across two axes (mirrors Button's intentOf precedence; first
+// match wins within an axis, axes are orthogonal):
+//   - Variant: `withSize` prepends a "Rows per page" size selector to the
+//     compact Prev/Next + "Page X of N" layout; `compact` collapses the number
+//     row to just Prev/Next plus a "Page X of N" label; the default is the full
+//     numbered row. Precedence when more than one is passed: withSize, then
+//     compact, then the numbered default.
+//   - Size: `small`, `large` (omit for the default, medium size).
+//
+// There is no icon utility at this layer, so Prev/Next use reading-direction
+// single guillemet glyphs ("‹" / "›") rendered as Text rather than SVG chevrons,
+// the size selector uses a "▾" caret glyph, and the truncation gap is an ellipsis
+// glyph ("…").
+
+export interface PaginationProps {
+  /** Current page, 1-based. Clamped into the 1..total range before rendering. */
+  page?: number;
+  /** Total number of pages. */
+  total?: number;
+  /** Fired with the next 1-based page when a control or number is pressed. */
+  onChange?: (page: number) => void;
+
+  // Variant (pick one; default is the full numbered row).
+  /** Collapse to Prev/Next plus a "Page X of N" label, no number buttons. */
+  compact?: boolean;
+  /**
+   * Prepend a "Rows per page" size selector to the compact Prev/Next +
+   * "Page X of N" layout. Takes precedence over `compact`.
+   */
+  withSize?: boolean;
+
+  // Content for the `withSize` selector.
+  /** Currently selected rows-per-page value shown in the selector. */
+  pageSize?: number;
+  /** Selectable rows-per-page values; pressing the selector advances through them. */
+  pageSizes?: number[];
+  /** Fired with the next rows-per-page value when the selector is pressed. */
+  onPageSizeChange?: (size: number) => void;
+
+  // Size (pick one; default is the medium size).
+  small?: boolean;
+  large?: boolean;
+
+  disabled?: boolean;
+  /** Escape hatch for layout/positioning composition (margins, alignment). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Size precedence when more than one is passed: first match wins.
+function sizeOf(p: PaginationProps): Size {
+  if (p.small) return "small";
+  if (p.large) return "large";
+  return "default";
+}
+
+type Variant = "withSize" | "compact" | "numbered";
+
+// Variant precedence when more than one is passed: first match wins.
+function variantOf(p: PaginationProps): Variant {
+  if (p.withSize) return "withSize";
+  if (p.compact) return "compact";
+  return "numbered";
+}
+
+// Sentinel inserted into the page list for a truncation gap.
+const GAP = -1;
+
+// Compute the windowed page list: first page, last page, and a one-page window
+// around the current page, with GAP sentinels marking truncated stretches. For
+// small totals (<= 7) every page is shown.
+function pageWindow(current: number, total: number): number[] {
+  if (total <= 7) {
+    const all: number[] = [];
+    for (let p = 1; p <= total; p++) all.push(p);
+    return all;
+  }
+  const list: number[] = [];
+  const add = (p: number) => {
+    if (!list.includes(p)) list.push(p);
+  };
+  add(1);
+  if (current > 3) list.push(GAP);
+  for (let p = Math.max(2, current - 1); p <= Math.min(total - 1, current + 1); p++) add(p);
+  if (current < total - 2) list.push(GAP);
+  add(total);
+  return list;
+}
+
+/** Build a Pagination component from a platform skin. */
+export function createPagination(skin: PaginationSkin) {
+  const ripple = skin.ripple;
+
+  interface ControlProps {
+    glyph: string;
+    size: Size;
+    tokens: ColorTokens;
+    disabled: boolean;
+    accessibilityLabel: string;
+    onPress: () => void;
+  }
+
+  // A Prev/Next chevron control. Reads as a square page button without a number.
+  function Control({ glyph, size, tokens, disabled, accessibilityLabel, onPress }: ControlProps) {
+    return (
+      <Pressable
+        style={({ pressed }) => [
+          skin.controlBox(tokens),
+          s.itemSize[size],
+          disabled ? { opacity: 0.5 } : null,
+          skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+        ]}
+        onPress={onPress}
+        disabled={disabled}
+        android_ripple={ripple ? ripple(tokens, false) : undefined}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+        accessibilityState={{ disabled }}
+      >
+        <Text style={[skin.controlLabel(tokens), s.labelSize[size]]}>{glyph}</Text>
+      </Pressable>
+    );
+  }
+
+  return function Pagination(props: PaginationProps) {
+    const { onChange, disabled, style } = props;
+    const size = sizeOf(props);
+    const variant = variantOf(props);
+    const { tokens } = useTheme();
+
+    // Clamp inputs so the control never renders an out-of-range current page.
+    const total = Math.max(1, Math.floor(props.total ?? 1));
+    const current = Math.min(Math.max(1, Math.floor(props.page ?? 1)), total);
+
+    const atStart = current <= 1;
+    const atEnd = current >= total;
+
+    const go = (next: number) => {
+      if (disabled) return;
+      const clamped = Math.min(Math.max(1, next), total);
+      if (clamped !== current) onChange?.(clamped);
+    };
+
+    const prev = (
+      <Control
+        glyph="‹"
+        size={size}
+        tokens={tokens}
+        disabled={disabled || atStart}
+        accessibilityLabel="Previous page"
+        onPress={() => go(current - 1)}
+      />
+    );
+    const next = (
+      <Control
+        glyph="›"
+        size={size}
+        tokens={tokens}
+        disabled={disabled || atEnd}
+        accessibilityLabel="Next page"
+        onPress={() => go(current + 1)}
+      />
+    );
+
+    // Compact: Prev/Next bracketing a "Page X of N" indicator, no number buttons.
+    if (variant === "compact") {
+      return (
+        <View style={[s.compactRow, style]}>
+          {prev}
+          <Text style={[skin.mutedLabel(tokens), s.labelSize[size]]}>
+            {`Page ${current} of ${total}`}
+          </Text>
+          {next}
+        </View>
+      );
+    }
+
+    // With-size: a "Rows per page" selector ahead of the compact indicator and the
+    // Prev/Next controls. There is no native select, so the selector is a closed
+    // trigger (value + caret) that advances through `pageSizes` on press.
+    if (variant === "withSize") {
+      const sizes = props.pageSizes ?? [10, 25, 50];
+      const pageSize = props.pageSize ?? sizes[0] ?? 10;
+      const cycleSize = () => {
+        if (disabled) return;
+        const i = sizes.indexOf(pageSize);
+        const nextSize = sizes[(i + 1) % sizes.length];
+        if (nextSize !== undefined && nextSize !== pageSize) props.onPageSizeChange?.(nextSize);
+      };
+      return (
+        <View style={[s.withSizeRow, style]}>
+          <View style={s.selectorCluster}>
+            <Text style={[skin.mutedLabel(tokens), s.labelSize[size]]}>Rows per page</Text>
+            <Pressable
+              style={({ pressed }) => [
+                skin.selectorBox(tokens),
+                s.itemSize[size],
+                disabled ? { opacity: 0.5 } : null,
+                skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+              ]}
+              onPress={cycleSize}
+              disabled={disabled}
+              android_ripple={ripple ? ripple(tokens, false) : undefined}
+              accessibilityRole="button"
+              accessibilityLabel="Rows per page"
+            >
+              <Text style={[skin.controlLabel(tokens), s.labelSize[size]]}>{pageSize}</Text>
+              <Text style={[skin.mutedLabel(tokens), s.labelSize[size]]}>▾</Text>
+            </Pressable>
+          </View>
+          <Text style={[skin.mutedLabel(tokens), s.labelSize[size]]}>
+            {`Page ${current} of ${total}`}
+          </Text>
+          <View style={s.controlPair}>
+            {prev}
+            {next}
+          </View>
+        </View>
+      );
+    }
+
+    // Numbered (default): a windowed row of page buttons with ellipsis gaps.
+    const window = pageWindow(current, total);
+
+    return (
+      <View style={[s.numberedRow, style]}>
+        {prev}
+        {window.map((p, i) => {
+          if (p === GAP) {
+            return (
+              <Text
+                key={`gap-${i}`}
+                style={[skin.gapLabel(tokens), s.labelSize[size]]}
+                accessibilityElementsHidden
+              >
+                …
+              </Text>
+            );
+          }
+          const selected = p === current;
+          return (
+            <Pressable
+              key={`page-${p}`}
+              style={({ pressed }) => [
+                skin.pageBox(tokens, selected),
+                s.itemSize[size],
+                disabled ? { opacity: 0.5 } : null,
+                skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+              ]}
+              onPress={() => go(p)}
+              disabled={disabled}
+              android_ripple={ripple ? ripple(tokens, selected) : undefined}
+              accessibilityRole="button"
+              accessibilityLabel={`Page ${p}`}
+              accessibilityState={{ selected, disabled: !!disabled }}
+            >
+              <Text style={[skin.pageLabel(tokens, selected), s.labelSize[size]]}>{p}</Text>
+            </Pressable>
+          );
+        })}
+        {next}
+      </View>
+    );
+  };
+}

package/src/atoms/pagination/pagination.styles.ts

@@ -0,0 +1,245 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, alpha } from "../../style/index.js";
+
+// Co-located Pagination skins, one per platform. The page buttons, Prev/Next
+// controls, and the size selector are square-ish boxes whose footprint scales
+// with the size axis; labels scale on a smaller type ramp. The BRAND survives on
+// every platform (the active page reads the indigo `primary` token, never a
+// platform default), and only the native SHAPE (cell radius / border) and press
+// feedback change per OS. This is a LIGHT platform touch: neither iOS nor
+// Material 3 ships a true numbered pagination, so the prev/next/numbered
+// structure stays identical and each platform applies only its shape + feedback.
+//   iOS (HIG page controls): pill-rounded cells (radius 8), no cell border, the
+//     ACTIVE page filled `primary`; press = opacity dim 0.8.
+//   Android (M3): flat cells (radius 8), no border, the ACTIVE page a tonal
+//     alpha(primary, .12) fill with a brand-indigo label; press = android_ripple.
+//   Web: the established Canvas look (1px bordered boxes, radius 6, the active
+//     page a solid `primary` fill/border), lifted verbatim.
+
+export type Size = "small" | "default" | "large";
+
+// The platform-varying surface. Everything color/shape-bearing the cells need
+// lives here, built from the active tokens (so fills/borders follow light/dark
+// and the glass surface). Layout (gaps, rows) is shared and stays in this file's
+// static fragments below.
+export interface PaginationSkin {
+  /** A Prev/Next chevron control: the bordered/filled box behind the glyph. */
+  controlBox: (t: ColorTokens) => ViewStyle;
+  /** A numbered page cell. Selected reads the brand fill; the rest are plain. */
+  pageBox: (t: ColorTokens, selected: boolean) => ViewStyle;
+  /** The rows-per-page selector trigger box (value + caret). */
+  selectorBox: (t: ColorTokens) => ViewStyle;
+  /** Control glyph / selector value color (foreground). */
+  controlLabel: (t: ColorTokens) => TextStyle;
+  /** A numbered page label; brand-on-fill when selected, foreground otherwise. */
+  pageLabel: (t: ColorTokens, selected: boolean) => TextStyle;
+  /** Muted supporting text: the "Page X of N" indicator, "Rows per page", caret. */
+  mutedLabel: (t: ColorTokens) => TextStyle;
+  /** The truncation ellipsis: muted, with a small horizontal inset. */
+  gapLabel: (t: ColorTokens) => TextStyle;
+  /** iOS/web dim the cell on press; Android uses a ripple instead (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over a pressed cell; null on iOS/web. */
+  ripple?: (t: ColorTokens, selected: boolean) => { color: string; borderless: boolean };
+}
+
+// --- shared size scales (brand type/sizing, identical across platforms) ------
+
+// Square-ish button footprint per size: height + matching min width + the
+// horizontal pad (`h-8 min-w-8 px-2` / `h-9 min-w-9 px-2.5` / `h-10 min-w-10 px-3`).
+export const itemSize: Record<Size, ViewStyle> = {
+  small: { height: 32, minWidth: 32, paddingHorizontal: 8 },
+  default: { height: 36, minWidth: 36, paddingHorizontal: 10 },
+  large: { height: 40, minWidth: 40, paddingHorizontal: 12 },
+};
+
+// Label type per size (`text-xs` for small, `text-sm` otherwise).
+export const labelSize: Record<Size, TextStyle> = {
+  small: { fontSize: 12, lineHeight: 16 },
+  default: { fontSize: 14, lineHeight: 20 },
+  large: { fontSize: 14, lineHeight: 20 },
+};
+
+// --- shared layout fragments (color-free; identical across platforms) --------
+
+// Row of [prev, numbers, next] for the numbered default (`gap-1`).
+export const numberedRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 4 };
+
+// Compact row: Prev/Next bracketing the "Page X of N" label (`gap-2`).
+export const compactRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 8 };
+
+// With-size outer row: the selector group, the indicator, and the controls (`gap-4`).
+export const withSizeRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 16 };
+
+// The "Rows per page" label + selector cluster (`gap-2`).
+export const selectorCluster: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 8 };
+
+// The Prev/Next pair inside the with-size row (`gap-1`).
+export const controlPair: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 4 };
+
+// The centered-row base every cell shares (the skin layers fill/border/radius on top).
+const CELL_ROW: ViewStyle = { flexDirection: "row", alignItems: "center", justifyContent: "center" };
+
+// =============================================================================
+// Web: the established Canvas look (lifted verbatim from the original file).
+// =============================================================================
+
+export const webSkin: PaginationSkin = {
+  // A Prev/Next chevron control: a square bordered box on the background fill
+  // (`rounded-md border border-input bg-background`).
+  controlBox(t) {
+    return {
+      ...CELL_ROW,
+      borderRadius: 6,
+      borderWidth: 1,
+      borderColor: t.input,
+      backgroundColor: t.background,
+    };
+  },
+  // A numbered page button. Selected uses the primary fill/border; the rest match
+  // the bordered background box (`border-primary bg-primary` vs `border-input bg-background`).
+  pageBox(t, selected) {
+    return {
+      ...CELL_ROW,
+      borderRadius: 6,
+      borderWidth: 1,
+      borderColor: selected ? t.primary : t.input,
+      backgroundColor: selected ? t.primary : t.background,
+    };
+  },
+  // The size selector trigger: value + caret pushed apart in a bordered box
+  // (`flex-row items-center justify-between gap-1 rounded-md border border-input bg-background`).
+  selectorBox(t) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: 4,
+      borderRadius: 6,
+      borderWidth: 1,
+      borderColor: t.input,
+      backgroundColor: t.background,
+    };
+  },
+  // Control glyph / selector value color (`font-medium text-foreground`).
+  controlLabel(t) {
+    return { fontWeight: "500", color: t.foreground };
+  },
+  // A numbered page label: medium weight, primary-foreground when selected
+  // (`font-medium` + `text-primary-foreground` / `text-foreground`).
+  pageLabel(t, selected) {
+    return { fontWeight: "500", color: selected ? t["primary-foreground"] : t.foreground };
+  },
+  // Muted supporting text (`text-muted-foreground`).
+  mutedLabel(t) {
+    return { color: t["muted-foreground"] };
+  },
+  // The truncation ellipsis: muted, with a small horizontal inset (`px-1`).
+  gapLabel(t) {
+    return { paddingHorizontal: 4, color: t["muted-foreground"] };
+  },
+  pressedOpacity: 0.9,
+};
+
+// =============================================================================
+// iOS (HIG page controls): pill-rounded cells, the active page filled primary.
+// =============================================================================
+
+export const iosSkin: PaginationSkin = {
+  // Pill-rounded (radius 8), no border; the chevron reads as a plain glyph on the
+  // background so the numbered cells carry the shape.
+  controlBox(t) {
+    return {
+      ...CELL_ROW,
+      borderRadius: 8,
+      backgroundColor: t.background,
+    };
+  },
+  // The active page is a filled `primary` pill (radius 8); inactive pages are
+  // plain background pills with no border (HIG dots: filled current, hollow rest).
+  pageBox(t, selected) {
+    return {
+      ...CELL_ROW,
+      borderRadius: 8,
+      backgroundColor: selected ? t.primary : t.background,
+    };
+  },
+  // The rows-per-page selector: a muted-filled pill trigger (radius 8), value +
+  // caret pushed apart, no border (iOS controls favor fills over outlines).
+  selectorBox(t) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: 4,
+      borderRadius: 8,
+      backgroundColor: t.muted,
+    };
+  },
+  controlLabel(t) {
+    // SF-scale control glyph reads slightly heavier on iOS.
+    return { fontWeight: "600", color: t.foreground };
+  },
+  pageLabel(t, selected) {
+    return { fontWeight: "600", color: selected ? t["primary-foreground"] : t.foreground };
+  },
+  mutedLabel(t) {
+    return { color: t["muted-foreground"] };
+  },
+  gapLabel(t) {
+    return { paddingHorizontal: 4, color: t["muted-foreground"] };
+  },
+  pressedOpacity: 0.8,
+};
+
+// =============================================================================
+// Android (Material 3): flat cells, the active page a tonal primary fill.
+// =============================================================================
+
+export const androidSkin: PaginationSkin = {
+  // Flat cell (radius 8), no border, transparent over the surface; the ripple is
+  // the press feedback.
+  controlBox() {
+    return {
+      ...CELL_ROW,
+      borderRadius: 8,
+      backgroundColor: "transparent",
+    };
+  },
+  // The active page is a tonal fill (secondaryContainer ≈ alpha(primary, .12)),
+  // M3's selected-cell treatment; inactive pages are flat/transparent.
+  pageBox(t, selected) {
+    return {
+      ...CELL_ROW,
+      borderRadius: 8,
+      backgroundColor: selected ? alpha(t.primary, 0.12) : "transparent",
+    };
+  },
+  // The selector trigger: a flat tonal pill (alpha(primary, .08)) with the value
+  // and caret pushed apart; the ripple supplies the press feedback.
+  selectorBox(t) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: 4,
+      borderRadius: 8,
+      backgroundColor: alpha(t.primary, 0.08),
+    };
+  },
+  controlLabel(t) {
+    return { fontWeight: "500", color: t.foreground };
+  },
+  pageLabel(t, selected) {
+    // labelMedium; the active page reads in brand indigo (onSecondaryContainer ≈ primary).
+    return { fontWeight: "500", color: selected ? t.primary : t.foreground };
+  },
+  mutedLabel(t) {
+    return { color: t["muted-foreground"] };
+  },
+  gapLabel(t) {
+    return { paddingHorizontal: 4, color: t["muted-foreground"] };
+  },
+  pressedOpacity: null, // Android uses a ripple instead
+  ripple: (t) => ({ color: alpha(t.primary, 0.12), borderless: false }),
+};

package/src/atoms/pagination/pagination.tsx

@@ -0,0 +1,6 @@
+import { createPagination } from "./pagination.shared.js";
+import { webSkin } from "./pagination.styles.js";
+
+// Web Pagination (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Pagination = createPagination(webSkin);
+export type { PaginationProps } from "./pagination.shared.js";

package/src/atoms/popover/popover.android.tsx

@@ -0,0 +1,8 @@
+import { createPopover } from "./popover.shared.js";
+import { androidSkin } from "./popover.styles.js";
+
+// Android (elevated surface) Popover. Material 3 has no native popover, so this
+// uses an elevated menu/dialog-style surface. Metro resolves this file on Android;
+// the docs import it for preview.
+export const Popover = createPopover(androidSkin);
+export type { PopoverProps } from "./popover.shared.js";

package/src/atoms/popover/popover.ios.tsx

@@ -0,0 +1,6 @@
+import { createPopover } from "./popover.shared.js";
+import { iosSkin } from "./popover.styles.js";
+
+// iOS (HIG popover) Popover. Metro resolves this file on iOS; the docs import it for preview.
+export const Popover = createPopover(iosSkin);
+export type { PopoverProps } from "./popover.shared.js";

package/src/atoms/popover/popover.md

@@ -0,0 +1,87 @@
+# Popover
+
+Floating panel for rich content triggered by a click.
+
+## Usage
+
+```tsx
+<Popover
+  trigger="Open popover"
+  title="Popover"
+  description="Place your rich content, form fields, or secondary actions here."
+  actionLabel="Close"
+/>
+```
+
+## Do & Don't
+
+**Do** — Keep popovers compact: a focused prompt with one input and a clear action.
+
+```tsx
+<View style={{ borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 16, ...shadow("md"), alignSelf: "flex-start", minWidth: 240 }}>
+  <Text style={{ marginBottom: 8, fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Rename this project?</Text>
+  <Input value="Identity Platform" style={{ marginBottom: 8 }} />
+  <View style={{ flexDirection: "row", justifyContent: "flex-end", gap: 8 }}>
+    <Button outline small>Cancel</Button>
+    <Button primary small>Rename</Button>
+  </View>
+</View>
+```
+
+**Don't** — A full form belongs in a dialog; in a floating popover it is cramped and easy to dismiss by accident.
+
+```tsx
+<View style={{ borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 16, ...shadow("md"), alignSelf: "flex-start", minWidth: 260 }}>
+  <Field label="Name" placeholder="Ada Lovelace" style={{ marginBottom: 8 }} />
+  <Field label="Email" placeholder="ada@canvas.dev" style={{ marginBottom: 8 }} />
+  <View style={{ marginBottom: 8 }}>
+    <Text style={{ marginBottom: 6, fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Role</Text>
+    <Select value="Engineer" options={["Engineer", "Designer", "Manager"]} />
+  </View>
+  <Field label="Team" placeholder="Identity Platform" style={{ marginBottom: 8 }} />
+  <View style={{ flexDirection: "row", justifyContent: "flex-end", gap: 8 }}>
+    <Button outline small>Cancel</Button>
+    <Button primary small>Save</Button>
+  </View>
+</View>
+```
+
+### Triggered
+
+**Do** — Wrap the trigger in a relative anchor and dismiss on outside click so the panel positions and closes predictably.
+
+```tsx
+<Popover trigger="Open popover" open description="Anchored to the trigger, closes on outside click." actionLabel="Close" />
+```
+
+**Don't** — A trigger with no relative anchor and no way to dismiss leaves the panel floating loose and stuck open.
+
+```tsx
+<View style={{ alignSelf: "flex-start" }}>
+  <Button outline small>Open popover</Button>
+  <View style={{ borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 16, ...shadow("md"), marginTop: 8, minWidth: 240 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>No anchor, no dismiss, no Close.</Text>
+  </View>
+</View>
+```
+
+### Inline
+
+**Do** — Reserve the static panel for a brief always-on message with a single follow-up action.
+
+```tsx
+<Popover inline description="Saved to drafts. Publish when ready." actionLabel="Publish" />
+```
+
+**Don't** — An always-visible panel that scrolls internally is doing a card's or section's job; use the panel chrome only for short content.
+
+```tsx
+<View style={{ borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 16, ...shadow("md"), maxHeight: 120, minWidth: 260, overflow: "hidden" }}>
+  <ScrollView style={{ maxHeight: 88 }}>
+    <Field label="Street" placeholder="100 Market St" style={{ marginBottom: 8 }} />
+    <Field label="City" placeholder="San Francisco" style={{ marginBottom: 8 }} />
+    <Field label="Region" placeholder="California" style={{ marginBottom: 8 }} />
+    <Field label="Postal code" placeholder="94105" style={{ marginBottom: 8 }} />
+  </ScrollView>
+</View>
+```