@industry-theme/markdown-panels 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+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 @@
+# Industry-Themed Markdown Panels
+
+A panel extension for rendering markdown documents with industry theming support, built using `@principal-ade/panel-framework-core`.
+
+This panel demonstrates how to integrate `themed-markdown` with the panel framework, following patterns from the desktop-app's `MarkdownRenderingPanel` and `GitHubReadmePanel`.
+
+## Features
+
+- **Themed Markdown Rendering**: Uses `themed-markdown` with `@a24z/industry-theme` for consistent, professional styling
+- **Multiple View Modes**: Switch between document view (all content) and slide view (paginated)
+- **Font Size Controls**: Adjustable font scaling from 50% to 300%
+- **Slide Navigation**: Navigate through markdown slides with previous/next controls
+- **Panel Framework Integration**: Full integration with context, actions, and events
+- **Responsive Design**: Adapts to different panel sizes and layouts
+
+## Installation
+
+```bash
+npm install
+```
+
+## Development
+
+```bash
+# Development mode (watch for changes)
+npm run dev
+
+# Build for production
+npm run build
+
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+
+# Storybook
+npm run storybook
+```
+
+## Project Structure
+
+```
+industry-themed-markdown-panels/
+├── src/
+│   ├── panels/
+│   │   └── MarkdownPanel.tsx          # Main markdown panel component
+│   ├── types/
+│   │   └── index.ts                   # TypeScript type definitions
+│   ├── mocks/
+│   │   └── panelContext.tsx           # Mock providers for Storybook
+│   └── index.tsx                      # Panel registration
+├── dist/
+│   ├── panels.bundle.js               # Built panel bundle
+│   └── index.d.ts                     # TypeScript declarations
+├── package.json
+├── vite.config.ts
+└── README.md
+```
+
+## Usage
+
+The panel exports a single `MarkdownPanel` that demonstrates:
+
+1. How to use `DocumentView` from `themed-markdown`
+2. How to integrate with `@a24z/industry-theme`
+3. How to parse markdown into slides using `parseMarkdownIntoPresentation`
+4. How to build interactive panel controls
+5. How to access panel context for repository information
+
+## Panel Definition
+
+```typescript
+{
+  id: 'principal-ade.markdown-viewer',
+  name: 'Markdown Viewer',
+  icon: '📄',
+  description: 'Themed markdown rendering panel with document and slide views',
+  component: MarkdownPanel
+}
+```
+
+## Panel Component API
+
+### PanelComponentProps
+
+Every panel component receives these props:
+
+```typescript
+interface PanelComponentProps {
+  // Access to shared data and state
+  context: PanelContextValue;
+
+  // Actions for host interaction
+  actions: PanelActions;
+
+  // Event system for inter-panel communication
+  events: PanelEventEmitter;
+}
+```
+
+### Context
+
+Access repository data and state:
+
+```tsx
+const { context } = props;
+
+// Repository information
+context.repositoryPath        // Current repository path
+context.repository            // Repository metadata
+
+// Data slices
+context.gitStatus             // Git status information
+context.fileTree              // File tree structure
+context.markdownFiles         // Markdown files list
+
+// State management
+context.loading               // Loading state
+context.refresh()             // Refresh data
+context.hasSlice('git')       // Check slice availability
+```
+
+### Actions
+
+Interact with the host application:
+
+```tsx
+const { actions } = props;
+
+// File operations
+actions.openFile?.('path/to/file.ts');
+actions.openGitDiff?.('path/to/file.ts', 'unstaged');
+
+// Navigation
+actions.navigateToPanel?.('panel-id');
+
+// Notifications
+actions.notifyPanels?.(event);
+```
+
+### Events
+
+Subscribe to and emit panel events:
+
+```tsx
+const { events } = props;
+
+// Subscribe to events
+useEffect(() => {
+  const unsubscribe = events.on('file:opened', (event) => {
+    console.log('File opened:', event.payload);
+  });
+
+  return unsubscribe; // Cleanup
+}, [events]);
+
+// Emit events
+events.emit({
+  type: 'custom:event',
+  source: 'my-panel',
+  timestamp: Date.now(),
+  payload: { data: 'value' },
+});
+```
+
+## Panel Definition
+
+Each panel must be defined with metadata:
+
+```typescript
+interface PanelDefinition {
+  id: string;              // Unique ID (e.g., 'org.panel-name')
+  name: string;            // Display name
+  icon?: string;           // Icon (emoji or URL)
+  version?: string;        // Version (defaults to package.json)
+  author?: string;         // Author (defaults to package.json)
+  description?: string;    // Short description
+  component: React.FC;     // The panel component
+
+  // Optional lifecycle hooks
+  onMount?: (context) => void | Promise<void>;
+  onUnmount?: (context) => void | Promise<void>;
+  onDataChange?: (slice, data) => void;
+}
+```
+
+## Lifecycle Hooks
+
+### Per-Panel Hooks
+
+Called for individual panels:
+
+```typescript
+{
+  id: 'my-panel',
+  component: MyPanel,
+
+  onMount: async (context) => {
+    console.log('Panel mounted');
+    if (context.hasSlice('git')) {
+      await context.refresh();
+    }
+  },
+
+  onUnmount: async (context) => {
+    console.log('Panel unmounting');
+    // Cleanup logic
+  },
+
+  onDataChange: (slice, data) => {
+    console.log(`Data changed: ${slice}`, data);
+  },
+}
+```
+
+### Package-Level Hooks
+
+Called once for the entire package:
+
+```typescript
+export const onPackageLoad = async () => {
+  console.log('Package loaded');
+  // Initialize shared resources
+};
+
+export const onPackageUnload = async () => {
+  console.log('Package unloading');
+  // Cleanup shared resources
+};
+```
+
+## Building and Publishing
+
+### Build Configuration
+
+The build process (via Vite) automatically:
+- Externalizes React and ReactDOM (provided by host)
+- Bundles all other dependencies
+- Generates TypeScript declarations
+- Creates source maps
+- Outputs to `dist/panels.bundle.js`
+
+### Local Testing
+
+Link your panel locally for testing:
+
+```bash
+# In your panel directory
+bun run build
+bun link
+
+# In your host application
+bun link @your-org/your-panel-name
+```
+
+### Publishing to NPM
+
+```bash
+# Build the package
+bun run build
+
+# Verify the output
+ls -la dist/
+
+# Publish to NPM
+npm publish --access public
+```
+
+### Installing in Host Application
+
+```bash
+# In the host application
+npm install @your-org/your-panel-name
+```
+
+The host application will automatically discover your panel by the `panel-extension` keyword in `package.json`.
+
+## Best Practices
+
+### 1. Namespaced Panel IDs
+
+Use reverse domain notation for panel IDs:
+
+```typescript
+id: 'com.company.feature-panel'  // ✅ Good
+id: 'my-panel'                   // ❌ Bad (collision risk)
+```
+
+### 2. Error Handling
+
+Always handle errors gracefully:
+
+```tsx
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  const loadData = async () => {
+    try {
+      if (!context.hasSlice('git')) {
+        throw new Error('Git data not available');
+      }
+      // Use data...
+    } catch (err) {
+      setError(err);
+    }
+  };
+  loadData();
+}, [context]);
+
+if (error) {
+  return <div>Error: {error.message}</div>;
+}
+```
+
+### 3. Loading States
+
+Show loading indicators:
+
+```tsx
+if (context.loading || context.isSliceLoading('git')) {
+  return <div>Loading...</div>;
+}
+```
+
+### 4. Cleanup Subscriptions
+
+Always unsubscribe from events:
+
+```tsx
+useEffect(() => {
+  const unsubscribe = events.on('event:type', handler);
+  return unsubscribe; // Cleanup on unmount
+}, [events]);
+```
+
+### 5. Type Safety
+
+Use provided types for type safety:
+
+```tsx
+import type { PanelComponentProps, GitStatus } from './types';
+
+const MyPanel: React.FC<PanelComponentProps> = ({ context }) => {
+  const gitStatus: GitStatus = context.gitStatus;
+  // ...
+};
+```
+
+## Available Data Slices
+
+Panels can access these data slices from the host:
+
+| Slice | Type | Description |
+|-------|------|-------------|
+| `git` | `GitStatus` | Git repository status |
+| `markdown` | `MarkdownFile[]` | Markdown files in repository |
+| `fileTree` | `FileTree` | File system tree structure |
+| `packages` | `PackageLayer[]` | Package dependencies |
+| `quality` | `QualityMetrics` | Code quality metrics |
+
+Check availability before use:
+
+```tsx
+if (context.hasSlice('git') && !context.isSliceLoading('git')) {
+  // Use git data
+}
+```
+
+## Event Types
+
+Standard panel events:
+
+| Event | Description | Payload |
+|-------|-------------|---------|
+| `file:opened` | File was opened | `{ filePath: string }` |
+| `file:saved` | File was saved | `{ filePath: string }` |
+| `file:deleted` | File was deleted | `{ filePath: string }` |
+| `git:status-changed` | Git status changed | `GitStatus` |
+| `git:commit` | Git commit made | `{ hash: string }` |
+| `git:branch-changed` | Branch changed | `{ branch: string }` |
+| `panel:focus` | Panel gained focus | `{ panelId: string }` |
+| `panel:blur` | Panel lost focus | `{ panelId: string }` |
+| `data:refresh` | Data was refreshed | `{ slices: string[] }` |
+
+## Dependencies
+
+### Peer Dependencies (Required)
+
+These are provided by the host application:
+
+- `react` >= 18.0.0
+- `react-dom` >= 18.0.0
+
+### Optional Peer Dependencies
+
+- `@principal-ade/panel-framework-core` - For advanced panel features
+
+### Bundled Dependencies
+
+Include any libraries unique to your panel:
+
+```json
+{
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "date-fns": "^2.29.0",
+    "your-custom-lib": "^1.0.0"
+  }
+}
+```
+
+These will be bundled into your panel output.
+
+## Troubleshooting
+
+### Panel Not Discovered
+
+Ensure `package.json` has:
+```json
+{
+  "keywords": ["panel-extension"],
+  "main": "dist/panels.bundle.js"
+}
+```
+
+### Build Errors
+
+Check that peer dependencies are externalized in `vite.config.ts`:
+```typescript
+external: ['react', 'react-dom']
+```
+
+### Type Errors
+
+Ensure TypeScript can find types:
+```bash
+bun run typecheck
+```
+
+### Runtime Errors
+
+Check browser console and ensure:
+- Panel ID is unique
+- Required exports are present (`panels` array)
+- Component is a valid React component
+
+## Resources
+
+- [Panel Extension Store Specification V2](https://github.com/principal-ade/panel-framework/blob/main/PANEL_EXTENSION_STORE_SPECIFICATION_V2.md)
+- [Panel Framework Core](https://github.com/principal-ade/panel-framework-core)
+- [Example Implementations](https://github.com/principal-ade/example-panels)
+
+## License
+
+MIT © Your Name
+
+## Contributing
+
+Contributions welcome! Please read the contributing guidelines first.
+
+## Support
+
+For issues and questions:
+- [GitHub Issues](https://github.com/your-org/your-panel-name/issues)
+- [Discussions](https://github.com/your-org/your-panel-name/discussions)

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { PanelDefinition } from './types';
+/**
+ * Export array of panel definitions.
+ * This is the required export for panel extensions.
+ */
+export declare const panels: PanelDefinition[];
+/**
+ * Optional: Called once when the entire package is loaded.
+ * Use this for package-level initialization.
+ */
+export declare const onPackageLoad: () => Promise<void>;
+/**
+ * Optional: Called once when the package is unloaded.
+ * Use this for package-level cleanup.
+ */
+export declare const onPackageUnload: () => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,SAAS,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,eAAe,EAwBnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,qBAEzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,qBAE3B,CAAC"}

package/dist/mocks/panelContext.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { PanelComponentProps, PanelContextValue, PanelActions, PanelEventEmitter, GitStatus } from '../types';
+/**
+ * Mock Git Status for Storybook
+ */
+export declare const mockGitStatus: GitStatus;
+/**
+ * Mock Panel Context for Storybook
+ */
+export declare const createMockContext: (overrides?: Partial<PanelContextValue>) => PanelContextValue;
+/**
+ * Mock Panel Actions for Storybook
+ */
+export declare const createMockActions: (overrides?: Partial<PanelActions>) => PanelActions;
+/**
+ * Mock Event Emitter for Storybook
+ */
+export declare const createMockEvents: () => PanelEventEmitter;
+/**
+ * Create complete mock panel context props
+ * Utility for creating all panel props at once
+ */
+export declare const createMockPanelContext: (contextOverrides?: Partial<PanelContextValue>, actionsOverrides?: Partial<PanelActions>) => PanelComponentProps;
+/**
+ * Mock Panel Props Provider
+ * Wraps components with mock context for Storybook
+ */
+export declare const MockPanelProvider: React.FC<{
+    children: (props: PanelComponentProps) => React.ReactNode;
+    contextOverrides?: Partial<PanelContextValue>;
+    actionsOverrides?: Partial<PanelActions>;
+}>;
+//# sourceMappingURL=panelContext.d.ts.map

package/dist/mocks/panelContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panelContext.d.ts","sourceRoot":"","sources":["../../src/mocks/panelContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EAEjB,SAAS,EACV,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,SAK3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,OAAO,CAAC,iBAAiB,CAAC,KACrC,iBAoDF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,OAAO,CAAC,YAAY,CAAC,KAChC,YAcD,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,iBA6BnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,mBAAmB,OAAO,CAAC,iBAAiB,CAAC,EAC7C,mBAAmB,OAAO,CAAC,YAAY,CAAC,KACvC,mBAMF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC;IACvC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,KAAK,CAAC,SAAS,CAAC;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1C,CAGA,CAAC"}

package/dist/panels/MarkdownPanel.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import 'themed-markdown/dist/index.css';
+import type { PanelComponentProps } from '../types';
+/**
+ * MarkdownPanel - A panel for rendering markdown documents with industry theming
+ *
+ * This panel integrates with the panel framework to:
+ * - Listen to file:opened events
+ * - Read content from the active-file context slice
+ * - Display markdown with themed rendering using DocumentView
+ * - Support view mode switching between document and slides
+ * - Provide font size controls and slide navigation
+ */
+export declare const MarkdownPanel: React.FC<PanelComponentProps>;
+//# sourceMappingURL=MarkdownPanel.d.ts.map

package/dist/panels/MarkdownPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownPanel.d.ts","sourceRoot":"","sources":["../../src/panels/MarkdownPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAuC,MAAM,OAAO,CAAC;AAQ5D,OAAO,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,UAAU,CAAC;AAUrE;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA6UvD,CAAC"}

package/dist/panels.bundle.css

@@ -0,0 +1 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#abb2bf;background:#282c34}.hljs-comment,.hljs-quote{color:#5c6370;font-style:italic}.hljs-doctag,.hljs-keyword,.hljs-formula{color:#c678dd}.hljs-section,.hljs-name,.hljs-selector-tag,.hljs-deletion,.hljs-subst{color:#e06c75}.hljs-literal{color:#56b6c2}.hljs-string,.hljs-regexp,.hljs-addition,.hljs-attribute,.hljs-meta .hljs-string{color:#98c379}.hljs-attr,.hljs-variable,.hljs-template-variable,.hljs-type,.hljs-selector-class,.hljs-selector-attr,.hljs-selector-pseudo,.hljs-number{color:#d19a66}.hljs-symbol,.hljs-bullet,.hljs-link,.hljs-meta,.hljs-selector-id,.hljs-title{color:#61aeee}.hljs-built_in,.hljs-title.class_,.hljs-class .hljs-title{color:#e6c07b}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}.hljs-link{text-decoration:underline}.animated-resizable-layout{width:100%;height:100%;position:relative;background-color:var(--panel-background)}.hybrid-panel{overflow:auto;height:100%;background-color:var(--panel-background)}.panel-content-wrapper{width:100%;height:100%;overflow:auto}.resize-handle{width:8px;background-color:var(--panel-handle);display:flex;justify-content:center;align-items:center;cursor:col-resize;position:relative;transition:background-color .2s,opacity .3s,width .3s}.resize-handle.collapsed{opacity:0;pointer-events:none}.resize-handle:hover{background-color:var(--panel-handle-hover)}.resize-handle:active{background-color:var(--panel-handle-active)}.handle-bar{height:100%;width:100%;display:flex;align-items:center;justify-content:center;position:relative}.collapse-toggle{position:absolute;background:var(--panel-button-bg);border:1px solid var(--panel-button-border);padding:4px 8px;cursor:pointer;color:var(--panel-button-icon);font-size:14px;outline:none;display:flex;align-items:center;justify-content:center;border-radius:4px;z-index:10;transition:all .2s;box-shadow:0 2px 4px #0000001a}.collapse-toggle:hover:not(:disabled){background-color:var(--panel-button-hover);box-shadow:0 2px 6px #00000026}.collapse-toggle:active:not(:disabled){opacity:.8}.three-panel-layout{height:100%;width:100%;display:flex;flex-direction:column;position:relative;background-color:var(--panel-background)}.three-panel-item{display:flex;flex-direction:column;overflow:hidden;position:relative;background-color:var(--panel-background)}.three-panel-item.collapsible-panel{will-change:flex}.three-panel-item.collapsible-panel.animating{pointer-events:none}.three-panel-item.collapsible-panel.collapsed{flex:0!important;min-width:0!important}.three-panel-item.middle-panel{flex:1;min-width:200px}.panel-content-wrapper{flex:1;overflow:auto;will-change:opacity}.resize-handle{position:relative;display:flex;align-items:center;justify-content:center;width:1px!important;cursor:col-resize;background:var(--panel-border);overflow:visible!important}.resize-handle:before{content:"";position:absolute;top:0;bottom:0;left:-10px;right:-10px;background:transparent}.resize-handle:after{content:"";position:absolute;top:0;bottom:0;left:-10px;right:-10px;background:var(--panel-handle);opacity:0;transition:opacity .2s ease;z-index:-1}.resize-handle:hover:after{opacity:1}.resize-handle:hover{background:var(--panel-handle-hover)}.resize-handle:active:after{opacity:1;background:var(--panel-handle-active)}.resize-handle:active{background:var(--panel-handle-active)}.resize-handle.collapsed{pointer-events:none;width:0!important;overflow:hidden}.resize-handle.left-handle.collapsed{margin-right:-1px}.resize-handle.right-handle.collapsed{margin-left:-1px}.handle-bar{position:relative;width:100%;height:100%;display:flex;align-items:center;justify-content:center}.collapse-toggle{position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);width:20px;height:40px;background:var(--panel-button-bg);border:1px solid var(--panel-button-border);border-radius:4px;display:flex;align-items:center;justify-content:center;cursor:pointer;font-size:12px;color:var(--panel-button-icon);transition:all .2s ease;z-index:10;padding:0;line-height:1}.collapse-toggle:hover{background:var(--panel-button-hover)}.collapse-toggle:active{opacity:.8}.collapse-toggle:disabled{opacity:.5;cursor:not-allowed}@media(max-width:768px){.resize-handle:before{left:-8px;right:-8px}.resize-handle:after{left:-8px;right:-8px}.collapse-toggle{width:24px;height:48px;font-size:14px}}