@clickless/react 0.0.0-stage → 0.1.0

package/dist/actions/actionCalls.d.ts

@@ -0,0 +1,50 @@
+import { type Action, type ActionCall } from "../core/index.js";
+import { type ActionArguments, type ActionDefinition, type RegisteredAction } from "./actionRegistry.js";
+/** An action call checked against what the page offers, ready to confirm or run. */
+export interface PreparedActionCall {
+    registeredAction: RegisteredAction;
+    actionArguments: ActionArguments;
+    /** What the user is asked to confirm, or told is happening. */
+    summary: string;
+    mode: "read" | "write";
+    /**
+     * The action's `run` as it was when the summary was written. What runs is
+     * what the user was shown, even if the component offering it has since
+     * re-rendered for something else, such as another customer's record.
+     */
+    run: ActionDefinition["run"];
+    /** Whether the planner is told what `run` said, as the action opted in when it was offered. */
+    shareResultWithPlanner: boolean;
+    /** Whether a read's result is shown to the user, as the action opted in when it was offered. */
+    showResult: boolean;
+}
+/** Said when the planner asked for an action the page no longer offers as it was. */
+export declare const ACTION_NO_LONGER_AVAILABLE_MESSAGE = "That can't be done on this screen right now.";
+/** Said when the screen changed while a change waited to be confirmed, so it was not made. */
+export declare const SCREEN_CHANGED_BEFORE_CONFIRM_MESSAGE = "This screen changed, so that wasn't done. Please ask again.";
+/**
+ * Checks the planner's calls against the actions on the page now, which may
+ * have changed while it worked, and fills each file parameter with the file
+ * itself. Null when any call no longer fits, or is for an action the page now
+ * declares differently from what the planner was shown, such as a change it
+ * now offers as something that runs at once.
+ */
+export declare function prepareActionCalls(registeredActions: readonly RegisteredAction[], actionCalls: readonly ActionCall[], attachedFiles: readonly File[], declarationsSent: readonly Action[]): PreparedActionCall[] | null;
+/** A parameter's name as words, for a parameter given no description: `phoneNumber` is "phone number". */
+export declare function wordsOfName(parameterName: string): string;
+/**
+ * Runs one call. Resolves to whether it worked, what to tell the user, and
+ * what to tell the planner: the action's title and how it ended, or what the
+ * user was told when the action shares it.
+ */
+export declare function runActionCall(preparedCall: PreparedActionCall): Promise<{
+    done: boolean;
+    text: string;
+    noteForPlanner: string;
+    returnedText: boolean;
+}>;
+/**
+ * What the planner is told of calls that never ran, and why, such as
+ * "cancelled": their titles only, never what the user was shown of them.
+ */
+export declare function describeNotRunForPlanner(preparedCalls: readonly PreparedActionCall[], reason: string): string;

package/dist/actions/actionRegistry.d.ts

@@ -0,0 +1,78 @@
+import type { Action, ActionParameter } from "../core/index.js";
+/** What a file parameter is given when the action runs: the file itself. */
+export type ActionArgumentValue = string | number | boolean | File;
+export type ActionArguments = Record<string, ActionArgumentValue>;
+/** What an application gives to offer one action. */
+export interface ActionDefinition {
+    /** How the planner names it: a letter, then letters, digits or _. Unique on the page. */
+    name: string;
+    /** What users would call it, such as "Change your name". Shown when asking them to confirm. */
+    title: string;
+    /** When to use it, for the planner. */
+    description?: string;
+    /**
+     * `write` (the default) changes something, so the user confirms before it runs.
+     * `read` only changes what is shown, such as opening a page or a tab, and runs
+     * at once. A read action must not change data.
+     */
+    mode?: "read" | "write";
+    /** What it needs, by name. Text, numbers, true or false, or a file the user attached. */
+    parameters?: Record<string, ActionParameter>;
+    /**
+     * The sentence the user confirms, such as "Change your name to Joshua King?".
+     * Without it, the title is shown with each value given.
+     */
+    confirm?: (actionArguments: ActionArguments) => string;
+    /**
+     * Carries the action out, with the user's own sign-in, as your own screens
+     * would. For a `write` action, what it resolves to, if text, is shown to the
+     * user; otherwise "Done.". A `read` action's result is shown only with
+     * `showResult`, since the planner's reply already says what it is showing.
+     * Throw an `ActionError` to show the user why it could not be done, whatever
+     * the mode.
+     */
+    run: (actionArguments: ActionArguments) => unknown;
+    /**
+     * True to tell the planner what `run` resolves to, or the `ActionError`
+     * message, so a later request can build on it ("now email that invoice").
+     * That text then goes to the AI model (Anthropic) with the user's next few
+     * requests. Off by default: the planner is told only the action's title and
+     * whether it was done, failed or was cancelled, while the user still sees
+     * the full sentence.
+     */
+    shareResultWithPlanner?: boolean;
+    /**
+     * For a `read` action: true to show the user the sentence `run` resolves to,
+     * under the planner's reply. A read that resolves to no sentence stays quiet. For a read whose answer the user needs before they
+     * decide, such as the new times a later change in the same request would
+     * use. Off by default, so actions that open or filter a page stay quiet.
+     */
+    showResult?: boolean;
+}
+/** An action as it is offered on the page now. */
+export interface RegisteredAction {
+    declaration: Action;
+    /** The definition as last rendered, so `run` and `confirm` may be inline functions. */
+    definition: () => ActionDefinition;
+}
+/** Thrown from an action's `run` to tell the user, in a sentence, why it could not be done. */
+export declare class ActionError extends Error {
+    constructor(userMessage: string);
+}
+export declare function declarationOf(definition: ActionDefinition): Action;
+/**
+ * The actions offered on the page right now. Each registers while the component
+ * that offers it is mounted, so the planner sees only what the screen can do.
+ */
+export declare class ActionRegistry {
+    private registered;
+    private cachedActions;
+    private listeners;
+    subscribe: (listener: () => void) => (() => void);
+    /** Stable until the actions on offer change. */
+    getActions: () => readonly RegisteredAction[];
+    /** Offers an action until the returned function is called. */
+    register(registeredAction: RegisteredAction): () => void;
+    private changed;
+}
+export declare const getServerActions: () => readonly RegisteredAction[];

package/dist/components/Adaptive.d.ts

@@ -0,0 +1,116 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type ApplyOperationsOutcome, type Capabilities, type LayoutItem, type PropValue } from "../core/index.js";
+import { type PresetSet, type PresetValues } from "../presets/propPresets.js";
+export interface AdaptiveProps<Presets extends PresetSet = PresetSet> {
+    /**
+     * Any name but "__proto__", which a saved layout cannot carry. The same goes
+     * for prop names; note that one written as `{ __proto__: … }` is not an entry
+     * at all in JavaScript, so that prop simply does not exist.
+     */
+    id: string;
+    /** What the component is, in a word: "chart", "table", "card". Shown to the model. */
+    kind?: string;
+    /**
+     * Human name, as a user would refer to it. Shown to the model, and to the
+     * user in what the panel says. Without one the model is given the id, and
+     * the user is told of "a section".
+     */
+    title?: string;
+    description?: string;
+    /** A locked component cannot be changed by any operation. */
+    locked?: boolean;
+    /**
+     * Names the items that share one container of the page, such as the cards
+     * of one tab or the links of one menu. Items are put in order only among
+     * those with the same group, and a request to move one to another group is
+     * refused with an explanation. Items without one form a group of their own.
+     * In a region with `grid={false}`, only items with a group can be moved.
+     */
+    group?: string;
+    /**
+     * How users may arrange the component. Anything not declared is refused.
+     *
+     * - `move`, `hide`: on unless set to false. Moving is off for an item with no
+     *   `group` in a region with `grid={false}`.
+     * - `resize`: `{ minW, maxW, minH, maxH }`, in columns and rows. Off unless given.
+     *
+     * Settings users may change, such as a colour or which columns show, are
+     * declared in `presets`.
+     */
+    capabilities?: Partial<Omit<Capabilities, "props">>;
+    /**
+     * `w` and `h` are the item's width in columns and height in rows. Give both
+     * or neither: they are needed in a region's grid, and an item without them,
+     * such as a button or a menu, is sized by the page and cannot be resized.
+     */
+    defaults?: Partial<Pick<LayoutItem, "w" | "h" | "hidden">>;
+    /**
+     * The settings users may change, from `propPresets`, each under a name of your
+     * choosing. Use a built-in one when it fits, such as `{ rows: propPresets.density() }`;
+     * otherwise a custom one, such as
+     * `{ view: propPresets.choice({ values: ["day", "week"], initial: "week", means: "how much shows at once" }) }`.
+     * Each brings its starting value and a sentence telling the model what it means,
+     * added after `description`. A render-function child receives each one's current
+     * value under the same name, as its third argument: ClickLess stores the value,
+     * and what it changes on screen is up to you.
+     *
+     * @example
+     * <Adaptive id="pipeline" title="Sales pipeline" defaults={{ w: 8, h: 4 }}
+     *   presets={{ accent: propPresets.accent({ marks: "the deal that is due soonest" }) }}>
+     *   {(props, adaptiveControls, presetValues) => <PipelineBoard accentColor={presetValues.accent} />}
+     * </Adaptive>
+     */
+    presets?: Presets;
+    className?: string;
+    /**
+     * Styles for the item's wrapper. `gridColumn` and `gridRow` are set by the
+     * layout for an item with a size, `order` for an item in a region's grid or
+     * in a group that has been moved, and `display` while the item is hidden,
+     * so those are not taken from here.
+     */
+    style?: CSSProperties;
+    /**
+     * Set when the component outlines the parts a change reaches itself, with
+     * `changeOutline`. Its own outline is then kept for what changes the whole
+     * section: hiding, moving or resizing it.
+     */
+    marksChanges?: boolean;
+    /**
+     * Pass a function to receive the stored value of every prop the presets
+     * declare, under its prop name (the name `setProp` takes), controls for
+     * changing them from your own UI, and the current value of each preset in
+     * `presets`, under the name given there.
+     */
+    children: ReactNode | ((props: Record<string, PropValue>, adaptiveControls: AdaptiveControls, presetValues: PresetValues<Presets>) => ReactNode);
+}
+export interface AdaptiveControls {
+    /**
+     * Changes one of this component's props, as a prompt would: it is validated,
+     * saved for the user and can be undone. Use it for controls you build
+     * yourself, such as a column picker. Unlike a prompt's change, it takes effect
+     * at once, without waiting for the engine, and its promise resolves at once:
+     * it is saved behind the scenes, later if the engine cannot be reached.
+     * Resolving means the change is shown, not saved: it is kept for the visit
+     * only if it clashes with the user's saved layout or the engine refuses it.
+     * `hasUnsavedChanges` from `useAdaptiveRegion` says whether any change is
+     * still waiting to be saved.
+     */
+    setProp: (propName: string, propValue: PropValue) => Promise<ApplyOperationsOutcome>;
+    /**
+     * Whether a preview, or the original while "See original" shows it, draws
+     * one of this component's props differently from the user's version. Give
+     * the prop's name, or the name of a preset in `presets` for all of its props. With
+     * `entry`, whether that entry of a list prop is new there or had to move,
+     * such as one column of a table. False when neither is showing.
+     */
+    isChanged: (propName: string, entry?: string) => boolean;
+    /**
+     * The outline a changed section gets, for the part of this component that
+     * shows `propName`, or one `entry` of it, where `isChanged` says it changed,
+     * and nothing elsewhere. Pass it to that part's own `style`, such as
+     * `<th style={adaptiveControls.changeOutline("columns", column)}>`, and set
+     * `marksChanges` on the component.
+     */
+    changeOutline: (propName: string, entry?: string) => CSSProperties | undefined;
+}
+export declare function Adaptive<Presets extends PresetSet = PresetSet>({ id, kind, title, description: ownDescription, locked, group, capabilities: ownCapabilities, defaults: ownDefaults, presets, className, style, marksChanges, children, }: AdaptiveProps<Presets>): import("react").JSX.Element;

package/dist/components/AdaptiveAction.d.ts

@@ -0,0 +1,4 @@
+import type { ActionDefinition } from "../actions/actionRegistry.js";
+export type AdaptiveActionProps = ActionDefinition;
+/** `useAdaptiveAction` as a component, for offering an action from JSX. Renders nothing. */
+export declare function AdaptiveAction(props: AdaptiveActionProps): null;

package/dist/components/AdaptiveProvider.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import type { EngineOptions } from "../engine/engineClient.js";
+import { type ColorSchemeSetting } from "./hostColorScheme.js";
+export interface AdaptiveProviderProps {
+    /**
+     * Who is signed in: the user id your backend puts in the token's `sub`.
+     * When it changes, everything inside the provider is mounted afresh, so
+     * nothing the last user typed or changed is shown to the next one. A token
+     * `getToken` gives for anyone else is never sent, so nothing the last user
+     * left unsaved is saved to the next one's account, even when signing out
+     * shows a page without ClickLess. A provider is for one tenant too: where
+     * someone can switch tenant without a reload, give the provider the tenant
+     * as its `key`.
+     */
+    userId: string;
+    /**
+     * Connects regions to the ClickLess engine, which stores each user's layout
+     * and plans changes from prompts. Read once for each signed-in user. Without it,
+     * layouts live in memory and `onLayoutChange` is the only way to persist them.
+     */
+    engine?: EngineOptions;
+    /**
+     * Regions whose saved layouts are read from the engine as soon as the
+     * provider mounts, before they are on the screen, such as a sidebar that a
+     * phone only draws once its menu is opened. Each then shows its saved layout
+     * the moment it mounts, rather than its default for as long as the read
+     * takes. A region not listed is read when it first mounts. Read once for
+     * each signed-in user, like `engine`.
+     */
+    preloadRegions?: readonly string[];
+    /**
+     * The colours of every PromptPanel and PromptBar inside that sets none of
+     * its own: "light", "dark", or "auto" (the default) to follow the page.
+     */
+    colorScheme?: ColorSchemeSetting;
+    children: ReactNode;
+}
+export declare function AdaptiveProvider({ userId, colorScheme, ...signedInUserProviderProps }: AdaptiveProviderProps): import("react").JSX.Element;

package/dist/components/AdaptiveRegion.d.ts

@@ -0,0 +1,60 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type Layout } from "../core/index.js";
+import type { LayoutChangeHandler } from "../region/regionStore.js";
+import { type RegionColumns } from "../region/responsiveColumns.js";
+export interface AdaptiveRegionProps {
+    id: string;
+    /**
+     * Bump when a release changes the set of components or their capabilities.
+     * Components that merely come and go while the application runs, such as
+     * the content of a tab, need nothing: what the user set on them is kept
+     * while they are off screen.
+     */
+    version: string;
+    /**
+     * Whether the region lays its items out in a grid of its own, as it does
+     * unless told otherwise. With `false` it draws nothing of its own: each item
+     * stays in whichever of your containers it is written in, such as a header,
+     * a menu or your own card grid, and the region can span all of them. Items
+     * that share a container are given the same `group`, and only items with a
+     * group can be moved. `className` and `style` are not used then.
+     */
+    grid?: boolean;
+    /**
+     * Columns in the region's grid. With `grid={false}`, the columns of your own
+     * grids that items with a size sit in, which is as wide as they can be made.
+     *
+     * For a grid that has fewer columns on narrow screens, give the columns from
+     * each screen width up, in pixels, such as `{ 0: 1, 768: 12 }`. Users arrange
+     * the widest grid; a narrower screen draws that arrangement in its own
+     * columns, each item keeping its share of the width, so a change made on a
+     * phone keeps what was set for a wide screen. With `grid={false}`, use the
+     * same widths and columns as your own grids.
+     */
+    columns?: RegionColumns;
+    /**
+     * What users call this part of the screen, such as "Sidebar". Give one to
+     * each region when a prompt bar speaks for several, so that "in the sidebar"
+     * is understood and replies can say where a change was made.
+     */
+    title?: string;
+    /**
+     * Height of one row of the grid, in pixels, or `"auto"` for rows as tall as
+     * their content, such as a table whose height follows its rows.
+     */
+    rowHeight?: number | "auto";
+    /** Gap between items, in pixels. */
+    gap?: number;
+    /**
+     * The user's saved layout. Read once, when the region first mounts. One that
+     * cannot be read is ignored and the default is shown. With an engine it is
+     * only what shows until the engine's own copy arrives, which then replaces it.
+     */
+    initialLayout?: Layout;
+    /** Called after every committed change. Persist the layout here. */
+    onLayoutChange?: LayoutChangeHandler;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+export declare function AdaptiveRegion({ id, version, grid, columns, title, rowHeight, gap, initialLayout, onLayoutChange, className, style, children, }: AdaptiveRegionProps): import("react").JSX.Element;

package/dist/components/ClicklessUiErrorBoundary.d.ts

@@ -0,0 +1,24 @@
+import { Component, type ReactNode } from "react";
+interface ClicklessUiErrorBoundaryProps {
+    children: ReactNode;
+    /** When this changes, a panel or bar that failed to draw is tried again: it now speaks for other regions. */
+    resetKey: string;
+}
+interface ClicklessUiErrorBoundaryState {
+    drawingFailed: boolean;
+    /** The `resetKey` of the last drawing, failed or not. */
+    drawnForKey: string;
+}
+/**
+ * Draws nothing in place of the SDK's own panel or bar if drawing it in the
+ * browser fails, so a fault there never takes the host's page down with it.
+ * The page, its own controls and its layouts go on working. React reports the
+ * fault. Pointing the panel or bar at other regions tries drawing it again.
+ */
+export declare class ClicklessUiErrorBoundary extends Component<ClicklessUiErrorBoundaryProps, ClicklessUiErrorBoundaryState> {
+    state: ClicklessUiErrorBoundaryState;
+    static getDerivedStateFromError(): Partial<ClicklessUiErrorBoundaryState>;
+    static getDerivedStateFromProps(props: ClicklessUiErrorBoundaryProps, state: ClicklessUiErrorBoundaryState): Partial<ClicklessUiErrorBoundaryState> | null;
+    render(): ReactNode;
+}
+export {};

package/dist/components/OriginalToolbar.d.ts

@@ -0,0 +1,21 @@
+export interface OriginalToolbarProps {
+    showingOriginal: boolean;
+    differsFromOriginal: boolean;
+    /** True when the original can be put back, which needs a history kept by the engine. */
+    canRevert: boolean;
+    isBusy: boolean;
+    previewing: boolean;
+    showOriginal: (shown: boolean) => void;
+    revertToOriginal: () => void;
+    /** Wraps each button's click handler, so the focus is not lost when the button goes. */
+    thenKeepFocus: (buttonAction: () => void) => (event: {
+        currentTarget: HTMLElement;
+    }) => void;
+}
+/**
+ * The bar pinned under the panel's title, so going back to the start never
+ * means scrolling to the top of a long history. It offers a look at how the
+ * screen first looked and a way to put that back; during the look, it says so
+ * and offers the way out of it.
+ */
+export declare function OriginalToolbar({ showingOriginal, differsFromOriginal, canRevert, isBusy, previewing, showOriginal, revertToOriginal, thenKeepFocus, }: OriginalToolbarProps): import("react").JSX.Element | null;

package/dist/components/PromptBar.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties } from "react";
+import { type ColorSchemeSetting } from "./hostColorScheme.js";
+export interface PromptBarProps {
+    /**
+     * The region the bar changes. Give several ids when the screen is made of
+     * more than one region, such as a page and a shared sidebar: one prompt is
+     * then planned, previewed, kept and undone across all of them.
+     * A list may name up to 8 regions.
+     */
+    regionId: string | readonly string[];
+    placeholder?: string;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * The colours it is drawn in: "light", "dark", or "auto" to follow the page.
+     * Default: AdaptiveProvider's `colorScheme`, which is "auto" unless set.
+     */
+    colorScheme?: ColorSchemeSetting;
+}
+/** A ready-made prompt bar. For a custom one, use `usePromptBar`. */
+export declare function PromptBar(props: PromptBarProps): import("react").JSX.Element;

package/dist/components/PromptPanel.d.ts

@@ -0,0 +1,103 @@
+import { type ReactNode } from "react";
+import { type ColorSchemeSetting } from "./hostColorScheme.js";
+/** The wording of the microphone button and of what replaces it while the user speaks. */
+export interface DictationLabels {
+    /** The microphone button's name, read out by screen readers and shown on hover. */
+    speak: string;
+    /** Shown while the browser hands over the microphone. */
+    starting: string;
+    /** Shown while the user is speaking. */
+    listening: string;
+    /** Shown while what they said is turned into text. */
+    transcribing: string;
+    /** The button that ends the recording and keeps it. */
+    done: string;
+    /** The button that throws the recording away. */
+    cancel: string;
+}
+/** What a microphone button of your own is given by `renderDictationButton`. */
+export interface DictationButtonProps {
+    /** Asks for the microphone and starts recording. */
+    start: () => void;
+    /** True while the panel is working on something else, when speaking cannot begin. */
+    disabled: boolean;
+    /** The button's name, from `dictationLabels.speak`. */
+    label: string;
+}
+type VerticalEdge = "bottom" | "top";
+type HorizontalEdge = "right" | "left";
+/** The corner of the screen the panel's button sits in. */
+export type PromptPanelPosition = `${VerticalEdge}-${HorizontalEdge}`;
+export interface PromptPanelProps {
+    /**
+     * The region the panel changes. Give several ids when the screen is made of
+     * more than one region, such as a page and a sidebar every page shares:
+     * `regionId={["dashboard", "sidebar"]}`. One prompt is then planned across
+     * all of them, and its preview is kept, discarded and undone in all of them
+     * together, while each region's layout is still saved on its own. A region
+     * that is not on the screen is left out until it is.
+     * A list may name up to 8 regions.
+     */
+    regionId: string | readonly string[];
+    /**
+     * The corner of the screen the button sits in. The panel opens from the same
+     * corner: above the button at the bottom of the screen, below it at the top.
+     * Default "bottom-right". Any other value is treated as "bottom-right". To
+     * move the button in from the edges, for example
+     * clear of a tab bar, set `--clickless-launcher-offset-x` and
+     * `--clickless-launcher-offset-y` to a length with its unit: `0px`, not `0`.
+     */
+    position?: PromptPanelPosition;
+    /**
+     * Text on the button that opens the panel. While a preview is waiting and
+     * the panel is minimised, the button reads "Keep or discard?" instead, and
+     * "Seeing original" while the screen shows how it first looked. While
+     * personalising is not available the button is dimmed, and still opens the
+     * panel, which says why and can still undo.
+     */
+    label?: string;
+    /** The panel's heading, and its name for screen readers. */
+    title?: string;
+    placeholder?: string;
+    /** How many past changes to show at first, and to load each time. */
+    pageSize?: number;
+    defaultOpen?: boolean;
+    /**
+     * Close the panel when the user clicks elsewhere on the page. Default true.
+     * A click elsewhere, like the Escape key, is easy to do by accident, so
+     * neither closes it while a preview is waiting, because Keep and Discard are
+     * in it. Nor does a click elsewhere while the user is in the middle of a
+     * request: while one is being worked on, while there is one in the box, or
+     * while the answer to the latest one is showing, as when it says to open a
+     * tab on the page and ask again. The Minimise button and the button that
+     * opened it always do.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Offer a microphone button for speaking a request. It appears only when the
+     * engine is set up to turn speech into text and the browser can record.
+     * What the user says goes to the engine's speech-to-text provider, so it is
+     * off unless you turn it on.
+     */
+    dictation?: boolean;
+    /** Replaces any of the microphone's wording. What is left out keeps its default. */
+    dictationLabels?: Partial<DictationLabels>;
+    /**
+     * Draws the microphone button in place of the built-in one, in the same spot
+     * and only when the built-in one would show, so it needs `dictation` too.
+     * Give your button `props.label` as its accessible name.
+     */
+    renderDictationButton?: (props: DictationButtonProps) => ReactNode;
+    /**
+     * The colours it is drawn in: "light", "dark", or "auto" to follow the page.
+     * Default: AdaptiveProvider's `colorScheme`, which is "auto" unless set.
+     */
+    colorScheme?: ColorSchemeSetting;
+}
+/**
+ * A button that stays in the corner of the screen and opens a panel for
+ * describing changes, with the user's past changes above the prompt. The page
+ * stays usable beside it, so a preview can be seen while deciding.
+ */
+export declare function PromptPanel(props: PromptPanelProps): import("react").JSX.Element;
+export {};

package/dist/components/WorkingDots.d.ts

@@ -0,0 +1,4 @@
+/** What a request shows while its answer is being worked out. */
+export declare const WORKING_WORDING = "Working on it\u2026";
+/** Three dots that light up in turn, drawn inline because the SDK ships no stylesheet. Still for reduced motion. */
+export declare function WorkingDots(): import("react").JSX.Element;

package/dist/components/focusAfterPromptAction.d.ts

@@ -0,0 +1,15 @@
+import { type RefObject } from "react";
+/**
+ * Keeps the keyboard focus somewhere once a button of the panel or bar has
+ * done its work. Keep, Discard, Undo, OK and Restore can leave the page when
+ * used, which would drop the focus on the page's body: it goes back to the
+ * button if that is still there, else to the prompt box. A user who has moved
+ * on to something else meanwhile keeps their place, and a press or focus
+ * anywhere else forgets the button, so a later render never moves the focus.
+ *
+ * `actionsSettled` is true while nothing a button began is still under way.
+ * Returns a wrapper for a button's click handler.
+ */
+export declare function useFocusAfterPromptAction(promptInput: RefObject<HTMLElement | null>, actionsSettled: boolean): (buttonAction: () => void) => (event: {
+    currentTarget: HTMLElement;
+}) => void;

package/dist/components/hostColorScheme.d.ts

@@ -0,0 +1,35 @@
+import { type CSSProperties } from "react";
+export type ColorScheme = "light" | "dark";
+/** The panel's and bar's colours: always light, always dark, or "auto" to follow the page. */
+export type ColorSchemeSetting = ColorScheme | "auto";
+/** The setting AdaptiveProvider gives every panel and bar inside it that sets none of its own. */
+export declare const ColorSchemeSettingContext: import("react").Context<ColorSchemeSetting>;
+/**
+ * The built-in colours for a scheme, to set on the outermost element of the
+ * panel or bar. Every colour there is written as the page's own
+ * --clickless-<name> if it sets one, else --clickless-built-in-<name>, else the
+ * light colour, so a page that maps the colours itself keeps them.
+ */
+export declare function builtInColorVariables(colorScheme: ColorScheme): CSSProperties;
+/**
+ * The colours a panel or bar is drawn in: its own `colorScheme`, else its
+ * provider's, else, for "auto" or anything not understood, the page's.
+ *
+ * The page's is whether it is drawn dark, so the panel can match it without
+ * being told, followed as it changes. It is read from the page's own
+ * background, which is how a page shows its theme whichever way it switches
+ * it (a class, an attribute, the system setting). A page that paints no
+ * background on <html> or <body> is read from a theme attribute or class
+ * there, its `color-scheme`, or the background in the middle of the screen,
+ * and the system setting only when none of them says. Light for a page that
+ * sets any of the colours on its root or body. The server, and the first
+ * paint, assume light unless the colours are chosen.
+ */
+export declare function usePanelColorScheme(colorScheme: ColorSchemeSetting | undefined): ColorScheme;
+/**
+ * How light a computed colour looks, from 0 to 1, or null when it is
+ * transparent or in a form not read here. Browsers give computed colours as
+ * rgb(), or in the space they were written in, such as oklch() for a page that
+ * uses Tailwind 4.
+ */
+export declare function lightnessOf(cssColor: string): number | null;

package/dist/components/promptPanelStyles.d.ts

@@ -0,0 +1,14 @@
+import type { CSSProperties } from "react";
+export declare const borderStyle = "1px solid var(--clickless-border, var(--clickless-built-in-border, #d6d3cb))";
+export declare const surfaceColor = "var(--clickless-surface, var(--clickless-built-in-surface, #fff))";
+export declare const mutedColor = "var(--clickless-muted, var(--clickless-built-in-muted, #52514e))";
+export declare const dangerColor = "var(--clickless-danger, var(--clickless-built-in-danger, #a82a2a))";
+export declare const recordingColor = "var(--clickless-recording, var(--clickless-danger, var(--clickless-built-in-danger, #a82a2a)))";
+export declare const controlStyle: CSSProperties;
+export declare const buttonStyle: CSSProperties;
+export declare const primaryButtonStyle: CSSProperties;
+export declare const linkButtonStyle: CSSProperties;
+export declare const userBubbleStyle: CSSProperties;
+export declare const replyBubbleStyle: CSSProperties;
+export declare const historyEntryDetailsStyle: CSSProperties;
+export declare const attachmentChipStyle: CSSProperties;

package/dist/core/applyOperations.d.ts

@@ -0,0 +1,21 @@
+import type { Layout, Manifest, Operation } from "./schemas.gen.js";
+import { type OperationError } from "./validateOperations.js";
+export type ApplyOperationsOutcome = {
+    applied: true;
+    layout: Layout;
+} | {
+    applied: false;
+    errors: OperationError[];
+};
+/**
+ * Validates the whole list, then applies it in order. Nothing is applied if any
+ * operation is invalid, or if the result would leave nothing showing in a
+ * region that showed something (see `findEmptyRegionFailure`). The input
+ * layout is never mutated.
+ *
+ * Throws if the layout's `order` and `items` do not hold exactly the manifest's
+ * components, which means it was not reconciled against this manifest. What
+ * the layout keeps in `offScreen` is carried through untouched, except that
+ * resetting the whole region drops it.
+ */
+export declare function applyOperations(manifest: Manifest, layout: Layout, operations: readonly Operation[]): ApplyOperationsOutcome;

package/dist/core/colorContrast.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The WCAG contrast ratio between two hex colours, from 1 (identical) to
+ * 21 (black on white). Returns 1 if either value is not a hex colour.
+ */
+export declare function contrastRatio(firstColour: string, secondColour: string): number;
+/**
+ * Black or white, whichever is easier to read on the given background.
+ * Use it for text drawn over a colour the user chose. Anything that is not a
+ * hex colour, such as `rgb(...)` or a colour name, is treated as a light
+ * background.
+ */
+export declare function readableTextColor(backgroundColour: string): "#000000" | "#ffffff";
+/**
+ * A text colour the user chose, kept only where it can be read. Returns
+ * `textColour` if it contrasts enough with `backgroundColour`, and otherwise black or
+ * white, whichever reads better. A background that is not a hex colour cannot
+ * be judged, so `textColour` is returned as it is.
+ *
+ * `minimumContrastRatio` defaults to 4.5, the WCAG AA ratio for body text. Use
+ * 3 for large or bold text.
+ */
+export declare function ensureReadableTextColor(textColour: string, backgroundColour: string, minimumContrastRatio?: number): string;