@oxyhq/bloom 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
@@ -1407,6 +1407,7 @@
   "files": [
     "src",
     "lib",
+    "docs/*.mdx",
     "!**/__tests__/**",
     "!**/__fixtures__/**",
     "!**/__mocks__/**",
@@ -1474,13 +1475,15 @@
   "scripts": {
     "generate:exports": "node scripts/generate-platform-exports.mjs",
     "generate:theme-css": "bun scripts/generate-theme-css.ts",
+    "generate:theme-golden": "bun scripts/generate-theme-golden.ts",
     "generate:tokens-json": "bun scripts/generate-design-tokens-json.ts",
     "prebuild": "node scripts/generate-platform-exports.mjs && bun scripts/generate-theme-css.ts && bun scripts/generate-design-tokens-json.ts",
     "build": "bob build",
     "postbuild": "node scripts/verify-package.mjs",
     "verify:package": "node scripts/verify-package.mjs",
+    "verify:consumer-types": "node scripts/verify-consumer-typecheck.mjs",
     "test": "jest",
-    "typescript": "tsc --noEmit",
+    "typescript": "tsc --noEmit && node scripts/verify-consumer-typecheck.mjs",
     "clean": "rm -rf lib",
     "prepack": "bun run clean && bun run build",
     "prepare": "[ -n \"$BLOOM_VERIFY_PACKAGE_RUNNING\" ] || bun run build || true",

package/src/__tests__/support/collision-fixture-barrel.ts

@@ -0,0 +1,20 @@
+/**
+ * A barrel that DELIBERATELY offers one name from two declarations, so that
+ * `barrel-name-collisions.test.ts` can prove its detector fires. It reproduces
+ * the shipped `Item` shape: a star export carrying `Item` from `item/`, and an
+ * explicit re-export binding that same name to a different component.
+ *
+ * Nothing imports this at runtime. bob's `exclude` keeps it out of `lib/`, and
+ * `files: ["src", …]` does ship it inside the tarball's `src/` like the other
+ * test files there — but no entry point reaches it, so no bundler links it, and
+ * `package.json#exports` never names it.
+ *
+ * The `Card` lines below are the other half of the
+ * control: one name offered twice from ONE declaration, which the detector must
+ * stay quiet about — otherwise its cheapest fix would be deleting a legitimate
+ * redundant re-export.
+ */
+export * from '../../item';
+export { Card as Item } from '../../card';
+export { Card } from '../../card';
+export * from '../../card';

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/__tests__/support/press-host.ts

@@ -0,0 +1,30 @@
+/**
+ * Pressing a component's OWN host node, and proving the component is what
+ * installed the handler being measured.
+ *
+ * `fireEvent.press` walks UP from the element it is handed to the nearest
+ * ancestor carrying an `onPress` prop, and it does not stop at host nodes — a
+ * COMPOSITE counts, because `getEventHandler` only reads `element.props`. So
+ * `<Thing onPress={fn}>` written in a test's own JSX catches the press itself.
+ * Measured on `ProfileCard`: with the handler deleted from the component the
+ * card rendered as an inert `View`, and the test still reported exactly one
+ * call. Green, and measuring nothing. Nine suites had the same shape.
+ *
+ * Asserting the host node's own `onPress` FIRST closes both halves:
+ *
+ *  - a component that installs no handler at all fails here, and
+ *  - a component that installs one which drops the caller's fails on the call
+ *    count, because `fireEvent` now finds a handler AT the node and never walks
+ *    past it to the test's own JSX.
+ *
+ * `host` must therefore be the node the component itself made pressable — the
+ * one carrying its `testID` / `accessibilityLabel` — not a `Text` deep inside
+ * it, or the walk-up is back and so is the hole.
+ */
+import { fireEvent } from '@testing-library/react-native';
+import type { ReactTestInstance } from 'react-test-renderer';
+
+export function pressHost(host: ReactTestInstance): void {
+  expect(typeof host.props.onPress).toBe('function');
+  fireEvent.press(host);
+}

package/src/__tests__/support/rendered-style.ts

@@ -0,0 +1,99 @@
+/**
+ * Reading what actually landed on a rendered node — shared by every suite that
+ * asserts the "className lands on the node the parent lays out" rule.
+ *
+ * Three components had the same two-node defect (`Button`, then `Fab` and
+ * `FrostedIconButton`), and asserting it needs the same two things each time:
+ * the HOST tree (composites do not appear in `toJSON()`, so a wrapper is only
+ * visible there) and a deep flatten of the `style` prop, because react-native-css
+ * merges a caller's class in as a `{ $$css: true, className }` descriptor
+ * ALONGSIDE the style objects rather than in a prop of its own.
+ */
+import type { ReactTestRendererJSON } from 'react-test-renderer';
+
+export type StyleEntry = Record<string, unknown>;
+
+export interface HostNode {
+  type: string;
+  props: Record<string, unknown>;
+  children: Array<HostNode | string> | null;
+}
+
+/**
+ * Deep-flatten an RN `style` prop (nested arrays, `false`/`null` holes) into the
+ * list of style objects that actually reached the node.
+ */
+export function styleEntries(style: unknown, out: StyleEntry[] = []): StyleEntry[] {
+  if (!style || typeof style !== 'object') return out;
+  if (Array.isArray(style)) {
+    for (const entry of style) styleEntries(entry, out);
+    return out;
+  }
+  out.push(style as StyleEntry);
+  return out;
+}
+
+/** Every style key/value that landed on a node, later entries winning. */
+export function resolvedStyle(style: unknown): StyleEntry {
+  return Object.assign({}, ...styleEntries(style)) as StyleEntry;
+}
+
+/** The class tokens react-native-css accepted for a node, in arrival order. */
+export function classNamesOn(style: unknown): string[] {
+  return styleEntries(style)
+    .filter((entry) => entry.$$css === true && typeof entry.className === 'string')
+    .map((entry) => String(entry.className));
+}
+
+export function isHostNode(value: unknown): value is HostNode {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as HostNode).type === 'string'
+  );
+}
+
+/** Walk the HOST tree (composites are absent from `toJSON()`) for a testID. */
+export function findHost(
+  node: ReactTestRendererJSON | ReactTestRendererJSON[] | unknown,
+  testID: string,
+): HostNode | null {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const hit = findHost(child, testID);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (!isHostNode(node)) return null;
+  if (node.props.testID === testID) return node;
+  return findHost(node.children, testID);
+}
+
+/**
+ * Every host node in a rendered tree, in document order.
+ *
+ * The reason to walk `toJSON()` rather than `UNSAFE_root.findAll` is that the
+ * latter yields COMPOSITE instances too, so a `memo(fn)` component contributes
+ * two matches for one rendered element and every count is silently doubled —
+ * which reads as "the component rendered the thing twice", not as an artefact
+ * of the query.
+ */
+export function hostNodes(tree: unknown, out: HostNode[] = []): HostNode[] {
+  if (Array.isArray(tree)) {
+    for (const child of tree) hostNodes(child, out);
+    return out;
+  }
+  if (!isHostNode(tree)) return out;
+  out.push(tree);
+  return hostNodes(tree.children, out);
+}
+
+/**
+ * The host nodes a parent laid out. Callers assert the LENGTH themselves —
+ * "exactly one" is the property, and a helper that returned only the first would
+ * hide the second.
+ */
+export function renderedChildren(tree: unknown, hostTestID: string): HostNode[] {
+  const host = findHost(tree, hostTestID);
+  if (host === null) throw new Error(`no host rendered for testID "${hostTestID}"`);
+  return (host.children ?? []).filter(isHostNode);
+}

package/src/__tests__/support/unread-hook-fixture.ts

@@ -0,0 +1,33 @@
+/**
+ * A module that DELIBERATELY throws away one of the values a hook hands back, so
+ * `hook-subscriptions-are-read.test.ts` can prove its detector fires. It carries
+ * both halves of the control: `unreadFlag` is bound and never read, which the
+ * detector must report, and `readFlag` is bound and read, which it must stay
+ * quiet about — otherwise the cheapest way to green the gate would be deleting a
+ * binding that is doing its job.
+ *
+ * Nothing imports this at runtime. bob's `exclude` keeps it out of `lib/`, and
+ * `files: ["src", …]` does ship it inside the tarball's `src/` like the other
+ * 137 test files there — but no entry point reaches it, so no bundler links it.
+ * It is a plain `.ts` with no React import because the
+ * detector reads source, never types: a call named `use…` bound to a name is all
+ * the shape there is.
+ *
+ * The destructuring RENAMES, which is not decoration — it reproduces the shipped
+ * shape (`const { state: pressed, onIn: onPressIn } = useInteractionState()`) and
+ * it is what keeps the control honest. A hook declared in the same file as its
+ * caller mentions its own property names in its return type and its return
+ * object, and the detector counts every occurrence of a spelling as a possible
+ * read, so an unrenamed fixture would be silently unreportable for a reason no
+ * real call site has.
+ */
+
+/** Stands in for a real subscription — a hook by name, with two return values. */
+function useFixtureInteractionState(): { first: boolean; second: boolean } {
+  return { first: false, second: false };
+}
+
+export function fixtureComponentBody(): boolean {
+  const { first: readFlag, second: unreadFlag } = useFixtureInteractionState();
+  return readFlag;
+}

package/src/design-tokens/color-roles.ts

@@ -81,6 +81,26 @@ export const TEXT_ROLES = {
   'text-placeholder': ref('muted-foreground'),
 } as const;
 
+/**
+ * Decorative brand-accent text roles → text-color utilities.
+ *
+ * These are deliberately separate from the semantic status roles
+ * (`success-text`, `warning-text`, `info-text`, and `error-text`). Product
+ * copy, labels, and artwork captions can use the active palette's accent
+ * families without pretending that the text communicates a system state.
+ *
+ * | utility               | canonical token    |
+ * | --------------------- | ------------------ |
+ * | text-accent-primary   | --primary-text     |
+ * | text-accent-secondary | --secondary-text   |
+ * | text-accent-tertiary  | --tertiary-text    |
+ */
+export const ACCENT_TEXT_ROLES = {
+  'accent-primary': ref('primary-text'),
+  'accent-secondary': ref('secondary-text'),
+  'accent-tertiary': ref('tertiary-text'),
+} as const;
+
 /**
  * Border roles → border-color utilities (`border-<role>`).
  *
@@ -107,4 +127,5 @@ export const BORDER_ROLES = {
 
 export type FillRole = keyof typeof FILL_ROLES;
 export type TextRole = keyof typeof TEXT_ROLES;
+export type AccentTextRole = keyof typeof ACCENT_TEXT_ROLES;
 export type BorderRole = keyof typeof BORDER_ROLES;

package/src/design-tokens/index.ts

@@ -10,7 +10,7 @@
  *     for CSS-configured web apps.
  *   - `getPresetVars` / `buildSeedScopeVars` — the resolved token VALUES behind
  *     that alias layer, for a named preset or an arbitrary brand seed.
- *   - The raw token maps (`FILL_ROLES`, `TEXT_ROLES`, `BORDER_ROLES`, `SPACING`,
+ *   - The raw token maps (`FILL_ROLES`, `TEXT_ROLES`, `ACCENT_TEXT_ROLES`, `BORDER_ROLES`, `SPACING`,
  *     `RADIUS`, `TYPOGRAPHY`, `SHADOW_BOX`) for direct programmatic use.
  *   - `bloomShadowStyle` — platform-correct shadow style object (web box-shadow /
  *     native elevation) so a consumer writes one call for both platforms.
@@ -65,9 +65,10 @@ export type { SeedScopeOptions } from '../theme/color-scope/seed-scope';
 export {
   FILL_ROLES,
   TEXT_ROLES,
+  ACCENT_TEXT_ROLES,
   BORDER_ROLES,
 } from './color-roles';
-export type { FillRole, TextRole, BorderRole } from './color-roles';
+export type { FillRole, TextRole, AccentTextRole, BorderRole } from './color-roles';
 
 export {
   SPACING,

package/src/design-tokens/tailwind-preset.ts

@@ -26,7 +26,7 @@
  * `Config`) so Bloom does not need to depend on `tailwindcss` types.
  */
 
-import { BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
+import { ACCENT_TEXT_ROLES, BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
 import {
   BORDER_WIDTH,
   FONT_FAMILY_VARS,
@@ -109,6 +109,7 @@ const BORDER_WIDTH_PX = toPxMap(BORDER_WIDTH);
 const COLOR_ROLES: Record<string, string> = {
   ...FILL_ROLES,
   ...TEXT_ROLES,
+  ...ACCENT_TEXT_ROLES,
   ...BORDER_ROLES,
 };
 
@@ -123,7 +124,7 @@ export const bloomTailwindPreset: TailwindPreset = Object.freeze({
       colors: { ...COLOR_ROLES },
       // Targeted buckets so the namespaced roles resolve on the right utility.
       backgroundColor: { ...FILL_ROLES },
-      textColor: { ...TEXT_ROLES },
+      textColor: { ...TEXT_ROLES, ...ACCENT_TEXT_ROLES },
       borderColor: { ...BORDER_ROLES },
 
       spacing: SPACING_PX,

package/src/design-tokens/theme-css.ts

@@ -23,7 +23,7 @@
  * `bloomThemeCss()` directly into their `@theme { … }` — the values are stable.
  */
 
-import { BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
+import { ACCENT_TEXT_ROLES, BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
 import { CANONICAL_TOKENS } from '../theme/token-registry';
 import {
   BORDER_WIDTH,
@@ -53,6 +53,7 @@ export function bloomThemeCss(): string {
   for (const [role, value] of Object.entries({
     ...FILL_ROLES,
     ...TEXT_ROLES,
+    ...ACCENT_TEXT_ROLES,
     ...BORDER_ROLES,
   })) {
     lines.push(`  --color-${role}: ${value};`);

package/src/design-tokens/theme.css

@@ -21,6 +21,9 @@
   --color-text-inverse: var(--primary-foreground);
   --color-text-fixed-light: var(--primary-foreground);
   --color-text-placeholder: var(--muted-foreground);
+  --color-accent-primary: var(--primary-text);
+  --color-accent-secondary: var(--secondary-text);
+  --color-accent-tertiary: var(--tertiary-text);
   --color-border: var(--border);
   --color-border-image: var(--border);
   --color-border-secondary: var(--input);

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

@@ -18,10 +18,13 @@
  */
 
 import {
-  APP_COLOR_NAMES,
-  APP_COLOR_PRESETS,
+  COLOR_PRESET_REGISTRY,
   type AppColorName,
+  type ColorPresetFamily,
+  type ColorPresetGate,
+  type ColorPresetPairing,
 } from '../theme/color-presets';
+import type { SchemeVariant } from '../theme/color-engine';
 import { getResolvedTokens } from '../theme/token-registry';
 import {
   BORDER_WIDTH,
@@ -44,11 +47,18 @@ export interface PresetExtensions {
     /** The brand seed the engine derived the whole palette from. */
     seed: string;
     /** The tonal scheme variant used with that seed. */
-    variant: string;
+    variant: SchemeVariant;
+    displayName: string;
+    family: ColorPresetFamily;
+    description: string;
+    pairing: ColorPresetPairing;
+    featured: boolean;
+    secondarySeed?: string;
+    tertiarySeed?: string;
     /** Who may pick the preset; absent means everyone. */
-    gate?: string;
+    gate?: ColorPresetGate;
     /** Present when the preset forces a white label in both schemes. */
-    label?: string;
+    label?: 'white';
   };
 }
 
@@ -133,16 +143,26 @@ function colorGroup(): BloomDesignTokens['color'] {
       '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];
+  for (const preset of COLOR_PRESET_REGISTRY) {
+    const { name } = preset;
     const extensions: PresetExtensions = {
-      'so.oxy.bloom': { seed: preset.hex, variant: preset.variant },
+      'so.oxy.bloom': {
+        seed: preset.hex,
+        variant: preset.variant,
+        displayName: preset.displayName,
+        family: preset.family,
+        description: preset.description,
+        pairing: preset.pairing,
+        featured: preset.featured,
+      },
     };
+    if (preset.secondaryHex) extensions['so.oxy.bloom'].secondarySeed = preset.secondaryHex;
+    if (preset.tertiaryHex) extensions['so.oxy.bloom'].tertiarySeed = preset.tertiaryHex;
     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}).`,
+      $description: preset.description,
       $extensions: extensions,
       light: schemeTokens(name, 'light'),
       dark: schemeTokens(name, 'dark'),