@principal-ade/panels

A modern React panel layout component library built on top of react-resizable-panels with enhanced animations, TypeScript support, and common layout patterns.

Installation

``bash
npm install @principal-ade/panels
`

Quick Start

⚠️ Important: You must import the CSS file for proper styling:

`tsx
import { AnimatedResizableLayout } from '@principal-ade/panels';
import '@principal-ade/panels/style.css'; // Required!

function App() {
return (
leftPanel={

We currently have an AnimatedResizableLayout component that provides:
- 2-panel horizontal layout (left/right)
- Smooth collapse/expand animations using requestAnimationFrame
- Collapsible panels on either side
- Dark mode support
- Custom collapse toggle button with directional icons
- Animated opacity transitions for content
- Proper handling of drag vs animation states
- Callbacks for animation lifecycle events

$3

#### Animation System
- Smooth transitions: 300ms cubic-bezier easing by default
- RAF-based animations: Custom requestAnimationFrame implementation for smooth 60fps animations
- Dual-state handling: Distinguishes between user dragging and programmatic animations
- Content opacity fading: Panel content fades during collapse/expand
- Handle visibility: Resize handle hides when panel is collapsed

#### Styling
- Clean, minimal resize handles (8px width)
- Hover states for interactive elements
- Dark mode support via CSS media queries
- Collapse toggle button with scaling animations on hover/active
- Shadow effects for depth perception

#### API
- leftPanel / rightPanel: ReactNode content
- collapsibleSide: 'left' | 'right'
- defaultSize: Initial panel size (0-100)
- minSize: Minimum size when expanded
- collapsed: Initial collapsed state
- showCollapseButton: Toggle button visibility
- animationDuration / animationEasing: Customizable animations
- Lifecycle callbacks: onCollapseStart, onCollapseComplete, onExpandStart, onExpandComplete

New Package Requirements

$3

#### 1. ThreePanelLayout
A horizontal 3-panel layout component with all panels resizable.

`tsx
interface ThreePanelLayoutProps {
leftPanel: ReactNode;
centerPanel: ReactNode;
rightPanel: ReactNode;

// Sizing
defaultSizes?: [number, number, number]; // Default: [25, 50, 25]
minSizes?: [number, number, number]; // Default: [10, 30, 10]

// Collapsible configuration
collapsiblePanels?: {
left?: boolean;
right?: boolean;
center?: boolean; // Rarely used but supported
};

// Animation
animationDuration?: number; // Default: 300
animationEasing?: string; // Default: cubic-bezier

// Collapse state
collapsed?: {
left?: boolean;
right?: boolean;
};

// Controls
showCollapseButtons?: boolean;
collapseButtonPosition?: 'handle' | 'panel' | 'both';

// Styling
className?: string;
handleClassName?: string;
panelClassName?: string;
theme?: 'light' | 'dark' | 'auto';

// Callbacks
onPanelResize?: (sizes: [number, number, number]) => void;
onPanelCollapse?: (panel: 'left' | 'center' | 'right') => void;
onPanelExpand?: (panel: 'left' | 'center' | 'right') => void;

// Persistence
persistenceKey?: string; // Save layout to localStorage
}
`

#### 2. TwoPanelLayout
A simplified 2-panel version using the native react-resizable-panels animations.

`tsx
interface TwoPanelLayoutProps {
leftPanel: ReactNode;
rightPanel: ReactNode;

orientation?: 'horizontal' | 'vertical';
defaultSize?: number;
minSize?: number;

collapsibleSide?: 'left' | 'right' | 'both';
collapsed?: 'left' | 'right' | null;

// Similar animation, styling, callback props as ThreePanelLayout
}
`

#### 3. AdaptiveLayout
A responsive layout that switches between layouts based on viewport size.

`tsx
interface AdaptiveLayoutProps {
panels: ReactNode[];

breakpoints?: {
mobile?: number; // Default: 768
tablet?: number; // Default: 1024
desktop?: number; // Default: 1440
};

layouts?: {
mobile?: 'stack' | 'tabs' | 'drawer';
tablet?: 'two-panel' | 'drawer-main';
desktop?: 'three-panel' | 'two-panel';
};

// All other props from ThreePanelLayout
}
`

$3

#### Must Have (v1.0)
- [x] Smooth native animations using react-resizable-panels built-in transitions
- [x] TypeScript definitions with strict typing
- [x] 2-panel and 3-panel layouts
- [x] Collapsible panels with animation
- [x] Dark mode support
- [x] Collapse/expand toggle buttons
- [x] Keyboard accessibility (arrow keys for resize, space/enter for toggle)
- [x] Proper ARIA labels
- [x] Zero dependencies except react-resizable-panels
- [x] < 10KB gzipped

#### Nice to Have (v1.1+)
- [ ] Persistence to localStorage
- [ ] Drag handle customization
- [ ] Custom collapse button components
- [ ] Snap points for panel sizes
- [ ] Double-click to reset panel size
- [ ] Nested panel support
- [ ] Vertical orientation support
- [ ] Touch gesture support for mobile
- [ ] Server-side rendering support
- [ ] Presets (sidebar layouts, dashboard layouts, etc.)

$3

#### Build Setup
`json
{
"name": "@principal-ade/panels",
"version": "1.0.0",
"main": "dist/index.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts",
"peerDependencies": {
"react": ">=16.8.0",
"react-dom": ">=16.8.0",
"react-resizable-panels": "^2.0.0"
},
"devDependencies": {
"@storybook/react": "^7.0.0",
"typescript": "^5.0.0",
"vite": "^5.0.0"
}
}
`

#### Storybook Stories
- Basic 2-panel layout
- Basic 3-panel layout
- Collapsible panels demo
- Dark mode toggle
- Animated collapse/expand
- Responsive adaptive layout
- Nested panels
- Custom styling examples
- Persistence demo
- Accessibility demo

$3

#### Key Differences
1. Use native react-resizable-panels animations instead of custom RAF implementation
2. Support 3 panels out of the box
3. Simplified API - less boilerplate needed
4. Better TypeScript support with generics for panel content types
5. Built-in persistence via localStorage
6. Responsive layouts with AdaptiveLayout component

#### Migration Steps
`tsx
// Old
import { AnimatedResizableLayout } from './layout-components';

leftPanel={}
rightPanel={}
collapsibleSide="left"
defaultSize={25}
showCollapseButton={true}
/>

// New
import { TwoPanelLayout } from '@principal-ade/panels';

leftPanel={}
rightPanel={}
collapsibleSide="left"
defaultSize={25}
showCollapseButtons={true}
/>
`

$3

#### Basic 3-Panel Layout
`tsx
import { ThreePanelLayout } from '@principal-ade/panels';

function App() {
return (
leftPanel={}
centerPanel={}
rightPanel={}
defaultSizes={[20, 60, 20]}
collapsiblePanels={{ left: true, right: true }}
showCollapseButtons
theme="auto"
persistenceKey="app-layout"
/>
);
}
`

#### Responsive Adaptive Layout
`tsx
import { AdaptiveLayout } from '@principal-ade/panels';

function App() {
return (
panels={[