@oxyhq/bloom 0.51.0 → 0.51.1

package/src/__tests__/icon-references.test.ts

@@ -0,0 +1,243 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+/**
+ * Every `Icons.*` reference in this repo must name an identifier `src/icons`
+ * actually exports.
+ *
+ * Icon exports carry their full style and corner suffix
+ * (`Home_Stroke2_Corner0_Rounded`), there are 250-odd of them, and a shortened
+ * name is not a compile error anywhere it usually appears: in a DOC COMMENT or an
+ * `.mdx` example, `tsc` never sees it. A reader copies it, gets `undefined`, and
+ * React reports "Element type is invalid … but got: undefined" against the
+ * consumer's own file — which is exactly how a phantom release blocker was filed
+ * against the tab bar's native surface.
+ *
+ * Two shapes are checked, because the real incident needed both:
+ *
+ *   1. `Icons.Home` — a member that does not exist.
+ *   2. `import { Icons } from '@oxyhq/bloom/icons'` — the NAMESPACE imported as a
+ *      named export. `Icons` is assembled by the ROOT barrel
+ *      (`export * as Icons from './icons'` in `src/index.ts`); the `./icons`
+ *      subpath exports the components flat, so that import is `undefined` too.
+ *      `import * as Icons from '@oxyhq/bloom/icons'` and
+ *      `import { Icons } from '@oxyhq/bloom'` are both correct and must stay
+ *      unflagged.
+ *
+ * Comments are deliberately NOT stripped here — the inverse of
+ * `TabBarWebFork.test.ts`, which blanks them so a doc comment naming a package is
+ * not mistaken for an import of it. Here the doc comments ARE the surface under
+ * test: four of the five instances this test was written for lived in JSDoc.
+ *
+ * Identifiers are matched against the UNION of everything exported anywhere under
+ * `src/icons`, because references legitimately target the barrel
+ * (`../icons`), a single icon file (`../icons/Check`) and `../icons/common` alike.
+ */
+
+const SRC = join(__dirname, '..');
+const REPO_ROOT = join(SRC, '..');
+const ICONS_DIR = join(SRC, 'icons');
+
+const SCANNED_EXTENSIONS = ['.ts', '.tsx', '.mdx', '.md'];
+
+/** True for a specifier that resolves to an icons module, package or relative. */
+const ICONS_MODULE = /(?:^|\/)icons(?:\/|$)/;
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    // Agent worktrees under `.claude/` are full copies of this repo — scanning
+    // them would double every file and report another checkout's problems.
+    if (entry === 'node_modules' || entry === 'lib' || entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else if (SCANNED_EXTENSIONS.includes(extname(full))) out.push(full);
+  }
+  return out;
+}
+
+/** Every identifier a module exports, across every export shape in use here. */
+function exportedNames(source: string): string[] {
+  const found = new Set<string>();
+
+  // `export const X` / `export function X` / `export class X` /
+  // `export type X =` / `export interface X`
+  for (const m of source.matchAll(
+    /export\s+(?:declare\s+)?(?:const|let|var|function|class|type|interface)\s+([A-Za-z0-9_$]+)/g,
+  )) {
+    if (m[1]) found.add(m[1]);
+  }
+
+  // `export { A, B as C }` and `export type { A, B } from './x'` — the form that
+  // carries `IconStyle` / `Props` out of `icons/common.tsx` through the barrel.
+  // Missing it is what made an earlier pass of this check report two phantom
+  // failures, and a check with known noise is a check somebody disables.
+  for (const m of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/g)) {
+    for (const name of namedBindings(m[1] ?? '', 'export')) found.add(name);
+  }
+
+  return [...found];
+}
+
+/**
+ * The bindings a brace list introduces.
+ *
+ * `as` means opposite things in the two directions: `export { A as B }` publishes
+ * `B`, while `import { A as B }` reads `A`. Getting that backwards would make the
+ * check blind to exactly the imports it exists to catch.
+ */
+function namedBindings(list: string, direction: 'import' | 'export'): string[] {
+  const names: string[] = [];
+  for (const raw of list.split(',')) {
+    const part = raw.trim().replace(/^type\s+/, '');
+    if (!part) continue;
+    const sides = part.split(/\s+as\s+/).map((s) => s.trim());
+    const name = direction === 'export' ? sides[sides.length - 1] : sides[0];
+    if (name && /^[A-Za-z0-9_$]+$/.test(name) && name !== 'default') names.push(name);
+  }
+  return names;
+}
+
+/** The union of every identifier exported anywhere under `src/icons`. */
+function iconExportUnion(): Set<string> {
+  const union = new Set<string>();
+  for (const file of walk(ICONS_DIR)) {
+    for (const name of exportedNames(readFileSync(file, 'utf8'))) union.add(name);
+  }
+  return union;
+}
+
+interface Unresolved {
+  line: number;
+  ref: string;
+}
+
+/** Every icon reference in `source` that `exported` cannot satisfy. */
+function unresolvedIconRefs(source: string, exported: Set<string>): Unresolved[] {
+  const problems: Unresolved[] = [];
+
+  source.split('\n').forEach((text, index) => {
+    const line = index + 1;
+
+    for (const m of text.matchAll(/\bIcons\.([A-Za-z0-9_$]+)/g)) {
+      if (m[1] && !exported.has(m[1])) problems.push({ line, ref: `Icons.${m[1]}` });
+    }
+
+    // Braces only: `import * as Icons from …` is the correct namespace form, and a
+    // bare `import '…/icons'` binds nothing.
+    const imported = /\bimport\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/.exec(text);
+    const specifier = imported?.[2];
+    if (imported && specifier && ICONS_MODULE.test(specifier)) {
+      for (const name of namedBindings(imported[1] ?? '', 'import')) {
+        if (!exported.has(name)) problems.push({ line, ref: `{ ${name} } from '${specifier}'` });
+      }
+    }
+  });
+
+  return problems;
+}
+
+const ICON_EXPORTS = iconExportUnion();
+
+const SCANNED = [
+  ...walk(SRC),
+  ...walk(join(REPO_ROOT, 'docs')),
+  join(REPO_ROOT, 'README.md'),
+  join(REPO_ROOT, 'AGENTS.md'),
+];
+
+/**
+ * This file is the one exclusion, and it has to be: it SPELLS the mistakes it
+ * forbids — in its probes, in the doc comment above, and in the `Icons.${…}`
+ * template that formats a finding. Nothing outside a test copies an example out of
+ * a test. The list is pinned to exactly one path in the first assertion below, so
+ * it can neither grow quietly nor become a silent no-op through a typo.
+ */
+const EXCLUDED = [join(__dirname, 'icon-references.test.ts')];
+const CHECKED = SCANNED.filter((file) => !EXCLUDED.includes(file));
+
+describe('icon reference integrity', () => {
+  it('reads a plausible repo — neither list may be empty or truncated', () => {
+    // Without these floors a broken traversal or a broken extractor makes every
+    // assertion below pass by finding nothing at all.
+    expect(ICON_EXPORTS.size).toBeGreaterThan(200);
+    expect(CHECKED.length).toBeGreaterThan(300);
+    expect(CHECKED).toContain(join(SRC, 'tab-bar', 'types.ts'));
+    expect(CHECKED).toContain(join(REPO_ROOT, 'docs', 'tab-bar.mdx'));
+
+    // Exactly one file is exempt, and it really is in the scan — a misspelled path
+    // here would make the exemption a no-op and the suite fail on itself instead.
+    expect(EXCLUDED).toHaveLength(1);
+    expect(SCANNED).toContain(EXCLUDED[0]);
+    expect(CHECKED).not.toContain(EXCLUDED[0]);
+  });
+
+  it('collects every export shape src/icons uses, types included', () => {
+    // The suffixed component itself, the helpers, and the two TYPE exports that an
+    // earlier version of this check mistook for phantom references.
+    for (const name of [
+      'Home_Stroke2_Corner0_Rounded',
+      'PlusLarge_Stroke2_Corner0_Rounded',
+      'sizes',
+      'useCommonSVGProps',
+      'createSinglePathSVG',
+      'IconStyle',
+      'Props',
+    ]) {
+      expect([...ICON_EXPORTS]).toContain(name);
+    }
+    // And nothing shortened is in there, which is the premise of the whole test.
+    expect(ICON_EXPORTS.has('Home')).toBe(false);
+    expect(ICON_EXPORTS.has('Icons')).toBe(false);
+  });
+
+  it('resolves the export/import directions of `as` correctly', () => {
+    // `export { A as B }` publishes B; `import { A as B }` reads A.
+    expect(exportedNames("export { TimesLarge_Stroke2_Corner0_Rounded as X } from './Times';")).toEqual(
+      ['X'],
+    );
+    expect(namedBindings('Check_Stroke2_Corner0_Rounded as CheckIcon', 'import')).toEqual([
+      'Check_Stroke2_Corner0_Rounded',
+    ]);
+  });
+
+  it('flags the two mistakes that have actually been made', () => {
+    const probe = [
+      "import { Icons } from '@oxyhq/bloom/icons';",
+      'const a = <Icons.Home />;',
+      "import { Bell, Home } from '@oxyhq/bloom/icons';",
+      " * A doc comment saying `<Icons.Lock size=\"sm\" />`, which is where four of these lived.",
+    ].join('\n');
+
+    expect(unresolvedIconRefs(probe, ICON_EXPORTS)).toEqual([
+      { line: 1, ref: "{ Icons } from '@oxyhq/bloom/icons'" },
+      { line: 2, ref: 'Icons.Home' },
+      { line: 3, ref: "{ Bell } from '@oxyhq/bloom/icons'" },
+      { line: 3, ref: "{ Home } from '@oxyhq/bloom/icons'" },
+      { line: 4, ref: 'Icons.Lock' },
+    ]);
+  });
+
+  it('leaves every correct form alone', () => {
+    const probe = [
+      "import * as Icons from '@oxyhq/bloom/icons';",
+      "import { Icons } from '@oxyhq/bloom';",
+      'const a = <Icons.Home_Stroke2_Corner0_Rounded />;',
+      "import { Check_Stroke2_Corner0_Rounded as CheckIcon } from '../icons/Check';",
+      "import { type IconStyle, type Props as SVGIconProps } from '../icons/common';",
+      '| `Icons` | `export * as Icons` | keep namespace | `Icons.*` |',
+      "import { useState } from 'react';",
+    ].join('\n');
+
+    expect(unresolvedIconRefs(probe, ICON_EXPORTS)).toEqual([]);
+  });
+
+  it('every icon reference in src, docs, README and AGENTS resolves', () => {
+    const problems = CHECKED.flatMap((file) =>
+      unresolvedIconRefs(readFileSync(file, 'utf8'), ICON_EXPORTS).map(
+        ({ line, ref }) => `${relative(REPO_ROOT, file)}:${line}  ${ref}`,
+      ),
+    );
+
+    expect(problems).toEqual([]);
+  });
+});

package/src/benefit-list/types.ts

@@ -4,7 +4,8 @@ import type { StyleProp, TextStyle, ViewStyle } from 'react-native';
 export interface BenefitRowProps {
   /**
    * Leading icon — rendered inside a rounded `fill-secondary` square. Pass a
-   * Bloom icon element (e.g. `<Icons.Lock size="sm" />`) or any node.
+   * Bloom icon element (e.g. `<Icons.Lock_Stroke2_Corner0_Rounded size="sm" />`,
+   * suffix included — there is no shortened alias) or any node.
    */
   icon: ReactNode;
   /**

package/src/fab/types.ts

@@ -63,8 +63,10 @@ export interface FabProps {
 
   /**
    * The icon to render inside the FAB. Typically a Bloom icon element
-   * (`<Icons.Plus .../>`). For an icon-only FAB this is the whole content; for
-   * the extended variant it sits to the left of the `label`.
+   * (`<Icons.PlusLarge_Stroke2_Corner0_Rounded />` — icon exports carry their full
+   * style and corner suffix, and there is no shortened alias). For an icon-only
+   * FAB this is the whole content; for the extended variant it sits to the left of
+   * the `label`.
    *
    * `children` is accepted as an alias/override of `icon` for ergonomics — if
    * both are given, `icon` wins and `children` is ignored.

package/src/frosted-icon-button/shared.ts

@@ -106,7 +106,7 @@ type FillableElement = ReactElement<{ fill?: unknown }>;
  * Inject `color` as the icon's `fill` — but only as a FALLBACK: if the caller
  * already set an explicit `fill` on the icon element, it wins and the node is
  * returned untouched. Bloom icons resolve their paint as `fill ?? style.color`,
- * so a bare `<Icons.X />` gets the theme-aware color for free while an
+ * so any bare Bloom icon element gets the theme-aware color for free while an
  * explicitly-colored icon is never overridden. Non-element children (plain
  * text/strings) pass through unchanged.
  */

package/src/frosted-icon-button/types.ts

@@ -18,7 +18,8 @@ export interface FrostedIconButtonProps {
 
   /**
    * The icon to render, centered inside the circle. Typically a Bloom icon
-   * element (`<Icons.ArrowLeft… />`). If the icon does not set its own `fill`,
+   * element (`<Icons.ArrowLeft_Stroke2_Corner0_Rounded />` — icon exports carry
+   * their full style and corner suffix). If the icon does not set its own `fill`,
    * the button injects the theme-aware icon color (foreground when frosted,
    * `primaryForeground` when `active`) as a fallback so a bare icon is colored
    * correctly out of the box; an explicit `fill` on the icon always wins.

package/src/tab-bar/surface-solid.tsx

@@ -0,0 +1,40 @@
+/**
+ * Ported from expo-glass-tabs v0.1.1 — src/glass-tab-bar.tsx
+ * (MIT © 2026 David Mokos). See the top-level NOTICE.
+ *
+ * The tab bar's NON-GLASS capsule surface: a plain animated view filled with the
+ * theme's near-opaque fallback. Android, pre-iOS-26 devices and any build without
+ * a usable `expo-glass-effect` all paint this.
+ *
+ * It lives in its own module because TWO variants render it and one of them
+ * cannot reach the other: Metro resolves a bare `./surface` to
+ * `surface.native.tsx` no matter which file asks, so `surface.native.tsx`
+ * importing its neutral sibling for the fallback would import ITSELF. A name with
+ * no platform variants resolves to this one file everywhere — which is the whole
+ * point, so please do not fold it back into `surface.tsx`.
+ */
+import { StyleSheet } from 'react-native';
+import Animated from 'react-native-reanimated';
+
+import type { TabBarSurfaceProps } from './shared';
+
+export function SolidTabBarSurface({ theme, style }: TabBarSurfaceProps) {
+  return (
+    <Animated.View
+      style={[
+        StyleSheet.absoluteFill,
+        styles.surface,
+        { backgroundColor: theme.solidFallback },
+        style,
+      ]}
+    />
+  );
+}
+
+SolidTabBarSurface.displayName = 'SolidTabBarSurface';
+
+const styles = StyleSheet.create({
+  surface: {
+    borderCurve: 'continuous',
+  },
+});

package/src/tab-bar/surface.native.tsx

@@ -2,7 +2,8 @@
  * Ported from expo-glass-tabs v0.1.1 — src/glass-tab-bar.tsx
  * (MIT © 2026 David Mokos). See the top-level NOTICE.
  *
- * NATIVE variant of the tab bar's capsule surface — real liquid glass.
+ * NATIVE variant of the tab bar's capsule surface — real liquid glass, degrading
+ * to the solid surface whenever the glass is not actually usable.
  *
  * `expo-glass-effect` is imported STATICALLY and this file is the only place it
  * appears: Metro selects `.native` on iOS/Android, so the import never reaches
@@ -14,18 +15,88 @@
  *
  * `isLiquidGlassAvailable()` is false on Android and pre-iOS-26, where the
  * package's `GlassView` has no material to render; those platforms get the same
- * opaque fallback the neutral variant paints.
+ * opaque fallback the neutral variant paints. "Installed" is not "usable"
+ * though, and BOTH remaining hazards sit at MODULE scope, which is why neither
+ * can be handled by a branch inside the component:
+ *
+ *  1. THE NATIVE MODULE. On iOS `isLiquidGlassAvailable()` resolves
+ *     `ExpoGlassEffect` through `requireNativeModule`, which THROWS
+ *     `Cannot find native module …` by contract when that module is not in the
+ *     binary. For these apps it is a normal deploy state rather than a
+ *     misconfiguration: an OTA JS update can land on a binary built before the
+ *     package was linked, while the JS side always resolves because expo-router
+ *     depends on it. Unguarded, the throw escapes render and takes down the whole
+ *     screen the bar is on.
+ *  2. THE EXPORTS. `Animated.createAnimatedComponent(GlassView)` runs at IMPORT
+ *     time, so a tree that resolves the specifier to something without
+ *     `GlassView` hands React an `undefined` element type before any render
+ *     happens.
+ *
+ * `isGlassEffectAPIAvailable()` is upstream's own third condition: on some iOS 26
+ * betas `UIGlassEffect` is missing and touching `GlassView` crashes NATIVELY,
+ * below JS (expo/expo#40911). It first shipped in expo-glass-effect 0.1.9, which is
+ * exactly why the peer floor is `>=0.1.9`: this file imports the symbol STATICALLY,
+ * and a floor predating it would be the same incoherence as declaring a
+ * statically-imported package optional. The `typeof` guard below is still not
+ * redundant — a peer range only WARNS, so a consumer can resolve an older copy
+ * anyway. A missing probe therefore means "not applicable", never "unavailable";
+ * reading it the other way would delete the glass look from every working device.
+ *
+ * Everything that fails routes to the SAME solid surface Android already paints —
+ * the intended fallback path, not a new one.
  */
-import { GlassView, isLiquidGlassAvailable } from 'expo-glass-effect';
+import { GlassView, isGlassEffectAPIAvailable, isLiquidGlassAvailable } from 'expo-glass-effect';
 import { StyleSheet } from 'react-native';
 import Animated from 'react-native-reanimated';
 
 import type { TabBarSurfaceProps } from './shared';
+import { SolidTabBarSurface } from './surface-solid';
+
+/**
+ * The animated glass view, or `null` when the package did not deliver the two
+ * exports this file needs. Built once, and guarded HERE rather than in the
+ * component because `createAnimatedComponent` runs on import (hazard 2 above).
+ */
+const AnimatedGlassView =
+  Boolean(GlassView) && typeof isLiquidGlassAvailable === 'function'
+    ? Animated.createAnimatedComponent(GlassView)
+    : null;
 
-const AnimatedGlassView = Animated.createAnimatedComponent(GlassView);
+/** Memo for {@link glassIsUsable} — the answer cannot change within a session. */
+let glassUsable: boolean | undefined;
+
+/**
+ * Whether this build can really render glass. Probed once: the native lookup
+ * behind it is not free, and on the failing path it throws.
+ *
+ * The `catch` reports rather than swallows. A bar that silently painted itself
+ * opaque on every iOS device would be far more expensive to find than one warning
+ * line, and reaching this branch always means a real, fixable packaging mistake.
+ * Warning exactly once falls out of the memo — the body runs at most one time.
+ */
+function glassIsUsable(): boolean {
+  if (glassUsable !== undefined) return glassUsable;
+
+  try {
+    glassUsable =
+      isLiquidGlassAvailable() &&
+      (typeof isGlassEffectAPIAvailable !== 'function' || isGlassEffectAPIAvailable());
+  } catch (error) {
+    glassUsable = false;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[Bloom] TabBar: expo-glass-effect could not report liquid-glass availability, ' +
+        'so the bar is painting its solid surface. Install expo-glass-effect and ' +
+        'rebuild the native app to get the glass capsule.',
+      error,
+    );
+  }
+
+  return glassUsable;
+}
 
 export function TabBarSurface({ theme, style }: TabBarSurfaceProps) {
-  if (isLiquidGlassAvailable()) {
+  if (AnimatedGlassView !== null && glassIsUsable()) {
     return (
       <AnimatedGlassView
         glassEffectStyle="regular"
@@ -39,16 +110,7 @@ export function TabBarSurface({ theme, style }: TabBarSurfaceProps) {
     );
   }
 
-  return (
-    <Animated.View
-      style={[
-        StyleSheet.absoluteFill,
-        styles.surface,
-        { backgroundColor: theme.solidFallback },
-        style,
-      ]}
-    />
-  );
+  return <SolidTabBarSurface theme={theme} style={style} />;
 }
 
 TabBarSurface.displayName = 'TabBarSurface';

package/src/tab-bar/surface.tsx

@@ -2,8 +2,7 @@
  * Ported from expo-glass-tabs v0.1.1 — src/glass-tab-bar.tsx
  * (MIT © 2026 David Mokos). See the top-level NOTICE.
  *
- * NEUTRAL default variant of the tab bar's capsule surface: a plain animated
- * view filled with the theme's solid fallback.
+ * NEUTRAL default variant of the tab bar's capsule surface: the non-glass one.
  *
  * This is the file resolved by everything that does NOT do React Native's
  * platform-extension resolution — a consumer's `tsc` (which follows Bloom's
@@ -14,34 +13,16 @@
  * resolution outright. Same three-way split, for the same reason, as
  * `theme/native-root-vars{,.native,.web}.ts`.
  *
+ * The surface itself lives in `surface-solid.tsx`, because `surface.native.tsx`
+ * renders it as its own fallback and cannot import this file to get it — Metro
+ * resolves `./surface` back to `surface.native.tsx`, i.e. to itself. This module's
+ * job is to give that one implementation the name every entry module imports.
+ *
  * The variants — all three implement `TabBarSurfaceProps` exactly, so the entry
  * modules can swap them freely:
- *   - `surface.native.tsx` — iOS/Android (Metro), real `UIGlassEffect` glass;
+ *   - `surface.native.tsx` — iOS/Android (Metro), real `UIGlassEffect` glass, with
+ *     the solid surface as its fallback;
  *   - `surface.web.tsx`    — web, a CSS `backdrop-filter`;
- *   - this file            — everywhere else, the opaque fallback.
+ *   - this file            — everywhere else, the opaque fallback alone.
  */
-import { StyleSheet } from 'react-native';
-import Animated from 'react-native-reanimated';
-
-import type { TabBarSurfaceProps } from './shared';
-
-export function TabBarSurface({ theme, style }: TabBarSurfaceProps) {
-  return (
-    <Animated.View
-      style={[
-        StyleSheet.absoluteFill,
-        styles.surface,
-        { backgroundColor: theme.solidFallback },
-        style,
-      ]}
-    />
-  );
-}
-
-TabBarSurface.displayName = 'TabBarSurface';
-
-const styles = StyleSheet.create({
-  surface: {
-    borderCurve: 'continuous',
-  },
-});
+export { SolidTabBarSurface as TabBarSurface } from './surface-solid';

package/src/tab-bar/types.ts

@@ -19,9 +19,12 @@ export type TabBarItem = {
   /** Text under the icon; fades out and is clipped when the bar minimizes. */
   label: string;
   /**
-   * The glyph, as a Bloom icon element (`<Icons.Home />`) or any node. This is
-   * the primary icon API — same convention as `Tabs`/`TabsTrigger` and
-   * `FrostedIconButton`. The bar renders it TWICE (an inactive layer with the
+   * The glyph, as a Bloom icon element (`<Icons.Home_Stroke2_Corner0_Rounded />`)
+   * or any node. Every `@oxyhq/bloom/icons` export carries its full style and
+   * corner suffix; a shortened `Home` is not an export, and a name that does not
+   * exist is simply `undefined`, which React then rejects as an invalid element
+   * type. This is the primary icon API — same convention as `Tabs`/`TabsTrigger`
+   * and `FrostedIconButton`. The bar renders it TWICE (an inactive layer with the
    * active layer crossfading on top), injecting the layer's tint as the icon's
    * `fill` unless the element already sets one.
    */