@fieldia/viewer 0.11.0 → 0.13.0

package/src/lib/viewer.d.ts

@@ -1,6 +1,9 @@
-import { type ActionHost, type ActionStep, type FormEvents, type Form, type FormOptions, type Page, type RecordId, type Locale, type OpenRequest, type OpenResult, type RunContext, type RunResult, type Values } from '@fieldia/core';
+import { type ActionHost, type ActionStep, type FormEvents, type Form, type FormOptions, type LayoutNode, type Page, type Theme, type RecordId, type ResolvedFilter, type Locale, type OpenRequest, type OpenResult, type RunContext, type RunResult, type Values } from '@fieldia/core';
 import { type IconSet, type PreferenceStore, type WidgetFactory } from '@fieldia/widgets';
 import { type PageFinder } from './related';
+import { type Tokens } from './look';
+import { type Breadcrumb, type RecordPager } from './record-bar';
+export type { Breadcrumb, RecordPager } from './record-bar';
 export type Skin = 'underline' | 'outlined';
 import { type ViewerLabels } from './labels';
 export { VIEWER_LABELS, DEFAULT_LABELS, type ViewerLabels } from './labels';
@@ -14,7 +17,17 @@ export interface ViewerOptions extends Omit<FormOptions, 'page' | 'host'> {
     page: Page;
     /** A form made elsewhere, to share one record between two views. */
     form?: Form;
+    /** The skin: a theme's own when it is left out (see `THEME_SKINS`), else `underline`. */
     skin?: Skin;
+    /** A theme in the style of a known design system, over the page's own (`look.theme`). */
+    theme?: Theme;
+    /**
+     * The host's own colours, corners and font, over the skin's, the theme's, the
+     * scheme's and the page's: `{ text, surface, accent, … }` (`TOKEN_NAMES`). The
+     * supported way to dress a form in an app's theme; a host's own stylesheet
+     * rule on the form does the same.
+     */
+    tokens?: Tokens;
     /** Widgets that replace or add to the built-in ones, by `type` or `type.widget`. */
     widgets?: Record<string, WidgetFactory>;
     slots?: Record<string, SlotRenderer>;
@@ -79,6 +92,8 @@ export interface ViewerOptions extends Omit<FormOptions, 'page' | 'host'> {
     translate?: (text: string) => string;
     /** A list page: a row was opened, by a click or by Enter. The app shows the record. */
     onOpenRecord?: (id: RecordId) => void;
+    /** A list page: only the records these conditions let through, whatever is searched — the invoices of one order, opened from it. */
+    listFilter?: ResolvedFilter[];
     /**
      * What the page's steps ask of the screen, the viewer does itself: a page
      * opened (in a dialog, a side panel, or this form's place, with Back), words
@@ -91,11 +106,32 @@ export interface ViewerOptions extends Omit<FormOptions, 'page' | 'host'> {
      * your router, your own dialog — or with undefined to let the viewer open it.
      */
     onOpen?: (request: OpenRequest) => Promise<OpenResult> | undefined;
+    /**
+     * The records round this one, for the pager over a record — "3 / 42",
+     * Previous and Next — as the list it was opened from has them: their ids in
+     * order, or how many there are, where this one is, and the id at a place.
+     * Moving saves what changed first, as Flectra does; the form then shows
+     * the other record (its `open` event says which). A copy joins them after
+     * its record; a record deleted leaves them, the pager moving to the next.
+     * Never in a dialog.
+     */
+    records?: readonly RecordId[] | RecordPager;
+    /**
+     * The trail to this record, for the breadcrumbs over it: each page before
+     * it with its words and what a press does (back to it); the record itself
+     * comes last, by its name. A page a step opens in this one's place adds
+     * this one to the trail, as the way back. Never in a dialog.
+     */
+    breadcrumbs?: readonly Breadcrumb[];
 }
 export interface ViewerHandle {
     readonly form: Form;
     readonly element: HTMLElement;
     setSkin(skin: Skin): void;
+    /** Wear another theme; the skin follows it unless the viewer was given one. */
+    setTheme(theme: Theme | null): void;
+    /** Wear the host's tokens in place of those given before, as when its app turns dark; null takes them off. Dialogs opened after wear them too. */
+    setTokens(tokens: Tokens | null): void;
     /** Save the record, or take the focus to the first problem when the form refuses. */
     save(): Promise<boolean>;
     /** Check the form without saving, taking the focus to the first problem. */
@@ -116,4 +152,11 @@ export interface ViewerHandle {
  * React, Angular and Vue bindings are thin shells around this function.
  * Throws when the page does not validate, listing every problem.
  */
-export declare function mountViewer(host: HTMLElement, options: ViewerOptions): ViewerHandle;
+export declare function mountViewer(host: HTMLElement, given: ViewerOptions): ViewerHandle;
+/**
+ * A one-line row's parts in runs that wrap as one: words before a field
+ * ("Expected:", "to") go with it, and words after it that no field follows
+ * ("attempts") too, as Flectra keeps them in one span; any other part runs
+ * alone.
+ */
+export declare function onelineRuns(children: readonly LayoutNode[]): LayoutNode[][];