@vc-shell/framework 1.2.4-beta.8 → 2.0.0-alpha.1

package/shared/components/blade-navigation/MIGRATION.md

@@ -1,224 +0,0 @@
-# Migration Guide: `useBladeNavigation()` → `useBladeContext()`
-
-## Why Migrate?
-
-The legacy `useBladeNavigation()` API is maintained via an adapter layer for backward compatibility. The new `useBladeContext()` API is cleaner, type-safe, and avoids common pitfalls:
-
-| Legacy (`useBladeNavigation`) | New (`useBladeContext`) |
-|-------------------------------|------------------------|
-| Index-based blade operations (fragile) | ID-based operations (stable) |
-| String method names for parent calls (no autocomplete) | Same, but with typed return values |
-| Manual `emit("parent:call", ...)` pattern | Direct `callParent(method, args)` |
-| Must manually track blade index | Auto-sets `parentId` |
-| Guard: `false` = prevent close | Guard: `true` = prevent close |
-
-## Prerequisites
-
-Your blade component must be rendered inside `VcBladeSlot` (the v2 render layer). If you're using VcBladeNavigation (new), this is already the case.
-
-## Step-by-Step Migration
-
-### 1. Replace the Import
-
-```diff
-- import { useBladeNavigation } from "@vc-shell/framework";
-- import { useBlade } from "@vc-shell/framework";
-+ import { useBladeContext } from "@vc-shell/framework";
-```
-
-### 2. Replace Setup Calls
-
-```diff
-- const { openBlade, closeBlade, onBeforeClose, onParentCall } = useBladeNavigation();
-- const blade = useBlade();
-+ const { param, options, expanded, closable, openBlade, closeSelf, callParent, onBeforeClose } = useBladeContext();
-```
-
-### 3. Access Blade Properties
-
-```diff
-  // Before: blade instance properties via useBlade()
-- const blade = useBlade();
-- const id = blade.value.param;
-- const opts = blade.value.options;
-
-  // After: direct computed refs
-+ const { param, options } = useBladeContext();
-+ // param.value, options.value — already reactive
-```
-
-### 4. Open a Blade
-
-```diff
-  // Before: pass component reference or { name } object
-- import { markRaw } from "vue";
-- import OrderDetails from "./order-details.vue";
-- openBlade({
--   blade: markRaw(OrderDetails),
--   param: orderId,
--   options: { product },
--   onOpen() { selectedId.value = orderId; },
--   onClose() { selectedId.value = undefined; },
-- });
-
-  // After: pass name string (component resolved from registry)
-+ openBlade({
-+   name: "OrderDetails",
-+   param: orderId,
-+   options: { product },
-+   onOpen() { selectedId.value = orderId; },
-+   onClose() { selectedId.value = undefined; },
-+ });
-```
-
-**Note**: `openBlade` from `useBladeContext()` auto-sets `parentId` to the current blade — no need to track indices.
-
-### 5. Close a Blade
-
-```diff
-  // Before: close by index (fragile)
-- closeBlade((blade.value.navigation?.idx ?? 0) + 1);
-
-  // After: close self (the most common case)
-+ closeSelf();
-```
-
-### 6. Call Parent Methods
-
-```diff
-  // Before: emit-based, no return value
-- emit("parent:call", {
--   method: "reload",
--   args: { id: item.id },
--   callback: (result) => { /* handle result */ },
-- });
-
-  // After: async/await, typed return value
-+ const result = await callParent<void>("reload", { id: item.id });
-```
-
-### 7. Expose Methods to Children
-
-```diff
-  // Before: implicit via defineExpose (VcBladeSlot extracts functions)
-- defineExpose({ reload, save, title });
-
-  // After: explicit registration (defineExpose still works for title)
-+ const { exposeToChildren } = useBladeContext();
-+ exposeToChildren({ reload, save });
-+ defineExpose({ title }); // title still propagated via defineExpose
-```
-
-### 8. Before-Close Guards
-
-```diff
-  // Before: return false to PREVENT close
-- onBeforeClose(async () => {
--   if (hasUnsavedChanges.value) {
--     return confirm("Discard changes?") ? undefined : false;
--     //                                    allow ↑    prevent ↑
--   }
-- });
-
-  // After: return true to PREVENT close
-+ onBeforeClose(async () => {
-+   if (hasUnsavedChanges.value) {
-+     return !confirm("Discard changes?");
-+     //      true = prevent, false = allow
-+   }
-+   return false; // allow close
-+ });
-```
-
-### 9. Replace Current Blade
-
-```diff
-  // Before: flag on openBlade
-- openBlade({
--   blade: markRaw(EditBlade),
--   replaceCurrentBlade: true,
--   param: item.id,
-- });
-
-  // After: dedicated method
-+ const { replaceWith } = useBladeContext();
-+ replaceWith({
-+   name: "EditBlade",
-+   param: item.id,
-+ });
-```
-
-### 10. Error Management
-
-```diff
-  // Before: by index
-- const { setBladeError, clearBladeError } = useBladeNavigation();
-- setBladeError(blade.value.navigation?.idx ?? 0, error);
-
-  // After: on current blade (no index needed)
-+ const { setError, clearError } = useBladeContext();
-+ setError(error);
-```
-
-## Full Example: Before & After
-
-### Before (Legacy)
-
-```vue
-<script lang="ts" setup>
-import { useBladeNavigation, useBlade } from "@vc-shell/framework";
-import { markRaw } from "vue";
-import OrderDetails from "./order-details.vue";
-
-const { openBlade, closeBlade, onBeforeClose, onParentCall } = useBladeNavigation();
-const blade = useBlade();
-
-onBeforeClose(async () => {
-  if (modified.value) return false; // prevent
-});
-
-function onItemClick(item: Order) {
-  openBlade({
-    blade: markRaw(OrderDetails),
-    param: item.id,
-    options: { source: "list" },
-    onOpen() { selectedId.value = item.id; },
-    onClose() { selectedId.value = undefined; },
-  });
-}
-
-function removeChild() {
-  closeBlade((blade.value.navigation?.idx ?? 0) + 1);
-}
-
-defineExpose({ reload, title });
-</script>
-```
-
-### After (New API)
-
-```vue
-<script lang="ts" setup>
-import { useBladeContext } from "@vc-shell/framework";
-
-const { param, options, openBlade, closeSelf, callParent, onBeforeClose, exposeToChildren } = useBladeContext();
-
-onBeforeClose(async () => {
-  if (modified.value) return true; // prevent
-  return false;
-});
-
-function onItemClick(item: Order) {
-  openBlade({
-    name: "OrderDetails",
-    param: item.id,
-    options: { source: "list" },
-    onOpen() { selectedId.value = item.id; },
-    onClose() { selectedId.value = undefined; },
-  });
-}
-
-exposeToChildren({ reload });
-defineExpose({ title }); // title still needs defineExpose for VcBladeSlot propagation
-</script>
-```

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

@@ -1,2 +0,0 @@
-export * from "@shared/components/blade-navigation/components/vc-blade-navigation";
-export * from "@shared/components/blade-navigation/components/vc-blade-slot";

package/shared/components/blade-navigation/components/vc-blade-navigation/_internal/vc-mobile-back-button.vue

@@ -1,78 +0,0 @@
-<template>
-  <VcBreadcrumbs
-    v-on-click-outside="hideBreadcrumbs"
-    :items="breadcrumbs"
-    collapsed
-  >
-    <template #trigger="{ click }">
-      <OnLongPress
-        as="button"
-        @trigger="click"
-      >
-        <VcButton
-          ref="buttonRef"
-          icon="material-arrow_back"
-          icon-class="tw-text-neutrals-500"
-          icon-size="l"
-          text
-          @click="onClick"
-          @contextmenu.prevent
-        />
-      </OnLongPress>
-    </template>
-  </VcBreadcrumbs>
-</template>
-
-<script lang="ts" setup>
-import { ref } from "vue";
-import { onLongPress } from "@vueuse/core";
-import { VcButton } from "@ui/components/atoms/vc-button";
-import VcBreadcrumbs from "@ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.vue";
-import type { Breadcrumbs } from "@ui/types";
-import { OnLongPress, vOnClickOutside } from "@vueuse/components";
-
-const props = defineProps<{
-  breadcrumbs: Breadcrumbs[];
-  onBack: () => void;
-}>();
-
-const buttonRef = ref<HTMLElement>();
-const showBreadcrumbs = ref(false);
-
-const onClick = () => {
-  props.onBack();
-};
-
-onLongPress(
-  buttonRef,
-  () => {
-    showBreadcrumbs.value = true;
-  },
-  { delay: 500 },
-);
-
-const hideBreadcrumbs = () => {
-  showBreadcrumbs.value = false;
-};
-</script>
-
-<style lang="scss">
-.vc-mobile-back-button {
-  position: relative;
-
-  &__breadcrumbs {
-    position: fixed;
-    z-index: 1000;
-    background: var(--additional-50);
-    border-radius: var(--blade-navigation-border-radius);
-    box-shadow: var(--blade-navigation-shadow);
-    padding: 0.5rem;
-
-    &-button {
-      &--active {
-        background-color: var(--neutrals-100);
-      }
-    }
-  }
-}
-</style>

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

@@ -1,2 +0,0 @@
-export { default as VcBladeNavigation } from "@shared/components/blade-navigation/components/vc-blade-navigation/vc-blade-navigation-new.vue";
-export { default as VcBladeNavigationV2 } from "@shared/components/blade-navigation/components/vc-blade-navigation/vc-blade-navigation-new.vue";

package/shared/components/blade-navigation/components/vc-blade-navigation/vc-blade-navigation-new.vue

@@ -1,160 +0,0 @@
-<template>
-  <div class="vc-blade-navigation tw-flex tw-flex-col tw-grow tw-basis-0 tw-min-w-0 tw-overflow-hidden">
-    <!-- Non-blade routes (Dashboard, etc.) -->
-    <RouterView v-if="!hasBlades" />
-
-    <!-- Blade stack -->
-    <div
-      v-else
-      class="tw-overflow-hidden tw-flex tw-grow tw-basis-0 tw-relative tw-min-w-0"
-    >
-      <VcBladeSlot
-        v-for="(descriptor, index) in blades"
-        :key="descriptor.id"
-        :descriptor="descriptor"
-        :closable="index > 0"
-        :expanded="descriptor.id === activeBlade?.id"
-        :visible="isBladeVisible(descriptor, index)"
-        :breadcrumbs="breadcrumbs.slice(0, index)"
-        :back-button="
-          bladeCount > 1
-            ? mobileBackButtonFor(index)
-            : undefined
-        "
-        @close="onClose"
-        @parent-call="onParentCall"
-      />
-    </div>
-  </div>
-</template>
-
-<script lang="ts" setup>
-import { computed, h, inject, Ref, toRef } from "vue";
-import { IsMobileKey } from "@framework/injection-keys";
-import { RouterView, useRouter } from "vue-router";
-import { watchDebounced } from "@vueuse/core";
-import { VcBladeSlot } from "@shared/components/blade-navigation/components/vc-blade-slot";
-import VcMobileBackButton from "@shared/components/blade-navigation/components/vc-blade-navigation/_internal/vc-mobile-back-button.vue";
-import { useBladeStack } from "@shared/components/blade-navigation/composables/useBladeStack";
-import { useBladeMessaging } from "@shared/components/blade-navigation/composables/useBladeMessaging";
-import { createUrlSync } from "@shared/components/blade-navigation/utils/urlSync";
-import { useBreadcrumbs } from "@core/composables/useBreadcrumbs";
-import { AiAgentServiceKey } from "@framework/injection-keys";
-import type { BladeDescriptor, IParentCallArgs } from "@shared/components/blade-navigation/types";
-
-const bladeStack = useBladeStack();
-const messaging = useBladeMessaging();
-const router = useRouter();
-const { breadcrumbs, push, remove } = useBreadcrumbs();
-
-// ── URL sync helper (centralized in urlSync.ts) ─────────────────────────────
-
-const { syncUrlReplace } = createUrlSync(router, bladeStack);
-
-// ── Blade state ─────────────────────────────────────────────────────────────
-
-const blades = computed(() => bladeStack.blades.value);
-const activeBlade = computed(() => bladeStack.activeBlade.value);
-const hasBlades = computed(() => blades.value.length > 0);
-
-const bladeCount = computed(() => {
-  return blades.value.filter((b) => b.visible).length;
-});
-
-// ── Visibility logic ────────────────────────────────────────────────────────
-
-const isMobile = inject(IsMobileKey)!;
-
-const aiAgentService = inject(AiAgentServiceKey, undefined);
-const isAiPanelExpanded = computed(() => aiAgentService?.isExpanded.value ?? false);
-
-const visibleBladesCount = computed(() => {
-  if (isMobile.value) return 1;
-  if (isAiPanelExpanded.value) return 1;
-  return 2;
-});
-
-function isBladeVisible(descriptor: BladeDescriptor, index: number): boolean {
-  if (!descriptor.visible) return false;
-  return index >= bladeCount.value - visibleBladesCount.value;
-}
-
-// ── Breadcrumbs sync ────────────────────────────────────────────────────────
-
-watchDebounced(
-  blades,
-  (newVal) => {
-    // Clear existing breadcrumbs
-    breadcrumbs.value.forEach((bc) => bc && remove([bc.id]));
-
-    // Rebuild from current blade stack
-    newVal.forEach((descriptor, index) => {
-      push({
-        id: index.toString(),
-        title: toRef({ title: descriptor.name }, "title"),
-        clickHandler: async (id) => {
-          const targetIndex = parseInt(id) + 1;
-          const bladeToClose = blades.value[targetIndex];
-          if (bladeToClose) {
-            const prevented = await bladeStack.closeBlade(bladeToClose.id);
-            if (!prevented) {
-              syncUrlReplace();
-            }
-            return !prevented;
-          }
-          return true;
-        },
-      });
-    });
-  },
-  {
-    deep: true,
-    immediate: true,
-    flush: "post",
-    debounce: 10,
-  },
-);
-
-// ── Event handlers ──────────────────────────────────────────────────────────
-
-async function onClose(bladeId: string): Promise<void> {
-  const prevented = await bladeStack.closeBlade(bladeId);
-  if (!prevented) {
-    syncUrlReplace();
-  }
-}
-
-async function onParentCall(args: IParentCallArgs, bladeId: string): Promise<void> {
-  try {
-    const result = await messaging.callParent(bladeId, args.method as string, args.args);
-    args.callback?.(result);
-  } catch (error) {
-    console.warn("[VcBladeNavigation] Parent call failed:", error);
-  }
-}
-
-// ── Mobile back button ──────────────────────────────────────────────────────
-
-function mobileBackButtonFor(index: number): ReturnType<typeof h> | undefined {
-  if (index <= 0) return undefined;
-  return h(VcMobileBackButton, {
-    breadcrumbs: breadcrumbs.value.slice(0, index),
-    onBack: async () => {
-      const blade = blades.value[index];
-      if (blade) {
-        const prevented = await bladeStack.closeBlade(blade.id);
-        if (!prevented) syncUrlReplace();
-      }
-    },
-  });
-}
-</script>
-
-<style lang="scss">
-:root {
-  --blade-navigation-bg-color: var(--additional-50);
-  --blade-navigation-shadow-color: var(--additional-950);
-  --blade-navigation-shadow: 2px 2px 8px rgb(from var(--blade-navigation-shadow-color) r g b / 7%);
-  --blade-navigation-border-radius: var(--blade-border-radius);
-}
-</style>

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

@@ -1 +0,0 @@
-export { default as VcBladeSlot } from "@shared/components/blade-navigation/components/vc-blade-slot/vc-blade-slot.vue";

package/shared/components/blade-navigation/components/vc-blade-slot/vc-blade-slot.vue

@@ -1,143 +0,0 @@
-<template>
-  <ErrorInterceptor :capture="true">
-    <template #default="{ error: interceptorError, reset: resetInterceptor }">
-      <component
-        :is="bladeComponent"
-        v-if="bladeComponent"
-        v-show="visible"
-        ref="bladeInstanceRef"
-        :param="descriptor.param"
-        :options="descriptor.options"
-        :closable="closable"
-        :expanded="expanded"
-        @close:blade="onCloseBlade"
-        @parent:call="onParentCall"
-        @expand:blade="onExpand"
-        @collapse:blade="onCollapse"
-        @vue:unmounted="resetInterceptor"
-      />
-    </template>
-  </ErrorInterceptor>
-</template>
-
-<script lang="ts" setup>
-import { computed, onBeforeUnmount, provide, ref, watch, watchEffect } from "vue";
-import { useBladeRegistry } from "@core/composables/useBladeRegistry";
-import { BladeInstance as BladeInstanceKey, BLADE_BACK_BUTTON } from "@framework/injection-keys";
-import { ErrorInterceptor } from "@shared/components/error-interceptor";
-import { useBladeMessaging } from "@shared/components/blade-navigation/composables/useBladeMessaging";
-import { useBladeStack } from "@shared/components/blade-navigation/composables/useBladeStack";
-import type { BladeDescriptor, IBladeInstance, IParentCallArgs } from "@shared/components/blade-navigation/types";
-import { BladeDescriptorKey } from "@shared/components/blade-navigation/types";
-import type { CoreBladeExposed } from "@shared/components/blade-navigation/types";
-import type { Breadcrumbs } from "@ui/types";
-import type { Component } from "vue";
-
-const props = defineProps<{
-  descriptor: BladeDescriptor;
-  closable: boolean;
-  expanded: boolean;
-  visible: boolean;
-  breadcrumbs?: Breadcrumbs[];
-  backButton?: Component;
-}>();
-
-const emit = defineEmits<{
-  (e: "close", bladeId: string): void;
-  (e: "parentCall", args: IParentCallArgs, bladeId: string): void;
-}>();
-
-const bladeRegistry = useBladeRegistry();
-const bladeStack = useBladeStack();
-const maximized = ref(false);
-const bladeInstanceRef = ref<CoreBladeExposed>();
-
-// Resolve blade component from registry
-const bladeComponent = computed(() => {
-  return bladeRegistry.getBladeComponent(props.descriptor.name);
-});
-
-// ── Provide new injection key (BladeDescriptor) ─────────────────────────────
-provide(
-  BladeDescriptorKey,
-  computed(() => props.descriptor),
-);
-
-// ── Provide legacy injection key (BladeInstance) for backward compatibility ──
-provide(
-  BladeInstanceKey,
-  computed<IBladeInstance>(() => ({
-    id: props.descriptor.name.toLowerCase(),
-    param: props.descriptor.param,
-    options: props.descriptor.options,
-    expandable: props.closable, // expandable when there are multiple blades
-    maximized: maximized.value,
-    error: (props.descriptor.error as IBladeInstance["error"]) ?? null,
-    navigation: undefined, // No longer VNode-based
-    breadcrumbs: props.breadcrumbs,
-    title: bladeInstanceRef.value?.title,
-  })),
-);
-
-// Provide back button component
-provide(
-  BLADE_BACK_BUTTON,
-  computed(() => props.backButton),
-);
-
-// ── Auto-register exposed methods with BladeMessaging ───────────────────────
-// Bridges defineExpose() (old API) → exposeToChildren() (new BladeMessaging)
-const messaging = useBladeMessaging();
-
-watch(
-  bladeInstanceRef,
-  (instance) => {
-    if (!instance) return;
-    const methods: Record<string, (...args: any[]) => any> = {};
-    for (const key of Object.keys(instance)) {
-      if (typeof instance[key] === "function") {
-        methods[key] = instance[key];
-      }
-    }
-    if (Object.keys(methods).length > 0) {
-      messaging.exposeToChildren(props.descriptor.id, methods);
-    }
-  },
-  { flush: "post" },
-);
-
-// Clean up exposed methods when blade is removed from the stack.
-// Hidden blades (v-show via replaceCurrentBlade) stay mounted — their methods persist.
-// Only truly removed blades (v-for key removed) trigger onBeforeUnmount.
-onBeforeUnmount(() => {
-  messaging.cleanup(props.descriptor.id);
-});
-
-// ── Propagate exposed title to BladeStack ────────────────────────────────────
-// Uses watchEffect so it tracks reactivity of bladeInstanceRef.value?.title
-// (which may be a ref exposed via defineExpose)
-watchEffect(() => {
-  const title = bladeInstanceRef.value?.title;
-  if (title !== undefined) {
-    bladeStack.setBladeTitle(props.descriptor.id, title);
-  }
-});
-
-// ── Event handlers ──────────────────────────────────────────────────────────
-
-function onCloseBlade(): void {
-  emit("close", props.descriptor.id);
-}
-
-function onParentCall(args: IParentCallArgs): void {
-  emit("parentCall", args, props.descriptor.id);
-}
-
-function onExpand(): void {
-  maximized.value = true;
-}
-
-function onCollapse(): void {
-  maximized.value = false;
-}
-</script>