@revenexx/studio-shared 0.3.1 → 0.3.3

package/dist/runtime/lib/facets.js

@@ -0,0 +1,171 @@
+export function isEmptyFacetValue(value) {
+  if (value === null || value === void 0) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "string") return value.trim() === "";
+  if (typeof value === "object") {
+    const range = value;
+    return !range.from?.trim() && !range.to?.trim();
+  }
+  return false;
+}
+export function pruneSelection(selection) {
+  const out = {};
+  for (const [key, value] of Object.entries(selection)) {
+    if (!isEmptyFacetValue(value)) out[key] = value;
+  }
+  return out;
+}
+export function countInFacet(selection, key) {
+  const value = selection[key];
+  if (isEmptyFacetValue(value)) return 0;
+  return Array.isArray(value) ? value.length : 1;
+}
+export function countSelected(facets, selection) {
+  return facets.reduce((n, facet) => n + countInFacet(selection, facet.key), 0);
+}
+export function flattenNodes(nodes, expanded) {
+  const out = [];
+  const walk = (list, depth) => {
+    for (const node of list) {
+      out.push({ node, depth });
+      if (node.children?.length && expanded.has(node.value)) walk(node.children, depth + 1);
+    }
+  };
+  walk(nodes, 0);
+  return out;
+}
+export function allNodes(nodes) {
+  const out = [];
+  const walk = (list) => {
+    for (const node of list) {
+      out.push(node);
+      if (node.children?.length) walk(node.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}
+export function nodePath(nodes, value) {
+  const walk = (list, trail) => {
+    for (const node of list) {
+      const here = [...trail, node];
+      if (node.value === value) return here;
+      if (node.children?.length) {
+        const hit = walk(node.children, here);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  };
+  return walk(nodes, []);
+}
+export function expandTo(nodes, value) {
+  if (!value) return /* @__PURE__ */ new Set();
+  const path = nodePath(nodes, value);
+  if (!path) return /* @__PURE__ */ new Set();
+  return new Set(path.slice(0, -1).map((node) => node.value));
+}
+export function initialExpanded(nodes) {
+  return new Set(nodes.filter((node) => node.children?.length).map((node) => node.value));
+}
+export function facetValueIds(key, value) {
+  if (isEmptyFacetValue(value)) return [];
+  if (Array.isArray(value)) return value.map((one) => `${key}:${one}`);
+  return [`${key}:`];
+}
+function optionLabel(facet, value) {
+  if (facet.kind === "tree") {
+    const path = nodePath(facet.nodes ?? [], value);
+    return path?.length ? path.map((node) => node.label).join(" \u203A ") : value;
+  }
+  return facet.options?.find((option) => option.value === value)?.label ?? value;
+}
+export function appliedFacets(facets, selection, format) {
+  const out = [];
+  for (const facet of facets) {
+    const value = selection[facet.key];
+    if (isEmptyFacetValue(value)) continue;
+    if (Array.isArray(value)) {
+      for (const one of value) {
+        out.push({
+          id: `${facet.key}:${one}`,
+          facetKey: facet.key,
+          facetLabel: facet.label,
+          label: optionLabel(facet, one),
+          value: one
+        });
+      }
+      continue;
+    }
+    out.push({
+      id: `${facet.key}:`,
+      facetKey: facet.key,
+      facetLabel: facet.label,
+      label: typeof value === "string" ? format.text(value) : format.range(value)
+    });
+  }
+  return out;
+}
+export function toggleFacetValue(selection, key, value, on, opts = {}) {
+  if (opts.single) {
+    const next2 = { ...selection };
+    if (on) next2[key] = [value];
+    else delete next2[key];
+    return next2;
+  }
+  const current = selection[key];
+  const set = new Set(Array.isArray(current) ? current : []);
+  if (on) set.add(value);
+  else set.delete(value);
+  const next = { ...selection };
+  if (set.size) next[key] = [...set];
+  else delete next[key];
+  return next;
+}
+export function setFacetValue(selection, key, value) {
+  const next = { ...selection };
+  if (isEmptyFacetValue(value)) delete next[key];
+  else next[key] = value;
+  return next;
+}
+export function clearFacetValue(selection, key, value) {
+  if (value === void 0) {
+    const next = { ...selection };
+    delete next[key];
+    return next;
+  }
+  return toggleFacetValue(selection, key, value, false);
+}
+export function sameSelection(a, b) {
+  const left = pruneSelection(a);
+  const right = pruneSelection(b);
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  for (const key of keys) {
+    const l = left[key];
+    const r = right[key];
+    if (r === void 0) return false;
+    if (Array.isArray(l) !== Array.isArray(r)) return false;
+    if (Array.isArray(l) && Array.isArray(r)) {
+      if (l.length !== r.length) return false;
+      const sorted = [...r].sort();
+      if ([...l].sort().some((one, i) => one !== sorted[i])) return false;
+      continue;
+    }
+    if (typeof l === "string" || typeof r === "string") {
+      if (l !== r) return false;
+      continue;
+    }
+    const lr = l;
+    const rr = r;
+    if ((lr.from ?? "") !== (rr.from ?? "") || (lr.to ?? "") !== (rr.to ?? "")) return false;
+  }
+  return true;
+}
+export function copySelection(selection) {
+  const out = {};
+  for (const [key, value] of Object.entries(selection)) {
+    out[key] = Array.isArray(value) ? [...value] : typeof value === "string" ? value : { ...value };
+  }
+  return out;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Grid track sizing for the data table's columns.
+ *
+ * A column declares either a fixed size it wants (`'120px'`, `'max-content'`)
+ * or nothing at all, meaning "give it what is left". CSS Grid expresses the
+ * second as an `fr` track, and an `fr` track's automatic minimum is the one
+ * thing that makes it dangerous: `minmax(0,1fr)` may be given ZERO.
+ *
+ * That is not hypothetical. On `/commerce/contacts` thirteen columns declare
+ * 1340px of fixed track, the gaps add 96px, and the container is 1438px — so
+ * the only flexible column, the one holding the record's NAME, was sized 0px
+ * and the last column was clipped by the panel's `overflow: hidden`. The
+ * anchor of every row, invisible, on the surface that needs it most.
+ *
+ * `datatable-ux` already names the rule: a column whose resting state must
+ * stay legible gets a FLOOR, not a share. This applies it to the tracks the
+ * component generates, so a manifest gets it without having to ask — and the
+ * table overflows its box, where a reader can scroll to what was cut off,
+ * rather than silently dropping a column to nothing.
+ */
+/**
+ * The narrowest a flexible column may become.
+ *
+ * Roughly the record-name cell at its minimum: the 28px icon tile, its gap,
+ * and enough left for a truncated word plus the ellipsis that says there is
+ * more. Below this a column stops being a column and becomes a smear.
+ */
+export declare const FLEX_TRACK_FLOOR = "120px";
+/**
+ * One column's declared width, resolved to a track with a floor under it.
+ *
+ * Fixed sizes are left exactly as declared — they are a statement about the
+ * content, and shrinking them is the manifest author's call, not this
+ * function's. Only the flexible ones are touched, and only their minimum.
+ */
+export declare function trackFor(width: string | undefined | null, floor?: string): string;
+/**
+ * The `grid-template-columns` value for a row of columns.
+ *
+ * A row spans `1 / -1` — the first track line to the last — so the tracks are
+ * also how WIDE a row is. Where every column declares a fixed size, they sum to
+ * less than the panel and nothing takes the remainder: on
+ * `/commerce/procurement/purchase-requests` the tracks and their gaps came to
+ * 1486px inside a 1698px box, and the header band and every row background
+ * stopped there while the toolbar and the footer went the whole way. A table
+ * torn off two centimetres short of its own panel.
+ *
+ * So when no column asked for a share, the LAST one absorbs what is left, and
+ * it keeps its declared size as the minimum it may never go below. On these
+ * lists the last column is the row actions — content right-aligned, so the
+ * menu button stays pinned to the right edge and every other column is exactly
+ * where the manifest put it. On a list without one it is the trailing data
+ * column that grows, which is where the eye is least likely to miss the space.
+ */
+export declare function gridTemplateColumns(widths: Array<string | undefined | null>, floor?: string): string;

package/dist/runtime/lib/gridTracks.js

@@ -0,0 +1,29 @@
+export const FLEX_TRACK_FLOOR = "120px";
+const MINMAX_FR = /^minmax\(\s*[^,]+,\s*([\d.]+fr)\s*\)$/i;
+const BARE_FR = /^([\d.]+)fr$/i;
+export function trackFor(width, floor = FLEX_TRACK_FLOOR) {
+  if (!width) return `minmax(${floor},1fr)`;
+  const declared = width.trim();
+  const weighted = MINMAX_FR.exec(declared);
+  if (weighted) return `minmax(${floor},${weighted[1].toLowerCase()})`;
+  const bare = BARE_FR.exec(declared);
+  if (bare) return `minmax(${floor},${bare[1]}fr)`;
+  return declared;
+}
+function isFlexible(track) {
+  return /\dfr\s*\)?$/i.test(track);
+}
+const MINMAX = /^minmax\(\s*([^,]+?)\s*,\s*(.+?)\s*\)$/i;
+function absorbing(track) {
+  const parts = MINMAX.exec(track);
+  return `minmax(${parts ? parts[2] : track},1fr)`;
+}
+export function gridTemplateColumns(widths, floor) {
+  const tracks = widths.map((w) => trackFor(w, floor));
+  if (tracks.length === 0) return "";
+  if (!tracks.some(isFlexible)) {
+    const last = tracks.length - 1;
+    tracks[last] = absorbing(tracks[last]);
+  }
+  return tracks.join(" ");
+}

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) : "";
+}

package/dist/runtime/types/dashboard.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The dashboard contract, shared by every surface that has one (PE-618).
+ *
+ * It started in the cockpit's `shared/dashboards/types.ts`, where the home
+ * screen and its Nitro routes were the only readers. The Commerce Studio now
+ * renders the same dashboards from a published module that cannot see the
+ * host's `#shared` alias — so the shape moves here, and the cockpit's file
+ * re-exports it. One declaration, two consumers, no drift between the rows
+ * Nitro writes and the layout the grid reads.
+ *
+ * The layout vocabulary is deliberately identical to `shared/analytics/types`:
+ * two dashboard surfaces in one product must not grow two models of a grid.
+ */
+/** Grid placement on a twelve-column grid. `i` is the widget instance id. */
+export interface DashboardLayoutItem {
+    i: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** One placed widget. `type` resolves against the surface's widget registry. */
+export interface DashboardWidget {
+    id: string;
+    type: string;
+    /** Operator-set title; falls back to the registry entry's title when unset. */
+    title?: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * Which surface a dashboard belongs to.
+ *
+ * A dashboard is made of the widgets available where it is edited, so it is
+ * only meaningful on its own surface: a Commerce dashboard listed in the
+ * cockpit's home switcher would open as a grid of widgets that screen cannot
+ * render. Stored on the row rather than encoded in the slug, because a
+ * convention nothing enforces is one typo away from the wrong surface.
+ */
+export type DashboardScope = 'home' | 'commerce';
+export declare const DASHBOARD_SCOPES: readonly DashboardScope[];
+/** `private` — owner only. `tenant` — anyone in the tenant may see it. */
+export type DashboardVisibility = 'private' | 'tenant';
+/**
+ * What a tenant-wide share grants. `view` is the default and the safe one; a
+ * dashboard several people can change becomes whatever the last one left
+ * behind, so `edit` is a decision the owner makes explicitly.
+ */
+export type DashboardTenantPermission = 'view' | 'edit';
+export interface Dashboard {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string | null;
+    icon?: string | null;
+    /** The surface this dashboard belongs to. Older rows read as `home`. */
+    scope: DashboardScope;
+    ownerUserId: string;
+    /** Display name captured when the dashboard was created. */
+    ownerName?: string | null;
+    /** Who last saved it, and under what name at that moment. */
+    updatedByUserId?: string | null;
+    updatedByName?: string | null;
+    visibility: DashboardVisibility;
+    tenantPermission: DashboardTenantPermission;
+    layout: DashboardLayoutItem[];
+    widgets: DashboardWidget[];
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Server-derived, per caller. True for the owner, and for anyone in the
+     * tenant when the dashboard is shared with `edit`.
+     */
+    canEdit: boolean;
+    /** Server-derived: this caller created it. Only the owner may share or delete. */
+    isOwner: boolean;
+    /** Server-derived: true when this is the caller's landing dashboard. */
+    isDefault: boolean;
+}
+export interface DashboardListResponse {
+    dashboards: Dashboard[];
+    defaultDashboardId: string | null;
+}
+export interface DashboardWritePayload {
+    name?: string;
+    description?: string | null;
+    icon?: string | null;
+    visibility?: DashboardVisibility;
+    tenantPermission?: DashboardTenantPermission;
+    layout?: DashboardLayoutItem[];
+    widgets?: DashboardWidget[];
+    /** Required on update — a stale value is answered with 409, not an overwrite. */
+    version?: number;
+}
+export declare const MAX_DASHBOARD_COLUMNS = 12;

package/dist/runtime/types/dashboard.js

@@ -0,0 +1,2 @@
+export const DASHBOARD_SCOPES = ["home", "commerce"];
+export const MAX_DASHBOARD_COLUMNS = 12;

package/dist/types.d.mts

@@ -16,6 +16,12 @@ export { type TalkbackChannel, type TalkbackChannelOptions, type TalkbackMaybeRe
 
 export { type MediaLibraryClient } from '../dist/runtime/composables/useMediaLibrary.js'
 
+export { type SavedViewsStore, type StoredSavedView } from '../dist/runtime/composables/useSavedViews.js'
+
+export { type WidgetCategory, type WidgetCategoryGroup, type WidgetConfigField, type WidgetDefinition, type WidgetPreviewShape, type WidgetRegistry } from '../dist/runtime/lib/widgetRegistry.js'
+
+export { type StickyListView } from '../dist/runtime/composables/useStickyListView.js'
+
 export { type FloatingPanelDock, type FloatingPanelMode, type FloatingPanelOptions } from '../dist/runtime/composables/useFloatingPanel.js'
 
 export { type IsoOption } from '../dist/runtime/lib/isoLists.js'
@@ -27,3 +33,5 @@ export { default } from './module.mjs'
 export * from '../dist/runtime/components/DataTable/types.js'
 
 export * from '../dist/runtime/types/storage.js'
+
+export * from '../dist/runtime/types/dashboard.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/studio-shared",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Shared revenexx Studio shell primitives (PageHeader, SidebarNav, StateCard, DataTable, …) + the platform provider contract (usePlatformAuth/usePlatformTenant). A Nuxt module — add it to `modules`.",
   "main": "./dist/module.mjs",
@@ -25,10 +25,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.0.0"
+    "@nuxt/kit": "^4.0.0",
+    "grid-layout-plus": "^1.1.1"
   },
   "peerDependencies": {
-    "@revenexx/studio": "^0.2.0",
+    "@revenexx/studio": "^0.2.3",
     "@revenexx/talkback-js": "^0.3.0",
     "@solar-icons/nuxt": "^1.2.0",
     "centrifuge": ">=5.2.0",