@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/components/password-strength.tsx

@@ -1,8 +1,9 @@
 import { useEffect, useRef } from "react";
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithRef } from "react";
 import { cn } from "../lib/cn";
 import { useAnnounce } from "../hooks/use-announce";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_PASSWORD_STRENGTH_LABELS } from "./password-strength-labels";
 
 /**
  * The bar, the word and the advisory checklist under a field where someone is
@@ -117,23 +118,8 @@ export interface PasswordStrengthLabels {
   tooLong: (maxBytes: number) => string;
 }
 
-export const DEFAULT_PASSWORD_STRENGTH_LABELS: PasswordStrengthLabels = {
-  tooShort: "Too short",
-  weak: "Weak",
-  fair: "Fair",
-  good: "Good",
-  strong: "Strong",
-  announcement: (level) => `Password strength: ${level}`,
-  ruleLength: (minLength) => `At least ${minLength} characters`,
-  ruleCase: "Upper and lower case",
-  ruleDigit: "A number",
-  ruleSymbol: "A symbol",
-  optional: (rule) => `${rule} (optional)`,
-  met: "Met:",
-  notMet: "Not met:",
-  tooLong: (maxBytes) =>
-    `At most ${maxBytes} characters (accents and emoji count for more than one).`,
-};
+// Defined in ./password-strength-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_PASSWORD_STRENGTH_LABELS };
 
 const LEVEL_KEYS = ["tooShort", "weak", "fair", "good", "strong"] as const;
 
@@ -144,13 +130,13 @@ const LEVEL_KEYS = ["tooShort", "weak", "fair", "good", "strong"] as const;
 // segment count. Index 0 is never drawn — a too-short secret fills no segment.
 const FILL: Record<PasswordStrengthScore, string> = {
   0: "",
-  1: "bg-[var(--danger)]",
-  2: "bg-[var(--warning)]",
+  1: "bg-danger",
+  2: "bg-warning",
   3: "bg-[color-mix(in_oklab,var(--success)_60%,var(--warning))]",
-  4: "bg-[var(--success)]",
+  4: "bg-success",
 };
 
-export interface PasswordStrengthMeterProps extends ComponentPropsWithoutRef<"div"> {
+export interface PasswordStrengthMeterProps extends ComponentPropsWithRef<"div"> {
   /** The secret being chosen. Nothing visible renders while it is empty. */
   value: string;
   /** Replace the built-in scorer (e.g. with zxcvbn's `score`). Must be pure. */
@@ -167,7 +153,7 @@ export interface PasswordStrengthMeterProps extends ComponentPropsWithoutRef<"di
    */
   maxBytes?: number;
   /** User-facing strings; see {@link PasswordStrengthLabels}. */
-  labels?: Partial<PasswordStrengthLabels>;
+  labels?: LabelOverride<PasswordStrengthLabels>;
 }
 
 /**
@@ -229,7 +215,7 @@ export function PasswordStrengthMeter({
                 />
               ))}
             </div>
-            <p className="min-w-[4.5rem] text-end text-xs text-[var(--text-secondary)]">{level}</p>
+            <p className="min-w-[4.5rem] text-end text-xs text-secondary">{level}</p>
           </div>
           {showRequirements && (
             <ul className="flex flex-wrap gap-x-3 gap-y-0.5 text-xs">
@@ -239,7 +225,7 @@ export function PasswordStrengthMeter({
                   // `relative`: the sr-only state needs a local containing block.
                   className={cn(
                     "relative",
-                    r.met ? "text-[var(--success)]" : "text-[var(--text-muted)]",
+                    r.met ? "text-success" : "text-muted",
                   )}
                   data-met={r.met}
                 >
@@ -250,7 +236,7 @@ export function PasswordStrengthMeter({
               ))}
             </ul>
           )}
-          {tooLong && <p className="text-xs text-[var(--danger)]">{labels.tooLong(maxBytes)}</p>}
+          {tooLong && <p className="text-xs text-danger">{labels.tooLong(maxBytes)}</p>}
         </>
       )}
     </div>

package/src/components/phone-input-labels.ts

@@ -0,0 +1,10 @@
+// The English words of ./phone-input, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./phone-input re-exports them.
+
+import type { PhoneInputLabels } from "./phone-input";
+
+export const DEFAULT_PHONE_INPUT_LABELS: PhoneInputLabels = {
+  countryCode: "Country code",
+  other: "Other",
+};

package/src/components/phone-input.tsx

@@ -1,6 +1,6 @@
-import { forwardRef, useId, useState } from "react";
+import { useState } from "react";
 import type { ChangeEvent, FocusEvent } from "react";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { cn } from "../lib/cn";
 import {
   PHONE_COUNTRIES,
@@ -11,8 +11,10 @@ import {
   parsePhone,
 } from "../lib/phone";
 import type { ParsedPhone, PhoneCountry, PhoneCountryCode } from "../lib/phone";
-import { hasMessage, mergeDescribedBy } from "./choice-parts";
-import { Input, Select, type InputProps } from "./ui";
+import { useFieldMessages } from "./field-parts";
+import { Input, type InputProps } from "./input";
+import { Select } from "./select";
+import { DEFAULT_PHONE_INPUT_LABELS } from "./phone-input-labels";
 
 // ── Labels ────────────────────────────────────────────────────────────────────
 
@@ -25,10 +27,8 @@ export interface PhoneInputLabels {
   other: string;
 }
 
-export const DEFAULT_PHONE_INPUT_LABELS: PhoneInputLabels = {
-  countryCode: "Country code",
-  other: "Other",
-};
+// Defined in ./phone-input-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_PHONE_INPUT_LABELS };
 
 /**
  * The `phoneInput` namespace: prop > `<UiKitProvider labels>` > English (0.22.0).
@@ -40,14 +40,6 @@ function usePhoneInputLabels(prop: Partial<PhoneInputLabels> | undefined): Phone
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-/** The caption and the error under the row — the type every kit field uses for them
- *  (Select's caption, Input's `error`). */
-const CAPTION_CLASS = "mt-1 text-caption leading-tight text-[var(--text-muted)]";
-const ERROR_CLASS = "mt-1 text-caption leading-tight text-[var(--danger)]";
-
-const isTextHint = (hint: unknown): hint is string | number =>
-  (typeof hint === "string" && hint !== "") || typeof hint === "number";
-
 /** A stored value read back: an E.164 number these rules can read, else `null`. */
 function storedNumber(value: string): ParsedPhone | null {
   return isE164(value) ? parsePhone(value, "other") : null;
@@ -99,7 +91,7 @@ export interface PhoneInputProps extends Omit<InputProps, "type" | "value" | "de
    *  left out still shows under its own code. */
   countries?: readonly PhoneCountryCode[];
   /** See {@link PhoneInputLabels}. */
-  labels?: Partial<PhoneInputLabels>;
+  labels?: LabelOverride<PhoneInputLabels>;
   /** Classes for the whole field — the select, the input and the lines under them.
    *  `inputClassName` reaches the `<input>`. */
   className?: string;
@@ -143,27 +135,25 @@ export interface PhoneInputProps extends Omit<InputProps, "type" | "value" | "de
  * the number with `aria-describedby`. The select is named by `labels.countryCode`, and
  * the pair is a group named by a string `label`.
  */
-export const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(function PhoneInput(
-  {
-    value,
-    onValueChange,
-    onChange,
-    onBlur,
-    defaultCountry = "CH",
-    countries = PHONE_COUNTRIES,
-    labels,
-    className,
-    inputClassName,
-    label,
-    hint,
-    error,
-    invalid,
-    disabled,
-    "aria-describedby": ariaDescribedBy,
-    ...rest
-  },
+export function PhoneInput({
   ref,
-) {
+  value,
+  onValueChange,
+  onChange,
+  onBlur,
+  defaultCountry = "CH",
+  countries = PHONE_COUNTRIES,
+  labels,
+  className,
+  inputClassName,
+  label,
+  hint,
+  error,
+  invalid,
+  disabled,
+  "aria-describedby": ariaDescribedBy,
+  ...rest
+}: PhoneInputProps) {
   const text = usePhoneInputLabels(labels);
   const [country, setCountry] = useState<PhoneCountry>(() => countryOf(value) ?? defaultCountry);
   // What was typed, shown for as long as it still reads as the value (AmountInput's
@@ -230,10 +220,16 @@ export const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(function
   const options: PhoneCountryCode[] = [...countries];
   if (country !== "other" && !options.includes(country)) options.push(country);
 
-  const captionId = useId();
-  const errorId = useId();
-  const caption = isTextHint(hint);
-  const showError = hasMessage(error);
+  // A FieldHint "?" rides the number's label line; text — and a FieldHint at Large and
+  // on touch (§4) — goes under the whole row with the error. Through useFieldMessages
+  // since 0.34, not a copy of its rule (DUP-2, DUP-8).
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: ariaDescribedBy,
+    ariaInvalid: rest["aria-invalid"],
+  });
   const named = typeof label === "string" && label !== "";
 
   return (
@@ -273,10 +269,9 @@ export const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(function
             type="tel"
             autoComplete={rest.autoComplete ?? "tel"}
             label={label}
-            // A FieldHint "?" rides the label line; text goes under the whole row.
-            hint={caption ? undefined : hint}
-            invalid={invalid || showError}
-            aria-describedby={mergeDescribedBy(ariaDescribedBy, caption && captionId, showError && errorId)}
+            hint={messages.labelHint}
+            invalid={messages.isInvalid}
+            aria-describedby={messages.describedBy}
             disabled={disabled}
             value={display}
             onChange={handleChange}
@@ -288,17 +283,7 @@ export const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(function
           />
         </div>
       </div>
-      {caption && (
-        <p id={captionId} className={CAPTION_CLASS}>
-          {hint}
-        </p>
-      )}
-      {showError && (
-        <p id={errorId} className={ERROR_CLASS}>
-          {error}
-        </p>
-      )}
+      {messages.below}
     </div>
   );
-});
-PhoneInput.displayName = "PhoneInput";
+}

package/src/components/picker-sheet.tsx

@@ -1,13 +1,15 @@
-import { useRef } from "react";
+import { useMemo, useRef } from "react";
 import { createPortal } from "react-dom";
 import { X } from "lucide-react";
-import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, RefObject } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, Ref, RefObject } from "react";
 import { cn } from "../lib/cn";
+import { mergeRefs } from "./field-parts";
 import { CLIPS_ATTRIBUTE } from "../lib/clipping";
 import { DropdownSearchHeader } from "./dropdown";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { useFocusTrap } from "../hooks/use-focus-trap";
+import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { useVisualViewport } from "../hooks/use-anchored-panel";
 import { DEFAULT_PICKER_SHEET_LABELS, useKitLabels } from "../i18n/kit-labels";
 
@@ -27,10 +29,26 @@ export interface PickerSheetProps
   query: string;
   onQueryChange: (value: string) => void;
   searchPlaceholder?: string;
+  /** The search box's accessible name. Default: `searchPlaceholder` — a placeholder is
+   *  gone the moment a character is typed, and is no name to many readers at all. */
+  searchLabel?: string;
   inputRef?: RefObject<HTMLInputElement | null>;
   /** Default: `pickerSheet.close` from the {@link UiKitProvider}, else "Close". */
   closeLabel?: string;
+  /**
+   * The list's keyboard, on the search box — where focus is while the sheet is up:
+   * Up/Down/Home/End/Enter (round 0.34 Wave 2, BUG-5). `ComboboxPanel` passes its own;
+   * without it arrows and Enter in the sheet did nothing at all.
+   */
+  onSearchKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  /** The `role="listbox"` the search box filters, for its `aria-controls`. */
+  listboxId?: string;
+  /** The option the arrow keys are on, for the search box's `aria-activedescendant`. */
+  activeId?: string;
   children: ReactNode;
+  /** The sheet, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —
+   *  merged with the sheet's own ref, which its focus trap holds. */
+  ref?: Ref<HTMLDivElement>;
 }
 
 /**
@@ -63,12 +81,17 @@ export function PickerSheet({
   query,
   onQueryChange,
   searchPlaceholder,
+  searchLabel,
   inputRef,
   closeLabel,
+  onSearchKeyDown,
+  listboxId,
+  activeId,
   children,
   "aria-label": ariaLabel,
   className,
   style,
+  ref,
   ...rest
 }: PickerSheetProps) {
   // Every picker in the kit opens one of these on a phone, and most of them pass
@@ -107,6 +130,7 @@ export function PickerSheet({
   const searchRef = inputRef ?? ownRef;
 
   const sheetRef = useRef<HTMLDivElement>(null);
+  const setSheet = useMemo(() => mergeRefs(sheetRef, ref), [ref]);
   /**
    * The sheet said `aria-modal="true"` and then left focus on the field behind it, so
    * a screen reader was told to hide the page the user's cursor was still standing in
@@ -139,17 +163,16 @@ export function PickerSheet({
     initialFocus: () => searchRef.current,
   });
 
+  // The sheet is almost always the INNERMOST overlay — it opens from a field inside a
+  // `Modal` or a `FullBleedDialog`. It is a layer on the Escape stack (Wave 2, DUP-1),
+  // above the dialog, and takes the key on its own element: one press dismissing this
+  // list and the dialog underneath with it was Keksdose live #309 (*"Mouse Back does
+  // not only close the select but also the whole edit or create dialog which is
+  // cumbersome"*), which the Back gesture already learned, on the key a desktop user
+  // reaches for instead.
+  useDismissLayer(open, onClose);
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    if (e.key !== "Escape") return;
-    // The sheet is almost always the INNERMOST overlay — it opens from a field inside a
-    // `Modal` or a `FullBleedDialog`, both of which take Escape on their own panel. A
-    // React portal's events still travel up the React tree, so without stopping it here
-    // one press would dismiss this list and the dialog underneath with it: Keksdose
-    // live #309 (*"Mouse Back does not only close the select but also the whole edit or
-    // create dialog which is cumbersome"*), which the Back gesture already learned, on
-    // the key a desktop user reaches for instead.
-    e.stopPropagation();
-    onClose();
+    takeEscape(e);
   };
 
   if (!open || typeof document === "undefined") return null;
@@ -165,7 +188,7 @@ export function PickerSheet({
       // MERGED rather than won outright (see below), which is the one case where a
       // caller has something to add.
       {...rest}
-      ref={sheetRef}
+      ref={setSheet}
       role="dialog"
       aria-modal="true"
       // Without it the container cannot take focus, and `useFocusTrap` has nothing to
@@ -218,17 +241,17 @@ export function PickerSheet({
       // or a transition from outside has nothing to do with them. Without a visual
       // viewport to correct for this is character-for-character what the caller passed.
       style={vv ? { ...style, top: vv.top, height: vv.height, bottom: "auto" } : style}
-      className={cn("fixed inset-0 z-50 flex flex-col bg-[var(--bg-surface)] outline-none", className)}
+      className={cn("fixed inset-0 z-50 flex flex-col bg-surface outline-none", className)}
     >
-      <div className="flex items-center gap-2 border-b border-[var(--border)] px-3 py-2">
-        <span className="min-w-0 flex-1 truncate text-sm font-semibold text-[var(--text-primary)]">
+      <div className="flex items-center gap-2 border-b border-subtle px-3 py-2">
+        <span className="min-w-0 flex-1 truncate text-sm font-semibold text-primary">
           {title}
         </span>
         <button
           type="button"
           aria-label={labels.close}
           onClick={onClose}
-          className="rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)]"
+          className="rounded p-1.5 text-muted hover:bg-hover"
         >
           <X className="size-5" />
         </button>
@@ -238,6 +261,12 @@ export function PickerSheet({
         onQueryChange={onQueryChange}
         inputRef={searchRef}
         placeholder={searchPlaceholder}
+        aria-label={searchLabel ?? searchPlaceholder}
+        // Focus is in this box while the sheet is up, so this is where the list's keys
+        // land and what has to name the list and the row the arrows are on (BUG-5).
+        onKeyDown={onSearchKeyDown}
+        listboxId={listboxId}
+        activeId={activeId}
       />
       {/* min-h-0 so the LIST scrolls rather than the dialog growing past the
           viewport — a flex child defaults to min-height:auto. */}
@@ -256,5 +285,5 @@ export function PickerSheet({
  *  so a list is comfortable to hit with a thumb rather than merely legible. */
 export const SHEET_ROW_CLASS = cn(
   "flex min-h-11 w-full items-center gap-2 px-4 py-2 text-start text-base",
-  "text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+  "text-primary hover:bg-hover",
 );

package/src/components/pie-chart.tsx

@@ -8,12 +8,12 @@
 // ramp (`paletteFor`), so it re-skins with the palette like every other chart, and the
 // kit's own legends (`ToggleLegend`, `StaticLegend`).
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import type { ComponentProps, ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from "react";
+import type { ComponentProps, ComponentPropsWithRef, KeyboardEvent, ReactNode } from "react";
 import { Pie, PieChart as RechartsPieChart, Sector } from "recharts";
 import type { PieLabelRenderProps, PieSectorShapeProps } from "recharts";
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { paletteFor } from "../theme/chart-palette";
 import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from "./chart";
 import { DEFAULT_PIE_CHART_LABELS, type PieChartLabels } from "./pie-chart-labels";
@@ -44,7 +44,7 @@ export interface PieChartSlice {
  * Everything a `<div>` takes reaches the chart's root, so a test id or a `data-tour`
  * anchor can find it. `children` is the chart's own.
  */
-export interface PieChartProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+export interface PieChartProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
   data: readonly PieChartSlice[];
   /** `"donut"` (default) leaves a hole with the total in it; `"pie"` is the full disc. */
   variant?: "donut" | "pie";
@@ -99,7 +99,7 @@ export interface PieChartProps extends Omit<ComponentPropsWithoutRef<"div">, "ch
   empty?: ReactNode;
   /** BCP 47 tag for the numbers and percentages. Default: the provider's. */
   locale?: string;
-  labels?: Partial<PieChartLabels>;
+  labels?: LabelOverride<PieChartLabels>;
 }
 
 /** A slice as drawn: only the ones with a positive value, in `data` order. */
@@ -305,7 +305,7 @@ export function PieChart({
           onBlur={() => setFocused(undefined)}
           // CSS beats a presentation attribute, so this recolours the sector's own
           // stroke for as long as it has keyboard focus.
-          className="outline-none [&:focus-visible>path]:stroke-[var(--text-primary)]"
+          className="outline-none [&:focus-visible>path]:stroke-primary"
         >
           <Sector key={key ?? undefined} {...sector} />
         </g>
@@ -404,7 +404,7 @@ export function PieChart({
 
   const emptyBox = (
     <div
-      className={cn("flex items-center justify-center text-sm text-[var(--text-muted)]", box.className)}
+      className={cn("flex items-center justify-center text-sm text-muted", box.className)}
       style={box.style}
     >
       {empty ?? labels.empty}
@@ -456,14 +456,16 @@ export function PieChart({
               aria-hidden={focusedSlice ? true : undefined}
               className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center"
             >
-              <span className="max-w-[40%] truncate text-xs text-[var(--text-muted)]">
+              {/* The label wraps from Large up, inside the hole's 40 % (text size
+                  §10.17, round 0.34 T1: the sweep read "Spent in Sept…"). */}
+              <span className="max-w-[40%] truncate-until-large text-xs text-muted">
                 {focusedSlice ? focusedSlice.slice.label : (centerLabel ?? labels.total)}
               </span>
-              <span className="max-w-[40%] truncate text-lg font-semibold tabular-nums text-[var(--text-primary)]">
+              <span className="max-w-[40%] truncate text-lg font-semibold tabular-nums text-primary">
                 {focusedSlice ? formatValue(focusedSlice.value) : (centerValue ?? formatValue(total))}
               </span>
               {focusedSlice && (
-                <span className="text-xs tabular-nums text-[var(--text-muted)]">
+                <span className="text-xs tabular-nums text-muted">
                   {formatShare(focusedSlice.share)}
                 </span>
               )}

package/src/components/popover-labels.ts

@@ -0,0 +1,14 @@
+// The English words of ./popover, in a module with no component code: the English catalogue
+// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk
+// like the other languages (0.34, KS U8). ./popover re-exports them.
+
+import type { PopoverLabels } from "./popover";
+
+// 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 = {
+  // "Pop-up", not "Popover": the panel's accessible name is read to USERS, and
+  // "popover" is a developer's word for it (reported by keksdose, 0.5.0). Only a
+  // bare Popover falls back to this — the kit's own pickers name their panels.
+  panel: "Pop-up",
+};

package/src/components/popover.tsx

@@ -1,14 +1,16 @@
-import { useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, RefObject } from "react";
+import { useMemo, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, Ref, RefObject } from "react";
 import { createPortal } from "react-dom";
-import { useAnchoredPanel } from "../hooks/use-anchored-panel";
-import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
+import { anchoredInline, useAnchoredPanel, viewportSize } from "../hooks/use-anchored-panel";
+import { runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { lengthPx, useRemPx, type RemLength } from "../hooks/use-breakpoint";
 import { cn } from "../lib/cn";
 import { dirOf } from "../lib/direction";
 import type { Direction } from "../lib/direction";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_POPOVER_LABELS } from "./popover-labels";
+import { mergeRefs } from "./field-parts";
 
 /** 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
@@ -19,14 +21,8 @@ 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 = {
-  // "Pop-up", not "Popover": the panel's accessible name is read to USERS, and
-  // "popover" is a developer's word for it (reported by keksdose, 0.5.0). Only a
-  // bare Popover falls back to this — the kit's own pickers name their panels.
-  panel: "Pop-up",
-};
+// Defined in ./popover-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_POPOVER_LABELS };
 
 /**
  * Exported, and extending the `<div>` attributes, so a consumer wrapping this — which is
@@ -48,13 +44,17 @@ export interface PopoverProps extends Omit<ComponentPropsWithoutRef<"div">, "chi
    * 432 px at Extra large, more than a 360 px phone has.
    */
   width?: number | RemLength;
-  labels?: Partial<PopoverLabels>;
+  labels?: LabelOverride<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;
+  /** The PANEL, while it is open — where the rest of the props go (0.34, API-2, refactor
+   *  audit 2026-10). Merged with the panel's own ref (focus trap, outside click), so
+   *  neither loses it. The trigger is the caller's own element, ref and all. */
+  ref?: Ref<HTMLDivElement>;
 }
 
 /** 288 px at Normal, in rem so it follows the text size (§3.2). */
@@ -111,10 +111,12 @@ export function Popover({
   style,
   "aria-label": ariaLabel,
   onKeyDown: onKeyDownProp,
+  ref,
   ...rest
 }: PopoverProps) {
   const triggerRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
+  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [ref]);
   const [open, setOpen] = useState(false);
   // The trigger's reading direction, read when it is pressed. The panel is portalled to
   // <body>, out of any `dir="rtl"` subtree the trigger sits in, so without carrying it
@@ -137,23 +139,27 @@ export function Popover({
   // of the screen (feedback #135). It re-measures on scroll/resize.
   const placement = useAnchoredPanel(triggerRef, open);
   const rect = placement.rect;
-  // In px for the arithmetic below, at the text size in force; capped at the viewport.
+  // In px for the arithmetic below, at the text size in force; capped at the glass — the
+  // root's client width, not `innerWidth`, which on a phone is the layout viewport grown
+  // by whatever overflows (live #381, Wave 2 DUP-7).
   const remPx = useRemPx();
-  const panelWidth = rect
-    ? Math.min(lengthPx(width, remPx), Math.max(0, window.innerWidth - 2 * EDGE))
-    : 0;
+  const glass = rect ? viewportSize().width : 0;
+  const panelWidth = rect ? Math.min(lengthPx(width, remPx), Math.max(0, glass - 2 * EDGE)) : 0;
   const pos = rect
     ? {
-        top: placement.top,
-        left: Math.min(
-          Math.max(EDGE, dir === "rtl" ? rect.left : rect.right - panelWidth),
-          window.innerWidth - panelWidth - EDGE,
-        ),
+        // Flipped above, the panel hangs from its bottom edge, so one shorter than its
+        // cap still meets the trigger (keksdose K1); the edge not in use is cleared.
+        top: placement.above ? undefined : placement.top,
+        bottom: placement.above ? placement.bottom : undefined,
+        left: anchoredInline(rect, panelWidth, { dir, align: "end", edge: EDGE, viewportWidth: glass }).left,
       }
     : null;
 
   useOutsideClick([triggerRef, panelRef], close, open);
-  useEscapeKey(close, open);
+  // A layer on the Escape stack while open (Wave 2, DUP-1): a list opened inside closes
+  // first, and the dialog this popover sits in only after it — the calculator on an
+  // amount field in a Modal is exactly that.
+  useDismissLayer(open, close);
 
   useFocusTrap(panelRef, {
     active: open && pos !== null,
@@ -171,18 +177,12 @@ export function Popover({
 
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     // A caller's own handler first (0.32.2: RowActions stops Enter / Space at the panel);
-    // it used to be dropped, overwritten by this one.
-    onKeyDownProp?.(e);
-    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();
+    // it used to be dropped, overwritten by this one. A `preventDefault()` on Escape
+    // there keeps the popover open — the owner's claim, as on the dialogs.
+    runOwnKeyDown(e, onKeyDownProp);
+    // Focus is in here, the normal case: the key is handed to the top layer and STOPPED,
+    // so it does not travel on up the React tree to a dialog around the popover.
+    takeEscape(e);
   };
 
   return (
@@ -199,7 +199,7 @@ export function Popover({
             // 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}
+            ref={setPanel}
             role="dialog"
             id={panelId}
             // The caller's own `aria-label` wins over {@link PopoverLabels.panel}, which
@@ -213,18 +213,19 @@ export function Popover({
             tabIndex={-1}
             onKeyDown={handleKeyDown}
             style={{
-              // Merged over the caller's, never replaced by it: these four are measured
+              // Merged over the caller's, never replaced by it: these 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,
+              bottom: pos.bottom,
               left: pos.left,
               width: panelWidth,
               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",
+              "z-50 overflow-y-auto rounded-md border border-subtle bg-surface p-3 shadow-lg outline-none",
               className,
             )}
           >