@lotics/ui 43.4.0 → 43.5.0

package/src/theme.web.ts

@@ -0,0 +1,49 @@
+import { themeDeclarations, type LoticsTheme } from "./theme_vars";
+
+export { THEME_VARS, deriveAccentWash, type LoticsTheme } from "./theme_vars";
+
+/**
+ * Give this app its own identity — call ONCE at boot, before `mount`.
+ *
+ * ```ts
+ * applyLoticsTheme({ primary: "#0F766E", bodyFont: "'Be Vietnam Pro', sans-serif" });
+ * ```
+ *
+ * THE ESCAPE HATCH, and deliberately shaped like one. Theming is not a product
+ * surface: nothing in the platform writes a theme, there is no settings screen
+ * for it, and `apps.theme.color` is the launcher icon's colour and nothing else.
+ * This exists because an app occasionally needs its own typeface or brand, and
+ * the alternative — passing `style` at every call site — is a fork rather than a
+ * theme.
+ *
+ * Every kit surface follows, because `colors.web.ts` reads each role through a
+ * CSS variable with the kit's own value as the inline fallback. Setting one role
+ * overrides that role and nothing else.
+ *
+ * THE DOCUMENT ROOT, which is the point rather than an implementation detail. A
+ * custom property inherits down the DOM tree, and `Modal` (react-native-web)
+ * mounts its content into `document.body` — so a theme scoped to a React subtree
+ * reaches the register and not the `Drawer` opened from it. Nothing errors; the
+ * two halves of the app simply disagree, and the seam is visible only with both
+ * on screen at once.
+ *
+ * Called BEFORE `mount`, the variables are in place for the first paint, so no
+ * frame renders in the kit's defaults first.
+ *
+ * Idempotent — call it again with different values and the app re-themes, which
+ * is what a tenant switch or a live preview needs. There is nothing to unwind,
+ * which is why this is a function rather than a component: the provider it
+ * replaces spent a memo, a wrapper element, a layout effect and a
+ * restore-on-unmount serving a React lifecycle that an app setting one identity
+ * at boot never had.
+ *
+ * A no-op where there is no document (SSR, a test without jsdom), so a call at
+ * module scope is safe.
+ */
+export function applyLoticsTheme(theme: LoticsTheme): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  for (const [name, value] of Object.entries(themeDeclarations(theme))) {
+    root.style.setProperty(name, value);
+  }
+}

package/src/theme_vars.ts

@@ -0,0 +1,113 @@
+/**
+ * THE THEME CONTRACT — the roles an app may own, and the CSS custom properties
+ * they resolve through.
+ *
+ * This is data, not machinery. `colors.web.ts` reads each variable with an
+ * inline fallback, so a role nobody sets answers with the kit's own value —
+ * which is what makes a theme ADDITIVE: setting one role overrides that role and
+ * nothing else.
+ *
+ * The variables are part of the published contract, so an app CAN declare them
+ * in its own stylesheet. Prefer `applyLoticsTheme`, which gets the two derived
+ * values right — see `deriveAccentWash` and the font fan-out below.
+ */
+
+/** The roles an app may own. See `color_tokens.ts` for why exactly these. */
+export interface LoticsTheme {
+  /** The one brand hue. It marks WHICH OF THESE — a selected row, an active
+   *  filter — never a status, a series or a valence, which come from a palette
+   *  family and carry meaning. */
+  accent?: string;
+  /** The surface Card, Drawer and Modal paint. Left white on almost every app;
+   *  set it only for a deliberately toned surface. */
+  background?: string;
+  /** Hairlines. A register is mostly these lines, so a small change here is felt
+   *  against a whole screen. */
+  border?: string;
+  /**
+   * THE TYPEFACE, for everything. One value — a CSS font stack — and the whole
+   * app follows it, because it fans out to the three weight rungs
+   * (`font_family.ts`): weight is a FAMILY in this kit, not a `font-weight`.
+   *
+   * Pass a stack you know RESOLVES — a face nobody `@font-face`d falls silently
+   * through to system sans, which is the one failure here that looks like
+   * nothing happening. And check Vietnamese: a face without the diacritics turns
+   * "Thẩm định" into tofu. The kit's letter-spacing curve is tuned for Inter's
+   * glyphs, so another face inherits tracking chosen for a different drawing —
+   * a refinement to check, not a blocker.
+   */
+  bodyFont?: string;
+  /**
+   * The typeface for DISPLAY text only — what `<Text family="display">` renders
+   * in. Defaults to `bodyFont` when that is set, so ONE parameter changes the
+   * whole app and a second is needed only to make display type differ from body.
+   */
+  displayFont?: string;
+  /** The ink that ACTS — the primary button's fill, a checkbox's fill, a
+   *  switch's track, an active tab's rail. Defaults to the kit's near-black. */
+  primary?: string;
+}
+
+/** Role → the CSS custom property `colors.web.ts` reads for it. */
+export const THEME_VARS: Record<keyof LoticsTheme, string> = {
+  accent: "--lotics-accent",
+  background: "--lotics-background",
+  border: "--lotics-border",
+  primary: "--lotics-primary",
+  bodyFont: "--lotics-font-regular",
+  displayFont: "--lotics-display-font",
+};
+
+/** The extra variable that is DERIVED — not a role an app sets, because it is
+ *  the accent seen through alpha and two sources for one colour drift. */
+export const ACCENT_WASH_VAR = "--lotics-accent-wash";
+
+/** The two rungs `bodyFont` fans out to beyond its own `THEME_VARS` entry. */
+export const FONT_MEDIUM_VAR = "--lotics-font-medium";
+export const FONT_SEMIBOLD_VAR = "--lotics-font-semibold";
+
+/**
+ * The accent at wash strength.
+ *
+ * Computed from the literal hex the app passed, because it CANNOT be computed
+ * downstream: on web the token is a `var()`, and the kit's alpha helpers parse
+ * `rgba()` strings. Returns undefined for a value it cannot parse (a named
+ * colour, an `oklch()`), so an unparseable accent falls back to the neutral wash
+ * rather than painting rows in garbage.
+ */
+export function deriveAccentWash(accent: string): string | undefined {
+  const m = /^#([0-9a-f]{6})$/i.exec(accent.trim());
+  if (!m) return undefined;
+  const n = parseInt(m[1], 16);
+  // 0.07 — heavy enough to read as a tint on white, light enough that body text
+  // on top keeps its contrast; the neutral it replaces (zinc-100) sits about here.
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, 0.07)`;
+}
+
+/**
+ * The theme as CSS declarations — the role variables plus the two things an app
+ * writing raw CSS has to remember and usually will not.
+ *
+ * Shared by both platforms' `applyLoticsTheme` so the mapping has one
+ * definition; only a role actually PASSED appears.
+ */
+export function themeDeclarations(theme: LoticsTheme): Record<string, string> {
+  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;
+  }
+  if (theme.accent !== undefined) {
+    const wash = deriveAccentWash(theme.accent);
+    if (wash !== undefined) vars[ACCENT_WASH_VAR] = wash;
+  }
+  // ONE font value, THREE rungs. `THEME_VARS` maps `bodyFont` to the regular
+  // rung; medium and semibold follow it here, because a family set on only one
+  // rung leaves every medium and semibold run in Inter — the screen comes out in
+  // two typefaces and reads as a font that half-loaded.
+  if (theme.bodyFont !== undefined) {
+    vars[FONT_MEDIUM_VAR] = theme.bodyFont;
+    vars[FONT_SEMIBOLD_VAR] = theme.bodyFont;
+  }
+  return vars;
+}

package/src/type_ramp.ts

@@ -0,0 +1,100 @@
+/**
+ * THE TYPE RAMP — the one place the two curves are written down.
+ *
+ * `Text` renders through two entirely different mechanisms: on web the size is a
+ * `data-text-size` attribute matched by `text.css`, on native it is a
+ * `StyleSheet` entry. Those were two hand-maintained tables, and they drifted
+ * exactly as far as you would expect — by the time this file was written native
+ * disagreed with web on the leading of three rungs and on the tracking of all
+ * seven, because every typographic change since had been made on the web side
+ * only. The mobile app was running a ramp nobody had looked at.
+ *
+ * So the ramp is DATA here, and both consumers derive from it. `text.tsx` builds
+ * its native sheet from these numbers, so no second native table exists to drift.
+ * `text.css` cannot read TypeScript and stays hand-written — it needs the media
+ * query and it carries the reasoning a reader needs — so `type_ramp.test.ts`
+ * parses it and fails when a value disagrees with this table. Eliminate the
+ * duplication where you can; test it where you cannot.
+ *
+ * LEADING: the body rungs carry PROSE leading — 14/24, ratio 1.71, exactly what
+ * `.ui-markdown` uses. The ladder tightens as it rises, which is the convention:
+ * large type needs proportionally less leading, so the display rungs sit near
+ * 1.2 and only the rungs carrying running text are generous. The cost is real
+ * and deliberate — line-height sets the BOX height of even a single line, so
+ * every label, value and control gained about 4px of line box. Density was
+ * traded for rhythm.
+ *
+ * TRACKING: negative throughout, steepening as the type grows. The body rung is
+ * ANCHORED on -0.028em — the -0.4px this product already set on `.ui-markdown`
+ * and on its inputs, expressed as an em so it scales. That value is the
+ * product's own, arrived at by reading it in Vietnamese every day, and the rest
+ * of the ramp is derived FROM it rather than imported from another design
+ * system. Inter is drawn generously at default tracking, so untracked body reads
+ * loose beside it, and what looks right at 14px looks slack at 32px.
+ *
+ * `xs` is the one rung held back (-0.02em rather than the full body value). 12px
+ * is where Vietnamese stacked diacritics (ự, ộ, ế, ệ) and Inter's `1`/`l`/`i`
+ * come closest to colliding, and tightening is the direction that makes both
+ * worse.
+ *
+ * Tracking is stated ONCE, in em, and is not repeated per breakpoint: an em
+ * scales with the font size, so the same value is correct at both. Only the
+ * sizes and their leading differ across the breakpoint.
+ */
+
+/** A rung's box, in px. */
+export interface TypeRung {
+  size: number;
+  leading: number;
+}
+
+/**
+ * The ramp below 768px — and the ramp NATIVE uses, because a phone is a phone.
+ * The display rungs are the ones that grow on a desktop; body sits still.
+ */
+export const TYPE_RAMP_MOBILE = {
+  xs: { size: 12, leading: 18 },
+  sm: { size: 14, leading: 24 },
+  md: { size: 16, leading: 26 },
+  lg: { size: 18, leading: 28 },
+  // Display ramp — the heading ladder: xl = `##` (section), xxl = `#`
+  // (page/record title), xxxl = hero numbers.
+  xl: { size: 22, leading: 28 },
+  xxl: { size: 28, leading: 34 },
+  xxxl: { size: 32, leading: 38 },
+} as const satisfies Record<string, TypeRung>;
+
+/** The ramp at 768px and above. Breakpoint per `use_screen_size`. */
+export const TYPE_RAMP_DESKTOP = {
+  xs: { size: 12, leading: 18 },
+  sm: { size: 14, leading: 24 },
+  md: { size: 16, leading: 26 },
+  lg: { size: 20, leading: 30 },
+  xl: { size: 24, leading: 32 },
+  xxl: { size: 32, leading: 44 },
+  xxxl: { size: 48, leading: 52 },
+} as const satisfies Record<keyof typeof TYPE_RAMP_MOBILE, TypeRung>;
+
+/** Tracking per rung, in em. Negative at every rung — see the header. */
+export const TYPE_TRACKING = {
+  xs: -0.02,
+  sm: -0.028,
+  md: -0.03,
+  lg: -0.032,
+  xl: -0.035,
+  xxl: -0.038,
+  xxxl: -0.04,
+} as const satisfies Record<keyof typeof TYPE_RAMP_MOBILE, number>;
+
+/** The rungs, in ladder order. `TextSize` in `text.tsx` is this set. */
+export type TypeRungName = keyof typeof TYPE_RAMP_MOBILE;
+
+/**
+ * The em tracking of a rung as px at a given size — what React Native needs,
+ * since `letterSpacing` there has no em unit and is a flat point value.
+ * Rounded to a thousandth so the number stays readable in a snapshot; the
+ * difference that discards is four orders of magnitude below a pixel.
+ */
+export function trackingPx(rung: TypeRungName, size: number): number {
+  return Math.round(size * TYPE_TRACKING[rung] * 1000) / 1000;
+}

package/src/theme.tsx

@@ -1,24 +0,0 @@
-import { type ReactNode } from "react";
-import { LoticsThemeContext, 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 — the NATIVE half.
- *
- * 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.
- *
- * 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 { children, ...theme } = props;
-  return <LoticsThemeContext.Provider value={theme}>{children}</LoticsThemeContext.Provider>;
-}

package/src/theme.web.tsx

@@ -1,79 +0,0 @@
-import { useMemo, type CSSProperties, type ReactNode } from "react";
-import { ACCENT_WASH_VAR, deriveAccentWash, FONT_MEDIUM_VAR, FONT_SEMIBOLD_VAR, 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;
-    }
-    // The wash is DERIVED here, where the accent is still a literal — see
-    // `deriveAccentWash`. An accent the parser cannot read leaves it undefined,
-    // so those surfaces keep the neutral default instead of breaking.
-    if (theme.accent !== undefined) {
-      const wash = deriveAccentWash(theme.accent);
-      if (wash !== undefined) vars[ACCENT_WASH_VAR] = wash;
-    }
-    // ONE font value, THREE rungs. `THEME_VARS` already mapped `bodyFont` to the
-    // regular rung; medium and semibold follow it here, because a family set on
-    // only one rung would leave every medium and semibold run in Inter — the
-    // screen would come out in two typefaces and look like a loading bug.
-    if (theme.bodyFont !== undefined) {
-      vars[FONT_MEDIUM_VAR] = theme.bodyFont;
-      vars[FONT_SEMIBOLD_VAR] = theme.bodyFont;
-    }
-    // `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

@@ -1,107 +0,0 @@
-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 against a whole screen. */
-  border?: string;
-  /**
-   * THE TYPEFACE, for everything. One value — a CSS font stack — and the whole
-   * app follows it.
-   *
-   * It fans out to the three weight rungs (`font_family.ts`), because weight is
-   * a FAMILY in this kit rather than a `font-weight`. Themed, all three resolve
-   * to this family and the numeric weight already on every style makes the
-   * ladder; unthemed, each keeps its own Inter face.
-   *
-   * Pass a stack you know RESOLVES — a face nobody `@font-face`d falls silently
-   * through to system sans, which is the one failure here that looks like
-   * nothing happening. And check Vietnamese: a face without the diacritics turns
-   * "Thẩm định" into tofu.
-   *
-   * The kit's letter-spacing curve is tuned for Inter's glyphs, so another face
-   * inherits tracking chosen for a different drawing. It is a refinement, not a
-   * defect — worth an eye, not a blocker.
-   */
-  bodyFont?: string;
-  /**
-   * The typeface for DISPLAY text only — what `<Text family="display">` renders
-   * in. A headline, a wordmark, a figure the page exists to show.
-   *
-   * Defaults to `bodyFont` when that is set, so ONE parameter changes the whole
-   * app and a SECOND one is only needed to make display type differ from body —
-   * a serif masthead over a sans register, say.
-   */
-  displayFont?: string;
-  /** The PRIMARY action's fill. Defaults to the kit's near-black, so an app that
-   *  themes nothing is unchanged; set it to put the brand on the one filled
-   *  button a surface gets. Distinct from `accent`, which marks identity. */
-  primary?: 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",
-  primary: "--lotics-primary",
-  bodyFont: "--lotics-font-regular",
-  displayFont: "--lotics-display-font",
-};
-
-/** The extra variable the provider DERIVES — not a role an app sets, because it
- *  is the accent seen through alpha and two sources for one colour drift. */
-export const ACCENT_WASH_VAR = "--lotics-accent-wash";
-
-/** The two rungs `bodyFont` fans out to beyond its own `THEME_VARS` entry. */
-export const FONT_MEDIUM_VAR = "--lotics-font-medium";
-export const FONT_SEMIBOLD_VAR = "--lotics-font-semibold";
-
-/**
- * The accent at wash strength.
- *
- * Computed from the literal hex the app passed, because it CANNOT be computed
- * downstream: on web the token is a `var()`, and the kit's alpha helpers parse
- * `rgba()` strings. Returns undefined for a value it cannot parse (a named
- * colour, an `oklch()`), so an unparseable accent falls back to the neutral wash
- * rather than painting rows in garbage.
- */
-export function deriveAccentWash(accent: string): string | undefined {
-  const hex = accent.trim();
-  const m = /^#([0-9a-f]{6})$/i.exec(hex);
-  if (!m) return undefined;
-  const n = parseInt(m[1], 16);
-  // 0.07 — heavy enough to read as a tint on white, light enough that body text
-  // on top keeps its contrast; the neutral it replaces (zinc-100) sits about here.
-  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, 0.07)`;
-}
-
-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);
-}