@principal-ade/panel-layouts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Principal ADE
+
+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,466 @@
+# @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 `@a24z/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 = **@a24z/panels** (layout primitives) + **persistence** + **workspace management** + **preset layouts**
+
+## 📦 What This Package Provides
+
+### Re-exported Components (from @a24z/panels)
+
+We re-export the core layout components from `@a24z/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 `@a24z/industry-theme`
+- 2-panel and 3-panel layout support
+
+### Our Value-Add: Hooks (Extracted from electron-app)
+
+#### `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
+
+### Our Value-Add: Services (Extracted from electron-app)
+
+#### `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`
+
+### Our Value-Add: Pre-built Layouts (Extracted from electron-app)
+
+**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
+
+### Re-exported from @a24z/panels
+
+```typescript
+// Panel Layout Structure (from @a24z/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[];
+}
+```
+
+### Our New Types
+
+```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 (
+    <PanelHarness context={context} actions={actions} events={events}>
+      <FeedViewLayout
+        defaultSizes={sizes}
+        collapsed={collapsed}
+        onResize={handleResize}
+      />
+    </PanelHarness>
+  );
+}
+```
+
+### Using ConfigurablePanelLayout Directly
+
+```typescript
+import { ConfigurablePanelLayout } from '@principal-ade/panel-layouts';
+
+<ConfigurablePanelLayout
+  panels={[
+    { id: 'git-changes', content: <GitChangesPanel /> },
+    { id: 'readme', content: <ReadmePanel /> },
+    { id: 'commits', content: <CommitsPanel /> },
+  ]}
+  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)}
+/>
+```
+
+### Using Workspace Presets
+
+```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 @a24z/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 `@a24z/panels`.
+
+## 🔗 Dependencies
+
+```json
+{
+  "peerDependencies": {
+    "@principal-ade/panel-framework-core": "^0.1.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@a24z/panels": "^1.0.26",
+    "@a24z/industry-theme": "^0.1.1",
+    "react-resizable-panels": "^3.0.0"
+  }
+}
+```
+
+**Architecture:**
+- We depend on `@a24z/panels` for layout primitives (ConfigurablePanelLayout, TabGroup, etc.)
+- `@a24z/panels` depends on `react-resizable-panels` for resizing functionality
+- We re-export components from `@a24z/panels` for convenience
+- We add our own persistence, workspace management, and preset layouts on top
+
+## 🎨 Design Principles
+
+### 1. Layered Architecture
+- **@principal-ade/panel-framework-core:** Panel registration, lifecycle, events
+- **@a24z/panels:** Layout primitives, resizing, collapsing, theming
+- **@principal-ade/panel-layouts (this package):** Persistence, workspaces, presets
+
+### 2. Reuse Over Rebuild
+We build on top of proven components (`@a24z/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. Optional Dependency
+Users can use `@principal-ade/panel-framework-core` + `@a24z/panels` directly if they don't need workspace management.
+
+### 4. Composable
+All components are composable - users can:
+- Use pre-built layouts as-is (`FeedViewLayout`)
+- Use `ConfigurablePanelLayout` with custom configs
+- Use `@a24z/panels` directly for full control
+
+### 5. Persistence-Ready
+Built-in support for saving/loading layout state to:
+- localStorage (web)
+- User preferences (Electron via IPC)
+- Remote storage (optional extension point)
+
+## 📝 Implementation Steps
+
+### Phase 1: Package Setup and Re-exports
+1. ✅ Set up package structure with TypeScript and Vite
+2. ✅ Install `@a24z/panels` as a dependency
+3. ✅ Create re-export index that exposes components from `@a24z/panels`
+4. ✅ Configure build to output ESM/CJS with CSS
+
+**What we're doing:** Setting up the foundation and making `@a24z/panels` components available through our package.
+
+### Phase 2: Extract Persistence Hook (High Priority)
+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 `@a24z/panels` doesn't provide.
+
+### Phase 3: Extract Workspace Service
+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.
+
+### Phase 4: Create Pre-built Layout Components
+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.
+
+### Phase 5: Documentation and Publishing
+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 '@a24z/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)
+- **@a24z/panels** - Current layout implementation in electron-app
+- **@a24z/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 `@a24z/panels` and adding workspace/persistence features.
+
+### Implementation Progress:
+- ✅ README specification complete
+- ✅ Package setup and build configuration (Vite + TypeScript)
+- ✅ Re-exports from @a24z/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
+
+### Architecture Decision:
+We're **reusing** `@a24z/panels@1.0.27` 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
+
+### What's Working Now:
+```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 ✅
+```
+
+### Package Contents:
+- **Re-exported:** All components from @a24z/panels
+- **New:** `usePanelPersistence` hook with localStorage adapter
+- **New:** Comprehensive TypeScript types
+- **New:** Interactive Storybook documentation
+
+### Reference Files (electron-app):
+- 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`