@k2b/ui 0.33.0 → 0.35.0

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

@@ -100,6 +100,11 @@ export type AppWorkspaceMainPaneProps = {
     resizable?: boolean;
     resizeShadow?: boolean;
     defaultSize?: number | AppWorkspaceWidthShare;
+    /**
+     * The narrowest width in px, also for a person resizing it. Levels mode: the level needs it to be shown; when the
+     * deepest levels do not fit side by side at their minimum widths, the shallowest of them gives way, so a wide list
+     * pushes earlier columns aside.
+     */
     minSize?: number;
     maxSize?: number;
     class?: string;
@@ -398,6 +403,11 @@ export type AppWorkspaceNavTreeItemProps = {
     class?: string;
     /** With the tree's `onMove`, the item can change its place among its siblings. Other items keep theirs, and no item moves past them. */
     movable?: boolean;
+    /**
+     * Shows the item as a branch before its children are rendered, for a tree that loads a branch when it opens. The
+     * application renders the children, or a row that says they load, once the item is expanded.
+     */
+    hasChildren?: boolean;
     onDragEnter?: JSX.EventHandlerUnion<HTMLDivElement, DragEvent>;
     onDragOver?: JSX.EventHandlerUnion<HTMLDivElement, DragEvent>;
     onDragLeave?: JSX.EventHandlerUnion<HTMLDivElement, DragEvent>;

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

@@ -8,9 +8,18 @@ export type DetailPanelProps = {
     class?: string;
 };
 type DetailPanelHeaderBaseProps = {
+    /** A short line above the title that names what is shown, such as "Conversation", followed by its state. */
+    kind?: JSX.Element;
     title: JSX.Element;
     subtitle?: JSX.Element;
     meta?: JSX.Element;
+    /**
+     * The resource's "…" menu, shown before `actions`. Pass every less frequent command on the shown resource here,
+     * so each panel opens its menu from the same place; an empty list shows no button.
+     */
+    menu?: readonly DropdownItem[];
+    /** Accessible name of the "…" button. Defaults to "More actions". */
+    menuLabel?: string;
     actions?: JSX.Element;
     primaryActions?: JSX.Element;
     class?: string;
@@ -37,6 +46,11 @@ export type DetailPanelSummaryProps = {
 export type DetailPanelGroupProps = {
     children: JSX.Element;
     label?: string;
+    /**
+     * A visible quiet title, such as "More about this conversation". Its sections then stand flush as rows below
+     * it, which suits collapsed secondary sections with a `summary`.
+     */
+    title?: JSX.Element;
     class?: string;
 };
 export type DetailPanelTone = "accent" | "neutral" | "success" | "warning" | "danger";
@@ -90,6 +104,7 @@ export type DetailPanelSectionProps = DetailPanelSectionBaseProps & ({
     children?: JSX.Element;
     actions?: JSX.Element;
     collapsible?: false;
+    summary?: never;
     defaultOpen?: never;
     open?: never;
     onOpenChange?: never;
@@ -98,6 +113,8 @@ export type DetailPanelSectionProps = DetailPanelSectionBaseProps & ({
     children: JSX.Element;
     actions?: never;
     collapsible: true;
+    /** One line that says what the closed section holds, such as its newest entry; hidden while open. */
+    summary?: JSX.Element;
     defaultOpen?: boolean;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;

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

@@ -48,8 +48,11 @@ export declare function observeMobileShell(root: HTMLElement): () => void;
 declare function MobileShellRoot(props: MobileShellProps): JSX.Element;
 declare function MobileShellHeader(props: MobileShellHeaderProps): JSX.Element;
 export type MobileShellSidebarItem = TabBarItem & {
-    /** A count after the label, such as unread messages; 0 shows nothing. */
-    count?: number;
+    /**
+     * A quiet count after the label, such as open tasks: a number (0 shows nothing) or an element that renders one. The
+     * item's `badge`, which calls for attention, takes its place.
+     */
+    count?: number | JSX.Element;
 };
 export type MobileShellSidebarProps = {
     /** Accessible name of the navigation landmark; usually the tab bar's. */

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

@@ -3,6 +3,8 @@ import { type ButtonVariant } from "../actions/Button";
 import type { MaybeAccessor } from "../inputs/field-contract";
 export type SettingsPageProps = {
     title: JSX.Element;
+    /** False when a surrounding head already shows the title, such as a workspace level; the actions move to the footer. */
+    header?: boolean;
     subtitle?: JSX.Element;
     icon?: string;
     actions?: JSX.Element;
@@ -69,4 +71,24 @@ export type SettingsSaveBarProps = {
 export declare function SettingsSaveBar(props: SettingsSaveBarProps): JSX.Element;
 export type SettingsPanelFooterProps = SettingsSaveBarProps;
 export declare function SettingsPanelFooter(props: SettingsPanelFooterProps): JSX.Element;
+export type SaveStatusState = "saved" | "draft" | "saving" | "failed" | "invalid" | "unknown" | "readonly";
+export type SaveStatusProps = {
+    /** What the person's values are now: saved, a draft with changes, being saved, or a problem that kept them unsaved. */
+    state: MaybeAccessor<SaveStatusState>;
+    /** Formatted time of the last save, shown with `saved`. */
+    savedAt?: MaybeAccessor<string | undefined>;
+    /** Fields to check, shown with `invalid`. Default 1. */
+    invalidCount?: MaybeAccessor<number>;
+    /** With both handlers, Discard and Save follow the status while there is something to save. */
+    onDiscard?: () => void;
+    onSave?: () => void;
+    saveLabel?: string;
+    saveDisabled?: MaybeAccessor<boolean>;
+    class?: string;
+};
+/**
+ * The save status of a settings form at one fixed place, usually the head of its column. It reserves its width, so
+ * a change of state never moves the title or the buttons beside it. Problems with one field stay at that field.
+ */
+export declare function SaveStatus(props: SaveStatusProps): JSX.Element;
 export {};

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

@@ -0,0 +1,26 @@
+import { type JSX } from "solid-js";
+/**
+ * True while `element` sits in the collapsed sidebar rail, which shows icons
+ * without labels. The stylesheet sets `--k2b-sidebar-rail` exactly where it
+ * collapses the sidebar, so this follows the same container width and state.
+ */
+export declare const inSidebarRail: (element: Element | undefined) => boolean;
+/**
+ * A sidebar entry's name, or its `title`, in the hint the Cloud app rail uses.
+ * In the collapsed rail it names the icon beside it at once. Elsewhere it
+ * shows above the entry with the usual delay, and only when it says more than
+ * the visible label: a label cut off, or a title with details. A native
+ * `title` on `target` gives way to it, so no hint shows twice.
+ */
+export declare function SidebarRailHint(props: {
+    target: () => HTMLElement | undefined;
+    label: string | undefined;
+    /** The element that holds keyboard focus for the entry, when that is not `target`. */
+    focusTarget?: () => HTMLElement | undefined;
+    /** The visible label text inside `target`. */
+    labelSelector: string;
+    /** The entry renders a native `title`, which the hint replaces from the first hover or focus. */
+    titled?: boolean;
+    /** Called once the hint takes over; the entry stops rendering its native `title`. */
+    onArm?: () => void;
+}): JSX.Element;

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

@@ -9,6 +9,11 @@ export type TabBarItem = {
     title?: string;
     /** The page this item leads to is open. */
     current?: boolean;
+    /**
+     * A mark at the icon's corner that calls for attention, such as an unread count. Its element names the count for
+     * screen readers; an empty one takes no space.
+     */
+    badge?: JSX.Element;
 };
 export type TabBarProps = {
     /** Accessible name of the navigation landmark. */

package/dist/types/layout/detail-panel-messages.d.ts

@@ -8,6 +8,7 @@ declare const detailPanelMessages: import("@k2b/stdlib").Catalog<{
         count: number;
     }) => string;
     showLess: string;
+    moreActions: string;
 }>;
 export type DetailPanelMessages = ReturnType<(typeof detailPanelMessages)["resolve"]>["t"];
 export declare const useDetailPanelMessages: () => (() => DetailPanelMessages);

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

@@ -1,3 +1,4 @@
+export { AnchoredPopover, type AnchoredPopoverProps } from "./AnchoredPopover";
 export type { AppOverviewCardsProps, AppOverviewEmptyStateProps, AppOverviewPanelProps, AppOverviewProps, } from "./AppOverview";
 export { default as AppOverview } from "./AppOverview";
 export type { AppWorkspaceBottomDrawerHeight, AppWorkspaceBottomDrawerProps, AppWorkspaceContentProps, AppWorkspaceDetailProps, AppWorkspaceDetailWidth, AppWorkspaceHeadProps, AppWorkspaceMainPaneProps, AppWorkspaceMainProps, AppWorkspaceNavTreeItemProps, AppWorkspaceNavTreeMove, AppWorkspaceNavTreeProps, AppWorkspaceProps, AppWorkspaceSidebarAccessoryVisibility, AppWorkspaceSidebarBodyProps, AppWorkspaceSidebarIconActionProps, AppWorkspaceSidebarIconActionTone, AppWorkspaceSidebarIconGridProps, AppWorkspaceSidebarItemActionProps, AppWorkspaceSidebarItemActionsProps, AppWorkspaceSidebarItemIconProps, AppWorkspaceSidebarItemLabelProps, AppWorkspaceSidebarItemMetaProps, AppWorkspaceSidebarItemProps, AppWorkspaceSidebarItemStatusProps, AppWorkspaceSidebarItemTone, AppWorkspaceSidebarProps, AppWorkspaceSidebarSectionProps, AppWorkspaceSidebarVisibility, AppWorkspaceWidthShare, } from "./AppWorkspace";
@@ -37,8 +38,8 @@ export { default as ResizeSeparator, type ResizeSeparatorProps } from "./ResizeS
 export { attachResizeSeparator, type ResizeSeparatorOptions } from "./resize-separator";
 export type { ScrollAreaProps } from "./ScrollArea";
 export { default as ScrollArea } from "./ScrollArea";
-export type { SettingsFieldControlProps, SettingsFieldProps, SettingsGroupActionProps, SettingsGroupProps, SettingsPageProps, SettingsPanelFooterProps, SettingsSaveBarProps, SettingsSectionProps, } from "./Settings";
-export { readSettingsError, SettingsField, SettingsGroup, SettingsPage, SettingsPanelFooter, SettingsSaveBar, SettingsSection, sameSettingValue, } from "./Settings";
+export type { SaveStatusProps, SaveStatusState, SettingsFieldControlProps, SettingsFieldProps, SettingsGroupActionProps, SettingsGroupProps, SettingsPageProps, SettingsPanelFooterProps, SettingsSaveBarProps, SettingsSectionProps, } from "./Settings";
+export { readSettingsError, SaveStatus, SettingsField, SettingsGroup, SettingsPage, SettingsPanelFooter, SettingsSaveBar, SettingsSection, sameSettingValue, } from "./Settings";
 export type { SettingsCollectionActionProps, SettingsCollectionItemActionsProps, SettingsCollectionItemProps, SettingsCollectionItemReorderProps, SettingsCollectionItemStatusProps, SettingsCollectionProps, } from "./SettingsCollection";
 export { default as SettingsCollection } from "./SettingsCollection";
 export type { SettingsModalFooterProps, SettingsModalGroupProps, SettingsModalProps, SettingsModalTabProps, SettingsModalTabTone, } from "./SettingsModal";

package/dist/types/layout/settings-messages.d.ts

@@ -11,12 +11,24 @@ declare const settingsMessages: import("@k2b/stdlib").Catalog<{
         label: string;
     }) => string;
     saveChanges: string;
+    save: string;
     saving: string;
     unsaved: string;
     unsavedChangeLabel: ({ count }: {
         count: number;
     }) => string;
     noUnsavedChanges: string;
+    statusSaved: string;
+    statusSavedAt: ({ time }: {
+        time: string;
+    }) => string;
+    statusDraft: string;
+    statusFailed: string;
+    statusInvalid: ({ count }: {
+        count: number;
+    }) => string;
+    statusUnknown: string;
+    statusReadOnly: string;
 }>;
 export type SettingsMessages = ReturnType<(typeof settingsMessages)["resolve"]>["t"];
 /** Resolved from the inherited render locale. */

package/dist/types/surfaces/DotStrip.d.ts

@@ -0,0 +1,22 @@
+import { type JSX } from "solid-js";
+/** `accent` = the app colour (it worked), `ai` = came from AI, `muted` = nothing happened. */
+export type DotStripTone = "accent" | "warning" | "danger" | "ai" | "muted";
+export type DotStripProps = {
+    /** Outcomes in order, left to right. */
+    dots: readonly DotStripTone[];
+    /** Total slots. Slots after `dots` show as empty rings, so a growing strip keeps its size. Defaults to `dots.length`. */
+    length?: number;
+    /** Shows every slot as a quiet placeholder, for "nothing checked yet". */
+    waiting?: boolean;
+    /** Index of the dot that belongs to the item shown next to the strip. */
+    selected?: number | null;
+    size?: "md" | "lg";
+    /** Dots per row; more wrap into further rows of the same width. Defaults to one row. */
+    columns?: number;
+    /** Names the strip and its counts, for example "Last 50 mails: 17 matched, 6 skipped, 27 not". */
+    label: string;
+    class?: string;
+};
+/** A fixed-size row of outcome dots: the last runs, checks or mails at a glance. */
+export declare function DotStrip(props: DotStripProps): JSX.Element;
+export default DotStrip;

package/dist/types/surfaces/ProgressRing.d.ts

@@ -1,6 +1,7 @@
 import { type JSX } from "solid-js";
 import type { IntentTone } from "../semantics";
-export type ProgressRingTone = Extract<IntentTone, "info" | "warning" | "danger">;
+/** `accent` draws the ring in the app's own colour, for progress that belongs to the app rather than to a state. */
+export type ProgressRingTone = Extract<IntentTone, "info" | "warning" | "danger"> | "accent";
 export type ProgressRingProps = {
     value: number;
     tone?: ProgressRingTone;

package/dist/types/surfaces/ResourceCard.d.ts

@@ -1,9 +1,12 @@
 import { type JSX } from "solid-js";
+import type { LinkCardColor } from "./LinkCard";
 /**
  * What a card can show of the element it stands for: the element itself, a placeholder while it is being looked up, or
  * why it cannot be shown.
  */
 export type ResourceCardState = "ok" | "loading" | "no_access" | "deleted" | "unavailable";
+/** The icon chip's colour, from the same palette as `LinkCard`. */
+export type ResourceCardColor = LinkCardColor;
 export type ResourceCardProps = {
     /** Defaults to `"ok"`. Every state has the same size, so a card that changes state moves nothing around it. */
     state?: ResourceCardState;
@@ -11,6 +14,12 @@ export type ResourceCardProps = {
     title?: string;
     /** Icon class of the element's kind, for example `ti ti-notebook`. Shown only in state `"ok"`. */
     icon?: string;
+    /** Colour of the icon chip, usually one per kind of element. Without it the chip stays neutral. Only in state `"ok"`. */
+    color?: ResourceCardColor;
+    /** One line above the title: what and where the element is, for example "Task in IT planning · due 30 Oct". Only in state `"ok"`. */
+    context?: string;
+    /** The element's current state as a short label, for example "Open", shown at the end. Only in state `"ok"`. */
+    status?: string;
     /** What the element belongs to, for example the application or service. Shown only in state `"ok"`. */
     source?: string;
     /** Where the element lives within its source, for example a folder or a project. Shown only in state `"ok"`. */

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

@@ -4,6 +4,8 @@ export type { AvatarStackPerson, AvatarStackProps } from "./AvatarStack";
 export { AvatarStack } from "./AvatarStack";
 export type { DescriptionListItem, DescriptionListProps } from "./DescriptionList";
 export { DescriptionList } from "./DescriptionList";
+export type { DotStripProps, DotStripTone } from "./DotStrip";
+export { DotStrip } from "./DotStrip";
 export type { LinkCardColor, LinkCardProps } from "./LinkCard";
 export { LinkCard } from "./LinkCard";
 export type { NotFoundStateAction, NotFoundStateProps } from "./NotFoundState";
@@ -18,7 +20,8 @@ export type { ProgressBarProps, ProgressBarTone } from "./ProgressBar";
 export { ProgressBar } from "./ProgressBar";
 export type { ProgressRingProps, ProgressRingTone } from "./ProgressRing";
 export { ProgressRing } from "./ProgressRing";
-export type { ResourceCardProps, ResourceCardState } from "./ResourceCard";
+export { PERSON_COLORS, personColor } from "./person-color";
+export type { ResourceCardColor, ResourceCardProps, ResourceCardState } from "./ResourceCard";
 export { ResourceCard } from "./ResourceCard";
 export { Skeleton, type SkeletonProps } from "./Skeleton";
 export type { StatCellAccent, StatCellProps, StatCellTone } from "./StatCell";

package/dist/types/surfaces/person-color.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The colors that stand for a person: the tint behind avatar initials, a collaborator's cursor, and the marks and
+ * comments a person leaves. The palette leaves out cyan, which means AI, and yellow, which reads as a text highlight.
+ * Several people can share a color, so a person's name always appears next to it.
+ */
+export declare const PERSON_COLORS: readonly ["#3b82f6", "#6366f1", "#8b5cf6", "#c026d3", "#ec4899", "#e11d48", "#f97316", "#16a34a"];
+/** The palette index for a name, the order of the `.k2b-avatar[data-tint]` rules. Surrounding spaces do not count. */
+export declare const personTint: (name: string) => number;
+/** A person's color from their display name, the same wherever Cloud shows that person. */
+export declare const personColor: (name: string) => string;

package/dist/types/surfaces/resource-messages.d.ts

@@ -3,6 +3,8 @@ declare const resourceMessages: import("@k2b/stdlib").Catalog<{
     resourceNoAccess: string;
     resourceDeleted: string;
     resourceUnavailable: string;
+    resourceKind: string;
+    resourceNoAccessHint: string;
 }>;
 export type ResourceMessages = ReturnType<(typeof resourceMessages)["resolve"]>["t"];
 /** Resolved from the inherited render locale. */

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

@@ -0,0 +1,69 @@
+import type { Extension } from "@codemirror/state";
+import { type JSX } from "solid-js";
+import { type DropdownPosition } from "../actions/Dropdown";
+import { type TextEditorController, type TextEditorMode, type TextEditorOptions } from "./engine";
+import { type InlineFormat } from "./format";
+import { type TableHost } from "./table";
+export type TextEditorProps = {
+    label: string;
+    initialValue?: string;
+    mode?: TextEditorMode;
+    onModeChange?: (mode: TextEditorMode) => void;
+    readOnly?: boolean;
+    loading?: boolean;
+    placeholder?: string;
+    extensions?: Extension;
+    /** Host-owned Markdown presentation; see `createTextEditor`. The host then also styles the editor surface. */
+    presentation?: TextEditorOptions["presentation"];
+    /** `false` when the host renders its own formatting toolbar and mode control; place `controls.TableMenu` in it. */
+    toolbar?: boolean;
+    /** Collaboration supplies history and server-owned structure here. */
+    host?: Pick<TableHost, "structure" | "renderCell" | "onCellSelection" | "tabMovesFocus"> & Partial<Pick<TableHost, "undo" | "redo" | "boundary">>;
+    maxLength: number;
+    maxPasteCells?: number;
+    onChange?: (text: string) => void;
+    onReady?: (editor: TextEditorController, controls: TextEditorControls) => void;
+    /** Return `true` when the host attached the images itself; otherwise the editor shows its attachment hint. */
+    onDroppedImages?: (count: number, files: File[]) => boolean | void;
+    /** 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. */
+    status?: JSX.Element;
+    class?: string;
+};
+export type TableSizePickerProps = {
+    maxRows: number;
+    maxColumns: number;
+    onPick: (size: {
+        rows: number;
+        columns: number;
+    }) => void;
+    /** Share this picker with slash commands or secondary menus. */
+    onReady?: (open: () => void) => void;
+    disabled?: boolean;
+    class?: string;
+    size?: "xs" | "sm";
+};
+/** Shared table-size control: pointer grid on desktop, large fields in a phone sheet. */
+export declare function TableSizePicker(props: TableSizePickerProps): JSX.Element;
+type TableMenuTrigger = {
+    text?: string;
+    class?: string;
+    size?: "xs" | "sm";
+    position?: DropdownPosition;
+};
+/** Shared table controls for a host-owned toolbar (`toolbar={false}`). */
+export type TextEditorControls = {
+    /** A table cell has focus in the formatted view. */
+    tableActive: () => boolean;
+    /** The shared cell menu behind a host-styled trigger; on phones it opens as a sheet. */
+    TableMenu: (props: TableMenuTrigger) => JSX.Element;
+    /** Formats the focused cell's selection; `false` when no cell has focus. */
+    formatCell: (format: InlineFormat) => boolean;
+    /** Shows a host message, such as a server's reason for a rejected table action, in the editor's notice. */
+    notify: (message: string) => void;
+};
+/** A Markdown text field with app-injected collaboration and a directly editable table view. */
+export declare function TextEditor(props: TextEditorProps): JSX.Element;
+export {};

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

@@ -0,0 +1,9 @@
+/** Parse only the HTML vocabulary that the Markdown converter consumes.
+ * Resource attributes and active elements never reach a clipboard consumer.
+ * The returned detached body is read as data and never mounted in the editor.
+ */
+export declare const parseClipboardHtml: (html: string) => HTMLElement;
+export declare const convertHtml: (html: string, code: boolean) => {
+    markdown: string;
+    droppedImages: number;
+} | null;

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

@@ -0,0 +1,8 @@
+import { type EditorView, ViewPlugin } from "@codemirror/view";
+import type { TableHost } from "./table";
+/** Load the HTML sanitizer only when needed, before either paste consumer runs.
+ * A delayed paste never overwrites edits made while its parser was loading.
+ */
+export declare const clipboardLoading: (getHost: (view: EditorView) => TableHost | null, syncSelection?: (view: EditorView) => void) => ViewPlugin<{
+    destroy(): void;
+}, undefined>;

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

@@ -0,0 +1,20 @@
+export declare const htmlClipboardReady: () => boolean;
+export declare const loadHtmlClipboard: () => Promise<void>;
+export declare const parseClipboardHtml: (html: string) => HTMLElement;
+export declare const convertClipboardHtml: (html: string, code: boolean) => {
+    markdown: string;
+    droppedImages: number;
+} | null;
+/** All clipboard entry paths share one preflight, before insertion or conversion. */
+export declare function inspectClipboard(data: DataTransfer, limits: {
+    maxLength: number;
+    maxPasteCells: number;
+}): {
+    error: "textTooLarge" | "pasteTooLarge";
+} | {
+    text: string;
+    html: string;
+    images: number;
+    files: File[];
+    tsv: string[][] | null;
+};

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

@@ -0,0 +1,34 @@
+import { type Extension } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { type TableHost } from "./table";
+export type TextEditorMode = "formatted" | "source" | "plain";
+export type TextEditorOptions = {
+    parent: HTMLElement;
+    /** Initial Markdown. Subsequent collaborative changes arrive through extensions. */
+    doc?: string;
+    mode?: TextEditorMode;
+    readOnly?: boolean;
+    placeholder?: string;
+    label: string;
+    extensions?: Extension;
+    /**
+     * Replaces the built-in Markdown language, highlighting, formatted markers and
+     * formatting keys of the formatted and source modes. The engine keeps the
+     * table grid, clean paste, limits and history routing in every mode.
+     */
+    presentation?: (mode: Exclude<TextEditorMode, "plain">) => Extension;
+    /** The host owns history; collaboration bindings supply theirs. */
+    host: TableHost;
+    onChange?: (text: string) => void;
+    onDroppedImages?: (count: number, files: File[]) => void;
+};
+/** Shared engine; application extensions own transport, awareness and domain features. */
+export declare function createTextEditor(options: TextEditorOptions): {
+    view: EditorView;
+    /** Also re-reads `presentation`, so a host can refresh it, e.g. after a theme change. */
+    setMode: (mode: TextEditorMode) => void;
+    setLabel: (label: string) => void;
+    setReadOnly: (readOnly: boolean) => void;
+    destroy: () => void;
+};
+export type TextEditorController = ReturnType<typeof createTextEditor>;

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

@@ -0,0 +1,34 @@
+/** Toolbar and keyboard commands. Each one is a plain Markdown edit of the selection. */
+import { type EditorState, Facet, type TransactionSpec } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+/** Insertion text follows the editor's inherited locale, including keyboard commands. */
+export declare const formatLabels: Facet<{
+    link: string;
+    column: (column: number) => string;
+}, {
+    link: string;
+    column: (column: number) => string;
+}>;
+/** Named Markdown marks or an app's single-line paired delimiter (for example Notebook's `==`). */
+export type InlineFormat = "bold" | "italic" | "code" | "strike" | "link" | {
+    marker: string;
+};
+/** Pure transaction spec, also used when a missing table cell must be materialized atomically. */
+export declare const inlineFormat: (state: EditorState, name: InlineFormat) => TransactionSpec;
+export declare const commands: {
+    bold: (view: EditorView) => boolean;
+    italic: (view: EditorView) => boolean;
+    code: (view: EditorView) => boolean;
+    strike: (view: EditorView) => boolean;
+    heading: (view: EditorView) => boolean;
+    heading1: (view: EditorView) => boolean;
+    heading2: (view: EditorView) => boolean;
+    heading3: (view: EditorView) => boolean;
+    codeBlock: (view: EditorView) => boolean;
+    bulletList: (view: EditorView) => boolean;
+    orderedList: (view: EditorView) => boolean;
+    quote: (view: EditorView) => boolean;
+    link: (view: EditorView) => boolean;
+    table: (view: EditorView) => boolean;
+    rule: (view: EditorView) => boolean;
+};

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

@@ -0,0 +1 @@
+export declare const formattedView: import("@codemirror/state").Extension[];

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

@@ -0,0 +1,8 @@
+/**
+ * Markdown language without `@codemirror/lang-markdown`: that package pulls in
+ * `@codemirror/lang-html` (and with it CSS and JavaScript) for HTML blocks.
+ * The shared editor needs only the GFM tree, so it wraps `@lezer/markdown`.
+ */
+import { Language, LanguageSupport } from "@codemirror/language";
+export declare const markdownLanguage: Language;
+export declare const markdown: () => LanguageSupport;

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

@@ -0,0 +1,105 @@
+/**
+ * Pure GFM table edits in original Markdown coordinates. Markdown is the only
+ * model; callers reparse after applying a transaction. No repair of damaged
+ * tables or prose is attempted. Extra and missing body cells remain inspectable.
+ */
+import type { ChangeDesc } from "@codemirror/state";
+export type Align = "left" | "center" | "right" | null;
+export type Change = {
+    from: number;
+    to: number;
+    insert: string;
+};
+/** Trimmed raw content, with absolute UTF-16 source offsets. */
+export type Cell = {
+    from: number;
+    to: number;
+    text: string;
+};
+export type Line = {
+    from: number;
+    to: number;
+    pipes: number[];
+    leadingPipe: boolean;
+    trailingPipe: boolean;
+    cells: Cell[];
+    /** Original terminator, used when inserting rows. */
+    lineBreak?: string;
+};
+export type Table = {
+    from: number;
+    to: number;
+    /** Header, delimiter, then body rows. */
+    lines: Line[];
+    align: Align[];
+    columns: number;
+};
+/** Only top-level Lezer GFM tables: never code, block quotes, or list items. */
+export declare const findTables: (doc: string) => Table[];
+export declare const tableAt: (doc: string, pos: number) => Table | null;
+/**
+ * Problems that must stay visible before formatted output is sent. A damaged
+ * separator makes GFM fall back to a paragraph: two adjacent pipe-framed rows
+ * there still need review. This only inspects top-level paragraph nodes, never
+ * code, quotations or lists, and does not repair or rewrite any text.
+ */
+export declare const inspectTableStructure: (doc: string) => {
+    extraCells: boolean;
+    missingSeparator: boolean;
+};
+export declare const gridLine: (table: Table, row: number) => Line | undefined;
+export declare const rowCount: (table: Table) => number;
+/** Literal displayed text → safe raw content. Call once, never on existing raw Markdown. */
+export declare const escapeCell: (value: string) => string;
+/** Display text and a raw offset for every displayed UTF-16 boundary. */
+export declare const cellDisplayMap: (raw: string) => {
+    text: string;
+    offsets: number[];
+};
+/** Decode only table pipes and backslashes; leave inline Markdown source editable. */
+export declare const displayCell: (raw: string) => string;
+/**
+ * One minimal contiguous source edit from literal displayed input. Unchanged
+ * escapes keep their exact bytes, including noncanonical lone backslashes.
+ * `from` is the old cell's absolute start; input must NOT be pre-escaped.
+ */
+export declare const cellChanges: (raw: string, nextDisplayed: string, from: number) => Change[];
+/**
+ * Map an edit based on an old cell through intervening document changes.
+ * Deletes only surviving old-source spans (iterGaps), preserving remote inserts
+ * and excluding replaced/deleted identities. Returns current-document offsets.
+ * The caller must first verify that the mapped range is still the same cell;
+ * concurrent structural/escape edits require resyncing its displayed snapshot.
+ */
+export declare const mappedCellChanges: (raw: string, nextDisplayed: string, from: number, changes: ChangeDesc) => Change[];
+/** Spike-compatible escaped RAW input; fills ragged cells within the existing grid width. */
+export declare const setCellText: (table: Table, row: number, col: number, next: string) => Change[];
+export declare const insertRow: (table: Table, after: number) => Change[];
+export declare const deleteRow: (table: Table, row: number) => Change[];
+/** Move a body row, retaining every untouched row's original source and identities. */
+export declare const moveRow: (source: string, table: Table, row: number, to: number) => Change[];
+/** Swap adjacent columns, including their alignment, without rewriting other cells. */
+export declare const moveColumn: (table: Table, column: number, to: number) => Change[];
+/** A hidden header is an empty GFM header; its former values become the first body row. */
+export declare const toggleHeader: (source: string, table: Table) => Change[];
+/** Delete only the selected table; surrounding prose remains byte-for-byte intact. */
+export declare const deleteTable: (table: Table) => Change[];
+/** Insert before `at`, including at the widest row's end; pad ragged rows without dropping cells. */
+export declare const insertColumn: (table: Table, at: number) => Change[];
+/** Complete a ragged grid without changing or removing any existing cell. */
+export declare const completeColumns: (table: Table) => Change[];
+export declare const deleteColumn: (table: Table, col: number) => Change[];
+export declare const setAlign: (table: Table, col: number, align: Align) => Change[];
+/** First grid row is the header; pad short rows, preserve every extra cell. */
+export declare const tableFromGrid: (grid: string[][]) => string;
+/** Quoted TSV (including doubled quotes and embedded newlines). Invalid quotes stay raw. */
+export declare const parseTsv: (text: string) => string[][] | null;
+/** Apply sorted or unsorted, non-overlapping edits in old-document coordinates. */
+export declare const applyChanges: (doc: string, changes: Change[]) => string;
+/**
+ * Settle recognized ragged GFM tables without deleting or rewriting source.
+ * Extra cells become named-grid positions with empty headers, never discarded.
+ * Unrecognizable tables remain raw text for the application's check state;
+ * code, quotes and lists are not repair candidates.
+ */
+export declare const repairTables: (doc: string, maxLength: number) => Change[];