@dlh.io/dlh-erd-viewer-deux 0.1.1 → 0.1.2

package/README.md

@@ -7,4 +7,413 @@ Popular ERD viewer designed by DLH.io originally to provide a better ERD experie
 Future features and enhancements are taken by reqeust and PR.
 
 ## More about DLH.io
-ETL/ELT, data integration, API solutions, and data engineering for reports, dashboards, and AI use cases. See more at [DLH.io](DLH.io)
+ETL/ELT, data integration, API solutions, and data engineering for reports, dashboards, and AI use cases. See more at [DLH.io](DLH.io)
+
+# @dlh.io/dlh-erd-viewer-deux
+
+A React component for visualizing database Entity-Relationship Diagrams (ERD) from DBML and TBLS schema formats.
+
+## Installation
+
+```bash
+npm install @dlh.io/dlh-erd-viewer-deux
+```
+
+## Quick Start
+
+```tsx
+import { ERDViewer } from '@dlh.io/dlh-erd-viewer-deux';
+import '@dlh.io/dlh-erd-viewer-deux/styles.css';
+
+const dbmlSchema = `
+Table users {
+  id integer [pk]
+  username varchar(255) [not null]
+  email varchar(255) [not null]
+}
+
+Table posts {
+  id integer [pk]
+  title varchar(255) [not null]
+  author_id integer [ref: > users.id]
+}
+`;
+
+function App() {
+  return (
+    <div style={{ width: '100%', height: '600px' }}>
+      <ERDViewer
+        format="dbml"
+        content={dbmlSchema}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `format` | `'dbml' \| 'tbls'` | The schema format of the content |
+| `content` | `string` | The schema content to parse and display |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `''` | Additional CSS class names for the container |
+| `style` | `React.CSSProperties` | - | Inline styles for the container |
+| `positions` | `PositionMetadata` | - | Pre-defined table positions for the layout |
+| `devMode` | `boolean` | `false` | Enable developer mode with position copying tools |
+| `draggable` | `boolean` | `false` | Allow users to drag and reposition tables |
+| `showMinimap` | `boolean` | `true` | Show or hide the minimap navigation |
+| `showInfoPanel` | `boolean` | `true` | Show or hide the information side panel |
+| `displayMode` | `DisplayMode` | `'all'` | Column display mode: `'all'`, `'keys'`, or `'tableOnly'` |
+| `layoutAlgorithm` | `LayoutAlgorithm` | `'default'` | Layout algorithm for table positioning |
+| `reverseAnimationFlow` | `boolean` | `false` | Reverse the animation flow direction on connector lines |
+| `tableOnlyConnectionMode` | `TableOnlyConnectionMode` | `'center'` | Connection mode when in table-only display |
+| `toolbarAlignment` | `PanelAlignment` | `'center'` | Toolbar position: `'left'`, `'center'`, or `'right'` |
+| `infoPaneAlignment` | `PanelAlignment` | `'right'` | Info panel position: `'left'` or `'right'` |
+| `printExportLogo` | `string` | DLH logo | URL of logo to watermark on exports |
+| `printExportLogoPosition` | `WatermarkPosition` | `'top-left'` | Position of watermark: `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'` |
+| `theme` | `ERDViewerTheme` | - | Theme overrides via CSS custom properties |
+
+### Callback Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onExport` | `(format: 'png' \| 'pdf') => void` | Called when diagram is exported |
+| `onPositionsChange` | `(positions: PositionMetadata) => void` | Called when table positions change (in devMode or draggable) |
+| `onTableSelect` | `(table: Table \| null) => void` | Called when a table is selected |
+| `onColumnSelect` | `(table: Table \| null, columnName: string \| null) => void` | Called when a column is selected |
+| `onDisplayModeChange` | `(mode: DisplayMode) => void` | Called when display mode changes |
+| `onLayoutAlgorithmChange` | `(algorithm: LayoutAlgorithm) => void` | Called when layout algorithm changes |
+
+## Types
+
+### DisplayMode
+
+Controls which columns are shown in table cards:
+
+```typescript
+type DisplayMode = 'all' | 'keys' | 'tableOnly';
+```
+
+- `'all'` - Show all columns
+- `'keys'` - Show only primary and foreign key columns
+- `'tableOnly'` - Show only table names (no columns)
+
+### LayoutAlgorithm
+
+Controls how tables are automatically positioned:
+
+```typescript
+type LayoutAlgorithm = 'default' | 'hierarchical' | 'force' | 'grid' | 'spiral' | 'proximity';
+```
+
+- `'default'` - Dagre-based top-to-bottom layout
+- `'hierarchical'` - Left-to-right hierarchical layout
+- `'force'` - Force-directed layout
+- `'grid'` - Grid pattern layout
+- `'spiral'` - Spiral pattern layout
+- `'proximity'` - Groups related tables together
+
+### PanelAlignment
+
+```typescript
+type PanelAlignment = 'left' | 'center' | 'right';
+```
+
+### WatermarkPosition
+
+```typescript
+type WatermarkPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+```
+
+### PositionMetadata
+
+Pre-defined positions for tables:
+
+```typescript
+interface PositionMetadata {
+  schemaFormat?: 'dbml' | 'tbls';
+  capturedAt?: string;
+  version?: string;
+  positions: TablePosition[];
+}
+
+interface TablePosition {
+  tableName: string;
+  x: number;
+  y: number;
+}
+```
+
+## CSS Customization
+
+The component uses CSS custom properties (variables) for theming. You can override these in your application's CSS:
+
+```css
+:root {
+  /* Core colors */
+  --erd-primary: #3b82f6;
+  --erd-secondary: #64748b;
+  --erd-background: #ffffff;
+  --erd-surface: #f8fafc;
+  --erd-border: #e2e8f0;
+  --erd-text: #1e293b;
+  --erd-text-muted: #64748b;
+  --erd-highlight: #3b82f6;
+
+  /* Key indicators */
+  --erd-pk: #eab308;           /* Primary key color */
+  --erd-fk: #8b5cf6;           /* Foreign key color */
+
+  /* Typography */
+  --erd-font-family: ui-sans-serif, system-ui, sans-serif;
+  --erd-font-mono: ui-monospace, monospace;
+
+  /* Toolbar */
+  --erd-toolbar-text: #1e293b;
+
+  /* Connector lines */
+  --erd-edge-color: #64748b;
+  --erd-edge-highlight-color: #3b82f6;
+  --erd-animation-color: #3b82f6;
+
+  /* Table cards */
+  --erd-table-header-bg: #3b82f6;
+  --erd-table-header-text: #ffffff;
+  --erd-table-column-bg: #ffffff;
+  --erd-table-column-highlight-bg: #eff6ff;
+
+  /* Info panel */
+  --erd-info-panel-bg: #ffffff;
+  --erd-info-panel-header-bg: #f8fafc;
+}
+```
+
+### Using the theme prop
+
+You can also pass theme overrides directly via the `theme` prop:
+
+```tsx
+<ERDViewer
+  format="dbml"
+  content={schema}
+  theme={{
+    '--erd-primary': '#10b981',
+    '--erd-highlight': '#10b981',
+    '--erd-table-header-bg': '#10b981',
+  }}
+/>
+```
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { ERDViewer } from '@dlh.io/dlh-erd-viewer-deux';
+import '@dlh.io/dlh-erd-viewer-deux/styles.css';
+
+function BasicExample() {
+  const schema = `
+    Table users {
+      id integer [pk]
+      name varchar(255)
+    }
+  `;
+
+  return (
+    <div style={{ width: '100%', height: '500px' }}>
+      <ERDViewer format="dbml" content={schema} />
+    </div>
+  );
+}
+```
+
+### With Custom Layout and Display Mode
+
+```tsx
+function CustomLayoutExample() {
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      layoutAlgorithm="hierarchical"
+      displayMode="keys"
+      toolbarAlignment="left"
+    />
+  );
+}
+```
+
+### With Selection Callbacks
+
+```tsx
+function SelectionExample() {
+  const handleTableSelect = (table) => {
+    if (table) {
+      console.log('Selected table:', table.name);
+    }
+  };
+
+  const handleColumnSelect = (table, columnName) => {
+    if (table && columnName) {
+      console.log(`Selected column: ${table.name}.${columnName}`);
+    }
+  };
+
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      onTableSelect={handleTableSelect}
+      onColumnSelect={handleColumnSelect}
+    />
+  );
+}
+```
+
+### With Custom Export Watermark
+
+```tsx
+function ExportExample() {
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      printExportLogo="https://example.com/my-logo.png"
+      printExportLogoPosition="bottom-right"
+      onExport={(format) => console.log(`Exported as ${format}`)}
+    />
+  );
+}
+```
+
+### Developer Mode for Position Capture
+
+Enable `devMode` to capture table positions for later use:
+
+```tsx
+function DevModeExample() {
+  const handlePositionsChange = (positions) => {
+    // Save positions to use as the `positions` prop later
+    console.log(JSON.stringify(positions, null, 2));
+  };
+
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      devMode={true}
+      draggable={true}
+      onPositionsChange={handlePositionsChange}
+    />
+  );
+}
+```
+
+### Using Pre-defined Positions
+
+```tsx
+const savedPositions = {
+  schemaFormat: 'dbml',
+  positions: [
+    { tableName: 'users', x: 100, y: 100 },
+    { tableName: 'posts', x: 400, y: 100 },
+    { tableName: 'comments', x: 400, y: 300 },
+  ],
+};
+
+function PositionedExample() {
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      positions={savedPositions}
+    />
+  );
+}
+```
+
+### Dark Theme Example
+
+```tsx
+function DarkThemeExample() {
+  return (
+    <ERDViewer
+      format="dbml"
+      content={schema}
+      theme={{
+        '--erd-background': '#1e293b',
+        '--erd-surface': '#334155',
+        '--erd-border': '#475569',
+        '--erd-text': '#f1f5f9',
+        '--erd-text-muted': '#94a3b8',
+        '--erd-table-header-bg': '#3b82f6',
+        '--erd-table-column-bg': '#1e293b',
+        '--erd-toolbar-text': '#f1f5f9',
+      }}
+    />
+  );
+}
+```
+
+### Next.js Usage
+
+For Next.js applications, use dynamic import with SSR disabled:
+
+```tsx
+import dynamic from 'next/dynamic';
+
+const ERDViewer = dynamic(
+  () => import('@dlh.io/dlh-erd-viewer-deux').then((mod) => mod.ERDViewer),
+  { ssr: false }
+);
+
+// Import CSS in your layout or page
+import '@dlh.io/dlh-erd-viewer-deux/styles.css';
+
+export default function Page() {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <ERDViewer format="dbml" content={schema} />
+    </div>
+  );
+}
+```
+
+## Supported Schema Formats
+
+### DBML
+
+The component supports [DBML (Database Markup Language)](https://dbml.dbdiagram.io/home/) format:
+
+```dbml
+Table users {
+  id integer [pk, increment]
+  username varchar(255) [not null, unique]
+  email varchar(255) [not null]
+  created_at timestamp [default: `now()`]
+}
+
+Table posts {
+  id integer [pk, increment]
+  title varchar(255) [not null]
+  content text
+  author_id integer [ref: > users.id]
+}
+```
+
+### TBLS
+
+The component also supports [TBLS](https://github.com/k1LoW/tbls) JSON format for schema documentation.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dlh.io/dlh-erd-viewer-deux",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A React component for viewing database ERD diagrams from DBML and TBLS formats",
   "type": "module",
   "main": "dist/index.cjs",
@@ -73,6 +73,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/datalakehouse/dlh-erd-viewer-deux.git"
+    "url": "git+https://github.com/datalakehouse/dlh-erd-viewer-deux.git"
   }
 }