@vc-shell/framework 1.2.3-beta.1 → 1.2.4-beta.1

package/shared/components/blade-navigation/composables/useBladeStack.ts

@@ -0,0 +1,335 @@
+import { ref, computed, inject } from "vue";
+import type { IBladeRegistry } from "../../../../core/composables/useBladeRegistry";
+import type { BladeDescriptor, BladeOpenEvent, IBladeStack } from "../types";
+import { BladeStackKey } from "../types";
+
+let _idCounter = 0;
+
+/** Generate a unique blade instance ID */
+function generateBladeId(): string {
+  return `blade_${++_idCounter}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Creates the BladeStack state machine.
+ *
+ * The stack manages an ordered list of BladeDescriptor objects (plain data).
+ * All mutations go through explicit actions — no direct VNode manipulation.
+ *
+ * @param bladeRegistry - Registry for resolving blade names → components
+ */
+export function createBladeStack(bladeRegistry: IBladeRegistry): IBladeStack {
+  // ── Internal State ────────────────────────────────────────────────────────
+  const _blades = ref<BladeDescriptor[]>([]);
+
+  // Guards: bladeId → guard function (returns true to PREVENT close)
+  const _beforeCloseGuards = new Map<string, () => Promise<boolean>>();
+
+  // Lifecycle callbacks stored per blade
+  const _onOpenCallbacks = new Map<string, () => void>();
+  const _onCloseCallbacks = new Map<string, () => void>();
+
+  // ── Computed (readonly) ───────────────────────────────────────────────────
+  const workspace = computed(() => _blades.value[0]);
+
+  const blades = computed<readonly BladeDescriptor[]>(() => _blades.value);
+
+  const activeBlade = computed(() => {
+    for (let i = _blades.value.length - 1; i >= 0; i--) {
+      if (_blades.value[i].visible) return _blades.value[i];
+    }
+    return undefined;
+  });
+
+  // ── Internal Helpers ──────────────────────────────────────────────────────
+
+  function _cleanupBlade(bladeId: string): void {
+    _beforeCloseGuards.delete(bladeId);
+    _onOpenCallbacks.delete(bladeId);
+    _onCloseCallbacks.delete(bladeId);
+  }
+
+  function _resolveUrl(name: string): string | undefined {
+    const registration = bladeRegistry.getBlade(name);
+    if (!registration) return undefined;
+    // registration.route holds the URL segment (e.g. "/orders")
+    return registration.route;
+  }
+
+  /**
+   * Check guards for a list of blades (deepest first).
+   * Returns true if any guard prevented the close.
+   */
+  async function _checkGuards(bladesToClose: BladeDescriptor[]): Promise<boolean> {
+    // Reverse: check deepest blade first
+    for (let i = bladesToClose.length - 1; i >= 0; i--) {
+      const guard = _beforeCloseGuards.get(bladesToClose[i].id);
+      if (guard) {
+        const prevented = await guard();
+        if (prevented) return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Fire onClose callbacks and cleanup for a list of blades.
+   */
+  function _closeBladesCleanup(bladesToClose: BladeDescriptor[]): void {
+    for (const blade of bladesToClose) {
+      _onCloseCallbacks.get(blade.id)?.();
+      _cleanupBlade(blade.id);
+    }
+  }
+
+  // ── Actions ───────────────────────────────────────────────────────────────
+
+  async function openWorkspace(event: BladeOpenEvent): Promise<void> {
+    const currentWorkspace = workspace.value;
+
+    // Same workspace — no-op
+    if (currentWorkspace?.name === event.name) return;
+
+    // Validate blade exists in registry
+    if (!bladeRegistry.getBlade(event.name)) {
+      throw new Error(`[BladeStack] Blade '${event.name}' not found in registry`);
+    }
+
+    // Close all existing blades (no guards — workspace switch is unconditional)
+    _closeBladesCleanup([..._blades.value]);
+
+    // Create workspace descriptor
+    const descriptor: BladeDescriptor = {
+      id: generateBladeId(),
+      name: event.name,
+      url: _resolveUrl(event.name),
+      // workspace blades don't have param when opened first
+      query: event.query,
+      options: event.options,
+      visible: true,
+    };
+
+    _blades.value = [descriptor];
+
+    if (event.onOpen) _onOpenCallbacks.set(descriptor.id, event.onOpen);
+    if (event.onClose) _onCloseCallbacks.set(descriptor.id, event.onClose);
+
+    event.onOpen?.();
+  }
+
+  async function openBlade(event: BladeOpenEvent & { parentId?: string }): Promise<void> {
+    // Validate blade exists in registry
+    if (!bladeRegistry.getBlade(event.name)) {
+      throw new Error(`[BladeStack] Blade '${event.name}' not found in registry`);
+    }
+
+    const parentId = event.parentId ?? activeBlade.value?.id;
+    if (!parentId) {
+      throw new Error("[BladeStack] Cannot open blade: no parent blade found");
+    }
+
+    const parentIndex = _blades.value.findIndex((b) => b.id === parentId);
+    if (parentIndex === -1) {
+      throw new Error(`[BladeStack] Parent blade '${parentId}' not found in stack`);
+    }
+
+    // Blades after the parent will be closed
+    const bladesToClose = _blades.value.slice(parentIndex + 1);
+
+    // Check guards (deepest first)
+    if (bladesToClose.length > 0) {
+      const prevented = await _checkGuards(bladesToClose);
+      if (prevented) return;
+    }
+
+    // Cleanup closing blades
+    _closeBladesCleanup(bladesToClose);
+
+    // Create new blade descriptor
+    const descriptor: BladeDescriptor = {
+      id: generateBladeId(),
+      name: event.name,
+      url: _resolveUrl(event.name),
+      param: event.param,
+      query: event.query,
+      options: event.options,
+      parentId,
+      visible: true,
+    };
+
+    // Replace blades: keep up to parent (inclusive), append new
+    _blades.value = [..._blades.value.slice(0, parentIndex + 1), descriptor];
+
+    if (event.onOpen) _onOpenCallbacks.set(descriptor.id, event.onOpen);
+    if (event.onClose) _onCloseCallbacks.set(descriptor.id, event.onClose);
+
+    event.onOpen?.();
+  }
+
+  async function closeBlade(bladeId: string): Promise<boolean> {
+    const index = _blades.value.findIndex((b) => b.id === bladeId);
+    if (index === -1) return false;
+
+    // Cannot close the workspace blade
+    if (index === 0) return false;
+
+    // Everything from this blade onwards will be closed
+    const bladesToClose = _blades.value.slice(index);
+
+    // Check guards (deepest first)
+    const prevented = await _checkGuards(bladesToClose);
+    if (prevented) return true;
+
+    // Cleanup and fire onClose callbacks
+    _closeBladesCleanup(bladesToClose);
+
+    // Remove from stack
+    _blades.value = _blades.value.slice(0, index);
+
+    // Restore visibility of blade hidden by replaceCurrentBlade
+    const lastIndex = _blades.value.length - 1;
+    if (lastIndex > 0 && !_blades.value[lastIndex].visible) {
+      const updated = [..._blades.value];
+      updated[lastIndex] = { ...updated[lastIndex], visible: true };
+      _blades.value = updated;
+    }
+
+    return false;
+  }
+
+  async function replaceCurrentBlade(
+    event: BladeOpenEvent & { parentId?: string },
+  ): Promise<void> {
+    const current = activeBlade.value;
+    if (!current) {
+      throw new Error("[BladeStack] No active blade to replace");
+    }
+
+    // Validate blade exists in registry
+    if (!bladeRegistry.getBlade(event.name)) {
+      throw new Error(`[BladeStack] Blade '${event.name}' not found in registry`);
+    }
+
+    const currentIndex = _blades.value.findIndex((b) => b.id === current.id);
+    if (currentIndex === -1) {
+      throw new Error(`[BladeStack] Active blade '${current.id}' not found in stack`);
+    }
+
+    // Close any blades after the current one first
+    const bladesToClose = _blades.value.slice(currentIndex + 1);
+    if (bladesToClose.length > 0) {
+      const prevented = await _checkGuards(bladesToClose);
+      if (prevented) return;
+      _closeBladesCleanup(bladesToClose);
+    }
+
+    // Create replacement descriptor — parent is the HIDDEN blade (not its parent),
+    // so parentCall from the replacing blade reaches the hidden blade's methods.
+    const descriptor: BladeDescriptor = {
+      id: generateBladeId(),
+      name: event.name,
+      url: _resolveUrl(event.name),
+      param: event.param,
+      query: event.query,
+      options: event.options,
+      parentId: current.id,
+      visible: true,
+    };
+
+    // Hide current blade (don't destroy it) and append new blade after it
+    const updated = _blades.value.slice(0, currentIndex);
+    updated.push({ ...current, visible: false });
+    updated.push(descriptor);
+    _blades.value = updated;
+
+    if (event.onOpen) _onOpenCallbacks.set(descriptor.id, event.onOpen);
+    if (event.onClose) _onCloseCallbacks.set(descriptor.id, event.onClose);
+
+    event.onOpen?.();
+  }
+
+  // ── Guards ────────────────────────────────────────────────────────────────
+
+  function registerBeforeClose(bladeId: string, guard: () => Promise<boolean>): void {
+    _beforeCloseGuards.set(bladeId, guard);
+  }
+
+  function unregisterBeforeClose(bladeId: string): void {
+    _beforeCloseGuards.delete(bladeId);
+  }
+
+  // ── Error Management ──────────────────────────────────────────────────────
+
+  function setBladeError(bladeId: string, error: unknown): void {
+    const index = _blades.value.findIndex((b) => b.id === bladeId);
+    if (index === -1) return;
+
+    // Immutable update: create new array with updated descriptor
+    const updated = [..._blades.value];
+    updated[index] = { ...updated[index], error };
+    _blades.value = updated;
+  }
+
+  function clearBladeError(bladeId: string): void {
+    const index = _blades.value.findIndex((b) => b.id === bladeId);
+    if (index === -1) return;
+
+    const updated = [..._blades.value];
+    updated[index] = { ...updated[index], error: undefined };
+    _blades.value = updated;
+  }
+
+  // ── Title Management ───────────────────────────────────────────────────────
+
+  function setBladeTitle(bladeId: string, title: string | undefined): void {
+    const index = _blades.value.findIndex((b) => b.id === bladeId);
+    if (index === -1) return;
+    if (_blades.value[index].title === title) return; // no-op if unchanged
+
+    const updated = [..._blades.value];
+    updated[index] = { ...updated[index], title };
+    _blades.value = updated;
+  }
+
+  // ── Internal: Restore (used by HistoryManager) ────────────────────────────
+
+  function _restoreStack(descriptors: BladeDescriptor[]): void {
+    // Clear all existing callbacks/guards
+    for (const blade of _blades.value) {
+      _cleanupBlade(blade.id);
+    }
+    _blades.value = descriptors;
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  return {
+    workspace,
+    blades,
+    activeBlade,
+    openWorkspace,
+    openBlade,
+    closeBlade,
+    replaceCurrentBlade,
+    registerBeforeClose,
+    unregisterBeforeClose,
+    setBladeError,
+    clearBladeError,
+    setBladeTitle,
+    _restoreStack,
+  };
+}
+
+/**
+ * Composable for accessing the BladeStack from within a component.
+ * Must be used after BladeStack is provided via BladeStackKey.
+ */
+export function useBladeStack(): IBladeStack {
+  const stack = inject(BladeStackKey);
+  if (!stack) {
+    throw new Error(
+      "[useBladeStack] BladeStack not found. Ensure BladeNavigationPlugin is installed.",
+    );
+  }
+  return stack;
+}

package/shared/components/blade-navigation/index.ts

@@ -1,4 +1,4 @@
-export * from "./plugin";
+export * from "./plugin-v2";
 export * from "./components";
 export * from "./composables";
 export * from "./types";

package/shared/components/blade-navigation/plugin-v2.ts

@@ -0,0 +1,144 @@
+import { Router } from "vue-router";
+import { App } from "vue";
+import * as components from "./components";
+import { BladeNavigationPlugin, BladeStackKey, BladeMessagingKey } from "./types";
+import { createBladeStack } from "./composables/useBladeStack";
+import { createBladeMessaging } from "./composables/useBladeMessaging";
+import { parseBladeUrl, buildUrlFromStack } from "./utils/urlSync";
+import { restoreFromUrl } from "./utils/restoreFromUrl";
+import { useBladeRegistry } from "../../../core/composables/useBladeRegistry";
+import type { IBladeRegistry } from "../../../core/composables/useBladeRegistry";
+
+// Declare globally
+declare module "@vue/runtime-core" {
+  export interface GlobalComponents {
+    VcBladeNavigation: (typeof components)["VcBladeNavigation"];
+  }
+}
+
+// Keep legacy global reference for backward compatibility
+export let bladeNavigationInstance: BladeNavigationPlugin;
+
+// Module-level singletons — accessible without inject() (for use in route guards, adapters, etc.)
+// These are set once during plugin install and persist for the app's lifetime.
+// Limitation: only one Vue app per JS context is supported.
+// Call _resetBladeNavigationSingletons() in test teardown to prevent cross-test leaks.
+import type { IBladeStack, IBladeMessaging } from "./types";
+export let bladeStackInstance: IBladeStack | undefined;
+export let bladeMessagingInstance: IBladeMessaging | undefined;
+export let bladeRegistryInstance: IBladeRegistry | undefined;
+
+/**
+ * Reset all module-level singletons. For use in test teardown only.
+ * @internal
+ */
+export function _resetBladeNavigationSingletons(): void {
+  bladeStackInstance = undefined;
+  bladeMessagingInstance = undefined;
+  bladeRegistryInstance = undefined;
+}
+
+/**
+ * New Blade Navigation Plugin (v2).
+ *
+ * Sets up:
+ * - BladeStack state machine (provided via BladeStackKey)
+ * - BladeMessaging for inter-blade communication (provided via BladeMessagingKey)
+ * - Auto catch-all route under the root route (safety net for blade URLs)
+ * - Router beforeEach guard for URL → blade stack restoration
+ *
+ * Vue Router serves as the URL sync layer only. BladeStack is the source of truth.
+ * Back/forward is handled natively by Vue Router — beforeEach fires on popstate
+ * and restores BladeStack from the URL.
+ */
+export const VcBladeNavigationComponent = {
+  install(app: App, args: { router: Router }) {
+    const { router } = args;
+
+    // ── Register UI components ──────────────────────────────────────────────
+    Object.entries(components).forEach(([componentName, component]) => {
+      app.component(componentName, component);
+    });
+
+    // ── Legacy backward compatibility ───────────────────────────────────────
+    const bladeNavigationPluginData: BladeNavigationPlugin = {
+      router: args.router,
+    };
+    bladeNavigationInstance = bladeNavigationPluginData;
+    app.provide("bladeNavigationPlugin", bladeNavigationPluginData);
+
+    // ── New BladeStack system ───────────────────────────────────────────────
+
+    // BladeRegistry must already be provided by the main app setup (framework/index.ts)
+    const bladeRegistry = app.runWithContext(() => {
+      try {
+        return useBladeRegistry();
+      } catch {
+        console.warn(
+          "[BladeNavigationPlugin] BladeRegistry not yet available. " +
+          "BladeStack will be created but URL restoration may be deferred.",
+        );
+        return undefined;
+      }
+    }) as IBladeRegistry | undefined;
+
+    if (!bladeRegistry) {
+      console.error("[BladeNavigationPlugin] BladeRegistry is required but not found.");
+      return;
+    }
+
+    // Create BladeStack
+    const bladeStack = createBladeStack(bladeRegistry);
+    app.provide(BladeStackKey, bladeStack);
+    bladeStackInstance = bladeStack;
+
+    // Create BladeMessaging
+    const messaging = createBladeMessaging(bladeStack);
+    app.provide(BladeMessagingKey, messaging);
+    bladeMessagingInstance = messaging;
+    bladeRegistryInstance = bladeRegistry;
+
+    // ── Auto-register catch-all route ───────────────────────────────────────
+    // Safety net: prevents Vue Router "route not found" errors for blade URLs
+    // in hash mode. BladeStack handles actual rendering.
+    const mainRoute = router.getRoutes().find((r) => r.meta?.root);
+    if (mainRoute) {
+      router.addRoute(mainRoute.name as string, {
+        path: ":pathMatch(.*)*",
+        component: { render: () => null },
+      });
+    }
+
+    // ── Router guard for URL → blade stack restoration ──────────────────────
+    // Fires on: direct URL entry, deep links, back/forward (popstate)
+    // The adapter's router.push()/replace() also triggers this, but
+    // restoreFromUrl is idempotent — if stack already matches URL, it's a no-op.
+    router.beforeEach(async (to) => {
+      // Only process routes under the root (App) route
+      if (!to.matched.some((r) => r.meta?.root)) return;
+
+      // Extract tenant prefix from route params (first param, typically sellerId)
+      const tenantPrefix = (Object.values(to.params)?.[0] as string) || "";
+
+      // Parse the URL path into blade segments
+      const parsed = parseBladeUrl(to.path, tenantPrefix);
+
+      if (!parsed.workspaceUrl) {
+        // No workspace in URL (e.g. Dashboard at "/") — clear any existing blade stack
+        if (bladeStack.blades.value.length > 0) {
+          bladeStack._restoreStack([]);
+        }
+        return;
+      }
+
+      // Restore blade stack from URL (idempotent — skips if already matching)
+      const needsUrlCleanup = await restoreFromUrl(bladeStack, bladeRegistry, parsed);
+
+      // If a non-routable blade was in the URL, clean up to match actual stack
+      if (needsUrlCleanup) {
+        const { path, query } = buildUrlFromStack(tenantPrefix, bladeStack.blades.value);
+        return { path, query, replace: true };
+      }
+    });
+  },
+};

package/shared/components/blade-navigation/types/index.ts

@@ -9,6 +9,8 @@ import {
   ComponentInternalInstance,
   VNodeTypes,
   Ref,
+  InjectionKey,
+  ComputedRef,
 } from "vue";
 import { ComponentPublicInstanceConstructor } from "../../../utilities/vueUtils";
 import { MenuItemConfig } from "../../../../core/types";
@@ -118,3 +120,128 @@ export interface BladeVNode extends VNode {
     CoreBladeComponentProps;
   type: VNodeTypes & BladeInstanceConstructor;
 }
+
+// ─── New Blade Navigation Types (BladeStack architecture) ─────────────────────
+
+/**
+ * Plain data descriptor for a blade instance in the stack.
+ * Replaces BladeVNode — no VNode mutation, purely reactive data.
+ */
+export interface BladeDescriptor {
+  /** Unique per open blade instance (generated at open time) */
+  id: string;
+  /** Registered component name (e.g. "OrderDetails") from defineOptions */
+  name: string;
+  /** URL segment (e.g. "/order") from defineOptions — used for URL construction */
+  url?: string;
+  /** Entity ID — appears in URL path */
+  param?: string;
+  /** Small key-value pairs — serialized to URL query params */
+  query?: Record<string, string>;
+  /** Large context data — stored in history.state only, not in URL */
+  options?: Record<string, unknown>;
+  /** ID of the blade that opened this one (undefined for workspace) */
+  parentId?: string;
+  /** Whether this blade is currently visible */
+  visible: boolean;
+  /** Error state for this blade */
+  error?: unknown;
+  /** Blade title — populated at runtime from the component's defineExpose({ title }) */
+  title?: string;
+}
+
+/**
+ * Event object for opening a blade.
+ * Used by BladeStack.openBlade, openWorkspace, replaceCurrentBlade.
+ */
+export interface BladeOpenEvent {
+  /** Registered component name — resolved via BladeRegistry */
+  name: string;
+  /** Entity ID for the blade */
+  param?: string;
+  /** Small key-value pairs for URL query */
+  query?: Record<string, string>;
+  /** Large context data — stored in history.state only */
+  options?: Record<string, unknown>;
+  /** Called after the blade is opened */
+  onOpen?: () => void;
+  /** Called after the blade is closed */
+  onClose?: () => void;
+  /** If true, replaces current blade instead of opening a new one */
+  replaceCurrentBlade?: boolean;
+}
+
+/**
+ * Result of parsing a blade URL into its segments.
+ */
+export interface ParsedBladeUrl {
+  /** Workspace URL segment (e.g. "orders") */
+  workspaceUrl?: string;
+  /** Child blade URL segment (e.g. "order") */
+  bladeUrl?: string;
+  /** Entity ID from the URL path */
+  param?: string;
+}
+
+/**
+ * Public interface for the BladeStack state machine.
+ */
+export interface IBladeStack {
+  /** The workspace blade (first in stack) */
+  readonly workspace: ComputedRef<BladeDescriptor | undefined>;
+  /** All blades in the stack (including workspace at [0]) */
+  readonly blades: ComputedRef<readonly BladeDescriptor[]>;
+  /** The last visible blade */
+  readonly activeBlade: ComputedRef<BladeDescriptor | undefined>;
+
+  /** Switch to a different workspace — clears all existing blades */
+  openWorkspace(event: BladeOpenEvent): Promise<void>;
+  /** Open a new blade as a child of the active blade */
+  openBlade(event: BladeOpenEvent & { parentId?: string }): Promise<void>;
+  /** Close a blade by ID. Returns true if close was prevented by a guard. */
+  closeBlade(bladeId: string): Promise<boolean>;
+  /** Replace the current active blade with a different one */
+  replaceCurrentBlade(event: BladeOpenEvent & { parentId?: string }): Promise<void>;
+
+  /**
+   * Register a before-close guard for a blade.
+   *
+   * Guard semantics (NEW API): return `true` to PREVENT close, `false` to ALLOW.
+   *
+   * **Note**: The legacy `onBeforeClose` callback has INVERTED semantics:
+   * return `false` to prevent, `undefined`/`true` to allow.
+   * The adapter in `useBladeNavigationAdapter.ts` handles this inversion.
+   */
+  registerBeforeClose(bladeId: string, guard: () => Promise<boolean>): void;
+  /** Unregister a before-close guard */
+  unregisterBeforeClose(bladeId: string): void;
+
+  /** Set an error on a blade */
+  setBladeError(bladeId: string, error: unknown): void;
+  /** Clear a blade's error */
+  clearBladeError(bladeId: string): void;
+
+  /** Update a blade's title (called by VcBladeSlot when component exposes title) */
+  setBladeTitle(bladeId: string, title: string | undefined): void;
+
+  /** Restore stack from descriptors (used by HistoryManager — bypasses guards) */
+  _restoreStack(descriptors: BladeDescriptor[]): void;
+}
+
+/**
+ * Public interface for inter-blade messaging.
+ */
+export interface IBladeMessaging {
+  /** Expose methods to child blades */
+  exposeToChildren(bladeId: string, methods: Record<string, (...args: any[]) => any>): void;
+  /** Call a method exposed by the parent blade */
+  callParent<T = unknown>(callerBladeId: string, method: string, args?: unknown): Promise<T>;
+  /** Remove all exposed methods for a blade (cleanup on close) */
+  cleanup(bladeId: string): void;
+}
+
+// ─── Injection Keys for new BladeStack architecture ───────────────────────────
+
+export const BladeStackKey: InjectionKey<IBladeStack> = Symbol("BladeStack");
+export const BladeMessagingKey: InjectionKey<IBladeMessaging> = Symbol("BladeMessaging");
+export const BladeDescriptorKey: InjectionKey<ComputedRef<BladeDescriptor>> = Symbol("BladeDescriptor");