@olympusoss/canvas 3.2.1 → 5.0.0

package/src/molecules/code-block/code-block.tsx

@@ -0,0 +1,176 @@
+import { type GestureResponderEvent } from "react-native";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import * as s from "./code-block.styles.js";
+import { type Variant } from "./code-block.styles.js";
+
+// CodeBlock: a muted, rounded surface that shows preformatted code in a
+// monospace face. Newlines in `code` survive verbatim because RN Text honors
+// "\n", so a multi-line string renders as multiple lines without any markup.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Badge's toneOf). Axes:
+//
+// - Variant (pick one; default is the plain block):
+//     `terminal` > `numbered` > `inline` > plain.
+//   - plain: the muted code surface, padded, monospace.
+//   - terminal: a dark window with a chrome bar (traffic-light dots + a "bash"
+//     label) over a dark body, for shell transcripts. A leading "$ " prompt is
+//     rendered for command lines.
+//   - numbered: the plain surface with a left gutter of right-aligned line
+//     numbers, one per line.
+//   - inline: a short, single token rendered as an inline pill (rounded bg-muted
+//     chip), for code mentioned mid-sentence.
+// - `copy` (orthogonal): show a copy affordance pinned to the top-right corner.
+//   Ignored by the inline variant, which is too small to carry one.
+// - `wrap` (orthogonal): let long lines wrap instead of overflowing. Ignored by
+//   the inline variant.
+//
+// RN has no font-mono utility, so the monospace face is requested via an inline
+// `style={s.MONO}` on each code Text (the same approach Badge's `mono` uses).
+
+export interface CodeBlockProps {
+  /** The code to render. Newlines are preserved (RN Text honors "\n"). */
+  code?: string;
+  /** Optional filename or language label for the header bar. */
+  filename?: string;
+  language?: string;
+
+  // Variant (pick one; default is the plain block).
+  terminal?: boolean;
+  numbered?: boolean;
+  inline?: boolean;
+
+  // Orthogonal modifiers.
+  copy?: boolean;
+  wrap?: boolean;
+
+  /** Called when the copy affordance is pressed (text is passed back). */
+  onCopy?: (code: string, event: GestureResponderEvent) => void;
+
+  /** Escape hatch for layout/positioning composition (mainly width, margins). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Variant precedence when more than one is passed: first match wins.
+function variantOf(p: CodeBlockProps): Variant {
+  if (p.terminal) return "terminal";
+  if (p.numbered) return "numbered";
+  if (p.inline) return "inline";
+  return "plain";
+}
+
+const DEFAULT_CODE = 'const theme = getTheme();\nsetTheme(theme === "dark" ? "light" : "dark");';
+
+// A small, neutral chip pinned to the top-right corner for the copy affordance.
+function CopyButton({
+  text,
+  onCopy,
+  dark,
+}: {
+  text: string;
+  onCopy?: (code: string, event: GestureResponderEvent) => void;
+  dark?: boolean;
+}) {
+  const { tokens } = useTheme();
+  const isDark = !!dark;
+  return (
+    <Pressable
+      style={({ pressed }) => [s.copyButton(tokens, isDark), pressed ? { opacity: 0.8 } : null]}
+      onPress={(e) => onCopy?.(text, e)}
+      accessibilityRole="button"
+      accessibilityLabel="Copy code"
+    >
+      <Text style={s.copyText(tokens, isDark)}>Copy</Text>
+    </Pressable>
+  );
+}
+
+export function CodeBlock(props: CodeBlockProps) {
+  const { code = DEFAULT_CODE, filename, language, copy, wrap, onCopy, style } = props;
+  const variant = variantOf(props);
+  const { tokens } = useTheme();
+  const lines = code.split("\n");
+
+  // Inline: a short token rendered as an inline pill. No header, copy, or wrap.
+  if (variant === "inline") {
+    return (
+      <View style={[s.inlineBox(tokens), style]}>
+        <Text style={[s.codeText(tokens), s.MONO, { fontSize: 13 }]}>{code}</Text>
+      </View>
+    );
+  }
+
+  // Terminal: a dark window with a chrome bar over a dark body.
+  if (variant === "terminal") {
+    const label = language ?? filename ?? "bash";
+    return (
+      <View style={[s.terminalOuter(tokens), style]}>
+        {/* Chrome bar: three traffic-light dots and a faint label. */}
+        <View style={s.terminalChrome}>
+          <View style={s.trafficDot("red")} />
+          <View style={s.trafficDot("amber")} />
+          <View style={s.trafficDot("green")} />
+          <Text style={[s.terminalLabel, s.MONO]}>{label}</Text>
+        </View>
+        {/* Body: each line gets a non-selectable "$ " prompt. */}
+        <View style={s.terminalBody}>
+          {lines.map((line, i) => (
+            <View key={i} style={s.terminalRow}>
+              <Text style={[s.terminalPrompt, s.MONO]}>{"$ "}</Text>
+              <Text style={[s.terminalLine, s.MONO]} numberOfLines={wrap ? undefined : 1}>
+                {line}
+              </Text>
+            </View>
+          ))}
+        </View>
+        {copy ? <CopyButton text={code} onCopy={onCopy} dark /> : null}
+      </View>
+    );
+  }
+
+  // Numbered: the plain surface with a right-aligned line-number gutter.
+  if (variant === "numbered") {
+    return (
+      <View style={[s.relative, style]}>
+        <View style={[s.surface(tokens), s.numberedSurface]}>
+          {/* Gutter: right-aligned, dimmed line numbers. */}
+          <View style={s.numberedGutter}>
+            {lines.map((_, i) => (
+              <Text key={i} style={[s.codeType, s.gutterText(tokens), s.MONO]}>
+                {String(i + 1)}
+              </Text>
+            ))}
+          </View>
+          {/* Code column: one Text per line so the gutter stays aligned. */}
+          <View style={s.numberedCodeCol}>
+            {lines.map((line, i) => (
+              <Text
+                key={i}
+                style={[s.codeType, s.codeText(tokens), s.MONO]}
+                numberOfLines={wrap ? undefined : 1}
+              >
+                {line}
+              </Text>
+            ))}
+          </View>
+        </View>
+        {copy ? <CopyButton text={code} onCopy={onCopy} /> : null}
+      </View>
+    );
+  }
+
+  // Plain (default): the muted code surface, padded, monospace.
+  return (
+    <View style={[s.relative, style]}>
+      <View style={[s.surface(tokens), s.surfacePad]}>
+        <Text
+          style={[s.codeType, s.codeText(tokens), s.MONO]}
+          numberOfLines={wrap ? undefined : lines.length}
+        >
+          {code}
+        </Text>
+      </View>
+      {copy ? <CopyButton text={code} onCopy={onCopy} /> : null}
+    </View>
+  );
+}

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

@@ -0,0 +1,129 @@
+# Description Lists
+
+Key-value pairs in stacked, two-column, or inline-edit layouts. Used for detail panels, settings, and profile views.
+
+## Usage
+
+```tsx
+<DescriptionList
+  card
+  twoColumn
+  divided
+  title="Application details"
+  subtitle="Personal information and credentials."
+  items={[
+    { term: "Full name", value: "Rachel Chen" },
+    { term: "Email", value: "rachel.chen@example.com" },
+    { term: "Role", value: "admin", badge: true },
+    { term: "Status", value: "Active", status: true }
+  ]}
+/>
+```
+
+## Variants
+
+### Layout - inline-edit
+
+```tsx
+<DescriptionList
+  card
+  twoColumn
+  divided
+  title="Profile"
+  items={[
+    { term: "Name", value: "Rachel Chen", update: true },
+    { term: "Email", value: "rachel.chen@example.com", update: true },
+    { term: "Title", value: "Senior Engineer", update: true }
+  ]}
+/>
+```
+
+### Layout - stacked
+
+```tsx
+<DescriptionList
+  card
+  stacked
+  items={[
+    { term: "Full name", value: "Rachel Chen" },
+    { term: "Email", value: "rachel.chen@example.com" },
+    { term: "Client ID", value: "clnt_01H2X8K9P3Q7VN4W6R5T0JYMZF", mono: true }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Two-column
+
+**Do** — Fix the label column wide enough for the longest term so every value lines up on one edge.
+
+```tsx
+<DescriptionList twoColumn divided style={{ maxWidth: 420 }} items={[
+    { term: "Client identifier", value: "clnt_01H2X8K9P3Q7VN4W6R5T0JYMZF", mono: true },
+    { term: "Status", value: "Active", status: true }
+  ]} />
+```
+
+**Don't** — A too-narrow label column wraps the longest term and knocks the two columns out of alignment.
+
+```tsx
+<View style={{ maxWidth: 420 }}>
+  <View style={{ flexDirection: "row", alignItems: "baseline", gap: 16, borderBottomWidth: 1, borderColor: tokens.border, paddingVertical: 12 }}>
+    <Text style={{ width: 64, fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Client identifier</Text>
+    <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 12.5, fontWeight: "500", color: tokens.foreground, fontFamily: "monospace" }}>clnt_01H2X8K9P3Q7VN4W6R5T0JYMZF</Text>
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "baseline", gap: 16, paddingVertical: 12 }}>
+    <Text style={{ width: 64, fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Status</Text>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <Badge status success>Active</Badge>
+    </View>
+  </View>
+</View>
+```
+
+### Inline-edit
+
+**Do** — Give every editable row a trailing Update affordance so the inline editor is discoverable.
+
+```tsx
+<DescriptionList twoColumn style={{ maxWidth: 420 }} items={[
+    { term: "Name", value: "Rachel Chen", update: true },
+    { term: "Email", value: "rachel.chen@example.com", update: true }
+  ]} />
+```
+
+**Don't** — Editable rows that look identical to read-only ones give no hint a value can be changed.
+
+```tsx
+<DescriptionList twoColumn style={{ maxWidth: 420 }} items={[
+    { term: "Name", value: "Rachel Chen" },
+    { term: "Email", value: "rachel.chen@example.com" }
+  ]} />
+```
+
+### Stacked
+
+**Do** — Keep the label small, uppercase, and muted above a full-weight value so the data stays primary.
+
+```tsx
+<DescriptionList stacked style={{ maxWidth: 320 }} items={[
+    { term: "Full name", value: "Rachel Chen" },
+    { term: "Email", value: "rachel.chen@example.com" }
+  ]} />
+```
+
+**Don't** — Muting the value and bolding nothing inverts the hierarchy; the label outweighs the data it describes.
+
+```tsx
+<View style={{ maxWidth: 320, gap: 16 }}>
+  <View style={{ gap: 4 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Full name</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Rachel Chen</Text>
+  </View>
+  <View style={{ gap: 4 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Email</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>rachel.chen@example.com</Text>
+  </View>
+</View>
+```

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

@@ -0,0 +1,102 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow } from "../../style/index.js";
+
+// Co-located DescriptionList styles. Layout-only fragments are static objects;
+// anything that reads a color is a function of the active tokens (so the card
+// surface follows light/dark and reads as glass when the ThemeProvider's surface
+// is "glass", since tokens.card is swapped translucent at the theming level).
+
+export type Layout = "inline" | "twoColumn" | "stacked";
+
+// Card surface: rounded, bordered, card fill, soft shadow. When a header band is
+// present the card carries no padding (the header and rows supply their own
+// px-6) so the header rule spans the full width; otherwise the card pads itself.
+export function cardSurface(tokens: ColorTokens): ViewStyle {
+  return { borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, ...shadow("sm") };
+}
+
+// The self-padding applied to a card with no header band (p-6).
+export const cardPad: ViewStyle = { padding: 24 };
+
+// gap-3 between rows when there is no header band wrapping them.
+export const stackGap: ViewStyle = { gap: 12 };
+
+// With a header, rows sit in their own px-6 group beneath the bordered band.
+export const rowsWrap: ViewStyle = { paddingHorizontal: 24, gap: 12 };
+
+// --- term / value text ------------------------------------------------------
+
+// Term: small, muted label.
+export function termLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}
+
+// Stacked term: uppercased and tracked so the label reads as secondary above a
+// full-weight value.
+export function termStacked(tokens: ColorTokens): TextStyle {
+  return {
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "500",
+    textTransform: "uppercase",
+    letterSpacing: 0.4,
+    color: tokens["muted-foreground"],
+  };
+}
+
+// The two-column term's fixed label column (w-40). Lands on a Text.
+export const termColumn: TextStyle = { width: 160 };
+
+// Value: full-weight data it describes.
+export function valueLabel(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground };
+}
+
+// The inline value is right-aligned in its row.
+export const valueAlignRight: TextStyle = { textAlign: "right" };
+
+// Monospace value face, for tokens, scopes, identifiers.
+export const valueMono: TextStyle = { fontFamily: "monospace" };
+
+// --- rows -------------------------------------------------------------------
+
+// Row layout per axis.
+export const rowLayout: Record<Layout, ViewStyle> = {
+  inline: { flexDirection: "row", alignItems: "baseline", justifyContent: "space-between", gap: 16 },
+  twoColumn: { flexDirection: "row", alignItems: "baseline", gap: 16 },
+  stacked: { gap: 4 },
+};
+
+// A divided list pads each row vertically so the rule sits clear of the text.
+export const rowDividedPad: ViewStyle = { paddingBottom: 12 };
+
+// The hairline beneath every divided row except the last.
+export function rowDivider(tokens: ColorTokens): ViewStyle {
+  return { borderBottomWidth: 1, borderColor: tokens.border };
+}
+
+// The two-column value cell: grows to fill, with the value and trailing
+// affordance pushed to opposite ends.
+export const twoColumnValueCell: ViewStyle = {
+  flexGrow: 1,
+  flexShrink: 1,
+  flexBasis: "0%",
+  flexDirection: "row",
+  alignItems: "baseline",
+  justifyContent: "space-between",
+  gap: 16,
+};
+
+// --- header band ------------------------------------------------------------
+
+export function headerBand(tokens: ColorTokens): ViewStyle {
+  return { borderBottomWidth: 1, borderColor: tokens.border, paddingHorizontal: 24, paddingVertical: 16, gap: 2 };
+}
+
+export function headerTitle(tokens: ColorTokens): TextStyle {
+  return { fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground };
+}
+
+export function headerSubtitle(tokens: ColorTokens): TextStyle {
+  return { fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] };
+}

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

@@ -0,0 +1,133 @@
+import { View, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Badge } from "../../atoms/badge/badge.js";
+import { Button } from "../../atoms/button/button.js";
+import * as s from "./description-lists.styles.js";
+import { type Layout } from "./description-lists.styles.js";
+
+// DescriptionList: term/value pairs for detail panels, settings, and profile
+// views. Each item is a { term, value } pair. The term is the small muted
+// label; the value is the full-weight data it describes, so the data always
+// outranks its label.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf / Card's surfaceOf).
+//
+// - Layout (pick one; precedence inline > twoColumn > stacked):
+//   `inline` lays the term on the left and the value on the right of a single
+//   row; `twoColumn` puts the term in a fixed 160px label column with the value
+//   beside it (the read-only detail look); the default `stacked` puts a small
+//   uppercase muted label above a full-weight value.
+// - Rows: `divided` draws a hairline (border-b border-border) under every row
+//   but the last, for the two-column detail look.
+// - Surface: `card` wraps the whole list in a card surface (border, radius,
+//   padding) so it reads as a self-contained panel. `title`/`subtitle` add a
+//   bordered header band to the card.
+//
+// Per-item value affordances (all optional, render the value richly):
+// `badge` renders the value as a secondary metadata Badge; `status` renders it
+// as a success status Badge with a leading dot (live state); `mono` sets a
+// monospace face for tokens/IDs; `update` appends a trailing "Update" link
+// button so an editable row is discoverable (the inline-edit affordance).
+//
+// Layout, rows, and surface are orthogonal axes and combine freely.
+
+export interface DescriptionListItem {
+  term: string;
+  value: string;
+  // Render the value as a secondary metadata badge (e.g. a role).
+  badge?: boolean;
+  // Render the value as a success status badge with a leading dot (live state).
+  status?: boolean;
+  // Monospace value face, for tokens, scopes, identifiers.
+  mono?: boolean;
+  // Append a trailing "Update" link affordance, marking the row editable.
+  update?: boolean;
+}
+
+export interface DescriptionListProps {
+  items: DescriptionListItem[];
+  // Card header band (only shown when `card`): a title and optional subtitle.
+  title?: string;
+  subtitle?: string;
+  // Layout (pick one; precedence inline > twoColumn > stacked).
+  inline?: boolean;
+  twoColumn?: boolean;
+  stacked?: boolean;
+  // Rows: hairline divider beneath every row but the last.
+  divided?: boolean;
+  // Surface: wrap the list in a card surface.
+  card?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Layout precedence when more than one is passed: first match wins.
+function layoutOf(p: DescriptionListProps): Layout {
+  if (p.inline) return "inline";
+  if (p.twoColumn) return "twoColumn";
+  return "stacked";
+}
+
+// Render a value cell: a badge family, a monospace token, or plain text.
+function Value({ item, align }: { item: DescriptionListItem; align?: boolean }) {
+  const { tokens } = useTheme();
+  if (item.status) return <Badge status success>{item.value}</Badge>;
+  if (item.badge) return <Badge secondary>{item.value}</Badge>;
+  if (item.mono) {
+    return <Text style={[s.valueLabel(tokens), s.valueMono]}>{item.value}</Text>;
+  }
+  return <Text style={[s.valueLabel(tokens), align ? s.valueAlignRight : null]}>{item.value}</Text>;
+}
+
+export function DescriptionList(props: DescriptionListProps) {
+  const { items, title, subtitle, divided, card, style } = props;
+  const { tokens } = useTheme();
+  const layout = layoutOf(props);
+  const hasHeader = card && !!title;
+
+  const container: StyleProp<ViewStyle> = [
+    card ? s.cardSurface(tokens) : null,
+    // No global padding when a header band supplies its own px-6 per section.
+    card && !hasHeader ? s.cardPad : null,
+    !hasHeader ? s.stackGap : null,
+    style,
+  ];
+
+  const rows = items.map((item, index) => {
+    const last = index === items.length - 1;
+    // A divided list draws a hairline under each row except the last, and pads
+    // the row vertically so the rule sits clear of the text.
+    const row: StyleProp<ViewStyle> = [
+      s.rowLayout[layout],
+      divided ? s.rowDividedPad : null,
+      divided && !last ? s.rowDivider(tokens) : null,
+    ];
+    return (
+      <View key={`${item.term}-${index}`} style={row}>
+        <Text style={[layout === "stacked" ? s.termStacked(tokens) : s.termLabel(tokens), layout === "twoColumn" ? s.termColumn : null]}>
+          {item.term}
+        </Text>
+        <View style={layout === "twoColumn" ? s.twoColumnValueCell : null}>
+          <Value item={item} align={layout === "inline"} />
+          {item.update ? (
+            <Button link small>
+              Update
+            </Button>
+          ) : null}
+        </View>
+      </View>
+    );
+  });
+
+  return (
+    <View style={container}>
+      {hasHeader ? (
+        <View style={s.headerBand(tokens)}>
+          <Text style={s.headerTitle(tokens)}>{title}</Text>
+          {subtitle ? <Text style={s.headerSubtitle(tokens)}>{subtitle}</Text> : null}
+        </View>
+      ) : null}
+      {hasHeader ? <View style={s.rowsWrap}>{rows}</View> : rows}
+    </View>
+  );
+}