@eifi1/ui-kit 0.6.0 → 0.7.0

package/src/components/file-button.tsx

@@ -36,8 +36,14 @@ import { Button, Spinner } from "./ui";
 /** Every string the file pickers ({@link FileButton}, `FileDropzone`) render or speak.
  *  Messages are functions of the file name so a translation can put it anywhere. */
 export interface FilePickerLabels {
-  /** The file's type is not in `accept`. */
+  /** The file's type is not in `accept`, when no `accept` is known to name (see
+   *  `rejectedTypeOnly`). */
   rejectedType: (name: string) => string;
+  /** The file's type is not in `accept`, naming what IS accepted: `accept`'s tokens,
+   *  lower-cased and joined with ", " (`".csv"` => "Only .csv files"). Used whenever
+   *  `accept` is set — kastlan kept a custom `isValid` + `invalidMessage` per form only
+   *  to say this, and `accept` already knows it. */
+  rejectedTypeOnly: (accept: string, name: string) => string;
   /** The file is larger than `maxSize`; `maxSize` arrives formatted ("5 MB"). */
   rejectedSize: (name: string, maxSize: string) => string;
   /** The file was one too many for `maxFiles`. */
@@ -46,6 +52,9 @@ export interface FilePickerLabels {
   rejectedInvalid: (name: string) => string;
   /** Spoken instead of the per-file message when more than one file was refused. */
   rejectedMany: (count: number) => string;
+  /** Spoken (and shown, on a dropzone) when `onPick` refused the WHOLE pick.
+   *  Receives the number of files in it. */
+  rejectedPick: (count: number) => string;
   /** Spoken after a pick the component itself echoes (the dropzone). */
   selected: (count: number, firstName: string) => string;
   /** The dropzone's remove button for one file. */
@@ -59,11 +68,14 @@ export interface FilePickerLabels {
 
 export const DEFAULT_FILE_PICKER_LABELS: FilePickerLabels = {
   rejectedType: (name) => `“${name}” is not a supported file type`,
+  rejectedTypeOnly: (accept) => `Only ${accept} files`,
   rejectedSize: (name, maxSize) => `“${name}” is larger than ${maxSize}`,
   rejectedCount: (name, maxFiles) =>
     `“${name}” was not added: at most ${maxFiles} ${maxFiles === 1 ? "file" : "files"}`,
   rejectedInvalid: (name) => `“${name}” cannot be used here`,
   rejectedMany: (count) => `${count} files were not added`,
+  rejectedPick: (count) =>
+    count === 1 ? "The file was not added" : `None of the ${count} files were added`,
   selected: (count, firstName) => (count === 1 ? `“${firstName}” selected` : `${count} files selected`),
   remove: (name) => `Remove “${name}”`,
   clearAll: "Remove all files",
@@ -100,7 +112,14 @@ export function matchesAccept(file: File, accept: string | undefined): boolean {
     .filter(Boolean);
   if (tokens.length === 0) return true;
   const name = file.name.toLowerCase();
-  const type = (file.type || "").toLowerCase();
+  // An EMPTY type is the browser saying "I don't know", not "it's something else": HEIC
+  // photos on Windows without the codec arrive with `type === ""`. Refusing them
+  // (0.6.0) refused iPhone photos the picker itself had just offered (keksdose). So a
+  // missing type is inferred from the extension where that is unambiguous, and a file
+  // whose type cannot be known at all is given the benefit of the doubt — nothing here
+  // proves it does not match, and the server validates what it receives anyway.
+  const type = (file.type || typeFromExtension(name) || "").toLowerCase();
+  if (!type && !tokens.every((t) => t.startsWith("."))) return true;
   return tokens.some((token) => {
     if (token.startsWith(".")) return name.endsWith(token);
     if (!type) return false;
@@ -109,6 +128,35 @@ export function matchesAccept(file: File, accept: string | undefined): boolean {
   });
 }
 
+/** MIME types for the extensions a browser most often leaves untyped. */
+const EXTENSION_TYPES: Record<string, string> = {
+  heic: "image/heic",
+  heif: "image/heif",
+  avif: "image/avif",
+  webp: "image/webp",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  pdf: "application/pdf",
+  csv: "text/csv",
+  txt: "text/plain",
+};
+
+function typeFromExtension(name: string): string | undefined {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? undefined : EXTENSION_TYPES[name.slice(dot + 1)];
+}
+
+/** `" .PDF, image/png ,"` => `".pdf, image/png"` — `accept` as a person reads it. */
+function formatAccept(accept: string): string {
+  return accept
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean)
+    .join(", ");
+}
+
 /** What the pickers screen a pick with. All optional; nothing set accepts everything. */
 export interface FileScreenOptions {
   accept?: string;
@@ -133,6 +181,15 @@ export function screenFiles(
 ): { accepted: File[]; rejected: FileRejection[] } {
   const accepted: File[] = [];
   const rejected: FileRejection[] = [];
+  // Name what `accept` takes ("Only .csv files") — unless the host translated
+  // `rejectedType` but not yet `rejectedTypeOnly`: its own sentence beats an English one.
+  const acceptText = opts.accept ? formatAccept(opts.accept) : "";
+  const useOnly =
+    acceptText !== "" &&
+    (labels.rejectedTypeOnly !== DEFAULT_FILE_PICKER_LABELS.rejectedTypeOnly ||
+      labels.rejectedType === DEFAULT_FILE_PICKER_LABELS.rejectedType);
+  const typeMessage = (name: string) =>
+    useOnly ? labels.rejectedTypeOnly(acceptText, name) : labels.rejectedType(name);
   for (const file of files) {
     let reason: FileRejectionReason | null = null;
     if (!matchesAccept(file, opts.accept)) reason = "type";
@@ -147,7 +204,7 @@ export function screenFiles(
     }
     const message =
       reason === "type"
-        ? labels.rejectedType(file.name)
+        ? typeMessage(file.name)
         : reason === "size"
           ? labels.rejectedSize(file.name, formatSize(opts.maxSize ?? 0))
           : reason === "count"
@@ -158,6 +215,34 @@ export function screenFiles(
   return { accepted, rejected };
 }
 
+/**
+ * Judges a pick as a whole — keksdose's "refuse the pick if any file is bad", which
+ * with `onFiles` + `onReject` alone had to be rebuilt from two calls in a microtask.
+ *
+ * Called ONCE per pick, after screening and before `onFiles` / `onReject`, with both
+ * halves (either may be empty). Return `false` to refuse the whole pick: the accepted
+ * files are not delivered, `onReject` still receives what screening refused, and one
+ * sentence (`labels.rejectedPick`) is spoken for the pick instead of a per-file one.
+ * Return nothing to let the pick through as usual.
+ *
+ * ```tsx
+ * onPick={(ok, bad) => bad.length === 0 || false}  // all or nothing
+ * ```
+ */
+export type FilePickHandler = (accepted: File[], rejected: FileRejection[]) => boolean | void;
+
+/** @internal The shared tail of both pickers: run `onPick`, and say whether the pick
+ *  stands. A pick with nothing accepted has nothing to refuse, so `false` there is
+ *  treated as no verdict and the usual per-file messages are kept. */
+export function judgePick(
+  onPick: FilePickHandler | undefined,
+  accepted: File[],
+  rejected: FileRejection[],
+): boolean {
+  if (!onPick) return true;
+  return onPick(accepted, rejected) !== false || accepted.length === 0;
+}
+
 /** One sentence for a whole batch of refusals: the file's own message for one, a
  *  count for several — reading out five sentences in a row helps nobody. */
 export function summariseRejections(rejected: readonly FileRejection[], labels: FilePickerLabels): string {
@@ -178,8 +263,11 @@ export interface UseFilePickerOptions extends FileScreenOptions {
    * keksdose's camera input has no `multiple`. Pass one or the other.
    */
   capture?: boolean | "user" | "environment";
-  /** The files that passed, in pick order. Never called with an empty array. */
-  onFiles: (files: File[]) => void;
+  /** The files that passed, in pick order. Never called with an empty array.
+   *  Optional since 0.7 for a caller that takes the pick through `onPick` alone. */
+  onFiles?: (files: File[]) => void;
+  /** See {@link FilePickHandler}: the whole pick at once, with the power to refuse it. */
+  onPick?: FilePickHandler;
   /** The files that did not, with a translated message each. The refusals are also
    *  spoken through a live region, so this is for SHOWING them, not for a11y. */
   onReject?: (rejections: FileRejection[]) => void;
@@ -219,6 +307,7 @@ export function useFilePicker({
   isValid,
   invalidMessage,
   onFiles,
+  onPick,
   onReject,
   disabled,
   labels: labelsProp,
@@ -242,7 +331,12 @@ export function useFilePicker({
       labels,
       fileText.size,
     );
-    if (accepted.length > 0) onFiles(accepted);
+    if (!judgePick(onPick, accepted, rejected)) {
+      if (rejected.length > 0) onReject?.(rejected);
+      announce(labels.rejectedPick(files.length));
+      return;
+    }
+    if (accepted.length > 0) onFiles?.(accepted);
     if (rejected.length > 0) {
       onReject?.(rejected);
       announce(summariseRejections(rejected, labels));
@@ -328,6 +422,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     isValid,
     invalidMessage,
     onFiles,
+    onPick,
     onReject,
     labels,
     pending,
@@ -354,6 +449,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     isValid,
     invalidMessage,
     onFiles,
+    onPick,
     onReject,
     labels,
     disabled: inert,

package/src/components/file-dropzone.tsx

@@ -5,8 +5,8 @@ import { Button, IconButton } from "./ui";
 import { cn } from "../lib/cn";
 import { useAnnounce } from "../hooks/use-announce";
 import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
-import { DEFAULT_FILE_PICKER_LABELS, screenFiles, summariseRejections } from "./file-button";
-import type { FilePickerLabels, FileRejection } from "./file-button";
+import { DEFAULT_FILE_PICKER_LABELS, judgePick, screenFiles, summariseRejections } from "./file-button";
+import type { FilePickHandler, FilePickerLabels, FileRejection } from "./file-button";
 
 /**
  * Where a refused file's message goes.
@@ -26,8 +26,8 @@ export type FileDropzoneRejectionFeedback = "toast" | "inline" | "none";
  * The DOM event of that name belongs to form validation and takes a `FormEvent`; this
  * one takes the rejected `File`, and the kit's meaning is the one every caller already
  * writes. Everything else a `<div>` takes reaches the root — which carries
- * `role="button"`, so that is also where an `aria-label` or an `aria-describedby`
- * belongs.
+ * `role="group"` named by `dropLabel`, so that is also where an `aria-label` or an
+ * `aria-describedby` belongs.
  *
  * Two modes. SINGLE (the default, and all of 0.5): `file` + `onFileSelected`. MULTIPLE
  * (`multiple`): `files` + `onFilesSelected`. They are optional rather than a union so
@@ -49,7 +49,7 @@ export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">,
    * Show a remove button inside the zone once something is chosen (kastlan asked for
    * it: the only way to un-choose a file was to reload). Single mode: removes the file.
    * Multiple mode: a "remove all" button. The host clears its own state here — the
-   * zone is controlled. Focus returns to the zone, and the removal is announced.
+   * zone is controlled. Focus moves to the Browse button, and the removal is announced.
    */
   onClear?: () => void;
   /** Multiple mode: a remove button per listed file. */
@@ -81,6 +81,10 @@ export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">,
   onInvalid?: (file: File) => void;
   /** Every refused file of one pick, with its reason and message. */
   onReject?: (rejections: FileRejection[]) => void;
+  /** The whole pick at once, before any of the above — return `false` to refuse all
+   *  of it (see {@link FilePickHandler}). A refused pick selects nothing; its one
+   *  message (`labels.rejectedPick`) goes where `rejectionFeedback` says. */
+  onPick?: FilePickHandler;
   /** See {@link FileDropzoneRejectionFeedback}. Defaults to `"toast"` when neither
    *  `onInvalid` nor `onReject` is given, `"none"` when one is. */
   rejectionFeedback?: FileDropzoneRejectionFeedback;
@@ -116,6 +120,7 @@ export function FileDropzone({
   maxFiles,
   onInvalid,
   onReject,
+  onPick,
   rejectionFeedback,
   labels: labelsProp,
   dropLabel,
@@ -130,7 +135,7 @@ export function FileDropzone({
   const [dragOver, setDragOver] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
-  const rootRef = useRef<HTMLDivElement>(null);
+  const browseRef = useRef<HTMLButtonElement>(null);
   const errorId = useId();
   // The size through the kit's `file.size` label (the provider's locale by default).
   // This was `${n / 1024} KB`: ASCII digits, an English unit, and a binary kilobyte
@@ -138,9 +143,8 @@ export function FileDropzone({
   const fileText = useKitFileLabels();
   const labels = useKitLabels("filePicker", DEFAULT_FILE_PICKER_LABELS, labelsProp);
   // Two regions, two urgencies: a pick or a removal is news, a refusal is a failure.
-  // Both are needed because nothing inside a `role="button"` is read out — its
-  // children are presentational — so the echoed file name never reaches a screen
-  // reader on its own.
+  // The echoed file name is only text in the zone, and text changing somewhere on the
+  // page is not announced by itself.
   const status = useAnnounce();
   const alert = useAnnounce({ politeness: "assertive" });
   const feedback: FileDropzoneRejectionFeedback =
@@ -149,8 +153,9 @@ export function FileDropzone({
   const acceptFiles = (list: ArrayLike<File> | null | undefined) => {
     if (!list || list.length === 0) return;
     const all = Array.from(list);
+    const picked = multiple ? all : all.slice(0, 1);
     const { accepted, rejected } = screenFiles(
-      multiple ? all : all.slice(0, 1),
+      picked,
       {
         accept: isValid ? undefined : accept,
         maxSize,
@@ -161,7 +166,8 @@ export function FileDropzone({
       labels,
       fileText.size,
     );
-    if (accepted.length > 0) {
+    const stands = judgePick(onPick, accepted, rejected);
+    if (stands && accepted.length > 0) {
       setError(null);
       if (multiple) {
         onFilesSelected?.(accepted);
@@ -171,10 +177,12 @@ export function FileDropzone({
       }
       status.announce(labels.selected(accepted.length, accepted[0].name));
     }
-    if (rejected.length > 0) {
+    if (!stands || rejected.length > 0) {
       for (const r of rejected) onInvalid?.(r.file);
-      onReject?.(rejected);
-      const message = summariseRejections(rejected, labels);
+      if (rejected.length > 0) onReject?.(rejected);
+      const message = stands
+        ? summariseRejections(rejected, labels)
+        : labels.rejectedPick(picked.length);
       if (feedback === "toast") {
         // sonner is an optional peer: imported here, on the failure path only, so an
         // app that never trips this never has to install it. Not awaited — nothing
@@ -190,9 +198,9 @@ export function FileDropzone({
   };
 
   // The remove buttons unmount with the file they removed, and focus would fall to
-  // <body>. The zone is where the next action (pick again) starts.
+  // <body>. Browse is where the next action (pick again) starts.
   const afterRemoval = (message: string) => {
-    rootRef.current?.focus();
+    browseRef.current?.focus();
     status.announce(message);
   };
 
@@ -202,11 +210,17 @@ export function FileDropzone({
 
   return (
     <>
+      {/* A named group, NOT a `role="button"`. It was one, with real buttons (Browse,
+          the remove buttons) inside it: nested interactive controls, which ARIA forbids
+          because a button's children are presentational — a screen reader either read
+          the zone as one opaque button or skipped the inner ones, and the zone was an
+          extra Tab stop that did what Browse does. Now the keyboard path is Browse, a
+          real button; the zone keeps its drop target and its click-anywhere for a
+          pointer, which is a convenience on top of Browse rather than the only way in. */}
+      {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions -- the click is a pointer shortcut for Browse, see above */}
       <div
-        // `...rest` first: every handler below is the drop gesture itself, and the
-        // `role`/`tabIndex` pair is what makes this div operable by keyboard at all.
+        // `...rest` first: every handler below is the drop gesture itself.
         {...rest}
-        ref={rootRef}
         onDragEnter={(e) => {
           e.preventDefault();
           e.stopPropagation();
@@ -230,24 +244,16 @@ export function FileDropzone({
           setDragOver(false);
           acceptFiles(e.dataTransfer.files);
         }}
+        // Pointer only; every control inside stops its own click from reaching here. The
+        // keyboard equivalent is the Browse button, so no key handler belongs on a group.
         onClick={() => fileInputRef.current?.click()}
-        onKeyDown={(e) => {
-          // Only the zone's OWN keys. A remove button inside it is a real button, and
-          // Enter on it bubbling up here would open the picker instead of removing.
-          if (e.target !== e.currentTarget) return;
-          if (e.key === "Enter" || e.key === " ") {
-            e.preventDefault();
-            fileInputRef.current?.click();
-          }
-        }}
-        role="button"
-        tabIndex={0}
+        role="group"
         // The DOM spelling wins over `dropLabel`, which stays the name for every caller
         // that passes no `aria-label` — i.e. all of them today. Standardising on
         // `aria-label` (audit §api-design) does not get to silently rename an existing
         // required prop.
         aria-label={ariaLabel ?? dropLabel}
-        // No `aria-invalid`: ARIA does not allow it on `role="button"`. The message is
+        // No `aria-invalid`: ARIA does not allow it on `role="group"`. The message is
         // reached through the description instead, and spoken when it appears.
         aria-describedby={describedBy}
         data-invalid={showError || undefined}
@@ -307,7 +313,9 @@ export function FileDropzone({
         ) : (
           <>
             <div className="flex items-center gap-1 text-sm text-[var(--text-secondary)]">
-              {file ? <span className="font-medium">{file.name}</span> : emptyLabel}
+              {/* `!multiple`: in multiple mode an empty `files` list is "nothing chosen",
+                  whatever a stray `file` prop says — it used to show that file's name. */}
+              {!multiple && file ? <span className="font-medium">{file.name}</span> : emptyLabel}
               {!multiple && file && onClear && (
                 <IconButton
                   type="button"
@@ -330,6 +338,7 @@ export function FileDropzone({
         )}
         <div className="flex flex-wrap items-center justify-center gap-2">
           <Button
+            ref={browseRef}
             type="button"
             variant="secondary"
             onClick={(e) => {
@@ -377,9 +386,9 @@ export function FileDropzone({
           className="sr-only"
         />
       </div>
-      {/* Outside the zone: a live region inside a `role="button"` is inside
-          presentational content, and screen readers are not consistent about
-          reading those. `sr-only-fixed`, so they need no positioned ancestor. */}
+      {/* Outside the zone, where they have always been (the zone used to be a
+          `role="button"`, whose content is presentational). `sr-only-fixed`, so they
+          need no positioned ancestor. */}
       <span {...status.regionProps} />
       <span {...alert.regionProps} />
     </>

package/src/components/grouped-picker.tsx

@@ -100,7 +100,7 @@ export function GroupedPicker({
         <ChevronDown className="size-4 shrink-0 text-[var(--text-placeholder)]" />
       </button>
       {open && (
-        <div className="absolute left-0 z-30 mt-1 flex max-h-96 w-[min(56rem,85vw)] flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg">
+        <div className="absolute start-0 z-30 mt-1 flex max-h-96 w-[min(56rem,85vw)] flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg">
           <DropdownSearchHeader
             query={query}
             onQueryChange={setQuery}
@@ -132,7 +132,7 @@ export function GroupedPicker({
                                 setOpen(false);
                               }}
                               className={cn(
-                                "flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-left text-sm",
+                                "flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-start text-sm",
                                 isSelected
                                   ? "bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)]"
                                   : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",

package/src/components/hover-menu.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
 import { cn } from "../lib/cn";
-import { useOutsideClick } from "../hooks/use-dismiss";
+import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
 
 /**
  * Exported and `<div>`-shaped: the top bar composes several of these side by side, and
@@ -14,13 +14,18 @@ import { useOutsideClick } from "../hooks/use-dismiss";
 export interface HoverMenuProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
   trigger: (state: { open: boolean; toggle: () => void }) => ReactNode;
   children: (close: () => void) => ReactNode;
-  align?: "left" | "right";
+  /**
+   * Which edge of the trigger the panel lines up with. `start`/`end` follow the
+   * reading direction (`end` is the right edge in LTR, the left in RTL); `left`/`right`
+   * are physical and kept for existing callers. Default `end` — the same right-aligned
+   * panel as before in LTR, mirrored in RTL.
+   */
+  align?: "start" | "end" | "left" | "right";
   panelClassName?: string;
   /** Extra classes for the WRAPPER (the panel has {@link panelClassName}). */
   className?: string;
   /**
-   * @deprecated Use the DOM spelling `aria-label`, which now reaches the wrapper like
-   * any other attribute. Kept working because keksdose, kastlan and lenkbank all pass
+   * @deprecated Use the DOM spelling `aria-label`, which names the `role="menu"` panel. Kept working because keksdose, kastlan and lenkbank all pass
    * this today and a rename to save one line of resolution is not a patch release; it
    * loses to `aria-label` wherever both are given. Removal is a later minor.
    */
@@ -35,6 +40,42 @@ const CLOSE_DELAY_MS = 120;
 
 type Phase = "closed" | "opening" | "open" | "closing";
 
+const ALIGN_CLASS = { start: "start-0", end: "end-0", left: "left-0", right: "right-0" } as const;
+
+/** Explicit menu-item roles a caller may already have written. */
+const ITEM_ROLES = '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]';
+/** What the panel promotes to `menuitem` when the caller wrote plain controls. */
+const PLAIN_ITEMS = "button:not([role]),a[href]:not([role])";
+/** The trigger: the first focusable in the wrapper that is not inside the panel. */
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+/**
+ * Give the caller's markup menu semantics.
+ *
+ * `children` is arbitrary — every caller in the kit renders a `<ul>` of `<li>`s holding
+ * `<button>`s and router `<Link>`s — so the panel was a `role="menu"` whose children
+ * were a list, list items and plain buttons: no `menuitem` anywhere, which is a menu
+ * with nothing in it as far as a screen reader is concerned. Rather than make every
+ * caller rewrite its rows, the panel upgrades them after render: controls become
+ * `menuitem`s out of the Tab order (the arrow keys move between them), and the list
+ * markup in between becomes `role="none"` so the menu owns its items directly. An
+ * element that already carries a role is the caller's decision and is left alone.
+ */
+function applyMenuSemantics(menu: HTMLElement): HTMLElement[] {
+  for (const el of menu.querySelectorAll<HTMLElement>(PLAIN_ITEMS)) el.setAttribute("role", "menuitem");
+  const items = Array.from(menu.querySelectorAll<HTMLElement>(ITEM_ROLES));
+  for (const item of items) {
+    item.setAttribute("tabindex", "-1");
+    for (let el = item.parentElement; el && el !== menu; el = el.parentElement) {
+      if (!el.hasAttribute("role")) el.setAttribute("role", "none");
+    }
+  }
+  for (const el of menu.querySelectorAll<HTMLElement>("ul:not([role]),ol:not([role]),li:not([role])")) {
+    el.setAttribute("role", "none");
+  }
+  return items.filter((el) => !el.hasAttribute("disabled") && el.getAttribute("aria-disabled") !== "true");
+}
+
 // Only one hover menu may show its panel at a time across the app — opening
 // one closes whichever was open, so adjacent top-bar menus can't overlap
 // (feedback #251). Module-level is fine: there is one cursor per document.
@@ -43,7 +84,7 @@ let activeClose: (() => void) | null = null;
 export function HoverMenu({
   trigger,
   children,
-  align = "right",
+  align = "end",
   panelClassName,
   className,
   ariaLabel,
@@ -118,6 +159,87 @@ export function HoverMenu({
 
   useOutsideClick(wrapperRef, close, open);
 
+  const menuRef = useRef<HTMLDivElement>(null);
+  /** Set by a keyboard press on the trigger, so the open that follows moves focus into
+   *  the menu. A hover or a mouse click opens it without taking focus off the page. */
+  const focusOnOpenRef = useRef<"first" | "last" | null>(null);
+
+  const triggerEl = () =>
+    Array.from(wrapperRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE) ?? []).find(
+      (el) => !menuRef.current?.contains(el),
+    ) ?? null;
+  const items = () => (menuRef.current ? applyMenuSemantics(menuRef.current) : []);
+
+  // Escape closes, from anywhere — it did nothing at all before. Focus goes back to the
+  // trigger only when it was inside the menu: a panel opened by hover while the user is
+  // typing elsewhere must not yank the caret over here on the way out.
+  useEscapeKey(() => {
+    const hadFocus = wrapperRef.current?.contains(document.activeElement) ?? false;
+    close();
+    if (hadFocus) triggerEl()?.focus();
+  }, open);
+
+  // Upgrade the markup every render while open (the caller's rows can change), then
+  // honour a pending keyboard open.
+  useLayoutEffect(() => {
+    if (!open) return;
+    const list = items();
+    const want = focusOnOpenRef.current;
+    focusOnOpenRef.current = null;
+    if (want) (want === "last" ? list[list.length - 1] : list[0])?.focus();
+  });
+
+  // Trigger state for assistive technology, on whatever element the caller rendered.
+  // Only where the caller has not said something of its own.
+  useLayoutEffect(() => {
+    const el = triggerEl();
+    if (!el) return;
+    if (!el.hasAttribute("aria-haspopup")) el.setAttribute("aria-haspopup", "menu");
+    if (el.getAttribute("aria-haspopup") === "menu") el.setAttribute("aria-expanded", String(open));
+  });
+
+  /** ↑/↓ roving focus with wrap, Home/End, Tab leaves (and closes); on the trigger,
+   *  Enter/Space/↓ open onto the first item and ↑ onto the last. */
+  const onKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    const target = e.target as HTMLElement;
+    const inMenu = menuRef.current?.contains(target) ?? false;
+    if (!inMenu) {
+      if (target !== triggerEl()) return;
+      if (e.key === "Enter" || e.key === " ") {
+        // The trigger's own click handler does the toggling; this only records that
+        // the press came from a keyboard.
+        if (!open) focusOnOpenRef.current = "first";
+      } else if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+        e.preventDefault();
+        const edge = e.key === "ArrowDown" ? "first" : "last";
+        if (open) {
+          const list = items();
+          (edge === "last" ? list[list.length - 1] : list[0])?.focus();
+        } else {
+          focusOnOpenRef.current = edge;
+          openedByHoverRef.current = false;
+          setPhase("open");
+        }
+      }
+      return;
+    }
+    if (e.key === "Tab") {
+      close();
+      return;
+    }
+    const list = items();
+    if (list.length === 0) return;
+    const at = list.indexOf(document.activeElement as HTMLElement);
+    let next: number | null = null;
+    if (e.key === "ArrowDown") next = at < 0 ? 0 : (at + 1) % list.length;
+    else if (e.key === "ArrowUp") next = at < 0 ? list.length - 1 : (at - 1 + list.length) % list.length;
+    else if (e.key === "Home") next = 0;
+    else if (e.key === "End") next = list.length - 1;
+    if (next === null) return;
+    e.preventDefault();
+    list[next].focus();
+  };
+
   // Keep the panel inside the viewport (feedback #85): a wide panel anchored to a
   // trigger near a screen edge would otherwise spill off it (on mobile the guided-
   // tours menu ran off the left). Once open, measure and translate it horizontally
@@ -153,9 +275,10 @@ export function HoverMenu({
       className={cn("relative", className)}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
-      // The DOM spelling wins; {@link HoverMenuProps.ariaLabel} is the deprecated alias
-      // three apps still pass, so it stays as the fallback rather than as the answer.
-      aria-label={ariaLabelAttr ?? ariaLabel}
+      onKeyDown={(e) => {
+        rest.onKeyDown?.(e);
+        onKeyDown(e);
+      }}
     >
       {trigger({ open, toggle })}
       {open && (
@@ -163,12 +286,18 @@ export function HoverMenu({
           ref={panelRef}
           className={cn(
             "absolute top-full z-40 pt-2",
-            align === "right" ? "right-0" : "left-0",
+            ALIGN_CLASS[align],
           )}
           style={shiftX ? { transform: `translateX(${shiftX}px)` } : undefined}
         >
           <div
+            ref={menuRef}
             role="menu"
+            // On the element with the role. It used to sit on the role-less wrapper,
+            // where no screen reader reads a name. The DOM spelling wins;
+            // {@link HoverMenuProps.ariaLabel} is the deprecated alias three apps still
+            // pass, so it stays as the fallback rather than as the answer.
+            aria-label={ariaLabelAttr ?? ariaLabel}
             className={cn(
               "min-w-44 max-w-[calc(100vw-1rem)] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
               panelClassName,

package/src/components/icon-picker.tsx

@@ -65,6 +65,15 @@ export interface IconPickerProps<T extends string>
   searchable?: boolean;
   /** 28 / 32 / 44px tiles. Default "md"; "lg" is the touch-target size. */
   size?: TileSize;
+  /**
+   * Classes for every tile's frame, merged after the kit's own — so a caller's
+   * `size-*` beats `size`'s. For a tile that has to follow a container query or a
+   * breakpoint (keksdose grows its tiles to 40px in a narrow card:
+   * `tileClassName="@max-md:size-10"`) without reaching into the kit's markup with an
+   * `[&_[role=radio]]` selector. The swatch dot / glyph inside keeps `size`'s
+   * dimensions; the tile grows round it.
+   */
+  tileClassName?: string;
   disabled?: boolean;
   labels?: Partial<IconPickerLabels>;
 }
@@ -93,6 +102,7 @@ export function IconPicker<T extends string>({
   activation = "automatic",
   searchable = false,
   size = "md",
+  tileClassName,
   disabled = false,
   labels,
   className,
@@ -156,7 +166,10 @@ export function IconPicker<T extends string>({
             return Icon ? <Icon aria-hidden className={TILE_SIZE[size].glyph} /> : null;
           }}
           tileClassName={(_item, selected) =>
-            selected ? "text-[var(--text-primary)]" : "text-[var(--text-secondary)]"
+            cn(
+              selected ? "text-[var(--text-primary)]" : "text-[var(--text-secondary)]",
+              tileClassName,
+            )
           }
         />
       </div>