chore: cleanup and docs (#1)

Author: huntabyte

.changeset/config.json

@@ -2,7 +2,7 @@
 	"$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
 	"changelog": [
 		"@svitejs/changesets-changelog-github-compact",
-		{ "repo": "huntabyte/paneforge" }
+		{ "repo": "svecosystem/paneforge" }
 	],
 	"commit": false,
 	"fixed": [],

.changeset/old-years-press.md

@@ -0,0 +1,5 @@
+---
+"paneforge": patch
+---
+
+Initial release 🎉

README.md

@@ -1 +1,41 @@
 # Paneforge
+
+PaneForge provides components that make it easy to create resizable panes in your Svelte apps. It's designed to be simple to use, and to work well with other Svelte components and libraries. This project has taken a lot of inspiration and code from the work done by [Bryan Vaughn](https://github.com/bvaughn) and [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels) and seeks to provide a similar experience for Svelte developers.
+
+## Features
+
+-   **Simple API**: PaneForge is designed to be easy to use. It provides a small set of components that can be combined to create complex layouts.
+-   **Resizable Panes**: Panes can be resized by dragging the resizer between them.
+-   **Nested Groups**: Groups of panes can be nested inside other groups to create complex layouts.
+-   **Customizable**: The appearance and behavior of the panes can be customized using CSS and Svelte props.
+-   **Persistent Layouts**: PaneForge can be used with LocalStorage or cookies to persist the layout of the panes between page loads.
+-   **Accessible**: PaneForge is designed to be accessible to all users, including those who use assistive technologies.
+-   **Community-driven**: PaneForge is an open-source project that welcomes contributions from the community. If you have an idea for a new feature or an improvement, we'd love to hear from you!
+
+## Installation
+
+```bash
+npm install paneforge
+```
+
+## Basic Usage
+
+Here's a simple example of how to use Paneforge to create a horizontal pane group with two panes:
+
+```svelte
+<script lang="ts">
+	import { PaneGroup, Pane, PaneResizer } from "paneforge";
+</script>
+
+<PaneGroup direction="horizontal">
+	<Pane defaultSize={50}>Pane 1</Pane>
+	<PaneResizer />
+	<Pane defaultSize={50}>Pane 2</Pane>
+</PaneGroup>
+```
+
+The `PaneGroup` component is used to initialize a pane group, and the `Pane` component is used to create a pane. The `PaneResizer` component is used to create a resizer that can be dragged to resize the panes.
+
+The components ship only with the styles necessary to position the panes in the appropriate layout. The rest of the styling is up to you.
+
+For more information, see the [Documentation](https://paneforge.com).

packages/paneforge/.prettierrc

@@ -3,7 +3,7 @@
 	"singleQuote": false,
 	"trailingComma": "es5",
 	"printWidth": 100,
-	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
+	"plugins": ["prettier-plugin-svelte"],
 	"overrides": [
 		{
 			"files": "*.svelte",

packages/paneforge/README.md

@@ -1,58 +1,41 @@
-# create-svelte
+# Paneforge
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+PaneForge provides components that make it easy to create resizable panes in your Svelte apps. It's designed to be simple to use, and to work well with other Svelte components and libraries. This project has taken a lot of inspiration and code from the work done by [Bryan Vaughn](https://github.com/bvaughn) and [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels) and seeks to provide a similar experience for Svelte developers.
 
-Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
+## Features
 
-## Creating a project
+- **Simple API**: PaneForge is designed to be easy to use. It provides a small set of components that can be combined to create complex layouts.
+- **Resizable Panes**: Panes can be resized by dragging the resizer between them.
+- **Nested Groups**: Groups of panes can be nested inside other groups to create complex layouts.
+- **Customizable**: The appearance and behavior of the panes can be customized using CSS and Svelte props.
+- **Persistent Layouts**: PaneForge can be used with LocalStorage or cookies to persist the layout of the panes between page loads.
+- **Accessible**: PaneForge is designed to be accessible to all users, including those who use assistive technologies.
+- **Community-driven**: PaneForge is an open-source project that welcomes contributions from the community. If you have an idea for a new feature or an improvement, we'd love to hear from you!
 
-If you're seeing this, you've probably already done this step. Congrats!
+## Installation
 
 ```bash
-# create a new project in the current directory
-npm create svelte@latest
-
-# create a new project in my-app
-npm create svelte@latest my-app
+npm install paneforge
 ```
 
-## Developing
+## Basic Usage
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+Here's a simple example of how to use Paneforge to create a horizontal pane group with two panes:
 
-```bash
-npm run dev
+```svelte
+<script lang="ts">
+	import { PaneGroup, Pane, PaneResizer } from "paneforge";
+</script>
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+<PaneGroup direction="horizontal">
+	<Pane defaultSize={50}>Pane 1</Pane>
+	<PaneResizer />
+	<Pane defaultSize={50}>Pane 2</Pane>
+</PaneGroup>
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
-
-## Building
+The `PaneGroup` component is used to initialize a pane group, and the `Pane` component is used to create a pane. The `PaneResizer` component is used to create a resizer that can be dragged to resize the panes.
 
-To build your library:
+The components ship only with the styles necessary to position the panes in the appropriate layout. The rest of the styling is up to you.
 
-```bash
-npm run package
-```
-
-To create a production version of your showcase app:
-
-```bash
-npm run build
-```
-
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
-
-## Publishing
-
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
-
-To publish your library to [npm](https://www.npmjs.com):
-
-```bash
-npm publish
-```
+For more information, see the [Documentation](https://paneforge.com).

packages/paneforge/package.json

@@ -12,10 +12,10 @@
 	},
 	"scripts": {
 		"dev": "pnpm watch",
-		"build": "vite build && npm run package",
+		"build": "pnpm package",
 		"preview": "vite preview",
 		"package": "svelte-kit sync && svelte-package && publint",
-		"prepublishOnly": "npm run package",
+		"prepublishOnly": "pnpm run package",
 		"test": "npm run test:integration && npm run test:unit",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",

packages/paneforge/src/lib/components/index.ts

@@ -1,4 +1,4 @@
 export { default as PaneGroup } from "./pane-group.svelte";
 export { default as Pane } from "./pane.svelte";
-export { default as PaneResizeHandle } from "./pane-resize-handle.svelte";
+export { default as PaneResizer } from "./pane-resizer.svelte";
 export type * from "./types.js";

packages/paneforge/src/lib/components/pane-group.svelte

@@ -14,14 +14,15 @@
 	export let onLayoutChange: PaneGroupOnLayout | null = null;
 	export let storage: PaneGroupStorage = defaultStorage as PaneGroupStorage;
 	export let el: $$Props["el"] = undefined;
-	export let api: $$Props["api"] = undefined;
+	export let paneGroup: $$Props["paneGroup"] = undefined;
 
 	let styleFromProps: $$Props["style"] = undefined;
 	export { styleFromProps as style };
 
 	const {
 		states: { paneGroupStyle, paneGroupSelectors, groupId },
 		methods: { setLayout, getLayout },
+		updateOption,
 	} = setCtx({
 		autoSaveId,
 		direction,
@@ -31,7 +32,14 @@
 		storage,
 	});
 
-	api = {
+	$: updateOption("autoSaveId", autoSaveId);
+	$: updateOption("direction", direction);
+	$: updateOption("id", id);
+	$: updateOption("keyboardResizeBy", keyboardResizeBy);
+	$: updateOption("onLayout", onLayoutChange);
+	$: updateOption("storage", storage);
+
+	paneGroup = {
 		getLayout,
 		setLayout,
 		getId: () => $groupId,

packages/paneforge/src/lib/components/pane-resize-handle.svelte packages/paneforge/src/lib/components/pane-resizer.svelte

@@ -7,10 +7,10 @@
 	import { getCursorStyle, generateId, styleToString } from "$lib/internal/utils/index.js";
 	import { onMount } from "svelte";
 	import { getCtx } from "./ctx.js";
-	import { resizeHandleAction } from "./pane-resize-handle.js";
-	import type { PaneResizeHandleProps, PaneResizeHandleAttributes } from "./types.js";
+	import { resizeHandleAction } from "./pane-resizer.js";
+	import type { PaneResizerProps, PaneResizerAttributes } from "./types.js";
 
-	type $$Props = PaneResizeHandleProps;
+	type $$Props = PaneResizerProps;
 
 	export let disabled: $$Props["disabled"] = false;
 	export let onDraggingChange: $$Props["onDraggingChange"] = undefined;
@@ -25,7 +25,7 @@
 	const {
 		methods: { registerResizeHandle, startDragging, stopDragging },
 		states: { direction, dragState, groupId },
-	} = getCtx("PaneResizeHandle");
+	} = getCtx("PaneResizer");
 
 	const resizeHandleId = generateId(idFromProps);
 	$: isDragging = $dragState?.dragHandleId === resizeHandleId;
@@ -98,12 +98,13 @@
 		}) + styleFromProps ?? "";
 
 	$: attrs = {
-		"data-pane-group-direction": $direction,
+		"data-direction": $direction,
 		"data-pane-group-id": $groupId,
 		"data-active": isDragging ? "pointer" : isFocused ? "keyboard" : undefined,
 		"data-enabled": !disabled,
-		"data-pane-resize-handle-id": resizeHandleId,
-	} satisfies PaneResizeHandleAttributes;
+		"data-pane-resizer-id": resizeHandleId,
+		"data-pane-resizer": "",
+	} satisfies PaneResizerAttributes;
 </script>
 
 <!-- svelte-ignore a11y-no-noninteractive-element-interactions -->

packages/paneforge/src/lib/components/pane-resize-handle.ts packages/paneforge/src/lib/components/pane-resizer.ts

@@ -6,7 +6,7 @@ import type {
 import { chain } from "$lib/internal/utils/chain.js";
 import { addEventListener } from "$lib/internal/utils/event.js";
 
-type ResizeHandleActionParams = {
+type ResizerActionParams = {
 	disabled?: boolean;
 	resizeHandler: ResizeHandler | null;
 	isDragging?: boolean;
@@ -18,9 +18,9 @@ type ResizeHandleActionParams = {
  * A Svelte action that adds resize handle functionality to an element.
  * This action is used to handle the dragging of a resize handle.
  */
-export function resizeHandleAction(node: HTMLElement, params: ResizeHandleActionParams) {
+export function resizeHandleAction(node: HTMLElement, params: ResizerActionParams) {
 	let unsub = () => {};
-	function update(params: ResizeHandleActionParams) {
+	function update(params: ResizerActionParams) {
 		unsub();
 		const { disabled, resizeHandler, isDragging, stopDragging, onDragging = undefined } = params;
 		if (disabled || resizeHandler === null || !isDragging) return;

packages/paneforge/src/lib/components/pane.svelte

@@ -17,7 +17,7 @@
 	export let onResize: $$Props["onResize"] = undefined;
 	export let order: $$Props["order"] = undefined;
 	export let el: $$Props["el"] = undefined;
-	export let api: $$Props["api"] = undefined;
+	export let pane: $$Props["pane"] = undefined;
 
 	let idFromProps: $$Props["id"] = undefined;
 	export { idFromProps as id };
@@ -42,7 +42,9 @@
 
 	const paneId = generateId(idFromProps);
 
-	const paneData: PaneData = {
+	let paneData: PaneData;
+
+	$: paneData = {
 		callbacks: {
 			onCollapse,
 			onExpand,
@@ -60,7 +62,7 @@
 		order,
 	};
 
-	api = {
+	pane = {
 		collapse: () => {
 			collapsePane(paneData);
 		},
@@ -72,18 +74,8 @@
 		getId: () => paneId,
 	};
 
-	let paneHasBeenRegistered = false;
-
-	function handlePaneRegistration(_: number | undefined, __: string) {
-		if (paneHasBeenRegistered) {
-			unregisterPane(paneData);
-		}
-
-		registerPane(paneData);
-	}
-
 	onMount(() => {
-		handlePaneRegistration(order, paneId);
+		registerPane(paneData);
 
 		return () => {
 			unregisterPane(paneData);

packages/paneforge/src/lib/components/types.ts

@@ -77,10 +77,10 @@ export type PaneProps = {
 	 * An imperative API for the pane. `bind` to this prop to get access
 	 * to methods for controlling the pane.
 	 */
-	api?: PaneAPI;
+	pane?: PaneAPI;
 } & Omit<HTMLAttributes<HTMLDivElement>, "id">;
 
-export type PaneResizeHandleProps = {
+export type PaneResizerProps = {
 	/**
 	 * Whether the resize handle is disabled.
 	 *
@@ -155,7 +155,7 @@ export type PaneGroupProps = {
 	 * An imperative API for the pane group. `bind` to this prop to get access
 	 * to methods for controlling the pane group.
 	 */
-	api?: PaneGroupAPI;
+	paneGroup?: PaneGroupAPI;
 } & Omit<HTMLAttributes<HTMLDivElement>, "id">;
 
 export type PaneAPI = {
@@ -201,20 +201,22 @@ export type PaneGroupAttributes = {
 	/** Applied to every pane group element. */
 	"data-pane-group": string;
 	/** The direction of the pane group. */
-	"data-pane-group-direction": Direction;
+	"data-direction": Direction;
 	/** The ID of the pane group. */
 	"data-pane-group-id": string;
 };
 
-export type PaneResizeHandleAttributes = {
-	/** The direction of the pane group the handle belongs to. */
-	"data-pane-group-direction": Direction;
-	/** The ID of the pane group the handle belongs to. */
+export type PaneResizerAttributes = {
+	/** Applied to all resizer elements */
+	"data-pane-resizer": string;
+	/** The direction of the pane group the resize handle belongs to. */
+	"data-direction": Direction;
+	/** The ID of the pane group the resize handle belongs to. */
 	"data-pane-group-id": string;
 	/** Whether the resize handle is active or not. */
 	"data-active"?: "pointer" | "keyboard";
 	/** Whether the resize handle is enabled or not. */
 	"data-enabled"?: boolean;
 	/** The ID of the resize handle. */
-	"data-pane-resize-handle-id": string;
+	"data-pane-resizer-id": string;
 };

packages/paneforge/src/lib/index.ts

@@ -1 +1,4 @@
+import type { PaneGroupStorage } from "$lib/internal/utils/storage.js";
+
 export * from "./components/index.js";
+export type { PaneGroupStorage };