@olympusoss/canvas 4.0.0 → 5.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @olympusoss/canvas
+
+Universal React Native UI kit. Canvas runs natively on iOS and Android, and on
+the web through React Native Web, from a single component API. Components are
+styled with semantic boolean props and authored desktop-first, so they adapt
+cleanly from large desktop down to phone.
+
+## Install
+
+```bash
+npm install @olympusoss/canvas
+```
+
+Canvas relies on three peer dependencies that you install alongside it:
+
+```bash
+npm install react react-native react-native-svg
+```
+
+For web rendering, add `react-native-web` to your app and alias `react-native`
+to `react-native-web` in your bundler, the same way any React Native Web project
+does.
+
+## Quick Start
+
+Wrap your app in the `ThemeProvider`, then compose components imported
+from `@olympusoss/canvas`. The provider supplies the active color scheme and
+token map; omit `scheme` to follow the OS appearance, or force it with
+`scheme="light"` / `scheme="dark"`.
+
+```jsx
+import { ThemeProvider, Card, CardHeader, CardTitle, CardContent, Button } from "@olympusoss/canvas";
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <Card padded>
+        <CardHeader>
+          <CardTitle>Welcome to Canvas</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <Button primary large onPress={() => console.log("saved")}>
+            Save
+          </Button>
+        </CardContent>
+      </Card>
+    </ThemeProvider>
+  );
+}
+```
+
+The same component tree renders natively on iOS and Android and, through React
+Native Web, in the browser. There is no separate web component set to learn.
+
+## Semantic boolean props
+
+Styling is done with flat boolean props. Each style choice is its own prop,
+named for the meaning it carries, and passing the prop turns it on. The prop
+name is the value, so the call site reads like natural language ("a primary,
+large button").
+
+```jsx
+<Button primary large>Save</Button>
+<Button destructive>Delete</Button>
+<Button ghost small>Cancel</Button>
+<Card glass>...</Card>
+```
+
+Props are grouped into orthogonal axes (intent, size, surface, density, and
+stacking state/layout flags). Props on different axes combine freely; props
+within one axis are mutually exclusive, so you pass at most one and the
+component resolves any conflict by a fixed precedence.
+
+```jsx
+// Four props from four axes, all applied together.
+<Button primary large loading block>Save</Button>
+```
+
+String-valued enum props such as `variant="primary"`, `size="lg"`, or
+`tone="destructive"` are not part of the API and are not accepted. The boolean
+form is the only styling surface.
+
+## Theming
+
+`ThemeProvider` reads the OS color scheme by default and exposes the resolved
+tokens to every Canvas component through `useTheme`. Force a scheme when you
+need to:
+
+```jsx
+<ThemeProvider scheme="dark">
+  <App />
+</ThemeProvider>
+```
+
+## What's Included
+
+- A full component kit: buttons, inputs, cards, tables, tabs, dialogs,
+  dropdowns, calendars, charts, sidebars, and more, all exported from
+  `@olympusoss/canvas`.
+- The style foundation: design tokens, the theme runtime (`ThemeProvider`,
+  `useTheme`), the `useResponsive` / `shadow` / `alpha` helpers, and the raw React
+  Native `View` / `Text` / `Pressable` / `Image` / `TextInput` / `ScrollView` primitives.
+- Light and dark color schemes resolved through theme tokens.
+- Desktop-first responsiveness built into every component.
+
+## License
+
+MIT

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@olympusoss/canvas",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "type": "module",
-  "description": "CSS-first design system for the Olympus platform",
+  "description": "Universal React Native UI kit styled with Tailwind",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -29,15 +29,26 @@
     "screenshots": "bun scripts/capture-screenshots.ts",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "changeset publish"
+    "release": "changeset publish",
+    "docs:dev": "cd docs && npx vite",
+    "docs:build": "cd docs && npx vite build"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.74",
+    "react-native-svg": ">=13"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@playwright/test": "^1.60.0",
+    "@types/react": "^19.2.16",
+    "react": "^19.2.7",
+    "react-native": "^0.85.3",
+    "react-native-svg": "^15",
     "typescript": "^5.8.3"
   }
 }

package/src/atoms/avatar/avatar.md

@@ -0,0 +1,185 @@
+# Avatars
+
+A photo when the account has one, falling back to two initials on a brand gradient (seeded admin accounts). Sizes scale font proportionally (40% of diameter).
+
+## Usage
+
+```tsx
+<Avatar name="AO" />
+```
+
+## Variants
+
+### Variant - stacked
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center" }}>
+  <Avatar ring src="/rachel-chen.jpg" name="RC" />
+  <Avatar ring src="/liang-bao.jpg" name="LB" style={{ marginLeft: -12 }} />
+  <Avatar ring src="/marcus-allen.jpg" name="LB" style={{ marginLeft: -12 }} />
+  <Avatar ring src="/kira-tanaka.jpg" name="KT" style={{ marginLeft: -12 }} />
+</View>
+```
+
+### Variant - topbar
+
+```tsx
+<Dropdown items={[
+    { label: "Your profile", icon: "👤" },
+    { label: "Settings", icon: "⚙" },
+    { label: "Sign out", icon: "↩", separatorBefore: true }
+  ]}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 9999, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, paddingVertical: 4, paddingLeft: 4, paddingRight: 10 }}>
+    <Avatar small src="/marcus-allen.jpg" name="MA" />
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>admin@example.com</Text>
+    <Icon chevronDown muted size={12} />
+  </View>
+</Dropdown>
+```
+
+### Variant - identity
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 16 }}>
+  <Avatar src="/rachel-chen.jpg" name="RC" />
+  <View>
+    <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>Rachel Chen</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>rachel.chen@example.com</Text>
+  </View>
+</View>
+```
+
+### Variant - menu
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 12, borderBottomWidth: 1, borderColor: tokens.border, paddingBottom: 12 }}>
+  <Avatar src="/ada-lovelace.jpg" name="AL" />
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Ada Lovelace</Text>
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>admin@example.com</Text>
+  </View>
+</View>
+```
+
+### Ring outline
+
+```tsx
+<Avatar ring name="AO" />
+```
+
+## Do & Don't
+
+### Single
+
+**Do** — One or two initials, sized about 40% of the diameter.
+
+```tsx
+<Avatar name="AO" />
+```
+
+**Don't** — Cramming in a full set of initials shrinks the type and crowds the circle.
+
+```tsx
+<View style={{ flexShrink: 0, alignItems: "center", justifyContent: "center", overflow: "hidden", backgroundColor: tokens.muted, width: 40, height: 40, borderRadius: 9999 }}>
+  <Text style={{ fontWeight: "500", color: tokens["muted-foreground"], fontSize: 12 }}>ABCD</Text>
+</View>
+```
+
+### Stacked
+
+**Do** — Cap the stack and summarize the rest with a +N count.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center" }}>
+  <Avatar small ring name="AO" />
+  <Avatar small ring name="RC" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="LB" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="KT" style={{ marginLeft: -10 }} />
+  <Text style={{ marginLeft: 6, fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>+12</Text>
+</View>
+```
+
+**Don't** — An unbounded stack runs off the row and stops being scannable.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center" }}>
+  <Avatar small ring name="AO" />
+  <Avatar small ring name="RC" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="LB" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="KT" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="JD" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="MA" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="AL" style={{ marginLeft: -10 }} />
+  <Avatar small ring name="SK" style={{ marginLeft: -10 }} />
+</View>
+```
+
+### Topbar account menu
+
+**Do** — Pair it with the account name and a chevron so it reads as a trigger.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 9999, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, paddingVertical: 4, paddingLeft: 4, paddingRight: 10 }}>
+  <Avatar small src="/marcus-allen.jpg" name="MA" />
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>admin@example.com</Text>
+  <Icon chevronDown muted size={12} />
+</View>
+```
+
+**Don't** — A lone avatar gives no hint that it opens the account menu.
+
+```tsx
+<Avatar small src="/marcus-allen.jpg" name="MA" />
+```
+
+### Identity
+
+**Do** — Name primary; email muted and secondary.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 16 }}>
+  <Avatar src="/rachel-chen.jpg" name="RC" />
+  <View>
+    <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>Rachel Chen</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>rachel.chen@example.com</Text>
+  </View>
+</View>
+```
+
+**Don't** — Equal weight on the name and email flattens the hierarchy.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 16 }}>
+  <Avatar src="/rachel-chen.jpg" name="RC" />
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Rachel Chen</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>rachel.chen@example.com</Text>
+  </View>
+</View>
+```
+
+### Menu header
+
+**Do** — Keep one consistent circular avatar shape across contexts.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+  <Avatar src="/ada-lovelace.jpg" name="AL" />
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Ada Lovelace</Text>
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>admin@example.com</Text>
+  </View>
+</View>
+```
+
+**Don't** — Squaring the avatar here clashes with the circular avatars everywhere else.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+  <Avatar rounded src="/ada-lovelace.jpg" name="AL" />
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Ada Lovelace</Text>
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>admin@example.com</Text>
+  </View>
+</View>
+```

package/src/atoms/avatar/avatar.styles.ts

@@ -0,0 +1,48 @@
+import { type ViewStyle, type TextStyle, type ImageStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Avatar styles. Diameter per size, corner radius per shape, and the
+// muted fallback surface, all built from the active tokens.
+
+export type Size = "small" | "default" | "large";
+export type Shape = "circle" | "rounded";
+
+// Diameter per size: small is the inline topbar/stack size, default the 40px row
+// avatar, large the identity-header size.
+const BOX: Record<Size, number> = { small: 28, default: 40, large: 48 };
+
+// Circle by default; the rounded square uses the card/menu radius.
+const RADIUS: Record<Shape, number> = { circle: 9999, rounded: 6 };
+
+// Initials type per size, ~40% of the diameter.
+const LABEL_SIZE: Record<Size, { fontSize: number; lineHeight: number }> = {
+  small: { fontSize: 12, lineHeight: 16 },
+  default: { fontSize: 16, lineHeight: 24 },
+  large: { fontSize: 18, lineHeight: 28 },
+};
+
+export function container(tokens: ColorTokens, size: Size, shape: Shape, ring: boolean): ViewStyle {
+  return {
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+    backgroundColor: tokens.muted,
+    width: BOX[size],
+    height: BOX[size],
+    borderRadius: RADIUS[shape],
+    // No ring-* equivalent in RN; a 2px background-colored border is the stand-in
+    // for ring-2 ring-background, the separator outline used when avatars overlap.
+    ...(ring ? { borderWidth: 2, borderColor: tokens.background } : null),
+  };
+}
+
+// The photo fills the container exactly; the parent's overflow-hidden clips it
+// to the circle (RN clips children to a parent's borderRadius).
+export function image(shape: Shape): ImageStyle {
+  return { width: "100%", height: "100%", borderRadius: RADIUS[shape] };
+}
+
+export function label(tokens: ColorTokens, size: Size): TextStyle {
+  return { fontWeight: "500", color: tokens["muted-foreground"], ...LABEL_SIZE[size] };
+}

package/src/atoms/avatar/avatar.tsx

@@ -0,0 +1,99 @@
+import { type ReactNode } from "react";
+import { View, Image, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import * as s from "./avatar.styles.js";
+import { type Size, type Shape } from "./avatar.styles.js";
+
+// The avatar shows an account's photo when it has one, falling back to one or
+// two initials on a muted surface. It is a circle by default (the consistent
+// shape across topbars, identity rows, and menus), optionally a rounded square.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf). Size picks the
+// diameter and proportional type (~40% of the diameter); shape switches the
+// corner radius; `ring` draws the separator outline used when avatars overlap
+// in a stack.
+
+export interface AvatarProps {
+  /** Photo URL. When set, the image fills the circle and the fallback is hidden. */
+  src?: string;
+  /** Alias for `src`, for callers that think in terms of a native image uri. */
+  uri?: string;
+  /** Initials fallback shown when there is no photo (e.g. "AO"). */
+  name?: string;
+  /** Same as `name`; the rendered initials when no photo is supplied. */
+  children?: ReactNode;
+  // Size (pick one; default is the 40px row avatar).
+  small?: boolean;
+  large?: boolean;
+  // Shape (pick one; default is a circle).
+  circle?: boolean;
+  rounded?: boolean;
+  /** Separator outline, for avatars that overlap in a stack. */
+  ring?: boolean;
+  /** When set, the avatar becomes pressable (e.g. a topbar account trigger). */
+  onPress?: () => void;
+  /** Escape hatch for layout/positioning composition (e.g. negative margin to overlap in a stack). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Size precedence when more than one is passed: first match wins.
+function sizeOf(p: AvatarProps): Size {
+  if (p.small) return "small";
+  if (p.large) return "large";
+  return "default";
+}
+
+// Shape precedence when more than one is passed: first match wins.
+function shapeOf(p: AvatarProps): Shape {
+  if (p.circle) return "circle";
+  if (p.rounded) return "rounded";
+  return "circle";
+}
+
+// Reduce a name or label to one or two initials ("Rachel Chen" -> "RC", "AO" ->
+// "AO"), so callers can pass either a full name or ready-made initials.
+function initialsFrom(text: string): string {
+  const parts = text.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 Avatar(props: AvatarProps) {
+  const { src, uri, name, children, ring, onPress, style } = props;
+  const { tokens } = useTheme();
+  const size = sizeOf(props);
+  const shape = shapeOf(props);
+  const photo = src ?? uri;
+
+  const container: StyleProp<ViewStyle> = [s.container(tokens, size, shape, !!ring), style];
+
+  let inner: ReactNode;
+  if (photo) {
+    inner = (
+      <Image
+        style={s.image(shape)}
+        source={{ uri: photo }}
+        accessibilityLabel={name}
+        resizeMode="cover"
+      />
+    );
+  } else {
+    const source = name ?? (typeof children === "string" ? children : "");
+    const initials = source ? initialsFrom(source) : "";
+    inner = initials ? <Text style={s.label(tokens, size)}>{initials}</Text> : null;
+  }
+
+  if (onPress) {
+    return (
+      <Pressable
+        style={({ pressed }) => [container, pressed ? { opacity: 0.9 } : null]}
+        onPress={onPress}
+        accessibilityRole="button"
+      >
+        {inner}
+      </Pressable>
+    );
+  }
+  return <View style={container}>{inner}</View>;
+}