@eifi1/ui-kit 0.33.1 → 0.34.0

package/src/feedback/feedback-thread-labels.ts

@@ -0,0 +1,22 @@
+// The English words of ./feedback-thread, 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). ./feedback-thread re-exports them.
+
+import type { FeedbackComposerLabels, FeedbackThreadLabels } from "./feedback-thread";
+
+export const DEFAULT_FEEDBACK_THREAD_LABELS: FeedbackThreadLabels = {
+  thread: "Comments",
+  empty: "No comments yet",
+  loading: "Loading comments…",
+  you: "You",
+  staff: "Staff",
+  attachments: "Attachments",
+};
+
+export const DEFAULT_FEEDBACK_COMPOSER_LABELS: FeedbackComposerLabels = {
+  field: "Write a comment",
+  placeholder: "Write a comment…",
+  send: "Send",
+  sendHint: (modifier) => `${modifier} + Enter to send`,
+  sendHintEnter: "Enter to send, Shift + Enter for a new line",
+};

package/src/feedback/feedback-thread.tsx

@@ -3,17 +3,25 @@ import type { ReactNode, Ref, RefObject } from "react";
 import { ImageIcon, ImageOff, Paperclip, Send } from "lucide-react";
 import { cn } from "../lib/cn";
 import { formatDate, formatRelativeTime } from "../lib/format";
-import { Button, EmptyState, Spinner, Textarea } from "../components/ui";
-import type { CharacterCountLabels } from "../components/ui";
+import { hasContent } from "../lib/presence";
+import { Button } from "../components/button";
+import { EmptyState } from "../components/empty-state";
+import { Spinner } from "../components/spinner";
+import { Textarea } from "../components/textarea";
+import type { CharacterCountLabels } from "../components/field-base";
 import { Skeleton } from "../components/skeleton";
 import { Tooltip } from "../components/tooltip";
 import { useWriteLock } from "../components/write-lock";
 import type { CommitScope } from "../components/write-lock";
-import { useKitFileLabels, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitFileLabels, useKitLabels, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { FeedbackAttachmentField } from "./feedback-attachment";
 import type { FeedbackAttachmentFieldSingleProps } from "./feedback-attachment";
 import type { FeedbackNoteAttachment } from "./feedback-inbox";
 import type { FeedbackAttachmentLabels } from "./feedback-dialog";
+import {
+  DEFAULT_FEEDBACK_COMPOSER_LABELS,
+  DEFAULT_FEEDBACK_THREAD_LABELS,
+} from "./feedback-thread-labels";
 
 /**
  * The conversation under a report: who said what, when, with what attached — and the
@@ -64,14 +72,8 @@ export interface FeedbackThreadLabels {
   attachments: string;
 }
 
-export const DEFAULT_FEEDBACK_THREAD_LABELS: FeedbackThreadLabels = {
-  thread: "Comments",
-  empty: "No comments yet",
-  loading: "Loading comments…",
-  you: "You",
-  staff: "Staff",
-  attachments: "Attachments",
-};
+// Defined in ./feedback-thread-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_FEEDBACK_THREAD_LABELS };
 
 /** The `feedbackComposer` namespace of `<UiKitProvider labels>`. The attach buttons'
  *  words are `feedbackAttachment`'s, shared with the dialog and the note editor. */
@@ -87,13 +89,8 @@ export interface FeedbackComposerLabels {
   sendHintEnter: string;
 }
 
-export const DEFAULT_FEEDBACK_COMPOSER_LABELS: FeedbackComposerLabels = {
-  field: "Write a comment",
-  placeholder: "Write a comment…",
-  send: "Send",
-  sendHint: (modifier) => `${modifier} + Enter to send`,
-  sendHintEnter: "Enter to send, Shift + Enter for a new line",
-};
+// Defined in ./feedback-thread-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_FEEDBACK_COMPOSER_LABELS };
 
 /* ── Thread ───────────────────────────────────────────────────────────────── */
 
@@ -183,7 +180,7 @@ export interface FeedbackThreadProps {
   now?: Date | number;
   /** Overrides the provider's locale for the times. */
   locale?: string;
-  labels?: Partial<FeedbackThreadLabels>;
+  labels?: LabelOverride<FeedbackThreadLabels>;
   className?: string;
 }
 
@@ -264,7 +261,7 @@ export function FeedbackThread({
             <li
               key={message.id}
               data-event=""
-              className="flex flex-wrap items-baseline justify-center gap-x-2 px-4 text-center text-xs text-[var(--text-muted)]"
+              className="flex flex-wrap items-baseline justify-center gap-x-2 px-4 text-center text-xs text-muted"
             >
               <span>{message.body}</span>
               {time && <span className="text-caption">{time}</span>}
@@ -284,18 +281,18 @@ export function FeedbackThread({
               className={cn(
                 "max-w-[85%] min-w-0 rounded-lg px-3 py-2 text-sm",
                 message.own
-                  ? "rounded-ee-sm bg-[var(--brand-bg)]"
-                  : "rounded-es-sm bg-[var(--bg-surface-2)]",
+                  ? "rounded-ee-sm bg-brand-soft"
+                  : "rounded-es-sm bg-surface-2",
               )}
             >
-              <header className="mb-0.5 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-caption text-[var(--text-muted)]">
+              <header className="mb-0.5 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-caption text-muted">
                 {author != null && (
-                  <span data-private={priv} className="font-medium text-[var(--text-secondary)]">
+                  <span data-private={priv} className="font-medium text-secondary">
                     {author}
                   </span>
                 )}
                 {message.staff && (
-                  <span className="rounded border border-[var(--border)] bg-[var(--bg-surface)] px-1 text-micro font-medium uppercase tracking-wide text-[var(--text-secondary)]">
+                  <span className="rounded border border-subtle bg-surface px-1 text-micro font-medium uppercase tracking-wide text-secondary">
                     {labels.staff}
                   </span>
                 )}
@@ -305,7 +302,7 @@ export function FeedbackThread({
                 <p
                   data-private={priv}
                   dir="auto"
-                  className="whitespace-pre-wrap break-words text-start text-[var(--text-primary)]"
+                  className="whitespace-pre-wrap break-words text-start text-primary"
                 >
                   {message.body}
                 </p>
@@ -344,16 +341,18 @@ function DefaultAttachment({
   const content = (
     <>
       <Paperclip className="size-3.5 shrink-0" aria-hidden />
-      <span className="truncate">{name}</span>
+      {/* A file name wraps from Large up, as the attachments of the composer do (text
+          size §10.17; round 0.34 T1: the sweep read "export-20…"). */}
+      <span className="min-w-0 truncate-until-large">{name}</span>
       {attachment.size !== undefined && (
-        <span className="shrink-0 text-[var(--text-muted)]">{size(attachment.size)}</span>
+        <span className="shrink-0 text-muted">{size(attachment.size)}</span>
       )}
     </>
   );
   const chip =
-    "inline-flex max-w-full items-center gap-1 rounded border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 text-xs text-[var(--text-secondary)]";
+    "inline-flex max-w-full items-center gap-1 rounded border border-subtle bg-surface px-2 py-1 text-xs text-secondary";
   return url ? (
-    <a href={url} target="_blank" rel="noopener noreferrer" className={cn(chip, "hover:bg-[var(--bg-hover)]")}>
+    <a href={url} target="_blank" rel="noopener noreferrer" className={cn(chip, "hover:bg-hover")}>
       {content}
     </a>
   ) : (
@@ -376,9 +375,9 @@ function ImageThumbnail({ url, name }: { url: string; name: string }) {
       href={url}
       target="_blank"
       rel="noopener noreferrer"
-      className="relative block h-20 w-20 overflow-hidden rounded border border-[var(--border)] bg-[var(--bg-surface-2)]"
+      className="relative block h-20 w-20 overflow-hidden rounded border border-subtle bg-surface-2"
     >
-      <Glyph aria-hidden className="absolute inset-0 m-auto size-6 text-[var(--text-muted)]" />
+      <Glyph aria-hidden className="absolute inset-0 m-auto size-6 text-muted" />
       {!failed && (
         // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- load/error are resource events, not interactions
         <img
@@ -449,7 +448,7 @@ function DaySeparator({ date, now, locale }: { date: Date; now: number; locale:
   const m = String(date.getMonth() + 1).padStart(2, "0");
   const d = String(date.getDate()).padStart(2, "0");
   return (
-    <li data-day-separator="" className="flex items-center gap-3 py-1 text-xs text-[var(--text-muted)]">
+    <li data-day-separator="" className="flex items-center gap-3 py-1 text-xs text-muted">
       <span aria-hidden className="h-px flex-1 bg-[var(--border)]" />
       <time dateTime={`${y}-${m}-${d}`} className="font-medium">
         {label}
@@ -473,7 +472,7 @@ function toDate(value: Date | string | number): Date | null {
  *  0.24.0 also the field's `buttonVariant` / `buttonSize`, for a composer whose row
  *  wants smaller or quieter attach buttons than the bordered `md` default. */
 export type FeedbackComposerAttachment = Omit<FeedbackNoteAttachment, "labels" | "onError"> & {
-  labels?: Partial<FeedbackAttachmentLabels>;
+  labels?: LabelOverride<FeedbackAttachmentLabels>;
   onError?: FeedbackAttachmentFieldSingleProps["onError"];
 } & Pick<FeedbackAttachmentFieldSingleProps, "buttonVariant" | "buttonSize">;
 
@@ -625,7 +624,7 @@ export interface FeedbackComposerProps {
   /** {@link FeedbackComposerHandle}: put text into the draft from outside (canned-reply
    *  chips) or focus the box. */
   ref?: Ref<FeedbackComposerHandle>;
-  labels?: Partial<FeedbackComposerLabels>;
+  labels?: LabelOverride<FeedbackComposerLabels>;
   className?: string;
   /**
    * `"sm"` for a narrow host — keksdose's assistant launcher, a small floating panel
@@ -676,8 +675,13 @@ const isApple = () =>
  * and Send — Ctrl/⌘+Enter sends, the shortcut the report dialog and the note editor
  * use, so the habit carries across the feature. Plain Enter is a new line: feedback is
  * written in paragraphs, unlike a chat — which `sendOn="enter"` is for (keksdose G5).
+ *
+ * Named for what it is since 0.22 (keksdose K17): the component was never
+ * feedback-specific — a textarea, an optional picture or a host's upload slot, Send,
+ * `sendOn="enter"` for the chat way — and keksdose's assistant and support chat are
+ * chats, not reports. `FeedbackComposer` is its old name, deprecated in 0.34.
  */
-export function FeedbackComposer({
+export function ChatComposer({
   onSend,
   pending = false,
   attachment,
@@ -759,9 +763,10 @@ export function FeedbackComposer({
     () => "Ctrl",
   );
 
-  if (disabledReason != null && disabledReason !== false) {
+  // The kit's one presence rule (DUP-11): `""` is no reason either, so it keeps the box.
+  if (hasContent(disabledReason)) {
     return (
-      <p {...rootAttributes} className={cn("text-xs text-[var(--text-muted)]", className)}>
+      <p {...rootAttributes} className={cn("text-xs text-muted", className)}>
         {disabledReason}
       </p>
     );
@@ -855,7 +860,7 @@ export function FeedbackComposer({
         <div className="ms-auto flex items-center gap-2">
           <span
             id={hintId}
-            className={size === "sm" ? "sr-only" : "text-xs text-[var(--text-placeholder)]"}
+            className={size === "sm" ? "sr-only" : "text-xs text-placeholder"}
           >
             {sendOn === "enter" ? labels.sendHintEnter : labels.sendHint(modifier)}
           </span>
@@ -888,15 +893,11 @@ function dataAttributes(props: object): Record<string, unknown> {
 }
 
 /**
- * {@link FeedbackComposer} under a name that is not about feedback (keksdose K17).
- *
- * The component was never feedback-specific: a textarea, an optional picture or a
- * host's upload slot, Send, `sendOn="enter"` for the chat way. keksdose's assistant
- * and support chat are chats, not reports, and an import of `FeedbackComposer` there
- * reads as a mistake to the next person. The same function, not a wrapper, so the
- * two names cannot drift.
+ * @deprecated 0.34 — `ChatComposer`, the same function under the name that is not about
+ * feedback; removed in 0.35 (refactor audit 2026-10, API-6d). keksdose's support thread
+ * is the one app site.
  */
-export const ChatComposer = FeedbackComposer;
+export const FeedbackComposer = ChatComposer;
 /** {@link FeedbackComposerProps}, for {@link ChatComposer}. */
 export type ChatComposerProps = FeedbackComposerProps;
 /** {@link FeedbackComposerHandle}, for {@link ChatComposer}. */

package/src/feedback/feedback-vocabulary.ts

@@ -0,0 +1,252 @@
+import {
+  Ban,
+  Bug,
+  CheckCircle2,
+  ClipboardCheck,
+  CloudUpload,
+  Eye,
+  HelpCircle,
+  Inbox,
+  Lightbulb,
+  MoreHorizontal,
+  OctagonAlert,
+  PauseCircle,
+  Wrench,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * The feedback **vocabulary**: the eight statuses and five categories, the glyph and tone
+ * of each, their orders, and the policy for how a report moves from status to status.
+ *
+ * Data and plain functions, no components. Until 0.34 this lived at the top of
+ * feedback-inbox.tsx, so the feedback menu every app mounts in its top bar imported the
+ * inbox — its components and the attachment field they render — for one constant (a
+ * category's glyph), and only tree-shaking kept the rest out of every app's entry chunk.
+ * From here the top bar's imports reach none of it (MOD-1, refactor audit 2026-10).
+ * feedback-inbox.tsx re-exports every name here, so nothing an app imports has moved.
+ */
+
+/** The eight states a report can be in.
+ *
+ *  Shared value for value across the apps on purpose: it is what lets one habit,
+ *  and one agent prompt, work on any repo. Five are a chain and three sit off
+ *  it — see {@link visibleFeedbackStatuses} for what that buys. `READY` joined in 0.31
+ *  (feedback contract §8.2): OPEN is "filed, not yet triaged", READY "released for
+ *  implementation", and nobody works an OPEN row. */
+export type FeedbackStatus =
+  | "OPEN"
+  | "READY"
+  | "IN_PROGRESS"
+  | "IN_EVALUATION"
+  | "NEEDS_LIVE_TEST"
+  | "POSTPONED"
+  | "DONE"
+  | "WONT_DO";
+
+/** What a report is about. `CRASH` is filed by an error boundary and never
+ *  chosen, which is exactly why it is loud below and absent from every picker. */
+export type FeedbackCategory = "CRASH" | "BUG" | "IDEA" | "QUESTION" | "OTHER";
+
+/**
+ * A glyph and a tone per status.
+ *
+ * Colour alone is not a label — two of these sit a hue apart, and a consumer who
+ * moves `--brand` can park it beside any of the others — so every status carries
+ * its own shape as well. Declaration order is chain order, and
+ * {@link FEEDBACK_STATUS_ORDER} is derived from it rather than restated, because
+ * a restated list cannot be checked for exhaustiveness: an eighth status would
+ * break the build here and leave a literal eight long (as READY did in 0.31).
+ */
+export const FEEDBACK_STATUS_META: Record<
+  FeedbackStatus,
+  { icon: LucideIcon; activeBg: string; activeText: string }
+> = {
+  OPEN: {
+    icon: Inbox,
+    activeBg: "bg-active",
+    activeText: "text-primary",
+  },
+  // Triaged and released for implementation (feedback contract §8.2, keksdose live
+  // #396): OPEN is "filed, nobody has looked yet", READY is "go". The brand tint at full
+  // strength, so it reads as the go-ahead beside OPEN's neutral fill and
+  // NEEDS_LIVE_TEST's muted brand.
+  READY: {
+    icon: ClipboardCheck,
+    activeBg: "bg-brand-soft",
+    activeText: "text-brand",
+  },
+  IN_PROGRESS: {
+    icon: Wrench,
+    activeBg: "bg-warning-soft",
+    activeText: "text-warning",
+  },
+  // Where solved work is parked, waiting on the person who reported it. Its own
+  // colour, because "somebody has to check this" is a state you want to find by
+  // scanning rather than by reading.
+  IN_EVALUATION: {
+    icon: Eye,
+    activeBg: "bg-info-soft",
+    activeText: "text-info",
+  },
+  // Resolved but only checkable on a deployed build — the SOFT brand tint, so it
+  // reads as "waiting on something" rather than as a done or a refusal, and it
+  // follows whatever the consumer's brand is instead of pinning an indigo island
+  // beside it.
+  NEEDS_LIVE_TEST: {
+    icon: CloudUpload,
+    activeBg: "bg-brand-soft",
+    activeText: "text-brand-muted",
+  },
+  // Parked on purpose. Muted, not `--danger`: it is not a refusal.
+  POSTPONED: {
+    icon: PauseCircle,
+    activeBg: "bg-active",
+    activeText: "text-secondary",
+  },
+  // The one status with nowhere to move to: the vocabulary has a brand, an info, a
+  // warning and a danger, and nothing that means "succeeded". Deliberately NOT
+  // borrowed from a family that means something else — `--status-synced` is a
+  // FIELD's trip to the database rather than an outcome, and tokens.css says so in
+  // as many words. Green beside WONT_DO's red is the classic CVD-unsafe pair, which
+  // is why both carry a glyph and neither leans on colour alone.
+  DONE: {
+    icon: CheckCircle2,
+    activeBg: "bg-success-soft",
+    activeText: "text-success",
+  },
+  WONT_DO: {
+    icon: Ban,
+    activeBg: "bg-danger-soft",
+    activeText: "text-danger",
+  },
+};
+
+/** Chain order, then the three off it. The order a picker offers, and the rank a
+ *  status column sorts by — so a list sorted by status reads as a queue rather
+ *  than as an alphabet. */
+export const FEEDBACK_STATUS_ORDER = Object.keys(FEEDBACK_STATUS_META) as FeedbackStatus[];
+
+/** States that sit OFF the linear chain: reachable from anywhere, leading
+ *  nowhere by themselves. `WONT_DO` has always worked this way; `POSTPONED`
+ *  ("not now") and `NEEDS_LIVE_TEST` ("resolved, but only provable on a deployed
+ *  build") are the same shape — a row can be parked or handed to the next deploy
+ *  from any point, and comes back to the chain when somebody picks a real state
+ *  for it.
+ *
+ *  Kept out of the forward chain deliberately: putting them in it would mean an
+ *  "advance" gesture could park an item, and every row would have to pass
+ *  through them to reach `DONE`. */
+const OFF_CHAIN: FeedbackStatus[] = ["NEEDS_LIVE_TEST", "POSTPONED", "WONT_DO"];
+
+const FORWARD_CHAIN: FeedbackStatus[] = ["OPEN", "READY", "IN_PROGRESS", "IN_EVALUATION", "DONE"];
+
+/** The next status along the chain, or null at the end (or off it, as `WONT_DO`
+ *  is). What a swipe-to-advance gesture commits. */
+export function nextFeedbackStatus(current: FeedbackStatus): FeedbackStatus | null {
+  const at = FORWARD_CHAIN.indexOf(current);
+  return at !== -1 && at < FORWARD_CHAIN.length - 1 ? FORWARD_CHAIN[at + 1] : null;
+}
+
+/**
+ * The steps that make sense from where a row currently stands.
+ *
+ * For the compact control in a table cell: it is a glanceable triage affordance,
+ * and a row of eight icons in a cell is noise. One step forward, one step back
+ * (so an item can be sent back for rework), and any of the three off-chain
+ * verdicts — which is what makes those usable as verdicts at all.
+ *
+ * The two parking states are not dead ends: each offers the step that resumes
+ * work and the ones that close it, but deliberately **not each other** —
+ * "postponed" and "waiting on a deploy" are different answers to different
+ * questions, and a row moving between them directly is a re-triage, which starts
+ * by picking the work back up.
+ */
+export function visibleFeedbackStatuses(current: FeedbackStatus): FeedbackStatus[] {
+  const set = new Set<FeedbackStatus>([current]);
+  const at = FORWARD_CHAIN.indexOf(current);
+  if (at !== -1) {
+    if (at < FORWARD_CHAIN.length - 1) set.add(FORWARD_CHAIN[at + 1]);
+    if (at > 0) set.add(FORWARD_CHAIN[at - 1]);
+    for (const off of OFF_CHAIN) set.add(off);
+  } else if (current !== "WONT_DO") {
+    set.add("IN_PROGRESS");
+    set.add("DONE");
+    set.add("WONT_DO");
+  }
+  // WONT_DO falls through with nothing added: it stays terminal, reopened by a
+  // note from its author rather than by a status pill.
+  return FEEDBACK_STATUS_ORDER.filter((status) => set.has(status));
+}
+
+/**
+ * Every status, in chain order — what an EXPANDED row offers.
+ *
+ * {@link visibleFeedbackStatuses} narrows the choice to the steps that make
+ * sense from where a row is, which is right for a table cell. Once the row is
+ * open in front of you, that same narrowing turns every non-adjacent move into a
+ * walk: OPEN to DONE meant three round trips, and WONT_DO could not be left at
+ * all except through a rework note.
+ *
+ * Takes a `current` it does not use, so the two policies read as one pair at the
+ * call sites and a future rule ("terminal rows still cannot jump to X") has a
+ * place to live.
+ */
+export function selectableFeedbackStatuses(_current: FeedbackStatus): FeedbackStatus[] {
+  return [...FEEDBACK_STATUS_ORDER];
+}
+
+/**
+ * Per-category badge treatment, the counterpart to the status meta above.
+ *
+ * A category cell that is one grey pill holding the raw enum makes a CRASH —
+ * filed automatically, by somebody staring at a broken page right now — read
+ * exactly like a QUESTION, and sit unnoticed in the queue. `--danger` plus its own
+ * glyph is what makes that impossible; the hand-filed categories stay
+ * deliberately quiet so that the loud one means something.
+ *
+ * Declaration order is triage order, CRASH first.
+ */
+export const FEEDBACK_CATEGORY_META: Record<
+  FeedbackCategory,
+  { icon: LucideIcon; badgeBg: string; badgeText: string }
+> = {
+  CRASH: {
+    icon: OctagonAlert,
+    badgeBg: "bg-danger-soft",
+    badgeText: "text-danger",
+  },
+  BUG: {
+    icon: Bug,
+    badgeBg: "bg-warning-soft",
+    badgeText: "text-warning",
+  },
+  IDEA: {
+    icon: Lightbulb,
+    badgeBg: "bg-surface-2",
+    badgeText: "text-secondary",
+  },
+  QUESTION: {
+    icon: HelpCircle,
+    badgeBg: "bg-surface-2",
+    badgeText: "text-secondary",
+  },
+  OTHER: {
+    icon: MoreHorizontal,
+    badgeBg: "bg-surface-2",
+    badgeText: "text-secondary",
+  },
+};
+
+/** Triage order, CRASH first — also a category column's sort key and the option
+ *  order in its filter. Sorting by the raw enum is alphabetical, which parks
+ *  CRASH between BUG and IDEA. */
+export const FEEDBACK_CATEGORY_ORDER = Object.keys(FEEDBACK_CATEGORY_META) as FeedbackCategory[];
+
+/** A category's rank for a column sort. Anything this build has never heard of —
+ *  an older client against a newer API — sorts LAST rather than to `indexOf`'s
+ *  −1, which would rank it above CRASH. */
+export function feedbackCategoryRank(category: FeedbackCategory): number {
+  const at = FEEDBACK_CATEGORY_ORDER.indexOf(category);
+  return at === -1 ? FEEDBACK_CATEGORY_ORDER.length : at;
+}

package/src/hooks/use-anchored-panel.ts

@@ -2,6 +2,7 @@ import { useLayoutEffect, useState } from "react";
 import type { RefObject } from "react";
 import { useAnchoredRect, type AnchorRect } from "./use-anchored-rect";
 import { useTextSize } from "../theme/text-size";
+import type { Direction } from "../lib/direction";
 
 /**
  * Vertical placement for a portalled, `position: fixed` panel anchored to a trigger.
@@ -191,6 +192,104 @@ export function anchoredPanelPlacement(
   return { top, bottom: layoutHeight - (top + maxHeight), maxHeight, above };
 }
 
+/**
+ * The glass a panel has to stay on, in CSS pixels — `window.innerWidth` is the wrong
+ * width on a phone (keksdose run 72, live #381). There it is the LAYOUT viewport, and
+ * that grows to the page's width as soon as anything sticks out past the screen: 430 on
+ * a 406px screen in Chromium's mobile emulation, with `position: fixed` layers laid out
+ * against the 430. A panel that had widened the page then measured itself as inside it.
+ * The root element's client width is the initial containing block instead — the screen,
+ * the width `100vw` and the media queries see — whatever overflows, and on a desktop it
+ * also leaves a classic scrollbar out, which is where a fixed box's `right` is measured
+ * from. It is 0 where nothing is laid out (jsdom), and the window is the answer there.
+ * The height stays the window's: nothing measured grows it, and a phone's collapsing
+ * toolbar makes the window the truer of the two.
+ *
+ * Tooltip's lesson, moved here so every anchored panel reads the same width (round 0.34
+ * Wave 2, DUP-7).
+ */
+export function viewportSize(): { width: number; height: number } {
+  return {
+    width: document.documentElement.clientWidth || window.innerWidth,
+    height: window.innerHeight,
+  };
+}
+
+export interface AnchoredInlineOptions {
+  /** The trigger's reading direction, which `start`, `end` and `after` follow. Default
+   *  `ltr`. A portalled panel has left the subtree it would inherit `dir` from, so read
+   *  it off the trigger (`dirOf`). */
+  dir?: Direction;
+  /**
+   * Which of the panel's edges lines up with which of the trigger's:
+   * - `start` / `end` — the panel's start (end) edge on the trigger's start (end) edge,
+   *   by reading direction: a picker hangs from its field's start, a popover from its
+   *   button's end;
+   * - `left` / `right` — the same, physically;
+   * - `after` — the panel's start edge on the trigger's END edge: beside it, as the
+   *   sidebar's flyout opens.
+   *
+   * Default `start`.
+   */
+  align?: "start" | "end" | "left" | "right" | "after";
+  /** The room kept from either edge of the glass, in px. Default 8. */
+  edge?: number;
+  /** The glass's width. Default {@link viewportSize}'s. */
+  viewportWidth?: number;
+}
+
+/** The horizontal place of a `position: fixed` panel: its `left`, and the `right` of the
+ *  same box for a panel hung from its right edge (both in px, from the glass's edges). */
+export interface InlinePlacement {
+  left: number;
+  right: number;
+}
+
+/**
+ * The horizontal half of an anchored panel, beside {@link anchoredPanelPlacement}'s
+ * vertical one (round 0.34 Wave 2, DUP-7): where a panel `panelWidth` wide goes against
+ * the trigger's `rect`, kept `edge` px inside the glass ({@link viewportSize}).
+ *
+ * Popover, DropdownPanel, ComboboxPanel, HoverMenu and the AppShell flyout each wrote
+ * this themselves, against three different widths: `innerWidth`, which on a phone is
+ * the grown layout viewport and on a desktop counts the scrollbar; the root's client
+ * width; and, for the entity picker's panel in a left-to-right form, no clamp at all.
+ *
+ * A panel wider than the room keeps its START on the glass — its left edge in a
+ * left-to-right form, its right in a right-to-left one — as Tooltip's slide does: the
+ * start of a row of text is the half worth keeping.
+ */
+export function anchoredInline(
+  rect: Pick<AnchorRect, "left" | "right">,
+  panelWidth: number,
+  { dir = "ltr", align = "start", edge = 8, viewportWidth = viewportSize().width }: AnchoredInlineOptions = {},
+): InlinePlacement {
+  const rtl = dir === "rtl";
+  // Where the panel's LEFT edge goes, before the clamp.
+  let wanted: number;
+  switch (align) {
+    case "left":
+      wanted = rect.left;
+      break;
+    case "right":
+      wanted = rect.right - panelWidth;
+      break;
+    case "start":
+      wanted = rtl ? rect.right - panelWidth : rect.left;
+      break;
+    case "end":
+      wanted = rtl ? rect.left : rect.right - panelWidth;
+      break;
+    case "after":
+      wanted = rtl ? rect.left - panelWidth : rect.right;
+      break;
+  }
+  const min = edge;
+  const max = viewportWidth - edge - panelWidth;
+  const left = max < min ? (rtl ? max : min) : Math.min(Math.max(wanted, min), max);
+  return { left, right: viewportWidth - left - panelWidth };
+}
+
 /**
  * The region actually on screen, tracked while `active` (Keksdose live #328).
  *
@@ -245,8 +344,9 @@ export function useVisualViewport(active: boolean): ViewportBox | null {
 /**
  * Where to put a panel anchored under `ref`, tracking the visible viewport.
  *
- * Callers own horizontal placement — the pickers align to the trigger's left edge, the
- * popovers to its right — and must apply `maxHeight` with an internal `overflow-y`.
+ * Callers own horizontal placement, through {@link anchoredInline} — the pickers align
+ * to the trigger's start edge, the popovers to its end — and must apply `maxHeight` with
+ * an internal `overflow-y`.
  * Vertically, apply `top` while the panel is below and `bottom` (with no `top`) once it
  * is `above`; see {@link AnchoredPanel}.
  */

package/src/hooks/use-anchored-rect.ts

@@ -11,17 +11,19 @@ export interface AnchorRect {
   height: number;
 }
 
-function sameRect(a: AnchorRect | null, b: AnchorRect | null): boolean {
+/**
+ * Whether two measurements are the same box, so a re-measure that moved nothing keeps the
+ * state it had (no render). Top, left, width and height decide it: an `AnchorRect`'s
+ * right and bottom are those sums. The kit's one copy — the tour's spotlight asks it too
+ * (DUP-11, refactor audit 2026-10).
+ */
+export function sameRect<R extends { top: number; left: number; width: number; height: number }>(
+  a: R | null,
+  b: R | null,
+): boolean {
   if (a === b) return true;
   if (!a || !b) return false;
-  return (
-    a.top === b.top &&
-    a.left === b.left &&
-    a.right === b.right &&
-    a.bottom === b.bottom &&
-    a.width === b.width &&
-    a.height === b.height
-  );
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
 }
 
 /**