@octanejs/resizable-panels 0.0.1

package/LICENSE.upstream

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Brian Vaughn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @octanejs/resizable-panels
+
+Octane binding for `react-resizable-panels@4.12.2`.
+
+Install `@octanejs/resizable-panels` and replace the React package import;
+the public `Group`, `Panel`, `Separator`, persistence hooks, refs, and imperative
+handles retain the pinned upstream contract.
+
+```tsrx
+import { Group, Panel, Separator } from '@octanejs/resizable-panels';
+
+export function Workspace() @{
+	<Group defaultLayout={{ navigation: 25, content: 75 }}>
+		<Panel id="navigation" minSize="15%">Navigation</Panel>
+		<Separator aria-label="Resize navigation" />
+		<Panel id="content">Content</Panel>
+	</Group>
+}
+```
+
+See [`UPSTREAM.md`](./UPSTREAM.md) for pinned provenance and executable parity
+evidence.

package/UPSTREAM.md

@@ -0,0 +1,64 @@
+# react-resizable-panels upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `react-resizable-panels` |
+| Version | `4.12.2` |
+| Canonical repository | `https://github.com/bvaughn/react-resizable-panels.git` |
+| Canonical tag commit | `a1eeb7aefdb024bb5879a323218e0ac05f77f28e` |
+| Supported upstream range | exactly `4.12.2` |
+| npm tarball SHA-256 | `099742808fafbe3a0288d758271aaf1c35dc9b66ec85077e60f0861e58e89e61` |
+| License | MIT, copyright Brian Vaughn |
+
+`upstream/` contains the byte-exact canonical `lib/` source and tests plus
+the package, TypeScript, and Vitest metadata needed to execute them.
+`upstream-artifact/` contains the complete unpacked npm publication artifact. Both
+boundaries are development evidence and excluded from the published `files`.
+`audit/upstream.lock.json` pins every committed Git-sourced byte to the canonical
+commit's Git blob identity; registry-only artifact bytes remain separately
+hash-checked by the package verifier.
+
+The adapted suite under `tests/upstream/` is regenerated from the lock's
+mechanical rewrites plus minimal patches in `audit/upstream-patches/`; it is not
+committed.
+
+Run `pnpm --dir packages/resizable-panels upstream:verify` to reject a
+modified, missing, or extra vendored file and drift in the export, type, or test
+inventories. The verifier's negative-control mode proves each fail-closed path.
+
+## Public runtime export crosswalk
+
+The binding exports the exact pinned runtime set: `Group`, `Panel`, `Separator`,
+`isCoarsePointer`, `useDefaultLayout`, `useGroupCallbackRef`, `useGroupRef`,
+`usePanelCallbackRef`, and `usePanelRef`. Their authoritative source modules and
+exact names are recorded in `audit/public-api.json`.
+
+## Public type crosswalk
+
+All 13 public types are implemented and checked against the pinned declaration:
+`GroupImperativeHandle`, `GroupProps`, `Layout`, `LayoutChangedMeta`,
+`LayoutStorage`, `OnGroupLayoutChange`, `Orientation`, `OnPanelResize`,
+`PanelImperativeHandle`, `PanelProps`, `PanelSize`, `SizeUnit`, and
+`SeparatorProps`.
+
+The npm declaration imports React's node, intrinsic attribute, CSS, ref,
+dispatch/set-state, and JSX result types. `audit/type-expressibility.json` and
+`audit/type-probes/` preserve equal strictness by deriving host attributes, CSS,
+events, and refs from Octane's existing strict JSX intrinsic surface. Octane's
+type declarations intentionally derive that surface from React types, and
+`@types/react` is a normal dependency of `octane`; this type-only lineage is
+acceptable. The binding itself has no React runtime dependency and no required
+React or ReactDOM peer. It must not replace the intrinsic surface with a
+hand-written or `any`-based map.
+
+## Upstream test disposition
+
+The canonical `lib/` tree contains the exact 29 test artifacts and 329 literal
+registrations enumerated in `audit/test-inventory.json`. Every artifact is
+adapted and executable; parameter matrices expand the adapted lane beyond the
+literal registration count. Port-authored differential, persistence, SSR,
+hydration, type, and real-browser evidence is inventoried separately. Negative
+controls reject missing or renamed tests, stale classifications, and API or
+provenance drift.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@octanejs/resizable-panels",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "Octane port of react-resizable-panels 4.12.2.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/resizable-panels"
+  },
+  "main": "src/index.tsrx",
+  "module": "src/index.tsrx",
+  "types": "src/index.tsrx",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "status.json",
+    "LICENSE.upstream"
+  ],
+  "exports": {
+    ".": "./src/index.tsrx"
+  },
+  "peerDependencies": {
+    "octane": "0.1.43"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@tsrx/react": "^0.2.58",
+    "jsdom": "26.1.0",
+    "playwright": "^1.61.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-resizable-panels": "4.12.2",
+    "vite": "^8.1.5",
+    "vitest": "3.2.4",
+    "vitest-fail-on-console": "^0.10.1",
+    "@octanejs/testing-library": "0.1.40",
+    "octane": "0.1.43"
+  },
+  "scripts": {
+    "test": "pnpm upstream:materialize && vitest run --root ../.. --project resizable-panels && vitest run --root ../.. --project resizable-panels-server && pnpm test:upstream && vitest run --root ../.. --project resizable-panels-browser",
+    "test:upstream": "vitest run --config vitest.pristine.config.ts",
+    "upstream:materialize": "node ../../scripts/react-port/materialize.mjs run --package-dir .",
+    "upstream:verify": "node ../../scripts/react-parity/verify-provenance.mjs && node audit/verify-provenance.mjs",
+    "upstream:verify:negative-controls": "node audit/verify-provenance.mjs --negative-controls",
+    "typecheck:probes": "tsc --noEmit -p audit/type-probes/tsconfig.pristine.json && tsrx-tsc --noEmit -p typetests/tsconfig.json",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/components/group/Group.tsrx

@@ -0,0 +1,244 @@
+import { useEffect, useMemo, useRef } from 'octane';
+import { calculatePanelConstraints } from '../../global/dom/calculatePanelConstraints';
+import { mountGroup } from '../../global/mountGroup';
+import {
+	getMountedGroupState,
+	getRegisteredGroup,
+	subscribeToMountedGroup,
+	updateMountedGroup,
+} from '../../global/mutable-state/groups';
+import { getInteractionState } from '../../global/mutable-state/interactions';
+import { layoutNumbersEqual } from '../../global/utils/layoutNumbersEqual';
+import { layoutsEqual } from '../../global/utils/layoutsEqual';
+import { useForceUpdate } from '../../hooks/useForceUpdate';
+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 type { RegisteredPanel } from '../panel/types';
+import type { RegisteredSeparator } from '../separator/types';
+import { GroupContext, type GroupContextValue } from './GroupContext';
+import { sortByElementOffset } from './sortByElementOffset';
+import type { GroupProps, Layout, RegisteredGroup, ResizeTargetMinimumSize } from './types';
+import { useGroupImperativeHandle } from './useGroupImperativeHandle';
+
+export function Group(props: GroupProps) @{
+	const {
+		children,
+		className,
+		defaultLayout,
+		disableCursor,
+		disabled,
+		elementRef: elementRefProp,
+		groupRef,
+		id: idProp,
+		onLayoutChange: onLayoutChangeUnstable,
+		onLayoutChanged: onLayoutChangedUnstable,
+		orientation = 'horizontal',
+		resizeTargetMinimumSize = { coarse: 20, fine: 10 },
+		style,
+		...rest
+	} = props;
+	const previousLayouts = useRef({ onLayoutChange: {} as Layout, onLayoutChanged: {} as Layout });
+	const onLayoutChange = useStableCallback((layout: Layout) => {
+		if (layoutsEqual(previousLayouts.current.onLayoutChange, layout)) return;
+		previousLayouts.current.onLayoutChange = layout;
+		onLayoutChangeUnstable?.(layout);
+	});
+	const onLayoutChanged = useStableCallback((layout: Layout, isUserInteraction: boolean) => {
+		if (layoutsEqual(previousLayouts.current.onLayoutChanged, layout)) return;
+		previousLayouts.current.onLayoutChanged = layout;
+		onLayoutChangedUnstable?.(layout, { isUserInteraction });
+	});
+
+	const id = useId(idProp);
+	const elementRef = useRef<HTMLDivElement | null>(null);
+	const [panelOrSeparatorChangeSigil, forceUpdate] = useForceUpdate();
+	const valuesRef = useRef<{
+		lastExpandedPanelSizes: Record<string, number>;
+		layouts: Record<string, Layout>;
+		panels: RegisteredPanel[];
+		resizeTargetMinimumSize: ResizeTargetMinimumSize;
+		separators: RegisteredSeparator[];
+	}>({
+		lastExpandedPanelSizes: {},
+		layouts: {},
+		panels: [],
+		resizeTargetMinimumSize,
+		separators: [],
+	});
+	valuesRef.current.resizeTargetMinimumSize = resizeTargetMinimumSize;
+	const mergedRef = useMergedRefs(elementRef, elementRefProp);
+	useGroupImperativeHandle(id, groupRef);
+
+	const getPanelStyles = useStableCallback((groupId: string, panelId: string) => {
+		const interaction = getInteractionState();
+		const group = getRegisteredGroup(groupId);
+		const state = getMountedGroupState(groupId);
+		if (state) {
+			const dragActive =
+				interaction.state === 'active' &&
+					interaction.hitRegions.some((region) => region.group === group);
+			return {
+				flexGrow: state.layout[panelId] ?? 1,
+				pointerEvents: dragActive ? 'none' as const : undefined,
+			};
+		}
+		const initialSize = defaultLayout?.[panelId];
+		return initialSize === undefined ? undefined : { flexGrow: initialSize };
+	});
+	const stableProps = useStableObject({ defaultLayout, disableCursor });
+	const context = useMemo<GroupContextValue>(
+		() => ({
+			get disableCursor() {
+				return !!stableProps.disableCursor;
+			},
+			getPanelStyles,
+			id,
+			orientation,
+			registerPanel(panel) {
+				valuesRef.current.panels = sortByElementOffset(orientation, [
+					...valuesRef.current.panels,
+					panel,
+				]);
+				forceUpdate();
+				return () => {
+					valuesRef.current.panels = valuesRef.current.panels.filter(
+						(current) => current !== panel,
+					);
+					forceUpdate();
+				};
+			},
+			registerSeparator(separator) {
+				valuesRef.current.separators = sortByElementOffset(orientation, [
+					...valuesRef.current.separators,
+					separator,
+				]);
+				forceUpdate();
+				return () => {
+					valuesRef.current.separators = valuesRef.current.separators.filter(
+						(current) => current !== separator,
+					);
+					forceUpdate();
+				};
+			},
+			updatePanelProps(panelId, next) {
+				const panel = valuesRef.current.panels.find((current) => current.id === panelId);
+				if (panel) panel.panelConstraints.disabled = next.disabled;
+				const group = getRegisteredGroup(id);
+				const state = getMountedGroupState(id);
+				if (group && state) updateMountedGroup(group, {
+					...state,
+					derivedPanelConstraints: calculatePanelConstraints(group),
+				});
+			},
+			updateSeparatorProps(separatorId, next) {
+				const separator = valuesRef.current.separators.find(
+					(current) => current.id === separatorId,
+				);
+				if (separator) Object.assign(separator, next);
+			},
+		}),
+		[forceUpdate, getPanelStyles, id, orientation, stableProps],
+	);
+
+	const registeredGroupRef = useRef<RegisteredGroup | null>(null);
+	useIsomorphicLayoutEffect(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		const values = valuesRef.current;
+		let sortedDefaultLayout: Layout | undefined;
+		if (
+			stableProps.defaultLayout &&
+				Object.keys(stableProps.defaultLayout).length === values.panels.length
+		) {
+			sortedDefaultLayout = {};
+			for (const panel of values.panels) {
+				const size = stableProps.defaultLayout[panel.id];
+				if (size !== undefined) sortedDefaultLayout[panel.id] = size;
+			}
+		}
+		const group: RegisteredGroup = {
+			disabled: !!disabled,
+			element,
+			id,
+			mutableState: {
+				defaultLayout: sortedDefaultLayout,
+				disableCursor: !!stableProps.disableCursor,
+				expandedPanelSizes: values.lastExpandedPanelSizes,
+				layouts: values.layouts,
+			},
+			orientation,
+			panels: values.panels,
+			resizeTargetMinimumSize: values.resizeTargetMinimumSize,
+			separators: values.separators,
+		};
+		registeredGroupRef.current = group;
+		const unmount = mountGroup(group);
+		const initial = getMountedGroupState(id, true);
+		if (!initial.defaultLayoutDeferred && initial.derivedPanelConstraints.length > 0) {
+			onLayoutChange(initial.layout);
+			onLayoutChanged(initial.layout, false);
+		}
+		const unsubscribe = subscribeToMountedGroup(id, (event) => {
+			const { defaultLayoutDeferred, derivedPanelConstraints, layout } = event.next;
+			if (defaultLayoutDeferred || derivedPanelConstraints.length === 0) return;
+			const panelIdsKey = group.panels.map((panel) => panel.id).join(',');
+			group.mutableState.layouts[panelIdsKey] = layout;
+			for (const constraints of derivedPanelConstraints) {
+				const previousLayout = event.prev?.layout;
+				if (
+					constraints.collapsible && previousLayout &&
+						layoutNumbersEqual(constraints.collapsedSize, layout[constraints.panelId]) &&
+						!layoutNumbersEqual(constraints.collapsedSize, previousLayout[constraints.panelId])
+				) {
+					group.mutableState.expandedPanelSizes[constraints.panelId] =
+						previousLayout[constraints.panelId];
+				}
+			}
+			onLayoutChange(layout);
+			if (getInteractionState().state !== 'active') onLayoutChanged(
+				layout,
+				event.isUserInteraction,
+			);
+		});
+		return () => {
+			registeredGroupRef.current = null;
+			unmount();
+			unsubscribe();
+		};
+	}, [disabled, id, onLayoutChange, onLayoutChanged, orientation, panelOrSeparatorChangeSigil, stableProps]);
+
+	// Match upstream: prop updates only refresh mutable state; they do not reapply
+	// defaultLayout via setLayout (React leaves the live layout alone).
+	useEffect(() => {
+		const group = registeredGroupRef.current;
+		if (!group) return;
+		group.mutableState.defaultLayout = defaultLayout;
+		group.mutableState.disableCursor = !!disableCursor;
+	}, [defaultLayout, disableCursor]);
+
+	return <GroupContext.Provider value={context}>
+		<div
+			{...rest}
+			className={className}
+			data-group
+			data-testid={id}
+			id={id}
+			ref={mergedRef}
+			style={{
+				height: '100%',
+				width: '100%',
+				overflow: 'hidden',
+				...style,
+				display: 'flex',
+				flexDirection: orientation === 'horizontal' ? 'row' : 'column',
+				flexWrap: 'nowrap',
+				touchAction: orientation === 'horizontal' ? 'pan-y' : 'pan-x',
+			}}
+		>{children}</div>
+	</GroupContext.Provider>;
+}
+
+(Group as { displayName?: string }).displayName = 'Group';

package/src/components/group/GroupContext.ts

@@ -0,0 +1,25 @@
+import { createContext } from 'octane';
+import type { RegisteredPanel } from '../panel/types';
+import type { RegisteredSeparator } from '../separator/types';
+import type { Orientation } from './types';
+
+export type PanelStyles = {
+	flexGrow?: number;
+	pointerEvents?: 'none';
+};
+
+export type GroupContextValue = {
+	disableCursor: boolean;
+	getPanelStyles(groupId: string, panelId: string): PanelStyles | undefined;
+	id: string;
+	orientation: Orientation;
+	registerPanel(panel: RegisteredPanel): () => void;
+	registerSeparator(separator: RegisteredSeparator): () => void;
+	updatePanelProps(id: string, props: { disabled: boolean | undefined }): void;
+	updateSeparatorProps(
+		id: string,
+		props: { disabled: boolean | undefined; disableDoubleClick: boolean | undefined },
+	): void;
+};
+
+export const GroupContext = createContext<GroupContextValue | null>(null);

package/src/components/group/auto-save/getStorageKey.ts

@@ -0,0 +1,3 @@
+export function getStorageKey(id: string, panelIds: readonly string[]): string {
+	return `react-resizable-panels:${[id, ...panelIds].join(':')}`;
+}

package/src/components/group/auto-save/readLegacyLayout.ts

@@ -0,0 +1,37 @@
+import type { Layout, LayoutStorage } from '../types';
+import { getStorageKey } from './getStorageKey';
+
+type LegacyLayout = Record<string, { expandToSizes: unknown; layout: number[] }>;
+
+export function readLegacyLayout({
+	id,
+	panelIds,
+	storage,
+}: {
+	id: string;
+	panelIds?: readonly string[];
+	storage: LayoutStorage;
+}): Layout | undefined {
+	const value = storage.getItem(getStorageKey(id, []));
+	if (!value) return undefined;
+
+	try {
+		const legacy = JSON.parse(value) as LegacyLayout;
+		const ids = panelIds ?? getOnlyLegacyPanelIds(legacy);
+		if (!ids) return undefined;
+
+		const entry = legacy[ids.join(',')];
+		if (!entry || !Array.isArray(entry.layout) || ids.length !== entry.layout.length) {
+			return undefined;
+		}
+
+		return Object.fromEntries(ids.map((panelId, index) => [panelId, entry.layout[index]]));
+	} catch {
+		return undefined;
+	}
+}
+
+function getOnlyLegacyPanelIds(legacy: LegacyLayout): string[] | undefined {
+	const keys = Object.keys(legacy);
+	return keys.length === 1 ? keys[0].split(',') : undefined;
+}

package/src/components/group/sortByElementOffset.ts

@@ -0,0 +1,20 @@
+import type { Orientation } from './types';
+
+export function sortByElementOffset<
+	Type extends { element: HTMLElement },
+	ReturnType extends Type[],
+>(orientation: Orientation, items: Type[]): ReturnType {
+	return Array.from(items).sort(
+		orientation === 'horizontal' ? horizontalSort : verticalSort,
+	) as ReturnType;
+}
+
+function horizontalSort<Type extends { element: HTMLElement }>(a: Type, b: Type) {
+	const delta = a.element.offsetLeft - b.element.offsetLeft;
+	return delta !== 0 ? delta : a.element.offsetWidth - b.element.offsetWidth;
+}
+
+function verticalSort<Type extends { element: HTMLElement }>(a: Type, b: Type) {
+	const delta = a.element.offsetTop - b.element.offsetTop;
+	return delta !== 0 ? delta : a.element.offsetHeight - b.element.offsetHeight;
+}

package/src/components/group/types.ts

@@ -0,0 +1,50 @@
+import type { OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+import type { RegisteredPanel } from '../panel/types';
+import type { RegisteredSeparator } from '../separator/types';
+
+export type Orientation = 'horizontal' | 'vertical';
+export type Layout = Record<string, number>;
+export type LayoutStorage = Pick<Storage, 'getItem' | 'setItem'>;
+export type LayoutChangedMeta = { isUserInteraction: boolean };
+export type ResizeTargetMinimumSize = { coarse: number; fine: number };
+export type RegisteredGroup = Readonly<{
+	disabled: boolean;
+	element: HTMLElement;
+	id: string;
+	mutableState: {
+		defaultLayout: Readonly<Layout> | undefined;
+		disableCursor: boolean;
+		expandedPanelSizes: Record<string, number>;
+		layouts: Record<string, Layout>;
+	};
+	orientation: Orientation;
+	panels: RegisteredPanel[];
+	resizeTargetMinimumSize: ResizeTargetMinimumSize;
+	separators: RegisteredSeparator[];
+}>;
+
+export interface GroupImperativeHandle {
+	getLayout(): Layout;
+	setLayout(layout: Layout): Layout;
+}
+
+type DivStyle = Exclude<Octane.JSX.IntrinsicElements['div']['style'], string | undefined>;
+type DivProps = Omit<Octane.JSX.IntrinsicElements['div'], 'children' | 'id' | 'ref' | 'style'>;
+export type GroupProps = DivProps & {
+	children?: OctaneNode;
+	defaultLayout?: Layout;
+	disableCursor?: boolean;
+	disabled?: boolean;
+	elementRef?: Octane.Ref<HTMLDivElement | null>;
+	groupRef?: Octane.Ref<GroupImperativeHandle | null>;
+	id?: string | number;
+	onLayoutChange?: (layout: Layout) => void;
+	onLayoutChanged?: (layout: Layout, meta: LayoutChangedMeta) => void;
+	orientation?: Orientation;
+	resizeTargetMinimumSize?: ResizeTargetMinimumSize;
+	style?: DivStyle;
+};
+
+export type OnGroupLayoutChange = GroupProps['onLayoutChange'];
+export type OnGroupLayoutChanged = GroupProps['onLayoutChanged'];