@pipelex/mthds-form 0.11.0 → 0.12.0

package/dist/react/index.d.ts

@@ -3,6 +3,8 @@ export { a as FieldRenderer, b as FieldRendererProps } from '../field-renderer-C
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.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/contracts.js';
 import 'mthds/protocol';
@@ -217,115 +219,14 @@ interface ResultFieldProps {
      */
     hideLabel?: boolean;
 }
-/** The single dispatch point, mirroring `FieldRenderer` on the input side. */
-declare function ResultField({ field, value, depth, hideLabel }: ResultFieldProps): react.JSX.Element | null;
-
-/**
- * A pipe's result, with the two views a result actually needs.
- *
- * ## Two, and why not three
- *
- * **Rendered** is the answer for a person: the descriptor-driven view, which
- * knows a field is an enum, that a date arrived in the serializer's typed
- * envelope, that fifteen records are a table. **JSON** is the answer for whoever
- * is debugging the pipe: what exactly came back, verbatim, copyable. Those are
- * different jobs and neither substitutes for the other.
- *
- * They are deliberately NOT peers, and the toggle should not read as a menu of
- * equal options. One is the result; the other is the receipt. Rendered opens
- * first, always.
- *
- * A third view is the one to resist. An engine-rendered HTML or plain-text
- * presentation — the shape the runtime's own viewer offers — is a second human
- * rendering of the same payload, produced by another codebase, carrying no
- * descriptor (so it cannot know a kind, a plurality or a nesting) and unable to
- * match a host's design system. It is a renderer that cannot be improved without
- * shipping the engine. If a plain-text form is wanted, it is a COPY FORMAT and
- * belongs behind a copy control, not beside the view that reads the standard.
- */
-type StuffViewerView = 'rendered' | 'json';
-interface StuffViewerProps {
-    field: RunField;
-    value: unknown;
-    /**
-     * The STUFF's name, for the header — `report_pages`, not `output`.
-     *
-     * A result descriptor's root node is named by the engine that built it, and
-     * `build_output_form` calls it `output` for every pipe there has ever been.
-     * That is correct in the artifact: the descriptor describes a pipe's output
-     * slot, which has no name of its own. It is wrong on screen, where the reader
-     * is looking at ONE data item and every other surface — the graph node they
-     * clicked, the input panel beside it, the method's own code — calls that item
-     * by the name the author gave it.
-     *
-     * So the name comes from the caller, because only the caller knows it: the
-     * graph knows which node was opened, a run page knows which variable it is
-     * showing. Absent, the descriptor's own name stands, which keeps a host that
-     * has nothing better to say honest rather than blank.
-     *
-     * It also supplies `downloadBaseName`'s default, so the file a reader saves
-     * is named after the thing they were reading rather than `output.json`.
-     */
-    name?: string;
-    /** Which view opens first. Rendered, unless a host has a reason. */
-    defaultView?: StuffViewerView;
-    /**
-     * Names the saved files: `<baseName>.json`, and any file inside the stuff
-     * that carries no name of its own. Defaults to the field's name, which is
-     * what the header shows.
-     */
-    downloadBaseName?: string;
-    /**
-     * Hide the download control. For a host that saves results its own way, or a
-     * surface where saving makes no sense — a preview inside an editor, say.
-     */
-    hideDownload?: boolean;
-    className?: string;
-}
 /**
- * The payload as JSON — the receipt, with the whole of it one click from the
- * clipboard.
+ * The single dispatch point, mirroring `FieldRenderer` on the input side.
  *
- * Exported because it is also the honest FLOOR: a host that holds a value but
- * not the artifacts describing it (an older engine, a spec restored without its
- * validate report) should show the value and say why it is not laid out, rather
- * than show nothing. That is a different thing from what `StuffViewer`'s JSON
- * tab was — one labelled fallback, not one of three guesses offered as a
- * choice.
+ * The outermost one also marks the root of the result, when no panel above it
+ * has: a file's own download button names the file by its place in the result,
+ * and the place starts here. Every nested one finds the root already there.
  */
-declare function JsonView({ value }: {
-    value: unknown;
-}): react.JSX.Element;
-declare function StuffViewer({ field, value, name, defaultView, downloadBaseName, hideDownload, className, }: StuffViewerProps): react.JSX.Element;
-
-/** How a host turns a stored reference into something fetchable. */
-type ResolveForDownload = (url: string) => string | undefined;
-/**
- * Everything a stuff contains, saved.
- *
- * The rule the caller asked for, and the one that matches what a result IS: the
- * data goes down as JSON, and any image or document inside it goes down as
- * ITSELF. A JSON file holding a URL to a picture is not the picture, and a
- * reader who clicks download on a report with three attachments wants the three
- * attachments — the reference is what the payload had, not what they asked for.
- *
- * The JSON is written whenever the stuff is anything more than its files: a
- * result that IS one image has nothing left over once the image is saved, so
- * writing `{"url": …}` beside it would be a second file saying less than the
- * first. A result with fields around its files keeps both.
- *
- * A file that cannot be fetched is opened in a tab instead of failing. The
- * fetch is same-origin for a host that proxies its storage, but a remote URL
- * with no CORS header cannot be read into a blob at all, and handing the reader
- * the file in a tab is the difference between an awkward download and none.
- */
-declare function downloadStuff({ field, value, baseName, resolveUrl, }: {
-    field: RunField;
-    value: unknown;
-    /** Names the JSON file and prefixes any file that has no name of its own. */
-    baseName: string;
-    resolveUrl?: ResolveForDownload;
-}): Promise<void>;
+declare function ResultField(props: ResultFieldProps): react.JSX.Element;
 
 /**
  * The host's seam for turning a stored reference into something a browser can
@@ -401,10 +302,57 @@ type ResolveShareUrl = (url: string) => Promise<string | undefined>;
  * Only `http:` and `https:` are ever painted or linked either way.
  */
 type ProseImages = 'link' | 'load';
+/**
+ * Which download controls a result view draws, each set on its own.
+ *
+ * Apps want different things here: one shows only the download of the whole
+ * result, another only a download on each image, a third both, a fourth
+ * neither because it saves results its own way. So the two are independent,
+ * and the per-file one can be narrowed to the kinds of file that should carry
+ * it.
+ *
+ * Set once on `ResultEnvProvider`, because a file's own button is drawn deep
+ * inside the result (a gallery tile, a table row's detail, a nested record) and
+ * has to follow the setting whether or not a `StuffViewer` wraps it.
+ * `StuffViewer`'s own `downloads` prop overrides it, key by key, for that one
+ * panel.
+ *
+ * Hiding a control never disables saving: a host with its own save UI still
+ * plans with `planStuffSave` and delivers through its own function.
+ */
+interface DownloadDisplay {
+    /** The header control that saves the whole result. Drawn unless `false`. */
+    result?: boolean;
+    /**
+     * Each file's own download button: on every file when `true` (the default),
+     * on none when `false`, or only on the kinds listed — `'image'`,
+     * `'document'`, and `'markup'` for an HTML page.
+     */
+    files?: boolean | readonly StuffFileKind[];
+}
 interface ResultEnv {
     resolveUrl?: ResolveUrl;
     resolveShareUrl?: ResolveShareUrl;
     proseImages?: ProseImages;
+    /**
+     * How saved files reach the reader. Every download goes through it: the
+     * whole-result control and each file's own button alike, each handing it the
+     * files to save as a plan (a name, a media type, and the URL the gate
+     * admitted or the inline text).
+     *
+     * Unset, files are saved by the browser tab (`saveInBrowser`), which fetches
+     * each URL and saves the bytes through an object URL and a clicked link. A
+     * host whose view runs in a sandboxed frame is refused all of that, and
+     * supplies a function that asks the host to deliver the files instead —
+     * passing the URLs on as links, since a host's download bridge fetches links
+     * itself.
+     *
+     * It reports the files it could not deliver rather than throwing, so the
+     * control can tell the reader which ones did not arrive.
+     */
+    saveFiles?: SaveFiles;
+    /** Which download controls are drawn. Both, on every kind of file, when unset. */
+    downloads?: DownloadDisplay;
     /**
      * How many data columns a table of records shows. Five when unset.
      *
@@ -422,7 +370,7 @@ interface ResultEnv {
      */
     tableColumns?: number;
 }
-declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, proseImages, tableColumns, children, }: ResultEnv & {
+declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, proseImages, tableColumns, saveFiles, downloads, children, }: ResultEnv & {
     children: ReactNode;
 }): react.JSX.Element;
 /**
@@ -443,6 +391,109 @@ declare function useResolveShareUrl(): ResolveShareUrl | undefined;
 /** The prose-image policy, defaulted to the safe answer for a host that stated none. */
 declare function useProseImages(): ProseImages;
 
+/**
+ * A pipe's result, with the two views a result actually needs.
+ *
+ * ## Two, and why not three
+ *
+ * **Rendered** is the answer for a person: the descriptor-driven view, which
+ * knows a field is an enum, that a date arrived in the serializer's typed
+ * envelope, that fifteen records are a table. **JSON** is the answer for whoever
+ * is debugging the pipe: what exactly came back, verbatim, copyable. Those are
+ * different jobs and neither substitutes for the other.
+ *
+ * They are deliberately NOT peers, and the toggle should not read as a menu of
+ * equal options. One is the result; the other is the receipt. Rendered opens
+ * first, always.
+ *
+ * A third view is the one to resist. An engine-rendered HTML or plain-text
+ * presentation — the shape the runtime's own viewer offers — is a second human
+ * rendering of the same payload, produced by another codebase, carrying no
+ * descriptor (so it cannot know a kind, a plurality or a nesting) and unable to
+ * match a host's design system. It is a renderer that cannot be improved without
+ * shipping the engine. If a plain-text form is wanted, it is a COPY FORMAT and
+ * belongs behind a copy control, not beside the view that reads the standard.
+ */
+type StuffViewerView = 'rendered' | 'json';
+interface StuffViewerProps {
+    field: RunField;
+    value: unknown;
+    /**
+     * The STUFF's name, for the header — `report_pages`, not `output`.
+     *
+     * A result descriptor's root node is named by the engine that built it, and
+     * `build_output_form` calls it `output` for every pipe there has ever been.
+     * That is correct in the artifact: the descriptor describes a pipe's output
+     * slot, which has no name of its own. It is wrong on screen, where the reader
+     * is looking at ONE data item and every other surface — the graph node they
+     * clicked, the input panel beside it, the method's own code — calls that item
+     * by the name the author gave it.
+     *
+     * So the name comes from the caller, because only the caller knows it: the
+     * graph knows which node was opened, a run page knows which variable it is
+     * showing. Absent, the descriptor's own name stands, which keeps a host that
+     * has nothing better to say honest rather than blank.
+     *
+     * It also supplies `downloadBaseName`'s default, so the file a reader saves
+     * is named after the thing they were reading rather than `output.json`.
+     */
+    name?: string;
+    /** Which view opens first. Rendered, unless a host has a reason. */
+    defaultView?: StuffViewerView;
+    /**
+     * Names the saved files: `<baseName>.json`, and any file inside the stuff
+     * that carries no name of its own, whichever control saved it. Defaults to
+     * the field's name, which is what the header shows.
+     */
+    downloadBaseName?: string;
+    /**
+     * Which download controls this panel draws, laid key by key over what
+     * `ResultEnvProvider` says: `{ result: false }` drops the header's Download
+     * and keeps each file's own button, `{ files: false }` the reverse. For a
+     * surface where saving makes no sense (a preview inside an editor, say), set
+     * both to `false`.
+     */
+    downloads?: DownloadDisplay;
+    className?: string;
+}
+/**
+ * The payload as JSON — the receipt, with the whole of it one click from the
+ * clipboard.
+ *
+ * Exported because it is also the honest FLOOR: a host that holds a value but
+ * not the artifacts describing it (an older engine, a spec restored without its
+ * validate report) should show the value and say why it is not laid out, rather
+ * than show nothing. That is a different thing from what `StuffViewer`'s JSON
+ * tab was — one labelled fallback, not one of three guesses offered as a
+ * choice.
+ */
+declare function JsonView({ value }: {
+    value: unknown;
+}): react.JSX.Element;
+declare function StuffViewer({ downloads, ...props }: StuffViewerProps): react.JSX.Element;
+
+/**
+ * The default delivery: the planned files, saved by this browser tab.
+ *
+ * Inline content is written straight into a blob. A URL is fetched and its
+ * bytes saved under the planned name. The fetch is same-origin for a host that
+ * proxies its storage, and works cross-origin only where the server sends a
+ * CORS header, so a file that cannot be read is REPORTED rather than recovered.
+ *
+ * There used to be a recovery: open the URL in a new tab when the fetch failed.
+ * It could not run. The fetch is awaited, so by the time it failed the click
+ * that started the download was spent, and a popup blocker suppresses a window
+ * opened outside a click, silently, inside a `catch` that also swallowed the
+ * reason. Reporting the file instead is what lets the control that asked tell
+ * the reader, and the reader still has the file's own link in the rendered
+ * view.
+ *
+ * This is also what a host gets from `ResultEnvProvider` when it supplies no
+ * `saveFiles` of its own, and it is exported for a host that wants to fall back
+ * to it, from a bridge that is not always there.
+ */
+declare function saveInBrowser(files: readonly SaveFile[]): Promise<SaveResult>;
+
 interface HtmlPreviewProps {
     content: HtmlContentView;
     /**
@@ -622,6 +673,20 @@ interface FieldStrings {
     download: string;
     /** Announced while the files are being fetched. */
     downloading: string;
+    /**
+     * What the whole-result download says when some files did not arrive: the
+     * ones no URL could be found for, and the ones the delivery reported. Takes
+     * the names the files would have been saved under.
+     */
+    downloadIncomplete: (names: readonly string[]) => string;
+    /**
+     * The button beside each file that saves that one file, given the name it
+     * saves under: a gallery of buttons all called "Download" would leave a
+     * screen-reader user unable to tell which file each one saves.
+     */
+    downloadFile: (name: string) => string;
+    /** What that button says when the file did not arrive. */
+    downloadFileFailed: string;
     /** The result panel's two views, and the control that copies the payload. */
     viewRendered: string;
     viewJson: string;
@@ -708,4 +773,4 @@ declare function useFieldPresentation(): FieldPresentation;
  */
 declare function humanizeFieldName(name: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, HtmlPreview, type HtmlPreviewProps, ImageField, JsonView, ListField, Markdown, type MarkdownProps, NumberField, ObjectField, OptionalToggle, ProseField, type ProseImages, type ResolveForDownload, type ResolveShareUrl, type ResolveUrl, ResultEnvProvider, ResultField, type ResultFieldProps, StuffViewer, type StuffViewerProps, type StuffViewerView, TextField, UnknownField, downloadStuff, fieldControlClass, humanizeFieldName, useFieldDomId, useFieldPresentation, useFieldStrings, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, type DownloadDisplay, EnumField, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, HtmlPreview, type HtmlPreviewProps, ImageField, JsonView, ListField, Markdown, type MarkdownProps, NumberField, ObjectField, OptionalToggle, ProseField, type ProseImages, type ResolveShareUrl, type ResolveUrl, ResultEnvProvider, ResultField, type ResultFieldProps, StuffViewer, type StuffViewerProps, type StuffViewerView, TextField, UnknownField, fieldControlClass, humanizeFieldName, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl };

package/dist/react/index.js

@@ -1,7 +1,8 @@
 "use client";
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, HtmlPreview, ImageField, JsonView, ListField, Markdown, NumberField, ObjectField, OptionalToggle, ProseField, ResultEnvProvider, ResultField, StuffViewer, TextField, UnknownField, downloadStuff, fieldControlClass, humanizeFieldName, useFieldDomId, useFieldPresentation, useFieldStrings, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-E2IVBAW3.js';
-import '../chunk-4JQAJT7C.js';
-import '../chunk-TID7ZN63.js';
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, HtmlPreview, ImageField, JsonView, ListField, Markdown, NumberField, ObjectField, OptionalToggle, ProseField, ResultEnvProvider, ResultField, StuffViewer, TextField, UnknownField, fieldControlClass, humanizeFieldName, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-4KX6YTLW.js';
+import '../chunk-V7T4DM63.js';
+import '../chunk-VS5JMFUV.js';
+import '../chunk-CM4KVG53.js';
 import '../chunk-FABY3DEY.js';
 import '../chunk-XCO6GTEC.js';
 import '../chunk-PM55AHRO.js';

package/package.json

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

package/dist/chunk-4JQAJT7C.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/stuff-files.ts"],"names":[],"mappings":"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","file":"chunk-4JQAJT7C.js","sourcesContent":["import { ownProp } from './own-property';\nimport {\n  isNativeHtmlNode,\n  readDocumentContent,\n  readHtmlContent,\n  readImageContent,\n} from './native-content';\nimport type { RunField } from './descriptor';\n\n/**\n * One file a stuff carries: what to fetch, and what to call it once saved.\n */\nexport interface StuffFile {\n  /**\n   * The durable reference or URL the value states, for a file held BY\n   * REFERENCE. Absent for inline content, which needs no fetch.\n   */\n  url?: string;\n  /**\n   * The content itself, for a file the stuff carries INLINE — markup, today.\n   * Exactly one of `url` and `text` is set.\n   */\n  text?: string;\n  /** The extension to save inline content under, without the dot. */\n  extension?: string;\n  /**\n   * The URL that works outside this session, when the value carries one. A host\n   * whose display URL is session-scoped (an owner-checked proxy route) needs\n   * this for anything that leaves the browser.\n   */\n  publicUrl?: string;\n  /** The file's own name when it states one — otherwise the caller derives it. */\n  filename?: string;\n  mimeType?: string;\n  /** Where it sat, dotted: `report.attachments.2.scan`. Names a saved file. */\n  path: string;\n  kind: 'image' | 'document' | 'markup';\n}\n\n/**\n * Every file inside a stuff, found by walking the DESCRIPTOR — never the value.\n *\n * The distinction is the whole point. A payload walk would have to decide what\n * a file is by looking at it: an object with a `url`, a string that ends in\n * `.pdf`. That is the guessing this package exists to remove, and it is wrong in\n * both directions — a method whose output legitimately has a `url` field of its\n * own is not a document, and a stored image whose reference carries no extension\n * is. The descriptor already states `kind: \"image\"` or `kind: \"document\"`, so\n * the walk reads the declaration and consults the value only for the members\n * that declaration promises.\n *\n * Ordering is the authored one, depth-first, which is the order the rendered\n * view puts them in — so a download of three images numbers them the way the\n * reader saw them.\n */\nexport function collectStuffFiles(field: RunField, value: unknown): StuffFile[] {\n  const found: StuffFile[] = [];\n  walk(field, value, [], found);\n  return found;\n}\n\nfunction walk(field: RunField, raw: unknown, path: string[], out: StuffFile[]): void {\n  const value = unwrapContent(field, raw);\n  const here = path.length > 0 ? path : [field.name];\n\n  // Markup, before the kind switch, exactly as the renderer takes it: a\n  // `native.Html` node's KIND is `object` (its content model has two members),\n  // so the switch below would walk into it looking for files and find none.\n  //\n  // It is a file even though nothing stores it as one. The stuff IS a page —\n  // the reader is looking at a rendered report — and handing them a JSON\n  // envelope with the page inside it as a string is the same mistake as handing\n  // them a URL instead of a picture. `isNativeHtmlNode` asks the descriptor\n  // whether the concept refines `native.Html`, which is the standard's own way\n  // to ask; it never looks at the value to decide.\n  if (isNativeHtmlNode(field)) {\n    const content = readHtmlContent(value);\n    if (content?.innerHtml) {\n      out.push({\n        text: content.innerHtml,\n        extension: 'html',\n        path: here.join('.'),\n        kind: 'markup',\n      });\n    }\n    return;\n  }\n\n  switch (field.kind) {\n    case 'image': {\n      const content = readImageContent(value);\n      if (content?.url) {\n        out.push({\n          url: content.url,\n          publicUrl: content.publicUrl,\n          filename: content.filename,\n          mimeType: content.mimeType,\n          path: here.join('.'),\n          kind: 'image',\n        });\n      }\n      return;\n    }\n    case 'document': {\n      const content = readDocumentContent(value);\n      if (content?.url) {\n        out.push({\n          url: content.url,\n          publicUrl: content.publicUrl,\n          filename: content.filename,\n          mimeType: content.mimeType,\n          path: here.join('.'),\n          kind: 'document',\n        });\n      }\n      return;\n    }\n    case 'object': {\n      if (typeof value !== 'object' || value === null || Array.isArray(value)) return;\n      const record = value as Record<string, unknown>;\n      for (const child of field.fields) {\n        walk(child, ownProp(record, child.name), [...here, child.name], out);\n      }\n      return;\n    }\n    case 'list': {\n      if (!Array.isArray(value)) return;\n      // The element descriptor's own `name` is unused by the standard, so the\n      // index is what identifies an entry — the same thing the rendered list\n      // shows beside each row.\n      value.forEach((entry, index) => walk(field.item, entry, [...here, String(index)], out));\n      return;\n    }\n    default:\n      // Every other kind is a scalar. It cannot contain a file, and a `native`\n      // node with no declared members (an `unknown` kind — a composite, say)\n      // states nothing a walk could follow, so there is nothing to look at.\n      return;\n  }\n}\n\n/**\n * The one unwrap path, matching the renderer's: a content model is opened by\n * the property the schema named, and by nothing else.\n */\nfunction unwrapContent(field: RunField, value: unknown): unknown {\n  if (!field.contentKey) return value;\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return value;\n  const unwrapped = ownProp(value as Record<string, unknown>, field.contentKey);\n  return unwrapped === undefined ? value : unwrapped;\n}\n"]}