@olympusoss/canvas 3.2.1 → 5.0.0

package/src/organisms/sidebar/sidebar.shared.tsx

@@ -0,0 +1,167 @@
+import { type GestureResponderEvent } from "react-native";
+import { View, Pressable, Text, useTheme, type ColorTokens, type StyleProp, type ViewStyle, type TextStyle } from "../../style/index.js";
+import { Badge } from "../../atoms/badge/badge.js";
+import { type Density, type Frame } from "./sidebar.styles.js";
+
+// Shared Sidebar shell. The structure (the outer column, the titled sections, the
+// nav rows with their leading icon / label / trailing badge, the single active
+// highlight), the section normalization, the flat-index active matching, the
+// density/frame precedence, the accessibility, and the select handler live here
+// once; a platform file supplies only its skin (the row shape, the selected-row
+// highlight + label/icon color, the section heading, the frame, the press
+// feedback) and calls createSidebar.
+//
+// A sidebar is the vertical app-navigation panel that runs down the left of a
+// layout: an optional list of titled sections, each holding nav rows. A row is a
+// leading icon glyph + label, with at most one row carrying the active highlight
+// and the rest sitting inactive. Rows may carry a trailing count <Badge>.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf).
+//
+// - Density axis (pick one; default is the comfortable row): `compact` tightens
+//   each row's padding and drops the type a step for dense navigation.
+// - Frame axis (pick one; default is the flush, right-bordered column that docks
+//   against the page): `bordered`/`floating` lift the panel into a fully bordered,
+//   rounded card surface. `bordered` wins over `floating` when both are passed.
+
+// The platform-varying surface. Everything color/shape-bearing the rows, the
+// frame, and the section heading need lives here, built from the active tokens
+// (so each follows light/dark and the glass surface).
+export interface SidebarSkin {
+  /** Web paints the accent fill on a pressed (non-active) row; iOS/Android don't. */
+  pressedFill: boolean;
+  /** iOS dims the row on press; web/Android don't (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over a pressed row; null on iOS/web. */
+  ripple: ((t: ColorTokens) => { color: string; borderless: boolean }) | null;
+
+  /** The outer navigation column, per frame. */
+  column: (t: ColorTokens, frame: Frame) => ViewStyle;
+  /** A titled group of nav rows. */
+  group: ViewStyle;
+  /** The section heading above a group. */
+  sectionTitle: (t: ColorTokens) => TextStyle;
+  /** The nav-row container (shape + density padding). */
+  row: (t: ColorTokens, density: Density) => ViewStyle;
+  /** The selected-row highlight fill (null when not active). */
+  rowFill: (t: ColorTokens, active: boolean) => ViewStyle | null;
+  /** The row label (flex, type, color), per active state + density. */
+  label: (t: ColorTokens, active: boolean, density: Density) => TextStyle;
+  /** The leading icon glyph color/size, per active state. */
+  icon: (t: ColorTokens, active: boolean) => TextStyle;
+}
+
+/** One nav row: a label, an optional leading icon glyph, an optional count. */
+export interface SidebarItem {
+  /** Row label (e.g. "Dashboard"). */
+  label: string;
+  /** Leading icon glyph rendered before the label (e.g. an emoji or symbol). */
+  icon?: string;
+  /** Trailing count rendered as a <Badge> (e.g. "12"). */
+  badge?: string;
+}
+
+/** A titled group of nav rows. */
+export interface SidebarSection {
+  /** Optional muted heading shown above the group. */
+  title?: string;
+  /** Rows in this group. */
+  items: SidebarItem[];
+}
+
+export interface SidebarProps {
+  /** Titled sections of nav rows. Use this or the flat `items` array. */
+  sections?: SidebarSection[];
+  /** Flat list of nav rows, wrapped into a single untitled section. */
+  items?: SidebarItem[];
+  /** The active row, by label or by flat index across all rows. */
+  active?: string | number;
+  /** Fired with the selected row and its flat index across all sections. */
+  onSelect?: (item: SidebarItem, index: number, event: GestureResponderEvent) => void;
+  // Density (pick one; default is the comfortable row).
+  compact?: boolean;
+  // Frame (pick one; default is the flush right-bordered column).
+  bordered?: boolean;
+  floating?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Density precedence when more than one is passed: first match wins.
+function densityOf(p: SidebarProps): Density {
+  if (p.compact) return "compact";
+  return "default";
+}
+
+// Frame precedence when more than one is passed: first match wins.
+function frameOf(p: SidebarProps): Frame {
+  if (p.bordered) return "bordered";
+  if (p.floating) return "bordered";
+  return "flush";
+}
+
+/** Build a Sidebar component from a platform skin. */
+export function createSidebar(skin: SidebarSkin) {
+  return function Sidebar(props: SidebarProps) {
+    const { sections, items, active, onSelect, style } = props;
+    const density = densityOf(props);
+    const frame = frameOf(props);
+    const { tokens } = useTheme();
+
+    // Normalize to a sections list; a flat `items` array becomes one untitled
+    // section. Sections always win when both are supplied.
+    const groups: SidebarSection[] = sections ?? (items ? [{ items }] : []);
+
+    // Active match is by label or by flat index across every row in order.
+    const isActive = (item: SidebarItem, flatIndex: number): boolean => {
+      if (active == null) return false;
+      if (typeof active === "number") return active === flatIndex;
+      return active === item.label;
+    };
+
+    // Running flat index so label/index matching and onSelect agree across groups.
+    let flat = -1;
+
+    return (
+      <View style={[skin.column(tokens, frame), style]}>
+        {groups.map((section, gi) => (
+          <View key={gi} style={skin.group}>
+            {section.title != null ? (
+              <Text style={skin.sectionTitle(tokens)}>{section.title}</Text>
+            ) : null}
+            {section.items.map((item) => {
+              flat += 1;
+              const index = flat;
+              const activeRow = isActive(item, index);
+              return (
+                <Pressable
+                  key={index}
+                  android_ripple={skin.ripple ? skin.ripple(tokens) : undefined}
+                  style={({ pressed }) => [
+                    skin.row(tokens, density),
+                    // The active row carries its highlight persistently; on web a
+                    // press paints it too (the old `active:bg-accent`).
+                    skin.rowFill(tokens, activeRow || (skin.pressedFill && pressed)),
+                    skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+                  ]}
+                  onPress={(event) => onSelect?.(item, index, event)}
+                  accessibilityRole="button"
+                  accessibilityState={{ selected: activeRow }}
+                >
+                  {item.icon != null ? (
+                    <Text style={skin.icon(tokens, activeRow)}>{item.icon}</Text>
+                  ) : null}
+                  <Text style={skin.label(tokens, activeRow, density)} numberOfLines={1}>
+                    {item.label}
+                  </Text>
+                  {item.badge != null ? <Badge secondary>{item.badge}</Badge> : null}
+                </Pressable>
+              );
+            })}
+          </View>
+        ))}
+      </View>
+    );
+  };
+}

package/src/organisms/sidebar/sidebar.styles.ts

@@ -0,0 +1,262 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, alpha } from "../../style/index.js";
+import { type SidebarSkin } from "./sidebar.shared.js";
+
+// Co-located Sidebar skins, one per platform. The shell resolves the density and
+// frame axes, the section grouping, the flat-index active matching, the badges,
+// and the select handler; the skin supplies only the native SHAPE of the nav row
+// (its radius and height), the selected-row highlight (fill + label/icon color),
+// the section heading, the frame (outer column), and the press feedback. The
+// BRAND survives on every platform (the indigo `primary`/`accent` tokens, never a
+// platform default), so each follows light/dark and the glass surface.
+//
+//   iOS 27 (Liquid Glass) sidebar: grouped rows; the SELECTED row is a CAPSULE
+//     highlight (radius 9999) filled with the light-gray `accent`, label in
+//     `accent-foreground`, while the leading icon stays TINTED in `primary`;
+//     section headers ~13pt 600 muted; ~36pt rows; press = opacity dim (0.8).
+//   Android (M3 navigation drawer): each nav item is a fully-rounded PILL (radius
+//     9999); the ACTIVE item is a tonal `alpha(primary, 0.12)` pill with the icon
+//     + label in brand `primary`; inactive transparent with `foreground`; ~56dp
+//     item height; press = android_ripple.
+//   Web: the established Canvas look (row radius 6, `accent` fill on the active OR
+//     pressed row, foreground/muted label + icon), lifted verbatim from the
+//     original file.
+
+export type Density = "default" | "compact";
+export type Frame = "flush" | "bordered";
+
+// =============================================================================
+// Web: the established Canvas look (lifted verbatim from the original file).
+// =============================================================================
+
+export const webSkin: SidebarSkin = {
+  // Web carries no row ripple; the active-row affordance is the accent fill, also
+  // applied while a row is pressed (the old `active:bg-accent`).
+  pressedFill: true,
+  pressedOpacity: null,
+  ripple: null,
+
+  // Fixed-width column with the standard inset (gap-4 p-2) on the background fill.
+  // The flush frame docks against the page with a single right hairline; the
+  // bordered/floating frame lifts it into a fully ruled, rounded, clipped card.
+  column(tokens, frame) {
+    const base: ViewStyle = {
+      width: 240,
+      backgroundColor: tokens.background,
+      gap: 16,
+      padding: 8,
+    };
+    if (frame === "bordered") {
+      return { ...base, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, overflow: "hidden" };
+    }
+    return { ...base, borderRightWidth: 1, borderColor: tokens.border };
+  },
+
+  // A titled group of nav rows.
+  group: { gap: 4 },
+
+  // The uppercase, muted, wide-tracked section heading above a group.
+  sectionTitle(tokens) {
+    return {
+      paddingHorizontal: 12,
+      paddingVertical: 4,
+      fontSize: 12,
+      lineHeight: 16,
+      fontWeight: "500",
+      textTransform: "uppercase",
+      letterSpacing: 0.8,
+      color: tokens["muted-foreground"],
+    };
+  },
+
+  // Row container layout per density: a centered icon/label/badge row with the
+  // medium pill radius. The comfortable row matches the documented px-3 py-2;
+  // compact tightens the vertical inset for dense navigation.
+  row(_tokens, density) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      gap: 12,
+      borderRadius: 6,
+      paddingHorizontal: 12,
+      paddingVertical: density === "compact" ? 6 : 8,
+    };
+  },
+
+  // The accent fill carried by the active row (and the pressed affordance).
+  rowFill(tokens, active) {
+    return active ? { backgroundColor: tokens.accent } : null;
+  },
+
+  // Label fills the remaining row width (flex-1), truncates to one line, and is
+  // medium-weight foreground when active else muted.
+  label(tokens, active, density) {
+    return {
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: "0%",
+      ...(density === "compact" ? { fontSize: 12, lineHeight: 16 } : { fontSize: 14, lineHeight: 20 }),
+      ...(active ? { fontWeight: "500", color: tokens.foreground } : { color: tokens["muted-foreground"] }),
+    };
+  },
+
+  // The leading icon glyph: text-base, foreground when active else muted.
+  icon(tokens, active) {
+    return { fontSize: 16, lineHeight: 24, color: active ? tokens.foreground : tokens["muted-foreground"] };
+  },
+};
+
+// =============================================================================
+// iOS 27 (Liquid Glass) sidebar: grouped rows; the selected row is a CAPSULE
+// highlight (radius 9999) filled with the light-gray `accent`, label in
+// `accent-foreground`, with the leading icon staying TINTED in `primary`. ~36pt
+// rows, ~13pt 600 section headers, press = opacity dim.
+// =============================================================================
+
+export const iosSkin: SidebarSkin = {
+  pressedFill: false, // iOS dims on press instead of painting the accent fill
+  pressedOpacity: 0.8,
+  ripple: null,
+
+  column(tokens, frame) {
+    const base: ViewStyle = {
+      width: 240,
+      backgroundColor: tokens.background,
+      gap: 16,
+      padding: 8,
+    };
+    if (frame === "bordered") {
+      return { ...base, borderRadius: 10, borderWidth: 1, borderColor: tokens.border, overflow: "hidden" };
+    }
+    return { ...base, borderRightWidth: 1, borderColor: tokens.border };
+  },
+
+  group: { gap: 2 },
+
+  // HIG grouped-list header: ~13pt, semibold, secondary/muted, not uppercase.
+  sectionTitle(tokens) {
+    return {
+      paddingHorizontal: 12,
+      paddingVertical: 4,
+      fontSize: 13,
+      lineHeight: 18,
+      fontWeight: "600",
+      color: tokens["muted-foreground"],
+    };
+  },
+
+  // ~36pt row, fully-rounded CAPSULE (radius 9999) to match the iOS 27 highlight.
+  row(_tokens, density) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      gap: 10,
+      borderRadius: 9999,
+      paddingHorizontal: 12,
+      paddingVertical: density === "compact" ? 6 : 8,
+    };
+  },
+
+  // The selected row is a capsule highlight filled with the light-gray `accent`.
+  rowFill(tokens, active) {
+    return active ? { backgroundColor: tokens.accent } : null;
+  },
+
+  // Active label reads in `accent-foreground` (on the accent highlight); inactive
+  // sits in the standard foreground (HIG list rows are not muted when inactive).
+  label(tokens, active, density) {
+    return {
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: "0%",
+      ...(density === "compact" ? { fontSize: 14, lineHeight: 18 } : { fontSize: 15, lineHeight: 20 }),
+      fontWeight: active ? "600" : "400",
+      color: active ? tokens["accent-foreground"] : tokens.foreground,
+    };
+  },
+
+  // Icon glyph: always the brand `primary` tint, active or not. iOS 27 keeps the
+  // leading glyph tinted even on the selected capsule (HIG glyphs carry the tint).
+  icon(tokens, _active) {
+    return { fontSize: 17, lineHeight: 22, color: tokens.primary };
+  },
+};
+
+// =============================================================================
+// Android (Material 3 navigation drawer): each nav item is a fully-rounded PILL
+// (radius 9999); the active item is a tonal alpha(primary, 0.12) pill with the
+// icon + label in brand `primary`; inactive transparent with `foreground`.
+// ~56dp item height; press = android_ripple.
+// =============================================================================
+
+export const androidSkin: SidebarSkin = {
+  pressedFill: false, // Android uses a ripple instead of a pressed fill
+  pressedOpacity: null,
+  ripple: (tokens) => ({ color: alpha(tokens.primary, 0.12), borderless: false }),
+
+  column(tokens, frame) {
+    const base: ViewStyle = {
+      width: 240,
+      backgroundColor: tokens.background,
+      gap: 16,
+      // M3 drawer items inset 12dp from the sheet edge so the pill clears it.
+      paddingHorizontal: 12,
+      paddingVertical: 8,
+    };
+    if (frame === "bordered") {
+      return { ...base, borderRadius: 16, borderWidth: 1, borderColor: tokens.border, overflow: "hidden" };
+    }
+    return { ...base, borderRightWidth: 1, borderColor: tokens.border };
+  },
+
+  group: { gap: 2 },
+
+  // M3 drawer section header: titleSmall ~14sp, medium, muted, padded to align
+  // with the pill's inner edge.
+  sectionTitle(tokens) {
+    return {
+      paddingHorizontal: 16,
+      paddingVertical: 6,
+      fontSize: 14,
+      lineHeight: 20,
+      fontWeight: "500",
+      color: tokens["muted-foreground"],
+    };
+  },
+
+  // ~56dp item: a fully-rounded pill (radius 9999) with 16dp horizontal padding.
+  row(_tokens, density) {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      gap: 12,
+      borderRadius: 9999,
+      paddingHorizontal: 16,
+      // ~56dp comfortable / ~48dp compact (paddingVertical + ~24 line box).
+      paddingVertical: density === "compact" ? 12 : 16,
+    };
+  },
+
+  // The active item is a tonal pill: secondaryContainer ~ alpha(primary, 0.12).
+  rowFill(tokens, active) {
+    return active ? { backgroundColor: alpha(tokens.primary, 0.12) } : null;
+  },
+
+  // M3 drawer label: labelLarge ~14sp medium; active carries the brand `primary`,
+  // inactive the on-surface `foreground`.
+  label(tokens, active, density) {
+    return {
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: "0%",
+      ...(density === "compact" ? { fontSize: 13, lineHeight: 18 } : { fontSize: 14, lineHeight: 20 }),
+      fontWeight: "500",
+      color: active ? tokens.primary : tokens.foreground,
+    };
+  },
+
+  // Icon glyph: brand `primary` when active, on-surface `foreground` when not.
+  icon(tokens, active) {
+    return { fontSize: 18, lineHeight: 24, color: active ? tokens.primary : tokens.foreground };
+  },
+};

package/src/organisms/sidebar/sidebar.tsx

@@ -0,0 +1,6 @@
+import { createSidebar } from "./sidebar.shared.js";
+import { webSkin } from "./sidebar.styles.js";
+
+// Web Sidebar (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Sidebar = createSidebar(webSkin);
+export type { SidebarProps, SidebarItem, SidebarSection } from "./sidebar.shared.js";

package/src/organisms/stepper/stepper.android.tsx

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

package/src/organisms/stepper/stepper.ios.tsx

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

package/src/organisms/stepper/stepper.md

@@ -0,0 +1,150 @@
+# Steppers
+
+Multi-step progress indicators: horizontal, vertical, with progress.
+
+## Usage
+
+```tsx
+<Stepper
+  steps={[
+    { label: "Account", description: "Email verified and password set." },
+    { label: "Profile", description: "Add your name and avatar." },
+    { label: "Review", description: "Invite collaborators to your workspace." },
+    { label: "Done", description: "You're all set." }
+  ]}
+  current={1}
+  value={68}
+  label="Setup progress"
+/>
+```
+
+## Variants
+
+### Type - Vertical
+
+```tsx
+<Stepper
+  steps={[
+    { label: "Account", description: "Email verified and password set." },
+    { label: "Profile", description: "Add your name and avatar." },
+    { label: "Review", description: "Invite collaborators to your workspace." },
+    { label: "Done", description: "You're all set." }
+  ]}
+  current={1}
+  vertical
+  value={68}
+  label="Setup progress"
+/>
+```
+
+### Type - Progress bar
+
+```tsx
+<Stepper
+  steps={[
+    { label: "Account", description: "Email verified and password set." },
+    { label: "Profile", description: "Add your name and avatar." },
+    { label: "Review", description: "Invite collaborators to your workspace." },
+    { label: "Done", description: "You're all set." }
+  ]}
+  current={1}
+  progress
+  value={68}
+  label="Setup progress"
+/>
+```
+
+## Do & Don't
+
+### Horizontal
+
+**Do** — Mark exactly one step active; show completed steps filled and the rest pending.
+
+```tsx
+<Stepper current={1} steps={[
+    { label: "Account" },
+    { label: "Profile" },
+    { label: "Review" }
+  ]} />
+```
+
+**Don't** — Styling several steps as active at once hides which step the user is actually on.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "flex-start" }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+    <View style={{ alignItems: "center", gap: 6 }}>
+      <View style={{ height: 32, width: 32, flexShrink: 0, flexDirection: "row", alignItems: "center", justifyContent: "center", borderRadius: 9999, borderWidth: 2, borderColor: tokens.primary, backgroundColor: "transparent" }}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.primary }}>1</Text>
+      </View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens.foreground }}>Account</Text>
+    </View>
+    <View style={{ marginHorizontal: 8, marginTop: 16, height: 1, flexGrow: 1, flexShrink: 1, flexBasis: "0%", backgroundColor: tokens.border }} />
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+    <View style={{ alignItems: "center", gap: 6 }}>
+      <View style={{ height: 32, width: 32, flexShrink: 0, flexDirection: "row", alignItems: "center", justifyContent: "center", borderRadius: 9999, borderWidth: 2, borderColor: tokens.primary, backgroundColor: "transparent" }}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.primary }}>2</Text>
+      </View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens.foreground }}>Profile</Text>
+    </View>
+    <View style={{ marginHorizontal: 8, marginTop: 16, height: 1, flexGrow: 1, flexShrink: 1, flexBasis: "0%", backgroundColor: tokens.border }} />
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "flex-start" }}>
+    <View style={{ alignItems: "center", gap: 6 }}>
+      <View style={{ height: 32, width: 32, flexShrink: 0, flexDirection: "row", alignItems: "center", justifyContent: "center", borderRadius: 9999, borderWidth: 2, borderColor: tokens.primary, backgroundColor: "transparent" }}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.primary }}>3</Text>
+      </View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens.foreground }}>Review</Text>
+    </View>
+  </View>
+</View>
+```
+
+### Vertical
+
+**Do** — Pair each vertical step with a one-line description so the extra width earns its place.
+
+```tsx
+<View style={{ maxWidth: 320 }}>
+  <Stepper vertical current={1} steps={[
+    { label: "Account created", description: "Email verified and password set." },
+    { label: "Profile setup", description: "Add your name and avatar." },
+    { label: "Team invite", description: "Invite collaborators to your workspace." },
+    { label: "Done", description: "You're all set." }
+  ]} />
+</View>
+```
+
+**Don't** — A vertical step with only a title wastes the space the layout is built to use.
+
+```tsx
+<View style={{ maxWidth: 320 }}>
+  <Stepper vertical current={1} steps={[
+    { label: "Account created" },
+    { label: "Profile setup" },
+    { label: "Team invite" },
+    { label: "Done" }
+  ]} />
+</View>
+```
+
+### Progress bar
+
+**Do** — Label the bar and show the exact percentage so progress is legible at a glance.
+
+```tsx
+<View style={{ maxWidth: 320 }}>
+  <Stepper progress current={0} steps={[]} label="Setup progress" value={68} />
+</View>
+```
+
+**Don't** — A bare progress bar with no percentage leaves users guessing how far along they are.
+
+```tsx
+<View style={{ maxWidth: 320 }}>
+  <View style={{ height: 6, overflow: "hidden", borderRadius: 9999, backgroundColor: tokens.muted }}>
+    <View style={{ height: "100%", borderRadius: 9999, backgroundColor: tokens.primary, width: "68%" }} />
+  </View>
+</View>
+```