@lotics/ui 1.6.0 → 1.8.0

package/src/kpi_card.tsx

@@ -0,0 +1,77 @@
+import { View, StyleSheet, type ViewStyle, type StyleProp } from "react-native";
+import { Text } from "./text";
+import { Metric, type MetricFormat, type MetricSize, type MetricTone } from "./metric";
+import { TrendChip } from "./trend_chip";
+import { SPACE } from "./spacing";
+
+interface KPICardProps {
+  /** Short uppercase label above the value. Identifies the metric. */
+  label: string;
+  /** The number to display. `null` renders as `emptyLabel`. */
+  value: number | string | null | undefined;
+  format?: MetricFormat;
+  currency?: string;
+  locale?: string;
+  emptyLabel?: string;
+  /** Numeric size hint. Default `lg`; pass `hero` for the dominant
+   * metric in a card; `md` for supporting metrics in a horizontal strip. */
+  size?: MetricSize;
+  tone?: MetricTone;
+  /** Optional ±% trend chip next to the value. Pass `null` (not omitted)
+   * to explicitly hide — useful when the comparator base is 0 and the
+   * percentage would be meaningless. */
+  trend?: number | null;
+  /**
+   * Goes below the value. Free text. Typical uses: comparator detail
+   * ("Tháng trước: 50.000.000 đ"), unit hint ("Hồ sơ"), or short caveat
+   * ("Tính theo ngày tạo").
+   */
+  caption?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * One labeled metric block — the building block of a KPI strip or hero
+ * row. Forces the recipe so authors can't drift:
+ *   - Uppercase muted label (eyeline anchor)
+ *   - Metric value with tabular nums + tighter tracking at display sizes
+ *   - Optional inline trend chip (the "is this good?" indicator)
+ *   - Optional caption below for comparator detail / unit / caveat
+ *
+ * The recipe matches Mercury's checking dashboard, Stripe's revenue cards,
+ * Linear's project metrics. Without enforcing it, dashboards drift into
+ * "every metric looks slightly different" — the #1 readability tell on
+ * mediocre dashboards.
+ */
+export function KPICard(props: KPICardProps) {
+  const { label, value, format, currency, locale, emptyLabel, size = "lg", tone, trend, caption, style } = props;
+  return (
+    <View style={[styles.container, style]}>
+      <Text size="xs" color="muted" transform="uppercase">
+        {label}
+      </Text>
+      <View style={styles.valueRow}>
+        <Metric
+          value={value}
+          format={format}
+          currency={currency}
+          locale={locale}
+          emptyLabel={emptyLabel}
+          size={size}
+          tone={tone}
+        />
+        {trend != null && <TrendChip value={trend} />}
+      </View>
+      {caption && (
+        <Text size="xs" color="muted">
+          {caption}
+        </Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: SPACE.xs },
+  valueRow: { flexDirection: "row", alignItems: "baseline", gap: SPACE.sm, flexWrap: "wrap" },
+});

package/src/legend_item.tsx

@@ -0,0 +1,47 @@
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Metric } from "./metric";
+import { SPACE } from "./spacing";
+
+interface LegendItemProps {
+  /** Square swatch color — should match the segment in the chart this
+   * legend annotates. */
+  color: string;
+  label: string;
+  /** Optional count to render after the label. `null` for loading state. */
+  value?: number | string | null;
+}
+
+/**
+ * Color swatch + label + optional count. Used as the legend row below a
+ * `StackedProgressBar`, a `ChartBar` with categorical colors, or any
+ * other chart where consumers need to map color → meaning.
+ *
+ * Tabular nums on the value (via Metric) keep counts aligned when several
+ * legend items sit in a row.
+ */
+export function LegendItem(props: LegendItemProps) {
+  return (
+    <View style={styles.row}>
+      <View style={[styles.swatch, { backgroundColor: props.color }]} />
+      <Text size="sm" color="muted">
+        {props.label}
+      </Text>
+      {props.value !== undefined && <Metric value={props.value} size="sm" />}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: SPACE.sm,
+    minWidth: 130,
+  },
+  swatch: {
+    width: 8,
+    height: 8,
+    borderRadius: 2,
+  },
+});

package/src/metric.tsx

@@ -1,10 +1,22 @@
-import { View, StyleSheet } from "react-native";
+import { View, StyleSheet, type TextStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { useMemo } from "react";
 
 export type MetricFormat = "currency" | "number" | "percentage" | "none";
 
+/** Semantic colour of the metric value. `default` inherits the text colour. */
+export type MetricTone = "default" | "warning" | "danger";
+
+/**
+ * Visual scale. `md` is the historical default — matches body display size.
+ * `hero` is for the single most important number in a section ("Doanh thu
+ * trong tháng: 10.000.000 đ" at the top of a card with smaller supporting
+ * metrics below). Mercury / Stripe / Linear all use this hero-supporting
+ * hierarchy to give dashboards a reading order.
+ */
+export type MetricSize = "sm" | "md" | "lg" | "hero";
+
 export interface MetricProps {
   value: number | string | null | undefined;
   previousValue?: number | string | null | undefined;
@@ -12,12 +24,36 @@ export interface MetricProps {
   currency?: string;
   locale?: string;
   emptyLabel?: string;
+  tone?: MetricTone;
+  size?: MetricSize;
 }
 
+const SIZE_TO_TEXT_SIZE: Record<MetricSize, "md" | "lg" | "xl" | "xxl"> = {
+  sm: "md",
+  md: "lg",
+  lg: "xl",
+  hero: "xxl",
+};
+
+// Letter-spacing tightens as font-size grows — "designed" not "inflated".
+// Hero gets the tightest tracking (-1.2) to match the 48px display size's
+// expected condensation.
+const SIZE_TO_LETTER_SPACING: Record<MetricSize, number> = {
+  sm: 0,
+  md: -0.25,
+  lg: -0.5,
+  hero: -1.2,
+};
+
 const TREND_UP = "↑";
 const TREND_DOWN = "↓";
 const TREND_FLAT = "→";
 
+const TONE_COLOR: Record<Exclude<MetricTone, "default">, string> = {
+  warning: colors.amber[600],
+  danger: colors.red[600],
+};
+
 export function Metric(props: MetricProps) {
   const {
     value,
@@ -26,6 +62,8 @@ export function Metric(props: MetricProps) {
     currency = "USD",
     locale,
     emptyLabel = "-",
+    tone = "default",
+    size = "md",
   } = props;
 
   const displayValue = useMemo(() => {
@@ -55,7 +93,22 @@ export function Metric(props: MetricProps) {
 
   return (
     <View style={styles.container}>
-      <Text size="xl" weight="semibold">
+      <Text
+        size={SIZE_TO_TEXT_SIZE[size]}
+        weight="medium"
+        style={[
+          // Tabular nums prevent the comma/decimal jitter when 1,234 sits
+          // next to 7,890 across cards — proportional glyphs misalign every
+          // column. Tighter tracking at display sizes reads as "designed",
+          // not "inflated body text" (Linear / Stripe / Geist all do this
+          // at hero metrics).
+          {
+            fontVariantNumeric: "tabular-nums",
+            letterSpacing: SIZE_TO_LETTER_SPACING[size],
+          } as TextStyle,
+          tone === "default" ? undefined : { color: TONE_COLOR[tone] },
+        ]}
+      >
         {displayValue}
       </Text>
       {trend && (

package/src/overlay_scope.ts

@@ -0,0 +1,44 @@
+import { useEffect } from "react";
+import { Platform } from "react-native";
+
+/**
+ * Tracks how many modal/overlay surfaces (dialogs, popovers) are currently open.
+ * A counter — not a boolean — so nested overlays compose correctly.
+ */
+let activeCount = 0;
+
+/**
+ * True while at least one modal dialog or popover is open. Read synchronously
+ * by the keyboard shortcut registry to suppress lower-layer page shortcuts so
+ * an open overlay does not hijack keystrokes (e.g. native Ctrl+F find).
+ */
+export function isOverlayScopeActive(): boolean {
+  return activeCount > 0;
+}
+
+/**
+ * Imperatively marks an overlay surface as open. Returns a release function
+ * that must be called exactly once when the overlay closes. Prefer the
+ * `useOverlayScope` hook in React components — this is the testable core.
+ */
+export function pushOverlayScope(): () => void {
+  activeCount++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    activeCount--;
+  };
+}
+
+/**
+ * Marks an overlay surface as open while `active` is true. Web-only — no-op on
+ * native. Call this from overlay primitives (Dialog, Popover, etc.), not from
+ * individual call sites.
+ */
+export function useOverlayScope(active: boolean): void {
+  useEffect(() => {
+    if (Platform.OS !== "web" || !active) return;
+    return pushOverlayScope();
+  }, [active]);
+}

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);
+}