@pipelex/mthds-form 0.23.1 → 0.24.0

package/dist/core/index.js

@@ -1,6 +1,6 @@
 export { planFileSave, planStuffSave } from '../chunk-ICUEHNEH.js';
 export { closeOptionalStructures, openOptionalStructures, seedInputs, seedObjectValue } from '../chunk-VH5CDQDR.js';
-export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-EQJBM3NS.js';
+export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-NSHGLM6A.js';
 export { collectStuffFiles } from '../chunk-RRTI7AIR.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

@@ -11,7 +11,10 @@
  *
  * Shapes and pure functions only, so a host's server can import the types it
  * answers with, and the rules that write an answer into a value are tested in
- * node. No React, no fetch.
+ * 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.
  */
 /** Whose files a file source lists: the person's own, or the whole team's. */
 type FileSourceScope = 'mine' | 'everyone';
@@ -45,8 +48,19 @@ interface SourceFile {
     url: string;
     /** The file's name, shown on the row and written into the field as its `filename`. */
     name: string;
-    /** The file's MIME type, which names its format on the row. */
+    /**
+     * The file's MIME type, which picks the field's format the row's file is:
+     * the row names that format's label ("PNG") unless `typeLabel` words the
+     * type, and draws an image's glyph or a document's from it unless the
+     * host draws its own.
+     */
     mediaType?: string;
+    /**
+     * The file's type in the host's own words ("Picture", "PDF document"), said
+     * on the row's second line in place of the format's label, so a row reads
+     * as the host's own list of files does. An empty string counts as none.
+     */
+    typeLabel?: string;
     /** The file's size in bytes. */
     size?: number;
     /** How the file came to be. A `test` file is marked "Test file" at the head of its row's second line. */
@@ -144,11 +158,45 @@ declare function sourceFileValue(file: SourceFile): {
  * a new array and leaves `held` as it was.
  */
 declare function addChosenFiles(held: readonly unknown[] | undefined, chosen: readonly SourceFile[]): unknown[];
+/** Where `placeDroppedFiles` puts a batch of files, and what it leaves out. */
+interface DroppedFilesPlacement {
+    /**
+     * The list once the rows the batch needs are appended: `held` as it was,
+     * then one empty row (`undefined`) per file that did not go into a free row.
+     * A new array whenever rows are appended, and a copy of `held` otherwise.
+     */
+    items: unknown[];
+    /** How many rows were appended, so a caller writes the list only when it grew. */
+    appended: number;
+    /** The row each placed file goes to, in the order the files were given. */
+    targets: number[];
+    /** How many files, from the end of the batch, found no room. */
+    leftOut: number;
+}
 /**
- * How many files a list may still take from a source: its bound less the files
- * it holds, since `addChosenFiles` writes into its empty rows before adding
- * any. `undefined` when the list has no bound.
+ * Where a batch of `count` files dropped on a list of files goes: first into
+ * the rows that are free, in index order, then into new rows after the last,
+ * as far as `maxItemCount` allows. The files keep the order they were given,
+ * and those beyond the room are left out from the end of the batch.
+ *
+ * A row is free when it holds no file (its value carries no `url`) and
+ * `isFree` says so too. The caller's predicate is where it adds what only it
+ * knows of a row: that a file is still arriving there, whose write-back the row
+ * must be kept for, or that the host reports a failure there, the only record
+ * that one of the person's files did not arrive. Without one, every row holding
+ * no file is free.
+ *
+ * It mirrors `addChosenFiles`, so the two ways several files enter a list fill
+ * it alike, and it knows nothing of `File`: the caller judges each file and
+ * hands over how many it accepted.
  */
+declare function placeDroppedFiles(held: readonly unknown[] | undefined, count: number, maxItemCount: number | undefined, isFree?: (index: number) => boolean): DroppedFilesPlacement;
+/**
+ * How many files `placeDroppedFiles` can place in `held`: its free rows, by the
+ * same test, and the rows its bound still allows after the last. `undefined`
+ * when the list has no bound, since appending then never runs out.
+ */
+declare function roomForDroppedFiles(held: readonly unknown[] | undefined, maxItemCount: number | undefined, isFree?: (index: number) => boolean): number | undefined;
 /**
  * How many files `addChosenFiles` writes for `chosen` into `held`: the choices
  * whose address the list does not hold yet, each address once. This is what a
@@ -156,6 +204,11 @@ declare function addChosenFiles(held: readonly unknown[] | undefined, chosen: re
  * second row naming a chosen file, takes no room.
  */
 declare function chosenFilesAdded(held: readonly unknown[] | undefined, chosen: readonly SourceFile[]): number;
+/**
+ * How many files a list may still take from a source: its bound less the files
+ * it holds, since `addChosenFiles` writes into its empty rows before adding
+ * any. `undefined` when the list has no bound.
+ */
 declare function roomForChosenFiles(held: readonly unknown[] | undefined, maxItemCount: number | undefined): number | undefined;
 
-export { type ExampleSource, type ExampleSourcePage, type ExampleSourceQuery, type FileSource, type FileSourcePage, type FileSourceQuery, type FileSourceScope, type FormExample, type SourceFile, addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue };
+export { type DroppedFilesPlacement, type ExampleSource, type ExampleSourcePage, type ExampleSourceQuery, type FileSource, type FileSourcePage, type FileSourceQuery, type FileSourceScope, type FormExample, type SourceFile, addChosenFiles, chosenFilesAdded, placeDroppedFiles, roomForChosenFiles, roomForDroppedFiles, sourceFileValue };

package/dist/core/sources.js

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

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

@@ -1,6 +1,111 @@
 import * as react from 'react';
+import { ReactNode, RefObject, Ref } from 'react';
 import { FileRunField, RunField } from './core/descriptor.js';
-import { FileSource } from './core/sources.js';
+import { FileFormat } from './core/file-formats.js';
+import { SourceFile, FileSource, FileSourceQuery, FileSourcePage } from './core/sources.js';
+
+/**
+ * A file source as the control set takes it: the kernel's `FileSource`, which
+ * lists the files, and how a row draws, which only a renderer can say. Every
+ * `FileSource` is one, so a host that draws nothing passes its source as it is.
+ *
+ * `F` is the host's own row: a host may carry its own fields on the rows its
+ * `list` answers with (the format key its glyphs are chosen by, for instance)
+ * and read them back in `renderGlyph`, which receives each row exactly as
+ * `list` returned it. A source typed over its own row is accepted wherever a
+ * `FilePickerSource` is, because `renderGlyph` is declared as a method, whose
+ * parameter TypeScript compares both ways. Declared as a function-typed
+ * property it would be compared strictly, and a host's typed source would
+ * stop being accepted by `useMethodForm`, `FieldEnv` and `FilePicker`.
+ */
+interface FilePickerSource<F extends SourceFile = SourceFile> extends FileSource {
+    list: (query: FileSourceQuery) => Promise<FileSourcePage & {
+        files: readonly F[];
+    }>;
+    /**
+     * Draws a row's glyph in place of the kernel's own, a 24px document or
+     * picture outline. What it returns sits at the row's start at its own size
+     * (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
+     * 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.
+     */
+    renderGlyph?(file: F): ReactNode;
+}
+interface FilePickerEntryProps {
+    /** Opens the sheet. */
+    onOpen: () => void;
+    /** The field's label as the form shows it, which names the row for assistive technology. */
+    label: string;
+    disabled?: boolean;
+    /** The row's button, which the sheet hands focus back to (`FilePicker`'s `returnFocusTo`). */
+    ref?: Ref<HTMLButtonElement>;
+    /** The button's id, for a field whose label names this row, when it is the field's only way in. */
+    id?: string;
+}
+/**
+ * "Choose from your team's files": a full-width row with a folder icon, under
+ * the field's own controls.
+ */
+declare function FilePickerEntry({ onOpen, label, disabled, ref, id }: FilePickerEntryProps): react.JSX.Element;
+interface FilePickerProps {
+    /** The host's list, and how its rows draw. */
+    source: FilePickerSource;
+    /** What the field accepts: the list is narrowed to these types, and the sheet names them. */
+    formats: readonly FileFormat[];
+    /** A list field's picker: several rows may be chosen. One otherwise. */
+    multiple?: boolean;
+    /**
+     * The most files a choice may add, a list's remaining room; unbounded when
+     * absent. Counted as `chosenFilesAdded` counts them, against `held`.
+     */
+    maxChoices?: number;
+    /**
+     * The list's items. A chosen file whose address they hold adds nothing to
+     * the list, nor does a second row naming a chosen file, so neither takes
+     * any of `maxChoices`.
+     */
+    held?: readonly unknown[];
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** What was chosen, in the order it was chosen. The sheet closes after. */
+    onUse: (files: SourceFile[]) => void;
+    /**
+     * Offered as "Upload a file" when the person holds no file of the field's
+     * formats: the sheet closes, and this starts the field's own upload.
+     */
+    onUpload?: () => void;
+    /**
+     * What focus goes back to when the sheet closes: the row that opened it, as
+     * a rule. Without it, focus goes back to whatever held it as the sheet
+     * opened, which a browser that does not focus a clicked button leaves unset.
+     */
+    returnFocusTo?: RefObject<HTMLElement | null>;
+    /**
+     * Runs as the sheet closes, before focus goes back: `preventDefault()` on the
+     * event and focus something else, as a field does with the file it now holds.
+     */
+    onCloseAutoFocus?: (event: Event) => void;
+    /**
+     * Holds the sheet shut, as the field is while it is disabled or a file is
+     * arriving: an open sheet closes, writing nothing, and `onOpenChange` is
+     * told so.
+     */
+    disabled?: boolean;
+}
+/**
+ * "Your team's files": a bottom sheet below 1280px and a dialog from 1280px,
+ * with the field's formats named under its title, the search, the Mine and
+ * Everyone switch, the rows newest first, and one primary button at the foot.
+ *
+ * Closing it, by its close button, Escape, the backdrop or a swipe down, leaves
+ * the field as it was: only Use writes. The sheet's state lives in its body,
+ * which mounts when it opens, so it always opens on a fresh choice.
+ */
+declare function FilePicker({ open, onOpenChange, returnFocusTo, onCloseAutoFocus, disabled, ...props }: FilePickerProps): react.JSX.Element;
 
 /** The serializable value of a file field. URL is what the runner sends. */
 interface FileValue {
@@ -56,7 +161,7 @@ interface FileFieldProps {
      * and the chosen file is written through `onChange` as `{ url, filename }`,
      * the value an upload writes. See docs/sources.md.
      */
-    fileSource?: FileSource;
+    fileSource?: FilePickerSource;
     error?: string;
     disabled?: boolean;
 }
@@ -192,9 +297,10 @@ interface FieldEnv {
      * is the capability, as `onDropFile`'s is: every empty file field then
      * offers "Choose from your team's files", and a list of files offers it for
      * several at once. The choice is written as `{ url, filename }`, exactly as
-     * an upload's result is. See docs/sources.md.
+     * an upload's result is. Its `renderGlyph`, when given, draws each row's
+     * glyph in the sheet. See docs/sources.md.
      */
-    fileSource?: FileSource;
+    fileSource?: FilePickerSource;
 }
 interface FieldRendererProps {
     field: RunField;
@@ -212,4 +318,4 @@ interface FieldRendererProps {
  */
 declare function FieldRenderer({ field, value, onChange, id, error, env }: FieldRendererProps): react.JSX.Element;
 
-export { DocumentField as D, type FieldEnv as F, ImageField as I, type RowMove as R, type UploadedFile as U, FieldRenderer as a, type FieldRendererProps as b, type FileValue as c };
+export { DocumentField as D, type FieldEnv as F, ImageField as I, type RowMove as R, type UploadedFile as U, type FilePickerSource as a, FieldRenderer as b, type FieldRendererProps as c, FilePicker as d, FilePickerEntry as e, type FilePickerEntryProps as f, type FilePickerProps as g, type FileValue as h };

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-lNhtw-Cz.js';
+import { F as FieldEnv } from '../field-renderer-CH-biG8C.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-NOSHTDID.js';
+import { cn, checkedAccentClass, focusOutlineClass, linkTextClass, selectedBorderClass, selectedFillClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-UGKFWX7L.js';
 import '../chunk-ICUEHNEH.js';
 export { seedInputs } from '../chunk-VH5CDQDR.js';
-import '../chunk-EQJBM3NS.js';
+import '../chunk-NSHGLM6A.js';
 import '../chunk-RRTI7AIR.js';
 import '../chunk-ZX52CQJ4.js';
 import { isNativeValueNode, readDateContent, formatDateContent, isNativeHtmlNode, isNativeDateNode, isNativeCompositeNode } from '../chunk-CM4KVG53.js';

package/dist/react/index.d.ts

@@ -1,16 +1,16 @@
-import { F as FieldEnv, R as RowMove, U as UploadedFile } from '../field-renderer-lNhtw-Cz.js';
-export { D as DocumentField, a as FieldRenderer, b as FieldRendererProps, c as FileValue, I as ImageField } from '../field-renderer-lNhtw-Cz.js';
+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 * as react from 'react';
-import { ReactNode, RefObject, Ref } from 'react';
+import { ReactNode } from 'react';
 import { BooleanRunField, DateRunField, EnumRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.js';
 import { PipeInputFormDescriptor, PipeIOContract } from 'mthds/protocol';
 import { Readiness } from '../core/readiness.js';
-import { FileSource, ExampleSource, SourceFile, FormExample } from '../core/sources.js';
-export { ExampleSourcePage, ExampleSourceQuery, FileSourcePage, FileSourceQuery, FileSourceScope } from '../core/sources.js';
-import { FileFormat } from '../core/file-formats.js';
+import { ExampleSource, FormExample } from '../core/sources.js';
+export { ExampleSourcePage, ExampleSourceQuery, FileSource, FileSourcePage, FileSourceQuery, FileSourceScope, SourceFile } from '../core/sources.js';
 import { SaveFiles, SaveFile, SaveResult } from '../core/save-plan.js';
 import { StuffFileKind } from '../core/stuff-files.js';
 import { HtmlContentView } from '../core/native-content.js';
+import '../core/file-formats.js';
 import '../core/contracts.js';
 
 interface BooleanFieldProps {
@@ -84,8 +84,9 @@ interface ListFieldProps {
  * instead of renumbering them into each other - which is what used to drop a
  * half-typed value or a pending preview onto the neighbouring row. The row's
  * field ID stays POSITIONAL (`cvs.1`), because that ID is a PATH: a host writes
- * an upload back with `setValueAtPath(values, id.split('.'), value)`, and
- * `setValueAtPath` is a pure function of the value tree. Handing out an opaque
+ * an upload back with `setValueAtPath(current, id.split('.'), value)`, over its
+ * values as they are when the upload lands, and `setValueAtPath` is a pure
+ * function of the value tree. Handing out an opaque
  * token instead would mean the kernel keeping a live token-to-index registry for
  * that function to consult, which is exactly the kind of hidden state the
  * headless core does not have.
@@ -361,6 +362,32 @@ interface FieldStrings {
      * accepted" on its own leaves the user guessing at the list they just failed.
      */
     unsupportedFileType: (formats: string) => string;
+    /** What a list of files' drop area says, under its rows. */
+    dropFilesOrBrowse: string;
+    /** What it says while files are dragged over it. */
+    dropFilesToAdd: string;
+    /**
+     * The accessible name of the file input inside that area, given the list's
+     * label as the form shows it, so it says which list the files go to.
+     */
+    addFilesAria: (label: string) => string;
+    /** Announced, visually hidden, once a batch is placed: how many files went in. */
+    filesAdded: (count: number) => string;
+    /**
+     * The files of a batch the list did not take because the slot does not accept
+     * their type: the first few names, how many more there were, and the slot's
+     * formats as the hint names them (`PDF, JPG, PNG`).
+     */
+    filesRefused: (names: readonly string[], more: number, formats: string) => string;
+    /**
+     * The files of a batch a bounded list had no room for: the first few names,
+     * how many more there were, and how many of the batch did fit.
+     */
+    filesLeftOut: (names: readonly string[], more: number, fitted: number) => string;
+    /** What a single file field says when several files are dropped on it at once. */
+    oneFileOnly: string;
+    /** The same, on a row of a list that has a drop area for several files. */
+    oneFileOnlyInList: string;
     /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
     hideOptionalFields: string;
     hideOptionalInputs: string;
@@ -556,9 +583,10 @@ interface UseMethodFormOptions {
      * is the capability, as `uploadFile`'s is: every empty file field then offers
      * "Choose from your team's files", and a list of files offers it for several
      * at once. The choice is written as `{ url, filename }`, as an upload's
-     * result is. See docs/sources.md.
+     * result is. Its `renderGlyph`, when given, draws each row's glyph in the
+     * sheet. See docs/sources.md.
      */
-    fileSource?: FileSource;
+    fileSource?: FilePickerSource;
     /**
      * Where the form can take a saved example of the method. When given,
      * `MethodForm` offers "Fill with an example" above the fields, which sets
@@ -686,7 +714,7 @@ interface MethodFormController extends MethodFormState {
         filename: string;
     }>) | undefined;
     /** The host's file source, which `MethodForm` hands its file fields. */
-    fileSource: FileSource | undefined;
+    fileSource: FilePickerSource | undefined;
     /** The host's example source, which `MethodForm` offers above the fields. */
     exampleSource: ExampleSource | undefined;
 }
@@ -741,78 +769,6 @@ interface MethodFormProps {
  */
 declare function MethodForm({ locale, strings, presentation, ...props }: MethodFormProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-interface FilePickerEntryProps {
-    /** Opens the sheet. */
-    onOpen: () => void;
-    /** The field's label as the form shows it, which names the row for assistive technology. */
-    label: string;
-    disabled?: boolean;
-    /** The row's button, which the sheet hands focus back to (`FilePicker`'s `returnFocusTo`). */
-    ref?: Ref<HTMLButtonElement>;
-    /** The button's id, for a field whose label names this row, when it is the field's only way in. */
-    id?: string;
-}
-/**
- * "Choose from your team's files": a full-width row with a folder icon, under
- * the field's own controls.
- */
-declare function FilePickerEntry({ onOpen, label, disabled, ref, id }: FilePickerEntryProps): react.JSX.Element;
-interface FilePickerProps {
-    /** The host's list. */
-    source: FileSource;
-    /** What the field accepts: the list is narrowed to these types, and the sheet names them. */
-    formats: readonly FileFormat[];
-    /** A list field's picker: several rows may be chosen. One otherwise. */
-    multiple?: boolean;
-    /**
-     * The most files a choice may add, a list's remaining room; unbounded when
-     * absent. Counted as `chosenFilesAdded` counts them, against `held`.
-     */
-    maxChoices?: number;
-    /**
-     * The list's items. A chosen file whose address they hold adds nothing to
-     * the list, nor does a second row naming a chosen file, so neither takes
-     * any of `maxChoices`.
-     */
-    held?: readonly unknown[];
-    open: boolean;
-    onOpenChange: (open: boolean) => void;
-    /** What was chosen, in the order it was chosen. The sheet closes after. */
-    onUse: (files: SourceFile[]) => void;
-    /**
-     * Offered as "Upload a file" when the person holds no file of the field's
-     * formats: the sheet closes, and this starts the field's own upload.
-     */
-    onUpload?: () => void;
-    /**
-     * What focus goes back to when the sheet closes: the row that opened it, as
-     * a rule. Without it, focus goes back to whatever held it as the sheet
-     * opened, which a browser that does not focus a clicked button leaves unset.
-     */
-    returnFocusTo?: RefObject<HTMLElement | null>;
-    /**
-     * Runs as the sheet closes, before focus goes back: `preventDefault()` on the
-     * event and focus something else, as a field does with the file it now holds.
-     */
-    onCloseAutoFocus?: (event: Event) => void;
-    /**
-     * Holds the sheet shut, as the field is while it is disabled or a file is
-     * arriving: an open sheet closes, writing nothing, and `onOpenChange` is
-     * told so.
-     */
-    disabled?: boolean;
-}
-/**
- * "Your team's files": a bottom sheet below 1280px and a dialog from 1280px,
- * with the field's formats named under its title, the search, the Mine and
- * Everyone switch, the rows newest first, and one primary button at the foot.
- *
- * Closing it, by its close button, Escape, the backdrop or a swipe down, leaves
- * the field as it was: only Use writes. The sheet's state lives in its body,
- * which mounts when it opens, so it always opens on a fresh choice.
- */
-declare function FilePicker({ open, onOpenChange, returnFocusTo, onCloseAutoFocus, disabled, ...props }: FilePickerProps): react.JSX.Element;
-
 interface FillWithExampleProps {
     /** The host's examples of this method. */
     source: ExampleSource;
@@ -1648,4 +1604,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, FilePicker, FilePickerEntry, type FilePickerEntryProps, type FilePickerProps, FileSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, 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 ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, RowMove, SUPPORTED_LOCALES, SourceFile, StuffViewer, type StuffViewerProps, type StuffViewerView, type TableLayout, TextField, UnknownField, UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+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 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 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, 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, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-NOSHTDID.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, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-UGKFWX7L.js';
 import '../chunk-ICUEHNEH.js';
 import '../chunk-VH5CDQDR.js';
-import '../chunk-EQJBM3NS.js';
+import '../chunk-NSHGLM6A.js';
 import '../chunk-RRTI7AIR.js';
 import '../chunk-ZX52CQJ4.js';
 import '../chunk-CM4KVG53.js';

package/package.json

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

package/dist/chunk-EQJBM3NS.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/sources.ts"],"names":[],"mappings":";AA+IO,SAAS,gBAAgB,IAAA,EAAqD;AACnF,EAAA,OAAO,EAAE,GAAA,EAAK,IAAA,CAAK,GAAA,EAAK,QAAA,EAAU,KAAK,IAAA,EAAK;AAC9C;AAGA,SAAS,QAAQ,IAAA,EAAmC;AAClD,EAAA,IAAI,CAAC,IAAA,IAAQ,OAAO,IAAA,KAAS,UAAU,OAAO,MAAA;AAC9C,EAAA,MAAM,MAAO,IAAA,CAA2B,GAAA;AACxC,EAAA,OAAO,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,KAAQ,KAAK,GAAA,GAAM,MAAA;AACvD;AAGA,SAAS,SAAS,KAAA,EAAwC;AACxD,EAAA,OAAO,IAAI,GAAA,CAAI,KAAA,CAAM,GAAA,CAAI,OAAO,CAAA,CAAE,MAAA,CAAO,CAAC,GAAA,KAAuB,GAAA,KAAQ,MAAS,CAAC,CAAA;AACrF;AAUO,SAAS,cAAA,CACd,MACA,MAAA,EACW;AACX,EAAA,MAAM,KAAA,GAAQ,CAAC,GAAI,IAAA,IAAQ,EAAG,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,SAAS,KAAK,CAAA;AAC3B,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,KAAA,MAAW,QAAQ,MAAA,EAAQ;AACzB,IAAA,IAAI,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,GAAG,CAAA,EAAG;AACxB,IAAA,IAAA,CAAK,GAAA,CAAI,KAAK,GAAG,CAAA;AACjB,IAAA,OAAO,IAAA,GAAO,MAAM,MAAA,IAAU,OAAA,CAAQ,MAAM,IAAI,CAAC,CAAA,KAAM,MAAA,EAAW,IAAA,IAAQ,CAAA;AAC1E,IAAA,IAAI,OAAO,KAAA,CAAM,MAAA,QAAc,IAAI,CAAA,GAAI,gBAAgB,IAAI,CAAA;AAAA,SACtD,KAAA,CAAM,IAAA,CAAK,eAAA,CAAgB,IAAI,CAAC,CAAA;AACrC,IAAA,IAAA,IAAQ,CAAA;AAAA,EACV;AACA,EAAA,OAAO,KAAA;AACT;AAaO,SAAS,gBAAA,CACd,MACA,MAAA,EACQ;AACR,EAAA,MAAM,IAAA,GAAO,QAAA,CAAS,IAAA,IAAQ,EAAE,CAAA;AAChC,EAAA,MAAM,SAAS,IAAA,CAAK,IAAA;AACpB,EAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,KAAK,GAAG,CAAA;AAC5C,EAAA,OAAO,KAAK,IAAA,GAAO,MAAA;AACrB;AAEO,SAAS,kBAAA,CACd,MACA,YAAA,EACoB;AACpB,EAAA,IAAI,YAAA,KAAiB,QAAW,OAAO,MAAA;AACvC,EAAA,MAAM,KAAA,GAAA,CAAS,IAAA,IAAQ,EAAC,EAAG,MAAA,CAAO,CAAC,IAAA,KAAS,OAAA,CAAQ,IAAI,CAAA,KAAM,MAAS,CAAA,CAAE,MAAA;AACzE,EAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,YAAA,GAAe,KAAK,CAAA;AACzC","file":"chunk-EQJBM3NS.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.\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  /** The file's MIME type, which names its format on the row. */\n  mediaType?: 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\". `rename` and `delete` are capabilities: each is\n * offered on a row's menu only when given, so a host gives them only to a\n * person allowed to change examples.\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   * 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/**\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 */\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\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"]}