@eifi1/ui-kit 0.6.1 → 0.7.0

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>