@filekit-studio/diagram 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 FileKit-Studio
+
+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

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @filekit-studio/diagram
+
+> Declarative Diagram-as-Code & JSON graph compiler for `@filekit-studio/sketch`.
+
+[![npm version](https://img.shields.io/npm/v/@filekit-studio/diagram.svg)](https://www.npmjs.com/package/@filekit-studio/diagram)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`@filekit-studio/diagram` lets you generate and render beautiful hand-drawn whiteboards, architecture diagrams, and flowcharts directly from declarative JSON or Diagram-as-Code in React and Next.js.
+
+- ⚡️ **Zero Coordinates Required**: Provide nodes, edges, and clusters — the deterministic DAG layout engine positions and aligns everything automatically.
+- 🎨 **Sketch Aesthetics**: Powered by `@filekit-studio/sketch`, rendering organic hand-drawn shapes, rough fills, and magnetic connector arrows.
+- 📐 **Directional Flows**: Supports Left-to-Right (`LR`), Top-to-Bottom (`TB`), Right-to-Left (`RL`), and Bottom-to-Top (`BT`).
+- 📦 **Excalidraw Native**: Direct conversion from `.excalidraw` schema files and element arrays.
+- 🔒 **100% Client-Side**: Zero server calls, zero tracking, works fully offline.
+
+---
+
+## Installation
+
+```bash
+bun add @filekit-studio/diagram @filekit-studio/sketch
+# or
+npm install @filekit-studio/diagram @filekit-studio/sketch
+# or
+pnpm add @filekit-studio/diagram @filekit-studio/sketch
+```
+
+Ensure `@filekit-studio/sketch/styles.css` is imported in your application:
+
+```tsx
+import '@filekit-studio/sketch/styles.css'
+```
+
+---
+
+## Quickstart
+
+### 1. Declarative `<Diagram />` Component
+
+```tsx
+'use client'
+
+import React from 'react'
+import { Diagram, type DiagramData } from '@filekit-studio/diagram'
+import '@filekit-studio/sketch/styles.css'
+
+const architecture: DiagramData = {
+  title: 'Cloud Payment Pipeline',
+  direction: 'LR',
+  nodes: [
+    {
+      id: 'client',
+      label: 'Client Browser\n(React / Next.js)',
+      shape: 'rectangle',
+      color: 'indigo',
+      badge: 'FRONTEND',
+    },
+    {
+      id: 'gateway',
+      label: 'API Gateway',
+      description: 'Kong / Cloudflare',
+      shape: 'rounded',
+      color: 'blue',
+    },
+    {
+      id: 'auth',
+      label: 'Auth Service',
+      description: 'JWT / OAuth2',
+      shape: 'diamond',
+      color: 'amber',
+    },
+    {
+      id: 'db',
+      label: 'Primary Database\n(PostgreSQL)',
+      shape: 'cylinder',
+      color: 'emerald',
+      badge: 'STORAGE',
+    },
+  ],
+  edges: [
+    { from: 'client', to: 'gateway', label: 'HTTPS POST' },
+    { from: 'gateway', to: 'auth', label: 'Verify Token' },
+    { from: 'auth', to: 'db', label: 'SQL Query' },
+  ],
+  groups: [
+    {
+      id: 'backend',
+      label: 'Internal VPC Cluster',
+      nodeIds: ['gateway', 'auth', 'db'],
+      color: 'indigo',
+    },
+  ],
+}
+
+export default function ArchitectureDoc() {
+  return (
+    <div className="w-full h-[500px] rounded-xl overflow-hidden border">
+      <Diagram
+        data={architecture}
+        mode="viewer"
+        theme="system"
+        autoFit={true}
+        showCopyButton={true}
+      />
+    </div>
+  )
+}
+```
+
+---
+
+### 2. Programmatic Compilation (`diagramToSketch`)
+
+If you want to compile graph JSON into a `SketchDocument` to save or manipulate:
+
+```tsx
+import { diagramToSketch } from '@filekit-studio/diagram'
+
+const sketchDoc = diagramToSketch(architecture, {
+  direction: 'LR',
+  nodeSpacing: 70,
+  rankSpacing: 130,
+})
+
+console.log(sketchDoc.elements) // Array of SketchBoardElement objects
+```
+
+---
+
+### 3. Rendering Excalidraw JSON Files
+
+```tsx
+import { Diagram } from '@filekit-studio/diagram'
+import excalidrawFile from './diagram.excalidraw.json'
+
+export function ExcalidrawViewer() {
+  return (
+    <div className="w-full h-[600px]">
+      <Diagram data={excalidrawFile} mode="viewer" autoFit={true} />
+    </div>
+  )
+}
+```
+
+---
+
+## `<Diagram />` Props Reference
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `data` | `DiagramData \| string` | *required* | Diagram specification object or JSON string. |
+| `mode` | `'viewer' \| 'editor'` | `'viewer'` | Display mode: clean doc viewer or full whiteboard studio. |
+| `direction` | `'TB' \| 'BT' \| 'LR' \| 'RL'` | `'LR'` | Flow direction for the DAG auto-layout engine. |
+| `uiConfig` | `SketchUIConfig` | `{}` | Granular toggle flags for all 54 UI controls and menus. |
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Color theme mode. |
+| `canvasBackground` | `string` | `'#f0f4f8'` | Hex background color override. |
+| `gridStyle` | `'grid' \| 'dots' \| 'cross' \| 'none'` | `'dots'` | Canvas grid pattern. |
+| `autoFit` | `boolean` | `true` | Scale and center elements to fit container on mount. |
+| `interactive` | `boolean` | `true` | Allow click-and-drag panning and wheel zooming. |
+| `showCopyButton` | `boolean` | `true` | Display 1-click clipboard PNG image export button. |
+| `showZoomControls` | `boolean` | `false` | Display zoom percentage and +/- buttons in corner. |
+| `layoutOptions` | `DiagramLayoutOptions` | `{}` | Fine-tuning for spacing, margins, and padding. |
+| `controllerRef` | `Ref<SketchController>` | `undefined` | Ref to imperative controller methods (`zoomToFit`, etc.). |
+
+---
+
+## License
+
+MIT © [FileKit Studio](https://tools.kanaddev.me)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.