@ahrowe/ui 0.48.0 → 0.49.0

package/dist/types/common/actionIcon/actionIcon.types.d.ts

@@ -6,7 +6,7 @@ export type ActionIconSlots = 'root' | 'icon';
  * A Button with only an icon, sized by that icon, so every Button prop applies except the ones
  * that describe a label or a size.
  */
-export interface ActionIconProps extends Omit<ButtonProps, 'icon' | 'size' | 'children' | 'isLoading' | 'classNames' | 'styles'> {
+export interface ActionIconProps extends Omit<ButtonProps, 'icon' | 'size' | 'children' | 'isLoading' | 'shortcut' | 'classNames' | 'styles'> {
     icon: IconContent;
     classNames?: SlotClassNames<ActionIconSlots>;
     styles?: SlotStyles<ActionIconSlots>;

package/dist/types/common/button/button.types.d.ts

@@ -26,7 +26,7 @@ export declare enum ButtonType {
     Reset = "reset",
     Submit = "submit"
 }
-export type ButtonSlots = 'background' | 'content' | 'loadingContainer' | 'label';
+export type ButtonSlots = 'background' | 'content' | 'loadingContainer' | 'label' | 'shortcut';
 /**
  * `DataProps` supplies the `data-*` index signature, which `ButtonHTMLAttributes` doesn't cover.
  * `type`, `color` and `onClick` below deliberately narrow their inherited counterparts.
@@ -43,6 +43,11 @@ export interface ButtonProps extends DataProps, React.ButtonHTMLAttributes<HTMLB
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
     children?: React.ReactNode;
     icon?: IconContent;
+    /**
+     * A shortcut drawn after the label, in `useHotkeys` spelling (`'mod+s'`): `⌘S` on Apple
+     * platforms, `Ctrl+S` elsewhere. Drawn only; bind it with `useHotkeys`.
+     */
+    shortcut?: string;
     isLoading?: boolean;
     disabled?: boolean;
     title?: string;

package/dist/types/common/hooks/useHotkeys.d.ts

@@ -18,6 +18,11 @@ export interface UseHotkeysOptions {
      * Default `true`.
      */
     preventDefault?: boolean;
+    /**
+     * Fire again for each repeat while the combo is held. Default `false`, so holding `mod+s` saves
+     * once. Turn it on for keys that step through something, such as arrows or zoom.
+     */
+    repeat?: boolean;
 }
 /**
  * A combo written for the reader: `'mod+shift+k'` reads `⇧⌘K` on an Apple platform and
@@ -30,6 +35,12 @@ export interface UseHotkeysOptions {
  * Resolved from the platform at call time, so a server-rendered page renders the non-Apple form.
  */
 export declare function formatHotkey(combo: string): string;
+/**
+ * A combo as `aria-keyshortcuts` spells it: `'mod+shift+k'` is `Control+Shift+K`, or
+ * `Meta+Shift+K` on an Apple platform. Resolved from the platform like `formatHotkey`, so the two
+ * always name the same keys.
+ */
+export declare function ariaKeyshortcuts(combo: string | undefined): string | undefined;
 /**
  * Keyboard shortcuts, for a whole app or for one element.
  *

package/docs/ActionIcon.md

@@ -38,8 +38,8 @@ import { faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 | `ref` | `Ref<HTMLButtonElement>` | Ref to the button |
 
 Every other Button prop and native `<button>` attribute passes through, except `size`,
-`children` and `isLoading`. The box is the icon plus `4px` on each side; set `width` and `height`
-for a different one.
+`children`, `isLoading` and `shortcut`. The box is the icon plus `4px` on each side; set `width`
+and `height` for a different one.
 
 **Slots:** `root` `icon`
 

package/docs/Button.md

@@ -11,7 +11,7 @@ works with any colour. The colours are the library-wide `ThemeColor`s or any CSS
 [ThemeColor.md](ThemeColor.md).
 
 ```tsx
-import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui';
+import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor, useHotkeys } from '@ahrowe/ui';
 import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
 // The main action
@@ -52,6 +52,10 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 // Small
 <Button size={ButtonSize.Small}>Cancel</Button>
 
+// A keyboard shortcut: the button draws it, useHotkeys binds it
+useHotkeys({ 'mod+s': handleSave });
+<Button styleType={ButtonStyleType.Filled} shortcut='mod+s' onClick={handleSave}>Save</Button>
+
 // Press-and-hold: act on press rather than release
 <Button
   icon={faPlus}
@@ -81,6 +85,7 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
 | `type` | `ButtonType` | HTML button type |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
+| `shortcut` | `string` | A combo in [useHotkeys](Hooks.md) spelling, e.g. `'mod+s'`. Shown after the label, written for the platform. Binding it is yours, see below |
 | `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
 | `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
@@ -92,6 +97,17 @@ press-and-hold controls that act on press rather than release), `onContextMenu`,
 takes the `ButtonType` enum, and `onClick` may return a promise. `color` is Button's own prop, not
 the obsolete HTML attribute.
 
+**Shortcuts are drawn, not bound.** `shortcut` writes the combo in a pill after the label,
+`⌘S` on an Apple platform and `Ctrl+S` elsewhere. It also sets `aria-keyshortcuts`, so a screen
+reader announces it apart from the button's name. It is hidden on a touch screen
+(`pointer: coarse`), which usually has no keyboard to press it on.
+
+Listening for it is yours, with `useHotkeys` and the same string, because only your app knows
+when the action is available. A button cannot tell: it would still fire while hidden in an
+inactive tab, behind an open Modal, or twice when the same action has a button in the toolbar and
+another in the footer. Turn the binding off wherever the button is disabled:
+`useHotkeys({ 'mod+s': handleSave }, { enabled: !isSaving })`.
+
 **Theming:** each colour reads the theme variables listed in [ThemeColor.md](ThemeColor.md). The
 `Filled` `Primary` button also paints `--primary-gradient` when the theme sets one. See
 [ThemeProvider.md](ThemeProvider.md).
@@ -112,7 +128,7 @@ sits inside the edge, in `--focus-border-color`, or in the text colour on a `Fil
 ripple is in the text colour too. Every button reserves a `1px` border, so switching style never
 shifts layout or changes its height.
 
-**Slots:** `background` `content` `loadingContainer` `label`
+**Slots:** `background` `content` `loadingContainer` `label` `shortcut`
 
 **Sizing in a flex row:** a Button never shrinks below its own content (`min-width: min-content`),
 so an icon is never cut off by a flexible sibling. A multi-word label still wraps above that floor.

package/docs/Hooks.md

@@ -59,6 +59,7 @@ Two rules worth knowing:
 | `target` | `RefObject<HTMLElement \| null>` | window | Scope the shortcuts to one element |
 | `enableInFields` | `boolean` | `false` | Let a combo fire while a text field or `contenteditable` has focus. Only combos the field would otherwise consume are held back: a single character, or an editing key (`arrowup`, `home`, `backspace`, `enter`, `tab`, …). Anything carrying Ctrl, Cmd or Alt fires regardless, and so do `f2`, `escape` and the other keys a field does not use |
 | `preventDefault` | `boolean` | `true` | Call `preventDefault()` on a match, so `mod+s` does not also open the browser's save dialog |
+| `repeat` | `boolean` | `false` | Fire again for each repeat while the combo is held. Off, holding `mod+s` saves once; turn it on for keys that step through something |
 
 Shortcuts keep firing while a `Modal` or `Drawer` is open, which is usually what a command palette
 wants. Pass `enabled` for the ones that should not:
@@ -67,7 +68,14 @@ wants. Pass `enabled` for the ones that should not:
 useHotkeys({ n: createRecord }, { enabled: !isModalOpen });
 ```
 
-A held key repeats, as it does natively. Check `event.repeat` in the handler to ignore repeats.
+A held combo fires once, where the browser's key repeat would save over and over or flicker a
+toggle. The skipped repeats are still `preventDefault()`-ed. Where a repeat is the point, as with
+arrows or zoom, ask for it, in a call of its own if the page also has actions:
+
+```tsx
+useHotkeys({ 'mod+s': save, '?': toggleHelp });
+useHotkeys({ j: selectNext, k: selectPrevious }, { repeat: true });
+```
 
 ### formatHotkey
 
@@ -79,9 +87,10 @@ formatHotkey('mod+shift+k'); // '⇧⌘K' on an Apple platform, 'Ctrl+Shift+K' e
 formatHotkey('f2'); // 'F2'
 ```
 
-This is what `Menu` uses to draw the shortcut on an entry, from the same string `menuHotkeys`
-turns into a binding, see [Menu.md](Menu.md). A combo it cannot parse is handed back unchanged. The platform is read at call
-time, so a server-rendered page renders the non-Apple spelling.
+This is what `Menu`, `CommandPalette` and `Button` use to draw a shortcut, from the same string
+`useHotkeys` binds, see [Menu.md](Menu.md) and [Button.md](Button.md). A combo it cannot parse is
+handed back unchanged. The platform is read at call time, so a server-rendered page renders the
+non-Apple spelling.
 
 ## useMediaQuery
 
@@ -266,3 +275,13 @@ Hooks documented with the thing they belong to:
 - `useComponentDefaults`, `useLabels` — see [ConfigProvider.md](ConfigProvider.md)
 - `useFormValidator` — see [FormValidator.md](FormValidator.md)
 - `useFormValidatorGroup` — see [FormValidatorGroup.md](FormValidatorGroup.md)
+
+## Migration from repeating hotkeys
+
+Before 0.49, a held `useHotkeys` combo fired its handler for every repeat the browser sent. It now
+fires once. Nothing fails to compile, so look for shortcuts that are meant to be held:
+
+| Before | After |
+|--------|-------|
+| `useHotkeys({ arrowdown: next })`, relying on the repeat | `useHotkeys({ arrowdown: next }, { repeat: true })` |
+| `if (event.repeat) return;` at the top of a handler | nothing: drop the check |

package/docs/Menu.md

@@ -34,7 +34,7 @@ const items: MenuEntry[] = [
 
 `keywords` are extra search terms for [CommandPalette](CommandPalette.md), which takes the same entries. The menu ignores them.
 
-**Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows.
+**Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows. Screen readers get it through `aria-keyshortcuts`, not as part of the item's name.
 
 Listening for it is yours, because only your app knows what else is listening: if it already binds `⌘S` and the menu bound it too, both would fire and the action would run twice. `menuHotkeys` turns the same entries into a map for `useHotkeys`, so the one spelling covers the hint and the binding:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",