@andrewcyuan/focusgrid 0.1.0

package/dist/dom/index.cjs

@@ -0,0 +1,318 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region dom/src/controller.ts
+/** Attach the renderer root; pane elements are resolved only when focus is requested. */
+var FocusGridDomController = class {
+	root = null;
+	setRoot(root) {
+		this.root = root;
+	}
+	focus(paneId) {
+		const root = this.root;
+		if (!root) return false;
+		const pane = [...root.querySelectorAll("[data-pane-id]")].find((element) => element.dataset.paneId === paneId && element.closest(".FocusgridFocusGrid") === root);
+		if (!pane) return false;
+		const ownsFocus = () => pane.contains(root.ownerDocument.activeElement);
+		if (ownsFocus()) return true;
+		pane.focus({ preventScroll: true });
+		return ownsFocus();
+	}
+};
+//#endregion
+//#region dom/src/frame.ts
+function requestFrame(callback) {
+	if (typeof globalThis.requestAnimationFrame === "function") return {
+		kind: "animation",
+		id: globalThis.requestAnimationFrame(() => callback())
+	};
+	return {
+		kind: "timeout",
+		id: globalThis.setTimeout(callback, 0)
+	};
+}
+function cancelFrame(frame) {
+	if (frame.kind === "animation") {
+		globalThis.cancelAnimationFrame(frame.id);
+		return;
+	}
+	globalThis.clearTimeout(frame.id);
+}
+//#endregion
+//#region dom/src/pointer-resize.ts
+var PointerResizeController = class {
+	controller;
+	state = { phase: "idle" };
+	onDocumentPointerMove = (event) => {
+		this.updateResize(event);
+	};
+	onDocumentPointerUp = (event) => {
+		this.endResize(event);
+	};
+	onDocumentPointerCancel = (event) => {
+		this.endResize(event);
+	};
+	constructor(controller) {
+		this.controller = controller;
+	}
+	startResize(event, handle, captureTarget) {
+		event.preventDefault();
+		this.destroy();
+		const ownerDocument = this.resolveOwnerDocument(event, captureTarget);
+		const pointerCaptureTarget = this.resolveCaptureTarget(captureTarget);
+		const startSizes = this.controller.getSplitSizes(handle.splitId);
+		if (!startSizes) return;
+		this.state = {
+			phase: "dragging",
+			pointerId: event.pointerId,
+			splitId: handle.splitId,
+			index: handle.index,
+			startX: event.clientX,
+			startY: event.clientY,
+			direction: handle.direction,
+			startSizes,
+			ownerDocument,
+			captureTarget: pointerCaptureTarget,
+			pendingDeltaPx: 0,
+			pendingFrame: null
+		};
+		this.setPointerCapture(pointerCaptureTarget, event.pointerId);
+		this.addDocumentListeners(ownerDocument);
+	}
+	updateResize(event) {
+		if (this.state.phase !== "dragging" || this.state.pointerId !== event.pointerId) return;
+		const deltaPx = this.state.direction === "horizontal" ? event.clientX - this.state.startX : event.clientY - this.state.startY;
+		if (this.state.pendingFrame) {
+			this.state = {
+				...this.state,
+				pendingDeltaPx: deltaPx
+			};
+			return;
+		}
+		const pendingFrame = requestFrame(() => {
+			if (this.state.phase !== "dragging") return;
+			this.state = {
+				...this.state,
+				pendingFrame: null
+			};
+			this.dispatchPendingResize();
+		});
+		this.state = {
+			...this.state,
+			pendingDeltaPx: deltaPx,
+			pendingFrame
+		};
+	}
+	endResize(event) {
+		if (this.state.phase !== "dragging" || this.state.pointerId !== event.pointerId) return;
+		this.flushPendingFrame();
+		this.finishDrag();
+	}
+	destroy() {
+		this.cancelPendingFrame();
+		this.finishDrag();
+	}
+	finishDrag() {
+		if (this.state.phase !== "dragging") return;
+		const { captureTarget, ownerDocument, pointerId } = this.state;
+		this.removeDocumentListeners(ownerDocument);
+		this.releasePointerCapture(captureTarget, pointerId);
+		this.state = { phase: "idle" };
+	}
+	flushPendingFrame() {
+		if (this.state.phase !== "dragging" || !this.state.pendingFrame) return;
+		cancelFrame(this.state.pendingFrame);
+		this.state = {
+			...this.state,
+			pendingFrame: null
+		};
+		this.dispatchPendingResize();
+	}
+	dispatchPendingResize() {
+		if (this.state.phase !== "dragging") return;
+		this.controller.resizeHandle(this.state.splitId, {
+			index: this.state.index,
+			deltaPx: this.state.pendingDeltaPx,
+			snapshotSizes: this.state.startSizes
+		});
+	}
+	cancelPendingFrame() {
+		if (this.state.phase !== "dragging" || !this.state.pendingFrame) return;
+		cancelFrame(this.state.pendingFrame);
+		this.state = {
+			...this.state,
+			pendingFrame: null
+		};
+	}
+	addDocumentListeners(ownerDocument) {
+		ownerDocument?.addEventListener("pointermove", this.onDocumentPointerMove);
+		ownerDocument?.addEventListener("pointerup", this.onDocumentPointerUp);
+		ownerDocument?.addEventListener("pointercancel", this.onDocumentPointerCancel);
+	}
+	removeDocumentListeners(ownerDocument) {
+		ownerDocument?.removeEventListener("pointermove", this.onDocumentPointerMove);
+		ownerDocument?.removeEventListener("pointerup", this.onDocumentPointerUp);
+		ownerDocument?.removeEventListener("pointercancel", this.onDocumentPointerCancel);
+	}
+	resolveOwnerDocument(event, captureTarget) {
+		if (captureTarget?.ownerDocument) return captureTarget.ownerDocument;
+		if (typeof Element !== "undefined" && event.target instanceof Element && event.target.ownerDocument) return event.target.ownerDocument;
+		return typeof document === "undefined" ? null : document;
+	}
+	resolveCaptureTarget(captureTarget) {
+		if (!captureTarget) return null;
+		if ("setPointerCapture" in captureTarget || "releasePointerCapture" in captureTarget) return captureTarget;
+		return null;
+	}
+	setPointerCapture(target, pointerId) {
+		try {
+			target?.setPointerCapture?.(pointerId);
+		} catch {}
+	}
+	releasePointerCapture(target, pointerId) {
+		if (!target?.releasePointerCapture) return;
+		try {
+			if (!target.hasPointerCapture || target.hasPointerCapture(pointerId)) target.releasePointerCapture(pointerId);
+		} catch {}
+	}
+};
+//#endregion
+//#region dom/src/resize-observer.ts
+function observeRootSize(root, controller) {
+	const updateSize = ({ width, height }) => {
+		controller.setContainerSize(Math.floor(width), Math.floor(height));
+	};
+	if (typeof ResizeObserver === "undefined") {
+		updateSize(root.getBoundingClientRect());
+		return () => {};
+	}
+	const observer = new ResizeObserver(([entry]) => {
+		if (entry) updateSize(entry.contentRect);
+	});
+	observer.observe(root);
+	return () => observer.disconnect();
+}
+//#endregion
+//#region dom/src/interactivity.ts
+const INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+	"alertdialog",
+	"button",
+	"checkbox",
+	"combobox",
+	"dialog",
+	"grid",
+	"gridcell",
+	"link",
+	"listbox",
+	"menu",
+	"menubar",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"radio",
+	"radiogroup",
+	"scrollbar",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"tab",
+	"tablist",
+	"textbox",
+	"toolbar",
+	"tree",
+	"treegrid",
+	"treeitem"
+]);
+function hasInteractiveOwner(target, boundary) {
+	let element = target;
+	while (element && element !== boundary) {
+		if (element instanceof HTMLElement && isInteractiveElement(element)) return true;
+		element = element.parentElement;
+	}
+	return boundary instanceof HTMLElement && isInteractiveElement(boundary);
+}
+function shouldFocusPaneShellForPointer(target, paneShell) {
+	return target === paneShell || !hasInteractiveOwner(target, paneShell);
+}
+function isInteractiveElement(element) {
+	if (isUnavailableElement(element)) return false;
+	const tagName = element.tagName.toLowerCase();
+	const role = element.getAttribute("role")?.toLowerCase();
+	return element.isContentEditable || element.tabIndex >= 0 || tagName === "a" && element.hasAttribute("href") || tagName === "button" || tagName === "input" || tagName === "select" || tagName === "textarea" || tagName === "dialog" || tagName === "summary" || role !== void 0 && INTERACTIVE_ROLES.has(role);
+}
+function isUnavailableElement(element) {
+	let current = element;
+	while (current) {
+		if (current.hidden || current.hasAttribute("hidden") || current.hasAttribute("inert") || current.getAttribute("aria-hidden") === "true" || current.getAttribute("aria-disabled") === "true" || "disabled" in current && Boolean(current.disabled)) return true;
+		const view = current.ownerDocument.defaultView;
+		if (view) {
+			const style = view.getComputedStyle(current);
+			if (style.display === "none" || style.visibility === "hidden") return true;
+		}
+		current = current.parentElement;
+	}
+	return false;
+}
+function isEditableTarget(target) {
+	if (!(target instanceof HTMLElement)) return false;
+	if (target.isContentEditable || target.getAttribute("role")?.toLowerCase() === "textbox") return true;
+	if (target.matches("textarea, select")) return !target.matches(":disabled");
+	return target instanceof HTMLInputElement && !target.disabled && !target.readOnly && [
+		"date",
+		"datetime-local",
+		"email",
+		"file",
+		"month",
+		"number",
+		"password",
+		"search",
+		"tel",
+		"text",
+		"time",
+		"url",
+		"week"
+	].includes(target.type);
+}
+//#endregion
+//#region dom/src/mount.ts
+/** Own native grid interactions; React only attaches and detaches the root. */
+function mountFocusGrid(root, controller, dom) {
+	dom.setRoot(root);
+	const resize = new PointerResizeController(controller);
+	const ownedTarget = (event) => {
+		const target = event.target;
+		return target instanceof Element && target.closest(".FocusgridFocusGrid") === root ? target : null;
+	};
+	const onFocus = (event) => {
+		const paneId = ownedTarget(event)?.closest("[data-pane-id]")?.dataset.paneId;
+		if (paneId) controller.focus(paneId);
+	};
+	const onPointerDown = (event) => {
+		const target = ownedTarget(event);
+		if (!target) return;
+		const separator = target.closest("[data-resize-handle]");
+		if (separator) {
+			const handle = controller.getLayout().handles.find((handle) => handle.id === separator.dataset.resizeHandle);
+			if (handle) resize.startResize(event, handle, separator);
+			return;
+		}
+		const pane = target.closest("[data-pane-id]");
+		if (!pane?.dataset.paneId) return;
+		controller.focus(pane.dataset.paneId);
+		if (shouldFocusPaneShellForPointer(target, pane)) pane.focus({ preventScroll: true });
+	};
+	root.addEventListener("focusin", onFocus, true);
+	root.addEventListener("pointerdown", onPointerDown);
+	const stopObserving = observeRootSize(root, controller);
+	return () => {
+		root.removeEventListener("focusin", onFocus, true);
+		root.removeEventListener("pointerdown", onPointerDown);
+		resize.destroy();
+		stopObserving();
+		dom.setRoot(null);
+	};
+}
+//#endregion
+exports.FocusGridDomController = FocusGridDomController;
+exports.isEditableTarget = isEditableTarget;
+exports.mountFocusGrid = mountFocusGrid;

package/dist/dom/index.d.cts

@@ -0,0 +1,177 @@
+//#region core/src/layout/types.d.ts
+type PaneId = string;
+type NodeId = string;
+type Orientation = "horizontal" | "vertical";
+declare const cardinalDirections: readonly ["left", "right", "up", "down"];
+type CardinalDirection = (typeof cardinalDirections)[number];
+declare enum PaneCommandCapability {
+  ResizeX = "canResizeX",
+  ResizeY = "canResizeY",
+  Remove = "canRemove",
+  SplitHorizontal = "canSplitHorizontal",
+  SplitVertical = "canSplitVertical",
+  SwapX = "canSwapX",
+  SwapY = "canSwapY",
+  Focus = "canFocus"
+}
+type PaneCommandCapabilityInput = Partial<Record<PaneCommandCapability, boolean>>;
+type PaneNode = {
+  kind: "pane";
+  id: NodeId;
+  paneId: PaneId;
+} & PaneCommandCapabilityInput;
+type SplitNode = {
+  kind: "split";
+  id: NodeId;
+  orientation: Orientation;
+  children: LayoutNode[];
+  sizes: number[];
+  lastFocusedChildId?: NodeId;
+};
+type LayoutNode = PaneNode | SplitNode;
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type ComputedPane = {
+  paneId: PaneId;
+  nodeId: NodeId;
+  rect: Rect;
+  active: boolean;
+};
+type ComputedHandle = {
+  id: string;
+  splitId: NodeId;
+  index: number;
+  rect: Rect;
+  direction: Orientation;
+};
+type ComputedNode = {
+  kind: "pane";
+  pane: ComputedPane;
+} | {
+  kind: "split";
+  orientation: Orientation;
+  children: ComputedNode[];
+  handles: ComputedHandle[];
+};
+type ComputedLayout = {
+  root: ComputedNode;
+  rectByNodeId: Map<NodeId, Rect>;
+  panes: ComputedPane[];
+  handles: ComputedHandle[];
+};
+type FocusGridControllerState = {
+  root: LayoutNode;
+  activePaneId: PaneId | null;
+  container: {
+    width: number;
+    height: number;
+  };
+};
+//#endregion
+//#region core/src/controller.d.ts
+interface DomController {
+  focus(paneId: PaneId): boolean;
+}
+type Listener = (next: FocusGridControllerState, previous: FocusGridControllerState) => void;
+type PaneLayoutChangeEvent = {
+  pane: ComputedPane;
+  previousPane: ComputedPane;
+  controller: FocusGridController;
+};
+type PaneCloseEvent = {
+  paneId: PaneId;
+  previousPane: ComputedPane;
+  controller: FocusGridController;
+};
+type PaneEventHandlers = {
+  onPaneLayoutChange?: (event: PaneLayoutChangeEvent) => void;
+  onPaneClose?: (event: PaneCloseEvent) => void;
+};
+type PaneDefaults = PaneCommandCapabilityInput;
+type FocusGridControllerProps = FocusGridControllerState & {
+  paneDefaults?: PaneDefaults;
+  minWidth?: number;
+  minHeight?: number;
+  directionalFocusOverflow?: boolean;
+};
+type SplitPaneOptions = Partial<Omit<PaneNode, "kind" | "id" | "paneId">> & {
+  side: CardinalDirection;
+  newPaneId?: PaneId;
+  newPaneNodeId?: NodeId;
+  splitId?: NodeId;
+  preserveActivePane?: boolean;
+};
+type ResizePaneOptions = {
+  direction: CardinalDirection;
+  deltaPx: number;
+};
+type ResizeHandleOptions = {
+  index: number;
+  deltaPx: number;
+  snapshotSizes?: number[];
+};
+declare class FocusGridController {
+  private readonly domController;
+  readonly minWidth: number;
+  readonly minHeight: number;
+  readonly directionalFocusOverflow: boolean;
+  private currentState;
+  private cachedLayout;
+  private readonly paneDefaults;
+  private readonly listeners;
+  constructor({
+    paneDefaults,
+    minWidth,
+    minHeight,
+    directionalFocusOverflow,
+    ...state
+  }: FocusGridControllerProps, domController: DomController);
+  /** Computed render data; stable until the next committed change. */
+  getLayout(): ComputedLayout;
+  getPane(paneId: PaneId): PaneNode | null;
+  getContainerSize(): {
+    width: number;
+    height: number;
+  };
+  getSplitSizes(splitId: NodeId): number[] | null;
+  splitActive(side: CardinalDirection): PaneId | null;
+  removeActive(): boolean;
+  focusAdjacent(direction: CardinalDirection): boolean;
+  swapAdjacent(direction: CardinalDirection): boolean;
+  resizeActive(direction: CardinalDirection, deltaPx: number): boolean;
+  split(paneNodeId: NodeId, props: SplitPaneOptions): PaneId | null;
+  remove(paneId: PaneId): boolean;
+  swap(firstPaneId: PaneId, secondPaneId: PaneId): boolean;
+  resize(paneId: PaneId, props: ResizePaneOptions): boolean;
+  resizeHandle(splitId: NodeId, props: ResizeHandleOptions): boolean;
+  focus(paneId: PaneId): boolean;
+  updatePane(paneId: PaneId, patch: Partial<Omit<PaneNode, "kind" | "id" | "paneId">>): boolean;
+  setContainerSize(width: number, height: number): boolean;
+  private commit;
+  subscribePaneEvents({
+    onPaneLayoutChange,
+    onPaneClose
+  }: PaneEventHandlers): () => void;
+  subscribe(listener: Listener): () => void;
+}
+//#endregion
+//#region dom/src/controller.d.ts
+/** Attach the renderer root; pane elements are resolved only when focus is requested. */
+declare class FocusGridDomController implements DomController {
+  private root;
+  setRoot(root: HTMLElement | null): void;
+  focus(paneId: PaneId): boolean;
+}
+//#endregion
+//#region dom/src/mount.d.ts
+/** Own native grid interactions; React only attaches and detaches the root. */
+declare function mountFocusGrid(root: HTMLElement, controller: FocusGridController, dom: FocusGridDomController): () => void;
+//#endregion
+//#region dom/src/interactivity.d.ts
+declare function isEditableTarget(target: EventTarget | null): boolean;
+//#endregion
+export { FocusGridDomController, isEditableTarget, mountFocusGrid };

package/dist/dom/index.d.ts

@@ -0,0 +1,177 @@
+//#region core/src/layout/types.d.ts
+type PaneId = string;
+type NodeId = string;
+type Orientation = "horizontal" | "vertical";
+declare const cardinalDirections: readonly ["left", "right", "up", "down"];
+type CardinalDirection = (typeof cardinalDirections)[number];
+declare enum PaneCommandCapability {
+  ResizeX = "canResizeX",
+  ResizeY = "canResizeY",
+  Remove = "canRemove",
+  SplitHorizontal = "canSplitHorizontal",
+  SplitVertical = "canSplitVertical",
+  SwapX = "canSwapX",
+  SwapY = "canSwapY",
+  Focus = "canFocus"
+}
+type PaneCommandCapabilityInput = Partial<Record<PaneCommandCapability, boolean>>;
+type PaneNode = {
+  kind: "pane";
+  id: NodeId;
+  paneId: PaneId;
+} & PaneCommandCapabilityInput;
+type SplitNode = {
+  kind: "split";
+  id: NodeId;
+  orientation: Orientation;
+  children: LayoutNode[];
+  sizes: number[];
+  lastFocusedChildId?: NodeId;
+};
+type LayoutNode = PaneNode | SplitNode;
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type ComputedPane = {
+  paneId: PaneId;
+  nodeId: NodeId;
+  rect: Rect;
+  active: boolean;
+};
+type ComputedHandle = {
+  id: string;
+  splitId: NodeId;
+  index: number;
+  rect: Rect;
+  direction: Orientation;
+};
+type ComputedNode = {
+  kind: "pane";
+  pane: ComputedPane;
+} | {
+  kind: "split";
+  orientation: Orientation;
+  children: ComputedNode[];
+  handles: ComputedHandle[];
+};
+type ComputedLayout = {
+  root: ComputedNode;
+  rectByNodeId: Map<NodeId, Rect>;
+  panes: ComputedPane[];
+  handles: ComputedHandle[];
+};
+type FocusGridControllerState = {
+  root: LayoutNode;
+  activePaneId: PaneId | null;
+  container: {
+    width: number;
+    height: number;
+  };
+};
+//#endregion
+//#region core/src/controller.d.ts
+interface DomController {
+  focus(paneId: PaneId): boolean;
+}
+type Listener = (next: FocusGridControllerState, previous: FocusGridControllerState) => void;
+type PaneLayoutChangeEvent = {
+  pane: ComputedPane;
+  previousPane: ComputedPane;
+  controller: FocusGridController;
+};
+type PaneCloseEvent = {
+  paneId: PaneId;
+  previousPane: ComputedPane;
+  controller: FocusGridController;
+};
+type PaneEventHandlers = {
+  onPaneLayoutChange?: (event: PaneLayoutChangeEvent) => void;
+  onPaneClose?: (event: PaneCloseEvent) => void;
+};
+type PaneDefaults = PaneCommandCapabilityInput;
+type FocusGridControllerProps = FocusGridControllerState & {
+  paneDefaults?: PaneDefaults;
+  minWidth?: number;
+  minHeight?: number;
+  directionalFocusOverflow?: boolean;
+};
+type SplitPaneOptions = Partial<Omit<PaneNode, "kind" | "id" | "paneId">> & {
+  side: CardinalDirection;
+  newPaneId?: PaneId;
+  newPaneNodeId?: NodeId;
+  splitId?: NodeId;
+  preserveActivePane?: boolean;
+};
+type ResizePaneOptions = {
+  direction: CardinalDirection;
+  deltaPx: number;
+};
+type ResizeHandleOptions = {
+  index: number;
+  deltaPx: number;
+  snapshotSizes?: number[];
+};
+declare class FocusGridController {
+  private readonly domController;
+  readonly minWidth: number;
+  readonly minHeight: number;
+  readonly directionalFocusOverflow: boolean;
+  private currentState;
+  private cachedLayout;
+  private readonly paneDefaults;
+  private readonly listeners;
+  constructor({
+    paneDefaults,
+    minWidth,
+    minHeight,
+    directionalFocusOverflow,
+    ...state
+  }: FocusGridControllerProps, domController: DomController);
+  /** Computed render data; stable until the next committed change. */
+  getLayout(): ComputedLayout;
+  getPane(paneId: PaneId): PaneNode | null;
+  getContainerSize(): {
+    width: number;
+    height: number;
+  };
+  getSplitSizes(splitId: NodeId): number[] | null;
+  splitActive(side: CardinalDirection): PaneId | null;
+  removeActive(): boolean;
+  focusAdjacent(direction: CardinalDirection): boolean;
+  swapAdjacent(direction: CardinalDirection): boolean;
+  resizeActive(direction: CardinalDirection, deltaPx: number): boolean;
+  split(paneNodeId: NodeId, props: SplitPaneOptions): PaneId | null;
+  remove(paneId: PaneId): boolean;
+  swap(firstPaneId: PaneId, secondPaneId: PaneId): boolean;
+  resize(paneId: PaneId, props: ResizePaneOptions): boolean;
+  resizeHandle(splitId: NodeId, props: ResizeHandleOptions): boolean;
+  focus(paneId: PaneId): boolean;
+  updatePane(paneId: PaneId, patch: Partial<Omit<PaneNode, "kind" | "id" | "paneId">>): boolean;
+  setContainerSize(width: number, height: number): boolean;
+  private commit;
+  subscribePaneEvents({
+    onPaneLayoutChange,
+    onPaneClose
+  }: PaneEventHandlers): () => void;
+  subscribe(listener: Listener): () => void;
+}
+//#endregion
+//#region dom/src/controller.d.ts
+/** Attach the renderer root; pane elements are resolved only when focus is requested. */
+declare class FocusGridDomController implements DomController {
+  private root;
+  setRoot(root: HTMLElement | null): void;
+  focus(paneId: PaneId): boolean;
+}
+//#endregion
+//#region dom/src/mount.d.ts
+/** Own native grid interactions; React only attaches and detaches the root. */
+declare function mountFocusGrid(root: HTMLElement, controller: FocusGridController, dom: FocusGridDomController): () => void;
+//#endregion
+//#region dom/src/interactivity.d.ts
+declare function isEditableTarget(target: EventTarget | null): boolean;
+//#endregion
+export { FocusGridDomController, isEditableTarget, mountFocusGrid };