@lotics/ui 8.0.0 → 10.0.0

package/src/record_summary.tsx

@@ -0,0 +1,101 @@
+import { type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { Text } from "./text";
+
+export interface RecordSummaryMetric {
+  /** Caption above the number ("Outstanding", "Total value"). */
+  label: string;
+  /** The headline figure — rendered lg semibold tabular. */
+  value: string;
+  /** Valence of the figure (and its note) — the summary's ONE permitted accent. */
+  tone?: "default" | "danger" | "warning" | "success";
+  /** One short qualifier under the number ("Overdue 25 days"). */
+  note?: string;
+}
+
+export interface RecordSummaryProps {
+  /** The record's id/name — xl semibold, tabular so ids align across records. */
+  title: string;
+  /** Heading level of the title (`role="header"` + aria-level). Default 1 —
+   *  the record page's one h1; pass 2 when the band sits inside a surface
+   *  that already owns the h1 (a drawer with its own titled header). */
+  level?: 1 | 2 | 3;
+  /** Identity qualifiers on the title line ("HCM → Hamburg · Export · FCL") —
+   *  sm muted; wraps under the title when narrow. */
+  subtitle?: string;
+  /** A status chip (a `Badge`) or any small node right after the title. */
+  status?: ReactNode;
+  /** ONE headline number with valence — pinned to the summary's top right.
+   *  More than one figure belongs in a KPI strip, not the record header. */
+  metric?: RecordSummaryMetric;
+}
+
+/**
+ * The identity band of a single record's detail screen or drawer: ONE row —
+ * title · subtitle · status chip, with an optional headline metric pinned
+ * right. It exists to stop hand-rolled record headers drifting: mixed type
+ * scales, several competing figures, color noise.
+ *
+ * Color discipline: the header stays neutral; `metric.tone` is the one accent.
+ * The record's FIELDS never live in the header — compose them as
+ * `DetailTable`s in the sections below (`SectionHeading` + `Divider` rhythm) —
+ * see `examples/tpl_record.tsx`.
+ */
+export function RecordSummary(props: RecordSummaryProps) {
+  const { title, subtitle, status, metric, level = 1 } = props;
+  return (
+    <View style={styles.identityRow}>
+        <View style={styles.identity}>
+          <View style={styles.titleRow}>
+            <Text size="xl" weight="semibold" tabular level={level}>
+              {title}
+            </Text>
+            {status ?? null}
+          </View>
+          {subtitle ? (
+            <Text size="sm" color="muted">
+              {subtitle}
+            </Text>
+          ) : null}
+        </View>
+        {metric ? (
+          <View style={styles.metric}>
+            <Text size="xs" color="muted" weight="medium" align="right">
+              {metric.label}
+            </Text>
+            <Text size="lg" weight="semibold" tabular align="right" color={metric.tone === "default" ? undefined : metric.tone}>
+              {metric.value}
+            </Text>
+            {metric.note ? (
+              <Text size="xs" align="right" weight={metric.tone && metric.tone !== "default" ? "medium" : "regular"} color={metric.tone && metric.tone !== "default" ? metric.tone : "muted"}>
+                {metric.note}
+              </Text>
+            ) : null}
+          </View>
+        ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  identityRow: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: 16,
+  },
+  identity: {
+    flex: 1,
+    gap: 2,
+  },
+  titleRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexWrap: "wrap",
+    columnGap: 10,
+    rowGap: 4,
+  },
+  metric: {
+    alignItems: "flex-end",
+    gap: 1,
+  },
+});

package/src/section_heading.tsx

@@ -2,6 +2,7 @@ import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Text, type HeadingLevel } from "./text";
 import { Icon, type IconName } from "./icon";
 import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 
 // The card-less section header — the bare-canvas sibling of `CardHeader`, built
 // the same compound way. A title (+ optional leading icon / description) on one
@@ -36,7 +37,12 @@ export interface SectionProps {
  *   </Section>
  */
 export function Section(props: SectionProps) {
-  return <View style={[{ gap: 10 }, props.style]}>{props.children}</View>;
+  // gap 12 spaces the heading from its body. Space BETWEEN sections belongs to
+  // the page column: flat record/form pages use `gap: 32` on the content column
+  // with a bare `Divider` BETWEEN sections (never under the heading — the
+  // heading belongs to its content; the hairline separates it from the LAST
+  // section).
+  return <View style={[{ gap: 12 }, props.style]}>{props.children}</View>;
 }
 
 export interface SectionHeadingProps {
@@ -58,26 +64,28 @@ export interface SectionHeadingTitleProps {
   icon?: IconName;
   /** Heading rank. Defaults to 2 — typical for page-level section titles. */
   level?: HeadingLevel;
-  /** Title weight. Defaults to `medium`; `semibold` (matching `CardHeaderTitle`)
-   * for denser surfaces — a side panel, a stacked group list — where `medium`
-   * blends into the body rows. */
+  /** Title weight. Defaults to `semibold` — a section title must separate from
+   * the body rows at a glance (medium blends in; it remains as an opt-down for
+   * a surface where the heading competes with a stronger band above it). */
   weight?: "medium" | "semibold";
   /** An ⓘ popover after the title — a short "what this is / where it came from"
    * gloss, mirroring `CardHeaderTitle`'s `info`. */
   info?: string;
 }
 
-/** The title block — grows to push any sibling actions to the right edge. */
+/** The title block — lg semibold (a section must announce itself; md blends
+ * into control labels) + an optional muted `description` line. Grows to push
+ * any sibling actions to the right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level = 2, weight = "medium", info } = props;
+  const { children, description, icon, level = 2, weight = "semibold", info } = props;
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
         {icon ? <Icon name={icon} size={18} /> : null}
-        <Text level={level} weight={weight} size="md">
+        <Text level={level} weight={weight} size="lg">
           {children}
         </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel="Giải thích dữ liệu" /> : null}
+        {info ? <InfoPopover text={info} accessibilityLabel={useLoticsLocale().sectionHeading.info} /> : null}
       </View>
       {description ? (
         <Text color="zinc-500" size="sm">

package/src/suggestion_chip.tsx

@@ -0,0 +1,47 @@
+import { StyleSheet, View } from "react-native";
+import { Chip } from "./chip";
+import { colors } from "./colors";
+import { Icon } from "./icon";
+import { useLoticsLocale } from "./locale";
+import { Text } from "./text";
+
+export interface SuggestionChipProps {
+  /** The suggested item ("Verify the customer's tax ID"). */
+  label: string;
+  /** Materialize the suggestion. */
+  onAdd: () => void;
+  /** Refuse the suggestion (the ✕). Omit for take-it-or-leave-it pills. */
+  onDismiss?: () => void;
+  /** Accessible name of the press target; default "Add: <label>". */
+  accessibilityLabel?: string;
+  /** The ✕'s name; defaults to the locale's "Dismiss suggestion". */
+  dismissLabel?: string;
+}
+
+/**
+ * A dismissible SUGGESTION pill — an item the record could have but doesn't
+ * yet (a common task, an expected line): a `Chip` whose press MATERIALIZES it
+ * and whose ✕ refuses it. A pill can never be mistaken for the real row it
+ * would become; suggestions never count in any total. Filter out labels the
+ * list already holds before rendering.
+ */
+export function SuggestionChip(props: SuggestionChipProps) {
+  const { label, onAdd, onDismiss, accessibilityLabel, dismissLabel } = props;
+  const labels = useLoticsLocale().suggestionChip;
+  return (
+    <Chip onPress={onAdd} accessibilityLabel={accessibilityLabel ?? labels.add(label)} onDismiss={onDismiss} dismissTooltip={dismissLabel ?? labels.dismiss}>
+      <View style={styles.content}>
+        <Icon name="plus" size={15} color={colors.zinc[500]} />
+        <Text size="sm">{label}</Text>
+      </View>
+    </Chip>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+  },
+});

package/src/trend_footer.tsx

@@ -1,4 +1,5 @@
 import { TrendingDown, TrendingUp } from "lucide-react";
+import { useLoticsLocale } from "./locale";
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
@@ -32,13 +33,14 @@ export function TrendFooter(props: TrendFooterProps) {
   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 labels = useLoticsLocale().trendFooter;
   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 ? "Up" : "Down"} {Math.abs(value)}% {periodLabel}
+          {up ? labels.up : labels.down} {Math.abs(value)}% {periodLabel}
         </Text>
       </View>
       {detail && (

package/src/use_screen_size.ts

@@ -1,5 +1,5 @@
 import { useEffect, useState } from "react";
-import { Dimensions, Platform } from "react-native";
+import { Dimensions } from "react-native";
 
 const breakpoints = {
   // small (mobile)

package/src/use_section_nav.test.ts

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useSectionNav } from "./use_section_nav";
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent } from "react-native";
+
+const layoutAt = (y: number) => ({ nativeEvent: { layout: { y } } }) as LayoutChangeEvent;
+const scrollTo = (y: number) => ({ nativeEvent: { contentOffset: { y } } }) as NativeSyntheticEvent<NativeScrollEvent>;
+
+function mounted() {
+  const hook = renderHook(() => useSectionNav(["a", "b", "c"] as const));
+  act(() => {
+    hook.result.current.register("a")(layoutAt(0));
+    hook.result.current.register("b")(layoutAt(400));
+    hook.result.current.register("c")(layoutAt(900));
+  });
+  return hook;
+}
+
+describe("useSectionNav", () => {
+  it("starts on the first key", () => {
+    const { result } = renderHook(() => useSectionNav(["a", "b"] as const));
+    expect(result.current.activeKey).toBe("a");
+  });
+
+  it("activates the last section whose top passed the viewport edge (+80 threshold)", () => {
+    const { result } = mounted();
+    act(() => result.current.onScroll(scrollTo(0)));
+    expect(result.current.activeKey).toBe("a");
+    // 321 + 80 threshold = 401 >= b's 400 → b is active
+    act(() => result.current.onScroll(scrollTo(321)));
+    expect(result.current.activeKey).toBe("b");
+    // just short of the threshold stays on a
+    act(() => result.current.onScroll(scrollTo(319)));
+    expect(result.current.activeKey).toBe("a");
+    act(() => result.current.onScroll(scrollTo(2000)));
+    expect(result.current.activeKey).toBe("c");
+  });
+
+  it("keys walk in page order — a later key with a smaller offset never wins", () => {
+    const { result } = renderHook(() => useSectionNav(["a", "b"] as const));
+    act(() => {
+      result.current.register("a")(layoutAt(500));
+      result.current.register("b")(layoutAt(100));
+    });
+    act(() => result.current.onScroll(scrollTo(600)));
+    // both tops passed; the LAST key in page order wins
+    expect(result.current.activeKey).toBe("b");
+  });
+
+  it("ignores keys that never registered", () => {
+    const { result } = renderHook(() => useSectionNav(["a", "b", "c"] as const));
+    act(() => result.current.register("a")(layoutAt(0)));
+    act(() => result.current.onScroll(scrollTo(999)));
+    expect(result.current.activeKey).toBe("a");
+  });
+
+  it("jumpTo scrolls to the section's offset minus the 12px breathing room, clamped at 0", () => {
+    const { result } = mounted();
+    const calls: { y: number }[] = [];
+    (result.current.scrollRef as { current: unknown }).current = {
+      scrollTo: (opts: { y: number }) => calls.push(opts),
+    };
+    act(() => result.current.jumpTo("b"));
+    expect(calls[0]?.y).toBe(388);
+    act(() => result.current.jumpTo("a"));
+    expect(calls[1]?.y).toBe(0);
+  });
+});

package/src/use_section_nav.ts

@@ -0,0 +1,59 @@
+import { RefObject, useRef, useState } from "react";
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView } from "react-native";
+
+export interface SectionNavHandle<K extends string> {
+  /** Attach to the content `ScrollView` (with `onScroll` + `scrollEventThrottle={16}`). */
+  scrollRef: RefObject<ScrollView | null>;
+  /** The section the scroll currently sits in — drives the rail's `selected`. */
+  activeKey: K;
+  /** `onLayout={register(key)}` on each section wrapper. The wrapper must be a
+   *  DIRECT child of the ScrollView content (layout.y is content-relative). */
+  register: (key: K) => (e: LayoutChangeEvent) => void;
+  /** Scroll to a section — the rail item's `onPress`. */
+  jumpTo: (key: K) => void;
+  onScroll: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+
+/**
+ * Scroll-spy for a LONG record surface with a left outline rail: one scrolling
+ * page whose sections register their offsets, a rail of `MenuButton`s that
+ * jumps to them, and an `activeKey` that follows the scroll (the section whose
+ * top has passed the viewport edge is the active one).
+ *
+ *   const nav = useSectionNav(["details", "gatein", "gateout"] as const);
+ *   <MenuButton title="Gate in" selected={nav.activeKey === "gatein"}
+ *               onPress={() => nav.jumpTo("gatein")} />
+ *   <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16}>
+ *     <View onLayout={nav.register("gatein")}>…</View>
+ *
+ * Pass the keys in PAGE ORDER — the spy walks them top-down. Hide the rail on
+ * narrow containers (the page still scrolls; the rail is a wide-screen aid).
+ *
+ * Contract: every key's section stays MOUNTED (an unmounted section leaves its
+ * last offset registered — conditional sections belong inside an always-mounted
+ * wrapper that carries the `onLayout`), and offsets refresh only when a
+ * section's own layout changes — react-native-web's `onLayout` won't refire on
+ * a pure position shift, so content above the sections should settle before
+ * precision matters.
+ */
+export function useSectionNav<K extends string>(keys: readonly [K, ...K[]]): SectionNavHandle<K> {
+  const scrollRef = useRef<ScrollView>(null);
+  const sectionY = useRef<Partial<Record<K, number>>>({});
+  const [activeKey, setActiveKey] = useState<K>(keys[0]);
+  const register = (key: K) => (e: LayoutChangeEvent) => {
+    sectionY.current[key] = e.nativeEvent.layout.y;
+  };
+  const jumpTo = (key: K) => {
+    scrollRef.current?.scrollTo({ y: Math.max(0, (sectionY.current[key] ?? 0) - 12), animated: true });
+  };
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const y = e.nativeEvent.contentOffset.y + 80;
+    let cur: K = keys[0];
+    for (const k of keys) {
+      const sy = sectionY.current[k];
+      if (sy != null && sy <= y) cur = k;
+    }
+    if (cur !== activeKey) setActiveKey(cur);
+  };
+  return { scrollRef, activeKey, register, jumpTo, onScroll };
+}