@olympusoss/canvas 3.2.1 → 5.0.0

package/src/atoms/typography/typography.md

@@ -0,0 +1,330 @@
+# Typography
+
+Type scale classes for headings, body text, and helper styles.
+
+## Usage
+
+```tsx
+<Typography h1>The quick brown fox</Typography>
+```
+
+## Variants
+
+### Style - display
+
+```tsx
+<Typography display>The quick brown fox</Typography>
+```
+
+### Style - h2
+
+```tsx
+<Typography h2>The quick brown fox</Typography>
+```
+
+### Style - h3
+
+```tsx
+<Typography h3>The quick brown fox</Typography>
+```
+
+### Style - h4
+
+```tsx
+<Typography h4>The quick brown fox</Typography>
+```
+
+### Style - h5
+
+```tsx
+<Typography h5>The quick brown fox</Typography>
+```
+
+### Style - body
+
+```tsx
+<Typography body>The quick brown fox</Typography>
+```
+
+### Style - small
+
+```tsx
+<Typography small>The quick brown fox</Typography>
+```
+
+### Style - tiny
+
+```tsx
+<Typography tiny>The quick brown fox</Typography>
+```
+
+### Style - muted
+
+```tsx
+<Typography muted>The quick brown fox</Typography>
+```
+
+### Style - caption
+
+```tsx
+<Typography caption>The quick brown fox</Typography>
+```
+
+### Style - code
+
+```tsx
+<Typography code>The quick brown fox</Typography>
+```
+
+### Style - mono
+
+```tsx
+<Typography mono>The quick brown fox</Typography>
+```
+
+## Do & Don't
+
+### display
+
+**Do** — Use display once per hero, then drop to a muted line for the supporting copy.
+
+```tsx
+<View>
+  <Typography display>Welcome</Typography>
+  <Typography muted style={{ marginTop: 8 }}>Sign in to pick up where you left off.</Typography>
+</View>
+```
+
+**Don't** — Two display-size lines in one view fight for attention and leave no clear focal point.
+
+```tsx
+<View style={{ gap: 8 }}>
+  <Typography display>Welcome</Typography>
+  <Typography display>Get started</Typography>
+</View>
+```
+
+### h1
+
+**Do** — Give each page a single h1, then step down to h2 for the sections beneath it.
+
+```tsx
+<View>
+  <Typography h1>Billing</Typography>
+  <Typography h2 style={{ marginTop: 16 }}>Invoices</Typography>
+</View>
+```
+
+**Don't** — Two h1 titles on a page break the document outline and confuse assistive tech.
+
+```tsx
+<View style={{ gap: 4 }}>
+  <Typography h1>Billing</Typography>
+  <Typography h1>Invoices</Typography>
+</View>
+```
+
+### h2
+
+**Do** — Follow an h1 with h2 for its top-level sections; don't skip the scale.
+
+```tsx
+<View>
+  <Typography h1>Settings</Typography>
+  <Typography h2 style={{ marginTop: 16 }}>Profile</Typography>
+</View>
+```
+
+**Don't** — Jumping from h1 straight to h4 skips a level and flattens the visible hierarchy.
+
+```tsx
+<View>
+  <Typography h1>Settings</Typography>
+  <Typography h4 style={{ marginTop: 16 }}>Profile</Typography>
+</View>
+```
+
+### h3
+
+**Do** — Reserve heading styles for titles; set running text in a small body utility.
+
+```tsx
+<View style={{ maxWidth: 340 }}>
+  <Typography h3>About Canvas</Typography>
+  <Typography body style={{ marginTop: 4 }}>Canvas is a universal React Native UI kit for building consistent product interfaces.</Typography>
+</View>
+```
+
+**Don't** — Body copy set in a heading style is hard to read in bulk and flattens the hierarchy.
+
+```tsx
+<Typography h3 style={{ maxWidth: 340 }}>Canvas is a universal React Native UI kit for building consistent product interfaces.</Typography>
+```
+
+### h4
+
+**Do** — Keep h4 to a short label and carry the explanation in a small supporting line.
+
+```tsx
+<View>
+  <Typography h4>Notifications</Typography>
+  <Typography small style={{ marginTop: 4 }}>Choose how and when we reach you.</Typography>
+</View>
+```
+
+**Don't** — h4 is a minor heading, not a place for full sentences; long text at this weight reads as a wall.
+
+```tsx
+<View style={{ gap: 4 }}>
+  <Typography h4>Notifications</Typography>
+  <Typography h4>A long descriptive sentence that explains everything in detail.</Typography>
+</View>
+```
+
+### h5
+
+**Do** — Use h5 only for the label; render the value in body so the pair stays scannable.
+
+```tsx
+<View>
+  <Typography h5>Members</Typography>
+  <Typography body style={{ marginTop: 2 }}>Aisha, Bao, Cleo, and 9 others have access.</Typography>
+</View>
+```
+
+**Don't** — Setting the value in h5 too makes the label and its data indistinguishable.
+
+```tsx
+<View style={{ gap: 4 }}>
+  <Typography h5>Members</Typography>
+  <Typography h5>Aisha, Bao, Cleo, and 9 others have access.</Typography>
+</View>
+```
+
+### body
+
+**Do** — Keep body copy in sentence case and let inline code carry the technical emphasis.
+
+```tsx
+<Typography body style={{ maxWidth: 340 }}>
+  Run 
+  <Typography code>npm install</Typography>
+  , then restart the dev server before you continue.
+</Typography>
+```
+
+**Don't** — All-caps emphasis inside body copy shouts and undercuts the relaxed reading rhythm.
+
+```tsx
+<Typography body style={{ maxWidth: 340 }}>
+  <Typography code>npm install</Typography>
+   THEN restart the dev server BEFORE you continue.
+</Typography>
+```
+
+### small
+
+**Do** — Use small for secondary captions on a plain surface, not for the primary label.
+
+```tsx
+<View>
+  <Typography body>Save changes</Typography>
+  <Typography small style={{ marginTop: 2 }}>Last saved 2 minutes ago.</Typography>
+</View>
+```
+
+**Don't** — small is muted-foreground; on a colored button it loses contrast and looks disabled.
+
+```tsx
+<Button secondary>
+  <Typography small>Save changes</Typography>
+</Button>
+```
+
+### tiny
+
+**Do** — Reserve tiny for short metadata like timestamps and counts beside the main text.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+  <Typography body>Deploy succeeded</Typography>
+  <Typography tiny>3m ago</Typography>
+</View>
+```
+
+**Don't** — tiny is for metadata, not legal prose; long copy at 12px strains the eye.
+
+```tsx
+<Typography tiny style={{ maxWidth: 300 }}>These terms govern your use of the service and your data; please read them carefully before you continue past this screen.</Typography>
+```
+
+### muted
+
+**Do** — Keep muted for de-emphasized context; give the actual action full foreground or primary color.
+
+```tsx
+<Typography body style={{ maxWidth: 340 }}>
+  Payment due May 31. 
+  <Typography body style={{ color: tokens.primary, textDecorationLine: "underline" }}>View invoices</Typography>
+</Typography>
+```
+
+**Don't** — A primary, clickable action in muted-foreground reads as disabled and is easy to miss.
+
+```tsx
+<Typography muted style={{ alignSelf: "flex-start", textDecorationLine: "underline" }}>View your invoices</Typography>
+```
+
+### caption
+
+**Do** — Use caption as a short eyebrow label above a section, then explain in body.
+
+```tsx
+<View>
+  <Typography caption>Billing</Typography>
+  <Typography body style={{ marginTop: 4 }}>Your subscription renews automatically each month.</Typography>
+</View>
+```
+
+**Don't** — Uppercase, letter-spaced caption text is illegible for anything longer than a label.
+
+```tsx
+<Typography caption style={{ maxWidth: 320 }}>Your subscription renews automatically each month unless you cancel from the billing page.</Typography>
+```
+
+### code
+
+**Do** — Use code for inline tokens inside a sentence; reach for the code block component for multi-line snippets.
+
+```tsx
+<Typography body>
+  Create a branch with 
+  <Typography code>git checkout -b feature</Typography>
+   before committing.
+</Typography>
+```
+
+**Don't** — The inline code utility has tight padding and no scroll; multi-line blocks overflow and clip.
+
+```tsx
+<Typography code>git checkout -b feature
+git add .
+git commit -m "wip"</Typography>
+```
+
+### mono
+
+**Do** — Use mono for identifiers, hashes, and tabular values where character alignment matters.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 16 }}>
+  <Typography small>Request ID</Typography>
+  <Typography mono>req_8f2c10ab</Typography>
+</View>
+```
+
+**Don't** — Mono spacing makes prose sentences sparse and slow to read; it is meant for fixed-width data.
+
+```tsx
+<Typography mono style={{ maxWidth: 320 }}>We could not process your request because the upstream service returned an unexpected response.</Typography>
+```

package/src/atoms/typography/typography.styles.ts

@@ -0,0 +1,95 @@
+import { type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Typography styles. One axis (role), each role mapping to a single
+// TextStyle built from the active brand tokens (so the type color follows
+// light/dark and the glass surface). The component resolves the active role by
+// first-match precedence and spreads the matching fragment.
+//
+// Every fragment is a TextStyle: Typography renders a single Text, so layout +
+// type + color all live on the Text. The `code` role additionally carries the
+// muted fill and pill padding (a Text can hold backgroundColor/padding in RN).
+
+export type Role =
+  | "display"
+  | "h1"
+  | "h2"
+  | "h3"
+  | "h4"
+  | "h5"
+  | "body"
+  | "small"
+  | "tiny"
+  | "muted"
+  | "caption"
+  | "code"
+  | "mono";
+
+// Type + layout per role, color-free (the parts that don't read a token).
+// Mirrors the docs' typeScale: heading sizes get the tight tracking, body gets
+// the relaxed line height, caption gets uppercase + wide tracking, and `code`
+// carries the self-start pill box (radius + padding).
+export const roleType: Record<Role, TextStyle> = {
+  // text-5xl font-bold tracking-tight
+  display: { fontSize: 48, lineHeight: 48, fontWeight: "700", letterSpacing: -0.4 },
+  // text-4xl font-bold tracking-tight
+  h1: { fontSize: 36, lineHeight: 40, fontWeight: "700", letterSpacing: -0.4 },
+  // text-3xl font-semibold tracking-tight
+  h2: { fontSize: 30, lineHeight: 36, fontWeight: "600", letterSpacing: -0.4 },
+  // text-2xl font-semibold tracking-tight
+  h3: { fontSize: 24, lineHeight: 32, fontWeight: "600", letterSpacing: -0.4 },
+  // text-xl font-semibold tracking-tight
+  h4: { fontSize: 20, lineHeight: 28, fontWeight: "600", letterSpacing: -0.4 },
+  // text-lg font-semibold
+  h5: { fontSize: 18, lineHeight: 28, fontWeight: "600" },
+  // text-sm leading-relaxed (the relaxed line height overrides text-sm's 20)
+  body: { fontSize: 14, lineHeight: 28 },
+  // text-sm
+  small: { fontSize: 14, lineHeight: 20 },
+  // text-xs
+  tiny: { fontSize: 12, lineHeight: 16 },
+  // text-sm
+  muted: { fontSize: 14, lineHeight: 20 },
+  // text-xs uppercase tracking-wide
+  caption: { fontSize: 12, lineHeight: 16, textTransform: "uppercase", letterSpacing: 0.4 },
+  // self-start rounded bg-muted px-1.5 py-0.5 text-sm (fill added in roleColor)
+  code: {
+    alignSelf: "flex-start",
+    borderRadius: 4,
+    paddingHorizontal: 6,
+    paddingVertical: 2,
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  // text-sm
+  mono: { fontSize: 14, lineHeight: 20 },
+};
+
+// Text color (and the `code` role's muted fill) per role. The docs relied on
+// inherited page color; RN text does not cascade, so every role names its color
+// token explicitly: headings/body/code/mono on `foreground`, the helper styles
+// on `muted-foreground`.
+export function roleColor(tokens: ColorTokens, role: Role): TextStyle {
+  switch (role) {
+    case "display":
+    case "h1":
+    case "h2":
+    case "h3":
+    case "h4":
+    case "h5":
+    case "body":
+    case "mono":
+      return { color: tokens.foreground };
+    case "code":
+      return { color: tokens.foreground, backgroundColor: tokens.muted };
+    case "small":
+    case "tiny":
+    case "muted":
+    case "caption":
+      return { color: tokens["muted-foreground"] };
+  }
+}
+
+// Roles whose face is monospace; RN has no font-family utility, so the component
+// supplies the cross-platform monospace alias inline (matches Badge's mono).
+export const MONO_ROLES = new Set<Role>(["code", "mono"]);

package/src/atoms/typography/typography.tsx

@@ -0,0 +1,76 @@
+import { type ReactNode } from "react";
+import { Text, useTheme, type StyleProp, type TextStyle } from "../../style/index.js";
+import { type Role, roleType, roleColor, MONO_ROLES } from "./typography.styles.js";
+
+// Typography: the Canvas type scale as a single styled Text. One boolean role
+// prop per style (display / h1..h5 / body / small / tiny / muted / caption /
+// code / mono) selects a token-backed style set; omit all for the plain body
+// look. The foundation's `Text` primitive is the host element, so the public
+// component is named `Typography` (the bare `Text` name belongs to the
+// foundation).
+//
+// Boolean-prop API: one boolean per role on a single axis, first-match
+// precedence (mirrors Button's intentOf / Badge's toneOf). Roles are mutually
+// exclusive; pass at most one. The text content comes from children.
+//
+// Two roles want a monospace face (code, mono). There is no font-family
+// utility, so each requests RN's cross-platform monospace alias via inline
+// style, the same pattern Badge's `mono` modifier uses. The docs set `code` at
+// text-[13px]; the type scale resolves only token sizes, so it falls back to the
+// nearest one (text-sm), as Kbd does for its 11px label.
+
+export interface TypographyProps {
+  children?: ReactNode;
+  // Role (pick one; default is the plain body style). First-match precedence.
+  display?: boolean;
+  h1?: boolean;
+  h2?: boolean;
+  h3?: boolean;
+  h4?: boolean;
+  h5?: boolean;
+  body?: boolean;
+  small?: boolean;
+  tiny?: boolean;
+  muted?: boolean;
+  caption?: boolean;
+  code?: boolean;
+  mono?: boolean;
+  /** Escape hatch for layout/positioning composition (margins, alignment). */
+  style?: StyleProp<TextStyle>;
+}
+
+// Role precedence when more than one is passed: first match wins. Order runs
+// largest-to-smallest, headings before helper styles, so a conflicting pair
+// resolves to the more prominent role.
+function roleOf(p: TypographyProps): Role {
+  if (p.display) return "display";
+  if (p.h1) return "h1";
+  if (p.h2) return "h2";
+  if (p.h3) return "h3";
+  if (p.h4) return "h4";
+  if (p.h5) return "h5";
+  if (p.code) return "code";
+  if (p.mono) return "mono";
+  if (p.caption) return "caption";
+  if (p.muted) return "muted";
+  if (p.small) return "small";
+  if (p.tiny) return "tiny";
+  if (p.body) return "body";
+  return "body";
+}
+
+export function Typography(props: TypographyProps) {
+  const { children, style } = props;
+  const { tokens } = useTheme();
+  const role = roleOf(props);
+
+  // The mono/code roles ask for a monospace face; there is no font-family
+  // utility, so request the cross-platform monospace alias via inline style.
+  const monoStyle = MONO_ROLES.has(role) ? { fontFamily: "monospace" as const } : null;
+
+  return (
+    <Text style={[roleType[role], roleColor(tokens, role), monoStyle, style]}>
+      {children}
+    </Text>
+  );
+}

package/src/index.ts

@@ -1,4 +1,3 @@
-export { cn } from "./cn.js";
 export { token, hsl } from "./tokens.js";
 export {
   getTheme,
@@ -10,4 +9,15 @@ export {
   setDensity,
 } from "./theme.js";
 
-export type { Theme, Surface, Density } from "./theme.js";
+export type { Theme, Density } from "./theme.js";
+
+// The style foundation: design tokens, the theme runtime (ThemeProvider/useTheme),
+// desktop-first responsive helpers, the shadow/alpha helpers, and the raw React
+// Native primitives (View/Text/Pressable/Image/TextInput/ScrollView). This also
+// exports the Surface type (the glass/default theming switch).
+export * from "./style/index.js";
+
+// Components, grouped by atomic-design level (atoms / molecules / organisms).
+export * from "./atoms/index.js";
+export * from "./molecules/index.js";
+export * from "./organisms/index.js";

package/src/molecules/action-panels/action-panels.md

@@ -0,0 +1,133 @@
+# Action Panels
+
+Section card with headline, body text, and a primary action. Used to surface a single decision or call-to-action.
+
+## Usage
+
+```tsx
+<ActionPanel
+  title="Delete this project"
+  description="Once you delete a project, there is no going back. Please be certain."
+  actionLabel="Delete project"
+  destructive
+/>
+```
+
+## Variants
+
+### Variant - side-by-side
+
+```tsx
+<ActionPanel
+  title="Delete this project"
+  description="You have unsaved edits in this form. Leaving now will lose all progress."
+  actionLabel="Discard"
+  destructive
+  inline
+/>
+```
+
+### Variant - toggle
+
+```tsx
+<ActionPanel
+  title="Delete this project"
+  description="Add an extra layer of security to your account by requiring a verification code on login."
+  toggle
+  checked
+/>
+```
+
+## Do & Don't
+
+### Simple
+
+**Do** — Spell out the consequence above the button so the stakes are clear before the click.
+
+```tsx
+<ActionPanel title="Delete this project" description="Once you delete a project, there is no going back. Please be certain." actionLabel="Delete project" destructive style={{ maxWidth: 420 }} />
+```
+
+**Don't** — A destructive action with no consequence copy invites accidental, irreversible clicks.
+
+```tsx
+<ActionPanel title="Delete this project" actionLabel="Delete project" destructive style={{ maxWidth: 420 }} />
+```
+
+### With form inline
+
+**Do** — Keep the input and its submit button on one row so the input + action reads as one step.
+
+```tsx
+<Card padded style={{ maxWidth: 420, gap: 16 }}>
+  <View style={{ gap: 4 }}>
+    <Text style={{ fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Subscribe to updates</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>We'll send you a weekly digest of what changed.</Text>
+  </View>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+    <Input placeholder="you@example.com" style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%" }} />
+    <Button primary>Subscribe</Button>
+  </View>
+</Card>
+```
+
+**Don't** — Stacking the field above its button breaks the single-decision rhythm and adds a row of dead space.
+
+```tsx
+<Card padded style={{ maxWidth: 420, gap: 16 }}>
+  <View style={{ gap: 4 }}>
+    <Text style={{ fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Subscribe to updates</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>We'll send you a weekly digest of what changed.</Text>
+  </View>
+  <Input placeholder="you@example.com" />
+  <View style={{ alignItems: "flex-start" }}>
+    <Button primary>Subscribe</Button>
+  </View>
+</Card>
+```
+
+### Side-by-side
+
+**Do** — Style only the irreversible action as destructive; keep the cancel/escape as a quiet outline button.
+
+```tsx
+<Card padded style={{ maxWidth: 460, flexDirection: "row", alignItems: "flex-start", gap: 24 }}>
+  <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", gap: 4 }}>
+    <Text style={{ fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Discard unsaved changes?</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>You have unsaved edits in this form. Leaving now will lose all progress.</Text>
+  </View>
+  <View style={{ flexShrink: 0, flexDirection: "row", gap: 8 }}>
+    <Button outline small>Cancel</Button>
+    <Button destructive small>Discard</Button>
+  </View>
+</Card>
+```
+
+**Don't** — Two destructive-styled buttons make the safe escape (Cancel) look as dangerous as the discard.
+
+```tsx
+<Card padded style={{ maxWidth: 460, flexDirection: "row", alignItems: "flex-start", gap: 24 }}>
+  <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", gap: 4 }}>
+    <Text style={{ fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Discard unsaved changes?</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>You have unsaved edits in this form. Leaving now will lose all progress.</Text>
+  </View>
+  <View style={{ flexShrink: 0, flexDirection: "row", gap: 8 }}>
+    <Button destructive small>Discard</Button>
+    <Button destructive small>Cancel</Button>
+  </View>
+</Card>
+```
+
+### With toggle
+
+**Do** — Pair the switch with a one-line explanation of what turning it on or off does.
+
+```tsx
+<ActionPanel title="Two-factor authentication" description="Add an extra layer of security to your account by requiring a verification code on login." toggle checked style={{ maxWidth: 460 }} />
+```
+
+**Don't** — A bare switch with no description leaves the user guessing what flipping it actually changes.
+
+```tsx
+<ActionPanel title="Two-factor authentication" toggle checked style={{ maxWidth: 460 }} />
+```

package/src/molecules/action-panels/action-panels.styles.ts

@@ -0,0 +1,39 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, palette } from "../../style/index.js";
+
+// Co-located ActionPanel styles. Layout-only fragments are static objects; the
+// title color is a function of the active tokens (neutral) or the dark scheme
+// (the destructive danger-zone red, which rides the Tailwind palette so it stays
+// fixed per scheme rather than following the semantic tokens).
+
+export type Tone = "destructive" | "neutral";
+export type Layout = "inline" | "stacked";
+
+// The card surface caps its width; passed to the Card child via its `style` prop.
+export const cardWidth: ViewStyle = { maxWidth: 560 };
+
+// The copy block: title stacked above its consequence line. In the inline layout
+// it grows to push the action to the right (flex-1); stacked, it stays natural.
+export const copyBlock: ViewStyle = { gap: 4 };
+export const copyGrow: ViewStyle = { flexGrow: 1, flexShrink: 1, flexBasis: "0%" };
+
+// The action wrapper: pinned (shrink-0) in the inline/toggle layouts, or
+// left-aligned (items-start) on its own line in the stacked layout.
+export const actionPinned: ViewStyle = { flexShrink: 0 };
+export const actionStacked: ViewStyle = { alignItems: "flex-start" };
+
+// The two body layouts: a side-by-side row (inline/toggle) or a vertical stack.
+export const inlineBody: ViewStyle = { flexDirection: "row", alignItems: "flex-start", gap: 24 };
+export const stackedBody: ViewStyle = { gap: 16 };
+
+// Title and description share Canvas's settings-row type scale (text-sm).
+export function titleText(tokens: ColorTokens, dark: boolean, tone: Tone): TextStyle {
+  // Danger-zone red rides the palette (fixed per scheme); neutral follows the
+  // semantic card foreground so it tracks light/dark/glass.
+  const color = tone === "destructive" ? (dark ? palette["red-400"] : palette["red-700"]) : tokens["card-foreground"];
+  return { fontSize: 14, lineHeight: 20, fontWeight: "600", color };
+}
+
+export function descriptionText(tokens: ColorTokens): TextStyle {
+  return { fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] };
+}