@k2b/ui 0.14.0 → 0.16.0

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

@@ -16,6 +16,8 @@ export type ChatMessageProps = {
 };
 export type ChatActivityProps = {
     label: string;
+    /** Spelled-out name for an expandable row whose visible text abbreviates, such as durations. */
+    ariaLabel?: string;
     description?: string;
     icon?: string;
     /** Optional host-owned leading visual rendered instead of the icon. */

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

@@ -2,6 +2,7 @@ import { type JSX } from "solid-js";
 import type { ChatAction, ChatActivityTone, ChatAttachment, ChatMessageStatus, ChatRole } from "./types";
 export type ChatMessageItem = {
     kind: "message";
+    /** Unique within the timeline. A record with a known id updates its row in place instead of replacing it. */
     id: string;
     role: ChatRole;
     content?: JSX.Element;
@@ -17,6 +18,7 @@ export type ChatMessageItem = {
 };
 export type ChatActivityItem = {
     kind: "activity";
+    /** Unique within the timeline. A record with a known id updates its row in place instead of replacing it. */
     id: string;
     label: string;
     description?: string;

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

@@ -6,6 +6,8 @@ export type FileGridProps<T> = {
     selection: CollectionSelection;
     label: string;
     size?: "sm" | "md" | "lg";
+    /** `list` shows one compact row per item: preview, name, and meta beside each other. Defaults to `grid`. */
+    layout?: "grid" | "list";
     renderPreview: (row: T) => JSX.Element;
     renderLabel: (row: T) => JSX.Element;
     renderMeta?: (row: T) => JSX.Element;
@@ -17,5 +19,8 @@ export type FileGridProps<T> = {
     itemProps?: (row: T) => JSX.HTMLAttributes<HTMLDivElement>;
     class?: string;
 };
-/** File presentation only; the host owns data, menus, leases and permissions. */
+/**
+ * File presentation only; the host owns data, menus, leases and permissions. Items the selection marks with
+ * `isDisabled` stay reachable by keyboard but cannot be selected or opened; say why in `renderMeta`.
+ */
 export declare function FileGrid<T>(props: FileGridProps<T>): JSX.Element;

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

@@ -1,3 +1,4 @@
+import { Marked, Renderer } from "marked";
 type CommonProps = MarkdownRenderOptions & {
     /** Optional additional CSS classes */
     class?: string;
@@ -29,7 +30,14 @@ export type MarkdownRenderOptions = {
     /** Locale for the screen-reader names of untitled info blocks. `MarkdownView` passes the inherited render locale. */
     locale?: string;
 };
+export declare const escapeHtml: (value: string) => string;
+export declare const createSafeRenderer: (options?: MarkdownRenderOptions) => Renderer;
 export declare const renderSafeMarkdown: (markdown: string, options?: MarkdownRenderOptions) => string;
+/**
+ * Internal to the package: the Markdown grammar of `renderSafeMarkdown`, for a component that renders with an adjusted
+ * safe renderer or reads the tokens, as `MessageRow` does.
+ */
+export declare const createSafeMarked: (locale?: string) => Marked;
 /**
  * Markdown View Component (SSR)
  *

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

@@ -0,0 +1,168 @@
+import { type JSX } from "solid-js";
+export type MessageRowAuthor = {
+    /** Display name, shown at the start of a group and read before every message. */
+    name: string;
+    /** Picture URL. Without one, the avatar shows initials on the author's tint. */
+    avatar?: string | null;
+    /** Icon class shown instead of initials, for example for an automated author. */
+    icon?: string;
+};
+export type MessageRowStatus = "pending" | "sent" | "failed";
+export type MessageRowAction = {
+    id: string;
+    /** Accessible name and tooltip. */
+    label: string;
+    /** Icon class, for example `ti ti-arrow-back-up`. */
+    icon: string;
+    onSelect: () => void;
+    disabled?: boolean;
+};
+export type MessageRowQuote = {
+    /** Name of the quoted message's author. */
+    author: string;
+    /** Plain text of the quoted message. It shows at most two lines. */
+    text: string;
+    /** Opens the quoted message, for example by scrolling to it. Without it, the quote is not a control. */
+    onSelect?: () => void;
+};
+export type MessageRowReaction = {
+    /** Stable identity of the reaction, passed to `onToggleReaction`. */
+    key: string;
+    emoji: string;
+    count: number;
+    /** The reader reacted this way; the chip shows pressed. */
+    own?: boolean;
+    /** Who reacted, for example "Nora, Tobias". Read by screen readers and shown as a tooltip. */
+    label?: string;
+};
+export type MessageRowThread = {
+    /** Number of replies. */
+    count: number;
+    /** People who replied, most recent first; the bar shows up to three. */
+    participants?: readonly MessageRowAuthor[];
+    /** Visible time of the last reply, formatted by the caller. */
+    lastReply?: string;
+    lastReplyDateTime?: string | Date;
+    onOpen: () => void;
+};
+type MessageRowAttachmentTarget = {
+    /** Opens the attachment, for example in a lightbox. Takes precedence over `href`. */
+    onOpen?: () => void;
+    /** Opens the attachment in a new tab. Absolute `https` or `http`, or relative. */
+    href?: string;
+};
+export type MessageRowMedia = MessageRowAttachmentTarget & {
+    kind: "image" | "video";
+    /** The image, or the poster frame of a video. Absolute `https` or `http`, relative, `blob`, or `data:image/`. */
+    src: string;
+    /** Describes the image or video for people who cannot see it. */
+    alt: string;
+    /** Stored pixel size. The row reserves the area from it, so nothing moves when the image loads. */
+    width: number;
+    height: number;
+    /** Visible length of a video, for example "0:42". */
+    duration?: string;
+};
+export type MessageRowFile = MessageRowAttachmentTarget & {
+    kind: "file";
+    name: string;
+    /** Second line, for example "PDF · 412 KB". */
+    detail?: string;
+    /** Media type, used with the name to choose the icon. */
+    mediaType?: string;
+    /** Icon class instead of the one chosen from the name. */
+    icon?: string;
+};
+export type MessageRowAttachment = MessageRowMedia | MessageRowFile;
+export type MessageRowProgress = {
+    /** What is happening, for example "Writing" or "Searching the files". */
+    status: string;
+    /** Called by "Stop". */
+    onStop?: () => void;
+};
+export type MessageRowProps = {
+    author: MessageRowAuthor;
+    /** Message text as Markdown. Raw HTML shows as text; links must be absolute and use `https`, `http`, or `mailto`. */
+    text: string;
+    /** Visible time, formatted by the caller, so server and browser render the same text. */
+    time: string;
+    /** Machine-readable time for the `<time>` element. */
+    dateTime?: string | Date;
+    /** The reader's own message: on the right in the accent tint, without avatar or name. */
+    own?: boolean;
+    /**
+     * Starts a group with avatar, name, badge, and time. A continuation shows only its text; screen readers still hear
+     * the author and time. Defaults to true; `startsMessageGroup` decides it from the previous message.
+     */
+    groupStart?: boolean;
+    /** Shown next to the name at the start of a group, for example the kind of account. */
+    badge?: JSX.Element;
+    /** Send state. Sets a line of fixed height below the message: a clock, a check, or "Not sent" with "Retry". */
+    status?: MessageRowStatus;
+    /** Text shown in that line instead of the check once someone has read the message, for example "Read by Nora". */
+    receipt?: string;
+    /** Called by "Retry" while `status` is `"failed"`. */
+    onRetry?: () => void;
+    /** Shown as a toolbar over the message while it is hovered or focused. It never moves the layout. */
+    actions?: readonly MessageRowAction[];
+    /** The message this one answers, shown above it. */
+    quote?: MessageRowQuote;
+    /** Marks the message as forwarded from somewhere else. */
+    forwarded?: boolean;
+    /** Marks the message as edited after it was sent. */
+    edited?: boolean;
+    /** Shows "This message was deleted" instead of the text, quote, attachments, previews, and reactions. */
+    deleted?: boolean;
+    /** Images and videos in a grid with areas reserved from their stored size, then files as chips. */
+    attachments?: readonly MessageRowAttachment[];
+    /** A preview of a link in the text, supplied with its final height. */
+    linkPreview?: JSX.Element;
+    /** A card for an element the message refers to, such as a task or a document, supplied with its final height. */
+    card?: JSX.Element;
+    /**
+     * Reactions in a bar of fixed height. The bar shows whenever this is set, even to an empty list, so chips that come
+     * and go never change the row. Only setting it where it was unset adds a line, so pass it on own messages and on
+     * messages that have or had reactions, and leave it out on others' messages that never had one.
+     */
+    reactions?: readonly MessageRowReaction[];
+    /** Called with a reaction's `key` when the reader presses its chip. Without it, the chips are not controls. */
+    onToggleReaction?: (key: string) => void;
+    /** Called by "Add reaction" in the reaction bar, with the button to anchor a picker to. */
+    onAddReaction?: (anchor: HTMLElement) => void;
+    /** A bar of fixed height that opens the replies to this message. */
+    thread?: MessageRowThread;
+    /** The message is still being written, by a person or an automated author alike: a status line with "Stop". */
+    progress?: MessageRowProgress;
+    class?: string;
+};
+export type MessageSystemRowProps = {
+    /** What happened, for example "Nora added Tobias". */
+    children: JSX.Element;
+    /** Visible time, formatted by the caller. */
+    time?: string;
+    dateTime?: string | Date;
+    /** Icon class shown before the text. */
+    icon?: string;
+    class?: string;
+};
+export type MessageGroupEntry = {
+    /** Stable identity of the author. */
+    author: string;
+    at: Date | number | string;
+    /** System rows never belong to a group. */
+    system?: boolean;
+};
+/**
+ * Whether a message starts a new group: there is no previous message, either is a system row, the author changes, or
+ * more than five minutes passed. Also start a group where you show a separator such as a new day.
+ */
+export declare const startsMessageGroup: (entry: MessageGroupEntry, previous?: MessageGroupEntry | null) => boolean;
+/**
+ * One message in a conversation with many people: own messages on the right, others on the left with avatar, name,
+ * and time at the start of a group. Every part has its final height when the row mounts, so a virtualized list such
+ * as `VirtualFeed` keeps its positions.
+ */
+export declare function MessageRow(props: MessageRowProps): JSX.Element;
+/** A quiet, centered line for something that happened in the conversation, such as a person joining. */
+export declare function MessageSystemRow(props: MessageSystemRowProps): JSX.Element;
+export {};

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

@@ -0,0 +1,81 @@
+import { type Accessor, type JSX } from "solid-js";
+export type VirtualFeedScrollOptions = {
+    /** Where the item lands in the visible area. Defaults to `"center"`. */
+    align?: "start" | "center";
+    /** Tints the item briefly so the reader finds it. */
+    highlight?: boolean;
+};
+export type VirtualFeedController = {
+    /**
+     * Scrolls to a loaded item, also when the reader's scroll still coasts. Returns false when no loaded item has this
+     * key, so the caller can load around it first.
+     */
+    scrollToKey: (key: string, options?: VirtualFeedScrollOptions) => boolean;
+    /**
+     * Follows the end again, also when the reader's scroll still coasts. When newer items exist but are not loaded, it
+     * asks `onLoadNewest` for them first.
+     */
+    scrollToEnd: () => void;
+    /** Whether the reader is at the end and new items keep the feed there. */
+    isAtEnd: () => boolean;
+};
+export type VirtualFeedProps<T> = {
+    /** Loaded items, oldest first. Replace the array to add, remove, or change items. */
+    items: readonly T[];
+    /** Stable, unique identity of an item across updates. */
+    getKey: (item: T) => string;
+    /** Height in px before the item was measured. Close estimates mean fewer corrections while scrolling. */
+    estimateSize: (item: T) => number;
+    /** Content of one item, created once per item object as with Solid's `For`. `index` is its position in `items`. */
+    children: (item: T, index: Accessor<number>) => JSX.Element;
+    /** Accessible name of the feed. */
+    label: string;
+    /** Accessible name of one item, for example its author and time. */
+    itemLabel?: (item: T) => string | undefined;
+    /**
+     * Label shown above an item, for example when the day changes. Return nothing for no separator. While `hasOlder` is
+     * set, the first loaded item has no known predecessor and gets none.
+     */
+    separator?: (item: T, previous: T | undefined) => JSX.Element;
+    /** Key of the first item the reader has not seen; a marker appears above it. */
+    markerKey?: string | null;
+    /** Text of that marker. Defaults to "New". */
+    markerLabel?: string;
+    /** Older items exist that `items` does not contain yet. */
+    hasOlder?: boolean;
+    /** Newer items exist that `items` does not contain yet. */
+    hasNewer?: boolean;
+    /** Called near the start of the loaded items while `hasOlder` is true. Prepend the next older page to `items`. */
+    onLoadOlder?: () => unknown;
+    /** Called near the end of the loaded items while `hasNewer` is true. Append the next newer page to `items`. */
+    onLoadNewer?: () => unknown;
+    /** Called by "Jump to latest" while `hasNewer` is true. Replace `items` with the newest page. */
+    onLoadNewest?: () => unknown;
+    /** Marks the feed as busy for assistive technology, for example during the first load. */
+    busy?: boolean;
+    /** Number of items in the whole feed when known. */
+    totalCount?: number;
+    /** One-based position of `items[0]` in the whole feed when known. */
+    firstPosition?: number;
+    /**
+     * Count shown on "Jump to latest". Defaults to the new items added while the reader was away from the end, which
+     * excludes pages of older history loaded toward the end.
+     */
+    newCount?: number;
+    /** Text announced for new items added at the end, bundled per second. Return nothing to stay silent. */
+    announce?: (added: readonly T[]) => string | undefined;
+    /** Called when the reader reaches or leaves the end. */
+    onEndChange?: (atEnd: boolean) => void;
+    /** Receives the controller once the feed is mounted. */
+    controller?: (controller: VirtualFeedController) => void;
+    /** Shown while `items` is empty. */
+    empty?: JSX.Element;
+    class?: string;
+};
+/**
+ * A virtualized feed of items with variable heights that grows at both ends and keeps the reading position: it stays
+ * at the end while the reader is there, and otherwise keeps the item in view where it is, whatever loads, grows, or
+ * resizes around it.
+ */
+export declare function VirtualFeed<T>(props: VirtualFeedProps<T>): JSX.Element;
+export default VirtualFeed;

package/dist/types/content/collection-selection.d.ts

@@ -4,14 +4,28 @@ export type SelectionModifiers = {
     metaKey?: boolean;
 };
 export type CollectionSelection = ReturnType<typeof createCollectionSelection>;
-/** One selection and focus model shared by alternate presentations of a collection. */
+/**
+ * One selection and focus model shared by alternate presentations of a collection.
+ *
+ * `ids` is the collection in display order. `isDisabled` marks items that stay in focus order, so the keyboard and
+ * screen readers still reach them, but can never be selected. `multiple: false` keeps at most one ID selected: a
+ * click, toggle, or arrow key selects only that item, and ranges and select-all do nothing.
+ *
+ * `checklist: true` suits choosing on touch screens: a plain click or tap toggles one item, and arrow keys only move
+ * focus. Space still toggles; Shift-click still selects a range.
+ */
 export declare function createCollectionSelection(options: {
     ids: () => readonly string[];
+    isDisabled?: (id: string) => boolean;
     initial?: readonly string[];
     onChange?: (ids: readonly string[]) => void;
+    multiple?: boolean;
+    checklist?: boolean;
 }): {
+    multiple: boolean;
     selected: import("solid-js").Accessor<ReadonlySet<string>>;
     focused: import("solid-js").Accessor<string | null>;
+    isDisabled: (id: string) => boolean;
     select: (id: string, modifiers?: SelectionModifiers) => void;
     toggle: (id: string) => void;
     replace: (ids: readonly string[]) => void;

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

@@ -31,6 +31,8 @@ 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 { 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 { Pagination, type PaginationProps } from "./Pagination";
 export type { PdfPreviewProps, PdfPreviewRequest } from "./PdfPreview";
@@ -39,5 +41,7 @@ export type { RangeOption, RangePickerProps } from "./RangePicker";
 export { default as RangePicker } from "./RangePicker";
 export type { StructuredDataPreviewMode, StructuredDataPreviewProps, StructuredDataValue } from "./StructuredDataPreview";
 export { default as StructuredDataPreview, isStructuredDataValue } from "./StructuredDataPreview";
+export type { VirtualFeedController, VirtualFeedProps, VirtualFeedScrollOptions } from "./VirtualFeed";
+export { VirtualFeed } from "./VirtualFeed";
 export type { ZoomPanAction, ZoomPanFullscreen, ZoomPanViewportProps } from "./ZoomPanViewport";
 export { ZoomPanViewport } from "./ZoomPanViewport";

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

@@ -5,8 +5,9 @@ export type InstallGuideProps = {
     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.
+     * The absolute address of the page to install. A browser inside another app copies it, to open it in Safari or
+     * Chrome, and shows it as text when copying fails, so it can be copied by hand. Samsung Internet opens an http or
+     * https address in Chrome.
      */
     url: string;
     /**
@@ -20,7 +21,8 @@ export type InstallGuideProps = {
  * 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.
+ * Chrome instead. Samsung Internet gets a link to Chrome even when it offers its own dialog, because Android may block
+ * the app package it builds. 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/install.d.ts

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * browser on iPhone or iPad, which installs through its Share menu but less reliably than Safari. `android-samsung` is
+ * Samsung Internet on Android, whose installed apps Android may block as built for an older Android version.
+ * `android-browser` is another Android browser, such as Firefox or Edge.
  */
-export type InstallationPlatform = "in-app" | "apple-in-app" | "apple-browser" | "apple-mobile" | "apple-desktop" | "android-browser" | "android" | "generic";
+export type InstallationPlatform = "in-app" | "apple-in-app" | "apple-browser" | "apple-mobile" | "apple-desktop" | "android-samsung" | "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

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

@@ -1,11 +1,19 @@
 import { type JSX } from "solid-js";
-export type QrScannerError = "denied" | "unavailable";
+/**
+ * Why the scanner could not start, as far as the browser tells: `"denied"` when camera access is off, `"no-camera"`
+ * when the device has no camera, `"in-use"` when the camera is busy or could not start, most often because another app
+ * holds it, and `"unavailable"` for anything else, including a scanning engine that cannot load.
+ */
+export type QrScannerError = "denied" | "no-camera" | "in-use" | "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. */
+    /**
+     * The camera or the scanning engine could not start; the scanner has stopped. Offer another way in. A frame that
+     * cannot be decoded never ends here.
+     */
     onError: (reason: QrScannerError) => void;
     /** What to point the camera at. Defaults to a generic QR code hint. */
     instructions?: string;

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

@@ -61,6 +61,8 @@ declare const uiMessages: import("@k2b/stdlib").Catalog<{
     hidePassword: string;
     noColumns: string;
     noData: string;
+    viewRaw: string;
+    viewFormatted: string;
     noRecords: string;
     noTagsYet: string;
     noResultsFound: string;
@@ -192,6 +194,42 @@ declare const uiMessages: import("@k2b/stdlib").Catalog<{
     dropFilesToAttach: string;
     conversation: string;
     jumpToLatest: string;
+    feedJumpToLatest: string;
+    feedJumpToLatestCount: ({ count }: {
+        count: number;
+    }) => string;
+    feedNewItems: ({ count }: {
+        count: number;
+    }) => string;
+    feedNewMarker: string;
+    messageSent: string;
+    messageNotSent: string;
+    messageRetry: string;
+    messageShowMore: string;
+    messageShowLess: string;
+    messageReplyTo: string;
+    messageForwarded: string;
+    messageEdited: string;
+    messageDeleted: string;
+    messageVideo: string;
+    messageMoreAttachments: ({ count }: {
+        count: number;
+    }) => string;
+    messageReactions: string;
+    messageReaction: ({ emoji, count, names, own }: {
+        emoji: string;
+        count: number;
+        names?: string;
+        own?: boolean;
+    }) => string;
+    messageAddReaction: string;
+    messageReplies: ({ count }: {
+        count: number;
+    }) => string;
+    messageLastReply: ({ time }: {
+        time: string;
+    }) => string;
+    messageStop: string;
     conversationMessages: ({ label }: {
         label: string;
     }) => string;
@@ -467,6 +505,11 @@ declare const uiMessages: import("@k2b/stdlib").Catalog<{
     installAppleBrowserDetail: string;
     installAndroidBrowserTitle: string;
     installAndroidBrowserDetail: string;
+    installSamsungTitle: string;
+    installSamsungDetail: ({ appName }: {
+        appName: string;
+    }) => string;
+    installOpenChrome: string;
     installCopyLink: string;
     installLinkCopied: string;
     installCopyFailed: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -21,6 +21,7 @@
       "import": "./dist/ssr/index.js",
       "default": "./dist/ssr/index.js"
     },
+    "./base.css": "./dist/base.css",
     "./global.css": "./dist/global.css",
     "./styles.css": "./dist/styles.css",
     "./fonts/plex.css": "./dist/plex.css",
@@ -59,6 +60,7 @@
     "@k2b/ssr": "0.14.0",
     "@types/babel__core": "7.20.5",
     "@types/bun": "1.4.2",
+    "axe-core": "4.11.0",
     "babel-preset-solid": "1.9.15",
     "bun-plugin-tailwind": "0.1.2",
     "happy-dom": "20.14.5",