polly-graph 0.1.3 → 0.1.5

package/README.md

@@ -4,14 +4,10 @@ Reusable D3-based graph visualization SDK with configurable nodes, links, labels
 
 ## Features
 
-* Interactive force-directed graph rendering
-* Configurable nodes, links, and labels
-* Hover states with tooltip support
-* Node selection support
-* Drag and zoom interactions
-* Arrow markers and relationship visualization
-* Framework-agnostic API
-* Angular and React compatible
+* **Managed Root Architecture**: Provide one host element; the SDK internally manages the SVG canvas and the HTML UI overlay.
+* **Smart Positioning**: Controls and legends use a class-based system (`pg-pos-top-right`) with CSS variable overrides for precision offsets.
+* **Declarative Styling**: Fully customizable node and link aesthetics via style objects.
+* **Animated UI**: Legends feature directional "retraction" animations that sync with their anchor position.
 
 ---
 
@@ -21,89 +17,46 @@ Reusable D3-based graph visualization SDK with configurable nodes, links, labels
 npm install polly-graph
 ```
 
-No separate D3 installation is required.
-
 ---
 
 ## Basic Usage
 
 ### HTML
-
 ```html
-<div class="graph-wrapper">
-  <svg id="graph-container"></svg>
-</div>
+<div id="graph-viewport" style="position: relative; width: 100%; height: 600px;"></div>
 ```
 
 ### TypeScript
-
 ```ts
-import {
-  createGraph,
-  GraphNode,
-  GraphLink,
-} from 'polly-graph';
-
-const container = document.getElementById(
-  'graph-container',
-) as SVGSVGElement;
-
-const nodes: GraphNode[] = [
-  {
-    id: 'users',
-    label: 'Users',
-    style: {
-      radius: 24,
-      fill: '#7c3aed',
-      stroke: '#6d28d9',
-      strokeWidth: 2,
-      textColor: '#ffffff',
-    },
-  },
-  {
-    id: 'orders',
-    label: 'Orders',
-    style: {
-      radius: 24,
-      fill: '#2563eb',
-      stroke: '#1d4ed8',
-      strokeWidth: 2,
-      textColor: '#ffffff',
-    },
-  },
-];
-
-const links: GraphLink[] = [
-  {
-    source: 'users',
-    target: 'orders',
-    label: 'has_many',
-    style: {
-      stroke: '#94a3b8',
-      strokeWidth: 2,
-      opacity: 1,
-    },
-  },
-];
+import { createGraph } from 'polly-graph';
+
+const viewport = document.getElementById('graph-viewport') as HTMLElement;
 
 const graph = createGraph({
-  container,
-  nodes,
-  links,
-  interaction: {
-    drag: {
-      enabled: true,
-    },
-    hover: {
-      enabled: true,
-      tooltip: {
-        enabled: true,
-      },
-    },
-    selection: {
-      enabled: true,
-    },
-  },
+  container: viewport,
+  nodes: [
+    { 
+      id: 'n1', 
+      label: 'Core Service', 
+      style: { 
+        radius: 30, 
+        fill: '#7c3aed', 
+        stroke: '#5b21b6', 
+        strokeWidth: 2,
+        textColor: '#ffffff',
+        fontSize: 12
+      } 
+    }
+  ],
+  links: [
+    { 
+      source: 'n1', 
+      target: 'n2', 
+      style: { stroke: '#94a3b8', strokeWidth: 2, opacity: 0.6 } 
+    }
+  ],
+  controls: { enabled: true, position: 'top-right' },
+  legend: { enabled: true, position: 'bottom-left' }
 });
 
 graph.render();
@@ -111,107 +64,77 @@ graph.render();
 
 ---
 
-## Hover + Tooltip Example
-
-```ts
-interaction: {
-  hover: {
-    enabled: true,
-    tooltip: {
-      enabled: true,
-      theme: 'dark',
-    },
-    nodeStyle: {
-      stroke: '#16a34a',
-      strokeWidth: 3,
-      opacity: 1,
-    },
-  },
-}
-```
-
----
+## Styling & Customization
 
-## Selection Example
+### Node Styles
+Every node can have a unique appearance defined in its `style` object.
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `radius` | `number` | The size of the node. |
+| `fill` | `string` | Background color (hex/rgb). |
+| `stroke` | `string` | Border color. |
+| `strokeWidth`| `number` | Thickness of the border. |
+| `textColor` | `string` | Label color. |
 
+### Link Styles
+Links support custom coloring, thickness, and arrow markers.
 ```ts
-selection: {
-  enabled: true,
-  multiSelect: false,
-  nodeStyle: {
-    stroke: '#f59e0b',
-    strokeWidth: 4,
-    opacity: 1,
-  },
+style: {
+  stroke: '#cbd5e1',
+  strokeWidth: 1.5,
+  opacity: 0.8,
+  dashed: false // Coming soon
 }
 ```
 
 ---
 
-## Angular Example
+## Positioning Logic
 
-### Template
+The UI components (Controls & Legend) use a hybrid positioning system.
 
-```html
-<div class="graph-wrapper">
-  <svg #svgRef></svg>
-</div>
-```
+### 1. Corner Anchoring
+Use the `position` property to anchor elements to viewport corners. The SDK applies classes like `.pg-pos-top-right` which handles the layout logic.
 
-### Component
+Available positions:
+* `top-left`
+* `top-right`
+* `bottom-left`
+* `bottom-right`
 
-```ts
-this.graph = createGraph({
-  container: this.svgRef.nativeElement,
-  nodes,
-  links,
-  interaction,
-});
+### 2. Custom Offsets
+While the corners provide the anchor, you can use the `offset` object for fine-tuning. This values are passed into CSS variables `--pg-offset-x` and `--pg-offset-y` internally.
 
-this.graph.render();
+```ts
+controls: {
+  position: 'top-right',
+  offset: { x: 24, y: 24 } // 24px away from the top and right edges
+}
 ```
 
----
-
-## Public API
-
-### Main Exports
-
-* `createGraph`
-* `GraphInstance`
-* `GraphNode`
-* `GraphLink`
-* `GraphConfig`
-* `GraphInteractionConfig`
+### 3. Directional Legend Retraction
+The Legend component is aware of its position.
+* If anchored **Left**: It collapses to the left; the toggle icon points **Right** to expand.
+* If anchored **Right**: It collapses to the right; the toggle icon points **Left** to expand.
 
 ---
 
-## Development
+## Framework Integration
 
-```bash
-npm install
-npm run dev
-npm run build
-npm run lint
-npm run typecheck
-npm run test
+### Angular
+```ts
+@ViewChild('viewport') viewport!: ElementRef;
+
+ngAfterViewInit() {
+  this.graph = createGraph({
+    container: this.viewport.nativeElement,
+    // ... config
+  });
+  this.graph.render();
+}
 ```
 
 ---
 
-## Publish Checklist
-
-* Package name available on npm
-* README completed
-* LICENSE added
-* Build succeeds
-* Tests pass
-* npm token configured
-* GitHub workflow passes
-* Repository is public
-
----
-
 ## License
-
-MIT
+MIT