@clickless/react 0.0.0-stage → 0.1.0

package/dist/hooks/usePromptBar.d.ts

@@ -0,0 +1,163 @@
+export type PromptBarStatus = "idle" | "planning" | "saving";
+/** A sentence about something done, shown to the user. */
+export interface PromptBarMessage {
+    text: string;
+    isError: boolean;
+    /** A second line under `text`, such as the request a restore went back to. */
+    detail?: string;
+}
+/** One request made since the bar was opened, and what came of it. */
+export interface PromptTurn {
+    /**
+     * Empty for sentences said here without a request, kept where they were
+     * said: that a change was saved or the page put back, or what came of an
+     * earlier request's actions once such a sentence came after it. They are in
+     * `outcomes`.
+     */
+    request: string;
+    /**
+     * What the planner answered: what it previewed or is opening, what could not
+     * be done, or a question. Empty when the request was only for changes to
+     * confirm, which the confirmation itself describes.
+     */
+    reply: string;
+    /**
+     * What happened when actions ran, one sentence each. `text` is what the user
+     * is shown. `noteForPlanner` is what later requests tell the planner: the
+     * action's title and how it ended, or `text` for an action with
+     * `shareResultWithPlanner` that ran.
+     */
+    outcomes: (PromptBarMessage & {
+        noteForPlanner: string;
+    })[];
+    /** True once its preview was kept, which puts it in the history of saved changes. */
+    savedAsChange: boolean;
+    /**
+     * The point in the history of saved changes the screen was at when it was
+     * said, in the numbering of `HistoryEntry.revision`, so it can be shown after
+     * the changes saved up to then and before those saved later. For one kept as
+     * a change, the point that change made.
+     */
+    afterRevision: number;
+}
+/**
+ * True when the turn says something the user has not heard yet: a request, or
+ * what came of one's actions. A sentence moved in from the bar's message was
+ * heard when it was said, and tells the planner nothing.
+ */
+export declare function saysSomethingNew(promptTurn: PromptTurn): boolean;
+/**
+ * State and actions for a prompt bar. Use it to build your own, or render `PromptBar`.
+ *
+ * Give several region ids when one screen is made of more than one region,
+ * such as a page and a sidebar every page shares. A prompt is then planned for
+ * all of them at once, and its preview is kept, discarded and undone in all of
+ * them together, while each region's layout is still saved on its own.
+ */
+export declare function usePromptBar(regionId: string | readonly string[]): {
+    prompt: string;
+    setPrompt: (nextPrompt: string | ((previousPrompt: string) => string)) => void;
+    status: PromptBarStatus;
+    /**
+     * A sentence about the last thing done here, such as that a change to the
+     * screen is saved, what an undo took back, or why it failed, with a `detail`
+     * line under it where there is more to say, such as the request a restore
+     * went back to.
+     */
+    message: PromptBarMessage | null;
+    /**
+     * The request sent and still waiting for its answer, so it can be shown at
+     * once rather than when the answer comes. Null otherwise.
+     */
+    requestInProgress: string | null;
+    /**
+     * What to show beside a one-line bar: `message`, or else the answer to the
+     * latest request while it is still the one being looked at, or what came of
+     * its actions. Null when the request was only for changes to confirm.
+     */
+    latestReply: PromptBarMessage | null;
+    /**
+     * Until dismissed: that personalising is not available right now, or how a
+     * saved layout was carried over to a changed screen.
+     */
+    notice: string | null;
+    dismissNotice: () => void;
+    /**
+     * False while the engine cannot be reached, so prompts cannot be carried out.
+     * The page's own controls still work, and their changes are saved later.
+     */
+    available: boolean;
+    previewing: boolean;
+    /** True while the screen shows how it first looked, in place of the user's changes. */
+    showingOriginal: boolean;
+    /** True when the screen differs from how it first looked, so there is an original to see or go back to. */
+    differsFromOriginal: boolean;
+    /**
+     * Shows the screen as it first looked, before any change, without saving
+     * anything, or goes back to the user's changes. A preview, or any change,
+     * ends it. To keep the original, `restoreRevision(0)`.
+     */
+    showOriginal: (shown: boolean) => void;
+    /**
+     * True when there is a change to the screen to undo, and no action has run
+     * since it was made during this visit to the page.
+     */
+    canUndo: boolean;
+    /**
+     * The requests made since the bar was opened, and sentences about what was
+     * done between them, oldest first, leaving out the requests the history of
+     * saved changes shows. One whose preview was kept but
+     * whose actions also ran stays, with `savedAsChange` set: the history shows
+     * the request and the reply, and only what came of the actions is left to show.
+     */
+    promptTurns: PromptTurn[];
+    /** Changes to the application's data that wait for the user to confirm them, or null. */
+    pendingActionCalls: {
+        summary: string;
+    }[] | null;
+    confirmActionCalls: () => void;
+    cancelActionCalls: () => void;
+    /**
+     * What will happen once the preview is kept or discarded, such as opening
+     * another page, or null.
+     */
+    callsAfterPreview: {
+        summary: string;
+    }[] | null;
+    /**
+     * What a past action run did, in a line, without the values it was given.
+     * Null for one that only changed what was shown, which a history of changes leaves out.
+     */
+    describeActionRun: (actionRun: {
+        actionTitle: string;
+        actionMode: "read" | "write";
+    }) => string | null;
+    /**
+     * The engine's numbers for the action runs recorded since the bar was
+     * opened. The conversation shows those, so a list of past runs can leave
+     * them out, and it changes each time one is recorded.
+     */
+    recordedActionRunIds: number[];
+    /** The screen's name for its records, such as its past action runs. */
+    screenId: string;
+    /** True when the page offers actions, so a request may do more than change how it looks. */
+    offersActions: boolean;
+    /** True when an action on the page takes a file, so the user can attach one. */
+    acceptsFiles: boolean;
+    attachedFiles: File[];
+    attachFiles: (newFiles: readonly File[]) => void;
+    removeAttachedFile: (position: number) => void;
+    submitPrompt: (submitOptions?: {
+        viaVoice?: boolean;
+    }) => void;
+    keepPreview: () => void;
+    discardPreview: () => void;
+    undoLastChange: () => void;
+    /**
+     * Returns the screen to how it was after the given saved change. Give the
+     * request that made that change as `restoredRequest`, and the sentence saying
+     * so names it in its `detail`. Resolves to the number of the saved change the
+     * restore made, or null if it did not happen.
+     */
+    restoreRevision: (revision: number, restoredRequest?: string) => Promise<number | null>;
+};

package/dist/hooks/useRegionGroup.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The regions a prompt bar speaks for: one id, or several for a screen made of
+ * more than one region. `regionIdsKey` names the set, for anything that must start
+ * again when the bar is pointed at other regions.
+ */
+export declare function useRegionGroup(regionId: string | readonly string[]): {
+    regionGroup: import("../region/regionGroup.js").RegionGroup;
+    groupSnapshot: import("../region/regionGroup.js").RegionGroupSnapshot;
+    regionIdsKey: string;
+};
+/**
+ * One string naming a set of region ids. An array written in JSX is a new one
+ * on every render, so the ids are compared by value through this.
+ */
+export declare function regionIdsKeyOf(regionId: string | readonly string[]): string;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { AdaptiveProvider, type AdaptiveProviderProps } from "./components/AdaptiveProvider.js";
+export { AdaptiveRegion, type AdaptiveRegionProps } from "./components/AdaptiveRegion.js";
+export type { RegionColumns } from "./region/responsiveColumns.js";
+export { Adaptive, type AdaptiveControls, type AdaptiveProps } from "./components/Adaptive.js";
+export { propPresets, type ColourReading, type CustomPreset, type PresetSet, type PresetValues, type PropPreset, } from "./presets/propPresets.js";
+export { PromptBar, type PromptBarProps } from "./components/PromptBar.js";
+export type { ColorSchemeSetting } from "./components/hostColorScheme.js";
+export { PromptPanel, type DictationButtonProps, type DictationLabels, type PromptPanelPosition, type PromptPanelProps, } from "./components/PromptPanel.js";
+export { AdaptiveAction, type AdaptiveActionProps } from "./components/AdaptiveAction.js";
+export { useAdaptiveAction } from "./hooks/useAdaptiveAction.js";
+export { ActionError, type ActionArgumentValue, type ActionArguments, type ActionDefinition, } from "./actions/actionRegistry.js";
+export { useAdaptiveRegion } from "./hooks/useAdaptiveRegion.js";
+export { usePromptBar, type PromptBarMessage, type PromptBarStatus, type PromptTurn } from "./hooks/usePromptBar.js";
+export { describeHistoryEntry, useChangeHistory, type ChangeHistoryOptions, } from "./hooks/useChangeHistory.js";
+export { useDictation, type DictationOptions, type DictationStatus } from "./hooks/useDictation.js";
+export { EngineError, type EngineOptions } from "./engine/engineClient.js";
+export type { HistoryEntry, UndoneChange } from "./engine/engineResponses.js";
+export type { RegionSnapshot } from "./region/regionSnapshot.js";
+export type { LayoutChangeHandler, UndoResult } from "./region/regionStore.js";
+export { contrastRatio, ensureReadableTextColor, readableTextColor } from "./core/index.js";
+export type { Action, ActionCall, ActionParameter, ApplyOperationsOutcome, Capabilities, Component, Layout, LayoutChange, LayoutItem, Manifest, Operation, OperationError, PropCapabilities, PropValue, } from "./core/index.js";