@revenexx/studio-shared 0.3.2 → 0.3.3

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.2",
+  "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,7 +25,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.0.0"
+    "@nuxt/kit": "^4.0.0",
+    "grid-layout-plus": "^1.1.1"
   },
   "peerDependencies": {
     "@revenexx/studio": "^0.2.3",