@lotics/ui 1.6.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -10,6 +10,18 @@
     "./line_chart": "./src/line_chart.tsx",
     "./pie_chart": "./src/pie_chart.tsx",
     "./metric": "./src/metric.tsx",
+    "./sparkline": "./src/sparkline.tsx",
+    "./trend_chip": "./src/trend_chip.tsx",
+    "./section_card": "./src/section_card.tsx",
+    "./kpi_card": "./src/kpi_card.tsx",
+    "./alert_row": "./src/alert_row.tsx",
+    "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
+    "./legend_item": "./src/legend_item.tsx",
+    "./trend_footer": "./src/trend_footer.tsx",
+    "./chart_area": "./src/chart_area.tsx",
+    "./chart_bar": "./src/chart_bar.tsx",
+    "./spacing": "./src/spacing.ts",
+    "./theme": "./src/theme.tsx",
     "./progress_bar": "./src/progress_bar.tsx",
     "./form_date_picker": "./src/form_date_picker.tsx",
     "./form_time_picker": "./src/form_time_picker.tsx",
@@ -25,6 +37,7 @@
     "./portal": "./src/portal.tsx",
     "./popover_nav": "./src/popover_nav.tsx",
     "./popover": "./src/popover.tsx",
+    "./overlay_scope": "./src/overlay_scope.ts",
     "./switcher": "./src/switcher.tsx",
     "./menu_button": "./src/menu_button.tsx",
     "./menu_list_item": "./src/menu_list_item.tsx",
@@ -130,13 +143,15 @@
     "lucide-react": ">=0.460.0",
     "react-native-svg": ">=15.0.0",
     "expo-image": ">=3.0.0",
-    "@react-native-picker/picker": ">=2.0.0"
+    "@react-native-picker/picker": ">=2.0.0",
+    "recharts": ">=3.0.0"
   },
   "peerDependenciesMeta": {
     "expo-image": { "optional": true },
     "@react-native-picker/picker": { "optional": true },
     "lucide-react-native": { "optional": true },
-    "react-native-svg": { "optional": true }
+    "react-native-svg": { "optional": true },
+    "recharts": { "optional": true }
   },
   "scripts": {
     "typecheck": "tsgo --noEmit",

package/src/alert.tsx

@@ -3,6 +3,7 @@ import { createRoot, Root } from "react-dom/client";
 import "./alert.css";
 import { Text } from "./text";
 import { Button, ButtonColor } from "./button";
+import { useOverlayScope } from "./overlay_scope";
 
 export type AlertButtonStyle = "default" | "cancel" | "destructive";
 
@@ -81,6 +82,8 @@ class Alert {
     const AlertComponent = () => {
       const [visible, setVisible] = useState(true);
 
+      useOverlayScope(visible);
+
       const handleDismiss = useCallback(() => {
         if (alertOptions.cancelable !== false) {
           setVisible(false);

package/src/alert_row.tsx

@@ -0,0 +1,81 @@
+import { type ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Metric, type MetricSize, type MetricTone } from "./metric";
+import { colors } from "./colors";
+import { SPACE } from "./spacing";
+
+interface AlertRowProps {
+  /** Leading icon (lucide-react `<AlertCircle />`, `<CheckCircle2 />`, etc.).
+   * Sized 18px in the host. Caller controls color so different severities
+   * can use different palettes. */
+  icon: ReactNode;
+  label: string;
+  /** The count or quantity. `null` while loading → renders as `emptyLabel`. */
+  count: number | string | null;
+  /** Small text below the count — unit ("Hồ sơ"), amount caption
+   * ("12.000.000 đ"), or short hint. */
+  hint?: string;
+  /** Number size. Default `lg` keeps the row scannable; `md` for denser
+   * lists where many rows compete. */
+  size?: MetricSize;
+  /** Auto-set: non-zero count = danger (red), zero = default. Override for
+   * status semantics (e.g., when down is good). */
+  tone?: MetricTone;
+  /** Suppress the bottom hairline. Set on the last row of a list. */
+  last?: boolean;
+}
+
+/**
+ * One row of a prioritized action list — icon + label on the left, count
+ * + hint on the right. The Mercury / Linear "needs attention" pattern.
+ *
+ * Layout enforces two-column rhythm: left side flex-grows with the label,
+ * right side is fixed-width and right-aligned. Without enforcement, rows
+ * drift into "label centered, count floating left of right edge" which
+ * makes the list unscannable.
+ */
+export function AlertRow(props: AlertRowProps) {
+  const { icon, label, count, hint, size = "lg", tone, last } = props;
+  const hasIssue = typeof count === "number" && count > 0;
+  const resolvedTone: MetricTone = tone ?? (hasIssue ? "danger" : "default");
+  return (
+    <View style={[styles.row, !last && styles.divider]}>
+      <View style={styles.leftCol}>
+        {icon}
+        <Text size="sm">{label}</Text>
+      </View>
+      <View style={styles.rightCol}>
+        <Metric value={count} size={size} tone={resolvedTone} />
+        {hint && (
+          <Text size="xs" color="muted">
+            {hint}
+          </Text>
+        )}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingVertical: SPACE.md,
+  },
+  divider: {
+    borderBottomWidth: 1,
+    borderBottomColor: colors.zinc[100],
+  },
+  leftCol: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: SPACE.md,
+    flex: 1,
+  },
+  rightCol: {
+    alignItems: "flex-end",
+    minWidth: 100,
+  },
+});

package/src/card.tsx

@@ -40,6 +40,20 @@ const styles = StyleSheet.create({
     padding: 20,
     borderRadius: 16,
     backgroundColor: colors.background,
+    // 1px hairline + 2-layer shadow: the research-validated default across
+    // shadcn/ui, Geist, Tailwind v4. Without either, cards on a near-white
+    // page bg float without rhythm. Border anchors; shadow lifts. The shadow
+    // uses warm-neutral tint (38,38,38), not pure black — premium signal vs
+    // cheap-feeling pure-black shadows.
+    borderWidth: 1,
+    borderColor: colors.zinc["200"],
+    // Slightly more visible than shadcn's `shadow-sm` — chosen because our
+    // page bg is `colors.background` (off-white), making `shadow-sm` nearly
+    // invisible. Stripe / Linear use this stronger value on similar bg.
+    ...({
+      boxShadow:
+        "0 1px 2px 0 rgba(38,38,38,0.06), 0 4px 12px -2px rgba(38,38,38,0.06)",
+    } as ViewStyle),
   },
   hovered: {
     outlineColor: colors.zinc["900"],

package/src/cell_date_format.ts

@@ -26,11 +26,22 @@ export function formatDateValue(
   const { format = "date", dateStyle = "short", timeStyle = "short" } = options;
   const includeTime = format === "datetime";
 
+  // Intl's `dateStyle: "short"` yields a 2-digit year in many locales (en-US: "5/22/26",
+  // vi-VN: "22/05/26"); for data cells we want a compact numeric format with the full year.
+  // When we override to explicit date parts, the time parts must also be explicit — Intl
+  // forbids mixing `dateStyle`/`timeStyle` with `year`/`month`/`day`/`hour`/`minute`/etc.
+  const intlOptions: Intl.DateTimeFormatOptions =
+    dateStyle === "short"
+      ? {
+          year: "numeric",
+          month: "numeric",
+          day: "numeric",
+          ...(includeTime ? { hour: "numeric", minute: "numeric" } : {}),
+        }
+      : { dateStyle, ...(includeTime ? { timeStyle } : {}) };
+
   try {
-    return new Intl.DateTimeFormat(
-      locale,
-      includeTime ? { dateStyle, timeStyle } : { dateStyle },
-    ).format(date);
+    return new Intl.DateTimeFormat(locale, intlOptions).format(date);
   } catch {
     return includeTime ? date.toISOString() : value;
   }

package/src/chart_area.tsx

@@ -0,0 +1,105 @@
+import { useId } from "react";
+import { View } from "react-native";
+import {
+  Area,
+  AreaChart,
+  CartesianGrid,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+import { colors } from "./colors";
+import { useLoticsTheme } from "./theme";
+import { chartAxisTickStyle, chartTooltipLabelStyle, chartTooltipStyle } from "./chart_internals";
+
+interface ChartAreaProps<T> {
+  data: T[];
+  /** Property to use as the X-axis category (e.g. month label). */
+  xKey: keyof T & string;
+  /** Property to use as the Y-axis value. */
+  yKey: keyof T & string;
+  /** Pixel height. Default 200. Charts shorter than ~120 lose readability;
+   * taller than ~280 dominate the card. */
+  height?: number;
+  /** Override the theme accent for this chart instance. */
+  color?: string;
+  /** Format the Y value in tooltips. Defaults to `Intl.NumberFormat` for
+   * numbers, identity for strings. */
+  formatValue?: (value: number) => string;
+  /** Label shown next to the value in the tooltip. Default `Value`. */
+  valueLabel?: string;
+}
+
+/**
+ * Shadcn-style area chart — gradient fill, dashed horizontal-only
+ * gridlines, clean axes (no axisLine, no tickLine), tooltip with the
+ * standard chart tooltip chrome.
+ *
+ * Defaults pulled from the `useLoticsTheme()` accent so consumers don't
+ * need to think about color choice. Override via the `color` prop for
+ * one-off charts that need a different hue.
+ *
+ * Why a wrapper instead of just exposing Recharts to consumers: the
+ * "shadcn pattern" is a dozen non-obvious Recharts props (axisLine={false},
+ * tickLine={false}, monotone interpolation, gradient stops at 5% and 95%,
+ * stroke-dasharray "3 3" on grid, …). Without the wrapper, every
+ * consumer has to remember the full recipe; with it, they pass data and
+ * get the polish.
+ */
+export function ChartArea<T extends Record<string, unknown>>(props: ChartAreaProps<T>) {
+  const { data, xKey, yKey, height = 200, color, formatValue, valueLabel = "Value" } = props;
+  const theme = useLoticsTheme();
+  const fill = color ?? theme.accent;
+  // `useId` guarantees the gradient `id` is unique even when multiple
+  // ChartArea instances render on the same page — without it, two charts
+  // would share the same `url(#revenueFill)` and the second would lose
+  // its gradient.
+  const gradientId = `chartArea-${useId()}`;
+  return (
+    <View style={{ height }}>
+      <ResponsiveContainer width="100%" height="100%">
+        <AreaChart data={data} margin={{ top: 12, right: 8, left: 8, bottom: 0 }}>
+          <defs>
+            {/* 3-stop gradient: deeper top (55%), accelerated mid-fade,
+                clean bottom. Single 5%→95% linear stop reads as "tinted",
+                3-stop with the middle inflection at 50%/18% reads as
+                "designed". Stripe / Mercury use the multi-stop shape; the
+                eye picks up the non-linear falloff as intentional. */}
+            <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+              <stop offset="0%" stopColor={fill} stopOpacity={0.55} />
+              <stop offset="50%" stopColor={fill} stopOpacity={0.18} />
+              <stop offset="100%" stopColor={fill} stopOpacity={0} />
+            </linearGradient>
+          </defs>
+          <CartesianGrid vertical={false} stroke={colors.zinc[200]} strokeDasharray="3 3" />
+          <XAxis
+            dataKey={xKey as string}
+            axisLine={false}
+            tickLine={false}
+            tickMargin={10}
+            tick={chartAxisTickStyle}
+          />
+          <YAxis hide />
+          <Tooltip
+            cursor={{ stroke: colors.zinc[300], strokeDasharray: "3 3" }}
+            contentStyle={chartTooltipStyle}
+            labelStyle={chartTooltipLabelStyle}
+            formatter={(val: unknown) => {
+              if (typeof val !== "number") return [String(val), valueLabel];
+              return [formatValue ? formatValue(val) : val.toLocaleString(), valueLabel];
+            }}
+          />
+          <Area
+            type="monotone"
+            dataKey={yKey as string}
+            stroke={fill}
+            strokeWidth={2.5}
+            fill={`url(#${gradientId})`}
+            animationDuration={600}
+          />
+        </AreaChart>
+      </ResponsiveContainer>
+    </View>
+  );
+}

package/src/chart_bar.tsx

@@ -0,0 +1,154 @@
+import { View } from "react-native";
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Cell,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+import { colors } from "./colors";
+import { useLoticsTheme } from "./theme";
+import {
+  chartAxisTickStyle,
+  chartTooltipLabelStyle,
+  chartTooltipStyle,
+  chartYAxisCategoryTickStyle,
+} from "./chart_internals";
+
+interface ChartBarProps<T> {
+  data: T[];
+  /** Property to use as the category axis. */
+  categoryKey: keyof T & string;
+  /** Property to use as the value axis. */
+  valueKey: keyof T & string;
+  /** Per-row fill color. Optional — when omitted, all bars use the theme
+   * accent. Set this when each category needs its own color (funnel
+   * stages, status breakdowns, etc.). */
+  fillKey?: keyof T & string;
+  /** Orientation. Default `vertical` (category on X, value on Y). Use
+   * `horizontal` for "rank by value" lists where category names are
+   * long (member names, account labels). */
+  orientation?: "vertical" | "horizontal";
+  /** Pixel height. Default 220 vertical / row-count × 56 horizontal.
+   * Pass explicit value for fixed-height layouts. */
+  height?: number;
+  /** Override the theme accent for this chart instance. */
+  color?: string;
+  /** Format the value in tooltips + value labels. */
+  formatValue?: (value: number) => string;
+  /** Label shown next to the value in the tooltip. Default `Value`. */
+  valueLabel?: string;
+}
+
+/**
+ * Shadcn-style bar chart. Vertical (categories on X axis) is the default;
+ * pass `orientation="horizontal"` for rank-by-value lists where labels are
+ * long.
+ *
+ * Vertical: rounded TOP corners only (radius 6) — the shadcn pattern.
+ * Horizontal: rounded RIGHT corners only.
+ *
+ * Per-bar colors via `fillKey`: each data row carries its own color. Use
+ * for funnel/category breakdowns. Omit for single-hue bar charts (the
+ * theme accent fills every bar).
+ */
+export function ChartBar<T extends Record<string, unknown>>(props: ChartBarProps<T>) {
+  const {
+    data,
+    categoryKey,
+    valueKey,
+    fillKey,
+    orientation = "vertical",
+    height,
+    color,
+    formatValue,
+    valueLabel = "Value",
+  } = props;
+  const theme = useLoticsTheme();
+  const fill = color ?? theme.accent;
+  const isHorizontal = orientation === "horizontal";
+  const resolvedHeight = height ?? (isHorizontal ? Math.max(120, data.length * 56) : 220);
+  return (
+    <View style={{ height: resolvedHeight }}>
+      <ResponsiveContainer width="100%" height="100%">
+        <BarChart
+          data={data}
+          layout={isHorizontal ? "vertical" : "horizontal"}
+          margin={
+            isHorizontal
+              ? { top: 4, right: 40, left: 4, bottom: 4 }
+              : { top: 8, right: 0, left: 0, bottom: 0 }
+          }
+          barCategoryGap={isHorizontal ? "35%" : undefined}
+        >
+          <CartesianGrid
+            vertical={isHorizontal ? false : false}
+            horizontal={isHorizontal ? false : true}
+            stroke={colors.zinc[200]}
+            strokeDasharray="3 3"
+          />
+          {isHorizontal ? (
+            <>
+              <XAxis type="number" hide />
+              <YAxis
+                type="category"
+                dataKey={categoryKey as string}
+                axisLine={false}
+                tickLine={false}
+                width={160}
+                tick={chartYAxisCategoryTickStyle}
+              />
+            </>
+          ) : (
+            <>
+              {/* Recharts v3's dataKey expects a TypedDataKey resolved from the
+                  generic; our wrapper is generic over T so we pass the raw
+                  string key. Cast at the boundary — consumers' data shape is
+                  validated via the categoryKey: keyof T constraint. */}
+              <XAxis
+                dataKey={categoryKey as string}
+                axisLine={false}
+                tickLine={false}
+                tickMargin={8}
+                tick={chartAxisTickStyle}
+              />
+              <YAxis hide />
+            </>
+          )}
+          <Tooltip
+            cursor={{ fill: colors.zinc[100] }}
+            contentStyle={chartTooltipStyle}
+            labelStyle={chartTooltipLabelStyle}
+            formatter={(val: unknown) => {
+              if (typeof val !== "number") return [String(val), valueLabel];
+              return [formatValue ? formatValue(val) : val.toLocaleString(), valueLabel];
+            }}
+          />
+          <Bar
+            dataKey={valueKey as string}
+            fill={fill}
+            radius={isHorizontal ? [0, 4, 4, 0] : [6, 6, 0, 0]}
+            label={
+              isHorizontal
+                ? {
+                    position: "right",
+                    fill: colors.zinc[700],
+                    fontSize: 13,
+                    fontWeight: 500,
+                  }
+                : undefined
+            }
+          >
+            {fillKey &&
+              data.map((row, i) => (
+                <Cell key={i} fill={String(row[fillKey] ?? fill)} />
+              ))}
+          </Bar>
+        </BarChart>
+      </ResponsiveContainer>
+    </View>
+  );
+}

package/src/chart_internals.tsx

@@ -0,0 +1,43 @@
+import { colors } from "./colors";
+
+/**
+ * Shared chart styling helpers + the shadcn-style tooltip box style.
+ * Centralized so every @lotics/ui chart wrapper looks identical without
+ * duplicating the magic numbers across files.
+ *
+ * Pure constants + a type — no JSX, no peer dep impact. The chart wrappers
+ * that import this also import Recharts directly; this file is safe to
+ * import from anywhere.
+ */
+
+/** Tooltip popover box. Matches shadcn's `<ChartTooltipContent />` chrome:
+ * white card, hairline border, soft warm-neutral shadow, tight padding. */
+export const chartTooltipStyle = {
+  backgroundColor: colors.white,
+  border: `1px solid ${colors.zinc[200]}`,
+  borderRadius: 10,
+  // Two-layer shadow: tight first stop for definition, soft second stop
+  // for atmosphere. Stripe / Linear pattern — single-shadow tooltips read
+  // as "default Recharts", layered shadow reads as "designed".
+  boxShadow: "0 1px 2px rgba(38,38,38,0.04), 0 8px 20px -4px rgba(38,38,38,0.08)",
+  fontSize: 13,
+  padding: "10px 14px",
+} as const;
+
+export const chartTooltipLabelStyle = {
+  color: colors.zinc[600],
+  fontWeight: 500,
+} as const;
+
+/** Axis tick text — small, muted, no rotation. */
+export const chartAxisTickStyle = {
+  fontSize: 12,
+  fill: colors.zinc[500],
+} as const;
+
+/** Y-axis label text on horizontal bar charts — slightly heavier than X
+ * because it's reading a name, not a number. */
+export const chartYAxisCategoryTickStyle = {
+  fontSize: 13,
+  fill: colors.zinc[700],
+} as const;

package/src/dialog.tsx

@@ -6,6 +6,7 @@ import { colors } from "@lotics/ui/colors";
 import { Button } from "@lotics/ui/button";
 import { Text } from "@lotics/ui/text";
 import { BackButton } from "@lotics/ui/back_button";
+import { useOverlayScope } from "@lotics/ui/overlay_scope";
 import {
   ScreenRouterContext,
   ScreenRouterInternalContext,
@@ -101,6 +102,8 @@ export function Dialog(props: DialogProps) {
   const isControlled = controlledOpen !== undefined;
   const open = isControlled ? controlledOpen : uncontrolledOpen;
 
+  useOverlayScope(open);
+
   const routeRegistry = useRouteRegistry();
   const { routerValue, internalValue, resetStack } = useNavigationStack(initialRoute, routeRegistry);
 

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,4 +1,4 @@
-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";
@@ -8,6 +8,15 @@ 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;
@@ -16,8 +25,26 @@ export interface MetricProps {
   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 = "→";
@@ -36,6 +63,7 @@ export function Metric(props: MetricProps) {
     locale,
     emptyLabel = "-",
     tone = "default",
+    size = "md",
   } = props;
 
   const displayValue = useMemo(() => {
@@ -66,9 +94,20 @@ export function Metric(props: MetricProps) {
   return (
     <View style={styles.container}>
       <Text
-        size="xl"
-        weight="semibold"
-        style={tone === "default" ? undefined : { color: TONE_COLOR[tone] }}
+        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>

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

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