@pipelex/mthds-form 0.23.2 → 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-O2VIVDHO.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

@@ -158,6 +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;
+}
+/**
+ * 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
@@ -172,4 +211,4 @@ declare function chosenFilesAdded(held: readonly unknown[] | undefined, chosen:
  */
 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-O2VIVDHO.js';
+export { addChosenFiles, chosenFilesAdded, placeDroppedFiles, roomForChosenFiles, roomForDroppedFiles, sourceFileValue } from '../chunk-NSHGLM6A.js';
 //# sourceMappingURL=sources.js.map
 //# sourceMappingURL=sources.js.map

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-W5MYXDLO.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-O2VIVDHO.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

@@ -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;

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-W5MYXDLO.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-O2VIVDHO.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.2",
+  "version": "0.24.0",
   "description": "Headless form kernel and control set for MTHDS method inputs",
   "license": "MIT",
   "repository": {

package/dist/chunk-O2VIVDHO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/sources.ts"],"names":[],"mappings":";AA6JO,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;AAQO,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;AAOO,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-O2VIVDHO.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 row is `./react`'s\n * (`FilePickerSource.renderGlyph`), 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\". `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 `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"]}