@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/code/skills/design/components/feedback.md

@@ -2,46 +2,107 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-## EmptyState
+Components: Alert, Empty, ErrorBoundary, ErrorState, IssueReporter, Loader, NotificationBadge, Progress, Skeleton, SystemBanner, Toaster + toast
 
-Placeholder for empty content areas.
+Each imports from its own subpath; a compound is one namespace with its parts as dotted members, e.g. `import { Empty } from "@nurix/components/compound/empty-state"` then `Empty.Header`, `Empty.Title`. Status colour is always `intent` (`neutral` | `info` | `success` | `warning` | `danger`, on the `--intent-*` tokens); a `danger` notice is `role="alert"`, every other intent `role="status"`, and a `role` you pass wins.
 
-**Props:** `icon`, `title`, `description`, `action`
+## Empty
+
+Placeholder for an empty table body, panel, card or page (`compound/empty-state`).
+
+**Sub-components:** `Empty.Header`, `Empty.Media` (`variant` [default|icon]), `Empty.Title`, `Empty.Description`, `Empty.Content`
+
+- The root is unframed and fills a flex parent (`flex-1`); add `border` for the dashed frame, and a `min-h-*` or `h-full` inside a block-flow parent.
+- `variant="icon"` draws the muted `size-10` tile, sizes an unsized `svg` to `size-6`, and is `aria-hidden`; the bare default stays exposed so an illustration `img` keeps its `alt`.
+- Every part takes `render`; a root given a `role` is labelled by its Title. A 404 page is this composition — `min-h-[60vh]`, `<Empty.Title render={<h1 />}>`, a way back in `Empty.Content`; there is no `NotFound` export.
+- Not for data in flight (`Skeleton`, `Loader`) or a failed load (`ErrorState`); `block/list` renders its own through its `emptyState` prop.
 
 ```tsx
-<EmptyState
-  icon={<InboxIcon className="h-12 w-12 text-muted-foreground" />}
-  title="No messages"
-  description="Start a conversation to see messages here"
-  action={<Button>New Message</Button>}
-/>
+<Empty className="border">
+  <Empty.Header>
+    <Empty.Media variant="icon"><Inbox /></Empty.Media>
+    <Empty.Title>No messages</Empty.Title>
+    <Empty.Description>Start a conversation to see messages here.</Empty.Description>
+  </Empty.Header>
+  <Empty.Content><Button>New message</Button></Empty.Content>
+</Empty>
 ```
 
 ## Alert
 
-Dismissible status block; `Alert` is the container, `AlertTitle`/`AlertDescription` lay out the icon-led grid.
+Inline notice that stays on the page until the user acts or navigates away (`compound/alert`).
 
-**Props:** `variant` [default|destructive], `dismissible`, `onDismiss`, `dismissButton` (custom node, overrides the default X button)
+**Props:** `intent` [neutral|info|success|warning|danger] (default `neutral`, the card surface), `icon` (replaces the intent's glyph; `null` draws none), `onDismiss`, `labels` (`dismiss`), `render`
+**Sub-components:** `Alert.Title`, `Alert.Description`
+
+- Each status intent draws its own glyph; `neutral` draws none. Never place an `<svg>` child for the icon — pass `icon`.
+- `onDismiss` draws the X in its own trailing column and never hides the alert — visibility stays in the parent (`{isVisible && <Alert … />}`).
+- `<Alert.Title render={<h3 />}>` makes the title a real heading. A message that should clear itself is a toast.
 
 ```tsx
-<Alert variant="destructive" dismissible onDismiss={handleDismiss}>
-  <TriangleAlert />
-  <AlertTitle>Sync failed</AlertTitle>
-  <AlertDescription>Retry in a few minutes.</AlertDescription>
+<Alert intent="danger" onDismiss={() => setIsVisible(false)}>
+  <Alert.Title>Sync failed</Alert.Title>
+  <Alert.Description>Retry in a few minutes.</Alert.Description>
 </Alert>
 ```
 
-## Other Components
+## Toaster + toast
+
+Self-clearing notifications on Base UI Toast (`compound/toast`): mount `<Toaster />` once at the app root, call `toast()` from anywhere, inside or outside React.
+
+**`toast` options:** `title`, `description`, `intent` (the only colour route, draws the glyph), `icon` (`null` draws none), `timeout` (ms; defaults to the dwell token, `Infinity` holds), `priority` [high|low] (default assertive for `danger`, polite otherwise), `action` (`{ label, onClick }`), `onDismiss`, `id` (reusing one updates in place)
+**Methods:** `toast.promise(work, { pending, success, error })` (`error` always takes `danger`; a phase may be a function of the result), `toast.update(id, options)` (changes only the named fields), `toast.close(id?)`
+**Toaster props:** `side` [top|bottom] (default `bottom`), `align` [start|center|end] (default `end`, logical), `hasCloseButton` (default `true`), `labels` (`region`, `dismiss`); parts `Toaster.Root`, `.Content`, `.Title`, `.Description`, `.Action`, `.Close`
+
+- There are no `toast.success` / `toast.error` shortcuts — pass `intent`. Never mount a second `Toaster`: every one renders the same queue.
+
+```tsx
+toast({ title: "Saved", description: "Your changes are live.", intent: "success" });
+toast.promise(save(), { pending: "Saving…", success: "Saved", error: "Save failed" });
+```
+
+## SystemBanner
 
-- `loader` — `Loader`: five-dot pulse indicator; `size`, `gap`, `colors` (array, cycles if fewer than `numberOfDots`), `numberOfDots`, `height`
-- `progress` — `Progress`: Radix `Progress.Root`/`Indicator` pair; `value` (0–100)
-- `skeleton` — `Skeleton`: pulsing placeholder `div`; size it with `className` to match the final layout
-- `typing-indicator` — `TypingIndicator`: `users` (`string[]` or `{ id, name, avatar }[]`), `maxVisible` — stacked avatars plus "X and N others are typing…"
-- `error-boundary` — `ErrorBoundary`: class component catching render errors; `fallback`, `onError`, `onRetry` (default UI renders a retry link)
-- `not-found` — `NotFound`: built on `EmptyState`; `title`, `description`, `showHomeButton`, `onGoBack`
-- `sonner` — `Toaster`: theme-synced wrapper over `sonner`'s `Toaster`, watches `document.documentElement`'s `dark` class via a `MutationObserver`
-- `braille` — `Braille`: animated unicode-braille spinner; `spinner` (18 named patterns — `braille`, `braillewave`, `dna`, `scan`, `rain`, `scanline`, `pulse`, `snake`, `sparkle`, `cascade`, `columns`, `orbit`, `breathe`, `waverows`, `checkerboard`, `helix`, `fillsweep`, `diagswipe`), `interval` (ms, overrides the spinner's default), `label` (screen-reader text). The `inline-spinner` subpath exports the underlying frame registry and grid utilities: `spinners`, `gridToBraille`, `makeGrid`.
+Shell-chrome banner above the app for environment, impersonation or outage states (`element/system-banner`); also exports `systemBannerVariants`.
+
+**Props:** `title` (required), `description`, `intent` [neutral|info|success|warning|danger] (default `neutral`), `icon`, `action`, `onDismiss`, `labels` (`dismiss`, `actions`)
+**Sub-components:** `SystemBanner.Stack` (orders and divides banners; placing it is yours)
+
+- The banner stores no visibility: `onDismiss` renders the dismiss button and your callback unmounts it; omit it for a banner that must not be dismissed.
+- `description` wraps on a narrow viewport. A message in content flow is `Alert`.
 
 ```tsx
-<Braille spinner="dna" label="Loading" />
+<SystemBanner.Stack>
+  <SystemBanner intent="warning" title="Sandbox environment" description="Data resets nightly" />
+  <SystemBanner title="Viewing as Dana" action={<Button size="sm">Exit view-as</Button>} />
+</SystemBanner.Stack>
 ```
+
+## IssueReporter
+
+Report-a-problem dialog with screenshot capture and an environment snapshot (`block/issue-reporter`). Requires the optional peer `html2canvas-pro` — without it the DOM raster fails on every capture and each one falls back to a `getDisplayMedia` permission prompt.
+
+**Props:** `onSubmit(report)` (required; a rejection keeps the dialog open, a resolution closes and resets), `open` / `defaultOpen` / `onOpenChange`, `shortcut` (e.g. `"mod+shift+i"`; default `null`), `shouldCaptureOnOpen` (default `true`), `fields` (default one `textarea` named `text`; types text|textarea|number|select|radio|checkbox), `defaultValue`, `metadata` (value or function, resolved at submit), `maxScreenshots` (default 3), `diagnosticsSections` (default all; `[]` turns collection off), `renderDiagnostics`, `captureOptions` (`ignoreElement`, `maxWidth`, `imageType`…), `onCaptureError`, `labels`
+**Also exports:** `useScreenCapture(options)` → `[state, actions]`, `useDiagnostics({ sections, collectOnMount })` → `{ data, isLoading, error, refresh }`, `DIAGNOSTICS_SECTIONS` (`system`, `capabilities`, `webVitals`, `storage`, `serviceWorkers`), `CaptureError`
+
+- `IssueReport` carries `fields`, `screenshots`, `diagnostics`, `metadata`. Submit stays disabled until every `required` field is set **and** a field holds a value or a screenshot is attached.
+- A report needing no screenshot or diagnostics is a plain form over `compound/dialog`, not this.
+
+```tsx
+<IssueReporter
+  shortcut="mod+shift+i"
+  fields={[{ name: "text", type: "textarea", label: "What went wrong?", required: true }]}
+  metadata={() => ({ route: location.pathname })}
+  onSubmit={async (report) => sendToTracker(report)}
+/>
+```
+
+## Other Components
+
+- `loader` — `Loader` (`element/loader`): em-sized lattice in `currentColor` for open-ended work; `status` [pending|success|error] (default `pending`) settles the same glyph into a check or a cross, `label`, `successLabel`, `errorLabel`, `hasTimer`, `labels`. A "Thinking…" or typing row is `<Loader label="Typing" />` — there is no dots variant.
+- `progress` — `Progress` (`element/progress`): `value` (0–100, clamped; `null` is indeterminate), `label` (the accessible name), `variant` [linear|circular|fill] (default `linear`), `size` [sm|default|lg] (not on `fill`), `format` / `getAriaValueText` to reword the announcement.
+- `skeleton` — `Skeleton` (`element/skeleton`): pulsing `aria-hidden` `div` with no intrinsic size — size it with `className`, mark the container `aria-busy`, and pass `render={<span />}` inside phrasing content.
+- `notification-badge` — `NotificationBadge` (`element/notification-badge`): `value` (pass the real count; renders nothing at zero), `max` (default 99, shows `99+`), `variant` [count|dot], `intent`, `labels` (`dot`); em-sized from the text beside it, positioned by you on a `relative` trigger.
+- `error-state` — `ErrorState` (`compound/error-state`): failed-load block on Empty's geometry; `description` (required), `title`, `icon`, `onRetry` (renders Retry), `labels` (`retry`). Carries no live role; `block/list`, `block/table` and `block/tree` take `error={{ message, onRetry }}` instead.
+- `error-boundary` — `ErrorBoundary` (`lib/error-boundary`): catches render errors in the subtree it wraps; `onError` (its only way out — it logs nothing), `onRetry` (refetch here, or the subtree throws again), `fallback` (replaces the whole card, retry included).
+- No nurix primitive: `text-spinner` — build from the `index.md` fallback spec.

package/data/harnesses/code/skills/design/components/hooks.md

@@ -2,34 +2,220 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Standalone React hooks, each imported from its own subpath under `@nurix/components/`.
+Standalone React hooks, each imported from its own `hooks/*` subpath under `@nurix/components/`, plus the Uppy upload adapter at `lib/uppy-adapter`. Every Base UI-backed surface already owns its dismissal, Escape and roving focus — never double-wire a hook onto one.
 
 ## useClickOutside
 
-`useClickOutside(ref, callback)` — invokes `callback` on `mousedown`/`touchstart` outside the referenced element.
+`useClickOutside(ref, callback)` (from `hooks/use-click-outside`) — fires `callback` on a `document` `mousedown`/`touchstart` outside `ref.current`. Only for a bespoke floating surface with no dismissal of its own.
+
+- Wrap the trigger and the panel in the same ref when the trigger toggles — `mousedown` runs before the trigger's `click`, so an unwrapped trigger closes and reopens the surface.
+- No `enabled` option: listeners live for the component's life, so unmount the surface on close or gate inside the callback. A portalled child reads as an outside press.
+
+```tsx
+const panelRef = useRef<HTMLDivElement>(null);
+useClickOutside(panelRef, () => setOpen(false));
+```
+
+## useControllableState
+
+`useControllableState({ prop, defaultProp, onChange })` (from `hooks/use-controllable-state`) — returns `[value, setValue]`, collapsing controlled and uncontrolled into one code path.
+
+- Presence decides the mode: `prop: undefined` is uncontrolled. `onChange(value)` fires only when the value changes (`Object.is`) and takes the value alone — a Base UI `onOpenChange(open, eventDetails)` keeps its own wiring.
+- `defaultProp` is read once at mount; hoist an array or object default to a module constant.
+
+```tsx
+const [value, setValue] = useControllableState({ prop: valueProp, defaultProp: defaultValue ?? "", onChange: onValueChange });
+```
+
+## useDebounce
+
+`useDebounce(value, delayMs)` (from `hooks/use-debounce`) — returns the value, settled `delayMs` after it stops changing. First render returns it as-is; a pending update drops on unmount.
+
+- Debounce the state, not the handler: keep the input controlled and immediate, point the expensive effect at the debounced value. A one-shot delayed action is `useTimeout`.
+
+```tsx
+const debouncedQuery = useDebounce(query, 300);
+```
+
+## useEventListener
+
+`useEventListener(eventName, handler, target?, options?)` (from `hooks/use-event-listener`) — `target` defaults to `window`; accepts `document`, a node, a ref, or `null` (subscribes nothing).
+
+- The handler is read at fire time, so an inline closure never re-subscribes; `options` is captured at subscribe time. A target that mounts later must be passed as the element via state — a ref's `.current` changing re-renders nothing.
+
+```tsx
+useEventListener("mousemove", (event) => setPointer({ x: event.clientX, y: event.clientY }), panelRef);
+```
+
+## useFilter
+
+`useFilter(options?)` (from `hooks/use-filter`) — returns `{ contains, startsWith, endsWith }`, each `(value, query) => boolean`, locale-aware via `Intl.Collator`. Options: `locale`, any `Intl.CollatorOptions`, `gapMatch` (default `false`).
+
+- An empty query matches everything. `gapMatch: true` strips separators so "jsmith" matches "J. Smith", and skips the collator's accent folding. `compound/command` filters its own items — a palette needs no matcher.
+
+```tsx
+const { contains } = useFilter({ sensitivity: "base" });
+const visible = items.filter((item) => contains(item.label, query));
+```
+
+## useFreshness
+
+`useFreshness({ fetchedAt?, onRefresh, staleAfterMs?, tickMs? })` (from `hooks/use-freshness`) — returns `{ refresh, isRefreshing, isStale }` for a refresh control.
+
+- `isRefreshing` follows a returned promise (a synchronous `onRefresh` never sets it); a click mid-refresh returns the in-flight promise, no queue. `isStale` needs both `fetchedAt` and `staleAfterMs`, else no clock runs.
+
+```tsx
+const { refresh, isRefreshing } = useFreshness({ fetchedAt, onRefresh: refetch, staleAfterMs: 5 * 60_000 });
+<Button onClick={refresh} disabled={isRefreshing}>Updated <Timestamp value={fetchedAt} relativeThreshold={Infinity} /></Button>
+```
+
+## useIntersectionObserver
+
+`useIntersectionObserver<T>(options?)` (from `hooks/use-intersection-observer`) — returns `[callbackRef, entry]`; options (`root`, `rootMargin`, `threshold`) pass through, and instances with the same root and options share one observer.
+
+- `entry` is `null` until the first observation and is not cleared on unmount. For paging a stream use `block/list`'s `onLoadMore` + `hasMore` — it owns the sentinel and its re-entry guard.
+
+```tsx
+const [sentinelRef, entry] = useIntersectionObserver<HTMLDivElement>();
+const isAtTop = entry?.isIntersecting ?? false;
+```
+
+## useInterval
+
+`useInterval(callback, delayMs | null)` (from `hooks/use-interval`) — `null` pauses; changing the delay restarts the cadence; the callback is read at tick time.
+
+- Stop by state, not `clearInterval`. Ticks are not a clock (background tabs throttle) — read `Date.now()` per tick for elapsed time.
 
 ```tsx
-const ref = useRef<HTMLDivElement>(null);
-useClickOutside(ref, () => setOpen(false));
+useInterval(tick, isDone ? null : speedMs);
 ```
 
-## useFileUpload
+## useKeyPress
 
-`useFileUpload(options?)` — returns `[state, actions]`.
+`useKeyPress(key, callback, { event?, target? })` (from `hooks/use-key-press`) — matches `event.key` (case-sensitive); `event` is `"keydown"` (default) or `"keyup"`, `target` defaults to `window`.
 
-**Options:** `maxFiles` (multi mode only, default Infinity), `maxSize` (bytes), `accept`, `multiple`, `initialFiles`, `onFilesChange`, `onFilesAdded`
+- A window listener hears keys typed into inputs — require a modifier or check `event.target`. Base UI popups own their Escape.
+
+```tsx
+useKeyPress("b", (event) => { if (event.metaKey || event.ctrlKey) { event.preventDefault(); toggleSidebar(); } });
+```
 
-**State:** `{ files: FileWithPreview[], isDragging, errors }` **Actions:** `addFiles`, `removeFile`, `clearFiles`, `clearErrors`, `handleDragEnter/Leave/Over/Drop`, `handleFileChange`, `openFileDialog`, `getInputProps()`. Also exports `formatBytes`.
+## useMeasure
+
+`useMeasure<T>()` (from `hooks/use-measure`) — returns `[callbackRef, { width, height }]`, `contentRect` sizes, `{ 0, 0 }` until the first observation.
+
+- Reports size only — animating a height change is `useSmoothResize`. Keep your own ref with `useComposedRefs(myRef, measureRef)` from `lib/compose-refs`.
 
 ```tsx
-const [state, actions] = useFileUpload({ multiple: true, maxFiles: 5 });
-<div {...actions.getInputProps()} onDrop={actions.handleDrop} />
+const [measureRef, { width }] = useMeasure<HTMLDivElement>();
 ```
 
 ## useMediaQuery
 
-`useMediaQuery(query)` — reactive boolean for a CSS media query string, updates on `matchMedia` change events.
+`useMediaQuery(query)` (from `hooks/use-media-query`) — reactive boolean; the first client render reports the real match; callers of the same query share one `MediaQueryList`.
+
+- Only when the answer changes behaviour — anything visual is a Tailwind breakpoint or container query. The server snapshot is `false`. Pass the full query: a bare `768` becomes the invalid `"768"` and reads `false` forever.
+
+```tsx
+const isCoarsePointer = useMediaQuery("(hover: none)");
+```
 
 ## useIsMobile
 
-`useIsMobile()` (from `hooks/use-mobile`) — reactive boolean, true below the 768px breakpoint.
+`useIsMobile(breakpoint = 768)` (from `hooks/use-mobile`) — true below `breakpoint`, the first non-mobile width (`useIsMobile(768)` asks `(max-width: 767px)`).
+
+- Behaviour only (`block/sidebar` swaps its rail for a sheet on it); the server snapshot is `false`. One listener per call — lift it to one owner instead of calling it per row.
+
+```tsx
+const isMobile = useIsMobile();
+```
+
+## useOverflowCount
+
+`useOverflowCount<T>(itemCount, { reserve? })` (from `hooks/use-overflow-count`) — returns `{ containerRef, visibleCount, overflowCount }` for a "+N more" row fitted to rendered widths; `reserve` (px, default `0`) keeps room for the indicator.
+
+- The row is `overflow: hidden` and non-wrapping; every item stays mounted, hidden past `visibleCount` with the `hidden` attribute; the indicator comes after the items. A fixed "first three" truncation is a slice, not this hook.
+
+```tsx
+const { containerRef, visibleCount, overflowCount } = useOverflowCount<HTMLDivElement>(tags.length, { reserve: 48 });
+```
+
+## useRangeSelect
+
+`useRangeSelect(orderedIds, selectedIds)` (from `hooks/use-range-select`) — returns `{ select, reset }`; `select(id, event)` returns the next selection array.
+
+- A plain click toggles and sets the anchor; shift-click selects anchor-to-click, and the anchor's direction wins. `orderedIds` is display order; call `reset()` when the list identity changes. `block/list` already wires it.
+
+```tsx
+const { select } = useRangeSelect(rows.map((row) => row.id), selectedIds);
+<Row onClick={(event) => setSelectedIds(select(row.id, event))} />
+```
+
+## useRovingFocus
+
+`useRovingFocus<T>({ orientation?, loop?, dir?, itemSelector?, enabled? })` (from `hooks/use-roving-focus`) — returns a callback ref for the group; defaults `orientation: "horizontal"`, `loop: true`, `dir: "ltr"`, `enabled: true`.
+
+- Keeps one reachable item (the active one, else the first enabled); Home/End jump; disabled items skip. Focus moves, selection does not.
+
+```tsx
+const rovingRef = useRovingFocus<HTMLDivElement>();
+<div role="tablist" ref={rovingRef}>{tabs}</div>
+```
+
+## useScrollOverflow
+
+`useScrollOverflow<T>({ orientation?, threshold? })` (from `hooks/use-scroll-overflow`) — returns a callback ref that writes `data-overflow-y-start`/`-end` (or `-x-` for `orientation: "horizontal"`, RTL-aware) straight to the DOM, so scrolling never re-renders; `threshold` defaults to `1`px.
+
+- Style the fade off the attribute (`[data-overflow-y-start]:before { … }`). Only for a bare scroll container — `element/scroll-area`'s `hasFadeEdges` already reads the same attributes.
+
+```tsx
+const scrollRef = useScrollOverflow<HTMLDivElement>();
+<div ref={scrollRef} className="overflow-y-auto">{rows}</div>
+```
+
+## useSearchSource · createStaticSource
+
+`useSearchSource(source, query)` (from `hooks/use-search-source`) — returns `{ items, status, error?, isBootstrap }` (`status`: `idle | loading | ready | error`). A source is `{ search(query), bootstrap?, debounceMs? }`; `createStaticSource(items, { filter?, bootstrap? })` wraps an in-memory list in the same shape.
+
+- Only the newest request writes; a synchronous source never flashes `loading`. An empty query shows `bootstrap()` with `isBootstrap: true`, or nothing without one.
+
+```tsx
+const search = useSearchSource(source, query);
+<Command searchValue={query} onSearchValueChange={setQuery} loading={search.status === "loading"} filter={null}>
+  <Command.Results data={search.items} renderItem={(item) => <Command.Item value={item.value}>{item.label}</Command.Item>} />
+</Command>
+```
+
+## useSmoothResize
+
+`useSmoothResize<T>(enabled = true)` (from `hooks/use-smooth-resize`) — returns a callback ref that animates the element's real `height` (slow motion step × 1.2 on `--motion-ease-travel`), so content below reflows with it.
+
+- First paint never animates; reduced motion and the still pace turn it off. For a page region prefer `<Block shouldSettle>`; settle the outermost region only. Plural or continuous motion wants a transform technique instead.
+
+```tsx
+const settleRef = useSmoothResize<HTMLDivElement>();
+<div ref={settleRef}>{isExpanded ? <Details /> : <Summary />}</div>
+```
+
+## useTimeout
+
+`useTimeout(callback, delayMs | null)` (from `hooks/use-timeout`) — arms when the delay is a number, `null` disarms; changing the delay restarts; unmount cleans up.
+
+- Replaces a bare `setTimeout` resetting a transient flag. A second trigger while armed keeps the first deadline — flip through `null` to restart.
+
+```tsx
+useTimeout(() => setIsCopied(false), isCopied ? 2000 : null);
+```
+
+## useUppyState · createUppyUploadHandler
+
+`createUppyUploadHandler(uppy)` and `useUppyState(uppy, selector)` (from `lib/uppy-adapter`) — bind a caller-owned `@uppy/core` instance to `compound/file-picker`'s `onUpload`. `@uppy/core` is an optional peer (the `file-picker` family); a picker that stages locally or uploads with plain `fetch` passes its own `onUpload` and skips this.
+
+- The instance and its transport plugins are the caller's; the library ships no network code. A rejected `upload()` fails every file in the batch; progress needs a numeric `percentage` in Uppy's `upload-progress`.
+- `useUppyState` is a `useSyncExternalStore` read — a selector that derives a new object must be module-scope or `useCallback`'d, or React loops.
+
+```tsx
+const uppy = useMemo(() => new Uppy().use(AwsS3, { endpoint: "/api/s3" }), []);
+const upload = useMemo(() => createUppyUploadHandler(uppy), [uppy]);
+<FilePicker value={files} onValueChange={setFiles} onUpload={upload}>…</FilePicker>
+```