@lotics/ui 1.6.1 → 1.9.0

package/src/popover.tsx

@@ -11,6 +11,7 @@ import { colors } from "./colors";
 import { IconButton } from "./icon_button";
 import { Portal } from "./portal";
 import { Divider } from "./divider";
+import { useOverlayScope } from "./overlay_scope";
 import { PopoverNavContext, type PopoverNavContextValue } from "./popover_nav";
 
 export type PopoverSide = "top" | "right" | "bottom" | "left";
@@ -76,6 +77,8 @@ export function Popover(props: PopoverProps) {
   const isControlled = controlledOpen !== undefined;
   const open = isControlled ? controlledOpen : uncontrolledOpen;
 
+  useOverlayScope(open);
+
   const onOpenChange = useCallback(
     (newOpen: boolean) => {
       if (!isControlled) {

package/src/section_card.tsx

@@ -0,0 +1,68 @@
+import { type ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { Card } from "./card";
+import { Text } from "./text";
+import { Divider } from "./divider";
+import { SPACE } from "./spacing";
+
+interface SectionCardProps {
+  title: string;
+  /**
+   * One-line context under the title. Mercury, Stripe, Linear all show this
+   * — a bare title says "what this is" but the description says "why this
+   * is here and what it answers". Skip only when the title is unambiguous
+   * on its own.
+   */
+  description?: string;
+  /** Body content. Author owns the internal layout. */
+  children: ReactNode;
+  /**
+   * Optional footer separated by a hairline. The right place for trend
+   * captions ("Tăng 12% so với tháng trước"), source notes, or
+   * cross-references. Skip if the body already self-explains.
+   */
+  footer?: ReactNode;
+}
+
+/**
+ * Section-shaped card with semantic title + description + body + optional
+ * footer slots. The shape every well-designed dashboard section takes:
+ * Linear's checklist sections, Stripe's metric cards, Mercury's account
+ * panels. Mirrors the shadcn `Card` + `CardHeader` + `CardContent` +
+ * `CardFooter` composition pattern.
+ *
+ * Uses Card under the hood — picks up the border + soft shadow defaults.
+ * Adds generous 32px internal padding so the description + body + footer
+ * breathe; bare Card's 20px feels cramped once you have structured content.
+ */
+export function SectionCard(props: SectionCardProps) {
+  return (
+    <Card style={styles.card}>
+      <View style={styles.container}>
+        <View style={styles.header}>
+          <Text size="lg" weight="semibold">
+            {props.title}
+          </Text>
+          {props.description && (
+            <Text size="sm" color="muted">
+              {props.description}
+            </Text>
+          )}
+        </View>
+        {props.children}
+        {props.footer && (
+          <>
+            <Divider />
+            {props.footer}
+          </>
+        )}
+      </View>
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: { padding: SPACE.xl }, // 32px — Stripe / Mercury internal padding
+  container: { gap: SPACE.lg },
+  header: { gap: SPACE.xs },
+});

package/src/spacing.ts

@@ -0,0 +1,23 @@
+/**
+ * 8-grid spacing tokens. Every gap, padding, and margin in a dashboard
+ * should come from this scale — multiples of 8 read as "designed",
+ * multiples of 4 read as "developer-tuned-on-the-fly", arbitrary numbers
+ * read as broken.
+ *
+ * Aliases (xs/sm/md/lg/xl/xxl) match the Text size scale so authors can
+ * reason about spacing and typography on the same vocabulary.
+ *
+ * Why not extend further (3xl, 4xl)? Lotics surfaces fit comfortably in
+ * the 4-48px range. A "between-section gap" of 64px+ usually means the
+ * sections should be on separate routes, not the same page.
+ */
+export const SPACE = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+  xxl: 48,
+} as const;
+
+export type SpaceToken = keyof typeof SPACE;

package/src/sparkline.tsx

@@ -0,0 +1,85 @@
+import { useMemo } from "react";
+import { View } from "react-native";
+import { colors } from "./colors";
+
+export interface SparklineProps {
+  /**
+   * Series of values in chronological order. Two or more required to draw
+   * a line; one value or empty renders an empty box of the requested
+   * height (preserves layout while data loads).
+   */
+  data: number[];
+  /** Pixel height of the chart. Default 32. */
+  height?: number;
+  /** Pixel width. Default 100. */
+  width?: number;
+  /** Stroke color. Default `colors.zinc[700]`. */
+  color?: string;
+  /** Whether to fill the area under the line. Default false. */
+  filled?: boolean;
+}
+
+/**
+ * Compact line trend, ~40px tall. Sits next to a metric to answer "is
+ * this good?" — static numbers answer "what" but not "trending up or
+ * down". Used in dashboards (Stripe, Mercury, Linear all ship this
+ * pattern).
+ *
+ * Implementation: native HTML `<svg>` rather than `react-native-svg`.
+ * Custom-code apps are web-only and Vite resolves react-native-svg's
+ * Fabric native paths incorrectly (Metro handles the platform variants
+ * but Vite doesn't). Wrapping in RN's `<View>` preserves the layout
+ * surface; SVG inside renders cleanly on the DOM.
+ */
+export function Sparkline(props: SparklineProps) {
+  const { data, height = 32, width = 100, color = colors.zinc[700], filled = false } = props;
+
+  const { path, fillPath } = useMemo(() => {
+    if (data.length < 2) return { path: null, fillPath: null };
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    // Flat data → horizontal line at vertical center. Avoid /0 division.
+    const range = max - min || 1;
+    // Stroke width budget — inset by 1.5px so the line doesn't clip the
+    // SVG viewport on either side.
+    const inset = 1.5;
+    const w = width - inset * 2;
+    const h = height - inset * 2;
+    const stepX = w / (data.length - 1);
+    let p = "";
+    data.forEach((v, i) => {
+      const x = inset + i * stepX;
+      // Y axis inverted in SVG (higher value = smaller y). Normalize to
+      // 0-1 then map into the inset area.
+      const y = inset + h - ((v - min) / range) * h;
+      p += `${i === 0 ? "M" : "L"} ${x.toFixed(2)} ${y.toFixed(2)} `;
+    });
+    const trimmed = p.trim();
+    return {
+      path: trimmed,
+      fillPath: filled
+        ? `${trimmed} L ${width - inset} ${height - inset} L ${inset} ${height - inset} Z`
+        : null,
+    };
+  }, [data, width, height, filled]);
+
+  if (!path) {
+    return <View style={{ width, height }} />;
+  }
+
+  return (
+    <View style={{ width, height }}>
+      <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`}>
+        {fillPath && <path d={fillPath} fill={color} fillOpacity={0.1} />}
+        <path
+          d={path}
+          stroke={color}
+          strokeWidth={1.5}
+          fill="none"
+          strokeLinejoin="round"
+          strokeLinecap="round"
+        />
+      </svg>
+    </View>
+  );
+}

package/src/stacked_progress_bar.tsx

@@ -0,0 +1,65 @@
+import { View, StyleSheet } from "react-native";
+import { colors } from "./colors";
+
+interface Segment {
+  /** Identifier for the segment — used as a React key. */
+  key: string;
+  /** Numeric weight. Each segment's width is `value / total`. */
+  value: number;
+  /** CSS color. */
+  color: string;
+}
+
+interface StackedProgressBarProps {
+  segments: Segment[];
+  /** Total value across all segments. Pass explicitly so loading + empty
+   * states render consistently (an empty array would otherwise look like
+   * "data loaded with no values"). */
+  total: number;
+  /** Bar pixel height. Default 14 — the dashboard hero-progress size.
+   * Drop to 6-8 for inline status bars in tight rows; bump to 20-24
+   * when the bar IS the section's main visualization. */
+  height?: number;
+  loading?: boolean;
+}
+
+/**
+ * Horizontal segmented bar for funnels / status breakdowns / category
+ * distributions. The Mercury / Linear stage-breakdown pattern — handles
+ * sparse data gracefully because zero-value segments collapse to zero
+ * width, and a single dominant value renders as one long segment rather
+ * than a "broken" bar chart with five empty stages.
+ *
+ * Pair with `<LegendItem />` rows below to name the colored segments.
+ * Without a legend, the colored bar is decorative — viewers can't map
+ * colors back to meaning.
+ */
+export function StackedProgressBar(props: StackedProgressBarProps) {
+  const { segments, total, height = 14, loading } = props;
+  if (loading || total === 0) {
+    return <View style={[styles.bar, { height, backgroundColor: colors.zinc[100] }]} />;
+  }
+  return (
+    <View style={[styles.bar, styles.barFilled, { height }]}>
+      {segments
+        .filter((s) => s.value > 0)
+        .map((seg) => (
+          <View
+            key={seg.key}
+            style={{ flex: seg.value, backgroundColor: seg.color }}
+          />
+        ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  bar: {
+    borderRadius: 999,
+    overflow: "hidden",
+  },
+  barFilled: {
+    backgroundColor: colors.zinc[100],
+    flexDirection: "row",
+  },
+});

package/src/text.css

@@ -1,10 +1,26 @@
+/*
+ * Letter-spacing curve: positive at small sizes (improves legibility for
+ * Vietnamese diacritics + Inter's `1`/`l`/`i` at 12px), neutral at body,
+ * negative at display. The single biggest "designed" tell on web type —
+ * Radix, Linear, Geist all use this curve.
+ *
+ * Inter stylistic alternates: `cv11` (single-storey `a`), `ss01` (alternate
+ * `1`), `ss03` (alternate `g`) — disambiguates similar glyphs without
+ * shifting metrics. No layout impact, premium-character signal.
+ */
+* {
+  font-feature-settings: "cv11", "ss01", "ss03";
+}
+
 [data-text-size="xs"] {
   font-size: 12px;
   line-height: 16px;
+  letter-spacing: 0.01em;
 }
 [data-text-size="sm"] {
   font-size: 14px;
   line-height: 20px;
+  letter-spacing: 0.0025em;
 }
 [data-text-size="md"] {
   font-size: 16px;
@@ -13,14 +29,17 @@
 [data-text-size="lg"] {
   font-size: 18px;
   line-height: 24px;
+  letter-spacing: -0.005em;
 }
 [data-text-size="xl"] {
-  font-size: 28;
+  font-size: 28px;
   line-height: 34px;
+  letter-spacing: -0.015em;
 }
 [data-text-size="xxl"] {
   font-size: 32px;
   line-height: 38px;
+  letter-spacing: -0.02em;
 }
 
 /* Refer to `use_screen_size` for breakpoints */

package/src/theme.tsx

@@ -0,0 +1,61 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * Default platform accent — refined OKLCH blue. Used by chart fills,
+ * focus rings, and any primitive that asks "what's the brand color".
+ * Apps that need a different accent wrap their root in `LoticsThemeProvider`.
+ *
+ * Why OKLCH instead of hex? Perceptual uniformity — `oklch(0.6 0.118 250)`
+ * sits at the same perceptual lightness/saturation as the `oklch(0.6 0.118
+ * 184.704)` (teal) chị's workspace uses, just shifted in hue. Hex shifts
+ * lightness as hue rotates and the eye picks it up as inconsistency.
+ */
+export const DEFAULT_ACCENT = "oklch(0.6 0.118 250)";
+
+interface LoticsTheme {
+  /** Single brand accent. Chart fills, hero CTAs, focus rings. */
+  accent: string;
+}
+
+const LoticsThemeContext = createContext<LoticsTheme>({ accent: DEFAULT_ACCENT });
+
+interface LoticsThemeProviderProps {
+  /** Brand accent. Overrides the platform default. Accepts any CSS color
+   * value (OKLCH recommended, hex / hsl also fine). */
+  accent?: string;
+  children: ReactNode;
+}
+
+/**
+ * App-root provider that supplies brand tokens to @lotics/ui primitives.
+ * Wrap your top-level app element to override the platform defaults:
+ *
+ *     // src/main.tsx
+ *     <LoticsThemeProvider accent="oklch(0.6 0.118 184.704)">
+ *       <App />
+ *     </LoticsThemeProvider>
+ *
+ * Components that consume theme tokens use `useLoticsTheme()`. Each
+ * primitive also accepts a per-instance `color` prop for one-off
+ * customization without needing a different provider.
+ *
+ * Scope is intentionally narrow — accent only. Semantic colors (success,
+ * danger) already work via existing `colors.green[600]` etc. Adding more
+ * theme tokens requires a real product reason.
+ */
+export function LoticsThemeProvider(props: LoticsThemeProviderProps) {
+  const accent = props.accent ?? DEFAULT_ACCENT;
+  return (
+    <LoticsThemeContext.Provider value={{ accent }}>
+      {props.children}
+    </LoticsThemeContext.Provider>
+  );
+}
+
+/**
+ * Read the current theme. Primitives that need the accent color call this
+ * hook; apps don't need it directly (use the provider's prop instead).
+ */
+export function useLoticsTheme(): LoticsTheme {
+  return useContext(LoticsThemeContext);
+}

package/src/trend_chip.tsx

@@ -0,0 +1,65 @@
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+
+export interface TrendChipProps {
+  /**
+   * Percent delta vs comparator. Positive = up, negative = down, 0 = flat.
+   * Convention: signed. `value={12}` → "↑ 12%". `value={-5}` → "↓ 5%".
+   */
+  value: number;
+  /**
+   * Semantic override. By default, up = good (green) and down = bad (red).
+   * For metrics where down is good (e.g. response time, error rate), pass
+   * `goodDirection="down"` to flip the colors without changing the arrow.
+   */
+  goodDirection?: "up" | "down";
+}
+
+/**
+ * Inline ±% chip that sits next to a metric. Answers "is this good?" — the
+ * single most common missing piece on dashboards that show only "what".
+ * Stripe, Mercury, Linear all ship this pattern.
+ *
+ * Color logic: trend direction × goodDirection. Up + good="up" = green.
+ * Up + good="down" = red. Symmetric for down. Flat = neutral.
+ */
+export function TrendChip(props: TrendChipProps) {
+  const { value, goodDirection = "up" } = props;
+
+  const direction = value > 0 ? "up" : value < 0 ? "down" : "flat";
+  const arrow = direction === "up" ? "↑" : direction === "down" ? "↓" : "→";
+
+  const isGood =
+    direction === "flat"
+      ? null
+      : (direction === "up" && goodDirection === "up") ||
+        (direction === "down" && goodDirection === "down");
+
+  const tone = isGood === null ? "neutral" : isGood ? "good" : "bad";
+
+  return (
+    <View style={[styles.chip, styles[`chip_${tone}`]]}>
+      <Text size="xs" weight="medium" style={styles[`text_${tone}`]}>
+        {arrow} {Math.abs(value)}%
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  chip: {
+    paddingHorizontal: 6,
+    paddingVertical: 2,
+    borderRadius: 4,
+    alignSelf: "flex-start",
+  },
+  // Tinted backgrounds (50-shade) keep the chip readable + non-shouty.
+  // Pairs with same-hue 700-shade text → 4.5+ contrast.
+  chip_good: { backgroundColor: colors.green[50] },
+  chip_bad: { backgroundColor: colors.red[50] },
+  chip_neutral: { backgroundColor: colors.zinc[100] },
+  text_good: { color: colors.green[700] },
+  text_bad: { color: colors.red[700] },
+  text_neutral: { color: colors.zinc[600] },
+});

package/src/trend_footer.tsx

@@ -0,0 +1,56 @@
+import { TrendingDown, TrendingUp } from "lucide-react";
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { SPACE } from "./spacing";
+
+interface TrendFooterProps {
+  /** Signed percentage change. Positive = up, negative = down, 0 = no
+   * arrow. Caller is responsible for skipping the component entirely
+   * when there's no comparator (e.g., last-period base = 0). */
+  value: number;
+  /** Suffix after the percentage, e.g. "so với tháng trước". */
+  periodLabel: string;
+  /** Optional detail line below, e.g. "Tháng trước: 50.000.000 đ". */
+  detail?: string;
+  /** Override the up=green convention for metrics where down is good
+   * (response time, error rate). Defaults to `up`. */
+  goodDirection?: "up" | "down";
+}
+
+/**
+ * Footer caption that pairs the shadcn TrendingUp icon with a directional
+ * Vietnamese sentence — the "Tăng X% so với tháng trước" pattern at the
+ * bottom of every chart card on Stripe, Mercury, Linear.
+ *
+ * Goes inside `<SectionCard footer={...} />`. The Card adds the hairline
+ * divider above; this component owns only the icon + text composition.
+ */
+export function TrendFooter(props: TrendFooterProps) {
+  const { value, periodLabel, detail, goodDirection = "up" } = props;
+  const up = value > 0;
+  const flat = value === 0;
+  const isGood = flat ? null : (up && goodDirection === "up") || (!up && goodDirection === "down");
+  const color = isGood === null ? colors.zinc[600] : isGood ? colors.green[700] : colors.red[700];
+  const Icon = up ? TrendingUp : TrendingDown;
+  return (
+    <View style={styles.container}>
+      <View style={styles.row}>
+        <Icon size={16} color={color} />
+        <Text size="sm" weight="medium" style={{ color }}>
+          {up ? "Tăng" : "Giảm"} {Math.abs(value)}% {periodLabel}
+        </Text>
+      </View>
+      {detail && (
+        <Text size="xs" color="muted">
+          {detail}
+        </Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: SPACE.xs },
+  row: { flexDirection: "row", alignItems: "center", gap: SPACE.sm },
+});