@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/item.mdx

@@ -0,0 +1,69 @@
+---
+title: Item
+description: The one row primitive — and the `role` prop that decides how it is announced.
+order: 31
+---
+
+# Item
+
+A row: optional leading element, a title, an optional subtitle, an optional
+trailing element. It is what menus, option lists, comboboxes and settings rows
+are built from, so a row anywhere in the ecosystem has the same height, the same
+press feedback and the same disabled treatment.
+
+```tsx
+import { Item } from '@oxyhq/bloom/item';
+
+<Item
+  leading={<Avatar source={user.avatar} size={32} />}
+  title={user.displayName}
+  subtitle={`@${user.username}`}
+  trailing={selected ? <CheckIcon /> : null}
+  onPress={() => choose(user)}
+  role="option"
+/>
+```
+
+## Which prop decides what
+
+| prop          | decides                                                        |
+| ------------- | --------------------------------------------------------------- |
+| `title` / `subtitle` | the two text lines                                       |
+| `leading` / `trailing` | the slots on either side                               |
+| `children`    | replaces the title/subtitle block entirely                       |
+| `onPress`     | makes the row pressable                                          |
+| `role`        | **how it is announced** — see below                              |
+| `selected`    | the selected state, for `option` / `radio` rows                  |
+| `active`      | the "you are here" state, for navigation rows                    |
+| `density`     | `comfortable` (default) or `compact` for a dense list            |
+| `destructive` | paints the title in the error role                               |
+
+## `role` is the prop that matters
+
+A row looks the same in every context and means something different in each.
+`role` is how you say which:
+
+| `role`     | for                                            |
+| ---------- | ----------------------------------------------- |
+| `option`   | a choice in a listbox — a combobox, a picker     |
+| `radio`    | a mutually exclusive choice                     |
+| `menuitem` | an action in a menu                             |
+| `listitem` | a row in a plain list                           |
+
+Getting this wrong is invisible on screen and wrong in every screen reader: a
+combobox whose rows are `listitem` announces as a list, and the user is never
+told they are choosing.
+
+## `selected` and `active` are different states
+
+`selected` means *this is the chosen one* — a checkmark in a picker. `active`
+means *this is where you are* — the current route in a sidebar. They look
+similar and they are not the same claim: a sidebar row is active without the
+user having selected anything, and a picker row is selected whether or not it
+is focused.
+
+## `destructive` colours, it does not confirm
+
+It paints the title in the error role. It does not add a confirmation step —
+if the action is irreversible, `confirm()` from
+[`surfaces`](/docs/bloom/main/surfaces) is what asks.

package/docs/kbd.mdx

@@ -0,0 +1,57 @@
+---
+title: Kbd
+description: A keyboard key rendered as a key — in menus, palettes and help text.
+order: 44
+---
+
+# Kbd
+
+Renders a keyboard key with the raised-cap look, so a shortcut in running text
+reads as a key rather than as a stray capital letter.
+
+```tsx
+import { Kbd } from '@oxyhq/bloom/kbd';
+
+<Text>
+  Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the command palette.
+</Text>
+
+<Kbd size="sm">Esc</Kbd>
+```
+
+## Which prop decides what
+
+| prop   | decides                                          |
+| ------ | ------------------------------------------------- |
+| `size` | `sm` for inside a row or a menu, `md` for prose   |
+
+## One key per `Kbd`
+
+`⌘K` as a single child renders one wide cap, which is not what a keyboard looks
+like and not what the user has to press. Two keys, two `Kbd`s.
+
+## Use the platform's own symbols
+
+`⌘` on Apple platforms, `Ctrl` elsewhere; `⌥` versus `Alt`; `⇧` versus `Shift`.
+A shortcut written for the wrong platform is worse than none — the user presses
+a key that does nothing and concludes the feature is broken.
+
+`Kbd` renders what you give it; deciding which spelling to give it belongs to
+the app, which knows the platform.
+
+## It is decoration, not a control
+
+`Kbd` draws a key. It does not register a shortcut, and pressing it does
+nothing. Binding keys belongs to the app or the surface that owns the key
+handling — the same reason [`Command`](/docs/bloom/main/command)'s `shortcut`
+field is a hint rather than a binding.
+
+## Where it earns its place
+
+- A [`Command`](/docs/bloom/main/command) row, showing the shortcut for the
+  action.
+- A menu item, for the same reason.
+- Help and onboarding text, where the key is the instruction.
+
+Not in a tooltip on a touch device: a user with no keyboard reading about `⌘K`
+is being told about a feature they cannot reach.

package/docs/label.mdx

@@ -0,0 +1,50 @@
+---
+title: Label
+description: A control's name, wired to the control rather than merely sitting above it.
+order: 33
+---
+
+# Label
+
+The text that names a control. Use it when you are laying a form out yourself;
+[`Field`](/docs/bloom/main/field) renders one for you and handles the wiring.
+
+```tsx
+import { Label } from '@oxyhq/bloom/label';
+
+<Label nativeID="workspace-name" required>Workspace name</Label>
+<TextField>
+  <TextFieldInput nativeID="workspace-name" label="Workspace name" value={name} onChangeText={setName} />
+</TextField>
+```
+
+## Which prop decides what
+
+| prop       | decides                                                      |
+| ---------- | ------------------------------------------------------------- |
+| `nativeID` | the id the control points at — this is what makes it a label   |
+| `htmlFor`  | the reverse association on web                                |
+| `required` | the required marker, and that it is announced as required      |
+| `disabled` | dims it in step with the control                              |
+| `size`     | `xs` · `sm` · `md`                                            |
+
+## Without the wiring it is just text above a box
+
+A `<Text>` above an input is not a label: a screen reader reaches the input and
+announces "edit text, blank". The association is the whole feature — either
+through `nativeID`/`htmlFor` here, or by letting `Field` do it.
+
+On web it also buys a click target: clicking the label focuses the control.
+
+## `required` is a claim, not a decoration
+
+The marker and the announced requirement come from the same prop, so they
+cannot disagree. Do not draw your own asterisk beside the text — it is
+invisible to a screen reader and produces a field that looks required and
+announces as optional.
+
+## Do not use a label as a heading
+
+A label names a control. A section title above a group of fields is a heading;
+using `Label` for it makes a screen reader look for a control that is not
+there.

package/docs/link-preview.mdx

@@ -0,0 +1,66 @@
+---
+title: LinkPreviewCard
+description: An unfurled link — structural props, so Bloom never depends on the contracts package.
+order: 59
+---
+
+# LinkPreviewCard
+
+The card that renders an unfurled link: cover image, site name, title,
+description.
+
+```tsx
+import { LinkPreviewCard } from '@oxyhq/bloom/link-preview';
+
+<LinkPreviewCard
+  url={preview.url}
+  siteName={preview.siteName}
+  title={preview.title}
+  description={preview.description}
+  image={preview.image}
+/>
+```
+
+## Which prop decides what
+
+| prop          | decides                                                    |
+| ------------- | ----------------------------------------------------------- |
+| `url`         | where it goes, and the fallback for everything else          |
+| `title` / `description` / `siteName` / `image` | the unfurled metadata     |
+| `coverFill`   | whether the cover crops to fill or fits                      |
+| `onPress`     | overrides the default "open the URL"                         |
+
+## Only `url` is required
+
+Everything else is optional because unfurling fails all the time — a site with
+no Open Graph tags, a link behind auth, a timeout. The hostname is the fallback
+for both the site name and the title, so a bare URL still renders a usable card
+rather than an empty box with a shadow.
+
+Design the calling code for that: pass whatever the unfurler returned, without
+deciding not to render when the metadata is thin.
+
+## The shape is structural, not a contracts type
+
+The props mirror the platform's `LinkPreview` DTO but are declared
+independently, so Bloom does not depend on `@oxyhq/contracts`. If the DTO gains
+a field, map it at the call site.
+
+## `image` is a plain URL, not a file id
+
+It is rendered directly with the RN `Image` primitive, **not** through
+[`ImageResolver`](/docs/bloom/main/image-resolver) — an OG image comes from
+whatever host the linked page uses, so there is no Oxy file id to resolve.
+
+That is the opposite of the avatar rule, and the reason both are worth stating:
+an avatar goes through the resolver, an OG image does not.
+
+## The chrome is `Card`'s
+
+`outlined` at the `radius-20` rung. It used to be `bg-card` / `border-border`
+classes, which are **inert on web until the consumer wires the Tailwind
+pipeline** — the card then drew as an unbordered transparent block with no
+error anywhere. As resolved inline tokens it paints either way.
+
+The text inside is still className-first, and those class strings must stay
+literal so a consumer's Tailwind content scan over `lib/` can see them.

package/docs/list.mdx

@@ -0,0 +1,72 @@
+---
+title: VirtualList
+description: The one list primitive — windowed on web, virtualized on native, one prop shape.
+order: 52
+---
+
+# VirtualList
+
+Bloom's list. On web it windows against the scroller; on native it is a
+virtualized list. Same props either way.
+
+```tsx
+import { VirtualList } from '@oxyhq/bloom/list';
+
+<VirtualList
+  data={posts}
+  keyExtractor={(post) => post.id}
+  estimatedItemSize={96}
+  renderItem={({ item }) => <PostRow post={item} />}
+  ListEmptyComponent={<Empty query={query} />}
+  onEndReached={loadMore}
+  onEndReachedThreshold={0.5}
+/>
+```
+
+## Which prop decides what
+
+| prop                    | decides                                              |
+| ----------------------- | ----------------------------------------------------- |
+| `data` / `renderItem`   | what is drawn                                         |
+| `keyExtractor`          | identity across updates                               |
+| `estimatedItemSize`     | how the scrollbar behaves before rows are measured    |
+| `ListHeaderComponent` / `ListFooterComponent` / `ListEmptyComponent` | the slots |
+| `onEndReached` / `onEndReachedThreshold` | pagination                           |
+| `refreshing` / `onRefresh` | pull to refresh                                    |
+
+## `estimatedItemSize` is why scrolling feels right or wrong
+
+It is a hint, but a badly wrong one makes the scrollbar jump as real heights
+replace the estimate. Estimate the **common** row, not the average of a bimodal
+set: for a list that is mostly one-line rows with occasional images, the
+one-line height is the better answer even though it is nowhere near the mean.
+
+## `ListEmptyComponent` is the one to wire first
+
+An unstyled empty list is indistinguishable from a list that failed to load.
+The empty state should say which — "No results for *bloom*" is a different
+message from "Couldn't load your feed".
+
+## `onEndReached` can fire while a page is in flight
+
+It fires once per approach to the end, not once per scroll event — but a second
+approach can happen before the first request resolves. Guard on your own
+loading flag; the list does not know what your fetch is doing.
+
+```tsx
+onEndReached={() => { if (!isFetching && hasMore) fetchNext(); }}
+```
+
+## `keyExtractor` is not optional in practice
+
+Without stable keys, rows recycle onto the wrong data: a list that reorders
+shows the previous row's content for a frame, and inputs inside rows keep the
+wrong value. Use the entity's id, never the index.
+
+## Native tuning props
+
+`removeClippedSubviews`, `maxToRenderPerBatch`, `windowSize`,
+`initialNumToRender`, `recycleItems` and `maintainVisibleContentPosition` are
+honoured on native where applicable and accepted-but-ignored on web, where the
+window virtualizer manages its own mounted-row budget. They are on the type so
+one call site type-checks on both platforms.

package/docs/loading.mdx

@@ -0,0 +1,129 @@
+---
+title: Loading
+description: Spinner, top bar, and inline loading indicators with one consistent API.
+order: 13
+---
+
+# Loading
+
+One component, three variants. Pick the right one for the affordance:
+
+- `spinner` — centered, optional text, the default
+- `top` — sliding bar at the top of the screen for global progress
+- `inline` — small spinner with a text label, for inline buttons or rows
+
+For content placeholders reach for the `Skeleton` family
+(`@oxyhq/bloom/skeleton`), which actually shimmers. `Loading` never had a real
+skeleton — its `skeleton` variant drew static rectangles under the same name —
+so the variant is gone.
+
+## Spinner (default)
+
+```tsx
+import { Loading } from '@oxyhq/bloom';
+
+<Loading variant="spinner" />
+<Loading variant="spinner" size="large" />
+<Loading variant="spinner" text="Loading…" />
+<Loading variant="spinner" text="Saving…" iconSize={32} />
+```
+
+## Top bar
+
+```tsx
+<Loading variant="top" showLoading={isFetching} />
+```
+
+Renders a fixed-height bar at the top of the parent. Use it as a global progress indicator (route transitions, background sync). Requires `react-native-reanimated`.
+
+## Inline
+
+```tsx
+<Loading variant="inline" text="Connecting…" />
+```
+
+Spinner + label rendered in a row — small enough to drop into a list row or a button.
+
+## NativeWind className
+
+For native-tailwind users, `className` overrides `color`:
+
+```tsx
+<Loading variant="spinner" className="text-primary" />
+```
+
+## Props
+
+### Shared
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant?` | `'spinner' \| 'top' \| 'inline'` | Default: `'spinner'`. |
+| `size?` | `'small' \| 'medium' \| 'large'` | Default: `'medium'`. |
+| `color?` | `string` | Spinner color. Defaults to theme primary. |
+| `className?` | `string` | NativeWind class. Overrides `color`. |
+| `style?` | `ViewStyle` | Container style. |
+| `showLoading?` | `boolean` | For animated variants — pause when false. |
+| `testID?` | `string` | |
+
+### `spinner`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text?` | `string` | Optional label rendered under the spinner. |
+| `textStyle?` | `TextStyle` | Label style. |
+| `showText?` | `boolean` | Hide the label without removing layout. |
+| `iconSize?` | `number` | Override the size prop's default icon px. |
+| `spinnerIcon?` | `React.ReactNode` | Custom spinner (defaults to `ActivityIndicator`). |
+
+### `top`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `iconSize?` | `number` | |
+| `heightOffset?` | `number` | Offset from the top edge. |
+| `spinnerIcon?` | `React.ReactNode` | |
+
+### `inline`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text?` | `string` | Label text. |
+| `textStyle?` | `TextStyle` | |
+| `spinnerIcon?` | `React.ReactNode` | |
+
+## Recipes
+
+### Lazy content placeholders
+
+```tsx
+import * as Skeleton from '@oxyhq/bloom/skeleton';
+
+const { data, isPending } = useQuery({ queryKey: ['articles'], queryFn });
+
+if (isPending) {
+  return (
+    <Skeleton.Col style={{ gap: 8 }}>
+      {Array.from({ length: 5 }, (_, i) => <Skeleton.Text key={i} />)}
+    </Skeleton.Col>
+  );
+}
+return <ArticleList articles={data} />;
+```
+
+### Button busy state
+
+Most of the time you want `<Button loading>` instead of an inline `Loading` — it preserves width. Reach for `inline` only when you can't use `Button`.
+
+### Global top progress
+
+```tsx
+import { useIsFetching, useIsMutating } from '@tanstack/react-query';
+
+function GlobalProgress() {
+  const fetches = useIsFetching();
+  const mutations = useIsMutating();
+  const busy = fetches > 0 || mutations > 0;
+  return <Loading variant="top" showLoading={busy} />;
+}
+```

package/docs/media-inset-border.mdx

@@ -0,0 +1,52 @@
+---
+title: MediaInsetBorder
+description: A hairline drawn INSIDE a media edge, so a white photo still has a boundary.
+order: 66
+---
+
+# MediaInsetBorder
+
+Draws a hairline just inside its own bounds, over whatever it wraps.
+
+```tsx
+import { MediaInsetBorder } from '@oxyhq/bloom/media-inset-border';
+
+<MediaInsetBorder style={{ borderRadius: 12 }}>
+  <Image source={photo} style={{ width: 320, height: 200 }} />
+</MediaInsetBorder>
+```
+
+## Which prop decides what
+
+| prop     | decides                                                       |
+| -------- | -------------------------------------------------------------- |
+| `opaque` | whether the hairline is solid rather than a translucent overlay |
+
+## The problem it solves
+
+A photo whose edges are white — a screenshot, a product shot on a light
+background, a diagram — has no visible boundary on a light page. It bleeds into
+the surface and the layout looks broken rather than seamless.
+
+A border on the container does not fix it, because the image paints *over* the
+container's inner edge at the corners. This draws the line on top, inside the
+media's own bounds, so it survives the image's own corners and any clipping.
+
+## It goes around media, not around content
+
+For a boundary around a text block or a group of controls, use
+[`Card`](/docs/bloom/main/card)'s `outlined` variant or
+[`Divider`](/docs/bloom/main/divider). This component exists specifically for
+the case where the *content itself* can be the same colour as the page.
+
+## Match the radius
+
+The inset border takes its shape from the style you give it, so a rounded photo
+needs the same `borderRadius` here as on the image. A mismatch shows as a
+hairline that clips the corners — subtle, and worse than no border.
+
+## `opaque`
+
+Use the translucent default over photos, where a solid line reads as a frame.
+Reach for `opaque` where the media is flat colour and the translucent line
+disappears into it.

package/docs/menubar.mdx

@@ -0,0 +1,86 @@
+---
+title: Menubar
+description: A horizontal bar of menus, at most one open at a time.
+order: 20
+---
+
+# Menubar
+
+A desktop-style menu bar: a row of triggers, each opening a menu, with at most one open at a time.
+
+New to Bloom in this release. Its parts are shadcn's, and its rows are the same rows `DropdownMenu` and `ContextMenu` publish.
+
+## Basic
+
+```tsx
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarSeparator,
+  MenubarShortcut,
+  MenubarTrigger,
+} from '@oxyhq/bloom/menubar';
+
+<Menubar>
+  <MenubarMenu value="file">
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem trailing={<MenubarShortcut>⌘N</MenubarShortcut>} onPress={newTab}>
+        New tab
+      </MenubarItem>
+      <MenubarItem onPress={open}>Open…</MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem variant="destructive" onPress={closeWindow}>
+        Close window
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+
+  <MenubarMenu value="edit">
+    <MenubarTrigger>Edit</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem onPress={undo}>Undo</MenubarItem>
+      <MenubarItem onPress={redo}>Redo</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+Each `MenubarMenu` needs a `value`. That value IS the open state.
+
+## One open menu, one state
+
+`Menubar` owns which menu is open, and each `MenubarMenu` derives its own boolean from it:
+
+```tsx
+const [open, setOpen] = useState<string | undefined>(undefined);
+
+<Menubar value={open} onValueChange={setOpen}>
+```
+
+Uncontrolled by default (`defaultValue` sets the initially-open menu; omit it for none). Switching menus is a single state write, so there is never a frame with both open or neither.
+
+## Presentation
+
+`MenubarTrigger` draws its own chrome — `rounded-md px-2 py-1.5` with a `text-sm font-medium` label, washed with the accent colour while its menu is open. Pass a string and it is set for you; pass nodes and they go inside that button; pass `asChild` and your own element replaces the whole thing.
+
+On web each menu is an anchored panel under its own trigger, aligned to the trigger's left edge. On native each is the bottom sheet the other menu families use — a phone has no room for a hanging panel, and every Bloom overlay resolving to the same sheet is what makes the native surfaces feel like one system.
+
+Pressing an open menu's trigger closes it.
+
+## Rows
+
+`MenubarItem`, `MenubarCheckboxItem`, `MenubarRadioGroup` / `MenubarRadioItem`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut`, `MenubarGroup`, and `MenubarSub` / `MenubarSubTrigger` / `MenubarSubContent`.
+
+Sub-menus fly out beside their trigger row on web and render as an inline disclosure on native — see [DropdownMenu](/docs/bloom/main/dropdown-menu).
+
+## What is not here yet
+
+Two things a desktop menu bar has that this one does not, both deliberate rather than forgotten:
+
+- **Hover to switch.** On a real desktop bar, once one menu is open, moving the pointer across a sibling trigger switches to it without a click. That needs hover intent, which is the same machinery a sub-menu flyout needs.
+- **Arrow-key navigation between menus.** Roving focus across the bar and into the open panel.
+
+A press opens, a press closes, and every row is reachable by tab. Nothing is half-wired.