@eifi1/ui-kit 0.50.0 → 0.51.0

package/dist/tour/use-tour-url-sync.js

@@ -4,6 +4,7 @@ import * as ReactRouter from "react-router";
 import { useLocation, useNavigate } from "react-router";
 import { useSearchParamsState } from "../hooks/use-search-param-state.js";
 import { useTourOptional } from "./tour.js";
+import { liveEngine } from "./tour-engine.js";
 import { devWarnings } from "./tour-gates.js";
 function navigationInFlight(history, dataRouter, rendered) {
   const state = dataRouter?.router?.state;
@@ -51,10 +52,12 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
   const aliases = stepAliases.join("\n");
   const launchRef = useRef(launch);
   const startRef = useRef(engine?.start ?? noProviderStart);
+  const [live] = useState(() => liveEngine(ENGINE_KEYS, NO_PROVIDER_ENGINE));
   const activeIdRef = useRef(activeId);
   useLayoutEffect(() => {
     launchRef.current = launch;
     startRef.current = engine?.start ?? noProviderStart;
+    live.set(engine ?? NO_PROVIDER_ENGINE);
     activeIdRef.current = active ? activeId : null;
   });
   const seenRef = useRef(null);
@@ -70,7 +73,7 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
     if (!pending || !ready) return;
     pendingRef.current = null;
     launchingRef.current = true;
-    void Promise.resolve().then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current)).catch(() => void 0).finally(() => {
+    void Promise.resolve().then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine)).catch(() => void 0).finally(() => {
       launchingRef.current = false;
       setSettled((n) => n + 1);
     });
@@ -95,6 +98,23 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
 const noProviderStart = () => {
   if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
 };
+const noProviderCall = () => {
+  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.");
+};
+const NO_PROVIDER_ENGINE = {
+  active: false,
+  activeId: null,
+  start: noProviderStart,
+  stop: noProviderCall,
+  next: noProviderCall,
+  prev: noProviderCall,
+  goToStep: noProviderCall,
+  index: 0,
+  total: 0,
+  position: 0,
+  count: 0
+};
+const ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE);
 const STATES = ["all", "todo", "done"];
 function useTourCatalogueUrlState(params = {}) {
   const [filter, setFilter] = useSearchParamsState({

package/dist/tour/use-tour-url-sync.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tour/use-tour-url-sync.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from \"react\";\nimport * as ReactRouter from \"react-router\";\nimport { useLocation, useNavigate, type Navigator } from \"react-router\";\nimport { useSearchParamsState } from \"../hooks/use-search-param-state\";\nimport { useTourOptional, type TourStart } from \"./tour\";\nimport { devWarnings } from \"./tour-gates\";\n\n/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */\n\nexport interface UseTourUrlSyncOptions {\n  /**\n   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the\n   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points\n   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:\n   * the parameters are kept until it settles. Under a `TourProvider` the third argument is\n   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves\n   * both. Without a provider it is a `start` that does nothing (a development build warns).\n   */\n  launch: (id: string, options: { startIndex: number }, start: TourStart) => void | Promise<unknown>;\n  /**\n   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the\n   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so\n   * an F5 mid-tour resumes the right variant at the right step. Default `true`.\n   */\n  ready?: boolean;\n  /**\n   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's\n   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.\n   */\n  stepAliases?: readonly string[];\n}\n\ntype Place = { pathname: string; search: string; hash: string };\n\n/**\n * Has the router already moved on from the location React is still rendering?\n * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built\n * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.\n *\n * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build\n *   review 0.43, kastlan A2), so the router's own state answers — a navigation still\n *   loading, or a location it has committed that React has not rendered yet.\n * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and\n *   carries where it is.\n * - Anything else answers \"not in flight\".\n */\nfunction navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {\n  const state = dataRouter?.router?.state;\n  if (state && (state.navigation?.state ?? \"idle\") !== \"idle\") return true;\n  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;\n  if (!live) return false;\n  return (\n    live.pathname !== rendered.pathname || (live.search ?? \"\") !== rendered.search || (live.hash ?? \"\") !== rendered.hash\n  );\n}\n\ntype NavigationProbe = { navigator?: Navigator } | null;\nconst NO_NAVIGATION = createContext<NavigationProbe>(null);\n/** The data router's state, as `useSearchParamState` reads it. */\ntype DataRouterProbe = {\n  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };\n} | null;\nconst NO_DATA_ROUTER = createContext<DataRouterProbe>(null);\nconst DataRouterContext: Context<DataRouterProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??\n      NO_DATA_ROUTER\n    );\n  } catch {\n    return NO_DATA_ROUTER;\n  }\n})();\n/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:\n *  a test's partial `vi.mock(\"react-router\")` throws on an export it does not define. */\nconst NavigationContext: Context<NavigationProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??\n      NO_NAVIGATION\n    );\n  } catch {\n    return NO_NAVIGATION;\n  }\n})();\n\n/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */\nfunction stepOf(params: URLSearchParams, aliases: readonly string[]): number {\n  const step = Number(params.get(\"tourStep\"));\n  if (params.has(\"tourStep\")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;\n  for (const alias of aliases) {\n    const value = Number(params.get(alias));\n    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n  }\n  return 0;\n}\n\n/**\n * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,\n * on the kit's engine (`useTourOptional`):\n *\n * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app\n *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —\n *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.\n * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied\n *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.\n * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.\n *\n * Mount it once inside the router and the `TourProvider`. Without a provider it still\n * launches through `launch` and never mirrors.\n */\nexport function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {\n  const navigate = useNavigate();\n  const location = useLocation();\n  const { pathname, search, hash } = location;\n  const history = useContext(NavigationContext)?.navigator;\n  const dataRouter = useContext(DataRouterContext);\n  const engine = useTourOptional();\n  const active = engine?.active ?? false;\n  const activeId = engine?.activeId ?? null;\n  const index = engine?.index ?? 0;\n  const urlTour = new URLSearchParams(search).get(\"tour\");\n  const aliases = stepAliases.join(\"\\n\");\n\n  const launchRef = useRef(launch);\n  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);\n  const activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\n    startRef.current = engine?.start ?? noProviderStart;\n    activeIdRef.current = active ? activeId : null;\n  });\n  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */\n  const seenRef = useRef<string | null>(null);\n  /** A deep link waiting for `ready`. */\n  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);\n  /** A launch under way (an app's `prepare()`). */\n  const launchingRef = useRef(false);\n  /** Bumped when a launch settles, so the mirror looks again. */\n  const [settled, setSettled] = useState(0);\n\n  useEffect(() => {\n    if (urlTour !== seenRef.current) {\n      seenRef.current = urlTour;\n      // Its own mirror writing the running tour back is no new link.\n      pendingRef.current =\n        urlTour && urlTour !== activeIdRef.current\n          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split(\"\\n\") : []) }\n          : null;\n    }\n    const pending = pendingRef.current;\n    if (!pending || !ready) return;\n    pendingRef.current = null;\n    launchingRef.current = true;\n    void Promise.resolve()\n      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current))\n      .catch(() => undefined)\n      .finally(() => {\n        launchingRef.current = false;\n        setSettled((n) => n + 1);\n      });\n    // Only a change of the parameter, or readiness, starts a tour.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [urlTour, ready]);\n\n  useEffect(() => {\n    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;\n    // A link not yet used keeps its parameters: a reload in that window resumes.\n    if (pendingRef.current || launchingRef.current) return;\n    const tourId = active && activeId ? activeId : null;\n    const own = [\"tour\", \"tourStep\", ...(aliases ? aliases.split(\"\\n\") : [])];\n    const current = new URLSearchParams(search);\n    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace\n    // clobbers a page's own just-issued navigation, keksdose feedback #4).\n    if (!tourId && !own.some((key) => current.has(key))) return;\n    const next = new URLSearchParams(search);\n    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the\n    // tour's own) go.\n    for (const key of tourId ? own.slice(2) : own) next.delete(key);\n    if (tourId) {\n      next.set(\"tour\", tourId);\n      next.set(\"tourStep\", String(index + 1));\n    }\n    if (next.toString() === current.toString()) return;\n    // Spelled out, not `setSearchParams` (\"?…\" drops the hash, keksdose dev#495).\n    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active, activeId, index, pathname, search, hash, settled, aliases]);\n}\n\n/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */\nconst noProviderStart: TourStart = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.\");\n};\n\n/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */\n\n/** The catalogue's state filter. */\nexport type TourStateFilter = \"all\" | \"todo\" | \"done\";\n\n/** The catalogue's filters: the search, the group (`null`: every group), the state. */\nexport interface TourCatalogueFilter {\n  query: string;\n  group: string | null;\n  state: TourStateFilter;\n}\n\nconst STATES: readonly TourStateFilter[] = [\"all\", \"todo\", \"done\"];\n\n/**\n * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each\n * written with `replace` (typing does not bury the Back button), the defaults as the\n * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.\n * `params` renames them (kastlan's `?group`). Requires a react-router Router.\n */\nexport function useTourCatalogueUrlState(\n  params: { query?: string; group?: string; state?: string } = {},\n): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {\n  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({\n    query: { param: params.query ?? \"q\", default: \"\", history: \"replace\" },\n    group: { param: params.group ?? \"topic\", default: null, history: \"replace\", parse: (raw) => raw || undefined },\n    state: {\n      param: params.state ?? \"state\",\n      default: \"all\",\n      history: \"replace\",\n      parse: (raw) => STATES.find((x) => x === raw),\n    },\n  });\n  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.\n  return { ...filter, onChange: setFilter };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/tour/use-tour-url-sync.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from \"react\";\nimport * as ReactRouter from \"react-router\";\nimport { useLocation, useNavigate, type Navigator } from \"react-router\";\nimport { useSearchParamsState } from \"../hooks/use-search-param-state\";\nimport { useTourOptional, type TourEngine, type TourStart } from \"./tour\";\nimport { liveEngine } from \"./tour-engine\";\nimport { devWarnings } from \"./tour-gates\";\n\n/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */\n\nexport interface UseTourUrlSyncOptions {\n  /**\n   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the\n   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points\n   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:\n   * the parameters are kept until it settles. Under a `TourProvider` the third argument is\n   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves\n   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,\n   * `active`, …). Without a provider `start` and the engine's methods do nothing (a\n   * development build warns) and the engine reads as idle.\n   */\n  launch: (\n    id: string,\n    options: { startIndex: number },\n    start: TourStart,\n    engine: TourEngine,\n  ) => void | Promise<unknown>;\n  /**\n   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the\n   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so\n   * an F5 mid-tour resumes the right variant at the right step. Default `true`.\n   */\n  ready?: boolean;\n  /**\n   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's\n   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.\n   */\n  stepAliases?: readonly string[];\n}\n\ntype Place = { pathname: string; search: string; hash: string };\n\n/**\n * Has the router already moved on from the location React is still rendering?\n * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built\n * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.\n *\n * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build\n *   review 0.43, kastlan A2), so the router's own state answers — a navigation still\n *   loading, or a location it has committed that React has not rendered yet.\n * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and\n *   carries where it is.\n * - Anything else answers \"not in flight\".\n */\nfunction navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {\n  const state = dataRouter?.router?.state;\n  if (state && (state.navigation?.state ?? \"idle\") !== \"idle\") return true;\n  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;\n  if (!live) return false;\n  return (\n    live.pathname !== rendered.pathname || (live.search ?? \"\") !== rendered.search || (live.hash ?? \"\") !== rendered.hash\n  );\n}\n\ntype NavigationProbe = { navigator?: Navigator } | null;\nconst NO_NAVIGATION = createContext<NavigationProbe>(null);\n/** The data router's state, as `useSearchParamState` reads it. */\ntype DataRouterProbe = {\n  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };\n} | null;\nconst NO_DATA_ROUTER = createContext<DataRouterProbe>(null);\nconst DataRouterContext: Context<DataRouterProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??\n      NO_DATA_ROUTER\n    );\n  } catch {\n    return NO_DATA_ROUTER;\n  }\n})();\n/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:\n *  a test's partial `vi.mock(\"react-router\")` throws on an export it does not define. */\nconst NavigationContext: Context<NavigationProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??\n      NO_NAVIGATION\n    );\n  } catch {\n    return NO_NAVIGATION;\n  }\n})();\n\n/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */\nfunction stepOf(params: URLSearchParams, aliases: readonly string[]): number {\n  const step = Number(params.get(\"tourStep\"));\n  if (params.has(\"tourStep\")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;\n  for (const alias of aliases) {\n    const value = Number(params.get(alias));\n    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n  }\n  return 0;\n}\n\n/**\n * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,\n * on the kit's engine (`useTourOptional`):\n *\n * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app\n *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —\n *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.\n * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied\n *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.\n * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.\n *\n * Mount it once inside the router and the `TourProvider`. Without a provider it still\n * launches through `launch` and never mirrors.\n */\nexport function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {\n  const navigate = useNavigate();\n  const location = useLocation();\n  const { pathname, search, hash } = location;\n  const history = useContext(NavigationContext)?.navigator;\n  const dataRouter = useContext(DataRouterContext);\n  const engine = useTourOptional();\n  const active = engine?.active ?? false;\n  const activeId = engine?.activeId ?? null;\n  const index = engine?.index ?? 0;\n  const urlTour = new URLSearchParams(search).get(\"tour\");\n  const aliases = stepAliases.join(\"\\n\");\n\n  const launchRef = useRef(launch);\n  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);\n  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));\n  const activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\n    startRef.current = engine?.start ?? noProviderStart;\n    live.set(engine ?? NO_PROVIDER_ENGINE);\n    activeIdRef.current = active ? activeId : null;\n  });\n  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */\n  const seenRef = useRef<string | null>(null);\n  /** A deep link waiting for `ready`. */\n  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);\n  /** A launch under way (an app's `prepare()`). */\n  const launchingRef = useRef(false);\n  /** Bumped when a launch settles, so the mirror looks again. */\n  const [settled, setSettled] = useState(0);\n\n  useEffect(() => {\n    if (urlTour !== seenRef.current) {\n      seenRef.current = urlTour;\n      // Its own mirror writing the running tour back is no new link.\n      pendingRef.current =\n        urlTour && urlTour !== activeIdRef.current\n          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split(\"\\n\") : []) }\n          : null;\n    }\n    const pending = pendingRef.current;\n    if (!pending || !ready) return;\n    pendingRef.current = null;\n    launchingRef.current = true;\n    void Promise.resolve()\n      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))\n      .catch(() => undefined)\n      .finally(() => {\n        launchingRef.current = false;\n        setSettled((n) => n + 1);\n      });\n    // Only a change of the parameter, or readiness, starts a tour.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [urlTour, ready]);\n\n  useEffect(() => {\n    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;\n    // A link not yet used keeps its parameters: a reload in that window resumes.\n    if (pendingRef.current || launchingRef.current) return;\n    const tourId = active && activeId ? activeId : null;\n    const own = [\"tour\", \"tourStep\", ...(aliases ? aliases.split(\"\\n\") : [])];\n    const current = new URLSearchParams(search);\n    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace\n    // clobbers a page's own just-issued navigation, keksdose feedback #4).\n    if (!tourId && !own.some((key) => current.has(key))) return;\n    const next = new URLSearchParams(search);\n    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the\n    // tour's own) go.\n    for (const key of tourId ? own.slice(2) : own) next.delete(key);\n    if (tourId) {\n      next.set(\"tour\", tourId);\n      next.set(\"tourStep\", String(index + 1));\n    }\n    if (next.toString() === current.toString()) return;\n    // Spelled out, not `setSearchParams` (\"?…\" drops the hash, keksdose dev#495).\n    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active, activeId, index, pathname, search, hash, settled, aliases]);\n}\n\n/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */\nconst noProviderStart: TourStart = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.\");\n};\n\nconst noProviderCall = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.\");\n};\n/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */\nconst NO_PROVIDER_ENGINE: TourEngine = {\n  active: false,\n  activeId: null,\n  start: noProviderStart,\n  stop: noProviderCall,\n  next: noProviderCall,\n  prev: noProviderCall,\n  goToStep: noProviderCall,\n  index: 0,\n  total: 0,\n  position: 0,\n  count: 0,\n};\nconst ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];\n\n/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */\n\n/** The catalogue's state filter. */\nexport type TourStateFilter = \"all\" | \"todo\" | \"done\";\n\n/** The catalogue's filters: the search, the group (`null`: every group), the state. */\nexport interface TourCatalogueFilter {\n  query: string;\n  group: string | null;\n  state: TourStateFilter;\n}\n\nconst STATES: readonly TourStateFilter[] = [\"all\", \"todo\", \"done\"];\n\n/**\n * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each\n * written with `replace` (typing does not bury the Back button), the defaults as the\n * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.\n * `params` renames them (kastlan's `?group`). Requires a react-router Router.\n */\nexport function useTourCatalogueUrlState(\n  params: { query?: string; group?: string; state?: string } = {},\n): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {\n  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({\n    query: { param: params.query ?? \"q\", default: \"\", history: \"replace\" },\n    group: { param: params.group ?? \"topic\", default: null, history: \"replace\", parse: (raw) => raw || undefined },\n    state: {\n      param: params.state ?? \"state\",\n      default: \"all\",\n      history: \"replace\",\n      parse: (raw) => STATES.find((x) => x === raw),\n    },\n  });\n  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.\n  return { ...filter, onChange: setFilter };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",

package/src/admin/user-roster.tsx

@@ -8,6 +8,7 @@ import { AccountStateChip, RoleChip, dateColumn } from "../components/account-ch
 import type { AccountState, RoleVocabulary } from "../components/account-chips";
 import type { ChipTone } from "../components/chip";
 import type { DataTableColumn } from "../components/data-table";
+import { SelectWidthFloor } from "../components/field-base";
 import { encodeSorts } from "../components/data-table-sort";
 import type { SortState } from "../components/data-table-sort";
 import { RowActions } from "../components/row-actions";
@@ -298,6 +299,13 @@ function rolesOf<T extends UserRosterRow, R extends string>(
   return typeof raw === "string" ? [raw as R] : [...(raw as readonly R[])];
 }
 
+/** What a row's role select can show as its value: every role's word, and a held key
+ *  the vocabulary does not know (RoleSelect shows it as the key). */
+function roleWordsOf<R extends string>(roles: RoleVocabulary<R>, held: R | undefined): string[] {
+  const words = (Object.keys(roles) as R[]).map((role) => roles[role].label);
+  return held !== undefined && !(held in roles) ? [...words, held] : words;
+}
+
 /** The row's name in the reader's order — a component, because the order is the
  *  READER's and the locale comes from the provider. */
 function RowName<T extends UserRosterRow>({ row, children }: { row: T; children: (name: string) => ReactNode }) {
@@ -423,16 +431,28 @@ export function userRosterColumns<T extends UserRosterRow, R extends string = st
           return (
             <RowName row={row}>
               {(name) => (
-                <RoleSelect<R>
-                  size="sm"
-                  name={name}
-                  value={held[0] ?? null}
-                  roles={roles}
-                  offered={rules.offered}
-                  disabledReason={rules.disabledReason}
-                  optionDisabledReason={rules.optionDisabledReason}
-                  onChange={(role) => onRoleChange(row, role)}
-                />
+                // The column keeps room for the select's longest ROLE word in the app's
+                // language (0.51, Kurvenschmiede N5): beside the `grow` Name every other
+                // column is squeezed to its min-content, which a `w-full` select does not
+                // have, so the role select was the header's ~92px and read "Meml…",
+                // "Admi…". Every word of the vocabulary, not only the row's offered
+                // ones: the column is as wide as its widest row, so the rows line up, and
+                // a role held but not offered (KS's Reviewer) is still a selected value.
+                // Not the options' reasons ("Customer (owns work)"): they are never the
+                // selected value, and the open list is as wide as it needs anyway.
+                <div>
+                  <RoleSelect<R>
+                    size="sm"
+                    name={name}
+                    value={held[0] ?? null}
+                    roles={roles}
+                    offered={rules.offered}
+                    disabledReason={rules.disabledReason}
+                    optionDisabledReason={rules.optionDisabledReason}
+                    onChange={(role) => onRoleChange(row, role)}
+                  />
+                  <SelectWidthFloor size="sm" values={roleWordsOf(roles, held[0])} />
+                </div>
               )}
             </RowName>
           );

package/src/auth/verify-email.tsx

@@ -364,6 +364,10 @@ export interface EmailVerificationBannerProps {
    * of a 390px phone). The resend's outcome ("Sent", the error) then moves out of the
    * message to sit after "Send again", at every width, so the line that answers the press
    * is never hidden behind "More". Default `false`: the outcome stays in the message.
+   *
+   * 0.51 (kastlan K1, KX-5): in the `strip` variant "Send again" then stays on the clamped
+   * message's line on a phone — one line, 43px, on a 390px phone in all seven catalogues —
+   * where it took a line of its own (71px). The box's equivalent is `actionPlacement`.
    */
   clampMobile?: boolean;
   /**

package/src/components/alert-banner.tsx

@@ -206,6 +206,15 @@ interface AlertBannerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "on
    * every phone screen, and the app built the clamp and the button around the banner's
    * children by hand. Ignored on a whole-row banner (`href` / `onClick`): a toggle cannot
    * sit inside the row's own link or button.
+   *
+   * 0.51 (kastlan K1): on a `strip` the clamped message claims 7rem instead of 12rem below
+   * `md`, so the {@link action} stays on its line rather than taking one of its own.
+   *
+   * For a one-line MESSAGE (a sentence or two). Not for a body with a list or a control in
+   * it: the clamp cuts the box to its first line, so a Disclosure's or a link's trigger
+   * past it is clipped out of sight and still takes the keyboard's focus, and "More" gives
+   * back the whole body at once. Shorten such a banner instead — one sentence, its action,
+   * and the rest behind a Disclosure of its own (keksdose's agree-again notice, 0.51).
    */
   clampMobile?: boolean;
   /**
@@ -300,7 +309,7 @@ export function AlertBanner({
   // server) the box is 0 tall, which reads as "may not fit": the toggle stays.
   const clamp = clampMobile && !interactive;
   const bodyId = useId();
-  const bodyRef = useRef<HTMLSpanElement>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
   const [expanded, setExpanded] = useState(false);
   const [fits, setFits] = useState(false);
   useLayoutEffect(() => {
@@ -357,6 +366,17 @@ export function AlertBanner({
   // into a three-word column on a phone instead. With a real basis the action drops to
   // a second line once message + action no longer fit, and the message keeps the width.
   const grow = strip ? "flex-[1_1_12rem]" : "flex-1";
+  // …except a CLAMPED strip on a phone (0.51, kastlan K1 / prod #22, KX-5). There the
+  // message is one line whatever its width (the rest is behind "More"), so the 12rem only
+  // pushed the action under it: "Erneut senden" took a line of its own on a 390px phone,
+  // and kastlan's banner stood 71px where one line is 43. The clamp needs its "More" and
+  // the first words beside it, so below `md` the basis is 7rem (~4rem of text). Measured
+  // in Chromium at 390 × 844, kastlan's `mx-4` strip (326px inside): one line, 43px, in
+  // all seven catalogues, with Roboto and with the wider DejaVu Sans; French, the longest
+  // "Send again", keeps 8px. At 360px French (and Spanish in DejaVu) still drop a line.
+  // A rem basis like the 12rem, so at Large the action drops a line sooner, by itself.
+  // From `md` up the clamp is off and the 12rem holds; without `clampMobile` nothing moves.
+  const clampBasis = strip && clamp ? "max-md:basis-28" : undefined;
   // Inside a whole-row banner's button or link, which then carries `grow` itself.
   const nested = interactive && (onDismiss !== undefined || (action !== undefined && action !== null));
   const frame = inline
@@ -367,25 +387,32 @@ export function AlertBanner({
       );
   const focusRing = cn(FOCUS_RING, "focus-visible:ring-offset-1 focus-visible:ring-offset-surface");
 
+  // The message's box: a `<div>` (0.51), so a banner may hold block content — keksdose's
+  // agree-again notice has a list and a Disclosure in it, which inside the `<span>` this was
+  // were block elements in phrasing content. A `<span>` still in a whole-row banner, whose
+  // `<a>` / `<button>` takes phrasing content only.
+  const Body = interactive ? "span" : "div";
   const contentBody = clamp ? (
     // Below `md` a row: the message, clamped, then the toggle on its baseline. From
-    // `md` up a plain span with the message in it, as without the prop.
-    <span
+    // `md` up a plain box with the message in it, as without the prop. (Never a whole-row
+    // banner, so always a `<div>`.)
+    <div
       className={cn(
         !inlineRow && grow,
+        clampBasis,
         "min-w-0 text-start max-md:flex max-md:items-baseline max-md:gap-2",
       )}
     >
       {/* The clamp is deliberate: the rest is one tap away behind More, so the size sweep's
           truncation gate (scripts/screenshot-sizes.mjs) leaves it alone. */}
-      <span
+      <div
         id={bodyId}
         ref={bodyRef}
         data-truncate-ok=""
         className={cn("max-md:min-w-0", !expanded && "max-md:line-clamp-1")}
       >
         {children}
-      </span>
+      </div>
       {(expanded || !fits) && (
         <button
           type="button"
@@ -400,11 +427,11 @@ export function AlertBanner({
           {expanded ? common.showLess : common.showMore}
         </button>
       )}
-    </span>
+    </div>
   ) : (
-    <span className={cn(!inlineRow && (nested ? "flex-1" : grow), "min-w-0 text-start")}>
+    <Body className={cn(!inlineRow && (nested ? "flex-1" : grow), "min-w-0 text-start")}>
       {children}
-    </span>
+    </Body>
   );
   const content = (
     <>
@@ -480,10 +507,10 @@ export function AlertBanner({
             <div className={flowRow} data-action-flow="">
               {/* The glyph rides with the message, on its first line; the two are
                   centred against the action as one, as the whole-row button is. */}
-              <span className={cn("flex min-w-0 flex-1 items-start", flowBasis, sm ? "gap-1.5" : "gap-2")}>
+              <div className={cn("flex min-w-0 flex-1 items-start", flowBasis, sm ? "gap-1.5" : "gap-2")}>
                 {glyph}
                 {contentBody}
-              </span>
+              </div>
               {trailing}
             </div>
           </>

package/src/components/autocomplete.tsx

@@ -7,6 +7,7 @@ import { Spinner } from "./spinner";
 import { useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { isImeEnter } from "../lib/ime";
+import { isQuietFocus } from "../lib/quiet-focus";
 import { useAnchorDir } from "./use-anchor-dir";
 import {
   ComboboxFieldLabel,
@@ -268,6 +269,8 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
   // either way, so a caller that controls only SOMETIMES (`open={confirming ? false :
   // undefined}`) hands back a field that is exactly as open as focus says it is.
   const open = openProp ?? ownOpen;
+  // The field took the tour's quiet focus (§11.8) and has not opened since.
+  const quietRef = useRef(false);
   const setOpen = (next: boolean) => {
     setOwnOpen(next);
     if (next !== open) onOpenChange?.(next);
@@ -410,11 +413,26 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
                 onFocus?.(e);
                 // A locked field takes focus to say why, and opens nothing.
                 if (locked) return;
+                // The tour's focus on arrival (§11.8) looks nothing up: the list would
+                // cover its card (0.50.1). A click, ArrowDown or typing opens it.
+                if (isQuietFocus(e.currentTarget)) {
+                  quietRef.current = true;
+                  return;
+                }
                 // A seeded field (keksdose's `initialQuery`) is looked up as it is
                 // focused; an empty one asks nothing, because of `minChars`.
                 setOpen(true);
               }}
+              // After a quiet focus, the person's click on the already-focused field
+              // fires no `focus`: the click is their "open" instead.
+              onClick={(e) => {
+                rest.onClick?.(e);
+                if (!quietRef.current || locked) return;
+                quietRef.current = false;
+                setOpen(true);
+              }}
               onBlur={(e) => {
+                quietRef.current = false;
                 onBlur?.(e);
                 close();
               }}

package/src/components/button-look.ts

@@ -34,54 +34,7 @@ export type ButtonVariant =
   | "secondary"
   | "ghost"
   | "danger"
-  | "link"
-  /** @deprecated 0.49 — use `default` (same look); removed in 0.51. */
-  | "primary"
-  /** @deprecated 0.49 — use `accent` (same look); removed in 0.51. */
-  | "brand";
-
-/** @internal A {@link ButtonVariant} without the deprecated aliases. */
-export type CanonicalButtonVariant = Exclude<ButtonVariant, "primary" | "brand">;
-
-/** The deprecated names and what they stand for — see {@link ButtonVariant}. */
-const DEPRECATED_BUTTON_VARIANTS: Readonly<Record<string, CanonicalButtonVariant>> = {
-  primary: "default",
-  brand: "accent",
-};
-
-/** The kit's dev switch, as `lib/logger.ts` reads it: a development build, never a
- *  production one (the consumer's bundler makes `import.meta.env.DEV` false) and never
- *  under vitest. Read per call so a test can switch it on with `vi.stubEnv`. */
-function devWarnings(): boolean {
-  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
-}
-
-const warnedVariants = new Set<string>();
-
-/**
- * @internal A deprecated variant name warns once (per `component` and name) in a
- * development build, then reads as the name it stands for. `component` is the prop's
- * owner in the message ("Button variant", "FormActions submitVariant", …).
- */
-export function warnDeprecatedVariant(component: string, name: string, replacement: string): void {
-  if (!devWarnings()) return;
-  const key = `${component}|${name}`;
-  if (warnedVariants.has(key)) return;
-  warnedVariants.add(key);
-  console.warn(
-    `[ui-kit] ${component}="${name}" is deprecated: use "${replacement}" (same look). ` +
-      `"${name}" is removed in 0.51.`,
-  );
-}
-
-/** @internal `primary` → `default`, `brand` → `accent` (warning once in development);
- *  every other variant as it is. Runs before every lookup keyed by the variant. */
-export function resolveButtonVariant(variant: ButtonVariant, component = "Button variant"): CanonicalButtonVariant {
-  const replacement = DEPRECATED_BUTTON_VARIANTS[variant];
-  if (replacement === undefined) return variant as CanonicalButtonVariant;
-  warnDeprecatedVariant(component, variant, replacement);
-  return replacement;
-}
+  | "link";
 
 // Shared base ring for every button-styled element. Kept as a named const so the
 // <Button> component and the {@link buttonClasses} helper draw from one source and
@@ -155,9 +108,8 @@ export const HOVER_INK = "hover:bg-[color-mix(in_srgb,var(--text-primary)_7%,tra
 // outline); `accent` is the solid brand fill for the rare strong CTA; `danger` takes the
 // semantic `--danger` family (destructive semantics), so a consumer can re-point the
 // destructive hue instead of inheriting a hard-coded red. Focus rings follow each
-// variant's own accent: brand for the four neutral ones, danger for `danger`. Keyed by
-// the canonical names: {@link resolveButtonVariant} maps the deprecated ones first.
-export const buttonVariantClasses: Record<CanonicalButtonVariant, string> = {
+// variant's own accent: brand for the four neutral ones, danger for `danger`.
+export const buttonVariantClasses: Record<ButtonVariant, string> = {
   default:
     // Hovers onto `--bg-active`, not `--border` (0.33, §12.9): More contrast steps the
     // border until it is a 3:1 LINE, and as a fill under the label that left 2.7:1.
@@ -223,12 +175,12 @@ const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
 };
 
 /** Only the two transparent variants take every tone; see {@link ButtonTone}. */
-const TONED_VARIANTS = new Set<CanonicalButtonVariant>(["link", "ghost"]);
+const TONED_VARIANTS = new Set<ButtonVariant>(["link", "ghost"]);
 
 // `tone="danger"` on the neutral boxed variants — see {@link ButtonTone}. Each string
 // restates every colour the variant sets (border, fill, text, hover, ring) so none of
 // the neutral ones survives the merge.
-const BUTTON_BOXED_DANGER: Partial<Record<CanonicalButtonVariant, string>> = {
+const BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {
   // Not boxed, but its hover is a fill: the danger wash under the danger text, as
   // IconButton's danger tone (0.33). On B′'s translucent ink `--danger` fell to 4.2:1
   // over a light page.
@@ -266,12 +218,11 @@ export interface ButtonClassesOptions {
  * compact toolbar links.
  */
 export function buttonClasses(
-  given: ButtonVariant = "default",
+  variant: ButtonVariant = "default",
   classNameOrOptions?: string | ButtonClassesOptions,
 ): string {
   const { size = "md", className } =
     typeof classNameOrOptions === "object" ? classNameOrOptions : { className: classNameOrOptions };
-  const variant = resolveButtonVariant(given, "buttonClasses variant");
   return cn(
     BUTTON_BASE,
     BUTTON_SIZES[size],
@@ -291,8 +242,7 @@ export const ICON_BUTTON_PRESSED =
   "bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted disabled:hover:bg-brand-soft disabled:hover:text-brand";
 
 /** @internal The button look shared by the `<button>` and the `<a>` form. */
-export function buttonLook(given: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {
-  const variant = resolveButtonVariant(given);
+export function buttonLook(variant: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {
   return cn(
     BUTTON_BASE,
     BUTTON_SIZES[size],

package/src/components/combobox.tsx

@@ -6,6 +6,7 @@ import { cn } from "../lib/cn";
 import { useDropdown } from "./dropdown";
 import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { isImeEnter } from "../lib/ime";
+import { isQuietFocus } from "../lib/quiet-focus";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import { ComboboxFieldLabel, endHintRowProps, GROUP_HEADING_STICKY, useActiveOptionScroll } from "./combobox-core";
@@ -421,11 +422,14 @@ export function Combobox(props: ComboboxProps) {
               autoFocus={autoFocus}
               onBlur={onBlur}
               onMouseDown={primaryOnly.onMouseDown}
-              onFocus={() => {
+              onFocus={(e) => {
                 // A back/forward mouse button focuses this field on its way to
                 // navigating; it is not a request to open anything (live #309 rework).
                 // A locked field takes focus to say why, and opens nothing.
                 if (primaryOnly.fromAuxButton() || locked) return;
+                // The tour's focus on arrival (§11.8) opens nothing: the list would cover
+                // its card (0.50.1). The click handler below still opens on a click.
+                if (isQuietFocus(e.currentTarget)) return;
                 setOpen(true);
                 setTyping(false);
                 // The sheet carries its own input, so the field behind it must not also

package/src/components/data-table-fit.ts

@@ -183,7 +183,10 @@ export function useColumnFit<T>({
     // update limit (#185). So a column whose return the next measure undid, at the same
     // scroller width, waits for more room than it had then: a wider scroller or narrower
     // content. Whatever the error in its width, that is one invisible flip per room it is
-    // tried at.
+    // tried at. (0.51, keksdose N2: under `virtualize` that excess was the table coming
+    // back at an OLD lock's ratcheted widths, not the ones measured here; the lock now goes
+    // when the columns change, data-table-virtual.ts. The guard stays for the rest: a
+    // column whose drawn cells are wider than its header.)
     let n = current.length;
     const rooms = new Map<string, number>();
     while (n > 0) {

package/src/components/data-table-virtual.ts

@@ -30,7 +30,9 @@ import type { RefObject } from "react";
 // nothing). Re-measured from scratch when the data, the columns, a user width, the text
 // size or the scroller's width change — and when a grown column would push the table
 // past its scroller, which it fit before. A `grow` column and a user-resized one are not
-// locked (the first takes the rest, the second is pinned already).
+// locked (the first takes the rest, the second is pinned already). A lock replaced is
+// gone: changing back (a column the fit leaves out and brings back) measures again
+// (0.51, keksdose N2).
 
 /** {@link DataTableProps.virtualize}'s options. */
 export interface DataTableVirtualize {
@@ -302,6 +304,17 @@ export function useRowWindow<T>({
   );
 
   const lockSig = `${resetKey}|${scrollerWidth}|${colKeys.join(",")}`;
+  // A lock is the table it was measured on, so it goes as soon as the signature moves on
+  // — not merely set aside until the signature comes BACK (0.51, keksdose N2). The fit
+  // leaves a column out and, measuring the table afresh without it, brings it back in the
+  // same frame, before this hook measures anything: the signature was then the old one
+  // again, and the column came back at the widths that had ratcheted up while rows
+  // scrolled (a wider cell widens its column once), 80–110px more than the fit had just
+  // measured (606 + 93 estimated, 778–812 drawn, at 757), and B2's guard kept it out
+  // although it fitted. Dropped here, the table it comes back to is drawn as measured,
+  // and the next frame locks that. Adjusted during render, as React's "storing
+  // information from previous renders": an effect would draw the stale widths first.
+  if (lock !== null && lock.sig !== lockSig) setLock(null);
   const colWidths = lock && lock.sig === lockSig ? lock.widths : null;
 
   // What the scroll handler and the frame's measure read: this render's model and lock.

package/src/components/field-base.tsx

@@ -21,7 +21,8 @@ import { DEFAULT_CHARACTER_COUNT_LABELS, DEFAULT_PASSWORD_REVEAL_LABELS } from "
  * `useFieldError`, every field's.
  *
  * Public through ./ui by name. `FieldGroup`, the counter and the placeholder helpers are
- * the three fields' shared parts (`@internal`).
+ * the three fields' shared parts (`@internal`), as are the Select's own classes and its
+ * `SelectWidthFloor` (0.51).
  */
 
 /**
@@ -197,6 +198,57 @@ export function FieldChevron({ className, ...rest }: FieldChevronProps) {
   );
 }
 
+/** A native dropdown Select's dress: no native arrow, and `pe-9`, the room the
+ *  {@link FieldChevron} takes. Shared with {@link SelectWidthFloor}. `@internal` */
+export const SELECT_MENU_DRESS = "appearance-none pe-9";
+
+/** The compact Select (`size="sm"`): the field's colours, a toolbar button's height.
+ *  `py-0` and a fixed height rather than a smaller padding, so the box is 28px whatever
+ *  line height the caller's type brings with it. Shared with {@link SelectWidthFloor}.
+ *  `@internal` */
+export const SELECT_SM = "h-7 py-0 ps-2 pe-7 text-xs";
+
+/**
+ * The width an UNLABELLED Select needs to show the widest of `values` whole: an invisible,
+ * zero-height line under it, in the select's own type, padding, chevron room and border
+ * (the same classes), one value per line. Placed beside the Select in the box that sizes
+ * it, it holds that box to the widest value, and the `w-full` select fills it. `@internal`
+ *
+ * Why it takes a sizer (0.51, Kurvenschmiede N5). A `<select>` with a percentage width
+ * is a "compressible" element: its min-content contribution is ZERO (CSS Sizing 3
+ * §5.2.2), so the auto table layout squeezes its column to the header, and beside a
+ * `grow` column every other column IS squeezed to its min-content (data-table-fit.ts).
+ * The user roster's role select stood 92px and read "Meml…" and "Admi…" (KS review,
+ * 0.49 and 0.50). `min-width: max-content` on the select would hold it instead — but to
+ * its widest OPTION, and an unavailable role's option carries its reason ("Customer (owns
+ * work)", RoleSelect's `optionDisabledReason`): the column would widen for a text that is
+ * never the selected value. So the caller says which values can be selected, in the
+ * current language.
+ */
+export function SelectWidthFloor({ values, size = "md" }: { values: readonly string[]; size?: "sm" | "md" }) {
+  if (values.length === 0) return null;
+  return (
+    <span
+      aria-hidden
+      data-select-floor=""
+      className={cn(
+        FIELD_BASE,
+        SELECT_MENU_DRESS,
+        size === "sm" && SELECT_SM,
+        // The horizontal box only: no height, no vertical padding or border, not painted.
+        "invisible h-0 overflow-hidden border-y-0 py-0 whitespace-nowrap shadow-none",
+      )}
+    >
+      {values.map((value, i) => (
+        // The value as generated content, not as text: it is laid out (and so measured)
+        // the same, but a test's `getByText("Member")` still finds the one option, and a
+        // find-in-page or a copied row does not meet a word nobody sees.
+        <span key={i} data-value={value} className="block before:content-[attr(data-value)]" />
+      ))}
+    </span>
+  );
+}
+
 // Animated label that starts centred (as a placeholder) in an empty field and
 // floats up INSIDE the top strip on focus or once the field has a value. Sits on
 // the field's own surface, so no background chip and nothing to mismatch the card.