@k2b/ui 0.12.0 → 0.14.0

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

@@ -26,14 +26,18 @@ export type MarkdownRenderOptions = {
     /** Optional protocol allowlist, including trailing colons. Relative URLs resolve as HTTPS. */
     linkProtocols?: readonly string[];
     linkTarget?: "_blank";
+    /** Locale for the screen-reader names of untitled info blocks. `MarkdownView` passes the inherited render locale. */
+    locale?: string;
 };
 export declare const renderSafeMarkdown: (markdown: string, options?: MarkdownRenderOptions) => string;
 /**
  * Markdown View Component (SSR)
  *
  * Renders untrusted Markdown safely by default. Raw HTML and unsafe link
- * protocols are escaped. Already-rendered HTML requires the deliberately named
- * `trustedHtml` boundary; the caller owns sanitization in that mode.
+ * protocols are escaped. Info blocks (`:::note`, `:::info`, `:::success`,
+ * `:::warning`, `:::danger`) render as the calm `NoticeCard`. Already-rendered
+ * HTML requires the deliberately named `trustedHtml` boundary; the caller owns
+ * sanitization in that mode.
  *
  * @example
  * ```tsx

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

@@ -31,6 +31,7 @@ export { default as Lightbox } from "./Lightbox";
 export type { LogTableEntry } from "./LogEntriesTable";
 export { default as LogEntriesTable } from "./LogEntriesTable";
 export { default as MarkdownView, type MarkdownRenderOptions, type MarkdownViewProps, renderSafeMarkdown } from "./MarkdownView";
+export { type MarkdownInfoBlock, type MarkdownInfoBlockRenderInput, type MarkdownInfoBlockType, markdownInfoBlocks, renderMarkdownInfoBlock, scanMarkdownInfoBlock, } from "./markdown-info-blocks";
 export { Pagination, type PaginationProps } from "./Pagination";
 export type { PdfPreviewProps, PdfPreviewRequest } from "./PdfPreview";
 export { default as PdfPreview } from "./PdfPreview";

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

@@ -0,0 +1,67 @@
+import { type MarkedExtension } from "marked";
+/**
+ * Markdown info blocks: one grammar and one look for every Markdown surface.
+ *
+ * ```markdown
+ * :::warning Before deleting
+ * Deleting an item cannot be undone.
+ * :::
+ * ```
+ *
+ * The opening line holds `:::`, a type in any letter case, and an optional
+ * plain-text title. The block ends at a line holding only `:::`, indented no
+ * deeper than the opener; code, lists, quotes, and HTML inside the body cannot
+ * end it. The body is ordinary Markdown. A block that is never closed stays
+ * ordinary text.
+ */
+declare const TONES: {
+    readonly note: "neutral";
+    readonly info: "info";
+    readonly success: "success";
+    readonly warning: "warning";
+    readonly danger: "danger";
+};
+export type MarkdownInfoBlockType = keyof typeof TONES;
+export type MarkdownInfoBlock = {
+    type: MarkdownInfoBlockType;
+    /** Plain-text title from the opening line. */
+    title?: string;
+    /** Raw Markdown between the opening and closing lines, with `\n` line breaks. */
+    body: string;
+    /** Source length through the closing line, or the whole source when the block is not closed. */
+    length: number;
+    closed: boolean;
+};
+export type MarkdownInfoBlockRenderInput = {
+    type: MarkdownInfoBlockType;
+    title?: string;
+    /** Already rendered body HTML. The caller owns its sanitization. */
+    bodyHtml: string;
+    /** Locale for the screen-reader name of an untitled block. */
+    locale?: string;
+};
+/**
+ * Reads the info block that starts `source`. Returns `null` when the first
+ * line is not an info-block opener. Applications with their own Markdown
+ * pipeline use this to recognize exactly the blocks `MarkdownView` renders.
+ * Any line endings are accepted; `length` counts `source` as given.
+ */
+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.
+ */
+export declare const renderMarkdownInfoBlock: (input: MarkdownInfoBlockRenderInput) => string;
+/**
+ * `marked` extension for info blocks at the top level of a document. Blocks
+ * inside lists, quotes, or another block stay ordinary text. The body goes
+ * through the host's own Markdown renderer, so its escaping and link rules
+ * apply unchanged. Locales that share a UI message catalog get the same
+ * extension, so a host may cache one `marked` instance per extension.
+ */
+export declare const markdownInfoBlocks: (options?: {
+    locale?: string;
+}) => MarkedExtension;
+export {};

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

@@ -0,0 +1,26 @@
+import { type JSX } from "solid-js";
+import type { InstallPrompt } from "./install";
+export type InstallGuideProps = {
+    /** The name people see on their Home Screen, used in the guidance text. */
+    appName: string;
+    install: InstallPrompt;
+    /**
+     * The address a browser inside another app copies, to open it in Safari or Chrome. Shown as text when copying
+     * fails, so it can be copied by hand.
+     */
+    url: string;
+    /**
+     * An application note under the installation steps or the embedded browser's link, for example what else the
+     * installed app enables.
+     */
+    note?: string;
+    class?: string;
+};
+/**
+ * Explains how to install the current page as an app on this platform: the browser's own dialog where it offers
+ * one, otherwise the steps for Safari on iPhone, iPad, and Mac, other browsers on iPhone and iPad, Android, and other
+ * browsers. A browser inside another app cannot install, so it gets a warning and the link to copy into Safari or
+ * Chrome instead. The host owns the surrounding surface, its heading, and dismissal.
+ */
+export declare function InstallGuide(props: InstallGuideProps): JSX.Element;
+export default InstallGuide;

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

@@ -0,0 +1,19 @@
+export type AnnouncePoliteness = "polite" | "assertive";
+export type AnnounceOptions = {
+    /** `polite` waits until the screen reader is idle; `assertive` interrupts it. Defaults to `polite`. */
+    politeness?: AnnouncePoliteness;
+};
+/**
+ * One pair of persistent, empty live regions per document, polite and assertive, shared by `announce` and every
+ * toast. A region that already exists when its text arrives is announced reliably, unlike one inserted with its text
+ * already inside. They sit directly in the body, outside every portal and the toast rail, which moves into a fresh
+ * top-layer element for every toast, so no scope that closes takes them along.
+ */
+export declare const ensureLiveRegions: (doc: Document) => HTMLElement;
+/**
+ * Tells screen readers about an outcome without showing anything: a change the screen shows but the focused control
+ * does not say, because a shortcut acted, the control was busy, or it was replaced. Each message is its own line, so
+ * a burst of messages or the same message twice is still read. Calls without `document`, including during SSR, do
+ * nothing.
+ */
+export declare const announce: (message: string, options?: AnnounceOptions) => void;

package/dist/types/feedback/dialog-core.d.ts

@@ -8,6 +8,11 @@ export type OpenDialogOptions = {
     initialFocus?: "first-input" | "none" | ((dialog: HTMLDialogElement) => HTMLElement | null);
     cancelBehavior?: "resolve-undefined" | "ignore";
     ariaLabel?: string;
+    /**
+     * Add a same-URL history entry while the dialog is open, so the browser's or the phone's Back closes the dialog
+     * instead of leaving the page. Closing the dialog removes the entry again; the returned promise settles after that.
+     */
+    history?: boolean;
 };
 export type DialogRender<T> = (close: DialogClose<T>, context: {
     dialog: HTMLDialogElement;

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

@@ -1,12 +1,19 @@
+export type { AnnounceOptions, AnnouncePoliteness } from "./announce";
+export { announce } from "./announce";
 export type { DialogClose, DialogCore, DialogRender, OpenDialogOptions } from "./dialog-core";
 export { dialogCore } from "./dialog-core";
 export type { HoverPreviewController, HoverPreviewOptions, HoverPreviewPlacement, HoverPreviewProps } from "./HoverPreview";
 export { createHoverPreview, HoverPreview } from "./HoverPreview";
 export type { InlineGuidanceProps } from "./InlineGuidance";
 export { default as InlineGuidance } from "./InlineGuidance";
+export type { InstallGuideProps } from "./InstallGuide";
+export { default as InstallGuide } from "./InstallGuide";
+export type { InstallationPlatform, InstallPrompt } from "./install";
+export { createInstallPrompt, installationPlatform } from "./install";
 export type { ConfirmOptions, DialogOptions, FieldSchema, PromptFieldBase, PromptSearchInput, PromptSearchItem, PromptSearchOptions, } from "./prompts";
 export { createFormState, DialogHeader, prompts } from "./prompts";
 export type { TooltipAnchorProps, TooltipPlacement, TooltipProps, TooltipTriggerProps } from "./Tooltip";
 export { Tooltip } from "./Tooltip";
+export { syncThemeColor } from "./theme-color";
 export type { ToastAction, ToastFn, ToastHandle, ToastOptions, ToastSlot, ToastVariant } from "./toast";
 export { isPointInsideToast, toast } from "./toast";

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

@@ -0,0 +1,32 @@
+/**
+ * Which installation steps a browser needs. `apple-in-app` and `in-app` are browsers embedded in another app, on
+ * iPhone or iPad and elsewhere, which cannot install at all. `apple-browser` is Chrome, Firefox, Edge, or another
+ * browser on iPhone or iPad, which installs through its Share menu but less reliably than Safari. `android-browser`
+ * is an Android browser other than Chrome.
+ */
+export type InstallationPlatform = "in-app" | "apple-in-app" | "apple-browser" | "apple-mobile" | "apple-desktop" | "android-browser" | "android" | "generic";
+/**
+ * Classifies the browser from its user agent; `platform` and `touchPoints` only tell an iPad that reports a Mac apart.
+ * A pure function, so the server and the browser compute the same value from the same user agent. Not a device
+ * check: an installed app on iPhone may itself look like an embedded browser.
+ */
+export declare function installationPlatform(userAgent: string, platform: string, touchPoints: number): InstallationPlatform;
+export type InstallPrompt = {
+    platform: InstallationPlatform;
+    /** Running from the Home Screen or as an installed app, or installed during this visit. */
+    installed: () => boolean;
+    /** The browser offered its own installation dialog, which `install()` opens. */
+    canPrompt: () => boolean;
+    busy: () => boolean;
+    /** The person accepted the browser's dialog; the browser finishes the installation. */
+    requested: () => boolean;
+    /** The browser's dialog could not be opened. */
+    failed: () => boolean;
+    /** Opens the browser's dialog once. Call it directly from a click. */
+    install: () => Promise<void>;
+};
+/**
+ * Tracks whether the page runs installed and captures the browser's installation prompt. Browser-only; call it once,
+ * when the page loads, under an owner that lives as long as the page: Chrome offers its prompt only once, early.
+ */
+export declare function createInstallPrompt(): InstallPrompt;

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

@@ -13,6 +13,8 @@ export interface DialogOptions {
     surface?: "default" | "bare";
     header?: false;
     cancelBehavior?: OpenDialogOptions["cancelBehavior"];
+    /** Back closes the prompt like Cancel, as in a phone app; see `OpenDialogOptions.history`. */
+    history?: boolean;
 }
 export interface ConfirmOptions extends DialogOptions {
     confirmationPhrase?: string;

package/dist/types/feedback/theme-color.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gives the browser chrome the page's current background after a theme change: the `html` background, which iOS
+ * shows behind the status bar and in overscroll, and every `theme-color` meta element. A `media` attribute is
+ * dropped, because the page's chosen theme wins over the system scheme. Browser-only.
+ */
+export declare function syncThemeColor(root?: Element): void;

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

@@ -0,0 +1,20 @@
+import { type JSX } from "solid-js";
+export type QrScannerError = "denied" | "unavailable";
+export type QrScannerProps = {
+    /** Decoded text is untrusted. Return `true` to accept it and stop the camera, `false` to reject it and keep scanning. */
+    onResult: (text: string) => boolean;
+    /** The page was hidden or left; unmount the scanner. */
+    onStop: () => void;
+    /** The camera could not start: access was denied, or there is no usable camera. Offer another way in. */
+    onError: (reason: QrScannerError) => void;
+    /** What to point the camera at. Defaults to a generic QR code hint. */
+    instructions?: string;
+    class?: string;
+};
+/**
+ * Scans a QR code with the rear camera. Each mount owns exactly one camera session, which stops when the scanner
+ * unmounts, the page is hidden, or a result is accepted. The scanning engine loads only when the scanner mounts.
+ * Decoded content is never logged.
+ */
+export declare function QrScanner(props: QrScannerProps): JSX.Element;
+export default QrScanner;

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

@@ -27,6 +27,8 @@ export type { MarkdownEditorProps } from "./markdown/MarkdownEditor";
 export { MarkdownEditor } from "./markdown/MarkdownEditor";
 export type { NumberInputProps } from "./NumberInput";
 export { NumberInput } from "./NumberInput";
+export type { QrScannerError, QrScannerProps } from "./QrScanner";
+export { QrScanner } from "./QrScanner";
 export type { ChoiceAppearance, SelectGridSize, SelectGroup, SelectOption, SelectProps, SelectSourceOption, SelectView } from "./Select";
 export { Select } from "./Select";
 export type { SelectChipOption, SelectChipProps } from "./SelectChip";

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

@@ -33,6 +33,11 @@ declare const uiMessages: import("@k2b/stdlib").Catalog<{
     close: string;
     closeDialog: string;
     copied: string;
+    infoBlockNote: string;
+    infoBlockInfo: string;
+    infoBlockSuccess: string;
+    infoBlockWarning: string;
+    infoBlockDanger: string;
     copy: string;
     closeLightbox: string;
     couldNotLoadData: string;
@@ -427,6 +432,48 @@ declare const uiMessages: import("@k2b/stdlib").Catalog<{
     audioUnsupported: string;
     videoUnsupported: string;
     yes: string;
+    installApp: string;
+    installNative: ({ appName }: {
+        appName: string;
+    }) => string;
+    installRequested: string;
+    installFailed: string;
+    installOpenShare: string;
+    installOpenShareDetail: string;
+    installHomeScreen: string;
+    installHomeScreenDetail: string;
+    installConfirmAdd: string;
+    installConfirmAddDetail: string;
+    installOpenShareBrowserDetail: string;
+    installSafariFallback: string;
+    installSafariMenu: string;
+    installSafariMenuDetail: string;
+    installAddDock: string;
+    installAddDockDetail: string;
+    installBrowserMenu: string;
+    installBrowserMenuDetail: string;
+    installAndroidDetail: string;
+    installBrowserDetail: string;
+    installUnavailable: string;
+    installAppleInAppTitle: string;
+    installAppleInAppDetail: ({ appName }: {
+        appName: string;
+    }) => string;
+    installInAppTitle: string;
+    installInAppDetail: ({ appName }: {
+        appName: string;
+    }) => string;
+    installAppleBrowserTitle: string;
+    installAppleBrowserDetail: string;
+    installAndroidBrowserTitle: string;
+    installAndroidBrowserDetail: string;
+    installCopyLink: string;
+    installLinkCopied: string;
+    installCopyFailed: string;
+    qrCameraPreview: string;
+    qrCameraStarting: string;
+    qrCameraInstructions: string;
+    qrCameraPrivacy: string;
 }>;
 export type UiMessages = ReturnType<(typeof uiMessages)["resolve"]>["t"];
 /** Generic component chrome owned by @k2b/ui, resolved from the inherited render locale. */

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

@@ -0,0 +1,40 @@
+import { type JSX } from "solid-js";
+export type MobileShellProps = {
+    /** Usually `MobileShell.Header`; it sits above the scroll area and pads the top safe area. */
+    header: JSX.Element;
+    /** Usually a `TabBar`; it sits below the scroll area and pads the bottom safe area itself. */
+    footer?: JSX.Element;
+    /** The page content, inside the shell's only scroll area. */
+    children: JSX.Element;
+    class?: string;
+};
+export type MobileShellHeaderProps = {
+    title: string;
+    /** A Back control before the title: a link with `href`, otherwise a button. */
+    back?: {
+        href?: string;
+        onClick?: () => void;
+        label: string;
+    };
+    /** Controls after the title, such as a menu. */
+    actions?: JSX.Element;
+};
+/**
+ * Keeps a mounted shell working: the footer height on the body, which the portalled toast rail reads, the room a
+ * persistent toast takes from the scroll area, the scroll area's edge fade, and immediate feedback for link taps.
+ * The fade is the only cue at the footer's edge, which has no rule. `MobileShell` calls it itself;
+ * a page that renders the shell on the server without hydrating it calls it once in the browser. Returns the
+ * cleanup.
+ */
+export declare function observeMobileShell(root: HTMLElement): () => void;
+declare function MobileShellRoot(props: MobileShellProps): JSX.Element;
+declare function MobileShellHeader(props: MobileShellHeaderProps): JSX.Element;
+/**
+ * The full-screen frame of a phone app: a header, one scroll area, and an optional footer such as a `TabBar`. While
+ * it is mounted, the document itself never scrolls, pinch zoom and rubber-banding are off, and the toast rail sits
+ * above the footer. Mount one per page, as the page's layout.
+ */
+export declare const MobileShell: typeof MobileShellRoot & {
+    Header: typeof MobileShellHeader;
+};
+export default MobileShell;

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

@@ -0,0 +1,26 @@
+import { type JSX } from "solid-js";
+export type TabBarItem = {
+    id: string;
+    label: string;
+    /** Icon class, for example `ti ti-home`. */
+    icon: string;
+    href: string;
+    /** The header title of the page this item opens, shown while that page loads. Defaults to `label`. */
+    title?: string;
+    /** The page this item leads to is open. */
+    current?: boolean;
+};
+export type TabBarProps = {
+    /** Accessible name of the navigation landmark. */
+    label: string;
+    /** Up to five destinations; further items are not rendered. Put the rest behind a "More" destination. */
+    items: readonly TabBarItem[];
+    class?: string;
+};
+/**
+ * Bottom navigation between a phone app's top-level pages: native links with equal widths, an icon above each label,
+ * and `aria-current="page"` on the open page. Place it in `MobileShell`'s footer; it pads the bottom safe area. There a
+ * tab switches at the first touch: the shell shows the item's `title` while its page loads.
+ */
+export declare function TabBar(props: TabBarProps): JSX.Element;
+export default TabBar;

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

@@ -15,6 +15,8 @@ export type { DiscussionComposerProps, DiscussionItemProps, DiscussionListProps,
 export { default as Discussion } from "./Discussion";
 export type { FloatingWindowClose, FloatingWindowProps, OpenFloatingWindowOptions, } from "./FloatingWindow";
 export { default as FloatingWindow, type FloatingWindowRect, fitFloatingWindowRect, openFloatingWindow, } from "./FloatingWindow";
+export type { MobileShellHeaderProps, MobileShellProps } from "./MobileShell";
+export { default as MobileShell, observeMobileShell } from "./MobileShell";
 export { default as Navigation, type NavigationProps } from "./Navigation";
 export { createNavigation, findNavigationItem, type NavigationController, type NavigationItem, type NavigationOptions, } from "./navigation-model";
 export type { PanelDialogBodyProps, PanelDialogFooterProps, PanelDialogHeaderProps, PanelDialogProps, PanelDialogSectionProps, PanelDialogSurface, PanelDialogTabOption, PanelDialogTabsProps, } from "./PanelDialog";
@@ -35,3 +37,5 @@ 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 type { TabBarItem, TabBarProps } from "./TabBar";
+export { default as TabBar } from "./TabBar";

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

@@ -4,28 +4,28 @@ export type NoticeTone = Extract<IntentTone, "neutral" | "info" | "success" | "w
 type NoticeCardContentProps = {
     title: JSX.Element;
     detail?: JSX.Element;
+    meta?: JSX.Element;
     children?: JSX.Element;
 } | {
     title?: never;
     detail?: never;
+    meta?: never;
     children: JSX.Element;
 };
 export type NoticeCardProps = Omit<JSX.HTMLAttributes<HTMLElement>, "children" | "class" | "title"> & NoticeCardContentProps & {
     tone?: NoticeTone;
-    icon?: string | false;
     class?: string;
     bodyClass?: string;
 };
 export declare const NOTICE_CARD_CLASSES: {
     readonly root: "k2b-notice-card";
-    readonly inner: "k2b-notice-card__inner";
-    readonly icon: "k2b-notice-card__icon";
     readonly content: "k2b-notice-card__content";
+    readonly head: "k2b-notice-card__head";
     readonly title: "k2b-notice-card__title";
+    readonly meta: "k2b-notice-card__meta";
     readonly description: "k2b-notice-card__description";
     readonly body: "k2b-notice-card__body";
 };
-export declare const NOTICE_CARD_ICONS: Readonly<Record<NoticeTone, string>>;
 declare function NoticeCardComponent(props: NoticeCardProps): JSX.Element;
 export type NoticeGridProps<T> = {
     items: readonly T[];

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

@@ -7,7 +7,7 @@ export { LinkCard } from "./LinkCard";
 export type { NotFoundStateAction, NotFoundStateProps } from "./NotFoundState";
 export { NotFoundState } from "./NotFoundState";
 export type { NoticeCardProps, NoticeGridProps, NoticeTone } from "./NoticeCard";
-export { NOTICE_CARD_CLASSES, NOTICE_CARD_ICONS, NoticeCard } from "./NoticeCard";
+export { NOTICE_CARD_CLASSES, NoticeCard } from "./NoticeCard";
 export type { PaperProps, PaperTag } from "./Paper";
 export { Paper } from "./Paper";
 export type { PlaceholderAlign, PlaceholderProps, PlaceholderState, PlaceholderSurface, PlaceholderVariant, } from "./Placeholder";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -46,7 +46,8 @@
     "@fontsource/ibm-plex-sans": "5.3.0",
     "@k2b/stdlib": "0.27.0",
     "@tabler/icons-webfont": "3.48.0",
-    "marked": "18.0.14"
+    "marked": "18.0.14",
+    "qr-scanner": "1.4.2"
   },
   "peerDependencies": {
     "@k2b/ssr": "^0.12.0 || ^0.13.0 || ^0.14.0",