@fieldia/core 0.32.0 → 0.33.0

package/src/lib/format/loading-schema.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageLoadingSchema = void 0;
+exports.loadingOptionIssues = loadingOptionIssues;
+const z = require("zod");
+const jitless_1 = require("./jitless");
+const loading_1 = require("./loading");
+// zod compiles no code for these schemas: a strict Content-Security-Policy refuses it (jitless.ts).
+(0, jitless_1.makeSchemasJitless)();
+/*
+ * The shape of `PageLoading` (loading.ts), where pages are made and checked (`validatePage`, the JSON Schema, the
+ * designer): an app showing forms never carries it.
+ */
+/** A length of time in whole milliseconds, up to ten minutes. */
+const ms = z.int().min(0).max(600000);
+exports.PageLoadingSchema = z
+    .strictObject({
+    first: z.enum(loading_1.LOADING_TECHNIQUES.first).optional(),
+    refresh: z.enum(loading_1.LOADING_TECHNIQUES.refresh).optional(),
+    more: z.enum(loading_1.LOADING_TECHNIQUES.more).optional(),
+    search: z.enum(loading_1.LOADING_TECHNIQUES.search).optional(),
+    action: z.enum(loading_1.LOADING_TECHNIQUES.action).optional(),
+    skeleton: z.enum(loading_1.LOADING_VARIANTS.skeleton).optional(),
+    spinner: z.enum(loading_1.LOADING_VARIANTS.spinner).optional(),
+    progress: z.enum(loading_1.LOADING_VARIANTS.progress).optional(),
+    delay: ms.max(10000).optional(),
+    minShown: ms.max(10000).optional(),
+    slowAfter: ms.optional(),
+    timeout: ms.min(1).optional(),
+    error: z.enum(loading_1.LOADING_ERRORS).optional(),
+})
+    .superRefine((loading, context) => {
+    // A wait that ends before anything could be said of it fails every slow answer unseen.
+    if (loading.timeout !== undefined && loading.timeout <= (loading.delay ?? loading_1.LOADING_DEFAULTS.delay)) {
+        context.addIssue({ code: 'custom', path: ['timeout'], message: `a timeout ends the wait as failed: make it longer than the delay before a loader shows (${loading.delay ?? loading_1.LOADING_DEFAULTS.delay} ms)` });
+    }
+    if (loading.timeout !== undefined && loading.slowAfter !== undefined && loading.slowAfter >= loading.timeout) {
+        context.addIssue({ code: 'custom', path: ['slowAfter'], message: `"Still loading…" is said before the wait ends: make slowAfter shorter than the timeout (${loading.timeout} ms)` });
+    }
+})
+    .meta({ id: 'PageLoading' });
+/** The issues of a field's `options.loading`, each at its path under `options`. */
+function loadingOptionIssues(node) {
+    const loading = node.options?.['loading'];
+    if (loading === undefined)
+        return [];
+    return (exports.PageLoadingSchema.safeParse(loading).error?.issues ?? []).map((issue) => ({ message: issue.message, path: ['options', 'loading', ...issue.path] }));
+}
+//# sourceMappingURL=loading-schema.js.map

package/src/lib/format/loading-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-schema.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/loading-schema.ts"],"names":[],"mappings":"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"}

package/src/lib/format/loading-schema.mjs

@@ -0,0 +1,45 @@
+import * as z from 'zod';
+import { makeSchemasJitless } from './jitless.mjs';
+import { LOADING_DEFAULTS, LOADING_ERRORS, LOADING_TECHNIQUES, LOADING_VARIANTS } from './loading.mjs';
+// zod compiles no code for these schemas: a strict Content-Security-Policy refuses it (jitless.ts).
+makeSchemasJitless();
+/*
+ * The shape of `PageLoading` (loading.ts), where pages are made and checked (`validatePage`, the JSON Schema, the
+ * designer): an app showing forms never carries it.
+ */
+/** A length of time in whole milliseconds, up to ten minutes. */
+const ms = z.int().min(0).max(600000);
+export const PageLoadingSchema = z
+    .strictObject({
+    first: z.enum(LOADING_TECHNIQUES.first).optional(),
+    refresh: z.enum(LOADING_TECHNIQUES.refresh).optional(),
+    more: z.enum(LOADING_TECHNIQUES.more).optional(),
+    search: z.enum(LOADING_TECHNIQUES.search).optional(),
+    action: z.enum(LOADING_TECHNIQUES.action).optional(),
+    skeleton: z.enum(LOADING_VARIANTS.skeleton).optional(),
+    spinner: z.enum(LOADING_VARIANTS.spinner).optional(),
+    progress: z.enum(LOADING_VARIANTS.progress).optional(),
+    delay: ms.max(10000).optional(),
+    minShown: ms.max(10000).optional(),
+    slowAfter: ms.optional(),
+    timeout: ms.min(1).optional(),
+    error: z.enum(LOADING_ERRORS).optional(),
+})
+    .superRefine((loading, context) => {
+    // A wait that ends before anything could be said of it fails every slow answer unseen.
+    if (loading.timeout !== undefined && loading.timeout <= (loading.delay ?? LOADING_DEFAULTS.delay)) {
+        context.addIssue({ code: 'custom', path: ['timeout'], message: `a timeout ends the wait as failed: make it longer than the delay before a loader shows (${loading.delay ?? LOADING_DEFAULTS.delay} ms)` });
+    }
+    if (loading.timeout !== undefined && loading.slowAfter !== undefined && loading.slowAfter >= loading.timeout) {
+        context.addIssue({ code: 'custom', path: ['slowAfter'], message: `"Still loading…" is said before the wait ends: make slowAfter shorter than the timeout (${loading.timeout} ms)` });
+    }
+})
+    .meta({ id: 'PageLoading' });
+/** The issues of a field's `options.loading`, each at its path under `options`. */
+export function loadingOptionIssues(node) {
+    const loading = node.options?.['loading'];
+    if (loading === undefined)
+        return [];
+    return (PageLoadingSchema.safeParse(loading).error?.issues ?? []).map((issue) => ({ message: issue.message, path: ['options', 'loading', ...issue.path] }));
+}
+//# sourceMappingURL=loading-schema.mjs.map

package/src/lib/format/loading-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-schema.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/loading-schema.ts"],"names":[],"mappings":"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"}

package/src/lib/format/loading.d.mts

@@ -0,0 +1,77 @@
+/**
+ * How a page looks while it waits for an answer (docs/plans/loading.md): at each of its moments, a way to show it, its
+ * looks and its timing, and what a failure shows. Set by the app for every page (the viewer's `loading`), by the page
+ * (`Page.loading`), and by a part of it — a list's, a related list's or a map's `loading`, a field's `options.loading` —
+ * the most specific winning, setting by setting; what nobody sets is `LOADING_DEFAULTS`.
+ *
+ * - `first`: a form, a list, a card, a map, a related list drawn for the first time.
+ * - `refresh`: a list or a part asked again — a search, a filter, an order, a record reloaded; a page turned (a list's
+ *   pager, a related list's), a calendar's next week or month: whatever replaces what is shown.
+ * - `more`: rows put under those shown — endless scroll, Show more, a tree's children.
+ * - `search`: a link's or a dropdown's suggestions, choices from the app's lists, a filter's values.
+ * - `action`: a save, a send, a button's steps, a delete, an export.
+ *
+ *   { "loading": { "first": "spinner", "refresh": "dim", "skeleton": "pulse", "delay": 250, "timeout": 20000 } }
+ */
+export declare const LOADING_MOMENTS: readonly ["first", "refresh", "more", "search", "action"];
+export type LoadingMoment = (typeof LOADING_MOMENTS)[number];
+/** The ways each moment can be shown, its default first. `custom` is drawn by the app's own function (the viewer's `loading.custom`). */
+export declare const LOADING_TECHNIQUES: {
+    readonly first: readonly ["skeleton", "spinner", "progress", "text", "none", "custom"];
+    readonly refresh: readonly ["keep", "dim", "skeleton", "spinner", "none", "custom"];
+    readonly more: readonly ["row", "spinner", "skeleton", "none", "custom"];
+    readonly search: readonly ["inline", "spinner", "none", "custom"];
+    readonly action: readonly ["button", "bar", "overlay", "none", "custom"];
+};
+export type LoadingTechnique<M extends LoadingMoment = LoadingMoment> = (typeof LOADING_TECHNIQUES)[M][number];
+/** The looks a technique comes in: a skeleton's, a spinner's, a progress bar's — the default first. */
+export declare const LOADING_VARIANTS: {
+    readonly skeleton: readonly ["shimmer", "pulse", "static"];
+    readonly spinner: readonly ["ring", "dots"];
+    readonly progress: readonly ["top", "inline"];
+};
+/** What a failed wait shows: words and Retry in its place, a toast with Retry, or the app's own. */
+export declare const LOADING_ERRORS: readonly ["inline", "toast", "custom"];
+export interface PageLoading {
+    /** A form, a list, a card, a map drawn for the first time: `skeleton` unless said. */
+    first?: LoadingTechnique<'first'>;
+    /** A list or a part asked again: `keep` — what is shown stays, a thin bar over it — unless said. */
+    refresh?: LoadingTechnique<'refresh'>;
+    /** Rows under those shown: `row` — "Loading more…" where they will come — unless said. */
+    more?: LoadingTechnique<'more'>;
+    /** Suggestions and choices asked for as a person types or opens a list: `inline` — "Searching…" in the list — unless said. */
+    search?: LoadingTechnique<'search'>;
+    /** A save, a send, a button's steps: `button` — the pressed button busy — unless said. */
+    action?: LoadingTechnique<'action'>;
+    /** How a skeleton moves: a band of light passing over it (`shimmer`), fading in and out (`pulse`), or not at all. */
+    skeleton?: (typeof LOADING_VARIANTS.skeleton)[number];
+    /** A spinner: a turning `ring`, or three `dots`. */
+    spinner?: (typeof LOADING_VARIANTS.spinner)[number];
+    /** A progress bar: along the top of what waits, or across its middle (`inline`). */
+    progress?: (typeof LOADING_VARIANTS.progress)[number];
+    /** Milliseconds before anything is drawn: a quicker answer shows no loader at all. 150 unless said. */
+    delay?: number;
+    /** Milliseconds a loader stays once drawn, so it never flickers off. 300 unless said. */
+    minShown?: number;
+    /** Milliseconds after which "Still loading…" is said. 5000 unless said. */
+    slowAfter?: number;
+    /** Milliseconds after which the wait ends as failed, with Retry. None unless said. */
+    timeout?: number;
+    /** What a failed wait shows: `inline` (words and Retry in its place) unless said, a `toast`, or the app's `custom`. */
+    error?: (typeof LOADING_ERRORS)[number];
+}
+/** What nobody set: the coordinator's proposal, 23 Oct (0.33). */
+export declare const LOADING_DEFAULTS: {
+    readonly first: "skeleton";
+    readonly refresh: "keep";
+    readonly more: "row";
+    readonly search: "inline";
+    readonly action: "button";
+    readonly skeleton: "shimmer";
+    readonly spinner: "ring";
+    readonly progress: "top";
+    readonly delay: 150;
+    readonly minShown: 300;
+    readonly slowAfter: 5000;
+    readonly error: "inline";
+};

package/src/lib/format/loading.d.ts

@@ -0,0 +1,77 @@
+/**
+ * How a page looks while it waits for an answer (docs/plans/loading.md): at each of its moments, a way to show it, its
+ * looks and its timing, and what a failure shows. Set by the app for every page (the viewer's `loading`), by the page
+ * (`Page.loading`), and by a part of it — a list's, a related list's or a map's `loading`, a field's `options.loading` —
+ * the most specific winning, setting by setting; what nobody sets is `LOADING_DEFAULTS`.
+ *
+ * - `first`: a form, a list, a card, a map, a related list drawn for the first time.
+ * - `refresh`: a list or a part asked again — a search, a filter, an order, a record reloaded; a page turned (a list's
+ *   pager, a related list's), a calendar's next week or month: whatever replaces what is shown.
+ * - `more`: rows put under those shown — endless scroll, Show more, a tree's children.
+ * - `search`: a link's or a dropdown's suggestions, choices from the app's lists, a filter's values.
+ * - `action`: a save, a send, a button's steps, a delete, an export.
+ *
+ *   { "loading": { "first": "spinner", "refresh": "dim", "skeleton": "pulse", "delay": 250, "timeout": 20000 } }
+ */
+export declare const LOADING_MOMENTS: readonly ["first", "refresh", "more", "search", "action"];
+export type LoadingMoment = (typeof LOADING_MOMENTS)[number];
+/** The ways each moment can be shown, its default first. `custom` is drawn by the app's own function (the viewer's `loading.custom`). */
+export declare const LOADING_TECHNIQUES: {
+    readonly first: readonly ["skeleton", "spinner", "progress", "text", "none", "custom"];
+    readonly refresh: readonly ["keep", "dim", "skeleton", "spinner", "none", "custom"];
+    readonly more: readonly ["row", "spinner", "skeleton", "none", "custom"];
+    readonly search: readonly ["inline", "spinner", "none", "custom"];
+    readonly action: readonly ["button", "bar", "overlay", "none", "custom"];
+};
+export type LoadingTechnique<M extends LoadingMoment = LoadingMoment> = (typeof LOADING_TECHNIQUES)[M][number];
+/** The looks a technique comes in: a skeleton's, a spinner's, a progress bar's — the default first. */
+export declare const LOADING_VARIANTS: {
+    readonly skeleton: readonly ["shimmer", "pulse", "static"];
+    readonly spinner: readonly ["ring", "dots"];
+    readonly progress: readonly ["top", "inline"];
+};
+/** What a failed wait shows: words and Retry in its place, a toast with Retry, or the app's own. */
+export declare const LOADING_ERRORS: readonly ["inline", "toast", "custom"];
+export interface PageLoading {
+    /** A form, a list, a card, a map drawn for the first time: `skeleton` unless said. */
+    first?: LoadingTechnique<'first'>;
+    /** A list or a part asked again: `keep` — what is shown stays, a thin bar over it — unless said. */
+    refresh?: LoadingTechnique<'refresh'>;
+    /** Rows under those shown: `row` — "Loading more…" where they will come — unless said. */
+    more?: LoadingTechnique<'more'>;
+    /** Suggestions and choices asked for as a person types or opens a list: `inline` — "Searching…" in the list — unless said. */
+    search?: LoadingTechnique<'search'>;
+    /** A save, a send, a button's steps: `button` — the pressed button busy — unless said. */
+    action?: LoadingTechnique<'action'>;
+    /** How a skeleton moves: a band of light passing over it (`shimmer`), fading in and out (`pulse`), or not at all. */
+    skeleton?: (typeof LOADING_VARIANTS.skeleton)[number];
+    /** A spinner: a turning `ring`, or three `dots`. */
+    spinner?: (typeof LOADING_VARIANTS.spinner)[number];
+    /** A progress bar: along the top of what waits, or across its middle (`inline`). */
+    progress?: (typeof LOADING_VARIANTS.progress)[number];
+    /** Milliseconds before anything is drawn: a quicker answer shows no loader at all. 150 unless said. */
+    delay?: number;
+    /** Milliseconds a loader stays once drawn, so it never flickers off. 300 unless said. */
+    minShown?: number;
+    /** Milliseconds after which "Still loading…" is said. 5000 unless said. */
+    slowAfter?: number;
+    /** Milliseconds after which the wait ends as failed, with Retry. None unless said. */
+    timeout?: number;
+    /** What a failed wait shows: `inline` (words and Retry in its place) unless said, a `toast`, or the app's `custom`. */
+    error?: (typeof LOADING_ERRORS)[number];
+}
+/** What nobody set: the coordinator's proposal, 23 Oct (0.33). */
+export declare const LOADING_DEFAULTS: {
+    readonly first: "skeleton";
+    readonly refresh: "keep";
+    readonly more: "row";
+    readonly search: "inline";
+    readonly action: "button";
+    readonly skeleton: "shimmer";
+    readonly spinner: "ring";
+    readonly progress: "top";
+    readonly delay: 150;
+    readonly minShown: 300;
+    readonly slowAfter: 5000;
+    readonly error: "inline";
+};

package/src/lib/format/loading.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOADING_DEFAULTS = exports.LOADING_ERRORS = exports.LOADING_VARIANTS = exports.LOADING_TECHNIQUES = exports.LOADING_MOMENTS = void 0;
+/**
+ * How a page looks while it waits for an answer (docs/plans/loading.md): at each of its moments, a way to show it, its
+ * looks and its timing, and what a failure shows. Set by the app for every page (the viewer's `loading`), by the page
+ * (`Page.loading`), and by a part of it — a list's, a related list's or a map's `loading`, a field's `options.loading` —
+ * the most specific winning, setting by setting; what nobody sets is `LOADING_DEFAULTS`.
+ *
+ * - `first`: a form, a list, a card, a map, a related list drawn for the first time.
+ * - `refresh`: a list or a part asked again — a search, a filter, an order, a record reloaded; a page turned (a list's
+ *   pager, a related list's), a calendar's next week or month: whatever replaces what is shown.
+ * - `more`: rows put under those shown — endless scroll, Show more, a tree's children.
+ * - `search`: a link's or a dropdown's suggestions, choices from the app's lists, a filter's values.
+ * - `action`: a save, a send, a button's steps, a delete, an export.
+ *
+ *   { "loading": { "first": "spinner", "refresh": "dim", "skeleton": "pulse", "delay": 250, "timeout": 20000 } }
+ */
+exports.LOADING_MOMENTS = ['first', 'refresh', 'more', 'search', 'action'];
+/** The ways each moment can be shown, its default first. `custom` is drawn by the app's own function (the viewer's `loading.custom`). */
+exports.LOADING_TECHNIQUES = {
+    first: ['skeleton', 'spinner', 'progress', 'text', 'none', 'custom'],
+    refresh: ['keep', 'dim', 'skeleton', 'spinner', 'none', 'custom'],
+    more: ['row', 'spinner', 'skeleton', 'none', 'custom'],
+    search: ['inline', 'spinner', 'none', 'custom'],
+    action: ['button', 'bar', 'overlay', 'none', 'custom'],
+};
+/** The looks a technique comes in: a skeleton's, a spinner's, a progress bar's — the default first. */
+exports.LOADING_VARIANTS = {
+    skeleton: ['shimmer', 'pulse', 'static'],
+    spinner: ['ring', 'dots'],
+    progress: ['top', 'inline'],
+};
+/** What a failed wait shows: words and Retry in its place, a toast with Retry, or the app's own. */
+exports.LOADING_ERRORS = ['inline', 'toast', 'custom'];
+/** What nobody set: the coordinator's proposal, 23 Oct (0.33). */
+exports.LOADING_DEFAULTS = {
+    first: 'skeleton',
+    refresh: 'keep',
+    more: 'row',
+    search: 'inline',
+    action: 'button',
+    skeleton: 'shimmer',
+    spinner: 'ring',
+    progress: 'top',
+    delay: 150,
+    minShown: 300,
+    slowAfter: 5000,
+    error: 'inline',
+};
+//# sourceMappingURL=loading.js.map

package/src/lib/format/loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/loading.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACU,QAAA,eAAe,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAGzF,yIAAyI;AAC5H,QAAA,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;IACpE,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;IACjE,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC;IACtD,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC/C,MAAM,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;CAC9C,CAAC;AAGX,uGAAuG;AAC1F,QAAA,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC;IACxC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEX,oGAAoG;AACvF,QAAA,cAAc,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AA+BrE,kEAAkE;AACrD,QAAA,gBAAgB,GAAG;IAC9B,KAAK,EAAE,UAAU;IACjB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,KAAK;IACX,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,SAAS;IACnB,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,KAAK;IACf,KAAK,EAAE,GAAG;IACV,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,IAAI;IACf,KAAK,EAAE,QAAQ;CACe,CAAC"}

package/src/lib/format/loading.mjs

@@ -0,0 +1,48 @@
+/**
+ * How a page looks while it waits for an answer (docs/plans/loading.md): at each of its moments, a way to show it, its
+ * looks and its timing, and what a failure shows. Set by the app for every page (the viewer's `loading`), by the page
+ * (`Page.loading`), and by a part of it — a list's, a related list's or a map's `loading`, a field's `options.loading` —
+ * the most specific winning, setting by setting; what nobody sets is `LOADING_DEFAULTS`.
+ *
+ * - `first`: a form, a list, a card, a map, a related list drawn for the first time.
+ * - `refresh`: a list or a part asked again — a search, a filter, an order, a record reloaded; a page turned (a list's
+ *   pager, a related list's), a calendar's next week or month: whatever replaces what is shown.
+ * - `more`: rows put under those shown — endless scroll, Show more, a tree's children.
+ * - `search`: a link's or a dropdown's suggestions, choices from the app's lists, a filter's values.
+ * - `action`: a save, a send, a button's steps, a delete, an export.
+ *
+ *   { "loading": { "first": "spinner", "refresh": "dim", "skeleton": "pulse", "delay": 250, "timeout": 20000 } }
+ */
+export const LOADING_MOMENTS = ['first', 'refresh', 'more', 'search', 'action'];
+/** The ways each moment can be shown, its default first. `custom` is drawn by the app's own function (the viewer's `loading.custom`). */
+export const LOADING_TECHNIQUES = {
+    first: ['skeleton', 'spinner', 'progress', 'text', 'none', 'custom'],
+    refresh: ['keep', 'dim', 'skeleton', 'spinner', 'none', 'custom'],
+    more: ['row', 'spinner', 'skeleton', 'none', 'custom'],
+    search: ['inline', 'spinner', 'none', 'custom'],
+    action: ['button', 'bar', 'overlay', 'none', 'custom'],
+};
+/** The looks a technique comes in: a skeleton's, a spinner's, a progress bar's — the default first. */
+export const LOADING_VARIANTS = {
+    skeleton: ['shimmer', 'pulse', 'static'],
+    spinner: ['ring', 'dots'],
+    progress: ['top', 'inline'],
+};
+/** What a failed wait shows: words and Retry in its place, a toast with Retry, or the app's own. */
+export const LOADING_ERRORS = ['inline', 'toast', 'custom'];
+/** What nobody set: the coordinator's proposal, 23 Oct (0.33). */
+export const LOADING_DEFAULTS = {
+    first: 'skeleton',
+    refresh: 'keep',
+    more: 'row',
+    search: 'inline',
+    action: 'button',
+    skeleton: 'shimmer',
+    spinner: 'ring',
+    progress: 'top',
+    delay: 150,
+    minShown: 300,
+    slowAfter: 5000,
+    error: 'inline',
+};
+//# sourceMappingURL=loading.mjs.map

package/src/lib/format/loading.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/loading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAGzF,yIAAyI;AACzI,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;IACpE,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;IACjE,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC;IACtD,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC/C,MAAM,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;CAC9C,CAAC;AAGX,uGAAuG;AACvG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC;IACxC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEX,oGAAoG;AACpG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AA+BrE,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,UAAU;IACjB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,KAAK;IACX,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,SAAS;IACnB,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,KAAK;IACf,KAAK,EAAE,GAAG;IACV,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,IAAI;IACf,KAAK,EAAE,QAAQ;CACe,CAAC"}