@lotics/ui 1.6.1 → 1.9.0

package/package.json

@@ -1,15 +1,31 @@
 {
   "name": "@lotics/ui",
-  "version": "1.6.1",
+  "version": "1.9.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
     "./colors": "./src/colors.ts",
+    "./mime": "./src/mime.ts",
+    "./file_badge": "./src/file_badge.tsx",
+    "./file_thumbnail": "./src/file_thumbnail.tsx",
+    "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
     "./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 +41,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 +147,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);