@hlang-tech/editor-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 hlang-tech
+
+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,79 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hlang-tech/hlang/main/media/logo.png" width="88" alt="hlang">
+</p>
 
-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.
+# @hlang-tech/editor-ui
+
+The Lumen design system for hlang: React components for a node editor built on React Flow and [`@hlang-tech/editor-react`](https://www.npmjs.com/package/@hlang-tech/editor-react). Black and silver surfaces, image and intent nodes, live edges, and the panels around the canvas.
+
+[![npm](https://img.shields.io/npm/v/@hlang-tech/editor-ui?color=c8ccd4&labelColor=0f1114)](https://www.npmjs.com/package/@hlang-tech/editor-ui)
+[![license](https://img.shields.io/npm/l/@hlang-tech/editor-ui?color=c8ccd4&labelColor=0f1114)](https://github.com/hlang-tech/hlang/blob/main/LICENSE)
+
+> **Status:** 0.x, in active development. The API can change in any minor release.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hlang-tech/hlang/main/media/lumen-editor.png" alt="The Lumen editor built with editor-ui" width="100%">
+</p>
+
+## Install
+
+```sh
+npm install @hlang-tech/editor-ui @hlang-tech/editor-react @hlang-tech/editor-core @xyflow/react react react-dom
+```
+
+The same build is published as `@hlang-org/editor-ui`. Import the stylesheet once:
+
+```ts
+import '@xyflow/react/dist/style.css';
+import '@hlang-tech/editor-ui/styles.css';
+```
+
+## Usage
+
+```tsx
+import { ReactFlow, ReactFlowProvider } from '@xyflow/react';
+import { useHlangFlow } from '@hlang-tech/editor-react';
+import { createHlangFlowTypes } from '@hlang-tech/editor-ui';
+
+const { nodeTypes, edgeTypes } = createHlangFlowTypes();
+
+function Canvas({ core }) {
+  const flow = useHlangFlow(core);
+  return <ReactFlow {...flow} nodeTypes={nodeTypes} edgeTypes={edgeTypes} colorMode="dark" fitView />;
+}
+```
+
+`createHlangFlowTypes` registers the node and edge components for the three node kinds. A node renders as a framed image when its `imageUrl` parameter is set, and as a pill otherwise. An edge shows the source node's `role` parameter as a label. The runtime contract does not change: every node is still a Readable, Transform, or Writable node with ports.
+
+See the [playground](https://github.com/hlang-tech/hlang/tree/main/examples/editor-react-playground) for a complete editor.
+
+## Components
+
+| Area | Exports |
+| --- | --- |
+| Nodes and edges | `HlangNode`, `AssetNodeChrome`, `PillNodeChrome`, `NodeChrome`, `PortRow`, `SignalBar`, `NodeBodySlot`, `FlowEdge`, `createHlangFlowTypes` |
+| Shell and toolbar | `EditorShell`, `Toolbar`, `UndoRedo`, `RunButton`, `ToolbarStat`, `ToolbarGhostButton`, `ToolCluster` |
+| Canvas | `CanvasChrome`, `CanvasDock`, `EmptyState` |
+| Panels | `OutlineTree`, `RailTabs`, `AssetGrid`, `InspectorPanel`, `ParamForm`, `PositionPanel`, `PreviewPanel`, `DiagnosticBadge` |
+| Creating nodes | `NodeSearch`, `useNodeSearch`, `useNodeSearchTriggers` (double-click the canvas, or drop a connection on empty space) |
+| Interaction | `useEditorHotkeys`, `NodeContextMenu`, `useNodeContextMenu`, `NodeInteractionProvider`, `Cheatsheet`, `ToastProvider` |
+| Live execution | `LiveSignalProvider`, `LiveSignalStore`, `useLiveSignals`, `useNodeLiveState`, `useEdgeFlowing` |
+| Theme | `TOKEN_NAMES`, `tokenVar`, `createTheme`, `EditorUIThemeProvider` |
+
+### Keyboard shortcuts
+
+`useEditorHotkeys(core)` binds undo (`⌘Z`), redo (`⇧⌘Z` or `⌘Y`), copy, cut, paste, duplicate (`⌘D`), select all (`⌘A`), and delete (`Delete` or `Backspace`). `Ctrl` replaces `⌘` on Windows and Linux. Shortcuts are ignored while a text field has focus.
+
+### Live execution
+
+`useLiveSignals(core, handle)` feeds a run's activity and errors into a `LiveSignalStore`. Nodes and edges subscribe by id, so only the elements whose state changes re-render.
+
+### Theming
+
+All colors, fonts, and radii are CSS custom properties (`--hl-*`). Override them with `createTheme({ 'hl-silver': '#d8dce4' })` passed as a `style`, or with `EditorUIThemeProvider`.
+
+Source and documentation: [github.com/hlang-tech/hlang](https://github.com/hlang-tech/hlang).
+
+## License
+
+MIT

package/lib/canvas/CanvasChrome.css

@@ -0,0 +1,45 @@
+/** Theme React Flow's built-in controls + minimap to the design tokens. */
+
+.hl-controls.react-flow__controls {
+  border-radius: 10px;
+  overflow: hidden;
+  border: 1px solid var(--hl-line);
+  box-shadow: none;
+}
+.hl-controls .react-flow__controls-button {
+  background: var(--hl-surface);
+  border-bottom: 1px solid var(--hl-line);
+  color: var(--hl-ink-2);
+}
+.hl-controls .react-flow__controls-button:hover {
+  background: var(--hl-surface-2);
+  color: var(--hl-ink);
+}
+.hl-controls .react-flow__controls-button svg {
+  fill: currentColor;
+}
+
+/* A discreet frosted minimap that recedes into the canvas at rest and lifts on
+   hover — furniture, not a focal point. */
+.hl-minimap.react-flow__minimap {
+  width: 168px;
+  height: 118px;
+  background: var(--hl-glass);
+  backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  -webkit-backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  border: 1px solid var(--hl-line);
+  border-radius: 12px;
+  box-shadow: var(--hl-glass-edge), 0 8px 24px -12px rgba(0, 0, 0, 0.7);
+  opacity: 0.42;
+  transition: opacity 0.2s var(--hl-ease);
+}
+.hl-minimap.react-flow__minimap:hover {
+  opacity: 1;
+}
+
+/* Connection line while dragging out a new edge. */
+.react-flow__connection-path {
+  stroke: var(--hl-silver);
+  stroke-width: 1.5;
+  filter: drop-shadow(0 0 4px color-mix(in oklab, var(--hl-silver) 50%, transparent));
+}

package/lib/canvas/CanvasDock.css

@@ -0,0 +1,82 @@
+/** CanvasDock — centred bottom glass toolbar (pan/zoom/add), black & silver. */
+
+.hl-dock {
+  position: absolute;
+  z-index: 8;
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  padding: 5px;
+  background: var(--hl-glass-2);
+  backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  -webkit-backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  border: 1px solid var(--hl-line-strong);
+  border-radius: var(--hl-r-pill);
+  box-shadow: var(--hl-glass-edge), 0 14px 34px -18px rgba(0, 0, 0, 0.85);
+}
+
+.hl-dock-btn {
+  width: 34px;
+  height: 34px;
+  display: grid;
+  place-items: center;
+  border: none;
+  background: transparent;
+  color: var(--hl-ink-2);
+  border-radius: var(--hl-r-pill);
+  cursor: pointer;
+  transition: background 0.14s var(--hl-ease), color 0.14s var(--hl-ease);
+}
+.hl-dock-btn:hover:not(:disabled) {
+  background: rgba(255, 255, 255, 0.07);
+  color: var(--hl-ink);
+}
+.hl-dock-btn:disabled {
+  opacity: 0.3;
+  cursor: not-allowed;
+}
+/* The active interaction mode reads in silver. */
+.hl-dock-btn.is-active {
+  background: color-mix(in oklab, var(--hl-silver) 22%, transparent);
+  color: var(--hl-silver-hi);
+  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--hl-silver) 30%, transparent);
+}
+
+/* Add-node is the one lightly-emphasised action. */
+.hl-dock-add {
+  color: var(--hl-ink);
+}
+.hl-dock-add:hover {
+  background: color-mix(in oklab, var(--hl-silver) 18%, transparent);
+}
+
+.hl-dock-glyph {
+  font-size: 17px;
+  line-height: 1;
+}
+
+.hl-dock-sep {
+  width: 1px;
+  height: 20px;
+  margin: 0 4px;
+  background: var(--hl-line-strong);
+}
+
+.hl-dock-zoom {
+  min-width: 48px;
+  height: 34px;
+  padding: 0 8px;
+  border: none;
+  background: transparent;
+  color: var(--hl-ink);
+  font-size: 12px;
+  border-radius: var(--hl-r-sm);
+  cursor: pointer;
+  transition: background 0.14s var(--hl-ease);
+}
+.hl-dock-zoom:hover {
+  background: rgba(255, 255, 255, 0.07);
+}

package/lib/canvas/EmptyState.css

@@ -0,0 +1,23 @@
+.hl-empty {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  pointer-events: none;
+}
+.hl-empty-title {
+  margin: 0;
+  font-size: 17px;
+  font-weight: 550;
+  letter-spacing: -0.01em;
+  color: var(--hl-ink-2);
+}
+.hl-empty-hint {
+  margin: 0;
+  font-family: var(--hl-font-mono);
+  font-size: 12px;
+  color: var(--hl-ink-3);
+}

package/lib/command-palette/NodeSearch.css

@@ -0,0 +1,153 @@
+/**
+ * NodeSearch palette — a floating deep-space glass command menu. Anchored at a
+ * fixed screen point; a full-viewport scrim catches outside clicks. Electric-
+ * blue focus accent, kind-tinted result chips, fuzzy-match emphasis.
+ */
+
+.hl-node-search-scrim {
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+}
+
+.hl-node-search {
+  position: fixed;
+  z-index: 41;
+  width: 320px;
+  max-height: 360px;
+  display: flex;
+  flex-direction: column;
+  /* Nearly opaque so canvas content does not bleed through and muddy the
+     panel's layering; the slight translucency + blur keeps it feeling like
+     glass floating above the graph, not a flat modal. */
+  background: color-mix(in oklab, var(--hl-surface) 98%, transparent);
+  border: 1px solid var(--hl-line-strong);
+  border-radius: var(--hl-r-lg);
+  box-shadow: var(--hl-shadow-node), 0 24px 48px -24px rgba(0, 0, 0, 0.9);
+  backdrop-filter: blur(20px) saturate(1.3);
+  overflow: hidden;
+  color: var(--hl-ink);
+  font-family: var(--hl-font-ui);
+  animation: hl-node-search-in 140ms var(--hl-ease);
+}
+
+@keyframes hl-node-search-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.hl-node-search-field {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--hl-line);
+}
+
+.hl-node-search-glyph {
+  color: var(--hl-silver);
+  font-size: 13px;
+  line-height: 1;
+}
+
+.hl-node-search-input {
+  flex: 1;
+  min-width: 0;
+  background: transparent;
+  border: none;
+  outline: none;
+  color: var(--hl-ink);
+  /* UI font (not mono) to sit consistently with the result labels below;
+     mono is reserved for the kind chips and port tags where it reads as code. */
+  font-family: var(--hl-font-ui);
+  font-size: 14px;
+  letter-spacing: 0;
+}
+
+.hl-node-search-input::placeholder {
+  color: var(--hl-ink-3);
+}
+
+.hl-node-search-list {
+  list-style: none;
+  margin: 0;
+  padding: 6px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.hl-node-search-empty {
+  padding: 12px;
+  color: var(--hl-ink-3);
+  font-size: 12px;
+  text-align: center;
+}
+
+.hl-node-search-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 10px;
+  border-radius: var(--hl-r-sm);
+  cursor: pointer;
+  transition: background-color 120ms var(--hl-ease);
+}
+
+.hl-node-search-item.is-active {
+  background: var(--hl-surface-2);
+  box-shadow: inset 0 0 0 1px var(--hl-line-strong);
+}
+
+.hl-node-search-kind {
+  flex: none;
+  width: 20px;
+  height: 20px;
+  display: grid;
+  place-items: center;
+  border-radius: var(--hl-r-sm);
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--hl-void);
+}
+
+.hl-node-search-kind.hl-kind-r {
+  background: var(--hl-r);
+}
+.hl-node-search-kind.hl-kind-t {
+  background: var(--hl-t);
+}
+.hl-node-search-kind.hl-kind-w {
+  background: var(--hl-w);
+}
+
+.hl-node-search-label {
+  flex: 1;
+  min-width: 0;
+  font-size: 13px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hl-node-search-hit {
+  background: transparent;
+  color: var(--hl-silver);
+  font-weight: 600;
+}
+
+.hl-node-search-port {
+  flex: none;
+  font-size: 11px;
+  color: var(--hl-ink-3);
+  padding: 2px 6px;
+  border: 1px solid var(--hl-line);
+  border-radius: 999px;
+}

package/lib/context-menu/NodeContextMenu.css

@@ -0,0 +1,102 @@
+/**
+ * NodeContextMenu — a compact black/silver liquid-glass menu, matching the
+ * command palette's material. Frosted panel, silver active row, muted-coral
+ * destructive row, monospace shortcut hints.
+ */
+
+.hl-ctx-scrim {
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+}
+
+.hl-ctx-menu {
+  position: fixed;
+  z-index: 41;
+  min-width: 192px;
+  padding: 5px;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  background: var(--hl-glass-2);
+  backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  -webkit-backdrop-filter: blur(var(--hl-glass-blur)) saturate(var(--hl-glass-sat));
+  border: 1px solid var(--hl-line-strong);
+  border-radius: var(--hl-r-md);
+  box-shadow: var(--hl-glass-edge), var(--hl-shadow-node),
+    0 20px 44px -22px rgba(0, 0, 0, 0.9);
+  outline: none;
+  animation: hl-ctx-in 0.13s var(--hl-ease);
+}
+@keyframes hl-ctx-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px) scale(0.98);
+  }
+}
+
+.hl-ctx-item {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  width: 100%;
+  padding: 7px 9px;
+  border: none;
+  background: transparent;
+  color: var(--hl-ink);
+  font-family: var(--hl-font-ui);
+  font-size: 12.5px;
+  text-align: left;
+  border-radius: var(--hl-r-sm);
+  cursor: pointer;
+  transition: background 0.12s var(--hl-ease), color 0.12s var(--hl-ease);
+}
+/* Silver active row (keyboard/hover). */
+.hl-ctx-item.is-active {
+  background: color-mix(in oklab, var(--hl-silver) 18%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--hl-silver) 26%, transparent);
+}
+.hl-ctx-item:disabled {
+  color: var(--hl-ink-3);
+  cursor: default;
+}
+.hl-ctx-item.is-danger {
+  color: var(--hl-error);
+}
+.hl-ctx-item.is-danger.is-active {
+  background: color-mix(in oklab, var(--hl-error) 20%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--hl-error) 34%, transparent);
+}
+
+.hl-ctx-item-icon {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: grid;
+  place-items: center;
+  color: var(--hl-silver-lo);
+}
+.hl-ctx-item.is-danger .hl-ctx-item-icon {
+  color: var(--hl-error);
+}
+.hl-ctx-item.is-active .hl-ctx-item-icon {
+  color: var(--hl-silver-hi);
+}
+
+.hl-ctx-item-label {
+  flex: 1;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hl-ctx-item-key {
+  flex: none;
+  font-size: 11px;
+  color: var(--hl-ink-3);
+  letter-spacing: 0.02em;
+}
+.hl-ctx-item.is-active .hl-ctx-item-key {
+  color: var(--hl-ink-2);
+}

package/lib/edges/FlowEdge.css

@@ -0,0 +1,80 @@
+/**
+ * Living-stream edge — THE signature. At rest an edge is a quiet silver
+ * hairline. While a flow is running, a cold spark marches along it O -> I —
+ * the one bold, memorable, hlang-unique moment (a static board can't do this).
+ * `value` sources show a solid overlay (change-only, no marching). Flow is
+ * gated by `.is-flowing` (driven by live signals). Reduced motion disables the
+ * march (handled globally in tokens.css).
+ */
+
+.hl-edge-base {
+  stroke: var(--hl-line-strong);
+  stroke-width: 1.25;
+  fill: none;
+}
+
+/* Resting overlay: a calm silver line, no glow, no march. */
+.hl-edge-flow {
+  stroke: color-mix(in oklab, var(--hl-silver) 55%, transparent);
+  stroke-width: 1.25;
+  stroke-linecap: round;
+  fill: none;
+  opacity: 0.8;
+}
+
+/* Live (hot) streams march; value streams are solid. */
+.hl-edge.is-live .hl-edge-flow {
+  stroke-dasharray: 2 10;
+  animation: hl-flow 0.9s linear infinite;
+}
+
+/* During execution, an edge whose source just emitted lights with the cold
+   spark and quickens — the visible living-stream pulse (via useLiveSignals). */
+.hl-edge.is-flowing .hl-edge-flow {
+  stroke: var(--hl-spark);
+  stroke-width: 1.75;
+  opacity: 1;
+  filter: drop-shadow(0 0 6px color-mix(in oklab, var(--hl-spark) 70%, transparent));
+  animation-duration: 0.4s;
+}
+.hl-edge.is-error.is-flowing .hl-edge-flow {
+  stroke: var(--hl-error);
+  filter: drop-shadow(0 0 6px color-mix(in oklab, var(--hl-error) 70%, transparent));
+}
+.hl-edge.is-value .hl-edge-flow {
+  stroke-dasharray: none;
+  opacity: 0.5;
+}
+
+.hl-edge.is-error .hl-edge-flow {
+  stroke: color-mix(in oklab, var(--hl-error) 60%, transparent);
+}
+
+.hl-edge:hover .hl-edge-base {
+  stroke: color-mix(in oklab, var(--hl-silver) 45%, var(--hl-line-strong));
+}
+
+@keyframes hl-flow {
+  to {
+    stroke-dashoffset: -12;
+  }
+}
+
+/* Semantic label riding the edge midpoint — a frosted glass pill naming what
+   the wire carries (Character / Background …). Reads the source node's role. */
+.hl-edge-label {
+  position: absolute;
+  pointer-events: none;
+  z-index: 6; /* ride above node cards so a short-edge label is never clipped */
+  font-size: 10px;
+  letter-spacing: 0.02em;
+  color: var(--hl-ink);
+  background: var(--hl-glass-2);
+  backdrop-filter: blur(10px) saturate(1.1);
+  -webkit-backdrop-filter: blur(10px) saturate(1.1);
+  border: 1px solid color-mix(in oklab, var(--hl-silver) 22%, var(--hl-line));
+  border-radius: var(--hl-r-pill);
+  padding: 2px 9px;
+  box-shadow: var(--hl-glass-edge), 0 2px 8px -3px rgba(0, 0, 0, 0.6);
+  white-space: nowrap;
+}