@olympusoss/canvas 4.0.0 → 5.0.0

package/src/molecules/media-objects/media-objects.tsx

@@ -0,0 +1,128 @@
+import { type ReactNode } from "react";
+import { View, Image, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Avatar } from "../../atoms/avatar/avatar.js";
+import * as s from "./media-objects.styles.js";
+import { type Align, type Direction } from "./media-objects.styles.js";
+
+// A media object is a horizontal row: a leading media element (avatar, image, or
+// icon glyph) sits beside a content column (a bold title, a muted description,
+// and an optional longer supporting body), sometimes with a trailing action
+// pinned to the right. It is the building block for list rows, notifications,
+// and comment layouts.
+//
+// Boolean-prop API, grouped by axis with first-match precedence within an axis
+// (mirrors Button's intentOf):
+//
+// - Alignment: `center` aligns the row's cross axis to the middle (the compact,
+//   single-line list/action row); the default top-aligns with items-start so the
+//   media anchors to the first line of a multi-line body (per the component's
+//   "Avatar" do/don't: items-start for multi-line, center for single-line rows).
+// - Direction: `reversed` flips the media to the trailing edge; default leads
+//   with the media on the left.
+// - Surface: `bordered` wraps the row in the card surface (border + padding) used
+//   when a media object stands alone as a card; omit for a bare row.
+//
+// State/layout booleans stack orthogonally: `truncate` clamps the title and
+// description to one line each (the action pattern, so a long email never wraps
+// and pushes the trailing action out of alignment).
+
+export interface MediaObjectProps {
+  /** Primary line: the bold heading (e.g. a person's name). */
+  title?: string;
+  /** Secondary line: muted supporting text under the title (e.g. a role or email). */
+  description?: string;
+  /** Optional longer body paragraph rendered below the description. */
+  body?: ReactNode;
+  /** Trailing metadata text pinned to the right (e.g. "2h ago", "admin"). */
+  meta?: string;
+  /** Initials for the leading avatar (e.g. "RC"); rendered as <Avatar>{avatar}</Avatar>. */
+  avatar?: string;
+  /** Photo URL for the leading avatar; takes precedence over initials. */
+  src?: string;
+  /** A leading icon glyph rendered in a tinted square box (stands in for an SVG icon). */
+  icon?: ReactNode;
+  /** A trailing action node (e.g. a <Button>), pinned to the right edge. */
+  action?: ReactNode;
+  // Alignment (pick one; default top-aligns with items-start).
+  center?: boolean;
+  start?: boolean;
+  // Direction (pick one; default leads with the media on the left).
+  reversed?: boolean;
+  leading?: boolean;
+  // Surface.
+  bordered?: boolean;
+  // Layout.
+  truncate?: boolean;
+  /** Escape hatch for layout/positioning composition (width, margins). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Alignment precedence when more than one is passed: first match wins. Default is
+// start (items-start) so the media anchors to the first line of a multi-line body.
+function alignOf(p: MediaObjectProps): Align {
+  if (p.center) return "center";
+  if (p.start) return "start";
+  return "start";
+}
+
+// Direction precedence when more than one is passed: first match wins.
+function directionOf(p: MediaObjectProps): Direction {
+  if (p.reversed) return "reversed";
+  if (p.leading) return "leading";
+  return "leading";
+}
+
+export function MediaObject(props: MediaObjectProps) {
+  const { title, description, body, meta, avatar, src, icon, action, truncate, style } = props;
+  const { tokens } = useTheme();
+  const align = alignOf(props);
+  const direction = directionOf(props);
+
+  const container: StyleProp<ViewStyle> = [
+    s.containerBase,
+    { flexDirection: s.DIRECTION_ROW[direction], alignItems: s.ALIGN_ITEMS[align] },
+    props.bordered ? s.borderedSurface(tokens) : null,
+    style,
+  ];
+
+  // Leading media: photo > initials avatar > icon box. Only one renders.
+  let media: ReactNode = null;
+  if (src) {
+    media = (
+      <View style={s.photoBox(tokens)}>
+        <Image style={s.photoImage} source={{ uri: src }} accessibilityLabel={title} resizeMode="cover" />
+      </View>
+    );
+  } else if (avatar) {
+    media = <Avatar name={avatar}>{avatar}</Avatar>;
+  } else if (icon != null) {
+    media = (
+      <View style={s.iconBox(tokens)}>
+        {typeof icon === "string" ? <Text style={s.iconGlyph(tokens)}>{icon}</Text> : icon}
+      </View>
+    );
+  }
+
+  // The engine has no truncate utility; RN clamps text via numberOfLines, which
+  // is the supported equivalent (single line with an ellipsis on overflow).
+  return (
+    <View style={container}>
+      {media}
+      <View style={s.content}>
+        {title != null ? (
+          <Text style={s.title(tokens)} numberOfLines={truncate ? 1 : undefined}>
+            {title}
+          </Text>
+        ) : null}
+        {description != null ? (
+          <Text style={s.description(tokens)} numberOfLines={truncate ? 1 : undefined}>
+            {description}
+          </Text>
+        ) : null}
+        {body != null ? <Text style={s.body(tokens)}>{body}</Text> : null}
+      </View>
+      {meta != null ? <Text style={s.meta(tokens)}>{meta}</Text> : null}
+      {action != null ? <View style={s.actionBox}>{action}</View> : null}
+    </View>
+  );
+}

package/src/molecules/stacked-lists/stacked-lists.md

@@ -0,0 +1,116 @@
+# Stacked Lists
+
+Vertical lists with avatar, two-line items, and trailing metadata. Used for contacts, activity feeds, and data previews.
+
+## Usage
+
+```tsx
+<StackedList
+  items={[
+    { name: "Rachel Chen", detail: "rachel.chen@example.com", meta: "admin" },
+    { name: "Ada Lovelace", detail: "ada@example.com", meta: "editor" },
+    { name: "Kevin Turner", detail: "kevin@example.com", meta: "viewer" }
+  ]}
+/>
+```
+
+## Variants
+
+### Variant - clickable
+
+```tsx
+<StackedList
+  items={[
+    { name: "Rachel Chen", detail: "rachel.chen@example.com", meta: "2h ago" },
+    { name: "Ada Lovelace", detail: "ada@example.com", meta: "5h ago" },
+    { name: "Kevin Turner", detail: "kevin@example.com", meta: "1d ago" }
+  ]}
+  clickable
+/>
+```
+
+### Variant - card
+
+```tsx
+<StackedList
+  items={[
+    { name: "Rachel Chen", detail: "Engineering Lead" },
+    { name: "Ada Lovelace", detail: "Staff Engineer" }
+  ]}
+  card
+  title="Team members"
+  addAction="Add"
+  rowMenu
+/>
+```
+
+## Do & Don't
+
+### Two-line with avatar
+
+**Do** — Primary line bold; secondary line smaller and muted, truncated so long values never wrap.
+
+```tsx
+<StackedList items={[
+    { name: "Rachel Chen", detail: "rachel.chen@example.com", initials: "RC" }
+  ]} />
+```
+
+**Don't** — Equal weight on both lines flattens the hierarchy; the email competes with the name.
+
+```tsx
+<View style={{ borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, overflow: "hidden", ...shadow("sm"), width: "100%", maxWidth: 560 }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12 }}>
+    <Avatar name="Rachel Chen">RC</Avatar>
+    <View style={{ minWidth: 0, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <Text style={{ fontSize: 13.5, fontWeight: "600", color: tokens.foreground }}>Rachel Chen</Text>
+      <Text style={{ fontSize: 13.5, fontWeight: "600", color: tokens.foreground }}>rachel.chen@example.com</Text>
+    </View>
+  </View>
+</View>
+```
+
+### Clickable
+
+**Do** — Wrap the row in a link with a hover background and a trailing chevron to signal drilldown.
+
+```tsx
+<StackedList clickable items={[
+    { name: "Ada Lovelace", detail: "ada@example.com", meta: "5h ago", initials: "AL" }
+  ]} />
+```
+
+**Don't** — A drilldown row with no hover state and no chevron gives no hint it is interactive.
+
+```tsx
+<StackedList items={[
+    { name: "Ada Lovelace", detail: "ada@example.com", meta: "5h ago", initials: "AL" }
+  ]} />
+```
+
+### Card surface group
+
+**Do** — Separate the titled header with a rule and give each row a trailing action menu.
+
+```tsx
+<StackedList card title="Team members" addAction="Add" rowMenu items={[
+    { name: "Rachel Chen", detail: "Engineering Lead", initials: "RC" }
+  ]} />
+```
+
+**Don't** — A header with no rule blends into the rows, and dropping the per-row action removes the affordance.
+
+```tsx
+<View style={{ borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, overflow: "hidden", ...shadow("sm"), width: "100%", maxWidth: 560 }}>
+  <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 20, paddingVertical: 12 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Team members</Text>
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12 }}>
+    <Avatar name="Rachel Chen">RC</Avatar>
+    <View style={{ minWidth: 0, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <Text style={{ fontSize: 13.5, fontWeight: "600", color: tokens.foreground }}>Rachel Chen</Text>
+      <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>Engineering Lead</Text>
+    </View>
+  </View>
+</View>
+```

package/src/molecules/stacked-lists/stacked-lists.styles.ts

@@ -0,0 +1,111 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow } from "../../style/index.js";
+
+// Co-located StackedList styles. Layout-only fragments are static objects;
+// anything that reads a color is a function of the active tokens (so the surface,
+// dividers, and labels follow light/dark and read as glass when the
+// ThemeProvider's surface is "glass", since tokens.card goes translucent there).
+
+// --- outer frame ------------------------------------------------------------
+
+// w-full max-w-[560px]: full width, capped at 560px.
+export const outer: ViewStyle = { width: "100%", maxWidth: 560 };
+
+// The card surface used by the `card` variant and as the optional frame when a
+// title is supplied: rounded-lg border bg-card overflow-hidden shadow-sm.
+export function cardSurface(tokens: ColorTokens): ViewStyle {
+  return {
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: tokens.border,
+    backgroundColor: tokens.card,
+    overflow: "hidden",
+    ...shadow("sm"),
+  };
+}
+
+// --- rows -------------------------------------------------------------------
+
+// flex-row items-center gap-3 px-5 py-3.
+export const rowBase: ViewStyle = {
+  flexDirection: "row",
+  alignItems: "center",
+  gap: 12,
+  paddingHorizontal: 20,
+  paddingVertical: 12,
+};
+
+// border-b border-border: the hairline between ruled rows.
+export function rowDivider(tokens: ColorTokens): ViewStyle {
+  return { borderBottomWidth: 1, borderColor: tokens.border };
+}
+
+// active:bg-accent press surface (clickable rows and the overflow menu button).
+export function pressedSurface(tokens: ColorTokens): ViewStyle {
+  return { backgroundColor: tokens.accent };
+}
+
+// flex-1: the primary + secondary text column.
+export const column: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// --- text -------------------------------------------------------------------
+
+// text-sm font-medium text-foreground: the primary (name) line.
+export function nameLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// text-xs text-muted-foreground: the secondary (detail) line, also the trailing
+// meta text and the trailing chevron.
+export function mutedLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] };
+}
+
+// --- header -----------------------------------------------------------------
+
+// flex-row items-center justify-between border-b border-border px-5 py-3.
+export function header(tokens: ColorTokens): ViewStyle {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    borderBottomWidth: 1,
+    borderColor: tokens.border,
+    paddingHorizontal: 20,
+    paddingVertical: 12,
+  };
+}
+
+// text-sm font-semibold text-foreground: the header title.
+export function headerTitle(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground };
+}
+
+// --- add-action button ------------------------------------------------------
+
+// flex-row items-center gap-1.5: the leading-plus + label row inside addAction.
+export const addActionRow: ViewStyle = { flexDirection: "row", alignItems: "center", gap: 6 };
+
+// text-xs font-medium text-foreground: the addAction button label.
+export function addActionLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, fontWeight: "500", color: tokens.foreground };
+}
+
+// --- overflow ("...") menu --------------------------------------------------
+
+// h-7 w-7 flex-row items-center justify-center gap-1 rounded-md bg-transparent.
+export const menuButton: ViewStyle = {
+  height: 28,
+  width: 28,
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: 4,
+  borderRadius: 6,
+  backgroundColor: "transparent",
+};
+
+// h-1 w-1 rounded-full bg-foreground: one of the three overflow dots.
+export function menuDot(tokens: ColorTokens): ViewStyle {
+  return { height: 4, width: 4, borderRadius: 9999, backgroundColor: tokens.foreground };
+}

package/src/molecules/stacked-lists/stacked-lists.tsx

@@ -0,0 +1,195 @@
+import { type ReactNode } from "react";
+import { type GestureResponderEvent } from "react-native";
+import { View, Pressable, 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 { Icon } from "../../atoms/icon/icon.js";
+import * as s from "./stacked-lists.styles.js";
+
+// A stacked list is a vertical list of rows separated by hairlines, each row a
+// leading avatar, a primary + secondary text column, and trailing meta/badge/
+// action. It is the building block for contact lists, activity feeds, and data
+// previews.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf).
+//
+// - Variant axis (pick one; default is the plain two-line list): `clickable`
+//   makes each row a pressable drilldown with a hover/press surface and a
+//   trailing chevron; `card` wraps the list in a titled card surface with an
+//   optional header. `clickable` wins over `card` when both are passed.
+// - Divider (orthogonal boolean, on by default): draws a hairline between rows.
+//   Pass `flush` to drop the dividers. The card variant always keeps its rows
+//   ruled regardless of `flush`, matching the documented card surface group.
+
+/** One row in the list. */
+export interface StackedListItem {
+  /** Primary line, bold (e.g. a person's name). */
+  name: string;
+  /** Secondary line, smaller and muted (e.g. an email or role). */
+  detail: string;
+  /** Trailing metadata text (e.g. "2h ago"). Ignored when `badge` is set. */
+  meta?: string;
+  /** Trailing badge label; rendered as a <Badge> instead of plain meta text. */
+  badge?: string;
+  /** Photo URL for the avatar; falls back to initials when absent. */
+  avatar?: string;
+  /** Initials shown when there is no photo; derived from `name` when omitted. */
+  initials?: string;
+}
+
+export interface StackedListProps {
+  /** Rows to render. */
+  items?: StackedListItem[];
+  /** Optional header title; shown above the rows, separated by a rule. */
+  title?: ReactNode;
+  /** Trailing header content (e.g. an action button); only shown with a title.
+   *  Takes precedence over `addAction` when both are supplied. */
+  action?: ReactNode;
+  /** Convenience header action: renders a small outlined button with a leading
+   *  plus icon and this label (e.g. "Add"). Only shown with a title and when
+   *  `action` is not set. Serializable, so the playground can drive it. */
+  addAction?: string;
+  /** Appends a trailing ghost overflow ("...") action-menu button to every row.
+   *  Press is reported through `onPressItemMenu`. */
+  rowMenu?: boolean;
+  /** Press handler for a row, by index. Only used in the `clickable` variant. */
+  onPressItem?: (index: number, event: GestureResponderEvent) => void;
+  /** Press handler for a row's overflow menu, by index. Used with `rowMenu`. */
+  onPressItemMenu?: (index: number, event: GestureResponderEvent) => void;
+  // Variant (pick one; default is the plain two-line list).
+  clickable?: boolean;
+  card?: boolean;
+  // Divider modifier: rows are ruled by default; `flush` removes the hairlines.
+  flush?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+type Variant = "two-line" | "clickable" | "card";
+
+// Variant precedence when more than one is passed: first match wins.
+function variantOf(p: StackedListProps): Variant {
+  if (p.clickable) return "clickable";
+  if (p.card) return "card";
+  return "two-line";
+}
+
+// Two initials from a name, used when an item supplies no explicit initials and
+// no photo (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 StackedList(props: StackedListProps) {
+  const { items = [], title, action, addAction, rowMenu, onPressItem, onPressItemMenu, flush, style } = props;
+  const variant = variantOf(props);
+  const { tokens } = useTheme();
+
+  // The header action: an explicit ReactNode wins; otherwise a small outlined
+  // button with a leading plus icon when `addAction` supplies a label.
+  const headerAction =
+    action != null ? (
+      action
+    ) : addAction != null ? (
+      <Button outline small>
+        <View style={s.addActionRow}>
+          <Icon plus size={13} />
+          <Text style={s.addActionLabel(tokens)}>{addAction}</Text>
+        </View>
+      </Button>
+    ) : null;
+
+  // The card variant always rules its rows; the others rule unless `flush`.
+  const ruled = variant === "card" ? true : !flush;
+  const framed = variant === "card" || title != null;
+
+  const lastIndex = items.length - 1;
+
+  const renderColumn = (item: StackedListItem) => (
+    <View style={s.column}>
+      <Text style={s.nameLabel(tokens)} numberOfLines={1}>
+        {item.name}
+      </Text>
+      <Text style={s.mutedLabel(tokens)} numberOfLines={1}>
+        {item.detail}
+      </Text>
+    </View>
+  );
+
+  const renderTrailing = (item: StackedListItem) => {
+    if (item.badge != null) return <Badge secondary>{item.badge}</Badge>;
+    if (item.meta != null) return <Text style={s.mutedLabel(tokens)}>{item.meta}</Text>;
+    return null;
+  };
+
+  // A ghost overflow ("...") action-menu button drawn as three horizontal dots;
+  // the Icon set has no more-horizontal glyph, so the dots are primitives.
+  const renderMenu = (index: number) => (
+    <Pressable
+      style={({ pressed }) => [s.menuButton, pressed ? s.pressedSurface(tokens) : null]}
+      onPress={(event) => onPressItemMenu?.(index, event)}
+      accessibilityRole="button"
+      accessibilityLabel="Actions"
+    >
+      <View style={s.menuDot(tokens)} />
+      <View style={s.menuDot(tokens)} />
+      <View style={s.menuDot(tokens)} />
+    </Pressable>
+  );
+
+  const renderAvatar = (item: StackedListItem) => (
+    <Avatar src={item.avatar} name={item.name}>
+      {item.initials ?? initialsFrom(item.name)}
+    </Avatar>
+  );
+
+  const rows = items.map((item, index) => {
+    const divider = ruled && index < lastIndex ? s.rowDivider(tokens) : null;
+
+    if (variant === "clickable") {
+      return (
+        <Pressable
+          key={index}
+          style={({ pressed }) => [s.rowBase, pressed ? s.pressedSurface(tokens) : null, divider]}
+          onPress={(event) => onPressItem?.(index, event)}
+          accessibilityRole="button"
+        >
+          {renderAvatar(item)}
+          {renderColumn(item)}
+          {renderTrailing(item)}
+          {rowMenu ? renderMenu(index) : null}
+          <Text style={s.mutedLabel(tokens)}>{"›"}</Text>
+        </Pressable>
+      );
+    }
+
+    return (
+      <View key={index} style={[s.rowBase, divider]}>
+        {renderAvatar(item)}
+        {renderColumn(item)}
+        {renderTrailing(item)}
+        {rowMenu ? renderMenu(index) : null}
+      </View>
+    );
+  });
+
+  const header =
+    title != null ? (
+      <View style={s.header(tokens)}>
+        <Text style={s.headerTitle(tokens)}>{title}</Text>
+        {headerAction != null ? <View>{headerAction}</View> : null}
+      </View>
+    ) : null;
+
+  return (
+    <View style={[s.outer, framed ? s.cardSurface(tokens) : null, style]}>
+      {header}
+      {rows}
+    </View>
+  );
+}