@forgeax/app-shell 0.9.1 → 0.11.0

package/dist/dock.d.ts

@@ -43,6 +43,32 @@ interface SerializedDockLayoutLike {
  * leaves and branches. The input snapshot is never mutated.
  */
 declare function pruneSerializedDockLayout<T extends SerializedDockLayoutLike>(layout: T, knownComponents: ReadonlySet<string>, allowedPanelIds?: ReadonlySet<string>): T | null;
+type DockLayoutOrientation = 'HORIZONTAL' | 'VERTICAL';
+type DockReopenDirection = 'left' | 'right' | 'above' | 'below' | 'within';
+/** Structural shape shared by concrete serialized dock tree implementations. */
+interface AuthoredDockNodeLike {
+    readonly type: 'leaf' | 'branch';
+    readonly data: unknown;
+}
+interface AuthoredDockLayoutLike {
+    readonly grid?: {
+        readonly orientation: DockLayoutOrientation;
+        readonly root?: AuthoredDockNodeLike;
+    };
+}
+type DesignedDockPanelPosition = {
+    readonly kind: 'relative';
+    readonly referencePanel: string;
+    readonly direction: DockReopenDirection;
+} | {
+    readonly kind: 'edge';
+    readonly direction: Exclude<DockReopenDirection, 'within'>;
+};
+/**
+ * Derive a closed panel's authored seat against a panel that is still open.
+ * Returns undefined when the panel is absent or no live sibling can anchor it.
+ */
+declare function designedDockPanelPosition(layout: AuthoredDockLayoutLike, panelId: string, isOpen: (id: string) => boolean): DesignedDockPanelPosition | undefined;
 type SideEdge = 'left' | 'right';
 interface RectLike {
     left: number;
@@ -80,4 +106,4 @@ declare function handleCrossInstanceDrop(event: CrossInstanceDropEvent, targetRe
     titleFor?: (panelId: string) => string | undefined;
 }): void;
 
-export { type CrossInstanceDropEvent, DOCK_REGIONS, type DockRegion, type DockRegionEntry, type DockviewApiLike, type PanelDescriptorLite, REGIONS, type RectLike, type Region, type SerializedDockLayoutLike, type SerializedDockPanelLike, type SideEdge, getDockRegions, getDockviewApi, handleCrossInstanceDrop, hasMountedPanelPlacement, isDockPanelVisible, isDockRegion, isOnSideEdge, nearerSideEdge, pruneSerializedDockLayout, registerDockRegion, registerDockviewApi, resolveRegion, trackDockPanelVisibility };
+export { type AuthoredDockLayoutLike, type AuthoredDockNodeLike, type CrossInstanceDropEvent, DOCK_REGIONS, type DesignedDockPanelPosition, type DockLayoutOrientation, type DockRegion, type DockRegionEntry, type DockReopenDirection, type DockviewApiLike, type PanelDescriptorLite, REGIONS, type RectLike, type Region, type SerializedDockLayoutLike, type SerializedDockPanelLike, type SideEdge, designedDockPanelPosition, getDockRegions, getDockviewApi, handleCrossInstanceDrop, hasMountedPanelPlacement, isDockPanelVisible, isDockRegion, isOnSideEdge, nearerSideEdge, pruneSerializedDockLayout, registerDockRegion, registerDockviewApi, resolveRegion, trackDockPanelVisibility };

package/dist/dock.js

@@ -84,6 +84,75 @@ function pruneSerializedDockLayout(layout, knownComponents, allowedPanelIds) {
     grid: layout.grid ? { ...layout.grid, root } : layout.grid
   };
 }
+function authoredLeafViews(node) {
+  if (node.type !== "leaf" || !node.data || typeof node.data !== "object") return [];
+  const views = node.data.views;
+  return Array.isArray(views) ? views : [];
+}
+function authoredBranchChildren(node) {
+  return node.type === "branch" && Array.isArray(node.data) ? node.data : [];
+}
+function firstOpenAuthoredPanel(node, isOpen) {
+  if (node.type === "leaf") return authoredLeafViews(node).find(isOpen);
+  for (const child of authoredBranchChildren(node)) {
+    const match = firstOpenAuthoredPanel(child, isOpen);
+    if (match) return match;
+  }
+  return void 0;
+}
+function findAuthoredPanelPath(root, panelId) {
+  if (root.type === "leaf") {
+    return authoredLeafViews(root).includes(panelId) ? [root] : void 0;
+  }
+  for (const child of authoredBranchChildren(root)) {
+    const path = findAuthoredPanelPath(child, panelId);
+    if (path) return [root, ...path];
+  }
+  return void 0;
+}
+function authoredBranchOrientation(rootOrientation, depth) {
+  if (depth % 2 === 0) return rootOrientation;
+  return rootOrientation === "HORIZONTAL" ? "VERTICAL" : "HORIZONTAL";
+}
+function designedDockPanelPosition(layout, panelId, isOpen) {
+  const root = layout.grid?.root;
+  if (!root) return void 0;
+  const path = findAuthoredPanelPath(root, panelId);
+  if (!path) return void 0;
+  const leaf = path[path.length - 1];
+  const tabMate = authoredLeafViews(leaf).find((id) => id !== panelId && isOpen(id));
+  if (tabMate) return { kind: "relative", referencePanel: tabMate, direction: "within" };
+  if (path.length === 2 && path[0].type === "branch") {
+    const siblings = authoredBranchChildren(path[0]);
+    const index = siblings.indexOf(leaf);
+    const horizontal = layout.grid?.orientation === "HORIZONTAL";
+    if (index === 0) return { kind: "edge", direction: horizontal ? "left" : "above" };
+    if (index === siblings.length - 1) {
+      return { kind: "edge", direction: horizontal ? "right" : "below" };
+    }
+  }
+  for (let depth = path.length - 2; depth >= 0; depth--) {
+    const branch = path[depth];
+    if (branch.type !== "branch") continue;
+    const children = authoredBranchChildren(branch);
+    const index = children.indexOf(path[depth + 1]);
+    if (index < 0) continue;
+    const horizontal = authoredBranchOrientation(layout.grid.orientation, depth) === "HORIZONTAL";
+    for (let i = index + 1; i < children.length; i++) {
+      const referencePanel = firstOpenAuthoredPanel(children[i], isOpen);
+      if (referencePanel) {
+        return { kind: "relative", referencePanel, direction: horizontal ? "left" : "above" };
+      }
+    }
+    for (let i = index - 1; i >= 0; i--) {
+      const referencePanel = firstOpenAuthoredPanel(children[i], isOpen);
+      if (referencePanel) {
+        return { kind: "relative", referencePanel, direction: horizontal ? "right" : "below" };
+      }
+    }
+  }
+  return void 0;
+}
 function isOnSideEdge(location) {
   return location.type === "edge" && (location.position === "left" || location.position === "right");
 }
@@ -138,6 +207,7 @@ function handleCrossInstanceDrop(event, targetRegion, moveTo, options) {
 export {
   DOCK_REGIONS,
   REGIONS,
+  designedDockPanelPosition,
   getDockRegions,
   getDockviewApi,
   handleCrossInstanceDrop,

package/dist/window.d.ts

@@ -0,0 +1,31 @@
+type SurfacePane = 'left' | 'center';
+type SurfaceKind = 'plugin' | 'panel';
+/** Structural identity shared by in-window and detached surface carriers. */
+interface SurfaceDescriptor {
+    readonly kind: SurfaceKind;
+    readonly id: string;
+    readonly pane?: SurfacePane;
+    readonly instance?: string;
+}
+/** Complete carrier-neutral declaration for opening one detached surface. */
+interface DetachedWindowTarget {
+    readonly surface: SurfaceDescriptor;
+    readonly title: string;
+    readonly width: number;
+    readonly height: number;
+    readonly dockBehavior: 'close' | 'keep-anchor';
+}
+/** Presence of this factory declares that a surface may be detached. */
+interface DetachedWindowCapability<Context = void> {
+    createTarget(context: Context): DetachedWindowTarget;
+}
+/** Stable identity shared by keep-alive registries and physical carriers. */
+declare function surfaceKey(surface: SurfaceDescriptor): string;
+/** Deterministic, injective and carrier-safe label for the complete identity. */
+declare function surfaceWindowLabel(surface: SurfaceDescriptor): string;
+/** Encode only structural surface identity; product carrier policy stays outside. */
+declare function encodeSurfaceQuery(surface: SurfaceDescriptor): string;
+/** Decode structural identity, or null for a normal shell/invalid entry. */
+declare function decodeSurfaceFromLocation(search?: string): SurfaceDescriptor | null;
+
+export { type DetachedWindowCapability, type DetachedWindowTarget, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, decodeSurfaceFromLocation, encodeSurfaceQuery, surfaceKey, surfaceWindowLabel };

package/dist/window.js

@@ -0,0 +1,57 @@
+// src/window.ts
+function surfaceKey(surface) {
+  return JSON.stringify([
+    surface.kind,
+    surface.id,
+    surface.pane ?? null,
+    surface.instance ?? null
+  ]);
+}
+var BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function utf8ToBase64Url(value) {
+  const bytes = new TextEncoder().encode(value);
+  let encoded = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index];
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    encoded += BASE64URL_ALPHABET[first >> 2];
+    encoded += BASE64URL_ALPHABET[(first & 3) << 4 | (second ?? 0) >> 4];
+    if (second !== void 0) {
+      encoded += BASE64URL_ALPHABET[(second & 15) << 2 | (third ?? 0) >> 6];
+    }
+    if (third !== void 0) encoded += BASE64URL_ALPHABET[third & 63];
+  }
+  return encoded;
+}
+function surfaceWindowLabel(surface) {
+  return `fx-surface-${utf8ToBase64Url(surfaceKey(surface))}`;
+}
+function encodeSurfaceQuery(surface) {
+  const params = new URLSearchParams();
+  params.set("surface", surface.kind);
+  params.set("id", surface.id);
+  if (surface.pane) params.set("pane", surface.pane);
+  if (surface.instance !== void 0) params.set("instance", surface.instance);
+  return params.toString();
+}
+function decodeSurfaceFromLocation(search = typeof window !== "undefined" ? window.location.search : "") {
+  const params = new URLSearchParams(search);
+  const kind = params.get("surface");
+  const id = params.get("id");
+  if (!id || kind !== "plugin" && kind !== "panel") return null;
+  const pane = params.get("pane");
+  const instance = params.get("instance");
+  return {
+    kind,
+    id,
+    pane: pane === "left" || pane === "center" ? pane : void 0,
+    instance: instance ?? void 0
+  };
+}
+export {
+  decodeSurfaceFromLocation,
+  encodeSurfaceQuery,
+  surfaceKey,
+  surfaceWindowLabel
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/dock.d.ts",
       "import": "./dist/dock.js"
     },
+    "./window": {
+      "types": "./dist/window.d.ts",
+      "import": "./dist/window.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
@@ -27,7 +31,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test test",
-    "build": "tsup src/index.ts src/dock.ts src/react.tsx --format esm --dts --outDir dist && bun run scripts/copy-resize-css.ts && bun run scripts/copy-panel-css.ts",
+    "build": "tsup src/index.ts src/dock.ts src/window.ts src/react.tsx --format esm --dts --outDir dist && bun run scripts/copy-resize-css.ts && bun run scripts/copy-panel-css.ts",
     "check": "bun run typecheck && bun run test && bun run build",
     "release:preflight": "bun run scripts/release-preflight.ts"
   },