@pipelex/mthds-form 0.4.0 → 0.6.0

package/dist/react/index.d.ts

@@ -1,6 +1,9 @@
 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 { 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
@@ -202,6 +205,215 @@ interface UnknownFieldProps {
  */
 declare function UnknownField({ field, value, onChange, id, error, disabled }: UnknownFieldProps): react.JSX.Element;
 
+interface ResultFieldProps {
+    field: RunField;
+    value: unknown;
+    /** Nesting depth, used only for indentation. */
+    depth?: number;
+    /**
+     * Suppress the field's own label. Set on a LIST ITEM, where the index already
+     * identifies the entry: the standard says an element descriptor's `name` is
+     * unused, and rendering it repeats the parent's label on every row.
+     */
+    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;
+    /** 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.
+ *
+ * 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({ field, value, 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>;
+
+/**
+ * The host's seam for turning a stored reference into something a browser can
+ * fetch.
+ *
+ * ## Why a result view needs one at all
+ *
+ * A run's files do not come back as public URLs. They come back as
+ * `pipelex-storage://…` references, which are an identity in the runtime's
+ * store and resolve nowhere in a browser. Without a way to exchange them, every
+ * file arm in the result view degrades to naming the file — a PDF that cannot
+ * be previewed, an image gallery of blank tiles — and no amount of care in
+ * those arms can fix it, because the missing thing is a fact only the host has.
+ *
+ * ## Why it is SYNCHRONOUS
+ *
+ * The obvious shape is `(uri) => Promise<string | null>`, and it is the wrong
+ * one here. It would put a loading state, a race and an effect into every arm
+ * that paints a file — inside table cells and gallery tiles, which are the
+ * places least able to carry them — and a gallery of twenty images would make
+ * twenty independent round trips as it scrolled.
+ *
+ * A host that resolves by REWRITING (the common case: map the reference onto
+ * its own `/assets` route, which checks ownership and streams the object) has
+ * no round trip to make and is served exactly by a pure function. A host that
+ * genuinely must presign is better off resolving the run's references in one
+ * batch — it holds the payload before it renders it — and closing over the
+ * result, which is also the only shape that does not make a gallery quadratic.
+ *
+ * So the seam is a pure function, and the async case is a lookup in a map the
+ * host filled. That is a real constraint on a host and it is stated rather than
+ * hidden.
+ *
+ * ## The contract
+ *
+ * Return `undefined` for a reference this host cannot resolve, and the view
+ * falls back to naming the file — which is what it does with no resolver at
+ * all. Never return a URL that will 404: a broken image tile says less than a
+ * filename.
+ */
+type ResolveUrl = (url: string) => string | undefined;
+/**
+ * How a stored reference becomes a URL that works OUTSIDE this page — pasted
+ * into another tab, another app, a colleague's message.
+ *
+ * Separate from `resolveUrl`, because the two answer different questions and a
+ * host's answers genuinely differ. A display URL may be a path on the host's
+ * own origin behind its session (`/api/assets/…`), which is what lets a strict
+ * `img-src 'self'` policy stand and what keeps a picture from expiring while
+ * the tab is open. That URL is useless on the clipboard: whoever pastes it has
+ * no session. A share URL therefore carries its own credential — a freshly
+ * minted presigned URL — and is minted per click rather than held, because it
+ * starts expiring the moment it exists.
+ *
+ * Async for the same reason: minting one is a round trip. Omit it and the copy
+ * control falls back to the display URL, which is right for a host whose
+ * storage is public anyway.
+ */
+type ResolveShareUrl = (url: string) => Promise<string | undefined>;
+interface ResultEnv {
+    resolveUrl?: ResolveUrl;
+    resolveShareUrl?: ResolveShareUrl;
+}
+declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, children, }: ResultEnv & {
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * The resolver, already applied.
+ *
+ * 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.
+ */
+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;
+
+interface HtmlPreviewProps {
+    content: HtmlContentView;
+    /**
+     * Beyond this the frame scrolls rather than growing.
+     *
+     * Generous on purpose. A `native.Html` result is usually a whole report, and
+     * 480px showed three paragraphs of one with a scrollbar down the side while
+     * the panel around it sat empty — the reader scrolls twice to read once. The
+     * frame still sizes itself to its CONTENT, so a short snippet stays short;
+     * this only says how far it may grow before scrolling instead.
+     */
+    maxHeight?: number;
+    /**
+     * The frame's `img-src`. Defaults to `data: https:` — a method's HTML result
+     * embeds the images that method produced. Pass `"data:"` to block remote
+     * images entirely, or name an origin to allow only your own storage.
+     */
+    imgSrc?: string;
+}
+declare function HtmlPreview({ content, maxHeight, imgSrc, }: HtmlPreviewProps): react.JSX.Element;
+
+interface MarkdownProps {
+    text: string;
+    className?: string;
+}
+declare function Markdown({ text, className }: MarkdownProps): react.JSX.Element;
+
 interface FieldShellProps {
     name: string;
     title?: string;
@@ -279,6 +491,53 @@ interface FieldStrings {
     preview: string;
     removeFileAria: string;
     previewUnavailablePdf: string;
+    /**
+     * What a result slot the run resolved as an absence SHOWS — a dash, not a
+     * sentence. Beside forty values in a grid, "not provided" repeated is louder
+     * than the data; a dash reads as the blank it is.
+     */
+    resultAbsent: string;
+    /**
+     * What that dash SAYS, to a screen reader.
+     *
+     * The two are separate because a glyph and a sentence are answers to different
+     * questions. A table column of hyphens read aloud is "hyphen, hyphen, hyphen",
+     * which is noise rather than information — so the dash is `aria-hidden` and
+     * this rides beside it, visually hidden.
+     */
+    resultAbsentDescription: string;
+    /**
+     * Shown above the raw value when a result cannot be laid out because the
+     * artifacts describing it are absent. It names the CAUSE — the descriptor,
+     * not the data — because the value is right there underneath and a reader
+     * who is not told why will assume the view is broken.
+     */
+    resultUndescribed: string;
+    /** The control that opens a result table row to show the rest of the record. */
+    toggleRowDetails: (index: number) => string;
+    /** The (visually hidden) header of the column those controls sit in. */
+    rowDetailsColumn: string;
+    /** The control that puts a file's whole URL on the clipboard. */
+    copyUrl: string;
+    /** The copy control beside any text value, markdown or not. */
+    copyText: string;
+    /** The download control's label. */
+    download: string;
+    /** Announced while the files are being fetched. */
+    downloading: string;
+    /** The result panel's two views, and the control that copies the payload. */
+    viewRendered: string;
+    viewJson: string;
+    copyJson: string;
+    resultViewGroup: string;
+    yes: string;
+    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.
+     */
+    unsupportedFileType: (accept: string) => string;
     /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
     hideOptionalFields: string;
     hideOptionalInputs: string;
@@ -294,6 +553,24 @@ declare function FieldStringsProvider({ strings, children, }: {
 /** The strings the nearest provider supplies (English defaults when none does). */
 declare function useFieldStrings(): FieldStrings;
 
+declare function FieldDomIdProvider({ prefix, children, }: {
+    /**
+     * Omit to mint one from `useId`; `''` writes the path unprefixed. An explicit
+     * prefix must be unique in the document - one provider, one form.
+     */
+    prefix?: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * The DOM id for a field path - the ONE place a path becomes an attribute.
+ *
+ * Called once per control so the `<label for>` and the control's `id` are the
+ * same string by construction: the pairing cannot drift, because there is only
+ * one call. `useId` runs unconditionally (hooks must) and is simply unused when
+ * a provider supplies the prefix.
+ */
+declare function useFieldDomId(path: string): string;
+
 /**
  * How a field's LABEL chrome should read. The control itself never changes.
  *
@@ -324,4 +601,4 @@ declare function useFieldPresentation(): FieldPresentation;
  */
 declare function humanizeFieldName(name: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, type FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldRenderer, type FieldRendererProps, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, ImageField, ListField, NumberField, ObjectField, OptionalToggle, ProseField, TextField, UnknownField, fieldControlClass, humanizeFieldName, useFieldPresentation, useFieldStrings };
+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 };