@ahrowe/ui 0.47.3 → 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/dist/types/common/menu/menu.types.d.ts

@@ -25,6 +25,11 @@ export interface MenuAction {
     disabled?: boolean;
     /** Renders in the destructive colour. For deleting, discarding, revoking. */
     danger?: boolean;
+    /**
+     * Followed after `onClick` and `onAction`. In `Menu` a real `<a>`, so Ctrl/⌘-click opens a new tab.
+     * Loads the whole page: with a client-side router, navigate in `onClick` instead.
+     */
+    href?: string;
     onClick?: () => void;
 }
 /** A line between groups of actions. */

package/dist/types/common/menu/menuHotkeys.d.ts

@@ -14,7 +14,7 @@ import { MenuEntry } from './menu.types.js';
  * useHotkeys(menuHotkeys(items, run), { enabled: isOpen }); // only while the menu is open
  * ```
  *
- * Runs each entry the way clicking it does: its own `onClick`, then `onAction`. A `disabled`
- * entry, and an entry with no `shortcut`, is left out.
+ * Runs each entry the way clicking it does: its own `onClick`, then `onAction`, then its `href`.
+ * A `disabled` entry, and an entry with no `shortcut`, is left out.
  */
 export declare function menuHotkeys(items: MenuEntry[], onAction?: (id: string) => void): HotkeyMap;

package/dist/types/common/menu/menuItem.d.ts

@@ -0,0 +1,10 @@
+import { CSSProperties, ReactNode } from 'react';
+import { MenuAction, MenuEntry } from './menu.types.js';
+export declare function hasAnyIcon(items: MenuEntry[]): boolean;
+/** The action's icon, or an empty cell as wide when another action has one, so the labels line up. */
+export declare function renderItemIcon(icon: MenuAction['icon'], reserveCell: boolean, props: {
+    className: string;
+    style?: CSSProperties;
+}): ReactNode;
+/** Runs an action the way clicking it does: its own `onClick`, then `onAction`, then its `href`. */
+export declare function runMenuAction(action: MenuAction, onAction?: (id: string) => void): void;

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/CommandPalette.md

@@ -73,7 +73,7 @@ On a small touch screen it can present as a bottom sheet like every `Modal`: pas
 | `isLoading` | `boolean` | Shows the `loading` label instead of `empty` while nothing matches |
 | `presentation` | `Presentation` | Centred dialog (default), bottom sheet, or a sheet only on a small touch screen |
 
-A command is a `MenuAction`: `id`, `label`, `icon`, `shortcut`, `keywords`, `disabled`, `danger` and `onClick`. See [Menu.md](Menu.md).
+A command is a `MenuAction`: `id`, `label`, `icon`, `shortcut`, `keywords`, `disabled`, `danger`, `href` and `onClick`. A command with an `href` goes there after running. See [Menu.md](Menu.md).
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CommandPalette: { presentation: Presentation.Auto } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

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/InteractableDiv.md

@@ -23,4 +23,4 @@ import { InteractableDiv } from '@ahrowe/ui';
 </InteractableDiv>
 ```
 
-**Note:** Check [package/common/interactableDiv/](https://github.com/AndreasWeinzierl/ahrowe-ui/tree/master/package/common/interactableDiv) for full prop details.
+**Note:** Check [package/common/interactableDiv/](https://github.com/ahrowe-dev/ahrowe-ui/tree/master/package/common/interactableDiv) for full prop details.

package/docs/Menu.md

@@ -27,14 +27,14 @@ const items: MenuEntry[] = [
 **Entries** are one of three shapes, and the list is read in the order you give it:
 
 ```ts
-{ id: 'edit', label: 'Edit', icon, shortcut, keywords, disabled, danger, onClick }  // an action
-{ separator: true }                                                                 // a line
-{ heading: 'This document' }                                                        // a label over what follows
+{ id: 'edit', label: 'Edit', icon, shortcut, keywords, disabled, danger, href, onClick }  // an action, or a link with `href`
+{ separator: true }                                                                       // a line
+{ heading: 'This document' }                                                              // a label over what follows
 ```
 
 `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:
 
@@ -54,7 +54,7 @@ useHotkeys(menuHotkeys(items, run));
 useHotkeys(menuHotkeys(items, run), { enabled: isOpen });
 ```
 
-It runs each entry the way clicking it does, its own `onClick` then `onAction`, and leaves out a `disabled` entry and any entry with no `shortcut`. Bind them yourself instead if the actions already live in a keymap of your own; the menu does not mind either way.
+It runs each entry the way clicking it does, its own `onClick` then `onAction` then its `href`, and leaves out a `disabled` entry and any entry with no `shortcut`. Bind them yourself instead if the actions already live in a keymap of your own; the menu does not mind either way.
 
 An action runs its own `onClick` first, then `onAction` on the menu, then the menu closes. Use whichever of the two fits: a handler per entry when they are unrelated, `onAction` when they funnel into one place.
 
@@ -116,10 +116,11 @@ Separators and headings are never focused. The trigger is given `aria-haspopup`,
 |-------|------|-------------|
 | `id` | `string` | Stable id, also what `onAction` reports |
 | `label` | `ReactNode` | What the entry says |
-| `icon` | `IconContent` | Leading icon |
+| `icon` | `IconContent` | Leading icon. Entries without one keep its space while any other has one, so the labels line up. Same in `CommandPalette` |
 | `shortcut` | `string` | A combo in `useHotkeys` spelling, e.g. `'mod+k'`. Shown on the trailing edge, written for the platform. Binding it is yours, see `menuHotkeys` |
 | `disabled` | `boolean` | Not clickable, and skipped by the arrow keys |
 | `danger` | `boolean` | Renders in the destructive colour |
+| `href` | `string` | Makes the entry a real `<a>`, so Ctrl/⌘-click and a middle click open it in a new tab. A click runs `onClick` and `onAction` first, a middle click neither. The browser loads the page, so with a client-side router navigate in `onClick` instead. A `disabled` entry stays a button |
 | `onClick` | `() => void` | Runs before `onAction` |
 
 **Slots:** `root` `trigger` `menu` `item` `itemIcon` `itemLabel` `itemShortcut` `separator` `heading`

package/docs/ProgressBar.md

@@ -49,7 +49,7 @@ when unset. A label on a coloured segment is black or white, whichever reads on
 
 | Variable | Falls back to |
 |----------|---------------|
-| `--progress-bar-track-color` | `var(--background-accent)` |
+| `--progress-bar-track-color` | `var(--background-accent-light)` |
 
 ```tsx
 // Theme-wide, via ThemeProvider

package/docs/RadioGroup.md

@@ -79,6 +79,6 @@ interface RadioOption {
 
 ## Sizing
 
-The group is sized by its font, so the radios, the spacing between options and the gap to each label all scale with the text. `--radio-size` and `--radio-gap` override the circle and the label spacing; they fall back to `1.125em` and `0.625em`, i.e. 18px and 10px at a 16px base. The dot is always half the circle.
+The group is sized by its font, so the radios, the spacing between options and the gap to each label all scale with the text. `--radio-size` and `--radio-gap` override the circle and the label spacing; they fall back to `1.125em` and `0.625em`, i.e. 18px and 10px at a 16px base. The dot is about half the circle.
 
 The `size` prop still wins where it is given, for a radio that must match a fixed layout rather than the text around it.

package/docs/ThemeProvider.md

@@ -92,7 +92,7 @@ interface Theme {
 }
 ```
 
-**Key CSS variables** (see `package/common/themeProvider/theme.types.ts` for the full list):
+**Key CSS variables** (`ThemeVariables` is the full list, in `node_modules/@ahrowe/ui/dist/types/common/themeProvider/theme.types.d.ts`):
 
 | Variable | Purpose |
 |----------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.47.3",
+  "version": "0.49.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",
@@ -18,13 +18,13 @@
   ],
   "homepage": "https://ahrowe.com/packages/ui/demo/",
   "bugs": {
-    "url": "https://github.com/AndreasWeinzierl/ahrowe-ui/issues"
+    "url": "https://github.com/ahrowe-dev/ahrowe-ui/issues"
   },
   "license": "MIT",
   "author": "ahrowe <dev@ahrowe.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AndreasWeinzierl/ahrowe-ui.git"
+    "url": "git+https://github.com/ahrowe-dev/ahrowe-ui.git"
   },
   "style": "./dist/style.css",
   "bin": {
@@ -77,7 +77,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "build:demo": "vite build --base=/packages/ui/demo/ --outDir dist-demo",
+    "build:demo": "vite build --base=./ --outDir dist-demo",
     "build:lib": "vite build --config vite.lib.config.ts",
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",