@zeyos/zx 2.1.0 → 2.2.0

package/src/compat/map/layout.js

@@ -0,0 +1,256 @@
+import {
+  Groupbox as ZxGroupbox,
+  MasterPanel as ZxMasterPanel,
+  NavigationBar as ZxNavigationBar,
+  Panel as ZxPanel,
+  Search as ZxSearch,
+  Tabbox as ZxTabbox
+} from '../../index.js';
+import { GxWrapper } from '../base.js';
+import { legacyContent, targetElement } from './helpers.js';
+import { LEGACY_EVENT_ARGS, translateTabboxOptions } from './options.js';
+
+/** Legacy ZeyOS collapsible groupbox. */
+export class Groupbox extends GxWrapper {
+  static legacyName = 'gx.zeyos.Groupbox';
+
+  /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
+  constructor(display, options = {}) {
+    super(options, { title: '', open: true });
+    const component = new ZxGroupbox(targetElement(display), {
+      title: String(options.title ?? ''), open: options.open !== false
+    });
+    this._attach(component, {
+      events: {
+        open: { type: 'open', args: () => [this] },
+        close: { type: 'close', args: () => [this] }
+      },
+      ui: { title: 'summary', inner: 'content' },
+      setters: { title: 'setTitle', open: (value) => value ? this.open() : this.close() }
+    });
+    if (Object.hasOwn(options, 'content')) component.setContent(legacyContent(options.content));
+    this._syncAct();
+  }
+
+  /** @returns {this} */
+  toggle() { this._zx.toggle(); this._syncAct(); return this; }
+  /** @returns {this} */
+  open() { this._zx.open(); this._syncAct(); return this; }
+  /** @returns {this} */
+  close() { this._zx.close(); this._syncAct(); return this; }
+  /** @returns {boolean} */
+  isOpen() { return this._zx.isOpen(); }
+  /** @param {string} title @returns {this} */
+  setTitle(title) { this._zx.setTitle(title); return this; }
+  /** @returns {void} */
+  _syncAct() { this._mirrorAct(this.display('title'), this.isOpen()); }
+}
+
+/** Legacy positional panel wrapper. */
+export class Panel extends GxWrapper {
+  static legacyName = 'gx.zeyos.Panel';
+
+  /** @param {Element|string|null} display @param {string} title @param {unknown} content @param {boolean} [open=true] */
+  constructor(display, title = '', content = null, open = true) {
+    super({ title, content, open });
+    const component = new ZxPanel(targetElement(display), {
+      title: String(title ?? ''), content: legacyContent(content), open: open !== false
+    });
+    this._attach(component, {
+      events: { open: 'open', close: 'close' },
+      // `title` is the clickable header: the Zx panel splits that into a toggle plus an action
+      // area, and the toggle is what the legacy display key stood for.
+      ui: { title: 'toggle', header: 'header', inner: 'content', content: 'content' },
+      setters: { title: 'setTitle', content: 'setContent', open: (value) => value ? this.open() : this.close() }
+    });
+  }
+
+  /** @returns {this} */
+  toggle() { this._zx.toggle(); return this; }
+  /** @returns {this} */
+  open() { this._zx.open(); return this; }
+  /** @returns {this} */
+  close() { this._zx.close(); return this; }
+  /** @returns {boolean} */
+  isOpen() { return this._zx.isOpen(); }
+  /** @param {unknown} content @returns {this} */
+  setContent(content) { this._zx.setContent(legacyContent(content)); return this; }
+  /** @param {string} title @returns {this} */
+  setTitle(title) { this._zx.setTitle(title); return this; }
+}
+
+/** Legacy positional master panel wrapper. */
+export class MasterPanel extends GxWrapper {
+  static legacyName = 'gx.zeyos.MasterPanel';
+
+  /** @param {Element|string|null} display @param {string} title @param {unknown} content @param {unknown[]} [buttons=[]] */
+  constructor(display, title = '', content = null, buttons = []) {
+    super({ title, content, buttons });
+    const component = new ZxMasterPanel(targetElement(display), {
+      title: String(title ?? ''), content: legacyContent(content), buttons: normalizeButtons(buttons)
+    });
+    this._attach(component, {
+      ui: { title: 'title', inner: 'content', content: 'content', buttons: 'buttons' },
+      setters: { title: 'setTitle', content: 'setContent', buttons: (value) => component.setButtons(normalizeButtons(value)) }
+    });
+  }
+
+  /** @param {unknown} content @returns {this} */
+  setContent(content) { this._zx.setContent(legacyContent(content)); return this; }
+  /** @param {string} title @returns {this} */
+  setTitle(title) { this._zx.setTitle(title); return this; }
+}
+
+/** Shared legacy tabbox implementation; subclasses only change warning identity. */
+export class Tabbox extends GxWrapper {
+  static legacyName = 'gx.zeyos.Tabbox';
+
+  /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
+  constructor(display, options = {}) {
+    super(options, { frames: [], show: 1 });
+    const translated = translateTabboxOptions(options);
+    const component = new ZxTabbox(targetElement(display), {
+      tabs: translated.tabs.map(normalizeTab), active: translated.active
+    });
+    this._attach(component, {
+      events: {
+        change: { type: 'change', args: (detail) => LEGACY_EVENT_ARGS.tabChange(detail) },
+        close: { type: 'close', args: (detail) => [detail.name] }
+      },
+      ui: { tablist: 'tablist', content: 'panels', div: 'tablist' },
+      setters: { show: 'openTab', height: (value) => this.setStyle('height', value) }
+    });
+    if (translated.height != null) this.setStyle('height', translated.height);
+    component.on('change', () => queueMicrotask(() => this._syncAct()));
+    this._syncAct();
+  }
+
+  /** @param {Record<string, any>|string} frame @param {string} [title] @param {unknown} [content] @returns {this} */
+  addTab(frame, title, content) {
+    const definition = typeof frame === 'object' ? frame : { name: frame, title, content };
+    this._zx.addTab(normalizeTab(definition));
+    this._syncAct();
+    return this;
+  }
+
+  /** @param {string} name @returns {this} */
+  closeTab(name) { this._zx.removeTab(String(name)); this._syncAct(); return this; }
+  /** @param {string|number} name @returns {this} */
+  openTab(name) {
+    const resolved = typeof name === 'number' ? this._zx._tabs?.[name - 1]?.definition.name : String(name);
+    if (resolved) this._zx.openTab(resolved);
+    this._syncAct();
+    return this;
+  }
+  /** @param {string} name @param {string} title @returns {this} */
+  setTabTitle(name, title) { this._zx.setTitle(String(name), title); return this; }
+  /** @param {string} name @param {unknown} content @param {string} [_style] @returns {this} */
+  setHighlight(name, content, _style) { this._zx.setBadge(String(name), content == null || content === '' ? null : String(content)); return this; }
+  /** @returns {string|null} */
+  getActive() { return this._zx.getActive(); }
+  /** @returns {void} */
+  _syncAct() {
+    for (const tab of this.display('tablist')?.querySelectorAll?.('[role="tab"]') ?? []) {
+      this._mirrorAct(tab, tab.getAttribute('aria-selected') === 'true');
+    }
+  }
+}
+
+/** Bootstrap-flavoured tabbox with the same behavior. */
+export class BootstrapTabbox extends Tabbox {
+  static legacyName = 'gx.bootstrap.Tabbox';
+}
+
+/** Legacy bootstrap navigation bar. */
+export class NavigationBar extends GxWrapper {
+  static legacyName = 'gx.bootstrap.NavigationBar';
+
+  /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
+  constructor(display, options = {}) {
+    super(options, { frames: [], title: '', buttons: [] });
+    const frames = Array.isArray(options.frames) ? options.frames : [];
+    this._frames = frames.map((frame) => ({ ...frame }));
+    const active = typeof options.show === 'number' ? frames[options.show - 1]?.name : options.show;
+    const component = new ZxNavigationBar(targetElement(display), {
+      title: String(options.title ?? ''),
+      items: frames.map(normalizeTab),
+      active: active == null ? null : String(active),
+      actions: normalizeButtons(options.buttons ?? [])
+    });
+    this._attach(component, {
+      events: { change: { type: 'change', args: (detail) => [detail.name] } },
+      ui: { title: 'title', tablist: 'items', content: 'panels', buttons: 'actions' },
+      setters: { title: 'setTitle' }
+    });
+    component.on('change', () => queueMicrotask(() => this._syncAct()));
+    this._syncAct();
+  }
+
+  /** @param {Record<string, any>|string} frame @param {string} [title] @param {unknown} [content] @returns {this} */
+  addTab(frame, title, content) {
+    const definition = typeof frame === 'object' ? { ...frame } : { name: frame, title, content };
+    this._frames.push(definition); this._rebuild(); return this;
+  }
+  /** @param {string} name @returns {this} */
+  closeTab(name) { this._frames = this._frames.filter((frame) => String(frame.name) !== String(name)); this._rebuild(); return this; }
+  /** @param {string} name @returns {this} */
+  openTab(name) { this._zx.setActive(String(name)); this._syncAct(); return this; }
+  /** @param {string|Element} title @returns {this} */
+  setTitle(title) { this._zx.setTitle(typeof title === 'string' ? title : title?.textContent ?? ''); return this; }
+  /** @param {string} name @param {string} title @returns {this} */
+  setTabTitle(name, title) { const frame = this._frames.find((item) => String(item.name) === String(name)); if (frame) frame.title = title; this._rebuild(); return this; }
+  /** @param {unknown[]} buttons @returns {this} */
+  setNavigationButtons(buttons) { this._zx.setActions(normalizeButtons(buttons)); return this; }
+  /** @param {string} name @param {unknown} content @param {string} [_style] @returns {this} */
+  setHighlight(name, content, _style) { this._zx.setBadge(String(name), content == null || content === '' ? null : String(content)); return this; }
+  /** @returns {void} */
+  _rebuild() { const active = this._zx._activeName; this._zx.setItems(this._frames.map(normalizeTab)); if (active && this._frames.some((frame) => String(frame.name) === String(active))) this._zx.setActive(active); this._syncAct(); }
+  /** @returns {void} */
+  _syncAct() { for (const item of this.display('tablist')?.querySelectorAll?.('[role="tab"]') ?? []) this._mirrorAct(item, item.getAttribute('aria-selected') === 'true'); }
+}
+
+/** Legacy standalone search control. */
+export class Search extends GxWrapper {
+  static legacyName = 'gx.zeyos.Search';
+
+  /** @param {Record<string, any>} [options={}] */
+  constructor(options = {}) {
+    super(options);
+    const component = new ZxSearch(null, { placeholder: options.placeholder ?? '', debounce: options.debounce ?? 0 });
+    this._attach(component, {
+      events: {
+        input: { type: 'input', args: (_detail, event) => [this, component.refs.input, event] }
+      },
+      ui: { input: 'input', submit: 'submit', button: 'submit' }
+    });
+    this._listen(component.refs.input, 'keydown', (event) => {
+      if (event.key === 'Enter') this.fireEvent('keypress', [this, component.refs.input, event]);
+    });
+    this._listen(component.refs.submit, 'click', (event) => this.fireEvent('click', [this, component.refs.input, event]));
+  }
+
+  /** @returns {string} */
+  get() { return this._zx.get(); }
+  /** @param {string} value @returns {this} */
+  set(value) { this._zx.set(value); return this; }
+}
+
+/** @param {Record<string, any>} frame @returns {Record<string, any>} */
+function normalizeTab(frame) {
+  let content = legacyContent(frame.content);
+  if (typeof content === 'string' || typeof content === 'number' || content == null) {
+    content = document.createTextNode(content == null ? '' : String(content));
+  }
+  return {
+    name: String(frame.name ?? ''),
+    title: String(frame.title ?? ''),
+    content,
+    closable: Boolean(frame.closable),
+    disabled: Boolean(frame.disabled)
+  };
+}
+
+/** @param {unknown} list @returns {Element[]} */
+function normalizeButtons(list) {
+  return (Array.isArray(list) ? list : [list]).filter(Boolean).map((item) => item?.toElement?.() ?? item).filter((item) => item?.nodeType === 1);
+}

package/src/compat/map/options.js

@@ -0,0 +1,267 @@
+/**
+ * Pure option and event translations shared by the gx compatibility wrappers.
+ * Keeping these helpers DOM-free makes the migration contract directly testable in Node.
+ * @module gx-compat-options
+ */
+
+/** @type {Readonly<Record<string, string>>} */
+export const SELECT_OPTION_MAP = Object.freeze({
+  data: 'items',
+  elementIndex: 'valueKey',
+  elementLabel: 'labelKey',
+  elementSelect: 'renderValue',
+  allowEmpty: 'clearable',
+  resetable: 'clearable',
+  searchfields: 'searchKeys',
+  height: 'listHeight'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+export const CHECKLIST_OPTION_MAP = Object.freeze({
+  data: 'items',
+  listValue: 'valueKey',
+  listFormat: 'labelKey',
+  listActive: 'checkedKey',
+  defaultState: 'defaultChecked'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+export const TABLE_OPTION_MAP = Object.freeze({
+  cols: 'columns'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+export const FORM_OPTION_MAP = Object.freeze({
+  horizontal: 'layout',
+  default: 'value'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+export const FIELD_TYPE_MAP = Object.freeze({
+  string: 'text',
+  integer: 'int',
+  gxselect: 'zxselect',
+  date: 'date',
+  month: 'month',
+  time: 'time',
+  optionlist: 'optionlist',
+  html: 'html',
+  multivalueeditor: 'multivalueeditor',
+  checklist: 'checklist'
+});
+
+/**
+ * Renames known keys while retaining unrelated options.
+ * @param {Record<string, any>|null|undefined} source Legacy options.
+ * @param {Readonly<Record<string, string>>} mapping Rename table.
+ * @returns {Record<string, any>} Translated copy.
+ */
+export function renameOptions(source, mapping) {
+  const translated = {};
+  if (!source || typeof source !== 'object') return translated;
+  for (const [key, value] of Object.entries(source)) {
+    if (/^on[A-Z]/.test(key)) continue;
+    translated[mapping[key] ?? key] = value;
+  }
+  return translated;
+}
+
+/**
+ * Converts legacy Select options to their Zx equivalents.
+ * @param {Record<string, any>} [options={}] Legacy Select options.
+ * @returns {Record<string, any>} Zx Select options.
+ */
+export function translateSelectOptions(options = {}) {
+  const translated = renameOptions(options, SELECT_OPTION_MAP);
+  if (Object.hasOwn(options, 'data')) translated.items = Array.isArray(options.data) ? options.data.slice() : [];
+  if (Object.hasOwn(options, 'allowEmpty') || Object.hasOwn(options, 'resetable')) {
+    translated.clearable = Boolean(options.allowEmpty || options.resetable);
+  }
+  if (options.msg && typeof options.msg === 'object' && options.msg.noSelection != null) {
+    translated.placeholder = String(options.msg.noSelection);
+  }
+  if (Object.hasOwn(options, 'height')) translated.listHeight = numericSize(options.height, 280);
+  delete translated.elementDefault;
+  delete translated.parseDefault;
+  delete translated.queryParam;
+  delete translated.requestData;
+  delete translated.requestHeader;
+  delete translated.url;
+  delete translated.method;
+  delete translated.entity;
+  delete translated.limit;
+  return translated;
+}
+
+/**
+ * Converts legacy Checklist options to Zx Checklist options.
+ * @param {Record<string, any>} [options={}] Legacy Checklist options.
+ * @returns {Record<string, any>} Zx Checklist options.
+ */
+export function translateChecklistOptions(options = {}) {
+  const translated = renameOptions(options, CHECKLIST_OPTION_MAP);
+  if (typeof options.getItemValue === 'function') translated.valueKey = options.getItemValue;
+  if (Object.hasOwn(options, 'height')) translated.height = numericSize(options.height, 280);
+  delete translated.url;
+  delete translated.method;
+  delete translated.requestData;
+  delete translated.decodeResponse;
+  delete translated.width;
+  delete translated.onClick;
+  return translated;
+}
+
+/**
+ * Converts the legacy Datebox token array to the kernel format string.
+ * Existing percent-token format strings pass through unchanged.
+ * @param {unknown} format Legacy array or format string.
+ * @returns {string} Kernel date format.
+ */
+export function translateDateboxFormat(format) {
+  if (typeof format === 'string') return format.replaceAll('&nbsp;', ' ');
+  const parts = Array.isArray(format) ? format : ['d', '.', 'M', '.', 'y'];
+  const tokens = {
+    d: '%d', m: '%m', M: '%m', y: '%Y', h: '%H', i: '%M', s: '%S'
+  };
+  return parts.map((part) => tokens[part] ?? String(part).replaceAll('&nbsp;', ' ')).join('');
+}
+
+/**
+ * Resolves the legacy one-based `show` option to a tab name.
+ * @param {Array<{name?: unknown}>} frames Legacy frame list.
+ * @param {unknown} show Name or one-based numeric index.
+ * @returns {string|null} Resolved name.
+ */
+export function resolveTabName(frames, show) {
+  if (typeof show === 'string') return show;
+  if (typeof show !== 'number' || !Number.isFinite(show)) return null;
+  const frame = frames[Math.trunc(show) - 1];
+  return frame?.name == null ? null : String(frame.name);
+}
+
+/**
+ * Converts legacy Tabbox options without normalizing DOM content.
+ * @param {Record<string, any>} [options={}] Legacy Tabbox options.
+ * @returns {{tabs: Array<Record<string, any>>, active: string|null, height: unknown}}
+ */
+export function translateTabboxOptions(options = {}) {
+  const frames = Array.isArray(options.frames) ? options.frames : [];
+  return {
+    tabs: frames.map((frame) => ({
+      name: String(frame.name ?? ''),
+      title: String(frame.title ?? ''),
+      content: frame.content,
+      closable: Boolean(frame.closable),
+      disabled: Boolean(frame.disabled)
+    })),
+    active: resolveTabName(frames, options.show ?? 1),
+    height: options.height ?? null
+  };
+}
+
+/**
+ * Converts a legacy table column list and its initial filter state.
+ * A cell adapter can turn legacy cell objects into DOM nodes in browser wrappers.
+ * @param {Record<string, any>} [options={}] Legacy Table options.
+ * @param {(cell: unknown) => unknown} [adaptCell=defaultCellAdapter] Cell adapter.
+ * @returns {Record<string, any>} Zx Table options.
+ */
+export function translateTableOptions(options = {}, adaptCell = defaultCellAdapter) {
+  const cols = Array.isArray(options.cols) ? options.cols : [];
+  const structure = typeof options.structure === 'function' ? options.structure : (row) => cols.map((col) => row?.[col.id]);
+  const cache = new WeakMap();
+  const getCells = (row, index) => {
+    if (row && typeof row === 'object') {
+      const cached = cache.get(row);
+      if (cached?.index === index) return cached.cells;
+    }
+    const result = structure(row, index);
+    const cells = Array.isArray(result) ? result : (Array.isArray(result?.row) ? result.row : []);
+    if (row && typeof row === 'object') cache.set(row, { index, cells });
+    return cells;
+  };
+  const columns = cols.map((column, columnIndex) => ({
+    id: String(column.id ?? columnIndex),
+    label: String(column.label ?? ''),
+    width: column.width ?? 'auto',
+    align: normalizeAlignment(column.align ?? column['text-align']),
+    sortable: column.filter != null || column.filterable !== false,
+    render: (row, rowIndex) => adaptCell(getCells(row, rowIndex)[columnIndex])
+  }));
+  const sorted = cols.find((column) => column.filter != null);
+  return {
+    columns,
+    data: Array.isArray(options.data) ? options.data.slice() : [],
+    sort: sorted ? { id: String(sorted.id), dir: sortDirection(sorted.mode ?? sorted.filter) } : null,
+    sortMode: 'server',
+    selectable: options.selectable === true ? 'single' : (['single', 'multi'].includes(options.selectable) ? options.selectable : false),
+    height: options.height ?? null,
+    stickyHeader: options.scroll !== false,
+    rowId: typeof options.rowId === 'function' || typeof options.rowId === 'string' ? options.rowId : legacyRowId
+  };
+}
+
+/**
+ * Converts a legacy field descriptor to Zx Field options.
+ * Component-specific `props` are completed by the browser wrapper.
+ * @param {Record<string, any>} [options={}] Legacy field descriptor.
+ * @returns {Record<string, any>} Zx Field options.
+ */
+export function translateFieldOptions(options = {}) {
+  const type = FIELD_TYPE_MAP[String(options.type ?? 'text').toLowerCase()] ?? String(options.type ?? 'text').toLowerCase();
+  const translated = {
+    id: options.id ?? null,
+    type,
+    label: options.label ?? '',
+    description: options.description ?? '',
+    value: Object.hasOwn(options, 'value') ? options.value : options.default,
+    placeholder: options.placeholder ?? '',
+    required: Boolean(options.required),
+    disabled: Boolean(options.disabled),
+    options: options.options ?? null,
+    layout: options.horizontal === false ? 'stack' : (options.horizontal ? 'inline' : 'stack'),
+    props: {}
+  };
+  if (type === 'html') translated.value = options.content ?? translated.value;
+  return translated;
+}
+
+/**
+ * Positional legacy event arguments for the mappings exercised by wrappers.
+ * @type {Readonly<Record<string, (detail: Record<string, any>, wrapper: unknown, event?: Event) => unknown[]>>}
+ */
+export const LEGACY_EVENT_ARGS = Object.freeze({
+  select: (detail, wrapper) => [detail.item ?? null, wrapper],
+  noselect: (_detail, wrapper) => [null, wrapper],
+  tableClick: (detail) => [detail.row, detail.event?.target?.closest?.('tr') ?? null, detail.event],
+  tableFilter: (detail, wrapper) => [wrapper?._legacyColumn?.(detail.id) ?? { id: detail.id }, detail.dir],
+  tabChange: (detail) => [detail.name]
+});
+
+/** @param {unknown} value @param {number} fallback @returns {number} */
+function numericSize(value, fallback) {
+  const number = typeof value === 'string' ? Number.parseFloat(value) : Number(value);
+  return Number.isFinite(number) ? Math.max(0, number) : fallback;
+}
+
+/** @param {unknown} align @returns {'start'|'center'|'end'|'left'|'right'} */
+function normalizeAlignment(align) {
+  const value = String(align ?? 'start');
+  return ['center', 'end', 'left', 'right'].includes(value) ? value : 'start';
+}
+
+/** @param {unknown} direction @returns {'asc'|'desc'} */
+function sortDirection(direction) {
+  return direction === 'desc' ? 'desc' : 'asc';
+}
+
+/** @param {unknown} cell @returns {unknown} */
+function defaultCellAdapter(cell) {
+  if (cell && typeof cell === 'object' && !Array.isArray(cell) && Object.hasOwn(cell, 'label')) return cell.label;
+  return cell;
+}
+
+/** @param {Record<string, any>} row @returns {unknown} */
+function legacyRowId(row) {
+  return row?.ID ?? row?.id ?? row;
+}