@recipe-book/react 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -12,44 +12,111 @@ type NotAnImageComponent = 'Recipe.Image: as must be a component whose src and a
 /** `C` when its `src` and `alt` props take a string, else `NotAnImageComponent`. */
 type ImageComponent<C extends ElementType> = 'src' | 'alt' extends keyof ComponentPropsWithoutRef<C> ? ImageAttributes extends Pick<ComponentPropsWithoutRef<C>, 'src' | 'alt'> ? C : NotAnImageComponent : NotAnImageComponent;
 /**
- * The props of `as`, an `<img>` by default, with `src` and `alt` optional.
- * `RecipeImageProps<typeof NextImage>` types a wrapper around `next/image`.
+ * The props of `<Recipe.Image>`: those of `C` without its `ref`, with `src`
+ * and `alt` optional, plus `as`. `C` defaults to `'img'`. Use it to type a
+ * wrapper that takes what `<Recipe.Image as={C}>` takes.
+ *
+ * @example
+ * import NextImage from 'next/image'
+ *
+ * function Hero(props: Recipe.RecipeImageProps<typeof NextImage>) {
+ *   return <Recipe.Image {...props} as={NextImage} className="hero" />
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/image/#type-a-wrapper
  */
 type RecipeImageProps<C extends ElementType = 'img'> = {
     /**
-     * The component to render instead of `<img>`, such as `next/image`. It gets
-     * `src`, `alt`, `data-recipe-image` and the ref, and `Recipe.Image` takes
-     * its props. Its `src` and `alt` must take strings, and its other required
-     * props are required on `Recipe.Image`. From a Server Component, pass a
-     * Client Component: one whose module starts with `'use client'`, as
+     * The component to render instead of `<img>`, such as `next/image`. It
+     * gets `src`, `alt`, `data-recipe-image` and the ref, and `Recipe.Image`
+     * takes its props. Its `src` and `alt` must take strings, and its other
+     * required props are required on `Recipe.Image`. From a Server Component,
+     * pass a Client Component: one whose module starts with `'use client'`, as
      * `next/image`'s does.
+     *
+     * @defaultValue `'img'`
+     *
+     * @see https://recipe-book.siraj.page/reference/react/image/#render-another-component
      */
     as?: ImageComponent<C> | undefined;
 } & Omit<ComponentPropsWithoutRef<C>, 'as' | 'src' | 'alt'> & {
-    /** Replaces the recipe's `image`, such as with a CDN URL; nothing renders when the recipe has none. */
+    /**
+     * Replaces the recipe's `image`, such as with a CDN URL. Nothing renders
+     * when the recipe has no `image`, even with `src`. With `as`, it takes
+     * that component's `src` type, such as `string | StaticImport` for
+     * `next/image`.
+     *
+     * @defaultValue The recipe's `image`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/image/#image
+     */
     src?: (ComponentPropsWithoutRef<C> extends {
         src?: infer S;
     } ? S : never) | undefined;
-    /** The alt text. Defaults to the recipe's `name`; pass `''` for a decorative image. */
+    /**
+     * The alt text. Pass `''` for a decorative image.
+     *
+     * @defaultValue The recipe's `name`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/image/#decorative-images
+     */
     alt?: string | undefined;
 };
 /**
  * The recipe's image, as an `<img>` or the component passed to `as`, or
  * nothing when the recipe has none. `src` defaults to the recipe's image and
- * `alt` to its name; pass `alt=""` when the image is decorative.
+ * `alt` to its name; pass `alt=""` when the image is decorative. Other props
+ * pass through, and it always sets `data-recipe-image`.
+ *
+ * `Recipe.Image` takes `as`, not `asChild`, so a component such as
+ * `next/image` gets `src` and `alt` from the recipe and still has its
+ * required props checked.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @example
+ * import NextImage from 'next/image'
+ *
+ * function RecipeHero() {
+ *   return <Recipe.Image as={NextImage} width={1200} height={800} />
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/image/
  */
 declare const Image: <C extends ElementType = "img">(props: RecipeImageProps<C> & {
-    /** Set to the `<img>`, or passed to the `as` component. Left unset when the recipe has no image. */
+    /**
+     * Set to the `<img>`, or passed to the `as` component. Left unset when the recipe has no image.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/image/#image
+     */
     ref?: Ref<ComponentRef<C>> | undefined;
 }) => ReactNode;
 
-/** What `useRecipeState()` takes. The state props of `<Recipe.Root>` are the same. */
+/**
+ * What `useRecipeState()` takes. The state props of `<Recipe.Root>` are the
+ * same.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#recipestateoptions
+ */
 type RecipeStateOptions = {
-    /** A parsed recipe, as returned by `parseRecipe` in `@recipe-book/core`. */
+    /** A parsed recipe, as returned by `parseRecipe` in `@recipe-book/react/core`. */
     recipe: Recipe;
-    /** The number of servings to show. Passing it makes servings controlled. */
+    /**
+     * The number of servings to show. Passing it makes servings controlled. A
+     * number outside the servings window shows `defaultServings` instead, with a
+     * warning in development.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/root/#controlled-and-uncontrolled-state
+     */
     servings?: number | undefined;
-    /** Starting servings when uncontrolled; defaults to the recipe's servings, then its yield, then 1. */
+    /**
+     * Starting servings when uncontrolled. A number outside the servings window
+     * falls back to the scaling base, with a warning in development.
+     *
+     * @defaultValue The recipe's scaling base: its servings, then its yield,
+     * then 1.
+     * @see https://recipe-book.siraj.page/reference/react/root/#scaling-base
+     */
     defaultServings?: number | undefined;
     /**
      * Called when `setServings` accepts a number other than the current one,
@@ -81,7 +148,12 @@ type StepItem = Step$1 & {
     /** The step's position, counted from 1 across sections. */
     number: number;
 };
-/** A section of a recipe's ingredients or steps. Untitled sections have no `title`. */
+/**
+ * A section of a recipe's ingredients or steps. Untitled sections have no
+ * `title`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#recipesection
+ */
 type RecipeSection<T> = {
     /** The section's id from the recipe. */
     id: string;
@@ -90,7 +162,11 @@ type RecipeSection<T> = {
     /** The ingredients or steps in the section. */
     items: T[];
 };
-/** What `useRecipe()` and `useRecipeState()` return. */
+/**
+ * What `useRecipe()` and `useRecipeState()` return.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#recipestate
+ */
 type RecipeState = {
     /** The parsed recipe. */
     recipe: Recipe;
@@ -98,9 +174,13 @@ type RecipeState = {
     servings: number;
     /**
      * Calls `onServingsChange` with a number other than the current one, and
-     * changes the servings unless controlled; ignores one outside a millionth to
-     * a million times the scaling base. While a controlled `servings` is outside
-     * that range, passing the number shown calls `onServingsChange` too.
+     * changes the servings unless controlled. Ignores a number outside the
+     * servings window, from a millionth to a million times the scaling base
+     * including both ends, and warns about it in development. While a
+     * controlled `servings` is outside that window, passing the number shown
+     * calls `onServingsChange` too.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/root/#servings-window
      */
     setServings: (servings: number) => void;
     /** From `resolveRecipe`: `servings` divided by the recipe's servings amount, else its yield amount, else 1. */
@@ -136,23 +216,61 @@ type RecipeState = {
  *
  * @throws {RecipeBookError} `invalid_argument` in development when `recipe`
  *   isn't a parsed recipe.
+ *
+ * @param options - The recipe and its state.
+ * @returns The recipe, its servings and display system with their setters,
+ *   its ingredients at those settings, and its numbered steps.
+ *
+ * @example
+ * import type { ParsedRecipe } from '@recipe-book/react/core'
+ * import * as Recipe from '@recipe-book/react'
+ *
+ * function ServingsSummary({ recipe }: { recipe: ParsedRecipe }) {
+ *   const { servings, scale } = Recipe.useRecipeState({
+ *     recipe,
+ *     defaultServings: 8,
+ *   })
+ *   return <p>{`Serves ${servings}, scaled ×${scale}`}</p>
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#userecipestate
  */
 declare function useRecipeState(options: RecipeStateOptions): RecipeState;
 
-/** Levels a section heading can take; level 1 belongs to the page. */
+/**
+ * The heading levels `<Recipe.Ingredients>` and `<Recipe.Steps>` take as
+ * `headingLevel` for section titles; level 1 belongs to the page's title.
+ * Both default to 3, for sections under an `<h2>` such as "Ingredients". Pass
+ * the level below your own heading to keep the outline in order.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#recipeheadinglevel
+ */
 type RecipeHeadingLevel = 2 | 3 | 4 | 5 | 6;
 
-/** Attributes for the wrapping `<div>`, plus `headingLevel`; `children` renders each section. */
-type RecipeIngredientsProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
+/**
+ * Attributes for the wrapping `<div>` other than `dangerouslySetInnerHTML`,
+ * plus `headingLevel`; `children` renders each section.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredients
+ */
+type RecipeIngredientsProps = Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'dangerouslySetInnerHTML'> & {
     /**
      * Heading level of section titles in the default rendering. Defaults to 3,
      * for ingredients under an `<h2>` such as "Ingredients".
+     *
+     * @defaultValue `3`
+     * @see https://recipe-book.siraj.page/guides/make-a-recipe-accessible/#set-heading-levels
      */
     headingLevel?: RecipeHeadingLevel | undefined;
     /**
      * Renders each section instead of the default. Each result is keyed for
      * you, so return one element or a fragment; an array's items need their own
      * keys, as anywhere in React.
+     *
+     * @defaultValue A `<section>` named by the section's heading, or a `<div>`
+     * for an untitled section, around a `<Recipe.IngredientList>` of its
+     * ingredients.
+     * @see https://recipe-book.siraj.page/reference/react/ingredients/#render-your-own-sections
      */
     children?: ((section: RecipeSection<IngredientItem>) => ReactNode) | undefined;
 };
@@ -160,33 +278,82 @@ type RecipeIngredientsProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'>
  * The recipe's ingredients at the current servings and display system, one
  * block per section. A titled section renders as a `<section>` named by its
  * heading, then a `<Recipe.IngredientList>`.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ * @throws {RecipeBookError} `invalid_argument` from the `<Recipe.Ingredient>`
+ *   it renders for each item by default, when Root's `locale` isn't a language
+ *   tag that `Intl` accepts, such as `'en_US'`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe}>
+ *   <h2>Ingredients</h2>
+ *   <Recipe.Ingredients />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredients
  */
 declare const Ingredients: ForwardRefExoticComponent<RecipeIngredientsProps & RefAttributes<HTMLDivElement>>;
-/** Attributes for the `<ul>`, plus the `section` to list; `children` renders each ingredient. */
-type RecipeIngredientListProps = Omit<ComponentPropsWithoutRef<'ul'>, 'children'> & {
+/**
+ * Attributes for the `<ul>` other than `dangerouslySetInnerHTML`, plus the
+ * `section` to list; `children` renders each ingredient.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientlist
+ */
+type RecipeIngredientListProps = Omit<ComponentPropsWithoutRef<'ul'>, 'children' | 'dangerouslySetInnerHTML'> & {
     /** The section to list. Defaults to every ingredient in the recipe. */
     section?: RecipeSection<IngredientItem> | undefined;
     /**
      * Renders each ingredient instead of `<Recipe.Ingredient>`. Each result is
      * keyed for you, so return one element or a fragment; an array's items need
      * their own keys, as anywhere in React.
+     *
+     * @defaultValue `(item) => <Recipe.Ingredient item={item} />`
+     * @see https://recipe-book.siraj.page/reference/react/ingredients/#render-your-own-ingredients
      */
     children?: ((item: IngredientItem) => ReactNode) | undefined;
 };
-/** An unordered list of ingredients. */
+/**
+ * An unordered list of ingredients, one `<Recipe.Ingredient>` each unless
+ * `children` renders them.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ * @throws {RecipeBookError} `invalid_argument` from the `<Recipe.Ingredient>`
+ *   it renders for each item by default, when Root's `locale` isn't a language
+ *   tag that `Intl` accepts, such as `'en_US'`.
+ *
+ * @example
+ * <Recipe.IngredientList>
+ *   {(item) => (
+ *     <Recipe.Ingredient item={item}>
+ *       <Recipe.IngredientName /> <Recipe.IngredientQuantity />
+ *     </Recipe.Ingredient>
+ *   )}
+ * </Recipe.IngredientList>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientlist
+ */
 declare const IngredientList: ForwardRefExoticComponent<RecipeIngredientListProps & RefAttributes<HTMLUListElement>>;
-/** Attributes for the `<li>`, plus the `item` to render and `asChild`. */
-type RecipeIngredientProps = ComponentPropsWithoutRef<'li'> & {
+/**
+ * Attributes for the `<li>` other than `dangerouslySetInnerHTML`, plus the
+ * `item` to render and `asChild`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredient
+ */
+type RecipeIngredientProps = Omit<ComponentPropsWithoutRef<'li'>, 'dangerouslySetInnerHTML'> & {
     /** The ingredient to render, such as one that `<Recipe.IngredientList>` passes to its `children`. */
     item: IngredientItem;
     /**
      * Renders the line as its one element child, such as `<motion.li layout />`,
-     * instead of an `<li>`. A prop on the child wins, except that the line's
+     * instead of an `<li>`. Render an `<li>` or a component that renders one, so
+     * the list keeps its items. A prop on the child wins, except that the line's
      * `tabIndex` wins, `className`s join, `style` merges key by key with the
      * child winning, both event handlers run (the child's first), and both refs
      * are set. The child's own children replace the line's, so an empty child
      * gets the default line. With anything but one element child, it renders
      * its own `<li>`, with a warning in development.
+     *
+     * @defaultValue `false`
+     * @see https://recipe-book.siraj.page/reference/react/ingredients/#render-your-own-element
      */
     asChild?: boolean | undefined;
 };
@@ -202,16 +369,27 @@ type RecipeIngredientProps = ComponentPropsWithoutRef<'li'> & {
  * or `converted` into the display system. Unquantified lines have
  * `data-unquantified` instead. Optional ingredients have `data-optional`.
  *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ * @throws {RecipeBookError} `invalid_argument` when Root's `locale` isn't a
+ *   language tag that `Intl` accepts, such as `'en_US'`; when `item` isn't
+ *   `{ ingredient, quantity? }`, such as an authored ingredient; or when an
+ *   `item` you build has an amount that isn't a finite number greater than 0
+ *   or a range of them, or a range whose `min` isn't less than its `max`.
+ * @throws {RecipeBookError} `unknown_unit` when the item's unit isn't a unit
+ *   ID.
+ *
  * @example
  * <Recipe.Ingredient item={item} className="flex gap-2">
  *   <Recipe.IngredientQuantity className="w-24 tabular-nums" />
  *   <Recipe.IngredientName />
  *   <Recipe.IngredientNote className="text-stone-500" />
  * </Recipe.Ingredient>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredient
  */
 declare const Ingredient: ForwardRefExoticComponent<RecipeIngredientProps & RefAttributes<HTMLLIElement>>;
 /** Attributes for an ingredient sub-part's `<span>`, plus `asChild`; `children` go before its text. */
-type IngredientTextProps = ComponentPropsWithoutRef<'span'> & {
+type IngredientTextProps = Omit<ComponentPropsWithoutRef<'span'>, 'dangerouslySetInnerHTML'> & {
     /**
      * Renders as its one element child, such as `<a href={url} />`, instead of a
      * `<span>`, with the text after the child's own children. A prop on the
@@ -233,6 +411,10 @@ type RecipeIngredientQuantityProps = IngredientTextProps;
  * <Recipe.IngredientQuantity>
  *   {item.origin === 'converted' && '≈ '}
  * </Recipe.IngredientQuantity>
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Ingredient>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientquantity
  */
 declare const IngredientQuantity: ForwardRefExoticComponent<RecipeIngredientQuantityProps & RefAttributes<HTMLSpanElement>>;
 /** Attributes for the `<span>`, plus `asChild`; `children` go before the name. */
@@ -246,6 +428,10 @@ type RecipeIngredientNameProps = IngredientTextProps;
  * <Recipe.IngredientName asChild>
  *   <a href={`/glossary/${item.id}`} />
  * </Recipe.IngredientName>
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Ingredient>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientname
  */
 declare const IngredientName: ForwardRefExoticComponent<RecipeIngredientNameProps & RefAttributes<HTMLSpanElement>>;
 /** Attributes for the `<span>`, plus `asChild`; `children` go before the note. */
@@ -256,6 +442,10 @@ type RecipeIngredientNoteProps = IngredientTextProps;
  *
  * @example
  * <Recipe.IngredientNote className="text-stone-500" />
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Ingredient>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientnote
  */
 declare const IngredientNote: ForwardRefExoticComponent<RecipeIngredientNoteProps & RefAttributes<HTMLSpanElement>>;
 /** Attributes for the `<span>`, plus `asChild`; `children` go before the label. */
@@ -267,28 +457,95 @@ type RecipeIngredientOptionalProps = IngredientTextProps;
  *
  * @example
  * <Recipe.IngredientOptional className="text-stone-500" />
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Ingredient>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/ingredients/#ingredientoptional
  */
 declare const IngredientOptional: ForwardRefExoticComponent<RecipeIngredientOptionalProps & RefAttributes<HTMLSpanElement>>;
 
-/** Attributes for the `<script>` but `type`, `src` and content, plus `toJsonLd`'s options. */
-type RecipeJsonLdProps = Pick<ToJsonLdOptions, 'servings' | 'system' | 'url' | 'extra'> & Omit<ComponentPropsWithoutRef<'script'>, 'type' | 'children' | 'dangerouslySetInnerHTML' | 'src'>;
+/**
+ * The props of `<Recipe.JsonLd>`: `toJsonLd`'s `servings`, `system`, `url`
+ * and `extra`, passed to it as they are, plus the `<script>`'s attributes but
+ * `type`, `src` and its content, which `<Recipe.JsonLd>` sets.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/json-ld/#jsonld
+ */
+type RecipeJsonLdProps = {
+    /**
+     * Writes the recipe at this many servings, as `resolveRecipe` scales it.
+     * The Root's servings don't change it.
+     *
+     * @defaultValue The recipe's own servings, unscaled.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/json-ld/#jsonld
+     */
+    servings?: ToJsonLdOptions['servings'];
+    /**
+     * Writes quantities in this measurement system. The Root's system doesn't
+     * change it.
+     *
+     * @defaultValue `recipe.system`, then `'metric'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/json-ld/#jsonld
+     */
+    system?: ToJsonLdOptions['system'];
+    /**
+     * The recipe page's URL. Each step gets it as `url`, with the step's id,
+     * percent-encoded, as the fragment; without it, steps have no `url`.
+     * `<Recipe.Step>` renders no `id`, so pass it the step's `id` for the
+     * fragment to point at it.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/json-ld/#step-ids
+     */
+    url?: ToJsonLdOptions['url'];
+    /**
+     * schema.org fields the recipe doesn't model, such as `author`,
+     * `datePublished`, or `keywords`, written as you pass them. A field
+     * `toJsonLd` writes from the recipe wins; `@context` and `@type` are always
+     * its own. A field that is `undefined` is left out, so
+     * `{ image: maybeImage }` adds an image only when there is one, and an
+     * `image` here stops the missing-image warning. A field `toJsonLd` writes
+     * from a recipe takes the type `SchemaOrgRecipe` gives it here too, so an
+     * `image` is a URL. Pass the `extra` that `fromJsonLd` returned to write them
+     * back.
+     *
+     * @example
+     * <Recipe.JsonLd
+     *   url="https://example.com/pancakes"
+     *   extra={{ author: { '@type': 'Person', name: 'Ada Lovelace' } }}
+     * />
+     *
+     * @see https://recipe-book.siraj.page/reference/react/json-ld/#jsonld
+     */
+    extra?: ToJsonLdOptions['extra'];
+} & Omit<ComponentPropsWithoutRef<'script'>, 'type' | 'children' | 'dangerouslySetInnerHTML' | 'src'>;
 /**
  * The recipe as schema.org Recipe JSON-LD, for search engines' recipe results,
  * in a `<script type="application/ld+json">` with `<` escaped as `\u003c`.
  * Writes the recipe as authored: at its own servings and in `recipe.system`,
  * else metric, unless `servings` or `system` say otherwise. Root's current
- * servings and system don't change it. The text is in English.
+ * servings and system don't change it. The text is in English. Other props
+ * pass to the `<script>`, and it always sets `data-recipe-json-ld`.
  *
  * In development, logs to the browser console the warnings that `toJsonLd`
  * returns, such as for a missing `image`, unless the previous render had the
- * same ones in the same order.
+ * same ones in the same order. Nothing logs where it renders only on the
+ * server, such as in an Astro page without a `client:` directive.
  *
  * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
  *
  * @example
- * <Recipe.Root recipe={recipe}>
- *   <Recipe.JsonLd url="https://example.com/pancakes" />
- * </Recipe.Root>
+ * // app/pancakes/page.tsx, a Server Component: no 'use client' needed
+ * export default function Page() {
+ *   return (
+ *     <Recipe.Root recipe={recipe}>
+ *       <Recipe.JsonLd url="https://example.com/pancakes" />
+ *     </Recipe.Root>
+ *   )
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/json-ld/
  */
 declare const JsonLd: ForwardRefExoticComponent<RecipeJsonLdProps & RefAttributes<HTMLScriptElement>>;
 
@@ -299,80 +556,229 @@ declare const JsonLd: ForwardRefExoticComponent<RecipeJsonLdProps & RefAttribute
  * A new key is additive: labels that leave it out keep its English default,
  * and a label pack checked with `satisfies RecipeLabels` gets a compile error
  * naming the new key.
+ *
+ * @example
+ * const spanish = {
+ *   servings: 'Raciones',
+ *   servingUnit: { one: 'ración', other: 'raciones' },
+ *   system: 'Sistema de medida',
+ *   metric: 'Métrico',
+ *   us: 'EE. UU.',
+ *   fan: 'con ventilador',
+ *   optional: '(opcional)',
+ *   to: 'a',
+ * } satisfies Recipe.RecipeLabels
+ *
+ * <Recipe.RecipeBookProvider locale="es-ES" labels={spanish}>
+ *   {children}
+ * </Recipe.RecipeBookProvider>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/provider/
  */
 type RecipeLabels = {
-    /** Accessible name of the servings controls. */
+    /**
+     * Accessible name of `<Recipe.ServingsSelect>` and `<Recipe.ServingsInput>`,
+     * unless they get an `aria-label` or `aria-labelledby`. Defaults to
+     * `'Servings'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     servings: string;
-    /** Unit for the servings count: "1 serving", "4 servings". */
+    /**
+     * Unit for the servings count: "1 serving", "4 servings".
+     * `<Recipe.ServingsSelect>` words each option with it, for a recipe with
+     * `servings`. Defaults to `{ one: 'serving', other: 'servings' }`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     servingUnit: {
         /** Follows 1 and a fraction below 1: "1 serving", "½ serving". */
         one: string;
         /** Follows decimals and any other number: "0.3 servings", "4 servings". */
         other: string;
     };
-    /** Accessible name of the system toggle. */
+    /**
+     * Accessible name of `<Recipe.SystemToggle>`, unless it gets an
+     * `aria-label` or `aria-labelledby`. Defaults to `'Measurement system'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     system: string;
-    /** Name of the metric system. */
+    /**
+     * Name of the metric system, shown by a `<Recipe.SystemOption>` for
+     * `'metric'` that has no children, or an empty `asChild` child. Defaults to
+     * `'Metric'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     metric: string;
-    /** Name of the US system. */
+    /**
+     * Name of the US system, shown by a `<Recipe.SystemOption>` for `'us'` that
+     * has no children, or an empty `asChild` child. Defaults to `'US'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     us: string;
-    /** Marker after a fan-oven temperature in step text: "160 °C fan". */
+    /**
+     * Marker after a fan-oven temperature in `<Recipe.StepText>`: "160 °C fan".
+     * An empty string leaves it out. Defaults to `'fan'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     fan: string;
-    /** Marker after an optional ingredient, shown as is, punctuation included. */
+    /**
+     * Marker after an optional ingredient, shown as is, punctuation included.
+     * `<Recipe.IngredientOptional>` renders it, and the function from
+     * `useFormatIngredient()` returns it as `optional`. Defaults to
+     * `'(optional)'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     optional: string;
-    /** Spoken between the ends of a range, "2 to 3 tbsp". Screen readers only. */
+    /**
+     * Spoken between the ends of a range, "2 to 3 tbsp". Screen readers only:
+     * `<Recipe.IngredientQuantity>` keeps the visible dash, "2–3 tbsp".
+     * Defaults to `'to'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     */
     to: string;
 };
 
 /** The locale, labels, and starting system that `RecipeBookProvider` and `<Recipe.Root>` take. */
 type RecipeBookConfig = {
-    /** BCP 47 locale for formatting numbers. Defaults to the outer provider's, then `'en-US'`. */
+    /**
+     * A language tag that `Intl` accepts, such as `'de-DE'`, for formatting
+     * numbers. With a tag it rejects, such as `'en_US'`, formatting a number
+     * throws `invalid_argument`.
+     *
+     * @defaultValue The outer provider's `locale`, then `'en-US'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/#recipebookprovider
+     * @see https://recipe-book.siraj.page/reference/react/root/#root
+     */
     locale?: string | undefined;
-    /** Overrides for built-in text. Unset keys keep the outer value. */
+    /**
+     * Built-in text to override. A key you leave out keeps the outer provider's
+     * value, then its English default. Pass an object that keeps its identity
+     * between renders: an equal but new one re-renders most parts.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/
+     * @see https://recipe-book.siraj.page/reference/react/root/
+     */
     labels?: RecipeLabelOverrides | undefined;
-    /** Initial display system. Defaults to the outer provider's, then the system each recipe was written in, then `'metric'`. */
+    /**
+     * The measurement system a Root starts in, unless its `system` is
+     * controlled. Defaults to the outer provider's, then the system its recipe
+     * was written in, then `'metric'`. A value other than `'metric'` or `'us'`
+     * counts as missing.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/#recipebookprovider
+     * @see https://recipe-book.siraj.page/reference/react/root/#root
+     */
     defaultSystem?: System | undefined;
 };
 /**
+ * Built-in text to override, for the `labels` prop of `RecipeBookProvider` and
+ * `<Recipe.Root>`.
+ *
  * Any keys of `RecipeLabels`. A value replaces the whole key, so `servingUnit`
  * needs both `one` and `other`.
+ *
+ * @example
+ * // At module scope, so it keeps its identity between renders.
+ * const labels = {
+ *   servings: 'Portions',
+ *   servingUnit: { one: 'portion', other: 'portions' },
+ * } satisfies Recipe.RecipeLabelOverrides
+ *
+ * <Recipe.Root recipe={recipe} labels={labels}>
+ *   <Recipe.ServingsSelect />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/provider/#recipelabeloverrides
  */
 type RecipeLabelOverrides = {
     [Key in keyof RecipeLabels]?: RecipeLabels[Key] | undefined;
 };
-/** Defaults for every Root below it, plus `children`. */
+/**
+ * Props of `RecipeBookProvider`: defaults for every Root below it, plus
+ * `children`.
+ *
+ * @example
+ * export function AppProvider(props: Recipe.RecipeBookProviderProps) {
+ *   return <Recipe.RecipeBookProvider locale="en-GB" {...props} />
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/provider/#recipebookprovider
+ */
 type RecipeBookProviderProps = RecipeBookConfig & {
-    /** The part of the app that uses these defaults. */
+    /**
+     * The part of the app that uses these defaults.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/provider/#recipebookprovider
+     */
     children?: ReactNode;
 };
 /**
  * App-wide defaults for every `<Recipe.Root>` below it. Takes only data, so it
  * can wrap a layout rendered as a Server Component. Nested providers override
  * the outer one key by key.
+ *
+ * @example
+ * // app/layout.tsx
+ * <Recipe.RecipeBookProvider defaultSystem="metric">
+ *   {children}
+ * </Recipe.RecipeBookProvider>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/provider/#recipebookprovider
  */
 declare function RecipeBookProvider({ children, ...config }: RecipeBookProviderProps): JSX.Element;
 /**
- * The state of the nearest `<Recipe.Root>`: the recipe, servings, and display
- * system, with their setters.
+ * The state of the nearest `<Recipe.Root>`: the recipe, servings, and
+ * measurement system, with their setters.
+ *
+ * @returns The Root's `RecipeState`: `recipe`, `servings`, `scale`, `system`,
+ * `canConvert`, `ingredients` and `steps` as the Root shows them, and the
+ * `setServings` and `setSystem` that change them.
  *
  * @throws {RecipeBookError} `missing_parent` outside a Root.
+ *
+ * @example
+ * function SystemSwitch() {
+ *   const { system, setSystem, canConvert } = Recipe.useRecipe()
+ *   if (!canConvert) return null
+ *   return (
+ *     <button onClick={() => setSystem(system === 'us' ? 'metric' : 'us')}>
+ *       {system === 'us' ? 'Show metric' : 'Show US'}
+ *     </button>
+ *   )
+ * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#userecipe
  */
 declare function useRecipe(): RecipeState;
 
 /**
- * A union: a parsed `recipe`, or raw data with `parse`. To wrap `Root`,
- * intersect (`RecipeRootProps & { … }`) or destructure it, rather than
- * `Omit<RecipeRootProps, …>`, which doesn't type-check against a union.
+ * The props of `<Recipe.Root>`, a union: a parsed `recipe`, or raw data with
+ * `parse`. To wrap `Root`, intersect (`RecipeRootProps & { … }`) or
+ * destructure it, rather than `Omit<RecipeRootProps, …>`, which doesn't
+ * type-check against a union.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/root/#root
+ * @see https://recipe-book.siraj.page/reference/react/root/#wrap-root
  */
 type RecipeRootProps = RecipeBookConfig & Omit<RecipeStateOptions, 'recipe' | 'defaultSystem'> & {
     /** The parts and components that read the recipe's state. */
     children?: ReactNode;
 } & ({
     /**
-     * A parsed recipe. Call `parseRecipe` from `@recipe-book/core` on the
-     * server, in a loader, or at build time, and pass `result.data`.
+     * A parsed recipe. Call `parseRecipe` from `@recipe-book/react/core`
+     * on the server, in a loader, or at build time, and pass
+     * `result.data`.
      */
     recipe: Recipe;
+    /** Only with recipe data to parse. A parsed recipe takes no `parse`. */
     parse?: undefined;
     /** Only with `parse`. A parsed recipe always renders. */
     fallback?: undefined;
@@ -381,14 +787,19 @@ type RecipeRootProps = RecipeBookConfig & Omit<RecipeStateOptions, 'recipe' | 'd
     recipe: unknown;
     /**
      * Parses `recipe` in the browser. Pass `parseRecipe` from
-     * `@recipe-book/core`; only apps that do download the parser.
+     * `@recipe-book/react/core`; only apps that do download the parser.
      *
      * A function, so it can only be passed from a Client Component. Pass a
      * stable function such as `parseRecipe` itself: an inline arrow
      * parses again on every render.
      */
     parse: (input: unknown) => ParseResult<Recipe>;
-    /** Rendered instead of `children` when `parse` rejects `recipe`. */
+    /**
+     * Rendered instead of `children` when `parse` rejects `recipe`.
+     *
+     * @defaultValue `null`
+     * @see https://recipe-book.siraj.page/reference/react/root/#parse-in-the-browser
+     */
     fallback?: ReactNode;
 });
 /**
@@ -402,16 +813,37 @@ type RecipeRootProps = RecipeBookConfig & Omit<RecipeStateOptions, 'recipe' | 'd
  *
  * @throws {RecipeBookError} `invalid_argument` when `recipe` isn't a parsed
  *   recipe and there is no `parse`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe} defaultServings={8}>
+ *   <Recipe.Image />
+ *   <Recipe.Ingredients />
+ *   <Recipe.Steps />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/root/
  */
 declare function Root({ recipe, parse, fallback, children, ...options }: RecipeRootProps): JSX.Element;
 
-/** Attributes for the `<select>`, plus the `options` to offer. */
-type RecipeServingsSelectProps = Omit<ComponentPropsWithoutRef<'select'>, 'value' | 'defaultValue' | 'multiple' | 'children'> & {
+/**
+ * The props of `<Recipe.ServingsSelect>`: the `<select>`'s attributes, plus
+ * the `options` to offer. It sets the value and the options itself, so it
+ * doesn't take `value`, `defaultValue`, `multiple`, `children` or
+ * `dangerouslySetInnerHTML`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/servings/#servingsselect
+ */
+type RecipeServingsSelectProps = Omit<ComponentPropsWithoutRef<'select'>, 'value' | 'defaultValue' | 'multiple' | 'children' | 'dangerouslySetInnerHTML'> & {
     /**
-     * Servings to offer, shown in ascending order. Defaults to ½×, 1×, 2×, and
-     * 3× the servings the recipe scales from (its servings amount, else its
-     * yield amount, else 1), each rounded to a whole number of at least 1.
-     * Values the recipe can't be scaled to are left out.
+     * Servings to offer, shown in ascending order. A number outside the
+     * servings window is left out.
+     *
+     * @defaultValue ½×, 1×, 2×, and 3× the recipe's scaling base (its servings
+     * amount, else its yield amount, else 1), each rounded to a whole number of
+     * at least 1.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/servings/#servingsselect
+     * @see https://recipe-book.siraj.page/reference/react/root/#servings-window
      */
     options?: readonly number[] | undefined;
 };
@@ -428,18 +860,55 @@ type RecipeServingsSelectProps = Omit<ComponentPropsWithoutRef<'select'>, 'value
  * It sets `autoComplete="off"`, so when going back reloads the page, the
  * browser doesn't restore an earlier choice over the Root's servings. An
  * `autoComplete` you pass wins.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`, and
+ *   `invalid_argument` when the Root's `locale` isn't a language tag that
+ *   `Intl` accepts, such as `'en_US'`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe}>
+ *   <Recipe.ServingsSelect options={[2, 4, 6, 8]} />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/servings/#servingsselect
  */
 declare const ServingsSelect: ForwardRefExoticComponent<RecipeServingsSelectProps & RefAttributes<HTMLSelectElement>>;
-/** Attributes for the `<input type="number">`, except its value, which follows the Root's servings. */
+/**
+ * The props of `<Recipe.ServingsInput>`: the `<input type="number">`'s
+ * attributes, with `min`, `max` and `step` as numbers. It sets the type and
+ * the value, which follows the Root's servings, so it doesn't take `type`,
+ * `value` or `defaultValue`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/servings/#servingsinput
+ */
 type RecipeServingsInputProps = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'value' | 'defaultValue' | 'min' | 'max' | 'step'> & {
-    /** The fewest servings that can be entered. Defaults to 1. */
+    /**
+     * The fewest servings that can be entered, set as the `min` attribute. The
+     * `step` grid counts from it.
+     *
+     * @defaultValue `1`
+     *
+     * @see https://recipe-book.siraj.page/reference/react/servings/#servingsinput
+     */
     min?: number | undefined;
-    /** The most servings that can be entered. */
+    /**
+     * The most servings that can be entered, set as the `max` attribute.
+     * Without it, there's no `max` attribute, and the input accepts numbers up
+     * to the top of the servings window.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/servings/#servingsinput
+     * @see https://recipe-book.siraj.page/reference/react/root/#servings-window
+     */
     max?: number | undefined;
     /**
      * How far the arrows move the value, and the grid, counted from `min`, that
-     * an entered value must be on. Defaults to 1. `'any'` allows any value. A
-     * `step` that isn't a number above 0 counts as 1, as in the browser.
+     * an entered value must be on. `'any'` allows any value. A `step` that
+     * isn't a number above 0 counts as 1, as in the browser.
+     *
+     * @defaultValue `1`, the browser's step for an input without a `step`
+     * attribute
+     *
+     * @see https://recipe-book.siraj.page/reference/react/servings/#the-step-grid
      */
     step?: number | 'any' | undefined;
 };
@@ -451,12 +920,28 @@ type RecipeServingsInputProps = Omit<ComponentPropsWithoutRef<'input'>, 'type' |
  * range, so typing them logs no warning.
  *
  * Its accessible name and `autoComplete` follow the same rules as
- * `<Recipe.ServingsSelect>`.
+ * `<Recipe.ServingsSelect>`. `inputMode` defaults to `'numeric'` when `min`
+ * and the step are whole numbers, as with the defaults of 1, and to
+ * `'decimal'` otherwise, including with `step="any"`.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe}>
+ *   <Recipe.ServingsInput max={48} />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/servings/#servingsinput
  */
 declare const ServingsInput: ForwardRefExoticComponent<RecipeServingsInputProps & RefAttributes<HTMLInputElement>>;
 
-/** Attributes for the `<span>`; it renders the step's text, so no `children`. */
-type RecipeStepTextProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * Attributes for the `<span>`; it renders the step's text, so no `children` or
+ * `dangerouslySetInnerHTML`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steptext
+ */
+type RecipeStepTextProps = Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'dangerouslySetInnerHTML'>;
 /**
  * The nearest `<Recipe.Step>`'s text, with each temperature shown in Root's
  * display system: °C for metric, °F for US. A reading the author wrote in that
@@ -467,64 +952,124 @@ type RecipeStepTextProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
  * mark that follows a temperature as another way to give the same setting, as
  * in `190C/170C fan/gas 5` or `200°C (gas mark 6)`, is left out. Everything
  * else, including a gas mark on its own or before a temperature, is shown as
- * authored. Each temperature is a `<span data-recipe-temperature>`.
+ * authored. Each temperature is a `<span data-recipe-temperature>`. When
+ * `segmentStepText` pairs a conventional setting with a fan one, the
+ * conventional one shows first and the fan one after a slash, as in
+ * `200 °C / 180 °C fan`.
  *
  * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Step>`.
+ * @throws {RecipeBookError} `invalid_argument` for a step with a temperature
+ *   when Root's `locale` isn't a language tag that `Intl` accepts, such as
+ *   `'en_US'`.
  *
  * @example
  * <Recipe.Step item={step}>
  *   <Recipe.StepName /> <Recipe.StepText />
  * </Recipe.Step>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steptext
  */
 declare const StepText: ForwardRefExoticComponent<RecipeStepTextProps & RefAttributes<HTMLSpanElement>>;
 
-/** Attributes for the wrapping `<div>`, plus `headingLevel`; `children` renders each section. */
-type RecipeStepsProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
+/**
+ * Attributes for the wrapping `<div>` other than `dangerouslySetInnerHTML`,
+ * plus `headingLevel`; `children` renders each section.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steps
+ */
+type RecipeStepsProps = Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'dangerouslySetInnerHTML'> & {
     /**
      * Heading level of section titles in the default rendering. Defaults to 3,
      * for steps under an `<h2>` such as "Method".
+     *
+     * @defaultValue `3`
+     * @see https://recipe-book.siraj.page/guides/make-a-recipe-accessible/#set-heading-levels
      */
     headingLevel?: RecipeHeadingLevel | undefined;
     /**
      * Renders each section instead of the default. Each result is keyed for
      * you, so return one element or a fragment; an array's items need their own
      * keys, as anywhere in React.
+     *
+     * @defaultValue A `<section>` named by the section's heading, or a `<div>`
+     * for an untitled section, around a `<Recipe.StepList>` of its steps.
+     * @see https://recipe-book.siraj.page/reference/react/steps/#render-your-own-sections
      */
     children?: ((section: RecipeSection<StepItem>) => ReactNode) | undefined;
 };
 /**
  * The recipe's steps, one block per section. A titled section renders as a
  * `<section>` named by its heading, then a `<Recipe.StepList>`.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe}>
+ *   <h2>Method</h2>
+ *   <Recipe.Steps />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steps
  */
 declare const Steps: ForwardRefExoticComponent<RecipeStepsProps & RefAttributes<HTMLDivElement>>;
-/** Attributes for the `<ol>`, plus the `section` to list; `children` renders each step. */
-type RecipeStepListProps = Omit<ComponentPropsWithoutRef<'ol'>, 'children'> & {
+/**
+ * Attributes for the `<ol>` other than `dangerouslySetInnerHTML`, plus the
+ * `section` to list; `children` renders each step.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steplist
+ */
+type RecipeStepListProps = Omit<ComponentPropsWithoutRef<'ol'>, 'children' | 'dangerouslySetInnerHTML'> & {
     /** The section to list. Defaults to every step in the recipe. */
     section?: RecipeSection<StepItem> | undefined;
     /**
      * Renders each step instead of `<Recipe.Step>`. Each result is keyed for
      * you, so return one element or a fragment; an array's items need their own
      * keys, as anywhere in React.
+     *
+     * @defaultValue `(step) => <Recipe.Step item={step} />`
+     * @see https://recipe-book.siraj.page/reference/react/steps/#render-your-own-steps
      */
     children?: ((step: StepItem) => ReactNode) | undefined;
 };
 /**
  * An ordered list of steps. `start` defaults to the first step's number, so
  * numbering continues across sections.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @example
+ * <Recipe.StepList>
+ *   {(step) => (
+ *     <Recipe.Step item={step}>
+ *       <Recipe.StepName /> <Recipe.StepText />
+ *     </Recipe.Step>
+ *   )}
+ * </Recipe.StepList>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#steplist
  */
 declare const StepList: ForwardRefExoticComponent<RecipeStepListProps & RefAttributes<HTMLOListElement>>;
-/** Attributes for the `<li>`, plus the `item` to render and `asChild`. */
-type RecipeStepProps = ComponentPropsWithoutRef<'li'> & {
+/**
+ * Attributes for the `<li>` other than `dangerouslySetInnerHTML`, plus the
+ * `item` to render and `asChild`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#step
+ */
+type RecipeStepProps = Omit<ComponentPropsWithoutRef<'li'>, 'dangerouslySetInnerHTML'> & {
     /** The step to render, with its number. */
     item: StepItem;
     /**
      * Renders the step as its one element child, such as `<motion.li layout />`,
-     * instead of an `<li>`. A prop on the child wins, except that the step's
+     * instead of an `<li>`. Render an `<li>` or a component that renders one, so
+     * the list keeps its items. A prop on the child wins, except that the step's
      * `tabIndex` wins, `className`s join, `style` merges key by key with the
      * child winning, both event handlers run (the child's first), and both refs
      * are set. The child's own children replace the step's, so an empty child
      * gets the name and text. With anything but one element child, it renders
      * its own `<li>`, with a warning in development.
+     *
+     * @defaultValue `false`
+     * @see https://recipe-book.siraj.page/reference/react/steps/#render-your-own-element
      */
     asChild?: boolean | undefined;
 };
@@ -538,24 +1083,42 @@ type RecipeStepProps = ComponentPropsWithoutRef<'li'> & {
  * <Recipe.Step item={step}>
  *   <Recipe.StepName /> <Recipe.StepText />
  * </Recipe.Step>
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#step
  */
 declare const Step: ForwardRefExoticComponent<RecipeStepProps & RefAttributes<HTMLLIElement>>;
-/** Attributes for the `<b>`; it renders the step's name, so no `children`. */
-type RecipeStepNameProps = Omit<ComponentPropsWithoutRef<'b'>, 'children'>;
+/**
+ * Attributes for the `<b>`; it renders the step's name, so no `children` or
+ * `dangerouslySetInnerHTML`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#stepname
+ */
+type RecipeStepNameProps = Omit<ComponentPropsWithoutRef<'b'>, 'children' | 'dangerouslySetInnerHTML'>;
 /**
  * The nearest `<Recipe.Step>`'s name in a `<b data-recipe-name>`, or nothing
  * when the step has none.
  *
  * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Step>`.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/steps/#stepname
  */
 declare const StepName: ForwardRefExoticComponent<RecipeStepNameProps & RefAttributes<HTMLElement>>;
 
 /**
- * Attributes for the radio group's `<div>`, except the `role` it sets, plus
- * `asChild`.
- * The group sets `aria-disabled` itself.
+ * The props of `<Recipe.SystemToggle>`: the radio group's `<div>` attributes,
+ * plus `asChild`. It sets `role` and renders its own content, so it doesn't
+ * take `role` or `dangerouslySetInnerHTML`.
+ *
+ * The group sets `aria-disabled` and its data attributes at runtime, over any
+ * you pass, so `aria-disabled` is there only while the toggle is disabled. An
+ * `asChild` child's own `role`, `aria-disabled` and data attributes still
+ * win.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemtoggle
  */
-type RecipeSystemToggleProps = Omit<ComponentPropsWithoutRef<'div'>, 'role'> & {
+type RecipeSystemToggleProps = Omit<ComponentPropsWithoutRef<'div'>, 'role' | 'dangerouslySetInnerHTML'> & {
     /**
      * Renders the radio group as its one element child, such as
      * `<motion.div layout />`, instead of a `<div>`. A prop on the child wins,
@@ -565,43 +1128,106 @@ type RecipeSystemToggleProps = Omit<ComponentPropsWithoutRef<'div'>, 'role'> & {
      * group's, so an empty child gets the metric and US options. With anything
      * but one element child, it renders its own `<div>`, with a warning in
      * development.
+     *
+     * @defaultValue `false`
+     *
+     * @see https://recipe-book.siraj.page/reference/react/system-toggle/#render-your-own-elements
      */
     asChild?: boolean | undefined;
 };
 /**
- * Switches the display system. A radio group whose default options are
- * metric and US. Disabled when there's nothing to convert: no ingredient has a
- * unit that belongs to only one system, and no `Recipe.StepText` in the Root
- * shows a temperature. A `StepText` counts once it mounts, so for a recipe
- * whose only temperatures are in its steps, the toggle enables after
+ * Switches the Root's measurement system. A radio group whose default options
+ * are metric and US. Disabled when there's nothing to convert: no ingredient
+ * has a unit that belongs to only one system, and no `Recipe.StepText` in the
+ * Root shows a temperature. A `StepText` counts once it mounts, so for a
+ * recipe whose only temperatures are in its steps, the toggle enables after
  * hydration.
+ *
+ * Its accessible name defaults to the `system` label, unless you pass
+ * `aria-label` or `aria-labelledby`.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a `<Recipe.Root>`.
+ *
+ * @example
+ * <Recipe.Root recipe={recipe}>
+ *   <Recipe.SystemToggle className="units" />
+ * </Recipe.Root>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemtoggle
  */
 declare const SystemToggle: ForwardRefExoticComponent<RecipeSystemToggleProps & RefAttributes<HTMLDivElement>>;
 /**
- * Attributes for the radio's `<button>`, except the `role` and `tabIndex` it
- * sets, with `value` the system it selects, plus `asChild`.
- * The option sets `aria-checked` itself.
+ * The props of `<Recipe.SystemOption>`: the radio's `<button>` attributes,
+ * with `value` the system it selects, plus `asChild`. It sets `role` and
+ * `tabIndex` and renders its own content, so it doesn't take them or
+ * `dangerouslySetInnerHTML`.
+ *
+ * The option sets `aria-checked` and its data attributes at runtime, over any
+ * you pass. An `asChild` child's own `role`, `aria-checked` and data
+ * attributes still win.
+ *
+ * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemoption
  */
-type RecipeSystemOptionProps = Omit<ComponentPropsWithoutRef<'button'>, 'value' | 'role' | 'tabIndex'> & {
-    /** The system this option selects. */
+type RecipeSystemOptionProps = Omit<ComponentPropsWithoutRef<'button'>, 'value' | 'role' | 'tabIndex' | 'dangerouslySetInnerHTML'> & {
+    /**
+     * The system this option selects: `'metric'` or `'us'`.
+     *
+     * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemoption
+     */
     value: System;
+    /**
+     * The button's `autocomplete` attribute. Off by default, so when going back
+     * reloads the page, Firefox doesn't re-enable an option that the server
+     * rendered disabled and the page enabled later.
+     *
+     * @defaultValue `'off'`
+     *
+     * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemoption
+     */
+    autoComplete?: string | undefined;
     /**
      * Renders the radio as its one element child, such as
-     * `<motion.button layout />`, instead of a `<button>`. A prop on the child
-     * wins, except that the option's `tabIndex` wins, `className`s join, `style`
-     * merges key by key with the child winning, both event handlers run (the
-     * child's first), and both refs are set. The option sets `tabIndex` to keep
-     * one radio in the tab order once React hydrates the page; before that,
-     * every enabled checked option is in it. The child's own children replace
-     * the option's, so an empty child gets the system's label. With anything but
-     * one element child, it renders its own `<button>`, with a warning in
-     * development.
+     * `<motion.button layout />`, instead of a `<button>`. Render a `<button>` or
+     * a component that renders one, so Space and Enter check it, and a disabled
+     * option reads as disabled to screen readers and doesn't take focus on a
+     * click. A prop on the child wins, except that the option's `tabIndex` wins,
+     * `className`s join, `style` merges key by key with the child winning, both
+     * event handlers run (the child's first), and both refs are set. The option
+     * sets `tabIndex` to keep one radio in the tab order once React hydrates the
+     * page; before that, every enabled checked option is in it. The child's own
+     * children replace the option's, so an empty child gets the system's label.
+     * With anything but one element child, it renders its own `<button>`, with a
+     * warning in development.
+     *
+     * @defaultValue `false`
+     *
+     * @see https://recipe-book.siraj.page/reference/react/system-toggle/#render-your-own-elements
      */
     asChild?: boolean | undefined;
 };
 /**
- * One option of a `<Recipe.SystemToggle>`. Children default to the system's
- * label.
+ * One option of a `<Recipe.SystemToggle>`. Checked when its `value` is the
+ * Root's system; a click sets the Root's system to `value`. Children default
+ * to the system's label. Its `type` defaults to `'button'`, so it doesn't
+ * submit a form. It's disabled while the toggle is, even with
+ * `disabled={false}`.
+ *
+ * It sets `autoComplete="off"`, so when going back reloads the page, Firefox
+ * doesn't re-enable an option that the server rendered disabled and the page
+ * enabled later. An `autoComplete` you pass wins.
+ *
+ * @throws {RecipeBookError} `missing_parent` outside a
+ *   `<Recipe.SystemToggle>`.
+ *
+ * @example
+ * <Recipe.SystemToggle>
+ *   <Recipe.SystemOption value="us">Cups and spoons</Recipe.SystemOption>
+ *   <Recipe.SystemOption value="metric">
+ *     Grams and milliliters
+ *   </Recipe.SystemOption>
+ * </Recipe.SystemToggle>
+ *
+ * @see https://recipe-book.siraj.page/reference/react/system-toggle/#systemoption
  */
 declare const SystemOption: ForwardRefExoticComponent<RecipeSystemOptionProps & RefAttributes<HTMLButtonElement>>;
 
@@ -618,10 +1244,17 @@ type FormattedIngredientItem = FormattedIngredient & {
  * renderers without a DOM. Returns the same function until the locale or
  * `labels.optional` changes.
  *
- * Without a Root, call `formatIngredient` from `@recipe-book/core`.
+ * Without a Root, call `formatIngredient` from `@recipe-book/react/core`.
  *
  * @throws {RecipeBookError} `missing_parent` outside a Root.
  *
+ * @returns A function that formats one of the state's ingredient items into
+ *   the pieces `<Recipe.Ingredient>` renders. It throws `invalid_argument`
+ *   when Root's `locale` isn't a language tag that `Intl` accepts, such as
+ *   `'en_US'`, the item isn't `{ ingredient, quantity? }`, or it has an amount
+ *   that `formatQuantity` rejects, and `unknown_unit` when the item's unit
+ *   isn't a unit ID.
+ *
  * @example
  * function CopyIngredients() {
  *   const { ingredients } = Recipe.useRecipe()
@@ -638,6 +1271,8 @@ type FormattedIngredientItem = FormattedIngredient & {
  *     </button>
  *   )
  * }
+ *
+ * @see https://recipe-book.siraj.page/reference/react/hooks/#useformatingredient
  */
 declare function useFormatIngredient(): (item: IngredientItem) => FormattedIngredientItem;