@lotics/ui 42.0.0 → 42.3.0

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