@kungal/ui-core 2.50.1 → 2.51.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ClassValue } from 'clsx';
 export { ClassValue } from 'clsx';
-import { K as KunMessages, a as KunMessagePath, b as KunMessageCatalog } from './types-Cgq63U6z.cjs';
-export { c as KunTranslate } from './types-Cgq63U6z.cjs';
+import { K as KunMessages, a as KunMessagePath, b as KunMessageCatalog } from './types-Dc-w7UpA.cjs';
+export { c as KunTranslate } from './types-Dc-w7UpA.cjs';
 
 type KunUIVariant = 'solid' | 'bordered' | 'light' | 'flat' | 'shadow';
 type KunUIColor = 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
@@ -167,6 +167,332 @@ interface KunAvatarDecoration {
     animatedSrc?: string;
 }
 
+type KunChatEntityType = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'spoiler' | 'code' | 'pre' | 'blockquote' | 'text_link' | 'mention' | 'url';
+/**
+ * A formatting range over a message's text. `offset` and `length` count
+ * UTF-16 code units, as JavaScript string indices and Dart strings do, so a
+ * range is `text.slice(offset, offset + length)` on both platforms.
+ */
+interface KunChatEntity {
+    type: KunChatEntityType;
+    offset: number;
+    length: number;
+    /** `mention` only: the mentioned user. */
+    user_id?: string;
+    /** `text_link` only: the link target. */
+    url?: string;
+    /** `pre` only: the code block's language, e.g. `go`. */
+    language?: string;
+}
+interface KunChatPhoto {
+    type: 'photo';
+    /** Image-service hash. The site turns it into a URL; KunUI never builds one. */
+    image_hash: string;
+    width: number;
+    height: number;
+    thumbhash?: string | null;
+}
+/** Media attached to a message. Only `photo` exists today; sticker and file
+ *  arrive later, and every consumer switches on `type`. */
+type KunChatMedia = KunChatPhoto;
+/** The message a reply points at, embedded by the server so a reply renders
+ *  without fetching its target. */
+interface KunChatReplyTo {
+    seq: number;
+    sender_id: string;
+    text: string;
+    entities: KunChatEntity[];
+    /** The replied-to message's `media.type`, or null. */
+    media_type: string | null;
+    /** The target was deleted for everyone; render "message deleted". */
+    deleted: boolean;
+}
+/** A reply that quotes only part of its target. `offset` is where the quote
+ *  starts in the target's text, in UTF-16 code units. */
+interface KunChatReplyQuote {
+    text: string;
+    entities: KunChatEntity[];
+    offset: number;
+}
+type KunChatServiceAction = {
+    type: 'group_created';
+    title?: string;
+} | {
+    type: 'members_added';
+    user_ids: string[];
+} | {
+    type: 'member_left';
+} | {
+    type: 'member_removed';
+    user_id: string;
+} | {
+    type: 'title_changed';
+    title: string;
+} | {
+    type: 'photo_changed';
+} | {
+    type: 'message_pinned';
+    seq: number;
+} | {
+    type: 'joined_by_link';
+};
+type KunChatServiceActionType = KunChatServiceAction['type'];
+/** A cross-site context card, e.g. "sent from the moyu page of patch X". */
+interface KunChatContext {
+    site: string;
+    kind: string;
+    id: string;
+    title: string;
+    url: string;
+}
+interface KunChatReaction {
+    /** A key from the reaction vocabulary, never an emoji character. */
+    reaction: string;
+    count: number;
+    /** Whether the viewer is one of `count`. */
+    reacted: boolean;
+}
+/** One entry of the reaction vocabulary served by `GET /v2/chat/reactions`. */
+interface KunChatReactionOption {
+    key: string;
+    /** Native emoji, shown when there is no `image_url`. */
+    emoji: string;
+    /** Accessible name, e.g. "爱心". */
+    label: string;
+    /** Animated image to draw instead of the emoji. */
+    image_url?: string | null;
+}
+/** Client-side delivery state of a message the viewer sent. */
+type KunChatSendStatus = 'sending' | 'sent' | 'read' | 'failed';
+interface KunChatMessage {
+    object?: 'message';
+    id: string;
+    conversation_id: string;
+    /** Position in the conversation, from 1, gap-free. */
+    seq: number;
+    sender_id: string;
+    kind: 'message' | 'service';
+    text: string;
+    entities: KunChatEntity[];
+    media: KunChatMedia | null;
+    /** Photos sent together share one value; each photo is its own message. */
+    media_group_id: string | null;
+    reply_to: KunChatReplyTo | null;
+    reply_quote: KunChatReplyQuote | null;
+    service_action: KunChatServiceAction | null;
+    context: KunChatContext | null;
+    reactions: KunChatReaction[];
+    silent: boolean;
+    pinned_at: string | null;
+    edited_at: string | null;
+    created_at: string;
+    /** Local only: the idempotency key a pending message was sent with. Kept on
+     *  the confirmed message, it keeps the row's identity across confirmation. */
+    client_message_id?: string | null;
+    /** Local only: the delivery state of the viewer's own message. When absent
+     *  it is derived — `read` at or below the peer's read cursor, else `sent`. */
+    status?: KunChatSendStatus;
+}
+/** The result of parsing composer input, and what a send carries. */
+interface KunChatFormattedText {
+    text: string;
+    entities: KunChatEntity[];
+}
+/** A member of the `users` array chat responses carry. A deleted account keeps
+ *  its id with an empty name and `deleted: true`; the components render it as
+ *  "deleted account" with the fallback avatar. Not a `KunUser`: that one's id
+ *  is a number, this one's a string. */
+interface KunChatUser {
+    object?: 'user';
+    id: string;
+    name: string;
+    avatar: string;
+    deleted?: boolean;
+}
+/** A typing notification as the site received it. `at` is the receiving
+ *  client's own clock (`Date.now()`), never the server's, so the 6-second
+ *  expiry is immune to clock skew. */
+interface KunChatTypingEvent {
+    user_id: string;
+    at: number;
+}
+
+/** Longest message text, in UTF-16 code units (Telegram's value). */
+declare const KUN_CHAT_TEXT_LIMIT = 4096;
+/** Most photos one album can hold. */
+declare const KUN_CHAT_ALBUM_LIMIT = 10;
+/** A client sends at most one typing notification per this many ms. */
+declare const KUN_CHAT_TYPING_INTERVAL = 5000;
+/** A typing notification not renewed within this many ms has expired. */
+declare const KUN_CHAT_TYPING_TIMEOUT = 6000;
+
+/** Types that break the line around themselves. */
+declare const KUN_CHAT_BLOCK_ENTITY_TYPES: ReadonlySet<string>;
+/**
+ * Make an entity list safe to render, without ever changing `text`:
+ *
+ * 1. Drop unknown types, non-integer or negative positions, empty ranges, a
+ *    `text_link` without a `url` and a `mention` without a `user_id`; clamp
+ *    the end to the text. Widen a range that would cut a surrogate pair (an
+ *    emoji) in half. Pull a blockquote's end in over trailing line breaks.
+ * 2. Merge touching or overlapping runs of one inline format (bold, italic,
+ *    underline, strikethrough, spoiler).
+ * 3. Cut every other entity at the boundaries of a blockquote it straddles,
+ *    so quotes are always outermost.
+ * 4. Pull the ends of an inline format in over line breaks, which draw
+ *    nothing there (a blockquote's end, before step 3).
+ * 5. Order by start, then longer first, then by nesting order; split an
+ *    entity that partially crosses another at the boundary, so every pair
+ *    nests or is disjoint.
+ * 6. Drop what cannot nest: anything inside `code`/`pre`, a type inside the
+ *    same type, a link inside a link.
+ *
+ * The result is a fixed point: normalizing it again changes nothing. The
+ * server already guarantees most of this; the client does it anyway so a bad
+ * row renders instead of throwing.
+ */
+declare const normalizeKunChatEntities: (text: string, entities: readonly KunChatEntity[] | null | undefined) => KunChatEntity[];
+interface KunChatTextLeaf {
+    kind: 'text';
+    text: string;
+    /** Where `text` starts in the message text, in UTF-16 code units. */
+    offset: number;
+}
+interface KunChatEntityNode {
+    kind: 'entity';
+    entity: KunChatEntity;
+    children: KunChatTextNode[];
+}
+type KunChatTextNode = KunChatTextLeaf | KunChatEntityNode;
+/**
+ * Turn `text` + `entities` into a tree: entity nodes whose children are text
+ * leaves and nested entity nodes, in document order. The entities are
+ * normalized first (see `normalizeKunChatEntities`), so any input renders.
+ */
+declare const buildKunChatEntityTree: (text: string, entities: readonly KunChatEntity[] | null | undefined) => KunChatTextNode[];
+/** The plain text of a subtree, as rendered (block-adjacent breaks omitted). */
+declare const kunChatTreeText: (nodes: readonly KunChatTextNode[]) => string;
+/**
+ * The part of a message from `start` to `end` (UTF-16 code units), with the
+ * entities clipped to it and shifted to start at 0 — what a partial quote
+ * carries. The range is widened rather than split through an emoji.
+ */
+declare const sliceKunChatEntities: (text: string, entities: readonly KunChatEntity[] | null | undefined, start: number, end: number) => {
+    text: string;
+    entities: KunChatEntity[];
+};
+
+/**
+ * Parse composer input into message text and entities. Never throws: input
+ * that is not valid shortcut syntax stays literal text.
+ */
+declare const parseKunChatMarkdown: (source: string) => KunChatFormattedText;
+/**
+ * Turn message text + entities back into composer input — for editing a sent
+ * message, or restoring a draft. Parsing the result gives back the same text
+ * and (normalized) entities, except for what the syntax cannot spell:
+ *
+ * - `url` entities are dropped; the server detects links again on save.
+ * - A blockquote is dropped unless it starts and ends at line breaks that
+ *   are text — not inside a code span or pre block.
+ * - Blockquotes on consecutive lines are written, and come back, as one.
+ * - A `pre` language with characters outside `A-Z a-z 0-9 _ + # . -` is
+ *   dropped, as is a `text_link` whose URL is itself `mention:<digits>`.
+ */
+declare const formatKunChatMarkdown: (text: string, entities: readonly KunChatEntity[] | null | undefined) => string;
+
+interface KunChatAlbumSize {
+    width: number;
+    height: number;
+}
+/** Which outer edges of the mosaic a tile touches — its rounded corners. */
+declare const KUN_CHAT_ALBUM_SIDE: {
+    readonly top: 1;
+    readonly right: 2;
+    readonly bottom: 4;
+    readonly left: 8;
+};
+interface KunChatAlbumTile {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Bitmask of `KUN_CHAT_ALBUM_SIDE`. */
+    sides: number;
+}
+interface KunChatAlbumLayout {
+    width: number;
+    height: number;
+    tiles: KunChatAlbumTile[];
+}
+interface KunChatAlbumOptions {
+    /** Default 420, tweb's desktop bubble width. */
+    maxWidth?: number;
+    /** Narrowest tile. Default 100. */
+    minWidth?: number;
+    /** Gap between tiles. Default 2. */
+    spacing?: number;
+}
+/**
+ * Lay out an album of 1–10 photos as Telegram does. Sizes with a zero or
+ * missing side are treated as square.
+ */
+declare const layoutKunChatAlbum: (sizes: readonly KunChatAlbumSize[], options?: KunChatAlbumOptions) => KunChatAlbumLayout;
+
+/** The row identity of a message: its `client_message_id` when it has one, so
+ *  a pending message keeps its row when the server confirms it. */
+declare const kunChatMessageKey: (message: KunChatMessage) => string;
+/**
+ * `YYYY-MM-DD` of an instant, in `timeZone` (an IANA name) or, when omitted,
+ * the runtime's own zone. Keys sort chronologically as strings.
+ */
+declare const kunChatDayKey: (date: Date, timeZone?: string) => string;
+type KunChatListRow = {
+    type: 'unread';
+    key: string;
+} | {
+    type: 'service';
+    key: string;
+    message: KunChatMessage;
+} | {
+    type: 'message';
+    key: string;
+    /** The message the row acts as: an album's first message with a
+     *  caption, else its first; the message itself otherwise. */
+    message: KunChatMessage;
+    /** Every message the row shows — an album's photos, in order. */
+    messages: KunChatMessage[];
+    own: boolean;
+    /** First of consecutive messages from one sender: the name goes here. */
+    groupStart: boolean;
+    /** Last of the run: the avatar and the bubble tail go here. */
+    groupEnd: boolean;
+};
+interface KunChatDaySection {
+    /** `YYYY-MM-DD` in the list's time zone. */
+    key: string;
+    /** The first message's instant, for formatting the date pill. */
+    date: Date;
+    rows: KunChatListRow[];
+}
+interface KunChatGroupOptions {
+    currentUserId: string;
+    /** The viewer's read cursor when the conversation was opened. The unread
+     *  divider goes above the first later message someone else sent. */
+    lastReadSeq?: number | null;
+    /** Longest gap, in seconds, inside one sender group. Default 600
+     *  (telegram-tt's `GROUP_INTERVAL_SECONDS`). */
+    groupWindow?: number;
+    /** IANA time zone for day boundaries; the runtime's zone when omitted. */
+    timeZone?: string;
+}
+/**
+ * Arrange messages — already in display order — into day sections and rows.
+ * A sender group breaks on another sender, a new day, a gap longer than
+ * `groupWindow`, the unread divider, and any service message.
+ */
+declare const groupKunChatMessages: (messages: readonly KunChatMessage[], options: KunChatGroupOptions) => KunChatDaySection[];
+
 interface KunIconData {
     body: string;
     width?: number;
@@ -177,4 +503,4 @@ declare const registerKunIcons: (icons: Record<string, KunIconData>) => void;
 declare const getKunIcon: (name: string) => KunIconData | undefined;
 declare const hasKunIcon: (name: string) => boolean;
 
-export { KUN_AVATAR_FALLBACK, KUN_CATALOG_ZH_CN, KUN_DEFAULT_ROUNDED, KUN_SHATTER_PHYSICS, KUN_SWIPE_DISMISS_PHYSICS, type KunAvatarDecoration, type KunIconData, KunMessageCatalog, KunMessagePath, KunMessages, type KunSelectionSize, type KunUIColor, type KunUIRounded, type KunUISize, type KunUIVariant, type KunUser, cn, decodeIfEncoded, getKunIcon, getRandomSticker, hasKunIcon, kunBgClasses, kunBorderClasses, kunChipSizeClasses, kunControlSizeClasses, kunControlSquareClasses, kunFocusRingClasses, kunFocusRingWithinClasses, kunPanelRoundedClass, kunRingClasses, kunRoundedClasses, kunSelectionSizeClasses, kunSoftBgClasses, kunSolidBgClasses, kunSolidClasses, kunSolidFgClasses, kunTextClasses, kunVariantClasses, pickAvatarFallback, randomNum, registerKunIcon, registerKunIcons, resolveRounded, translateKunMessage };
+export { KUN_AVATAR_FALLBACK, KUN_CATALOG_ZH_CN, KUN_CHAT_ALBUM_LIMIT, KUN_CHAT_ALBUM_SIDE, KUN_CHAT_BLOCK_ENTITY_TYPES, KUN_CHAT_TEXT_LIMIT, KUN_CHAT_TYPING_INTERVAL, KUN_CHAT_TYPING_TIMEOUT, KUN_DEFAULT_ROUNDED, KUN_SHATTER_PHYSICS, KUN_SWIPE_DISMISS_PHYSICS, type KunAvatarDecoration, type KunChatAlbumLayout, type KunChatAlbumOptions, type KunChatAlbumSize, type KunChatAlbumTile, type KunChatContext, type KunChatDaySection, type KunChatEntity, type KunChatEntityNode, type KunChatEntityType, type KunChatFormattedText, type KunChatGroupOptions, type KunChatListRow, type KunChatMedia, type KunChatMessage, type KunChatPhoto, type KunChatReaction, type KunChatReactionOption, type KunChatReplyQuote, type KunChatReplyTo, type KunChatSendStatus, type KunChatServiceAction, type KunChatServiceActionType, type KunChatTextLeaf, type KunChatTextNode, type KunChatTypingEvent, type KunChatUser, type KunIconData, KunMessageCatalog, KunMessagePath, KunMessages, type KunSelectionSize, type KunUIColor, type KunUIRounded, type KunUISize, type KunUIVariant, type KunUser, buildKunChatEntityTree, cn, decodeIfEncoded, formatKunChatMarkdown, getKunIcon, getRandomSticker, groupKunChatMessages, hasKunIcon, kunBgClasses, kunBorderClasses, kunChatDayKey, kunChatMessageKey, kunChatTreeText, kunChipSizeClasses, kunControlSizeClasses, kunControlSquareClasses, kunFocusRingClasses, kunFocusRingWithinClasses, kunPanelRoundedClass, kunRingClasses, kunRoundedClasses, kunSelectionSizeClasses, kunSoftBgClasses, kunSolidBgClasses, kunSolidClasses, kunSolidFgClasses, kunTextClasses, kunVariantClasses, layoutKunChatAlbum, normalizeKunChatEntities, parseKunChatMarkdown, pickAvatarFallback, randomNum, registerKunIcon, registerKunIcons, resolveRounded, sliceKunChatEntities, translateKunMessage };