@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/components/popover.tsx

@@ -0,0 +1,195 @@
+import { useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, RefObject } from "react";
+import { createPortal } from "react-dom";
+import { useAnchoredPanel } from "../hooks/use-anchored-panel";
+import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
+import { useFocusTrap } from "../hooks/use-focus-trap";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+
+/** The panel's accessible name. A `role="dialog"` with no name announces as "dialog"
+ *  and nothing else, which is worse than the unlabelled div it replaced — so it is a
+ *  prop with an English default, like every other string this package renders. Callers
+ *  should pass the control's own name ("Filter", "Choose a date"); the default is only
+ *  there so an unmigrated call site is still named. */
+export interface PopoverLabels {
+  panel: string;
+}
+
+// Exported since the kit grew one label tree (`UiKitLabels`, src/i18n): the complete
+// English reference a translator works from has to be able to name every namespace.
+export const DEFAULT_POPOVER_LABELS: PopoverLabels = {
+  panel: "Popover",
+};
+
+/**
+ * Exported, and extending the `<div>` attributes, so a consumer wrapping this — which is
+ * what `DateField` and `FilterPopover` in this very package do — can hand anything
+ * through to the PANEL: a `data-tour` anchor for the kit's own guided tour, a test id,
+ * an `aria-describedby`, or an `aria-label` naming this particular popover.
+ *
+ * `children` is omitted from those attributes rather than inherited: here it is a render
+ * prop taking the panel's `close`, not a `ReactNode`, so the two cannot be reconciled.
+ */
+export interface PopoverProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  trigger: (state: { open: boolean; toggle: () => void; ref: RefObject<HTMLButtonElement | null> }) => ReactNode;
+  children: (close: () => void) => ReactNode;
+  width?: number;
+  labels?: Partial<PopoverLabels>;
+  /** Id for the panel, so a trigger wearing `role="combobox"` can `aria-controls` it.
+   *  Required by ARIA on that role, and the panel is rendered here rather than by the
+   *  caller, so the id has to come in from outside. */
+  panelId?: string;
+  /** Extra classes for the PANEL. The trigger is the caller's own element. */
+  className?: string;
+}
+
+const POPOVER_WIDTH = 288;
+
+/**
+ * Portal-rendered popover anchored under its trigger button. The panel is fixed
+ * to the viewport (so table/overflow ancestors can't clip it) and re-aligns on
+ * scroll/resize; it closes on outside-click and Escape.
+ *
+ * ## Trapped, not merely focused — and why, because it is the closer call
+ *
+ * The audit's finding was that this panel *"portals out of the tab order with no role
+ * and no focus move"*: Tab from the trigger went straight past the panel into the page
+ * behind it, so the calendar, the calculator keypad and every column filter in the kit
+ * were mouse-only. Two shapes fix that, and a popover is not automatically a dialog, so
+ * this was chosen rather than inherited:
+ *
+ *  - **The light one** — move focus in on open, hand it back on close, and let Tab walk
+ *    OUT of the panel into whatever follows the trigger. That is the right shape for a
+ *    non-modal popover sitting inline in the document.
+ *  - **The trap** — Tab cycles inside the panel; Escape and a click outside are the
+ *    ways out. What is here.
+ *
+ * The deciding fact is the portal. This panel is rendered to the END of `<body>`, not
+ * beside its trigger, so "let Tab walk out" does not mean "carry on from the trigger" —
+ * it means land at the end of the document, several hundred controls from where the
+ * user was. Tabbing out of it would be a worse place to arrive than the one the finding
+ * complains about, and fixing that properly needs a sentinel-and-return dance that
+ * nothing in this package has. The trap gets the user back to the trigger every time,
+ * because `useFocusTrap` restores focus on close.
+ *
+ * And the panels this kit actually opens are self-contained: pick a date, tap out a
+ * sum, narrow a column. Each of them commits and closes, and each already has two
+ * documented ways out wired above — Escape and an outside press — so containment costs
+ * a keyboard user nothing they had.
+ *
+ * **It stays non-modal in every other respect**, deliberately: no backdrop, no body
+ * scroll lock, and no `aria-modal`, so the page behind is still readable by a screen
+ * reader, still scrollable, and still clickable — clicking it is what dismisses this.
+ * Only Tab is contained. A popover that took the page away as well would be a
+ * {@link Modal}, and there is one of those.
+ */
+export function Popover({
+  trigger,
+  children,
+  width = POPOVER_WIDTH,
+  labels,
+  panelId,
+  className,
+  style,
+  "aria-label": ariaLabel,
+  ...rest
+}: PopoverProps) {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState(false);
+  const close = () => setOpen(false);
+  const toggle = () => setOpen((v) => !v);
+  // prop > `<UiKitProvider labels={{ popover }}>` > English. The provider's
+  // `popover.panel` is only the last-resort name for a panel no caller named.
+  const text = useKitLabels("popover", DEFAULT_POPOVER_LABELS, labels);
+
+  // Align the panel's right edge to the trigger's and clamp it horizontally; the
+  // hook owns the vertical half — below by default, flipped above (and height-capped)
+  // when that is where the room is, e.g. once a mobile keyboard has eaten the bottom
+  // of the screen (feedback #135). It re-measures on scroll/resize.
+  const placement = useAnchoredPanel(triggerRef, open);
+  const rect = placement.rect;
+  const pos = rect
+    ? {
+        top: placement.top,
+        left: Math.min(Math.max(8, rect.right - width), window.innerWidth - width - 8),
+      }
+    : null;
+
+  useOutsideClick([triggerRef, panelRef], close, open);
+  useEscapeKey(close, open);
+
+  useFocusTrap(panelRef, {
+    active: open && pos !== null,
+    // The panel keeps a focus one of its own children has already taken. `FilterPopover`
+    // autofocuses its text box on mount — that is what the press on "Filter" was FOR,
+    // and it is a prop there precisely so the popover keeps it — and a trap that
+    // unconditionally focused the container would take it straight back off again,
+    // one effect later and invisibly.
+    initialFocus: () => {
+      const panel = panelRef.current;
+      const active = document.activeElement;
+      return panel?.contains(active) ? (active as HTMLElement) : panel;
+    },
+  });
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== "Escape") return;
+    // `useEscapeKey` above listens on the document and still covers the case where
+    // focus somehow is not in here. This handler is for the case that focus IS, which
+    // is now the normal one — and it exists to STOP the key, because a popover opened
+    // from inside a `Modal` (the calculator on an amount field is exactly that) would
+    // otherwise have its Escape travel on up the React tree and close the dialog
+    // underneath as well. Closing twice is harmless — `close` is a state setter, not a
+    // caller's callback — so the two paths cannot double-fire anything.
+    e.stopPropagation();
+    close();
+  };
+
+  return (
+    <>
+      {trigger({ open, toggle, ref: triggerRef })}
+      {open && pos &&
+        createPortal(
+          <div
+            // `...rest` first: the role, the id the trigger's `aria-controls` points at,
+            // the `tabIndex` the trap needs and the measured position are what make this
+            // a popover, and a caller reaching for a `data-tour` anchor must not be able
+            // to remove one of them by accident.
+            {...rest}
+            ref={panelRef}
+            role="dialog"
+            id={panelId}
+            // The caller's own `aria-label` wins over {@link PopoverLabels.panel}, which
+            // is the package's English fallback for an unnamed panel. Both name the same
+            // element; the DOM spelling is the one being standardised on, so where both
+            // are present it is the one that survives.
+            aria-label={ariaLabel ?? text.panel}
+            // Without it the panel cannot take focus at all, and the trap above would
+            // silently do nothing on a panel whose children are not yet tabbable.
+            tabIndex={-1}
+            onKeyDown={handleKeyDown}
+            style={{
+              // Merged over the caller's, never replaced by it: these four are measured
+              // against the trigger every scroll and resize, and a panel that dropped
+              // them would paint at the top-left of the viewport.
+              ...style,
+              position: "fixed",
+              top: pos.top,
+              left: pos.left,
+              width,
+              maxHeight: placement.maxHeight,
+            }}
+            className={cn(
+              "z-50 overflow-y-auto rounded-md border border-[var(--border)] bg-[var(--bg-surface)] p-3 shadow-lg outline-none",
+              className,
+            )}
+          >
+            {children(close)}
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}

package/src/components/search-field.tsx

@@ -0,0 +1,146 @@
+import { forwardRef, useRef } from "react";
+import type { InputHTMLAttributes } from "react";
+import { Search, X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { FIELD_BASE } from "./ui";
+
+interface SearchFieldOwnProps
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "value" | "onChange" | "type" | "aria-label"
+  > {
+  value: string;
+  /** The typed text. Emitted as a plain string, not an event: every caller of the
+   *  four this replaced wanted the string, and one of them held it in a URL param
+   *  rather than in state. */
+  onChange: (value: string) => void;
+  /**
+   * The field's accessible name.
+   *
+   * @deprecated Pass `aria-label` instead — the DOM spelling this kit standardised on
+   * when it found three names for one idea (`ariaLabel`, `aria-label`, and this).
+   * Unchanged and still supported; it names the field only when `aria-label` is
+   * absent, so a consumer can migrate one call site at a time.
+   */
+  label?: string;
+  /** Names the clear button. Omit it and no clear button is rendered — which is a
+   *  decision, not a default: a filter you can type into and not untype is the
+   *  complaint that produced the button on three of these four screens. */
+  clearLabel?: string;
+}
+
+/**
+ * One of the two spellings is REQUIRED, and the union is how that survives the
+ * deprecation. Making `label` merely optional would have been the easy change and the
+ * wrong one: the whole reason this component exists is that two of the four boxes it
+ * replaced were named by nothing but their placeholder — which disappears the moment
+ * someone types, i.e. exactly when a screen-reader user is working in the field. A
+ * caller now has a choice of spelling; it still has no option to pass neither.
+ */
+export type SearchFieldProps = SearchFieldOwnProps &
+  ({ "aria-label": string; label?: string } | { label: string; "aria-label"?: string });
+
+/**
+ * The page-level filter box: a search icon, a `type="search"` input, and a clear
+ * "×" that appears once there is something to clear.
+ *
+ * ## Why it is a component
+ *
+ * Keksdose had four of these and no two agreed. Two were character-identical
+ * twenty-line copies (the settings catalogue filter and the tour list filter) —
+ * the same absolute icon at `left-3`, the same `pl-9 pr-9`, the same
+ * `[&::-webkit-search-cancel-button]:appearance-none`, the same conditional clear
+ * button at `right-2` — differing only in which state setter they called. The
+ * third (the admin support queue) was the same idea at `left-2`/`size-3.5`/`pl-7`
+ * with no clear button and no `type="search"`, so it had neither the `searchbox`
+ * role nor a way to empty itself. The fourth (the bank picker) was a bare `<Input
+ * placeholder="Search">`: no icon, no clear, and no accessible name at all once
+ * the placeholder went away.
+ *
+ * None of that is a design decision anyone made; it is four people solving the
+ * same problem on four days. A shared component is how the fourth screen gets the
+ * clear button the first one earned.
+ *
+ * ## The two X's
+ *
+ * `type="search"` is what gives the field its `searchbox` role — and, in Chrome, a
+ * NATIVE clear cross that paints right next to ours, so a non-empty box shows two
+ * X's an inch apart. Ours is the one that survives: it carries an accessible name
+ * and matches the app's other icon buttons, and it returns focus to the input so
+ * the next query can be typed straight away.
+ */
+export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(function SearchField(
+  { value, onChange, label, clearLabel, className, placeholder, "aria-label": ariaLabel, ...rest },
+  ref,
+) {
+  const innerRef = useRef<HTMLInputElement>(null);
+  // Whichever spelling the caller used. It is the accessible name AND the placeholder
+  // fallback, so a box named only by `aria-label` still says what it is before anyone
+  // has typed in it — the same deal `label` has always had.
+  const name = ariaLabel ?? label;
+  return (
+    <div className={cn("relative", className)}>
+      <Search
+        aria-hidden
+        className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]"
+      />
+      <input
+        ref={(node) => {
+          innerRef.current = node;
+          if (typeof ref === "function") ref(node);
+          else if (ref) ref.current = node;
+        }}
+        type="search"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        aria-label={name}
+        placeholder={placeholder ?? name}
+        // Keksdose live #333: *"Entering the search here — is that set as password?
+        // … I got prompted for remembering my name or mail address"*, typed into the
+        // settings filter on a phone.
+        //
+        // A `type="search"` input with no `name` and no `autocomplete` is a field
+        // Chrome's autofill classifies by GUESSWORK, from the labels around it and
+        // the other fields on the page — and a settings page has an email and a
+        // password on it. Naming the field and declaring the intent is what takes it
+        // out of that guess: `autocomplete="off"` says it is not part of any profile,
+        // and a `name` of "search" is the strongest hint the heuristics take.
+        //
+        // The three that follow are not about autofill but about the same keyboard:
+        // a filter box that capitalises the first letter and autocorrects "2fa" to
+        // "2FA" is fighting the person typing into it. Declared BEFORE `{...rest}` so
+        // a caller with a reason can still override any of them.
+        name="search"
+        autoComplete="off"
+        autoCapitalize="none"
+        autoCorrect="off"
+        spellCheck={false}
+        {...rest}
+        className={cn(
+          FIELD_BASE,
+          "pl-9",
+          // Room for our own "×" only when there is one; a field that can't be
+          // cleared has no reason to reserve the space.
+          clearLabel === undefined ? "pr-3" : "pr-9",
+          "[&::-webkit-search-cancel-button]:appearance-none",
+        )}
+      />
+      {clearLabel !== undefined && value !== "" && (
+        <button
+          type="button"
+          onClick={() => {
+            onChange("");
+            // Clearing is the start of the next query far more often than it is the
+            // end of this one, so the caret stays where it can be typed into.
+            innerRef.current?.focus();
+          }}
+          aria-label={clearLabel}
+          className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-1 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+        >
+          <X className="size-4" />
+        </button>
+      )}
+    </div>
+  );
+});
+SearchField.displayName = "SearchField";

package/src/components/series-chart-labels.ts

@@ -0,0 +1,26 @@
+// All user-facing strings for the series chart family — `SeriesChart`, its drag-to-zoom
+// layer and `ToggleLegend` — as the `seriesChart` namespace of `<UiKitProvider labels>`,
+// and per chart the `labels` prop over that.
+//
+// A module of its own, with no recharts in it, so the label registry (src/i18n) can
+// import the defaults without pulling the chart library in behind them.
+
+export interface SeriesChartLabels {
+  /** The button that puts a zoomed chart back to its full extent. Visible text. */
+  resetZoom: string;
+  /** Accessible name of the drag surface laid over the plot. It is the only place the
+   *  gesture is explained, so it says how the drag is read and how to undo it. */
+  zoomHint: string;
+  /** What a chart with nothing to draw says, when the caller passes no `empty`. */
+  empty: string;
+  /** Accessible name of a `ToggleLegend` — a group of switches, one per series. */
+  legend: string;
+}
+
+export const DEFAULT_SERIES_CHART_LABELS: SeriesChartLabels = {
+  resetZoom: "Reset zoom",
+  zoomHint:
+    "Drag to zoom: a roughly square selection zooms both axes, a long thin one only its own. Double-click to reset.",
+  empty: "No data",
+  legend: "Series",
+};