@evaro/consultation-sdk 0.1.0 → 0.2.0-next.0

package/dist/types/Consultation.d.ts

@@ -1,4 +1,5 @@
-import type { ConsultationEvent, ConsultationType, Environment, GetToken, Target } from './types';
+import { type VendorTheme } from './api';
+import type { ConsultationEvent, ConsultationType, Environment, GetToken, SavedAnswers, Target } from './types';
 export interface ConsultationProps {
     /** The hash of the consultation to show. */
     consultation: string;
@@ -9,10 +10,16 @@ export interface ConsultationProps {
     target?: Target;
     /** Returns the signed-in user's token for the target's calls. */
     getToken?: GetToken;
+    /** Sends the target's calls to this NodeAPI URL in place of the environment's host, for example a local stub server. */
+    nodeApiUrl?: string;
     /** Shows the target's saved answers. They cannot be changed or submitted. */
     readOnly?: boolean;
     /** Loads the unpublished version of the consultation. */
     preview?: boolean;
+    /** `steps` shows one question per screen. `form` shows every question on one page, grouped by section. */
+    layout?: ConsultationLayout;
+    /** The label of the form layout's submit button. Defaults to "Submit". */
+    submitLabel?: string;
     /** Reported as `consultation_type` on the events. Defaults to the consultation's own type. */
     consultationType?: ConsultationType;
     /** Called when the flow ends: after submit, or when the user closes the knockout screen. */
@@ -20,5 +27,13 @@ export interface ConsultationProps {
     /** Receives the analytics signals, with the names and fields Connect uses. */
     onEvent?: (event: ConsultationEvent) => void;
 }
-export declare const DRAFT_DELAY_MS = 600;
+export type ConsultationLayout = 'steps' | 'form';
+export { DRAFT_DELAY_MS } from './useTargetSave';
+export type Loaded = {
+    key: string;
+    attempt: number;
+    consultation: iConsultation;
+    theme: VendorTheme | null;
+    saved: SavedAnswers;
+};
 export declare function Consultation(props: ConsultationProps): import("react").JSX.Element;

package/dist/types/api.d.ts

@@ -1,10 +1,15 @@
 import type { Environment } from './types';
 export declare const apiHost: (environment: Environment) => string;
 export declare const nodeApiHost: (environment: Environment) => string;
+/** The NodeAPI base for target calls: `nodeApiUrl` when the host sets one, otherwise the environment's host. */
+export declare function nodeApiBase(environment: Environment, nodeApiUrl?: string): string;
 export declare class RequestError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
+/** The server refused a write because the answers changed in another place. */
+export declare const isConflict: (error: unknown) => boolean;
+export declare const REQUEST_TIMEOUT_MS = 30000;
 export declare function requestJson<T>(url: string, init?: RequestInit): Promise<T>;
 export interface VendorTheme {
     colours?: Partial<Record<'100' | '300' | '500' | '700' | '900', string>>;

package/dist/types/draftQueue.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runs one target's drafts and submits one after another, so an older write never lands after a newer one, and
+ * a reload can wait for the writes that are still open.
+ */
+export declare class DraftQueue {
+    private readonly onIdle;
+    private tail;
+    private open;
+    constructor(onIdle?: () => void);
+    /** Runs the task after the open ones. A failed task does not stop the queue. */
+    run<T>(task: () => Promise<T>): Promise<T>;
+    /** Settles when every task queued so far has settled. */
+    idle(): Promise<unknown>;
+}
+/** Runs a write on the target's queue. Only a write creates a queue, and the queue goes once it is idle. */
+export declare function runOnDraftQueue<T>(key: string, task: () => Promise<T>): Promise<T>;
+/** Settles when the target's open writes have settled. A target with no open writes settles at once. */
+export declare function draftQueueIdle(key: string): Promise<unknown>;
+/** How many targets have open writes. For tests. */
+export declare const openDraftQueues: () => number;
+/** Forgets every queue, so one test's open writes cannot hold up the next test. For tests. */
+export declare const resetDraftQueues: () => void;

package/dist/types/flow/form.d.ts

@@ -0,0 +1,67 @@
+/** Rules of the one-page form layout: which questions show, how they group, and what a submit checks and sends. */
+import type { AnswerMap } from './answer';
+import { type Walk } from './path';
+type Section = NonNullable<iConsultation['sections']>[number];
+export interface FormTable {
+    /** Headings, the first one for the row labels. */
+    columns: string[];
+    /** One list of question hashes for each row, in column order. The first question's title is the row label. */
+    rows: string[][];
+}
+export interface FormSection {
+    id: string;
+    name: string;
+    description: string;
+    /** Set when the section draws as a table; otherwise its questions show as a list. */
+    table: FormTable | null;
+    /** The section's main questions, in flow order. */
+    questions: string[];
+}
+/** What the page shows, in flow order. */
+export type FormBlock = {
+    kind: 'questions';
+    questions: string[];
+} | {
+    kind: 'section';
+    section: FormSection;
+} | {
+    kind: 'tabs';
+    name: string;
+    sections: FormSection[];
+};
+export interface FormExit {
+    questionHash: string;
+    title: string | null;
+    content: string | null;
+}
+export interface Form {
+    /** The main questions on the page, in flow order. */
+    path: string[];
+    /** Every question on the page: the main ones and their open follow-ups, in the order the page draws them. */
+    shown: string[];
+    blocks: FormBlock[];
+    /** Questions that may stay empty: a table section's questions that are not Yes / No, and one-tick checkboxes. */
+    optional: Set<string>;
+    /** An answer with an exit. The questions after it are hidden. */
+    exit: FormExit | null;
+}
+/** A radio question whose only options are Yes and No. The form draws it as a Yes / No pair. */
+export declare function isYesNo(question: iQuestion | undefined): boolean;
+/**
+ * A table section reads its main questions row by row, in consultation order: one question for each heading
+ * after the first. A row a jump or an exit hides as a whole is left out. When the questions do not fill whole
+ * rows, or an answer hides part of a row, the section shows as a list, so a cell can never move under the wrong
+ * row label.
+ */
+export declare function sectionTable(section: Section, questions: string[], shown: Set<string>): FormTable | null;
+/**
+ * What the page shows: the flow from the first question. A section's questions show together, where its first
+ * question comes in the flow, and questions with no section show where they come. Sections next to each other
+ * with the same group show as tabs. Follow-ups show under their parent, so only main questions are grouped.
+ */
+export declare function buildForm(walk: Walk, consultation: Pick<iConsultation, 'hash' | 'sections'>): Form;
+/** Questions on the page that still need an answer, in page order. Optional questions are never missing. */
+export declare function missingAnswers(form: Form, walk: Walk): string[];
+/** The answers on the page: what a draft saves and a submit sends. Answers of a branch a jump leaves are dropped. */
+export declare function formAnswers(form: Form, walk: Walk): AnswerMap;
+export {};

package/dist/types/flow/path.d.ts

@@ -1,4 +1,6 @@
 import { type AnswerMap } from './answer';
+/** A question and its open follow-ups, walking nested ones. */
+export declare function withFollowUps(hash: string, allQuestions: iQuestion[], answers: AnswerMap, optionHashes: AnswerMap, into: Set<string>): void;
 /**
  * Only the answers on the path the user took. Going Back and choosing another option leaves the answers of the
  * old branch in state; they must not be saved as if they were given on this path.
@@ -17,6 +19,11 @@ export interface Walk {
  * Returns the questions passed on the way, with the one to show last.
  */
 export declare function resumeHistory(walk: Walk): string[];
+/**
+ * The one-page form's main questions: the flow from the first question, where only an answer takes a jump, so an
+ * unanswered question goes on to its default next one. It stops at an answer with an exit.
+ */
+export declare function formPath(walk: Walk): string[];
 /**
  * The answers a draft keeps: the path behind the user, and ahead of them the questions the current answers
  * still lead to. After Back, answers further on survive while the user edits, even when an edit leaves the

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export { Consultation, type ConsultationProps } from './Consultation';
+export { Consultation, type ConsultationLayout, type ConsultationProps } from './Consultation';
 export type { Answer, Answers, ConsultationEvent, ConsultationEventName, ConsultationType, Environment, GetToken, SavedAnswers, Target, TargetAdapter } from './types';

package/dist/types/targets/diagnosisRequest.d.ts

@@ -1,3 +1,3 @@
 import type { Environment, GetToken, TargetAdapter } from '../types';
 /** Assessment answers stored on a diagnosis request, through NodeAPI with the Prescriber App user's token. */
-export declare function diagnosisRequestTarget(environment: Environment, id: string, getToken: GetToken): TargetAdapter;
+export declare function diagnosisRequestTarget(environment: Environment, id: string, getToken: GetToken, nodeApiUrl?: string): TargetAdapter;

package/dist/types/targets/index.d.ts

@@ -1,3 +1,3 @@
 import type { Environment, GetToken, Target, TargetAdapter } from '../types';
 /** One adapter for each target type. To save answers in a new place, add a type here, not code in the host. */
-export declare function createTargetAdapter(target: Target, environment: Environment, getToken: GetToken): TargetAdapter;
+export declare function createTargetAdapter(target: Target, environment: Environment, getToken: GetToken, nodeApiUrl?: string): TargetAdapter;

package/dist/types/types.d.ts

@@ -16,9 +16,13 @@ export interface SavedAnswers {
     /** The consultation version the answers were given against, when the target knows it. */
     consultationVersion: string | null;
     submittedAt: string | null;
+    /** The server's version of the saved answers. A draft must start from it, or the server refuses the draft. */
+    version: number | null;
 }
 /** The calls the package makes for one target type. The adapter is the only code that knows the endpoints. */
 export interface TargetAdapter {
+    /** The version of the last load or saved draft. Each draft sends it. */
+    readonly version: number | null;
     load: () => Promise<SavedAnswers>;
     saveDraft: (answers: Answers) => Promise<void>;
     submit: (answers: Answers) => Promise<void>;

package/dist/types/ui/ErrorNotice.d.ts

@@ -0,0 +1,4 @@
+export declare const ErrorNotice: ({ message, onRetry }: {
+    message: string;
+    onRetry: () => void;
+}) => import("react").JSX.Element;

package/dist/types/ui/FormFlow.d.ts

@@ -0,0 +1,9 @@
+import type { ConsultationProps, Loaded } from '../Consultation';
+import type { TargetAdapter } from '../types';
+export declare const FormFlow: ({ loaded, adapter, consultationType, submitLabel, onDone, onEvent, queueKey, onConflict, onSaved }: ConsultationProps & {
+    loaded: Loaded;
+    adapter: TargetAdapter | null;
+    queueKey: string;
+    onConflict: () => void;
+    onSaved: () => void;
+}) => import("react").JSX.Element;

package/dist/types/ui/form/Blocks.d.ts

@@ -0,0 +1,6 @@
+import { type FormBlock } from '../../flow/form';
+import { type FieldContext } from './FormField';
+export declare const Block: ({ block, context }: {
+    block: FormBlock;
+    context: FieldContext;
+}) => import("react").JSX.Element;

package/dist/types/ui/form/FormField.d.ts

@@ -0,0 +1,38 @@
+import type { AnswerMap } from '../../flow/answer';
+import { type Answer } from './inputs';
+export interface FieldContext {
+    consultationHash: string;
+    questions: iQuestion[];
+    answers: AnswerMap;
+    optionHashes: AnswerMap;
+    onAnswer: Answer;
+    disabled?: boolean;
+    /** Questions to mark as needing an answer, after a submit that failed the check. */
+    missing: Set<string>;
+    /** The question a failed submit points at. A new tick asks again, so tabs open the one that holds it. */
+    focus: {
+        hash: string;
+        tick: number;
+    } | null;
+}
+export declare const MissingNote: ({ show }: {
+    show: boolean;
+}) => import("react").JSX.Element;
+export declare const getOpenFollowUps: (hash: string, context: FieldContext) => string[];
+/** The open follow-ups of a question, indented under it. */
+export declare const FollowUps: ({ hash, context }: {
+    hash: string;
+    context: FieldContext;
+}) => import("react").JSX.Element;
+/** `spaced` adds the gap a field needs inside a section, where Yes / No rows sit with no gap. */
+export declare const FormField: ({ hash, context, spaced }: {
+    hash: string;
+    context: FieldContext;
+    spaced?: boolean;
+}) => import("react").JSX.Element;
+/** A question as a table cell, with no label of its own. */
+export declare const Cell: ({ hash, column, context }: {
+    hash: string;
+    column: string;
+    context: FieldContext;
+}) => import("react").JSX.Element;

package/dist/types/ui/form/inputs.d.ts

@@ -0,0 +1,28 @@
+import type { AnswerMap, AnswerValue } from '../../flow/answer';
+type OptionLogic = iQuestion['options'][number]['logic'];
+export type Answer = (question: iQuestion, value: AnswerValue, logic: OptionLogic | undefined) => void;
+export interface InputProps {
+    question: iQuestion;
+    answers: AnswerMap;
+    optionHashes: AnswerMap;
+    onAnswer: Answer;
+    disabled?: boolean;
+    /** Names the field for screen readers when no visible label sits next to it, as in a table cell. */
+    label?: string;
+}
+export declare const fieldClass = "w-full rounded-2xl border border-gray-300 bg-white px-4 text-sm font-normal text-gray-900 placeholder:text-gray-400 focus:border-primary-700 focus:ring-primary-700 disabled:opacity-60";
+export declare const plainText: (html: string | undefined) => string;
+/** Options as a joined pair of buttons, such as Yes / No. They are radio inputs, so the keyboard works as usual. */
+export declare const Segmented: ({ question, answers, optionHashes, onAnswer, disabled, label }: InputProps) => import("react").JSX.Element;
+/** A radio question as a dropdown. The native list opens outside the shadow root's styles but works everywhere. */
+export declare const Select: ({ question, answers, optionHashes, onAnswer, disabled, label }: InputProps) => import("react").JSX.Element;
+/** Free text, a phone number or a date. `multiline` draws the tall box used for notes. */
+export declare const TextInput: ({ question, answers, onAnswer, disabled, label, multiline, placeholder }: InputProps & {
+    multiline?: boolean;
+    placeholder?: string;
+}) => import("react").JSX.Element;
+/** Checkbox options as small ticks. A question with one option draws as one tick with its label. */
+export declare const Checks: ({ question, answers, optionHashes, onAnswer, disabled }: InputProps) => import("react").JSX.Element;
+/** Radio options that are not Yes / No, as a list of round buttons. */
+export declare const Radios: ({ question, answers, optionHashes, onAnswer, disabled }: InputProps) => import("react").JSX.Element;
+export {};

package/dist/types/useTargetSave.d.ts

@@ -0,0 +1,30 @@
+import type { Answers, TargetAdapter } from './types';
+export declare const DRAFT_DELAY_MS = 600;
+export type SaveState = 'idle' | 'saving' | 'saved' | 'error';
+export type SubmitState = 'idle' | 'submitting' | 'submitted' | 'error';
+interface Options {
+    adapter: TargetAdapter | null;
+    /** The target's queue key. Its drafts and submits run one after another, and a reload of it waits for them. */
+    queueKey: string;
+    /** Bumped on every change the user makes. */
+    revision: number;
+    /** The answers a draft sends now. */
+    latestDraft: () => Answers;
+    onDone?: () => void;
+    /** Called once a submit has landed, before `onDone`. */
+    onSubmitted?: () => void;
+    /** The server refused a write because the answers changed in another place. */
+    onConflict: () => void;
+    /** A draft or the submit was saved. */
+    onSaved: () => void;
+}
+export declare const errorMessage: (error: unknown) => string;
+export declare function useTargetSave({ adapter, queueKey, revision, latestDraft, onDone, onSubmitted, onConflict, onSaved }: Options): {
+    saveState: SaveState;
+    submitState: SubmitState;
+    submitError: string;
+    saveDraft: () => void;
+    submit: (answers: Answers) => void;
+    rejectSubmit: (message: string) => void;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evaro/consultation-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0-next.0",
   "description": "The Evaro consultation flow as a React component: one question at a time, follow-ups, jumps and the knockout screen.",
   "license": "MIT",
   "publishConfig": {