@gusnips/react 0.9.24 → 0.9.25

package/src/query.ts

@@ -3,29 +3,28 @@ import type { DefaultOptions } from "@tanstack/react-query";
 import { ApiError } from "./api-error.ts";
 
 /**
- * react-query defaults — the merge of three repos that each got part of this right.
+ * react-query defaults merged from three repos that each got part of this right.
  *
  * The default is three blind retries, which is wrong for an API that answers refusals
  * precisely: a 402, a 403 or a 451 says exactly the same thing three times, and a 429 we hammer
  * is a 429 we deserve. All three donors knew that much. What each knew alone:
  *
  * - one allowed **408** through, the only 4xx that a second attempt genuinely fixes;
- * - one refused to retry a 429 whose CODE says the limit is durable — a monthly quota or a
- *   spent balance clears by buying, not by waiting, so retrying burns another request against
+ * - one refused to retry a 429 whose CODE says the limit is durable. A monthly quota or a spent balance clears by buying, not by waiting, so retrying burns another request against
  *   the limiter and cannot succeed;
  * - one set **`refetchOnReconnect`**, which none of the others had, and which is the single
  *   most useful refetch there is: coming back from a tunnel is exactly when the screen is stale.
  *
  * The second migration added the fourth rule, which no donor had: **when a 429 says how long,
  * believe it.** Its limiter answers `Retry-After: 60` on a per-minute window, and the default
- * backoff retries at 1s and 2s — two more requests that cannot succeed, both charged against the
- * same limiter, and three seconds added before the screen says anything. So a stated wait is
+ * backoff retries at 1s and 2s, sending two more requests that cannot succeed, both charged against
+ * the same limiter, and three seconds added before the screen says anything. So a stated wait is
  * waited out when it is short, and is an ANSWER when it is not.
  *
  * The fifth rule came from the server half of this fleet rather than from a donor: a refusal can
  * state that waiting will never fix it at all, by sending `details.retryAfterSecs: null`. Read as
- * "did not say how long" — which is what every version before this one did — that 429 is retried
- * against a limit no amount of time moves.
+ * "did not say how long", as every version before this one did, that 429 is retried against a limit
+ * no amount of time moves.
  *
  * This is invariant 8. The rule itself lives in `@gusnips/http/retry`, so an SDK with no React
  * in it follows the same one; what is here is the binding to react-query.
@@ -33,9 +32,9 @@ import { ApiError } from "./api-error.ts";
 
 export interface QueryDefaultsOptions {
   /**
-   * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
-   * balance that needs topping up. They usually arrive as 402 or 429; the status alone cannot
-   * tell them apart from a burst limit, which is why the caller names them.
+   * Error codes for limits that do not clear by waiting, such as a spent monthly quota or a balance
+   * that needs topping up. They usually arrive as 402 or 429; the status alone cannot tell them
+   * apart from a burst limit, which is why the caller names them.
    *
    * Only needed where the server does not say so itself. One that sends
    * `details.retryAfterSecs: null` has already made the claim and `shouldRetry` reads it, which
@@ -47,10 +46,10 @@ export interface QueryDefaultsOptions {
   /**
    * Longest stated wait still worth retrying. Default 10 seconds.
    *
-   * Only applies when the refusal named its own expiry (`Retry-After`, or `retryAfterSecs` in
-   * the body). A burst limit that clears in two seconds is worth sitting out; a monthly ceiling
-   * that clears in an hour is an answer, and holding a spinner for it helps nobody — show the
-   * wait instead, which is what `humanizeWait` is for.
+   * Only applies when the refusal named its own expiry (`Retry-After`, or `retryAfterSecs` in the
+   * body). A burst limit that clears in two seconds is worth sitting out; a monthly ceiling that
+   * clears in an hour is an answer, and holding a spinner for it helps nobody. Show the wait
+   * instead, which is what `humanizeWait` is for.
    */
   maxRetryWaitSecs?: number;
   staleTime?: number;
@@ -84,8 +83,8 @@ export function shouldRetry(
 
 /**
  * How long before the next attempt: the server's stated wait when there is one, an exponential
- * backoff with jitter otherwise, and never less than the backoff — a `Retry-After: 0` is a
- * server saying "immediately", which for a client that just got refused is still too soon.
+ * backoff with jitter otherwise, and never less than the backoff. A `Retry-After: 0` is a server
+ * saying "immediately", which for a client that just got refused is still too soon.
  */
 export function retryDelayMs(attemptIndex: number, error: unknown): number {
   return delayFor(attemptIndex, answerOf(error));
@@ -130,7 +129,7 @@ export function queryDefaults({
  * When it is ready, `refreshError` says whether the last refresh failed.
  *
  * **Never gate a screen on `isError`.** It is also true when a BACKGROUND refetch fails over data
- * already on screen — a window regaining focus, a poll, the invalidation after a save — so
+ * already on screen after a window regains focus, a poll or the invalidation after a save. So
  * `isError ? <failure panel> : <data>` throws away what the reader was looking at over one blip.
  * The adopters that had noticed each wrote `isLoadingError` beside a comment saying so; the ones
  * that had not were a boundary and a great many inline ternaries. A refresh that failed is not a

package/src/sse.ts

@@ -1,26 +1,26 @@
 /**
  * Server-sent events: the framing and the transport, kept apart.
  *
- * Three donors had three readers and each had half the answer. One was spec-correct about the
- * wire but welded to `TextDecoderStream`, so the React Native app — whose fetch has no body
- * reader — could not use a line of it. One was a platform-free `feed(text)` that three
- * transports shared, and it silently dropped data. One was a whole second transport with its
- * own fetch and its own 401 handling, bypassing the app's only API client.
+ * Three donors had three readers and each had half the answer. One was spec-correct about the wire
+ * but welded to `TextDecoderStream`, so the React Native app, whose fetch has no body reader, could
+ * not use a line of it. One was a platform-free `feed(text)` that three transports shared, and it
+ * silently dropped data. One was a whole second transport with its own fetch and its own 401
+ * handling, bypassing the app's only API client.
  *
  * So: {@link createSseParser} is the state machine and knows about no platform at all;
  * {@link readSseStream} is fifteen lines of `ReadableStream` on top of it. A caller on a
  * platform without body readers keeps its own fifteen lines and shares the machine underneath.
  * (providerkit reached this exact split from the other direction and for the same reason.)
  *
- * And streams ride the ordinary API client — `client.request(path, {headers: {Accept:
- * "text/event-stream"}, timeoutMs: null})`. Not `EventSource`, which cannot carry an
- * Authorization header, and not a second fetch, which would need its own copy of the refresh
- * logic and would drift from it.
+ * And streams ride the ordinary API client: `client.request(path, {headers: {Accept:
+ * "text/event-stream"}, timeoutMs: null})`. Not `EventSource`, which cannot carry an Authorization
+ * header, and not a second fetch, which would need its own copy of the refresh logic and would
+ * drift from it.
  */
 
 /** One frame off the wire. `data` is raw text; see {@link createSseParser} on why. */
 export interface SseFrame {
-  /** The `event:` field, or `"message"` — which is what the spec says an unnamed frame is. */
+  /** The `event:` field, or `"message"` for an unnamed frame, as the spec requires. */
   event: string;
   /** Every `data:` line in the frame, joined with newlines. Never parsed here. */
   data: string;
@@ -31,23 +31,22 @@ export interface SseFrame {
 /**
  * An incremental parser. Feed it text in whatever sizes the transport delivers.
  *
- * Frames split across reads are held until they complete, so a payload cut mid-line is never
- * lost or truncated — which is the failure this shape exists to prevent, and the one that only
- * shows up under a slow network.
+ * Frames split across reads are held until they complete, so a payload cut mid-line is never lost
+ * or truncated. That is the failure this shape exists to prevent, and the one that only shows up
+ * under a slow network.
  *
  * Three rules that are easy to get wrong, and one donor got each of them wrong:
  *
  * - **`data:` repeats.** A frame may carry several `data:` lines and they are JOINED with
- *   newlines. One donor assigned instead of appending, so a multi-line payload arrived as its
- *   last line only — no error, no warning, just a truncated message.
+ *   newlines. One donor assigned instead of appending, so a multi-line payload arrived as its last line only, with no error or warning, just a truncated message.
  * - **Strip ONE leading space after the colon**, not all whitespace. `.trim()` is the obvious
  *   thing and it corrupts any payload whose own content begins or ends with a space.
  * - **A frame with no `data:` is not dispatched.** That is what lets a server send bare
  *   `event: heartbeat` keepalives, or `:` comment lines, without waking a consumer.
  *
- * `data` is handed back as a raw string and deliberately NOT JSON-parsed. One donor parsed here
- * and its three consumers wanted three different things — one wraps non-JSON, one uses a
- * tolerant parser, one parses directly. Parsing in the parser picks a policy for all of them.
+ * `data` is handed back as a raw string and deliberately NOT JSON-parsed. One donor parsed here and
+ * its three consumers wanted three different things: one wraps non-JSON, one uses a tolerant
+ * parser, one parses directly. Parsing in the parser picks a policy for all of them.
  */
 export function createSseParser(onFrame: (frame: SseFrame) => void): {
   feed: (text: string) => void;
@@ -95,8 +94,8 @@ function parseFrame(raw: string): SseFrame | null {
  * single-flight refresh, and a 402 or a 404 arriving as an `ApiError` the page can explain
  * rather than an `onerror` event with nothing in it.
  *
- * Cancels the reader on the way out however it leaves — a stream abandoned without cancelling
- * holds the connection open until the server gives up on it.
+ * Cancels the reader on the way out however it leaves. A stream abandoned without cancelling holds
+ * the connection open until the server gives up on it.
  */
 export async function readSseStream(
   response: Response,

package/src/states.ts

@@ -5,10 +5,10 @@ import type { ReactNode } from "react";
  * somebody remembers.
  *
  * **No component ships here, on purpose.** Seven repos have an `EmptyState.tsx` and an
- * `ErrorState.tsx`, and read side by side they overlap 9–37%: one draws a tinted icon badge,
- * one a branded illustration set, one a mascot. What they genuinely share is the PROP SHAPE —
- * which is the rule itself, and the only part a package can hold without deciding how eight
- * brands look. Same reasoning as the styled Button: share behaviour, skin per product.
+ * `ErrorState.tsx`, and read side by side they overlap 9–37%: one draws a tinted icon badge, one a
+ * branded illustration set, one a mascot. What they genuinely share is the PROP SHAPE, which is the
+ * rule itself, and the only part a package can hold without deciding how eight brands look. Same
+ * reasoning as the styled Button: share behaviour, skin per product.
  *
  * Import the type, write your own component against it, and the compiler enforces the rest.
  */
@@ -22,16 +22,16 @@ import type { ReactNode } from "react";
  * `action` is optional only because some panels fill themselves once a job upstream finishes.
  */
 export interface EmptyStateProps {
-  /** What this panel is for. "No lookups yet" — not "No results". */
+  /** What this panel is for. Use "No lookups yet", not "No results". */
   title: string;
   /** What belongs here, and what it will show once it does. */
   description: ReactNode;
   /** The way forward, as a control. Usually one button. */
   action?: ReactNode;
   /**
-   * `3` inside a panel that already sits under a page heading — the default and the common
-   * case. `1` when this composer IS the page (a 404, a suspended account), which otherwise
-   * ships a document with no `h1` in it at all.
+   * Defaults to `3` for a panel that already sits under a page heading, the common case. `1` when
+   * this composer IS the page (a 404, a suspended account), which otherwise ships a document with
+   * no `h1` in it at all.
    *
    * Only one donor had this, and it is the difference between a screen reader announcing a
    * page and announcing nothing.
@@ -49,9 +49,9 @@ export interface EmptyStateProps {
  * Something did not work.
  *
  * `problem` names what failed, `cause` says why it most likely happened, `fix` says what to do
- * about it, and `action` is that fix as a control. **`fix` and `action` are both required** — a
- * required prop is the only version of "never dead-end" that a caller in a hurry cannot skip,
- * and the donor that made them required is the one whose error screens all have a way out.
+ * about it, and `action` is that fix as a control. **`fix` and `action` are both required**. A
+ * required prop is the only version of "never dead-end" that a caller in a hurry cannot skip, and
+ * the donor that made them required is the one whose error screens all have a way out.
  *
  * Not a place for a stack trace. `cause` is what a person can act on ("the site answered too
  * slowly"), with the request id, if there is one, alongside it in `reference`.
@@ -66,7 +66,7 @@ export interface ErrorStateProps {
   cause?: ReactNode;
   /** The way forward, in words. */
   fix: ReactNode;
-  /** The way forward, as a control — usually a retry button. */
+  /** The way forward as a control, usually a retry button. */
   action: ReactNode;
   /** A request id or code, for a support thread. Set in mono, never shouted. */
   reference?: ReactNode;

package/src/supabase-session.ts

@@ -43,33 +43,33 @@ type _StorageFitsCreateClient = Satisfied<
  * Auth FAILED rather than answered, so nothing is known about the credential it was handed:
  * either the request never landed, or GoTrue failed on its own.
  *
- * This is the question every site that ends a session has to ask — a token refresh, an API
- * door, and a callback choosing between "try again" and "that link is spent". Without it one
- * bad minute at GoTrue signs out everybody whose token happened to need refreshing, and tells
- * everybody clicking a recovery link that it has expired, which sends them to ask the service
- * that is down for a replacement.
+ * This is the question every site that ends a session has to ask: a token refresh, an API door, and
+ * a callback choosing between "try again" and "that link is spent". Without it one bad minute at
+ * GoTrue signs out everybody whose token happened to need refreshing, and tells everybody clicking
+ * a recovery link that it has expired, which sends them to ask the service that is down for a
+ * replacement.
  *
  * Both clauses carry weight, and the second is why this is a function rather than one call.
  * `isAuthRetryableFetchError` is a NAME check, and the statuses that earn that name are a list
- * auth-js owns. The list has drifted — 502, 503 and 504 at 2.91; those plus the 52x family and
- * still no 500 at 2.106; 500 through 530 at 2.108 — so code leaning on it alone is right at
- * whichever version happens to be installed, which is not the same as being right, and a fleet
- * installs several versions at once. It is also a LIST rather than a range, so it has holes at
- * every version, drift or no drift: at 2.112 nothing covers 505 through 519 or 531 up, and a
- * 507 or a 599 with a JSON body arrives as a plain `AuthApiError`. Pinning a recent SDK does not
- * make the status clause redundant.
+ * auth-js owns. The list has drifted: 502, 503 and 504 at 2.91; those plus the 52x family and still
+ * no 500 at 2.106; 500 through 530 at 2.108. Code leaning on it alone is right at whichever version
+ * happens to be installed, which is not the same as being right, and a fleet installs several
+ * versions at once. It is also a LIST rather than a range, so it has holes at every version, drift
+ * or no drift: at 2.112 nothing covers 505 through 519 or 531 up, and a 507 or a 599 with a JSON
+ * body arrives as a plain `AuthApiError`. Pinning a recent SDK does not make the status clause
+ * redundant.
  *
- * The same statuses with a body that is NOT JSON — a proxy's HTML page — arrive as an
- * `AuthUnknownError`, which carries no status at any status, so nothing here can tell that 507
- * from a malformed 400. It answers false for both, on purpose: reading an unreadable 4xx as an
- * outage would leave a dead session retrying forever, which is the other half of the same bug.
+ * The same statuses with a body that is NOT JSON, such as a proxy's HTML page, arrive as an
+ * `AuthUnknownError`, which carries no status at any status, so nothing here can tell that 507 from
+ * a malformed 400. It answers false for both, on purpose: reading an unreadable 4xx as an outage
+ * would leave a dead session retrying forever, which is the other half of the same bug.
  *
  * Read the version a tree really serves with `bun why @supabase/auth-js`, which prints one
  * heading per RESOLVED version; `node_modules` keeps copies the resolver does not serve.
  *
- * Anything that is not an auth error at all answers true: a failure from outside auth-js is not
- * a verdict on the credential either. Nothing at all answers false — `null` is what every
- * supabase-js auth call returns on success, and success is not an outage.
+ * Anything that is not an auth error at all answers true: a failure from outside auth-js is not a
+ * verdict on the credential either. Nothing at all answers false. `null` is what every supabase-js
+ * auth call returns on success, and success is not an outage.
  */
 export function isAuthOutage(error: unknown): boolean {
   // Nothing thrown is not an outage, and this clause exists because the function is exported.
@@ -171,12 +171,12 @@ function localStorageOrMemory(): SupportedStorage {
  * 2.116.0 and 41–51 s at 2.106.2. Nobody at a shared computer waits that long, and a page that
  * navigates away in the meantime takes the removal with it.
  *
- * It resolves once the stored session is gone. `error` is `null` when auth ended the session on
- * the server too. Otherwise it is the reason auth did not — its error, a thrown value, or the
- * deadline — and the session may still be live on the server and on other devices. `SIGNED_OUT`
- * arrives once auth-js has finished with the first call: about 100 ms later from 2.108.2 on, and
- * up to 22 s later at 2.106.2. If your screen does not reload, clear your own store when this
- * resolves instead of waiting for the event.
+ * It resolves once the stored session is gone. `error` is `null` when auth ended the session on the
+ * server too. Otherwise it is the reason auth did not: its error, a thrown value or the deadline.
+ * The session may still be live on the server and on other devices. `SIGNED_OUT` arrives once
+ * auth-js has finished with the first call: about 100 ms later from 2.108.2 on, and up to 22 s
+ * later at 2.106.2. If your screen does not reload, clear your own store when this resolves instead
+ * of waiting for the event.
  */
 export async function signOutEvenOffline(
   auth: Pick<SupabaseSessionAuth, "signOut">,
@@ -254,7 +254,7 @@ export function createSupabaseSessionAdapter(
 }
 
 /**
- * Every link type a GoTrue email can carry — not only the ones this app's templates send today.
+ * Every link type a GoTrue email can carry, including ones this app's templates do not send today.
  * One donor rejected `invite` because "invites are never sent", which was true of the product and
  * false of the deployment: an operator inviting somebody from Studio sent a branded email whose
  * link then said it was invalid. A type the templates never emit costs nothing to accept: the hash
@@ -262,9 +262,9 @@ export function createSupabaseSessionAdapter(
  *
  * Closed on purpose: auth-js's own `EmailOtpType` ends in `(string & {})`, so it cannot make a
  * destination map name every case. `Record<EmailLinkType, string>` can, and that is where an app
- * decides that `recovery` and `invite` both continue to the new-password screen — GoTrue creates
- * an invited account with NO password, so landing one "inside" signs them in once and locks them
- * out after.
+ * decides that `recovery` and `invite` both continue to the new-password screen. GoTrue creates an
+ * invited account with NO password, so landing one "inside" signs them in once and locks them out
+ * after.
  */
 export type EmailLinkType =
   "signup" | "invite" | "magiclink" | "recovery" | "email_change" | "email";
@@ -290,10 +290,10 @@ export type AuthCallback =
   | { kind: "email-link"; tokenHash: string; type: EmailLinkType }
   /**
    * A session arriving in the address: a PKCE `code`, or the implicit flow's tokens. In a browser
-   * with `detectSessionInUrl` on, the client has already taken it — wait for the session, and do
-   * not trade it again, which would be a second exchange racing the first. Where nothing reads
-   * the address for you (React Native), `credential` is what `exchangeCodeForSession` or
-   * `setSession` takes.
+   * with `detectSessionInUrl` on, the client has already taken it. Wait for the session, and do not
+   * trade it again, which would be a second exchange racing the first. Where nothing reads the
+   * address for you (React Native), `credential` is what `exchangeCodeForSession` or `setSession`
+   * takes.
    */
   | {
       kind: "session";
@@ -301,10 +301,9 @@ export type AuthCallback =
       credential: { code: string } | { access_token: string; refresh_token: string };
     }
   /**
-   * GoTrue, or the provider behind it, reported a failure in the address. `code` is GoTrue's
-   * stable `error_code` (`otp_expired`, `bad_oauth_state`, …) and is what to choose words by;
-   * `error_description` is left out on purpose — it is English-only and often names the wrong
-   * cause.
+   * GoTrue, or the provider behind it, reported a failure in the address. `code` is GoTrue's stable
+   * `error_code` (`otp_expired`, `bad_oauth_state`, …) and is what to choose words by;
+   * `error_description` is left out because it is English-only and often names the wrong cause.
    */
   | { kind: "error"; error: string | null; code: string | null; cancelled: boolean }
   /** Nothing usable: cut short between the mail client and here, or edited by hand. */
@@ -312,19 +311,19 @@ export type AuthCallback =
 
 /**
  * Reads an auth callback address. Pure, so every edge case is testable without a router or a
- * client — pass `location.search` and `location.hash`, or the two halves of a deep link.
+ * client. Pass `location.search` and `location.hash`, or the two halves of a deep link.
  *
- * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some — the
- * query too after a provider round trip, the fragment alone after an implicit-flow email link —
- * so a callback reading one of the two misses a failure the other carries, and the person lands
+ * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some. After a
+ * provider round trip, it writes both; after an implicit-flow email link, it writes the fragment
+ * alone. A callback reading one of the two misses a failure the other carries, and the person lands
  * on a screen that says nothing. Both are read here.
  *
- * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel
- * — their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue writes
- * that same value for an expired email link, a banned user and a disabled signup, each with an
- * `error_code` beside it, while a refusal relayed from the provider arrives with none. The obvious
- * test reads an expired link as a change of mind. And `error` itself is absent for a status
- * outside GoTrue's OAuth mapping — a rate-limited link arrives with `error_code` alone.
+ * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel.
+ * That is their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue
+ * writes that same value for an expired email link, a banned user and a disabled signup, each with
+ * an `error_code` beside it, while a refusal relayed from the provider arrives with none. The
+ * obvious test reads an expired link as a change of mind. And `error` itself is absent for a status
+ * outside GoTrue's OAuth mapping. A rate-limited link arrives with `error_code` alone.
  */
 export function parseAuthCallback(search: string | URLSearchParams, hash = ""): AuthCallback {
   const query = new URLSearchParams(search);

package/src/theme.ts

@@ -109,10 +109,10 @@ declare global {
  * "system" is stored as the word, not as an empty key. An empty key means the default, and the
  * default is not always "system".
  *
- * **It writes to the page when the theme changes, and at no other time.** A page may override
- * the class for its own lifetime — a public booking page that is always light — and keeps that
- * override until the theme really changes. Repainting on every resync would undo it a moment
- * later, because `pageshow` fires on every load, not only on a back-forward restore.
+ * **It writes to the page when the theme changes, and at no other time.** A page may override the
+ * class for its own lifetime, as a public booking page that is always light does, and keeps that
+ * override until the theme really changes. Repainting on every resync would undo it a moment later,
+ * because `pageshow` fires on every load, not only on a back-forward restore.
  */
 export function startTheme(options: ThemeOptions): ThemeController {
   const running = window.__frontkitTheme;

package/src/ui/class-name.ts

@@ -10,10 +10,9 @@ export type StateClassName<State> = string | ((state: State) => string | undefin
 /**
  * Merge a wrapper's own classes with the caller's, keeping BOTH forms working.
  *
- * `cn()` on its own silently DROPS the function form — clsx walks strings, arrays and plain
- * objects, and a function is none of the three — so a caller styling by `open` or
- * `transitionStatus` would get an empty class and no warning. Always returning a function
- * keeps one code path for both.
+ * `cn()` on its own silently DROPS the function form. clsx walks strings, arrays and plain objects,
+ * and a function is none of the three, so a caller styling by `open` or `transitionStatus` would
+ * get an empty class and no warning. Always returning a function keeps one code path for both.
  */
 export function mergeClassName<State>(
   base: ClassValue,

package/src/ui/combobox.tsx

@@ -37,7 +37,7 @@ export function comboboxInputValue<T>(
   return value === null ? "" : getLabel(value);
 }
 
-/** A loading state needs the line that says so — there is no default, and no English. */
+/** Pass text for the loading state. There is no default text or English fallback. */
 type ComboboxLoadingState =
   { loading: boolean; loadingHint: ReactNode } | { loading?: undefined; loadingHint?: undefined };
 
@@ -60,15 +60,15 @@ export type ComboboxProps<T> = Omit<
 > & {
   value: T | null;
   /**
-   * Items for the current query. Filtering is yours: this passes `filter={null}` to Base UI,
-   * so the list shows exactly what you return — a server search, a fuzzy match, a bounded
-   * page. Bound it here if it needs bounding; there is no cap in the wrapper, because a cap
-   * would quietly truncate a list a caller meant to show whole.
+   * Items for the current query. Filtering is yours: this passes `filter={null}` to Base UI, so the
+   * list shows exactly what you return, whether it is a server search, a fuzzy match or a bounded
+   * page. Bound it here if it needs bounding; there is no cap in the wrapper, because a cap would
+   * quietly truncate a list a caller meant to show whole.
    */
   search: (query: string) => readonly T[];
   /** Stable identity of an item: its React key, and how two items are compared. */
   getKey: (item: T) => string;
-  /** The item's text — what the input shows once it is picked, and what typeahead matches. */
+  /** The item's text, shown in the input once it is picked and used for typeahead matches. */
   getLabel: (item: T) => string;
   renderItem?: (item: T) => ReactNode;
   /**
@@ -76,7 +76,7 @@ export type ComboboxProps<T> = Omit<
    * end, and this is the line that offers one.
    */
   emptyHint: ReactNode;
-  /** Label for the clear button. Required — it is a button with an icon and no text. */
+  /** Label for the clear button. Required because the button has an icon and no text. */
   clearLabel: string;
   /** Label for the button that opens the list. Required, same reason. */
   openLabel: string;
@@ -88,10 +88,10 @@ export type ComboboxProps<T> = Omit<
   popupClassName?: StateClassName<Primitive.Popup.State>;
   inputProps?: Primitive.Input.Props;
   /**
-   * Positioner props — `align`, `side`, `sideOffset`, `collisionPadding`, and the stacking
-   * order. The default `z-[60]` puts the list above the overlay layer (z-50: dialog, drawer);
-   * raise it with `positionerProps={{ className: "z-[80]" }}` if the app stacks something
-   * higher than a dialog above it.
+   * Positioner props: `align`, `side`, `sideOffset`, `collisionPadding` and the stacking order. The
+   * default `z-[60]` puts the list above the overlay layer (z-50: dialog, drawer); raise it with
+   * `positionerProps={{ className: "z-[80]" }}` if the app stacks something higher than a dialog
+   * above it.
    */
   positionerProps?: Primitive.Positioner.Props;
 } & ComboboxLoadingState;

package/src/ui/dialog.tsx

@@ -22,9 +22,9 @@ export type DialogContentProps = Primitive.Popup.Props & {
    */
   label?: string;
   /**
-   * Label for the built-in close button — REQUIRED to get one, which is the whole point:
-   * passing the label is the only way to render the button, so an unlabelled close button
-   * cannot be written. There is no default string, because a default would be English.
+   * Label for the built-in close button. REQUIRED to render the button: passing the label is the
+   * only way to render the button, so an unlabelled close button cannot be written. There is no
+   * default string, because a default would be English.
    */
   closeLabel?: string;
   backdropClassName?: StateClassName<Primitive.Backdrop.State>;
@@ -39,8 +39,8 @@ export type DialogContentProps = Primitive.Popup.Props & {
  * page behind it) and is capped to the viewport, so a tall dialog is never taller than the
  * screen it opens on.
  *
- * Everything else — padding, radius, shadow, type — is the product's. What is here is what
- * makes the primitive work.
+ * Padding, radius, shadow and type all belong to the product. What is here is what makes the
+ * primitive work.
  */
 export function DialogContent({
   className,

package/src/ui/drawer.tsx

@@ -38,9 +38,9 @@ const popupSide: Record<DrawerSide, string> = {
 /**
  * Where the portal mounts, and whether the drawer covers the page or a box inside it.
  *
- * A scoped drawer positions itself `absolute` against a container instead of `fixed` against
- * the viewport — so it MUST be given that container, or it lands in `<body>` and positions
- * against a box that is not there. The two travel together in the type.
+ * A scoped drawer positions itself `absolute` against a container instead of `fixed` against the
+ * viewport, so it MUST be given that container, or it lands in `<body>` and positions against a box
+ * that is not there. The two travel together in the type.
  *
  * The container also needs a positioning context of its own (`relative`): `absolute` walks up
  * to the nearest positioned ancestor, so a static container hands the drawer the whole page
@@ -56,20 +56,20 @@ export type DrawerProps<Payload = unknown> = Omit<
 > &
   DrawerPortalTarget & {
     /**
-     * Which edge it comes from. This also sets `swipeDirection` on the root — the two must
-     * agree, and a mismatch is silent: the drawer looks right and dismisses on a swipe
-     * towards the screen it is attached to.
+     * Which edge it comes from. This also sets `swipeDirection` on the root. The two must agree,
+     * and a mismatch is silent: the drawer looks right and dismisses on a swipe towards the screen
+     * it is attached to.
      */
     side?: DrawerSide;
     /** Accessible name, for a drawer with no visible `DrawerTitle`. */
     label?: string;
     children?: ReactNode;
-    /** Classes for the popup — the panel itself. */
+    /** Classes for the popup panel. */
     className?: StateClassName<Primitive.Popup.State>;
     backdropClassName?: StateClassName<Primitive.Backdrop.State>;
     viewportClassName?: StateClassName<Primitive.Viewport.State>;
     contentClassName?: StateClassName<Primitive.Content.State>;
-    /** Popup-level props the wrapper does not own — `initialFocus`, `finalFocus`, `data-*`. */
+    /** Popup-level props the wrapper does not own, such as `initialFocus`, `finalFocus` and `data-*`. */
     popupProps?: Primitive.Popup.Props;
   };
 
@@ -78,8 +78,8 @@ export type DrawerProps<Payload = unknown> = Omit<
  * composed once here because the parts have to be arranged in exactly this order to work at
  * all, and because two of the four rules below cost someone a bug that no test would catch.
  *
- * Everything the root takes — `open`, `onOpenChange`, `modal`, `snapPoints`, `actionsRef`,
- * `data-*` — passes straight through.
+ * Every root prop passes straight through, including `open`, `onOpenChange`, `modal`, `snapPoints`,
+ * `actionsRef` and `data-*`.
  */
 export function Drawer<Payload = unknown>({
   side = "right",

package/src/ui/input.tsx

@@ -12,8 +12,8 @@ const TEXTAREA_MAX_HEIGHT = 160;
 /**
  * The inline height an autosizing textarea should carry, or `""` for "leave it to CSS".
  *
- * ponytail: this whole observer is here only until `field-sizing: content` is baseline —
- * one CSS line does the same job. Ceiling: it does not exist in every browser we support yet.
+ * ponytail: this whole observer is here only until `field-sizing: content` is baseline. One CSS
+ * line does the same job. Ceiling: it does not exist in every browser we support yet.
  */
 export function textareaHeight(clientWidth: number, scrollHeight: number): string {
   if (clientWidth < TEXTAREA_MIN_AUTO_WIDTH) return "";

package/src/ui/menu.tsx

@@ -37,18 +37,18 @@ export type MenuContentProps = Primitive.Popup.Props & {
   /** Where the portal mounts. Defaults to `<body>`. */
   container?: Primitive.Portal.Props["container"];
   /**
-   * Positioner props — `side`, `align`, `sideOffset`, `collisionPadding`, and the stacking
-   * order. The default `z-[60]` puts the menu above the overlay layer (z-50: dialog, drawer)
-   * so a menu opened inside a dialog is not painted behind it; raise it with
-   * `positionerProps={{ className: "z-[80]" }}` if the app stacks something higher.
+   * Positioner props: `side`, `align`, `sideOffset`, `collisionPadding` and the stacking order. The
+   * default `z-[60]` puts the menu above the overlay layer (z-50: dialog, drawer) so a menu opened
+   * inside a dialog is not painted behind it; raise it with `positionerProps={{ className: "z-[80]"
+   * }}` if the app stacks something higher.
    */
   positionerProps?: Primitive.Positioner.Props;
 };
 
 /**
- * A dropdown of decisions — the account menu, a row's actions, a picker. Portal, positioner
- * and popup composed once, for the same reason the dialog's are: the arrangement is not
- * optional and getting it wrong throws a number.
+ * A dropdown for choices, such as the account menu, a row's actions or a picker. Portal, positioner
+ * and popup composed once, for the same reason the dialog's are: the arrangement is not optional
+ * and getting it wrong throws a number.
  *
  * Roving focus, typeahead, escape, outside-dismiss and focus return all come from Base UI.
  * Nothing here re-implements any of them.
@@ -146,7 +146,7 @@ export function MenuGroup({ label, children, ...rest }: Primitive.Group.Props &
   );
 }
 
-/** A set of choices — theme, locale, one axis of a filter. Same caption rule as `MenuGroup`. */
+/** A set of choices for a theme, locale or one axis of a filter. Same caption rule as `MenuGroup`. */
 export function MenuRadioGroup({
   label,
   children,