@revenexx/studio-shared 0.3.2 → 0.4.0

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;

package/dist/runtime/lib/solarIconMap.js

@@ -0,0 +1,280 @@
+import {
+  AddCircle,
+  AddSquare,
+  Alarm,
+  Archive,
+  ArrowRight,
+  Atom,
+  Backspace,
+  Bag,
+  BagCheck,
+  Bell,
+  Bill,
+  BillList,
+  Bolt,
+  Book,
+  Bookmark,
+  Box,
+  BranchingPathsUp,
+  Broom,
+  Buildings,
+  Calendar,
+  CalendarMinimalistic,
+  Card,
+  CardTransfer,
+  Cart,
+  CartLarge,
+  CartPlus,
+  Chart,
+  Chart2,
+  ChartSquare,
+  ChatRound,
+  ChatRoundLine,
+  CheckCircle,
+  CheckRead,
+  ChecklistMinimalistic,
+  Clipboard,
+  ClipboardList,
+  ClockCircle,
+  CloseCircle,
+  Code,
+  Copy,
+  Cpu,
+  DangerTriangle,
+  Database,
+  Delivery,
+  Document,
+  DocumentText,
+  Download,
+  DownloadMinimalistic,
+  Earth,
+  Eye,
+  File,
+  FileText,
+  Folder,
+  FolderOpen,
+  FolderPathConnect,
+  Forbidden,
+  Gallery,
+  GalleryMinimalistic,
+  Global,
+  GraphDown,
+  GraphUp,
+  Hashtag,
+  Heart,
+  Help,
+  Home,
+  Import,
+  Inbox,
+  InboxIn,
+  Key,
+  Layers,
+  Letter,
+  Lightbulb,
+  Link,
+  LinkRound,
+  List,
+  ListCheck,
+  Lock,
+  MagicStick,
+  Magnifer,
+  Map,
+  MapPoint,
+  MedalRibbon,
+  MoneyBag,
+  Notebook,
+  NotebookMinimalistic,
+  Palette,
+  Pause,
+  Pen,
+  Plain,
+  Play,
+  PlugCircle,
+  Pulse,
+  Radar,
+  Refresh,
+  RefreshCircle,
+  Restart,
+  RewindBackCircle,
+  Routing,
+  Ruler,
+  Scale,
+  Server,
+  Settings,
+  Shield,
+  ShieldCheck,
+  ShieldCross,
+  ShieldUser,
+  Shop,
+  Shuffle,
+  Star,
+  Stars,
+  Tag,
+  TagPrice,
+  Ticket,
+  TrashBinMinimalistic,
+  TrashBinTrash,
+  UndoLeftRound,
+  Upload,
+  User,
+  UserBlock,
+  UserCheck,
+  UserId,
+  UsersGroupRounded,
+  Wallet,
+  WalletMoney,
+  Weigher,
+  Widget,
+  Widget5
+} from "#solar-icons";
+export const SOLAR_ICON_MAP = {
+  AddCircle,
+  AddSquare,
+  Alarm,
+  Archive,
+  ArrowRight,
+  Atom,
+  Backspace,
+  Bag,
+  BagCheck,
+  Bell,
+  Bill,
+  BillList,
+  Bolt,
+  Book,
+  Bookmark,
+  Box,
+  BranchingPathsUp,
+  Broom,
+  Buildings,
+  Calendar,
+  CalendarMinimalistic,
+  Card,
+  CardTransfer,
+  Cart,
+  CartLarge,
+  CartPlus,
+  Chart,
+  Chart2,
+  ChartSquare,
+  ChatRound,
+  ChatRoundLine,
+  CheckCircle,
+  CheckRead,
+  ChecklistMinimalistic,
+  Clipboard,
+  ClipboardList,
+  ClockCircle,
+  CloseCircle,
+  Code,
+  Copy,
+  Cpu,
+  DangerTriangle,
+  Database,
+  Delivery,
+  Document,
+  DocumentText,
+  Download,
+  DownloadMinimalistic,
+  Earth,
+  Eye,
+  File,
+  FileText,
+  Folder,
+  FolderOpen,
+  FolderPathConnect,
+  Forbidden,
+  Gallery,
+  GalleryMinimalistic,
+  Global,
+  GraphDown,
+  GraphUp,
+  Hashtag,
+  Heart,
+  Help,
+  Home,
+  Import,
+  Inbox,
+  InboxIn,
+  Key,
+  Layers,
+  Letter,
+  Lightbulb,
+  Link,
+  LinkRound,
+  List,
+  ListCheck,
+  Lock,
+  MagicStick,
+  Magnifer,
+  Map,
+  MapPoint,
+  MedalRibbon,
+  MoneyBag,
+  Notebook,
+  NotebookMinimalistic,
+  Palette,
+  Pause,
+  Pen,
+  Plain,
+  Play,
+  PlugCircle,
+  Pulse,
+  Radar,
+  Refresh,
+  RefreshCircle,
+  Restart,
+  RewindBackCircle,
+  Routing,
+  Ruler,
+  Scale,
+  Server,
+  Settings,
+  Shield,
+  ShieldCheck,
+  ShieldCross,
+  ShieldUser,
+  Shop,
+  Shuffle,
+  Star,
+  Stars,
+  Tag,
+  TagPrice,
+  Ticket,
+  TrashBinMinimalistic,
+  TrashBinTrash,
+  UndoLeftRound,
+  Upload,
+  User,
+  UserBlock,
+  UserCheck,
+  UserId,
+  UsersGroupRounded,
+  Wallet,
+  WalletMoney,
+  Weigher,
+  Widget,
+  Widget5
+};
+export const SOLAR_ICON_ALIASES = {
+  "activity": "Pulse",
+  "building": "Buildings",
+  "check": "CheckCircle",
+  "clock": "ClockCircle",
+  "edit": "Pen",
+  "file-search": "FileText",
+  "folder-tree": "FolderPathConnect",
+  "git-merge": "BranchingPathsUp",
+  "plug": "PlugCircle",
+  "plus": "AddCircle",
+  "puzzle": "Widget",
+  "receipt": "Bill",
+  "send": "Plain",
+  "shield-x": "ShieldCross",
+  "shopping-cart": "Cart",
+  "slash": "Forbidden",
+  "sparkles": "Stars",
+  "trending-down": "GraphDown",
+  "users": "UsersGroupRounded"
+};
+export const SOLAR_FALLBACK_ICON = Widget;

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

@@ -0,0 +1,37 @@
+/**
+ * A Solar icon by the name an app manifest uses for it (`money-bag`).
+ *
+ * The one lookup behind every surface that draws a glyph by NAME — the Apps and
+ * Commerce sidebars, `AppIcon`, and the Commerce renderer's tiles, buttons,
+ * empty states and option icons. It was copy-pasted into each of them before
+ * PE-560 and PE-985.
+ *
+ * The names resolve against a CLOSED map (`solarIconMap.ts`, generated by
+ * `scripts/icons.mjs` from the app manifests and this repo's code), not the
+ * whole icon set: a namespace import put all 1,413 Solar icons into the boot
+ * bundle, 11.66 MB of JS, for the ~130 anything asks for (PE-985).
+ *
+ * Two lookups, because callers want different things from a miss:
+ *
+ *  - {@link solarIcon} returns `undefined`, for callers that have their own
+ *    next candidate (`AppIcon` walks `manifest.icon` → nav icon → fallback);
+ *  - {@link solarIconOrFallback} returns the generic glyph, for a spot that
+ *    would otherwise be blank.
+ */
+import type { Component } from 'vue';
+import { SOLAR_FALLBACK_ICON } from './solarIconMap.js';
+export { SOLAR_FALLBACK_ICON };
+/**
+ * The map's export name for `name`, or null when the map has none.
+ *
+ * Accepts every spelling the consumers accepted before: kebab (`money-bag`),
+ * snake (`card_2`), digits (`chart-2`) and the export name itself (`Layers`).
+ */
+export declare function solarIconKey(name: string | null | undefined): string | null;
+/** The icon for `name`, or undefined — the caller picks its own fallback. */
+export declare function solarIcon(name: string | null | undefined): Component | undefined;
+/**
+ * The icon for `name`; the generic glyph for a name the map does not know;
+ * null only when there is no name at all (nothing was asked for).
+ */
+export declare function solarIconOrFallback(name: string | null | undefined): Component | null;

package/dist/runtime/lib/solarIcons.js

@@ -0,0 +1,25 @@
+import { SOLAR_FALLBACK_ICON, SOLAR_ICON_ALIASES, SOLAR_ICON_MAP } from "./solarIconMap.js";
+import { solarExportName } from "./appIcon.js";
+export { SOLAR_FALLBACK_ICON };
+const warned = /* @__PURE__ */ new Set();
+function reportMiss(name) {
+  if (!import.meta.dev || warned.has(name)) return;
+  warned.add(name);
+  console.warn(`[solarIcons] no icon "${name}" in the closed map; drawing the fallback. Run \`pnpm icons\` (scripts/icons.mjs) to add it.`);
+}
+export function solarIconKey(name) {
+  const raw = name?.trim();
+  if (!raw) return null;
+  const key = SOLAR_ICON_ALIASES[raw] ?? solarExportName(raw);
+  return key in SOLAR_ICON_MAP ? key : null;
+}
+export function solarIcon(name) {
+  const key = solarIconKey(name);
+  if (key) return SOLAR_ICON_MAP[key];
+  if (name?.trim()) reportMiss(name.trim());
+  return void 0;
+}
+export function solarIconOrFallback(name) {
+  if (!name?.trim()) return null;
+  return solarIcon(name) ?? SOLAR_FALLBACK_ICON;
+}

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

@@ -0,0 +1,124 @@
+import type { Component, InjectionKey, MaybeRef } from 'vue';
+export type WidgetCategory = 'commerce' | 'operations' | 'ai' | 'workspace' | 'apps';
+/**
+ * The schematic the library draws for a widget. Not a screenshot and not the
+ * live widget: a shape, so the picture cannot go stale and costs no query.
+ */
+export type WidgetPreviewShape = 'kpi-row' | 'bar-chart' | 'ranked-list' | 'funnel' | 'stat-split' | 'feed' | 'status-grid' | 'text' | 'links' | 'greeting' | 'sparkline-grid' | 'count';
+export interface WidgetConfigField {
+    key: string;
+    /** Catalogue key for the field label. */
+    labelKey?: string;
+    /** Ready-made label — a field a manifest named, which arrives translated. */
+    label?: string;
+    type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'links' | 'filters' | 'sort';
+    /** Catalogue keys for the help line and the placeholder. */
+    helpKey?: string;
+    placeholderKey?: string;
+    help?: string;
+    options?: {
+        value: string;
+        labelKey?: string;
+        label?: string;
+    }[];
+    default?: unknown;
+}
+export interface WidgetDefinition {
+    /** Stable id persisted in `dashboards.widgets[].type`. Never rename in place. */
+    type: string;
+    /**
+     * Catalogue key for the title. A surface whose widgets are declared in code
+     * uses this; one whose widgets come from a manifest already has the operator's
+     * language and passes `title` instead.
+     */
+    titleKey?: string;
+    title?: string;
+    descriptionKey?: string;
+    description?: string;
+    /** Solar icon name — must also exist in WidgetIcon's map. */
+    icon: string;
+    category: WidgetCategory;
+    /** The schematic the library draws. */
+    preview: WidgetPreviewShape;
+    defaultSize: {
+        w: number;
+        h: number;
+    };
+    minSize?: {
+        w: number;
+        h: number;
+    };
+    /**
+     * The component, always as a loader, always memoised per type. An adapter
+     * that renders many types through ONE component hands in a loader that
+     * resolves immediately (`() => Promise.resolve(Adapter)`) rather than the
+     * component itself — a Vue component can be a function too, and telling the
+     * two apart by inspection is how a functional component ends up being awaited.
+     */
+    component: () => Promise<Component | {
+        default: Component;
+    }>;
+    /** Rendered by the generic config form; omit for a widget with no options. */
+    configFields?: WidgetConfigField[];
+    /** Installed apps this widget reads from. Empty = works for every tenant. */
+    requiresApps?: string[];
+    /**
+     * Announced but not built. It appears in the library so people can see what
+     * is coming, and cannot be placed — a card that adds an empty promise to a
+     * dashboard is worse than one that says "not yet".
+     */
+    comingSoon?: boolean;
+    /** Widget draws its own header/card; the frame then renders body-only. */
+    bare?: boolean;
+    /**
+     * Config the widget always carries, merged under the operator's own. The
+     * adapter for manifest widgets uses it to say WHICH manifest widget a type
+     * stands for, without that ending up in the config form.
+     */
+    fixedConfig?: Record<string, unknown>;
+}
+export interface WidgetCategoryGroup {
+    category: WidgetCategory;
+    labelKey: string;
+    widgets: WidgetDefinition[];
+}
+/** Catalogue keys for the library's group headings. */
+export declare const WIDGET_CATEGORY_KEYS: Record<WidgetCategory, string>;
+export interface WidgetRegistry {
+    all: () => WidgetDefinition[];
+    get: (type: string) => WidgetDefinition | undefined;
+    byCategory: () => WidgetCategoryGroup[];
+    /** The component for a type, memoised. Null when the type is unknown. */
+    componentFor: (type: string) => Component | null;
+    /** Defaults from `configFields`, plus whatever the definition fixes. */
+    defaultConfigFor: (type: string) => Record<string, unknown>;
+}
+/**
+ * Build a registry over a fixed list or a reactive one.
+ *
+ * Reactive is the interesting case: Commerce derives its definitions from the
+ * installed apps' manifests, which resolve after mount. A registry built over
+ * the computed sees them arrive without the surface re-providing anything.
+ */
+export declare function createWidgetRegistry(source: MaybeRef<WidgetDefinition[]>): WidgetRegistry;
+export declare const WIDGET_REGISTRY: InjectionKey<WidgetRegistry>;
+/** Called once by the surface that owns the dashboard. */
+export declare function provideWidgetRegistry(registry: WidgetRegistry): void;
+/**
+ * The registry of the surface this component is rendering on.
+ *
+ * An empty registry rather than a throw when nothing is provided: a dashboard
+ * component mounted outside a surface should render the same "unknown widget"
+ * placeholder it renders for a retired type, not take the page down.
+ */
+export declare function useWidgetRegistry(): WidgetRegistry;
+/** Apps a widget needs that are not in the given installed set. */
+export declare function missingAppsFor(definition: WidgetDefinition, installed: Set<string>): string[];
+/**
+ * A definition's heading, with the translator the host registered. Written
+ * once because four components need it and each got it subtly wrong on its own:
+ * an operator's own title wins, then the definition's text, then its key.
+ */
+export declare function widgetTitle(definition: WidgetDefinition | undefined, t: (key: string) => string, operatorTitle?: string): string;
+/** Same rule for the library's second line. */
+export declare function widgetDescription(definition: WidgetDefinition, t: (key: string) => string): string;

package/dist/runtime/lib/widgetRegistry.js

@@ -0,0 +1,66 @@
+import { computed, defineAsyncComponent, inject, isRef, provide } from "vue";
+export const WIDGET_CATEGORY_KEYS = {
+  commerce: "dashboard.category.commerce",
+  operations: "dashboard.category.operations",
+  ai: "dashboard.category.ai",
+  workspace: "dashboard.category.workspace",
+  apps: "dashboard.category.apps"
+};
+const CATEGORY_ORDER = ["commerce", "apps", "operations", "ai", "workspace"];
+export function createWidgetRegistry(source) {
+  const definitions = computed(() => isRef(source) ? source.value : source);
+  const byType = computed(() => new Map(definitions.value.map((d) => [d.type, d])));
+  const components = /* @__PURE__ */ new Map();
+  function get(type) {
+    return byType.value.get(type);
+  }
+  return {
+    all: () => definitions.value,
+    get,
+    byCategory() {
+      return CATEGORY_ORDER.map((category) => ({
+        category,
+        labelKey: WIDGET_CATEGORY_KEYS[category],
+        widgets: definitions.value.filter((d) => d.category === category)
+      })).filter((group) => group.widgets.length > 0);
+    },
+    componentFor(type) {
+      const cached = components.get(type);
+      if (cached) return cached;
+      const definition = get(type);
+      if (!definition) return null;
+      const component = defineAsyncComponent(definition.component);
+      components.set(type, component);
+      return component;
+    },
+    defaultConfigFor(type) {
+      const definition = get(type);
+      if (!definition) return {};
+      const out = {};
+      for (const field of definition.configFields ?? []) {
+        if (field.default !== void 0) out[field.key] = field.default;
+      }
+      return { ...out, ...definition.fixedConfig ?? {} };
+    }
+  };
+}
+export const WIDGET_REGISTRY = Symbol("studio-widget-registry");
+export function provideWidgetRegistry(registry) {
+  provide(WIDGET_REGISTRY, registry);
+}
+export function useWidgetRegistry() {
+  return inject(WIDGET_REGISTRY, null) ?? createWidgetRegistry([]);
+}
+export function missingAppsFor(definition, installed) {
+  return (definition.requiresApps ?? []).filter((app) => !installed.has(app));
+}
+export function widgetTitle(definition, t, operatorTitle) {
+  if (operatorTitle) return operatorTitle;
+  if (!definition) return "";
+  if (definition.title) return definition.title;
+  return definition.titleKey ? t(definition.titleKey) : "";
+}
+export function widgetDescription(definition, t) {
+  if (definition.description) return definition.description;
+  return definition.descriptionKey ? t(definition.descriptionKey) : "";
+}