@octanejs/resizable-panels 0.0.1

package/src/global/utils/updateActiveHitRegion.ts

@@ -0,0 +1,132 @@
+import type { Layout, RegisteredGroup } from '../../components/group/types';
+import {
+	CURSOR_FLAG_HORIZONTAL_MAX,
+	CURSOR_FLAG_HORIZONTAL_MIN,
+	CURSOR_FLAG_VERTICAL_MAX,
+	CURSOR_FLAG_VERTICAL_MIN,
+	CURSOR_FLAGS_HORIZONTAL,
+	CURSOR_FLAGS_VERTICAL,
+} from '../../constants';
+import type { Point } from '../../types';
+import { updateCursorStyle } from '../cursor/updateCursorStyle';
+import type { HitRegion } from '../dom/calculateHitRegions';
+import { updateMountedGroup, type MountedGroups } from '../mutable-state/groups';
+import { updateCursorFlags } from '../mutable-state/interactions';
+import { adjustLayoutByDelta } from './adjustLayoutByDelta';
+import { layoutsEqual } from './layoutsEqual';
+
+export function updateActiveHitRegions({
+	document,
+	event,
+	hitRegions,
+	initialLayoutMap,
+	mountedGroups,
+	pointerDownAtPoint,
+	prevCursorFlags,
+}: {
+	document: Document;
+	event: {
+		clientX: number;
+		clientY: number;
+		movementX: number;
+		movementY: number;
+	};
+	hitRegions: HitRegion[];
+	initialLayoutMap: Map<RegisteredGroup, Layout>;
+	mountedGroups: MountedGroups;
+	pointerDownAtPoint?: Point;
+	prevCursorFlags: number;
+}) {
+	let nextCursorFlags = 0;
+
+	// Note that HitRegions are frozen once a drag has started
+	// Modify the Group layouts for all matching HitRegions though
+	hitRegions.forEach((current) => {
+		const { group, groupSize } = current;
+		const { orientation, panels } = group;
+		const { disableCursor } = group.mutableState;
+
+		let deltaAsPercentage = 0;
+		if (pointerDownAtPoint) {
+			if (orientation === 'horizontal') {
+				deltaAsPercentage = ((event.clientX - pointerDownAtPoint.x) / groupSize) * 100;
+			} else {
+				deltaAsPercentage = ((event.clientY - pointerDownAtPoint.y) / groupSize) * 100;
+			}
+		} else {
+			if (orientation === 'horizontal') {
+				deltaAsPercentage = event.clientX < 0 ? -100 : 100;
+			} else {
+				deltaAsPercentage = event.clientY < 0 ? -100 : 100;
+			}
+		}
+
+		const initialLayout = initialLayoutMap.get(group);
+		const groupState = mountedGroups.get(group);
+		if (!initialLayout || !groupState) {
+			return;
+		}
+
+		const {
+			defaultLayoutDeferred,
+			derivedPanelConstraints,
+			groupSize: mountedGroupSize,
+			layout: prevLayout,
+			separatorToPanels,
+		} = groupState;
+		if (derivedPanelConstraints && prevLayout && separatorToPanels) {
+			const nextLayout = adjustLayoutByDelta({
+				delta: deltaAsPercentage,
+				initialLayout,
+				panelConstraints: derivedPanelConstraints,
+				pivotIndices: current.panels.map((panel) => panels.indexOf(panel)),
+				prevLayout,
+				trigger: 'mouse-or-touch',
+			});
+
+			if (layoutsEqual(nextLayout, prevLayout)) {
+				if (deltaAsPercentage !== 0 && !disableCursor) {
+					// An unchanged means the cursor has exceeded the allowed bounds
+					switch (orientation) {
+						case 'horizontal': {
+							nextCursorFlags |=
+								deltaAsPercentage < 0 ? CURSOR_FLAG_HORIZONTAL_MIN : CURSOR_FLAG_HORIZONTAL_MAX;
+							break;
+						}
+						case 'vertical': {
+							nextCursorFlags |=
+								deltaAsPercentage < 0 ? CURSOR_FLAG_VERTICAL_MIN : CURSOR_FLAG_VERTICAL_MAX;
+							break;
+						}
+					}
+				}
+			} else {
+				updateMountedGroup(current.group, {
+					defaultLayoutDeferred,
+					derivedPanelConstraints: derivedPanelConstraints,
+					groupSize: mountedGroupSize,
+					layout: nextLayout,
+					separatorToPanels,
+				});
+			}
+		}
+	});
+
+	// Edge case
+	// Re-use previous horizontal/vertical cursor flags if there's been no movement since the last event
+	// This accounts for edge cases in browsers like Firefox that sometimes round clientX/clientY values
+	let cursorFlags = 0;
+	if (event.movementX === 0) {
+		cursorFlags |= prevCursorFlags & CURSOR_FLAGS_HORIZONTAL;
+	} else {
+		cursorFlags |= nextCursorFlags & CURSOR_FLAGS_HORIZONTAL;
+	}
+	if (event.movementY === 0) {
+		cursorFlags |= prevCursorFlags & CURSOR_FLAGS_VERTICAL;
+	} else {
+		cursorFlags |= nextCursorFlags & CURSOR_FLAGS_VERTICAL;
+	}
+
+	updateCursorFlags(cursorFlags);
+	updateCursorStyle(document);
+}

package/src/global/utils/validateLayoutKeys.ts

@@ -0,0 +1,19 @@
+import type { Layout } from '../../components/group/types';
+import type { RegisteredPanel } from '../../components/panel/types';
+
+export function validateLayoutKeys(panels: RegisteredPanel[], layout: Layout) {
+	const panelIds = panels.map((panel) => panel.id);
+	const layoutKeys = Object.keys(layout);
+
+	if (panelIds.length !== layoutKeys.length) {
+		return false;
+	}
+
+	for (const panelId of panelIds) {
+		if (!layoutKeys.includes(panelId)) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/global/utils/validatePanelGroupLayout.ts

@@ -0,0 +1,92 @@
+import type { Layout } from '../../components/group/types';
+import type { PanelConstraints } from '../../components/panel/types';
+import { assert } from '../../utils/assert';
+import { layoutNumbersEqual } from './layoutNumbersEqual';
+import { validatePanelSize } from './validatePanelSize';
+
+// All units must be in percentages; pixel values should be pre-converted
+export function validatePanelGroupLayout({
+	layout,
+	panelConstraints,
+}: {
+	layout: Layout;
+	panelConstraints: PanelConstraints[];
+}): Layout {
+	const prevLayout = Object.values(layout);
+	const nextLayout = [...prevLayout];
+
+	const nextLayoutTotalSize = nextLayout.reduce((accumulated, current) => accumulated + current, 0);
+
+	// Validate layout expectations
+	if (nextLayout.length !== panelConstraints.length) {
+		throw Error(
+			`Invalid ${panelConstraints.length} panel layout: ${nextLayout
+				.map((size) => `${size}%`)
+				.join(', ')}`,
+		);
+	} else if (!layoutNumbersEqual(nextLayoutTotalSize, 100) && nextLayout.length > 0) {
+		for (let index = 0; index < panelConstraints.length; index++) {
+			const unsafeSize = nextLayout[index];
+			assert(unsafeSize != null, `No layout data found for index ${index}`);
+			const safeSize = (100 / nextLayoutTotalSize) * unsafeSize;
+			nextLayout[index] = safeSize;
+		}
+	}
+
+	let remainingSize = 0;
+
+	// First pass: Validate the proposed layout given each panel's constraints
+	for (let index = 0; index < panelConstraints.length; index++) {
+		const prevSize = prevLayout[index];
+		assert(prevSize != null, `No layout data found for index ${index}`);
+
+		const unsafeSize = nextLayout[index];
+		assert(unsafeSize != null, `No layout data found for index ${index}`);
+
+		const safeSize = validatePanelSize({
+			overrideDisabledPanels: true,
+			panelConstraints: panelConstraints[index],
+			prevSize,
+			size: unsafeSize,
+		});
+
+		if (unsafeSize != safeSize) {
+			remainingSize += unsafeSize - safeSize;
+
+			nextLayout[index] = safeSize;
+		}
+	}
+
+	// If there is additional, left over space, assign it to any panel(s) that permits it
+	// (It's not worth taking multiple additional passes to evenly distribute)
+	if (!layoutNumbersEqual(remainingSize, 0)) {
+		for (let index = 0; index < panelConstraints.length; index++) {
+			const prevSize = nextLayout[index];
+			assert(prevSize != null, `No layout data found for index ${index}`);
+			const unsafeSize = prevSize + remainingSize;
+			const safeSize = validatePanelSize({
+				overrideDisabledPanels: true,
+				panelConstraints: panelConstraints[index],
+				prevSize,
+				size: unsafeSize,
+			});
+
+			if (prevSize !== safeSize) {
+				remainingSize -= safeSize - prevSize;
+				nextLayout[index] = safeSize;
+
+				// Once we've used up the remainder, bail
+				if (layoutNumbersEqual(remainingSize, 0)) {
+					break;
+				}
+			}
+		}
+	}
+
+	const prevLayoutKeys = Object.keys(layout);
+
+	return nextLayout.reduce<Layout>((accumulated, current, index) => {
+		accumulated[prevLayoutKeys[index]] = current;
+		return accumulated;
+	}, {});
+}

package/src/global/utils/validatePanelSize.ts

@@ -0,0 +1,41 @@
+import type { PanelConstraints } from '../../components/panel/types';
+import { compareLayoutNumbers } from './compareLayoutNumbers';
+import { formatLayoutNumber } from './formatLayoutNumber';
+
+// Panel size must be in percentages; pixel values should be pre-converted
+export function validatePanelSize({
+	overrideDisabledPanels,
+	panelConstraints,
+	prevSize,
+	size,
+}: {
+	overrideDisabledPanels?: boolean;
+	panelConstraints: PanelConstraints;
+	prevSize: number;
+	size: number;
+}) {
+	const { collapsedSize = 0, collapsible, disabled, maxSize = 100, minSize = 0 } = panelConstraints;
+
+	if (disabled && !overrideDisabledPanels) {
+		return prevSize;
+	}
+
+	if (compareLayoutNumbers(size, minSize) < 0) {
+		if (collapsible) {
+			// Collapsible panels should snap closed or open only once they cross the halfway point between collapsed and min size.
+			const halfwayPoint = (collapsedSize + minSize) / 2;
+			if (compareLayoutNumbers(size, halfwayPoint) < 0) {
+				size = collapsedSize;
+			} else {
+				size = minSize;
+			}
+		} else {
+			size = minSize;
+		}
+	}
+
+	size = Math.min(maxSize, size);
+	size = formatLayoutNumber(size);
+
+	return size;
+}

package/src/hooks/useForceUpdate.ts

@@ -0,0 +1,8 @@
+import { useCallback, useState } from 'octane';
+import { subSlot } from '../internal';
+
+export function useForceUpdate(slot?: symbol) {
+	const [sigil, setSigil] = useState({}, subSlot(slot, 'state'));
+	const forceUpdate = useCallback(() => setSigil({}), [], subSlot(slot, 'callback'));
+	return [sigil as unknown, forceUpdate] as const;
+}

package/src/hooks/useId.ts

@@ -0,0 +1,6 @@
+import { useId as useOctaneId } from 'octane';
+
+export function useId(stableId: number | string | undefined, slot?: symbol): string {
+	const dynamicId = useOctaneId(slot);
+	return `${stableId ?? dynamicId}`;
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,4 @@
+import { useEffect, useLayoutEffect } from 'octane';
+
+export const useIsomorphicLayoutEffect =
+	typeof window === 'undefined' ? useEffect : useLayoutEffect;

package/src/hooks/useMergedRefs.ts

@@ -0,0 +1,18 @@
+import type { Octane } from 'octane/jsx-runtime';
+import { useStableCallback } from './useStableCallback';
+
+type PossibleRef<Type> = Octane.Ref<Type> | undefined;
+
+export function useMergedRefs<Type>(...args: Array<PossibleRef<Type> | symbol>) {
+	const maybeSlot = args.at(-1);
+	const slot = typeof maybeSlot === 'symbol' ? maybeSlot : undefined;
+	const refs = (slot === undefined ? args : args.slice(0, -1)) as PossibleRef<Type>[];
+	return useStableCallback((value: Type | null) => {
+		const assign = (ref: PossibleRef<Type>) => {
+			if (Array.isArray(ref)) for (const child of ref) assign(child);
+			else if (typeof ref === 'function') ref(value);
+			else if (ref) (ref as { current: Type | null }).current = value;
+		};
+		for (const ref of refs) assign(ref);
+	}, slot);
+}

package/src/hooks/useStableArray.ts

@@ -0,0 +1,15 @@
+import { useRef } from 'octane';
+import { subSlot } from '../internal';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+
+export function useStableArray<Type>(value: Type[], slot?: symbol): Type[] {
+	const ref = useRef<Type[]>([...value], subSlot(slot, 'ref'));
+	useIsomorphicLayoutEffect(
+		() => {
+			ref.current.splice(0, ref.current.length, ...value);
+		},
+		[value],
+		subSlot(slot, 'effect'),
+	);
+	return ref.current;
+}

package/src/hooks/useStableCallback.ts

@@ -0,0 +1,18 @@
+import { useCallback, useRef } from 'octane';
+import { subSlot } from '../internal';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+
+export function useStableCallback<Args extends readonly unknown[], Result>(
+	fn: (...args: Args) => Result,
+	slot?: symbol,
+): (...args: Args) => Result {
+	const ref = useRef(fn, subSlot(slot, 'ref'));
+	useIsomorphicLayoutEffect(
+		() => {
+			ref.current = fn;
+		},
+		[fn],
+		subSlot(slot, 'effect'),
+	);
+	return useCallback((...args: Args) => ref.current(...args), [], subSlot(slot, 'callback'));
+}

package/src/hooks/useStableObject.ts

@@ -0,0 +1,15 @@
+import { useRef } from 'octane';
+import { subSlot } from '../internal';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+
+export function useStableObject<Type extends object>(value: Type, slot?: symbol): Type {
+	const ref = useRef<Type>({ ...value }, subSlot(slot, 'ref'));
+	useIsomorphicLayoutEffect(
+		() => {
+			Object.assign(ref.current, value);
+		},
+		[value],
+		subSlot(slot, 'effect'),
+	);
+	return ref.current;
+}

package/src/index.tsrx

@@ -0,0 +1,12 @@
+export { Group } from './components/group/Group.tsrx';
+export { Panel } from './components/panel/Panel.tsrx';
+export { Separator } from './components/separator/Separator.tsrx';
+export { useGroupCallbackRef } from './components/group/useGroupCallbackRef';
+export { useGroupRef } from './components/group/useGroupRef';
+export { useDefaultLayout } from './components/group/useDefaultLayout';
+export { usePanelCallbackRef } from './components/panel/usePanelCallbackRef';
+export { usePanelRef } from './components/panel/usePanelRef';
+export { isCoarsePointer } from './global/utils/isCoarsePointer';
+export type { GroupImperativeHandle, GroupProps, Layout, LayoutChangedMeta, LayoutStorage, OnGroupLayoutChange, Orientation } from './components/group/types';
+export type { OnPanelResize, PanelImperativeHandle, PanelProps, PanelSize, SizeUnit } from './components/panel/types';
+export type { SeparatorProps } from './components/separator/types';

package/src/internal.ts

@@ -0,0 +1,23 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined)
+			bareTagCache.set(tag, (bare = Symbol.for(`react-resizable-panels:${tag}`)));
+		return bare;
+	}
+
+	let tags = subSlotCache.get(slot);
+	if (tags === undefined) subSlotCache.set(slot, (tags = new Map()));
+	let child = tags.get(tag);
+	if (child === undefined) tags.set(tag, (child = Symbol.for(`${slot.description ?? ''}:${tag}`)));
+	return child;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+export type Dimensions = { height: number; width: number };
+export type Point = { x: number; y: number };
+export type PointerPrecision = { coarse: number; precise: number };
+export type Rect = Dimensions & Point;
+
+export type {
+	Layout,
+	LayoutChangedMeta,
+	LayoutStorage,
+	Orientation,
+} from './components/group/types';
+export type {
+	GroupResizeBehavior,
+	PanelConstraints,
+	PanelImperativeHandle,
+	PanelSize,
+	SizeUnit,
+} from './components/panel/types';

package/src/utils/EventEmitter.ts

@@ -0,0 +1,72 @@
+export type EventMap = {
+	[key: string]: unknown;
+};
+
+export type EventListener<Data> = (data: Data) => void;
+
+export class EventEmitter<Events extends EventMap> {
+	#listenerMap: {
+		[Key in keyof Events]?: EventListener<Events[Key]>[];
+	} = {};
+
+	addListener<Type extends keyof Events>(type: Type, listener: EventListener<Events[Type]>) {
+		const listeners = this.#listenerMap[type];
+		if (listeners === undefined) {
+			this.#listenerMap[type] = [listener];
+		} else {
+			if (!listeners.includes(listener)) {
+				listeners.push(listener);
+			}
+		}
+
+		return () => {
+			this.removeListener(type, listener);
+		};
+	}
+
+	emit<Type extends keyof Events>(type: Type, data: Events[Type]) {
+		const listeners = this.#listenerMap[type];
+		if (listeners !== undefined) {
+			if (listeners.length === 1) {
+				const listener = listeners[0];
+				listener.call(null, data);
+			} else {
+				let didThrow = false;
+				let caughtError = null;
+
+				// Clone the current listeners before calling
+				// in case calling triggers listeners to be added or removed
+				const clonedListeners = Array.from(listeners);
+				for (let i = 0; i < clonedListeners.length; i++) {
+					const listener = clonedListeners[i];
+					try {
+						listener.call(null, data);
+					} catch (error) {
+						if (caughtError === null) {
+							didThrow = true;
+							caughtError = error;
+						}
+					}
+				}
+
+				if (didThrow) {
+					throw caughtError;
+				}
+			}
+		}
+	}
+
+	removeAllListeners() {
+		this.#listenerMap = {};
+	}
+
+	removeListener<Type extends keyof Events>(type: Type, listener: EventListener<Events[Type]>) {
+		const listeners = this.#listenerMap[type];
+		if (listeners !== undefined) {
+			const index = listeners.indexOf(listener);
+			if (index >= 0) {
+				listeners.splice(index, 1);
+			}
+		}
+	}
+}

package/src/utils/assert.ts

@@ -0,0 +1,8 @@
+export function assert(
+	expectedCondition: unknown,
+	message: string = 'Assertion error',
+): asserts expectedCondition {
+	if (!expectedCondition) {
+		throw Error(message);
+	}
+}

package/src/utils/isArrayEqual.ts

@@ -0,0 +1,12 @@
+export function isArrayEqual(a: number[], b: number[]) {
+	if (a.length !== b.length) {
+		return false;
+	} else {
+		for (let index = 0; index < a.length; index++) {
+			if (a[index] != b[index]) {
+				return false;
+			}
+		}
+	}
+	return true;
+}

package/src/utils/isHTMLElement.ts

@@ -0,0 +1,9 @@
+// Detects HTMLElement without requiring instanceof and browser globals
+export function isHTMLElement(value: unknown): value is HTMLElement {
+	return (
+		value !== null &&
+		typeof value === 'object' &&
+		'nodeType' in value &&
+		value.nodeType === Node.ELEMENT_NODE
+	);
+}

package/src/utils/isShadowRoot.ts

@@ -0,0 +1,9 @@
+// Detects ShadowRoot without requiring instanceof and browser globals
+export function isShadowRoot(value: unknown): value is ShadowRoot {
+	return (
+		value !== null &&
+		typeof value === 'object' &&
+		'nodeType' in value &&
+		value.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+	);
+}

package/src/utils/parseNumericStyleValue.ts

@@ -0,0 +1,15 @@
+export function parseNumericStyleValue(value: number | string | undefined): number | undefined {
+	if (value !== undefined) {
+		switch (typeof value) {
+			case 'number': {
+				return value;
+			}
+			case 'string': {
+				if (value.endsWith('px')) {
+					return parseFloat(value);
+				}
+				break;
+			}
+		}
+	}
+}