stickyflow 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -17,6 +17,49 @@ Two things count as breaking here that are easy to overlook:
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-22
+
+### Added
+
+- An `Isometric` block takes a `symbol`. The outline of the `Symbol` is extruded by the height, and every wall that faces the viewer is shaded on its own. It works for any closed outline of three or more points that does not cross itself.
+- `cornerRadius` in the style of an `Isometric` block rounds the vertical edges of the box or of an extruded symbol.
+- `shape: sphere` draws an `Isometric` block as a shaded ball that sits in the center of its box.
+- A point of a `Path` or a `Symbol` can carry a third value, its own tension. `0` makes the point a corner, so one outline can mix corners and curves. A point without one takes the `tension` of the whole path.
+- `pathToSymbol()` turns a `Path` into a `Symbol`, and `symbolToPath()` turns it back. `pathBounds()` and `flattenPath()` give the box of a path and the points of its curve as short straight edges. The types `PathFrame`, `PathPoint` and `PathSymbol` are exported.
+- The `Dimension` block draws a measure line with an arrow at each end, extension lines and a label. `start` and `end` are the two measured points, and `offset` is the distance of the line, positive to the left of the direction. Without `text` the label is the measured length, rounded to one decimal place, followed by `unit`. `isDimensionObject()` and the types `Dimension` and `SflDimensionObject` are exported, and `RenderInput` takes `dimensions`.
+
+### Changed
+
+- Moving a path through `applyMoveChange` keeps the tension of its points.
+- An `Isometric` block with a `symbol` that has curved points uses the curve as many short straight edges.
+
+## [0.5.0] - 2026-10-18
+
+### Added
+
+- The entry `stickyflow/binding` with `createDataSource`, `createBindingRuntime`, `buildBindingGraph`, `renderBound` and `interactiveElements`. The same names stay exported from `stickyflow` for now.
+- The components `switch`, `checkbox`, `toggleButton` and `button`. A switch, a checkbox and a toggle button hold a boolean value, a button fires `onTap`. They are drawn from scene nodes, so they render without a DOM, and they carry `role`, `aria-checked` or `aria-pressed` and `aria-disabled`.
+- `value: <-> source.field` binds the value of a component to a field of a record source in both directions. A change by the user writes the field. A value bound with `<-` cannot be changed by the user.
+- `onChange` runs when the user changes the value of a component. A binding or another handler never fires it.
+- The states `focused` and `value` of a component are readable in expressions, and `disabled` can be set and bound. `runtime.change(id, value)` and `runtime.activate(id)` do from code what a tap and the keyboard do.
+- `onTap` also fires when a component that can take focus is activated with Enter or Space. `connectInteraction` handles focus and the keyboard.
+- `defineComponent()` adds a component type from outside the library, with its description and its drawing. `getComponentDescriptor()` reads a description.
+- A type of component that is not known draws a dashed placeholder with its name, and is reported as before.
+
+### Changed
+
+- The `Widget` block is now called `Component`. Both names are read, so existing documents render as before. The types follow the new name (`Component`, `ComponentType`, `RollingNumberComponent`, `TickScaleComponent`, `RulerComponent`) and `viewer.setComponentValue()` replaces `viewer.setWidgetValue()`. `RenderInput` takes `components`. The old names remain as aliases for now.
+- The diagnostic `unsupported-widget-type` is now `unsupported-component-type`.
+- `sflToRenderInput()` returns the components as `components` and no longer as `widgets`. `BoundProperty.ownerKind` is `'Component'` for a `Component` and for a `Widget` block, and a binding is keyed `Component.value`.
+- `Component` now also covers components that are not one of the three built-in types. Narrow with `isGenericComponent()` before reading `parameters` or `style`.
+- The component types are listed in one place, `COMPONENT_TYPES`, as the shape and chart types are, and no longer repeated in the code that reads them.
+
+### Fixed
+
+- The number next to the knob of a ruler fades to the `peak` color and no longer always to white, so it stays readable on a light canvas.
+
+The DOM contract is unchanged. The attributes `data-sf-widget*`, the role `widget` and the scene ids keep their names.
+
 ## [0.4.0] - 2026-10-17
 
 ### Added

package/README.md

@@ -104,16 +104,17 @@ const { svg, width, height, diagnostics } = render(sfl)
 // A complete, deterministic SVG string. render() never touches the DOM.
 ```
 
-## Four entry points
+## Five entry points
 
 | Import | What it is |
 |---|---|
 | `stickyflow` | Static tier. SFL text in, SVG string out. Node, SSR, CLI. |
-| `stickyflow/viewer` | Read-only viewer in the DOM: select, hover, pan, zoom, typed events. |
+| `stickyflow/viewer` | Viewer in the DOM: select, hover, pan, zoom, typed events, and live input for components such as a switch or a button. |
 | `stickyflow/interaction` | Editing gestures on a viewer. Reports what changed; the host applies the patch to the SFL text. |
+| `stickyflow/binding` | Data sources, bindings and handlers. `createDataSource`, `createBindingRuntime`, `renderBound`. No DOM. |
 | `stickyflow/web-component` | `<stickyflow-diagram>` custom element in Shadow DOM, no build step. |
 
-Each tier only depends on the one below it; `test/boundary.test.ts` enforces that.
+Each entry only depends on the ones below it; `test/architecture` enforces that.
 
 ```ts
 import { createViewer } from 'stickyflow/viewer'
@@ -128,9 +129,52 @@ editing.on('moveChange', (event) => {
 })
 ```
 
+## Components and data binding
+
+A component is an interface element with a value, a look and a behavior. Seven are built in. RollingNumber, TickScale and Ruler show a value. Switch, Checkbox, ToggleButton and Button are operated by the user. An application adds its own type with `defineComponent()`.
+
+A document declares a data source and binds to it. `<-` makes a property follow the data. `<->` also writes the data when the user changes a component value, and `onChange` runs for each change by the user.
+
+```text
+DataSource lamp {
+  mode: record
+  fields {
+    on: boolean
+  }
+}
+
+Model demo {
+  Component power {
+    type: switch
+    value: <-> lamp.on
+    layout {
+      position: 0, 0
+      size: 104, 60
+    }
+  }
+}
+```
+
+```ts
+import { createBindingRuntime, createDataSource } from 'stickyflow/binding'
+import { connectInteraction, createViewer } from 'stickyflow/viewer'
+
+const viewer = createViewer({ container, source: sfl, interactive: true })
+const runtime = createBindingRuntime(sfl)
+const lamp = createDataSource({ on: false })
+
+runtime.registerSource('lamp', lamp)
+runtime.attach(viewer)
+connectInteraction(viewer, runtime)
+
+lamp.set({ on: true })   // the switch follows
+```
+
+Binding and live input need only `stickyflow/binding` and `stickyflow/viewer`. Editing with `stickyflow/interaction` is separate.
+
 ## What it draws
 
-Shapes, links, frames, swimlanes, paths and text. Fifteen chart types. Isometric objects. Shader surfaces and widgets. Data sources with bindings, and events with handlers, so a document can react to data and input.
+Shapes, links, frames, swimlanes, paths and text. Fifteen chart types. Isometric objects. Shader surfaces and components. Data sources with bindings, and events with handlers, so a document can react to data and input.
 
 ## Principles
 
@@ -140,11 +184,13 @@ Shapes, links, frames, swimlanes, paths and text. Fifteen chart types. Isometric
 
 ```
 src/
+  model/         types and registries for shapes, charts, components
   sflLanguage/   AST, lexer, parser, canonical emitter
   sflSemantic/   SFL AST to canvas state
   renderInput/   renderer contract and style decoding
   renderScene/   deterministic scene construction
   svg/           SVG serialization and the DOM contract
+  binding/       data sources, bindings and handlers
   runtime/       viewer, interaction, web component
 ```
 
@@ -155,7 +201,7 @@ npm run ci      # lint, typecheck, tests, build, smoke
 npm run build   # tsup
 ```
 
-How the package and its neighbours fit together: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Adding a new placeable object: [docs/ADDING_CANVAS_OBJECT.md](docs/ADDING_CANVAS_OBJECT.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+How the package and its neighbours fit together: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Adding a new placeable object: [docs/ADDING_CANVAS_OBJECT.md](docs/ADDING_CANVAS_OBJECT.md). Adding a component: [docs/ADDING_COMPONENT.md](docs/ADDING_COMPONENT.md). Changes: [CHANGELOG.md](CHANGELOG.md).
 
 ## More
 

package/dist/binding/index.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+var chunkJIJMZMGY_cjs = require('../chunk-JIJMZMGY.cjs');
+require('../chunk-WQRT5PVT.cjs');
+require('../chunk-XJ4W6TW4.cjs');
+
+
+
+Object.defineProperty(exports, "buildBindingGraph", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.buildBindingGraph; }
+});
+Object.defineProperty(exports, "collectContracts", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.collectContracts; }
+});
+Object.defineProperty(exports, "createBindingRuntime", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.createBindingRuntime; }
+});
+Object.defineProperty(exports, "createDataSource", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.createDataSource; }
+});
+Object.defineProperty(exports, "interactiveElements", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.interactiveElements; }
+});
+Object.defineProperty(exports, "renderBound", {
+  enumerable: true,
+  get: function () { return chunkJIJMZMGY_cjs.renderBound; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/binding/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/binding/index.d.cts

@@ -0,0 +1,11 @@
+import { S as SflDocument, D as DataSourceContract, B as BindingDiagnostic } from '../runtimeTypes-CrkMHvVi.cjs';
+export { a as BindingGraph, b as BindingRuntime, c as BindingRuntimeOptions, d as BindingTarget, e as BindingType, f as BindingValue, g as BoundAssignment, h as BoundHandler, i as BoundProperty, j as DataSource, E as ElementInfo, k as ElementState, I as InteractiveElements, M as MutableDataSource, l as buildBindingGraph, m as createDataSource, n as interactiveElements } from '../runtimeTypes-CrkMHvVi.cjs';
+export { R as RenderBoundOptions, c as createBindingRuntime, r as renderBound } from '../runtime-BhivvBeL.cjs';
+import '../render-Db0eSz_s.cjs';
+
+declare function collectContracts(sflDocument: SflDocument): {
+    contracts: Map<string, DataSourceContract>;
+    diagnostics: BindingDiagnostic[];
+};
+
+export { BindingDiagnostic, DataSourceContract, collectContracts };

package/dist/binding/index.d.ts

@@ -0,0 +1,11 @@
+import { S as SflDocument, D as DataSourceContract, B as BindingDiagnostic } from '../runtimeTypes-DnI7mRF5.js';
+export { a as BindingGraph, b as BindingRuntime, c as BindingRuntimeOptions, d as BindingTarget, e as BindingType, f as BindingValue, g as BoundAssignment, h as BoundHandler, i as BoundProperty, j as DataSource, E as ElementInfo, k as ElementState, I as InteractiveElements, M as MutableDataSource, l as buildBindingGraph, m as createDataSource, n as interactiveElements } from '../runtimeTypes-DnI7mRF5.js';
+export { R as RenderBoundOptions, c as createBindingRuntime, r as renderBound } from '../runtime-n2yG-_j-.js';
+import '../render-Db0eSz_s.js';
+
+declare function collectContracts(sflDocument: SflDocument): {
+    contracts: Map<string, DataSourceContract>;
+    diagnostics: BindingDiagnostic[];
+};
+
+export { BindingDiagnostic, DataSourceContract, collectContracts };

package/dist/binding/index.js

@@ -0,0 +1,5 @@
+export { buildBindingGraph, collectContracts, createBindingRuntime, createDataSource, interactiveElements, renderBound } from '../chunk-MFNUJA26.js';
+import '../chunk-FVHVOJS2.js';
+import '../chunk-4G2R7PEL.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/binding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}