@k2b/ui 0.24.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;

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-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

@@ -8,7 +8,8 @@ export type AppWorkspaceProps = {
     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;
     /**
@@ -234,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 = {

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

@@ -43,3 +43,5 @@ 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/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.24.0",
+  "version": "0.25.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -51,13 +51,13 @@
     "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.1",
+    "@k2b/ssr": "0.16.0",
     "@types/babel__core": "7.20.5",
     "@types/bun": "1.4.2",
     "axe-core": "4.11.0",