react-native-terra-ui 0.7.2 → 0.8.0

package/src/utils/color-utils.ts

@@ -1,12 +1,34 @@
-/** Small color helpers for deriving accent shades from a single hue. */
+/**
+ * Colour helpers shared by the accent generator, the contrast diagnostics and
+ * the public `shade` / `withAlpha` / `readableOn` utilities.
+ *
+ * Everything here is pure sRGB maths with no runtime dependency:
+ * - parsing of `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`,
+ * - WCAG 2.x relative luminance / contrast with sRGB alpha compositing,
+ * - OKLab / OKLCH conversions (Björn Ottosson's published matrices) with
+ *   sRGB gamut mapping by chroma reduction at constant lightness and hue.
+ */
 
-interface RGB {
+export interface RGB {
   r: number;
   g: number;
   b: number;
 }
 
-const clamp = (n: number): number => Math.max(0, Math.min(255, Math.round(n)));
+/** A parsed sRGB colour with 0-255 channels and a 0-1 alpha. */
+export interface RGBA extends RGB {
+  a: number;
+}
+
+/** OKLCH coordinates: L in [0, 1], C ≥ 0, h in degrees [0, 360). */
+export interface OKLCH {
+  l: number;
+  c: number;
+  h: number;
+}
+
+const clamp255 = (n: number): number => Math.max(0, Math.min(255, Math.round(n)));
+const clamp01 = (n: number): number => Math.max(0, Math.min(1, n));
 
 function parseHex(hex: string): RGB | null {
   const hex6 = /^#?([0-9a-f]{6})$/i.exec(hex.trim())?.[1];
@@ -16,7 +38,201 @@ function parseHex(hex: string): RGB | null {
 }
 
 const toHex = ({ r, g, b }: RGB): string =>
-  `#${[r, g, b].map((v) => clamp(v).toString(16).padStart(2, "0")).join("")}`;
+  `#${[r, g, b].map((v) => clamp255(v).toString(16).padStart(2, "0")).join("")}`;
+
+/** Formats 0-255 channels as a lowercase `#rrggbb` string (channels are rounded and clamped). */
+export function rgbToHex(rgb: RGB): string {
+  return toHex(rgb);
+}
+
+/**
+ * Parses an sRGB colour string. Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ * (case-insensitive) and `rgb(r, g, b)` / `rgba(r, g, b, a)` with integer or
+ * percentage channels. Returns `null` for anything else (named colours,
+ * `transparent`, hsl(), gradients, platform dynamic colours, ...).
+ */
+export function parseColor(value: unknown): RGBA | null {
+  if (typeof value !== "string") return null;
+  const input = value.trim();
+
+  const hex = /^#([0-9a-f]{3,8})$/i.exec(input)?.[1];
+  if (hex !== undefined) {
+    if (hex.length === 3 || hex.length === 4) {
+      const [r, g, b, a] = [...hex].map((ch) => Number.parseInt(ch + ch, 16));
+      return { r: r ?? 0, g: g ?? 0, b: b ?? 0, a: hex.length === 4 ? (a ?? 255) / 255 : 1 };
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const channels = [0, 2, 4, 6]
+        .filter((start) => start < hex.length)
+        .map((start) => Number.parseInt(hex.slice(start, start + 2), 16));
+      const [r, g, b, a] = channels;
+      return { r: r ?? 0, g: g ?? 0, b: b ?? 0, a: hex.length === 8 ? (a ?? 255) / 255 : 1 };
+    }
+    return null;
+  }
+
+  const fn = /^rgba?\(\s*([^)]*)\)$/i.exec(input)?.[1];
+  if (fn !== undefined) {
+    const parts = fn.split(/\s*[,/]\s*|\s+/).filter((part) => part.length > 0);
+    if (parts.length !== 3 && parts.length !== 4) return null;
+    const channel = (part: string): number | null => {
+      const percent = part.endsWith("%");
+      const n = Number(percent ? part.slice(0, -1) : part);
+      if (!Number.isFinite(n)) return null;
+      return clamp255(percent ? (n / 100) * 255 : n);
+    };
+    const alpha = (part: string | undefined): number | null => {
+      if (part === undefined) return 1;
+      const percent = part.endsWith("%");
+      const n = Number(percent ? part.slice(0, -1) : part);
+      if (!Number.isFinite(n)) return null;
+      return clamp01(percent ? n / 100 : n);
+    };
+    const r = channel(parts[0] as string);
+    const g = channel(parts[1] as string);
+    const b = channel(parts[2] as string);
+    const a = alpha(parts[3]);
+    if (r === null || g === null || b === null || a === null) return null;
+    return { r, g, b, a };
+  }
+
+  return null;
+}
+
+/** Source-over compositing of `front` at `alpha` onto an opaque `back`, in gamma-encoded sRGB. */
+export function compositeOver(front: RGB, back: RGB, alpha: number): RGB {
+  const a = clamp01(alpha);
+  return {
+    r: front.r * a + back.r * (1 - a),
+    g: front.g * a + back.g * (1 - a),
+    b: front.b * a + back.b * (1 - a),
+  };
+}
+
+const linearizeChannel = (channel: number): number => {
+  const srgb = channel / 255;
+  return srgb <= 0.04045 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
+};
+
+const delinearizeChannel = (linear: number): number => {
+  const v = Math.max(0, Math.min(1, linear));
+  return (v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055) * 255;
+};
+
+/** WCAG 2.x relative luminance of an opaque sRGB colour (0-255 channels). */
+export function relativeLuminance(rgb: RGB): number {
+  return (
+    0.2126 * linearizeChannel(rgb.r) + 0.7152 * linearizeChannel(rgb.g) + 0.0722 * linearizeChannel(rgb.b)
+  );
+}
+
+/** WCAG 2.x contrast ratio between two opaque sRGB colours (≥ 1). */
+export function contrastRatio(a: RGB, b: RGB): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * Contrast of a foreground on a background, both composited over an opaque
+ * `surface`, with `opacity` applied to the whole control afterwards (the way a
+ * pressed Button or Toast action fades as one unit). Matches the reference
+ * calculation in `theme/__tests__/color-contrast.test.ts`.
+ */
+export function compositedContrast(fg: RGBA, bg: RGBA, surface: RGB, opacity = 1): number {
+  const background = compositeOver(bg, surface, bg.a);
+  const foreground = compositeOver(fg, background, fg.a);
+  return contrastRatio(
+    compositeOver(foreground, surface, opacity),
+    compositeOver(background, surface, opacity)
+  );
+}
+
+// ─── OKLab / OKLCH ────────────────────────────────────────────────────────────
+// Matrices from https://bottosson.github.io/posts/oklab/ (sRGB D65).
+
+const cbrt = (x: number): number => (x < 0 ? -((-x) ** (1 / 3)) : x ** (1 / 3));
+
+function linearSrgbToOklab(r: number, g: number, b: number): [number, number, number] {
+  const l = cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+function oklabToLinearSrgb(L: number, a: number, b: number): [number, number, number] {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+/** Converts 0-255 sRGB channels to OKLCH. Achromatic input yields `c ≈ 0` and `h = 0`. */
+export function rgbToOklch(rgb: RGB): OKLCH {
+  const [L, a, b] = linearSrgbToOklab(
+    linearizeChannel(rgb.r),
+    linearizeChannel(rgb.g),
+    linearizeChannel(rgb.b)
+  );
+  const c = Math.hypot(a, b);
+  if (c < 1e-4) return { l: clamp01(L), c: 0, h: 0 };
+  const h = (Math.atan2(b, a) * 180) / Math.PI;
+  return { l: clamp01(L), c, h: h < 0 ? h + 360 : h };
+}
+
+function oklchToLinear({ l, c, h }: OKLCH): [number, number, number] {
+  const rad = (h * Math.PI) / 180;
+  return oklabToLinearSrgb(l, c * Math.cos(rad), c * Math.sin(rad));
+}
+
+const GAMUT_EPSILON = 1e-4;
+
+const inGamut = (linear: readonly number[]): boolean =>
+  linear.every((v) => v >= -GAMUT_EPSILON && v <= 1 + GAMUT_EPSILON);
+
+/**
+ * Converts OKLCH to 0-255 sRGB channels. Colours outside the sRGB gamut are
+ * mapped by reducing chroma at constant lightness and hue (binary search)
+ * until they fit, so the requested lightness — what the contrast targets
+ * depend on — is preserved as closely as the gamut allows.
+ */
+export function oklchToRgb(color: OKLCH): RGB {
+  const l = clamp01(color.l);
+  const h = ((color.h % 360) + 360) % 360;
+  let c = Math.max(0, color.c);
+  let linear = oklchToLinear({ l, c, h });
+  if (!inGamut(linear)) {
+    let lo = 0;
+    let hi = c;
+    for (let i = 0; i < 24; i += 1) {
+      const mid = (lo + hi) / 2;
+      if (inGamut(oklchToLinear({ l, c: mid, h }))) lo = mid;
+      else hi = mid;
+    }
+    c = lo;
+    linear = oklchToLinear({ l, c, h });
+  }
+  return {
+    r: delinearizeChannel(linear[0]),
+    g: delinearizeChannel(linear[1]),
+    b: delinearizeChannel(linear[2]),
+  };
+}
+
+/** `oklchToRgb` followed by `rgbToHex`. */
+export function oklchToHex(color: OKLCH): string {
+  return toHex(oklchToRgb(color));
+}
+
+// ─── Public shade / alpha / readable helpers (unchanged behaviour) ────────────
 
 /**
  * Shifts a hex color toward black (negative `amount`) or white (positive),
@@ -41,11 +257,12 @@ export function withAlpha(hex: string, alpha: number): string {
   return `rgba(${c.r}, ${c.g}, ${c.b}, ${alpha})`;
 }
 
-/** Picks black or white for legible text/icons on top of `hex`. */
+/** Picks the higher-contrast black/white foreground for an opaque 6-digit hex. */
 export function readableOn(hex: string): string {
   const c = parseHex(hex);
   if (!c) return "#ffffff";
-  // Perceived luminance (0–1).
-  const luminance = (0.299 * c.r + 0.587 * c.g + 0.114 * c.b) / 255;
-  return luminance > 0.6 ? "#000000" : "#ffffff";
+  const luminance = relativeLuminance(c);
+  const blackContrast = (luminance + 0.05) / 0.05;
+  const whiteContrast = 1.05 / (luminance + 0.05);
+  return blackContrast >= whiteContrast ? "#000000" : "#ffffff";
 }

package/src/utils/deep-merge.ts

@@ -5,7 +5,7 @@ export type DeepPartial<T> = T extends (infer U)[]
     ? { [K in keyof T]?: DeepPartial<T[K]> }
     : T;
 
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+export const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" &&
   value !== null &&
   !Array.isArray(value) &&

package/src/utils/resolve-theme-color.ts

@@ -12,8 +12,8 @@ const isColorLiteral = (value: string): boolean =>
  * Raw literals pass through unchanged.
  *
  * @example
- * resolveThemeColor('text.default', theme)         // → '#020618'
- * resolveThemeColor('action.bg.primary', theme)    // → '#009966'
+ * resolveThemeColor('text.primary', theme)         // → '#020618'
+ * resolveThemeColor('accent.solid.bg', theme)    // → '#009966'
  * resolveThemeColor('#ff0000', theme)              // → '#ff0000'
  */
 export function resolveThemeColor(token: ColorToken | undefined, theme: TerraTheme): string | undefined {

package/lib/module/components/screen/parts/BottomSafeArea.js

@@ -1,62 +0,0 @@
-"use strict";
-
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * `SafeAreaView` is not re-exported from the `react-native-screens` root, so it
- * has to be reached by path — and it has to be the TypeScript source entry, the
- * one the package points React Native at. The built `lib/module` copy of the
- * native component never went through React Native's codegen, so loading it
- * fails at bundle time with "Could not find component config for native
- * component".
- *
- * `require` rather than `import` so the dependency's own `.tsx` is not pulled
- * into this package's build, where it trips compiler options it was never
- * written against.
- */
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const {
-  SafeAreaView
-} = require("react-native-screens/src/components/safe-area");
-const BOTTOM_EDGE = {
-  bottom: true
-};
-const SPACER = {
-  flex: 0
-};
-
-/**
- * Bottom clearance that measures itself.
- *
- * The insets Unistyles reports are the window's, which cover the system bars and
- * nothing else — 24dp for the gesture bar on a Pixel — while a native tab bar
- * sits on top of them for another 80dp and overlaps the content beneath it.
- * `react-native-screens` tracks that second one separately, as an *interface*
- * inset, and reports it to its own `SafeAreaView`; asking a view is the only way
- * to learn it. Neither `runtime.insets.bottom` nor `useSafeAreaInsets()` knows
- * about it — both read 24 on a tab screen — and a constant would be wrong the
- * moment the bar is absent, which is every pushed screen.
- *
- * `insetType="all"` covers system and interface both, so this view owns the
- * whole bottom edge — which is why the scroll containers pad only their margin;
- * adding the window inset there too would double-count the gesture bar.
- * `"interface"` alone would be wrong: it measures the same on a tab screen (the
- * bar's inset already spans the gesture bar beneath it) but reports nothing on a
- * pushed screen, which would then lose its gesture-bar clearance.
- *
- * `insetType` is Android-only; on iOS the bottom safe area of a view inside a
- * tab controller already includes the bar. Measured on a tab screen: 132dp on a
- * Pixel, 95pt on an iPhone 17 — against the 24dp / 34pt the window insets
- * report, which is the gap this closes.
- *
- * `flex: 0` cancels the `flex: 1` that `SafeAreaView` sets on itself, which
- * would otherwise stretch it into the leftover space of a list shorter than the
- * viewport. With no children, its height is exactly the padding it applies.
- */
-export function BottomSafeArea() {
-  return /*#__PURE__*/_jsx(SafeAreaView, {
-    edges: BOTTOM_EDGE,
-    insetType: "all",
-    style: SPACER
-  });
-}
-//# sourceMappingURL=BottomSafeArea.js.map

package/lib/module/components/screen/parts/BottomSafeArea.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["SafeAreaView","require","BOTTOM_EDGE","bottom","SPACER","flex","BottomSafeArea","_jsx","edges","insetType","style"],"sourceRoot":"../../../../../src","sources":["components/screen/parts/BottomSafeArea.tsx"],"mappings":";;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAM;EAAEA;AAAa,CAAC,GAAGC,OAAO,CAAC,+CAA+C,CAE/E;AAED,MAAMC,WAAW,GAAG;EAAEC,MAAM,EAAE;AAAK,CAAU;AAC7C,MAAMC,MAAM,GAAG;EAAEC,IAAI,EAAE;AAAE,CAAU;;AAEnC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAG;EAC/B,oBAAOC,IAAA,CAACP,YAAY;IAACQ,KAAK,EAAEN,WAAY;IAACO,SAAS,EAAC,KAAK;IAACC,KAAK,EAAEN;EAAO,CAAE,CAAC;AAC5E","ignoreList":[]}

package/lib/typescript/src/components/screen/parts/BottomSafeArea.d.ts

@@ -1,30 +0,0 @@
-/**
- * Bottom clearance that measures itself.
- *
- * The insets Unistyles reports are the window's, which cover the system bars and
- * nothing else — 24dp for the gesture bar on a Pixel — while a native tab bar
- * sits on top of them for another 80dp and overlaps the content beneath it.
- * `react-native-screens` tracks that second one separately, as an *interface*
- * inset, and reports it to its own `SafeAreaView`; asking a view is the only way
- * to learn it. Neither `runtime.insets.bottom` nor `useSafeAreaInsets()` knows
- * about it — both read 24 on a tab screen — and a constant would be wrong the
- * moment the bar is absent, which is every pushed screen.
- *
- * `insetType="all"` covers system and interface both, so this view owns the
- * whole bottom edge — which is why the scroll containers pad only their margin;
- * adding the window inset there too would double-count the gesture bar.
- * `"interface"` alone would be wrong: it measures the same on a tab screen (the
- * bar's inset already spans the gesture bar beneath it) but reports nothing on a
- * pushed screen, which would then lose its gesture-bar clearance.
- *
- * `insetType` is Android-only; on iOS the bottom safe area of a view inside a
- * tab controller already includes the bar. Measured on a tab screen: 132dp on a
- * Pixel, 95pt on an iPhone 17 — against the 24dp / 34pt the window insets
- * report, which is the gap this closes.
- *
- * `flex: 0` cancels the `flex: 1` that `SafeAreaView` sets on itself, which
- * would otherwise stretch it into the leftover space of a list shorter than the
- * viewport. With no children, its height is exactly the padding it applies.
- */
-export declare function BottomSafeArea(): import("react").JSX.Element;
-//# sourceMappingURL=BottomSafeArea.d.ts.map

package/lib/typescript/src/components/screen/parts/BottomSafeArea.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BottomSafeArea.d.ts","sourceRoot":"","sources":["../../../../../../src/components/screen/parts/BottomSafeArea.tsx"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,gCAE7B"}

package/src/components/screen/parts/BottomSafeArea.tsx

@@ -1,59 +0,0 @@
-import type { ComponentType } from "react";
-
-type SafeAreaViewProps = {
-  edges: { readonly bottom: true };
-  insetType: "all";
-  style: { readonly flex: 0 };
-};
-
-/**
- * `SafeAreaView` is not re-exported from the `react-native-screens` root, so it
- * has to be reached by path — and it has to be the TypeScript source entry, the
- * one the package points React Native at. The built `lib/module` copy of the
- * native component never went through React Native's codegen, so loading it
- * fails at bundle time with "Could not find component config for native
- * component".
- *
- * `require` rather than `import` so the dependency's own `.tsx` is not pulled
- * into this package's build, where it trips compiler options it was never
- * written against.
- */
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { SafeAreaView } = require("react-native-screens/src/components/safe-area") as {
-  SafeAreaView: ComponentType<SafeAreaViewProps>;
-};
-
-const BOTTOM_EDGE = { bottom: true } as const;
-const SPACER = { flex: 0 } as const;
-
-/**
- * Bottom clearance that measures itself.
- *
- * The insets Unistyles reports are the window's, which cover the system bars and
- * nothing else — 24dp for the gesture bar on a Pixel — while a native tab bar
- * sits on top of them for another 80dp and overlaps the content beneath it.
- * `react-native-screens` tracks that second one separately, as an *interface*
- * inset, and reports it to its own `SafeAreaView`; asking a view is the only way
- * to learn it. Neither `runtime.insets.bottom` nor `useSafeAreaInsets()` knows
- * about it — both read 24 on a tab screen — and a constant would be wrong the
- * moment the bar is absent, which is every pushed screen.
- *
- * `insetType="all"` covers system and interface both, so this view owns the
- * whole bottom edge — which is why the scroll containers pad only their margin;
- * adding the window inset there too would double-count the gesture bar.
- * `"interface"` alone would be wrong: it measures the same on a tab screen (the
- * bar's inset already spans the gesture bar beneath it) but reports nothing on a
- * pushed screen, which would then lose its gesture-bar clearance.
- *
- * `insetType` is Android-only; on iOS the bottom safe area of a view inside a
- * tab controller already includes the bar. Measured on a tab screen: 132dp on a
- * Pixel, 95pt on an iPhone 17 — against the 24dp / 34pt the window insets
- * report, which is the gap this closes.
- *
- * `flex: 0` cancels the `flex: 1` that `SafeAreaView` sets on itself, which
- * would otherwise stretch it into the leftover space of a list shorter than the
- * viewport. With no children, its height is exactly the padding it applies.
- */
-export function BottomSafeArea() {
-  return <SafeAreaView edges={BOTTOM_EDGE} insetType="all" style={SPACER} />;
-}