@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/styles.mdx

@@ -0,0 +1,61 @@
+---
+title: Styles
+description: Atoms, tokens, breakpoints and the platform helpers — for styles a className cannot express.
+order: 74
+---
+
+# Styles
+
+`@oxyhq/bloom/styles` holds the style primitives Bloom itself uses.
+
+```tsx
+import { atoms as a, tokens, BREAKPOINTS, web, native, select } from '@oxyhq/bloom/styles';
+```
+
+## `atoms`
+
+Utility style objects — `a.flex_1`, `a.flex_row`, `a.align_center`, `a.px_sm`.
+They are the inline equivalent of the Tailwind utilities, and they exist
+because **a className is inert on web without the consumer's Tailwind
+pipeline**. Anything Bloom must draw correctly with or without that pipeline
+uses atoms; layout that only apps compose can use classes.
+
+## `tokens`
+
+The t-shirt view of the scales — `tokens.space.lg`, `tokens.borderRadius.xl`.
+
+The numbers themselves live in `design-tokens/scales.ts` and are read from
+there by reference, so a rung cannot exist in one spelling and not the other.
+They did once diverge: `borderRadius.full` was 999 against `radius-max` 9999,
+and each file's comments claimed to match the other.
+
+Prefer the numeric names (`radius-20`) when you are naming a rung in an API —
+[`Card`](/docs/bloom/main/card)'s `radius` prop takes those — and the t-shirt
+names in ad-hoc inline style.
+
+## `BREAKPOINTS`
+
+The shared widths, so a component and the screen around it agree about when the
+layout changes.
+
+## `web` / `native` / `ios` / `android` / `platform` / `select`
+
+Platform-conditional style helpers. Use them for a genuine platform difference
+— a shadow, a font smoothing, a scrollbar — and not to work around something
+that should be the same on both.
+
+## `Z_INDEX`
+
+**Within-context values only.** Which overlay paints on top is decided by the
+overlay stack, not by a constant: `overlay/stack.ts` ranks surfaces by when
+they OPENED, and a per-component z-index answers that question by what a
+surface *is*, which leaves some pairings permanently inverted.
+
+Never give an overlay surface a `zIndex` of its own.
+
+## `flatten`
+
+`StyleSheet.flatten` re-exported for code that already depends on the RN
+runtime. A raw-DOM web fork should use `flattenWebStyle()` instead — jest's RN
+mock stubs `StyleSheet.flatten` as identity, so the array form would survive
+and crash the DOM with `Failed to set an indexed property [0]`.

package/docs/subtle-hover.mdx

@@ -0,0 +1,53 @@
+---
+title: SubtleHover
+description: The hover wash behind a row — one tint, so every hoverable row matches.
+order: 64
+---
+
+# SubtleHover
+
+A faint fill that appears behind its parent's content on hover. It is what
+makes a list row feel hoverable without a border or a shadow.
+
+```tsx
+import { SubtleHover } from '@oxyhq/bloom/subtle-hover';
+
+<Pressable onPress={open} onHoverIn={…} onHoverOut={…}>
+  <SubtleHover active={hovered} />
+  <Row />
+</Pressable>
+```
+
+## Which prop decides what
+
+| prop     | decides                                                     |
+| -------- | ------------------------------------------------------------ |
+| `active` | whether the wash is shown — the caller owns the hover state   |
+| `native` | whether it also renders on native, where there is no hover    |
+
+## It does not detect hover
+
+The caller does. That is deliberate: what counts as "hovered" depends on the
+row — sometimes it is the row itself, often it is a larger container, and
+occasionally it should stay lit while a menu opened from the row is up. A
+component that owned the detection could not express the third case at all.
+
+## `native` defaults off, because hover does not exist there
+
+On touch there is no hover state to reflect, and a wash that appears on press
+duplicates the press feedback the row already has. Turn it on only for a native
+surface that genuinely has a pointer — an iPad with a trackpad, a keyboard
+focus ring you are mirroring.
+
+## One tint, everywhere
+
+The value of this component is not the effect, which is three lines of style —
+it is that every hoverable row in the ecosystem uses the *same* wash. Rolling
+your own is how a menu and a list on the same screen end up hovering in
+different greys.
+
+## Not a substitute for focus
+
+Hover is for pointers. A keyboard user needs a visible focus state, which is a
+separate thing and must not be styled away — a row that only responds to hover
+is invisible to anyone navigating with a keyboard.

package/docs/surfaces.mdx

@@ -0,0 +1,72 @@
+---
+title: Surfaces
+description: The one imperative overlay API — alert, confirm, prompt, and the stack they present onto.
+order: 36
+---
+
+# Surfaces
+
+The surface stack is Bloom's **one** imperative overlay API. `alert()`,
+`confirm()` and `prompt()` present from anywhere — no ref, no local `open`
+state, no second provider — and a single `<SurfaceHost>` renders whatever is on
+the stack.
+
+```tsx
+import { alert, confirm, prompt } from '@oxyhq/bloom/surfaces';
+
+alert('Saved', 'Your changes are live.');
+
+if (await confirm({ title: 'Leave this page?', confirmLabel: 'Leave' })) {
+  router.back();
+}
+
+const name = await prompt({ title: 'Name this list', placeholder: 'Reading list' });
+```
+
+## Why these are not components
+
+They are answers to a **question**, so the call site wants a value back, and a
+component you have to mount cannot be awaited. `confirm()` resolves to a
+boolean and `prompt()` to a string or `null`. That difference is the whole
+reason this API exists beside [`Dialog`](/docs/bloom/main/dialog):
+
+- **Surfaces** — a one-shot question from inside an event handler, in code
+  that has no render tree of its own (a mutation callback, a service).
+- **Dialog** — a surface with real content that belongs to a screen.
+
+## Mounting
+
+`<SurfaceProvider>` wraps the app; `<SurfaceHost>` renders the stack. **Both
+stay out of `BloomProvider`** — where an outlet sits is an app decision, and a
+second mount would duplicate every surface.
+
+## Two calls in a row STACK, they do not queue
+
+```tsx
+alert('First');
+alert('Second');   // paints over the first; dismissing reveals it
+```
+
+If you want them one after the other, `await` the first. This is deliberate: a
+queue would delay an urgent surface behind a trivial one, and there is no
+general rule for which of two surfaces matters more.
+
+## `present()` is the general form
+
+```tsx
+const size = await present<string>(
+  (surface) => <SizeList onPick={(s) => surface.dismiss(s)} />,
+  { placement: 'bottom', title: 'Pick a size', label: 'Pick a size' },
+);
+```
+
+The content resolves the promise by calling `surface.dismiss(value)`. Note what
+it does **not** call: `Dialog`'s own `close()`. The value has to reach the
+`present()` promise, and it resolves on the press — a surface closed any other
+way resolves with nothing, which reads as the user having cancelled.
+
+## Buttons
+
+A built-in surface's buttons carry `shouldCloseOnPress: false` and dismiss
+through `surface.dismiss(result)` for that reason. A `'cancel'` colour on a
+`DialogAction` is purely visual; it does not make the button dismiss.

package/docs/switch.mdx

@@ -0,0 +1,90 @@
+---
+title: Switch
+description: An immediate on/off toggle — why it must carry `aria-checked` rather than `accessibilityState`, and why it cannot name itself.
+order: 24
+---
+
+# Switch
+
+A binary control whose change takes effect **immediately**. That is the whole
+distinction from a checkbox: a switch turns something on, a checkbox records an
+intent you confirm later with a Save button.
+
+```tsx
+import { Switch } from '@oxyhq/bloom/switch';
+
+<Switch
+  value={pushEnabled}
+  onValueChange={setPushEnabled}
+  accessibilityLabel="Push notifications"
+/>
+```
+
+## Which prop decides what
+
+| prop                 | decides                                       |
+| -------------------- | --------------------------------------------- |
+| `value`              | on or off — the component is fully controlled  |
+| `onValueChange`      | receives the **opposite** of the current value |
+| `disabled`           | dims it and takes it out of the tab order      |
+| `size`               | `default` (44×26) or `sm` (36×22)              |
+| `accessibilityLabel` | what it announces as — see below               |
+
+There is no uncontrolled mode. A switch whose state the caller does not own is a
+switch that can disagree with the thing it is supposed to be controlling — the
+classic version being an optimistic toggle that stays on after the request
+failed.
+
+## A switch needs a label it does not draw
+
+`Switch` renders a track and a thumb and nothing else, so there is no text for
+either platform to compute a name from. **`accessibilityLabel` is the only
+route to one.** Without it the control announces "switch, on" and never says
+which of the settings on the page it belongs to.
+
+The caption next to it does not do this job. A `SettingsListItem` title, a
+`Label`, a `Text` in the same row — all of them are SIBLING elements, and
+neither React Native nor react-native-web associates a sibling with a control.
+So the row below needs the label even though the words are already on screen:
+
+```tsx
+<SettingsListItem
+  title="Push notifications"
+  rightElement={
+    <Switch
+      value={push}
+      onValueChange={setPush}
+      accessibilityLabel="Push notifications"
+    />
+  }
+  showChevron={false}
+/>
+```
+
+One spelling covers both platforms, and it is not the same rule as the state
+below: react-native-web emits `aria-label` from `accessibilityLabel` when no
+`aria-label` is given, and React Native reads it directly.
+
+Omitting it warns once per component in development. The warning is dev-only
+(`process.env.NODE_ENV`, folded out of production bundles) and never throws — an
+unnamed switch still renders and still toggles. An empty or whitespace-only
+label counts as missing, because `aria-label=""` names nothing.
+
+## The accessibility rule this component is the reference for
+
+`Switch` sets `role="switch"` and **`aria-checked`**, not
+`accessibilityState={{ checked }}`.
+
+react-native-web drops `accessibilityState` entirely and reads only `aria-*`,
+while React Native folds `aria-checked` back into `accessibilityState`. So
+`aria-checked` is the one spelling that works on both platforms, and a control
+that set only `accessibilityState` would render a switch role carrying no
+state — drawn correctly, announced as nothing.
+
+The disabled state is the mirror image and goes the other way: it travels on
+the `disabled` **prop**, because react-native-web's `Pressable` appends its own
+`aria-disabled` *after* spreading the caller's props, so a hand-written one is
+silently overwritten.
+
+Neither of these is visible to a prop-level test. Assert the rendered
+attribute.

package/docs/tab-bar.mdx

@@ -0,0 +1,386 @@
+---
+title: TabBar
+description: A floating, minimize-on-scroll tab bar with a sliding highlight, liquid glass on iOS 26 and a backdrop-filter on web.
+order: 19
+---
+
+# TabBar
+
+A floating tab bar that sits over your content instead of boxing it in. It minimizes as you scroll down and re-expands as you scroll up, its highlight slides between tabs and can be scrubbed with a finger, and its capsule renders as real liquid glass on iOS 26, a CSS `backdrop-filter` on web, and a solid themed fill everywhere else.
+
+It works with or without a router. `@oxyhq/bloom/tab-bar` has no router dependency at all; the expo-router bindings live in a separate `@oxyhq/bloom/tab-bar/expo-router` subpath.
+
+## Install
+
+The tab bar adds three peers on top of Bloom's usual ones:
+
+```bash
+bunx expo install expo-glass-effect expo-symbols react-native-screens
+```
+
+| Peer | Used by | Needed when |
+|------|---------|-------------|
+| `expo-glass-effect` | `tab-bar/surface.native` | Any native build that renders the bar. Its NATIVE module is Apple-only (`"platforms": ["apple"]`) and provides the iOS 26 liquid-glass capsule; on Android the package is pure JS, its own `isLiquidGlassAvailable()` answers `false`, and the bar paints the solid themed fill instead. A build whose native module is missing altogether — an OTA JS update landing on a binary built before the package was linked — degrades to that same solid fill and logs one `[Bloom]` warning, rather than throwing out of render. |
+| `expo-symbols` | `tab-bar/glyph.native` | Any native build that renders the bar. Apple-only as well: it draws `item.sfSymbol` as a real SF Symbol on iOS, and the bar falls back to `item.icon` everywhere else. |
+| `react-native-screens` | `tab-bar/expo-router` | Only if you use `renderFadingTabScreen`. |
+
+The bar also uses Bloom's existing `expo-blur`, `react-native-reanimated`, `react-native-gesture-handler` and `react-native-safe-area-context` peers. Native apps must wrap their root in `GestureHandlerRootView` — the bar is scrubbable, so it needs gesture-handler mounted.
+
+<Callout variant="info" title="Web builds pull none of the native packages">
+`expo-glass-effect` and `expo-symbols` are imported only from `.native` files, and the router packages only from the `expo-router` subpath. A web bundle of `@oxyhq/bloom/tab-bar` reaches none of them, so nothing about them ends up in a web app's output.
+
+Both are nonetheless declared as **required** peers, deliberately. They are static imports, so omitting them from a native build that imports the tab bar does not degrade to anything — Metro fails to resolve the specifier and the build dies. The only thing marking them optional would buy is silencing the one warning that says so in advance. That applies on Android too: the native module there is Apple-only (`"platforms": ["apple"]`), but the JS package still has to be installed for the bundle to resolve.
+
+That degrade-to-nothing only follows once you import the tab bar. An app that never imports `@oxyhq/bloom/tab-bar` at all — on native or web — never reaches these files, so leaving the peer unmet costs nothing; don't install two Apple-only packages just to quiet a warning about a surface you don't use. In practice bun 1.3.14 doesn't even print that warning, so the gap is silent regardless of whether you use the tab bar.
+</Callout>
+
+## Usage without a router
+
+Drive it like any controlled component: pass `activeIndex`, handle `onIndexChange`.
+
+```tsx
+import { useState } from 'react';
+import * as Icons from '@oxyhq/bloom/icons';
+import { TabBar, TabBarButton, TabBarMinimizeProvider } from '@oxyhq/bloom/tab-bar';
+
+const TABS = [
+  { name: 'home', label: 'Home', icon: <Icons.Home_Stroke2_Corner0_Rounded /> },
+  { name: 'search', label: 'Search', icon: <Icons.MagnifyingGlass_Stroke2_Corner0_Rounded /> },
+  { name: 'you', label: 'You', icon: <Icons.UserCircle_Stroke2_Corner0_Rounded /> },
+];
+
+export function Shell() {
+  const [index, setIndex] = useState(0);
+
+  return (
+    <TabBarMinimizeProvider>
+      <Screen index={index} />
+      <TabBar activeIndex={index} onIndexChange={setIndex}>
+        {TABS.map((item, i) => (
+          <TabBarButton key={item.name} item={item} index={i} />
+        ))}
+      </TabBar>
+    </TabBarMinimizeProvider>
+  );
+}
+```
+
+`TabBarMinimizeProvider` wraps the whole tab tree once, so any screen that calls `useMinimizeOnScroll()` drives the same bar. It is optional — without it each consumer falls back to its own local progress, which keeps a screen working when it is rendered outside a tab layout.
+
+### No selection
+
+An `activeIndex` that names no tab — negative, past the last tab, or fractional — means **no selection**: the highlight fades out where it stands and no tab is left tinted. Returning to a real index fades it back in at that tab rather than sliding to it, since there was no visible position to travel from. Scrubbing and tapping still work from there: the finger arms the highlight and a release selects, exactly as when a tab was already picked.
+
+This is the state to use whenever the current screen is not a tab. An index derived from the route — `TABS.findIndex((tab) => tab.href === pathname)` — is `-1` on every screen outside the tab set, and passing it straight through is correct; there is nothing to special-case.
+
+<Callout variant="warning" title="Omitting `activeIndex` is NOT the same as no selection">
+Leaving the prop off entirely selects the focus-driven path, where each `TabBarButton` supplies `isFocused` and drives the highlight itself (this is what `RouterTabBar` does). That path always shows the highlight. Only a NUMBER that names no tab hides it.
+</Callout>
+
+## Usage with expo-router
+
+```tsx
+import * as Icons from '@oxyhq/bloom/icons';
+import { TabBarMinimizeProvider } from '@oxyhq/bloom/tab-bar';
+import {
+  RouterTabBar,
+  RouterTabBarButton,
+  renderFadingTabScreen,
+} from '@oxyhq/bloom/tab-bar/expo-router';
+import { Tabs, TabList, TabSlot, TabTrigger } from 'expo-router/ui';
+import { router } from 'expo-router';
+
+const TABS = [
+  { name: 'home', label: 'Home', href: '/', icon: <Icons.Home_Stroke2_Corner0_Rounded /> },
+  { name: 'search', label: 'Search', href: '/search', icon: <Icons.MagnifyingGlass_Stroke2_Corner0_Rounded /> },
+  { name: 'you', label: 'You', href: '/you', icon: <Icons.UserCircle_Stroke2_Corner0_Rounded /> },
+];
+
+export default function TabLayout() {
+  return (
+    <TabBarMinimizeProvider>
+      <Tabs>
+        <TabSlot style={{ height: '100%' }} renderFn={renderFadingTabScreen} />
+        <TabList asChild>
+          <RouterTabBar onIndexChange={(i) => router.navigate(TABS[i].href)}>
+            {TABS.map(({ href, ...item }, index) => (
+              <TabTrigger key={item.name} name={item.name} href={href} asChild>
+                <RouterTabBarButton item={item} index={index} />
+              </TabTrigger>
+            ))}
+          </RouterTabBar>
+        </TabList>
+      </Tabs>
+    </TabBarMinimizeProvider>
+  );
+}
+```
+
+Two things about this shape are load-bearing:
+
+- **Navigation runs through `onIndexChange`, not through the triggers.** The bar's gesture detector consumes the touches — that is what makes scrubbing possible — so a tap never reaches a trigger's own `Pressable`.
+- **`RouterTabBar` takes no `activeIndex`.** With a router the highlight is driven by each trigger's own focus, which is what keeps it correct through deep links, back gestures and any other programmatic navigation. Setting both would put two writers on one shared value.
+
+`renderFadingTabScreen` is a drop-in for `TabSlot`'s `renderFn`: identical to expo-router's default render, plus a fade and a micro-scale on the screen becoming focused. It is the only place `react-native-screens` is used.
+
+## Minimizing on scroll
+
+Screens opt in with `useMinimizeOnScroll()`, which returns a scroll handler for `Animated.ScrollView`. Scrolling down minimizes the bar to icons only; scrolling up, or being near the top, expands it.
+
+```tsx
+import Animated from 'react-native-reanimated';
+import { useMinimizeOnScroll } from '@oxyhq/bloom/tab-bar';
+
+export default function Feed() {
+  const onScroll = useMinimizeOnScroll();
+
+  return (
+    <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
+      {/* … */}
+    </Animated.ScrollView>
+  );
+}
+```
+
+For anything else that should react to the same progress — a header that fades with the bar, say — read the raw shared value:
+
+```tsx
+import { useTabBarMinimized } from '@oxyhq/bloom/tab-bar';
+
+const minimized = useTabBarMinimized(); // SharedValue<number>, 0 = expanded, 1 = minimized
+```
+
+<Callout variant="warning" title="List every shared value in your mapper's deps array">
+On web without the react-native-worklets babel plugin — the production reality for every Oxy RN-Web app — reanimated drives a mapper off its dependency array, not off auto-tracked reads. `useAnimatedStyle(() => ({ opacity: minimized.value }), [minimized])` animates; the same mapper with `[]` runs once and freezes at the first frame, with no error anywhere. Native ignores the extra deps, so listing them is correct on both platforms.
+</Callout>
+
+## Icons
+
+`item.icon` is the primary API and takes any node — a Bloom icon, an SVG, your own component — exactly like `TabsTrigger` and `FrostedIconButton`. The bar renders it twice per tab (an inactive layer with the active layer crossfading on top) and injects the layer's tint as the icon's `fill`. An icon that sets its own `fill` (a brand mark, say) keeps it, so both layers render it identically and it never flickers.
+
+`item.sfSymbol` is an **iOS-only enhancement**: when present, iOS renders the real system glyph instead, weight-matched to the platform and tinted natively. Android, web and every non-Metro resolver ignore it and render `item.icon`, so every item still needs one.
+
+```tsx
+const TABS = [
+  {
+    name: 'home',
+    label: 'Home',
+    icon: <Icons.Home_Stroke2_Corner0_Rounded />,
+    sfSymbol: 'house.fill',
+  },
+  {
+    name: 'you',
+    label: 'You',
+    icon: <Icons.UserCircle_Stroke2_Corner0_Rounded />,
+    sfSymbol: 'person.crop.circle',
+  },
+];
+```
+
+### Icon sets that change SHAPE when selected
+
+Tinting says everything an icon set needs to say only when its selected state *is* a different color. Plenty of sets — including Mention's — say it with a different **shape** instead: an outline glyph becomes a filled one, on a different path. A tint crossfade cannot express that, because both layers would draw the same path in two colors.
+
+`item.activeIcon` gives the crossfade a second node, so the outline dissolves into the fill:
+
+```tsx
+const TABS = [
+  {
+    name: 'home',
+    label: 'Home',
+    icon: <Home />,          // outline: fill="none" + stroke
+    activeIcon: <HomeActive />, // filled, different path
+  },
+];
+```
+
+It is optional and additive: an item with only `icon` renders it on both layers exactly as before. On iOS an item carrying `sfSymbol` renders the symbol on both layers and ignores `activeIcon` — a symbol is tinted natively, so the tint crossfade is still the right expression there.
+
+<Callout variant="warning" title="An icon that paints from a `color` prop never lights up">
+The bar tints a glyph by cloning the element with a `fill` prop. That is how Bloom's own icons (and raw SVG) take paint — they resolve `fill ?? style.color`. An icon set whose components read a **`color` prop** instead simply ignores the injected `fill`, and the result is a glyph that renders fine and never changes between the two layers. Nothing throws and nothing warns.
+
+Two ways out, both explicit: pass `activeIcon` so selection is carried by the shape rather than by the tint, or pre-color both nodes yourself (`icon={<Home color={inactive} />}`, `activeIcon={<HomeActive color={active} />}`) — an element that already has a `fill` is never overridden, and one that paints from `color` was never going to be.
+</Callout>
+
+## Long press
+
+The bar's gesture detector consumes its touches — that is what makes scrubbing possible — so a `TabBarButton`'s own `onLongPress` never fires for a real finger. `onIndexLongPress` on the **bar** is the way to get one:
+
+```tsx
+<TabBar
+  activeIndex={index}
+  onIndexChange={setIndex}
+  onIndexLongPress={(i) => TABS[i].name === 'you' && openAccountSheet()}
+>
+```
+
+It reports the index under the finger after a 500ms hold, resolved through the same geometry as a tap, and it does **not** select the tab — it is a secondary action (an account switcher on the profile tab, say), so the highlight stays where it was.
+
+The gesture joins the bar's gesture race only when you pass the prop. Without it, nothing about a held finger changes: you can still rest a finger and then scrub. With it, a hold that reaches 500ms wins the race and cancels the scrub — the tap is unaffected either way, since it gives up at 400ms, before the long press can activate.
+
+## Laying out around the bar
+
+The bar floats over your content (`position: absolute`), so nothing accounts for it. `useTabBarFootprint()` returns the space it physically occupies above the bottom of the window — its own height plus its own bottom offset, and nothing else:
+
+```tsx
+import { useMinimizeOnScroll, useTabBarFootprint } from '@oxyhq/bloom/tab-bar';
+
+export default function Feed() {
+  const onScroll = useMinimizeOnScroll();
+  const footprint = useTabBarFootprint();
+
+  return (
+    <>
+      <Animated.ScrollView
+        onScroll={onScroll}
+        scrollEventThrottle={16}
+        // The last row clears the pill by 12pt — that gap is yours, not Bloom's.
+        contentContainerStyle={{ paddingBottom: footprint + 12 }}
+      />
+      {/* A FAB anchored by `bottom` already carries its own gap: sit it right
+          on top of the footprint. */}
+      <Fab style={{ position: 'absolute', right: 16, bottom: footprint }} />
+    </>
+  );
+}
+```
+
+**No clearance is baked in.** Clearance is a per-call-site decision — a list wants breathing room above the pill, a FAB anchored by `bottom` supplies its own — and only you know which. Adding a margin inside the hook would place that FAB too high and make one word mean two things in a single file. Bloom returns the one number it actually knows.
+
+<Callout variant="warning" title="Never add `insets.bottom` to it">
+The value is measured from the true bottom of the window, because the bar folds the bottom safe-area inset into its own gap. `footprint + insets.bottom` — the reflex for anything anchored to the bottom edge — counts the home indicator twice and accounts 110pt for a 76pt bar, leaving a visible band of dead space under every list. Whatever you add on top is your own clearance, never the inset a second time.
+</Callout>
+
+It is the bar's **expanded** height, deliberately: the bar minimizes on the way down and re-expands on the way up, so measuring the minimized height would hide the end of a list the moment the user scrolled back to it.
+
+## Constraining the width on a tablet
+
+By default the bar spans the window. That is right on a phone and wrong on a tablet: an iPad 11" gives you an 810pt pill in portrait and 1342pt in landscape, with 21pt glyphs adrift in cells hundreds of points wide. `maxWidth` caps it and centres it:
+
+```tsx
+<TabBar activeIndex={index} onIndexChange={setIndex} maxWidth={480}>
+```
+
+There is **no default** — omit the prop and the bar is exactly the bar it has always been. The value is a **ceiling, never a floor**: a window narrower than it keeps the full-bleed bar, so you can pass one number unconditionally from a shared tab layout and phones are untouched.
+
+The important part is what comes with it: the item width, the sliding highlight's position and the tap / scrub / long-press hit-testing all derive from the **same** constrained width, so a tap still lands on the tab it is visibly over.
+
+<Callout variant="warning" title="Do not narrow the bar with `style` instead">
+`style={{ maxWidth: 480, alignSelf: 'center' }}` on the bar moves the pixels and nothing else. The highlight and the gesture worklet keep dividing the **window** width by the tab count, so the pill is sized and positioned for a bar that is no longer there — and on a wide window a tap near the right edge selects a tab two places to the left. `maxWidth` is a prop rather than something you can express in a style precisely because the geometry has to follow it.
+</Callout>
+
+Centring and the minimize animation compose without either knowing about the other: the constrained wrap is centred once by layout, and the pill's minimized inset stays a pair of equal animated margins **inside** it, so the bar shrinks about its own centre on the way down.
+
+## The blur behind the bar
+
+The bar draws a progressive blur rising from the bottom edge of the screen — the band content dissolves into instead of meeting the pill at a hard line. It is full-bleed and 114pt tall at a zero bottom inset (the bar's bottom gap + its expanded height + 44pt of bleed above it), which is taller than the bar itself.
+
+That matters if your screen floats its own chrome down there. A video scrubber, a compose FAB, a QR-scan button — anything inside that band is blurred, and **no `zIndex` gets it out**: z-order only sorts siblings within one stacking context, and your FAB lives inside the screen, which is an earlier sibling of the bar's host. Turn the band off instead:
+
+```tsx
+<TabBar activeIndex={index} onIndexChange={setIndex} blur={false}>
+```
+
+`false` renders no blur at all — not an invisible one, and not an empty absolutely-positioned view left behind. `true` (or omitting it) is the default. The object form tunes the strength on the same 0–100 `expo-blur` scale the standalone [`ProgressiveBlur`](#progressiveblur) uses, defaulting to 5:
+
+```tsx
+<TabBar activeIndex={index} onIndexChange={setIndex} blur={{ intensity: 2 }}>
+```
+
+The band stays full-bleed under `maxWidth`: it is the screen-edge scrim, not part of the pill, and constraining it would leave a floating blurred rectangle.
+
+## Theming
+
+Every color comes from the active `BloomThemeProvider` preset and mode — there is no hardcoded palette, so the bar follows a preset or a light/dark switch for free.
+
+| Role | Resolves from | Meaning |
+|------|---------------|---------|
+| `activeTint` | `colors.text` | Label and glyph of the tab the highlight is over. |
+| `inactiveTint` | `colors.textSecondary` | Label and glyph of every other tab. |
+| `highlight` | `colors.contrast50` | The sliding highlight pill. |
+| `glassTint` | `colors.background` at 55% | Tint layered over the liquid glass (iOS 26) or `backdrop-filter` (web) material. |
+| `solidFallback` | `colors.backgroundSecondary` at 94% | Near-opaque background used when there is no glass to lens. |
+
+Override any subset with the `theme` prop; the rest keep their token-derived values.
+
+```tsx
+<TabBar activeIndex={index} onIndexChange={setIndex} theme={{ highlight: 'rgb(255 0 128)' }}>
+```
+
+Overrides are coalesced key by key, so an explicit `undefined` in a partial can never punch a hole in the resolved theme.
+
+## Per-platform behaviour
+
+| Platform | Capsule surface | Blur behind the bar |
+|----------|-----------------|---------------------|
+| iOS 26 | Real `UIGlassEffect` liquid glass under `glassTint`, with the native corner configuration (true squircle + rim lighting) tracking the animated height. | Ten thin stacked `BlurView`s — iOS has no public variable-blur API, so the falloff is built from layer coverage. |
+| iOS &lt; 26, Android | Solid `solidFallback` fill. `isLiquidGlassAvailable()` reports `false`, so `GlassView` is never mounted. | Same ten-layer stack. |
+| Web | `backdrop-filter: blur(24px) saturate(180%)` under `glassTint`. Browsers without `backdrop-filter` simply skip it and keep the translucent tint. | One `backdrop-filter` faded with a `mask-image` — an order of magnitude cheaper than ten composited backdrop passes, and it traces the same curve as the native stack. |
+
+The capsule radius rides on the surface itself rather than on a clipping parent: iOS 26 glass renders its own native corner configuration, which an RN mask would flatten.
+
+## ProgressiveBlur
+
+The gradient blur behind the bar is also a standalone component. Use it behind any floating chrome — a transparent header, a docked composer — so content dissolves rather than meeting a hard blur line.
+
+```tsx
+import { ProgressiveBlur } from '@oxyhq/bloom/progressive-blur';
+
+<ProgressiveBlur
+  direction="top"
+  intensity={5}
+  style={{ position: 'absolute', top: 0, left: 0, right: 0, height: 120 }}
+/>;
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `direction?` | `'top' \| 'bottom'` | `'top'` | Which edge the blur is anchored to — strongest there, fading away. |
+| `intensity?` | `number` | `5` | Blur strength at the anchored edge, on `expo-blur`'s 0–100 scale. Applied per layer on native; the web fork maps it onto the single CSS blur radius that approximates the same stack. |
+| `style?` | `StyleProp<ViewStyle>` | — | Position and size it yourself; it has no intrinsic layout. |
+
+The tail gradient is derived from the theme's page background, so it works on light and dark alike.
+
+## TabBar props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | The `TabBarButton`s, in bar order. |
+| `activeIndex?` | `number` | — | **Controlled path.** The focused tab; an index that names no tab (`-1`, past the last, fractional) hides the highlight — see [No selection](#no-selection). Omit it with a router — use per-button `isFocused` instead. |
+| `onIndexChange?` | `(index: number) => void` | — | Called with the chosen index on tap, on scrub release, or on keyboard / assistive-technology activation. |
+| `onIndexLongPress?` | `(index: number) => void` | — | Called with the index under the finger after a 500ms hold. Does not select. The gesture is armed only when this is supplied. |
+| `theme?` | `Partial<TabBarTheme>` | — | Partial override of the token-resolved theme. |
+| `haptics?` | `boolean` | `true` | Picker-style tick as the scrub crosses tab boundaries. Already a no-op on web and when `expo-haptics` is absent. |
+| `blur?` | `boolean \| { intensity?: number }` | `true` | The progressive blur band behind the bar. `false` removes it entirely — the escape hatch for a FAB or scrubber that sits inside its 114pt reach. |
+| `maxWidth?` | `number` | — | Caps the pill's width and centres it, with the item geometry and the hit-testing following. A ceiling, never a floor: narrower windows keep the full-bleed bar. |
+
+Everything `View` accepts is forwarded.
+
+## TabBarButton props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `item` | `TabBarItem` | — | `{ name, label, icon, activeIcon?, sfSymbol? }`. |
+| `index` | `number` | — | Position in the bar. Must match the child order. |
+| `isFocused?` | `boolean` | — | **Focus-driven path**, supplied by the router adapter. When present it wins over the bar's `activeIndex` and this button drives the highlight. |
+
+Everything `Pressable` accepts is forwarded, including the function form of `style`.
+
+## Exports
+
+| Export | From | Description |
+|--------|------|-------------|
+| `TabBar`, `TabBarButton` | `@oxyhq/bloom/tab-bar` | The bar and its trigger. |
+| `TabBarMinimizeProvider` | `@oxyhq/bloom/tab-bar` | Shares one minimize progress across the tab tree. |
+| `useMinimizeOnScroll` | `@oxyhq/bloom/tab-bar` | Scroll handler for `Animated.ScrollView`. |
+| `useTabBarMinimized` | `@oxyhq/bloom/tab-bar` | The raw `SharedValue<number>`, 0…1. |
+| `useTabBarFootprint` | `@oxyhq/bloom/tab-bar` | Space the bar occupies at the bottom, safe-area included, no clearance added. |
+| `useMinimizeState`, `setMinimized`, `MINIMIZE_SPRING` | `@oxyhq/bloom/tab-bar` | Lower-level control of the same progress. |
+| `RouterTabBar`, `RouterTabBarButton`, `renderFadingTabScreen` | `@oxyhq/bloom/tab-bar/expo-router` | expo-router bindings. |
+| `ProgressiveBlur` | `@oxyhq/bloom/progressive-blur` | The gradient blur, standalone. |
+
+Types: `TabBarItem`, `TabBarProps`, `TabBarButtonProps`, `TabBarTheme`, `MinimizeState`, `ProgressiveBlurProps`.
+
+<Callout variant="info" title="TabBar vs Tabs">
+`TabBar` is app-level navigation chrome: floating, minimize-on-scroll, one per screen tree. For switching between panels *inside* a screen, reach for `Tabs` from `@oxyhq/bloom/tabs` instead — an inline, underlined control with no gestures and no surface of its own.
+</Callout>