staffa 0.15.0 → 0.17.0

package/dist/components/menu.d.ts

@@ -26,15 +26,40 @@ export interface MenuItem {
      * `attrs: "data-panel=push"` for a row that should stack instead.
      */
     href?: string;
+    /**
+     * A keyboard shortcut that activates this item: `"mod+k"`, `"f2"`, a bare
+     * `"?"`. The spelling, and which keystrokes are yours to take, are
+     * documented on {@link bindKey}. In a dropdown or context menu the
+     * combination shows at the right end of the row (not on a touch device); a
+     * nav row — `S.main`'s sidebar, {@link menu} — keeps its label clean and
+     * tells it in its {@link MenuItem.tooltip | tooltip} instead. Either way
+     * it reaches screen readers as `aria-keyshortcuts`, and the `?` overview
+     * ({@link showKeyHelp}) lists it under the item's label. Activating runs
+     * `click` with the `KeyboardEvent` and follows `href` as a fresh navigation
+     * to it — the target getting its own panel stack, as a nav item's does.
+     *
+     * The shortcut works with the menu shut — rather the point of one on a
+     * dropdown or context menu — for as long as whatever owns the items is
+     * drawn: the {@link menu}, {@link menuButton} or {@link addContextMenu}
+     * call, or `S.main`'s `nav`. (The bare {@link showFloatingMenu} binds
+     * nothing: its menu exists only while it is up.) A disabled item's key is
+     * not bound.
+     */
+    key?: string;
+    /**
+     * A tooltip for this item, shown on hover and keyboard focus. A string
+     * renders as rich text. In a nav, the item's `key` is shown underneath it,
+     * behind a subtle separator (see {@link MenuItem.key}).
+     */
+    tooltip?: Slot;
     /**
      * Pages this item claims *beyond* its own `href`: a string claims that path
      * and everything under it (`"/mail"` claims `/mail/…`, not `/mailbox`), a
      * function is asked with the current path. While a claimed page is current,
      * the item is highlighted and the branches above it stay unfolded — for the
      * detail screens a menu has no row of their own: the `/thread/[id]` a
-     * notification lands on, an icon's page under the gallery's row. Claims
-     * work from the very first paint, so they also cover cold deep links,
-     * which no amount of fold-state keeping can.
+     * notification lands on, an icon's page under the gallery's row. Claims work
+     * from the first paint, so cold deep links are covered too.
      */
     match?: string | ((path: string) => boolean);
     /** `target` for the link (`_blank`, etc.). Only meaningful with `href`. */
@@ -154,15 +179,28 @@ export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor" | "at" | "cl
  * @param onLeafSelect Optional — run when a *leaf* item is activated (used by
  *   the floating menu to close itself on selection). A branch expanding is
  *   not a selection, so it doesn't run this.
+ * @param keyHints Print each row's `key` at its right end, as the floating
+ *   menus do. Off — any kind of nav — a row tells its key in its tooltip
+ *   instead, keeping the resting rows quiet.
  */
-export declare function drawMenu(items: MenuEntry[], onLeafSelect?: () => void): void;
+export declare function drawMenu(items: MenuEntry[], onLeafSelect?: () => void, keyHints?: boolean): void;
 /**
- * Whether any item anywhere in `items` — branches, their leaves, `match`
- * claims — is the current page. The one question both the fold logic and the
- * shell's tagline rule (see `taglineFits` in main.ts) ask of a menu, exported
- * so the two can never disagree with the highlighting.
+ * Whether any item anywhere in `items` — branches, their leaves, `match` claims — is
+ * the current page. Exported because the shell's tagline rule (`taglineFits` in
+ * main.ts) must agree with the highlighting.
  */
 export declare function anyCurrent(items: MenuEntry[]): boolean;
+/**
+ * Bind the shortcuts of every item in a menu — see {@link MenuItem.key} — for as
+ * long as the calling scope lives. The `?` overview lists each binding under its
+ * item's label. No `aria-keyshortcuts` here — the rows announce their own.
+ *
+ * `getItems` is a function rather than the array itself, so that the read happens
+ * in this scope and not the caller's: a menu's items are often a reactive array,
+ * and subscribing the caller (`S.main()`'s whole shell, say) to it would redraw
+ * far more than the menu.
+ */
+export declare function registerMenuKeys(getItems: () => MenuEntry[], onSelect?: () => void): void;
 /**
  * Whether the navigation that just landed on `path` was a branch row expanding
  * (consuming the note it left). Internal — used by the floating menu below and
@@ -210,8 +248,8 @@ export declare function menu(opts: MenuListOptions): void;
 /**
  * Open a floating dropdown menu anchored to an element. Portals to
  * `document.body` (never clipped), positions itself (flipping up when there's
- * no room below), and closes on Escape, Tab, item selection, or any click
- * outside the panel and anchor. Returns a `close()` function.
+ * no room below), and closes on Escape, Tab, item selection, a navigation, or
+ * any click outside the panel and anchor. Returns a `close()` function.
  *
  * Menus are usually opened through {@link menuButton} or
  * {@link addContextMenu}; reach for this primitive when you need to trigger a