@octanejs/resizable-panels 0.0.1

package/src/global/utils/findMatchingHitRegions.ts

@@ -0,0 +1,41 @@
+import { calculateHitRegions, type HitRegion } from '../dom/calculateHitRegions';
+import type { MountedGroups } from '../mutable-state/groups';
+import { findClosestHitRegion } from './findClosestHitRegion';
+import { isViableHitTarget } from './isViableHitTarget';
+
+export function findMatchingHitRegions(
+	event: {
+		clientX: number;
+		clientY: number;
+		target: EventTarget | null;
+	},
+	mountedGroups: MountedGroups,
+): HitRegion[] {
+	const matchingHitRegions: HitRegion[] = [];
+
+	mountedGroups.forEach((_, groupData) => {
+		if (groupData.disabled) {
+			return;
+		}
+
+		const hitRegions = calculateHitRegions(groupData);
+		const match = findClosestHitRegion(groupData.orientation, hitRegions, {
+			x: event.clientX,
+			y: event.clientY,
+		});
+		if (
+			match &&
+			match.distance.x <= 0 &&
+			match.distance.y <= 0 &&
+			isViableHitTarget({
+				groupElement: groupData.element,
+				hitRegion: match.hitRegion.rect,
+				pointerEventTarget: event.target,
+			})
+		) {
+			matchingHitRegions.push(match.hitRegion);
+		}
+	});
+
+	return matchingHitRegions;
+}

package/src/global/utils/findSeparatorGroup.ts

@@ -0,0 +1,13 @@
+import { getMountedGroups } from '../mutable-state/groups';
+
+export function findSeparatorGroup(separatorElement: HTMLElement) {
+	const mountedGroups = getMountedGroups();
+
+	for (const [group] of mountedGroups) {
+		if (group.separators.some((separator) => separator.element === separatorElement)) {
+			return group;
+		}
+	}
+
+	throw Error('Could not find parent Group for separator element');
+}

package/src/global/utils/formatLayoutNumber.ts

@@ -0,0 +1,3 @@
+export function formatLayoutNumber(number: number) {
+	return parseFloat(number.toFixed(3));
+}

package/src/global/utils/getDistanceBetweenPointAndRect.ts

@@ -0,0 +1,14 @@
+import type { Point } from '../../types';
+
+export function getDistanceBetweenPointAndRect(point: Point, rect: DOMRectReadOnly) {
+	return {
+		x:
+			point.x >= rect.left && point.x <= rect.right
+				? 0
+				: Math.min(Math.abs(point.x - rect.left), Math.abs(point.x - rect.right)),
+		y:
+			point.y >= rect.top && point.y <= rect.bottom
+				? 0
+				: Math.min(Math.abs(point.y - rect.top), Math.abs(point.y - rect.bottom)),
+	};
+}

package/src/global/utils/getImperativeGroupMethods.ts

@@ -0,0 +1,68 @@
+import type { GroupImperativeHandle, Layout } from '../../components/group/types';
+import { getMountedGroups, updateMountedGroup } from '../mutable-state/groups';
+import { layoutsEqual } from './layoutsEqual';
+import { validatePanelGroupLayout } from './validatePanelGroupLayout';
+
+export function getImperativeGroupMethods({ groupId }: { groupId: string }): GroupImperativeHandle {
+	const find = () => {
+		const mountedGroups = getMountedGroups();
+		for (const [group, value] of mountedGroups) {
+			if (group.id === groupId) {
+				return { group, ...value };
+			}
+		}
+
+		throw Error(`Could not find Group with id "${groupId}"`);
+	};
+
+	return {
+		getLayout() {
+			const { defaultLayoutDeferred, layout } = find();
+
+			if (defaultLayoutDeferred) {
+				// This indicates that the Group has not finished mounting yet
+				// Likely because it has been rendered inside of a hidden DOM subtree
+				// Any layout value will not have been validated and so it should not be returned
+				return {};
+			}
+
+			return layout;
+		},
+		setLayout(unsafeLayout: Layout) {
+			const {
+				defaultLayoutDeferred,
+				derivedPanelConstraints,
+				group,
+				groupSize,
+				layout: prevLayout,
+				separatorToPanels,
+			} = find();
+
+			const nextLayout = validatePanelGroupLayout({
+				layout: unsafeLayout,
+				panelConstraints: derivedPanelConstraints,
+			});
+
+			if (defaultLayoutDeferred) {
+				// This indicates that the Group has not finished mounting yet
+				// Likely because it has been rendered inside of a hidden DOM subtree
+				// In this case we cannot fully validate the layout, so we shouldn't apply it
+				// It's okay to run the validate function above though,
+				// it will still warn about certain types of errors (e.g. wrong number of panels)
+				return prevLayout;
+			}
+
+			if (!layoutsEqual(prevLayout, nextLayout)) {
+				updateMountedGroup(group, {
+					defaultLayoutDeferred,
+					derivedPanelConstraints,
+					groupSize,
+					layout: nextLayout,
+					separatorToPanels,
+				});
+			}
+
+			return nextLayout;
+		},
+	};
+}

package/src/global/utils/getImperativePanelMethods.ts

@@ -0,0 +1,228 @@
+import type { Layout } from '../../components/group/types';
+import type {
+	PanelConstraints,
+	PanelImperativeHandle,
+	RegisteredPanel,
+} from '../../components/panel/types';
+import { calculateAvailableGroupSize } from '../dom/calculateAvailableGroupSize';
+import { getMountedGroups, updateMountedGroup } from '../mutable-state/groups';
+import { sizeStyleToPixels } from '../styles/sizeStyleToPixels';
+import { adjustLayoutByDelta } from './adjustLayoutByDelta';
+import { formatLayoutNumber } from './formatLayoutNumber';
+import { layoutNumbersEqual } from './layoutNumbersEqual';
+import { layoutsEqual } from './layoutsEqual';
+import { validatePanelGroupLayout } from './validatePanelGroupLayout';
+
+export function getImperativePanelMethods({
+	groupId,
+	panelId,
+}: {
+	groupId: string;
+	panelId: string;
+}): PanelImperativeHandle {
+	const find = () => {
+		const mountedGroups = getMountedGroups();
+		for (const [
+			group,
+			{ defaultLayoutDeferred, derivedPanelConstraints, layout, groupSize, separatorToPanels },
+		] of mountedGroups) {
+			if (group.id === groupId) {
+				return {
+					defaultLayoutDeferred,
+					derivedPanelConstraints,
+					group,
+					groupSize,
+					layout,
+					separatorToPanels,
+				};
+			}
+		}
+
+		throw Error(`Group ${groupId} not found`);
+	};
+
+	const getPanelConstraints = () => {
+		const match = find().derivedPanelConstraints.find((current) => current.panelId === panelId);
+		if (match !== undefined) {
+			return match;
+		}
+
+		throw Error(`Panel constraints not found for Panel ${panelId}`);
+	};
+
+	const getPanel = () => {
+		const match = find().group.panels.find((current) => current.id === panelId);
+		if (match !== undefined) {
+			return match;
+		}
+
+		throw Error(`Layout not found for Panel ${panelId}`);
+	};
+
+	const getPanelSize = () => {
+		const match = find().layout[panelId];
+		if (match !== undefined) {
+			return match;
+		}
+
+		throw Error(`Layout not found for Panel ${panelId}`);
+	};
+
+	/**
+	 * Compute the next (unvalidated) layout when resizing a panel imperatively.
+	 *
+	 * Handles two edge cases for the last panel:
+	 * 1. Single panel in the group — no sibling exists to form valid pivot indices.
+	 * 2. All preceding panels are already collapsed — the normal reversed-delta
+	 *    logic would cascade the freed space to the first panel. Instead the last
+	 *    panel keeps the remainder so it stays the largest.
+	 */
+	const computeLayout = ({
+		nextSize,
+		panels,
+		prevLayout,
+		derivedPanelConstraints,
+	}: {
+		nextSize: number;
+		panels: RegisteredPanel[];
+		prevLayout: Layout;
+		derivedPanelConstraints: PanelConstraints[];
+	}): Layout => {
+		const prevSize = getPanelSize();
+
+		const index = panels.findIndex((current) => current.id === panelId);
+		const isFirstPanel = index === 0;
+		const isLastPanel = index === panels.length - 1;
+
+		const allPreviousCollapsed =
+			isLastPanel &&
+			nextSize < prevSize &&
+			(isFirstPanel ||
+				panels.slice(0, index).every((_panel, panelIndex) => {
+					const pc = derivedPanelConstraints[panelIndex];
+					return pc?.collapsible && layoutNumbersEqual(pc.collapsedSize, prevLayout[pc.panelId]);
+				}));
+
+		if (allPreviousCollapsed) {
+			const occupiedByPrevious = panels
+				.slice(0, index)
+				.reduce((total, panel) => total + prevLayout[panel.id], 0);
+			return {
+				...prevLayout,
+				[panelId]: formatLayoutNumber(100 - occupiedByPrevious),
+			};
+		}
+
+		return adjustLayoutByDelta({
+			delta: isLastPanel ? prevSize - nextSize : nextSize - prevSize,
+			initialLayout: prevLayout,
+			panelConstraints: derivedPanelConstraints,
+			pivotIndices: isLastPanel ? [index - 1, index] : [index, index + 1],
+			prevLayout,
+			trigger: 'imperative-api',
+		});
+	};
+
+	const setPanelSize = (nextSize: number) => {
+		const prevSize = getPanelSize();
+		if (nextSize === prevSize) {
+			return;
+		}
+
+		const {
+			defaultLayoutDeferred,
+			derivedPanelConstraints,
+			group,
+			groupSize,
+			layout: prevLayout,
+			separatorToPanels,
+		} = find();
+
+		const unsafeLayout = computeLayout({
+			nextSize,
+			panels: group.panels,
+			prevLayout,
+			derivedPanelConstraints,
+		});
+
+		const nextLayout = validatePanelGroupLayout({
+			layout: unsafeLayout,
+			panelConstraints: derivedPanelConstraints,
+		});
+		if (!layoutsEqual(prevLayout, nextLayout)) {
+			updateMountedGroup(group, {
+				defaultLayoutDeferred,
+				derivedPanelConstraints,
+				groupSize,
+				layout: nextLayout,
+				separatorToPanels,
+			});
+		}
+	};
+
+	return {
+		collapse: () => {
+			const { collapsible, collapsedSize } = getPanelConstraints();
+			const { mutableValues } = getPanel();
+			const size = getPanelSize();
+
+			if (collapsible && size !== collapsedSize) {
+				// Store previous size in to restore if expand() is called
+				mutableValues.expandToSize = size;
+
+				setPanelSize(collapsedSize);
+			}
+		},
+		expand: () => {
+			const { collapsible, collapsedSize, minSize } = getPanelConstraints();
+			const { mutableValues } = getPanel();
+			const size = getPanelSize();
+
+			if (collapsible && size === collapsedSize) {
+				// Restore pre-collapse size, fallback to minSize
+				let nextSize = mutableValues.expandToSize ?? minSize;
+
+				// Edge case: if minSize is 0, pick something meaningful to expand the panel to
+				if (nextSize === 0) {
+					nextSize = 1;
+				}
+
+				setPanelSize(nextSize);
+			}
+		},
+		getSize: () => {
+			const { group } = find();
+			const asPercentage = getPanelSize();
+			const { element } = getPanel();
+
+			const inPixels =
+				group.orientation === 'horizontal' ? element.offsetWidth : element.offsetHeight;
+
+			return {
+				asPercentage,
+				inPixels,
+			};
+		},
+		isCollapsed: () => {
+			const { collapsible, collapsedSize } = getPanelConstraints();
+			const size = getPanelSize();
+
+			return collapsible && layoutNumbersEqual(collapsedSize, size);
+		},
+		resize: (size: number | string) => {
+			const { group } = find();
+			const { element } = getPanel();
+			const groupSize = calculateAvailableGroupSize({ group });
+
+			const asPixels = sizeStyleToPixels({
+				groupSize,
+				panelElement: element,
+				styleProp: size,
+			});
+
+			const asPercentage = formatLayoutNumber((asPixels / groupSize) * 100);
+
+			setPanelSize(asPercentage);
+		},
+	} satisfies PanelImperativeHandle;
+}

package/src/global/utils/isCoarsePointer.ts

@@ -0,0 +1,8 @@
+let cached: boolean | undefined;
+
+/** Caches the current primary-pointer precision without reading browser globals during SSR. */
+export function isCoarsePointer(): boolean {
+	if (cached === undefined)
+		cached = typeof matchMedia === 'function' && matchMedia('(pointer:coarse)').matches;
+	return cached;
+}

package/src/global/utils/isViableHitTarget.ts

@@ -0,0 +1,53 @@
+import { isHTMLElement } from '../../utils/isHTMLElement';
+import { compare } from '../../vendor/stacking-order';
+import { doRectsIntersect } from './doRectsIntersect';
+
+// This library adds pointer event handlers to the Window for two reasons:
+// 1. It allows detecting when the pointer is "near" to a panel border or separator element,
+//    (which can be particularly helpful on touch devices)
+// 2. It allows detecting pointer interactions that apply to multiple, nearby panels/separators
+//    (in the event of e.g. nested groups)
+//
+// Because events are handled at the Window, it's important to detect when another element is "above" a separator (e.g. a modal)
+// as this should prevent the separator element from being clicked.
+// This function does that determination.
+export function isViableHitTarget({
+	groupElement,
+	hitRegion,
+	pointerEventTarget,
+}: {
+	groupElement: HTMLElement;
+	hitRegion: DOMRect;
+	pointerEventTarget: EventTarget | null;
+}) {
+	if (
+		!isHTMLElement(pointerEventTarget) ||
+		pointerEventTarget.contains(groupElement) ||
+		groupElement.contains(pointerEventTarget)
+	) {
+		// Calculating stacking order has a cost;
+		// If either group or element contain the other, the click is safe and we can skip calculating the indices
+		return true;
+	}
+
+	if (compare(pointerEventTarget, groupElement) > 0) {
+		// If the pointer target is above the separator, check for overlap
+		// If they are near each other, but not overlapping, then the separator is still a viable target
+		//
+		// Note that it's not sufficient to compare only the target
+		// The target might be a small element inside of a larger container
+		// (For example, a SPAN or a DIV inside of a larger modal dialog)
+		let currentElement: HTMLElement | SVGElement | null = pointerEventTarget;
+		while (currentElement) {
+			if (currentElement.contains(groupElement)) {
+				return true;
+			} else if (doRectsIntersect(currentElement.getBoundingClientRect(), hitRegion)) {
+				return false;
+			}
+
+			currentElement = currentElement.parentElement;
+		}
+	}
+
+	return true;
+}

package/src/global/utils/layoutNumbersEqual.ts

@@ -0,0 +1,5 @@
+import { formatLayoutNumber } from './formatLayoutNumber';
+
+export function layoutNumbersEqual(actual: number, expected: number, minimumDelta = 0) {
+	return Math.abs(formatLayoutNumber(actual) - formatLayoutNumber(expected)) <= minimumDelta;
+}

package/src/global/utils/layoutsEqual.ts

@@ -0,0 +1,17 @@
+import type { Layout } from '../../components/group/types';
+import { compareLayoutNumbers } from './compareLayoutNumbers';
+
+export function layoutsEqual(a: Layout, b: Layout): boolean {
+	if (Object.keys(a).length !== Object.keys(b).length) {
+		return false;
+	}
+
+	for (const id in a) {
+		// Edge case: Panel id has been changed
+		if (b[id] === undefined || compareLayoutNumbers(a[id], b[id]) !== 0) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/global/utils/notifyPanelOnResize.ts

@@ -0,0 +1,33 @@
+import type { RegisteredGroup } from '../../components/group/types';
+import { calculateAvailableGroupSize } from '../dom/calculateAvailableGroupSize';
+import { formatLayoutNumber } from './formatLayoutNumber';
+
+export function notifyPanelOnResize(
+	group: RegisteredGroup,
+	element: HTMLElement,
+	borderBoxSize: readonly ResizeObserverSize[],
+) {
+	const resizeObserverSize = borderBoxSize[0];
+	if (!resizeObserverSize) {
+		return;
+	}
+
+	const panel = group.panels.find((current) => current.element === element);
+	if (!panel || !panel.onResize) {
+		return;
+	}
+
+	const groupSize = calculateAvailableGroupSize({ group });
+
+	const panelSize =
+		group.orientation === 'horizontal' ? panel.element.offsetWidth : panel.element.offsetHeight;
+
+	const prevSize = panel.mutableValues.prevSize;
+	const nextSize = {
+		asPercentage: formatLayoutNumber((panelSize / groupSize) * 100),
+		inPixels: panelSize,
+	};
+	panel.mutableValues.prevSize = nextSize;
+
+	panel.onResize(nextSize, panel.id, prevSize);
+}

package/src/global/utils/objectsEqual.ts

@@ -0,0 +1,14 @@
+export function objectsEqual(a: object, b: object) {
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) {
+		return false;
+	}
+
+	for (const key in a) {
+		if (a[key as keyof typeof a] !== b[key as keyof typeof b]) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/global/utils/preserveFixedPanelSizes.ts

@@ -0,0 +1,74 @@
+import type { Layout, RegisteredGroup } from '../../components/group/types';
+import { formatLayoutNumber } from './formatLayoutNumber';
+
+export function preserveFixedPanelSizes({
+	group,
+	nextGroupSize,
+	prevGroupSize,
+	prevLayout,
+}: {
+	group: RegisteredGroup;
+	nextGroupSize: number;
+	prevGroupSize: number;
+	prevLayout: Layout;
+}) {
+	if (prevGroupSize <= 0 || nextGroupSize <= 0 || prevGroupSize === nextGroupSize) {
+		return prevLayout;
+	}
+
+	let fixedPanelsTotalSize = 0;
+	let flexiblePanelsTotalPrevSize = 0;
+	let hasPreservePixelSizePanels = false;
+
+	const fixedPanels = new Map<string, number>();
+	const flexiblePanelIds: string[] = [];
+
+	for (const panel of group.panels) {
+		const prevPanelSize = prevLayout[panel.id] ?? 0;
+		switch (panel.panelConstraints.groupResizeBehavior) {
+			case 'preserve-pixel-size': {
+				hasPreservePixelSizePanels = true;
+
+				const prevPanelSizeInPixels = (prevPanelSize / 100) * prevGroupSize;
+				const nextPanelSize = formatLayoutNumber((prevPanelSizeInPixels / nextGroupSize) * 100);
+
+				fixedPanels.set(panel.id, nextPanelSize);
+				fixedPanelsTotalSize += nextPanelSize;
+				break;
+			}
+			case 'preserve-relative-size':
+			default: {
+				flexiblePanelIds.push(panel.id);
+				flexiblePanelsTotalPrevSize += prevPanelSize;
+				break;
+			}
+		}
+	}
+
+	if (!hasPreservePixelSizePanels || flexiblePanelIds.length === 0) {
+		return prevLayout;
+	}
+
+	const remainingSize = 100 - fixedPanelsTotalSize;
+	const nextLayout = { ...prevLayout };
+
+	fixedPanels.forEach((size, panelId) => {
+		nextLayout[panelId] = size;
+	});
+
+	if (flexiblePanelsTotalPrevSize > 0) {
+		for (const panelId of flexiblePanelIds) {
+			const prevSize = prevLayout[panelId] ?? 0;
+			nextLayout[panelId] = formatLayoutNumber(
+				(prevSize / flexiblePanelsTotalPrevSize) * remainingSize,
+			);
+		}
+	} else {
+		const evenSize = formatLayoutNumber(remainingSize / flexiblePanelIds.length);
+		for (const panelId of flexiblePanelIds) {
+			nextLayout[panelId] = evenSize;
+		}
+	}
+
+	return nextLayout;
+}