@olympusoss/canvas 4.0.0 → 5.0.0

package/src/atoms/listbox/listbox.md

@@ -0,0 +1,177 @@
+# Listboxes
+
+A custom (non-native) select: single or multi-select, optional avatars or icons per option, and a checkmark on the chosen items. Reach for it when a native select can't show rich options; prefer a native select for simple short lists.
+
+## Usage
+
+```tsx
+<Listbox
+  items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: false },
+    { label: "Design", selected: false },
+    { label: "Platform", selected: false },
+    { label: "Security", selected: false }
+  ]}
+  bordered
+/>
+```
+
+## Variants
+
+### Mode - multi
+
+```tsx
+<Listbox
+  items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: false },
+    { label: "Design", selected: true },
+    { label: "Platform", selected: false },
+    { label: "Security", selected: false }
+  ]}
+  multi
+  bordered
+/>
+```
+
+### Size - sm
+
+```tsx
+<Listbox
+  items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: false },
+    { label: "Design", selected: false },
+    { label: "Platform", selected: false },
+    { label: "Security", selected: false }
+  ]}
+  bordered
+  small
+/>
+```
+
+### Size - lg
+
+```tsx
+<Listbox
+  items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: false },
+    { label: "Design", selected: false },
+    { label: "Platform", selected: false },
+    { label: "Security", selected: false }
+  ]}
+  bordered
+  large
+/>
+```
+
+### Avatars
+
+```tsx
+<Listbox
+  items={[
+    { label: "Rachel Chen", detail: "rachel@acme.io", selected: true },
+    { label: "Ada Lovelace", detail: "ada@acme.io", selected: false },
+    { label: "Kevin Turner", detail: "kevin@acme.io", selected: false },
+    { label: "Linus Berg", detail: "linus@acme.io", selected: false }
+  ]}
+  bordered
+/>
+```
+
+### Disabled
+
+```tsx
+<Listbox
+  items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: false },
+    { label: "Design", selected: false },
+    { label: "Platform", selected: false },
+    { label: "Security", selected: false }
+  ]}
+  bordered
+  disabled
+/>
+```
+
+## Do & Don't
+
+### Prefer a native select for simple lists
+
+**Do** — For short, plain lists a native select is lighter, accessible, and uses the platform picker on mobile.
+
+```tsx
+<Select open value="Yes" options={["Yes", "No"]} style={{ width: 192 }} />
+```
+
+**Don't** — A custom listbox for two short options is heavier than it needs to be and worse on mobile.
+
+```tsx
+<Listbox bordered style={{ width: 192 }} items={[
+    { label: "Yes", selected: true },
+    { label: "No" }
+  ]} />
+```
+
+### single
+
+**Do** — Show exactly one checkmark, mirror it in the trigger value, and close the panel on pick.
+
+```tsx
+<Listbox bordered style={{ width: 224 }} items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend" },
+    { label: "Design" },
+    { label: "Platform" }
+  ]} />
+```
+
+**Don't** — Single-select with two checkmarks lies about state: only one option can be the value.
+
+```tsx
+<Listbox bordered style={{ width: 224 }} items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: true },
+    { label: "Design" },
+    { label: "Platform" }
+  ]} />
+```
+
+### multi
+
+**Do** — Keep the panel open, toggle each option's own checkmark, and summarize the count in the trigger.
+
+```tsx
+<View style={{ width: 224, gap: 4 }}>
+  <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, height: 36 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>3 selected</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>▾</Text>
+  </View>
+  <Listbox multi bordered items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: true },
+    { label: "Design" },
+    { label: "Platform", selected: true }
+  ]} />
+</View>
+```
+
+**Don't** — Don't close on each pick or echo only the last choice: multi-select needs to keep all selections visible.
+
+```tsx
+<View style={{ width: 224, gap: 4 }}>
+  <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, height: 36 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Backend</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>▾</Text>
+  </View>
+  <Listbox multi bordered items={[
+    { label: "Backend", selected: true },
+    { label: "Frontend", selected: true },
+    { label: "Design" },
+    { label: "Platform", selected: true }
+  ]} />
+</View>
+```

package/src/atoms/listbox/listbox.styles.ts

@@ -0,0 +1,60 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Listbox styles. Layout-only fragments are static objects; anything
+// that reads a color is a function of the active tokens (so the bordered surface,
+// the selected/press fill, and the label/detail colors follow light/dark and the
+// glass surface via tokens.popover/accent). The component resolves its mode and
+// size axes and spreads these.
+
+export type Mode = "single" | "multi";
+export type Size = "small" | "medium" | "large";
+
+// A bordered container reads as a popover surface: rounded card, hairline border,
+// popover fill (translucent under glass), and a 4px inset so rows don't touch the
+// edge.
+export function containerBordered(tokens: ColorTokens): ViewStyle {
+  return { borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 4 };
+}
+
+// Each row: a horizontal Pressable with a leading control, the label/detail
+// stack, and (added by the component) a subtle press-state fill. Size adds the
+// vertical padding.
+export const rowBase: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2 };
+
+// Per-row padding by size: small reads like the legacy h-8 trigger, medium like
+// h-9, large like h-10.
+export const rowSize: Record<Size, ViewStyle> = {
+  small: { paddingHorizontal: 8, paddingVertical: 6 },
+  medium: { paddingHorizontal: 8, paddingVertical: 8 },
+  large: { paddingHorizontal: 8, paddingVertical: 10 },
+};
+
+// The accent fill used for a selected single-select row and the press state.
+export function rowSelected(tokens: ColorTokens): ViewStyle {
+  return { backgroundColor: tokens.accent };
+}
+
+// Single-select checkmark column: a fixed-width gutter reserved on every row so
+// labels stay aligned whether or not the row is selected.
+export function checkmark(tokens: ColorTokens): TextStyle {
+  return { width: 16, fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// The label/detail stack grows to fill the remaining row width.
+export const textStack: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// Label type per size (small is smaller; medium and large share the body size).
+const LABEL_TYPE: Record<Size, TextStyle> = {
+  small: { fontSize: 12, lineHeight: 16 },
+  medium: { fontSize: 14, lineHeight: 20 },
+  large: { fontSize: 14, lineHeight: 20 },
+};
+
+export function label(tokens: ColorTokens, size: Size): TextStyle {
+  return { color: tokens.foreground, ...LABEL_TYPE[size] };
+}
+
+export function detail(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] };
+}

package/src/atoms/listbox/listbox.tsx

@@ -0,0 +1,113 @@
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Checkbox } from "../checkbox/checkbox.js";
+import * as s from "./listbox.styles.js";
+import { type Mode, type Size } from "./listbox.styles.js";
+
+// An inline, selectable list of options rendered directly (not a popover). Each
+// row is a Pressable. Two selection modes, mutually exclusive:
+//
+// 1. Single-select (default): the chosen row is filled with the accent and shows
+//    a leading checkmark ("✓"); at most one row is the value.
+// 2. Multi-select (`multi`): every row carries a leading Checkbox reflecting its
+//    own selected state, and any number of rows may be selected at once.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf). `multi` switches the
+// selection mode; `bordered` wraps the list in a rounded popover-surface card.
+
+export interface ListboxItem {
+  /** The option's primary text. */
+  label: string;
+  /** Optional secondary text shown under the label in a muted tone. */
+  detail?: string;
+  /** Whether this option is currently selected. */
+  selected?: boolean;
+}
+
+export interface ListboxProps {
+  /** The options to render, top to bottom. */
+  items: ListboxItem[];
+  /** Multi-select: each row gets a leading Checkbox instead of a single ✓. */
+  multi?: boolean;
+  /** Wrap the list in a rounded, bordered popover-surface card. */
+  bordered?: boolean;
+  // Size (pick one; default is medium).
+  /** Tighter rows with smaller text. */
+  small?: boolean;
+  /** Taller rows. */
+  large?: boolean;
+  /** Dim the list and block selection. */
+  disabled?: boolean;
+  /** Fired with the pressed option's index. */
+  onSelect?: (index: number) => void;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Selection mode precedence when more than one axis prop is passed: first match
+// wins. Only `multi` competes here; the default is single-select.
+function modeOf(p: ListboxProps): Mode {
+  if (p.multi) return "multi";
+  return "single";
+}
+
+// Size precedence when more than one is passed: first match wins (small over
+// large). The default is medium.
+function sizeOf(p: ListboxProps): Size {
+  if (p.small) return "small";
+  if (p.large) return "large";
+  return "medium";
+}
+
+export function Listbox(props: ListboxProps) {
+  const { items, bordered, disabled, onSelect, style } = props;
+  const mode = modeOf(props);
+  const size = sizeOf(props);
+  const { tokens } = useTheme();
+
+  const container: StyleProp<ViewStyle> = [
+    bordered ? s.containerBordered(tokens) : null,
+    disabled ? { opacity: 0.5 } : null,
+    style,
+  ];
+
+  return (
+    <View style={container} accessibilityRole="list">
+      {items.map((item, index) => {
+        const selected = !!item.selected;
+        // Single-select fills the chosen row; multi-select leaves the row plain
+        // and reflects state in the leading Checkbox instead.
+        const rowBase: StyleProp<ViewStyle> = [
+          s.rowBase,
+          s.rowSize[size],
+          mode === "single" && selected ? s.rowSelected(tokens) : null,
+        ];
+
+        return (
+          <Pressable
+            key={index}
+            // The press fill (the old `active:bg-accent`) is the accent, applied
+            // only when the list is enabled.
+            style={({ pressed }) => [rowBase, !disabled && pressed ? s.rowSelected(tokens) : null]}
+            onPress={disabled ? undefined : () => onSelect?.(index)}
+            disabled={disabled}
+            accessibilityRole={mode === "multi" ? "checkbox" : "menuitem"}
+            accessibilityState={{ selected, disabled: !!disabled }}
+          >
+            {mode === "multi" ? (
+              <Checkbox checked={selected} />
+            ) : (
+              // Reserve the checkmark column on every row so labels stay aligned
+              // whether or not the row is selected.
+              <Text style={s.checkmark(tokens)}>{selected ? "✓" : ""}</Text>
+            )}
+            <View style={s.textStack}>
+              <Text style={s.label(tokens, size)}>{item.label}</Text>
+              {item.detail != null ? <Text style={s.detail(tokens)}>{item.detail}</Text> : null}
+            </View>
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}

package/src/atoms/pagination/pagination.android.tsx

@@ -0,0 +1,6 @@
+import { createPagination } from "./pagination.shared.js";
+import { androidSkin } from "./pagination.styles.js";
+
+// Material 3 Pagination. Metro resolves this file on Android; the docs import it for preview.
+export const Pagination = createPagination(androidSkin);
+export type { PaginationProps } from "./pagination.shared.js";

package/src/atoms/pagination/pagination.ios.tsx

@@ -0,0 +1,6 @@
+import { createPagination } from "./pagination.shared.js";
+import { iosSkin } from "./pagination.styles.js";
+
+// iOS (HIG page controls) Pagination. Metro resolves this file on iOS; the docs import it for preview.
+export const Pagination = createPagination(iosSkin);
+export type { PaginationProps } from "./pagination.shared.js";

package/src/atoms/pagination/pagination.md

@@ -0,0 +1,133 @@
+# Pagination
+
+Page-of-N navigation for tables and lists.
+
+## Usage
+
+```tsx
+<Pagination page={2} total={12} compact pageSize={10} pageSizes={[10, 25, 50]} />
+```
+
+## Variants
+
+### Variant - numbered
+
+```tsx
+<Pagination page={2} total={12} pageSize={10} pageSizes={[10, 25, 50]} />
+```
+
+### Variant - with-size
+
+```tsx
+<Pagination page={2} total={12} withSize pageSize={10} pageSizes={[10, 25, 50]} />
+```
+
+## Do & Don't
+
+### compact
+
+**Do** — Pair the buttons with a "Showing X–Y of N" range so position and total are always visible.
+
+```tsx
+<Pagination compact page={2} total={12} />
+```
+
+**Don't** — Bare Previous/Next with no range label leaves the user unable to tell where they are or how much is left.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", justifyContent: "flex-end", gap: 4 }}>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Previous page">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>‹</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Next page">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>›</Text>
+  </Pressable>
+</View>
+```
+
+### numbered
+
+**Do** — Truncate the middle with an ellipsis; keep first, last, and a window around the current page.
+
+```tsx
+<Pagination page={2} total={12} />
+```
+
+**Don't** — Rendering every page number overflows and stops being scannable past a handful.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, opacity: 0.5 }} accessibilityRole="button" accessibilityLabel="Previous page">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>‹</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.primary, backgroundColor: tokens.primary }} accessibilityRole="button" accessibilityLabel="Page 1">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["primary-foreground"] }}>1</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 2">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>2</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 3">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>3</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 4">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>4</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 5">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>5</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 6">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>6</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 7">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>7</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 8">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>8</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 9">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>9</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 10">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>10</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 11">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>11</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Page 12">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>12</Text>
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Next page">
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>›</Text>
+  </Pressable>
+</View>
+```
+
+### with-size
+
+**Do** — Show "Page X of N" beside the size selector and reset to page 1 when the size changes.
+
+```tsx
+<Pagination withSize page={2} total={12} pageSize={10} pageSizes={[10, 25, 50]} />
+```
+
+**Don't** — Offering a page-size selector without a page indicator hides which page the new size landed on.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 16 }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Rows per page</Text>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 4, height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Rows per page">
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>10</Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>▾</Text>
+    </Pressable>
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, opacity: 0.5 }} accessibilityRole="button" accessibilityLabel="Previous page">
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>‹</Text>
+    </Pressable>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 36, minWidth: 36, paddingHorizontal: 10, borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background }} accessibilityRole="button" accessibilityLabel="Next page">
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>›</Text>
+    </Pressable>
+  </View>
+</View>
+```