Alexandria Docs Panel

A panel extension for viewing and managing repository documentation in Principal ADE applications.

Features

$3

- ✅ 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

$3

- ✅ 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

Installation

``bash
npm install @principal-ade/alexandria-docs-panel


or


bun install @principal-ade/alexandria-docs-panel
`

Usage

$3

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.

$3

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-library
- Adapter: context.adapters.glob - GlobAdapter from @principal-ai/alexandria-core-library
- Data Slice: fileTree - FileTree object (used to detect Alexandria configuration)
- Action: openFile(filePath: string) - 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 objects
- Data Slice: fileTree - FileTree object (fallback: derive markdown files from here)
- Action: openFile(filePath: string) - To open documents when clicked

$3

`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.

Development

$3

`bash
bun install
`

$3

`bash


Build the panel

bun run build

Type check

bun run typecheck

Lint

bun run lint

Format

bun run format

Storybook (preview panel in isolation)

bun run storybook
`

$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.0

License

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
- 🔧 Extended MarkdownFile interface to support Alexandria metadata
- 📚 Updated Storybook with "With Associated Files" story
- 📝 Updated documentation

$3

- ✨ Added filter bar for searching documents
- 🐛 Fixed production JSX runtime issue

$3

- 🎉 Initial MVP release
- ✨ Basic document list display
- ✨ Click to open functionality
- ✨ Industry theme styling