@olympusoss/canvas 4.0.0 → 5.0.0

package/src/atoms/textarea/textarea.styles.ts

@@ -0,0 +1,116 @@
+import { type TextStyle } from "react-native";
+import { type ColorTokens, alpha } from "../../style/index.js";
+
+// Co-located Textarea skins, one per platform. The field is a multiline
+// TextInput, so every fragment is a TextStyle. The BRAND survives on every
+// platform (the focus/active cue is always the indigo `ring`/`primary` token,
+// the error cue the `destructive` token, never a platform default); only the
+// native SHAPE, fill, border/underline, and focus feedback change per OS:
+//   iOS (HIG, iOS 27 / Liquid Glass): the PLAIN multiline text view, a fully
+//     transparent field with NO fill and NO box, carrying only a subtle bottom
+//     hairline rule (the `input` token at rest), so it reads like the iOS 27
+//     plain text field rather than a filled gray capsule. The hairline brightens
+//     to the brand `primary` on focus and `destructive` on error; the brand
+//     cursor/selection is the indigo `primary` (set on the shell, never a system
+//     blue).
+//   Android (Material 3 filled): a subtle fill with a flat bottom active
+//     indicator (underline). Top corners ~4, square bottom. The indicator is a
+//     1px resting line that thickens to 2px indigo on focus (destructive on
+//     error).
+//   Web: the established Canvas look (lifted verbatim) — full-width, 6 radius,
+//     1px border, on the background fill; border is error > focus(ring) > input.
+
+export type Size = "small" | "base" | "large";
+
+// State the shell resolves and hands to the skin's field builder.
+export interface TextareaFieldState {
+  /** Error/validation state (error or invalid prop). */
+  error: boolean;
+  /** The field currently holds keyboard focus. */
+  focused: boolean;
+}
+
+// The only thing a platform skin owns: the field surface for a given state.
+// `sizeText` and `minHeight` are shared (the brand type scale and the rows math
+// are identical across platforms), so the shell composes them around the skin.
+export interface TextareaSkin {
+  field: (tokens: ColorTokens, state: TextareaFieldState) => TextStyle;
+}
+
+// --- shared, platform-neutral fragments -------------------------------------
+
+// Text scale per size; mirrors the height the larger control reads as. Default
+// is the base text-sm field (no size prop). Shared across platforms.
+export function sizeText(size: Size): TextStyle {
+  if (size === "large") return { fontSize: 16, lineHeight: 24 }; // text-base
+  if (size === "small") return { fontSize: 12, lineHeight: 16 }; // text-xs
+  return { fontSize: 14, lineHeight: 20 }; // text-sm
+}
+
+// Derived min height from the row count: each row ~22px plus the vertical
+// padding. Falls back to the 80px floor when no rows are given. The field still
+// grows with content past this floor. Shared across platforms.
+export function minHeight(rows?: number): TextStyle {
+  return { minHeight: rows == null ? 80 : rows * 22 + 16 };
+}
+
+// ---------- Web: the established Canvas look (lifted verbatim) ----------
+// Full width, bordered, padded, on the background fill, with the foreground
+// text color. Border resolves error > focus(ring) > default input.
+export const webSkin: TextareaSkin = {
+  field: (t, st) => ({
+    width: "100%",
+    borderRadius: 6,
+    borderWidth: 1,
+    borderColor: st.error ? t.destructive : st.focused ? t.ring : t.input,
+    backgroundColor: t.background,
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    color: t.foreground,
+  }),
+};
+
+// ---------- iOS (HIG, iOS 27 / Liquid Glass): plain transparent field, bottom hairline ----------
+// The iOS 27 plain multiline text view: no fill, no box, a transparent field
+// with a single subtle bottom hairline rule. The rule is the `input` token at
+// rest (1pt), brightening to the brand `primary` on focus and `destructive` on
+// error, mirroring the new plain single-line input. Horizontal padding drops to
+// 0 so the text and the rule align to the field's edges like the reference.
+export const iosSkin: TextareaSkin = {
+  field: (t, st) => ({
+    width: "100%",
+    backgroundColor: "transparent",
+    // The only chrome: a bottom hairline that carries focus/error.
+    borderBottomWidth: 1,
+    borderBottomColor: st.error ? t.destructive : st.focused ? t.primary : t.input,
+    paddingHorizontal: 0,
+    paddingTop: 8,
+    paddingBottom: 8,
+    color: t.foreground,
+  }),
+};
+
+// ---------- Android (Material 3 filled): subtle fill + active indicator ------
+// A subtle fill (~8% of the muted-foreground hue over the surface) with rounded
+// top corners (~4) and a square bottom, carrying a bottom active indicator
+// (underline). The indicator is a 1px resting line (the input token) that
+// thickens to 2px indigo `primary` on focus, or destructive on error.
+export const androidSkin: TextareaSkin = {
+  field: (t, st) => ({
+    width: "100%",
+    borderTopLeftRadius: 4,
+    borderTopRightRadius: 4,
+    borderBottomLeftRadius: 0,
+    borderBottomRightRadius: 0,
+    backgroundColor: alpha(t["muted-foreground"], 0.08),
+    // The active indicator: only the bottom edge is drawn.
+    borderBottomWidth: st.focused || st.error ? 2 : 1,
+    // Rest baseline must read clearly (on-surface-variant ~ muted-foreground) so the
+    // M3 filled field is distinct from the iOS lineless capsule.
+    borderBottomColor: st.error ? t.destructive : st.focused ? t.primary : t["muted-foreground"],
+    paddingHorizontal: 12,
+    paddingTop: 10,
+    paddingBottom: 8,
+    color: t.foreground,
+  }),
+};

package/src/atoms/textarea/textarea.tsx

@@ -0,0 +1,6 @@
+import { createTextarea } from "./textarea.shared.js";
+import { webSkin } from "./textarea.styles.js";
+
+// Web Textarea (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Textarea = createTextarea(webSkin);
+export type { TextareaProps } from "./textarea.shared.js";

package/src/atoms/tooltip/tooltip.android.tsx

@@ -0,0 +1,6 @@
+import { createTooltip } from "./tooltip.shared.js";
+import { androidSkin } from "./tooltip.styles.js";
+
+// Material 3 (plain tooltip) Tooltip. Metro resolves this file on Android; the docs import it for preview.
+export const Tooltip = createTooltip(androidSkin);
+export type { TooltipProps } from "./tooltip.shared.js";

package/src/atoms/tooltip/tooltip.ios.tsx

@@ -0,0 +1,7 @@
+import { createTooltip } from "./tooltip.shared.js";
+import { iosSkin } from "./tooltip.styles.js";
+
+// iOS Tooltip (no native tooltip; a small rounded inverse label). Metro resolves
+// this file on iOS; the docs import it for preview.
+export const Tooltip = createTooltip(iosSkin);
+export type { TooltipProps } from "./tooltip.shared.js";

package/src/atoms/tooltip/tooltip.md

@@ -0,0 +1,122 @@
+# Tooltips
+
+Small floating helper text on hover or focus.
+
+## Usage
+
+```tsx
+<Tooltip label="Open settings" iconTrigger trigger="Hover me" open top />
+```
+
+## Variants
+
+### Side - right
+
+```tsx
+<Tooltip label="Open settings" iconTrigger trigger="Hover me" open right />
+```
+
+### Side - bottom
+
+```tsx
+<Tooltip label="Open settings" iconTrigger trigger="Hover me" open bottom />
+```
+
+### Side - left
+
+```tsx
+<Tooltip label="Open settings" iconTrigger trigger="Hover me" open left />
+```
+
+### Trigger - button
+
+```tsx
+<Tooltip label="Open settings" trigger="Hover me" open top />
+```
+
+### Trigger - text
+
+```tsx
+<Tooltip label="Open settings" trigger="hover this text" open top />
+```
+
+### Reveal - on hover
+
+```tsx
+<Tooltip label="Open settings" iconTrigger trigger="Hover me" top />
+```
+
+## Do & Don't
+
+**Do** — Keep tooltips short and supplementary; put essential steps in visible copy.
+
+```tsx
+<Tooltip iconTrigger bottom open label="Rotate key" />
+```
+
+**Don't** — Long, essential instructions hidden in a tooltip are missed on touch and by screen readers.
+
+```tsx
+<Tooltip iconTrigger bottom open label="To rotate this key you must first revoke the old one in Settings, then confirm via email within 24 hours." />
+```
+
+### top
+
+**Do** — Leave headroom above (or flip to bottom) so a top-placed tooltip stays fully on screen.
+
+```tsx
+<Tooltip trigger="Save" top open label="Saves your changes" />
+```
+
+**Don't** — A top tooltip on a trigger near the top edge clips above the viewport and goes unread.
+
+```tsx
+<Tooltip trigger="Save" top open label="Saves your changes" />
+```
+
+### right
+
+**Do** — Keep room to the right, or flip the tooltip to the left when the trigger hugs the edge.
+
+```tsx
+<Tooltip iconTrigger right open label="More info" />
+```
+
+**Don't** — A right tooltip on a control flush against the right edge is cut off by the container.
+
+```tsx
+<View style={{ alignItems: "flex-end" }}>
+  <Tooltip iconTrigger right open label="More info" />
+</View>
+```
+
+### bottom
+
+**Do** — Give a bottom tooltip clearance so it never overlaps the interactive content below.
+
+```tsx
+<Tooltip trigger="Filters" bottom open label="Refine results" />
+```
+
+**Don't** — A bottom tooltip sits right on top of the next row, masking the control beneath it.
+
+```tsx
+<View style={{ alignItems: "flex-start", gap: 0 }}>
+  <Tooltip trigger="Filters" bottom open label="Refine results" />
+  <Button outline small style={{ marginTop: -12 }}>Clear all</Button>
+</View>
+```
+
+### left
+
+**Do** — Reserve space on the left, or flip to the right, so a left-placed tooltip is never cut off.
+
+```tsx
+<Tooltip iconTrigger left open label="Need help?" />
+```
+
+**Don't** — A left tooltip on a trigger at the left edge is clipped by the container's left boundary.
+
+```tsx
+<Tooltip iconTrigger left open label="Need help?" />
+```

package/src/atoms/tooltip/tooltip.shared.tsx

@@ -0,0 +1,113 @@
+import { useState } from "react";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Button } from "../button/button.js";
+import { Icon } from "../icon/icon.js";
+import {
+  wrapper,
+  bubbleGap,
+  iconTrigger,
+  type Placement,
+  type TooltipSkin,
+} from "./tooltip.styles.js";
+
+// Shared Tooltip shell. The structure (the trigger plus the open bubble placed
+// next to it via flex order), the public boolean-prop API, the placement
+// precedence, the controlled/uncontrolled open state, the toggle handler, and
+// accessibility all live here once. A platform file supplies only its skin (the
+// bubble surface shape/fill and the label type) and calls createTooltip.
+//
+// Tooltip: a small dark bubble of helper text shown beside a trigger on hover
+// or focus. This RN port renders the open state inline (no portal/Modal): a
+// trigger button with the bubble positioned next to it via flex order, so the
+// docs playground can show it without an overlay layer.
+//
+// Placement is a boolean axis (top default, bottom, left, right); first match
+// wins. top/bottom stack the bubble above/below the trigger in a column;
+// left/right place it beside the trigger in a row.
+export interface TooltipProps {
+  // The tip text shown in the bubble.
+  label?: string;
+  // The element the tip describes; rendered as an <Button outline small>.
+  trigger?: string;
+  // Render the trigger as a ghost icon button (a settings glyph) instead of the
+  // text Button. When set, `trigger` (the label string) is ignored.
+  iconTrigger?: boolean;
+  // Controlled visibility. Omit for uncontrolled (tap the trigger to toggle).
+  open?: boolean;
+  // Fired when the bubble is shown/hidden.
+  onOpenChange?: (open: boolean) => void;
+  // Placement (pick one; default is top).
+  top?: boolean;
+  bottom?: boolean;
+  left?: boolean;
+  right?: boolean;
+  /** Escape hatch for layout/positioning composition (margins, alignment). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Placement precedence when more than one is passed: first match wins.
+function placementOf(p: TooltipProps): Placement {
+  if (p.top) return "top";
+  if (p.bottom) return "bottom";
+  if (p.left) return "left";
+  if (p.right) return "right";
+  return "top";
+}
+
+// Whether the bubble renders before the trigger in source order. top and left
+// place the bubble first; bottom and right place it after.
+const BUBBLE_FIRST: Record<Placement, boolean> = {
+  top: true,
+  bottom: false,
+  left: true,
+  right: false,
+};
+
+/** Build a Tooltip component from a platform skin. */
+export function createTooltip(skin: TooltipSkin) {
+  return function Tooltip(props: TooltipProps) {
+    const { label, trigger, iconTrigger: isIconTrigger, onOpenChange, style } = props;
+    const placement = placementOf(props);
+    const { tokens } = useTheme();
+    // Uncontrolled by default: tapping the trigger toggles the bubble (a touch
+    // analogue of hover); a controlled `open` prop overrides this.
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = props.open ?? internalOpen;
+    const setOpen = (next: boolean) => {
+      if (props.open === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+
+    const tip = open ? (
+      <View style={[skin.bubble(tokens), bubbleGap[placement]]}>
+        <Text style={skin.label(tokens)}>{label}</Text>
+      </View>
+    ) : null;
+
+    // Icon trigger: a ghost icon button (40px square) holding the settings glyph,
+    // matching a ghost icon Button. The glyph renders directly inside the
+    // Pressable (not via Button's <Text> children, which can't host an SVG).
+    const triggerEl = isIconTrigger ? (
+      <Pressable
+        style={({ pressed }) => [iconTrigger, pressed ? { opacity: 0.9 } : null]}
+        onPress={() => setOpen(!open)}
+        accessibilityRole="button"
+        accessibilityLabel={label}
+      >
+        <Icon settings size={16} />
+      </Pressable>
+    ) : (
+      <Button outline small onPress={() => setOpen(!open)}>
+        {trigger}
+      </Button>
+    );
+
+    return (
+      <View style={[wrapper[placement], style]}>
+        {BUBBLE_FIRST[placement] ? tip : null}
+        {triggerEl}
+        {BUBBLE_FIRST[placement] ? null : tip}
+      </View>
+    );
+  };
+}

package/src/atoms/tooltip/tooltip.styles.ts

@@ -0,0 +1,113 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow } from "../../style/index.js";
+
+// Co-located Tooltip skins, one per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark and the glass surface). A
+// tooltip carries no brand fill of its own; the convention on every platform is
+// an INVERSE label (a dark bubble in a light theme, painted on the `foreground`
+// token with `background` text) so the tip reads against the page. Only the
+// native SHAPE, radius, type scale, padding, and elevation change per OS:
+//   iOS (no native tooltip): a small rounded label, radius ~6, an inverse fill
+//     (`foreground` bg with `background` text), caption ~12pt, compact padding,
+//     a soft lift. There is no system tooltip, so this is the platform-
+//     appropriate label convention, not an invented control.
+//   Android (Material 3 plain tooltip): a small rounded rect (radius 4), an
+//     inverse-surface fill (dark in a light theme: `foreground` bg, `background`
+//     text), body-small ~12sp, padding 8x4, flat (no elevation per M3 plain).
+//   Web: the established Canvas look (the current tooltip, lifted verbatim) — a
+//     6-radius dark pill on `foreground`, padding 8x4, `background` text at 12/16
+//     medium, with a soft `md` shadow.
+
+export type Placement = "top" | "bottom" | "left" | "right";
+
+// The contract a platform skin fulfills. Layout (wrapper direction per placement,
+// the gap between bubble and trigger, the bubble-first ordering) is shared and
+// lives in the shell; the skin supplies only the bubble surface and the label
+// type, both functions of the active tokens so the inverse fill follows
+// light/dark automatically.
+export interface TooltipSkin {
+  /** The bubble surface: shape, radius, inverse fill, padding, elevation. */
+  bubble: (t: ColorTokens) => ViewStyle;
+  /** The tip label: size/weight, painted in the inverse text token. */
+  label: (t: ColorTokens) => TextStyle;
+}
+
+// --- shared layout fragments (identical across platforms) -------------------
+
+// Wrapper layout per placement: a column for top/bottom (bubble stacked above or
+// below the trigger), a row for left/right (bubble beside the trigger). Centered
+// on the cross axis and shrunk to its content (self-start).
+export const wrapper: Record<Placement, ViewStyle> = {
+  top: { flexDirection: "column", alignItems: "center", alignSelf: "flex-start" },
+  bottom: { flexDirection: "column", alignItems: "center", alignSelf: "flex-start" },
+  left: { flexDirection: "row", alignItems: "center", alignSelf: "flex-start" },
+  right: { flexDirection: "row", alignItems: "center", alignSelf: "flex-start" },
+};
+
+// Gap between bubble and trigger (the old `m{b,t,r,l}-1.5` = 6), applied to the
+// bubble on the trigger-facing side: top -> below, bottom -> above, etc.
+export const bubbleGap: Record<Placement, ViewStyle> = {
+  top: { marginBottom: 6 },
+  bottom: { marginTop: 6 },
+  left: { marginRight: 6 },
+  right: { marginLeft: 6 },
+};
+
+// The icon trigger: a 40px square ghost button holding the settings glyph,
+// matching a ghost icon Button. Press feedback is applied by the component's
+// Pressable (opacity dim on iOS/web, ripple on Android).
+export const iconTrigger: ViewStyle = {
+  height: 40,
+  width: 40,
+  alignItems: "center",
+  justifyContent: "center",
+  borderRadius: 6,
+};
+
+// ---------- Web: the established Canvas look (lifted verbatim) ----------
+// A small dark pill on the `foreground` token (so it inverts against the page),
+// 6 radius, 8x4 padding, a soft `md` lift; the label is 12/16 medium painted in
+// `background` so it reads as light text on the dark bubble.
+export const webSkin: TooltipSkin = {
+  bubble: (t) => ({
+    borderRadius: 6,
+    backgroundColor: t.foreground,
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    ...shadow("md"),
+  }),
+  label: (t) => ({ fontSize: 12, lineHeight: 16, fontWeight: "500", color: t.background }),
+};
+
+// ---------- iOS (no native tooltip): a small rounded inverse label ----------
+// iOS ships no tooltip, so this is the platform-appropriate label convention: a
+// small rounded rect (radius 6) over the inverse `foreground` fill with
+// `background` text, a compact caption (12/16), tight 8x4 padding, and a soft
+// `md` lift so it floats off the page.
+export const iosSkin: TooltipSkin = {
+  bubble: (t) => ({
+    borderRadius: 6,
+    backgroundColor: t.foreground,
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    ...shadow("md"),
+  }),
+  label: (t) => ({ fontSize: 12, lineHeight: 16, fontWeight: "500", color: t.background }),
+};
+
+// ---------- Android (Material 3 plain tooltip): inverse-surface rounded rect ----------
+// M3 plain tooltip: a small rounded rect with a tighter 4dp corner radius, an
+// inverse-surface fill (dark in a light theme: `foreground` bg, `background`
+// text), body-small ~12sp, padding 8x4, and FLAT (no elevation) per the M3 plain
+// tooltip spec. A 24dp minimum height keeps single-line tips at the spec height.
+export const androidSkin: TooltipSkin = {
+  bubble: (t) => ({
+    borderRadius: 4,
+    backgroundColor: t.foreground,
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    minHeight: 24,
+    justifyContent: "center",
+  }),
+  label: (t) => ({ fontSize: 12, lineHeight: 16, fontWeight: "400", color: t.background }),
+};

package/src/atoms/tooltip/tooltip.tsx

@@ -0,0 +1,6 @@
+import { createTooltip } from "./tooltip.shared.js";
+import { webSkin } from "./tooltip.styles.js";
+
+// Web Tooltip (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Tooltip = createTooltip(webSkin);
+export type { TooltipProps } from "./tooltip.shared.js";