@octanejs/resizable-panels 0.0.1

package/src/components/group/useDefaultLayout.ts

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'octane';
+import { splitSlot, subSlot } from '../../internal';
+import { getStorageKey } from './auto-save/getStorageKey';
+import { readLegacyLayout } from './auto-save/readLegacyLayout';
+import type { Layout, LayoutChangedMeta, LayoutStorage } from './types';
+
+type UseDefaultLayoutOptions = {
+	debounceSaveMs?: number;
+	onlySaveAfterUserInteractions?: boolean;
+	panelIds?: string[];
+	storage?: LayoutStorage;
+} & ({ groupId: string } | { id: string });
+
+export function useDefaultLayout(options: UseDefaultLayoutOptions, ...rest: [symbol?]) {
+	const [args, slot] = splitSlot(rest);
+	if (args.length !== 0) throw new TypeError('useDefaultLayout() accepts one options argument.');
+	const {
+		debounceSaveMs = 100,
+		onlySaveAfterUserInteractions,
+		panelIds,
+		storage: storageProp,
+		...identity
+	} = options;
+	const id = 'id' in identity ? identity.id : identity.groupId;
+	const hasPanelIds = panelIds !== undefined;
+	const storage = resolveStorage(storageProp);
+	const readStorageKey = getStorageKey(id, panelIds ?? []);
+	// Match upstream: the same storage read runs on server and client so
+	// cookie/DB-backed LayoutStorage can restore during SSR. Client-only APIs
+	// (implicit localStorage) resolve to undefined on the server via
+	// resolveStorage, so the snapshot stays null without a custom storage prop.
+	const defaultLayoutString = useSyncExternalStore(
+		subscribe,
+		() => readDefaultLayoutString(storage, readStorageKey, id, panelIds),
+		() => readDefaultLayoutString(storage, readStorageKey, id, panelIds),
+		subSlot(slot, 'stored-layout'),
+	);
+	const defaultLayout = useMemo(
+		() => readModernLayout(defaultLayoutString),
+		[defaultLayoutString],
+		subSlot(slot, 'default-layout'),
+	);
+	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null, subSlot(slot, 'timeout'));
+	const storageRef = useRef<LayoutStorage | undefined>(storage, subSlot(slot, 'storage'));
+	storageRef.current = storage;
+
+	const clearPendingTimeout = useCallback(
+		() => {
+			if (timeoutRef.current !== null) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		},
+		[],
+		subSlot(slot, 'clear-timeout'),
+	);
+
+	useEffect(() => clearPendingTimeout, [clearPendingTimeout], subSlot(slot, 'cleanup-effect'));
+
+	const onLayoutChanged = useCallback<(layout: Layout, meta: LayoutChangedMeta) => void>(
+		(layout: Layout, meta: LayoutChangedMeta) => {
+			if (onlySaveAfterUserInteractions && !meta.isUserInteraction) return;
+			clearPendingTimeout();
+
+			const storage = storageRef.current;
+			if (!storage) return;
+			const key = getStorageKey(id, hasPanelIds ? Object.keys(layout) : []);
+			try {
+				storage.setItem(key, JSON.stringify(layout));
+			} catch (error) {
+				console.error(error);
+			}
+		},
+		[clearPendingTimeout, hasPanelIds, id, onlySaveAfterUserInteractions],
+		subSlot(slot, 'layout-changed'),
+	);
+
+	const onLayoutChange = useCallback<(layout: Layout) => void>(
+		(layout: Layout) => {
+			clearPendingTimeout();
+			if (debounceSaveMs === 0) {
+				onLayoutChanged(layout, { isUserInteraction: false });
+			} else {
+				timeoutRef.current = setTimeout(
+					() => onLayoutChanged(layout, { isUserInteraction: false }),
+					debounceSaveMs,
+				);
+			}
+		},
+		[clearPendingTimeout, debounceSaveMs, onLayoutChanged],
+		subSlot(slot, 'layout-change'),
+	);
+
+	return { defaultLayout, onLayoutChange, onLayoutChanged };
+}
+
+function subscribe() {
+	return () => {};
+}
+
+function resolveStorage(storage: LayoutStorage | undefined): LayoutStorage | undefined {
+	if (storage) return storage;
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return undefined;
+	}
+}
+
+function readStorageItem(storage: LayoutStorage | undefined, key: string): string | null {
+	if (!storage) return null;
+	try {
+		return storage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+
+function readDefaultLayoutString(
+	storage: LayoutStorage | undefined,
+	modernKey: string,
+	id: string,
+	panelIds: readonly string[] | undefined,
+): string | null {
+	const modernString = readStorageItem(storage, modernKey);
+	if (readModernLayout(modernString)) return modernString;
+	if (!storage) return null;
+	try {
+		const legacy = readLegacyLayout({ id, panelIds, storage });
+		return legacy ? JSON.stringify(legacy) : null;
+	} catch {
+		return null;
+	}
+}
+
+function readModernLayout(value: string | null): Layout | undefined {
+	if (!value) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(value);
+		if (
+			parsed !== null &&
+			typeof parsed === 'object' &&
+			!Array.isArray(parsed) &&
+			Object.values(parsed).every((item) => typeof item === 'number')
+		) {
+			return parsed as Layout;
+		}
+	} catch {
+		// Malformed modern records fall through to the legacy reader.
+	}
+	return undefined;
+}

package/src/components/group/useGroupCallbackRef.ts

@@ -0,0 +1,6 @@
+import { useState } from 'octane';
+import type { GroupImperativeHandle } from './types';
+
+export function useGroupCallbackRef(slot?: symbol) {
+	return useState<GroupImperativeHandle | null>(null, slot);
+}

package/src/components/group/useGroupContext.ts

@@ -0,0 +1,12 @@
+import { useContext } from 'octane';
+import { GroupContext } from './GroupContext';
+
+export function useGroupContext(_slot?: symbol) {
+	const value = useContext(GroupContext);
+	if (value === null) {
+		throw new Error(
+			'Group Context not found; did you render a Panel or Separator outside of a Group?',
+		);
+	}
+	return value;
+}

package/src/components/group/useGroupImperativeHandle.ts

@@ -0,0 +1,46 @@
+import { useRef } from 'octane';
+import { IDENTITY_FUNCTION } from '../../constants';
+import { getImperativeGroupMethods } from '../../global/utils/getImperativeGroupMethods';
+import { subSlot } from '../../internal';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect';
+import type { GroupImperativeHandle, GroupProps } from './types';
+
+export function useGroupImperativeHandle(
+	groupId: string,
+	groupRef: GroupProps['groupRef'],
+	slot?: symbol,
+) {
+	const imperativeGroupRef = useRef<GroupImperativeHandle>(
+		{
+			getLayout: () => ({}),
+			setLayout: IDENTITY_FUNCTION,
+		},
+		subSlot(slot, 'ref'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			Object.assign(imperativeGroupRef.current, getImperativeGroupMethods({ groupId }));
+			assignRef(groupRef, imperativeGroupRef.current);
+			return () => assignRef(groupRef, null);
+		},
+		[groupId, groupRef],
+		subSlot(slot, 'effect'),
+	);
+}
+
+function assignRef(ref: GroupProps['groupRef'], value: GroupImperativeHandle | null): void {
+	if (isRefArray(ref)) {
+		for (const nested of ref) assignRef(nested, value);
+	} else if (typeof ref === 'function') {
+		(ref as (next: GroupImperativeHandle | null) => void)(value);
+	} else if (ref) {
+		(ref as { current: GroupImperativeHandle | null }).current = value;
+	}
+}
+
+function isRefArray(
+	ref: GroupProps['groupRef'],
+): ref is readonly NonNullable<GroupProps['groupRef']>[] {
+	return Array.isArray(ref);
+}

package/src/components/group/useGroupRef.ts

@@ -0,0 +1,6 @@
+import { useRef } from 'octane';
+import type { GroupImperativeHandle } from './types';
+
+export function useGroupRef(slot?: symbol) {
+	return useRef<GroupImperativeHandle | null>(null, slot);
+}

package/src/components/panel/Panel.tsrx

@@ -0,0 +1,130 @@
+import { useEffect, useRef, useSyncExternalStore } from 'octane';
+import { subscribeToMountedGroup } from '../../global/mutable-state/groups';
+import { useId } from '../../hooks/useId';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useStableObject } from '../../hooks/useStableObject';
+import { useGroupContext } from '../group/useGroupContext';
+import type { PanelProps, PanelSize, RegisteredPanel } from './types';
+import { usePanelImperativeHandle } from './usePanelImperativeHandle';
+
+export function Panel(props: PanelProps) @{
+	const {
+		children,
+		className,
+		collapsedSize = '0%',
+		collapsible = false,
+		defaultSize,
+		disabled,
+		elementRef: elementRefProp,
+		groupResizeBehavior = 'preserve-relative-size',
+		id: idProp,
+		maxSize = '100%',
+		minSize = '0%',
+		onResize: onResizeUnstable,
+		panelRef,
+		style,
+		...rest
+	} = props;
+	const idIsStable = !!idProp;
+	const id = useId(idProp);
+	const stableProps = useStableObject({ disabled });
+	const elementRef = useRef<HTMLDivElement | null>(null);
+	const mergedRef = useMergedRefs(elementRef, elementRefProp);
+	const { getPanelStyles, id: groupId, orientation, registerPanel, updatePanelProps } =
+		useGroupContext();
+	const hasOnResize = onResizeUnstable != null;
+	const onResizeStable = useStableCallback((
+		panelSize: PanelSize,
+		_id: string | number | undefined,
+		prevPanelSize: PanelSize | undefined,
+	) => {
+		onResizeUnstable?.(panelSize, idProp, prevPanelSize);
+	});
+
+	useIsomorphicLayoutEffect(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		const registeredPanel: RegisteredPanel = {
+			element,
+			id,
+			idIsStable,
+			mutableValues: { expandToSize: undefined, prevSize: undefined },
+			onResize: hasOnResize ? onResizeStable : undefined,
+			panelConstraints: {
+				groupResizeBehavior,
+				collapsedSize,
+				collapsible,
+				defaultSize,
+				disabled: stableProps.disabled,
+				maxSize,
+				minSize,
+			},
+		};
+		return registerPanel(registeredPanel);
+	}, [groupResizeBehavior, collapsedSize, collapsible, defaultSize, hasOnResize, id, idIsStable, maxSize, minSize, onResizeStable, registerPanel, stableProps]);
+
+	useEffect(() => updatePanelProps(id, { disabled }), [disabled, id, updatePanelProps]);
+	usePanelImperativeHandle(id, panelRef);
+
+	const read = () => {
+		const panelStyles = getPanelStyles(groupId, id);
+		return panelStyles === undefined ? undefined : JSON.stringify(panelStyles);
+	};
+	const panelStylesString = useSyncExternalStore(
+		(subscribe) => subscribeToMountedGroup(groupId, () => subscribe()),
+		read,
+		read,
+	);
+	const panelStyles =
+		panelStylesString
+			? JSON.parse(panelStylesString) as Record<string, unknown>
+			: defaultSize !== undefined
+				? { flexGrow: undefined, flexShrink: undefined, flexBasis: defaultSize }
+				: { flexGrow: 1 };
+
+	return <div
+		{...rest}
+		data-disabled={disabled || undefined}
+		data-panel
+		data-testid={id}
+		id={id}
+		ref={mergedRef}
+		style={{
+			...PROHIBITED_CSS_PROPERTIES,
+			display: 'flex',
+			flexBasis: 0,
+			flexShrink: 1,
+			overflow: 'visible',
+			...panelStyles,
+		}}
+	>
+		<div
+			className={className}
+			style={{
+				maxHeight: '100%',
+				maxWidth: '100%',
+				flexGrow: 1,
+				overflow: 'auto',
+				...style,
+				touchAction: orientation === 'horizontal' ? 'pan-y' : 'pan-x',
+			}}
+		>{children}</div>
+	</div>;
+}
+
+(Panel as { displayName?: string }).displayName = 'Panel';
+
+const PROHIBITED_CSS_PROPERTIES = {
+	minHeight: 0,
+	maxHeight: '100%',
+	height: 'auto',
+	minWidth: 0,
+	maxWidth: '100%',
+	width: 'auto',
+	border: 'none',
+	borderWidth: 0,
+	padding: 0,
+	margin: 0,
+} as const;

package/src/components/panel/types.ts

@@ -0,0 +1,66 @@
+import type { OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+export type PanelSize = { asPercentage: number; inPixels: number };
+export type GroupResizeBehavior = 'preserve-relative-size' | 'preserve-pixel-size';
+export type SizeUnit = 'px' | '%' | 'em' | 'rem' | 'vh' | 'vw';
+export type PanelConstraintProps = {
+	collapsedSize?: number | string;
+	collapsible?: boolean;
+	defaultSize?: number | string;
+	disabled?: boolean;
+	groupResizeBehavior?: GroupResizeBehavior;
+	maxSize?: number | string;
+	minSize?: number | string;
+};
+export type PanelConstraints = {
+	collapsedSize: number;
+	collapsible: boolean;
+	defaultSize: number | undefined;
+	disabled: boolean | undefined;
+	groupResizeBehavior?: GroupResizeBehavior;
+	maxSize: number;
+	minSize: number;
+	panelId: string;
+};
+type PanelResizeCallback = (
+	size: PanelSize,
+	id: string | number | undefined,
+	previousSize: PanelSize | undefined,
+) => void;
+export type RegisteredPanel = {
+	id: string;
+	idIsStable: boolean;
+	element: HTMLDivElement;
+	mutableValues: { expandToSize: number | undefined; prevSize: PanelSize | undefined };
+	onResize: PanelResizeCallback | undefined;
+	panelConstraints: PanelConstraintProps;
+};
+export interface PanelImperativeHandle {
+	collapse(): void;
+	expand(): void;
+	getSize(): PanelSize;
+	isCollapsed(): boolean;
+	resize(size: number | string): void;
+}
+type DivStyle = Exclude<Octane.JSX.IntrinsicElements['div']['style'], string | undefined>;
+type DivProps = Omit<
+	Octane.JSX.IntrinsicElements['div'],
+	'children' | 'id' | 'ref' | 'onResize' | 'style'
+>;
+export type PanelProps = DivProps & {
+	children?: OctaneNode;
+	collapsedSize?: number | string;
+	collapsible?: boolean;
+	defaultSize?: number | string;
+	disabled?: boolean;
+	elementRef?: Octane.Ref<HTMLDivElement | null>;
+	groupResizeBehavior?: GroupResizeBehavior;
+	id?: string | number;
+	maxSize?: number | string;
+	minSize?: number | string;
+	onResize?: PanelResizeCallback;
+	panelRef?: Octane.Ref<PanelImperativeHandle | null>;
+	style?: DivStyle;
+};
+export type OnPanelResize = PanelProps['onResize'];

package/src/components/panel/usePanelCallbackRef.ts

@@ -0,0 +1,6 @@
+import { useState } from 'octane';
+import type { PanelImperativeHandle } from './types';
+
+export function usePanelCallbackRef(slot?: symbol) {
+	return useState<PanelImperativeHandle | null>(null, slot);
+}

package/src/components/panel/usePanelImperativeHandle.ts

@@ -0,0 +1,42 @@
+import { useImperativeHandle, useRef } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+import { subSlot } from '../../internal';
+import { getImperativePanelMethods } from '../../global/utils/getImperativePanelMethods';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { useGroupContext } from '../group/useGroupContext';
+import type { PanelImperativeHandle } from './types';
+
+const noop = () => {};
+
+export function usePanelImperativeHandle(
+	panelId: string,
+	panelRef: Octane.Ref<PanelImperativeHandle | null> | undefined,
+	slot?: symbol,
+) {
+	const { id: groupId } = useGroupContext();
+	const imperativePanelRef = useRef<PanelImperativeHandle>(
+		{
+			collapse: noop,
+			expand: noop,
+			getSize: () => ({ asPercentage: 0, inPixels: 0 }),
+			isCollapsed: () => false,
+			resize: noop,
+		},
+		subSlot(slot, 'ref'),
+	);
+	const mergedPanelRef = useMergedRefs(panelRef, subSlot(slot, 'merged-ref'));
+	useImperativeHandle(
+		mergedPanelRef,
+		() => imperativePanelRef.current,
+		[],
+		subSlot(slot, 'handle'),
+	);
+	useIsomorphicLayoutEffect(
+		() => {
+			Object.assign(imperativePanelRef.current, getImperativePanelMethods({ groupId, panelId }));
+		},
+		[groupId, panelId],
+		subSlot(slot, 'effect'),
+	);
+}

package/src/components/panel/usePanelRef.ts

@@ -0,0 +1,6 @@
+import { useRef } from 'octane';
+import type { PanelImperativeHandle } from './types';
+
+export function usePanelRef(slot?: symbol) {
+	return useRef<PanelImperativeHandle | null>(null, slot);
+}

package/src/components/separator/Separator.tsrx

@@ -0,0 +1,126 @@
+import { useEffect, useRef, useState } from 'octane';
+import { subscribeToMountedGroup } from '../../global/mutable-state/groups';
+import { subscribeToInteractionState } from '../../global/mutable-state/interactions';
+import type { InteractionState } from '../../global/mutable-state/types';
+import { calculateSeparatorAriaValues } from '../../global/utils/calculateSeparatorAriaValues';
+import { useId } from '../../hooks/useId';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { useStableObject } from '../../hooks/useStableObject';
+import { useGroupContext } from '../group/useGroupContext';
+import type { RegisteredSeparator, SeparatorProps } from './types';
+
+type SeparatorAria = {
+	valueControls?: string;
+	valueMin?: number;
+	valueMax?: number;
+	valueNow?: number;
+};
+
+export function Separator(props: SeparatorProps) @{
+	const {
+		children,
+		className,
+		disabled,
+		disableDoubleClick,
+		elementRef: elementRefProp,
+		id: idProp,
+		style,
+		...rest
+	} = props;
+	const id = useId(idProp);
+	const stableProps = useStableObject({ disabled, disableDoubleClick });
+	const [aria, setAria] = useState<SeparatorAria>({});
+	const [dragState, setDragState] = useState<InteractionState['state']>('inactive');
+	const [isFocused, setIsFocused] = useState(false);
+	const elementRef = useRef<HTMLDivElement | null>(null);
+	const mergedRef = useMergedRefs(elementRef, elementRefProp);
+	const {
+		disableCursor,
+		id: groupId,
+		orientation: groupOrientation,
+		registerSeparator,
+		updateSeparatorProps,
+	} = useGroupContext();
+	const orientation =
+		groupOrientation === 'horizontal' ? 'vertical' : 'horizontal';
+
+	useIsomorphicLayoutEffect(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		const separator: RegisteredSeparator = {
+			disabled: stableProps.disabled,
+			disableDoubleClick: stableProps.disableDoubleClick,
+			element,
+			id,
+		};
+		const unregisterSeparator = registerSeparator(separator);
+		const removeInteractionListener = subscribeToInteractionState((event) => {
+			setDragState(
+				event.next.state !== 'inactive' &&
+				event.next.hitRegions.some((region) => region.separator === separator)
+					? event.next.state
+					: 'inactive',
+			);
+		});
+		const removeGroupListener = subscribeToMountedGroup(groupId, (event) => {
+			const { derivedPanelConstraints, layout, separatorToPanels } = event.next;
+			const panels = separatorToPanels.get(separator);
+			if (!panels) return;
+			const primaryPanel = panels[0];
+			if (!primaryPanel) return;
+			setAria(
+				calculateSeparatorAriaValues({
+					layout,
+					panelConstraints: derivedPanelConstraints,
+					panelId: primaryPanel.id,
+					panelIndex: panels.indexOf(primaryPanel),
+				}),
+			);
+		});
+		return () => {
+			removeInteractionListener();
+			removeGroupListener();
+			unregisterSeparator();
+		};
+	}, [groupId, id, registerSeparator, stableProps]);
+
+	useEffect(() => updateSeparatorProps(id, { disabled, disableDoubleClick }), [
+		disabled,
+		disableDoubleClick,
+		id,
+		updateSeparatorProps,
+	]);
+	const cursor =
+		disabled && !disableCursor ? 'not-allowed' : undefined;
+	const dataSeparator =
+		disabled
+			? 'disabled'
+			: dragState === 'active'
+				? 'active'
+				: isFocused
+					? 'focus'
+					: dragState;
+
+	return <div
+		{...rest}
+		aria-controls={aria.valueControls}
+		aria-disabled={disabled || undefined}
+		aria-orientation={orientation}
+		aria-valuemax={aria.valueMax}
+		aria-valuemin={aria.valueMin}
+		aria-valuenow={aria.valueNow}
+		className={className}
+		data-separator={dataSeparator}
+		data-testid={id}
+		id={id}
+		onBlur={() => setIsFocused(false)}
+		onFocus={() => setIsFocused(true)}
+		ref={mergedRef}
+		role="separator"
+		style={{ flexBasis: 'auto', cursor, ...style, flexGrow: 0, flexShrink: 0, touchAction: 'none' }}
+		tabIndex={disabled ? undefined : 0}
+	>{children}</div>;
+}
+
+(Separator as { displayName?: string }).displayName = 'Separator';

package/src/components/separator/types.ts

@@ -0,0 +1,22 @@
+import type { OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+type DivStyle = Exclude<Octane.JSX.IntrinsicElements['div']['style'], string | undefined>;
+type DivProps = Omit<
+	Octane.JSX.IntrinsicElements['div'],
+	'children' | 'id' | 'ref' | 'role' | 'tabIndex' | 'style'
+>;
+export type SeparatorProps = DivProps & {
+	children?: OctaneNode;
+	disabled?: boolean;
+	disableDoubleClick?: boolean;
+	elementRef?: Octane.Ref<HTMLDivElement | null>;
+	id?: string | number;
+	style?: DivStyle;
+};
+export type RegisteredSeparator = {
+	disabled?: boolean;
+	disableDoubleClick?: boolean;
+	element: HTMLDivElement;
+	id: string;
+};

package/src/constants.ts

@@ -0,0 +1,25 @@
+// Constants used for memoization
+export const EMPTY_ARRAY: unknown[] = [];
+export const EMPTY_DOM_RECT: DOMRectReadOnly = {
+	bottom: 0,
+	height: 0,
+	left: 0,
+	right: 0,
+	toJSON: () => {},
+	top: 0,
+	width: 0,
+	x: 0,
+	y: 0,
+};
+export const EMPTY_OBJECT = {};
+export const EMPTY_POINT = { x: 0, y: 0 };
+export const IDENTITY_FUNCTION = <Value>(value: Value) => value;
+export const NOOP_FUNCTION = () => {};
+
+// Cursor flags
+export const CURSOR_FLAG_HORIZONTAL_MIN = 0b0001;
+export const CURSOR_FLAG_HORIZONTAL_MAX = 0b0010;
+export const CURSOR_FLAG_VERTICAL_MIN = 0b0100;
+export const CURSOR_FLAG_VERTICAL_MAX = 0b1000;
+export const CURSOR_FLAGS_HORIZONTAL = 0b0011;
+export const CURSOR_FLAGS_VERTICAL = 0b1100;