@marktiderman/genesis-forms-studio 0.4.0 → 0.5.0

package/dist/rules-DZ1gTZoH.d.ts

@@ -1,528 +0,0 @@
-import { FieldBlock, Json, FormDefinition } from '@marktiderman/genesis-forms';
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { SubNavItem } from '@marktiderman/genesis-ui/layout';
-
-type Cell = string | number | boolean;
-
-/** One answer as a cell: option labels for choices, Yes/No, lists joined with commas. */
-declare function answerCell(field: FieldBlock, value: Json | undefined): Cell;
-/** A label with recall tokens replaced by their fallback. */
-declare const plainLabel: (label: string) => string;
-interface AnswerColumn {
-    /** The field's key: stable across versions, so one column covers every version's answers. */
-    key: string;
-    label: string;
-}
-/**
- * One column per field key across the given definitions, in the order the newest
- * definition asks them, then keys only older versions had (in their order). Labels come
- * from the newest definition that has the key.
- */
-declare function answerColumns(definitions: readonly FormDefinition[], skip?: ReadonlySet<string>): AnswerColumn[];
-/** A response's answers by field key, as cells (answers are stored by field id). */
-declare function answersByKey(definition: FormDefinition, answers: Record<string, Json>): Record<string, Cell>;
-/** A response's raw answers by field key, with the field each was given to (answers are stored by field id). */
-declare function valuesByKey(definition: FormDefinition, answers: Record<string, Json>): Map<string, {
-    field: FieldBlock;
-    value: Json;
-}>;
-/**
- * CSV text (RFC 4180, CRLF) with a header row; every cell is quoted when it needs to be.
- * Text that a spreadsheet would run as a formula (starting with = + - @, tab or CR) gets a
- * leading apostrophe, so a respondent's answer can't run in Excel when staff open the
- * download. Numbers stay as they are. (Sheets delivery writes RAW values and needs none.)
- */
-declare function toCsv(header: readonly string[], rows: readonly (readonly Cell[])[]): string;
-
-/**
- * Where a response is, on a form that saves answers as they go (`settings.saveProgress`):
- * `in_progress` while someone is answering, `partial` once they stopped without sending
- * (kept, and counted like a sent one), `completed` once sent.
- */
-type ResponseStatus = "in_progress" | "partial" | "completed";
-/** One answered form (a feedback response, a worksheet entry). */
-interface SummaryItem {
-    id: string;
-    /** The day it was answered, YYYY-MM-DD. */
-    date: string;
-    definition: FormDefinition;
-    answers: Record<string, Json>;
-    /** Extra plain values a filter can match, such as the class or coach. */
-    extra?: Record<string, Cell>;
-    /** Default `completed`. */
-    status?: ResponseStatus | undefined;
-    /**
-     * The furthest question reached (a field id of `definition`), for an unfinished
-     * response: genesis-forms `formProgress`'s `fieldId`. Drop-off by question reads it.
-     */
-    furthest?: string | null | undefined;
-    /**
-     * Its hidden inputs, as stored. Drop-off by question rebuilds the respondent's path
-     * from them and `answers`, so logic that reads a hidden input is followed.
-     */
-    hidden?: Record<string, Json> | undefined;
-    /**
-     * Answers the host keeps apart from `answers` (contact details on their own row, say),
-     * by field key. Only the path reads them: summaries and filters don't.
-     */
-    extraAnswers?: Record<string, Json | null | undefined> | undefined;
-}
-/**
- * Which responses to show by status. `counted` (the default): sent and partial ones,
- * which summaries count; `in_progress` ones are still being answered.
- */
-type StatusFilter = "counted" | "completed" | "partial" | "in_progress";
-/** The status filter's words, in the menu's order. */
-declare const STATUS_FILTER_LABEL: Record<StatusFilter, string>;
-/** A response status's word, as a table or a detail panel shows it. */
-declare const RESPONSE_STATUS_LABEL: Record<ResponseStatus, string>;
-/** Whether `item` passes a status filter (no status is `completed`). */
-declare function matchesStatus(item: Pick<SummaryItem, "status">, filter?: StatusFilter): boolean;
-interface ScaleSummary {
-    kind: "scale";
-    key: string;
-    label: string;
-    type: "rating" | "nps";
-    /** The field type, as for every summary. */
-    fieldType: "rating" | "nps";
-    /** How many responses answered it. */
-    count: number;
-    min: number;
-    max: number;
-    /** Null when no one answered. */
-    average: number | null;
-    /** One per value from min to max, in order, zeros included. */
-    buckets: {
-        value: number;
-        count: number;
-    }[];
-    /**
-     * Answers given on an older version's different scale (a 1–10 rating now 1–5), moved
-     * onto this one in proportion: they count, at their nearest point on this scale.
-     */
-    rescaled: number;
-    /** Answers left out: outside their own question's scale, or not a whole number. */
-    excluded: number;
-    /** NPS only: promoters 9–10, passives 7–8, detractors 0–6, score = % promoters − % detractors. */
-    nps: {
-        promoters: number;
-        passives: number;
-        detractors: number;
-        score: number;
-    } | null;
-}
-interface ChoiceSummary {
-    kind: "choice";
-    key: string;
-    label: string;
-    /** single-choice, multi-choice, dropdown, yes-no or consent. */
-    fieldType: string;
-    /** How many responses answered it. */
-    count: number;
-    /** Several options per response, so the percentages can add up to more than 100. */
-    multiple: boolean;
-    /** The newest version's options in order, then any only older versions had. */
-    options: {
-        value: string;
-        label: string;
-        count: number;
-        percent: number;
-    }[];
-}
-interface TextSummary {
-    kind: "text";
-    key: string;
-    label: string;
-    /** The field type: short-text, long-text, email… */
-    fieldType: string;
-    count: number;
-    /** Every answer, newest day first. */
-    answers: {
-        id: string;
-        date: string;
-        text: string;
-    }[];
-}
-type QuestionSummary = ScaleSummary | ChoiceSummary | TextSummary;
-/**
- * One summary per question across `definitions` (newest first: it sets the order, labels,
- * type and options), counting each item's answers by field key. Keys in `skip` are left out.
- */
-declare function summarizeResponses(items: readonly SummaryItem[], definitions: readonly FormDefinition[], skip?: ReadonlySet<string>): QuestionSummary[];
-/** The highest score any rating question in `definitions` asks for (NPS left out); null when none. */
-declare function highestRating(definitions: readonly FormDefinition[]): number | null;
-/** The lowest rating-question answer in an item (NPS left out), or null when it has none. */
-declare function lowestRating(item: SummaryItem): number | null;
-/**
- * The highest answer that counts as low on a rating or NPS question: the bottom 40% of a
- * rating's scale (at least 1), or 0–6 (detractors) on NPS. Null for other questions.
- */
-declare function lowRatingAtMost(field: FieldBlock): number | null;
-/** lowRatingAtMost for a scale known only by its type and top score (a ScaleSummary's). */
-declare function lowScaleAtMost(type: "rating" | "nps", max: number): number;
-/** Whether any rating or NPS answer in an item is low on its own question's scale. */
-declare function hasLowRating(item: SummaryItem): boolean;
-/** hasLowRating, leaving out the answers to keys in `skip` (as summaries and needsFollowUp do). */
-declare function hasLowRatingExcept(item: SummaryItem, skip: ReadonlySet<string>): boolean;
-/**
- * What "low" means across `definitions`, in words: "2 or below" for one 1–5 scale, "2 or
- * below out of 5, 4 or below out of 10" for two, "0–6 on NPS" beside them ("0–6" alone).
- * Null when no question has a rating or NPS answer.
- */
-declare function lowRatingLabel(definitions: readonly FormDefinition[]): string | null;
-interface ResponseFilter {
-    /** First and last day, YYYY-MM-DD, both included; open-ended when absent. */
-    from?: string | null;
-    to?: string | null;
-    /** Extra values that must match exactly, such as { class: "6am WOD" }. */
-    match?: Record<string, string | null | undefined>;
-    /** Only items with a rating at or below this (any rating question). */
-    ratingAtMost?: number | null;
-    /** Only items with a low answer on its question's own scale (hasLowRating). */
-    low?: boolean;
-    /** By status (matchesStatus); default `counted`: sent and partial, not in progress. */
-    status?: StatusFilter | undefined;
-}
-/** Whether a filter leaves anything out beyond the default (in-progress responses). */
-declare function isFiltered(filter: ResponseFilter): boolean;
-/** The items a filter keeps, in their order. */
-declare function filterResponses<T extends SummaryItem>(items: readonly T[], filter: ResponseFilter): T[];
-type DatePreset = "all" | "today" | "week" | "7d" | "30d" | "month";
-/**
- * A preset's first and last day, given today (YYYY-MM-DD, on the clock the items' days
- * use). "week" starts on Monday; "7d" and "30d" include today.
- */
-declare function presetRange(preset: DatePreset, today: string): {
-    from: string | null;
-    to: string | null;
-};
-/** What the filter bar holds; `toResponseFilter` turns it into a filter. */
-interface FiltersValue {
-    when: DatePreset | "custom";
-    /** Custom range, YYYY-MM-DD; empty for open-ended. */
-    from: string;
-    to: string;
-    /** By choice filter key, e.g. { class: "6am WOD" }; missing or empty for any. */
-    match: Record<string, string>;
-    ratingAtMost: number | null;
-    /** Low ratings, each on its own question's scale (lowRatingAtMost). */
-    low: boolean;
-    /** By status, on a form that saves answers as they go; missing is `counted`. */
-    status?: StatusFilter | undefined;
-}
-declare const NO_FILTERS: FiltersValue;
-/** The filter for `value`, given today's date on the clock the responses' days use. */
-declare function toResponseFilter(value: FiltersValue, today: string): ResponseFilter;
-/**
- * The one-click "Low ratings this week": this week, and low on each question's own scale
- * (lowRatingAtMost: the bottom 40% of a rating, NPS detractors), other filters kept.
- */
-declare const lowThisWeek: (value: FiltersValue) => FiltersValue;
-
-/** One headline number: a label, the number, and a short line under it. */
-interface HeadlineNumber {
-    key: string;
-    label: string;
-    value: ReactNode;
-    detail?: ReactNode;
-    /** The detail's colour: good news, bad news, a warning, or plain. Default plain. */
-    tone?: "positive" | "negative" | "warning" | "muted" | undefined;
-}
-/** A row of headline numbers (KPI cards): two across on a phone, up to four on a wide screen. */
-declare function HeadlineNumbers({ numbers, isLoading, className, }: {
-    numbers: readonly HeadlineNumber[];
-    isLoading?: boolean | undefined;
-    className?: string | undefined;
-}): react.JSX.Element | null;
-
-interface Headline {
-    responses: {
-        count: number;
-        /** Responses in the period before, under the same other filters; null with no period. */
-        previous: number | null;
-        /** count − previous; null with no period. */
-        change: number | null;
-        /** How many of `count` are partial (never sent); left out when there are none. */
-        partial?: number;
-    };
-    /** The first rating question (newest definition order); null when the form has none. */
-    rating: {
-        key: string;
-        label: string;
-        max: number;
-        /** Null when nobody answered it. */
-        average: number | null;
-        /** The same question's average in the period before; null without one or without answers. */
-        previousAverage: number | null;
-        /** average − previousAverage, when both are known. */
-        change: number | null;
-    } | null;
-    /** Responses with a low answer on any rating or NPS question; null when there is none. */
-    low: {
-        count: number;
-    } | null;
-    /** The first consent question, else the first yes/no one; null when there is none. */
-    rate: {
-        key: string;
-        label: string;
-        type: "consent" | "yes-no";
-        /** Agreed or Yes. */
-        yes: number;
-        /** How many answered it. */
-        count: number;
-        /** 0–100; null when nobody answered. */
-        percent: number | null;
-    } | null;
-}
-/**
- * The headline numbers for `items` (already filtered), with `previous` (the same filters
- * over the period before, from `comparisonFilter`) for the changes. `definitions` are
- * newest first, as `summarizeResponses` takes them; `skip` leaves keys out.
- */
-declare function headlineNumbers(items: readonly SummaryItem[], definitions: readonly FormDefinition[], options?: {
-    previous?: readonly SummaryItem[] | null;
-    skip?: ReadonlySet<string>;
-}): Headline;
-/**
- * The period before the one the filter bar picks, with the bar's other filters kept, and
- * what to call it ("last week"). "This week" compares with the same weekdays last week,
- * "This month" with last month up to the same day, any other range with as many days
- * just before it. Null for "All time", or a
- * custom range with an open end.
- */
-declare function comparisonFilter(value: FiltersValue, today: string): {
-    filter: ResponseFilter;
-    label: string;
-} | null;
-/**
- * The cards for `headlineNumbers`' answer: Responses (with the change against `period`,
- * e.g. "last week"), Average rating, Low ratings, and the consent or yes/no rate. A card
- * the form has no question for is left out.
- */
-declare function headlineCards(headline: Headline, options?: {
-    period?: string | null | undefined;
-    /** How many low-rated responses still need a follow-up (not handled); the card says so. */
-    lowOpen?: number | undefined;
-}): HeadlineNumber[];
-
-interface QuestionDropOff {
-    key: string;
-    label: string;
-    /** How many responses reached this question (it was on their path, on screen or answered). */
-    views: number;
-    /** How many stopped here: their furthest question, never sent. */
-    stopped: number;
-    /** stopped ÷ views as a whole percentage; null when nobody reached it. */
-    dropOff: number | null;
-}
-interface DropOffSummary {
-    /**
-     * How many people started: distinct responses of any status (sent, partial, in progress),
-     * each once. Someone is saved once they answer a question or move on from the first.
-     */
-    started: number;
-    /** Each question's views and drop-off (`dropOffByQuestion`). */
-    dropOffs: QuestionDropOff[];
-}
-/**
- * Each question's views and drop-off, in the newest definition's order (`definitions`
- * newest first, as `summarizeResponses` takes them), matched across versions by field key.
- * Each response counts once (by `id`).
- *
- * - A sent response (`completed`, or no status) reached every question on its path and
- *   stopped at none. A question logic hid or jumped over for them was never reached.
- * - A `partial` response reached the questions on its path before its `furthest` (the
- *   path is rebuilt from the answers so far, so it can run past it), then `furthest`, and
- *   stopped there. One without `furthest` (saved before it was kept) is left out.
- * - An `in_progress` response is left out: they may still be answering.
- *
- * The path is rebuilt from `answers`, `hidden` and `extraAnswers`; give the item every
- * answer logic can read, or a rule reading a missing one sees it unanswered. Two things a
- * stored response can't tell, so they count as on the path:
- *
- * - A question a prefilled link answered and hid (`props.prefill.hideWhenPrefilled`):
- *   which answers came from the link lives in the form's answer events, which aren't kept.
- * - A rule comparing a pick from a host-supplied option list to an option value, when the
- *   host stores the pick as its label: the rule sees the label.
- *
- * Someone who opened the form and left before moving on from the first question was
- * never saved, so they aren't counted.
- */
-declare function dropOffByQuestion(items: readonly SummaryItem[], definitions: readonly FormDefinition[], skip?: ReadonlySet<string>): QuestionDropOff[];
-/**
- * What `<DropOffByQuestion>` shows: how many people started and each question's drop-off.
- * Pass every response under the host's filters except status (in-progress ones count as
- * started, never per question).
- */
-declare function dropOffSummary(items: readonly SummaryItem[], definitions: readonly FormDefinition[], skip?: ReadonlySet<string>): DropOffSummary;
-
-interface FollowUp<T extends SummaryItem = SummaryItem> {
-    item: T;
-    /** The lowest low answer, on its own question's scale. */
-    rating: {
-        value: number;
-        max: number;
-        type: "rating" | "nps";
-    };
-    /** The first written answer (short or long text), trimmed; null when there is none. */
-    comment: string | null;
-}
-/** One item's follow-up, or null when none of its answers is low. */
-declare function followUpOf<T extends SummaryItem>(item: T, skip?: ReadonlySet<string>): FollowUp<T> | null;
-/**
- * The items that need a follow-up, newest day first: a low answer on a rating or NPS
- * question (lowRatingAtMost), and not handled yet. `skip` leaves keys out (contact details).
- */
-declare function needsFollowUp<T extends SummaryItem>(items: readonly T[], options?: {
-    isHandled?: (item: T) => boolean;
-    skip?: ReadonlySet<string>;
-}): FollowUp<T>[];
-
-/** A day (YYYY-MM-DD) in words, given today on the same clock: "Today", "Yesterday", "Oct 21", "Oct 21, 2025". */
-declare function dayLabel(day: string, today?: string): string;
-
-/** One search param a prefilled link may set, and the values staff pick from. */
-interface PrefillChoice {
-    key: string;
-    /** The picker's accessible name, e.g. "Class". */
-    label: string;
-    /** The picker's "leave it out" choice, e.g. "Any class". */
-    anyLabel: string;
-    options: readonly {
-        value: string;
-        label: string;
-    }[];
-}
-/**
- * `url` with `values` set as search params (empty values left out), keeping what it has.
- * An absolute link stays absolute; a relative one (`/f/a?x=1`) stays relative, so it never
- * throws while a page is still working out its origin.
- */
-declare function prefilledUrl(url: string, values: Record<string, string | undefined>): string;
-/** An `<iframe>` that shows the form on another website, full width. */
-declare function embedSnippet(url: string, title: string): string;
-
-type FormAvailability = "draft" | "archived" | "paused" | "scheduled" | "closed" | "full" | "live";
-interface AvailabilityInput {
-    status: "draft" | "active" | "archived";
-    /** False when the form has never been published (it has no version to serve). */
-    published?: boolean;
-    /**
-     * ISO times it takes responses from and until; open-ended when absent. Each needs `Z` or
-     * an offset (`+02:00`): a time without one would be read on whatever clock the code runs
-     * on. One that doesn't parse, or has no offset, keeps the form closed (fail closed).
-     * Normalise times where they are written (`new Date(…).toISOString()`).
-     */
-    opensAt?: string | null | undefined;
-    closesAt?: string | null | undefined;
-    paused?: boolean | undefined;
-    /** At most this many completed responses; null or absent for no cap. */
-    responseCap?: number | null | undefined;
-    /** Completed, non-deleted responses so far, when the caller knows the count. */
-    completedResponses?: number | null | undefined;
-    /** Whether the cap is reached, when only that is known (the public page never sees the count). */
-    full?: boolean | undefined;
-}
-/** Whether the form has its response cap: from `full` when given, else from the cap and count. */
-declare function isFull(form: Pick<AvailabilityInput, "responseCap" | "completedResponses" | "full">): boolean;
-/** An ISO time with `Z` or an offset, as epoch milliseconds; NaN for anything else. */
-declare function parseInstant(value: string): number;
-/**
- * Where a form stands at `at`. Archived and draft first, then paused (staff chose it,
- * whatever the clock says), then the opening window (a time that can't be read, or has no
- * offset, counts as closed), then the cap. Only "live" takes
- * responses.
- */
-declare function formAvailability(form: AvailabilityInput, at?: Date): FormAvailability;
-/** Whether the form takes responses at `at`. */
-declare function takesResponses(form: AvailabilityInput, at?: Date): boolean;
-
-/** Where the host's draft saving stands. */
-type SaveState = "saved" | "saving" | "unsaved" | "failed" | "stopped" | "conflict";
-declare const SAVE_STATE_LABEL: Record<SaveState, string>;
-type ChipTone = "success" | "warning" | "danger" | "info" | "muted";
-/** Whether something can be published, from an editor's checks. */
-interface Readiness {
-    state: "ready" | "problems" | "warnings" | "empty" | "pending";
-    /** Problems or warnings to look at (0 when ready, empty or pending). */
-    count: number;
-}
-/**
- * Readiness from an editor's findings (genesis-forms-builder's `Analysis.findings`, or any
- * list shaped like it): errors block publishing; `no-questions` (nothing to answer yet)
- * is "empty", not broken. `pending` says errors are held back while a new question is being written.
- */
-declare function readinessOf(findings: readonly {
-    level: "error" | "warning" | "info";
-    code?: string;
-}[], options?: {
-    pending?: boolean;
-}): Readiness;
-declare function readinessChip(readiness: Readiness): {
-    label: string;
-    tone: ChipTone;
-};
-
-/**
- * A form's status chip: "Live · version 3", "Draft", "Paused · version 3"… `availability`
- * is formAvailability's answer; `version` the live version, when there is one.
- */
-declare function formStatusChip(availability: FormAvailability, version?: number | null): {
-    label: string;
-    tone: ChipTone;
-};
-/** The form page's four places, in order. */
-type FormTab = "questions" | "logic" | "responses" | "settings";
-/** One of a form page's child navigation items: genesis-ui's `SubNavItem`, plus its place. */
-type FormNavItem = SubNavItem & {
-    id: FormTab;
-    badge?: number;
-};
-/** How many questions a definition asks, and how many rules plus endings it has. */
-declare function formCounts(definition: FormDefinition | null | undefined): {
-    questions: number;
-    logic: number;
-};
-/**
- * The form page's child navigation items (Questions, Logic and endings, Responses,
- * Settings) with their counts as badges, for the app shell's sub-navigation:
- * `useAppShellSubNav(formNavItems("/forms/f1", counts))`. `at` is the form page's path
- * (each place is `?tab=<id>` on it, Questions the path itself, which the shell's most
- * specific match keeps from lighting up on the others) or a function giving each place's
- * address. A count left out (or null) shows no badge.
- */
-declare function formNavItems(at: string | ((tab: FormTab) => string), counts?: {
-    questions?: number | null;
-    logic?: number | null;
-    responses?: number | null;
-}, 
-/** Each place's icon, for the rail and the phone's bottom bar (`FORM_NAV_ICONS`). */
-icons?: Partial<Record<FormTab, SubNavItem["icon"]>>): FormNavItem[];
-
-/**
- * "How was class?" → "how-was-class": the public link's last part (lowercase words and
- * hyphens, at most 60). `fallback` is used when the title has no letters or numbers.
- */
-declare function slugFromTitle(title: string, fallback?: string): string;
-/** A form link: lowercase letters and numbers, in words joined by single hyphens. */
-declare const SLUG_PATTERN: RegExp;
-/** Why a form link can't be used, or nothing when it fits SLUG_PATTERN. */
-declare function validateSlug(slug: string): string | undefined;
-/** A duplicate's name: "Copy of …", within the 120 characters a form name may have. */
-declare function copyTitle(title: string): string;
-/** The first of `slug`, `slug-2`, `slug-3`… that isn't in `taken`, within 60 characters. */
-declare function freeSlug(slug: string, taken: ReadonlySet<string>): string;
-
-/**
- * Whether the thank-you page offers "Send another response" (on unless `submitAnother`
- * is false). Never on a form that takes one response per person: a second response
- * would be refused. Anonymous forms don't know who answered, so one per person doesn't apply.
- */
-declare function offersSubmitAnother(form: {
-    submitAnother?: boolean | null | undefined;
-    onePerPerson?: boolean | null | undefined;
-    anonymous?: boolean | null | undefined;
-}): boolean;
-
-export { isFull as $, type AnswerColumn as A, dropOffByQuestion as B, type ChipTone as C, type DatePreset as D, dropOffSummary as E, type FiltersValue as F, embedSnippet as G, type Headline as H, filterResponses as I, followUpOf as J, formAvailability as K, formCounts as L, formNavItems as M, NO_FILTERS as N, formStatusChip as O, type PrefillChoice as P, type QuestionSummary as Q, type Readiness as R, type SaveState as S, type TextSummary as T, freeSlug as U, hasLowRating as V, hasLowRatingExcept as W, headlineCards as X, headlineNumbers as Y, highestRating as Z, isFiltered as _, type QuestionDropOff as a, lowRatingAtMost as a0, lowRatingLabel as a1, lowScaleAtMost as a2, lowThisWeek as a3, lowestRating as a4, matchesStatus as a5, needsFollowUp as a6, offersSubmitAnother as a7, parseInstant as a8, plainLabel as a9, prefilledUrl as aa, presetRange as ab, readinessChip as ac, readinessOf as ad, slugFromTitle as ae, summarizeResponses as af, takesResponses as ag, toCsv as ah, toResponseFilter as ai, validateSlug as aj, valuesByKey as ak, type AvailabilityInput as b, type Cell as c, type ChoiceSummary as d, type DropOffSummary as e, type FollowUp as f, type FormAvailability as g, type FormNavItem as h, type FormTab as i, type HeadlineNumber as j, HeadlineNumbers as k, RESPONSE_STATUS_LABEL as l, type ResponseFilter as m, type ResponseStatus as n, SAVE_STATE_LABEL as o, SLUG_PATTERN as p, STATUS_FILTER_LABEL as q, type ScaleSummary as r, type StatusFilter as s, type SummaryItem as t, answerCell as u, answerColumns as v, answersByKey as w, comparisonFilter as x, copyTitle as y, dayLabel as z };