@erd-studio/renderer 0.1.0

package/LICENSE

@@ -0,0 +1,167 @@
+Required Notice: Copyright Liam Wynne (https://github.com/liam-machine)
+Licensor Line of Business: ERD Studio, a visual ERD designer for dbt (https://github.com/liam-machine/erd-studio)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,132 @@
+# @erd-studio/renderer
+
+The entity-relationship diagram canvas from the [ERD Studio](https://github.com/liam-machine/erd-studio) VS Code extension, packaged for reuse. It is built on React Flow and renders a `DisplayDomain` from `@erd-studio/core`: model nodes with their columns and key badges, FK edges with cardinality, annotations, the detail panel and the legend.
+
+Peer dependencies: `react` and `react-dom` 18.3+, `@xyflow/react` 12.4+.
+
+## Entry points
+
+| Import | What it is for |
+|---|---|
+| `@erd-studio/renderer` | Showing a domain: the `ErdCanvas` viewer component (below), plus `transformDomain` (a `DisplayDomain` to React Flow nodes and edges), `pickHandleSides`, `repickHandleSides` / `nodeRect`, and the display, domain and graph types (`DisplayDomain`, `ModelFlowNode`, `FkFlowEdge`, …). |
+| `@erd-studio/renderer/editor` | Everything above plus what a host needs to build a full editor around the canvas, as the extension's webview does: the store (below), the host adapter, `useCanvasGraph`, `CanvasBackdrop`, `canvasNodeTypes` / `canvasEdgeTypes`, the components (`ModelNode`, `FkEdge`, `AnnotationNode`, `AnnotationEdge`, `DetailPanel`, `Legend`, `KeyBadge`, `KeyBadgeGroup`, `DataTypeSelect`, `ColumnRowEditor`), the canvas hooks and the pure helpers. |
+| `@erd-studio/renderer/store` | The canvas store on its own, with no React Flow runtime: `createCanvasSlice`, `createCanvasStore`, `CanvasStoreProvider`, `useEditorStore`, `useEditorStoreApi` and their types. |
+| `@erd-studio/renderer/sizing` | Model node size estimation (`NODE_WIDTH`, `estimateNodeWidth`, `estimateNodeHeight`, `countVisibleColumnRows`, `resolveNodeDimensions`), for layout code that needs node sizes before React Flow has measured them. No components. |
+| `@erd-studio/renderer/styles.css` | The stylesheet: every component's CSS in cascade order, then the theme tokens. It `@import`s `@xyflow/react/dist/style.css`, which your bundler resolves. |
+
+All four JavaScript entry points share their modules, so a store or context created through one is the same one the others see.
+
+## Viewer: `ErdCanvas`
+
+`ErdCanvas` renders a `DisplayDomain` read-only, the way the extension shows a read-only domain: model nodes with their columns and key badges, FK edges, annotations, the minimap, the legend, and the detail panel a click on a model opens. It presents no editing affordances and posts nothing anywhere.
+
+```tsx
+import { useRef, useState } from 'react';
+import { ErdCanvas, type ErdCanvasHandle, type DisplayDomain } from '@erd-studio/renderer';
+import '@erd-studio/renderer/styles.css';
+
+function Diagram({ domain }: { domain: DisplayDomain }) {
+  const canvas = useRef<ErdCanvasHandle>(null);
+  const [moved, setMoved] = useState(false);
+  return (
+    <div style={{ height: 600, position: 'relative' }}>
+      <ErdCanvas ref={canvas} domain={domain} nodesDraggable onLayoutModifiedChange={setMoved} />
+      {moved && <button onClick={() => canvas.current?.resetLayout()}>Reset layout</button>}
+    </div>
+  );
+}
+```
+
+| Prop | |
+|---|---|
+| `domain` | The domain to show. It is rendered read-only whatever its `readOnly` flag says. Missing `layer`, `stage`, `relationships`, `viewConfig`, model `columns` and column `dataType` are filled with defaults. Pass a new object to show a new domain; re-rendering with the same object keeps the reader's view. |
+| `nodesDraggable` | Let readers move model and annotation nodes (default `false`). Moves are never saved; the edges on a moved node re-pick their sides as it moves. |
+| `onLayoutModifiedChange(modified)` | Called when the layout starts or stops differing from the domain's positions (a node moved; `resetLayout()`, a new domain, or a node moved back). |
+| `onReady()` | Called once, after the first nodes are measured and fitted into view (straight away for an empty domain). |
+| `className`, `style` | Applied to the canvas's wrapper element, which fills its parent. |
+
+The ref exposes `resetLayout()`, which puts every node back at its position in the domain with its original edge sides.
+
+Each `ErdCanvas` has its own store, so several can share a page.
+
+## Editor: store and host
+
+The canvas components read their state from the store supplied by the nearest `CanvasStoreProvider`, and post the edits a user makes on the canvas (renaming a column, moving an annotation, changing a cardinality, …) as `CanvasEditMessage`s to the `CanvasHost` supplied by `CanvasEnvironmentProvider`.
+
+```tsx
+import { ReactFlowProvider } from '@xyflow/react';
+import {
+  createCanvasStore,
+  CanvasStoreProvider,
+  CanvasEnvironmentProvider,
+  type CanvasHost,
+} from '@erd-studio/renderer/editor';
+import '@erd-studio/renderer/styles.css';
+
+const store = createCanvasStore({ domain });
+const host: CanvasHost = { postMessage: (edit) => applyEdit(edit) };
+
+<CanvasStoreProvider store={store}>
+  <CanvasEnvironmentProvider host={host}>
+    <ReactFlowProvider>{/* <ReactFlow nodeTypes={canvasNodeTypes} … /> */}</ReactFlowProvider>
+  </CanvasEnvironmentProvider>
+</CanvasStoreProvider>
+```
+
+- Without a `CanvasEnvironmentProvider`, edits go to a no-op host.
+- `CanvasEnvironmentProvider`'s `viewer` flag switches the components to the read-only presentation `ErdCanvas` uses. It is separate from a domain's `readOnly` flag, which the extension sets for the physical stage and which still offers menus such as the key-type picker.
+- A host with more state of its own can build its store from `createCanvasSlice(set)` and pass that to `CanvasStoreProvider`, which is what the extension does.
+- Components used outside a `CanvasStoreProvider` throw.
+
+## CSS variables
+
+The styles are written against VS Code's theme variables. A page that is not a VS Code webview must define these 31 on `:root` (or any ancestor of the canvas). Most have fallbacks, but the canvas only matches your theme when they are set.
+
+```
+--vscode-button-background                 --vscode-font-family
+--vscode-button-foreground                 --vscode-font-size
+--vscode-button-hoverBackground            --vscode-font-weight
+--vscode-charts-green                      --vscode-input-background
+--vscode-charts-purple                     --vscode-input-border
+--vscode-descriptionForeground             --vscode-input-foreground
+--vscode-editor-background                 --vscode-list-activeSelectionBackground
+--vscode-editor-font-family                --vscode-list-activeSelectionForeground
+--vscode-editor-foreground                 --vscode-panel-border
+--vscode-editor-inactiveSelectionBackground --vscode-sideBar-background
+--vscode-editor-selectionBackground        --vscode-textLink-activeForeground
+--vscode-editorGroup-border                --vscode-textLink-foreground
+--vscode-editorHoverWidget-background
+--vscode-editorHoverWidget-border
+--vscode-editorHoverWidget-foreground
+--vscode-editorWarning-foreground
+--vscode-editorWidget-background
+--vscode-errorForeground
+--vscode-focusBorder
+```
+
+These four more are read only by the data-type picker, which appears only while editing a column (never in `ErdCanvas`):
+
+```
+--vscode-dropdown-background   --vscode-dropdown-border
+--vscode-dropdown-foreground   --vscode-list-hoverBackground
+```
+
+Dark-theme variants of a few annotation and legend colours key off `body[data-vscode-theme-kind="vscode-dark"]` (and `vscode-high-contrast`).
+
+The stylesheet does not size the page. Give the element the canvas is mounted in an explicit height.
+
+## Development
+
+This package lives in the `packages/renderer` workspace of the ERD Studio repository. Inside the repository it is consumed from source (TypeScript `paths` and vitest aliases); the published package ships only `dist/`.
+
+```sh
+npm run build -w @erd-studio/renderer       # dist/*.js (esbuild, ESM), dist/styles.css, dist/types/*.d.ts
+npm run typecheck -w @erd-studio/renderer
+npm test -w @erd-studio/renderer
+```
+
+The sources import each other without file extensions, as bundlers expect. The build's last step (`scripts/dts-extensions.mjs`) adds `.js` to the relative imports in the emitted declarations, so the types also work for consumers on `moduleResolution: node16` or `nodenext`.
+
+## License
+
+[PolyForm Shield 1.0.0](./LICENSE), the same licence as the rest of the repository.