@kubex/zinc 1.1.22 → 1.1.24

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

@@ -0,0 +1,371 @@
+@use "../../../../wc";
+
+:host {
+  display: block;
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+.viewport {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  background-color: rgb(var(--zn-color-body));
+  background-image: radial-gradient(rgb(var(--zn-color-border)) 1px, transparent 1px);
+  background-size: 20px 20px; // matches GRID_SIZE — positions snap to these dots
+  cursor: grab;
+  touch-action: none;
+
+  // During a move/pan drag, force grabbing across the canvas and its notes.
+  // (The dragged node card is handled inside its own shadow via [dragging].)
+  &.grabbing,
+  &.grabbing * {
+    cursor: grabbing !important;
+  }
+
+  &.connecting,
+  &.connecting * {
+    cursor: crosshair !important;
+  }
+
+  &.resizing,
+  &.resizing * {
+    cursor: nwse-resize !important;
+  }
+}
+
+.connections {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  overflow: visible;
+
+  .wire {
+    fill: none;
+    stroke: rgb(var(--zn-color-primary));
+    stroke-width: 2;
+  }
+
+  .wire--stub {
+    stroke: rgb(var(--zn-color-border-active));
+    stroke-dasharray: 4 4;
+  }
+
+  // The stray branch following the cursor while picking a node to attach to.
+  .wire--preview {
+    stroke-dasharray: 6 4;
+  }
+
+  // A wire that loops back to an earlier step — solid amber, so return paths
+  // stand out from the forward flow.
+  .wire--loop {
+    stroke: rgb(var(--zn-color-warning));
+  }
+
+  marker path {
+    fill: rgb(var(--zn-color-primary));
+  }
+
+  marker#flow-arrow-loop path {
+    fill: rgb(var(--zn-color-warning));
+  }
+}
+
+// While a stray branch is live, everything is either a target (a node) or a cancel.
+.viewport.linking {
+  cursor: crosshair;
+}
+
+.add-point {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  margin: -12px; // centre on the transformed point
+  padding: 0;
+  border-radius: 50%;
+  color: rgb(var(--zn-color-primary));
+  background: rgb(var(--zn-panel));
+  border: 1px dashed rgb(var(--zn-color-border-active));
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+
+  &:hover {
+    color: rgb(var(--zn-panel));
+    background: rgb(var(--zn-color-primary));
+    border-style: solid;
+  }
+
+  &--target {
+    color: rgb(var(--zn-panel));
+    background: rgb(var(--zn-color-primary));
+    border-style: solid;
+    box-shadow: 0 0 0 4px color-mix(in srgb, rgb(var(--zn-color-primary)) 25%, transparent);
+  }
+
+  &--wire {
+    width: 20px;
+    height: 20px;
+    margin: -10px;
+  }
+}
+
+// While dragging a step, emphasise every "+" so the drop targets are obvious.
+.viewport.step-dragging .add-point {
+  color: rgb(var(--zn-panel));
+  background: rgb(var(--zn-color-primary));
+  border-style: solid;
+  box-shadow: 0 0 0 4px color-mix(in srgb, rgb(var(--zn-color-primary)) 22%, transparent);
+}
+
+.layer {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: 0 0;
+  width: 0;
+  height: 0;
+}
+
+.node-pos {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
+// Branch names rendered as a clickable pill on their branch; the wire drops
+// into the pill's top and continues from its bottom. Clicking opens the editor;
+// hovering slides out a delete button to the right.
+.branch-pill-wrap {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: stretch;
+
+  // Invisible bridge so the cursor can travel from the pill to the delete
+  // button without the hover (and the button) disappearing.
+  &::after {
+    content: '';
+    position: absolute;
+    left: 100%;
+    top: 0;
+    width: 40px;
+    height: 100%;
+  }
+
+  // The reveal is slightly delayed so pills that shift under a stationary
+  // cursor (e.g. re-spreading after a sibling branch is deleted) don't flash
+  // their delete button; hiding stays immediate.
+  &:hover .branch-pill-delete {
+    opacity: 1;
+    transform: translate(0, -50%);
+    pointer-events: auto;
+    transition-delay: 0.15s;
+  }
+}
+
+.branch-pill {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  // Size to the text, hard-wrapping at PILL_MAX_WIDTH — width: max-content
+  // stops overflow-wrap: anywhere collapsing the shrink-wrapped pill to a
+  // single character column. Height is intrinsic: fixed padding around
+  // 20px lines (one line = 40px tall, matching PILL_HEIGHT).
+  width: max-content;
+  max-width: 240px;
+  box-sizing: border-box;
+  text-align: center;
+  overflow-wrap: anywhere;
+  overflow: hidden;
+  padding: 0 18px;
+  border-radius: 10px; // matches the node cards
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  // After the font shorthand, which would reset it — matches PILL_LINE_HEIGHT
+  // so wrapped lines track the estimated pill height.
+  line-height: 20px;
+  color: rgb(var(--zn-text));
+  background: color-mix(in srgb, rgb(var(--zn-color-primary)) 8%, rgb(var(--zn-panel)));
+  border: 1px solid color-mix(in srgb, rgb(var(--zn-color-primary)) 45%, transparent);
+  cursor: pointer;
+  transition: border-color 0.12s ease, box-shadow 0.12s ease;
+
+  &:hover {
+    border-color: rgb(var(--zn-color-primary));
+    box-shadow: 0 1px 3px rgba(var(--zn-shadow), 0.4);
+  }
+
+  &--selected {
+    border-color: rgb(var(--zn-color-primary));
+    background: color-mix(in srgb, rgb(var(--zn-color-primary)) 16%, rgb(var(--zn-panel)));
+  }
+
+  // A loop branch — amber to match its return wire.
+  &--loop {
+    background: color-mix(in srgb, rgb(var(--zn-color-warning)) 10%, rgb(var(--zn-panel)));
+    border-color: color-mix(in srgb, rgb(var(--zn-color-warning)) 55%, transparent);
+
+    &:hover {
+      border-color: rgb(var(--zn-color-warning));
+    }
+
+    &.branch-pill--selected {
+      border-color: rgb(var(--zn-color-warning));
+      background: color-mix(in srgb, rgb(var(--zn-color-warning)) 18%, rgb(var(--zn-panel)));
+    }
+  }
+}
+
+// Slides out from behind the pill on hover; deletes the branch and its wire.
+// Sits above the wrap's ::after hover bridge, which would otherwise swallow
+// clicks (and the pointer cursor).
+.branch-pill-delete {
+  position: absolute;
+  z-index: 1;
+  left: calc(100% + 8px);
+  top: 50%;
+  transform: translate(-10px, -50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: rgb(var(--zn-color-error));
+  color: white;
+  cursor: pointer;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease, transform 0.15s ease;
+
+  &:hover {
+    filter: brightness(1.1);
+  }
+}
+
+// Placeholder shown while dragging a step over the canvas — previews
+// the step that will be created, so you can see what and where it lands.
+.drop-ghost {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 0 12px;
+  border: 2px dashed rgb(var(--zn-color-primary));
+  border-radius: 10px;
+  background: color-mix(in srgb, rgb(var(--zn-color-primary)) 10%, rgb(var(--zn-panel)));
+  opacity: 0.9;
+  pointer-events: none;
+
+  &__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) 16%, rgb(var(--zn-panel)));
+  }
+
+  &__label {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    color: rgb(var(--zn-text));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
+.toolbar {
+  position: absolute;
+  top: 16px;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background: rgb(var(--zn-panel));
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  box-shadow: 0 1px 3px rgba(var(--zn-shadow), 0.4);
+  z-index: 2;
+
+  &--history {
+    left: 16px;
+  }
+
+  &--zoom {
+    right: 16px;
+  }
+}
+
+.note {
+  position: absolute;
+  display: flex;
+  flex-direction: column;
+  background: #fef9c3;
+  border: 1px solid #fde68a;
+  border-radius: 4px;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
+}
+
+.note__resize {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 16px;
+  height: 16px;
+  cursor: nwse-resize;
+  // Visual corner grip.
+  background: linear-gradient(135deg, transparent 0 50%, #d9c64a 50% 60%, transparent 60% 70%, #d9c64a 70% 80%, transparent 80%);
+}
+
+.note__bar {
+  display: flex;
+  justify-content: flex-end;
+  height: 20px;
+  cursor: grab;
+}
+
+.note__close {
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  font-size: 14px;
+  line-height: 1;
+  color: #92400e;
+  background: transparent;
+  cursor: pointer;
+}
+
+.note__text {
+  flex: 1;
+  margin: 0;
+  padding: 0 10px 10px;
+  resize: none;
+  border: none;
+  outline: none;
+  background: transparent;
+  font: inherit;
+  font-size: 0.8125rem;
+  color: #713f12;
+}

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

@@ -0,0 +1,39 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import {FlowRegistry} from '../../flow-registry';
+import type {FlowNodeInstance} from '../../flow.types';
+import type ZnFlowCanvas from './flow-canvas.component';
+
+describe('<zn-flow-canvas>', () => {
+  it('should render a component', async () => {
+    const el = await fixture<ZnFlowCanvas>(html`
+      <zn-flow-canvas></zn-flow-canvas>`);
+    expect(el).to.exist;
+    expect(el.shadowRoot?.querySelector('.toolbar--zoom')).to.exist;
+  });
+
+  it('should render one flow node per node in the model', async () => {
+    const registry = new FlowRegistry();
+    registry.register({type: 'a', label: 'A', group: 'action'});
+    const nodes: FlowNodeInstance[] = [
+      {id: 'n1', type: 'a', x: 0, y: 0, data: {}},
+      {id: 'n2', type: 'a', x: 100, y: 100, data: {}},
+    ];
+    const el = await fixture<ZnFlowCanvas>(html`
+      <zn-flow-canvas></zn-flow-canvas>`);
+    el.registry = registry;
+    el.nodes = nodes;
+    await el.updateComplete;
+
+    expect(el.shadowRoot?.querySelectorAll('zn-flow-node')?.length).to.equal(2);
+  });
+
+  it('should map screen coordinates to canvas space at the default transform', async () => {
+    const el = await fixture<ZnFlowCanvas>(html`
+      <zn-flow-canvas></zn-flow-canvas>`);
+    const rect = el.getBoundingClientRect();
+    const pt = el.screenToCanvas(rect.left + 50, rect.top + 80);
+    expect(pt.x).to.be.closeTo(50, 0.5);
+    expect(pt.y).to.be.closeTo(80, 0.5);
+  });
+});

package/src/components/flow-builder/modules/flow-canvas/index.ts

@@ -0,0 +1,12 @@
+import ZnFlowCanvas from './flow-canvas.component';
+
+export * from './flow-canvas.component';
+export default ZnFlowCanvas;
+
+ZnFlowCanvas.define('zn-flow-canvas');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-flow-canvas': ZnFlowCanvas;
+  }
+}

package/src/components/flow-builder/modules/flow-node/flow-node.component.ts

@@ -0,0 +1,174 @@
+import {classMap} from 'lit/directives/class-map.js';
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
+import {ifDefined} from 'lit/directives/if-defined.js';
+import {property} from 'lit/decorators.js';
+import ZincElement from '../../../../internal/zinc-element';
+import ZnButton from '../../../button';
+import ZnDropdown from '../../../dropdown';
+import ZnIcon from '../../../icon';
+import ZnMenu from '../../../menu';
+import ZnMenuItem from '../../../menu-item';
+
+import {
+  type FlowNodeInstance,
+  type FlowNodeType,
+  type FlowPort,
+  NODE_HEIGHT,
+  NODE_WIDTH,
+  nodeInputs,
+  nodeOutputs,
+} from '../../flow.types';
+
+import styles from './flow-node.scss';
+
+/**
+ * @summary A single node tile on the flow canvas, with input/output ports and a context menu.
+ * @documentation https://zinc.style/components/flow-node
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-icon
+ * @dependency zn-button
+ * @dependency zn-dropdown
+ * @dependency zn-menu
+ * @dependency zn-menu-item
+ *
+ * @event flow-node-select - Emitted when the node body is clicked.
+ * @event flow-node-grab - Emitted on pointerdown of the node body to begin a move (handled by the canvas).
+ * @event flow-node-action - Emitted when a context-menu action (delete/duplicate/move) is chosen.
+ * @event flow-port-click - An output port was clicked; the canvas starts (or attaches) a branch.
+ *
+ * @csspart base - The node card wrapper.
+ */
+export default class ZnFlowNode extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  static dependencies = {
+    'zn-icon': ZnIcon,
+    'zn-button': ZnButton,
+    'zn-dropdown': ZnDropdown,
+    'zn-menu': ZnMenu,
+    'zn-menu-item': ZnMenuItem,
+  };
+
+  @property({attribute: false}) node: FlowNodeInstance;
+  @property({attribute: false}) type: FlowNodeType;
+
+  @property({type: Boolean, reflect: true}) selected = false;
+  @property({type: Boolean, reflect: true}) error = false;
+  @property({type: Boolean, reflect: true}) dragging = false;
+  /** A stray branch is snapped onto this node — highlight it as the drop target. */
+  @property({type: Boolean, reflect: true, attribute: 'link-target'}) linkTarget = false;
+
+  protected updated(changed: PropertyValues) {
+    super.updated(changed);
+    // Position is owned by the canvas (a transformed wrapper) so it updates live
+    // during a drag; the node owns only its size and accent colour.
+    this.style.width = `${NODE_WIDTH}px`;
+    this.style.height = `${NODE_HEIGHT}px`;
+    this.style.setProperty('--node-accent', this.type?.color ?? 'rgb(var(--zn-color-primary))');
+  }
+
+  private get nodeTitle(): string {
+    return this.node?.label ?? this.type?.label ?? this.node?.type ?? 'Node';
+  }
+
+  private get nodeSubtitle(): string {
+    const sub = this.node?.data?.['subtitle'] ?? this.node?.data?.['description'];
+    return typeof sub === 'string' ? sub : (this.type?.description ?? '');
+  }
+
+  private _emit(name: string, detail: Record<string, unknown>) {
+    this.dispatchEvent(new CustomEvent(name, {bubbles: true, composed: true, detail}));
+  }
+
+  private _onBodyPointerDown = (e: PointerEvent) => {
+    if (e.button !== 0) return;
+    const target = e.target as HTMLElement;
+    if (target.closest('.port') || target.closest('zn-dropdown')) return;
+    e.stopPropagation();
+    this._emit('flow-node-select', {nodeId: this.node.id});
+    this._emit('flow-node-grab', {nodeId: this.node.id, clientX: e.clientX, clientY: e.clientY});
+  };
+
+  private _action(action: 'delete' | 'duplicate' | 'move') {
+    this._emit('flow-node-action', {nodeId: this.node.id, action});
+  }
+
+  // Input ports are visual anchors only; the output stem port (rendered in
+  // `render`) spawns a branch on click.
+  private _renderPorts(ports: FlowPort[], side: 'in' | 'out') {
+    const count = ports.length;
+    return html`
+      <div class="ports ports--${side}">
+        ${ports.map((port, i) => {
+      const left = `${(100 * (i + 1)) / (count + 1)}%`;
+      return html`
+            <div class="port-wrap" style="left:${left}">
+              ${side === 'out' && port.label
+        ? html`<span class="port-label">${port.label}</span>`
+        : ''}
+              <span class="port port--${side}" data-node="${this.node.id}" data-port="${port.id}"></span>
+            </div>
+          `;
+    })}
+      </div>
+    `;
+  }
+
+  render() {
+    if (!this.node) return html``;
+
+    const inputs = nodeInputs(this.node, this.type);
+    const outputs = nodeOutputs(this.node, this.type);
+
+    return html`
+      <div
+        part="base"
+        class="${classMap({card: true, selected: this.selected, error: this.error, 'link-target': this.linkTarget})}"
+        @pointerdown="${this._onBodyPointerDown}"
+      >
+        ${inputs.length ? this._renderPorts(inputs, 'in') : ''}
+
+        <div class="body">
+          <div class="icon-tile">
+            ${this.type?.icon
+      ? html`
+                <zn-icon src="${this.type.icon}" library="${ifDefined(this.type.iconLibrary)}" size="20"></zn-icon>`
+      : html`
+                <zn-icon src="circle" library="lucide" size="20"></zn-icon>`}
+          </div>
+          <div class="text">
+            <span class="title">${this.nodeTitle}</span>
+            ${this.nodeSubtitle ? html`<span class="subtitle">${this.nodeSubtitle}</span>` : ''}
+          </div>
+          <zn-dropdown class="menu">
+            <zn-button slot="trigger" icon="ellipsis@lu" icon-size="20" icon-button="small" plain></zn-button>
+            <zn-menu>
+              <zn-menu-item class="danger" @click="${() => this._action('delete')}">Delete</zn-menu-item>
+              <zn-menu-item @click="${() => this._action('move')}">Move</zn-menu-item>
+              <zn-menu-item @click="${() => this._action('duplicate')}">Duplicate</zn-menu-item>
+            </zn-menu>
+          </zn-dropdown>
+        </div>
+
+        ${outputs.length
+      ? html`
+            <div class="ports ports--out">
+              <div class="port-wrap" style="left:50%">
+                <span
+                  class="port port--out"
+                  title="Start a branch"
+                  @pointerdown="${(e: PointerEvent) => e.button === 0 && e.stopPropagation()}"
+                  @click="${(e: Event) => {
+        e.stopPropagation();
+        this._emit('flow-port-click', {nodeId: this.node.id});
+      }}"
+                ></span>
+              </div>
+            </div>`
+      : ''}
+      </div>
+    `;
+  }
+}