@kubex/zinc 1.1.22 → 1.1.24

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

@@ -0,0 +1,180 @@
+@use "../../../../wc";
+
+:host {
+  --node-accent: rgb(var(--zn-color-primary));
+  --port-size: 11px;
+
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: block;
+  user-select: none;
+  touch-action: none;
+}
+
+:host([dragging]) .card {
+  cursor: grabbing;
+}
+
+.card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  padding: 0 10px;
+  background: rgb(var(--zn-panel));
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 10px;
+  box-shadow: 0 1px 2px rgba(var(--zn-shadow), 0.4);
+  cursor: grab;
+  transition: border-color 0.12s ease, box-shadow 0.12s ease;
+
+  &:hover {
+    border-color: rgb(var(--zn-color-border-active));
+  }
+
+  &.selected {
+    border-color: var(--node-accent);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--node-accent) 35%, transparent);
+  }
+
+  // A stray branch is snapped here — glow as the drop target.
+  &.link-target {
+    border-color: rgb(var(--zn-color-primary));
+    box-shadow: 0 0 0 3px color-mix(in srgb, rgb(var(--zn-color-primary)) 30%, transparent);
+  }
+
+  &.error {
+    border-color: rgb(var(--zn-color-error));
+    background: color-mix(in srgb, rgb(var(--zn-color-error)) 6%, rgb(var(--zn-panel)));
+  }
+}
+
+.body {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.icon-tile {
+  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);
+}
+
+.text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1 1 auto;
+
+  .title {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    color: rgb(var(--zn-text));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .subtitle {
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
+.menu {
+  flex: 0 0 auto;
+  margin-right: -4px;
+}
+
+zn-menu-item.danger {
+  color: rgb(var(--zn-color-error));
+}
+
+.ports {
+  position: absolute;
+  left: 0;
+  width: 100%;
+  height: 0;
+
+  &--in {
+    top: 0;
+  }
+
+  &--out {
+    bottom: 0;
+  }
+}
+
+// Anchored at the card edge, at its horizontal position (set inline as left:%).
+.port-wrap {
+  position: absolute;
+}
+
+.port {
+  position: absolute;
+  left: 0;
+  top: 0;
+  transform: translate(-50%, -50%); // centre the dot on both the edge and the port x
+  width: var(--port-size);
+  height: var(--port-size);
+  border-radius: 50%;
+  background: rgb(var(--zn-panel));
+  border: 2px solid var(--node-accent);
+  box-sizing: border-box;
+  pointer-events: none;
+}
+
+// Input ports ease in and out of the snap highlight with the same timing as
+// the output ports' hover effect.
+.port--in {
+  transition: transform 0.12s ease, background 0.12s ease, box-shadow 0.12s ease;
+}
+
+// The snapped arrow lands on the input — light the port up while targeted.
+:host([link-target]) .port--in {
+  transform: translate(-50%, -50%) scale(1.4);
+  background: rgb(var(--zn-color-primary));
+  border-color: rgb(var(--zn-color-primary));
+  box-shadow: 0 0 0 4px color-mix(in srgb, rgb(var(--zn-color-primary)) 25%, transparent);
+}
+
+// Output ports are the branch spawn points: hover to highlight, click to start
+// a branch that follows the cursor to its target node.
+.port--out {
+  pointer-events: auto;
+  cursor: pointer;
+  transition: transform 0.12s ease, background 0.12s ease, box-shadow 0.12s ease;
+
+  &:hover {
+    transform: translate(-50%, -50%) scale(1.4);
+    background: var(--node-accent);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--node-accent) 25%, transparent);
+  }
+}
+
+// Output labels (e.g. TRUE / FALSE) sit just below the card edge, beside the
+// outgoing arrow — never overlapping the card content.
+.port-label {
+  position: absolute;
+  top: calc(var(--port-size) / 2 + 3px);
+  left: 8px;
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  color: rgb(var(--zn-color-muted-text));
+  white-space: nowrap;
+  pointer-events: none;
+}

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

@@ -0,0 +1,50 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import type {FlowNodeInstance, FlowNodeType} from '../../flow.types';
+import type ZnFlowNode from './flow-node.component';
+
+const splitType: FlowNodeType = {
+  type: 'split',
+  label: 'Conditional Split',
+  group: 'rule',
+  outputs: [{id: 'true', label: 'TRUE'}, {id: 'false', label: 'FALSE'}],
+};
+
+const node: FlowNodeInstance = {id: 'n1', type: 'split', x: 0, y: 0, data: {}};
+
+describe('<zn-flow-node>', () => {
+  it('should render a component', async () => {
+    const el = await fixture<ZnFlowNode>(html`
+      <zn-flow-node></zn-flow-node>`);
+    expect(el).to.exist;
+  });
+
+  it('should render the type label and one port per output', async () => {
+    const el = await fixture<ZnFlowNode>(html`
+      <zn-flow-node></zn-flow-node>`);
+    el.node = node;
+    el.type = splitType;
+    await el.updateComplete;
+
+    expect(el.shadowRoot?.querySelector('.title')?.textContent).to.contain('Conditional Split');
+    expect(el.shadowRoot?.querySelectorAll('.port--out')?.length).to.equal(2);
+    expect(el.shadowRoot?.querySelector('.port-label')?.textContent).to.contain('TRUE');
+  });
+
+  it('should emit flow-node-grab when the card body is pressed', async () => {
+    const el = await fixture<ZnFlowNode>(html`
+      <zn-flow-node></zn-flow-node>`);
+    el.node = node;
+    el.type = splitType;
+    await el.updateComplete;
+
+    let grabbedId = '';
+    el.addEventListener('flow-node-grab', (e: Event) => {
+      grabbedId = (e as CustomEvent<{ nodeId: string }>).detail.nodeId;
+    });
+    const card = el.shadowRoot?.querySelector('.card') as HTMLElement;
+    card.dispatchEvent(new PointerEvent('pointerdown', {bubbles: true, button: 0}));
+
+    expect(grabbedId).to.equal('n1');
+  });
+});

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

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

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

@@ -0,0 +1,88 @@
+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 ZnIcon from '../../../icon';
+
+import {emptyDragImage, FLOW_TYPE_MIME} from '../../flow.types';
+
+import styles from './flow-step.scss';
+
+/**
+ * @summary A draggable step in the `<zn-flow-steps>`, representing a registered node type. Drag
+ *   it onto the canvas (or a "+" slot) of a `<zn-flow-builder>` to add that step.
+ * @documentation https://zinc.style/components/flow-step
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-icon
+ *
+ * @event flow-step-drag - Emitted on dragstart with `detail.type`, so the builder can preview the drop.
+ * @event flow-step-drag-end - Emitted on dragend.
+ *
+ * @slot - The step's label.
+ *
+ * @csspart base - The row.
+ */
+export default class ZnFlowStep extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  static dependencies = {'zn-icon': ZnIcon};
+
+  /** The node type id this item creates when dropped. */
+  @property() type: string;
+  /** Display label; falls back to the slotted text. Also used as the node's label. */
+  @property() label: string;
+  @property() icon: string;
+  @property({attribute: 'icon-library'}) iconLibrary: string;
+  @property() color: string;
+  @property() description: string;
+  /** JSON array of input ports — `""` for a trigger (no input), omit for a single default input. */
+  @property() inputs: string;
+  /** JSON array of outputs (`"a"` or `{"id","label"}`), e.g. `'[{"id":"true","label":"TRUE"}]'`. Omit for one default output. */
+  @property() outputs: string;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.draggable = true;
+    this.addEventListener('dragstart', this._onDragStart);
+    this.addEventListener('dragend', this._onDragEnd);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('dragstart', this._onDragStart);
+    this.removeEventListener('dragend', this._onDragEnd);
+    super.disconnectedCallback();
+  }
+
+  protected updated(changed: PropertyValues) {
+    super.updated(changed);
+    this.style.setProperty('--node-accent', this.color ?? 'rgb(var(--zn-color-primary))');
+  }
+
+  private _onDragStart = (e: DragEvent) => {
+    if (!e.dataTransfer || !this.type) return;
+    e.dataTransfer.setData(FLOW_TYPE_MIME, this.type);
+    e.dataTransfer.effectAllowed = 'copyMove';
+    // Hide the native drag image — the builder shows an in-canvas preview instead.
+    e.dataTransfer.setDragImage(emptyDragImage(), 0, 0);
+    this.dispatchEvent(new CustomEvent('flow-step-drag', {
+      bubbles: true,
+      composed: true,
+      detail: {type: this.type}
+    }));
+  };
+
+  private _onDragEnd = () => {
+    this.dispatchEvent(new CustomEvent('flow-step-drag-end', {bubbles: true, composed: true}));
+  };
+
+  render() {
+    return html`
+      <span part="base" class="item__icon">
+        <zn-icon src="${this.icon ?? 'circle'}" library="${ifDefined(this.iconLibrary)}" size="16"></zn-icon>
+      </span>
+      <span class="item__label"><slot>${this.label ?? ''}</slot></span>
+    `;
+  }
+}

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

@@ -0,0 +1,52 @@
+@use "../../../../wc";
+
+:host {
+  //@include text-style(input-label);
+
+  --node-accent: rgb(var(--zn-color-primary));
+
+  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;
+  overflow: hidden;
+  cursor: grab;
+  transition: border-color 0.12s ease, box-shadow 0.12s ease;
+  max-height: 40px;
+}
+
+:host(:hover) {
+  border-color: rgb(var(--zn-color-border-active));
+  box-shadow: 0 1px 3px rgba(var(--zn-shadow), 0.4);
+}
+
+:host(:active) {
+  cursor: grabbing;
+}
+
+:host([hidden]) {
+  display: none;
+}
+
+.item__icon {
+  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);
+}
+
+.item__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

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

@@ -0,0 +1,21 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import type ZnFlowStep from './flow-step.component';
+
+describe('<zn-flow-step>', () => {
+  it('should render a component', async () => {
+    const el = await fixture<ZnFlowStep>(html`
+      <zn-flow-step type="webhook">Webhook</zn-flow-step>`);
+    expect(el).to.exist;
+    expect(el.draggable).to.equal(true);
+  });
+
+  it('should put its type on the dataTransfer at dragstart', async () => {
+    const el = await fixture<ZnFlowStep>(html`
+      <zn-flow-step type="webhook">Webhook</zn-flow-step>`);
+
+    const dt = new DataTransfer();
+    el.dispatchEvent(new DragEvent('dragstart', {dataTransfer: dt, bubbles: true}));
+    expect(dt.getData('application/x-zn-flow-type')).to.equal('webhook');
+  });
+});

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

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

package/src/components/flow-builder/modules/flow-step-group/flow-step-group.component.ts

@@ -0,0 +1,35 @@
+import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {property} from 'lit/decorators.js';
+import ZincElement from '../../../../internal/zinc-element';
+import ZnCollapsible from '../../../collapsible';
+
+import styles from './flow-step-group.scss';
+
+/**
+ * @summary A collapsible category of `<zn-flow-step>`s inside a `<zn-flow-steps>` (typically a `<zn-tabs>` panel).
+ *   Wraps `<zn-collapsible>` for the standard expand/collapse behaviour and spacing.
+ * @documentation https://zinc.style/components/flow-step-group
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-collapsible
+ *
+ * @slot - The group's `<zn-flow-step>`s.
+ */
+export default class ZnFlowStepGroup extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  static dependencies = {'zn-collapsible': ZnCollapsible};
+
+  @property() caption: string;
+  /** Start collapsed. Defaults to open. */
+  @property({type: Boolean, reflect: true}) collapsed = false;
+
+  render() {
+    return html`
+      <zn-collapsible caption="${this.caption ?? ''}" default="${this.collapsed ? 'closed' : 'open'}">
+        <slot></slot>
+      </zn-collapsible>
+    `;
+  }
+}

package/src/components/flow-builder/modules/flow-step-group/flow-step-group.scss

@@ -0,0 +1,28 @@
+@use "../../../../wc";
+
+:host {
+  display: block;
+}
+
+:host([hidden]) {
+  display: none;
+}
+
+zn-collapsible {
+  // 16px block padding on the header (inline stays the collapsible's 24px). The
+  // !important beats the collapsible's internal `.header` class specificity.
+  // align-items centres the caption with the chevron regardless of the header's
+  // internal column layout.
+  &::part(header) {
+    align-items: center !important;
+    padding-block: calc(var(--zn-base-px) * 2) !important;
+  }
+
+  // Caption type: Inter SemiBold 14 / 16 (Primary text).
+  &::part(caption) {
+    font-size: 14px;
+    font-weight: 600;
+    line-height: 16px;
+    color: rgb(var(--zn-text));
+  }
+}

package/src/components/flow-builder/modules/flow-step-group/flow-step-group.test.ts

@@ -0,0 +1,20 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import type ZnFlowStepGroup from './flow-step-group.component';
+
+describe('<zn-flow-step-group>', () => {
+  it('should render a component with its caption', async () => {
+    const el = await fixture<ZnFlowStepGroup>(html`
+      <zn-flow-step-group caption="Contacts"></zn-flow-step-group>`);
+    expect(el.shadowRoot?.querySelector('.header')?.textContent).to.contain('Contacts');
+  });
+
+  it('should toggle collapsed when the header is clicked', async () => {
+    const el = await fixture<ZnFlowStepGroup>(html`
+      <zn-flow-step-group caption="Contacts"></zn-flow-step-group>`);
+    const header = el.shadowRoot?.querySelector('.header') as HTMLElement;
+    header.click();
+    await el.updateComplete;
+    expect(el.collapsed).to.equal(true);
+  });
+});

package/src/components/flow-builder/modules/flow-step-group/index.ts

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

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

@@ -0,0 +1,88 @@
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
+import {property, state} from 'lit/decorators.js';
+import ZincElement from '../../../../internal/zinc-element';
+import ZnInput from '../../../input';
+
+import styles from './flow-steps.scss';
+
+/**
+ * @summary A search + scroll wrapper for building a standalone steps panel. Place a standard
+ *   `<zn-tabs>` (with a `<zn-navbar slot="top">` and panels of `<zn-flow-step-group>` /
+ *   `<zn-flow-step>`) inside it; the search box filters the slotted items.
+ * @documentation https://zinc.style/components/flow-steps
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-input
+ *
+ * @slot - The steps panel content, typically a `<zn-tabs>`.
+ *
+ * @csspart search - The search input.
+ */
+export default class ZnFlowSteps extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  static dependencies = {'zn-input': ZnInput};
+
+  @property({type: Boolean}) searchable = true;
+  @property({attribute: 'search-placeholder'}) searchPlaceholder = 'Search by step name';
+
+  @state() private _search = '';
+
+  /** Re-applies the filter when zn-tabs moves `selected` to another panel. */
+  private _tabObserver = new MutationObserver(() => this._applyFilter());
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._tabObserver.observe(this, {subtree: true, attributeFilter: ['selected']});
+  }
+
+  disconnectedCallback() {
+    this._tabObserver.disconnect();
+    super.disconnectedCallback();
+  }
+
+  protected updated(changed: PropertyValues) {
+    super.updated(changed);
+    this._applyFilter();
+  }
+
+  /** True when the element isn't tabbed, or sits in the active (selected) tab panel. */
+  private _inActiveTab(el: HTMLElement): boolean {
+    return !el.closest('zn-tabs') || !!el.closest('[selected]');
+  }
+
+  /** Filter the slotted items (and hide emptied groups) by the search term — active tab only. */
+  private _applyFilter() {
+    const term = this._search.trim().toLowerCase();
+
+    this.querySelectorAll<HTMLElement>('zn-flow-step').forEach(it => {
+      it.hidden = term !== '' && this._inActiveTab(it) && !(it.textContent ?? '').toLowerCase().includes(term);
+    });
+    this.querySelectorAll<HTMLElement>('zn-flow-step-group').forEach(g => {
+      const items = Array.from(g.querySelectorAll<HTMLElement>('zn-flow-step'));
+      g.hidden = term !== '' && this._inActiveTab(g) && items.length > 0 && items.every(it => it.hidden);
+    });
+  }
+
+  render() {
+    return html`
+      ${this.searchable
+        ? html`
+          <zn-input
+            part="search"
+            class="search"
+            placeholder="${this.searchPlaceholder}"
+            clearable
+            .value="${this._search}"
+            @zn-input="${(e: Event) => (this._search = String((e.target as ZnInput).value ?? ''))}"
+            @input="${(e: Event) => (this._search = String((e.target as ZnInput).value ?? ''))}"
+          ></zn-input>`
+        : ''}
+
+      <div class="body">
+        <slot></slot>
+      </div>
+    `;
+  }
+}

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

@@ -0,0 +1,24 @@
+@use "../../../../wc";
+
+:host {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  height: 100%;
+  // Make the slotted zn-navbar's active tab panel-coloured (white) to match the
+  // steps-panel surface, rather than the navbar's default body colour.
+  --zn-active-nav-background: var(--zn-panel);
+}
+
+.search {
+  // Inline padding matches the standard --zn-base-gap (24px) used by the panels.
+  padding: 12px var(--zn-base-gap) 8px;
+}
+
+// Holds the slotted <zn-tabs>, which fills the remaining height and scrolls.
+.body {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}

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

@@ -0,0 +1,17 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import type ZnFlowSteps from './flow-steps.component';
+
+describe('<zn-flow-steps>', () => {
+  it('should render a search box and slot its content', async () => {
+    const el = await fixture<ZnFlowSteps>(html`
+      <zn-flow-steps>
+        <zn-flow-step type="a">Apple</zn-flow-step>
+        <zn-flow-step type="b">Banana</zn-flow-step>
+      </zn-flow-steps>`);
+    await el.updateComplete;
+
+    expect(el.shadowRoot?.querySelector('.search')).to.exist;
+    expect(el.querySelectorAll('zn-flow-step')).to.have.length(2);
+  });
+});

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

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

package/src/events/events.ts

@@ -12,3 +12,6 @@ export type {ZnLanguageChangeEvent} from './zn-language-change';
 export type {ZnReorderEvent} from './zn-reorder';
 export type {ZnAcceptEvent} from './zn-accept';
 export type {ZnRejectEvent} from './zn-reject';
+export type {ZnFlowChangeEvent} from './zn-flow-change';
+export type {ZnFlowSelectionChangeEvent} from './zn-flow-selection-change';
+export type {ZnFlowConnectEvent} from './zn-flow-connect';

package/src/events/zn-flow-change.ts

@@ -0,0 +1,9 @@
+import type {FlowState} from '../components/flow-builder/flow.types';
+
+export type ZnFlowChangeEvent = CustomEvent<{ state: FlowState }>;
+
+declare global {
+  interface GlobalEventHandlersEventMap {
+    'zn-flow-change': ZnFlowChangeEvent;
+  }
+}