@k2b/ui 0.23.0 → 0.25.0

package/dist/types/actions/Dropdown.d.ts

@@ -8,11 +8,21 @@ export type DropdownActionBase = {
     icon?: string;
     image?: string;
     label: string;
+    /**
+     * Accessible name when it must say more than the visible label, such as the current value and what the next
+     * activation does. It must contain the visible label.
+     */
+    ariaLabel?: string;
     description?: string;
     variant?: "danger";
 };
 export type DropdownAction = (DropdownActionBase & {
     action: () => void;
+    /**
+     * Set `false` for an action that changes a value in place, such as cycling a setting: the menu stays open and
+     * the focus stays on the row. Defaults to `true`.
+     */
+    closeOnSelect?: boolean;
     href?: never;
     external?: never;
 }) | (DropdownActionBase & {
@@ -80,6 +90,8 @@ export type DropdownTriggerProps = Omit<ButtonProps, "aria-controls" | "aria-exp
 };
 export type DropdownItemProps = {
     children: JSX.Element;
+    closeOnSelect?: boolean;
+    ariaLabel?: string;
     icon?: string;
     image?: string;
     description?: string;

package/dist/types/actions/SpotlightSearch.d.ts

@@ -10,6 +10,8 @@ export type SpotlightButtonProps = {
     label?: string;
     title?: string;
     icon?: string;
+    /** Shortcut such as "mod+k"; takes precedence over shortcutLabel. */
+    shortcut?: string;
     shortcutLabel?: string | false;
     ariaLabel?: string;
     disabled?: boolean;

package/dist/types/content/Calendar.d.ts

@@ -155,17 +155,27 @@ export type CalendarProps<V extends string = never> = {
      * `startHour`, `endHour`, and the visible hours do not apply then.
      */
     dayHours?: readonly [start: number, end: number];
-    /** Day and week views with `dayHours`: the days of `events`. Without it they cover the day or week of `date`. */
+    /** Loaded days of the continuous month view and the day/week views with `dayHours`, with an exclusive end. */
     range?: CalendarRange;
-    /** Called once when the reader nears the first loaded day, again once `range.from` moved. */
+    /**
+     * Called once when the reader nears the first loaded day, again once `range.from` moved.
+     * May return a promise that settles once the range has grown; when it settles without moving that end, the
+     * continuous month treats the end as reached, and Next/Previous past it go through the host's navigation.
+     */
     onLoadEarlier?: () => unknown;
-    /** Called once when the reader nears the last loaded day, again once `range.to` moved. */
+    /**
+     * Called once when the reader nears the last loaded day, again once `range.to` moved.
+     * May return a promise that settles once the range has grown; when it settles without moving that end, the
+     * continuous month treats the end as reached, and Next/Previous past it go through the host's navigation.
+     */
     onLoadLater?: () => unknown;
     /**
-     * Day and week views with `dayHours`: the first and the last day the reader sees, once the view opened and whenever
-     * scrolling changed them, such as for the URL or a count of what is in view.
+     * Scrolling views: the first and last visible day, and the focus date, after positioning and when they change.
+     * Day/week views use their first day as focus. Continuous month uses the first selected day inside its focus month,
+     * else the host's `date` when in that month, else today when in that month, else its first. Month rows count as
+     * visible when more than half is on screen.
      */
-    onVisibleDateChange?: (date: Date, last: Date) => void;
+    onVisibleDateChange?: (date: Date, last: Date, focus: Date) => void;
     visibleStartHour?: number;
     visibleEndHour?: number;
     allDayMaxHeightRem?: number;
@@ -240,7 +250,10 @@ export type CalendarSelectionControls = {
 export type CalendarQuickCreateControls = {
     /** What the person asked to create through `quickCreate`; absent after a click, a drag, or the keyboard. */
     create?: string;
-    /** Closes the quick create and returns the focus to the selected day; once another quick create replaced it, nothing. */
+    /**
+     * Closes the quick create, returns the focus to the selected day only while the focus is still in the quick create, and
+     * leaves a newer selection in place; once another quick create replaced it, nothing.
+     */
     close: () => void;
 };
 export type CalendarEventTimeChange = {

package/dist/types/content/CalendarWeekView.d.ts

@@ -2,6 +2,6 @@ import { type TimeViewProps } from "./calendar-time-view";
 /**
  * The week view with `dayHours`: the loaded days side by side in one strip, seven on a wide screen and three on a
  * phone. A trackpad, Shift with the wheel, or a finger scroll it sideways day by day; each gesture keeps the axis it
- * started on, and the strip settles on a day start. The arrows move by whole weeks.
+ * started on, and the strip settles on a day edge. The arrows move by whole weeks.
  */
 export declare const CalendarWeekView: (props: TimeViewProps) => import("solid-js").JSX.Element;

package/dist/types/content/DataTable.d.ts

@@ -14,6 +14,15 @@ export type DataTableColumn<T> = {
     cellClass?: string;
     /** Defaults to right for numeric values and left for everything else. */
     align?: "left" | "center" | "right";
+    /**
+     * Keeps each value on one line, so the column is at least as wide as its
+     * longest value. For dates, times, numbers, amounts, and short codes.
+     * Defaults to true when the column's first value is a number or date. The
+     * default cell wrapper already keeps every value on one line; this option
+     * decides wrapping for content under a custom `cellContentClass`, and a
+     * `white-space` that class sets itself wins.
+     */
+    nowrap?: boolean;
     /**
      * Marks the column sortable. Pass a string when the server's sort key
      * differs from the column id — they often do, because one column can show a

package/dist/types/content/Kbd.d.ts

@@ -0,0 +1,16 @@
+import { type JSX } from "solid-js";
+import { type KeyboardPlatform } from "../intl/shortcut";
+export type KbdProps = {
+    /** Shortcut such as "mod+k", "shift+/", "enter". */
+    keys: string;
+    /** Set on the server when the host knows the reader's platform. */
+    platform?: KeyboardPlatform;
+    class?: string;
+};
+/**
+ * Accessible key caps using the inherited locale and the reader's platform.
+ * A host rendering caps on the server passes `platform` to avoid a switch after hydration.
+ * @example <Kbd keys="mod+k" platform="apple" />
+ */
+export declare function Kbd(props: KbdProps): JSX.Element;
+export default Kbd;

package/dist/types/content/LabelChip.d.ts

@@ -0,0 +1,12 @@
+import { type JSX } from "solid-js";
+export type LabelChipProps = {
+    icon?: string;
+    children: JSX.Element;
+    class?: string;
+};
+/**
+ * Names a UI control inside running text. The icon is a full class string.
+ * @example <LabelChip icon="ti ti-share">Share</LabelChip>
+ */
+export declare function LabelChip(props: LabelChipProps): JSX.Element;
+export default LabelChip;

package/dist/types/content/MarkdownView.d.ts

@@ -43,7 +43,8 @@ export declare const createSafeMarked: (locale?: string) => Marked;
  *
  * Renders untrusted Markdown safely by default. Raw HTML and unsafe link
  * protocols are escaped. Info blocks (`:::note`, `:::info`, `:::success`,
- * `:::warning`, `:::danger`) render as the calm `NoticeCard`. Already-rendered
+ * `:::warning`, `:::danger`) render on a tinted surface without a border.
+ * The icon and title use the tone colour; body text stays neutral. Rendered
  * HTML requires the deliberately named `trustedHtml` boundary; the caller owns
  * sanitization in that mode.
  *

package/dist/types/content/Steps.d.ts

@@ -0,0 +1,12 @@
+import type { JSX } from "solid-js";
+export type StepsProps = {
+    children: JSX.Element;
+    start?: number;
+    class?: string;
+};
+/**
+ * An ordered instruction list with accent numbers. Trusted HTML can use the same class.
+ * @example <Steps start={2}><li>Select Share.</li><li>Copy the link.</li></Steps>
+ */
+export declare function Steps(props: StepsProps): JSX.Element;
+export default Steps;

package/dist/types/content/VirtualFeed.d.ts

@@ -66,6 +66,14 @@ export type VirtualFeedProps<T> = {
     announce?: (added: readonly T[]) => string | undefined;
     /** Called when the reader reaches or leaves the end. */
     onEndChange?: (atEnd: boolean) => void;
+    /**
+     * Called when the items in view change: the first and last item whose whole height is in view. An item taller
+     * than the view counts while it covers the view. `null` while no item is in view.
+     */
+    onVisibleChange?: (visible: {
+        first: T;
+        last: T;
+    } | null) => void;
     /** Receives the controller once the feed is mounted. */
     controller?: (controller: VirtualFeedController) => void;
     /** Shown while `items` is empty. */

package/dist/types/content/calendar-day-scroll.d.ts

@@ -3,8 +3,9 @@
  *
  * The day view runs down through the days and stops gently at each day start: within `STOP_ZONE` pixels of one the
  * wheel slows down, and a scroll that rests close to one glides onto it. The week view scrolls sideways through the
- * days; a wheel or trackpad gesture keeps the axis it started on, and a scroll that rests between two days glides to
- * the nearer day.
+ * days; a wheel or trackpad gesture keeps the axis it started on, and a resting scroll glides to the nearest day start
+ * or, with end space, day end at the edge of the visible room. A scroll no gesture made, such as a reveal, glides on in
+ * its own direction, so what it brought into view stays there.
  */
 /** Pixels before and after a day start in which the wheel slows down. */
 export declare const STOP_ZONE = 72;
@@ -38,5 +39,9 @@ export type WheelAxis = "x" | "y";
 export declare const wheelAxis: (deltaX: number, deltaY: number, shiftKey: boolean) => WheelAxis;
 /** The sideways part of a wheel event on an axis, Shift turning the vertical delta into a sideways one. */
 export declare const wheelDelta: (axis: WheelAxis, deltaX: number, deltaY: number, shiftKey: boolean) => number;
-/** The scroll position of the nearest day start in a strip of equal columns. */
-export declare const snapToColumn: (position: number, width: number) => number;
+/**
+ * The day start nearest to `position` in a strip of equal columns, or with `room` the nearer day edge at either end of
+ * the visible room; ties keep the start. A `heading` of 1 or -1 only looks ahead or back, for a scroll that brought
+ * something into view and must not slide back over it.
+ */
+export declare const snapToColumn: (position: number, width: number, room?: number, heading?: number) => number;

package/dist/types/content/calendar-dialogs.d.ts

@@ -1,7 +1,5 @@
 import type { CalendarCommand } from "./Calendar";
 import type { CalendarMessages } from "./calendar-messages";
-/** The keys of a shortcut as the reader presses them, such as ["⇧", "N"] or ["Shift", "N"]. */
-export declare const shortcutKeys: (shortcut: string) => string[];
 /**
  * The calendar's shortcuts: the same list the host registers for its dispatcher and its help. `alternatives` names
  * other keys the calendar itself handles for a command, such as the arrow keys that page like J and K.

package/dist/types/content/calendar-month-scroll.d.ts

@@ -0,0 +1,25 @@
+import type { TodayDirection } from "./calendar-time-view";
+export declare const MONTH_ROWS_IN_VIEW = 5;
+export declare const MONTH_ROW_BLOCK = 8;
+/** Whole weeks covering the loaded days, with an exclusive end and the date context's first weekday. */
+export declare const monthWeekKeys: (first: string, to: string, firstDayOfWeek: 0 | 1) => string[];
+/** The row at the center of the area below the weekday header, clamped to the loaded weeks. */
+export declare const monthFocusRow: (top: number, viewHeight: number, rowHeight: number, total: number) => number;
+/** The middle day of a week names its month: Thursday for Monday weeks, Wednesday for Sunday weeks. */
+export declare const monthOfWeek: (week: string) => string;
+/** The loaded row containing a day, including the first of a month; absent outside the loaded weeks. */
+export declare const monthRowOf: (weeks: readonly string[], key: string) => number | undefined;
+/** The half-open interval of rows whose visible height exceeds half a row. */
+export declare const monthVisibleRows: (top: number, viewHeight: number, rowHeight: number, total: number) => {
+    first: number;
+    end: number;
+};
+/** One block above and below the visible rows' blocks; the window changes only at their block boundaries. */
+export declare const monthRenderWindow: (top: number, viewHeight: number, rowHeight: number, total: number) => {
+    first: number;
+    end: number;
+};
+/** The least movement that shows a row whole, or nothing when it is already fully in view. */
+export declare const monthRevealTop: (row: number, top: number, viewHeight: number, rowHeight: number) => number | undefined;
+/** Today points up or down until more than half its row is visible. */
+export declare const monthTodayDirection: (row: number, top: number, viewHeight: number, rowHeight: number) => TodayDirection;

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

@@ -26,6 +26,10 @@ export { FileBrowserPanel, type FileBrowserPanelProps, type FileSource, openFile
 export { FileGrid, type FileGridProps } from "./FileGrid";
 export { default as FileTree, type FileTreeActions, type FileTreeEntry, type FileTreeProps } from "./FileTree";
 export { canPreviewFile, default as FileView, type FileViewContent, type FileViewFile, type FileViewPreviewKind, type FileViewProps, type FileViewRenderer, type FileViewRendererProps, formatFileViewSize, getFileViewPreviewKind, } from "./FileView";
+export type { KbdProps } from "./Kbd";
+export { Kbd } from "./Kbd";
+export type { LabelChipProps } from "./LabelChip";
+export { LabelChip } from "./LabelChip";
 export type { LightboxAction, LightboxImage } from "./Lightbox";
 export { default as Lightbox } from "./Lightbox";
 export type { LogTableEntry } from "./LogEntriesTable";
@@ -33,13 +37,15 @@ export { default as LogEntriesTable } from "./LogEntriesTable";
 export { default as MarkdownView, type MarkdownRenderOptions, type MarkdownViewProps, renderSafeMarkdown } from "./MarkdownView";
 export type { MessageGroupEntry, MessageRowAction, MessageRowAttachment, MessageRowAuthor, MessageRowFile, MessageRowMedia, MessageRowProgress, MessageRowProps, MessageRowQuote, MessageRowReaction, MessageRowStatus, MessageRowThread, MessageSystemRowProps, } from "./MessageRow";
 export { MessageRow, MessageSystemRow, startsMessageGroup } from "./MessageRow";
-export { type MarkdownInfoBlock, type MarkdownInfoBlockRenderInput, type MarkdownInfoBlockType, markdownInfoBlocks, renderMarkdownInfoBlock, scanMarkdownInfoBlock, } from "./markdown-info-blocks";
+export { MARKDOWN_CALLOUT_CLASSES, MARKDOWN_CALLOUT_ICON_ATTRIBUTES, type MarkdownInfoBlock, type MarkdownInfoBlockRenderInput, type MarkdownInfoBlockType, markdownInfoBlocks, renderMarkdownInfoBlock, scanMarkdownInfoBlock, } from "./markdown-info-blocks";
 export { type MarkdownLinkInput, type MarkdownReference, type MarkdownReferenceKind, type MarkdownReferenceType, markdownLinkReference, markdownReferenceIcon, markdownReferenceType, markdownReferenceTypeLabel, markStandaloneLinks, renderMarkdownLink, } from "./markdown-links";
 export { Pagination, type PaginationProps } from "./Pagination";
 export type { PdfPreviewProps, PdfPreviewRequest } from "./PdfPreview";
 export { default as PdfPreview } from "./PdfPreview";
 export type { RangeOption, RangePickerProps } from "./RangePicker";
 export { default as RangePicker } from "./RangePicker";
+export type { StepsProps } from "./Steps";
+export { Steps } from "./Steps";
 export type { StructuredDataPreviewMode, StructuredDataPreviewProps, StructuredDataValue } from "./StructuredDataPreview";
 export { default as StructuredDataPreview, isStructuredDataValue } from "./StructuredDataPreview";
 export type { TimelineColor, TimelineController, TimelineItem, TimelineProps } from "./Timeline";

package/dist/types/content/markdown-info-blocks.d.ts

@@ -21,6 +21,23 @@ declare const TONES: {
     readonly warning: "warning";
     readonly danger: "danger";
 };
+export declare const MARKDOWN_CALLOUT_CLASSES: {
+    readonly root: "k2b-callout";
+    readonly icon: "k2b-callout__icon";
+};
+/** Fixed attributes for decorative callout icons, including hosts with their own sanitizer. */
+export declare const MARKDOWN_CALLOUT_ICON_ATTRIBUTES: {
+    readonly class: "k2b-callout__icon";
+    readonly "aria-hidden": "true";
+    readonly width: "20";
+    readonly height: "20";
+    readonly viewBox: "0 0 24 24";
+    readonly fill: "none";
+    readonly stroke: "currentColor";
+    readonly "stroke-width": "2";
+    readonly "stroke-linecap": "round";
+    readonly "stroke-linejoin": "round";
+};
 export type MarkdownInfoBlockType = keyof typeof TONES;
 export type MarkdownInfoBlock = {
     type: MarkdownInfoBlockType;
@@ -48,10 +65,10 @@ export type MarkdownInfoBlockRenderInput = {
  */
 export declare const scanMarkdownInfoBlock: (source: string) => MarkdownInfoBlock | null;
 /**
- * Renders an info block as the calm `NoticeCard`: the tone tints the surface,
- * the text stays neutral, and there is no icon. A title is the visible heading
- * and names the block; without one, the localized type name is announced to
- * screen readers only.
+ * Renders a callout on a tinted surface without a border. The decorative icon
+ * and title use the tone colour; body text stays neutral. A title is the
+ * visible heading and names the block; without one, screen readers hear the
+ * localized type name.
  */
 export declare const renderMarkdownInfoBlock: (input: MarkdownInfoBlockRenderInput) => string;
 /**

package/dist/types/feedback/prompts.d.ts

@@ -1,5 +1,5 @@
 import { type JSX } from "solid-js";
-import { type OpenDialogOptions } from "./dialog-core";
+import { type DialogRender, type OpenDialogOptions } from "./dialog-core";
 export interface DialogOptions {
     signal?: AbortSignal;
     title?: string;
@@ -165,7 +165,13 @@ export declare const prompts: {
     prompt: typeof promptText;
     promptNumber: typeof promptNumber;
     form: <T extends Record<string, FieldSchema>>(config: PromptFormOptions<T>) => Promise<InferFormValues<T> | null>;
-    dialog: <T extends unknown = unknown>(component: (close: (result?: T) => void) => JSX.Element, options?: DialogOptions) => Promise<T | undefined>;
+    /**
+     * Open custom content with a typed close callback and the dialog render context.
+     * Register a dismiss handler to guard Escape, backdrop clicks and the supplied header's close button,
+     * for example while saving. Explicit close(result) bypasses the guard. Without a handler, dismissal
+     * keeps its existing behavior, including a header close button independent of cancelBehavior.
+     */
+    dialog: <T extends unknown = unknown>(component: DialogRender<T>, options?: DialogOptions) => Promise<T | undefined>;
     search: typeof openSearchPrompt;
     error: (content: string | HTMLElement, options?: DialogOptions) => Promise<unknown>;
 };

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

@@ -2,3 +2,5 @@ export type { FormatBytesProps, FormatCurrencyProps, FormatDateProps, FormatDate
 export { Format } from "./Format";
 export type { LocaleProviderProps } from "./locale";
 export { LocaleProvider, useLocale } from "./locale";
+export type { FormattedShortcut, KeyboardPlatform, ShortcutFormatOptions, ShortcutKey } from "./shortcut";
+export { formatShortcut, keyboardPlatform } from "./shortcut";

package/dist/types/intl/shortcut-messages.d.ts

@@ -0,0 +1,35 @@
+/** Imperative UI inherits the document locale when no locale is supplied. */
+export declare const resolveShortcutMessages: (locale?: string) => {
+    ctrlLabel: string;
+    altLabel: string;
+    shiftLabel: string;
+    metaLabel: string;
+    control: string;
+    appleControl: string;
+    option: string;
+    shift: string;
+    command: string;
+    alt: string;
+    meta: string;
+    arrowup: string;
+    arrowdown: string;
+    arrowleft: string;
+    arrowright: string;
+    enter: string;
+    escape: string;
+    tab: string;
+    space: string;
+    backspace: string;
+    delete: string;
+    home: string;
+    end: string;
+    pageup: string;
+    pagedown: string;
+    spaceLabel: string;
+    deleteLabel: string;
+    homeLabel: string;
+    endLabel: string;
+    pageupLabel: string;
+    pagedownLabel: string;
+};
+export declare const checkShortcutMessages: () => import("@k2b/stdlib").CatalogIssue[];

package/dist/types/intl/shortcut.d.ts

@@ -0,0 +1,29 @@
+export type KeyboardPlatform = "apple" | "other";
+/**
+ * Apple keyboards name the platform modifier Command. `source` is a User-Agent or `navigator.platform` string.
+ * Without `source`, reads the runtime's navigator; server callers pass the request's User-Agent.
+ * @example keyboardPlatform("MacIntel") // "apple"
+ */
+export declare const keyboardPlatform: (source?: string) => KeyboardPlatform;
+export type ShortcutKey = {
+    /** What the cap shows: "⌘", "Strg", "K", "↵". */
+    label: string;
+    /** What a screen reader says: "Command", "Steuerung", "K", "Enter". */
+    name: string;
+};
+export type FormattedShortcut = {
+    keys: ShortcutKey[];
+    /** "⌘K" on Apple, "Ctrl+K" / "Strg+K" elsewhere. */
+    label: string;
+    /** "Command K", "Steuerung K". */
+    name: string;
+};
+export type ShortcutFormatOptions = {
+    platform?: KeyboardPlatform;
+    locale?: string;
+};
+/**
+ * Formats one plus-separated shortcut in canonical modifier order.
+ * @example formatShortcut("mod+alt+n", { platform: "apple" }).label // "⌥⌘N"
+ */
+export declare const formatShortcut: (shortcut: string, options?: ShortcutFormatOptions) => FormattedShortcut;

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

@@ -2,12 +2,14 @@ import { type LinkNavigateEvent, type NavigationScrollMode } from "@k2b/ssr/nav"
 import { type JSX } from "solid-js";
 import { type AppWorkspaceLayoutState } from "./app-workspace-state";
 import type { ScrollAreaProps } from "./ScrollArea";
+import { type AppWorkspaceSidebarSwitcherProps } from "./SidebarSwitcher";
 export type AppWorkspaceProps = {
     children: JSX.Element;
     class?: string;
     /** A host with its own phone chrome can use the full canvas below 48rem (768 px). */
     mobileSurface?: "contained" | "flush";
-    /** Draws no frame: no border, corner radius, or shadow, for an overview that is the page itself. */
+    /** Removes the workspace's own border, radius, and shadow for an overview that is the page itself.
+     * A host may frame the outermost workspace as its app card, as Cloud does from 1536 px on signed-in pages. */
     flat?: boolean;
     resizable?: boolean;
     /**
@@ -233,6 +235,7 @@ export type AppWorkspaceSidebarItemIconProps = {
 };
 export type AppWorkspaceSidebarItemLabelProps = {
     children: JSX.Element;
+    /** False keeps one line with an ellipsis; rows wrap long labels onto a second line by default. */
     marquee?: boolean;
 };
 export type AppWorkspaceSidebarItemMetaProps = {
@@ -354,6 +357,7 @@ type AppWorkspaceComponent = ((props: AppWorkspaceProps) => JSX.Element) & {
     SidebarDesktop: (props: {
         children: JSX.Element;
     }) => JSX.Element;
+    SidebarSwitcher: (props: AppWorkspaceSidebarSwitcherProps) => JSX.Element;
     SidebarSection: (props: AppWorkspaceSidebarSectionProps) => JSX.Element;
     SidebarBody: (props: AppWorkspaceSidebarBodyProps) => JSX.Element;
     SidebarFooter: (props: AppWorkspaceSidebarContentProps) => JSX.Element;

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

@@ -0,0 +1,65 @@
+import { type JSX } from "solid-js";
+/** One container a person can switch to, such as a notebook, a space, or a mailbox. */
+export type AppWorkspaceSwitcherOption = {
+    id: string;
+    label: string;
+    /** One secondary fact, such as a mailbox's address. */
+    description?: string;
+    /** Tabler icon class; without it the row takes the switcher's icon. */
+    icon?: string;
+    /** Tints the icon; without it the app accent does. */
+    color?: string;
+    href: string;
+};
+/** A row below the containers, such as "New notebook" or "All notebooks". */
+export type AppWorkspaceSwitcherAction = {
+    id: string;
+    label: string;
+    icon: string;
+    disabled?: boolean;
+} & ({
+    href: string;
+    action?: never;
+} | {
+    action: () => void;
+    href?: never;
+});
+export type AppWorkspaceSidebarSwitcherProps = {
+    /** The current container's ID among `options`. */
+    currentId: string;
+    /** The current container's name. */
+    label: string;
+    /** One secondary fact under the name, such as a mailbox's address. */
+    description?: string;
+    icon: string;
+    /** Tints the icon; without it the app accent does. */
+    color?: string;
+    /** Names the button's purpose and its panel, such as "Switch notebook". */
+    switchLabel: string;
+    /** Every container the person can switch to, the current one included; `undefined` until they are loaded. */
+    options?: readonly AppWorkspaceSwitcherOption[];
+    /** Shown in place of the options when loading them failed; the panel offers to try again through `onLoad`. */
+    error?: string;
+    /**
+     * Asks for `options` while they are `undefined`: when a pointer or the focus first reaches the button, so the list
+     * is usually there when the panel opens, on every opening, and from the panel's retry. Ignore repeated calls while a
+     * request runs.
+     */
+    onLoad?: () => void;
+    actions?: readonly AppWorkspaceSwitcherAction[];
+    /**
+     * A host menu around the switcher, such as the phone menu, finishes dismissing itself before a chosen container
+     * opens or an action runs; `false` cancels the choice. Navigation passes its own.
+     */
+    beforeSelect?: () => boolean | void | Promise<boolean | void>;
+    /** Sizes the switcher in its place, such as `flex-1` beside a button in one row. */
+    class?: string;
+};
+/** From this many containers the panel scrolls, so it offers a search field. */
+export declare const APP_WORKSPACE_SWITCHER_SEARCH_FROM = 8;
+/**
+ * The current container at the top of a sidebar: its icon, name, and an optional fact, with a chevron that opens the
+ * other containers, a search field when there are many, and actions such as "New …" and "All …". The rows are links,
+ * so a container also opens in a new tab. In a collapsed rail it shows only the icon and opens beside the rail.
+ */
+export declare function AppWorkspaceSidebarSwitcher(props: AppWorkspaceSidebarSwitcherProps): JSX.Element;

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

@@ -0,0 +1,24 @@
+import { type JSX } from "solid-js";
+import type { MaybeAccessor } from "../inputs/field-contract";
+export type TableOfContentsItem = {
+    id: string;
+    label: string;
+};
+export type TableOfContentsProps = {
+    items: readonly TableOfContentsItem[];
+    /** Visible heading and navigation name. Defaults to the localized "On this page". */
+    title?: string;
+    /** Element whose scrolling decides the active section. Defaults to the window. */
+    scrollRoot?: MaybeAccessor<HTMLElement | undefined>;
+    /** Stay in view inside the caller's layout. */
+    sticky?: boolean;
+    /** Called when another section becomes active. */
+    onActiveChange?: (id: string | undefined) => void;
+    class?: string;
+};
+/**
+ * Native section links with a scroll spy on the window or a content container.
+ * @example <TableOfContents items={[{ id: "sharing", label: "Sharing" }]} sticky />
+ */
+export declare function TableOfContents(props: TableOfContentsProps): JSX.Element;
+export default TableOfContents;

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

@@ -40,5 +40,8 @@ export type { SettingsCollectionActionProps, SettingsCollectionItemActionsProps,
 export { default as SettingsCollection } from "./SettingsCollection";
 export type { SettingsModalFooterProps, SettingsModalGroupProps, SettingsModalProps, SettingsModalTabProps, SettingsModalTabTone, } from "./SettingsModal";
 export { default as SettingsModal } from "./SettingsModal";
+export { APP_WORKSPACE_SWITCHER_SEARCH_FROM, type AppWorkspaceSidebarSwitcherProps, type AppWorkspaceSwitcherAction, type AppWorkspaceSwitcherOption, } from "./SidebarSwitcher";
 export type { TabBarItem, TabBarProps } from "./TabBar";
 export { default as TabBar } from "./TabBar";
+export type { TableOfContentsItem, TableOfContentsProps } from "./TableOfContents";
+export { TableOfContents } from "./TableOfContents";

package/dist/types/layout/navigation-model.d.ts

@@ -1,6 +1,7 @@
 import type { LinkNavigateEvent, NavigationScrollMode } from "@k2b/ssr/nav";
 import type { Accessor } from "solid-js";
 import type { IntentTone } from "../semantics";
+import type { AppWorkspaceSidebarSwitcherProps } from "./SidebarSwitcher";
 /** A status icon at a row's end, such as "running". `label` names it for screen readers and as its tooltip. */
 export type NavigationStatus = {
     icon: string;
@@ -72,6 +73,8 @@ export type NavigationItem = NavigationEntry & ({
 });
 export type NavigationOptions = {
     items: Accessor<readonly NavigationItem[]>;
+    /** The container the navigation works in, shown above the items with the same switcher as the sidebar's head. */
+    switcher?: Accessor<AppWorkspaceSidebarSwitcherProps>;
     onAction?: (action: string) => void | Promise<void>;
     onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
     /** Receives disclosure toggles of items that carry `expanded`; the owner decides the next state. */
@@ -81,6 +84,7 @@ export declare function findNavigationItem(items: readonly NavigationItem[], id:
 /** One live source for renderers; no router, registry, fetching or persisted state. */
 export declare function createNavigation(options: NavigationOptions): {
     items: Accessor<readonly NavigationItem[]>;
+    switcher: Accessor<AppWorkspaceSidebarSwitcherProps> | undefined;
     onNavigate: ((event: LinkNavigateEvent) => void | Promise<void>) | undefined;
     onExpandedChange: ((id: string, expanded: boolean) => void) | undefined;
     activate(id: string): Promise<void>;

package/dist/types/layout/table-of-contents-messages.d.ts

@@ -0,0 +1,4 @@
+export declare const useTableOfContentsMessages: () => () => {
+    title: string;
+};
+export declare const checkTableOfContentsMessages: () => import("@k2b/stdlib").CatalogIssue[];

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

@@ -1,7 +1,10 @@
+import { type LinkNavigateEvent } from "@k2b/ssr/nav";
 import { type JSX } from "solid-js";
 export type LinkCardColor = "blue" | "emerald" | "violet" | "orange" | "red" | "amber" | "zinc" | "cyan" | "rose";
 export type LinkCardProps = {
     href: string;
+    navigation?: "document" | "enhanced";
+    onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
     title: string;
     description: string;
     icon: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -45,19 +45,19 @@
   "dependencies": {
     "@fontsource/ibm-plex-mono": "5.3.0",
     "@fontsource/ibm-plex-sans": "5.3.0",
-    "@k2b/stdlib": "0.28.0",
+    "@k2b/stdlib": "0.29.0",
     "@tabler/icons-webfont": "3.48.0",
     "marked": "18.0.14",
     "qr-scanner": "1.4.2"
   },
   "peerDependencies": {
-    "@k2b/ssr": "^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0",
+    "@k2b/ssr": "^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0 || ^0.16.0",
     "solid-js": "^1.9.10"
   },
   "devDependencies": {
     "@babel/core": "8.0.6",
     "@babel/preset-typescript": "8.0.1",
-    "@k2b/ssr": "0.15.0",
+    "@k2b/ssr": "0.16.0",
     "@types/babel__core": "7.20.5",
     "@types/bun": "1.4.2",
     "axe-core": "4.11.0",