Readable Text

1"use client";
2 
3import * as React from "react";
4import {
5  apcaContrast,
6  formatOklch,
7  glassSurface,
8  type OklchColor,
9  parseOklch,
10  READABLE_USAGE,
11  type ReadableUsage,
12  readableForeground,
13} from "@/lib/oklch-utils";
14 
15/**
16 * Readable foreground for a KNOWN surface color — pure and memoized (no DOM read, no observer), so it
17 * scales to hundreds of off-theme surfaces (e.g. colored tool-call bubbles) at negligible cost.
18 * Returns an oklch() string banded for `usage` (ARC Bronze; default "body"). For theme-surface text,
19 * prefer the CSS tokens (text-foreground / -soft / -strong) or <ReadableText>.
20 *
21 *   const fg = useReadableForeground({ l: 70, c: 0.18, h: 50 }, "ui"); // readable icon on orange
22 */
23export function useReadableForeground(surface: string | OklchColor, usage: ReadableUsage = "body"): string {
24  const css = typeof surface === "string" ? surface : formatOklch(surface);
25  return React.useMemo(() => {
26    const s = parseOklch(css);
27    return s
28      ? formatOklch(
29          readableForeground(s, {
30            usage,
31          }),
32        )
33      : "inherit";
34  }, [
35    css,
36    usage,
37  ]);
38}
39 
40const cssNum = (cs: CSSStyleDeclaration, name: string, fallback: number): number => {
41  const v = Number.parseFloat(cs.getPropertyValue(name));
42  return Number.isNaN(v) ? fallback : v;
43};
44 
45/**
46 * Dynamic APCA contrast guard. Renders its text in `accent` (a CSS custom-property name such as
47 * "--primary") *while that color stays readable* on the surface, otherwise a soft readable foreground
48 * via readableForeground — legible without the pure-black/white spike. The surface is the live glass
49 * (reactive to tint + light/dark) by default; pass `on` (an oklch string) to band against an arbitrary
50 * surface, e.g. an off-theme bubble. `usage` selects the ARC-Bronze band. Reuses lib/oklch-utils.
51 */
52export function ReadableText({
53  accent,
54  on,
55  usage,
56  minLc,
57  className,
58  children,
59}: {
60  /** CSS custom-property name to use when readable, e.g. "--primary". */
61  accent: string;
62  /** Surface to judge against — an oklch() string. Defaults to the live glass surface. */
63  on?: string;
64  /** ARC-Bronze band ("body" | "large" | "ui" | …) — sets the keep-accent floor + the soft fallback. */
65  usage?: ReadableUsage;
66  /** Minimum |APCA Lc| to keep the accent. Defaults to the usage floor, else 45. */
67  minLc?: number;
68  className?: string;
69  children: React.ReactNode;
70}) {
71  const [color, setColor] = React.useState<string>();
72 
73// … truncated