@kungal/ui-core 2.53.0 → 2.55.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @kungal/ui-core
 
+## 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

package/dist/index.cjs

@@ -458,6 +458,30 @@ var zh_CN_default = {
       reveal: "显示密码",
       hide: "隐藏密码"
     },
+    kbd: {
+      control: "Ctrl",
+      alt: "Alt",
+      option: "Option",
+      shift: "Shift",
+      command: "Command",
+      meta: "Windows 键",
+      enter: "回车",
+      escape: "Esc",
+      backspace: "退格",
+      delete: "删除",
+      tab: "Tab",
+      space: "空格",
+      up: "上箭头",
+      down: "下箭头",
+      left: "左箭头",
+      right: "右箭头",
+      pageUp: "向上翻页",
+      pageDown: "向下翻页",
+      home: "Home",
+      end: "End",
+      plus: "加号",
+      then: "然后"
+    },
     lightbox: {
       label: "图片查看器",
       close: "关闭",
@@ -517,6 +541,9 @@ var zh_CN_default = {
       clear: "清除",
       removeOption: "移除 {label}"
     },
+    splitPane: {
+      handle: "调整分栏宽度"
+    },
     spoiler: {
       copyCode: "复制代码",
       reveal: "剧透内容,点击或按回车显示"
@@ -552,6 +579,133 @@ var zh_CN_default = {
 // src/locale/zh-CN.ts
 var KUN_CATALOG_ZH_CN = zh_CN_default;
 
+// src/shortcut.ts
+var ALIASES = {
+  mod: "Mod",
+  ctrl: "Control",
+  control: "Control",
+  alt: "Alt",
+  option: "Alt",
+  opt: "Alt",
+  shift: "Shift",
+  meta: "Meta",
+  cmd: "Meta",
+  command: "Meta",
+  super: "Meta",
+  win: "Meta",
+  enter: "Enter",
+  return: "Enter",
+  esc: "Escape",
+  escape: "Escape",
+  backspace: "Backspace",
+  del: "Delete",
+  delete: "Delete",
+  tab: "Tab",
+  space: "Space",
+  spacebar: "Space",
+  up: "ArrowUp",
+  arrowup: "ArrowUp",
+  down: "ArrowDown",
+  arrowdown: "ArrowDown",
+  left: "ArrowLeft",
+  arrowleft: "ArrowLeft",
+  right: "ArrowRight",
+  arrowright: "ArrowRight",
+  pageup: "PageUp",
+  pgup: "PageUp",
+  pagedown: "PageDown",
+  pgdn: "PageDown",
+  home: "Home",
+  end: "End",
+  plus: "+"
+};
+var MODIFIER_ORDER = {
+  apple: ["Control", "Alt", "Shift", "Meta"],
+  other: ["Control", "Meta", "Alt", "Shift"]
+};
+var NAMED = {
+  Control: { apple: "⌃", other: "Ctrl", spoken: () => "control" },
+  Alt: { apple: "⌥", other: "Alt", spoken: (p) => p === "apple" ? "option" : "alt" },
+  Shift: { apple: "⇧", other: "Shift", spoken: () => "shift" },
+  Meta: { apple: "⌘", other: "Win", spoken: (p) => p === "apple" ? "command" : "meta" },
+  Enter: { apple: "↩", other: "Enter", spoken: () => "enter" },
+  Escape: { apple: "Esc", other: "Esc", spoken: () => "escape" },
+  Backspace: { apple: "⌫", other: "Backspace", spoken: () => "backspace" },
+  Delete: { apple: "⌦", other: "Del", spoken: () => "delete" },
+  Tab: { apple: "⇥", other: "Tab", spoken: () => "tab" },
+  Space: { apple: "Space", other: "Space", spoken: () => "space" },
+  ArrowUp: { apple: "↑", other: "↑", spoken: () => "up" },
+  ArrowDown: { apple: "↓", other: "↓", spoken: () => "down" },
+  ArrowLeft: { apple: "←", other: "←", spoken: () => "left" },
+  ArrowRight: { apple: "→", other: "→", spoken: () => "right" },
+  PageUp: { apple: "PgUp", other: "PgUp", spoken: () => "pageUp" },
+  PageDown: { apple: "PgDn", other: "PgDn", spoken: () => "pageDown" },
+  Home: { apple: "Home", other: "Home", spoken: () => "home" },
+  End: { apple: "End", other: "End", spoken: () => "end" },
+  "+": { apple: "+", other: "+", spoken: () => "plus" }
+};
+var canonicalKey = (token) => {
+  const alias = ALIASES[token.toLowerCase()];
+  if (alias) return alias;
+  if (/^f\d{1,2}$/i.test(token)) return token.toUpperCase();
+  return token.length === 1 ? token.toUpperCase() : token;
+};
+var splitChord = (chord) => {
+  if (chord === "+") return ["+"];
+  const plusKey = chord.endsWith("++");
+  const body = plusKey ? chord.slice(0, -2) : chord;
+  const keys = body.split("+").filter(Boolean);
+  return plusKey ? [...keys, "+"] : keys;
+};
+var parseKunShortcut = (keys) => keys.trim().split(/\s+/).filter(Boolean).map((chord) => splitChord(chord).map(canonicalKey)).filter((chord) => chord.length > 0);
+var resolveKunShortcut = (keys, platform) => {
+  const order = MODIFIER_ORDER[platform];
+  return parseKunShortcut(keys).map((chord) => {
+    const resolved = chord.map(
+      (key) => key === "Mod" ? platform === "apple" ? "Meta" : "Control" : key
+    );
+    const modifiers = order.filter((m) => resolved.includes(m));
+    const rest = resolved.filter((k, i) => !order.includes(k) && resolved.indexOf(k) === i);
+    return [...modifiers, ...rest].map((key) => {
+      const named = NAMED[key];
+      return named ? { key, label: named[platform], spoken: named.spoken(platform) } : { key, label: key, spoken: null };
+    });
+  });
+};
+var formatKunShortcut = (keys, platform) => resolveKunShortcut(keys, platform).map((chord) => chord.map((k) => k.label).join(platform === "apple" ? "" : "+")).join(" ");
+var speakKunShortcut = (sequence, name, then) => sequence.map((chord) => chord.map((k) => k.spoken ? name(k.spoken) : k.label).join(" ")).join(` ${then} `);
+
+// src/menu.ts
+var normalizeKunMenuSeparators = (entries) => {
+  const out = [];
+  for (const entry of entries) {
+    const last = out[out.length - 1];
+    if (entry.type === "separator" && (!last || last.type === "separator")) continue;
+    out.push(entry);
+  }
+  while (out.length && out[out.length - 1].type === "separator") out.pop();
+  return out;
+};
+
+// src/splitPane.ts
+var resolveKunSplitSize = (raw, { min, max, snapPoints = [], snapThreshold = 8, from }) => {
+  const lo = Math.min(min, max);
+  const hi = Math.max(min, max);
+  const clamped = Math.min(Math.max(raw, lo), hi);
+  let best = clamped;
+  let bestDistance = Infinity;
+  for (const point of snapPoints) {
+    if (point < lo || point > hi) continue;
+    const distance = Math.abs(point - clamped);
+    if (distance <= snapThreshold && distance < bestDistance) {
+      best = point;
+      bestDistance = distance;
+    }
+  }
+  if (from !== void 0 && Math.sign(best - from) !== Math.sign(clamped - from)) best = clamped;
+  return Math.round(best);
+};
+
 // src/random.ts
 var randomNum = (lowerValue, upperValue) => Math.floor(Math.random() * (upperValue - lowerValue + 1) + lowerValue);
 
@@ -1582,6 +1736,7 @@ exports.buildKunChatEntityTree = buildKunChatEntityTree;
 exports.cn = cn;
 exports.decodeIfEncoded = decodeIfEncoded;
 exports.formatKunChatMarkdown = formatKunChatMarkdown;
+exports.formatKunShortcut = formatKunShortcut;
 exports.getKunIcon = getKunIcon;
 exports.getRandomSticker = getRandomSticker;
 exports.groupKunChatMessages = groupKunChatMessages;
@@ -1608,13 +1763,18 @@ exports.kunTextClasses = kunTextClasses;
 exports.kunVariantClasses = kunVariantClasses;
 exports.layoutKunChatAlbum = layoutKunChatAlbum;
 exports.normalizeKunChatEntities = normalizeKunChatEntities;
+exports.normalizeKunMenuSeparators = normalizeKunMenuSeparators;
 exports.parseKunChatMarkdown = parseKunChatMarkdown;
+exports.parseKunShortcut = parseKunShortcut;
 exports.pickAvatarFallback = pickAvatarFallback;
 exports.randomNum = randomNum;
 exports.registerKunIcon = registerKunIcon;
 exports.registerKunIcons = registerKunIcons;
+exports.resolveKunShortcut = resolveKunShortcut;
+exports.resolveKunSplitSize = resolveKunSplitSize;
 exports.resolveRounded = resolveRounded;
 exports.sliceKunChatEntities = sliceKunChatEntities;
+exports.speakKunShortcut = speakKunShortcut;
 exports.translateKunMessage = translateKunMessage;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map