@forgeax/app-shell 0.13.0 → 0.15.0

package/dist/chunk-ZYCR2LSP.js

@@ -0,0 +1,270 @@
+// src/window.ts
+function canOpenPanelWindow(capability, carrierAvailable) {
+  return capability !== void 0 && carrierAvailable;
+}
+function shouldShowDetachedPlaceholder(floatingSurfaces, surface) {
+  return floatingSurfaces[surfaceKey(surface)] === true;
+}
+function createPanelWindowingController() {
+  const detachedPanels = /* @__PURE__ */ new Map();
+  return {
+    async openPanelWindow(panelId, capability, options) {
+      if (!capability) return false;
+      let target;
+      try {
+        target = capability.createTarget();
+      } catch {
+        return false;
+      }
+      const key = surfaceKey(target.surface);
+      const closesPlacement = target.dockBehavior === "close";
+      let reservation;
+      if (closesPlacement) {
+        if (!options.closeDockPanel || detachedPanels.has(key)) return false;
+        reservation = { panelId, state: "pending" };
+        detachedPanels.set(key, reservation);
+      }
+      let opened;
+      try {
+        opened = await options.detachSurface(target.surface, {
+          title: target.title,
+          width: target.width,
+          height: target.height,
+          ...options.position
+        });
+      } catch {
+        if (reservation && detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+        return false;
+      }
+      if (!opened) {
+        if (reservation && detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+        return false;
+      }
+      if (closesPlacement) {
+        if (detachedPanels.get(key) !== reservation) return false;
+        try {
+          options.closeDockPanel();
+        } catch {
+          if (detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+          return false;
+        }
+        reservation.state = "leased";
+      }
+      return true;
+    },
+    panelForClosedSurface(surface) {
+      const key = surfaceKey(surface);
+      const lease = detachedPanels.get(key);
+      if (lease?.state === "pending") {
+        detachedPanels.delete(key);
+        return void 0;
+      }
+      if (lease?.state === "leased") {
+        queueMicrotask(() => {
+          if (detachedPanels.get(key) === lease) detachedPanels.delete(key);
+        });
+      }
+      return lease?.state === "leased" ? lease.panelId : void 0;
+    }
+  };
+}
+function currentBrowserHost() {
+  if (typeof window === "undefined" || typeof window.open !== "function") return void 0;
+  return {
+    screen: window.screen,
+    open: (url, target, features) => window.open(url, target, features),
+    setInterval: (callback, delayMs) => window.setInterval(callback, delayMs),
+    clearInterval: (handle) => window.clearInterval(handle)
+  };
+}
+function createBrowserWindowManager(options) {
+  const host = options.host ?? currentBrowserHost();
+  const windows = /* @__PURE__ */ new Map();
+  const closePolls = /* @__PURE__ */ new Map();
+  const closeListeners = /* @__PURE__ */ new Set();
+  const forget = (surface) => {
+    const key = surfaceWindowLabel(surface);
+    const poll = closePolls.get(key);
+    if (poll !== void 0) host?.clearInterval(poll);
+    closePolls.delete(key);
+    windows.delete(key);
+  };
+  const notifyClosed = (surface) => {
+    for (const listener of closeListeners) {
+      try {
+        listener(surface);
+      } catch {
+      }
+    }
+  };
+  return {
+    canDetach: () => host !== void 0,
+    async openSurfaceWindow(surface, detachOptions) {
+      if (!host) return false;
+      const label = surfaceWindowLabel(surface);
+      const existing = windows.get(label);
+      if (existing !== void 0 && !existing.closed) {
+        existing.focus();
+        return true;
+      }
+      if (existing !== void 0) forget(surface);
+      const width = detachOptions?.width ?? 960;
+      const height = detachOptions?.height ?? 720;
+      const left = detachOptions?.x ?? Math.max(0, Math.round((host.screen.width - width) / 2));
+      const top = detachOptions?.y ?? Math.max(0, Math.round((host.screen.height - height) / 2));
+      const popup = host.open(
+        options.surfaceUrl(surface),
+        label,
+        `popup=yes,width=${width},height=${height},left=${left},top=${top},resizable=yes`
+      );
+      if (popup === null) return false;
+      windows.set(label, popup);
+      const poll = host.setInterval(() => {
+        if (!popup.closed) return;
+        forget(surface);
+        notifyClosed(surface);
+      }, options.closePollIntervalMs ?? 250);
+      closePolls.set(label, poll);
+      return true;
+    },
+    async closeSurfaceWindow(surface) {
+      const popup = windows.get(surfaceWindowLabel(surface));
+      if (popup !== void 0 && !popup.closed) popup.close();
+      forget(surface);
+    },
+    async isSurfaceWindowOpen(surface) {
+      const popup = windows.get(surfaceWindowLabel(surface));
+      return popup !== void 0 && !popup.closed;
+    },
+    onSurfaceWindowClosed(listener) {
+      closeListeners.add(listener);
+      return () => {
+        closeListeners.delete(listener);
+      };
+    }
+  };
+}
+function createExternalWindowManager(options) {
+  const closeListeners = /* @__PURE__ */ new Set();
+  const notifyClosed = (surface) => {
+    for (const listener of closeListeners) {
+      try {
+        listener(surface);
+      } catch {
+      }
+    }
+  };
+  return {
+    canDetach: options.canDetach,
+    async openSurfaceWindow(surface, detachOptions) {
+      const host = await options.loadHost();
+      if (!host) return false;
+      const label = surfaceWindowLabel(surface);
+      const existing = await host.getByLabel(label);
+      if (existing) {
+        try {
+          await existing.show();
+          await existing.focus();
+          return true;
+        } catch {
+        }
+      }
+      return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          resolve(result);
+        };
+        const timeout = setTimeout(() => finish(true), options.createdTimeoutMs ?? 2e3);
+        void host.create(label, surface, detachOptions, {
+          created: () => finish(true),
+          error: () => finish(false),
+          destroyed: () => notifyClosed(surface)
+        }).catch(() => finish(false));
+      });
+    },
+    async closeSurfaceWindow(surface) {
+      const host = await options.loadHost();
+      if (!host) return;
+      const existing = await host.getByLabel(surfaceWindowLabel(surface));
+      if (!existing) return;
+      try {
+        await existing.close();
+      } catch {
+      }
+    },
+    async isSurfaceWindowOpen(surface) {
+      const host = await options.loadHost();
+      if (!host) return false;
+      return await host.getByLabel(surfaceWindowLabel(surface)) !== null;
+    },
+    onSurfaceWindowClosed(listener) {
+      closeListeners.add(listener);
+      return () => {
+        closeListeners.delete(listener);
+      };
+    }
+  };
+}
+function surfaceKey(surface) {
+  const id = surface.id.includes(":") || surface.id.startsWith("~") ? `~${encodeURIComponent(surface.id)}` : surface.id;
+  const pane = surface.pane ? `:${surface.pane}` : "";
+  const instance = surface.instance ? `:instance=${encodeURIComponent(surface.instance)}` : "";
+  return `${surface.kind}:${id}${pane}${instance}`;
+}
+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) 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 {
+  canOpenPanelWindow,
+  shouldShowDetachedPlaceholder,
+  createPanelWindowingController,
+  createBrowserWindowManager,
+  createExternalWindowManager,
+  surfaceKey,
+  surfaceWindowLabel,
+  encodeSurfaceQuery,
+  decodeSurfaceFromLocation
+};

package/dist/react.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactElement, HTMLAttributes, ReactNode } from 'react';
+import { DetachedWindowCapability } from './window.js';
 
 /** Stable FNV-1a color bucket for a shell slot name. */
 declare function hashSlotHue(name: string): number;
@@ -39,6 +40,15 @@ interface PanelSurfaceProps extends Omit<HTMLAttributes<HTMLElement>, 'children'
 /** Product-neutral panel section and content presentation. */
 declare function PanelSurface({ id, registered, singleTab, header, content, children, className, ...props }: PanelSurfaceProps): ReactElement;
 
+interface DetachedPanelBoundaryProps {
+    readonly capability?: DetachedWindowCapability;
+    readonly floatingSurfaces: Readonly<Record<string, true>>;
+    readonly placeholder: ReactNode;
+    readonly children: ReactNode;
+}
+/** Product-neutral presentation switch for a keep-anchor detached surface. */
+declare function DetachedPanelBoundary({ capability, floatingSurfaces, placeholder, children, }: DetachedPanelBoundaryProps): ReactNode;
+
 type ShellSlotElement = 'aside' | 'div' | 'main' | 'section';
 interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
     as?: ShellSlotElement;
@@ -47,4 +57,4 @@ interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
 /** Structural shell marker that preserves the caller's semantic element. */
 declare function ShellSlot({ as, name, ...props }: ShellSlotProps): ReactElement;
 
-export { type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelSurface, type PanelSurfaceProps, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled, useLocalSize };
+export { DetachedPanelBoundary, type DetachedPanelBoundaryProps, type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelSurface, type PanelSurfaceProps, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled, useLocalSize };

package/dist/react.js

@@ -1,3 +1,7 @@
+import {
+  shouldShowDetachedPlaceholder
+} from "./chunk-ZYCR2LSP.js";
+
 // src/react.tsx
 import { createElement } from "react";
 
@@ -293,6 +297,24 @@ function PanelSurface({
   );
 }
 
+// src/detached-panel.tsx
+function DetachedPanelBoundary({
+  capability,
+  floatingSurfaces,
+  placeholder,
+  children
+}) {
+  if (!capability) return children;
+  try {
+    const target = capability.createTarget();
+    if (target.dockBehavior === "keep-anchor" && shouldShowDetachedPlaceholder(floatingSurfaces, target.surface)) {
+      return placeholder;
+    }
+  } catch {
+  }
+  return children;
+}
+
 // src/react.tsx
 function ShellSlot({
   as = "div",
@@ -302,6 +324,7 @@ function ShellSlot({
   return createElement(as, { ...props, "data-fx-slot": name });
 }
 export {
+  DetachedPanelBoundary,
   PanelSurface,
   ResizeHandle,
   ShellSlot,

package/dist/window.d.ts

@@ -73,6 +73,19 @@ interface CreateExternalWindowManagerOptions {
     readonly loadHost: () => Promise<ExternalWindowHost | undefined>;
     readonly createdTimeoutMs?: number;
 }
+interface OpenPanelWindowOptions {
+    readonly detachSurface: (surface: SurfaceDescriptor, options: Required<Pick<DetachWindowOptions, 'title' | 'width' | 'height'>> & Pick<DetachWindowOptions, 'x' | 'y'>) => Promise<boolean>;
+    readonly position?: Readonly<Pick<DetachWindowOptions, 'x' | 'y'>>;
+    readonly closeDockPanel?: () => void;
+}
+interface PanelWindowingController {
+    openPanelWindow(panelId: string, capability: DetachedWindowCapability | undefined, options: OpenPanelWindowOptions): Promise<boolean>;
+    panelForClosedSurface(surface: SurfaceDescriptor): string | undefined;
+}
+declare function canOpenPanelWindow(capability: DetachedWindowCapability | undefined, carrierAvailable: boolean): capability is DetachedWindowCapability;
+declare function shouldShowDetachedPlaceholder(floatingSurfaces: Readonly<Record<string, true>>, surface: SurfaceDescriptor): boolean;
+/** Product-neutral transaction joining a dock placement to a detached carrier. */
+declare function createPanelWindowingController(): PanelWindowingController;
 /** Product-neutral browser popup carrier with injected surface URL policy. */
 declare function createBrowserWindowManager(options: CreateBrowserWindowManagerOptions): WindowManager;
 /** Event-driven external-window lifecycle with all native policy injected. */
@@ -86,4 +99,4 @@ 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 BrowserPopupWindow, type BrowserWindowHost, type CreateBrowserWindowManagerOptions, type CreateExternalWindowManagerOptions, type DetachWindowOptions, type DetachedWindowCapability, type DetachedWindowTarget, type ExternalWindowHandle, type ExternalWindowHost, type ExternalWindowLifecycle, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, type WindowManager, createBrowserWindowManager, createExternalWindowManager, decodeSurfaceFromLocation, encodeSurfaceQuery, surfaceKey, surfaceWindowLabel };
+export { type BrowserPopupWindow, type BrowserWindowHost, type CreateBrowserWindowManagerOptions, type CreateExternalWindowManagerOptions, type DetachWindowOptions, type DetachedWindowCapability, type DetachedWindowTarget, type ExternalWindowHandle, type ExternalWindowHost, type ExternalWindowLifecycle, type OpenPanelWindowOptions, type PanelWindowingController, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, type WindowManager, canOpenPanelWindow, createBrowserWindowManager, createExternalWindowManager, createPanelWindowingController, decodeSurfaceFromLocation, encodeSurfaceQuery, shouldShowDetachedPlaceholder, surfaceKey, surfaceWindowLabel };

package/dist/window.js

@@ -1,197 +1,22 @@
-// src/window.ts
-function currentBrowserHost() {
-  if (typeof window === "undefined" || typeof window.open !== "function") return void 0;
-  return {
-    screen: window.screen,
-    open: (url, target, features) => window.open(url, target, features),
-    setInterval: (callback, delayMs) => window.setInterval(callback, delayMs),
-    clearInterval: (handle) => window.clearInterval(handle)
-  };
-}
-function createBrowserWindowManager(options) {
-  const host = options.host ?? currentBrowserHost();
-  const windows = /* @__PURE__ */ new Map();
-  const closePolls = /* @__PURE__ */ new Map();
-  const closeListeners = /* @__PURE__ */ new Set();
-  const forget = (surface) => {
-    const key = surfaceWindowLabel(surface);
-    const poll = closePolls.get(key);
-    if (poll !== void 0) host?.clearInterval(poll);
-    closePolls.delete(key);
-    windows.delete(key);
-  };
-  const notifyClosed = (surface) => {
-    for (const listener of closeListeners) {
-      try {
-        listener(surface);
-      } catch {
-      }
-    }
-  };
-  return {
-    canDetach: () => host !== void 0,
-    async openSurfaceWindow(surface, detachOptions) {
-      if (!host) return false;
-      const label = surfaceWindowLabel(surface);
-      const existing = windows.get(label);
-      if (existing !== void 0 && !existing.closed) {
-        existing.focus();
-        return true;
-      }
-      if (existing !== void 0) forget(surface);
-      const width = detachOptions?.width ?? 960;
-      const height = detachOptions?.height ?? 720;
-      const left = detachOptions?.x ?? Math.max(0, Math.round((host.screen.width - width) / 2));
-      const top = detachOptions?.y ?? Math.max(0, Math.round((host.screen.height - height) / 2));
-      const popup = host.open(
-        options.surfaceUrl(surface),
-        label,
-        `popup=yes,width=${width},height=${height},left=${left},top=${top},resizable=yes`
-      );
-      if (popup === null) return false;
-      windows.set(label, popup);
-      const poll = host.setInterval(() => {
-        if (!popup.closed) return;
-        forget(surface);
-        notifyClosed(surface);
-      }, options.closePollIntervalMs ?? 250);
-      closePolls.set(label, poll);
-      return true;
-    },
-    async closeSurfaceWindow(surface) {
-      const popup = windows.get(surfaceWindowLabel(surface));
-      if (popup !== void 0 && !popup.closed) popup.close();
-      forget(surface);
-    },
-    async isSurfaceWindowOpen(surface) {
-      const popup = windows.get(surfaceWindowLabel(surface));
-      return popup !== void 0 && !popup.closed;
-    },
-    onSurfaceWindowClosed(listener) {
-      closeListeners.add(listener);
-      return () => {
-        closeListeners.delete(listener);
-      };
-    }
-  };
-}
-function createExternalWindowManager(options) {
-  const closeListeners = /* @__PURE__ */ new Set();
-  const notifyClosed = (surface) => {
-    for (const listener of closeListeners) {
-      try {
-        listener(surface);
-      } catch {
-      }
-    }
-  };
-  return {
-    canDetach: options.canDetach,
-    async openSurfaceWindow(surface, detachOptions) {
-      const host = await options.loadHost();
-      if (!host) return false;
-      const label = surfaceWindowLabel(surface);
-      const existing = await host.getByLabel(label);
-      if (existing) {
-        try {
-          await existing.show();
-          await existing.focus();
-          return true;
-        } catch {
-        }
-      }
-      return new Promise((resolve) => {
-        let settled = false;
-        const finish = (result) => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timeout);
-          resolve(result);
-        };
-        const timeout = setTimeout(() => finish(true), options.createdTimeoutMs ?? 2e3);
-        void host.create(label, surface, detachOptions, {
-          created: () => finish(true),
-          error: () => finish(false),
-          destroyed: () => notifyClosed(surface)
-        }).catch(() => finish(false));
-      });
-    },
-    async closeSurfaceWindow(surface) {
-      const host = await options.loadHost();
-      if (!host) return;
-      const existing = await host.getByLabel(surfaceWindowLabel(surface));
-      if (!existing) return;
-      try {
-        await existing.close();
-      } catch {
-      }
-    },
-    async isSurfaceWindowOpen(surface) {
-      const host = await options.loadHost();
-      if (!host) return false;
-      return await host.getByLabel(surfaceWindowLabel(surface)) !== null;
-    },
-    onSurfaceWindowClosed(listener) {
-      closeListeners.add(listener);
-      return () => {
-        closeListeners.delete(listener);
-      };
-    }
-  };
-}
-function surfaceKey(surface) {
-  const id = surface.id.includes(":") || surface.id.startsWith("~") ? `~${encodeURIComponent(surface.id)}` : surface.id;
-  const pane = surface.pane ? `:${surface.pane}` : "";
-  const instance = surface.instance ? `:instance=${encodeURIComponent(surface.instance)}` : "";
-  return `${surface.kind}:${id}${pane}${instance}`;
-}
-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) 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
-  };
-}
+import {
+  canOpenPanelWindow,
+  createBrowserWindowManager,
+  createExternalWindowManager,
+  createPanelWindowingController,
+  decodeSurfaceFromLocation,
+  encodeSurfaceQuery,
+  shouldShowDetachedPlaceholder,
+  surfaceKey,
+  surfaceWindowLabel
+} from "./chunk-ZYCR2LSP.js";
 export {
+  canOpenPanelWindow,
   createBrowserWindowManager,
   createExternalWindowManager,
+  createPanelWindowingController,
   decodeSurfaceFromLocation,
   encodeSurfaceQuery,
+  shouldShowDetachedPlaceholder,
   surfaceKey,
   surfaceWindowLabel
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",