@kubex/zinc 1.1.22 → 1.1.24

package/src/components/flow-builder/flow-builder.scss

@@ -0,0 +1,489 @@
+@use "../../wc";
+
+:host {
+  @include wc.scrollbars; // styles scrollbars of all descendant scroll areas (steps panel, inspector, sidebar, picker)
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 480px;
+  color: rgb(var(--zn-text));
+}
+
+.builder {
+  display: grid;
+  grid-template-columns: 343px minmax(0, 1fr) 343px;
+  grid-template-rows: auto minmax(0, 1fr);
+  width: 100%;
+  height: 100%;
+  background: rgb(var(--zn-panel));
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+// Full-width action bar above the three panels; hidden unless actions are slotted.
+.header {
+  grid-row: 1;
+  grid-column: 1 / -1;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 10px 14px;
+  border-bottom: 1px solid rgb(var(--zn-border-color));
+  background: rgb(var(--zn-panel));
+
+  &[hidden] {
+    display: none;
+  }
+
+  &__group {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+}
+
+// The panels sit on the second grid row explicitly — the hidden header leaves
+// the grid entirely (display: none), so auto-placement would pull them into the
+// `auto` first row and collapse the builder to its content height.
+.steps,
+.inspector,
+.sidebar {
+  grid-row: 2;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  background: rgb(var(--zn-panel));
+}
+
+// Colour the slotted zn-navbar's active tab to match the steps panel surface,
+// rather than the navbar's default body colour.
+.steps {
+  --zn-active-nav-background: var(--zn-panel);
+}
+
+// Left column (steps panel).
+.steps {
+  border-right: 1px solid rgb(var(--zn-border-color));
+}
+
+// Right column (version history / errors, or the node/branch editor).
+.sidebar,
+.inspector {
+  border-left: 1px solid rgb(var(--zn-border-color));
+}
+
+// The editor slides in from the right when a node or branch is selected.
+.inspector {
+  animation: inspector-in 0.18s ease;
+}
+
+@keyframes inspector-in {
+  from {
+    transform: translateX(32px);
+    opacity: 0.3;
+  }
+
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+
+.canvas-cell {
+  grid-row: 2;
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+}
+
+// --- Steps panel -----------------------------------------------------------------
+
+// The registry-driven steps panel fills the column below the title block.
+.steps-content {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+// Slotted <zn-flow-step>s are type declarations only — never displayed.
+.declarations {
+  display: none;
+}
+
+.title-block {
+  padding: 16px;
+  border-bottom: 1px solid rgb(var(--zn-border-color));
+
+  .heading {
+    font-size: 0.9375rem;
+    font-weight: 600;
+  }
+
+  .subheading {
+    margin-top: 2px;
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+  }
+}
+
+.search {
+  padding: 12px 12px 8px;
+}
+
+// Each tab panel fills the zn-tabs content area and lets its category list scroll.
+.steps-panel {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  height: 100%;
+}
+
+// Per-tab hint, shown beneath the tab bar with a divider before the categories.
+.steps-hint {
+  margin: 0;
+  padding: 12px var(--zn-base-gap);
+  font-size: 0.8125rem;
+  line-height: 1.4;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+.steps-scroll {
+  @include wc.scrollbars;
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding-bottom: 16px;
+
+  // Divider above every category (and between the hint/tabs and the first one).
+  zn-flow-step-group {
+    display: block;
+    border-top: 1px solid rgb(var(--zn-border-color));
+  }
+}
+
+.steps-uncategorized {
+  padding: 8px var(--zn-base-gap);
+}
+
+.steps-empty {
+  padding: 16px var(--zn-base-gap);
+  font-size: 0.8125rem;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+.step {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 10px;
+  margin-bottom: 6px;
+  background: rgb(var(--zn-panel));
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  font-size: 0.8125rem;
+  cursor: grab;
+  transition: border-color 0.12s ease, box-shadow 0.12s ease;
+
+  &:hover {
+    border-color: rgb(var(--zn-color-border-active));
+    box-shadow: 0 1px 3px rgba(var(--zn-shadow), 0.4);
+  }
+
+  &:active {
+    cursor: grabbing;
+  }
+
+  &__icon {
+    --node-accent: rgb(var(--zn-color-primary));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    width: 28px;
+    height: 28px;
+    border-radius: 6px;
+    color: var(--node-accent);
+    background: color-mix(in srgb, var(--node-accent) 14%, transparent);
+  }
+
+  &__label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}
+
+// --- Inspector ---------------------------------------------------------------
+
+.inspector-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  height: 100%;
+  padding: 24px;
+  text-align: center;
+  color: rgb(var(--zn-color-muted-text));
+  font-size: 0.8125rem;
+}
+
+.inspector-head {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  border-bottom: 1px solid rgb(var(--zn-border-color));
+
+  &__icon {
+    --node-accent: rgb(var(--zn-color-primary));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    width: 36px;
+    height: 36px;
+    border-radius: 8px;
+    color: var(--node-accent);
+    background: color-mix(in srgb, var(--node-accent) 14%, transparent);
+  }
+
+  // Long labels truncate rather than pushing the close button out of the panel.
+  &__text {
+    flex: 1;
+    min-width: 0;
+  }
+
+  // Title + badges (e.g. the Loop tag) on one line: the title shrinks with an
+  // ellipsis while the badge always stays visible.
+  &__title-row {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 0;
+
+    .inspector-head__title {
+      min-width: 0;
+    }
+  }
+
+  &__title {
+    font-size: 0.875rem;
+    font-weight: 600;
+  }
+
+  &__title,
+  &__type {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__type {
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+  }
+}
+
+.inspector-body {
+  @include wc.scrollbars;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 16px;
+}
+
+.inspector-hint {
+  margin: 0;
+  font-size: 0.75rem;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+// Marks a loop branch in the editor head, matching its amber pill and wire.
+.inspector-loop-tag {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  gap: 3px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 0.6875rem;
+  font-weight: 600;
+  line-height: 1;
+  color: rgb(var(--zn-color-warning));
+  background: color-mix(in srgb, rgb(var(--zn-color-warning)) 14%, transparent);
+}
+
+.inspector-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  margin-left: auto;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border-radius: 6px;
+  color: rgb(var(--zn-color-muted-text));
+  background: transparent;
+  cursor: pointer;
+
+  &:hover {
+    background: rgb(var(--zn-color-tab));
+    color: rgb(var(--zn-text));
+  }
+}
+
+// --- Sidebar (right rail) ----------------------------------------------------
+
+.sidebar {
+  @include wc.scrollbars;
+  overflow-y: auto;
+  padding: 16px;
+}
+
+.sidebar-section__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 10px;
+  font-size: 0.8125rem;
+  font-weight: 600;
+}
+
+.sidebar-count {
+  min-width: 20px;
+  padding: 0 6px;
+  font-size: 0.75rem;
+  line-height: 18px;
+  text-align: center;
+  border-radius: 9px;
+  color: rgb(var(--zn-color-muted-text));
+  background: rgb(var(--zn-color-tab));
+}
+
+.sidebar-empty {
+  margin: 0;
+  font-size: 0.75rem;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+.sidebar-error {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  margin-bottom: 6px;
+  padding: 8px 10px;
+  font-size: 0.8125rem;
+  text-align: left;
+  color: rgb(var(--zn-color-error));
+  background: color-mix(in srgb, rgb(var(--zn-color-error)) 7%, transparent);
+  border: 1px solid color-mix(in srgb, rgb(var(--zn-color-error)) 25%, transparent);
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+// --- "+" picker popover ------------------------------------------------------
+
+.picker-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+}
+
+.picker {
+  position: fixed;
+  z-index: 21;
+  width: 220px;
+  max-height: 320px;
+  overflow-y: auto;
+  padding: 6px;
+  background: rgb(var(--zn-panel));
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  box-shadow: 0 6px 24px rgba(var(--zn-shadow), 0.5);
+  @include wc.scrollbars;
+}
+
+.picker-group {
+  padding: 8px 8px 4px;
+  font-size: 0.6875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+.picker-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 7px 8px;
+  font-size: 0.8125rem;
+  text-align: left;
+  background: transparent;
+  border-radius: 6px;
+  cursor: pointer;
+
+  &:hover {
+    background: rgb(var(--zn-color-tab));
+  }
+
+  &__icon {
+    --node-accent: rgb(var(--zn-color-primary));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    width: 26px;
+    height: 26px;
+    border-radius: 6px;
+    color: var(--node-accent);
+    background: color-mix(in srgb, var(--node-accent) 14%, transparent);
+  }
+}
+
+.picker-empty {
+  margin: 0;
+  padding: 10px;
+  font-size: 0.75rem;
+  color: rgb(var(--zn-color-muted-text));
+}
+
+// --- Move banner -------------------------------------------------------------
+
+.move-banner {
+  position: absolute;
+  top: 16px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 5;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  font-size: 0.8125rem;
+  color: rgb(var(--zn-panel));
+  background: rgb(var(--zn-color-primary));
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(var(--zn-shadow), 0.5);
+
+  button {
+    padding: 2px 8px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: rgb(var(--zn-panel));
+    background: rgba(255, 255, 255, 0.2);
+    border-radius: 6px;
+    cursor: pointer;
+  }
+}

package/src/components/flow-builder/flow-builder.test.ts

@@ -0,0 +1,59 @@
+import '../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import type {FlowNodeType, FlowState} from './flow.types';
+import type ZnFlowBuilder from './flow-builder.component';
+
+const TRIGGER: FlowNodeType = {type: 'webhook', label: 'Webhook', group: 'trigger', category: 'Contacts'};
+const ACTION: FlowNodeType = {type: 'email', label: 'Send Email', group: 'action'};
+
+describe('<zn-flow-builder>', () => {
+  it('should render a component', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    expect(el).to.exist;
+    expect(el.shadowRoot?.querySelector('zn-flow-canvas')).to.exist;
+  });
+
+  it('should list registered node types for the active tab', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    el.registerNodeTypes([TRIGGER, ACTION]);
+    await el.updateComplete;
+
+    // Each group renders its own zn-tabs panel; the default (Triggers) panel is first.
+    const triggerPanel = el.shadowRoot?.querySelectorAll('.steps-panel')[0];
+    const items = triggerPanel?.querySelectorAll('.step');
+    expect(items?.length).to.equal(1); // only the trigger shows on the default Triggers tab
+    expect(items?.[0].textContent).to.contain('Webhook');
+  });
+
+  it('should round-trip state through getState/setState', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    const state: FlowState = {
+      nodes: [{id: 'n1', type: 'webhook', x: 10, y: 20, data: {}}],
+      connections: [],
+      notes: [],
+    };
+    el.setState(state);
+    await el.updateComplete;
+
+    expect(el.getState().nodes).to.have.length(1);
+    expect(el.getState().nodes[0].id).to.equal('n1');
+  });
+
+  it('should parse the value attribute as JSON', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    el.value = JSON.stringify({nodes: [{id: 'a', type: 'x', x: 0, y: 0, data: {}}]});
+    await el.updateComplete;
+    expect(el.getState().nodes).to.have.length(1);
+  });
+
+  it('should treat undo as a no-op with empty history', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    expect(() => el.undo()).to.not.throw();
+    expect(el.getState().nodes).to.have.length(0);
+  });
+});

package/src/components/flow-builder/flow-layout.ts

@@ -0,0 +1,139 @@
+import {
+  BRANCH_SPREAD,
+  type FlowConnection,
+  type FlowNodeInstance,
+  type FlowNodeType,
+  type FlowState,
+  loopConnections,
+  NODE_WIDTH,
+  nodeOutputs,
+  snapToGrid,
+} from './flow.types';
+
+/** Horizontal gap between node origins within a layer. */
+export const LAYOUT_H_GAP = NODE_WIDTH + 80;
+/** Vertical gap between layers — clears the bus, a branch pill, and the wire run-in. */
+export const LAYOUT_V_GAP = 300;
+const MARGIN = 40;
+
+const avg = (ns: number[]) => ns.reduce((a, b) => a + b, 0) / ns.length;
+
+/**
+ * "Untangle" auto-layout: assigns every node a position in a layered, top-down
+ * flow. Layers come from the longest path back to a root (the graph is a DAG —
+ * connects are cycle-guarded), ordering within a layer follows where each node's
+ * parents sit (barycenter, respecting the parents' output-port order), and the
+ * coordinate passes centre children under the branch anchors they hang from.
+ * Returns the new positions; the caller applies them.
+ */
+export function untangledPositions(
+  state: FlowState,
+  typeOf: (type: string) => FlowNodeType | undefined
+): Map<string, { x: number; y: number }> {
+  const out = new Map<string, { x: number; y: number }>();
+  const nodes = state.nodes;
+  if (!nodes.length) return out;
+
+  const byId = new Map(nodes.map(n => [n.id, n] as const));
+  const incoming = new Map<string, FlowConnection[]>(nodes.map(n => [n.id, []]));
+  const outgoing = new Map<string, FlowConnection[]>(nodes.map(n => [n.id, []]));
+  for (const c of state.connections) {
+    if (!byId.has(c.source.node) || !byId.has(c.target.node)) continue;
+    incoming.get(c.target.node)!.push(c);
+    outgoing.get(c.source.node)!.push(c);
+  }
+
+  // 1. Loops are allowed in the flow, but layering needs a DAG: ignore each
+  //    cycle's back-edge. Longest-path layering then puts roots (and isolated
+  //    nodes) at 0 and every other node one layer below its deepest parent —
+  //    loop wires simply travel back up.
+  const backEdges = loopConnections(nodes, state.connections);
+
+  const layerOf = new Map<string, number>();
+  const layerFor = (id: string): number => {
+    const known = layerOf.get(id);
+    if (known !== undefined) return known;
+    const ins = incoming.get(id)!.filter(c => !backEdges.has(c));
+    const layer = ins.length ? Math.max(...ins.map(c => layerFor(c.source.node))) + 1 : 0;
+    layerOf.set(id, layer);
+    return layer;
+  };
+  nodes.forEach(n => layerFor(n.id));
+
+  const layers: FlowNodeInstance[][] = Array.from(
+    {length: Math.max(...layerOf.values()) + 1},
+    () => []
+  );
+  nodes.forEach(n => layers[layerOf.get(n.id)!].push(n));
+
+  // The canvas-space x offset of a connection's branch anchor from its source
+  // node's origin (branches spread symmetrically around the bottom centre).
+  const branchOffset = (c: FlowConnection): number => {
+    const parent = byId.get(c.source.node)!;
+    const outputs = nodeOutputs(parent, typeOf(parent.type));
+    const count = Math.max(outputs.length, 1);
+    const idx = Math.max(outputs.findIndex(p => p.id === c.source.port), 0);
+    return count === 1 ? 0 : (idx - (count - 1) / 2) * BRANCH_SPREAD;
+  };
+
+  // 2. Ordering: roots keep their left-to-right order; deeper layers sort by the
+  //    mean of their parents' order (nudged by which output port they hang from),
+  //    which keeps siblings in port order and reduces wire crossings.
+  const orderIdx = new Map<string, number>();
+  layers[0].sort((a, b) => a.x - b.x).forEach((n, i) => orderIdx.set(n.id, i));
+  for (let l = 1; l < layers.length; l++) {
+    const bary = (n: FlowNodeInstance) => {
+      // Forward parents only — loops don't influence ordering.
+      const ordered = incoming.get(n.id)!.filter(c => !backEdges.has(c) && orderIdx.has(c.source.node));
+      if (!ordered.length) return 0;
+      return avg(ordered.map(c => {
+        const parent = byId.get(c.source.node)!;
+        const outputs = nodeOutputs(parent, typeOf(parent.type));
+        const count = Math.max(outputs.length, 1);
+        const idx = Math.max(outputs.findIndex(p => p.id === c.source.port), 0);
+        return orderIdx.get(parent.id)! + (idx + 1) / (count + 1) - 0.5;
+      }));
+    };
+    layers[l].sort((a, b) => bary(a) - bary(b)).forEach((n, i) => orderIdx.set(n.id, i));
+  }
+
+  // 3. Coordinates: place a layer at each node's desired x, resolving overlaps
+  //    left-to-right, then shift the layer back so it stays centred on the wish.
+  const xs = new Map<string, number>();
+  const place = (layer: FlowNodeInstance[], desired: (n: FlowNodeInstance) => number | null) => {
+    const wishes = layer.map(n => desired(n) ?? xs.get(n.id) ?? 0);
+    let prev = -Infinity;
+    const placed = wishes.map(w => (prev = Math.max(w, prev + LAYOUT_H_GAP)));
+    const shift = avg(placed.map((x, i) => x - wishes[i]));
+    layer.forEach((n, i) => xs.set(n.id, placed[i] - shift));
+  };
+
+  const parentWish = (n: FlowNodeInstance): number | null => {
+    // Forward parents only, and only ones already placed (a loop's back-edge
+    // parent sits in a deeper layer).
+    const ins = incoming.get(n.id)!.filter(c => !backEdges.has(c) && xs.has(c.source.node));
+    return ins.length ? avg(ins.map(c => xs.get(c.source.node)! + branchOffset(c))) : null;
+  };
+  const childWish = (n: FlowNodeInstance): number | null => {
+    const outs = outgoing.get(n.id)!.filter(c => !backEdges.has(c) && xs.has(c.target.node));
+    return outs.length ? avg(outs.map(c => xs.get(c.target.node)! - branchOffset(c))) : null;
+  };
+
+  layers[0].forEach((n, i) => xs.set(n.id, i * LAYOUT_H_GAP));
+  for (let l = 1; l < layers.length; l++) place(layers[l], parentWish);   // down
+  for (let l = layers.length - 2; l >= 0; l--) place(layers[l], childWish); // up: recentre over children
+  for (let l = 1; l < layers.length; l++) place(layers[l], parentWish);   // settle
+
+  // Safety net: never emit a non-finite coordinate — a NaN here would leave
+  // nodes unpositioned (stacked at the origin).
+  const finite = [...xs.values()].filter(Number.isFinite);
+  const minX = finite.length ? Math.min(...finite) : 0;
+  nodes.forEach(n => {
+    const raw = xs.get(n.id);
+    out.set(n.id, {
+      x: snapToGrid(Number.isFinite(raw) ? (raw as number) - minX + MARGIN : MARGIN),
+      y: MARGIN + layerOf.get(n.id)! * LAYOUT_V_GAP,
+    });
+  });
+  return out;
+}