@forgeax/app-shell 0.7.0 → 0.9.0

package/README.md

@@ -67,6 +67,37 @@ const [width, setWidth] = useLocalSize('product.sidebar.width', 280, 180, 640);
 </aside>
 ```
 
+Generic panel sections keep product renderers and action policies outside App
+Shell while providing stable shell/content metadata:
+
+```tsx
+import '@forgeax/app-shell/panel.css';
+import { PanelSurface } from '@forgeax/app-shell/react';
+
+<PanelSurface
+  id="project-tree"
+  registered
+  header={<ProductPanelActions />}
+  content={{ padding: 'sm', scroll: 'auto', tone: 'tool' }}
+>
+  <ProjectTree />
+</PanelSurface>
+```
+
+Dock state adapters are available without a Dockview runtime dependency:
+
+```ts
+import {
+  hasMountedPanelPlacement,
+  isDockPanelVisible,
+  pruneSerializedDockLayout,
+  trackDockPanelVisibility,
+} from '@forgeax/app-shell/dock';
+```
+
+Products own event subscription and layout persistence; the adapters only track
+stable panel ids and transform structural serialized snapshots.
+
 ## Ownership boundary
 
 | Package | Owns |

package/dist/dock.d.ts

@@ -25,6 +25,27 @@ interface DockRegionEntry {
 }
 declare function registerDockRegion(entry: DockRegionEntry): () => void;
 declare function getDockRegions(): DockRegionEntry[];
+/** Track one live mount of a dock panel and return an idempotent release. */
+declare function trackDockPanelVisibility(panelId: string): () => void;
+declare function isDockPanelVisible(panelId: string): boolean;
+declare function hasMountedPanelPlacement(panelIds: readonly string[], mountedPanelIds: ReadonlySet<string>): boolean;
+interface SerializedDockPanelLike {
+    readonly contentComponent?: string;
+    readonly [key: string]: unknown;
+}
+interface SerializedDockLayoutLike {
+    readonly panels?: Readonly<Record<string, SerializedDockPanelLike>>;
+    readonly grid?: Readonly<{
+        readonly root?: unknown;
+        readonly [key: string]: unknown;
+    }>;
+    readonly [key: string]: unknown;
+}
+/**
+ * Remove panels that the current shell cannot render, then prune empty grid
+ * 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 SideEdge = 'left' | 'right';
 interface RectLike {
     left: number;
@@ -62,4 +83,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 SideEdge, getDockRegions, getDockviewApi, handleCrossInstanceDrop, isDockRegion, isOnSideEdge, nearerSideEdge, registerDockRegion, registerDockviewApi, resolveRegion };
+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 };

package/dist/dock.js

@@ -27,6 +27,63 @@ function registerDockRegion(entry) {
 function getDockRegions() {
   return [...dockRegions.values()];
 }
+var visibleDockPanels = /* @__PURE__ */ new Map();
+function trackDockPanelVisibility(panelId) {
+  visibleDockPanels.set(panelId, (visibleDockPanels.get(panelId) ?? 0) + 1);
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    const next = (visibleDockPanels.get(panelId) ?? 1) - 1;
+    if (next > 0) visibleDockPanels.set(panelId, next);
+    else visibleDockPanels.delete(panelId);
+  };
+}
+function isDockPanelVisible(panelId) {
+  return visibleDockPanels.has(panelId);
+}
+function hasMountedPanelPlacement(panelIds, mountedPanelIds) {
+  return panelIds.some((id) => mountedPanelIds.has(id));
+}
+function pruneSerializedDockLayout(layout, knownComponents, allowedPanelIds) {
+  if (!layout.panels) return layout;
+  const removed = new Set(Object.entries(layout.panels).filter(([id, panel]) => !knownComponents.has(panel.contentComponent ?? id) || allowedPanelIds !== void 0 && !allowedPanelIds.has(id)).map(([id]) => id));
+  if (removed.size === 0) return layout;
+  const panels = Object.fromEntries(
+    Object.entries(layout.panels).filter(([id]) => !removed.has(id))
+  );
+  if (Object.keys(panels).length === 0) return null;
+  const pruneNode = (node) => {
+    if (!node || typeof node !== "object") return node;
+    const value = node;
+    if (value.type === "leaf") {
+      const data = value.data;
+      if (!Array.isArray(data?.views)) return node;
+      const views = data.views.filter((id) => !removed.has(id));
+      if (views.length === 0) return null;
+      return {
+        ...value,
+        data: {
+          ...data,
+          views,
+          activeView: views.includes(data.activeView ?? "") ? data.activeView : views[0]
+        }
+      };
+    }
+    if (value.type === "branch" && Array.isArray(value.data)) {
+      const children = value.data.map(pruneNode).filter((child) => child !== null);
+      return children.length === 0 ? null : { ...value, data: children };
+    }
+    return node;
+  };
+  const root = pruneNode(layout.grid?.root);
+  if (root === null) return null;
+  return {
+    ...layout,
+    panels,
+    grid: layout.grid ? { ...layout.grid, root } : layout.grid
+  };
+}
 function isOnSideEdge(location) {
   return location.type === "edge" && (location.position === "left" || location.position === "right");
 }
@@ -84,10 +141,14 @@ export {
   getDockRegions,
   getDockviewApi,
   handleCrossInstanceDrop,
+  hasMountedPanelPlacement,
+  isDockPanelVisible,
   isDockRegion,
   isOnSideEdge,
   nearerSideEdge,
+  pruneSerializedDockLayout,
   registerDockRegion,
   registerDockviewApi,
-  resolveRegion
+  resolveRegion,
+  trackDockPanelVisibility
 };

package/dist/panel.css

@@ -0,0 +1,41 @@
+.fx-panel {
+  height: 100%;
+  width: 100%;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  background: var(--color-background-base, #191919);
+  color: var(--color-text-primary, #e8eaed);
+}
+
+.fx-panel-content {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+}
+
+.fx-panel-content[data-scroll="none"] {
+  overflow: hidden;
+}
+
+.fx-panel-content[data-padding="none"] {
+  padding: 0;
+}
+
+.fx-panel-content[data-padding="sm"] {
+  padding: 8px;
+}
+
+.fx-panel-content[data-padding="md"] {
+  padding: 12px;
+}
+
+.fx-panel-content[data-tone="surface"] {
+  background: var(--color-background-elevated, #161619);
+}
+
+.fx-panel-content[data-tone="tool"] {
+  background: var(--color-background-base, #191919);
+}

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactElement, HTMLAttributes } from 'react';
+import { ReactElement, HTMLAttributes, ReactNode } from 'react';
 
 /** Stable FNV-1a color bucket for a shell slot name. */
 declare function hashSlotHue(name: string): number;
@@ -20,6 +20,25 @@ interface ResizeHandleProps {
 }
 declare function ResizeHandle({ orientation, onDrag, onDragStart, onDragEnd, className, ariaLabel, title, }: ResizeHandleProps): react.JSX.Element;
 
+type PanelContentPadding = 'none' | 'sm' | 'md';
+type PanelContentScroll = 'none' | 'auto';
+type PanelContentTone = 'default' | 'surface' | 'tool';
+interface PanelContentPolicy {
+    readonly padding?: PanelContentPadding;
+    readonly scroll?: PanelContentScroll;
+    readonly tone?: PanelContentTone;
+}
+interface PanelSurfaceProps extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'content' | 'id'> {
+    readonly id: string;
+    readonly registered?: boolean;
+    readonly singleTab?: 'default' | 'full' | 'hideTitle';
+    readonly header?: ReactNode;
+    readonly content?: PanelContentPolicy;
+    readonly children?: ReactNode;
+}
+/** Product-neutral panel section and content presentation. */
+declare function PanelSurface({ id, registered, singleTab, header, content, children, className, ...props }: PanelSurfaceProps): ReactElement;
+
 type ShellSlotElement = 'aside' | 'div' | 'main' | 'section';
 interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
     as?: ShellSlotElement;
@@ -28,4 +47,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 { ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled, useLocalSize };
+export { 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

@@ -255,6 +255,44 @@ function ResizeHandle({
   );
 }
 
+// src/panel.tsx
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+function PanelSurface({
+  id,
+  registered = false,
+  singleTab,
+  header,
+  content,
+  children,
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      ...props,
+      className: className ? `fx-panel ${className}` : "fx-panel",
+      "data-fx-panel-id": id,
+      "data-panel-registered": registered ? "true" : "false",
+      "data-dock-single-tab": singleTab,
+      "data-fx-slot": `DockPanel:${id}`,
+      children: [
+        header,
+        /* @__PURE__ */ jsx3(
+          "div",
+          {
+            className: "fx-panel-content",
+            "data-padding": content?.padding ?? "none",
+            "data-scroll": content?.scroll ?? "auto",
+            "data-tone": content?.tone ?? "default",
+            children
+          }
+        )
+      ]
+    }
+  );
+}
+
 // src/react.tsx
 function ShellSlot({
   as = "div",
@@ -264,6 +302,7 @@ function ShellSlot({
   return createElement(as, { ...props, "data-fx-slot": name });
 }
 export {
+  PanelSurface,
   ResizeHandle,
   ShellSlot,
   SlotDebugOverlay,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",
-  "sideEffects": ["./dist/resize.css"],
+  "sideEffects": ["./dist/resize.css", "./dist/panel.css"],
   "files": ["dist"],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,12 +21,13 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
     },
-    "./resize.css": "./dist/resize.css"
+    "./resize.css": "./dist/resize.css",
+    "./panel.css": "./dist/panel.css"
   },
   "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",
+    "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",
     "check": "bun run typecheck && bun run test && bun run build",
     "release:preflight": "bun run scripts/release-preflight.ts"
   },