@principal-ade/panel-layouts

> Pre-built panel layout components and workspace management for the Panel Framework

This package provides ready-to-use panel layout components, workspace presets, and persistence hooks that work with @principal-ade/panel-framework-core. Built on top of @principal-ade/panels, it adds workspace management, persistence, and pre-configured layouts from the electron-app.

🎯 Purpose

While @principal-ade/panel-framework-core provides the foundation for how panels work (registration, lifecycle, events), this package handles how panels arrange on screen (layouts, resizing, workspaces).

This package = @principal-ade/panels (layout primitives) + persistence + workspace management + preset layouts

📦 What This Package Provides

$3

We re-export the core layout components from @principal-ade/panels for convenience:

- ConfigurablePanelLayout - Main layout component supporting 2 or 3 panel configurations
- TabGroup - Tab-based panel grouping
- PanelConfigurator - Interactive UI for configuring layouts
- AnimatedResizableLayout - Lower-level resizable layout primitive
- Types: PanelLayout, PanelSlot, PanelGroup, TabsConfig, TilesConfig

These components provide:
- Resizable panels with drag handles (powered by react-resizable-panels)
- Collapsible panels with animations
- Tab groups and tile arrangements
- Theme integration with @principal-ade/industry-theme
- 2-panel and 3-panel layout support

$3

#### usePanelPersistence
NEW - Extracted from electron-app

Manages saving and loading panel sizes and collapsed states:
- Saves to user preferences (Electron) or localStorage (web)
- Supports both 2-panel and 3-panel layouts
- Debounced saving (500ms) to avoid excessive writes
- Handles collapse/expand animations
- Tracks last non-zero sizes for restoring after collapse

Source: /Users/griever/Developer/electron-app/src/renderer/hooks/usePanelPersistence.ts

#### useWorkspace
NEW - Convenience hook

Easy workspace management:
- Load and apply workspace presets
- Switch between workspaces
- Create custom workspaces
- React hooks API for workspace state

$3

#### WorkspaceLayoutService
NEW - Extracted from electron-app

Manages workspace presets and configurations:
- CRUD operations for custom workspaces
- Built-in workspace presets (Feed View, Code Review, etc.)
- Per-repository workspace state tracking
- Workspace switching and persistence

Source: /Users/griever/Developer/electron-app/src/renderer/services/WorkspaceLayoutService.ts

$3

NEW - Ready-to-use layout configurations

Ready-to-use React components wrapping ConfigurablePanelLayout with preset configurations:

#### FeedViewLayout
Three-panel layout optimized for repository exploration:
- Left Panel (20%): Projects, Stars, Social, Graphs
- Middle Panel (80%): Commits, README, Signals
- Right Panel: Collapsed by default

Source: /Users/griever/Developer/electron-app/src/renderer/principal-window/views/FeedView/FeedView.tsx

#### Other Workspace Presets (to be extracted from electron-app)
- ProjectManagementLayout - Project tracking and planning
- CodeReviewLayout - Git changes and diffs
- DocumentationLayout - README and markdown focus
- AgentWorkLayout - AI agent interaction
- QualityCheckLayout - Code quality metrics
- DrawingLayout - Excalidraw integration
- PrincipalOfficeLayout - Executive dashboard

📋 Type Definitions

$3

``typescript
// Panel Layout Structure (from @principal-ade/panels)
interface PanelLayout {
left?: PanelSlot;
middle?: PanelSlot;
right?: PanelSlot;
}

// Panel Slot Configuration
type PanelSlot = string | null | PanelGroup;

interface PanelGroup {
type: 'tabs' | 'tiles';
panels: string[];
config?: TabsConfig | TilesConfig;
}

// Tabs Configuration
interface TabsConfig {
defaultActiveTab?: number;
tabPosition?: 'top' | 'bottom' | 'left' | 'right';
centered?: boolean;
activeTabIndex?: number;
onTabChange?: (index: number) => void;
}

// Tiles Configuration
interface TilesConfig {
direction?: 'horizontal' | 'vertical' | 'grid';
columns?: number;
rows?: number;
tileSizes?: number[];
}
`

$3

`typescript
// Workspace Preset (NEW)
interface WorkspacePreset {
id: string;
name: string;
description?: string;
icon?: string;
layout: PanelLayout;
defaultSizes?: {
left?: number;
middle?: number;
right?: number;
};
collapsed?: {
left?: boolean;
right?: boolean;
};
}

// Panel Persistence Options (NEW)
interface PanelPersistenceOptions {
viewKey: string;
defaultSizes: PanelSizes | TwoPanelSizes;
collapsed: PanelCollapsed | { left?: boolean };
panelType: 'three-panel' | 'two-panel';
}
`

🚀 Proposed Usage

`typescript
import { PanelHarness, globalPanelRegistry } from '@principal-ade/panel-framework-core';
import {
FeedViewLayout,
usePanelPersistence,
WorkspaceLayoutService
} from '@principal-ade/panel-layouts';

// Register your panels
globalPanelRegistry.register({
metadata: { id: 'git-changes', name: 'Git Changes' },
component: GitChangesPanel,
});

function App() {
// Use persistence hook for saving layout state
const { sizes, collapsed, handleResize } = usePanelPersistence('my-app');

return (

defaultSizes={sizes}
collapsed={collapsed}
onResize={handleResize}
/>

);
}
`

$3

`typescript
import { ConfigurablePanelLayout } from '@principal-ade/panel-layouts';

panels={[
{ id: 'git-changes', content: },
{ id: 'readme', content: },
{ id: 'commits', content: },
]}
layout={{
left: {
type: 'tabs',
panels: ['git-changes'],
config: { defaultActiveTab: 0, tabPosition: 'top' }
},
middle: {
type: 'tabs',
panels: ['readme', 'commits'],
config: { defaultActiveTab: 0 }
},
right: null
}}
defaultSizes={{ left: 30, middle: 70, right: 0 }}
collapsed={{ left: false, right: true }}
collapsiblePanels={{ left: true, right: false }}
showCollapseButtons={true}
onPanelResize={(sizes) => console.log('Resized:', sizes)}
/>
`

$3

`typescript
import { WorkspaceLayoutService } from '@principal-ade/panel-layouts';

// Get built-in workspaces
const workspaces = WorkspaceLayoutService.getBuiltInWorkspaces();

// Apply a workspace
WorkspaceLayoutService.applyWorkspace('code-review', repositoryPath);

// Create custom workspace
WorkspaceLayoutService.createCustomWorkspace({
id: 'my-workflow',
name: 'My Custom Workflow',
layout: { / ... / },
defaultSizes: { left: 25, middle: 50, right: 25 }
});
`

📁 Package Structure

`
@principal-ade/panel-layouts/
├── src/
│ ├── index.ts # Main entry - re-exports from @principal-ade/panels + our code
│ ├── layouts/
│ │ ├── FeedViewLayout.tsx # Pre-built feed view
│ │ ├── ProjectManagementLayout.tsx # Project management preset
│ │ ├── CodeReviewLayout.tsx # Code review preset
│ │ ├── DocumentationLayout.tsx # Documentation preset
│ │ └── index.ts
│ ├── hooks/
│ │ ├── usePanelPersistence.ts # Layout state persistence (extracted)
│ │ ├── useWorkspace.ts # Workspace management hook
│ │ └── index.ts
│ ├── services/
│ │ ├── WorkspaceLayoutService.ts # Workspace CRUD operations (extracted)
│ │ └── index.ts
│ └── types/
│ ├── workspace.types.ts # Workspace types
│ ├── persistence.types.ts # Persistence types
│ └── index.ts
├── package.json
├── tsconfig.json
├── vite.config.ts
├── README.md
└── LICENSE
`

Note: We don't duplicate ConfigurablePanelLayout, TabGroup, etc. - we re-export them from @principal-ade/panels.

🔗 Dependencies

`json
{
"peerDependencies": {
"@principal-ade/panel-framework-core": "^0.1.0",
"react": ">=18.0.0",
"react-dom": ">=18.0.0"
},
"dependencies": {
"@principal-ade/panels": "^1.0.39",
"@principal-ade/industry-theme": "^0.1.2",
"react-resizable-panels": "^3.0.0"
}
}
`

Architecture:
- We depend on @principal-ade/panels for layout primitives (ConfigurablePanelLayout, TabGroup, etc.)
- @principal-ade/panels depends on react-resizable-panels for resizing functionality
- We re-export components from @principal-ade/panels for convenience
- We add our own persistence, workspace management, and preset layouts on top

🎨 Design Principles

$3

- @principal-ade/panel-framework-core: Panel registration, lifecycle, events
- @principal-ade/panels: Layout primitives, resizing, collapsing, theming
- @principal-ade/panel-layouts (this package): Persistence, workspaces, presets

$3

We build on top of proven components (@principal-ade/panels) rather than reinventing the wheel. This allows us to:
- Focus on high-value features (workspaces, persistence)
- Get resizing, animations, and theming for free
- Maintain compatibility with existing electron-app code

$3

Users can use @principal-ade/panel-framework-core + @principal-ade/panels directly if they don't need workspace management.

$3

All components are composable - users can:
- Use pre-built layouts as-is (FeedViewLayout)
- Use ConfigurablePanelLayout with custom configs
- Use @principal-ade/panels directly for full control

$3

Built-in support for saving/loading layout state to:
- localStorage (web)
- User preferences (Electron via IPC)
- Remote storage (optional extension point)

📝 Implementation Steps

$3

1. ✅ Set up package structure with TypeScript and Vite
2. ✅ Install @principal-ade/panels as a dependency
3. ✅ Create re-export index that exposes components from @principal-ade/panels
4. ✅ Configure build to output ESM/CJS with CSS

What we're doing: Setting up the foundation and making @principal-ade/panels components available through our package.

$3


1. Extract usePanelPersistence from electron-app
2. Adapt for both web (localStorage) and Electron (IPC) environments
3. Add type definitions
4. Write unit tests

Source File:
- /Users/griever/Developer/electron-app/src/renderer/hooks/usePanelPersistence.ts

What we're doing: Adding the state persistence layer that @principal-ade/panels doesn't provide.

$3


1. Extract WorkspaceLayoutService from electron-app
2. Adapt for both web and Electron environments
3. Define built-in workspace presets
4. Create useWorkspace convenience hook
5. Write unit tests

Source File:
- /Users/griever/Developer/electron-app/src/renderer/services/WorkspaceLayoutService.ts

What we're doing: Adding workspace management for quick layout switching.

$3

1. Extract FeedView layout configuration
2. Create React component wrappers for each preset
3. Make them configurable and extensible
4. Document each preset's use case

Source Files:
- /Users/griever/Developer/electron-app/src/renderer/principal-window/views/FeedView/FeedView.tsx
- Workspace definitions from WorkspaceLayoutService

What we're doing: Creating ready-to-use layout components for common use cases.

$3


1. Write comprehensive usage documentation
2. Create example applications (web + Electron)
3. Add migration guide from electron-app
4. Publish to npm as @principal-ade/panel-layouts

🔄 Integration with electron-app

Once published, the electron-app can replace its current implementation:

`diff
- import { ConfigurablePanelLayout } from '@principal-ade/panels';
- import { usePanelPersistence } from '../hooks/usePanelPersistence';
+ import { ConfigurablePanelLayout, usePanelPersistence } from '@principal-ade/panel-layouts';
`

Benefits:
- Shared between web and desktop
- Community can contribute improvements
- Consistent across all applications
- Easier to maintain

📚 Related Packages

- @principal-ade/panel-framework-core - Core panel system (published)
- @principal-ade/panel-layouts - This package (to be implemented)
- @principal-ade/panels - Current layout implementation in electron-app
- @principal-ade/industry-theme - Theming system used by layouts

🤝 Contributing

This package is designed to be the standard layout system for Panel Framework applications. Contributions should focus on:

1. Performance - Layouts should be fast and responsive
2. Flexibility - Support various use cases and customization
3. Accessibility - Keyboard navigation, screen reader support
4. Documentation - Clear examples and API docs

📄 License

MIT

---

🚧 Current Status

Status: 🚧 In Active Development

This package is being actively developed with a focus on reusing @principal-ade/panels and adding workspace/persistence features.

$3


- ✅ README specification complete
- ✅ Package setup and build configuration (Vite + TypeScript)
- ✅ Re-exports from @principal-ade/panels (25+ components)
- ✅ usePanelPersistence hook extracted and adapted
- ✅ LocalStoragePersistenceAdapter for web apps
- ✅ Storybook with interactive component stories
- ✅ ESLint + TypeScript linting configured
- ✅ Vitest test suite (14 tests passing)
- ⏳ Extract WorkspaceLayoutService (next)
- ⏳ Create pre-built layout components
- ⏳ Additional documentation and examples
- ⏳ Publish to npm

$3

We're reusing @principal-ade/panels@1.0.39 as a dependency rather than rebuilding layout components. This allows us to:
- Focus on high-value features (persistence, workspaces, presets)
- Leverage proven, tested layout components
- Maintain compatibility with existing electron-app code

$3

`bash

Development

npm run dev # Start Vite dev server
npm run storybook # Start Storybook on :6006

Quality Checks

npm run type-check # TypeScript type checking ✅
npm run lint # ESLint (2 warnings) ✅
npm run test # Vitest (14/14 passing) ✅

Build

npm run build # Build ESM + CJS + types ✅
`

$3

- Re-exported: All components from @principal-ade/panels
- New: usePanelPersistence hook with localStorage adapter
- New: Comprehensive TypeScript types
- New: Interactive Storybook documentation

$3

- Persistence: /Users/griever/Developer/electron-app/src/renderer/hooks/usePanelPersistence.ts
- Workspace Service: /Users/griever/Developer/electron-app/src/renderer/services/WorkspaceLayoutService.ts
- FeedView Layout: /Users/griever/Developer/electron-app/src/renderer/principal-window/views/FeedView/FeedView.tsx`