@fieldia/core 0.30.0 → 0.31.0

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

@@ -0,0 +1,43 @@
+import * as z from 'zod';
+/**
+ * A review before a page of responses is sent (`review` on a page): every answer shown — by step on a wizard, by
+ * titled group on a page of sections — each with Edit, then Back and Send. `true` says it with Fieldia's own words
+ * ("Check your answers"); its own `title` and `text` say it in the page's.
+ *
+ *   "review": { "title": "Check your answers before you send them", "text": "Press Edit to change one." }
+ */
+export interface PageReview {
+    /** Its heading, in place of "Check your answers". */
+    title?: string;
+    /** Words under the heading. */
+    text?: string;
+}
+export declare const PageReviewSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/**
+ * A time limit for a whole page of responses (`timeLimit` on the page) or one step of its wizard (`timeLimit` on the
+ * step): a countdown while it runs, a warning `warn` minutes before its end, then — as `then` says, and the page says
+ * which — the answers sent as they stand (`send`), or locked (`lock`): a page's kept for the person to send, a step's
+ * kept as they are while the form goes on to the next. A page's clock starts as the person presses Start, a step's as
+ * it is first entered; both are kept in a draft, so a page opened again goes on counting.
+ *
+ *   "timeLimit": { "minutes": 20, "warn": 2, "then": "send" }
+ */
+export interface TimeLimit {
+    /** The time it allows, in minutes: 0.5 is thirty seconds. */
+    minutes: number;
+    /** How many minutes before its end the countdown warns: 1 unless said (a fifth of the time, where that is less). */
+    warn?: number;
+    /** What happens as it runs out: the answers sent as they stand (a page's, unless said), or locked (a step's, unless said). */
+    then?: 'send' | 'lock';
+}
+export declare const TimeLimitSchema: z.ZodObject<{
+    minutes: z.ZodNumber;
+    warn: z.ZodOptional<z.ZodNumber>;
+    then: z.ZodOptional<z.ZodEnum<{
+        send: "send";
+        lock: "lock";
+    }>>;
+}, z.core.$strict>;

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

@@ -0,0 +1,43 @@
+import * as z from 'zod';
+/**
+ * A review before a page of responses is sent (`review` on a page): every answer shown — by step on a wizard, by
+ * titled group on a page of sections — each with Edit, then Back and Send. `true` says it with Fieldia's own words
+ * ("Check your answers"); its own `title` and `text` say it in the page's.
+ *
+ *   "review": { "title": "Check your answers before you send them", "text": "Press Edit to change one." }
+ */
+export interface PageReview {
+    /** Its heading, in place of "Check your answers". */
+    title?: string;
+    /** Words under the heading. */
+    text?: string;
+}
+export declare const PageReviewSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.z.core.$strict>]>;
+/**
+ * A time limit for a whole page of responses (`timeLimit` on the page) or one step of its wizard (`timeLimit` on the
+ * step): a countdown while it runs, a warning `warn` minutes before its end, then — as `then` says, and the page says
+ * which — the answers sent as they stand (`send`), or locked (`lock`): a page's kept for the person to send, a step's
+ * kept as they are while the form goes on to the next. A page's clock starts as the person presses Start, a step's as
+ * it is first entered; both are kept in a draft, so a page opened again goes on counting.
+ *
+ *   "timeLimit": { "minutes": 20, "warn": 2, "then": "send" }
+ */
+export interface TimeLimit {
+    /** The time it allows, in minutes: 0.5 is thirty seconds. */
+    minutes: number;
+    /** How many minutes before its end the countdown warns: 1 unless said (a fifth of the time, where that is less). */
+    warn?: number;
+    /** What happens as it runs out: the answers sent as they stand (a page's, unless said), or locked (a step's, unless said). */
+    then?: 'send' | 'lock';
+}
+export declare const TimeLimitSchema: z.ZodObject<{
+    minutes: z.ZodNumber;
+    warn: z.ZodOptional<z.ZodNumber>;
+    then: z.ZodOptional<z.ZodEnum<{
+        send: "send";
+        lock: "lock";
+    }>>;
+}, z.z.core.$strict>;

package/src/lib/format/flow.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeLimitSchema = exports.PageReviewSchema = void 0;
+const z = require("zod");
+exports.PageReviewSchema = z
+    .union([
+    z.boolean(),
+    z.strictObject({
+        title: z.string().regex(/\S/, 'a review’s title is words').max(300).optional(),
+        text: z.string().regex(/\S/, 'a review’s text is words').max(2000).optional(),
+    }),
+])
+    .meta({ id: 'PageReview' });
+exports.TimeLimitSchema = z
+    .strictObject({
+    minutes: z.number().positive().max(24 * 60),
+    warn: z.number().positive().max(24 * 60).optional(),
+    then: z.enum(['send', 'lock']).optional(),
+})
+    .refine((limit) => limit.warn === undefined || limit.warn < limit.minutes, { message: 'warn comes before the end: fewer minutes than the limit', path: ['warn'] })
+    .meta({ id: 'TimeLimit' });
+//# sourceMappingURL=flow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/flow.ts"],"names":[],"mappings":";;;AAAA,yBAAyB;AAgBZ,QAAA,gBAAgB,GAAG,CAAC;KAC9B,KAAK,CAAC;IACL,CAAC,CAAC,OAAO,EAAE;IACX,CAAC,CAAC,YAAY,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;QAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,0BAA0B,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;KAC9E,CAAC;CACH,CAAC;KACD,IAAI,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;AAoBjB,QAAA,eAAe,GAAG,CAAC;KAC7B,YAAY,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,yDAAyD,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;KACjK,IAAI,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC"}

package/src/lib/format/flow.mjs

@@ -0,0 +1,19 @@
+import * as z from 'zod';
+export const PageReviewSchema = z
+    .union([
+    z.boolean(),
+    z.strictObject({
+        title: z.string().regex(/\S/, 'a review’s title is words').max(300).optional(),
+        text: z.string().regex(/\S/, 'a review’s text is words').max(2000).optional(),
+    }),
+])
+    .meta({ id: 'PageReview' });
+export const TimeLimitSchema = z
+    .strictObject({
+    minutes: z.number().positive().max(24 * 60),
+    warn: z.number().positive().max(24 * 60).optional(),
+    then: z.enum(['send', 'lock']).optional(),
+})
+    .refine((limit) => limit.warn === undefined || limit.warn < limit.minutes, { message: 'warn comes before the end: fewer minutes than the limit', path: ['warn'] })
+    .meta({ id: 'TimeLimit' });
+//# sourceMappingURL=flow.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAgBzB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,KAAK,CAAC;IACL,CAAC,CAAC,OAAO,EAAE;IACX,CAAC,CAAC,YAAY,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;QAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,0BAA0B,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;KAC9E,CAAC;CACH,CAAC;KACD,IAAI,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;AAoB9B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,YAAY,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,yDAAyD,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;KACjK,IAAI,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC"}

package/src/lib/format/from-schema.d.mts

@@ -0,0 +1,70 @@
+import type { Page } from './page.mjs';
+/**
+ * A starting page from what an app already has: a JSON Schema, an OpenAPI document (a component's schema, or an
+ * operation's request body and parameters), or a model's fields (Fieldia's own, or a backend's field list such as
+ * Flectra's `fields_get`). Each property becomes a field of its kind — text, numbers, yes or no, dates, choices, files,
+ * lines — with its label, help, whether it is required or read-only, its limits, its pattern and its default, laid out
+ * in sections (a screen) or steps (a survey). What has no field of its own is kept as JSON and said; what cannot be
+ * read is left out and said: nothing is dropped quietly.
+ *
+ *   const { page, notes, unmapped } = pageFromSchema(openApi, { schema: 'POST /enquiries' });
+ *
+ * The page is a start, to edit in the designer: it names a model (`data.model`) the app's data source answers for.
+ */
+/** Something a schema said, about one of its properties (`path`, as the schema names it), and how it was taken. */
+export interface SchemaNote {
+    path: string;
+    /**
+     * Kept with a change: `renamed` (a name a field cannot have), `flattened` (an object's properties as fields of their
+     * own, in a section), `json` (a value of a kind no field holds, kept as JSON), `limit` (a limit no setting holds),
+     * `format` (a format Fieldia does not know, kept as text), `pattern` (a pattern that does not read, left out),
+     * `constant` (one value, shown read-only), `links` (lines whose fields are not given, kept as links), `languages` (a
+     * backend's text kept in several languages, `translate: true`, typed in one here: the page names its languages).
+     * Left out: `reference` (a `$ref` outside the document, or one that refers to itself), `kind` (no kind of value).
+     */
+    code: 'renamed' | 'flattened' | 'json' | 'limit' | 'format' | 'pattern' | 'constant' | 'links' | 'languages' | 'reference' | 'kind';
+    /** What exactly: the new name, the limit as the schema wrote it, the kind of value, the reference. */
+    detail?: string;
+}
+export interface PageFromSchema {
+    page: Page;
+    /** What was kept with a change. */
+    notes: SchemaNote[];
+    /** What was left out. */
+    unmapped: SchemaNote[];
+    /** What it was read as. */
+    from: 'json-schema' | 'openapi' | 'fields';
+}
+/** Why a schema gave no page, for an app (or the designer) to say in its own words; the error's message says it in English. */
+export type SchemaRefusal = 'not-json-object' | 'not-a-schema' | 'not-an-object' | 'outside' | 'no-properties' | 'no-such-schema' | 'nothing-in-document';
+/** A schema that gave no page: what `pageFromSchema` throws, its `code` saying why. */
+export declare class SchemaRefused extends Error {
+    readonly code: SchemaRefusal;
+    constructor(code: SchemaRefusal, message: string);
+}
+export interface PageFromSchemaOptions {
+    /** A screen of sections, kept as a record of `model` (the default), or a survey's steps, sent as responses. */
+    kind?: 'screen' | 'survey';
+    /** The page's title: the schema's own, else its name in the document, else "Form". */
+    title?: string;
+    /** The page's id: its title's words joined by hyphens. */
+    id?: string;
+    /** The model its records are kept as: its title's words joined by dots. */
+    model?: string;
+    /**
+     * An OpenAPI document's schema to start from: a component's name (`Pet`), an operation's id (`addPet`), or its
+     * method and path (`POST /pets`). The first operation with a request body or parameters, else the first component.
+     */
+    schema?: string;
+}
+/** What an OpenAPI document offers to start from, for a person to choose: its operations, then its components. */
+export declare function schemaChoices(input: unknown): {
+    value: string;
+    label: string;
+}[];
+/** A page to start from, from a JSON Schema, an OpenAPI document or a model's fields. Throws when it is none of them. */
+export declare function pageFromSchema(input: unknown, options?: PageFromSchemaOptions): PageFromSchema;
+/** Each note in words, for an app to show; the designer says them in its own language. */
+export declare function schemaNoteWords(note: SchemaNote): string;
+/** Words for a name: `first_name`, `firstName` and `first-name` all "First name". */
+export declare function wordsOf(name: string): string;

package/src/lib/format/from-schema.d.ts

@@ -0,0 +1,70 @@
+import type { Page } from './page';
+/**
+ * A starting page from what an app already has: a JSON Schema, an OpenAPI document (a component's schema, or an
+ * operation's request body and parameters), or a model's fields (Fieldia's own, or a backend's field list such as
+ * Flectra's `fields_get`). Each property becomes a field of its kind — text, numbers, yes or no, dates, choices, files,
+ * lines — with its label, help, whether it is required or read-only, its limits, its pattern and its default, laid out
+ * in sections (a screen) or steps (a survey). What has no field of its own is kept as JSON and said; what cannot be
+ * read is left out and said: nothing is dropped quietly.
+ *
+ *   const { page, notes, unmapped } = pageFromSchema(openApi, { schema: 'POST /enquiries' });
+ *
+ * The page is a start, to edit in the designer: it names a model (`data.model`) the app's data source answers for.
+ */
+/** Something a schema said, about one of its properties (`path`, as the schema names it), and how it was taken. */
+export interface SchemaNote {
+    path: string;
+    /**
+     * Kept with a change: `renamed` (a name a field cannot have), `flattened` (an object's properties as fields of their
+     * own, in a section), `json` (a value of a kind no field holds, kept as JSON), `limit` (a limit no setting holds),
+     * `format` (a format Fieldia does not know, kept as text), `pattern` (a pattern that does not read, left out),
+     * `constant` (one value, shown read-only), `links` (lines whose fields are not given, kept as links), `languages` (a
+     * backend's text kept in several languages, `translate: true`, typed in one here: the page names its languages).
+     * Left out: `reference` (a `$ref` outside the document, or one that refers to itself), `kind` (no kind of value).
+     */
+    code: 'renamed' | 'flattened' | 'json' | 'limit' | 'format' | 'pattern' | 'constant' | 'links' | 'languages' | 'reference' | 'kind';
+    /** What exactly: the new name, the limit as the schema wrote it, the kind of value, the reference. */
+    detail?: string;
+}
+export interface PageFromSchema {
+    page: Page;
+    /** What was kept with a change. */
+    notes: SchemaNote[];
+    /** What was left out. */
+    unmapped: SchemaNote[];
+    /** What it was read as. */
+    from: 'json-schema' | 'openapi' | 'fields';
+}
+/** Why a schema gave no page, for an app (or the designer) to say in its own words; the error's message says it in English. */
+export type SchemaRefusal = 'not-json-object' | 'not-a-schema' | 'not-an-object' | 'outside' | 'no-properties' | 'no-such-schema' | 'nothing-in-document';
+/** A schema that gave no page: what `pageFromSchema` throws, its `code` saying why. */
+export declare class SchemaRefused extends Error {
+    readonly code: SchemaRefusal;
+    constructor(code: SchemaRefusal, message: string);
+}
+export interface PageFromSchemaOptions {
+    /** A screen of sections, kept as a record of `model` (the default), or a survey's steps, sent as responses. */
+    kind?: 'screen' | 'survey';
+    /** The page's title: the schema's own, else its name in the document, else "Form". */
+    title?: string;
+    /** The page's id: its title's words joined by hyphens. */
+    id?: string;
+    /** The model its records are kept as: its title's words joined by dots. */
+    model?: string;
+    /**
+     * An OpenAPI document's schema to start from: a component's name (`Pet`), an operation's id (`addPet`), or its
+     * method and path (`POST /pets`). The first operation with a request body or parameters, else the first component.
+     */
+    schema?: string;
+}
+/** What an OpenAPI document offers to start from, for a person to choose: its operations, then its components. */
+export declare function schemaChoices(input: unknown): {
+    value: string;
+    label: string;
+}[];
+/** A page to start from, from a JSON Schema, an OpenAPI document or a model's fields. Throws when it is none of them. */
+export declare function pageFromSchema(input: unknown, options?: PageFromSchemaOptions): PageFromSchema;
+/** Each note in words, for an app to show; the designer says them in its own language. */
+export declare function schemaNoteWords(note: SchemaNote): string;
+/** Words for a name: `first_name`, `firstName` and `first-name` all "First name". */
+export declare function wordsOf(name: string): string;