@pipelex/mthds-form 0.35.1 → 0.36.0

package/dist/generative/index.js

@@ -1,5 +1,5 @@
 "use client";
-import { cn, headingClass, checkedAccentClass, focusOutlineClass, useResolveUrl, panelSurfaceClass, panelFlatShadowClass, linkTextClass, actionShadowClass, panelRaisedShadowClass, fieldControlClass, useFieldPresentation, useFieldStrings, fieldLabel, ResultRoot, ResultField, FieldRenderer, enumLabeler, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem, selectedBorderClass, selectedFillClass, isThenable, FieldPresentationProvider } from '../chunk-TD62R3P6.js';
+import { cn, headingClass, checkedAccentClass, focusOutlineClass, useResolveUrl, panelSurfaceClass, panelFlatShadowClass, linkTextClass, actionShadowClass, panelRaisedShadowClass, fieldControlClass, useFieldPresentation, useFieldStrings, fieldLabel, ResultRoot, ResultField, FieldRenderer, enumLabeler, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem, selectedBorderClass, selectedFillClass, isThenable, FieldPresentationProvider } from '../chunk-ROM2KLQD.js';
 import { baseCatalog, catalog, frameComponents, shareAmount, INPUTS_ROOT, joinPath, resultFieldAtPath, segmentsUnder, RESULT_ROOT, inputFieldAtPath, definitionChain, unwrapped } from '../chunk-XLTYIIUY.js';
 export { COMPONENT_NAMES, COMPONENT_RENDERINGS, COMPOSER_COMPONENTS, CUSTOM_COMPONENTS, DESIGNER_BRIEF_CONCEPT, DESIGNER_CATALOG_CONCEPT, FRAMES, FRAME_COMPONENTS, ICON_NAMES, INPUTS_ROOT, METRIC_FORMATS, PICKED_SHADCN, PRODUCT_COMPONENTS, PROMPT_HASH, REPAIR_ATTEMPTS, RESULT_COMPONENTS, RESULT_ROOT, absoluteHatchPath, catalog, componentNamesFor, designerCatalog, fieldAtSegments, findFixture, fixtureId, fixtureLabel, formatProblems, frameCatalog, inputBrief, inputFieldAtPath, isDelegatedInput, isDelegatedResult, joinPath, jsonlLines, layoutCheck, layoutCheckProblems, layoutFits, layoutProblems, payloadToState, promptHashSubject, repeatBasePathOf, resultBrief, resultFieldAtPath, seedLine, segmentsUnder, specFromJsonl, specToJsonl, validateAgainstCatalog, writtenSampleOf } from '../chunk-XLTYIIUY.js';
 import '../chunk-4VAO6BDE.js';

package/dist/react/index.d.ts

@@ -326,6 +326,12 @@ interface FieldStrings {
     pdfViewerUnavailable: string;
     /** The link that opens a file in a new tab, where it cannot be shown in the page. */
     openInNewTab: string;
+    /** Said in a document's preview while the host makes a PDF of it. */
+    documentPdfPreparing: string;
+    /** Said in a document's preview when the host could not make a PDF of it and gives no reason. */
+    documentPdfFailed: string;
+    /** Said in a document's preview when the host has no PDF of it to offer. */
+    documentPdfUnavailable: 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
@@ -1069,6 +1075,94 @@ interface RenditionRequest {
  *   missing copy costs the reader the wait, never the picture.
  */
 type ResolveRendition = (url: string, request: RenditionRequest) => string | undefined;
+/**
+ * What the payload declares about a document a host is asked for a PDF of, so
+ * that a host can decide by the document's format.
+ */
+interface DocumentPdfRequest {
+    filename?: string;
+    mimeType?: string;
+}
+/**
+ * Where the PDF of a document stands, in the host's answer.
+ *
+ * - `ready`: `url` is where the PDF is read. It is the URL of a document the
+ *   view will frame, so it passes the same gate as any resolver's answer: an
+ *   `http(s):` URL, or a root-relative path on the host's own origin. An answer
+ *   the gate refuses reads as `unavailable`.
+ * - `preparing`: the host is making the PDF. The view says so and asks again.
+ * - `failed`: the host could not make the PDF. `message`, when the host can
+ *   say why (a file protected by a password), is shown to the reader as it
+ *   stands, so it must be in the reader's language; with none, the view says
+ *   the package's `documentPdfFailed`. The reader is offered to try again.
+ * - `unavailable`: there is no PDF of this document to be had, and asking
+ *   again would not change that (a file past the host's limits). The view says
+ *   there is no preview.
+ */
+type DocumentPdfAnswer = {
+    state: 'ready';
+    url: string;
+} | {
+    state: 'preparing';
+} | {
+    state: 'failed';
+    message?: string;
+} | {
+    state: 'unavailable';
+};
+/**
+ * One question to the host about one document: where does its PDF stand?
+ *
+ * The view asks when the reader opens the preview, and again while the answer
+ * is `preparing`, so asking twice must not start the work twice. An ask that
+ * throws, rejects, answers something else or takes longer than thirty seconds
+ * reads as `failed`.
+ */
+type AskDocumentPdf = () => Promise<DocumentPdfAnswer>;
+/**
+ * The host's seam for a PDF of a document the browser cannot render itself,
+ * such as a Word, Excel or PowerPoint file.
+ *
+ * ## Why a result view needs one
+ *
+ * A browser renders a PDF and a picture and nothing else a run hands back, so
+ * a `.docx` result is a name and a download. The kernel cannot convert it,
+ * since it holds a reference and the host holds the file; a host that can make
+ * a PDF of the file (a conversion service behind its storage) answers here.
+ *
+ * ## Why deciding and asking are apart
+ *
+ * Deciding is this function, which answers synchronously and is pure, as
+ * `ResolveRendition` is. It is called while the view renders, for every
+ * document the browser cannot render, and says only whether this host has a
+ * way to a PDF of this document: `undefined` means it has none, and the view
+ * behaves exactly as it does with no such function, offering no preview. So
+ * the Preview toggle is decided with no round trip, and a server render and
+ * the first browser render agree.
+ *
+ * Asking is the {@link AskDocumentPdf} it returns, which is the round
+ * trip. It is asked only when a reader opens the preview, because a conversion
+ * is real work and a run's result can hold many documents nobody will open: a
+ * host that converts on first request therefore converts only what someone
+ * asked to see.
+ *
+ * ## The contract
+ *
+ * Called with the document's own `url` member, exactly as `resolveUrl` is, and
+ * what the payload declares about it. The view decides which documents to ask
+ * about only from whether the browser renders them, so a host answers for the
+ * formats it converts, and the kernel keeps no list of them.
+ *
+ * - **A first view does not wait.** The ask is expected to answer quickly,
+ *   `preparing` while the PDF is being made, and the view shows that it is
+ *   preparing and asks again, at growing intervals, until the answer changes.
+ *   It stops after three minutes and reads that as `failed`, and it stops when
+ *   the reader closes the preview.
+ * - **It only ever shows pages.** The PDF is framed, or linked from the card
+ *   shown where the browser has no PDF viewer, and it is nothing else: the
+ *   document's name, its copy control and every download keep the original.
+ */
+type ResolveDocumentPdf = (url: string, request: DocumentPdfRequest) => AskDocumentPdf | undefined;
 /**
  * How a stored reference becomes a URL that works OUTSIDE this page — pasted
  * into another tab, another app, a colleague's message.
@@ -1215,6 +1309,13 @@ interface ResultEnv {
      * {@link ResolveRendition}.
      */
     resolveRendition?: ResolveRendition;
+    /**
+     * A PDF of a document the browser cannot render, such as a Word file, which
+     * the view shows in that document's preview. Optional; unset, or for a
+     * document it does not answer, the document offers no preview. See
+     * {@link ResolveDocumentPdf}.
+     */
+    resolveDocumentPdf?: ResolveDocumentPdf;
     resolveShareUrl?: ResolveShareUrl;
     proseImages?: ProseImages;
     /**
@@ -1273,7 +1374,7 @@ interface ResultEnv {
      */
     framed?: boolean;
 }
-declare function ResultEnvProvider({ resolveUrl, resolveUrls, resolveRendition, resolveShareUrl, proseImages, tableColumns, tableLayout, saveFiles, downloads, renderPdf, framed, children, }: ResultEnv & {
+declare function ResultEnvProvider({ resolveUrl, resolveUrls, resolveRendition, resolveDocumentPdf, resolveShareUrl, proseImages, tableColumns, tableLayout, saveFiles, downloads, renderPdf, framed, children, }: ResultEnv & {
     children: ReactNode;
 }): react.JSX.Element;
 /**
@@ -1291,6 +1392,8 @@ declare function useResolvedUrl(url: string): string;
 declare function useResolveUrl(): ResolveUrl | undefined;
 /** The host's smaller copies of a picture, when it supplies them. */
 declare function useResolveRendition(): ResolveRendition | undefined;
+/** The host's way to a PDF of a document the browser cannot render, when it supplies one. */
+declare function useResolveDocumentPdf(): ResolveDocumentPdf | 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. */
@@ -1799,4 +1902,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, type ExamplePickerSource, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, FieldPresentation, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, 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 RenditionRequest, type ResolveRendition, 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, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+export { type AskDocumentPdf, BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, type DocumentPdfAnswer, type DocumentPdfRequest, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, type ExamplePickerSource, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, FieldPresentation, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, 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 RenditionRequest, type ResolveDocumentPdf, type ResolveRendition, 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, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldStrings, useMethodForm, useProseImages, useResolveDocumentPdf, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };

package/dist/react/index.js

@@ -1,5 +1,5 @@
 "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, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-TD62R3P6.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, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveDocumentPdf, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-ROM2KLQD.js';
 import '../chunk-4VAO6BDE.js';
 import '../chunk-AURDKAIC.js';
 import '../chunk-L23R3JNQ.js';

package/package.json

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