@kubex/zinc 1.1.28 → 1.1.31

package/src/components/flow-builder/modules/flow-branch-conditions/flow-branch-conditions.component.ts

@@ -0,0 +1,300 @@
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
+import {property, state} from 'lit/decorators.js';
+import ZincElement from '../../../../internal/zinc-element';
+import ZnButton from '../../../button';
+import ZnIcon from '../../../icon';
+import ZnInput from '../../../input';
+import ZnOption from '../../../option';
+import ZnSelect from '../../../select';
+
+import {
+  type FlowBranchCondition,
+  type FlowBranchConditions,
+  type FlowBranchFilter,
+  type FlowFilterField,
+  operatorLabel,
+} from '../../flow.types';
+
+import styles from './flow-branch-conditions.scss';
+
+/**
+ * @summary The built-in branch conditions editor: pick filters from a searchable list, then
+ *   combine them into AND groups joined by OR. Rendered by `<zn-flow-builder>`'s branch editor
+ *   for node types that declare `branchFilters`; edits are drafted locally and only applied
+ *   on Save.
+ * @documentation https://zinc.style/components/flow-branch-conditions
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-button
+ * @dependency zn-icon
+ * @dependency zn-input
+ * @dependency zn-option
+ * @dependency zn-select
+ *
+ * @event flow-conditions-save - Emitted on Save with `detail.conditions` (OR groups of AND-ed conditions).
+ * @event flow-conditions-cancel - Emitted on Cancel, with the draft discarded.
+ *
+ * @csspart base - The editor wrapper.
+ * @csspart picker - The filter picker (search + list).
+ * @csspart conditions - The configured condition groups.
+ */
+export default class ZnFlowBranchConditions extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  static dependencies = {
+    'zn-button': ZnButton,
+    'zn-icon': ZnIcon,
+    'zn-input': ZnInput,
+    'zn-option': ZnOption,
+    'zn-select': ZnSelect,
+  };
+
+  /** The filters available to build conditions from. */
+  @property({attribute: false}) filters: FlowBranchFilter[] = [];
+
+  /** The saved conditions being edited; changes stay in a local draft until Save. */
+  @property({attribute: false}) value: FlowBranchConditions = [];
+
+  @state() private _draft: FlowBranchConditions = [];
+  /** Group index the picker adds into (`_draft.length` starts a new OR group), or null when closed. */
+  @state() private _picker: number | null = null;
+  @state() private _search = '';
+
+  /** JSON of the last `value` the draft was built from, so re-renders that pass an
+   *  equivalent value (fresh array refs) don't wipe in-progress edits. */
+  private _valueJson = '';
+
+  protected willUpdate(changed: PropertyValues) {
+    super.willUpdate(changed);
+    if (changed.has('value')) {
+      const json = JSON.stringify(this.value ?? []);
+      if (json !== this._valueJson) {
+        this._valueJson = json;
+        this._draft = JSON.parse(json) as FlowBranchConditions;
+        this._picker = null;
+        this._search = '';
+      }
+    }
+  }
+
+  private _emit(name: string, detail?: Record<string, unknown>) {
+    this.dispatchEvent(new CustomEvent(name, {bubbles: true, composed: true, detail}));
+  }
+
+  private _save = () => {
+    this._emit('flow-conditions-save', {conditions: JSON.parse(JSON.stringify(this._draft)) as FlowBranchConditions});
+  };
+
+  private _cancel = () => {
+    this._emit('flow-conditions-cancel');
+  };
+
+  // --- Draft edits ------------------------------------------------------------
+
+  private _cloneDraft(): FlowBranchConditions {
+    return this._draft.map(group => group.map(c => ({...c, values: {...c.values}})));
+  }
+
+  private _addCondition(filter: FlowBranchFilter) {
+    const values: FlowBranchCondition['values'] = {};
+    filter.fields.forEach(f => {
+      values[f.id] = {
+        ...(f.operators?.length ? {operator: f.operators[0].value} : {}),
+        ...(f.value !== undefined ? {value: f.value} : {}),
+        ...(f.units?.length ? {unit: f.units[0].value} : {}),
+      };
+    });
+    const draft = this._cloneDraft();
+    const group = Math.min(this._picker ?? 0, draft.length);
+    if (group === draft.length) draft.push([]);
+    draft[group].push({filter: filter.id, values});
+    this._draft = draft;
+    this._picker = null;
+    this._search = '';
+  }
+
+  private _removeCondition(group: number, index: number) {
+    const draft = this._cloneDraft();
+    draft[group].splice(index, 1);
+    this._draft = draft.filter(g => g.length);
+  }
+
+  private _setField(group: number, index: number, fieldId: string, patch: { operator?: string; value?: string | number; unit?: string }) {
+    const draft = this._cloneDraft();
+    const condition = draft[group][index];
+    condition.values[fieldId] = {...condition.values[fieldId], ...patch};
+    this._draft = draft;
+  }
+
+  // --- Rendering --------------------------------------------------------------
+
+  private _renderPicker() {
+    const term = this._search.trim().toLowerCase();
+    const matches = this.filters.filter(f => !term || f.label.toLowerCase().includes(term));
+
+    return html`
+      <div part="picker" class="picker">
+        <div class="picker__head">
+          <span>Add Filters</span>
+          ${this._draft.length ? html`
+            <zn-button
+              class="picker__back"
+              icon="x@lu"
+              icon-button="small"
+              plain
+              title="Back to conditions"
+              @click="${() => (this._picker = null)}"
+            ></zn-button>` : ''}
+        </div>
+        <zn-input
+          class="picker__search"
+          placeholder="Search filters..."
+          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-icon slot="suffix" src="search@lu" size="16"></zn-icon>
+        </zn-input>
+        <div class="picker__list">
+          ${matches.length === 0
+            ? html`<p class="picker__empty">No matching filters.</p>`
+            : matches.map(f => html`
+              <button class="picker__item" @click="${() => this._addCondition(f)}">
+                <span class="picker__item-text">
+                  <span class="picker__item-label">${f.label}</span>
+                  ${f.description ? html`<span class="picker__item-description">${f.description}</span>` : ''}
+                </span>
+                <zn-icon src="arrow-right@lu" size="16"></zn-icon>
+              </button>`)}
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * A select's minimum width, sized so its longest label never truncates
+   * (estimated per char, plus padding and the chevron). When the row can't
+   * fit it, flex-wrap gives the select its own full-width line instead.
+   */
+  private static _selectMinWidth(labels: string[]): number {
+    const longest = Math.max(0, ...labels.map(l => l.length));
+    return Math.min(260, Math.round(52 + longest * 7.2));
+  }
+
+  private _renderField(condition: FlowBranchCondition, group: number, index: number, field: FlowFilterField) {
+    const entry = condition.values[field.id] ?? {};
+    const type = field.type ?? (field.options?.length ? 'select' : 'text');
+    const set = (patch: { operator?: string; value?: string | number; unit?: string }) =>
+      this._setField(group, index, field.id, patch);
+
+    return html`
+      <div class="condition__row">
+        ${field.label ? html`<span class="condition__row-label">${field.label}</span>` : ''}
+        ${field.operators?.length ? html`
+          <zn-select
+            class="control control--operator"
+            size="small"
+            style="min-width:${ZnFlowBranchConditions._selectMinWidth(field.operators.map(o => operatorLabel(o)))}px"
+            .value="${entry.operator ?? field.operators[0].value}"
+            @zn-change="${(e: Event) => set({operator: String((e.target as ZnSelect).value)})}"
+          >
+            ${field.operators.map(o => html`
+              <zn-option value="${o.value}">${operatorLabel(o)}</zn-option>`)}
+          </zn-select>` : ''}
+        ${type === 'select' ? html`
+          <zn-select
+            class="control control--value"
+            size="small"
+            style="min-width:${ZnFlowBranchConditions._selectMinWidth((field.options ?? []).map(o => o.label ?? o.value))}px"
+            placeholder="${field.placeholder ?? ''}"
+            .value="${String(entry.value ?? '')}"
+            @zn-change="${(e: Event) => set({value: String((e.target as ZnSelect).value)})}"
+          >
+            ${(field.options ?? []).map(o => html`
+              <zn-option value="${o.value}">${o.label ?? o.value}</zn-option>`)}
+          </zn-select>` : html`
+          <zn-input
+            class="control ${type === 'number' ? 'control--number' : 'control--value'}"
+            size="small"
+            type="${type}"
+            .value="${String(entry.value ?? '')}"
+            placeholder="${field.placeholder ?? ''}"
+            @zn-input="${(e: Event) => {
+              const raw = String((e.target as ZnInput).value ?? '');
+              set({value: type === 'number' ? Number(raw) : raw});
+            }}"
+            @input="${(e: Event) => {
+              const raw = String((e.target as ZnInput).value ?? '');
+              set({value: type === 'number' ? Number(raw) : raw});
+            }}"
+          ></zn-input>`}
+        ${field.units?.length ? html`
+          <zn-select
+            class="control control--unit"
+            size="small"
+            style="min-width:${ZnFlowBranchConditions._selectMinWidth(field.units.map(u => u.label ?? u.value))}px"
+            .value="${entry.unit ?? field.units[0].value}"
+            @zn-change="${(e: Event) => set({unit: String((e.target as ZnSelect).value)})}"
+          >
+            ${field.units.map(u => html`
+              <zn-option value="${u.value}">${u.label ?? u.value}</zn-option>`)}
+          </zn-select>`
+          : field.suffix ? html`<span class="condition__suffix">${field.suffix}</span>` : ''}
+      </div>
+    `;
+  }
+
+  private _renderCondition(condition: FlowBranchCondition, group: number, index: number) {
+    const filter = this.filters.find(f => f.id === condition.filter);
+    return html`
+      <div class="condition">
+        <div class="condition__head">
+          <span class="condition__name">${filter?.label ?? condition.filter}</span>
+          <zn-button class="condition__remove" title="Remove filter" icon="x@lu" icon-button="small" plain
+                     @click="${() => this._removeCondition(group, index)}">
+          </zn-button>
+        </div>
+        ${(filter?.fields ?? []).map(f => this._renderField(condition, group, index, f))}
+      </div>
+    `;
+  }
+
+  private _renderConditions() {
+    return html`
+      <div part="conditions" class="conditions">
+        ${this._draft.map((group, gi) => html`
+          ${gi > 0 ? html`
+            <div class="or-label">OR</div>` : ''}
+          <div class="group">
+            ${group.map((condition, ci) => html`
+              ${ci > 0 ? html`
+                <div class="and-rule"><span>AND</span></div>` : ''}
+              ${this._renderCondition(condition, gi, ci)}
+            `)}
+            <zn-button icon="plus@lu" @click="${() => (this._picker = gi)}" panel-bg>AND
+            </zn-button>
+          </div>
+        `)}
+        <zn-button icon="plus@lu" @click="${() => (this._picker = this._draft.length)}" panel-bg>
+          OR
+        </zn-button>
+      </div>
+    `;
+  }
+
+  render() {
+    // With nothing configured yet, the picker is the first step (as designed).
+    const picking = this._picker !== null || this._draft.length === 0;
+    return html`
+      <div part="base" class="editor">
+        ${picking ? this._renderPicker() : this._renderConditions()}
+        <div class="actions">
+          <zn-button class="actions__save" icon="check@lu" @click="${this._save}">Save</zn-button>
+          <zn-button class="actions__cancel" icon="x@lu" @click="${this._cancel}" panel-bg>Cancel</zn-button>
+        </div>
+      </div>
+    `;
+  }
+}

package/src/components/flow-builder/modules/flow-branch-conditions/flow-branch-conditions.scss

@@ -0,0 +1,222 @@
+@use "../../../../wc";
+
+:host {
+  display: block;
+  font-size: 0.8125rem;
+}
+
+.editor {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+// --- Filter picker (step 1) --------------------------------------------------
+
+.picker {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 12px;
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  background: rgb(var(--zn-panel));
+
+  &__head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    font-weight: 600;
+  }
+
+  &__back {
+    flex: 0 0 auto;
+  }
+
+  &__list {
+    display: flex;
+    flex-direction: column;
+  }
+
+  &__item {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    width: 100%;
+    padding: 10px 12px;
+    margin-top: -1px;
+    border: 1px solid rgb(var(--zn-border-color));
+    background: rgb(var(--zn-panel));
+    color: rgb(var(--zn-text));
+    font-size: 0.8125rem;
+    text-align: left;
+    cursor: pointer;
+
+    &:first-child {
+      margin-top: 0;
+      border-top-left-radius: 8px;
+      border-top-right-radius: 8px;
+    }
+
+    &:last-child {
+      border-bottom-left-radius: 8px;
+      border-bottom-right-radius: 8px;
+    }
+
+    &:hover {
+      background: rgb(var(--zn-color-tab));
+    }
+  }
+
+  &__item-text {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+  }
+
+  &__item-label {
+    font-weight: 500;
+  }
+
+  &__item-description {
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+  }
+
+  &__empty {
+    margin: 0;
+    padding: 10px 2px;
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+  }
+}
+
+// --- Condition groups (step 2) -----------------------------------------------
+
+.conditions {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 12px;
+  width: 100%;
+  padding: 14px;
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: 8px;
+  background: rgb(var(--zn-panel));
+}
+
+// The AND joining two conditions in a group: a label on a full-width rule.
+.and-rule {
+  @include wc.text-style(paragraph);
+  
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  color: rgb(var(--zn-color-success));
+
+  &::after {
+    content: "";
+    flex: 1;
+    height: 1px;
+    background: color-mix(in srgb, rgb(var(--zn-color-success)) 50%, transparent);
+  }
+}
+
+// The OR joining two groups.
+.or-label {
+  @include wc.text-style(paragraph);
+
+  margin: 2px 0;
+  color: rgb(var(--zn-color-error));
+}
+
+.condition {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  width: 100%;
+
+  &__head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    width: 100%;
+  }
+
+  &__name {
+    @include wc.text-style(heading-section);
+  }
+
+  &__remove {
+    flex: 0 0 auto;
+  }
+
+  &__row {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 6px;
+  }
+
+  &__row-label,
+  &__suffix {
+    font-size: 0.75rem;
+    color: rgb(var(--zn-color-muted-text));
+    white-space: nowrap;
+  }
+}
+
+// Zinc form controls sized into the row: a zero flex-basis overrides the
+// controls' natural 100% width so a row shares one line. Each select also gets
+// an inline min-width sized to its longest label, so a row that can't show a
+// label in full wraps and gives the select its own line instead of truncating.
+.control {
+  min-width: 0;
+
+  &--operator {
+    flex: 1 1 0;
+    min-width: 120px;
+  }
+
+  &--number {
+    flex: 0 0 auto;
+    width: 80px;
+  }
+
+  // Adjustable unit dropdown after the value (e.g. day(s) / month(s)).
+  &--unit {
+    flex: 1 1 0;
+  }
+
+  // The value control soaks up the remaining row width.
+  &--value {
+    flex: 1 1 0;
+    min-width: 100px;
+  }
+}
+
+// Graceful fallback for labels past the min-width cap.
+zn-select.control::part(display-input) {
+  text-overflow: ellipsis;
+}
+
+// Save / Cancel sit in their own section, clear of the last group's "+ OR".
+.actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 2px;
+  padding-top: 16px;
+  border-top: 1px solid rgb(var(--zn-border-color));
+}

package/src/components/flow-builder/modules/flow-branch-conditions/flow-branch-conditions.test.ts

@@ -0,0 +1,125 @@
+import '../../../../../dist/zn.min.js';
+import {expect, fixture, html, oneEvent} from '@open-wc/testing';
+import type {FlowBranchConditions, FlowBranchFilter} from '../../flow.types';
+import type ZnFlowBranchConditions from './flow-branch-conditions.component';
+import type ZnInput from '../../../input';
+
+const FILTERS: FlowBranchFilter[] = [
+  {
+    id: 'engagement',
+    label: 'Email engagement',
+    fields: [
+      {
+        id: 'count',
+        type: 'number',
+        // 'gte' has no label — the editor falls back to its well-known default.
+        operators: [{value: 'gte'}, {value: 'at-most', label: 'at most'}],
+        units: [{value: 'days', label: 'day(s)'}, {value: 'months', label: 'month(s)'}],
+        value: 2,
+      },
+    ],
+  },
+  {
+    id: 'lost-reason',
+    label: 'Lost reason',
+    fields: [
+      {
+        id: 'reason',
+        type: 'select',
+        operators: [{value: 'eq', label: 'Is equal to'}, {value: 'neq', label: 'Is not equal to'}],
+        options: [{value: 'price', label: 'Price'}, {value: 'competitor', label: 'Competitor'}],
+      },
+    ],
+  },
+];
+
+// zn-button overrides click() without dispatching an event, so raise a real one.
+function clickButton(el: Element | null | undefined) {
+  el?.dispatchEvent(new MouseEvent('click', {bubbles: true, composed: true}));
+}
+
+async function makeEditor(value: FlowBranchConditions = []): Promise<ZnFlowBranchConditions> {
+  const el = await fixture<ZnFlowBranchConditions>(html`
+    <zn-flow-branch-conditions .filters="${FILTERS}" .value="${value}"></zn-flow-branch-conditions>`);
+  await el.updateComplete;
+  return el;
+}
+
+describe('<zn-flow-branch-conditions>', () => {
+  it('should open on the filter picker when nothing is configured', async () => {
+    const el = await makeEditor();
+    const items = el.shadowRoot?.querySelectorAll('.picker__item');
+    expect(el.shadowRoot?.querySelector('.picker')).to.exist;
+    expect(items?.length).to.equal(2);
+    expect(items?.[0].textContent).to.contain('Email engagement');
+  });
+
+  it('should add a condition with field defaults when a filter is picked', async () => {
+    const el = await makeEditor();
+    (el.shadowRoot?.querySelectorAll('.picker__item')[0] as HTMLButtonElement).click();
+    await el.updateComplete;
+
+    const condition = el.shadowRoot?.querySelector('.condition');
+    expect(condition?.querySelector('.condition__name')?.textContent).to.contain('Email engagement');
+    expect(String(condition!.querySelector<ZnInput>('zn-input.control')!.value)).to.equal('2');
+    // A label-less well-known operator key renders its default label.
+    expect(condition!.querySelector('zn-select.control--operator zn-option')!.textContent)
+      .to.contain('Greater Than or Equal To');
+    // The adjustable unit dropdown defaults to the first unit.
+    const unit = condition!.querySelector('zn-select.control--unit') as Element & { value: string };
+    expect(String(unit.value)).to.equal('days');
+  });
+
+  it('should render saved conditions with OR groups and AND rules', async () => {
+    const el = await makeEditor([
+      [
+        {filter: 'engagement', values: {count: {operator: 'gte', value: 2}}},
+        {filter: 'lost-reason', values: {reason: {operator: 'eq', value: 'price'}}},
+      ],
+      [{filter: 'engagement', values: {count: {operator: 'at-most', value: 5}}}],
+    ]);
+
+    expect(el.shadowRoot?.querySelectorAll('.group').length).to.equal(2);
+    expect(el.shadowRoot?.querySelectorAll('.condition').length).to.equal(3);
+    expect(el.shadowRoot?.querySelectorAll('.and-rule').length).to.equal(1);
+    expect(el.shadowRoot?.querySelectorAll('.or-label').length).to.equal(1);
+  });
+
+  it('should emit flow-conditions-save with the draft on Save', async () => {
+    const el = await makeEditor();
+    (el.shadowRoot?.querySelectorAll('.picker__item')[1] as HTMLButtonElement).click();
+    await el.updateComplete;
+
+    setTimeout(() => clickButton(el.shadowRoot?.querySelector('.actions__save')));
+    const event = await oneEvent(el, 'flow-conditions-save') as CustomEvent<{ conditions: FlowBranchConditions }>;
+
+    expect(event.detail.conditions).to.deep.equal([
+      [{filter: 'lost-reason', values: {reason: {operator: 'eq'}}}],
+    ]);
+  });
+
+  it('should emit flow-conditions-cancel without mutating the saved value', async () => {
+    const saved: FlowBranchConditions = [[{filter: 'engagement', values: {count: {value: 2}}}]];
+    const el = await makeEditor(saved);
+    clickButton(el.shadowRoot!.querySelector('.condition__remove'));
+    await el.updateComplete;
+
+    setTimeout(() => clickButton(el.shadowRoot?.querySelector('.actions__cancel')));
+    await oneEvent(el, 'flow-conditions-cancel');
+
+    expect(saved[0]).to.have.length(1);
+    expect(el.value).to.deep.equal(saved);
+  });
+
+  it('should filter the picker list by the search term', async () => {
+    const el = await makeEditor();
+    const search = el.shadowRoot!.querySelector<ZnInput>('.picker__search')!;
+    search.value = 'lost';
+    search.dispatchEvent(new Event('input', {bubbles: true}));
+    await el.updateComplete;
+
+    const items = el.shadowRoot?.querySelectorAll('.picker__item');
+    expect(items?.length).to.equal(1);
+    expect(items?.[0].textContent).to.contain('Lost reason');
+  });
+});

package/src/components/flow-builder/modules/flow-branch-conditions/index.ts

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