@pipelex/mthds-form 0.27.0 → 0.28.0

package/dist/{chunk-NSHGLM6A.js → chunk-L23R3JNQ.js}

@@ -60,5 +60,5 @@ function roomForChosenFiles(held, maxItemCount) {
 }
 
 export { addChosenFiles, chosenFilesAdded, placeDroppedFiles, roomForChosenFiles, roomForDroppedFiles, sourceFileValue };
-//# sourceMappingURL=chunk-NSHGLM6A.js.map
-//# sourceMappingURL=chunk-NSHGLM6A.js.map
+//# sourceMappingURL=chunk-L23R3JNQ.js.map
+//# sourceMappingURL=chunk-L23R3JNQ.js.map

package/dist/chunk-L23R3JNQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/sources.ts"],"names":[],"mappings":"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","file":"chunk-L23R3JNQ.js","sourcesContent":["/**\n * The two optional host seams beside the upload: a **file source**, which lets\n * a file field take a file the host already stores, and an **example source**,\n * which lets a whole form take a set of values someone saved for the method.\n *\n * The kernel states the shapes and applies the answers; the host answers. It\n * knows nothing of any platform's routes, records or permissions: a host maps\n * its own list onto these shapes, and a host that gives neither seam gets the\n * form it had before. The controls that use them are `./react`'s\n * (`FilePicker`, `FillWithExample`), and docs/sources.md is the contract.\n *\n * Shapes and pure functions only, so a host's server can import the types it\n * answers with, and the rules that write an answer into a value are tested in\n * node. No React, no fetch. What a row SAYS is data here (`SourceFile`'s\n * `typeLabel` and `origin` are the host's words); how a row DRAWS is a\n * rendering, so the glyph a host draws on a file's row and the line it draws\n * under an example's name are `./react`'s (`FilePickerSource.renderGlyph`,\n * `ExamplePickerSource.renderDetail`), never a field of these shapes.\n */\n\n/** Whose files a file source lists: the person's own, or the whole team's. */\nexport type FileSourceScope = 'mine' | 'everyone';\n\n/** One page of a file source's list, as the picker asks for it. */\nexport interface FileSourceQuery {\n  /** What the person searched for, trimmed; empty when they searched for nothing. */\n  search: string;\n  /** Whose files to list. */\n  scope: FileSourceScope;\n  /**\n   * The MIME types the field accepts, after any narrowing a host applied\n   * (`narrowFileFormats`), in the field's own order. The list must hold only\n   * files of these types: the picker writes what is chosen straight into the\n   * field, and a field that refuses a dropped file of another type must not\n   * be handed one this way.\n   */\n  mediaTypes: readonly string[];\n  /** Where to continue: absent for the first page, else the previous page's `nextCursor`. */\n  cursor?: string;\n  /** Aborted when the answer is no longer wanted: a newer search, a closed picker. */\n  signal: AbortSignal;\n}\n\n/** One row of a file source's list: a file the host already stores. */\nexport interface SourceFile {\n  /** The row's identity in the host's list, which a choice is kept by. */\n  id: string;\n  /**\n   * The stored file's address, written into the field as its `url`, exactly as\n   * an upload's result is. Several rows may share one address.\n   */\n  url: string;\n  /** The file's name, shown on the row and written into the field as its `filename`. */\n  name: string;\n  /**\n   * The file's MIME type, which picks the field's format the row's file is:\n   * the row names that format's label (\"PNG\") unless `typeLabel` words the\n   * type, and draws an image's glyph or a document's from it unless the\n   * host draws its own.\n   */\n  mediaType?: string;\n  /**\n   * The file's type in the host's own words (\"Picture\", \"PDF document\"), said\n   * on the row's second line in place of the format's label, so a row reads\n   * as the host's own list of files does. An empty string counts as none.\n   */\n  typeLabel?: string;\n  /** The file's size in bytes. */\n  size?: number;\n  /** How the file came to be. A `test` file is marked \"Test file\" at the head of its row's second line. */\n  kind?: 'uploaded' | 'generated' | 'test';\n  /** When the file was stored, as an ISO 8601 timestamp; the row says it as a date. */\n  createdAt?: string;\n  /**\n   * Where the file came from, in the host's own words (\"Uploaded by Ana\",\n   * \"Made by Invoice extraction\"), shown on the row's second line as it is.\n   */\n  origin?: string;\n}\n\n/** One page of a file source's answer. */\nexport interface FileSourcePage {\n  /** The page's files, newest first. A page may be empty and still carry a cursor. */\n  files: readonly SourceFile[];\n  /** Where the next page starts, or nothing when this page is the last. */\n  nextCursor?: string | null;\n}\n\n/**\n * Where a file field can take a file the host already stores. When a form has\n * one, every file field offers \"Choose from your team's files\", and a list of\n * files offers it for several at once.\n */\nexport interface FileSource {\n  /** Lists one page of files for a query. Rejecting shows the failure with Try again. */\n  list: (query: FileSourceQuery) => Promise<FileSourcePage>;\n  /** Which of Mine and Everyone the picker opens on. */\n  initialScope: FileSourceScope;\n}\n\n/** One example of a method: a name and the inputs a run of it sends. */\nexport interface FormExample {\n  /** The example's identity in the host's list. */\n  id: string;\n  /** The example's name, shown on its row. */\n  name: string;\n  /**\n   * The inputs as a run takes them: each input `{ concept, content }`, an\n   * optional input left out, an empty plural input a bare `[]`. It is the\n   * shape `apiInputsFromRunValues` produces, so a host saves an example from\n   * `form.inputs` and hands it back as it is.\n   */\n  inputs: Readonly<Record<string, unknown>>;\n}\n\n/** One page of an example source's list. */\nexport interface ExampleSourceQuery {\n  /** Where to continue: absent for the first page, else the previous page's `nextCursor`. */\n  cursor?: string;\n  /** Aborted when the answer is no longer wanted. */\n  signal: AbortSignal;\n}\n\n/** One page of an example source's answer. */\nexport interface ExampleSourcePage {\n  /** The page's examples, in the order the list shows them. */\n  examples: readonly FormExample[];\n  /** Where the next page starts, or nothing when this page is the last. */\n  nextCursor?: string | null;\n}\n\n/**\n * Where a form can take a whole set of values. When a form has one, it offers\n * \"Fill with an example\". `open`, `rename` and `delete` are capabilities: each\n * is offered on a row's menu only when given, Open first, so a host gives each\n * only to a person it is for, and `rename` and `delete` only to a person\n * allowed to change examples. A source with any one of them has a row menu.\n *\n * The three are declared as methods, as `./react`'s `renderDetail` is,\n * because TypeScript compares a method's parameter in both directions: a\n * source whose handlers take the host's own example type, the type its `list`\n * answers with, is accepted. Declared as function-typed properties they would\n * refuse it under `strictFunctionTypes`, which is why they must stay methods.\n * The control calls each on its source, so a class's methods keep `this`.\n */\nexport interface ExampleSource {\n  /** Lists one page of the method's examples. Rejecting shows the failure with Try again. */\n  list: (query: ExampleSourceQuery) => Promise<ExampleSourcePage>;\n  /**\n   * Opens an example in the host's own surface, to show what it holds and\n   * what it produced. Choosing Open closes the list and gives focus back to\n   * \"Fill with an example\", then calls `open` once, so a surface the host\n   * opens over the form from there returns focus there as it closes.\n   *\n   * `fill` is the row's own choice of that example, made when it is called:\n   * the example's inputs read back against the form's fields as they are at\n   * that moment, \"Replace what you entered?\" asked first when the form holds\n   * the person's own values, and nothing at all while the form is held shut\n   * or once the control is gone, `hideWhenEmpty` having taken it away included.\n   * It fills through the same path a row's choice does, so a host's \"Fill the\n   * form\" calls it rather than setting the values itself. It may be called\n   * any number of times, or never.\n   */\n  open?(example: FormExample, fill: () => void): void;\n  /**\n   * Renames an example. Resolving to the example as stored replaces the row;\n   * resolving to nothing keeps the row under the new name.\n   */\n  rename?(example: FormExample, name: string): Promise<FormExample | void>;\n  /** Deletes an example. Asked for only after the person confirmed it. */\n  delete?(example: FormExample): Promise<void>;\n  /**\n   * Whether \"Fill with an example\" is left out while the method has no\n   * example. `false` by default, when the empty list says how to make one.\n   * A host sets it for a person who cannot save an example, to whom an empty\n   * list has nothing to offer; the form then asks for the first page as it\n   * mounts, to know whether to offer the control.\n   */\n  hideWhenEmpty?: boolean;\n}\n\n/** What a chosen file writes into its field: the same `{ url, filename }` an upload writes. */\nexport function sourceFileValue(file: SourceFile): { url: string; filename: string } {\n  return { url: file.url, filename: file.name };\n}\n\n/** The `url` a list item holds, when it is a file value holding one. */\nfunction heldUrl(item: unknown): string | undefined {\n  if (!item || typeof item !== 'object') return undefined;\n  const url = (item as { url?: unknown }).url;\n  return typeof url === 'string' && url !== '' ? url : undefined;\n}\n\n/** The addresses a list's items hold, each once. */\nfunction heldUrls(items: readonly unknown[]): Set<string> {\n  return new Set(items.map(heldUrl).filter((url): url is string => url !== undefined));\n}\n\n/**\n * A list of files with the chosen files written into it, in the order they\n * were chosen: first into the rows that hold no file yet (a row the person\n * added and left empty), then as new rows after the last. A file whose address\n * the list already holds is not written again, and neither is a second choice\n * of one address: two rows of a source may name the same stored file. Returns\n * a new array and leaves `held` as it was.\n */\nexport function addChosenFiles(\n  held: readonly unknown[] | undefined,\n  chosen: readonly SourceFile[],\n): unknown[] {\n  const items = [...(held ?? [])];\n  const urls = heldUrls(items);\n  let free = 0;\n  for (const file of chosen) {\n    if (urls.has(file.url)) continue;\n    urls.add(file.url);\n    while (free < items.length && heldUrl(items[free]) !== undefined) free += 1;\n    if (free < items.length) items[free] = sourceFileValue(file);\n    else items.push(sourceFileValue(file));\n    free += 1;\n  }\n  return items;\n}\n\n/** Where `placeDroppedFiles` puts a batch of files, and what it leaves out. */\nexport interface DroppedFilesPlacement {\n  /**\n   * The list once the rows the batch needs are appended: `held` as it was,\n   * then one empty row (`undefined`) per file that did not go into a free row.\n   * A new array whenever rows are appended, and a copy of `held` otherwise.\n   */\n  items: unknown[];\n  /** How many rows were appended, so a caller writes the list only when it grew. */\n  appended: number;\n  /** The row each placed file goes to, in the order the files were given. */\n  targets: number[];\n  /** How many files, from the end of the batch, found no room. */\n  leftOut: number;\n}\n\n/**\n * Where a batch of `count` files dropped on a list of files goes: first into\n * the rows that are free, in index order, then into new rows after the last,\n * as far as `maxItemCount` allows. The files keep the order they were given,\n * and those beyond the room are left out from the end of the batch.\n *\n * A row is free when it holds no file (its value carries no `url`) and\n * `isFree` says so too. The caller's predicate is where it adds what only it\n * knows of a row: that a file is still arriving there, whose write-back the row\n * must be kept for, or that the host reports a failure there, the only record\n * that one of the person's files did not arrive. Without one, every row holding\n * no file is free.\n *\n * It mirrors `addChosenFiles`, so the two ways several files enter a list fill\n * it alike, and it knows nothing of `File`: the caller judges each file and\n * hands over how many it accepted.\n */\nexport function placeDroppedFiles(\n  held: readonly unknown[] | undefined,\n  count: number,\n  maxItemCount: number | undefined,\n  isFree: (index: number) => boolean = () => true,\n): DroppedFilesPlacement {\n  const items = [...(held ?? [])];\n  const targets: number[] = [];\n  for (let index = 0; index < items.length && targets.length < count; index += 1) {\n    if (heldUrl(items[index]) === undefined && isFree(index)) targets.push(index);\n  }\n  let appended = 0;\n  while (targets.length < count && (maxItemCount === undefined || items.length < maxItemCount)) {\n    targets.push(items.length);\n    items.push(undefined);\n    appended += 1;\n  }\n  return { items, appended, targets, leftOut: count - targets.length };\n}\n\n/**\n * How many files `placeDroppedFiles` can place in `held`: its free rows, by the\n * same test, and the rows its bound still allows after the last. `undefined`\n * when the list has no bound, since appending then never runs out.\n */\nexport function roomForDroppedFiles(\n  held: readonly unknown[] | undefined,\n  maxItemCount: number | undefined,\n  isFree: (index: number) => boolean = () => true,\n): number | undefined {\n  if (maxItemCount === undefined) return undefined;\n  const items = held ?? [];\n  let free = 0;\n  for (let index = 0; index < items.length; index += 1) {\n    if (heldUrl(items[index]) === undefined && isFree(index)) free += 1;\n  }\n  return free + Math.max(0, maxItemCount - items.length);\n}\n\n/**\n * How many files `addChosenFiles` writes for `chosen` into `held`: the choices\n * whose address the list does not hold yet, each address once. This is what a\n * choice spends of `roomForChosenFiles`, so a held file chosen again, or a\n * second row naming a chosen file, takes no room.\n */\nexport function chosenFilesAdded(\n  held: readonly unknown[] | undefined,\n  chosen: readonly SourceFile[],\n): number {\n  const urls = heldUrls(held ?? []);\n  const before = urls.size;\n  for (const file of chosen) urls.add(file.url);\n  return urls.size - before;\n}\n\n/**\n * How many files a list may still take from a source: its bound less the files\n * it holds, since `addChosenFiles` writes into its empty rows before adding\n * any. `undefined` when the list has no bound.\n */\nexport function roomForChosenFiles(\n  held: readonly unknown[] | undefined,\n  maxItemCount: number | undefined,\n): number | undefined {\n  if (maxItemCount === undefined) return undefined;\n  const files = (held ?? []).filter((item) => heldUrl(item) !== undefined).length;\n  return Math.max(0, maxItemCount - files);\n}\n"]}

package/dist/core/index.js

@@ -1,6 +1,6 @@
 export { planFileSave, planStuffSave } from '../chunk-4VAO6BDE.js';
 export { closeOptionalStructures, openOptionalStructures, seedInputs, seedObjectValue } from '../chunk-VH5CDQDR.js';
-export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-NSHGLM6A.js';
+export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-L23R3JNQ.js';
 export { collectStuffFiles } from '../chunk-56WECFBD.js';
 export { describeValidationError, displayValue, valueAtProperty } from '../chunk-RPA7DNSK.js';
 export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromInputs, runValuesFromStore, sameRunValues, setValueAtPath, storeInputDataFromRunValues } from '../chunk-ZX52CQJ4.js';

package/dist/core/sources.d.ts

@@ -13,8 +13,9 @@
  * answers with, and the rules that write an answer into a value are tested in
  * node. No React, no fetch. What a row SAYS is data here (`SourceFile`'s
  * `typeLabel` and `origin` are the host's words); how a row DRAWS is a
- * rendering, so the glyph a host draws on a row is `./react`'s
- * (`FilePickerSource.renderGlyph`), never a field of these shapes.
+ * rendering, so the glyph a host draws on a file's row and the line it draws
+ * under an example's name are `./react`'s (`FilePickerSource.renderGlyph`,
+ * `ExamplePickerSource.renderDetail`), never a field of these shapes.
  */
 /** Whose files a file source lists: the person's own, or the whole team's. */
 type FileSourceScope = 'mine' | 'everyone';
@@ -121,20 +122,44 @@ interface ExampleSourcePage {
 }
 /**
  * Where a form can take a whole set of values. When a form has one, it offers
- * "Fill with an example". `rename` and `delete` are capabilities: each is
- * offered on a row's menu only when given, so a host gives them only to a
- * person allowed to change examples.
+ * "Fill with an example". `open`, `rename` and `delete` are capabilities: each
+ * is offered on a row's menu only when given, Open first, so a host gives each
+ * only to a person it is for, and `rename` and `delete` only to a person
+ * allowed to change examples. A source with any one of them has a row menu.
+ *
+ * The three are declared as methods, as `./react`'s `renderDetail` is,
+ * because TypeScript compares a method's parameter in both directions: a
+ * source whose handlers take the host's own example type, the type its `list`
+ * answers with, is accepted. Declared as function-typed properties they would
+ * refuse it under `strictFunctionTypes`, which is why they must stay methods.
+ * The control calls each on its source, so a class's methods keep `this`.
  */
 interface ExampleSource {
     /** Lists one page of the method's examples. Rejecting shows the failure with Try again. */
     list: (query: ExampleSourceQuery) => Promise<ExampleSourcePage>;
+    /**
+     * Opens an example in the host's own surface, to show what it holds and
+     * what it produced. Choosing Open closes the list and gives focus back to
+     * "Fill with an example", then calls `open` once, so a surface the host
+     * opens over the form from there returns focus there as it closes.
+     *
+     * `fill` is the row's own choice of that example, made when it is called:
+     * the example's inputs read back against the form's fields as they are at
+     * that moment, "Replace what you entered?" asked first when the form holds
+     * the person's own values, and nothing at all while the form is held shut
+     * or once the control is gone, `hideWhenEmpty` having taken it away included.
+     * It fills through the same path a row's choice does, so a host's "Fill the
+     * form" calls it rather than setting the values itself. It may be called
+     * any number of times, or never.
+     */
+    open?(example: FormExample, fill: () => void): void;
     /**
      * Renames an example. Resolving to the example as stored replaces the row;
      * resolving to nothing keeps the row under the new name.
      */
-    rename?: (example: FormExample, name: string) => Promise<FormExample | void>;
+    rename?(example: FormExample, name: string): Promise<FormExample | void>;
     /** Deletes an example. Asked for only after the person confirmed it. */
-    delete?: (example: FormExample) => Promise<void>;
+    delete?(example: FormExample): Promise<void>;
     /**
      * Whether "Fill with an example" is left out while the method has no
      * example. `false` by default, when the empty list says how to make one.

package/dist/core/sources.js

@@ -1,3 +1,3 @@
-export { addChosenFiles, chosenFilesAdded, placeDroppedFiles, roomForChosenFiles, roomForDroppedFiles, sourceFileValue } from '../chunk-NSHGLM6A.js';
+export { addChosenFiles, chosenFilesAdded, placeDroppedFiles, roomForChosenFiles, roomForDroppedFiles, sourceFileValue } from '../chunk-L23R3JNQ.js';
 //# sourceMappingURL=sources.js.map
 //# sourceMappingURL=sources.js.map

package/dist/{field-renderer-CH-biG8C.d.ts → field-renderer-Dz03dpig.d.ts}

@@ -28,8 +28,9 @@ interface FilePickerSource<F extends SourceFile = SourceFile> extends FileSource
      * (the row is at least 64px tall and grows with a larger glyph), and is
      * hidden from assistive technology, since the row's second line says the
      * type. A row it returns what React renders nothing for keeps the kernel's
-     * glyph: `null`, `undefined`, `true`, `false` or `''`, so a
-     * `cond && <Tile />` whose condition is false falls back as it reads. A
+     * glyph: `null`, `undefined`, `true`, `false` or `''`, or an array of
+     * nothing but those, an empty one included, so a `cond && <Tile />` whose
+     * condition is false, or a `.map()` over nothing, falls back as it reads. A
      * number is drawn, `0` included, because React draws it as text, so a
      * condition that is a count is the host's to turn into a boolean.
      */

package/dist/generative/index.d.ts

@@ -9,7 +9,7 @@ import { Components, Renderer } from '@json-render/react';
 import { B as BrandManifest } from '../manifest-DUeAWeqa.js';
 export { b as brandManifestSchema } from '../manifest-DUeAWeqa.js';
 import * as zod_v4_core from 'zod/v4/core';
-import { F as FieldEnv } from '../field-renderer-CH-biG8C.js';
+import { F as FieldEnv } from '../field-renderer-Dz03dpig.js';
 export { seedInputs } from '../core/seed.js';
 import '../core/contracts.js';
 import 'mthds/protocol';

package/dist/generative/index.js

@@ -1,8 +1,8 @@
 "use client";
-import { cn, checkedAccentClass, focusOutlineClass, linkTextClass, selectedBorderClass, selectedFillClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-AZIUFSIQ.js';
+import { cn, checkedAccentClass, focusOutlineClass, linkTextClass, selectedBorderClass, selectedFillClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-II5TOORN.js';
 import '../chunk-4VAO6BDE.js';
 export { seedInputs } from '../chunk-VH5CDQDR.js';
-import '../chunk-NSHGLM6A.js';
+import '../chunk-L23R3JNQ.js';
 import '../chunk-56WECFBD.js';
 import '../chunk-ZX52CQJ4.js';
 import { isNativeValueNode, readDateContent, formatDateContent, isNativeHtmlNode, isNativeDateNode, isNativeCompositeNode } from '../chunk-QQK6Y55E.js';

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FieldEnv, R as RowMove, a as FilePickerSource, U as UploadedFile } from '../field-renderer-CH-biG8C.js';
-export { D as DocumentField, b as FieldRenderer, c as FieldRendererProps, d as FilePicker, e as FilePickerEntry, f as FilePickerEntryProps, g as FilePickerProps, h as FileValue, I as ImageField } from '../field-renderer-CH-biG8C.js';
+import { F as FieldEnv, R as RowMove, a as FilePickerSource, U as UploadedFile } from '../field-renderer-Dz03dpig.js';
+export { D as DocumentField, b as FieldRenderer, c as FieldRendererProps, d as FilePicker, e as FilePickerEntry, f as FilePickerEntryProps, g as FilePickerProps, h as FileValue, I as ImageField } from '../field-renderer-Dz03dpig.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { BooleanRunField, DateRunField, EnumRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.js';
@@ -177,6 +177,67 @@ interface UnknownFieldProps {
  */
 declare function UnknownField({ field, value, onChange, id, error, disabled }: UnknownFieldProps): react.JSX.Element;
 
+/**
+ * An example source as the control set takes it: the kernel's `ExampleSource`,
+ * which lists the examples and says what may be done with them, and what a
+ * row says under the example's name, which only a renderer can draw. Every
+ * `ExampleSource` is one, so a host that describes nothing passes its source
+ * as it is.
+ */
+interface ExamplePickerSource extends ExampleSource {
+    /**
+     * Draws a line under a row's name: what the example holds, say, or that it
+     * no longer fits the form. It receives the example as `list` returned it and
+     * the fields the control reads examples back against, the form's own. What
+     * it returns is drawn inside the row's button, under the name, in the list's
+     * small muted type unless it styles itself, and is read with the name as the
+     * row's accessible name, so it is phrasing content with nothing interactive
+     * in it: text, a `<span>`, a decorative icon. It wraps within the row and
+     * never widens it; a host wanting one line truncates its own element. A row
+     * it returns what React renders nothing for stays the one line of its name:
+     * `null`, `undefined`, `true`, `false` or `''`, or an array of nothing but
+     * those, an empty one included. It is declared as a method,
+     * as `FilePickerSource.renderGlyph` is, so a source whose `renderDetail`
+     * takes the host's own example type, the type its `list` answers with, is
+     * still accepted.
+     */
+    renderDetail?(example: FormExample, fields: readonly RunField[]): ReactNode;
+}
+interface FillWithExampleProps {
+    /** The host's examples of this method, and what each row says under its name. */
+    source: ExamplePickerSource;
+    /** The form's fields, which an example's inputs are read back against. */
+    fields: RunField[];
+    /**
+     * Whether the form holds a value the person typed or attached. An untouched
+     * form fills at once; a touched one asks "Replace what you entered?" first.
+     * `useMethodForm` reports it as `touched`; a host holding its own values
+     * compares them with the ones it last set (`sameRunValues`).
+     */
+    touched: boolean;
+    /**
+     * Sets the whole form's values to the example's, read back into the
+     * controls' shape (`runValuesFromInputs`). Never a run.
+     */
+    onFill: (values: Record<string, unknown>, example: FormExample) => void;
+    /** Holds the control shut, as a host does while a run is in flight. */
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * "Fill with an example", and everything behind it.
+ *
+ * With `hideWhenEmpty`, the control reads the list as it mounts and again each
+ * time the list closes (a delete may have taken the last example), and is
+ * offered once the method is known to have an example, or when the list could
+ * not be read, so a failure is shown rather than hidden. That read follows the
+ * list past empty pages, and while it is under way the control keeps the last
+ * answer rather than blinking out. The list itself never vanishes while it is
+ * open. Without `hideWhenEmpty`, the control is always offered and an empty
+ * list says how to make one.
+ */
+declare function FillWithExample({ source, fields, touched, onFill, disabled, className, }: FillWithExampleProps): react.JSX.Element | null;
+
 /**
  * How a field's LABEL chrome, and the enum values a person reads, should read.
  * What a control stores never changes.
@@ -518,6 +579,8 @@ interface FieldStrings {
     replaceEnteredConfirm: string;
     /** The accessible name of an example row's menu, given the example's name. */
     exampleActions: (name: string) => string;
+    /** The row menu's items, in its order: Open, offered when the source opens examples, then Rename and Delete. */
+    openExample: string;
     renameExample: string;
     deleteExample: string;
     /** The rename dialog: its title, the name field's label, and its button while it works. */
@@ -636,9 +699,11 @@ interface UseMethodFormOptions {
      * Where the form can take a saved example of the method. When given,
      * `MethodForm` offers "Fill with an example" above the fields, which sets
      * every value at once (as `reset` does) and never starts a run; a touched
-     * form asks before it replaces what was entered. See docs/sources.md.
+     * form asks before it replaces what was entered. Its `open`, when given,
+     * hands a row's example to the host's own surface, and its `renderDetail`
+     * draws a line under each row's name. See docs/sources.md.
      */
-    exampleSource?: ExampleSource;
+    exampleSource?: ExamplePickerSource;
 }
 /** What the form says to its consumer: the values, the run inputs, the gate. */
 interface MethodFormState {
@@ -761,7 +826,7 @@ interface MethodFormController extends MethodFormState {
     /** The host's file source, which `MethodForm` hands its file fields. */
     fileSource: FilePickerSource | undefined;
     /** The host's example source, which `MethodForm` offers above the fields. */
-    exampleSource: ExampleSource | undefined;
+    exampleSource: ExamplePickerSource | undefined;
 }
 /**
  * The state of one method's input form. See `UseMethodFormOptions` for what it
@@ -814,41 +879,6 @@ interface MethodFormProps {
  */
 declare function MethodForm({ locale, strings, presentation, ...props }: MethodFormProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-interface FillWithExampleProps {
-    /** The host's examples of this method. */
-    source: ExampleSource;
-    /** The form's fields, which an example's inputs are read back against. */
-    fields: RunField[];
-    /**
-     * Whether the form holds a value the person typed or attached. An untouched
-     * form fills at once; a touched one asks "Replace what you entered?" first.
-     * `useMethodForm` reports it as `touched`; a host holding its own values
-     * compares them with the ones it last set (`sameRunValues`).
-     */
-    touched: boolean;
-    /**
-     * Sets the whole form's values to the example's, read back into the
-     * controls' shape (`runValuesFromInputs`). Never a run.
-     */
-    onFill: (values: Record<string, unknown>, example: FormExample) => void;
-    /** Holds the control shut, as a host does while a run is in flight. */
-    disabled?: boolean;
-    className?: string;
-}
-/**
- * "Fill with an example", and everything behind it.
- *
- * With `hideWhenEmpty`, the control reads the list as it mounts and again each
- * time the list closes (a delete may have taken the last example), and is
- * offered once the method is known to have an example, or when the list could
- * not be read, so a failure is shown rather than hidden. That read follows the
- * list past empty pages, and while it is under way the control keeps the last
- * answer rather than blinking out. The list itself never vanishes while it is
- * open. Without `hideWhenEmpty`, the control is always offered and an empty
- * list says how to make one.
- */
-declare function FillWithExample({ source, fields, touched, onFill, disabled, className, }: FillWithExampleProps): react.JSX.Element | null;
-
 interface ResultFieldProps {
     field: RunField;
     value: unknown;
@@ -1741,4 +1771,4 @@ declare function FieldDomIdProvider({ prefix, children, }: {
  */
 declare function useFieldDomId(path: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, type MarkdownProps, type MarkupResolvers, MethodForm, type MethodFormController, type MethodFormProps, type MethodFormState, type MethodFormUploadContext, type MethodFormValues, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, type PdfDownloadButtonProps, type PdfPage, ProseField, type ProseImages, type RenderPdf, type RenditionRequest, type ResolveRendition, type ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, RowMove, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, type TableLayout, TextField, UnknownField, UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, type ExamplePickerSource, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, type MarkdownProps, type MarkupResolvers, MethodForm, type MethodFormController, type MethodFormProps, type MethodFormState, type MethodFormUploadContext, type MethodFormValues, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, type PdfDownloadButtonProps, type PdfPage, ProseField, type ProseImages, type RenderPdf, type RenditionRequest, type ResolveRendition, type ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, RowMove, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, type TableLayout, TextField, UnknownField, UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };

package/dist/react/index.js

@@ -1,8 +1,8 @@
 "use client";
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, FilePicker, FilePickerEntry, FillWithExample, HtmlPreview, ImageField, JsonView, ListField, Markdown, MethodForm, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, ProseField, ResultEnvProvider, ResultField, SUPPORTED_LOCALES, StuffViewer, TextField, UnknownField, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-AZIUFSIQ.js';
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, FilePicker, FilePickerEntry, FillWithExample, HtmlPreview, ImageField, JsonView, ListField, Markdown, MethodForm, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, ProseField, ResultEnvProvider, ResultField, SUPPORTED_LOCALES, StuffViewer, TextField, UnknownField, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-II5TOORN.js';
 import '../chunk-4VAO6BDE.js';
 import '../chunk-VH5CDQDR.js';
-import '../chunk-NSHGLM6A.js';
+import '../chunk-L23R3JNQ.js';
 import '../chunk-56WECFBD.js';
 import '../chunk-ZX52CQJ4.js';
 import '../chunk-QQK6Y55E.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/mthds-form",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Headless form kernel and control set for MTHDS method inputs",
   "license": "MIT",
   "repository": {