@bruno00o/graph 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,121 @@
+<div align="center">
+<a href="https://npmjs.com/package/@bruno00o/graph" target="_parent">
+<img alt="npm version" src="https://img.shields.io/npm/v/@bruno00o/graph.svg" />
+</a>
+<a href="https://npmjs.com/package/@bruno00o/graph" target="_parent">
+<img alt="npm downloads" src="https://img.shields.io/npm/dm/@bruno00o/graph.svg" />
+</a>
+<a href="https://bundlephobia.com/result?p=@bruno00o/graph" target="_parent">
+<img alt="bundle size" src="https://badgen.net/bundlephobia/minzip/@bruno00o/graph" />
+</a>
+<a href="https://github.com/bruno00o/graph/actions/workflows/ci.yml" target="_parent">
+<img alt="CI" src="https://github.com/bruno00o/graph/actions/workflows/ci.yml/badge.svg" />
+</a>
+<a href="./LICENSE" target="_parent">
+<img alt="MIT license" src="https://img.shields.io/npm/l/@bruno00o/graph.svg" />
+</a>
+</div>
+
 # @bruno00o/graph
 
 Framework-agnostic, typed graph visualization rendered with WebGL2.
 
-Early development: nothing is usable yet.
+- Smooth with 50,000 nodes and 100,000 edges, picking included
+- Declarative marks: map your fields to color, size, labels, arrows and dashes through shared scales, with types inferred from your data
+- Live sources: pass a TanStack DB collection as is, or anything with `subscribeChanges`, and only what changed is redrawn
+- Named states (selection, hover, focus and your own) resolved on the GPU
+- Images and icons clipped to the node shape, corner badges, parallel edges and self loops
+- Drag, pan, zoom, multiple selection and lasso out of the box, plus keyboard navigation announced to screen readers
+- Themed with CSS variables, light and dark
+- A framework-agnostic core with a thin React adapter, plus TanStack DB and TanStack Query integrations
+
+> Early development: the API may still change before 1.0.
+
+## Install
+
+```sh
+pnpm add @bruno00o/graph
+```
+
+| Entry point                 | Contents                                                         | Peer dependency        |
+| --------------------------- | ---------------------------------------------------------------- | ---------------------- |
+| `@bruno00o/graph`           | `defineGraph`, `nodes`, `edges`, `mountGraph`                    |                        |
+| `@bruno00o/graph/react`     | `<Graph>`, `useGraph`, `useGraphState`, `useGraphEvent`          | `react` 19             |
+| `@bruno00o/graph/db`        | `persistPositions` for TanStack DB collections                   | `@tanstack/db`         |
+| `@bruno00o/graph/query`     | `createExploration` for neighborhoods loaded with TanStack Query | `@tanstack/query-core` |
+| `@bruno00o/graph/theme.css` | Default light and dark theme                                     |                        |
+
+## Quick start
+
+```ts
+import { defineGraph, edges, mountGraph, nodes } from '@bruno00o/graph'
+import '@bruno00o/graph/theme.css'
+
+type Item = { id: string; label: string; group: string; weight: number }
+type Link = { id: string; from: string; to: string }
+
+const definition = defineGraph({
+  marks: [
+    edges<Link>(links, { source: 'from', target: 'to', arrow: 'target' }),
+    nodes<Item>(items, { color: 'group', size: 'weight', label: 'label' }),
+  ],
+  states: { muted: { opacity: 0.2, label: false } },
+})
+
+const graph = mountGraph(container, { definition, ariaLabel: 'Sample graph' })
+
+graph.on('click', ({ target }) => {
+  if (target?.kind === 'node') graph.view.fit([target.key], { duration: 400 })
+})
+graph.states.set('muted', { nodes: ['n4', 'n7'] })
+```
+
+With React:
+
+```tsx
+import { defineGraph, edges, nodes } from '@bruno00o/graph'
+import { Graph, useGraphState } from '@bruno00o/graph/react'
+import { useMemo } from 'react'
+
+function Hovered() {
+  const hovered = useGraphState((state) => state.hovered)
+  return <output>{hovered?.kind === 'node' ? String(hovered.key) : ''}</output>
+}
+
+export function SampleGraph({ items, links }: { items: Item[]; links: Link[] }) {
+  const definition = useMemo(
+    () =>
+      defineGraph({
+        marks: [
+          edges(links, { source: 'from', target: 'to' }),
+          nodes(items, { color: 'group', label: 'label' }),
+        ],
+      }),
+    [items, links],
+  )
+  return (
+    <Graph definition={definition} ariaLabel="Sample graph" style={{ height: 480 }}>
+      <Hovered />
+    </Graph>
+  )
+}
+```
+
+A TanStack DB collection is a live source: pass it to a mark and its changes arrive without a new definition.
+
+```ts
+nodes(itemsCollection, { color: 'group', label: 'label' })
+```
+
+## Examples
+
+The [`examples`](./examples) folder holds runnable examples: vanilla and React graphs, images and badges, parallel edges and loops, collaboration across tabs with TanStack DB, and neighborhood exploration with TanStack Query. Run them with `pnpm install && pnpm dev`.
+
+## Get Involved
+
+- Issues and pull requests are welcome.
+- `pnpm verify` runs lint, types, tests, the build and package checks.
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/db.d.ts

@@ -1,5 +1,5 @@
-import { r as GraphInstance } from "./mount-graph-B88WGOQu.js";
-import { O as Point, _ as Key, d as FieldOf } from "./types-D6b86Rt1.js";
+import { i as GraphInstance } from "./mount-graph-DQLST9-_.js";
+import { _ as Key, d as FieldOf, k as Point } from "./types-BaflHDaf.js";
 import { Collection, MutationFn, Strategy } from "@tanstack/db";
 export interface PersistPositionsOptions<T extends object, TKey extends string | number> {
   readonly collection: Collection<T, TKey>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ResolvedTransitions, C as NodeMark, D as NumberScaleType, E as NumberScale, F as StateStyle, I as StateStyles, L as Style, M as SelectMode, N as SourceChange, O as Point, P as SourceSubscription, R as TransitionOptions, S as Mark, T as NodeShape, _ as Key, a as Channel, b as LabelOptions, c as EdgeDash, d as FieldOf, f as FreeState, g as InteractionOptions, h as GraphDefinitionOptions, i as BuiltInState, j as ScalesOptions, k as ResolvedInteraction, l as EdgeMark, m as GraphDefinition, n as Badge, o as ColorScale, p as GraphData, r as BadgeCorner, s as EdgeArrow, t as Accessor, u as EdgeOptions, v as KeyChannel, w as NodeOptions, x as LiveSource, y as KeyFieldOf, z as View } from "./types-D6b86Rt1.js";
-import { C as PositionOrigin, S as GraphTargetEvent, _ as GraphEventName, a as GraphSelection, b as GraphPositionEvent, c as GraphStore, d as ViewOptions, f as mountGraph, g as GraphEventHandler, h as GraphDragEvent, i as GraphPositions, l as GraphView, m as ElementKeysInput, n as GraphElement, o as GraphState, p as ElementKeys, r as GraphInstance, s as GraphStates, t as FitOptions, u as MountGraphOptions, v as GraphEvents, x as GraphTarget, y as GraphPointerEvent } from "./mount-graph-B88WGOQu.js";
+import { A as ResolvedInteraction, B as View, C as NodeImage, D as NumberScale, E as NodeShape, F as SourceSubscription, I as StateStyle, L as StateStyles, M as ScalesOptions, N as SelectMode, O as NumberScaleType, P as SourceChange, R as Style, S as Mark, T as NodeOptions, _ as Key, a as Channel, b as LabelOptions, c as EdgeDash, d as FieldOf, f as FreeState, g as InteractionOptions, h as GraphDefinitionOptions, i as BuiltInState, j as ResolvedTransitions, k as Point, l as EdgeMark, m as GraphDefinition, n as Badge, o as ColorScale, p as GraphData, r as BadgeCorner, s as EdgeArrow, t as Accessor, u as EdgeOptions, v as KeyChannel, w as NodeMark, x as LiveSource, y as KeyFieldOf, z as TransitionOptions } from "./types-BaflHDaf.js";
+import { C as GraphTarget, S as GraphPositionEvent, T as PositionOrigin, _ as GraphEventHandler, a as GraphPositions, b as GraphFocusEvent, c as GraphStates, d as MountGraphOptions, f as ViewOptions, g as GraphDragEvent, h as ElementKeysInput, i as GraphInstance, l as GraphStore, m as ElementKeys, n as GraphElement, o as GraphSelection, p as mountGraph, r as GraphFocus, s as GraphState, t as FitOptions, u as GraphView, v as GraphEventName, w as GraphTargetEvent, x as GraphPointerEvent, y as GraphEvents } from "./mount-graph-DQLST9-_.js";
 export declare function defineGraph<S extends string = never>(options: GraphDefinitionOptions<S>): GraphDefinition<S>;
 export declare function nodes<T>(data: LiveSource<T>, options?: NodeOptions<NoInfer<T>>): NodeMark<T>;
 export declare function nodes<T extends {
@@ -15,5 +15,5 @@ export declare function edges<T extends {
 export declare function edges<T>(data: Iterable<T>, options: EdgeOptions<NoInfer<T>> & {
   readonly key: KeyChannel<NoInfer<T>>;
 }): EdgeMark<T>;
-export { type Accessor, type Badge, type BadgeCorner, type BuiltInState, type Channel, type ColorScale, type EdgeArrow, type EdgeDash, type EdgeMark, type EdgeOptions, type ElementKeys, type ElementKeysInput, type FieldOf, type FitOptions, type FreeState, type GraphData, type GraphDefinition, type GraphDefinitionOptions, type GraphDragEvent, type GraphElement, type GraphEventHandler, type GraphEventName, type GraphEvents, type GraphInstance, type GraphPointerEvent, type GraphPositionEvent, type GraphPositions, type GraphSelection, type GraphState, type GraphStates, type GraphStore, type GraphTarget, type GraphTargetEvent, type GraphView, type InteractionOptions, type Key, type KeyChannel, type KeyFieldOf, type LabelOptions, type LiveSource, type Mark, type MountGraphOptions, type NodeMark, type NodeOptions, type NodeShape, type NumberScale, type NumberScaleType, type Point, type PositionOrigin, type ResolvedInteraction, type ResolvedTransitions, type ScalesOptions, type SelectMode, type SourceChange, type SourceSubscription, type StateStyle, type StateStyles, type Style, type TransitionOptions, type View, type ViewOptions, mountGraph };
+export { type Accessor, type Badge, type BadgeCorner, type BuiltInState, type Channel, type ColorScale, type EdgeArrow, type EdgeDash, type EdgeMark, type EdgeOptions, type ElementKeys, type ElementKeysInput, type FieldOf, type FitOptions, type FreeState, type GraphData, type GraphDefinition, type GraphDefinitionOptions, type GraphDragEvent, type GraphElement, type GraphEventHandler, type GraphEventName, type GraphEvents, type GraphFocus, type GraphFocusEvent, type GraphInstance, type GraphPointerEvent, type GraphPositionEvent, type GraphPositions, type GraphSelection, type GraphState, type GraphStates, type GraphStore, type GraphTarget, type GraphTargetEvent, type GraphView, type InteractionOptions, type Key, type KeyChannel, type KeyFieldOf, type LabelOptions, type LiveSource, type Mark, type MountGraphOptions, type NodeImage, type NodeMark, type NodeOptions, type NodeShape, type NumberScale, type NumberScaleType, type Point, type PositionOrigin, type ResolvedInteraction, type ResolvedTransitions, type ScalesOptions, type SelectMode, type SourceChange, type SourceSubscription, type StateStyle, type StateStyles, type Style, type TransitionOptions, type View, type ViewOptions, mountGraph };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as freeStateNames, r as maxFreeStates, t as mountGraph } from "./mount-graph-BHwq3LOr.js";
+import { n as freeStateNames, r as maxFreeStates, t as mountGraph } from "./mount-graph-CzVfiIte.js";
 // src/define-graph.ts
 const defaultZoomSpeed = 1;
 const defaultPositionTransition = 120;