@olympusoss/canvas 4.0.0 → 5.0.0

package/src/molecules/empty-state/empty-state.md

@@ -0,0 +1,218 @@
+# Empty States
+
+Centered, calm, never blame the user. Always tell them what could be here, and ideally how to get there.
+
+## Usage
+
+```tsx
+<EmptyState
+  icon="🔍"
+  title="No results found"
+  description="Try adjusting your search filters."
+  bordered
+/>
+```
+
+## Variants
+
+### Variant - users
+
+```tsx
+<EmptyState
+  icon="👥"
+  title="No users"
+  description="Invite your first team member."
+  bordered
+/>
+```
+
+### Variant - files
+
+```tsx
+<EmptyState
+  icon="📄"
+  title="No files"
+  description="Upload or drag files here."
+  bordered
+/>
+```
+
+### Variant - activity
+
+```tsx
+<EmptyState
+  icon="📈"
+  title="No activity"
+  description="Events will appear as they happen."
+  bordered
+/>
+```
+
+### Variant - notifications
+
+```tsx
+<EmptyState
+  icon="🔔"
+  title="All caught up"
+  description="No new notifications."
+  bordered
+/>
+```
+
+### Variant - errors
+
+```tsx
+<EmptyState
+  icon="✅"
+  title="No errors"
+  description="Everything is running smoothly."
+  positive
+  bordered
+/>
+```
+
+### Variant - all-clear
+
+```tsx
+<EmptyState
+  icon="✅"
+  title="All clear"
+  description="No locked accounts or pending reviews."
+  positive
+  bordered
+/>
+```
+
+### Single action
+
+```tsx
+<EmptyState
+  icon="🔍"
+  title="No results found"
+  description="Try adjusting your search filters."
+  actionLabel="Create identity"
+  bordered
+/>
+```
+
+### Inside a table
+
+```tsx
+<View style={{ overflow: "scroll", borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", borderBottomWidth: 1, borderColor: tokens.border }}>
+    <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingHorizontal: 16, paddingVertical: 10, textAlign: "left", fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Name</Text>
+    <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingHorizontal: 16, paddingVertical: 10, textAlign: "left", fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Email</Text>
+    <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingHorizontal: 16, paddingVertical: 10, textAlign: "left", fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Role</Text>
+    <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingHorizontal: 16, paddingVertical: 10, textAlign: "left", fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Status</Text>
+  </View>
+  <View style={{ paddingHorizontal: 16, paddingVertical: 40 }}>
+    <EmptyState bordered icon="🔍" title="No results found" description="Try adjusting your search filters." />
+  </View>
+</View>
+```
+
+## Do & Don't
+
+### search
+
+**Do** — State the result neutrally and point at the lever the user can pull (filters, query).
+
+```tsx
+<EmptyState bordered icon="🔍" title="No results found" description="Try adjusting your search filters." />
+```
+
+**Don't** — Blaming the searcher for an empty result set makes a normal outcome feel like a mistake.
+
+```tsx
+<EmptyState bordered icon="🔍" title="Nothing matched" description="You searched for the wrong thing. Check your spelling and try again." />
+```
+
+### users
+
+**Do** — When the user can fix it, give them the one action that does (Invite, Create).
+
+```tsx
+<EmptyState bordered icon="👥" title="No users" description="Invite your first team member." actionLabel="Invite member" />
+```
+
+**Don't** — A dead-end that only restates the emptiness leaves the user with nowhere to go.
+
+```tsx
+<EmptyState bordered icon="👥" title="No users" description="There are no team members in this workspace." />
+```
+
+### files
+
+**Do** — Name the gesture that fills the empty space so the next step is obvious.
+
+```tsx
+<EmptyState bordered icon="📄" title="No files" description="Upload or drag files here." />
+```
+
+**Don't** — Generic 'nothing here' copy never tells the user how files would get into the folder.
+
+```tsx
+<EmptyState bordered icon="📄" title="Nothing here" description="This folder is empty." />
+```
+
+### activity
+
+**Do** — Keep a routinely-empty state calm: muted icon, reassuring copy, no urgency.
+
+```tsx
+<EmptyState bordered icon="📈" title="No activity" description="Events will appear as they happen." />
+```
+
+**Don't** — An alarming red icon turns a calm, expected empty feed into a false error.
+
+```tsx
+<View style={{ alignItems: "center", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, paddingHorizontal: 24, paddingVertical: 32 }}>
+  <View style={{ marginBottom: 12, height: 48, width: 48, alignItems: "center", justifyContent: "center", borderRadius: 9999, backgroundColor: alpha(tokens.destructive, 0.1) }}>
+    <Text style={{ fontSize: 20, lineHeight: 28, color: tokens.destructive }}>⚠️</Text>
+  </View>
+  <Text style={{ textAlign: "center", fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>No activity</Text>
+  <Text style={{ marginTop: 4, textAlign: "center", fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Events will appear as they happen.</Text>
+</View>
+```
+
+### notifications
+
+**Do** — Celebrate a cleared queue: 'All caught up' reads as success, not absence.
+
+```tsx
+<EmptyState bordered icon="🔔" title="All caught up" description="No new notifications." />
+```
+
+**Don't** — Apologetic, sad-toned copy frames an inbox-zero win as a letdown.
+
+```tsx
+<EmptyState bordered icon="🔔" title="Nothing to see" description="You have no notifications. Sorry, it's quiet in here." />
+```
+
+### errors
+
+**Do** — Signal the good news with a green check: zero errors is a passing state, not an empty one.
+
+```tsx
+<EmptyState bordered positive icon="✅" title="No errors" description="Everything is running smoothly." />
+```
+
+**Don't** — A grey 'nothing found' disc reads as a failed query, not as a healthy, error-free system.
+
+```tsx
+<EmptyState bordered icon="🔍" title="No errors" description="Nothing was found." />
+```
+
+### all-clear
+
+**Do** — Reserve the green all-clear for genuinely empty queues: nothing locked, nothing waiting.
+
+```tsx
+<EmptyState bordered positive icon="✅" title="All clear" description="No locked accounts or pending reviews." />
+```
+
+**Don't** — A green all-clear over copy that admits work is pending hides the action the user must take.
+
+```tsx
+<EmptyState bordered positive icon="✅" title="No pending reviews" description="3 accounts are locked and waiting on you." />
+```

package/src/molecules/empty-state/empty-state.styles.ts

@@ -0,0 +1,63 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, palette, alpha } from "../../style/index.js";
+
+// Co-located EmptyState styles. Layout-only fragments are static objects; the
+// disc fill + glyph color read a color and so are functions of the active
+// tokens. The `positive` tone paints the disc and glyph green from the fixed
+// Tailwind palette (green-600), while the default tone stays on the semantic
+// muted / muted-foreground tokens so it follows light/dark/glass.
+
+export type Tone = "positive" | "default";
+
+// The centered column. Bordered wraps it in a rounded, bordered card whose
+// padding tightens under `compact`.
+export const container: ViewStyle = { alignItems: "center" };
+
+export const borderedBase: ViewStyle = { borderRadius: 8, borderWidth: 1 };
+
+export function borderedSurface(tokens: ColorTokens): ViewStyle {
+  return { borderColor: tokens.border };
+}
+
+// Bordered card padding by density (compact tightens it for dense table cells).
+export const borderedPad: Record<"compact" | "default", ViewStyle> = {
+  compact: { paddingHorizontal: 16, paddingVertical: 24 },
+  default: { paddingHorizontal: 24, paddingVertical: 32 },
+};
+
+// The round 48x48 icon disc.
+export const discBase: ViewStyle = {
+  marginBottom: 12,
+  height: 48,
+  width: 48,
+  alignItems: "center",
+  justifyContent: "center",
+  borderRadius: 9999,
+};
+
+// Disc fill per tone: a 10% green wash when positive, the muted token otherwise.
+export function discTone(tokens: ColorTokens, tone: Tone): ViewStyle {
+  return tone === "positive"
+    ? { backgroundColor: alpha(palette["green-600"], 0.1) }
+    : { backgroundColor: tokens.muted };
+}
+
+// The glyph inside the disc (text-xl), colored per tone.
+export const glyphBase: TextStyle = { fontSize: 20, lineHeight: 28 };
+
+export function glyphTone(tokens: ColorTokens, tone: Tone): TextStyle {
+  return tone === "positive" ? { color: palette["green-600"] } : { color: tokens["muted-foreground"] };
+}
+
+// Title: centered, semibold, foreground.
+export function title(tokens: ColorTokens): TextStyle {
+  return { textAlign: "center", fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground };
+}
+
+// Description: centered, muted, with a small inset above the title.
+export function description(tokens: ColorTokens): TextStyle {
+  return { marginTop: 4, textAlign: "center", fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}
+
+// The action button's inset above it.
+export const actionSpacing: ViewStyle = { marginTop: 16 };

package/src/molecules/empty-state/empty-state.tsx

@@ -0,0 +1,77 @@
+import { View, Text, type StyleProp, type ViewStyle, useTheme } from "../../style/index.js";
+import { Button } from "../../atoms/button/button.js";
+import * as s from "./empty-state.styles.js";
+
+// Empty state: a centered, calm column that explains why a region is empty and,
+// when the user can act, offers the one action that fills it. Anatomy mirrors
+// the docs entry: a round 48x48 icon disc, a 12px gap, a semibold title, a
+// muted description, and an optional primary action button.
+//
+// Boolean-prop API: flat booleans grouped into axes, first-match precedence
+// within an axis (mirrors Button's intentOf).
+//
+// - Tone axis: `positive` paints the disc and glyph green for states where
+//   emptiness is good news (no errors, all caught up). The default tone keeps
+//   the disc muted and the glyph muted-foreground for routinely-empty states.
+// - Container axis: `bordered` wraps the column in a rounded, bordered card
+//   (used inside a SectionCard or a table cell). Omit for a bare column.
+// - Density axis: `compact` tightens the card padding for dense table cells.
+
+export interface EmptyStateProps {
+  /** A glyph (emoji or icon character) shown in the disc. */
+  icon?: string;
+  /** Short, neutral headline naming the empty result. */
+  title?: string;
+  /** One reassuring line, ideally pointing at the next step. */
+  description?: string;
+  /** When set, renders a primary action button below the description. */
+  actionLabel?: string;
+  /** Called when the action button is pressed. */
+  onAction?: () => void;
+  // Tone axis (pick one; default keeps the disc muted).
+  positive?: boolean;
+  // Container axis: wrap the column in a bordered card.
+  bordered?: boolean;
+  // Density axis (only affects the bordered card's padding).
+  compact?: boolean;
+  /** Escape hatch for layout/positioning composition (width, margins). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Tone precedence: first match wins.
+function isPositive(p: EmptyStateProps): boolean {
+  return !!p.positive;
+}
+
+export function EmptyState(props: EmptyStateProps) {
+  const { icon, title, description, actionLabel, onAction, bordered, compact, style } = props;
+  const { tokens } = useTheme();
+  const tone: s.Tone = isPositive(props) ? "positive" : "default";
+
+  const container: StyleProp<ViewStyle> = [
+    s.container,
+    bordered ? s.borderedBase : null,
+    bordered ? s.borderedSurface(tokens) : null,
+    bordered ? s.borderedPad[compact ? "compact" : "default"] : null,
+    style,
+  ];
+
+  return (
+    <View style={container}>
+      {icon != null ? (
+        <View style={[s.discBase, s.discTone(tokens, tone)]}>
+          <Text style={[s.glyphBase, s.glyphTone(tokens, tone)]}>{icon}</Text>
+        </View>
+      ) : null}
+      {title != null ? <Text style={s.title(tokens)}>{title}</Text> : null}
+      {description != null ? <Text style={s.description(tokens)}>{description}</Text> : null}
+      {actionLabel != null ? (
+        <View style={s.actionSpacing}>
+          <Button primary small onPress={onAction}>
+            {actionLabel}
+          </Button>
+        </View>
+      ) : null}
+    </View>
+  );
+}

package/src/molecules/feeds/feeds.md

@@ -0,0 +1,102 @@
+# Feeds
+
+Vertical activity streams with icons and timestamps. Used for audit logs, change history, and notification lists.
+
+## Usage
+
+```tsx
+<Feed
+  connector
+  items={[
+    { actor: "Rachel Chen", action: "approved the request", time: "2 hours ago" },
+    { actor: "Ada Lovelace", action: "updated the description", time: "5 hours ago" },
+    { actor: "System", action: "created the project", time: "3 days ago" }
+  ]}
+/>
+```
+
+## Variants
+
+### Variant - avatar
+
+```tsx
+<Feed
+  avatar
+  items={[
+    { actor: "Rachel Chen", action: "commented on the pull request", time: "2 hours ago" },
+    { actor: "Ada Lovelace", action: "pushed 3 commits", time: "5 hours ago" },
+    { actor: "Kevin Turner", action: "opened the pull request", time: "1 day ago" }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Connector
+
+**Do** — Drop the connector on the last item so the line terminates cleanly at the final event.
+
+```tsx
+<Feed connector items={[
+    { actor: "Rachel Chen", action: "approved the request", time: "2 hours ago" },
+    { actor: "System", action: "created the project", time: "3 days ago" }
+  ]} />
+```
+
+**Don't** — Running the connector line past the final event leaves a dangling tail pointing at nothing.
+
+```tsx
+<View style={{ width: "100%", maxWidth: 420, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, overflow: "hidden", padding: 24 }}>
+  <View style={{ position: "relative", flexDirection: "row", gap: 12, paddingBottom: 24 }}>
+    <View style={{ position: "absolute", bottom: -24, left: 13, top: 28, width: 1, backgroundColor: tokens.border }} />
+    <View style={{ height: 28, width: 28, flexShrink: 0, alignItems: "center", justifyContent: "center", borderRadius: 9999, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card }}>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens["muted-foreground"] }}>RC</Text>
+    </View>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingTop: 2 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20 }}>
+        <Text style={{ fontWeight: "500" }}>Rachel Chen </Text>
+        <Text style={{ color: tokens["muted-foreground"] }}>approved the request</Text>
+      </Text>
+      <Text style={{ marginTop: 2, fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>2 hours ago</Text>
+    </View>
+  </View>
+  <View style={{ position: "relative", flexDirection: "row", gap: 12 }}>
+    <View style={{ position: "absolute", bottom: -24, left: 13, top: 28, width: 1, backgroundColor: tokens.border }} />
+    <View style={{ height: 28, width: 28, flexShrink: 0, alignItems: "center", justifyContent: "center", borderRadius: 9999, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card }}>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens["muted-foreground"] }}>SY</Text>
+    </View>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", paddingTop: 2 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20 }}>
+        <Text style={{ fontWeight: "500" }}>System </Text>
+        <Text style={{ color: tokens["muted-foreground"] }}>created the project</Text>
+      </Text>
+      <Text style={{ marginTop: 2, fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>3 days ago</Text>
+    </View>
+  </View>
+</View>
+```
+
+### Avatar
+
+**Do** — Lead with the person's avatar, bold the actor, and keep the action plus a relative timestamp muted.
+
+```tsx
+<Feed avatar items={[
+    { actor: "Ada Lovelace", action: "pushed 3 commits", time: "5 hours ago", avatar: "/ada-lovelace.jpg" }
+  ]} />
+```
+
+**Don't** — An anonymous avatar with no actor name and no timestamp strips the row of the who and the when.
+
+```tsx
+<View style={{ width: "100%", maxWidth: 420, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, overflow: "hidden" }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 12, paddingHorizontal: 20, paddingVertical: 16 }}>
+    <View style={{ height: 40, width: 40, flexShrink: 0, alignItems: "center", justifyContent: "center", overflow: "hidden", borderRadius: 9999, backgroundColor: tokens.muted }}>
+      <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "500", color: tokens["muted-foreground"] }}>?</Text>
+    </View>
+    <View style={{ minWidth: 0, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Pushed 3 commits</Text>
+    </View>
+  </View>
+</View>
+```

package/src/molecules/feeds/feeds.styles.ts

@@ -0,0 +1,120 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Feed styles. Layout-only fragments are static objects; anything that
+// reads a color is a function of the active tokens (so the card surface, node
+// fill, and divider follow light/dark and read as glass when the ThemeProvider's
+// surface is "glass", since tokens.card is swapped translucent at the theming
+// level). Grouped by axis: shared surface, the avatar lead, and the connector lead.
+
+export type Lead = "connector" | "avatar";
+
+// --- shared surface ---------------------------------------------------------
+
+// The card surface framing the feed (mirrors the docs cardCls):
+// w-full max-w-[560px] rounded-lg border border-border bg-card overflow-hidden.
+export function cardSurface(tokens: ColorTokens): ViewStyle {
+  return {
+    width: "100%",
+    maxWidth: 560,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+    overflow: "hidden",
+  };
+}
+
+// --- shared content column --------------------------------------------------
+
+// The content column wrapper (flex-1).
+export const contentColumn: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// The outer line wrapping actor + action + target (text-sm).
+export const lineText: TextStyle = { fontSize: 14, lineHeight: 20 };
+
+// The actor name, rendered bold (text-sm font-medium text-foreground).
+export function actorLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// The action / target text, muted (text-sm text-muted-foreground).
+export function actionLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}
+
+// The relative timestamp, muted and small (text-xs text-muted-foreground mt-0.5).
+export function timeLabel(tokens: ColorTokens): TextStyle {
+  return { marginTop: 2, fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] };
+}
+
+// --- avatar lead ------------------------------------------------------------
+
+// Avatar row base (flex-row items-start gap-3) + density-driven padding.
+export const avatarRow: ViewStyle = { flexDirection: "row", alignItems: "flex-start", gap: 12 };
+
+// Row padding by density: compact (px-5 py-3) vs default (px-5 py-4).
+export function avatarRowPad(compact: boolean): ViewStyle {
+  return { paddingHorizontal: 20, paddingVertical: compact ? 12 : 16 };
+}
+
+// The hairline rule between avatar rows (border-b border-border); omitted on last.
+export function avatarDivider(tokens: ColorTokens): ViewStyle {
+  return { borderBottomWidth: 1, borderColor: tokens.border };
+}
+
+// --- connector lead ---------------------------------------------------------
+
+// Connector surface padding by density: compact (p-5) vs default (p-6).
+export function connectorPad(compact: boolean): ViewStyle {
+  return { padding: compact ? 20 : 24 };
+}
+
+// Connector row base (relative flex-row gap-3).
+export const connectorRow: ViewStyle = { position: "relative", flexDirection: "row", gap: 12 };
+
+// Inter-row vertical rhythm by density: compact (pb-4) vs default (pb-6).
+export function connectorRowGap(compact: boolean): ViewStyle {
+  return { paddingBottom: compact ? 16 : 24 };
+}
+
+// The vertical connector line (absolute bottom-0 left-[13px] top-7 w-px bg-border):
+// a 1px border-colored line under the node's horizontal center, dropped on the last row.
+export function connectorLine(tokens: ColorTokens): ViewStyle {
+  return { position: "absolute", bottom: 0, left: 13, top: 28, width: 1, backgroundColor: tokens.border };
+}
+
+// The leading node for the connector variant (h-7 w-7 shrink-0 items-center
+// justify-center rounded-full border border-border bg-card): a small bordered
+// circle carrying the actor's initials, sized to sit on the connector line.
+export function node(tokens: ColorTokens): ViewStyle {
+  return {
+    height: 28,
+    width: 28,
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 9999,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+  };
+}
+
+// The node's initials (text-xs font-medium text-muted-foreground).
+export function nodeInitials(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens["muted-foreground"] };
+}
+
+// The node's actor-less dot (h-1.5 w-1.5 rounded-full bg-muted-foreground).
+export function nodeDot(tokens: ColorTokens): ViewStyle {
+  return { height: 6, width: 6, borderRadius: 9999, backgroundColor: tokens["muted-foreground"] };
+}
+
+// The connector content column (flex-1 pt-0.5): nudged down to align with the node.
+export const connectorContentColumn: ViewStyle = {
+  flexGrow: 1,
+  flexShrink: 1,
+  flexBasis: "0%",
+  paddingTop: 2,
+};