@lotics/ui 42.0.0 → 42.4.0

package/src/summary.tsx

@@ -0,0 +1,217 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { Metric, type MetricFormat, type MetricTone } from "./metric";
+import { StackedProgressBar } from "./stacked_progress_bar";
+import { SummaryLine, type SummaryLineItem } from "./summary_line";
+import { useLocaleTag } from "./locale";
+import { Text } from "./text";
+
+/**
+ * One bucket of the set being summarized — a slice of the whole, with the colour
+ * it wears wherever it appears.
+ *
+ * The buckets PARTITION the set: their values sum to the total, which is why the
+ * total is derived rather than passed. A count that belongs to the same rows but
+ * does not partition them — a condition rather than a position, "overdue" beside
+ * "draft / sent / paid" — is not a bucket and must not be one, or the bar starts
+ * claiming a share for something that is already inside another segment. Pass
+ * those to `Summary.Facts` as `extra`.
+ */
+export interface SummaryBucket {
+  key: string;
+  /** Reads AFTER the value, like every other label in this family. */
+  label: string;
+  value: number;
+  /** The segment's colour, and the swatch's. Use the same value this bucket
+   *  wears in the rest of the product — a bar that disagrees with the badge
+   *  beside it is worse than no bar. */
+  color: string;
+  /** What this bucket means — the ⓘ beside its count. */
+  info?: string;
+}
+
+interface SummaryContext {
+  buckets: readonly SummaryBucket[];
+  total: number;
+}
+
+const Ctx = createContext<SummaryContext | null>(null);
+
+function useSummary(part: string): SummaryContext {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error(`<Summary.${part}> must be rendered inside <Summary>.`);
+  return ctx;
+}
+
+interface SummaryProps {
+  buckets: readonly SummaryBucket[];
+  children: ReactNode;
+}
+
+/**
+ * The register's summary band — a headline figure, the set's DISTRIBUTION, and
+ * the buckets named — composed from parts rather than configured by props.
+ *
+ * **Why a compound and not one component with more props.** The parts encode a
+ * correspondence that is easy to break and impossible to see broken: the bar,
+ * the legend and the headline all describe ONE set. Passing a `segments` array
+ * beside an `items` array beside a `total` invites exactly three drifts —
+ * segments reordered against their labels, a legend swatch picking a different
+ * shade, and a hardcoded total that stops summing after a bucket is added. So
+ * the buckets are declared ONCE on the root and every part derives from them.
+ * The total is a sum. The swatches are the segments' own colours. Nothing is
+ * restated, so nothing can disagree.
+ *
+ * That correspondence is the reason this is a primitive at all — this kit does
+ * not extract a composition for saving lines of layout.
+ *
+ * Reach for it when the set has a SHAPE worth showing. A summary that is only a
+ * few aggregates stays `SummaryLine`, which is this band's `Facts` row on its
+ * own; a boxed dashboard stat band is `KPIStrip`; a drill-down facet browser
+ * over a large population is `Breakdown`.
+ *
+ *     <Summary buckets={STAGES}>
+ *       <Summary.Header>
+ *         <Summary.Total label="khách hàng" />
+ *         <Summary.Metric value={660_000_000} label="hoa hồng" format="currency" compact />
+ *       </Summary.Header>
+ *       <Summary.Distribution />
+ *       <Summary.Facts extra={[{ label: "đang tắc", value: 3, tone: "warning" }]} />
+ *     </Summary>
+ */
+export function Summary(props: SummaryProps) {
+  const { buckets, children } = props;
+  const total = buckets.reduce((sum, b) => sum + b.value, 0);
+  return (
+    <Ctx.Provider value={{ buckets, total }}>
+      <View style={styles.root}>{children}</View>
+    </Ctx.Provider>
+  );
+}
+
+/** The band's top line: a `Total` at the start, anything else pushed to the end.
+ *  Baseline-aligned, because figures of different sizes sitting on one line is
+ *  the whole reason this row exists. */
+function Header(props: { children: ReactNode }) {
+  return <View style={styles.header}>{props.children}</View>;
+}
+
+/**
+ * The set's SIZE, at display scale — the band's headline.
+ *
+ * The number is the sum of the buckets and is never passed in. A page that
+ * restates its own total eventually restates it wrongly: a bucket gets added,
+ * the constant does not move, and the headline quietly disagrees with the bar
+ * directly beneath it.
+ */
+function Total(props: { label: string; formatValue?: (n: number) => string }) {
+  const { total } = useSummary("Total");
+  const tag = useLocaleTag();
+  // Grouped by the reader's locale by default — a set of 12,345 was rendering
+  // "12345" in the one place on the screen sized to be read first, because the
+  // first app to use this counted in the hundreds. `formatValue` is the escape
+  // hatch for a total whose unit is not a plain count.
+  const shown = props.formatValue ? props.formatValue(total) : total.toLocaleString(tag);
+  return (
+    <View style={styles.pair}>
+      <Text size="xxxl" weight="semibold" tabular>
+        {shown}
+      </Text>
+      <Text size="md" color="muted">
+        {props.label}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * A second headline figure that is NOT part of the distribution — a sum of money
+ * over the same rows, an average, a rate.
+ *
+ * Deliberately not a bucket: it does not partition the set, so the bar must not
+ * carry it. It sits on the header row because a reader opening a register asks
+ * two questions ("how much of this is there" and "what is it worth"), and the
+ * answers belong side by side.
+ */
+function SummaryMetric(props: {
+  value: number | string | null | undefined;
+  label: string;
+  format?: MetricFormat;
+  currency?: string;
+  compact?: boolean;
+  emptyLabel?: string;
+  tone?: MetricTone;
+}) {
+  const { value, label, ...rest } = props;
+  return (
+    <View style={styles.pair}>
+      <Metric value={value} size="lg" {...rest} />
+      <Text size="sm" color="muted">
+        {label}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * The set's shape — one segment per bucket, in declaration order.
+ *
+ * Order is the CALLER's, untouched, because for an ordered set (a pipeline, a
+ * ladder, an age bracket) the sequence carries meaning that sorting by size
+ * would destroy. Re-rank the array before passing it if size is what matters.
+ */
+function Distribution(props: { height?: number }) {
+  const { buckets, total } = useSummary("Distribution");
+  return (
+    <StackedProgressBar
+      height={props.height ?? 20}
+      total={total}
+      segments={buckets.map((b) => ({ key: b.key, value: b.value, color: b.color }))}
+    />
+  );
+}
+
+/**
+ * The buckets named, with their counts — the band's legend, and on its own the
+ * whole of `SummaryLine`.
+ *
+ * Each item takes its swatch from its own bucket, so the legend cannot drift
+ * from the bar above it. `extra` appends aggregates that are NOT segments and
+ * therefore get no swatch — the visual difference is the point: a reader can see
+ * that the unswatched figure is not a slice of the bar.
+ */
+function Facts(props: { extra?: readonly SummaryLineItem[] }) {
+  const { buckets } = useSummary("Facts");
+  const items: SummaryLineItem[] = buckets.map((b) => ({
+    label: b.label,
+    value: b.value,
+    color: b.color,
+    info: b.info,
+  }));
+  return <SummaryLine items={[...items, ...(props.extra ?? [])]} />;
+}
+
+Summary.Header = Header;
+Summary.Total = Total;
+Summary.Metric = SummaryMetric;
+Summary.Distribution = Distribution;
+Summary.Facts = Facts;
+
+const styles = StyleSheet.create({
+  // 12, and it is half of what a page must put BETWEEN this band and its
+  // neighbours. The band's parts are one group — a figure, the shape of what it
+  // counts, and that shape's key — so they have to sit closer to each other than
+  // the band sits to the register below it. Measured at 14 against a 16px page
+  // gap, the ratio was 1.14: every block on the screen an equal peer, nothing
+  // grouped, which is what "no rhythm" is when you measure it.
+  root: { gap: 12 },
+  header: {
+    flexDirection: "row",
+    alignItems: "baseline",
+    flexWrap: "wrap",
+    justifyContent: "space-between",
+    columnGap: 20,
+    rowGap: 8,
+  },
+  pair: { flexDirection: "row", alignItems: "baseline", gap: 8 },
+});

package/src/summary_line.tsx

@@ -20,6 +20,21 @@ export interface SummaryLineItem {
   trend?: number | null;
   /** What this metric means — the ⓘ next to the value opens it in a popover. */
   info?: string;
+  /**
+   * Swatch colour, when this line is ALSO the legend for a chart above it —
+   * typically a `StackedProgressBar` whose segments are these same aggregates.
+   *
+   * It exists so a bar can be labelled without giving up what this component
+   * already carries. `LegendItem` annotates a chart but holds no `info`, so
+   * reaching for it costs the popovers that explain what a bucket includes and
+   * what it must not be added to — and those explanations are the reason several
+   * of these lines are trustworthy. One swatch here keeps identity off colour
+   * alone, which is what a legend is for.
+   *
+   * Pass the SAME value the segment uses. Omit it and the item renders exactly
+   * as it always has.
+   */
+  color?: string;
 }
 
 export interface SummaryLineProps {
@@ -55,6 +70,7 @@ export function SummaryLine(props: SummaryLineProps) {
     <View style={styles.row}>
       {items.map((item) => (
         <View key={item.label} style={styles.item}>
+          {item.color ? <View style={[styles.swatch, { backgroundColor: item.color }]} /> : null}
           <Metric
             value={item.value}
             format={item.format}
@@ -89,4 +105,11 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 6,
   },
+  // Matches `LegendItem`'s swatch, because the two annotate the same charts and
+  // a reader should not be able to tell which component drew the legend.
+  swatch: {
+    width: 8,
+    height: 8,
+    borderRadius: 2,
+  },
 });

package/src/theme.tsx

@@ -1,61 +1,24 @@
-import { createContext, useContext, type ReactNode } from "react";
+import { type ReactNode } from "react";
+import { LoticsThemeContext, type LoticsTheme } from "./theme_context";
 
-/**
- * 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 });
+export { DEFAULT_ACCENT, useLoticsTheme, THEME_VARS, type LoticsTheme } from "./theme_context";
 
-interface LoticsThemeProviderProps {
-  /** Brand accent. Overrides the platform default. Accepts any CSS color
-   * value (OKLCH recommended, hex / hsl also fine). */
-  accent?: string;
+interface LoticsThemeProviderProps extends LoticsTheme {
   children: ReactNode;
 }
 
 /**
- * App-root provider that supplies brand tokens to @lotics/ui primitives.
- * Wrap your top-level app element to override the platform defaults:
+ * App-root provider — the NATIVE half.
  *
- *     // src/main.tsx
- *     <LoticsThemeProvider accent="oklch(0.6 0.118 184.704)">
- *       <App />
- *     </LoticsThemeProvider>
+ * On native there are no CSS variables, and `colors` is a literal table, so
+ * there is nothing to declare: the provider publishes the values for anything
+ * that reads them through `useLoticsTheme()` and renders its children
+ * untouched. The web half (`theme.web.tsx`) is where a theme actually paints.
  *
- * 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.
+ * Deliberately NOT a `View`: a wrapper here would insert a layout box into every
+ * themed app's tree on the one platform that gains nothing from it.
  */
 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);
+  const { children, ...theme } = props;
+  return <LoticsThemeContext.Provider value={theme}>{children}</LoticsThemeContext.Provider>;
 }

package/src/theme.web.tsx

@@ -0,0 +1,64 @@
+import { useMemo, type CSSProperties, type ReactNode } from "react";
+import { LoticsThemeContext, THEME_VARS, type LoticsTheme } from "./theme_context";
+
+export { DEFAULT_ACCENT, useLoticsTheme, THEME_VARS, type LoticsTheme } from "./theme_context";
+
+interface LoticsThemeProviderProps extends LoticsTheme {
+  children: ReactNode;
+}
+
+/**
+ * App-root provider that gives `@lotics/ui` primitives this app's identity:
+ *
+ *     // src/main.tsx
+ *     <LoticsThemeProvider accent="#0F766E" border="#E3E8E6">
+ *       <App />
+ *     </LoticsThemeProvider>
+ *
+ * It declares the CSS custom properties `colors.web.ts` reads, so every kit
+ * component below re-paints without knowing the provider exists. That
+ * indirection is the point: the alternative — a context each primitive
+ * subscribes to — would have to be threaded through 136 modules and would turn
+ * their static stylesheets into per-render inline styles.
+ *
+ * **It renders a plain `div`, not a `View`, and that is load-bearing.**
+ * react-native-web's style compiler only emits properties it knows; a custom
+ * property handed to a `View` is silently DROPPED, so the variables never reach
+ * the DOM and a themed app renders in the platform defaults with no error
+ * anywhere. React DOM, by contrast, writes `--*` inline style keys through
+ * verbatim. The failure is invisible rather than loud, which is exactly why the
+ * two platforms get two files instead of one clever component.
+ *
+ * Only a role actually PASSED is declared, so an omitted one leaves its variable
+ * undefined and `colors.web.ts`'s inline fallback answers. That is what makes
+ * theming additive: a partial theme overrides a part, never resetting the rest
+ * to some second set of defaults.
+ */
+export function LoticsThemeProvider(props: LoticsThemeProviderProps) {
+  const { children, ...theme } = props;
+
+  // Keyed on the four values, not the object: the call site is normally an
+  // inline literal, which would otherwise rebuild this style — and re-render
+  // every kit surface under it — on each parent render.
+  const style = useMemo(() => {
+    const vars: Record<string, string> = {};
+    for (const [role, name] of Object.entries(THEME_VARS)) {
+      const value = theme[role as keyof LoticsTheme];
+      if (value !== undefined) vars[name] = value;
+    }
+    // `display: contents` — the provider generates NO box. Custom properties
+    // inherit down the DOM tree rather than the box tree, so the variables still
+    // reach every descendant while the element itself adds no layout at all.
+    // The first version was a flex column with `flex: 1`, which silently imposed
+    // a layout contract on every app that wrapped its root in this: a provider
+    // whose entire job is declaring three strings has no business deciding how its
+    // children stack.
+    return { display: "contents", ...vars } as CSSProperties;
+  }, [theme.accent, theme.background, theme.border]);
+
+  return (
+    <div style={style}>
+      <LoticsThemeContext.Provider value={theme}>{children}</LoticsThemeContext.Provider>
+    </div>
+  );
+}

package/src/theme_context.ts

@@ -0,0 +1,45 @@
+import { createContext, useContext } from "react";
+import { colors } from "./color_tokens";
+
+/**
+ * The platform's own accent — what every kit surface wears unthemed. Same value
+ * `colors.accent` falls back to; named so an app can reference the default
+ * explicitly instead of re-typing a literal.
+ */
+export const DEFAULT_ACCENT = colors.accent;
+
+/** The roles an app may own. See `color_tokens.ts` for why exactly these. */
+export interface LoticsTheme {
+  /** The one brand hue. It paints IDENTITY marks — today the avatar's initials
+   *  disc — and deliberately NOT the focus ring or the primary action, which stay
+   *  neutral so those read the same in every app. Never a status, a series or a
+   *  valence: those come from a palette family and carry meaning. */
+  accent?: string;
+  /** The surface Card, Drawer and Modal paint — 21 sites in the kit. Left white
+   *  on almost every app; set it only for a deliberately toned surface. */
+  background?: string;
+  /** Hairlines — 48 sites in the kit, and a register is mostly these lines, so a
+   *  small change here is felt across a whole screen. */
+  border?: string;
+}
+
+/**
+ * The CSS custom properties `colors.web.ts` reads. Part of the published
+ * contract: an app may set them from its own stylesheet instead of the provider.
+ */
+export const THEME_VARS: Record<keyof LoticsTheme, string> = {
+  accent: "--lotics-accent",
+  background: "--lotics-background",
+  border: "--lotics-border",
+};
+
+export const LoticsThemeContext = createContext<LoticsTheme>({});
+
+/**
+ * Read the current theme. An app SETS values through the provider's props; this
+ * is for a surface that must branch on one (a chart picking a fill). A role the
+ * app did not set reads `undefined` — ask `colors.<role>` for what will paint.
+ */
+export function useLoticsTheme(): LoticsTheme {
+  return useContext(LoticsThemeContext);
+}