# @kungal/ui-core ## 2.58.0 ### Minor Changes - 81b3b71: New `KunCommandSearch`: a search field that stays in the top bar and opens KunCommandPalette's results in a panel under it. This is the top-bar search of Slack, Teams, GitHub, Jira and Steam. The kungal desktop app asked for it, and it was faking one with KunAutocomplete. - **Same content as the palette.** It takes the same `items` (flat or `KunCommandGroup[]`), `v-model:query`, `loading` and `highlight`, and renders the same rows: icon, section, label, description, match highlight, and the `#item` slot. Like the palette it does no searching: you compute `items` from the query and own the debounce. - **Opens on focus.** With an empty field it shows whatever `items` you pass, so recent searches go there. It opens nothing when there is nothing to show (no rows and no `#empty` slot), and `aria-expanded` follows what is on screen. Clearing the field keeps it open. - **Enter goes to the search page.** Unlike the palette, nothing is highlighted until an arrow key moves onto a row. Enter after typing emits `@submit(query)`; Enter on a highlighted row, or a click, emits `@select(item)`. The arrow keys cycle through "nothing highlighted", as a browser's address bar does. Every documented desktop app we checked behaves this way; none picks the first suggestion on Enter. - **Escape:** the first press closes the panel and keeps the text, the second clears the text. Tab, a click outside, selecting and submitting all close it. Focus never leaves the field: the panel is a listbox driven by `aria-activedescendant`, its options are out of the tab order, and there is no dialog, backdrop, scroll lock or focus trap. - **Size:** the panel is left-aligned 4px under the field, as wide as the field but at least 360px, capped to the viewport. Its height is the smaller of `maxHeight` (default 420) and the room below. `loading` turns the field's search icon into a spinner. Rows already on screen stay until new ones arrive, so the list does not blink on every keystroke. - **Shortcut:** ⌘K / Ctrl+K focuses the field. A field that is not on screen, or sits behind a modal, ignores the shortcut and leaves it to a KunCommandPalette on the same page. That is the narrow-screen recipe: show the field from `md` up and the palette's icon button below it with breakpoint classes, both fed the same `query` and `items`. The component never switches layout from JavaScript, so the server renders the right one at every width. **Changes to KunCommandPalette**, all additive: - `KunCommandItem.removable` adds a remove button to a row (recent searches, say). Shift+Delete removes the highlighted row; both emit the new `@remove`, you drop the item from `items`, and the highlight stays on the row that takes its place. - A labelled group is now `role="group"`, named by its heading. A group with no items is no longer rendered: it used to leave an orphan heading. - The palette's ⌘K ignores a keystroke another handler already consumed, which is how a visible KunCommandSearch takes it first. **KunModal and KunDrawer** no longer close on an Escape that a field inside them already used. A KunCommandSearch clearing its text and a KunChatComposer cancelling its reply bar each took the modal down on the same press. Locale: `commandPalette.remove` and `commandPalette.clear` (zh-CN and en), shared by both components. ## 2.57.1 ## 2.57.0 ## 2.56.2 ## 2.56.1 ## 2.56.0 ### Minor Changes - 570067b: Coloured text and placeholders now clear WCAG AA (4.5:1). A kungal Flutter app's contrast check measured KunUI's own coloured text and placeholders below it, and the web uses the same classes. **New tokens:** - `--color-{color}-text` (Tailwind `text-primary-text`, `text-danger-text`, …), one per semantic colour, `default` included. - In Dart: `KunColorScale.text`. **Why a new token.** A fill colour used as text measured 1.75–4.42:1 on the light page for every colour but `default`, and in dark mode primary and danger fell to 3.87:1 and 3.66:1 on cards. `{color}-text` is the ramp step closest to the fill that clears 4.5:1 on: - the page background; - cards (`content1`); - the colour's own 20% tint over each, which is the hover and keyboard-focus fill of a light item and the fill of a flat chip. The token generator measures all four in both modes and fails the build if one misses. The steps it picks: | Mode | Step 600 | Step 700 | | ----- | ----------------------------- | --------------------------------------- | | Light | secondary, warning | primary, success, danger, info, default | | Dark | every colour except secondary | secondary | **What moved to it:** - The `light`, `bordered` and `flat` variants (buttons, chips, badges, menu items) and `kunTextClasses`, which covers KunLink, selected tabs, active steps and reactions. - KunInfo's `bordered` text, and its dark `flat` danger and info. - Every form error message and required asterisk. - Chat sender names, reply and pinned titles, links, mentions, typing and status text. **What you'll see.** Coloured text is one step darker in light mode and one step lighter in dark mode. Icons, SVG strokes, spinners and text on solid fills keep their colours. **If your own markup uses `text-primary` for readable text**, switch it to `text-primary-text`. `text-primary` stays the fill colour, meant for fills, borders and icons. **Placeholders** now use `foreground-muted`, the secondary-text colour: 5.52:1 light and 4.85:1 dark, where `default-400` measured 2.31–3.58:1. This covers the base-layer `::placeholder` rule (every native input), KunSelect's and KunDatePicker's empty trigger, KunChatComposer and KunCommandPalette. A placeholder is often the only label a field has, such as "全部平台" in a filter. Disabled text, outside-month days and icons keep their lighter steps: WCAG exempts disabled controls, and the others are not text. Measured on the docs site in Chromium: 227 text elements in each mode across the button, chip, tab, link, select, input, info, dropdown, chat bubble, date picker and textarea pages all clear 4.5:1. The lowest are a warning chip (4.77:1 light, 4.87:1 dark) and the dark placeholder (4.85:1). ## 2.55.0 ### Minor Changes - 0bac099: New `KunSplitPane`: two panes with a divider you can drag or move with the keyboard. It suits a list beside a detail view, or a main area with an auxiliary column. KunChatLayout now switches between one and two panes by its own width, and its list pane can be made draggable. **KunSplitPane** puts its panes in the `#start` and `#end` slots. - **Width.** `v-model:size` is the primary pane's width in px (default 360). It is a prop the server knows, so the server-rendered HTML already has the layout and the divider's `aria-valuenow`/`min`/`max`. - **Persisting the width.** `v-model:size` updates on every pointer move. Save from `resize-end`, which fires once per drag or key press, for example to a cookie your server reads back into `size`. - **Limits and snapping.** `min-size` and `max-size` default to 240 and 480. `snap-points` (e.g. `[360, 412]`) pull the divider in once it comes within `snap-threshold` px (default 8), and any width in between stays reachable. A keyboard step that ends within the threshold snaps too, but a snap never cancels or reverses a step, so a small `step` cannot get stuck on a snap point. - **Which pane is sized.** `primary="end"` gives the width to the right pane, for an auxiliary column. - **Keyboard** (WAI-ARIA window splitter pattern): - ← and → move the divider by `step` (default 10px); Shift moves five steps. - Home and End jump to the minimum and maximum. - **The divider** is a 1px line. Its grab area is 9px wide with a mouse and 21px on a touch screen, and it sits above the panes' content. A drag follows the pointer that started it; a second finger or the mouse cannot take it over. While you drag, the page keeps a col-resize cursor, no text gets selected, and the panes ignore the pointer, so an iframe can't swallow the drag. - **Narrow layouts.** Below `stack-below` (`md` = 48rem by default, `lg` = 64rem, or `false`), it shows one pane at a time, chosen by `show-pane`. This is a container query on the component's own width, not a media query on the window: a split nested beside a side rail or inside another pane stacks based on the room it actually has. - **Flutter port.** The snapping rule is a pure `resolveKunSplitSize` in `@kungal/ui-core`, with tests. **KunChatLayout** now shows two panes once the layout itself is 48rem (768px) wide, rather than once the window is. - **Why:** a chat beside an app's side rail used to switch to two panes in a 768px window that left it 679px, and the conversation was squeezed to 327px. - **What might change for you:** pages that give the chat less than 48rem (for example, a window of about 768–800px minus page padding) now show one pane. - **KunChatHeader's `back="mobile"`** follows the KunChatLayout around it. Outside a KunChatLayout it still uses the window's `md` width. - **New props:** `resizable`, `v-model:sidebar-size` (px), `sidebar-min-size` and `sidebar-max-size` make the list draggable through KunSplitPane. The `sidebar-resize-end` event is the one to persist from. Without `resizable`, `sidebar-width` works as before. ## 2.54.0 ### Minor Changes - 5ca083f: Menus gain separators, shortcut hints and one level of submenu, and a new `KunKbd` shows keyboard shortcuts. Everything is additive: existing `items` arrays and props render exactly as before. **KunContextMenu and KunDropdown** share one item list, so an app can render the same command list as a right-click menu, a ⋯ menu and a long-press menu. `items` now takes `KunMenuEntry[]`, which is an item or `{ type: 'separator' }`. `KunContextMenuItem[]` arrays are still accepted. - **Separators.** Leading, trailing and repeated separators are dropped, so a list filtered per context never shows a stray line. - **Shortcuts.** `shortcut: 'Mod+C'` shows ⌘C on Apple and Ctrl+C elsewhere at the item's end. It is display only; your app still binds the key. Screen readers read the item's label as its name and the shortcut as its description. - **Submenus.** `children` opens a submenu, one level deep. - Opening: hover (after 100 ms), →, Enter or a tap. - Closing: ← and Escape close one level, as the WAI-ARIA menu pattern specifies; Tab closes the whole menu. - A 300 ms grace period and a safe triangle keep the submenu open while the pointer moves diagonally towards it. - An item with `children` never emits `select`; if a filter leaves it no child items, it shows disabled. Selecting a submenu item emits that item and closes everything. - **Keyboard.** KunContextMenu now has the type-ahead KunDropdown already had. ↑ in a menu with nothing focused yet, such as right after a click opened it, now goes to the last item. Before, it went to the second-to-last. - **Link items.** Enter or Space on an `href` item now follows the link. Before, it emitted `select` and closed without navigating. **KunKbd** takes `keys` in the aria-keyshortcuts grammar plus `Mod`: `+` joins a chord and a space separates a sequence, e.g. `'Mod+K'`, `'Shift+Delete'`, `'G G'`. - **Order.** Modifiers sort into each platform's order: ⌃⌥⇧⌘ on Apple, Ctrl+Win+Alt+Shift elsewhere. - **Screen readers** hear key names ("Command K"), not glyphs. - **Size** is in em, so it follows the surrounding text. - **Variants.** `variant="plain"` is the one-line form menus use: ⇧⌘Z, or Ctrl+Shift+Z. - **Server rendering.** The server cannot know the visitor's keyboard, so it renders the Ctrl form; a Mac switches to ⌘ once the page has mounted. Components created afterwards, such as a menu or tooltip opening, start in the right form. - **Related APIs:** - `KunTooltip` gains `shortcut`: `text="Search" shortcut="Mod+K"` renders "Search Ctrl K". - `KunCommandPalette`'s `trigger` slot also passes `keys` for use with KunKbd. - `useKunShortcutPlatform()` and `formatKunShortcut()` are exported for your own markup. - The parser and formatter live in `@kungal/ui-core`, so the Flutter port renders the same labels. **KunChip and KunTagInput:** the × remove button now has a 24×24 px hit area. The glyph did not change size: it was 14 px in KunChip and 18 px in KunTagInput, which is under WCAG 2.2's 24 px minimum. The hit area is not clipped: in Chromium, a clipped one measured worse than none, because it switches off the browser's own tap adjustment. `useKunFloating`'s `offset` option now accepts floating-ui's full `OffsetOptions` (for example `{ mainAxis, crossAxis }`), not just a number. ## 2.53.0 ## 2.52.1 ## 2.52.0 ### Minor Changes - a56cbbf: Chat photos show the URL the server sends. NextMoe chat spec 1.1.0 (nextmoe-infra #337) gives every photo a `url`, which the spec describes as "where the image is served; never build it from image_hash". It is present on history, updates, pins, last messages, pushes and the upload response. `KunChatPhoto` gains `url?: string | null`. It is optional so payloads and fixtures from before 1.1.0 still type-check. `KunChatBubble`, `KunChatMessageList` (its lightbox included) and `KunChatPinnedBar` now show `media.url` when you pass no `resolve-media-url`, so a site on spec 1.1.0 can drop its hash-to-URL resolver. A resolver you do pass still takes precedence: keep it if you serve the bubble a smaller preview than the lightbox, because `url` is a single address for both. A photo with neither a `url` nor a resolver renders as before, with an empty `src`. A conversation's `photo_url` needs nothing new from KunUI. Pass it to `KunChatConversationItem`'s `avatar`, which already takes a URL. ## 2.51.1 ### Patch Changes - 70e5ec2: `normalizeKunChatEntities` is now a fixed point, as its documentation says. Inline entities were cut at the boundaries of every blockquote, including a quote that nesting then dropped because it sat inside, or crossed, another quote. A second pass had no reason to keep that cut and merged the pieces back together. For example, `'中中b*bab'` with a spoiler across two nested quotes normalized to three spoiler runs, and normalizing that result gave two. Blockquotes are now settled among themselves first, and only a quote that survives cuts anything. Output changes only for input with overlapping blockquotes. The property test that should have caught this drew its cases from an LCG computed in doubles, which cycled after about 10,000 draws. It now uses mulberry32, runs 20,000 rounds, and fails on the old code. `formatKunChatMarkdown` no longer loses text after a link or mention whose label ends on a line break. The parser checks for a `> ` quote prefix and the `\>` escape where the new line's text begins, which is after the label's closing `](…)`. The formatter decided whether to escape by reading the characters it had already written, and those end in `)` at that point. So `'a\n\\>b'` with a mention on the line break came back as `'a\n>b'`, and a `>` in that position was read as a quote marker and disappeared. The formatter now tracks the parser's line-start state. `parseKunChatMarkdown` is unchanged, so no composer input parses differently. Over 2.3 million random messages, `parse(format(m))` returned the text unchanged every time. The old code lost text in 50 of the first 300,000. `KunDatePicker` formats the trigger text in its locale. A custom `format` with a month or weekday token showed English names in a zh-CN app. Measured with `format="yyyy MMMM do EEEE"`: the trigger now reads "2026 九月 27 日 星期日" under zh-CN and "2026 September 27th Sunday" under en-US. The default numeric formats render as before. `KunDatePicker` shows which cell the arrow keys are on. Focus stays on the trigger while the arrows move `aria-activedescendant`, so no cell ever matched `:focus-visible`, and a sighted keyboard user saw nothing move until the page turned. The active cell now draws the picker's focus ring once a key opens the panel or moves the cell, and drops it on a pointer press inside the panel. This follows React Aria's `useOption`, which shows a virtually focused option as focus-visible only under keyboard input. Opening the picker with a click shows no ring until an arrow key is pressed. ## 2.51.0 ### Minor Changes - b4b6a8a: Chat components for the NextMoe private-chat service (`/v2/chat`), modelled on Telegram. Twelve new components take the API's JSON as it comes — snake_case fields and string ids included — so a site writes no conversion layer: - `KunChatMessageList` — the scrollback. Consecutive messages from one sender run together (avatar and tail on the last), day pills stick to the top, and the list opens at the "unread messages" divider. Older pages load above you without moving the view, new messages stick to the bottom when you are there and count on the scroll-down button when you are not, and `scrollToSeq(seq)` jumps to a message and flashes it. Right-click or long-press opens the message menu, and swiping left on a touch screen replies. Thousands of messages scroll smoothly with no virtualisation library: rows off screen skip layout and paint (`content-visibility`). The scroller is `column-reverse`, so the server-rendered HTML already sits at the newest message, and history growing above the viewport never writes `scrollTop` — an iOS momentum fling through it is not cut short. - `KunChatBubble` — one message: own (right, primary tint) or theirs; reply and partial-quote previews; a photo, or an album laid out with Telegram's mosaic (ported from Telegram Desktop via tweb); a cross-site context card; reactions; time, "edited" and delivery status (a failed message emits `retry`). A service message renders as a centred pill. - `KunChatText` — text + entities: bold, italic, underline, strikethrough, spoiler (one click reveals them all), inline code, a code block with its language and a copy button, quotes, links and mentions. There is no `v-html`: every run of text is a text node, and a link only renders for `http`, `https` and `mailto`. - `KunChatComposer` — the input. It grows with its content; Enter sends on a desktop and breaks the line on a touch screen. The composer shortcuts (`**bold**`, `||spoiler||`, ` ``` `…) are sent as entities. Reply, quote and edit bars are v-models, and editing puts the message back in the input and keeps the draft aside. Pasted or dropped photos are passed on as `attach(files)`, a counter shows near the 4096-character limit, and a throttled `typing` event fires while the user types. - `KunChatConversationItem`, `KunChatHeader`, `KunChatPinnedBar`, `KunChatRequestBar`, `KunChatMessageMenu`, `KunChatReactionPicker`, `KunChatTyping` and `KunChatLayout` (two panes from `md` up, one at a time on a phone), plus the `useKunChatTyping` composable. Typing notifications expire on their own after 6 s, so a site only forwards what it receives. `@kungal/ui-core` gains the wire types (`KunChatMessage`, `KunChatEntity`, `KunChatUser`, …) and the pure functions behind the components, for the Flutter port to reproduce: `normalizeKunChatEntities` / `buildKunChatEntityTree`, `parseKunChatMarkdown` / `formatKunChatMarkdown`, `layoutKunChatAlbum` and `groupKunChatMessages`. The two markdown functions are exact inverses — a message survives `parse(format(message))` — for everything the syntax can spell. The exceptions are listed on `formatKunChatMarkdown`: `url` entities, which the server detects again, and quotes that do not cover whole lines. Store a draft as the parsed `{ text, entities }` and restore it with `formatKunChatMarkdown`. These algorithms have the repository's first unit tests (`pnpm test`, `node:test` on the sources). What it costs you: - **Custom locales.** New locale namespaces (`chat`, `chatComposer`, `chatMenu`, `chatPinned`, `chatRequest`, `chatService`, `chatStatus`, `chatTyping`) ship in zh-CN and en. A locale you wrote yourself with `defineKunLocale` now fails to type-check until it has them. - **Icons.** 21 more lucide icons are bundled (message status, actions, the composer). - **Bundle size.** The components add about 23 kB gzip to `dist/index.js`, and they tree-shake away if you do not import them. - **Server rendering.** When you render chat on the server, pass `time-zone`: dates are formatted in the runtime's zone otherwise, and the server's and the reader's disagree. Photos need `resolve-media-url`: KunUI never builds an image URL from a hash. A chat avatar does not link to a profile — the chat ids are strings, while `KunUser.id` stays a number — so clicks come out as `user-click` for the site to route. ## 2.50.1 ## 2.50.0 ## 2.49.1 ## 2.49.0 ### Minor Changes - f398a45: **`KunSteps` steps are clickable** when you bind `v-model:current`. Each step becomes a `