@forgeax/app-shell 0.2.0 → 0.4.0

package/README.md

@@ -33,6 +33,25 @@ registry.register(createShellContribution({
 }));
 ```
 
+React shell and slot-diagnostic primitives are available from the explicit
+React entry point:
+
+```tsx
+import {
+  ShellSlot,
+  SlotDebugOverlay,
+  isSlotDebugEnabled,
+} from '@forgeax/app-shell/react';
+
+export function ProductShell() {
+  return (
+    <ShellSlot as="main" name="Workspace">
+      {isSlotDebugEnabled() ? <SlotDebugOverlay /> : null}
+    </ShellSlot>
+  );
+}
+```
+
 ## Ownership boundary
 
 | Package | Owns |

package/dist/dock.d.ts

@@ -0,0 +1,65 @@
+declare const REGIONS: readonly ["DockShell", "AuxBar", "ChatDock", "StatusBar"];
+type Region = typeof REGIONS[number];
+declare const DOCK_REGIONS: readonly ["DockShell", "AuxBar", "ChatDock"];
+type DockRegion = typeof DOCK_REGIONS[number];
+declare function isDockRegion(value: string): value is DockRegion;
+interface PanelDescriptorLite {
+    defaultRegion?: DockRegion;
+}
+declare function resolveRegion(id: string, descriptor: PanelDescriptorLite, overrides: Readonly<Record<string, DockRegion>>): DockRegion;
+interface DockviewApiLike {
+    readonly id: string;
+    getPanel(id: string): {
+        readonly api: {
+            close(): void;
+        };
+    } | undefined;
+}
+declare function registerDockviewApi(api: DockviewApiLike): () => void;
+declare function getDockviewApi(viewId: string): DockviewApiLike | undefined;
+interface DockRegionEntry {
+    readonly viewId: string;
+    readonly region: string;
+    readonly api: unknown;
+    readonly wrapEl: HTMLElement;
+}
+declare function registerDockRegion(entry: DockRegionEntry): () => void;
+declare function getDockRegions(): DockRegionEntry[];
+type SideEdge = 'left' | 'right';
+interface RectLike {
+    left: number;
+    right: number;
+}
+declare function isOnSideEdge(location: {
+    type: string;
+    position?: string;
+}): boolean;
+declare function nearerSideEdge(panel: RectLike, shell: RectLike): SideEdge;
+type DropPosition = 'top' | 'bottom' | 'left' | 'right' | 'center';
+type Direction = 'left' | 'right' | 'above' | 'below' | 'within';
+interface AddPanelPosition {
+    referenceGroup?: unknown;
+    direction?: Direction;
+}
+interface CrossInstanceDropEvent {
+    readonly api: DockviewApiLike & {
+        addPanel(options: {
+            id: string;
+            component: string;
+            title?: string;
+            position?: AddPanelPosition;
+        }): unknown;
+    };
+    readonly position?: DropPosition;
+    readonly group?: unknown;
+    getData(): {
+        readonly viewId: string;
+        readonly panelId: string | null;
+    } | undefined;
+}
+declare function handleCrossInstanceDrop(event: CrossInstanceDropEvent, targetRegion: DockRegion, moveTo: (panelId: string, region: DockRegion) => void, options?: {
+    componentFor?: (panelId: string) => string;
+    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 SideEdge, getDockRegions, getDockviewApi, handleCrossInstanceDrop, isDockRegion, isOnSideEdge, nearerSideEdge, registerDockRegion, registerDockviewApi, resolveRegion };

package/dist/dock.js

@@ -0,0 +1,93 @@
+// src/dock.ts
+var REGIONS = ["DockShell", "AuxBar", "ChatDock", "StatusBar"];
+var DOCK_REGIONS = ["DockShell", "AuxBar", "ChatDock"];
+function isDockRegion(value) {
+  return DOCK_REGIONS.includes(value);
+}
+function resolveRegion(id, descriptor, overrides) {
+  return overrides[id] ?? descriptor.defaultRegion ?? "DockShell";
+}
+var dockviewApis = /* @__PURE__ */ new Map();
+function registerDockviewApi(api) {
+  dockviewApis.set(api.id, api);
+  return () => {
+    if (dockviewApis.get(api.id) === api) dockviewApis.delete(api.id);
+  };
+}
+function getDockviewApi(viewId) {
+  return dockviewApis.get(viewId);
+}
+var dockRegions = /* @__PURE__ */ new Map();
+function registerDockRegion(entry) {
+  dockRegions.set(entry.viewId, entry);
+  return () => {
+    if (dockRegions.get(entry.viewId) === entry) dockRegions.delete(entry.viewId);
+  };
+}
+function getDockRegions() {
+  return [...dockRegions.values()];
+}
+function isOnSideEdge(location) {
+  return location.type === "edge" && (location.position === "left" || location.position === "right");
+}
+function nearerSideEdge(panel, shell) {
+  const middle = (panel.left + panel.right) / 2;
+  return middle - shell.left <= shell.right - middle ? "left" : "right";
+}
+function toDirection(position) {
+  switch (position) {
+    case "top":
+      return "above";
+    case "bottom":
+      return "below";
+    case "left":
+      return "left";
+    case "right":
+      return "right";
+    case "center":
+      return "within";
+    default:
+      return void 0;
+  }
+}
+function handleCrossInstanceDrop(event, targetRegion, moveTo, options) {
+  const transfer = event.getData();
+  if (!transfer?.panelId || transfer.viewId === event.api.id) return;
+  const sourceApi = getDockviewApi(transfer.viewId);
+  if (sourceApi) {
+    try {
+      sourceApi.getPanel(transfer.panelId)?.api.close();
+    } catch {
+    }
+  }
+  const direction = toDirection(event.position);
+  let position;
+  if (event.group && direction) {
+    position = { referenceGroup: event.group, direction };
+  } else if (direction && direction !== "within") {
+    position = { direction };
+  }
+  try {
+    event.api.addPanel({
+      id: transfer.panelId,
+      component: options?.componentFor?.(transfer.panelId) ?? transfer.panelId,
+      title: options?.titleFor?.(transfer.panelId),
+      ...position ? { position } : {}
+    });
+  } catch {
+  }
+  moveTo(transfer.panelId, targetRegion);
+}
+export {
+  DOCK_REGIONS,
+  REGIONS,
+  getDockRegions,
+  getDockviewApi,
+  handleCrossInstanceDrop,
+  isDockRegion,
+  isOnSideEdge,
+  nearerSideEdge,
+  registerDockRegion,
+  registerDockviewApi,
+  resolveRegion
+};

package/dist/react.d.ts

@@ -0,0 +1,18 @@
+import { ReactElement, HTMLAttributes } from 'react';
+
+/** Stable FNV-1a color bucket for a shell slot name. */
+declare function hashSlotHue(name: string): number;
+/** Whether a composable `debug` query contains the exact `slots` token. */
+declare function isSlotDebugEnabled(search?: string): boolean;
+/** Dev-time visualization derived only from live `data-fx-slot` markers. */
+declare function SlotDebugOverlay(): ReactElement;
+
+type ShellSlotElement = 'aside' | 'div' | 'main' | 'section';
+interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
+    as?: ShellSlotElement;
+    name: string;
+}
+/** Structural shell marker that preserves the caller's semantic element. */
+declare function ShellSlot({ as, name, ...props }: ShellSlotProps): ReactElement;
+
+export { ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled };

package/dist/react.js

@@ -0,0 +1,178 @@
+// src/react.tsx
+import { createElement } from "react";
+
+// src/slot-debug.tsx
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var OVERLAY_Z = 2147483e3;
+var LABEL_CORNERS = [
+  { top: 2, left: 2 },
+  { top: 2, right: 2 },
+  { bottom: 2, left: 2 },
+  { bottom: 2, right: 2 }
+];
+function hashSlotHue(name) {
+  let hash = 2166136261;
+  for (let index = 0; index < name.length; index += 1) {
+    hash ^= name.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % 360;
+}
+function isSlotDebugEnabled(search = typeof window !== "undefined" ? window.location.search : "") {
+  try {
+    const debug = new URLSearchParams(search).get("debug");
+    return debug?.split(",").some((flag) => flag.trim() === "slots") ?? false;
+  } catch {
+    return false;
+  }
+}
+function measureSlots() {
+  const elements = Array.from(document.querySelectorAll("[data-fx-slot]"));
+  const boxes = [];
+  for (const element of elements) {
+    const name = element.getAttribute("data-fx-slot") ?? "";
+    if (!name) continue;
+    let rect;
+    if (element.firstChild) {
+      const range = document.createRange();
+      range.selectNodeContents(element);
+      rect = range.getBoundingClientRect();
+    } else {
+      rect = element.getBoundingClientRect();
+    }
+    if (rect.width === 0 && rect.height === 0) continue;
+    let depth = 0;
+    let parentName = null;
+    let cursor = element.parentElement;
+    while (cursor) {
+      if (cursor.hasAttribute("data-fx-slot")) {
+        parentName ??= cursor.getAttribute("data-fx-slot");
+        depth += 1;
+      }
+      cursor = cursor.parentElement;
+    }
+    boxes.push({
+      name,
+      parentName,
+      depth,
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height
+    });
+  }
+  return boxes;
+}
+function SlotDebugOverlay() {
+  const [boxes, setBoxes] = useState([]);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    let frame = 0;
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => setBoxes(measureSlots()));
+    };
+    setBoxes(measureSlots());
+    const resizeObserver = new ResizeObserver(schedule);
+    const attach = () => {
+      resizeObserver.disconnect();
+      document.querySelectorAll("[data-fx-slot]").forEach((element) => resizeObserver.observe(element));
+    };
+    attach();
+    const mutationObserver = new MutationObserver((records) => {
+      let markerSetChanged = false;
+      for (const record of records) {
+        if (record.type === "attributes" && record.attributeName === "data-fx-slot") {
+          markerSetChanged = true;
+          break;
+        }
+        if (record.type !== "childList") continue;
+        const nodes = [...record.addedNodes, ...record.removedNodes];
+        markerSetChanged = nodes.some((node) => node instanceof Element && (node.matches("[data-fx-slot]") || node.querySelector("[data-fx-slot]")));
+        if (markerSetChanged) break;
+      }
+      if (markerSetChanged) attach();
+      schedule();
+    });
+    mutationObserver.observe(document.body, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ["data-fx-slot"]
+    });
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, true);
+    return () => {
+      cancelAnimationFrame(frame);
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        inset: 0,
+        pointerEvents: "none",
+        zIndex: OVERLAY_Z
+      },
+      "data-fx-slot-overlay": "",
+      children: boxes.map((box, index) => {
+        const hue = hashSlotHue(box.name);
+        const corner = LABEL_CORNERS[box.depth % LABEL_CORNERS.length];
+        const label = box.parentName ? `${box.parentName} \u2192 ${box.name}` : box.name;
+        return /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              position: "fixed",
+              left: box.left,
+              top: box.top,
+              width: box.width,
+              height: box.height,
+              background: `hsla(${hue}, 65%, 55%, ${Math.min(0.35, 0.1 + box.depth * 0.06)})`,
+              outline: `${Math.max(1, 3 - box.depth)}px solid hsla(${hue}, 65%, 55%, 0.7)`,
+              pointerEvents: "none"
+            },
+            children: /* @__PURE__ */ jsx(
+              "span",
+              {
+                style: {
+                  position: "absolute",
+                  ...corner,
+                  background: `hsla(${hue}, 65%, 25%, 0.9)`,
+                  color: "#fff",
+                  font: "10px/14px ui-monospace, monospace",
+                  padding: "1px 4px",
+                  borderRadius: 2,
+                  whiteSpace: "nowrap"
+                },
+                children: label
+              }
+            )
+          },
+          `${box.name}:${index}`
+        );
+      })
+    }
+  );
+}
+
+// src/react.tsx
+function ShellSlot({
+  as = "div",
+  name,
+  ...props
+}) {
+  return createElement(as, { ...props, "data-fx-slot": name });
+}
+export {
+  ShellSlot,
+  SlotDebugOverlay,
+  hashSlotHue,
+  isSlotDebugEnabled
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,20 +12,36 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./dock": {
+      "types": "./dist/dock.d.ts",
+      "import": "./dist/dock.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
     }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test test/*.test.ts",
-    "build": "tsup src/index.ts --format esm --dts --outDir dist",
+    "test": "bun test test",
+    "build": "tsup src/index.ts src/dock.ts src/react.tsx --format esm --dts --outDir dist",
     "check": "bun run typecheck && bun run test && bun run build",
     "release:preflight": "bun run scripts/release-preflight.ts"
   },
   "dependencies": {
     "@forgeax/extension-contracts": "^0.1.0"
   },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "bun-types": "^1.3.14",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "typescript": "^5.9.2"
   },