Alexandria documentation panel for Principal ADE - view and manage repository documentation with associated files tree view
npm install @industry-theme/alexandria-docs-panelA panel extension for viewing and managing repository documentation in Principal ADE applications.
- ✅ Display list of markdown documents from repository
- ✅ Click to open documents
- ✅ Auto-refresh when data changes
- ✅ Empty state handling
- ✅ Loading state
- ✅ Industry theme styling
- ✅ Search and filtering
- ✅ Associated Files Tree View - Expandable tree showing files linked to each document
- 🔲 Sort by name/date
- 🔲 Track/untracked status indicators
- 🔲 Git status indicators
- 🔲 Map/visualization integration
- 🔲 Coverage view
``bash`
npm install @principal-ade/alexandria-docs-panelor
bun install @principal-ade/alexandria-docs-panel
The panel will automatically be discovered by host applications that support the @principal-ade/panel-framework-core architecture.
`typescript
import { panels } from '@principal-ade/alexandria-docs-panel';
// Panels are auto-loaded via the panel-extension keyword
// No manual registration needed if your host scans packages
`
📖 See INTEGRATION_GUIDE.md for detailed setup instructions and troubleshooting.
This panel supports multiple data sources with automatic fallback:
#### Option 1: Adapters (Preferred)
Provide adapters for the panel to use MemoryPalace directly:
- Adapter: context.adapters.fileSystem - FileSystemAdapter from @principal-ai/alexandria-core-librarycontext.adapters.glob
- Adapter: - GlobAdapter from @principal-ai/alexandria-core-libraryfileTree
- Data Slice: - FileTree object (used to detect Alexandria configuration)openFile(filePath: string)
- Action: - To open documents when clicked
When adapters are provided, the panel uses MemoryPalace.getDocumentsOverview() to get documents with full tracking info and associated files.
#### Option 2: Data Slices (Legacy/Fallback)
If adapters are not available, the panel falls back to data slices:
- Data Slice: markdown - Array of MarkdownFile objectsfileTree
- Data Slice: - FileTree object (fallback: derive markdown files from here)openFile(filePath: string)
- Action: - To open documents when clicked
`typescript
interface MarkdownFile {
path: string; // Full file system path
title?: string; // Optional document title
lastModified: number; // Unix timestamp
// Optional: Alexandria-specific metadata
associatedFiles?: string[]; // Array of file paths linked to this document
isTracked?: boolean; // Whether document is tracked by Alexandria
hasUncommittedChanges?: boolean; // Git status indicator
}
`
Note: The adapter-based approach is preferred as it provides richer data (tracked status, associated files from CodebaseViews) without requiring the host to implement Alexandria-specific logic.
`bash`
bun install
`bashBuild the panel
bun run build
$3
View the panel in isolation with mock data:
`bash
bun run storybook
`This will open http://localhost:6006 with interactive stories:
- Empty State - No documents
- Loading State - Data loading
- With Documents - 5 example documents
- With Associated Files - Documents with expandable file trees
- Many Documents - 50 documents for scroll testing
Architecture
$3
`
src/
├── panels/
│ ├── AlexandriaDocsPanel.tsx # Main panel component
│ ├── AlexandriaDocsPanel.stories.tsx # Storybook stories
│ └── components/
│ ├── AlexandriaDocItem.tsx # Individual doc item with expand/collapse
│ └── AssociatedFilesTree.tsx # File tree view for associated files
├── types/
│ └── index.ts # TypeScript types
└── index.tsx # Panel registration
`$3
`typescript
{
id: 'principal-ade.alexandria-docs',
name: 'Alexandria Docs',
icon: '📚',
version: '0.1.0',
author: 'Principal AI',
description: 'View and manage repository documentation with Alexandria',
component: AlexandriaDocsPanel,
}
`Roadmap
$3
- ✅ Associated files tree view
- 🚧 Sort by name/date
- 🚧 Track/untracked status indicators
- 🚧 Git status indicators
- 🚧 Map/visualization integration
- 🚧 Coverage view
$3
- Document creation UI
- Full-text search
- Batch operations
- Document templates
Bundle Size
- Bundle: ~283KB (gzipped: ~55KB)
- Includes dynamic file tree library for associated files feature
Dependencies
$3
-
@principal-ade/industry-theme - Theming and styling
- @principal-ade/dynamic-file-tree - File tree visualization component
- @principal-ai/repository-abstraction - File tree data structures
- lucide-react - Icon library
- clsx - Conditional className utility$3
-
react >= 19.0.0
- react-dom >= 19.0.0License
MIT
Contributing
See DESIGN.md for the full design document and architecture details.
---
Version: 0.4.4 (Milestone 2 - In Progress)
Author: Principal AI
Changelog
$3
- 🔧 Use CONFIG_FILENAME from core library - No longer hardcoding config path; uses
CONFIG_FILENAME constant from @principal-ai/alexandria-core-library$3
- 🔧 Panel uses only relative paths - Panel no longer constructs absolute paths; host resolves relative paths via
openFile and readFile adapters
- 🔧 Simplified path handling throughout the panel$3
- 🔧 Fixed relative path handling - Panel now uses relative paths for config detection (matching electron app FileTree format)
- 🔧 Updated Storybook stories to use relative paths in FileTree mock
$3
- 🔧 Improved config detection - Uses
FileSystemAdapter.exists() instead of manual fileTree checking
- 🔧 Simplified hook by creating adapters once and reusing them$3
- ✨ FileTree-based adapters - Uses
FileTreeFileSystemAdapter and FileTreeGlobAdapter from core library
- ✨ ConfigView toggle - Click the book icon to view Alexandria configuration (Context & Rules tabs)
- 🔧 Host now only needs to provide readFile and matchesPath adapters (minimal primitives)
- 🔧 Requires @principal-ade/panel-framework-core@0.1.10+ for new adapter types
- 🔧 Requires @principal-ai/alexandria-core-library@0.1.42+ for FileTree adapters
- 📚 Updated Storybook stories with proper mock adapters$3
- 🔧 Removed markdown slice dependency - Panel now uses only adapters or fileTree fallback
- 🔧 Simplified
useAlexandriaData hook: adapters → fileTree (removed legacy markdown slice path)
- 🗑️ Removed MarkdownFile type from exports (no longer needed)$3
- ✨ Adapter-based architecture - Panel can now use
MemoryPalace directly via host-provided adapters
- ✨ Uses MemoryPalace.getDocumentsOverview() for rich document data (tracking status, associated files)
- 🔧 Added useAlexandriaData hook with automatic fallback: adapters → fileTree
- 🔧 Requires @principal-ade/panel-framework-core@0.1.9+ for adapter support
- 🔧 Requires @principal-ai/alexandria-core-library@0.1.41+ for browser-safe MemoryPalace
- 📚 Updated documentation with adapter vs slice options$3
- 🔧 Removed dependency on
alexandria slice - now derives hasAlexandriaConfig from fileTree slice
- 🔧 Panel now checks for .alexandria/alexandria.json in the file tree to determine config presence
- ⬇️ Reduced host application requirements (no need to provide separate alexandria slice)$3
- ✨ Added associated files tree view with expand/collapse functionality
- ✨ Integrated
@principal-ade/dynamic-file-tree` for file tree visualization- ✨ Added filter bar for searching documents
- 🐛 Fixed production JSX runtime issue
- 🎉 Initial MVP release
- ✨ Basic document list display
- ✨ Click to open functionality
- ✨ Industry theme styling