@forgeax/app-shell 0.3.0 → 0.5.0

package/README.md

@@ -33,6 +33,37 @@ registry.register(createShellContribution({
 }));
 ```
 
+React shell and slot-diagnostic primitives are available from the explicit
+React entry point:
+
+```tsx
+import {
+  ResizeHandle,
+  ShellSlot,
+  SlotDebugOverlay,
+  isSlotDebugEnabled,
+  useLocalSize,
+} from '@forgeax/app-shell/react';
+
+export function ProductShell() {
+  return (
+    <ShellSlot as="main" name="Workspace">
+      {isSlotDebugEnabled() ? <SlotDebugOverlay /> : null}
+    </ShellSlot>
+  );
+}
+```
+
+Generic persisted sizing and pointer-capture handles use the same public entry:
+
+```tsx
+const [width, setWidth] = useLocalSize('product.sidebar.width', 280, 180, 640);
+
+<aside style={{ width }}>
+  <ResizeHandle orientation="col" onDrag={(delta) => setWidth((value) => value + delta)} />
+</aside>
+```
+
 ## Ownership boundary
 
 | Package | Owns |

package/dist/react.d.ts

@@ -1,4 +1,20 @@
-import { HTMLAttributes, ReactElement } from 'react';
+import * as react from 'react';
+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;
+
+declare function useLocalSize(key: string, initial: number, min: number, max: number): readonly [number, (next: number | ((previous: number) => number)) => void];
+interface ResizeHandleProps {
+    orientation: 'col' | 'row';
+    onDrag: (delta: number) => void;
+    title?: string;
+}
+declare function ResizeHandle({ orientation, onDrag, title }: ResizeHandleProps): react.JSX.Element;
 
 type ShellSlotElement = 'aside' | 'div' | 'main' | 'section';
 interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
@@ -8,4 +24,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 { ShellSlot, type ShellSlotElement, type ShellSlotProps };
+export { ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled, useLocalSize };

package/dist/react.js

@@ -1,5 +1,245 @@
 // 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/resize.tsx
+import { useEffect as useEffect2, useRef, useState as useState2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function useLocalSize(key, initial, min, max) {
+  const clamp = (value2) => Math.min(max, Math.max(min, value2));
+  const [value, setValueRaw] = useState2(() => {
+    if (typeof window === "undefined") return initial;
+    try {
+      const raw = window.localStorage.getItem(key);
+      if (!raw) return initial;
+      const persisted = Number(raw);
+      if (!Number.isFinite(persisted)) return initial;
+      return clamp(persisted);
+    } catch {
+      return initial;
+    }
+  });
+  useEffect2(() => {
+    try {
+      window.localStorage.setItem(key, String(value));
+    } catch {
+    }
+  }, [key, value]);
+  const setValue = (next) => {
+    setValueRaw((previous) => clamp(
+      typeof next === "function" ? next(previous) : next
+    ));
+  };
+  return [value, setValue];
+}
+function ResizeHandle({ orientation, onDrag, title }) {
+  const startRef = useRef(null);
+  const resetGlobalDragStyles = () => {
+    document.body.style.cursor = "";
+    document.body.style.userSelect = "";
+  };
+  useEffect2(() => () => {
+    if (startRef.current) resetGlobalDragStyles();
+  }, []);
+  const onPointerDown = (event) => {
+    event.preventDefault();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    startRef.current = { x: event.clientX, y: event.clientY };
+    document.body.style.cursor = orientation === "col" ? "col-resize" : "row-resize";
+    document.body.style.userSelect = "none";
+  };
+  const onPointerMove = (event) => {
+    if (!startRef.current) return;
+    const deltaX = event.clientX - startRef.current.x;
+    const deltaY = event.clientY - startRef.current.y;
+    startRef.current = { x: event.clientX, y: event.clientY };
+    onDrag(orientation === "col" ? deltaX : deltaY);
+  };
+  const finish = (event) => {
+    if (!startRef.current) return;
+    startRef.current = null;
+    try {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    } catch {
+    }
+    resetGlobalDragStyles();
+  };
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      className: `resize-handle resize-handle-${orientation}`,
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: finish,
+      onPointerCancel: finish,
+      title,
+      role: "separator",
+      "aria-orientation": orientation === "col" ? "vertical" : "horizontal"
+    }
+  );
+}
+
+// src/react.tsx
 function ShellSlot({
   as = "div",
   name,
@@ -8,5 +248,10 @@ function ShellSlot({
   return createElement(as, { ...props, "data-fx-slot": name });
 }
 export {
-  ShellSlot
+  ResizeHandle,
+  ShellSlot,
+  SlotDebugOverlay,
+  hashSlotHue,
+  isSlotDebugEnabled,
+  useLocalSize
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,6 +36,7 @@
     "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",