@olympusoss/canvas 4.0.0 → 5.0.0

package/src/atoms/skeleton/skeleton.md

@@ -0,0 +1,135 @@
+# Skeletons
+
+Placeholders for loading content.
+
+## Usage
+
+```tsx
+<Skeleton text animate style={{ width: "60%" }} />
+```
+
+## Variants
+
+### Shape - avatar
+
+```tsx
+<Skeleton avatar animate />
+```
+
+### Shape - button
+
+```tsx
+<Skeleton button animate style={{ width: "60%" }} />
+```
+
+### Shape - card
+
+```tsx
+<Skeleton card animate />
+```
+
+### Shape - list
+
+```tsx
+<Skeleton list animate />
+```
+
+### Shape - table
+
+```tsx
+<Skeleton table animate />
+```
+
+## Do & Don't
+
+### text
+
+**Do** — Vary the line widths and shorten the last line so it reads like real wrapped text.
+
+```tsx
+<View style={{ width: 320, flexDirection: "column", gap: 6 }}>
+  <Skeleton text animate style={{ width: "100%" }} />
+  <Skeleton text animate style={{ width: "95%" }} />
+  <Skeleton text animate style={{ width: "60%" }} />
+</View>
+```
+
+**Don't** — Three full-width lines read as a solid block, not as a paragraph of prose.
+
+```tsx
+<View style={{ width: 320, flexDirection: "column", gap: 6 }}>
+  <Skeleton text animate style={{ width: "100%" }} />
+  <Skeleton text animate style={{ width: "100%" }} />
+  <Skeleton text animate style={{ width: "100%" }} />
+</View>
+```
+
+### avatar
+
+**Do** — Match the avatar's circle exactly so the photo drops in with no shift.
+
+```tsx
+<Skeleton avatar animate />
+```
+
+**Don't** — A square placeholder for a round avatar snaps shape the instant the image loads.
+
+```tsx
+<View style={{ backgroundColor: tokens.muted, borderRadius: 6, width: 40, height: 40 }} />
+```
+
+### button
+
+**Do** — Size the placeholder to the button's real height and width (h-9, content-fit).
+
+```tsx
+<Skeleton button animate />
+```
+
+**Don't** — An oversized bar overstates a button and the layout jumps when the real control mounts.
+
+```tsx
+<View style={{ backgroundColor: tokens.muted, width: 320, height: 72, borderRadius: 6 }} />
+```
+
+### card
+
+**Do** — Mirror the real layout (avatar circle, text lines) so the swap is seamless.
+
+```tsx
+<Skeleton card animate />
+```
+
+**Don't** — A generic block that ignores the content's shape causes a jarring shift when it loads.
+
+```tsx
+<View style={{ backgroundColor: tokens.muted, borderRadius: 6, width: 320, height: 88 }} />
+```
+
+### list
+
+**Do** — Repeat a per-row placeholder so the avatar-and-text rhythm matches the loaded list.
+
+```tsx
+<Skeleton list animate />
+```
+
+**Don't** — One tall block hides the row rhythm, so the list reflows when each item appears.
+
+```tsx
+<View style={{ backgroundColor: tokens.muted, width: 400, height: 120, borderRadius: 6 }} />
+```
+
+### table
+
+**Do** — Lay placeholders out on the real column grid so each cell stays put when it fills in.
+
+```tsx
+<Skeleton table animate />
+```
+
+**Don't** — A single rectangle gives no column structure; cells shift sideways once data lands.
+
+```tsx
+<View style={{ backgroundColor: tokens.muted, width: 400, height: 120, borderRadius: 6 }} />
+```

package/src/atoms/skeleton/skeleton.styles.ts

@@ -0,0 +1,117 @@
+import { type ViewStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Skeleton styles. Every placeholder shares one muted fill (a color,
+// so it reads the active token); the rest is layout-only (line heights, the
+// avatar/button footprints, and the composite card/list/table scaffolds). The
+// component resolves its shape and size axes and composes these fragments.
+
+export type Shape = "text" | "avatar" | "button" | "card" | "list" | "table";
+
+// The muted fill every placeholder shares (was `bg-muted`).
+export function fill(tokens: ColorTokens): ViewStyle {
+  return { backgroundColor: tokens.muted };
+}
+
+// --- line (the building block for text and composite shapes) ----------------
+
+// A single muted line base: full width, the default line height (`h-3.5`), the
+// small radius (`rounded`). Was `h-3.5 rounded w-full`.
+export const lineBase: ViewStyle = { height: 14, borderRadius: 4, width: "100%" };
+
+// --- text shape: line height per size --------------------------------------
+
+// Line height per size; the default line reads like a single row of text.
+// `h-4` -> 16, `h-3` -> 12, `h-3.5` -> 14.
+export function lineHeight(p: { small?: boolean; large?: boolean }): ViewStyle {
+  if (p.large) return { height: 16 };
+  if (p.small) return { height: 12 };
+  return { height: 14 };
+}
+
+// The text-line radius (`rounded`) plus its full-width default (`w-full`), which
+// the caller's `style` escape hatch can override (e.g. width: "60%").
+export const textBase: ViewStyle = { borderRadius: 4, width: "100%" };
+
+// --- avatar shape: diameter per size ----------------------------------------
+
+// Avatar diameter per size + the full radius (`rounded-full`).
+// `w-12 h-12` -> 48, `w-8 h-8` -> 32, `w-10 h-10` -> 40.
+export function avatarSize(p: { small?: boolean; large?: boolean }): ViewStyle {
+  const d = p.large ? 48 : p.small ? 32 : 40;
+  return { width: d, height: d, borderRadius: 9999 };
+}
+
+// --- button shape: footprint per size ---------------------------------------
+
+// Button placeholder footprint per size + the medium radius (`rounded-md`);
+// mirrors the real control's height. `h-12 w-32` -> {48,128},
+// `h-8 w-20` -> {32,80}, `h-9 w-28` -> {36,112}.
+export function buttonSize(p: { small?: boolean; large?: boolean }): ViewStyle {
+  if (p.large) return { height: 48, width: 128, borderRadius: 6 };
+  if (p.small) return { height: 32, width: 80, borderRadius: 6 };
+  return { height: 36, width: 112, borderRadius: 6 };
+}
+
+// --- card shape -------------------------------------------------------------
+
+// The card surface: rounded-lg border on the card fill, capped width, padded.
+// `rounded-lg border border-border bg-card max-w-[320px] p-4`.
+export function cardSurface(tokens: ColorTokens): ViewStyle {
+  return {
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+    maxWidth: 320,
+    padding: 16,
+  };
+}
+
+// The card's identity row (avatar + two lines). `flex-row items-center gap-3 mb-4`.
+export const cardRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 12, marginBottom: 16 };
+
+// The card avatar pulse. `shrink-0 rounded-full w-10 h-10`.
+export const cardAvatar: ViewStyle = { flexShrink: 0, borderRadius: 9999, width: 40, height: 40 };
+
+// The flex column holding the avatar's two lines. `flex-1`.
+export const flexFill: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// Line widths inside the card (`w-[70%]` / `w-[40%]` / `w-[80%]`).
+export const cardLine70: ViewStyle = { width: "70%" };
+export const cardLine40: ViewStyle = { width: "40%", marginTop: 6 };
+export const cardLine80: ViewStyle = { width: "80%", marginTop: 6 };
+
+// --- list shape -------------------------------------------------------------
+
+// The list container. `flex-col gap-4 max-w-[400px]`.
+export const listContainer: ViewStyle = { flexDirection: "column", gap: 16, maxWidth: 400 };
+
+// A list row. `flex-row items-center gap-3`.
+export const listRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 12 };
+
+// The list row's avatar pulse. `rounded-full w-8 h-8`.
+export const listAvatar: ViewStyle = { borderRadius: 9999, width: 32, height: 32 };
+
+// The list row's primary line spacing. `mb-1.5`.
+export const listLineGap: ViewStyle = { marginBottom: 6 };
+
+// The list row's trailing meta line. `w-10`.
+export const w10: ViewStyle = { width: 40 };
+
+// --- table shape ------------------------------------------------------------
+
+// The table container. `max-w-[560px]`.
+export const tableContainer: ViewStyle = { maxWidth: 560 };
+
+// A table row. `flex-row items-center gap-3 py-3`.
+export const tableRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 12 };
+
+// The hairline divider between table rows (omitted on the last row).
+// `border-b border-border`.
+export function tableDivider(tokens: ColorTokens): ViewStyle {
+  return { borderBottomWidth: 1, borderColor: tokens.border };
+}
+
+// The table row's trailing cell line. `w-20`.
+export const w20: ViewStyle = { width: 80 };

package/src/atoms/skeleton/skeleton.tsx

@@ -0,0 +1,145 @@
+import { useEffect, useRef } from "react";
+import { Animated } from "react-native";
+import { View, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import * as s from "./skeleton.styles.js";
+
+// Skeleton: muted placeholder blocks shown while content loads. A single shape
+// (text line, avatar, button, or a composite card/list/table scaffold) built
+// from one muted fill, optionally pulsing. The size axis scales the line height
+// and the avatar/button footprint.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf).
+
+export interface SkeletonProps {
+  // Shape (pick one; default is a single text line).
+  text?: boolean;
+  avatar?: boolean;
+  button?: boolean;
+  card?: boolean;
+  list?: boolean;
+  table?: boolean;
+  // Size (pick one). Scales the line height and the avatar/button footprint.
+  small?: boolean;
+  large?: boolean;
+  /** Subtle opacity pulse while content loads. */
+  animate?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly sizing, e.g. width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+type Shape = s.Shape;
+
+// Shape precedence when more than one is passed: first match wins.
+function shapeOf(p: SkeletonProps): Shape {
+  if (p.text) return "text";
+  if (p.avatar) return "avatar";
+  if (p.button) return "button";
+  if (p.card) return "card";
+  if (p.list) return "list";
+  if (p.table) return "table";
+  return "text";
+}
+
+/** A pulsing or static muted block. The resolved width/height/fill go on the
+ *  Animated.View itself so percentage widths resolve against the real parent
+ *  (a nested View would collapse `w-[60%]` against an auto-width wrapper). */
+function Pulse({ animate, style }: { animate?: boolean; style: StyleProp<ViewStyle> }) {
+  const opacity = useRef(new Animated.Value(1)).current;
+
+  useEffect(() => {
+    if (!animate) {
+      opacity.setValue(1);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(opacity, { toValue: 0.5, duration: 600, useNativeDriver: false }),
+        Animated.timing(opacity, { toValue: 1, duration: 600, useNativeDriver: false }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [animate, opacity]);
+
+  return <Animated.View style={[style, { opacity: animate ? opacity : 1 }]} />;
+}
+
+// A single muted line; the building block for text and the composite shapes.
+// The muted fill + the line base (`h-3.5 rounded w-full`), then any width/margin
+// overrides the caller layers on.
+function Line({ animate, style }: { animate?: boolean; style?: StyleProp<ViewStyle> }) {
+  const { tokens } = useTheme();
+  return <Pulse animate={animate} style={[s.fill(tokens), s.lineBase, style]} />;
+}
+
+export function Skeleton(props: SkeletonProps) {
+  const { animate, style } = props;
+  const { tokens } = useTheme();
+  const shape = shapeOf(props);
+
+  if (shape === "avatar") {
+    return <Pulse animate={animate} style={[s.fill(tokens), s.avatarSize(props), style]} />;
+  }
+
+  if (shape === "button") {
+    return <Pulse animate={animate} style={[s.fill(tokens), s.buttonSize(props), style]} />;
+  }
+
+  if (shape === "card") {
+    return (
+      <View style={[s.cardSurface(tokens), style]}>
+        <View style={s.cardRow}>
+          <Pulse animate={animate} style={[s.fill(tokens), s.cardAvatar]} />
+          <View style={s.flexFill}>
+            <Line animate={animate} style={s.cardLine70} />
+            <Line animate={animate} style={s.cardLine40} />
+          </View>
+        </View>
+        <Line animate={animate} />
+        <Line animate={animate} style={s.cardLine80} />
+      </View>
+    );
+  }
+
+  if (shape === "list") {
+    const Row = ({ a, b }: { a: StyleProp<ViewStyle>; b: StyleProp<ViewStyle> }) => (
+      <View style={s.listRow}>
+        <Pulse animate={animate} style={[s.fill(tokens), s.listAvatar]} />
+        <View style={s.flexFill}>
+          <Line animate={animate} style={[s.listLineGap, a]} />
+          <Line animate={animate} style={b} />
+        </View>
+        <Line animate={animate} style={s.w10} />
+      </View>
+    );
+    return (
+      <View style={[s.listContainer, style]}>
+        <Row a={{ width: "70%" }} b={{ width: "50%" }} />
+        <Row a={{ width: "55%" }} b={{ width: "35%" }} />
+      </View>
+    );
+  }
+
+  if (shape === "table") {
+    const Row = ({ a, b, last }: { a: StyleProp<ViewStyle>; b: StyleProp<ViewStyle>; last?: boolean }) => (
+      <View style={[s.tableRow, !last ? s.tableDivider(tokens) : null]}>
+        <Line animate={animate} style={s.w10} />
+        <Line animate={animate} style={[s.flexFill, a]} />
+        <Line animate={animate} style={[s.flexFill, b]} />
+        <Line animate={animate} style={s.w20} />
+      </View>
+    );
+    return (
+      <View style={[s.tableContainer, style]}>
+        <Row a={{ width: "70%" }} b={{ width: "50%" }} />
+        <Row a={{ width: "80%" }} b={{ width: "60%" }} />
+        <Row a={{ width: "65%" }} b={{ width: "45%" }} last />
+      </View>
+    );
+  }
+
+  // Default: a single text line, full width by default; style carries the width
+  // override (e.g. width: "60%") and any other layout.
+  return <Pulse animate={animate} style={[s.fill(tokens), s.lineHeight(props), s.textBase, style]} />;
+}

package/src/atoms/spinner/spinner.android.tsx

@@ -0,0 +1,7 @@
+import { createSpinner } from "./spinner.shared.js";
+import { androidSkin } from "./spinner.styles.js";
+
+// Material 3 Spinner: the indeterminate CircularProgressIndicator, a single
+// sweeping arc. Metro resolves this file on Android; the docs import it for preview.
+export const Spinner = createSpinner(androidSkin);
+export type { SpinnerProps } from "./spinner.shared.js";

package/src/atoms/spinner/spinner.ios.tsx

@@ -0,0 +1,7 @@
+import { createSpinner } from "./spinner.shared.js";
+import { iosSkin } from "./spinner.styles.js";
+
+// iOS (HIG) Spinner: the UIActivityIndicatorView ring of fading spokes. Metro
+// resolves this file on iOS; the docs import it for preview.
+export const Spinner = createSpinner(iosSkin);
+export type { SpinnerProps } from "./spinner.shared.js";

package/src/atoms/spinner/spinner.md

@@ -0,0 +1,94 @@
+# Spinner
+
+Animated loading spinner in three sizes.
+
+## Usage
+
+```tsx
+<Spinner />
+```
+
+## Variants
+
+### Size - sm
+
+```tsx
+<Spinner small />
+```
+
+### Size - lg
+
+```tsx
+<Spinner large />
+```
+
+## Do & Don't
+
+**Do** — Pair longer waits with a short label so the spinner has context.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+  <Spinner small />
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Loading…</Text>
+</View>
+```
+
+**Don't** — A bare spinner with no label leaves users guessing what is happening and for how long.
+
+```tsx
+<Spinner />
+```
+
+### sm
+
+**Do** — Use the small size inline: inside a button or beside a line of text where its scale matches the type.
+
+```tsx
+<Button loading disabled>Saving…</Button>
+```
+
+**Don't** — The 4×4 spinner is too small to anchor a full panel; alone in open space it reads as a stray dot.
+
+```tsx
+<View style={{ height: 128, alignItems: "center", justifyContent: "center", borderRadius: 8, borderWidth: 1, borderStyle: "dashed", borderColor: tokens.border }}>
+  <Spinner small />
+</View>
+```
+
+### default
+
+**Do** — Keep the default square and centered with a label for small content panels and cards.
+
+```tsx
+<View style={{ flexDirection: "column", alignItems: "center", gap: 8, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, padding: 24 }}>
+  <Spinner />
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Loading…</Text>
+</View>
+```
+
+**Don't** — Don't stretch it with conflicting w/h utilities; a spinner must stay a perfect circle to spin cleanly.
+
+```tsx
+<View style={{ borderRadius: 6, backgroundColor: tokens.muted, padding: 12 }}>
+  <View style={{ width: 48, height: 20, borderRadius: 9999, borderWidth: 2, borderColor: tokens.muted, borderTopColor: tokens.foreground }} />
+</View>
+```
+
+### lg
+
+**Do** — Reserve the large size for section- or page-level loading, centered in the empty content area.
+
+```tsx
+<View style={{ height: 160, flexDirection: "column", alignItems: "center", justifyContent: "center", gap: 12, borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <Spinner large />
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Loading dashboard…</Text>
+</View>
+```
+
+**Don't** — The 8×8 spinner overflows a small control; cramming the large size into a button breaks its height.
+
+```tsx
+<Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", height: 32, borderRadius: 6, paddingHorizontal: 12, backgroundColor: tokens.primary, opacity: 0.5 }}>
+  <Spinner large />
+</Pressable>
+```

package/src/atoms/spinner/spinner.shared.tsx

@@ -0,0 +1,92 @@
+import { type ReactElement, useEffect, useRef } from "react";
+import { Animated, Easing } from "react-native";
+import { useTheme, type ColorTokens } from "../../style/index.js";
+import { type Tone, TONE_TOKEN } from "./spinner.styles.js";
+
+// Shared Spinner shell. Uses React Native's primitives DIRECTLY (no engine
+// className layer) and reads the active brand tokens via useTheme, so the arc/
+// spoke color follows light/dark and the glass surface. The shared structure
+// (size/tone precedence, the continuous-rotation animation, accessibility) lives
+// here once; a platform file supplies only its rendered shape (a SpinnerSkin) and
+// calls createSpinner. The web skin keeps the current ActivityIndicator look; the
+// iOS skin draws the ring of fading spokes (UIActivityIndicatorView); the Android
+// skin draws the single sweeping arc (M3 CircularProgressIndicator).
+
+export interface SpinnerProps {
+  // Size (pick one; default sits between small and large).
+  small?: boolean;
+  large?: boolean;
+  // Tone (pick one; default is the foreground arc color).
+  primary?: boolean;
+  muted?: boolean;
+  foreground?: boolean;
+  /** Accessible description of what is loading. */
+  accessibilityLabel?: string;
+}
+
+// Tone precedence when more than one is passed: first match wins.
+function toneOf(p: SpinnerProps): Tone {
+  if (p.primary) return "primary";
+  if (p.muted) return "muted";
+  if (p.foreground) return "foreground";
+  return "foreground";
+}
+
+// Three distinct diameters (px) so each size axis value renders a different
+// spinner. Precedence within the size axis: large > small > default (first
+// match wins). Kept identical to the original component.
+function sizeOf(p: SpinnerProps): number {
+  if (p.large) return 32;
+  if (p.small) return 16;
+  return 20;
+}
+
+// What a platform skin owns: how it draws the spinner for a given diameter and
+// color. `rotate` is the shared Animated spin value (0..1, mapped to 0..360deg by
+// the skin if it spins the whole shape). The skin returns a ready-to-mount node.
+export interface SpinnerSkin {
+  render: (args: {
+    size: number;
+    color: string;
+    rotate: Animated.Value;
+    tokens: ColorTokens;
+  }) => ReactElement;
+}
+
+/** Build a Spinner component from a platform skin. */
+export function createSpinner(skin: SpinnerSkin) {
+  return function Spinner(props: SpinnerProps) {
+    const { accessibilityLabel } = props;
+    const { tokens } = useTheme();
+    const tone = toneOf(props);
+    const size = sizeOf(props);
+    const color = tokens[TONE_TOKEN[tone]];
+
+    // One continuous rotation per ~900ms, looping forever. The skins that spin a
+    // drawn shape (iOS spokes, Android arc) interpolate this 0..1 value to
+    // 0..360deg; the web ActivityIndicator animates itself and ignores it.
+    const rotate = useRef(new Animated.Value(0)).current;
+    useEffect(() => {
+      const loop = Animated.loop(
+        Animated.timing(rotate, {
+          toValue: 1,
+          duration: 900,
+          easing: Easing.linear,
+          useNativeDriver: true,
+        }),
+      );
+      loop.start();
+      return () => loop.stop();
+    }, [rotate]);
+
+    return (
+      <Animated.View
+        accessibilityRole="progressbar"
+        accessibilityLabel={accessibilityLabel ?? "Loading"}
+        style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}
+      >
+        {skin.render({ size, color, rotate, tokens })}
+      </Animated.View>
+    );
+  };
+}