@k2b/ui 0.40.0 → 0.41.0

package/dist/types/chat/ChatComposer.d.ts

@@ -1,4 +1,5 @@
 import { type JSX } from "solid-js";
+import type { DictationAlternative, DictationSource } from "../inputs/dictation/types";
 import type { ChatAction, ChatAttachment, ChatComposerEmoji, ChatComposerMicrophone, ChatComposerState, ChatContextUsageData, ChatMention, ChatModelOption, ChatSubmitInput } from "./types";
 export type ChatCommandContext = {
     setValue: (value: string) => void;
@@ -237,6 +238,14 @@ export type ChatComposerProps = {
     emoji?: ChatComposerEmoji;
     /** A microphone at a fixed place: a tap dictates, holding it or its menu asks for a voice message. */
     microphone?: ChatComposerMicrophone;
+    /**
+     * Live dictation at the microphone's place, before Send. A press starts it; while it runs, the dictation bar stands in
+     * for the footer and the words land at the caret, also when the person types elsewhere. Sending waits until it ended.
+     */
+    dictation?: {
+        source: DictationSource;
+        alternative?: DictationAlternative;
+    };
     /** One line above the field. The conversation variant always keeps its height; the default shows it only with content. */
     hint?: JSX.Element;
     /**

package/dist/types/inputs/SpecialInputs.d.ts

@@ -18,4 +18,12 @@ export type IconInputProps = ValueFieldProps<string | null> & {
     gridSize?: SelectGridSize;
     name?: string;
 };
+/**
+ * Every query word has to appear in the icon's names or keywords: as the start
+ * of a word, or anywhere in one once it has three letters, so German compounds
+ * such as "Kreditkarte" match "karte". A loose subsequence match let "gro" find
+ * "warninG eRrOr", so it is not used. Ranked by where the query hits: the label
+ * start, a label word, a keyword, then anywhere.
+ */
+export declare const searchIconOptions: <T extends IconOption>(source: readonly T[], query: string, limit: number) => T[];
 export declare function IconInput(props: IconInputProps): JSX.Element;

package/dist/types/inputs/dictation/Dictation.d.ts

@@ -0,0 +1,26 @@
+import { type JSX } from "solid-js";
+import { type DictationController } from "./create-dictation";
+/** Whether the bar stands in for the host's controls: while dictating, finishing, or showing a bar notice. */
+export declare const dictationBarShown: (dictation: DictationController) => boolean;
+export type DictationButtonProps = {
+    dictation: DictationController;
+    size?: "xs" | "sm";
+    class?: string;
+    /** The box the notice cards line up with, such as the whole composer; defaults to the button. */
+    cardAnchor?: () => HTMLElement | undefined;
+};
+/**
+ * The microphone at its fixed place. A press starts live dictation; offline it stays focusable and says why it waits.
+ * Notices that need a decision, such as a blocked microphone or a used-up allowance, open as cards above it.
+ */
+export declare function DictationButton(props: DictationButtonProps): JSX.Element;
+export type DictationBarProps = {
+    dictation: DictationController;
+    class?: string;
+};
+/**
+ * The row that stands in for the host's controls while dictating, at the same place and height: Discard, level, time,
+ * microphone and Stop; then "Finishing …" until the last words arrived; and a notice with "Continue" when the session
+ * ended early. Render it where `dictationBarShown()` is true. Escape stops, after closing an open menu.
+ */
+export declare function DictationBar(props: DictationBarProps): JSX.Element;

package/dist/types/inputs/dictation/create-dictation.d.ts

@@ -0,0 +1,77 @@
+import { type Accessor } from "solid-js";
+import type { DictationAlternative, DictationDevice, DictationSource, DictationTarget } from "./types";
+export type DictationStatus = "idle" | "starting" | "live" | "finishing";
+/**
+ * What stays visible after a session could not start or ended on its own. `interrupted` and `ended` replace the bar,
+ * so "Continue" writes on at the same mark; the others are cards at the microphone.
+ */
+export type DictationNotice = {
+    kind: "blocked";
+} | {
+    kind: "unavailable";
+} | {
+    kind: "not_available";
+} | {
+    kind: "quota";
+    resetsAt?: string;
+} | {
+    kind: "overloaded";
+} | {
+    kind: "elsewhere";
+} | {
+    kind: "interrupted";
+} | {
+    kind: "ended";
+    reason: "max_duration" | "silence";
+    maxMs: number;
+};
+export type DictationOptions = {
+    source: DictationSource;
+    target: DictationTarget;
+    /** Offered beside "Try again" when live dictation is busy. */
+    alternative?: DictationAlternative;
+    /** While true, dictation cannot start, such as in a read-only field; the host calls `end()` when it turns true. */
+    disabled?: () => boolean;
+};
+export type DictationController = {
+    status: Accessor<DictationStatus>;
+    /** Dictating, starting, or finishing: the bar stands in for the host's controls. */
+    active: Accessor<boolean>;
+    notice: Accessor<DictationNotice | null>;
+    /** Recent levels from 0 to 1, newest last. */
+    levels: Accessor<readonly number[]>;
+    elapsedMs: Accessor<number>;
+    maxMs: Accessor<number>;
+    offline: Accessor<boolean>;
+    device: Accessor<DictationDevice | undefined>;
+    deviceId: Accessor<string | undefined>;
+    devices: Accessor<readonly DictationDevice[]>;
+    loadDevices(): Promise<void>;
+    chooseDevice(id: string): void;
+    alternative?: DictationAlternative;
+    start(): void;
+    stop(): Promise<void>;
+    /** Ends the session at once and removes only the text it inserted. */
+    discard(): void;
+    /** Closes a notice; the text stays. */
+    dismiss(): void;
+    /** Ends any session at once and closes the dictation; the text stays. For a field that changes or turns read-only. */
+    end(): void;
+    /** Whether dictation may start now. */
+    disabled: Accessor<boolean>;
+    /** Elements that receive focus: the microphone after the end, the stop button after the start. */
+    bind(role: "microphone" | "stop" | "continue", element: HTMLElement | undefined): void;
+};
+/** Bar notices stand where the bar was; card notices open at the microphone. */
+export declare const isBarNotice: (notice: DictationNotice | null) => notice is {
+    kind: "interrupted";
+} | {
+    kind: "ended";
+    reason: "max_duration" | "silence";
+    maxMs: number;
+};
+/**
+ * The state of one dictation place: which session runs, what its bar shows, and the notice it leaves. Render it with
+ * `DictationButton` and `DictationBar`; the target decides where text lands. One controller runs one session at a time.
+ */
+export declare function createDictation(options: DictationOptions): DictationController;

package/dist/types/inputs/dictation/dictation-messages.d.ts

@@ -0,0 +1,54 @@
+export declare const dictationMessages: import("@k2b/stdlib").Catalog<{
+    dictate: string;
+    dictateOffline: string;
+    offline: string;
+    discard: string;
+    stop: string;
+    running: string;
+    finishingGroup: string;
+    finishing: string;
+    starting: string;
+    ended: string;
+    discarded: string;
+    microphone: string;
+    microphoneNamed: ({ name }: {
+        name: string;
+    }) => string;
+    systemDefault: string;
+    interrupted: string;
+    interruptedShort: string;
+    maxDone: ({ minutes }: {
+        minutes: number;
+    }) => string;
+    maxDoneShort: ({ minutes }: {
+        minutes: number;
+    }) => string;
+    silenceDone: string;
+    silenceDoneShort: string;
+    continue: string;
+    dismiss: string;
+    blockedTitle: string;
+    blockedBody: string;
+    blockedStep1: string;
+    blockedStep2: string;
+    retry: string;
+    quotaTitle: string;
+    quotaBody: ({ time }: {
+        time: string;
+    }) => string;
+    quotaBodyTomorrow: ({ time }: {
+        time: string;
+    }) => string;
+    overloadedTitle: string;
+    overloadedBody: string;
+    elsewhereTitle: string;
+    elsewhereBody: string;
+    unavailableTitle: string;
+    unavailableBody: string;
+    notAvailableTitle: string;
+    notAvailableBody: string;
+    ok: string;
+    timeLeft: ({ time }: {
+        time: string;
+    }) => string;
+}>;

package/dist/types/inputs/dictation/text-dictation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dictation into plain text, such as a textarea: a mark where the next words land and the ranges dictation inserted.
+ * Both follow edits the person makes anywhere else, so typing elsewhere never moves the dictated text.
+ */
+export type TextDictationState = {
+    mark: number;
+    /** Inserted ranges, as UTF-16 offsets into the current text, in order. */
+    ranges: readonly (readonly [number, number])[];
+    /** Whether the next insert is the first of a session, which adjusts the space before it. */
+    fresh: boolean;
+};
+export declare const beginTextDictation: (mark: number) => TextDictationState;
+/** Where `offset` lands after `previous` became `next`; `after` keeps it behind text inserted exactly at it. */
+export declare const mapTextOffset: (previous: string, next: string, offset: number, after: boolean) => number;
+/** Follow an edit that dictation did not make. Ranges that the edit removed entirely disappear. */
+export declare const mapTextDictation: (state: TextDictationState, previous: string, next: string) => TextDictationState;
+/** Append `text` at the mark. The first words of a session get one space from earlier text, never two. */
+export declare const insertTextDictation: (state: TextDictationState, value: string, text: string) => {
+    state: TextDictationState;
+    value: string;
+};
+/** Remove every dictated range; text that was there before stays. */
+export declare const discardTextDictation: (state: TextDictationState, value: string) => {
+    value: string;
+    caret: number;
+};
+/**
+ * Split highlight segments of a field's text at the newest dictated words and the mark, for an overlay that tints the
+ * fresh words and shows where the next ones land. A mark arrives as an empty segment.
+ */
+export declare const splitDictationSegments: <T extends {
+    text: string;
+}>(segments: readonly T[], fresh: readonly (readonly [number, number])[], mark: number | undefined) => (T & {
+    fresh?: boolean;
+    mark?: boolean;
+})[];

package/dist/types/inputs/dictation/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A speech-to-text stream as dictation consumes it. The library knows no server: an application passes a source, such
+ * as one that relays the microphone to a speech model, and a target that places the text.
+ */
+export type DictationErrorCode = "not_configured" | "no_access" | "daily_limit" | "overloaded" | "busy_elsewhere" | "provider_failed" | "connection_lost" | "microphone_blocked" | "microphone_unavailable";
+export type DictationDevice = {
+    id: string;
+    label: string;
+};
+/** Why a session ended on its own; the text so far stays. */
+export type DictationEndReason = "max_duration" | "silence" | "daily_limit";
+export type DictationEvent = {
+    type: "state";
+    state: "connecting";
+} | {
+    type: "state";
+    state: "live";
+    maxMs: number;
+    device?: DictationDevice;
+} | {
+    type: "state";
+    state: "finishing";
+} | {
+    type: "state";
+    state: "finished";
+    reason?: DictationEndReason;
+}
+/** 0 to 1, about every 100 ms while live. */
+ | {
+    type: "level";
+    level: number;
+}
+/** New text to append at the dictation mark; earlier text is never revised. */
+ | {
+    type: "text";
+    text: string;
+} | {
+    type: "error";
+    code: DictationErrorCode;
+    retryable: boolean;
+    resetsAt?: string;
+};
+export type DictationSession = {
+    /** Ends after `finished` or `error`, or without further events once the start signal aborted. */
+    events: AsyncIterable<DictationEvent>;
+    /** Regular stop: resolves after `finished` or an error, so the last words arrive before it. */
+    stop(): Promise<void>;
+};
+export type DictationSource = {
+    /** Aborting `signal` closes the microphone and the connection at once, for discarding or leaving the page. */
+    start(options: {
+        deviceId?: string;
+        signal: AbortSignal;
+    }): DictationSession;
+    /** Microphones with their names; names may be empty before the first permission. */
+    devices(): Promise<DictationDevice[]>;
+};
+/**
+ * Where dictated text lands. `begin` starts each session: the first one remembers the insertion point, later ones of
+ * the same dictation write on at it. `insert` appends at the mark, `discard` removes exactly the inserted text, and
+ * `end` closes the dictation; the text stays.
+ */
+export type DictationTarget = {
+    begin(): void;
+    insert(text: string): void;
+    discard(): void;
+    end(): void;
+};
+/** A second way out when live dictation is busy, such as recording instead, with what it changes. */
+export type DictationAlternative = {
+    label: string;
+    note: string;
+    run: () => void;
+};

package/dist/types/inputs/icon-messages.d.ts

@@ -1,9 +1,23 @@
 declare const iconMessages: import("@k2b/stdlib").Catalog<{
     filterIcons: string;
     pickIcon: string;
+    recommended: string;
+    people: string;
+    work: string;
+    communication: string;
+    files: string;
+    data: string;
+    commerce: string;
+    places: string;
+    food: string;
+    media: string;
+    devices: string;
 }>;
 export type IconMessages = ReturnType<(typeof iconMessages)["resolve"]>["t"];
+export type IconGroupMessage = keyof Omit<IconMessages, "filterIcons" | "pickIcon">;
 /** Resolved from the inherited render locale. */
+/** The catalog locale the render locale resolves to, such as "de" for "de-AT". */
+export declare const useIconLocale: () => (() => string);
 export declare const useIconMessages: () => (() => IconMessages);
 export declare const checkIconMessages: () => import("@k2b/stdlib").CatalogIssue[];
 export {};

package/dist/types/inputs/icon-texts.d.ts

@@ -0,0 +1,13 @@
+import type { IconOption } from "./SpecialInputs";
+type IconText = readonly [label: string, description: string, keywords: string];
+/**
+ * German names for the default catalogue, keyed by the Tabler glyph name.
+ * Keywords are extra German search words; the English label and keywords stay
+ * searchable in every locale. This is catalogue data, not UI messages: the
+ * locale itself resolves through the icon message catalog, and
+ * `icon-options.test.ts` keeps the table complete.
+ */
+export declare const GERMAN_ICON_TEXTS: Readonly<Record<string, IconText>>;
+/** The default catalogue in a resolved locale; English is the catalogue itself. */
+export declare const localizedIconOptions: (locale: string) => readonly IconOption[];
+export {};

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

@@ -25,6 +25,11 @@ export type { Completion, QueryContext, SuggestContext, Suggestion, } from "./co
 export { abbreviations } from "./completion";
 export type { DatePickerBaseProps, DatePickerProps, DatePreset, DateRangePickerProps, DateRangeValue, DateTimePickerProps, DurationPreset, } from "./DatePicker";
 export { DatePicker, DateRangePicker, DateTimePicker } from "./DatePicker";
+export type { DictationController, DictationNotice, DictationOptions, DictationStatus } from "./dictation/create-dictation";
+export { createDictation } from "./dictation/create-dictation";
+export type { DictationBarProps, DictationButtonProps } from "./dictation/Dictation";
+export { DictationBar, DictationButton, dictationBarShown } from "./dictation/Dictation";
+export type { DictationAlternative, DictationDevice, DictationEndReason, DictationErrorCode, DictationEvent, DictationSession, DictationSource, DictationTarget, } from "./dictation/types";
 export type { EmojiPickerPopoverProps, EmojiPickerProps } from "./emoji/EmojiPicker";
 export { EmojiPicker } from "./emoji/EmojiPicker";
 export type { EmojiSkinTone } from "./emoji/emoji-index";

package/dist/types/layout/AnchoredPopover.d.ts

@@ -18,6 +18,11 @@ export type AnchoredPopoverProps = {
     plannedHeight?: number;
     /** Width of the panel on wide screens, such as `21rem`. On a phone it is a bottom sheet across the screen. */
     width?: string;
+    /**
+     * `false` keeps a small notice beside its control on a phone too, inside the screen with a margin, instead of a
+     * bottom sheet that would cover the control. Defaults to `true`.
+     */
+    sheet?: boolean;
     /** Moves the focus into the panel when it opens; defaults to the panel itself. */
     initialFocus?: () => HTMLElement | null | undefined;
     class?: string;

package/dist/types/text-editor/TextEditor.d.ts

@@ -1,6 +1,7 @@
 import type { Extension } from "@codemirror/state";
 import { type JSX } from "solid-js";
 import { type DropdownPosition } from "../actions/Dropdown";
+import type { DictationAlternative, DictationSource } from "../inputs/dictation/types";
 import { type TextEditorController, type TextEditorMode, type TextEditorOptions } from "./engine";
 import { type InlineFormat } from "./format";
 import { type TableHost } from "./table";
@@ -28,8 +29,16 @@ export type TextEditorProps = {
     /** Opens the host's attachment picker when clipboard images cannot be inserted. */
     onAttachImages?: () => void;
     onTableCheck?: (needsCheck: boolean) => void;
-    /** Host-owned sync status; its place is reserved across transitions. */
+    /** Host-owned sync status. Its row appears only while there is a status or a table check; keep it set across transitions. */
     status?: JSX.Element;
+    /**
+     * Live dictation as the last control of the toolbar, so it never scrolls away. While it runs, the dictation bar
+     * stands in for the formatting controls in the same row. Words land at the caret as typed text does.
+     */
+    dictation?: {
+        source: DictationSource;
+        alternative?: DictationAlternative;
+    };
     class?: string;
 };
 export type TableSizePickerProps = {

package/dist/types/text-editor/dictation.d.ts

@@ -0,0 +1,20 @@
+import { type RangeSet, StateField } from "@codemirror/state";
+import { Decoration, type DecorationSet, EditorView } from "@codemirror/view";
+import type { DictationTarget } from "../inputs/dictation/types";
+type DictationState = {
+    /** Where the next words land; `null` while no dictation is open. */
+    mark: number | null;
+    /** Every range dictation inserted, mapped through all later edits. */
+    dictated: RangeSet<Decoration>;
+    /** The newest words, tinted for a moment. */
+    fresh: DecorationSet;
+};
+/** The editor state dictation needs; add it to the view that `codeMirrorDictationTarget` writes into. */
+export declare const dictationExtension: () => StateField<DictationState>;
+/**
+ * A dictation target for a CodeMirror view. Words go into the document at once, as typed text does, so a shared
+ * document shows them to everyone and they last as long as the host saves typed text. The mark follows local and
+ * remote edits; Discard removes exactly the dictated ranges in one step, including what the person typed inside them.
+ */
+export declare function codeMirrorDictationTarget(editorView: () => EditorView | undefined): DictationTarget;
+export {};

package/dist/types/text-editor.d.ts

@@ -1,3 +1,4 @@
+export { codeMirrorDictationTarget, dictationExtension } from "./text-editor/dictation";
 export { createTextEditor, type TextEditorController, type TextEditorMode, type TextEditorOptions } from "./text-editor/engine";
 export { commands as textEditorCommands, formatLabels as textEditorFormatLabels, type InlineFormat } from "./text-editor/format";
 export { TableSizePicker, type TableSizePickerProps, TextEditor, type TextEditorControls, type TextEditorProps, } from "./text-editor/TextEditor";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",