@revenexx/studio-shared 0.3.3 → 0.4.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/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);
+}

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

@@ -0,0 +1,94 @@
+/**
+ * The decisions behind the shared form layout (PE-976), as pure functions.
+ *
+ * `FormLayout`, `FormSection`, `FieldGrid`, `FieldCell`, `FormContextCard` and
+ * `SaveBar` draw a form; this file decides the parts that have to agree across
+ * every surface that draws one — how wide a field is when nobody said, when the
+ * section navigation appears, which section the navigation marks while the
+ * page scrolls, and which grid tracks the layout gets. The Commerce renderer
+ * (mapping a manifest), hand-written cockpit forms and the manifest lint all
+ * read the same answers from here, so a phone number cannot be half width in
+ * one place and full width in another.
+ *
+ * The class strings live here as whole literals on purpose: Tailwind finds
+ * classes by scanning source text, so a class assembled at runtime from parts
+ * would never be generated. This directory is under the host's `@source`.
+ */
+/** How much of a two-column field grid a field takes. */
+export type FieldSpan = 'half' | 'full';
+/** The width a field of `fieldType` gets when nothing says otherwise. */
+export declare function defaultSpan(fieldType: string | null | undefined): FieldSpan;
+/** What `resolveSpan` reads — a manifest field fits, so does a hand-written one. */
+export interface SpanSource {
+    type?: string | null;
+    /** `auto` (or absent) means "the type decides". */
+    span?: 'auto' | FieldSpan | string | null;
+}
+/** An explicit `half` / `full` wins; `auto`, absent or unknown falls back to the type. */
+export declare function resolveSpan(field: SpanSource): FieldSpan;
+/**
+ * The grid-item class for a span inside `FieldGrid`.
+ *
+ * The grid is one column until its OWN width reaches the `@md` container size
+ * (28rem) and two above it — a container query, not a viewport breakpoint, so
+ * the same grid is right in a 512 px dialog, beside a section nav, and in a
+ * full-width page. A full field spans both tracks once there are two.
+ */
+export declare function spanClass(span: FieldSpan): string;
+/** Below this many sections a navigation is noise — the form fits in a glance. */
+export declare const SECTION_NAV_MIN = 3;
+/**
+ * Whether the left section navigation is drawn.
+ * `auto` = from {@link SECTION_NAV_MIN} sections on; a boolean forces it.
+ */
+export declare function showSectionNav(mode: boolean | 'auto', sectionCount: number): boolean;
+/** One section as the scroll spy sees it: its top edge, relative to the viewport of the scroller. */
+export interface SectionOffset {
+    id: string;
+    top: number;
+}
+/**
+ * Which section the navigation marks.
+ *
+ * The last section whose top edge has scrolled up to `threshold` (the line just
+ * under the sticky header) is the one being read. Two edges need a rule of
+ * their own: before anything has scrolled the first section is current even if
+ * it starts lower than the line, and once the scroller cannot move further the
+ * LAST section is current — a short final section can never reach the line,
+ * and a navigation that can never mark it reads as broken.
+ *
+ * `sections` must be in document order. Returns `null` for no sections.
+ */
+export declare function activeSectionId(sections: readonly SectionOffset[], options: {
+    threshold: number;
+    atEnd?: boolean;
+}): string | null;
+/** A scroller has reached its end, within a pixel or two of subpixel rounding. */
+export declare function isScrolledToEnd(scrollTop: number, clientHeight: number, scrollHeight: number): boolean;
+/**
+ * The tracks of the layout grid, by which side columns are present.
+ *
+ * The form column is capped at 48rem (~760 px, the mockup's readable width) and
+ * centred; the navigation is 10rem, the context column 16rem. Each side column
+ * only exists from the container width it fits at — the nav from `@3xl`
+ * (48rem), the context column from `@5xl` (64rem) — and below that the layout
+ * is the bare form column. Container queries again, because the space a form
+ * gets is the content pane beside a 256 px studio sidebar, not the window.
+ */
+export declare function layoutGridClass(nav: boolean, context: boolean): string;
+/** Visibility of the side columns, matching the breakpoints in {@link layoutGridClass}. */
+export declare const NAV_COLUMN_CLASS = "hidden @3xl:block";
+export declare const CONTEXT_COLUMN_CLASS = "hidden @5xl:block";
+/** One fact in a `FormContextCard`. Empty values render as an em dash. */
+export interface FormContextRow {
+    /** Stable key; the `value` slot receives the whole row. */
+    key: string;
+    label: string;
+    value?: string | number | null;
+}
+/**
+ * Up to two initials for an avatar: first letters of the first and last word (split on spaces, `-`, `_`),
+ * or the first two letters of a single word. Letters only — `"ACME GmbH (Test)"`
+ * reads as `AT`, not `A(`. Empty for nothing usable.
+ */
+export declare function initialsOf(name: string | null | undefined): string;

package/dist/runtime/lib/formLayout.js

@@ -0,0 +1,70 @@
+const FULL_WIDTH_TYPES = /* @__PURE__ */ new Set([
+  "textarea",
+  "json",
+  "key-value",
+  "multi-select",
+  "market-assignment",
+  "repeater",
+  "record-list",
+  "string-list",
+  "fieldset",
+  "rich-text",
+  "richtext",
+  "markdown",
+  "media",
+  "media-collection",
+  "image",
+  "localized-text",
+  "rules",
+  "record-view",
+  "address",
+  "tree-assign",
+  "line-selection"
+]);
+export function defaultSpan(fieldType) {
+  if (!fieldType) return "half";
+  return FULL_WIDTH_TYPES.has(fieldType.trim().toLowerCase()) ? "full" : "half";
+}
+export function resolveSpan(field) {
+  if (field.span === "half" || field.span === "full") return field.span;
+  return defaultSpan(field.type);
+}
+export function spanClass(span) {
+  return span === "full" ? "col-span-1 @md:col-span-2" : "col-span-1";
+}
+export const SECTION_NAV_MIN = 3;
+export function showSectionNav(mode, sectionCount) {
+  if (mode === "auto") return sectionCount >= SECTION_NAV_MIN;
+  return mode && sectionCount > 0;
+}
+export function activeSectionId(sections, options) {
+  if (!sections.length) return null;
+  if (options.atEnd) return sections[sections.length - 1].id;
+  let active = sections[0].id;
+  for (const section of sections) {
+    if (section.top <= options.threshold) active = section.id;
+    else break;
+  }
+  return active;
+}
+export function isScrolledToEnd(scrollTop, clientHeight, scrollHeight) {
+  if (scrollHeight <= clientHeight + 2) return false;
+  return scrollTop + clientHeight >= scrollHeight - 2;
+}
+export function layoutGridClass(nav, context) {
+  if (nav && context)
+    return "grid grid-cols-[minmax(0,48rem)] justify-center gap-6 @3xl:grid-cols-[10rem_minmax(0,48rem)] @5xl:grid-cols-[10rem_minmax(0,48rem)_16rem]";
+  if (nav)
+    return "grid grid-cols-[minmax(0,48rem)] justify-center gap-6 @3xl:grid-cols-[10rem_minmax(0,48rem)]";
+  if (context)
+    return "grid grid-cols-[minmax(0,48rem)] justify-center gap-6 @5xl:grid-cols-[minmax(0,48rem)_16rem]";
+  return "grid grid-cols-[minmax(0,48rem)] justify-center gap-6";
+}
+export const NAV_COLUMN_CLASS = "hidden @3xl:block";
+export const CONTEXT_COLUMN_CLASS = "hidden @5xl:block";
+export function initialsOf(name) {
+  const words = (name ?? "").split(/[\s_-]+/).map((w) => w.replace(/[^\p{L}\p{N}]/gu, "")).filter(Boolean);
+  if (!words.length) return "";
+  if (words.length === 1) return words[0].slice(0, 2).toUpperCase();
+  return (words[0][0] + words[words.length - 1][0]).toUpperCase();
+}

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

@@ -0,0 +1,26 @@
+/**
+ * What `FormLayout` shares with the parts inside it (PE-976).
+ *
+ * `FormSection` registers itself so the navigation is built from the sections
+ * actually on the page — their ids and titles, in document order — instead of a
+ * second list the page has to keep in step. `SaveBar` reads the grid tracks so
+ * its buttons line up under the form column rather than under the nav.
+ *
+ * Kept out of `components/` so the module's component scan never mistakes it
+ * for a component.
+ */
+import type { ComputedRef, InjectionKey } from 'vue';
+export interface FormSectionEntry {
+    id: string;
+    title: string;
+    el: () => HTMLElement | null;
+}
+export interface FormLayoutContext {
+    register: (entry: FormSectionEntry) => void;
+    unregister: (id: string) => void;
+    /** Grid classes of the layout row, reused by the save bar. */
+    gridClass: ComputedRef<string>;
+    navVisible: ComputedRef<boolean>;
+    contextVisible: ComputedRef<boolean>;
+}
+export declare const FORM_LAYOUT_KEY: InjectionKey<FormLayoutContext>;

package/dist/runtime/lib/formLayoutContext.js

@@ -0,0 +1 @@
+export const FORM_LAYOUT_KEY = Symbol("studio-shared.form-layout");

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

@@ -0,0 +1,38 @@
+/**
+ * Moving a row by dragging it, as arithmetic the table does not have to own.
+ *
+ * The DataTable only knows rows and keys. What a move MEANS — which position
+ * column is written, which rows have to change — is the surface's business, so
+ * the table answers one question and stops: "the operator put row X here; what
+ * is the order now?". Kept apart from the component so the edge cases are a
+ * test rather than something found by dragging.
+ */
+/** Which half of the row under the pointer the dragged row is dropped on. */
+export type DropEdge = 'before' | 'after';
+/**
+ * The edge of a row a pointer is nearest to.
+ *
+ * The middle of the row, not an arithmetic row height: a row whose label wraps
+ * is taller than its neighbours, and an index derived from "pointer offset ÷ 40
+ * pixels" puts the row one slot off on every list that has a long value in it.
+ */
+export declare function dropEdge(pointerY: number, rowTop: number, rowHeight: number): DropEdge;
+/**
+ * Where a row dragged from `from` lands when dropped on the `edge` of the row
+ * at `target`, as an index into the list WITHOUT the dragged row taken out.
+ *
+ * Returns null when the drop changes nothing — onto itself, or onto the edge
+ * it already touches (the bottom of the row above, the top of the row below).
+ * A move that changes nothing must not write anything, and it is easy to send
+ * two position updates for a row the operator merely picked up and put back.
+ */
+export declare function dropTargetIndex(from: number, target: number, edge: DropEdge): number | null;
+/** The keys in their new order, `from` moved to `to`. */
+export declare function moveKey<K>(keys: readonly K[], from: number, to: number): K[];
+/**
+ * The keyboard half of the same move: one step up or down, or null at an end.
+ *
+ * Dragging is a pointer gesture and cannot be the only way to reorder a list —
+ * the handle is a button, and the arrow keys on it move the row one place.
+ */
+export declare function stepTarget(from: number, delta: -1 | 1, length: number): number | null;

package/dist/runtime/lib/rowMove.js

@@ -0,0 +1,20 @@
+export function dropEdge(pointerY, rowTop, rowHeight) {
+  return pointerY < rowTop + rowHeight / 2 ? "before" : "after";
+}
+export function dropTargetIndex(from, target, edge) {
+  if (from < 0 || target < 0) return null;
+  const insertAt = edge === "before" ? target : target + 1;
+  const to = insertAt > from ? insertAt - 1 : insertAt;
+  return to === from ? null : to;
+}
+export function moveKey(keys, from, to) {
+  if (from < 0 || from >= keys.length || to < 0 || to >= keys.length || from === to) return [...keys];
+  const next = [...keys];
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved);
+  return next;
+}
+export function stepTarget(from, delta, length) {
+  const to = from + delta;
+  return to < 0 || to >= length ? null : to;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * GENERATED by `node scripts/icons.mjs`. Do not edit by hand.
+ *
+ * The closed set of Solar icons the cockpit resolves by name: every icon the
+ * app manifests, this repo's code and the curated picker set ask for. Named
+ * imports, so the bundle carries these 127 instead of all 1,413
+ * (PE-985). A name outside the set renders the fallback glyph; run
+ * `pnpm icons` after adding one, and `pnpm icons:check` to verify.
+ */
+import type { Component } from 'vue';
+export declare const SOLAR_ICON_MAP: Readonly<Record<string, Component>>;
+/** Manifest names Solar does not have → the glyph drawn for them. */
+export declare const SOLAR_ICON_ALIASES: Readonly<Record<string, string>>;
+/** Drawn for a name outside the map. */
+export declare const SOLAR_FALLBACK_ICON: Component;