nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/DashboardHelpers.d.ts

@@ -0,0 +1,115 @@
+import type { DashboardLayout, DashboardLayoutItem, WidgetContext, WidgetDefinition, WidgetModuleLoader, WidgetSize } from "../Interfaces/DashboardInterfaces.ts";
+/** Each size's span on the 12-column grid, and its name in the size menu. */
+export declare const WIDGET_SPANS: Readonly<Record<WidgetSize, {
+    readonly columns: number;
+    readonly rows: number;
+    readonly label: string;
+}>>;
+/** The sizes in the order a size menu lists them. */
+export declare const WIDGET_SIZES: readonly WidgetSize[];
+/** "Medium (6 × 2)". */
+export declare const widgetSizeLabel: (size: WidgetSize) => string;
+/** Whether a widget may go on a place's board: an `anywhere` widget everywhere, an `own` one on its module's board only. */
+export declare function widgetAllowedIn(widget: Pick<WidgetDefinition, "placement" | "module">, placeModule: string | null | undefined): boolean;
+/**
+ * The widgets a place's board may draw now, by code: allowed in the place and seen by the person (`canSee`: the module
+ * held, the key held). Duplicate codes keep the first.
+ */
+export declare function drawableWidgets(widgets: readonly WidgetDefinition<any>[], placeModule: string | null | undefined, canSee?: (widget: WidgetDefinition<any>) => boolean): Map<string, WidgetDefinition<any>>;
+/**
+ * A layout as the board keeps it: each code once (the first), each size one its widget takes (else its first). A code
+ * the board does not know now (a widget hidden, removed from the app, or not allowed here) is kept as it was, so it
+ * comes back if it can be drawn again.
+ */
+export declare function normaliseLayout(layout: readonly DashboardLayoutItem[] | null | undefined, widgets: readonly WidgetDefinition<any>[]): DashboardLayoutItem[];
+/** The items of a layout the board draws now, in order. */
+export declare function drawnItems(layout: DashboardLayout, drawable: ReadonlyMap<string, unknown>): DashboardLayoutItem[];
+/**
+ * A layout to save after an edit of the drawn items: the edited items in their new order, and every item that was not
+ * drawn (hidden now) back in its place - after the drawn item it followed, or at the start. One whose drawn neighbour
+ * was removed follows the drawn item before that one. Nothing hidden is lost by a save.
+ */
+export declare function mergeHidden(full: DashboardLayout, edited: DashboardLayout, drawable: ReadonlyMap<string, unknown>): DashboardLayoutItem[];
+/** The list with the item at `from` moved to `to` (both clamped). */
+export declare function moveItem<T>(list: readonly T[], from: number, to: number): T[];
+/** Whether two layouts are the same widgets, sizes and order. */
+export declare function sameLayout(a: DashboardLayout | null | undefined, b: DashboardLayout | null | undefined): boolean;
+/** A widget's box on the screen, as the keyboard and the drag read it. */
+export interface WidgetRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * The widget an arrow key up or down moves to: in the nearest row above (or below) the one at `index`, the one whose
+ * middle is nearest across. `null` when there is no row that way. Rows are told apart by their tops.
+ */
+export declare function neighbourInColumn(rects: readonly WidgetRect[], index: number, direction: "up" | "down"): number | null;
+/** The widget under a point, leaving out `skip` (the one being dragged). `null` over a gap. */
+export declare function widgetAtPoint(rects: readonly WidgetRect[], x: number, y: number, skip: number): number | null;
+/** A module's widgets in the Add list. */
+export interface WidgetGroup {
+    module: string;
+    widgets: {
+        widget: WidgetDefinition<any>;
+        onBoard: boolean;
+    }[];
+}
+/**
+ * The Add list: every widget the place may draw now, grouped by module - the place's own module first, the rest in the
+ * order the app declared them - each marked when it is on the board already.
+ */
+export declare function addableWidgets(drawable: ReadonlyMap<string, WidgetDefinition<any>>, layout: DashboardLayout, placeModule: string | null | undefined): WidgetGroup[];
+/** Whether a widget's data is nothing to show: its own `isEmpty`, else `null`, `undefined` or an empty list. */
+export declare function widgetDataEmpty(widget: Pick<WidgetDefinition<any>, "isEmpty">, data: unknown): boolean;
+/** Whether a widget reads data at all (`load` or `batch`). */
+export declare const widgetNeedsData: (widget: Pick<WidgetDefinition<any>, "load" | "batch">) => boolean;
+/** What `createWidgetBatcher` answers. */
+export interface WidgetBatcher {
+    /**
+     * The widget's data: from the cache while fresh (unless `force`), from a call already on its way, else asked. Batched
+     * widgets asked in the same task go to their module together, one call per module.
+     */
+    request(widget: WidgetDefinition<any>, context: WidgetContext, options?: {
+        force?: boolean;
+    }): Promise<unknown>;
+    /** The widget's data as kept, and when it came. */
+    cached(code: string): {
+        data: unknown;
+        at: number;
+    } | undefined;
+    /** Keeps data read elsewhere (with the page, on the server) as if it had been asked now. */
+    prime(code: string, data: unknown): void;
+    /** Whether the widget's kept data is still fresh (its `refresh` seconds; no `refresh`: the page's life). */
+    isFresh(widget: Pick<WidgetDefinition<any>, "code" | "refresh">): boolean;
+    /** Forgets the kept data (of these codes, or all), so the next request asks again. */
+    clear(codes?: readonly string[]): void;
+    /** How many calls went out: each module call and each own `load` count one. */
+    readonly calls: number;
+}
+export interface WidgetBatcherOptions {
+    /** The clock, for tests. Default `Date.now`. */
+    now?: () => number;
+    /** When the gathered requests go out. Default: the next task (`setTimeout(0)`), so one draw's requests go together. */
+    defer?: (flush: () => void) => void;
+}
+/**
+ * One cache and one queue for a board's widgets: every batched widget asked while one draw runs goes to its module in
+ * one call (`loadModule(module, codes)`), each answer is kept for the page's life (or the widget's `refresh` seconds),
+ * and a widget asked twice while its call is on its way waits for that call.
+ */
+export declare function createWidgetBatcher(loadModule: WidgetModuleLoader | undefined, options?: WidgetBatcherOptions): WidgetBatcher;
+/** A typed mark on a calendar widget's day: a holiday, a leave, an event, or a kind of the app's own. */
+export interface CalendarMark {
+    /** The first day, an ISO date. */
+    date: string;
+    /** The last day of a mark over several days (a leave), an ISO date; none for one day. */
+    until?: string;
+    /** `holiday`, `leave`, `event`, or the app's own kind (give it in `kinds`). */
+    kind: string;
+    /** What it is: "Dashain", "Sita Rai - annual leave". */
+    label: string;
+}
+/** Each day's marks, by ISO date: a mark over several days is on each of them. A mark with a broken date is left out. */
+export declare function marksByDay(marks: readonly CalendarMark[]): Map<string, CalendarMark[]>;

package/dist/Helpers/DashboardHelpers.js

@@ -0,0 +1,305 @@
+/*
+ * A dashboard board's rules, kept apart from React so they can be tested alone: the size presets, which widgets a place
+ * may draw, a layout kept whole through edits (the widgets a person cannot see now keep their places), moving in the
+ * list by keyboard and by pointer, the Add list, and the batcher that asks each module once per draw.
+ */
+import { addDays, isIsoDate } from "./DateHelpers.js";
+/** Each size's span on the 12-column grid, and its name in the size menu. */
+export const WIDGET_SPANS = {
+    S: { columns: 3, rows: 1, label: "Small" },
+    M: { columns: 6, rows: 2, label: "Medium" },
+    L: { columns: 6, rows: 4, label: "Large" },
+    W: { columns: 12, rows: 2, label: "Wide" },
+    T: { columns: 12, rows: 4, label: "Tall" },
+};
+/** The sizes in the order a size menu lists them. */
+export const WIDGET_SIZES = ["S", "M", "L", "W", "T"];
+/** "Medium (6 × 2)". */
+export const widgetSizeLabel = (size) => `${WIDGET_SPANS[size].label} (${WIDGET_SPANS[size].columns} × ${WIDGET_SPANS[size].rows})`;
+/** Whether a widget may go on a place's board: an `anywhere` widget everywhere, an `own` one on its module's board only. */
+export function widgetAllowedIn(widget, placeModule) {
+    return widget.placement === "anywhere" || (placeModule !== null && placeModule !== undefined && widget.module === placeModule);
+}
+/**
+ * The widgets a place's board may draw now, by code: allowed in the place and seen by the person (`canSee`: the module
+ * held, the key held). Duplicate codes keep the first.
+ */
+export function drawableWidgets(widgets, placeModule, canSee) {
+    const drawable = new Map();
+    for (const widget of widgets) {
+        if (drawable.has(widget.code) || widget.sizes.length === 0)
+            continue;
+        if (!widgetAllowedIn(widget, placeModule))
+            continue;
+        if (canSee && !canSee(widget))
+            continue;
+        drawable.set(widget.code, widget);
+    }
+    return drawable;
+}
+/**
+ * A layout as the board keeps it: each code once (the first), each size one its widget takes (else its first). A code
+ * the board does not know now (a widget hidden, removed from the app, or not allowed here) is kept as it was, so it
+ * comes back if it can be drawn again.
+ */
+export function normaliseLayout(layout, widgets) {
+    const byCode = new Map(widgets.map(widget => [widget.code, widget]));
+    const seen = new Set();
+    const items = [];
+    for (const item of layout ?? []) {
+        if (!item || typeof item.code !== "string" || seen.has(item.code))
+            continue;
+        seen.add(item.code);
+        const widget = byCode.get(item.code);
+        const size = widget && !widget.sizes.includes(item.size) ? widget.sizes[0] : item.size;
+        items.push({ code: item.code, size });
+    }
+    return items;
+}
+/** The items of a layout the board draws now, in order. */
+export function drawnItems(layout, drawable) {
+    return layout.filter(item => drawable.has(item.code));
+}
+/**
+ * A layout to save after an edit of the drawn items: the edited items in their new order, and every item that was not
+ * drawn (hidden now) back in its place - after the drawn item it followed, or at the start. One whose drawn neighbour
+ * was removed follows the drawn item before that one. Nothing hidden is lost by a save.
+ */
+export function mergeHidden(full, edited, drawable) {
+    const editedCodes = new Set(edited.map(item => item.code));
+    // Each hidden item and the drawn items before it, nearest first: it follows the nearest that is still there.
+    const anchored = new Map();
+    const before = [];
+    for (const item of full) {
+        if (drawable.has(item.code)) {
+            before.push(item.code);
+            continue;
+        }
+        if (editedCodes.has(item.code))
+            continue;
+        let anchor = null;
+        for (let index = before.length - 1; index >= 0; index--)
+            if (editedCodes.has(before[index])) {
+                anchor = before[index];
+                break;
+            }
+        anchored.set(anchor, [...(anchored.get(anchor) ?? []), item]);
+    }
+    const result = [...(anchored.get(null) ?? [])];
+    for (const item of edited) {
+        result.push(item);
+        result.push(...(anchored.get(item.code) ?? []));
+    }
+    return result;
+}
+/** The list with the item at `from` moved to `to` (both clamped). */
+export function moveItem(list, from, to) {
+    const result = [...list];
+    if (from < 0 || from >= result.length)
+        return result;
+    const target = Math.max(0, Math.min(result.length - 1, to));
+    const [item] = result.splice(from, 1);
+    result.splice(target, 0, item);
+    return result;
+}
+/** Whether two layouts are the same widgets, sizes and order. */
+export function sameLayout(a, b) {
+    const left = a ?? [];
+    const right = b ?? [];
+    return left.length === right.length && left.every((item, index) => item.code === right[index].code && item.size === right[index].size);
+}
+/**
+ * The widget an arrow key up or down moves to: in the nearest row above (or below) the one at `index`, the one whose
+ * middle is nearest across. `null` when there is no row that way. Rows are told apart by their tops.
+ */
+export function neighbourInColumn(rects, index, direction) {
+    const from = rects[index];
+    if (!from)
+        return null;
+    const middle = from.left + from.width / 2;
+    let rowTop = null;
+    for (const rect of rects) {
+        const wanted = direction === "up" ? rect.top < from.top - 1 : rect.top > from.top + 1;
+        if (!wanted)
+            continue;
+        if (rowTop === null || (direction === "up" ? rect.top > rowTop : rect.top < rowTop))
+            rowTop = rect.top;
+    }
+    if (rowTop === null)
+        return null;
+    let best = null;
+    let bestDistance = Infinity;
+    rects.forEach((rect, at) => {
+        if (Math.abs(rect.top - rowTop) > 1)
+            return;
+        const distance = Math.abs(rect.left + rect.width / 2 - middle);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = at;
+        }
+    });
+    return best;
+}
+/** The widget under a point, leaving out `skip` (the one being dragged). `null` over a gap. */
+export function widgetAtPoint(rects, x, y, skip) {
+    for (let index = 0; index < rects.length; index++) {
+        if (index === skip)
+            continue;
+        const rect = rects[index];
+        if (x >= rect.left && x < rect.left + rect.width && y >= rect.top && y < rect.top + rect.height)
+            return index;
+    }
+    return null;
+}
+/**
+ * The Add list: every widget the place may draw now, grouped by module - the place's own module first, the rest in the
+ * order the app declared them - each marked when it is on the board already.
+ */
+export function addableWidgets(drawable, layout, placeModule) {
+    const onBoard = new Set(layout.map(item => item.code));
+    const groups = new Map();
+    if (placeModule)
+        groups.set(placeModule, { module: placeModule, widgets: [] });
+    for (const widget of drawable.values()) {
+        const group = groups.get(widget.module) ?? {
+            module: widget.module,
+            widgets: [],
+        };
+        group.widgets.push({ widget, onBoard: onBoard.has(widget.code) });
+        groups.set(widget.module, group);
+    }
+    return [...groups.values()].filter(group => group.widgets.length > 0);
+}
+/** Whether a widget's data is nothing to show: its own `isEmpty`, else `null`, `undefined` or an empty list. */
+export function widgetDataEmpty(widget, data) {
+    if (widget.isEmpty)
+        return widget.isEmpty(data);
+    return data === null || data === undefined || (Array.isArray(data) && data.length === 0);
+}
+/** Whether a widget reads data at all (`load` or `batch`). */
+export const widgetNeedsData = (widget) => Boolean(widget.load || widget.batch);
+/**
+ * One cache and one queue for a board's widgets: every batched widget asked while one draw runs goes to its module in
+ * one call (`loadModule(module, codes)`), each answer is kept for the page's life (or the widget's `refresh` seconds),
+ * and a widget asked twice while its call is on its way waits for that call.
+ */
+export function createWidgetBatcher(loadModule, options = {}) {
+    const now = options.now ?? Date.now;
+    const defer = options.defer ?? (flush => void setTimeout(flush, 0));
+    const cache = new Map();
+    const inFlight = new Map();
+    let pending = new Map();
+    let scheduled = false;
+    let calls = 0;
+    function keep(code, data) {
+        cache.set(code, { data, at: now() });
+    }
+    function flush() {
+        scheduled = false;
+        const batches = pending;
+        pending = new Map();
+        for (const [module, waiting] of batches) {
+            const codes = [...new Set(waiting.flatMap(one => one.widget.batch?.codes ?? [one.widget.code]))];
+            calls++;
+            let call;
+            try {
+                call = loadModule ? Promise.resolve(loadModule(module, codes)) : Promise.reject(new Error(`No loadModule for ${module}.`));
+            }
+            catch (error) {
+                call = Promise.reject(error);
+            }
+            call.then(answer => {
+                for (const one of waiting) {
+                    const own = one.widget.batch?.codes ?? [one.widget.code];
+                    const parts = {};
+                    for (const code of own)
+                        if (answer && Object.prototype.hasOwnProperty.call(answer, code))
+                            parts[code] = answer[code];
+                    let data;
+                    try {
+                        data = one.widget.batch?.pick ? one.widget.batch.pick(parts) : own.length === 1 ? parts[own[0]] : parts;
+                    }
+                    catch (error) {
+                        one.reject(error);
+                        continue;
+                    }
+                    keep(one.widget.code, data);
+                    one.resolve(data);
+                }
+            }, error => waiting.forEach(one => one.reject(error)));
+        }
+    }
+    const batcher = {
+        request(widget, context, requestOptions = {}) {
+            if (!requestOptions.force && batcher.isFresh(widget))
+                return Promise.resolve(cache.get(widget.code).data);
+            const running = inFlight.get(widget.code);
+            if (running)
+                return running;
+            let promise;
+            if (widget.batch) {
+                promise = new Promise((resolve, reject) => {
+                    const module = widget.batch.module;
+                    pending.set(module, [...(pending.get(module) ?? []), { widget, resolve, reject }]);
+                    if (!scheduled) {
+                        scheduled = true;
+                        defer(flush);
+                    }
+                });
+            }
+            else if (widget.load) {
+                calls++;
+                promise = Promise.resolve()
+                    .then(() => widget.load(context))
+                    .then(data => {
+                    keep(widget.code, data);
+                    return data;
+                });
+            }
+            else {
+                keep(widget.code, undefined);
+                return Promise.resolve(undefined);
+            }
+            inFlight.set(widget.code, promise);
+            const done = () => {
+                if (inFlight.get(widget.code) === promise)
+                    inFlight.delete(widget.code);
+            };
+            promise.then(done, done);
+            return promise;
+        },
+        cached: code => cache.get(code),
+        prime: (code, data) => keep(code, data),
+        isFresh(widget) {
+            const kept = cache.get(widget.code);
+            if (!kept)
+                return false;
+            return widget.refresh === undefined || widget.refresh <= 0 || now() - kept.at < widget.refresh * 1000;
+        },
+        clear(codes) {
+            if (!codes)
+                cache.clear();
+            else
+                codes.forEach(code => cache.delete(code));
+        },
+        get calls() {
+            return calls;
+        },
+    };
+    return batcher;
+}
+/** At most this many days of one mark are drawn, so a broken range never fills a year of cells. */
+const MAX_MARK_DAYS = 366;
+/** Each day's marks, by ISO date: a mark over several days is on each of them. A mark with a broken date is left out. */
+export function marksByDay(marks) {
+    const days = new Map();
+    for (const mark of marks) {
+        if (!isIsoDate(mark.date))
+            continue;
+        const last = mark.until && isIsoDate(mark.until) && mark.until > mark.date ? mark.until : mark.date;
+        let day = mark.date;
+        for (let count = 0; day <= last && count < MAX_MARK_DAYS; count++, day = addDays(day, 1))
+            days.set(day, [...(days.get(day) ?? []), mark]);
+    }
+    return days;
+}

package/dist/Helpers/DomainCards.d.ts

@@ -0,0 +1,140 @@
+import type { ChatDomainInfo, ChatDomainValue, ChatId } from "../Interfaces/ChatInterfaces.ts";
+import type { DatePreferences } from "../Interfaces/DateInterfaces.ts";
+import type { DomainCardContext, DomainCardDefinition, DomainCardField, DomainCardParams, DomainCardShape, DomainCardSnapshot, DomainCardValueKind } from "../Interfaces/DomainInterfaces.ts";
+/** How long a card's answer is kept for every card of the page that draws the same record, in milliseconds. */
+export declare const DOMAIN_CARD_LIFETIME = 30000;
+/**
+ * A kind's card, with `view` typed by what `load` answers.
+ *
+ * @example
+ * defineChatDomains([{ domain: EDomainTypes.LeaveRequest, key: "leave-request", label: "Leave request", card: domainCard({
+ *   load: (id, signal) => api.get<LeaveRequestCard>(REQUEST_CARD.leave(id), { signal }),
+ *   view: leave => ({ title: `${leave.leaveTypeName} · ${formatDays(leave.days)}`, code: leave.requestCode, ... }),
+ * }) }]);
+ */
+export declare function domainCard<TData>(definition: DomainCardDefinition<TData>): DomainCardDefinition<TData>;
+/** A kind's registered row and its card, or `undefined` when the app gave it none. */
+export declare function domainCardOf(domainType: ChatDomainValue): {
+    info: ChatDomainInfo<ChatDomainValue>;
+    card: DomainCardDefinition;
+} | undefined;
+/** The key a record's answer is kept under: its kind, its id, and who reads it (the same record reads otherwise for another). */
+export declare function domainCardKey(domainType: ChatDomainValue, id: ChatId, viewer?: ChatId | null): string;
+/** The start of every key of one record (every reader's), or of every record of a kind without an id. */
+export declare function domainCardRecordPrefix(domainType: ChatDomainValue, id?: ChatId): string;
+/** One wait for a read: its answer, and a way to stop waiting (the last to stop aborts it). */
+export interface DomainCardReading<T> {
+    promise: Promise<T>;
+    leave(): void;
+}
+/**
+ * Reads shared by every card on the page: one read of a record at a time, its answer kept for a lifetime, a failure not
+ * kept. A read nobody waits for any more is aborted.
+ */
+export declare class DomainCardReads {
+    private entries;
+    private now;
+    constructor(now?: () => number);
+    /** The answer kept under `key` while it is younger than `lifetime` and was read from a read started at or after `since`. */
+    peek<T>(key: string, lifetime?: number, since?: number): T | undefined;
+    /**
+     * The answer under `key`: a read on its way that started at or after `since`, else a kept fresh one, else a new read by
+     * `load`. `since` is the moment the record was seen to change: what was read before it does not answer.
+     */
+    read<T>(key: string, load: (signal: AbortSignal) => Promise<T>, options?: {
+        lifetime?: number;
+        since?: number;
+    }): DomainCardReading<T>;
+    private wait;
+    /**
+     * Drops what is kept or on its way under keys that start with `prefix` (every key when none); a read on its way still
+     * answers its waiters. `keptOnly` leaves the reads on their way, so cards reading again for the same change still share one.
+     */
+    drop(prefix?: string, keptOnly?: boolean): number;
+    /** Answers kept and reads on their way. */
+    get size(): number;
+}
+/** The reads every card of the page shares. */
+export declare const domainCardReads: DomainCardReads;
+/** A read the page called off (the card closed): not a failure to show. */
+export declare function isDomainCardAbort(error: unknown): boolean;
+/** Whether a failure means the reader may not open the record, or it is not there for them: 403 and 404 alike. */
+export declare function isDomainCardRefusal(error: unknown): boolean;
+/** What a run reads and how. */
+export interface DomainCardRunOptions<TData> {
+    domainType: ChatDomainValue;
+    id: ChatId;
+    /** Who reads: part of the key, and told to `load`. */
+    viewer?: ChatId | null;
+    load: (signal: AbortSignal) => Promise<TData>;
+    /** Default 30,000. */
+    lifetime?: number;
+    /** Default: the page's `domainCardReads`. */
+    reads?: DomainCardReads;
+    now?: () => number;
+}
+/**
+ * One card's read: loading, then the record, a refusal or a failure; read again when the record changes (the card stays
+ * on screen meanwhile, and says so when the record turned out different); tried again on Retry. Subscribe to draw it.
+ */
+export declare class DomainCardRun<TData = unknown> {
+    readonly domainType: ChatDomainValue;
+    readonly id: ChatId;
+    readonly key: string;
+    private options;
+    private reads;
+    private now;
+    private snapshot;
+    private listeners;
+    private reading;
+    private round;
+    constructor(options: DomainCardRunOptions<TData>);
+    private get lifetime();
+    readonly subscribe: (listener: () => void) => (() => void);
+    readonly getSnapshot: () => DomainCardSnapshot<TData>;
+    private set;
+    /** The card is drawn: reads, unless it already shows a kept answer. */
+    start(): void;
+    /** The card is gone: stops waiting (the read is aborted when no other card waits for it). */
+    stop(): void;
+    /**
+     * The record changed: reads it again, from a read started now. The card on screen stays until the answer lands, and
+     * what other readers kept of the record is forgotten, since it changed for them too.
+     */
+    reload(): void;
+    /** After a failure: reads once more. */
+    retry(): void;
+    private read;
+}
+/**
+ * A record changed (the page approved it, a message said so): every card drawing it reads it again, and no answer kept
+ * from before is handed out. Without an id, every record of the kind.
+ */
+export declare function refreshDomainCards(domainType: ChatDomainValue, id?: ChatId, reads?: DomainCardReads): number;
+/** The kind's name inside a sentence: "Leave request" reads "leave request"; "HR letter" keeps its capitals. */
+export declare function domainCardNoun(kind?: string | null): string;
+/** What a reader the record's module refused reads: the same for "not yours" and "not there", so a stranger learns nothing. */
+export declare function domainCardRefusedText(kind?: string | null): string;
+/** What a failed read says, beside Try again. */
+export declare function domainCardFailedText(kind?: string | null): string;
+/** What a card's values are written with: the reader's date settings and zone, number locale and currency. */
+export interface DomainCardValueOptions {
+    preferences?: Partial<DatePreferences>;
+    timeZone?: string | null;
+    locale?: string;
+    currency?: string | null;
+}
+/** A value written by its kind, or "" when it is missing. A value its kind cannot read is written as it is. */
+export declare function domainCardValueText(value: string | number | null | undefined, kind?: DomainCardValueKind, options?: DomainCardValueOptions): string;
+/** The fields a card draws: the ones with a value, and the ones that say what stands in for a missing one. */
+export declare function domainCardFields(params: Pick<DomainCardParams, "fields">): DomainCardField[];
+/** What a placeholder holds when a kind gave nothing and none of its cards has loaded yet: a title, a state, four fields. */
+export declare const DEFAULT_DOMAIN_CARD_SHAPE: DomainCardShape;
+/** How many of each part a card drew. */
+export declare function domainCardShape(params: DomainCardParams): DomainCardShape;
+/** Keeps a kind's last drawn shape, so its next placeholder holds the same parts. */
+export declare function rememberDomainCardShape(domainType: ChatDomainValue, shape: DomainCardShape): void;
+/** The shape a kind's placeholder holds: its last card's, else what its card says, else the default. */
+export declare function heldDomainCardShape(domainType: ChatDomainValue, card?: Pick<DomainCardDefinition, "held"> | null): DomainCardShape;
+/** What `load`, `view` and `extra` are told about a record. */
+export declare function domainCardContext(domainType: ChatDomainValue, id: ChatId, extra?: Omit<DomainCardContext, "domainType" | "id">): DomainCardContext;