@olympusoss/canvas 4.0.0 → 5.0.0

package/src/molecules/feeds/feeds.tsx

@@ -0,0 +1,167 @@
+import { type ReactNode } from "react";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Avatar } from "../../atoms/avatar/avatar.js";
+import * as s from "./feeds.styles.js";
+
+// An activity feed is a vertical timeline of events. Each item is a row with a
+// leading mark (a small dot/initials node or a person's avatar), a content
+// column carrying the actor + action + target line, and a muted timestamp.
+//
+// Two lead variants:
+//
+// 1. The connector feed (default): each row leads with a small bordered node
+//    and a vertical connector line links one event to the next. The connector
+//    is dropped on the final item so the line terminates cleanly at the last
+//    event rather than dangling past it.
+// 2. The avatar feed (`avatar`): each row leads with the actor's avatar and the
+//    rows are separated by hairline rules instead of a connector line.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf). The lead axis picks
+// between the connector node and the avatar; `compact` is an orthogonal density
+// modifier that tightens the vertical rhythm.
+
+/** One event in the feed. */
+export interface FeedItem {
+  /** Actor who performed the action, rendered bold (e.g. "Rachel Chen"). */
+  actor?: string;
+  /** The action text, muted (e.g. "approved the request"). */
+  action: string;
+  /** Optional target of the action, muted and trailing the action. */
+  target?: string;
+  /** Relative timestamp, muted and small (e.g. "2 hours ago"). */
+  time: string;
+  /** Photo URL for the avatar lead; falls back to initials from the actor. */
+  avatar?: string;
+}
+
+export interface FeedProps {
+  /** Events to render, top to bottom. */
+  items?: FeedItem[];
+  // Lead axis (pick one; default is the connector node + vertical line).
+  connector?: boolean;
+  avatar?: boolean;
+  // Density modifier: tightens the row padding and connector spacing.
+  compact?: boolean;
+  /** When set, each event row is pressable, reporting the row index. */
+  onItemPress?: (index: number) => void;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+type Lead = "connector" | "avatar";
+
+// Lead precedence when more than one is passed: first match wins.
+function leadOf(p: FeedProps): Lead {
+  if (p.connector) return "connector";
+  if (p.avatar) return "avatar";
+  return "connector";
+}
+
+// Two initials from an actor name, used for the avatar/node fallback when no
+// photo is supplied (e.g. "Rachel Chen" -> "RC").
+function initialsFrom(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+
+export function Feed(props: FeedProps) {
+  const { items = [], onItemPress, style } = props;
+  const { tokens } = useTheme();
+  const lead = leadOf(props);
+  const compact = !!props.compact;
+  const lastIndex = items.length - 1;
+
+  const renderContent = (item: FeedItem) => (
+    <View style={s.contentColumn}>
+      <Text style={s.lineText}>
+        {item.actor ? <Text style={s.actorLabel(tokens)}>{item.actor} </Text> : null}
+        <Text style={s.actionLabel(tokens)}>{item.action}</Text>
+        {item.target ? <Text style={s.actionLabel(tokens)}> {item.target}</Text> : null}
+      </Text>
+      <Text style={s.timeLabel(tokens)}>{item.time}</Text>
+    </View>
+  );
+
+  if (lead === "avatar") {
+    // Avatar lead: each row leads with the actor's avatar; rows are ruled by a
+    // hairline between items (the last row keeps no rule).
+    const rows = items.map((item, index) => {
+      const divider = index < lastIndex ? s.avatarDivider(tokens) : null;
+      const rowStyle: StyleProp<ViewStyle> = [s.avatarRow, s.avatarRowPad(compact), divider];
+      const inner: ReactNode = (
+        <>
+          <Avatar src={item.avatar} name={item.actor}>
+            {item.actor ? initialsFrom(item.actor) : ""}
+          </Avatar>
+          {renderContent(item)}
+        </>
+      );
+      if (onItemPress) {
+        return (
+          <Pressable
+            key={index}
+            accessibilityRole="button"
+            onPress={() => onItemPress(index)}
+            style={({ pressed }) => [rowStyle, pressed ? { backgroundColor: tokens.accent } : null]}
+          >
+            {inner}
+          </Pressable>
+        );
+      }
+      return (
+        <View key={index} style={rowStyle}>
+          {inner}
+        </View>
+      );
+    });
+    return <View style={[s.cardSurface(tokens), style]}>{rows}</View>;
+  }
+
+  // Connector lead: a bordered node per row with a vertical line linking each
+  // event to the next. The line is dropped on the final item.
+  const rows = items.map((item, index) => {
+    const isLast = index === lastIndex;
+    const rowStyle: StyleProp<ViewStyle> = [s.connectorRow, isLast ? null : s.connectorRowGap(compact)];
+    const inner: ReactNode = (
+      <>
+        {!isLast ? (
+          // Vertical connector: a 1px border-colored line running from just below
+          // the node down to the next row. Absolutely placed under the node's
+          // horizontal center (node is 28px wide -> center at 14px, minus the
+          // 0.5px line half-width lands at 13px).
+          <View style={s.connectorLine(tokens)} />
+        ) : null}
+        <View style={s.node(tokens)}>
+          {item.actor ? (
+            <Text style={s.nodeInitials(tokens)}>{initialsFrom(item.actor)}</Text>
+          ) : (
+            <View style={s.nodeDot(tokens)} />
+          )}
+        </View>
+        <View style={s.connectorContentColumn}>{renderContent(item)}</View>
+      </>
+    );
+    if (onItemPress) {
+      return (
+        <Pressable
+          key={index}
+          accessibilityRole="button"
+          onPress={() => onItemPress(index)}
+          style={({ pressed }) => [rowStyle, pressed ? { backgroundColor: tokens.accent } : null]}
+        >
+          {inner}
+        </Pressable>
+      );
+    }
+    return (
+      <View key={index} style={rowStyle}>
+        {inner}
+      </View>
+    );
+  });
+
+  return <View style={[s.cardSurface(tokens), s.connectorPad(compact), style]}>{rows}</View>;
+}

package/src/molecules/field/field.md

@@ -0,0 +1,117 @@
+# Field Display
+
+Read-only key/value pairs. Used in detail views, modal previews, and audit screens. Optional mono mode for IDs, tokens, dates.
+
+## Usage
+
+```tsx
+<Field
+  rows={[
+    { label: "User ID", value: "usr_abc123", mono: true },
+    { label: "Name", value: "Rachel Chen" },
+    { label: "Role", value: "Admin" },
+    { label: "Status", status: "Active" }
+  ]}
+  style={{ maxWidth: 400 }}
+/>
+```
+
+## Variants
+
+### Value mode - mono
+
+```tsx
+<Field
+  rows={[
+    { label: "Client ID", value: "clt_8f2a9b4c7e1d", mono: true },
+    { label: "Created", value: "2026-05-24T14:32:00Z", mono: true },
+    { label: "Fingerprint", value: "sha256:xK9v...", mono: true }
+  ]}
+  style={{ maxWidth: 400 }}
+/>
+```
+
+### Value mode - composed
+
+```tsx
+<Field
+  rows={[
+    { label: "Status", status: "Active" },
+    { label: "Plan", badge: "Pro" },
+    { label: "Token", value: "sk_live_a8f2...c9e1", mono: true, copyValue: "sk_live_a8f2c9e1" },
+    { label: "Members", avatars: [
+      { src: "/rachel-chen.jpg", name: "RC" },
+      { name: "AJ" }
+    ], overflow: 3 }
+  ]}
+  style={{ maxWidth: 400 }}
+/>
+```
+
+## Do & Don't
+
+### Basic
+
+**Do** — Use the fixed 180px label column so every value aligns to one baseline.
+
+```tsx
+<Field style={{ maxWidth: 400 }} rows={[
+    { label: "Name", value: "Rachel Chen" },
+    { label: "Role", value: "Admin" }
+  ]} />
+```
+
+**Don't** — Inline label-colon-value with no shared column makes values ragged and impossible to scan down a list.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 4 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20 }}>
+    <Text style={{ fontWeight: "600" }}>Name:</Text>
+     Rachel Chen
+  </Text>
+  <Text style={{ fontSize: 14, lineHeight: 20 }}>
+    <Text style={{ fontWeight: "600" }}>Role:</Text>
+     Admin
+  </Text>
+</View>
+```
+
+### Mono
+
+**Do** — Wrap IDs, hashes, and timestamps in font-mono so every glyph is fixed-width and copy-able.
+
+```tsx
+<Field style={{ maxWidth: 400 }} rows={[
+    { label: "Client ID", value: "clt_8f2a9b4c7e1d", mono: true },
+    { label: "Fingerprint", value: "sha256:xK9v...", mono: true }
+  ]} />
+```
+
+**Don't** — Rendering IDs and hashes in proportional type makes look-alike characters (l/1, O/0) hard to compare.
+
+```tsx
+<Field style={{ maxWidth: 400 }} rows={[
+    { label: "Client ID", value: "clt_8f2a9b4c7e1d" },
+    { label: "Fingerprint", value: "sha256:xK9v..." }
+  ]} />
+```
+
+### Composed
+
+**Do** — Compose real nodes into the value slot: a status badge for state, a badge for the plan tier.
+
+```tsx
+<Field style={{ maxWidth: 400 }} rows={[
+    { label: "Status", status: "Active" },
+    { label: "Plan", badge: "Pro" }
+  ]} />
+```
+
+**Don't** — Flattening a live status or plan tier to plain text drops the color and shape that signal state at a glance.
+
+```tsx
+<Field style={{ maxWidth: 400 }} rows={[
+    { label: "Status", value: "Active" },
+    { label: "Plan", value: "Pro" }
+  ]} />
+```

package/src/molecules/field/field.styles.ts

@@ -0,0 +1,85 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Field styles. Layout-only fragments are static objects; anything
+// that reads a color is a function of the active tokens, so the label/value text
+// and the avatar-overflow chip follow light/dark (and the glass surface).
+
+// --- shared text ------------------------------------------------------------
+
+// The engine has no font-family utility, so request RN's cross-platform
+// monospace alias via inline style (the same technique Badge uses for `mono`).
+export const monoStyle: TextStyle = { fontFamily: "monospace" };
+
+// Left-column label of a display row: a fixed 180px muted term.
+export function fieldLabel(tokens: ColorTokens): TextStyle {
+  return { width: 180, flexShrink: 0, fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}
+
+// The default value shape: medium-weight foreground text.
+export function fieldValue(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// --- display mode (rows) ----------------------------------------------------
+
+// Outer stack of label/value rows.
+export const displayStack: ViewStyle = { flexDirection: "column", gap: 12 };
+
+// One row: label column + value, baseline-aligned.
+export const displayRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 16 };
+
+// The value column grows to fill the row beside the fixed label column.
+export const valueFill: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// An overlapping avatar stack row.
+export const avatarRow: ViewStyle = { flexDirection: "row", alignItems: "center" };
+
+// Each avatar after the first overlaps the previous one.
+export const avatarOverlap: ViewStyle = { marginLeft: -8 };
+
+// The trailing "+N" overflow chip after an avatar stack.
+export function overflowChip(tokens: ColorTokens): ViewStyle {
+  return {
+    marginLeft: -8,
+    height: 28,
+    width: 28,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 9999,
+    borderWidth: 2,
+    borderColor: tokens.background,
+    backgroundColor: tokens.muted,
+  };
+}
+
+export function overflowText(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens["muted-foreground"] };
+}
+
+// A copyable value: the value text followed by a ghost Copy button.
+export const copyRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 8 };
+
+// --- control mode -----------------------------------------------------------
+
+// Outer stack of label / control / message.
+export const controlStack: ViewStyle = { flexDirection: "column", gap: 6 };
+
+// The dimmed look applied to the whole field when disabled.
+export const dimmed: ViewStyle = { opacity: 0.5 };
+
+// The control's label above the Input.
+export function label(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// The destructive "*" appended to a required field's label.
+export function requiredMark(tokens: ColorTokens): TextStyle {
+  return { color: tokens.destructive };
+}
+
+// The helper / error line below the control. Error text is destructive, the
+// resting helper is muted.
+export function message(tokens: ColorTokens, error: boolean): TextStyle {
+  return { fontSize: 12, lineHeight: 16, color: error ? tokens.destructive : tokens["muted-foreground"] };
+}

package/src/molecules/field/field.tsx

@@ -0,0 +1,175 @@
+import { View, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Avatar } from "../../atoms/avatar/avatar.js";
+import { Badge } from "../../atoms/badge/badge.js";
+import { Button } from "../../atoms/button/button.js";
+import { Input } from "../../atoms/input/input.js";
+import * as s from "./field.styles.js";
+
+/** One avatar in a Members stack: a photo (`src`) or initials (`name`). */
+export interface FieldAvatar {
+  src?: string;
+  name?: string;
+}
+
+/**
+ * One row of the read-only Field display: a label paired with a value. The
+ * value slot is data-driven and composes real atoms; pass at most one value
+ * shape per row, resolved in this precedence: avatars > copyValue > status >
+ * badge > plain value.
+ */
+export interface FieldRow {
+  /** Left-column label (the muted term). */
+  label: string;
+  /** Plain text value (the default value shape). */
+  value?: string;
+  /** Render `value`/`copyValue` in a fixed-width monospace face (IDs, tokens, hashes). */
+  mono?: boolean;
+  /** Render the value as a metadata Badge (secondary tone) carrying this text, e.g. a plan tier. */
+  badge?: string;
+  /** Render the value as a success status Badge carrying this text, e.g. "Active". */
+  status?: string;
+  /** Append a ghost "Copy" button after the value that copies this string. */
+  copyValue?: string;
+  /** Render the value as an overlapping avatar stack. */
+  avatars?: FieldAvatar[];
+  /** Trailing "+N" overflow chip after an avatar stack. */
+  overflow?: number;
+}
+
+export interface FieldProps {
+  /**
+   * Read-only key/value rows. When set, Field renders the field-display
+   * (label column + composed value) instead of the editable input control.
+   */
+  rows?: FieldRow[];
+  /** Label shown above the control. */
+  label?: string;
+  /** Helper text shown below the control in the resting state. */
+  helper?: string;
+  /** Error message shown below the control when `error` is set; replaces the helper. */
+  error?: string;
+  /** Placeholder forwarded to the wrapped Input. */
+  placeholder?: string;
+  /** Current text value (controlled), forwarded to the Input. */
+  value?: string;
+  /** Called with the new text on each keystroke, forwarded to the Input. */
+  onChangeText?: (text: string) => void;
+  // Boolean axes (orthogonal, stack freely).
+  /** Marks the field as required: appends a destructive "*" to the label. */
+  required?: boolean;
+  /** Disables the control and dims the whole field. */
+  disabled?: boolean;
+  /** Invalid state: shows the error message (red) and flags the Input. */
+  invalid?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Render a row's value slot from its data descriptor. Precedence: an avatar
+// stack, then a copyable value, then a status badge, then a metadata badge,
+// then plain (optionally monospace) text.
+function FieldValue(row: FieldRow) {
+  const { tokens } = useTheme();
+
+  if (row.avatars && row.avatars.length > 0) {
+    return (
+      <View style={s.avatarRow}>
+        {row.avatars.map((a, i) => (
+          <View key={i} style={i > 0 ? s.avatarOverlap : undefined}>
+            <Avatar small ring src={a.src} name={a.name}>
+              {a.name}
+            </Avatar>
+          </View>
+        ))}
+        {typeof row.overflow === "number" && row.overflow > 0 ? (
+          <View style={s.overflowChip(tokens)}>
+            <Text style={s.overflowText(tokens)}>{`+${row.overflow}`}</Text>
+          </View>
+        ) : null}
+      </View>
+    );
+  }
+  if (row.copyValue != null) {
+    return (
+      <View style={s.copyRow}>
+        <Text style={[s.fieldValue(tokens), row.mono ? s.monoStyle : null]}>
+          {row.value ?? row.copyValue}
+        </Text>
+        <Button ghost small>
+          Copy
+        </Button>
+      </View>
+    );
+  }
+  if (row.status != null) {
+    return (
+      <Badge status success>
+        {row.status}
+      </Badge>
+    );
+  }
+  if (row.badge != null) {
+    return <Badge secondary>{row.badge}</Badge>;
+  }
+  return (
+    <Text style={[s.fieldValue(tokens), row.mono ? s.monoStyle : null]}>
+      {row.value}
+    </Text>
+  );
+}
+
+export function Field(props: FieldProps) {
+  const {
+    rows,
+    label,
+    helper,
+    error,
+    placeholder,
+    value,
+    onChangeText,
+    required,
+    disabled,
+    invalid,
+    style,
+  } = props;
+  const { tokens } = useTheme();
+
+  // Display mode: a read-only stack of label/value rows. Each row aligns its
+  // label to a fixed 180px column (flex, not grid) so every value lines up to
+  // one baseline.
+  if (rows) {
+    return (
+      <View style={[s.displayStack, disabled ? s.dimmed : null, style]}>
+        {rows.map((row, index) => (
+          <View key={`${row.label}-${index}`} style={s.displayRow}>
+            <Text style={s.fieldLabel(tokens)}>{row.label}</Text>
+            <View style={s.valueFill}>{FieldValue(row)}</View>
+          </View>
+        ))}
+      </View>
+    );
+  }
+
+  // Error takes precedence over the resting helper below the control.
+  const showError = !!invalid && !!error;
+  const messageText = showError ? error : helper;
+
+  return (
+    <View style={[s.controlStack, disabled ? s.dimmed : null, style]}>
+      {label != null ? (
+        <Text style={s.label(tokens)}>
+          {label}
+          {required ? <Text style={s.requiredMark(tokens)}> *</Text> : null}
+        </Text>
+      ) : null}
+      <Input
+        value={value}
+        onChangeText={onChangeText}
+        placeholder={placeholder}
+        disabled={disabled}
+        error={invalid}
+      />
+      {messageText != null ? <Text style={s.message(tokens, showError)}>{messageText}</Text> : null}
+    </View>
+  );
+}

package/src/molecules/fieldset/fieldset.md

@@ -0,0 +1,141 @@
+# Fieldsets
+
+Group related form controls under a legend. Each field pairs a label, control, optional help text, and an inline error, so a set of inputs reads as one labeled unit.
+
+## Usage
+
+```tsx
+<Fieldset
+  legend="Shipping details"
+  description="Where should we send your order?"
+  items={[
+    { label: "Full name", placeholder: "Ada Lovelace" },
+    { label: "Email", placeholder: "ada@example.com", value: "ada@", help: "We'll only use this for order updates." },
+    { label: "Country", placeholder: "United States" }
+  ]}
+/>
+```
+
+## Variants
+
+### Content - checkboxes
+
+```tsx
+<Fieldset
+  legend="Email notifications"
+  description="Choose what we email you about."
+  checkboxes={[
+    { label: "Product updates", checked: true },
+    { label: "Security alerts", checked: true },
+    { label: "Weekly digest", checked: false }
+  ]}
+/>
+```
+
+### Validation error
+
+```tsx
+<Fieldset
+  legend="Shipping details"
+  description="Where should we send your order?"
+  items={[
+    { label: "Full name", placeholder: "Ada Lovelace" },
+    { label: "Email", placeholder: "ada@example.com", value: "ada@", help: "We'll only use this for order updates.", error: "Enter a valid email address" },
+    { label: "Country", placeholder: "United States" }
+  ]}
+/>
+```
+
+### Disabled
+
+```tsx
+<Fieldset
+  legend="Shipping details"
+  description="Where should we send your order?"
+  disabled
+  items={[
+    { label: "Full name", placeholder: "Ada Lovelace" },
+    { label: "Email", placeholder: "ada@example.com", value: "ada@", help: "We'll only use this for order updates." },
+    { label: "Country", placeholder: "United States" }
+  ]}
+/>
+```
+
+### Columns - 2
+
+```tsx
+<Fieldset
+  legend="Shipping details"
+  description="Where should we send your order?"
+  twoColumn
+  items={[
+    { label: "Full name", placeholder: "Ada Lovelace" },
+    { label: "Email", placeholder: "ada@example.com", value: "ada@", help: "We'll only use this for order updates." },
+    { label: "Country", placeholder: "United States" }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Text fields
+
+**Do** — Give every field a persistent label; use the placeholder only for an example value or format hint.
+
+```tsx
+<Fieldset legend="Shipping details" items={[
+    { label: "Full name", placeholder: "Ada Lovelace" },
+    { label: "Email", placeholder: "ada@example.com", help: "We'll only use this for order updates." }
+  ]} />
+```
+
+**Don't** — A placeholder is not a label: it vanishes on focus and is skipped by many screen readers, leaving the field unnamed.
+
+```tsx
+<Fieldset legend="Shipping details" items={[
+    { label: "", placeholder: "Full name" },
+    { label: "", placeholder: "Email" }
+  ]} />
+```
+
+### Checkbox group
+
+**Do** — A legend names the group so its checkboxes read as one labeled unit.
+
+```tsx
+<Fieldset legend="Notify me by" checkboxes={[
+    { label: "Email" },
+    { label: "SMS" },
+    { label: "Push" }
+  ]} />
+```
+
+**Don't** — Without a legend the relationship between the controls is implicit; screen readers announce them as unrelated.
+
+```tsx
+<Fieldset checkboxes={[
+    { label: "Email" },
+    { label: "SMS" },
+    { label: "Push" }
+  ]} />
+```
+
+### Two-column
+
+**Do** — Pair only naturally adjacent, short fields side by side; the grid stacks to one column on small screens.
+
+```tsx
+<Fieldset legend="Card details" twoColumn items={[
+    { label: "Expiry", placeholder: "MM / YY" },
+    { label: "CVC", placeholder: "123" }
+  ]} />
+```
+
+**Don't** — Splitting unrelated or full-width fields across two columns crams the form and breaks the reading order.
+
+```tsx
+<Fieldset legend="Account" twoColumn items={[
+    { label: "Bio", value: "Engineering lead." },
+    { label: "Country", value: "United States" }
+  ]} />
+```