react-split-pane 2.0.3 → 3.0.1

package/README.md

@@ -1,183 +1,490 @@
-# React Split Pane
+# React Split Pane v3
 
-Split-Pane component built with [React](http://facebook.github.io/react), can be split vertically or horizontally.
+Modern, accessible, TypeScript-first split pane component for React.
 
+[![NPM version](https://img.shields.io/npm/v/react-split-pane.svg?style=flat)](https://www.npmjs.com/package/react-split-pane)
+![NPM license](https://img.shields.io/npm/l/react-split-pane.svg?style=flat)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/react-split-pane)](https://bundlephobia.com/package/react-split-pane)
+
+**[Live Examples](https://tomkp.github.io/react-split-pane)**
+
+## ✨ Features
+
+- 🪝 **Hooks-based** - Built with modern React patterns
+- 📘 **TypeScript** - Full type safety out of the box
+- ♿ **Accessible** - Keyboard navigation, ARIA attributes, screen reader support
+- 📱 **Touch-friendly** - Full mobile/tablet support
+- 🎯 **Flexible** - Controlled/uncontrolled modes, nested layouts, 2+ panes
+- 🪶 **Lightweight** - < 5KB gzipped
+- ⚡ **Performant** - RAF-throttled resize, optimized renders
+- 🎨 **Customizable** - Full styling control
+
+## Installation
+
+```bash
+npm install react-split-pane@next
+
+# or
+yarn add react-split-pane@next
+
+# or
+pnpm add react-split-pane@next
 ```
-npm install react-split-pane
+
+## Quick Start
+
+```tsx
+import { SplitPane, Pane } from 'react-split-pane';
+
+function App() {
+  return (
+    <SplitPane direction="horizontal">
+      <Pane minSize="200px" defaultSize="300px">
+        <Sidebar />
+      </Pane>
+      <Pane>
+        <MainContent />
+      </Pane>
+    </SplitPane>
+  );
+}
 ```
 
-[![Build Status](https://img.shields.io/travis/tomkp/react-split-pane/master.svg?style=flat-square)](https://travis-ci.org/tomkp/react-split-pane)
-[![Coverage Status](https://img.shields.io/coveralls/tomkp/react-split-pane/master.svg?style=flat-square)](https://coveralls.io/r/tomkp/react-split-pane)
+## Basic Usage
+
+### Horizontal Split (Side-by-Side)
 
+```tsx
+<SplitPane direction="horizontal">
+  <Pane defaultSize="25%">
+    <LeftPanel />
+  </Pane>
+  <Pane>
+    <RightPanel />
+  </Pane>
+</SplitPane>
+```
+
+### Vertical Split (Top-Bottom)
+
+```tsx
+<SplitPane direction="vertical">
+  <Pane defaultSize="100px">
+    <Header />
+  </Pane>
+  <Pane>
+    <Content />
+  </Pane>
+</SplitPane>
+```
 
-Check out the [demos](http://react-split-pane.surge.sh/)
+### Controlled Mode
 
+```tsx
+function App() {
+  const [sizes, setSizes] = useState([300, 500]);
 
-```html
-   <SplitPane split="vertical" minSize={50} defaultSize={100}>
-       <div></div>
-       <div></div>
-   </SplitPane>
+  return (
+    <SplitPane onResize={setSizes}>
+      <Pane size={sizes[0]} minSize="200px">
+        <Sidebar />
+      </Pane>
+      <Pane size={sizes[1]}>
+        <Main />
+      </Pane>
+    </SplitPane>
+  );
+}
 ```
 
-```html
-    <SplitPane split="vertical" minSize={50}>
-        <div></div>
-        <SplitPane split="horizontal">
-            <div></div>
-            <div></div>
-        </SplitPane>
+### Nested Layouts
+
+```tsx
+<SplitPane direction="vertical">
+  <Pane defaultSize="60px">
+    <Header />
+  </Pane>
+
+  <SplitPane direction="horizontal">
+    <Pane defaultSize="250px" minSize="150px">
+      <Sidebar />
+    </Pane>
+
+    <SplitPane direction="vertical">
+      <Pane>
+        <Editor />
+      </Pane>
+      <Pane defaultSize="200px">
+        <Console />
+      </Pane>
     </SplitPane>
+  </SplitPane>
+</SplitPane>
 ```
 
-### Primary pane
+## Advanced Features
 
-By dragging 'draggable' surface you can change size of the first pane.
-The first pane keeps then its size while the second pane is resized by browser window.
-By default it is the left pane for 'vertical' SplitPane and the top pane for 'horizontal' SplitPane.
-If you want to keep size of the second pane and let the first pane to shrink or grow by browser window dimensions,
-set SplitPane prop `primary` to `second`. In case of 'horizontal' SplitPane the height of bottom pane remains the same.
+### Persistence
 
-Resizing can be disabled by passing the `allowResize` prop as `false` (`allowResize={false}`). Resizing is enabled by default.
+The `usePersistence` hook saves and restores pane sizes to localStorage (or sessionStorage):
 
-You can also set the size of the pane using the `size` prop. Note that a size set through props ignores the `defaultSize` and `minSize` properties.
+```tsx
+import { usePersistence } from 'react-split-pane/persistence';
 
-In this example right pane keeps its width 200px while user is resizing browser window.
+function App() {
+  const [sizes, setSizes] = usePersistence({ key: 'my-layout' });
 
-```html
-    <SplitPane split="vertical" defaultSize={200} primary="second">
-        <div></div>
-        <div></div>
+  return (
+    <SplitPane onResize={setSizes}>
+      <Pane size={sizes[0] || 300}>
+        <Sidebar />
+      </Pane>
+      <Pane size={sizes[1]}>
+        <Main />
+      </Pane>
     </SplitPane>
+  );
+}
 ```
 
-### maxSize
-You can limit the maximal size of the 'fixed' pane using the maxSize parameter with a positive value (measured in pixels but state just a number).
-If you wrap the SplitPane into a container component (yes you can, just remember the container has to have the relative or absolute positioning),
-then you'll need to limit the movement of the splitter (resizer) at the end of the SplitPane (otherwise it can be dragged outside the SplitPane
-and you don't catch it never more). For this purpose use the maxSize parameter with value 0. When dragged the splitter/resizer will stop at the border
-of the SplitPane component and think this you'll be able to pick it again and drag it back then.
-And more: if you set the maxSize to negative value (e.g. -200), then the splitter stops 200px before the border (in other words it sets the minimal
-size of the 'resizable' pane in this case). This can be useful also in the full-screen case of use.
+#### usePersistence Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `key` | `string` | Required | Storage key for persisting sizes |
+| `storage` | `Storage` | `localStorage` | Storage backend (localStorage or sessionStorage) |
+| `debounce` | `number` | `300` | Debounce delay in ms before saving |
+
+```tsx
+// Use sessionStorage instead of localStorage
+const [sizes, setSizes] = usePersistence({
+  key: 'my-layout',
+  storage: sessionStorage,
+  debounce: 500,
+});
+```
 
-### step
-You can use the step prop to only allow resizing in fixed increments.
+### Snap Points
 
-### Persisting Positions
+```tsx
+<SplitPane
+  snapPoints={[200, 400, 600]}
+  snapTolerance={20}
+>
+  {/* panes */}
+</SplitPane>
+```
 
-Each SplitPane accepts an onChange function prop.  Used in conjunction with
-defaultSize and a persistence layer, you can ensure that your splitter choices
-survive a refresh of your app.
+### Custom Divider
 
-For example, if you are comfortable with the trade-offs of localStorage, you
-could do something like the following:
+```tsx
+function CustomDivider(props) {
+  return (
+    <div {...props} style={{ ...props.style, background: 'blue' }}>
+      <GripIcon />
+    </div>
+  );
+}
 
-```html
-    <SplitPane split="vertical" minSize={50}
-               defaultSize={ parseInt(localStorage.getItem('splitPos'), 10) }
-               onChange={ size => localStorage.setItem('splitPos', size) }>
-        <div></div>
-        <div></div>
-    </SplitPane>
+<SplitPane divider={CustomDivider}>
+  {/* panes */}
+</SplitPane>
+```
+
+## Keyboard Navigation
+
+The divider is fully keyboard accessible:
+
+- **Arrow Keys**: Resize by `step` pixels (default: 10px)
+- **Shift + Arrow**: Resize by larger step (default: 50px)
+- **Home**: Minimize left/top pane
+- **End**: Maximize left/top pane
+- **Tab**: Navigate between dividers
+
+## API Reference
+
+### SplitPane Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `resizable` | `boolean` | `true` | Whether panes can be resized |
+| `snapPoints` | `number[]` | `[]` | Snap points in pixels |
+| `snapTolerance` | `number` | `10` | Snap tolerance in pixels |
+| `step` | `number` | `10` | Keyboard resize step |
+| `onResizeStart` | `(event) => void` | - | Called when resize starts |
+| `onResize` | `(sizes, event) => void` | - | Called during resize |
+| `onResizeEnd` | `(sizes, event) => void` | - | Called when resize ends |
+| `className` | `string` | - | CSS class name |
+| `style` | `CSSProperties` | - | Inline styles |
+| `divider` | `ComponentType` | - | Custom divider component |
+| `dividerClassName` | `string` | - | Divider class name |
+| `dividerStyle` | `CSSProperties` | - | Divider inline styles |
+
+### Pane Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultSize` | `string \| number` | `'50%'` | Initial size (uncontrolled) |
+| `size` | `string \| number` | - | Controlled size |
+| `minSize` | `string \| number` | `0` | Minimum size |
+| `maxSize` | `string \| number` | `Infinity` | Maximum size |
+| `className` | `string` | - | CSS class name |
+| `style` | `CSSProperties` | - | Inline styles |
+
+## Styling
+
+### Default Stylesheet
+
+Import the optional default styles with CSS custom properties:
+
+```tsx
+import 'react-split-pane/styles.css';
+```
+
+Customize via CSS variables:
+
+```css
+.my-split-pane {
+  --split-pane-divider-size: 8px;
+  --split-pane-divider-color: #e0e0e0;
+  --split-pane-divider-color-hover: #b0b0b0;
+  --split-pane-focus-color: #2196f3;
+}
+```
+
+The default styles include dark mode support via `prefers-color-scheme`.
+
+### Basic Styles
+
+```css
+.split-pane {
+  height: 100vh;
+}
+
+.split-pane-divider {
+  background: #e0e0e0;
+  transition: background 0.2s;
+}
+
+.split-pane-divider:hover {
+  background: #b0b0b0;
+}
+
+.split-pane-divider:focus {
+  outline: 2px solid #2196f3;
+  outline-offset: -2px;
+}
+```
+
+### Expanded Hover Area
+
+This classic pattern creates a thin visible divider with a larger grabbable area that reveals on hover:
+
+```css
+.split-pane-divider {
+  background: #000;
+  opacity: 0.2;
+  z-index: 1;
+  box-sizing: border-box;
+  background-clip: padding-box;
+}
+
+.split-pane-divider:hover {
+  transition: all 0.2s ease;
+}
+
+.split-pane-divider.horizontal {
+  width: 11px;
+  margin: 0 -5px;
+  border-left: 5px solid rgba(255, 255, 255, 0);
+  border-right: 5px solid rgba(255, 255, 255, 0);
+  cursor: col-resize;
+}
+
+.split-pane-divider.horizontal:hover {
+  border-left: 5px solid rgba(0, 0, 0, 0.5);
+  border-right: 5px solid rgba(0, 0, 0, 0.5);
+}
+
+.split-pane-divider.vertical {
+  height: 11px;
+  margin: -5px 0;
+  border-top: 5px solid rgba(255, 255, 255, 0);
+  border-bottom: 5px solid rgba(255, 255, 255, 0);
+  cursor: row-resize;
+}
+
+.split-pane-divider.vertical:hover {
+  border-top: 5px solid rgba(0, 0, 0, 0.5);
+  border-bottom: 5px solid rgba(0, 0, 0, 0.5);
+}
+```
+
+### Minimal Divider
+
+A subtle single-pixel divider:
+
+```css
+.split-pane-divider.horizontal {
+  width: 1px;
+  margin: 0;
+  background: linear-gradient(to right, transparent, #ccc, transparent);
+}
+
+.split-pane-divider.vertical {
+  height: 1px;
+  margin: 0;
+  background: linear-gradient(to bottom, transparent, #ccc, transparent);
+}
+```
+
+## Tailwind CSS & shadcn/ui
+
+React Split Pane works seamlessly with Tailwind CSS and shadcn/ui. The component uses plain CSS and inline styles (no CSS-in-JS), so there are no conflicts with utility-first frameworks.
+
+### Using Tailwind Classes
+
+Apply Tailwind classes directly via `className` props. Skip importing the default stylesheet for full Tailwind control:
+
+```tsx
+import { SplitPane, Pane } from 'react-split-pane';
+// Don't import 'react-split-pane/styles.css' if using Tailwind
+
+<SplitPane
+  className="h-screen w-full"
+  dividerClassName="bg-gray-200 hover:bg-gray-300 dark:bg-gray-700 dark:hover:bg-gray-600 transition-colors"
+>
+  <Pane defaultSize="300px" className="bg-white dark:bg-gray-900 p-4">
+    <Sidebar />
+  </Pane>
+  <Pane className="bg-gray-50 dark:bg-gray-800 p-4">
+    <MainContent />
+  </Pane>
+</SplitPane>
 ```
 
-Disclaimer: localStorage has a variety of performance trade-offs.  Browsers such
-as Firefox have now optimized localStorage use so that they will asynchronously
-initiate a read of all saved localStorage data for an origin once they know the
-page will load.  If the data has not fully loaded by the time code accesses
-localStorage, the code will cause the page's main thread to block until the
-database load completes.  When the main thread is blocked, no other JS code will
-run or layout will occur.  In multiprocess browsers and for users with fast
-disk storage, this will be less of a problem.  You *are* likely to get yelled at
-if you use localStorage.
+### shadcn/ui Integration
 
-A potentially better idea is to use something like
-https://github.com/mozilla/localForage although hooking it up will be slightly
-more involved.  You are likely to be admired by all for judiciously avoiding
-use of localStorage.
+Use shadcn's CSS variables and utilities for consistent theming:
 
-### Resizing callbacks
+```tsx
+import { SplitPane, Pane } from 'react-split-pane';
 
-If you need more control over resizing, SplitPane can notify you about when resizing started
-and when it ended through two callbacks: `onDragStarted` and `onDragFinished`.
+<SplitPane
+  className="h-full w-full"
+  dividerClassName="bg-border hover:bg-accent transition-colors"
+>
+  <Pane defaultSize="280px" className="bg-background border-r">
+    <Sidebar />
+  </Pane>
+  <Pane className="bg-muted/50">
+    <MainContent />
+  </Pane>
+</SplitPane>
+```
 
-### Example styling
+### Custom Divider with shadcn
+
+Create a themed divider component using shadcn's `cn` utility:
+
+```tsx
+import { cn } from '@/lib/utils';
+import type { DividerProps } from 'react-split-pane';
+
+function ThemedDivider({ direction, isDragging, disabled, ...props }: DividerProps) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center transition-colors',
+        'bg-border hover:bg-accent focus:outline-none focus:ring-2 focus:ring-ring',
+        direction === 'horizontal'
+          ? 'w-1 cursor-col-resize'
+          : 'h-1 cursor-row-resize',
+        isDragging && 'bg-primary',
+        disabled && 'cursor-not-allowed opacity-50'
+      )}
+      {...props}
+    />
+  );
+}
+
+<SplitPane divider={ThemedDivider}>
+  <Pane>Left</Pane>
+  <Pane>Right</Pane>
+</SplitPane>
+```
 
-This gives a single pixel wide divider, but with a 'grabbable' surface of 11 pixels.
+### CSS Variables with Tailwind
 
-Thanks to ```background-clip: padding-box;``` for making transparent borders possible.
+Override the default CSS variables in your `globals.css` to match your Tailwind theme:
+
+```css
+/* globals.css */
+@layer base {
+  :root {
+    --split-pane-divider-size: 4px;
+    --split-pane-divider-color: theme('colors.gray.200');
+    --split-pane-divider-color-hover: theme('colors.gray.300');
+    --split-pane-focus-color: theme('colors.blue.500');
+  }
+
+  .dark {
+    --split-pane-divider-color: theme('colors.gray.700');
+    --split-pane-divider-color-hover: theme('colors.gray.600');
+  }
+}
+```
 
+Or with shadcn/ui CSS variables:
 
 ```css
+@layer base {
+  :root {
+    --split-pane-divider-color: hsl(var(--border));
+    --split-pane-divider-color-hover: hsl(var(--accent));
+    --split-pane-focus-color: hsl(var(--ring));
+  }
+}
+```
+
+## Migration from v0.1.x
+
+See [MIGRATION.md](./MIGRATION.md) for detailed migration guide.
+
+**Quick changes:**
+
+```tsx
+// v0.1.x
+<SplitPane split="vertical" minSize={50} defaultSize={100}>
+  <div>Pane 1</div>
+  <div>Pane 2</div>
+</SplitPane>
+
+// v3
+<SplitPane direction="horizontal">
+  <Pane minSize="50px" defaultSize="100px">
+    <div>Pane 1</div>
+  </Pane>
+  <Pane>
+    <div>Pane 2</div>
+  </Pane>
+</SplitPane>
+```
+
+## Browser Support
+
+- Chrome/Edge (latest 2 versions)
+- Firefox (latest 2 versions)
+- Safari (latest 2 versions)
+- Mobile browsers (iOS Safari, Chrome Android)
+
+**Note:** IE11 is not supported. Use v0.1.x for IE11 compatibility.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
 
-    .Resizer {
-        background: #000;
-        opacity: .2;
-        z-index: 1;
-        -moz-box-sizing: border-box;
-        -webkit-box-sizing: border-box;
-        box-sizing: border-box;
-        -moz-background-clip: padding;
-        -webkit-background-clip: padding;
-        background-clip: padding-box;
-    }
-
-     .Resizer:hover {
-        -webkit-transition: all 2s ease;
-        transition: all 2s ease;
-    }
-
-     .Resizer.horizontal {
-        height: 11px;
-        margin: -5px 0;
-        border-top: 5px solid rgba(255, 255, 255, 0);
-        border-bottom: 5px solid rgba(255, 255, 255, 0);
-        cursor: row-resize;
-        width: 100%;
-    }
-
-    .Resizer.horizontal:hover {
-        border-top: 5px solid rgba(0, 0, 0, 0.5);
-        border-bottom: 5px solid rgba(0, 0, 0, 0.5);
-    }
-
-    .Resizer.vertical {
-        width: 11px;
-        margin: 0 -5px;
-        border-left: 5px solid rgba(255, 255, 255, 0);
-        border-right: 5px solid rgba(255, 255, 255, 0);
-        cursor: col-resize;
-    }
-
-    .Resizer.vertical:hover {
-        border-left: 5px solid rgba(0, 0, 0, 0.5);
-        border-right: 5px solid rgba(0, 0, 0, 0.5);
-    }
-    .Resizer.disabled {
-      cursor: not-allowed;
-    }
-    .Resizer.disabled:hover {
-      border-color: transparent;
-    }
-
- ```
-### Inline Styles
-
-You can also pass inline styles to the components via props. These are:
-
- * `paneStyle` - Styling to be applied to both panes
- * `pane1Style` - Styling to be applied to the first pane, with precedence over `paneStyle`
- * `pane2Style` - Styling to be applied to the second pane, with precedence over `paneStyle`
- * `resizerStyle` - Styling to be applied to the resizer bar
-
-
-### Contributing
-
-I'm always happy to receive Pull Requests for contributions of any kind. 
-
-Please include tests and/or update the examples if possible.
-  
-I've been working on an updated version of this library - if you'd like to get involved in any way please ping me a message.    
-  
-Thanks, Tom  
-  
+MIT © [tomkp](https://github.com/tomkp)

package/dist/components/Divider.d.ts

@@ -0,0 +1,31 @@
+import type { DividerProps } from '../types';
+/**
+ * The divider component that separates panes and handles resize interactions.
+ *
+ * This component is automatically rendered between panes by SplitPane.
+ * You can provide a custom divider via the `divider` prop on SplitPane.
+ *
+ * Features:
+ * - Keyboard accessible (arrow keys, Home, End)
+ * - Touch-friendly for mobile devices
+ * - ARIA attributes for screen readers
+ *
+ * @example
+ * ```tsx
+ * // Custom divider component
+ * function CustomDivider(props: DividerProps) {
+ *   return (
+ *     <div {...props} className="my-divider">
+ *       <GripIcon />
+ *     </div>
+ *   );
+ * }
+ *
+ * <SplitPane divider={CustomDivider}>
+ *   <Pane>Left</Pane>
+ *   <Pane>Right</Pane>
+ * </SplitPane>
+ * ```
+ */
+export declare function Divider(props: DividerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Divider.d.ts.map

package/dist/components/Divider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Divider.d.ts","sourceRoot":"","sources":["../../src/components/Divider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAQ7C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,2CAgF1C"}

package/dist/components/Pane.d.ts

@@ -0,0 +1,27 @@
+import type { PaneProps } from '../types';
+/**
+ * A pane component that must be used as a direct child of SplitPane.
+ *
+ * Panes can have size constraints and can be either controlled (with `size`)
+ * or uncontrolled (with `defaultSize`).
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled with constraints
+ * <Pane minSize="100px" maxSize="500px" defaultSize="300px">
+ *   Content here
+ * </Pane>
+ *
+ * // Controlled
+ * <Pane size={sizes[0]} minSize={100}>
+ *   Content here
+ * </Pane>
+ *
+ * // Percentage-based sizing
+ * <Pane defaultSize="25%" minSize="10%">
+ *   Sidebar
+ * </Pane>
+ * ```
+ */
+export declare const Pane: import("react").ForwardRefExoticComponent<PaneProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=Pane.d.ts.map