@kungal/ui-core 2.52.1 → 2.54.0

package/CHANGELOG.md

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

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: "关闭",
@@ -552,6 +576,114 @@ 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/random.ts
 var randomNum = (lowerValue, upperValue) => Math.floor(Math.random() * (upperValue - lowerValue + 1) + lowerValue);
 
@@ -1582,6 +1714,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 +1741,17 @@ 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.resolveRounded = resolveRounded;
 exports.sliceKunChatEntities = sliceKunChatEntities;
+exports.speakKunShortcut = speakKunShortcut;
 exports.translateKunMessage = translateKunMessage;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map