@revenexx/studio-shared 0.3.2 → 0.4.0

package/dist/runtime/composables/useDetailSheet.d.ts

@@ -0,0 +1,20 @@
+import type { ComputedRef, MaybeRefOrGetter, WritableComputedRef } from 'vue';
+export interface DetailSheetBinding {
+    /** The open record's id, or `null` when the panel is shut. */
+    openId: ComputedRef<string | null>;
+    /** For `v-model:open` — writing `false` closes. */
+    isOpen: WritableComputedRef<boolean>;
+    open: (id: string) => void;
+    close: () => void;
+    /** Move to the neighbouring record in `ids`; a no-op at either end. */
+    step: (dir: -1 | 1) => void;
+    /** Whether `step(-1)` / `step(1)` would land anywhere — for the panel's arrow buttons. */
+    canStep: ComputedRef<{
+        prev: boolean;
+        next: boolean;
+    }>;
+}
+export declare function useDetailSheet(key: string, options?: {
+    /** The records in the order the list shows them, for `step`. */
+    ids?: MaybeRefOrGetter<readonly string[]>;
+}): DetailSheetBinding;

package/dist/runtime/composables/useDetailSheet.js

@@ -0,0 +1,50 @@
+import { computed, toValue, watch } from "vue";
+import { idFromQuery, neighbourId, queryWith } from "../lib/detailSheet.js";
+const MARKER = "detailSheet";
+export function useDetailSheet(key, options = {}) {
+  const route = useRoute();
+  const router = useRouter();
+  const openId = computed(() => idFromQuery(route.query[key]));
+  function pushedHere() {
+    if (typeof window === "undefined") return false;
+    return window.history.state?.[MARKER] === key;
+  }
+  let closing = false;
+  watch(openId, (id) => {
+    if (id === null) closing = false;
+  });
+  function open(id) {
+    if (openId.value === id) return;
+    closing = false;
+    const query = queryWith(route.query, key, id);
+    if (openId.value === null) {
+      void router.push({ query, state: { [MARKER]: key } });
+    } else {
+      void router.replace({ query, state: pushedHere() ? { [MARKER]: key } : {} });
+    }
+  }
+  function close() {
+    if (openId.value === null || closing) return;
+    closing = true;
+    if (pushedHere()) router.back();
+    else void router.replace({ query: queryWith(route.query, key, null) });
+  }
+  function step(dir) {
+    const next = neighbourId(toValue(options.ids) ?? [], openId.value, dir);
+    if (next !== null) open(next);
+  }
+  const canStep = computed(() => {
+    const ids = toValue(options.ids) ?? [];
+    return {
+      prev: neighbourId(ids, openId.value, -1) !== null,
+      next: neighbourId(ids, openId.value, 1) !== null
+    };
+  });
+  const isOpen = computed({
+    get: () => openId.value !== null,
+    set: (v) => {
+      if (!v) close();
+    }
+  });
+  return { openId, isOpen, open, close, step, canStep };
+}

package/dist/runtime/composables/usePlatformTenant.d.ts

@@ -9,6 +9,12 @@ import type { Ref } from 'vue';
  */
 export interface PlatformTenant {
     slug: Ref<string | null>;
+    /**
+     * Resolves once the active tenant is known, or once it is clear there is
+     * none yet (bounded — the host decides how long). Never throws. Callers that
+     * send tenant-scoped requests use `requirePlatformTenant` from
+     * `@revenexx/studio-shared/lib/activeTenant` instead of reading `slug`.
+     */
     load: () => Promise<void>;
 }
 export declare function usePlatformTenant(): PlatformTenant;

package/dist/runtime/composables/useSavedViews.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Saved-views storage provider — the DEFAULT (PE-608).
+ *
+ * ## Why this is a seam and not just an API call
+ *
+ * `SavedViewsMenu` ships inside `@revenexx/studio-shared`, which is published
+ * into hosts that have no cockpit backend: the standalone Commerce Studio dev
+ * host, and anything else that installs the module for its DataTable. So the
+ * component cannot reach for `/api/cockpit/saved-views` — it would 404 in every
+ * host but one, and the control would be permanently broken there.
+ *
+ * Same shape as `usePlatformAuth`, `usePlatformTenant` and `useMediaLibrary`:
+ * this file is the default, registered at `priority: -1`, and the cockpit ships
+ * a same-named app-level composable that wins. Here, views are kept in
+ * `localStorage`, which is exactly what the menu did before — so a bare host
+ * behaves as it always has, and only the cockpit gains the account-backed copy.
+ *
+ * ## Why `id` exists in a localStorage implementation
+ *
+ * The server keys a view by a uuid and the menu deletes by it. Making the local
+ * store agree means the component has one code path instead of two, and a
+ * `name`-keyed delete cannot be quietly wrong about which of two views with the
+ * same name it removed. The id is derived from the surface and the name, which
+ * is stable across reloads and is all the uniqueness a browser-local store has.
+ */
+/** One named snapshot of how a list was narrowed. */
+export interface StoredSavedView {
+    id: string;
+    name: string;
+    snapshot: unknown;
+}
+export interface SavedViewsStore {
+    /** Read this surface's views. Never throws — a failure is an empty list. */
+    list: (surface: string) => Promise<StoredSavedView[]>;
+    /** Save under a name, replacing what that name held. */
+    save: (surface: string, name: string, snapshot: unknown) => Promise<StoredSavedView>;
+    remove: (surface: string, id: string) => Promise<void>;
+    /**
+     * Does this store survive a new browser? The menu says so in one line, so
+     * "saved to your account" and "saved in this browser only" stay honest.
+     */
+    readonly durable: boolean;
+}
+export declare function useSavedViews(): SavedViewsStore;

package/dist/runtime/composables/useSavedViews.js

@@ -0,0 +1,44 @@
+function localId(surface, name) {
+  return `local:${surface}::${name}`;
+}
+function readAll(surface) {
+  try {
+    if (typeof window === "undefined") return [];
+    const raw = window.localStorage.getItem(surface);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((v) => !!v && typeof v === "object" && typeof v.name === "string").map((v) => ({ id: localId(surface, v.name), name: v.name, snapshot: v.snapshot }));
+  } catch {
+    return [];
+  }
+}
+function writeAll(surface, views) {
+  try {
+    if (typeof window === "undefined") return;
+    window.localStorage.setItem(surface, JSON.stringify(
+      views.map((v) => ({ name: v.name, snapshot: v.snapshot }))
+    ));
+  } catch {
+  }
+}
+export function useSavedViews() {
+  return {
+    durable: false,
+    async list(surface) {
+      return readAll(surface);
+    },
+    async save(surface, name, snapshot) {
+      const views = readAll(surface);
+      const entry = { id: localId(surface, name), name, snapshot };
+      const at = views.findIndex((v) => v.name === name);
+      if (at >= 0) views.splice(at, 1, entry);
+      else views.push(entry);
+      writeAll(surface, views);
+      return entry;
+    },
+    async remove(surface, id) {
+      writeAll(surface, readAll(surface).filter((v) => v.id !== id));
+    }
+  };
+}

package/dist/runtime/composables/useStickyListView.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The narrowing a list was left in, kept across a page change (PE-608).
+ *
+ * Leaving a list to open a record — or to check another one — and coming back
+ * to an unfiltered table is the small tax every operator pays repeatedly: they
+ * re-tick the same facets, re-pick the same sort, and do it again the next
+ * time. The state is already a snapshot (it is what a saved view stores), so
+ * remembering the last one per surface costs nothing new.
+ *
+ * ## Why `sessionStorage` and not `localStorage`
+ *
+ * This is the decision worth arguing, because both are defensible and only one
+ * of them is safe by default.
+ *
+ * A sticky filter is a known way to lose people. An operator opens Orders, sees
+ * three rows out of twenty-three thousand, and concludes the data is gone —
+ * because the filter that did it was set last Tuesday and nothing on screen
+ * looks like an answer to "why is this list short". That is a support ticket,
+ * and a scary one.
+ *
+ * Two things make it safe here rather than merely convenient:
+ *
+ *  1. **It is visible.** The chip strip under the toolbar names every applied
+ *     value and the trigger is lit. A restored narrowing announces itself; the
+ *     version of this feature that is dangerous is the one you cannot see.
+ *  2. **It ends with the tab.** `sessionStorage` survives a navigation and a
+ *     reload — which is what "come back to the list" means — and is gone when
+ *     the tab closes. Tomorrow morning is a fresh list. `localStorage` would
+ *     carry Friday's filter into Monday, and `localStorage` is also what the
+ *     saved views deliberately stopped being: a durable narrowing is a thing
+ *     you NAME and store on your account, not something a list does to you.
+ *
+ * So: sticky within a session, explicit across them. Swapping the two is one
+ * identifier if that trade ever reads differently.
+ *
+ * ## What it does not do
+ *
+ * It does not write the URL. A link to a list is a link to the list, not to how
+ * one person last left it — pasting a narrowed URL into a ticket and having a
+ * colleague see something else is worse than either behaviour here. The queue
+ * pills are the linkable half, and they already carry `?queue=` on purpose.
+ */
+export interface StickyListView<T> {
+    /**
+     * The snapshot this surface was last left in, or `null`.
+     *
+     * Read once, deliberately: a surface restores on mount and owns its state
+     * from then on. A reactive value here would fight the surface for it.
+     */
+    read: () => T | null;
+    /** Remember the current snapshot. Call it whenever the surface's state moves. */
+    write: (snapshot: T) => void;
+    /** Forget this surface's state — what a "reset" should also do. */
+    clear: () => void;
+}
+/**
+ * @param key A stable identifier for the surface — the same route pattern the
+ *   saved views are keyed by, so two lists never share a memory.
+ */
+export declare function useStickyListView<T>(key: string): StickyListView<T>;

package/dist/runtime/composables/useStickyListView.js

@@ -0,0 +1,32 @@
+const VERSION = 1;
+export function useStickyListView(key) {
+  const storageKey = `commerce.listState.${key}`;
+  return {
+    read() {
+      try {
+        if (typeof window === "undefined") return null;
+        const raw = window.sessionStorage.getItem(storageKey);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.v !== VERSION) return null;
+        return parsed.snapshot ?? null;
+      } catch {
+        return null;
+      }
+    },
+    write(snapshot) {
+      try {
+        if (typeof window === "undefined") return;
+        window.sessionStorage.setItem(storageKey, JSON.stringify({ v: VERSION, snapshot }));
+      } catch {
+      }
+    },
+    clear() {
+      try {
+        if (typeof window === "undefined") return;
+        window.sessionStorage.removeItem(storageKey);
+      } catch {
+      }
+    }
+  };
+}

package/dist/runtime/lib/activeTenant.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The active tenant, as every tenant-scoped client sends it (PE-828).
+ *
+ * The contract the Cockpit shares with Console, Baseline and every gateway:
+ * each tenant-scoped request carries the active tenant slug in a header, and
+ * the service checks it against the token. The header only SELECTS a tenant
+ * the token already holds; it never grants one.
+ *
+ * Before this helper each client had its own copy of "send the header if we
+ * happen to know the slug", and most of them sent the request without it while
+ * the top-bar selection was still resolving. In an org with two tenants that
+ * is an ambiguous request, which the services answer with 400/403/422.
+ *
+ * So the rule is now one function: wait (bounded) for the active tenant, and
+ * refuse to send a tenant-scoped request when there is none. A missing tenant
+ * is a `NoActiveTenantError`, which the UI shows as "pick a tenant".
+ *
+ * Pure (Vue only), so the cockpit, studio-commerce and their tests share it.
+ */
+import { type Ref } from 'vue';
+/** The header the platform, Console, Baseline and most gateways read. */
+export declare const TENANT_HEADER = "X-Revenexx-Tenant";
+/** The header the AI gateway, Aria and integrations read instead. */
+export declare const TENANT_ID_HEADER = "X-Tenant-Id";
+/** How long a request waits for the active tenant before it gives up. */
+export declare const TENANT_WAIT_MS = 8000;
+export declare class NoActiveTenantError extends Error {
+    readonly status = 400;
+    readonly code = "no_active_tenant";
+    constructor(message?: string);
+}
+/** True for the error `requireTenant` throws, across bundle copies. */
+export declare function isNoActiveTenant(err: unknown): err is NoActiveTenantError;
+/**
+ * Wait for a shared ref to hold a value, bounded (RAD-182).
+ *
+ * Loads what can be loaded, then waits until the value arrives or `timeoutMs`
+ * passes. Resolves null on timeout; never throws.
+ */
+export declare function waitForValue<T>(source: Ref<T | null | undefined>, load: () => Promise<unknown>, timeoutMs?: number): Promise<T | null>;
+/** Anything that can name the active tenant: `useConsoleTenants`, `usePlatformTenant`. */
+export interface TenantSource {
+    slug: Ref<string | null>;
+    load: () => Promise<unknown>;
+}
+/**
+ * The active tenant slug, or a `NoActiveTenantError`.
+ *
+ * Never returns null: a caller that gets past this line has a tenant to send.
+ */
+export declare function requireTenant(source: TenantSource, timeoutMs?: number): Promise<string>;
+/**
+ * The active tenant from a `usePlatformTenant()` seam, or a `NoActiveTenantError`.
+ *
+ * The seam's `load` already waits for the selection (the host bounds it), so
+ * nothing is waited for twice here.
+ */
+export declare function requirePlatformTenant(tenant: TenantSource): Promise<string>;

package/dist/runtime/lib/activeTenant.js

@@ -0,0 +1,45 @@
+import { watch } from "vue";
+export const TENANT_HEADER = "X-Revenexx-Tenant";
+export const TENANT_ID_HEADER = "X-Tenant-Id";
+export const TENANT_WAIT_MS = 8e3;
+export class NoActiveTenantError extends Error {
+  status = 400;
+  code = "no_active_tenant";
+  constructor(message = "No active tenant. Pick one in the top bar.") {
+    super(message);
+    this.name = "NoActiveTenantError";
+  }
+}
+export function isNoActiveTenant(err) {
+  return err?.code === "no_active_tenant";
+}
+export async function waitForValue(source, load, timeoutMs = TENANT_WAIT_MS) {
+  if (source.value) return source.value;
+  try {
+    await load();
+  } catch {
+  }
+  if (source.value) return source.value;
+  if (timeoutMs <= 0) return null;
+  return await new Promise((resolve) => {
+    let stop = null;
+    const timer = setTimeout(() => {
+      stop?.();
+      resolve(null);
+    }, timeoutMs);
+    stop = watch(source, (value) => {
+      if (!value) return;
+      clearTimeout(timer);
+      stop?.();
+      resolve(value);
+    });
+  });
+}
+export async function requireTenant(source, timeoutMs = TENANT_WAIT_MS) {
+  const slug = await waitForValue(source.slug, source.load, timeoutMs);
+  if (!slug) throw new NoActiveTenantError();
+  return slug;
+}
+export function requirePlatformTenant(tenant) {
+  return requireTenant(tenant, 0);
+}

package/dist/runtime/lib/appIcon.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What an app's icon is, read from the one field the manifest documents (PE-560).
+ *
+ * `manifest.icon` is either a FILE or a SOLAR ICON NAME, told apart by shape:
+ *
+ *  - a file contains a `/` or ends in `.svg`, `.png` or `.webp` — a URL, a
+ *    `data:` URI, or a path the registry has resolved to one;
+ *  - a Solar name is kebab-case (`money-bag`), the same token a `cockpit.json`
+ *    navigation entry carries.
+ *
+ * Anything else is neither and is skipped. The Cockpit used to read the field
+ * three ways — a Solar name in the sidebar, an `<img src>` on the installed
+ * pages, not at all in the Marketplace — so no value rendered everywhere, and
+ * no app shipped one.
+ *
+ * Pure on purpose: the Solar registry lookup lives in `solarIcons.ts`, so this
+ * module has no imports and is testable without a Nuxt alias.
+ */
+export type AppIconSource = {
+    kind: 'file';
+    src: string;
+} | {
+    kind: 'solar';
+    name: string;
+};
+/**
+ * `money-bag` → `MoneyBag`, the export name in the Solar registry. Snake case
+ * (`card_2`) and the export name itself (`Layers`) read the same way.
+ * `scripts/icons.mjs` carries a copy (`exportName`) and must agree with it.
+ */
+export declare function solarExportName(name: string): string;
+/** How one `manifest.icon` value reads, or null when it is neither shape. */
+export declare function readAppIcon(value: string | null | undefined): AppIconSource | null;
+/**
+ * The Solar name of the first `cockpit.json` navigation entry that has one —
+ * the glyph the app already shows in its host studio's sidebar, and the
+ * fallback for the apps that set no `manifest.icon`.
+ */
+export declare function firstNavIcon(navigation: ReadonlyArray<{
+    icon?: string | null;
+}> | null | undefined): string | null;
+/**
+ * Every source to try, in order: `manifest.icon` (file or Solar name), then the
+ * navigation glyph. The renderer walks the list and draws the first that
+ * resolves — an image that fails to load, or a name the registry lacks, falls
+ * through to the next, and past the end to the generic glyph.
+ */
+export declare function appIconCandidates(icon: string | null | undefined, navIcon?: string | null): AppIconSource[];

package/dist/runtime/lib/appIcon.js

@@ -0,0 +1,27 @@
+const FILE_EXTENSION = /\.(?:svg|png|webp)$/i;
+const SOLAR_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function solarExportName(name) {
+  return name.replace(/(^|[-_])([a-z0-9])/gi, (_m, _sep, ch) => ch.toUpperCase());
+}
+export function readAppIcon(value) {
+  const v = value?.trim();
+  if (!v) return null;
+  if (v.includes("/") || FILE_EXTENSION.test(v)) return { kind: "file", src: v };
+  if (SOLAR_NAME.test(v)) return { kind: "solar", name: v };
+  return null;
+}
+export function firstNavIcon(navigation) {
+  for (const item of navigation ?? []) {
+    const icon = item.icon?.trim();
+    if (icon) return icon;
+  }
+  return null;
+}
+export function appIconCandidates(icon, navIcon) {
+  const out = [];
+  const own = readAppIcon(icon);
+  if (own) out.push(own);
+  const nav = navIcon?.trim();
+  if (nav && !(own?.kind === "solar" && own.name === nav)) out.push({ kind: "solar", name: nav });
+  return out;
+}

package/dist/runtime/lib/canonicalJson.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A stable string for any JSON value, for comparing two of them (PE-608).
+ *
+ * ## The bug this exists for
+ *
+ * `SavedViewsMenu` decides whether a stored view is the one currently applied
+ * by comparing snapshots, and it compared them with `JSON.stringify`. That
+ * works exactly as long as both sides were built by the same code in the same
+ * order — which stopped being true the moment saved views moved into Postgres.
+ *
+ * `jsonb` does not preserve key order; it normalises it. So a surface that
+ * builds `{ filters, sort }` gets `{ sort, filters }` back from the database,
+ * the two strings differ, and the applied view is never recognised as applied.
+ * Nothing throws and nothing looks broken — the menu simply never marks
+ * anything, and the trigger never shows that a view is in effect. It is the
+ * kind of defect that survives review because the code reads as obviously
+ * correct.
+ *
+ * ## What "canonical" means here
+ *
+ * Object keys sorted, recursively. Arrays left alone, because their order IS
+ * their meaning — `["a","b"]` and `["b","a"]` are different filter values as
+ * far as a query is concerned, and a facet that wants them treated as a set
+ * sorts them before it stores them.
+ *
+ * `undefined` is dropped from objects, exactly as `JSON.stringify` does, so an
+ * absent key and an explicitly-undefined one compare equal. That matters:
+ * `{ queue: undefined }` is what a spread produces for a surface with no queue,
+ * and the server round-trips it as an absent key.
+ */
+/**
+ * Deterministic JSON for `value` — same input, same string, whatever order the
+ * keys arrived in.
+ *
+ * A cycle would make this recurse forever, so it is caught and reported as a
+ * sentinel rather than thrown: the one caller is a comparison in a computed,
+ * and a snapshot is not worth crashing a toolbar over. Two cyclic values
+ * compare equal, which is wrong but harmless — and a snapshot with a cycle
+ * could never have been stored in the first place.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Do two JSON values mean the same thing, whatever order their keys are in? */
+export declare function sameJson(a: unknown, b: unknown): boolean;

package/dist/runtime/lib/canonicalJson.js

@@ -0,0 +1,38 @@
+export function canonicalJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk = (input) => {
+    if (input === null) return "null";
+    const type = typeof input;
+    if (type === "number") return Number.isFinite(input) ? String(input) : "null";
+    if (type === "boolean") return String(input);
+    if (type === "string") return JSON.stringify(input);
+    if (type === "undefined" || type === "function" || type === "symbol") return "undefined";
+    if (type === "bigint") return JSON.stringify(String(input));
+    const object = input;
+    if (seen.has(object)) return '"[cycle]"';
+    seen.add(object);
+    try {
+      if (Array.isArray(object)) {
+        return `[${object.map((item) => {
+          const part = walk(item);
+          return part === "undefined" ? "null" : part;
+        }).join(",")}]`;
+      }
+      if (object instanceof Date) return JSON.stringify(object.toISOString());
+      const parts = [];
+      for (const key of Object.keys(object).sort()) {
+        const part = walk(object[key]);
+        if (part === "undefined") continue;
+        parts.push(`${JSON.stringify(key)}:${part}`);
+      }
+      return `{${parts.join(",")}}`;
+    } finally {
+      seen.delete(object);
+    }
+  };
+  const out = walk(value);
+  return out === "undefined" ? "null" : out;
+}
+export function sameJson(a, b) {
+  return canonicalJson(a) === canonicalJson(b);
+}

package/dist/runtime/lib/dashboardIcons.d.ts

@@ -0,0 +1,4 @@
+export declare const DASHBOARD_ICONS: Record<string, unknown>;
+/** Every name the picker may offer, in a stable order. */
+export declare const PICKABLE_ICONS: string[];
+export declare function dashboardIcon(name?: string): unknown;

package/dist/runtime/lib/dashboardIcons.js

@@ -0,0 +1,50 @@
+import {
+  Bag,
+  BillList,
+  Bolt,
+  Box,
+  Card,
+  Cart,
+  ChartSquare,
+  ClipboardList,
+  DangerTriangle,
+  Earth,
+  GraphUp,
+  Hashtag,
+  Home,
+  Layers,
+  List,
+  MagicStick,
+  NotebookMinimalistic,
+  Pulse,
+  Routing,
+  UsersGroupRounded,
+  Widget
+} from "#solar-icons";
+export const DASHBOARD_ICONS = {
+  Bag,
+  BillList,
+  Bolt,
+  Box,
+  Card,
+  Cart,
+  ChartSquare,
+  ClipboardList,
+  DangerTriangle,
+  Earth,
+  GraphUp,
+  Hashtag,
+  Home,
+  Layers,
+  List,
+  MagicStick,
+  NotebookMinimalistic,
+  Pulse,
+  Routing,
+  UsersGroupRounded,
+  Widget
+};
+export const PICKABLE_ICONS = Object.keys(DASHBOARD_ICONS);
+export function dashboardIcon(name) {
+  return name && DASHBOARD_ICONS[name] || Widget;
+}

package/dist/runtime/lib/detailSheet.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The parts of `DetailSheet` that are arithmetic rather than UI (PE-691).
+ *
+ * Kept out of the component and the composable so they can be tested without a
+ * router or a DOM: which record is next, what the query looks like with the
+ * panel open or shut, and whether a keypress belongs to the panel or to the
+ * control it landed on.
+ */
+export type QueryValue = string | null | (string | null)[] | undefined;
+export type Query = Record<string, QueryValue>;
+/** The open record id from a query value — the first one if a link repeats it. */
+export declare function idFromQuery(value: QueryValue): string | null;
+/** `query` with `key` set to `id`, or without `key` when `id` is null. */
+export declare function queryWith(query: Query, key: string, id: string | null): Query;
+/**
+ * The id `step` places away from `current` in `ids`, or null at either end.
+ *
+ * No wrap-around: arrowing past the last row and landing on the first reads as
+ * the list having jumped, and in a paginated list the first row is not even on
+ * the page. An id that is no longer in the list (deleted, filtered out) has no
+ * neighbours either — guessing one would open a record nobody pointed at.
+ */
+export declare function neighbourId(ids: readonly string[], current: string | null, step: -1 | 1): string | null;
+interface KeyEvent {
+    key: string;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    defaultPrevented?: boolean;
+    target?: unknown;
+}
+/**
+ * Whether the focused element handles arrows and Escape itself: a text field
+ * (caret, clearing), a select, a menu, a listbox, a slider. The panel's keys
+ * give way there — taking them would break the control to save one click.
+ */
+export declare function targetOwnsKeys(target: unknown): boolean;
+/** Whether ArrowUp/ArrowDown should move to the neighbouring record, and which way. */
+export declare function isRecordStepKey(ev: KeyEvent): -1 | 1 | null;
+/** Whether Escape should close the panel rather than the control it landed on. */
+export declare function isCloseKey(ev: KeyEvent): boolean;
+export {};

package/dist/runtime/lib/detailSheet.js

@@ -0,0 +1,34 @@
+export function idFromQuery(value) {
+  const v = Array.isArray(value) ? value[0] : value;
+  return typeof v === "string" && v !== "" ? v : null;
+}
+export function queryWith(query, key, id) {
+  const next = { ...query };
+  if (id === null) delete next[key];
+  else next[key] = id;
+  return next;
+}
+export function neighbourId(ids, current, step) {
+  if (current === null) return null;
+  const i = ids.indexOf(current);
+  if (i < 0) return null;
+  return ids[i + step] ?? null;
+}
+export function targetOwnsKeys(target) {
+  const t = target;
+  if (!t) return false;
+  const tag = (t.tagName ?? "").toUpperCase();
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (t.isContentEditable) return true;
+  return !!t.closest?.('[role="menu"],[role="listbox"],[role="combobox"],[role="slider"],[role="spinbutton"],[role="radiogroup"],[role="tablist"]');
+}
+export function isRecordStepKey(ev) {
+  if (ev.defaultPrevented) return null;
+  if (ev.altKey || ev.ctrlKey || ev.metaKey || ev.shiftKey) return null;
+  const step = ev.key === "ArrowDown" ? 1 : ev.key === "ArrowUp" ? -1 : null;
+  if (step === null) return null;
+  return targetOwnsKeys(ev.target) ? null : step;
+}
+export function isCloseKey(ev) {
+  return ev.key === "Escape" && !ev.defaultPrevented && !targetOwnsKeys(ev.target);
+}