@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/components/full-bleed-dialog.tsx

@@ -0,0 +1,179 @@
+import { useRef } from "react";
+import { createPortal } from "react-dom";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from "react";
+import { X } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { useBackdropClose } from "./modal";
+import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
+import { useOverlayHistory } from "../hooks/use-overlay-history";
+import { useCloseTransition } from "../hooks/use-close-transition";
+import { useFocusTrap } from "../hooks/use-focus-trap";
+
+/**
+ * Named and exported, because `ComponentProps<typeof FullBleedDialog>` was the only way
+ * to say "the props of this" and five call sites across keksdose and kastlan had already
+ * written one (audit §api-design).
+ *
+ * It extends the `<div>` attributes so a caller can reach the OUTER element — the one
+ * carrying `role="dialog"`, and therefore the one an `aria-label`, an
+ * `aria-describedby` or a `data-tour` anchor belongs on. {@link className} keeps going
+ * to the panel inside it, which is what it has always meant here.
+ */
+export interface FullBleedDialogProps extends ComponentPropsWithoutRef<"div"> {
+  open: boolean;
+  /** The X, the backdrop (where one shows) and — unless {@link backCloses} is off —
+   *  the platform Back gesture all call this. */
+  onClose: () => void;
+  /** What the header strip shows beside the close button. */
+  header?: ReactNode;
+  closeLabel: string;
+  children: ReactNode;
+  /**
+   * Push a history entry so Back dismisses this dialog instead of navigating
+   * (Keksdose feedback #172). On by default, because a full-screen form that ignores
+   * the phone's universal "go back" gesture does not merely fail to close — the
+   * navigation lands somewhere else with the form still notionally open.
+   *
+   * **Off for a caller whose open state is already in the URL.** The transactions
+   * create card is `?action=new`, so Back already pops it through the router; a
+   * sentinel on top of that would cost two presses to close one dialog. One owner of
+   * the Back press, always.
+   */
+  backCloses?: boolean;
+  /** Extra classes for the PANEL (not the backdrop). */
+  className?: string;
+}
+
+/**
+ * The phone's full-screen dialog: a panel that covers the viewport edge to edge.
+ *
+ * Not {@link Modal}, and that is a decision rather than an omission. Keksdose feedback
+ * #32: the inset panel #204 shipped left a strip of page showing beside it on a phone,
+ * and tapping that strip dismissed a form mid-edit. With no backdrop exposed there is
+ * nothing to mis-tap, so the X is the way out — `backdropClose` stays wired for any
+ * layout that does leave a backdrop visible, and costs nothing where none is.
+ *
+ * ## Why it is a component
+ *
+ * It was markup inside `data-table.tsx`, where it is the phone's row EDITOR. Keksdose
+ * live #307's follow-up needed the same shell for the transactions CREATE card —
+ * *"Is the creation window of the tx still different than the edit window? Since the tx
+ * list still appears below when scrolling down?"* — and the two answers to that are
+ * either one component or two copies that drift. Every previous convergence in that app
+ * drifted the moment a second surface was written beside the first, which is what
+ * `field-layer-parity` exists to catch one layer down.
+ *
+ * So the panel, the header strip, the scrolling body, the body-scroll lock and the Back
+ * handling are all here, once.
+ *
+ * ## What the caller still owns
+ *
+ * The HEADER's content, because the two callers name themselves differently: the row
+ * editor shows the row's own first column, the create card a plain title. And `open`,
+ * because who decides is the caller's business — see {@link backCloses}.
+ */
+export function FullBleedDialog({
+  open,
+  onClose,
+  header,
+  closeLabel,
+  children,
+  backCloses = true,
+  className,
+  ...rest
+}: FullBleedDialogProps) {
+  // Every way OUT goes through `requestClose`, so the panel lowers itself before the
+  // caller unmounts it (live #320 rework). `onClose` is still what finally runs — this
+  // only delays it by the length of the animation.
+  const { closing, requestClose } = useCloseTransition(onClose);
+  const backdropClose = useBackdropClose(requestClose);
+  // The page behind must not scroll or jump under the overlay (feedback #204).
+  useBodyScrollLock(open);
+  useOverlayHistory(open && backCloses, requestClose);
+
+  const dialogRef = useRef<HTMLDivElement>(null);
+  // The half of "modal" this dialog was only claiming. It has said
+  // `aria-modal="true"` since it was extracted from `data-table.tsx`, which tells
+  // assistive technology to hide everything outside it — while the user's focus stayed
+  // on the row they tapped, in the part that is now hidden. Tab then walked them
+  // through a table the screen reader would not describe, and on a phone this dialog
+  // covers the whole screen, so there was nothing on screen to say where they were.
+  //
+  // `initialFocus` is left at the default — the dialog itself, not the first field.
+  // This is the phone's row EDITOR and its first child is usually an input; focusing it
+  // would pull the software keyboard up over half the form before the user has said
+  // which field they came for. `Modal` made the same call for the same reason.
+  useFocusTrap(dialogRef, { active: open });
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== "Escape") return;
+    // On the panel, the way `Modal` does it, and NOT through `useEscapeKey`: this
+    // dialog is the thing a `PickerSheet` opens on top of, and a document-level
+    // listener cannot tell which of the two the user meant. One press would dismiss
+    // the sheet AND throw away the edit behind it — Keksdose live #309 (*"Mouse Back
+    // does not only close the select but also the whole edit or create dialog"*) on a
+    // different key. The sheet's own handler stops the event here, so the innermost
+    // overlay is the one that closes, which is only true because focus is now in it.
+    e.stopPropagation();
+    requestClose();
+  };
+
+  if (!open || typeof document === "undefined") return null;
+
+  return createPortal(
+    <div
+      // `animate-overlay` on the backdrop and `animate-sheet` on the panel (live #320):
+      // the backdrop fades, the panel rises from the bottom edge it is anchored to.
+      // Both are no-ops under prefers-reduced-motion — see tokens.css.
+      //
+      // …and the same two backwards while `closing`, which is the #320 rework. The
+      // backdrop keeps taking pointer events on the way out: a tap during those 220ms
+      // is a tap on a dialog that is leaving, and letting it through to the row
+      // underneath would open a second one.
+      //
+      // `...rest` first, the dialog's own contract after it. A caller adding a
+      // `data-tour` anchor must not be able to take away the role, the modality or the
+      // `tabIndex` below by passing one of them too — this is the element the focus
+      // trap holds, and each of those failures is invisible on screen.
+      {...rest}
+      className={cn(
+        "fixed inset-0 z-50 flex items-stretch justify-center bg-black/40 outline-none",
+        closing ? "animate-overlay-out" : "animate-overlay",
+      )}
+      role="dialog"
+      aria-modal="true"
+      // `tabIndex={-1}` is what makes the line above more than a claim: without it the
+      // container cannot take focus and `useFocusTrap` silently does nothing.
+      tabIndex={-1}
+      ref={dialogRef}
+      onKeyDown={handleKeyDown}
+      {...backdropClose}
+    >
+      <div
+        className={cn(
+          "flex h-full w-full flex-col overflow-hidden bg-[var(--bg-surface)] shadow-xl",
+          closing ? "animate-sheet-out" : "animate-sheet",
+          className,
+        )}
+      >
+        <div className="flex items-center justify-between gap-2 border-b border-[var(--border)] px-3 py-3">
+          <div className="min-w-0 font-medium">{header}</div>
+          <button
+            type="button"
+            onClick={requestClose}
+            aria-label={closeLabel}
+            className="-mr-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
+          >
+            <X className="size-5" />
+          </button>
+        </div>
+        {/* px-3, not px-4: every pixel of chrome here is width the form fields lose
+            on a phone (feedback #32). The body is the only thing that scrolls, so the
+            header stays put and the page underneath cannot move at all. */}
+        <div className="flex-1 overflow-y-auto overscroll-contain px-3 py-3">{children}</div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/src/components/grouped-picker.tsx

@@ -0,0 +1,157 @@
+import { useEffect, useMemo } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn";
+import { DropdownSearchHeader, useDropdownSearch } from "./dropdown";
+import { useKitLocale } from "../i18n/kit-labels";
+
+export interface PickerGroup {
+  key: string;
+  label: string;
+  /** `icon` is an optional leading glyph, drawn before the label — the same slot
+   *  `ComboOption` has always had, so the two pickers can present one option set
+   *  the same way. Omitted, a row is exactly what it was: label only, with no
+   *  reserved space, so a list where nothing has an icon does not indent. */
+  items: { key: string; label: string; icon?: ReactNode }[];
+}
+
+/**
+ * `onSelect` is omitted from the div's own attributes because this component's
+ * means "an item was chosen", not the DOM's "text was selected inside me" — two
+ * different signatures under one name, and the kit's meaning is the one three apps
+ * are written against.
+ */
+export interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
+  groups: PickerGroup[];
+  /** Face of the closed picker button. */
+  buttonLabel: ReactNode;
+  /** Keys of the current selection, if any. */
+  selected: { group: string; item: string } | null;
+  onSelect: (groupKey: string, itemKey: string) => void;
+  /**
+   * @deprecated Use `aria-label`, the DOM spelling every control in the kit now
+   * takes. Kept working — three apps pass it — and it applies only when
+   * `aria-label` is absent; it goes in a later minor.
+   */
+  ariaLabel?: string;
+  filterPlaceholder?: string;
+}
+
+/** Panel picker for large grouped option sets: instead of one long flat
+ * dropdown, the groups sit side by side as columns with their items listed
+ * beneath (feedback #267/#276), narrowed by a filter box at the top (feedback
+ * #267 rework). A query that matches a group's name keeps the whole group;
+ * otherwise groups are reduced to their matching items. */
+export function GroupedPicker({
+  groups,
+  buttonLabel,
+  selected,
+  onSelect,
+  ariaLabel,
+  "aria-label": ariaLabelAttr,
+  filterPlaceholder,
+  className,
+  ...rest
+}: GroupedPickerProps) {
+  const { open, setOpen, wrapperRef, query, setQuery, inputRef } = useDropdownSearch();
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, setOpen]);
+
+  // Case folding in the provider's locale — see `rowMatches` for the Turkish "İ"
+  // that plain `toLowerCase` gets wrong.
+  const locale = useKitLocale();
+  const filtered = useMemo(() => {
+    const fold = (s: string) => s.toLocaleLowerCase(locale);
+    const q = fold(query.trim());
+    if (!q) return groups;
+    return groups
+      .map((g) =>
+        fold(g.label).includes(q)
+          ? g
+          : { ...g, items: g.items.filter((i) => fold(i.label).includes(q)) },
+      )
+      .filter((g) => g.items.length > 0);
+  }, [groups, query, locale]);
+
+  return (
+    // `rest` goes on the wrapper, but the accessible NAME does not: this div is a
+    // positioning box with no role, so a label parked on it would be announced by
+    // nothing. It belongs to the control — the same split every picker in this wave
+    // makes, and the reason `aria-label` is destructured out rather than left in
+    // `rest`. Spread FIRST so the attributes below, each of them a fix with an
+    // incident behind it, cannot be clobbered from outside.
+    <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
+      <button
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={ariaLabelAttr ?? ariaLabel}
+        onClick={() => setOpen((o) => !o)}
+        className="flex w-full items-center justify-between gap-2 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] px-2.5 py-1.5 text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)]"
+      >
+        <span className="truncate">{buttonLabel}</span>
+        <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">
+          <DropdownSearchHeader
+            query={query}
+            onQueryChange={setQuery}
+            inputRef={inputRef}
+            placeholder={filterPlaceholder}
+          />
+          <div className="overflow-y-auto p-3">
+            {filtered.length === 0 ? (
+              <p className="text-sm text-[var(--text-muted)]">—</p>
+            ) : (
+              <div className="columns-2 gap-4 md:columns-3 xl:columns-4">
+                {filtered.map((g) => (
+                  <div key={g.key} className="mb-3 break-inside-avoid">
+                    <div className="mb-1 text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]">
+                      {g.label}
+                    </div>
+                    <ul className="space-y-0.5">
+                      {g.items.map((item) => {
+                        const isSelected =
+                          selected !== null &&
+                          g.key === selected.group &&
+                          item.key === selected.item;
+                        return (
+                          <li key={item.key}>
+                            <button
+                              type="button"
+                              onClick={() => {
+                                onSelect(g.key, item.key);
+                                setOpen(false);
+                              }}
+                              className={cn(
+                                "flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-left text-sm",
+                                isSelected
+                                  ? "bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)]"
+                                  : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
+                              )}
+                            >
+                              {item.icon && <span className="shrink-0">{item.icon}</span>}
+                              <span className="min-w-0 truncate">{item.label}</span>
+                            </button>
+                          </li>
+                        );
+                      })}
+                    </ul>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/hover-menu.tsx

@@ -0,0 +1,183 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useOutsideClick } from "../hooks/use-dismiss";
+
+/**
+ * Exported and `<div>`-shaped: the top bar composes several of these side by side, and
+ * telling them apart — in a test, in a guided tour, in an accessibility tree — needs an
+ * attribute the kit does not know about. A closed prop list dropped every one of them.
+ *
+ * `children` is omitted from the div attributes because here it is a render prop taking
+ * the panel's `close`, not a `ReactNode`.
+ */
+export interface HoverMenuProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  trigger: (state: { open: boolean; toggle: () => void }) => ReactNode;
+  children: (close: () => void) => ReactNode;
+  align?: "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
+   * 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.
+   */
+  ariaLabel?: string;
+}
+
+// Hovering waits briefly before opening so sweeping the cursor across a row of
+// triggers doesn't flash menus; closing waits so the cursor can travel from
+// trigger to panel. Click/keyboard toggling is instant (no "opening" phase).
+const OPEN_DELAY_MS = 120;
+const CLOSE_DELAY_MS = 120;
+
+type Phase = "closed" | "opening" | "open" | "closing";
+
+// 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.
+let activeClose: (() => void) | null = null;
+
+export function HoverMenu({
+  trigger,
+  children,
+  align = "right",
+  panelClassName,
+  className,
+  ariaLabel,
+  "aria-label": ariaLabelAttr,
+  ...rest
+}: HoverMenuProps) {
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const [phase, setPhase] = useState<Phase>("closed");
+  const open = phase === "open" || phase === "closing";
+
+  // Whether the panel is open *because hover opened it*, vs. an explicit
+  // click/keyboard toggle. A real mouse click on the trigger is always
+  // preceded by a real mouseenter — the cursor has to land on the button
+  // before it can be clicked — so once hover has opened the panel, the click
+  // that inevitably follows is the same physical gesture, not a request to
+  // close what was just opened (feedback #19). Toggling closed on click stays
+  // for keyboard/touch activation, which reaches "open" without going through
+  // the hover path.
+  const openedByHoverRef = useRef(false);
+
+  const close = useCallback(() => {
+    openedByHoverRef.current = false;
+    setPhase("closed");
+  }, []);
+
+  const toggle = useCallback(
+    () =>
+      setPhase((p) => {
+        if (p === "open" || p === "closing") return openedByHoverRef.current ? p : "closed";
+        openedByHoverRef.current = false;
+        return "open";
+      }),
+    [],
+  );
+
+  const handleMouseEnter = useCallback(
+    () => setPhase((p) => (p === "closing" ? "open" : p === "closed" ? "opening" : p)),
+    [],
+  );
+
+  const handleMouseLeave = useCallback(
+    () => setPhase((p) => (p === "opening" ? "closed" : p === "open" ? "closing" : p)),
+    [],
+  );
+
+  // Drive the delayed transitions; unmount/phase changes cancel the timer.
+  useEffect(() => {
+    if (phase === "opening") {
+      const id = setTimeout(() => {
+        openedByHoverRef.current = true;
+        setPhase("open");
+      }, OPEN_DELAY_MS);
+      return () => clearTimeout(id);
+    }
+    if (phase === "closing") {
+      const id = setTimeout(() => setPhase("closed"), CLOSE_DELAY_MS);
+      return () => clearTimeout(id);
+    }
+  }, [phase]);
+
+  // Claim the "active menu" slot while our panel is visible, closing the
+  // previous holder. Cleanup releases the slot only if we still hold it
+  // (a successor that displaced us has already overwritten it).
+  useEffect(() => {
+    if (!open) return;
+    if (activeClose !== close) activeClose?.();
+    activeClose = close;
+    return () => {
+      if (activeClose === close) activeClose = null;
+    };
+  }, [open, close]);
+
+  useOutsideClick(wrapperRef, close, open);
+
+  // 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
+  // just enough to sit within an 8px margin. Recomputed on each open; `shiftX` is
+  // subtracted first so the measurement is against the natural position.
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [shiftX, setShiftX] = useState(0);
+  useLayoutEffect(() => {
+    if (!open) {
+      setShiftX(0);
+      return;
+    }
+    const el = panelRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0) return; // unmeasured (e.g. jsdom) — leave as-is
+    const margin = 8;
+    const naturalLeft = rect.left - shiftX;
+    const naturalRight = rect.right - shiftX;
+    let next = 0;
+    if (naturalRight > window.innerWidth - margin) next = window.innerWidth - margin - naturalRight;
+    if (naturalLeft + next < margin) next = margin - naturalLeft;
+    setShiftX(next);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- recompute only on open/close
+  }, [open]);
+
+  return (
+    <div
+      // `...rest` first: the hover handlers below are the whole component, and a caller
+      // passing one of its own must not silently replace them.
+      {...rest}
+      ref={wrapperRef}
+      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}
+    >
+      {trigger({ open, toggle })}
+      {open && (
+        <div
+          ref={panelRef}
+          className={cn(
+            "absolute top-full z-40 pt-2",
+            align === "right" ? "right-0" : "left-0",
+          )}
+          style={shiftX ? { transform: `translateX(${shiftX}px)` } : undefined}
+        >
+          <div
+            role="menu"
+            className={cn(
+              "min-w-44 max-w-[calc(100vw-1rem)] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+              panelClassName,
+            )}
+          >
+            {children(close)}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}