@oxyhq/bloom 0.87.1 → 0.88.0

package/src/__tests__/design-tokens-json.test.ts

@@ -0,0 +1,112 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  bloomDesignTokens,
+  renderBloomTokensJson,
+  resolvedColorToHex,
+  type PresetGroup,
+} from '../design-tokens/tokens-json';
+import { APP_COLOR_NAMES, APP_COLOR_PRESETS } from '../theme/color-presets';
+import { CANONICAL_TOKENS, getResolvedTokens } from '../theme/token-registry';
+
+const TOKENS_PATH = join(__dirname, '..', 'design-tokens', 'tokens.json');
+
+describe('the shipped tokens.json is generated, not maintained', () => {
+  it('is byte-identical to a fresh render', () => {
+    // The whole guarantee: a token changed in the engine and not regenerated
+    // fails here rather than shipping a JSON that describes a palette Bloom no
+    // longer paints.
+    expect(readFileSync(TOKENS_PATH, 'utf8')).toBe(renderBloomTokensJson());
+  });
+
+  it('says so in its own $description', () => {
+    expect(bloomDesignTokens().$description).toContain('AUTO-GENERATED');
+  });
+});
+
+describe('tokens.json shape contract', () => {
+  /* Astro codegens C++ SkColor tables from these paths, so the shape is a
+   * published interface: new groups may be added, existing paths may not move. */
+  const tokens = bloomDesignTokens();
+
+  it('covers every preset Bloom ships, and nothing else', () => {
+    const presets = Object.keys(tokens.color).filter((key) => !key.startsWith('$'));
+    expect(presets.sort()).toEqual([...APP_COLOR_NAMES].sort());
+  });
+
+  it('carries both schemes and every canonical token, for every preset', () => {
+    for (const name of APP_COLOR_NAMES) {
+      const preset = tokens.color[name] as PresetGroup;
+      for (const scheme of ['light', 'dark'] as const) {
+        expect(Object.keys(preset[scheme]).sort()).toEqual([...CANONICAL_TOKENS].sort());
+      }
+    }
+  });
+
+  it('names tokens as the CSS custom property without the leading --', () => {
+    // What makes the mapping mechanical for a consumer. A token renamed on one
+    // side only would break it silently.
+    const preset = tokens.color.oxy as PresetGroup;
+    for (const token of Object.keys(preset.light)) {
+      expect(token.startsWith('--')).toBe(false);
+      expect(getResolvedTokens('oxy', 'light')[`--${token}`]).toBeDefined();
+    }
+  });
+
+  it('resolves every colour to an sRGB hex string', () => {
+    for (const name of APP_COLOR_NAMES) {
+      const preset = tokens.color[name] as PresetGroup;
+      for (const scheme of ['light', 'dark'] as const) {
+        for (const [token, entry] of Object.entries(preset[scheme])) {
+          expect(`${name}.${scheme}.${token} = ${String(entry.$value)}`).toMatch(
+            /= #[0-9a-f]{6}([0-9a-f]{2})?$/,
+          );
+        }
+      }
+    }
+  });
+
+  it('records each preset’s seed and variant', () => {
+    for (const name of APP_COLOR_NAMES) {
+      const preset = tokens.color[name] as PresetGroup;
+      expect(preset.$extensions['so.oxy.bloom']).toMatchObject({
+        seed: APP_COLOR_PRESETS[name].hex,
+        variant: APP_COLOR_PRESETS[name].variant,
+      });
+    }
+  });
+
+  it('emits the numeric scales as px dimensions', () => {
+    expect(tokens.spacing['space-8']).toEqual({ $value: '8px' });
+    expect(tokens.radius['radius-max']).toEqual({ $value: '9999px' });
+    expect(tokens.borderWidth['hairline']).toEqual({ $value: '0.5px' });
+    expect(tokens.typography['body']).toMatchObject({
+      fontSize: { $value: '15px' },
+      fontWeight: { $value: 400 },
+    });
+  });
+});
+
+describe('resolvedColorToHex', () => {
+  it('converts the engine’s two output forms', () => {
+    expect(resolvedColorToHex('rgb(255 239 253)')).toBe('#ffeffd');
+    expect(resolvedColorToHex('rgb(0 0 0)')).toBe('#000000');
+    // 0.13 × 255 = 33.15 → 33 → 0x21. An 8-bit alpha is exactly what an SkColor
+    // holds, so nothing is lost downstream.
+    expect(resolvedColorToHex('rgba(213, 86, 255, 0.13)')).toBe('#d556ff21');
+  });
+
+  it('drops a fully opaque alpha rather than emitting #rrggbbff', () => {
+    expect(resolvedColorToHex('rgba(1, 2, 3, 1)')).toBe('#010203');
+  });
+
+  /* The engine emitting a third form — an oklch(), a bare hex, a named colour —
+   * would otherwise reach a C++ colour table as an unparseable string. Failing
+   * at generation time is the only place anyone would notice. */
+  it('throws on anything that is not an rgb()/rgba() colour', () => {
+    expect(() => resolvedColorToHex('oklch(0.7 0.1 300)')).toThrow(/not an rgb/);
+    expect(() => resolvedColorToHex('#ffeffd')).toThrow(/not an rgb/);
+    expect(() => resolvedColorToHex('0.5rem')).toThrow(/not an rgb/);
+  });
+});

package/src/__tests__/exports-map-contract.test.ts

@@ -37,7 +37,11 @@ const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8')) as {
 const exportsMap = pkg.exports;
 
 /** Non-subpath entries that are legitimately plain strings (static assets). */
-const STRING_ENTRIES = ['./design-tokens/theme.css', './package.json'];
+const STRING_ENTRIES = [
+  './design-tokens/theme.css',
+  './design-tokens/tokens.json',
+  './package.json',
+];
 
 /**
  * Vacuity floor. `SUBPATHS` in the generator is 86 entries today; a traversal

package/src/__tests__/support/constructed-style-sheets.ts

@@ -0,0 +1,68 @@
+/**
+ * A spec-shaped stand-in for constructed stylesheets, for the jsdom suites.
+ *
+ * jsdom 26 ships the `CSSStyleSheet` CONSTRUCTOR but neither `replaceSync` nor
+ * `document.adoptedStyleSheets`, so every jsdom test takes Bloom's `<style>`
+ * fallback. That makes the whole CSP-safe path — the reason
+ * `styles/adopt-style-sheet.ts` exists — invisible to jest unless a test
+ * installs the API itself. Without this, a mutation that deleted the adoption
+ * branch entirely would leave the suite green.
+ *
+ * Not collected as a suite: jest's `testMatch` wants `*.test.ts` / `*.spec.ts`.
+ */
+
+export interface FakeStyleSheet {
+  /** The CSS most recently handed to `replaceSync`. */
+  cssText: string;
+  /** How many times the sheet has been re-parsed, so a test can prove it wasn't. */
+  replaceSyncCalls: number;
+  replaceSync(css: string): void;
+}
+
+export interface ConstructedStyleSheetsHarness {
+  /** The document's adopted sheets, read live (the code reassigns the array). */
+  adopted(): readonly FakeStyleSheet[];
+  /** Drop the API again, restoring jsdom's own `CSSStyleSheet`. */
+  uninstall(): void;
+}
+
+export function installConstructedStyleSheets(): ConstructedStyleSheetsHarness {
+  class FakeCSSStyleSheet implements FakeStyleSheet {
+    cssText = '';
+    replaceSyncCalls = 0;
+
+    replaceSync(css: string): void {
+      this.cssText = css;
+      this.replaceSyncCalls += 1;
+    }
+  }
+
+  const previousConstructor = Object.getOwnPropertyDescriptor(
+    globalThis,
+    'CSSStyleSheet',
+  );
+
+  Object.defineProperty(globalThis, 'CSSStyleSheet', {
+    value: FakeCSSStyleSheet,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(document, 'adoptedStyleSheets', {
+    value: [],
+    writable: true,
+    configurable: true,
+  });
+
+  return {
+    adopted: () =>
+      document.adoptedStyleSheets as unknown as readonly FakeStyleSheet[],
+    uninstall: () => {
+      Reflect.deleteProperty(document, 'adoptedStyleSheets');
+      if (previousConstructor) {
+        Object.defineProperty(globalThis, 'CSSStyleSheet', previousConstructor);
+      } else {
+        Reflect.deleteProperty(globalThis, 'CSSStyleSheet');
+      }
+    },
+  };
+}

package/src/bottom-sheet/BottomSheetBase.tsx

@@ -11,6 +11,7 @@ import {
     type StyleProp,
 } from 'react-native';
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler';
+import { adoptStyleSheet, dropStyleSheet } from '../styles/adopt-style-sheet';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { Z_INDEX } from '../styles/z-index';
 import Animated, {
@@ -921,15 +922,7 @@ const styles = StyleSheet.create({
 
 // Create web scrollbar styles dynamically based on theme
 const createWebScrollbarStyle = (borderColor: string) => {
-    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
-
-    let styleElement = document.getElementById(SCROLLBAR_STYLE_ID) as HTMLStyleElement | null;
-
-    if (!styleElement) {
-        styleElement = document.createElement('style');
-        styleElement.id = SCROLLBAR_STYLE_ID;
-        document.head.appendChild(styleElement);
-    }
+    if (Platform.OS !== 'web') return;
 
     // Derive a slightly darker scrollbar hover color from the border color
     const scrollbarColor = borderColor;
@@ -937,7 +930,9 @@ const createWebScrollbarStyle = (borderColor: string) => {
         ? borderColor.replace(/\)$/, ' / 0.7)')  // add alpha for hover
         : '#888';
 
-    styleElement.textContent = `
+    adoptStyleSheet(
+        SCROLLBAR_STYLE_ID,
+        `
         .bottom-sheet-scrollview::-webkit-scrollbar {
             width: 6px;
         }
@@ -952,13 +947,14 @@ const createWebScrollbarStyle = (borderColor: string) => {
         .bottom-sheet-scrollview::-webkit-scrollbar-thumb:hover {
             background: ${scrollbarHoverColor};
         }
-    `;
+    `,
+    );
 };
 
 const SCROLLBAR_STYLE_ID = 'bottom-sheet-scrollbar-style';
 
-/** Remove the injected scrollbar <style> tag on unmount. */
+/** Detach the scrollbar rules on unmount. */
 const removeWebScrollbarStyle = () => {
-    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
-    document.getElementById(SCROLLBAR_STYLE_ID)?.remove();
+    if (Platform.OS !== 'web') return;
+    dropStyleSheet(SCROLLBAR_STYLE_ID);
 };

package/src/button/Button.web.tsx

@@ -12,6 +12,7 @@ import React, {
 import { useTheme } from '../theme/use-theme';
 import type { Theme } from '../theme/types';
 import { SpinnerIcon } from '../loading/SpinnerIcon.web';
+import { adoptStyleSheet } from '../styles/adopt-style-sheet';
 import { flattenWebStyle } from '../styles/flatten-web-style';
 import type { ButtonProps, ButtonSize, ButtonVariant } from './types';
 
@@ -128,12 +129,7 @@ const BLOOM_BUTTON_CSS = `
 
 function useButtonCss(): void {
   useEffect(() => {
-    if (typeof document === 'undefined') return;
-    if (document.getElementById(STYLE_ID)) return;
-    const style = document.createElement('style');
-    style.id = STYLE_ID;
-    style.textContent = BLOOM_BUTTON_CSS;
-    document.head.appendChild(style);
+    adoptStyleSheet(STYLE_ID, BLOOM_BUTTON_CSS);
   }, []);
 }
 

package/src/connection-dots/ConnectionDots.web.tsx

@@ -1,6 +1,7 @@
 import React, { memo, useEffect, useState } from 'react';
 import { View, type ViewStyle } from 'react-native';
 
+import { adoptStyleSheet } from '../styles/adopt-style-sheet';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
 import { ConnectionDotsBase } from './ConnectionDotsBase';
@@ -31,12 +32,7 @@ export const BLOOM_CONNECTION_DOTS_CSS = `
 
 function useKeyframes(): void {
   useEffect(() => {
-    if (typeof document === 'undefined') return;
-    if (document.getElementById(KEYFRAMES_ID)) return;
-    const style = document.createElement('style');
-    style.id = KEYFRAMES_ID;
-    style.textContent = BLOOM_CONNECTION_DOTS_CSS;
-    document.head.appendChild(style);
+    adoptStyleSheet(KEYFRAMES_ID, BLOOM_CONNECTION_DOTS_CSS);
   }, []);
 }
 

package/src/design-tokens/index.ts

@@ -27,6 +27,22 @@ export type {
 
 export { bloomThemeCss, bloomThemeBlock } from './theme-css';
 
+/* The same tokens as a data structure rather than a stylesheet, for a consumer
+ * that is not a browser (`@oxyhq/bloom/design-tokens/tokens.json` is the
+ * generated artifact; these rebuild it in memory). Both come from the colour
+ * engine, so the JSON and the CSS cannot disagree. */
+export {
+  bloomDesignTokens,
+  renderBloomTokensJson,
+  resolvedColorToHex,
+} from './tokens-json';
+export type {
+  BloomDesignTokens,
+  DesignToken,
+  PresetExtensions,
+  PresetGroup,
+} from './tokens-json';
+
 /* The resolved counterpart of `bloomThemeCss()`. That emits the alias layer
  * (`--color-x: var(--x)`); these resolve `--x` itself, so a build script can
  * write a static `:root` / `.dark` block and a prerendered page paints the real

package/src/design-tokens/tokens-json.ts

@@ -0,0 +1,214 @@
+/**
+ * The machine-readable form of every Bloom design token, in W3C Design Tokens
+ * (DTCG) format.
+ *
+ * The CSS artifacts next to this file (`theme.css`, `bloomThemeCss()`) are the
+ * ALIAS layer and only make sense to a browser. A consumer that is not a
+ * browser — Astro codegens `SkColor` tables for Chromium's native UI so the
+ * toolbar and the WebUI pages cannot disagree about what "primary" is — needs
+ * the RESOLVED values, for every preset and both schemes, in a format it can
+ * read without running Bloom's colour engine. That is this file.
+ *
+ * Same single source as everything else: `getResolvedTokens`, i.e. the colour
+ * engine. `tokens.json` is generated from it by
+ * `scripts/generate-design-tokens-json.ts`, and
+ * `src/__tests__/design-tokens-json.test.ts` fails if the checked-in file is
+ * not byte-identical to a fresh render — so the JSON, the CSS and the runtime
+ * palette cannot drift from each other.
+ */
+
+import {
+  APP_COLOR_NAMES,
+  APP_COLOR_PRESETS,
+  type AppColorName,
+} from '../theme/color-presets';
+import { getResolvedTokens } from '../theme/token-registry';
+import {
+  BORDER_WIDTH,
+  RADIUS,
+  SPACING,
+  TYPOGRAPHY,
+  type TypeRoleName,
+} from './scales';
+
+/** One DTCG token. `$type` is inherited from the nearest group that declares it. */
+export interface DesignToken {
+  $value: string | number;
+  $type?: string;
+  $description?: string;
+}
+
+/** Bloom-specific metadata on a preset group, namespaced per the DTCG `$extensions` rule. */
+export interface PresetExtensions {
+  'so.oxy.bloom': {
+    /** The brand seed the engine derived the whole palette from. */
+    seed: string;
+    /** The tonal scheme variant used with that seed. */
+    variant: string;
+    /** Who may pick the preset; absent means everyone. */
+    gate?: string;
+    /** Present when the preset forces a white label in both schemes. */
+    label?: string;
+  };
+}
+
+export interface PresetGroup {
+  $description: string;
+  $extensions: PresetExtensions;
+  light: Record<string, DesignToken>;
+  dark: Record<string, DesignToken>;
+}
+
+export interface BloomDesignTokens {
+  $description: string;
+  color: { $type: 'color'; $description: string } & Record<string, unknown>;
+  spacing: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  radius: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  borderWidth: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  typography: { $description: string } & Record<string, unknown>;
+}
+
+const FILE_DESCRIPTION = [
+  'Bloom design tokens, resolved. W3C Design Tokens Community Group format.',
+  'SHAPE CONTRACT (consumers codegen against this — additions are additive, existing paths do not move):',
+  'color.<preset>.<scheme>.<token> — <preset> is a Bloom AppColorName, <scheme> is "light" or "dark",',
+  'and <token> is the CSS custom property Bloom writes on the document root with its leading "--" removed,',
+  'so color.oxy.dark.card carries the value of --card under the oxy preset in dark.',
+  'Every colour $value is an sRGB hex string: "#rrggbb", or "#rrggbbaa" when the token carries alpha',
+  '(the -subtle family does). spacing/radius/borderWidth are DTCG dimensions with a px unit in the string.',
+  'typography.<role> is a group of fontSize (dimension), lineHeight (dimension) and fontWeight (number);',
+  'font FAMILIES are deliberately absent — they resolve to CSS variables a non-browser consumer cannot use.',
+  'Shadows are absent for the same reason: Bloom ships them as a platform-forked style object (bloomShadowStyle),',
+  'not as a value.',
+  'AUTO-GENERATED by scripts/generate-design-tokens-json.ts from Bloom’s colour engine — do not edit.',
+].join(' ');
+
+/**
+ * Turn one resolved token value into an sRGB hex string.
+ *
+ * The engine emits exactly two forms — `rgb(r g b)` for opaque tokens and
+ * `rgba(r, g, b, a)` for the translucent `-subtle` family. Anything else is a
+ * change in the engine's output that this file has not been taught about, and
+ * throwing at generation time is the only way that surfaces: a silently
+ * passed-through CSS string would end up in a C++ colour table as garbage.
+ */
+export function resolvedColorToHex(value: string): string {
+  const channels = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*(?:[,/]\s*([\d.]+%?)\s*)?\)$/.exec(
+    value,
+  );
+  if (!channels) {
+    throw new Error(
+      `Bloom token value is not an rgb()/rgba() colour: ${JSON.stringify(value)}`,
+    );
+  }
+
+  const [, red = '0', green = '0', blue = '0', alpha] = channels;
+  const byte = (channel: string): string =>
+    Math.round(Number(channel)).toString(16).padStart(2, '0');
+  const hex = `#${byte(red)}${byte(green)}${byte(blue)}`;
+
+  if (alpha === undefined) return hex;
+  const fraction = alpha.endsWith('%')
+    ? Number(alpha.slice(0, -1)) / 100
+    : Number(alpha);
+  if (fraction >= 1) return hex;
+  return `${hex}${byte(String(fraction * 255))}`;
+}
+
+function schemeTokens(
+  preset: AppColorName,
+  scheme: 'light' | 'dark',
+): Record<string, DesignToken> {
+  const tokens: Record<string, DesignToken> = {};
+  for (const [property, value] of Object.entries(getResolvedTokens(preset, scheme))) {
+    tokens[property.replace(/^--/, '')] = { $value: resolvedColorToHex(value) };
+  }
+  return tokens;
+}
+
+function colorGroup(): BloomDesignTokens['color'] {
+  const group: Record<string, unknown> = {
+    $type: 'color',
+    $description:
+      'One group per Bloom colour preset, each with a light and a dark scheme. Token names match the CSS custom properties without the leading "--".',
+  };
+
+  for (const name of APP_COLOR_NAMES) {
+    const preset = APP_COLOR_PRESETS[name];
+    const extensions: PresetExtensions = {
+      'so.oxy.bloom': { seed: preset.hex, variant: preset.variant },
+    };
+    if (preset.gate) extensions['so.oxy.bloom'].gate = preset.gate;
+    if (preset.label) extensions['so.oxy.bloom'].label = preset.label;
+
+    group[name] = {
+      $description: `Derived by Bloom’s colour engine from seed ${preset.hex} (${preset.variant}).`,
+      $extensions: extensions,
+      light: schemeTokens(name, 'light'),
+      dark: schemeTokens(name, 'dark'),
+    } satisfies PresetGroup;
+  }
+
+  return group as BloomDesignTokens['color'];
+}
+
+function dimensionGroup(
+  description: string,
+  scale: Record<string, number>,
+): BloomDesignTokens['spacing'] {
+  const group: Record<string, unknown> = {
+    $type: 'dimension',
+    $description: description,
+  };
+  for (const [key, value] of Object.entries(scale)) {
+    group[key] = { $value: `${value}px` } satisfies DesignToken;
+  }
+  return group as BloomDesignTokens['spacing'];
+}
+
+function typographyGroup(): BloomDesignTokens['typography'] {
+  const group: Record<string, unknown> = {
+    $description:
+      'One group per type role. Sizes and line-heights are px dimensions; weights are DTCG numeric font weights.',
+  };
+  for (const name of Object.keys(TYPOGRAPHY) as TypeRoleName[]) {
+    const role = TYPOGRAPHY[name];
+    group[name] = {
+      fontSize: { $type: 'dimension', $value: `${role.size}px` },
+      lineHeight: { $type: 'dimension', $value: `${role.lineHeight}px` },
+      fontWeight: { $type: 'fontWeight', $value: Number(role.weight) },
+    };
+  }
+  return group as BloomDesignTokens['typography'];
+}
+
+/** The whole token file, as a plain object. */
+export function bloomDesignTokens(): BloomDesignTokens {
+  return {
+    $description: FILE_DESCRIPTION,
+    color: colorGroup(),
+    spacing: dimensionGroup(
+      'The Oxy spacing scale. Same keys as the Tailwind/NativeWind utilities (p-space-8, gap-space-20, px-screen-margin).',
+      SPACING,
+    ),
+    radius: dimensionGroup(
+      'The corner-radius scale. Same keys as the rounded-radius-* utilities; radius-max is the pill/circle sentinel.',
+      RADIUS,
+    ),
+    borderWidth: dimensionGroup(
+      'Border widths. hairline is the 0.5px rule that pairs with the border-image colour role.',
+      BORDER_WIDTH,
+    ),
+    typography: typographyGroup(),
+  };
+}
+
+/**
+ * The exact bytes of `design-tokens/tokens.json`.
+ *
+ * Both the generator script and the drift test call this, so neither can be
+ * right about the file while the other is wrong.
+ */
+export function renderBloomTokensJson(): string {
+  return `${JSON.stringify(bloomDesignTokens(), null, 2)}\n`;
+}