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

package/shared/components/blade-navigation/utils/restoreFromUrl.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { computed } from "vue";
+import { restoreFromUrl } from "./restoreFromUrl";
+import { createBladeStack } from "../composables/useBladeStack";
+import type { IBladeRegistry, IBladeRegistrationData } from "../../../../core/composables/useBladeRegistry";
+import type { IBladeStack, ParsedBladeUrl } from "../types";
+
+// ── Mock registry ──────────────────────────────────────────────────────────────
+
+function createMockRegistry(
+  blades: Record<string, { route?: string; isWorkspace?: boolean; routable?: boolean }> = {},
+): IBladeRegistry {
+  const map = new Map<string, IBladeRegistrationData>(
+    Object.entries(blades).map(([name, data]) => [
+      name,
+      {
+        component: {} as any,
+        route: data.route,
+        isWorkspace: data.isWorkspace ?? false,
+        routable: data.routable,
+      },
+    ]),
+  );
+
+  // Build reverse route index (mirrors createBladeRegistry._routeIndex)
+  const routeIndex = new Map<string, { name: string; data: IBladeRegistrationData }>();
+  for (const [name, data] of map.entries()) {
+    if (data.route) {
+      const normalized = data.route.replace(/^\/+|\/+$/g, "").toLowerCase();
+      if (normalized) {
+        routeIndex.set(normalized, { name, data });
+      }
+    }
+  }
+
+  return {
+    registeredBladesMap: computed(() => map),
+    getBlade: (name: string) => map.get(name),
+    getBladeComponent: (name: string) => map.get(name)?.component,
+    getBladeByRoute: (route: string) => {
+      const normalized = route.replace(/^\/+|\/+$/g, "").toLowerCase();
+      return routeIndex.get(normalized);
+    },
+  };
+}
+
+function defaultRegistry(): IBladeRegistry {
+  return createMockRegistry({
+    Orders: { route: "/orders", isWorkspace: true },
+    OrderDetails: { route: "/order", routable: true },
+    Products: { route: "/products", isWorkspace: true },
+    NonRoutableBlade: { route: "/non-routable", routable: false },
+    NotAWorkspace: { route: "/not-workspace", isWorkspace: false },
+  });
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe("restoreFromUrl", () => {
+  let stack: IBladeStack;
+  let registry: IBladeRegistry;
+
+  beforeEach(() => {
+    registry = defaultRegistry();
+    stack = createBladeStack(registry);
+  });
+
+  // ── Empty / no-op cases ───────────────────────────────────────────────────
+
+  describe("no-op cases", () => {
+    it("returns false for empty parsed URL", async () => {
+      const result = await restoreFromUrl(stack, registry, {});
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(0);
+    });
+
+    it("returns false when workspaceUrl is undefined", async () => {
+      const result = await restoreFromUrl(stack, registry, {
+        bladeUrl: "order",
+        param: "123",
+      });
+      expect(result).toBe(false);
+    });
+  });
+
+  // ── Workspace restoration ─────────────────────────────────────────────────
+
+  describe("workspace restoration", () => {
+    it("opens workspace from URL", async () => {
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(1);
+      expect(stack.workspace.value?.name).toBe("Orders");
+    });
+
+    it("skips workspace open if already current", async () => {
+      // Pre-open workspace
+      await stack.openWorkspace({ name: "Orders" });
+      const openSpy = vi.spyOn(stack, "openWorkspace");
+
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+      });
+
+      expect(result).toBe(false);
+      expect(openSpy).not.toHaveBeenCalled();
+    });
+
+    it("returns false when workspace URL not found in registry", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "unknown",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(0);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("No workspace blade found"),
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it("returns false when matched blade is not a workspace", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "not-workspace",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(0);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("not a workspace"),
+      );
+
+      warnSpy.mockRestore();
+    });
+  });
+
+  // ── Workspace + child blade restoration ───────────────────────────────────
+
+  describe("workspace + child blade", () => {
+    it("opens workspace and child blade with param", async () => {
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "order",
+        param: "uuid-123",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(2);
+      expect(stack.workspace.value?.name).toBe("Orders");
+      expect(stack.blades.value[1].name).toBe("OrderDetails");
+      expect(stack.blades.value[1].param).toBe("uuid-123");
+    });
+
+    it("opens workspace and child blade without param", async () => {
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "order",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(2);
+      expect(stack.blades.value[1].name).toBe("OrderDetails");
+      expect(stack.blades.value[1].param).toBeUndefined();
+    });
+
+    it("warns when child blade URL not found in registry", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "unknown-blade",
+      });
+
+      expect(result).toBe(false);
+      expect(stack.blades.value).toHaveLength(1); // Only workspace
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("No blade found for URL segment"),
+      );
+
+      warnSpy.mockRestore();
+    });
+  });
+
+  // ── Idempotency ───────────────────────────────────────────────────────────
+
+  describe("idempotency", () => {
+    it("skips child blade if already open with same name and param", async () => {
+      // Pre-populate: workspace + child already open
+      await stack.openWorkspace({ name: "Orders" });
+      await stack.openBlade({ name: "OrderDetails", param: "uuid-123" });
+
+      expect(stack.blades.value).toHaveLength(2);
+
+      // Attempt restore with same params
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "order",
+        param: "uuid-123",
+      });
+
+      expect(result).toBe(false);
+      // Still only 2 blades — no duplicate opened
+      expect(stack.blades.value).toHaveLength(2);
+    });
+
+    it("opens new child if param differs from existing", async () => {
+      // Pre-populate with different param
+      await stack.openWorkspace({ name: "Orders" });
+      await stack.openBlade({ name: "OrderDetails", param: "uuid-old" });
+
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "order",
+        param: "uuid-new",
+      });
+
+      expect(result).toBe(false);
+      // New blade was opened (exact count depends on BladeStack.openBlade behavior)
+      const orderBlades = stack.blades.value.filter((b) => b.name === "OrderDetails");
+      expect(orderBlades.some((b) => b.param === "uuid-new")).toBe(true);
+    });
+  });
+
+  // ── Non-routable blade handling ───────────────────────────────────────────
+
+  describe("non-routable blade handling", () => {
+    it("returns true (needs cleanup) for non-routable blade", async () => {
+      const result = await restoreFromUrl(stack, registry, {
+        workspaceUrl: "orders",
+        bladeUrl: "non-routable",
+      });
+
+      expect(result).toBe(true);
+      // Workspace should be opened, but non-routable child should NOT be
+      expect(stack.blades.value).toHaveLength(1);
+      expect(stack.workspace.value?.name).toBe("Orders");
+    });
+  });
+});

package/shared/components/blade-navigation/utils/restoreFromUrl.ts

@@ -0,0 +1,84 @@
+import type { IBladeRegistry } from "../../../../core/composables/useBladeRegistry";
+import type { IBladeStack, ParsedBladeUrl } from "../types";
+
+/**
+ * Restore the blade stack from a parsed URL.
+ *
+ * Used on initial page load and when navigating via URL (not back/forward).
+ * Resolves URL segments to blade names via BladeRegistry, then opens
+ * workspace + child blade.
+ *
+ * Returns `true` if the URL contained segments for a non-routable blade
+ * that was skipped — the caller should clean up the URL to match the
+ * actual blade stack state.
+ *
+ * @param bladeStack - The BladeStack to populate
+ * @param bladeRegistry - Registry for resolving URLs → blade names
+ * @param parsed - Parsed URL segments
+ * @returns `true` if the URL needs cleanup (non-routable blade was skipped)
+ */
+export async function restoreFromUrl(
+  bladeStack: IBladeStack,
+  bladeRegistry: IBladeRegistry,
+  parsed: ParsedBladeUrl,
+): Promise<boolean> {
+  // Skip if no workspace URL to restore
+  if (!parsed.workspaceUrl) return false;
+
+  // Find workspace blade by URL segment
+  const workspaceMatch = bladeRegistry.getBladeByRoute(parsed.workspaceUrl);
+  if (!workspaceMatch) {
+    console.warn(
+      `[restoreFromUrl] No workspace blade found for URL segment '${parsed.workspaceUrl}'`,
+    );
+    return false;
+  }
+
+  // Check if workspace is actually marked as workspace
+  if (!workspaceMatch.data.isWorkspace) {
+    console.warn(
+      `[restoreFromUrl] Blade '${workspaceMatch.name}' matched URL '${parsed.workspaceUrl}' but is not a workspace`,
+    );
+    return false;
+  }
+
+  // Open workspace (if not already the current one)
+  const currentWorkspace = bladeStack.workspace.value;
+  if (currentWorkspace?.name !== workspaceMatch.name) {
+    await bladeStack.openWorkspace({ name: workspaceMatch.name });
+  }
+
+  // If there's a child blade URL, open it (if not already open with matching param)
+  if (parsed.bladeUrl) {
+    const bladeMatch = bladeRegistry.getBladeByRoute(parsed.bladeUrl);
+    if (bladeMatch) {
+      // Idempotency: skip if child already exists with same name and param.
+      // This means the blade was opened programmatically (normal operation)
+      // and syncUrlPush just triggered the guard — not a page restore.
+      const existingChild = bladeStack.blades.value.find(
+        (b) => b.name === bladeMatch.name && b.param === parsed.param,
+      );
+      if (existingChild) {
+        return false;
+      }
+
+      // Non-routable blades should not be restored from URL.
+      // Signal the caller to clean the URL.
+      if (bladeMatch.data.routable === false) {
+        return true;
+      }
+
+      await bladeStack.openBlade({
+        name: bladeMatch.name,
+        param: parsed.param,
+        // options not available from URL — blade must handle gracefully
+      });
+    } else {
+      console.warn(
+        `[restoreFromUrl] No blade found for URL segment '${parsed.bladeUrl}'`,
+      );
+    }
+  }
+
+  return false;
+}

package/shared/components/blade-navigation/utils/urlSync.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import { buildUrlFromStack, parseBladeUrl, buildQueryString } from "./urlSync";
+import type { BladeDescriptor } from "../types";
+
+// ── Helper ──────────────────────────────────────────────────────────────────────
+
+function makeDescriptor(overrides: Partial<BladeDescriptor> = {}): BladeDescriptor {
+  return {
+    id: "blade_1",
+    name: "TestBlade",
+    visible: true,
+    ...overrides,
+  };
+}
+
+// ── buildUrlFromStack ───────────────────────────────────────────────────────────
+
+describe("buildUrlFromStack", () => {
+  it("returns root path for empty stack", () => {
+    const result = buildUrlFromStack("", []);
+    expect(result.path).toBe("/");
+    expect(result.query).toEqual({});
+  });
+
+  it("returns tenant root for empty stack with tenant prefix", () => {
+    const result = buildUrlFromStack("tenant-abc", []);
+    expect(result.path).toBe("/tenant-abc");
+  });
+
+  it("builds workspace-only URL", () => {
+    const stack = [makeDescriptor({ name: "Orders", url: "/orders" })];
+    const result = buildUrlFromStack("", stack);
+    expect(result.path).toBe("/orders");
+  });
+
+  it("builds workspace-only URL with tenant", () => {
+    const stack = [makeDescriptor({ name: "Orders", url: "/orders" })];
+    const result = buildUrlFromStack("seller-123", stack);
+    expect(result.path).toBe("/seller-123/orders");
+  });
+
+  it("builds workspace + child blade URL", () => {
+    const stack = [
+      makeDescriptor({ id: "ws", name: "Orders", url: "/orders" }),
+      makeDescriptor({ id: "child", name: "OrderDetails", url: "/order", param: "uuid-1", parentId: "ws" }),
+    ];
+    const result = buildUrlFromStack("", stack);
+    expect(result.path).toBe("/orders/order/uuid-1");
+  });
+
+  it("builds workspace + child blade URL with tenant", () => {
+    const stack = [
+      makeDescriptor({ id: "ws", name: "Orders", url: "/orders" }),
+      makeDescriptor({ id: "child", name: "OrderDetails", url: "/order", param: "abc-123", parentId: "ws" }),
+    ];
+    const result = buildUrlFromStack("seller-1", stack);
+    expect(result.path).toBe("/seller-1/orders/order/abc-123");
+  });
+
+  it("skips invisible child blades", () => {
+    const stack = [
+      makeDescriptor({ id: "ws", name: "Orders", url: "/orders" }),
+      makeDescriptor({ id: "child", name: "OrderDetails", url: "/order", param: "x", visible: false }),
+    ];
+    const result = buildUrlFromStack("", stack);
+    expect(result.path).toBe("/orders");
+  });
+
+  it("uses last visible child blade", () => {
+    const stack = [
+      makeDescriptor({ id: "ws", name: "Orders", url: "/orders" }),
+      makeDescriptor({ id: "c1", name: "OldBlade", url: "/old", param: "old-id", visible: false }),
+      makeDescriptor({ id: "c2", name: "NewBlade", url: "/new", param: "new-id" }),
+    ];
+    const result = buildUrlFromStack("", stack);
+    expect(result.path).toBe("/orders/new/new-id");
+  });
+
+  it("normalizes URLs with leading/trailing slashes", () => {
+    const stack = [makeDescriptor({ name: "Orders", url: "//orders/" })];
+    const result = buildUrlFromStack("", stack);
+    expect(result.path).toBe("/orders");
+  });
+
+  it("merges query params from visible blades", () => {
+    const stack = [
+      makeDescriptor({ name: "Orders", url: "/orders", query: { page: "1" } }),
+      makeDescriptor({ name: "Details", url: "/order", query: { tab: "info" }, parentId: "ws" }),
+    ];
+    const result = buildUrlFromStack("", stack);
+    expect(result.query).toEqual({ page: "1", tab: "info" });
+  });
+
+  it("ignores query from invisible blades", () => {
+    const stack = [
+      makeDescriptor({ name: "Orders", url: "/orders", query: { page: "1" } }),
+      makeDescriptor({ name: "Details", url: "/order", query: { tab: "info" }, visible: false }),
+    ];
+    const result = buildUrlFromStack("", stack);
+    expect(result.query).toEqual({ page: "1" });
+  });
+});
+
+// ── parseBladeUrl ───────────────────────────────────────────────────────────────
+
+describe("parseBladeUrl", () => {
+  it("returns empty for root path", () => {
+    expect(parseBladeUrl("/")).toEqual({});
+  });
+
+  it("returns empty for empty string", () => {
+    expect(parseBladeUrl("")).toEqual({});
+  });
+
+  it("parses workspace-only path", () => {
+    expect(parseBladeUrl("/orders")).toEqual({ workspaceUrl: "orders" });
+  });
+
+  it("parses workspace + blade path", () => {
+    expect(parseBladeUrl("/orders/order")).toEqual({
+      workspaceUrl: "orders",
+      bladeUrl: "order",
+    });
+  });
+
+  it("parses workspace + blade + param path", () => {
+    expect(parseBladeUrl("/orders/order/uuid-123")).toEqual({
+      workspaceUrl: "orders",
+      bladeUrl: "order",
+      param: "uuid-123",
+    });
+  });
+
+  it("strips tenant prefix", () => {
+    expect(parseBladeUrl("/seller-1/orders/order/id-1", "seller-1")).toEqual({
+      workspaceUrl: "orders",
+      bladeUrl: "order",
+      param: "id-1",
+    });
+  });
+
+  it("handles missing tenant prefix gracefully", () => {
+    expect(parseBladeUrl("/orders", "non-existent-tenant")).toEqual({
+      workspaceUrl: "orders",
+    });
+  });
+
+  it("handles path without leading slash", () => {
+    expect(parseBladeUrl("orders/order")).toEqual({
+      workspaceUrl: "orders",
+      bladeUrl: "order",
+    });
+  });
+});
+
+// ── buildQueryString ────────────────────────────────────────────────────────────
+
+describe("buildQueryString", () => {
+  it("returns empty string for empty object", () => {
+    expect(buildQueryString({})).toBe("");
+  });
+
+  it("builds single-param string", () => {
+    expect(buildQueryString({ page: "1" })).toBe("?page=1");
+  });
+
+  it("builds multi-param string", () => {
+    const result = buildQueryString({ page: "1", sort: "name" });
+    expect(result).toContain("page=1");
+    expect(result).toContain("sort=name");
+    expect(result.startsWith("?")).toBe(true);
+  });
+
+  it("encodes special characters", () => {
+    expect(buildQueryString({ q: "hello world" })).toBe("?q=hello%20world");
+  });
+
+  it("skips empty string values", () => {
+    expect(buildQueryString({ page: "1", empty: "" })).toBe("?page=1");
+  });
+});

package/shared/components/blade-navigation/utils/urlSync.ts

@@ -0,0 +1,151 @@
+import type { Router } from "vue-router";
+import type { BladeDescriptor, IBladeStack, ParsedBladeUrl } from "../types";
+
+/**
+ * Build a URL path from the current blade stack.
+ *
+ * URL format: /<tenantPrefix>/<workspaceUrl>/<bladeUrl>/<param>
+ * - tenantPrefix: optional seller/tenant ID
+ * - workspaceUrl: from workspace blade's `url` (e.g. "/orders" → "orders")
+ * - bladeUrl: from active child blade's `url` (e.g. "/order" → "order")
+ * - param: entity ID
+ *
+ * @param tenantPrefix - Tenant/seller ID segment (empty string if none)
+ * @param stack - Current blade stack
+ * @returns path string and merged query params
+ */
+export function buildUrlFromStack(
+  tenantPrefix: string,
+  stack: readonly BladeDescriptor[],
+): { path: string; query: Record<string, string> } {
+  if (stack.length === 0) {
+    return { path: tenantPrefix ? `/${tenantPrefix}` : "/", query: {} };
+  }
+
+  const workspace = stack[0];
+  const wsUrl = normalizeSegment(workspace.url);
+
+  // Find the last visible child blade (not the workspace)
+  let activeBlade: BladeDescriptor | undefined;
+  for (let i = stack.length - 1; i >= 1; i--) {
+    if (stack[i].visible) {
+      activeBlade = stack[i];
+      break;
+    }
+  }
+
+  // Build path: /tenant/workspace or /tenant/workspace/blade/param
+  let path = tenantPrefix ? `/${tenantPrefix}` : "";
+
+  if (wsUrl) {
+    path += `/${wsUrl}`;
+  }
+
+  if (activeBlade) {
+    const bladeUrl = normalizeSegment(activeBlade.url);
+    if (bladeUrl) {
+      path += `/${bladeUrl}`;
+    }
+    if (activeBlade.param) {
+      path += `/${activeBlade.param}`;
+    }
+  }
+
+  // Merge query params from all visible blades
+  const query: Record<string, string> = {};
+  for (const blade of stack) {
+    if (blade.visible && blade.query) {
+      Object.assign(query, blade.query);
+    }
+  }
+
+  return { path: path || "/", query };
+}
+
+/**
+ * Parse a URL path into workspace, blade, and param segments.
+ *
+ * Handles both with and without tenant prefix:
+ *   /orders                    → { workspaceUrl: "orders" }
+ *   /orders/order/uuid         → { workspaceUrl: "orders", bladeUrl: "order", param: "uuid" }
+ *   /tenant-id/orders          → { workspaceUrl: "orders" } (after stripping tenant)
+ *   /tenant-id/orders/order/id → { workspaceUrl: "orders", bladeUrl: "order", param: "id" }
+ *
+ * @param hashPath - The path portion after the hash (e.g. "/orders/order/uuid")
+ * @param tenantPrefix - Optional tenant/seller ID to strip from the beginning
+ */
+export function parseBladeUrl(hashPath: string, tenantPrefix?: string): ParsedBladeUrl {
+  let segments = hashPath.split("/").filter(Boolean);
+
+  // Strip tenant prefix if present
+  if (tenantPrefix && segments.length > 0 && segments[0] === tenantPrefix) {
+    segments = segments.slice(1);
+  }
+
+  if (segments.length === 0) {
+    return {};
+  }
+
+  return {
+    workspaceUrl: segments[0],
+    bladeUrl: segments[1],
+    param: segments[2],
+  };
+}
+
+/**
+ * Build query string from a record of key-value pairs.
+ * Returns empty string if no params.
+ */
+export function buildQueryString(query: Record<string, string>): string {
+  const entries = Object.entries(query).filter(([, v]) => v !== undefined && v !== "");
+  if (entries.length === 0) return "";
+  return "?" + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+}
+
+/**
+ * Normalize a URL segment by removing leading/trailing slashes.
+ * "/orders/" → "orders", "orders" → "orders", undefined → undefined
+ */
+function normalizeSegment(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  return url.replace(/^\/+|\/+$/g, "") || undefined;
+}
+
+// ── Centralized URL sync helpers ──────────────────────────────────────────────
+
+/**
+ * Extract the tenant prefix from the current route params.
+ * Convention: first string param value (e.g. sellerId segment).
+ */
+export function getTenantPrefix(router: Router): string {
+  const params = router.currentRoute.value.params;
+  return (Object.values(params).find((v) => typeof v === "string" && v) as string) || "";
+}
+
+/**
+ * Creates URL sync helpers bound to a specific router and blade stack.
+ * Eliminates duplication between VcBladeNavigation and useBladeNavigationAdapter.
+ *
+ * @param router - Vue Router instance
+ * @param bladeStack - BladeStack state machine
+ */
+export function createUrlSync(router: Router, bladeStack: IBladeStack) {
+  /**
+   * Push URL to create a browser history entry (for blade open).
+   */
+  function syncUrlPush(): void {
+    const { path, query } = buildUrlFromStack(getTenantPrefix(router), bladeStack.blades.value);
+    router.push({ path, query });
+  }
+
+  /**
+   * Replace URL without creating a history entry (for blade close, cleanup).
+   */
+  function syncUrlReplace(): void {
+    const { path, query } = buildUrlFromStack(getTenantPrefix(router), bladeStack.blades.value);
+    router.replace({ path, query });
+  }
+
+  return { syncUrlPush, syncUrlReplace };
+}