@zeyos/zx 2.3.0 → 4.0.0

package/src/components/dropdown/dropdown.js

@@ -9,7 +9,7 @@ const HANDLE_ESCAPE_DISMISS = Symbol('zxDropdownEscapeDismiss');
 /**
  * @typedef {Object} DropdownOptions
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Panel content.
- * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'} [placement='bottom-start'] Panel placement.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'|'right-start'|'right-end'|'left-start'|'left-end'|'right'|'left'} [placement='bottom-start'] Panel placement.
  * @property {number} [offset=4] Gap between anchor and panel in pixels.
  * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
  * @property {'click'|'manual'} [openOn='click'] Trigger behavior.

package/src/components/field/field.js

@@ -16,6 +16,8 @@ import { uid } from '../../core/util.js';
  * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
  * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
  * @property {FieldAdapterFactory} [adapter] Adapter used by the `custom` type.
+ * @property {(event: CustomEvent<{value: unknown}>) => void} [onchange] Value change listener.
+ * @property {(event: CustomEvent<{message: string}>) => void} [oninvalid] Validation failure listener.
  */
 
 /**

package/src/components/field-upload/field-upload.js

@@ -30,6 +30,11 @@ import { uid } from '../../core/util.js';
  * @property {boolean} [autoUpload=true] Upload immediately after selection.
  * @property {boolean} [preview=true] Show a preview for the first selected image.
  * @property {UploadTransport|null} [http=null] Injected Http-compatible or stub upload transport.
+ * @property {(event: CustomEvent<{files: File[]}>) => void} [onselect] File selection listener.
+ * @property {(event: CustomEvent<{percent: number}>) => void} [onprogress] Upload progress listener.
+ * @property {(event: CustomEvent<{response: unknown}>) => void} [onsuccess] Upload success listener.
+ * @property {(event: CustomEvent<{error: Error}>) => void} [onerror] Upload failure listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onabort] Upload abort listener.
  */
 
 /**
@@ -447,25 +452,25 @@ function abortError() {
 /**
  * Files selected event.
  * @event FieldUpload#select
- * @type {CustomEvent<{files: File[]}>
+ * @type {CustomEvent<{files: File[]}>}
  */
 
 /**
  * Upload progress event.
  * @event FieldUpload#progress
- * @type {CustomEvent<{percent: number}>
+ * @type {CustomEvent<{percent: number}>}
  */
 
 /**
  * Upload success event.
  * @event FieldUpload#success
- * @type {CustomEvent<{response: unknown}>
+ * @type {CustomEvent<{response: unknown}>}
  */
 
 /**
  * Upload failure event.
  * @event FieldUpload#error
- * @type {CustomEvent<{error: Error}>
+ * @type {CustomEvent<{error: Error}>}
  */
 
 /**

package/src/components/form/form.js

@@ -22,6 +22,9 @@ import { coerceFloat, coerceInteger } from '../field/field.js';
  * @property {Array<Fieldset|import('../fieldset/fieldset.js').FieldsetOptions>} [fieldsets=[]] Initial fieldsets.
  * @property {FormAction[]} [actions=[]] Form action descriptors.
  * @property {boolean} [novalidate=true] Native `novalidate` state.
+ * @property {(event: CustomEvent<{values: Record<string, unknown>}>) => void} [onsubmit] Submit listener.
+ * @property {(event: CustomEvent<{errors: Record<string, string>}>) => void} [oninvalid] Invalid listener.
+ * @property {(event: CustomEvent<{id: string, value: unknown}>) => void} [onchange] Field change listener.
  */
 
 /**
@@ -286,17 +289,17 @@ function isEmpty(value) {
 /**
  * Successful form submission event.
  * @event Form#submit
- * @type {CustomEvent<{values: Record<string, unknown>}>
+ * @type {CustomEvent<{values: Record<string, unknown>}>}
  */
 
 /**
  * Form validation failure event.
  * @event Form#invalid
- * @type {CustomEvent<{errors: Record<string, string>}>
+ * @type {CustomEvent<{errors: Record<string, string>}>}
  */
 
 /**
  * Delegated field value change event.
  * @event Form#change
- * @type {CustomEvent<{id: string, value: unknown}>
+ * @type {CustomEvent<{id: string, value: unknown}>}
  */

package/src/components/grid/grid.css

@@ -0,0 +1,6 @@
+/* Data Grid intentionally renders the Table block. Preset-only treatment stays narrowly scoped so
+   the lowercase `.zx-grid` layout helper remains a separate, unchanged primitive. */
+.zx-table[data-preset="billing-items"] tr.zx-grid-billing__summary > td {
+  background: var(--zx-color-bg-subtle);
+  font-weight: 700;
+}

package/src/components/grid/grid.js

@@ -0,0 +1,220 @@
+import { Table } from '../table/table.js';
+
+/** @typedef {Record<string, any>} BillingRow */
+/**
+ * @typedef {Object} GridOptions
+ * Grid inherits its constructor options and runtime API from `Table`; this record owns the Grid
+ * name in generated documentation, where the Table API is shown alongside it.
+ */
+/**
+ * @typedef {Object} BillingFields
+ * @property {string} [id='id'] Row identifier field.
+ * @property {string} [parent='parent'] Parent identifier field.
+ * @property {string} [item='item'] Line description field.
+ * @property {string} [kind='kind'] Line-kind field (`group`/`subtotal` rows are read-only).
+ * @property {string} [quantity='quantity'] Quantity field.
+ * @property {string} [unit='unit'] Unit field.
+ * @property {string} [unitPrice='unitPrice'] Unit-price field.
+ * @property {string} [currency='currency'] Currency-code field.
+ * @property {string} [total='total'] Line-total field.
+ */
+/**
+ * @typedef {Object} BillingItemsOptions
+ * @property {BillingRow[]} [data=[]] Billing rows.
+ * @property {Partial<BillingFields>} [fields={}] Schema field overrides.
+ * @property {Array<{value: unknown, label: string}>|Record<string, string>} [units=[]] Unit choices.
+ * @property {Array<{value: unknown, label: string}>|Record<string, string>} [currencies=[]] Currency choices.
+ * @property {string} [currency='EUR'] Fallback currency.
+ * @property {string} [locale] Number/currency locale.
+ * @property {number} [decimals=2] Currency fraction digits.
+ * @property {Record<string, object>} [columnOverrides={}] Per-canonical-column overrides.
+ * @property {(row: BillingRow, changes: Record<string, unknown>) => number|null|undefined} [lineTotal] Optional total calculation; defaults to quantity × unit price.
+ * @property {import('../table/table.js').TableColumn[]} [columns] Complete column replacement.
+ * @property {(event: CustomEvent<import('../table/table.js').TableEditCommitDetail>) => void} [oneditcommit] Caller edit listener, invoked after total calculation.
+ */
+
+/**
+ * Public data grid. It deliberately inherits Table's DOM/CSS/API instead of forking the data layer.
+ * @extends {Table}
+ */
+export class Grid extends Table {
+  // The lowercase `grid()` layout factory owns `.zx-grid`; the data Grid is a Table specialization.
+  static cssName = 'table';
+
+  /**
+   * Creates a generic data grid with the complete inherited Table contract.
+   * @param {Element|string|null} target Grid target.
+   * @param {GridOptions & import('../table/table.js').TableOptions} [options={}] Grid/Table options.
+   */
+  constructor(target = null, options = {}) {
+    super(target, options);
+  }
+
+  /**
+   * Creates an editable hierarchical billing-line grid.
+   * @param {Element|string|null} target Grid target.
+   * @param {BillingItemsOptions & import('../table/table.js').TableOptions} [options={}] Preset and Table overrides.
+   * @returns {Grid}
+   */
+  static BillingItems(target, options = {}) {
+    const grid = new Grid(target, billingItemsConfig(options));
+    grid.el.dataset.preset = 'billing-items';
+    return grid;
+  }
+}
+
+/**
+ * Builds the Table-compatible options behind `Grid.BillingItems()` without touching the DOM.
+ * @param {BillingItemsOptions & import('../table/table.js').TableOptions} [options={}] Preset and Table overrides.
+ * @returns {import('../table/table.js').TableOptions}
+ */
+export function billingItemsConfig(options = {}) {
+  const {
+    fields: requestedFields = {},
+    units = [],
+    currencies = [],
+    currency = 'EUR',
+    locale,
+    decimals = 2,
+    columnOverrides = {},
+    lineTotal = null,
+    columns: suppliedColumns,
+    oneditcommit,
+    rowClass,
+    ...tableOptions
+  } = options;
+  const fields = { ...DEFAULT_FIELDS, ...requestedFields };
+  const calculateLineTotal = typeof lineTotal === 'function' ? lineTotal : (row) => {
+    const quantity = billingNumber(row?.[fields.quantity]);
+    const price = billingNumber(row?.[fields.unitPrice]);
+    return quantity !== null && price !== null ? quantity * price : null;
+  };
+  const columns = Array.isArray(suppliedColumns) ? suppliedColumns.map((column) => ({ ...column }))
+    : billingColumns(fields, { units, currencies, currency, locale, decimals, columnOverrides });
+  return {
+    rowId: fields.id,
+    editMode: 'cell',
+    hierarchy: { parentId: fields.parent, column: fields.item, expanded: true },
+    responsive: 'sm',
+    ...tableOptions,
+    columns,
+    rowClass(row) {
+      const own = isBillingLine(row, fields) ? '' : 'zx-grid-billing__summary';
+      const supplied = typeof rowClass === 'function' ? rowClass(row) : '';
+      return [own, supplied].filter(Boolean).join(' ');
+    },
+    oneditcommit(event) {
+      const { row, changes } = event.detail;
+      if (isBillingLine(row, fields)) {
+        const next = { ...row, ...changes };
+        const calculated = calculateLineTotal(next, changes);
+        if (calculated !== undefined && calculated !== null && Number.isFinite(Number(calculated))) {
+          changes[fields.total] = Number(calculated);
+        }
+      }
+      oneditcommit?.(event);
+    }
+  };
+}
+
+/** @type {Readonly<BillingFields>} */
+const DEFAULT_FIELDS = Object.freeze({
+  id: 'id',
+  parent: 'parent',
+  item: 'item',
+  kind: 'kind',
+  quantity: 'quantity',
+  unit: 'unit',
+  unitPrice: 'unitPrice',
+  currency: 'currency',
+  total: 'total'
+});
+
+/**
+ * Returns whether a billing row is an editable line rather than a group/subtotal.
+ * @param {BillingRow} row Row.
+ * @param {BillingFields} [fields=DEFAULT_FIELDS] Field map.
+ * @returns {boolean}
+ */
+export function isBillingLine(row, fields = DEFAULT_FIELDS) {
+  const kind = String(row?.[fields.kind] ?? 'line').toLowerCase();
+  return !['group', 'subtotal', 'header', 'section'].includes(kind);
+}
+
+/**
+ * Produces the preset columns without mutating overrides.
+ * @param {BillingFields} fields Field map.
+ * @param {{units: unknown, currencies: unknown, currency: string, locale?: string, decimals: number, columnOverrides: Record<string, object>}} options Formatting/editor options.
+ * @returns {import('../table/table.js').TableColumn[]}
+ */
+export function billingColumns(fields, { units, currencies, currency, locale, decimals, columnOverrides }) {
+  const editableLine = (type) => (row) => isBillingLine(row, fields) ? type : false;
+  const rowCurrency = (row) => String(row?.[fields.currency] || currency);
+  const rowUnit = (row) => String(row?.[fields.unit] ?? '');
+  const columns = {
+    item: {
+      id: fields.item,
+      label: 'Item',
+      width: '2fr',
+      sortable: true,
+      editable: editableLine('text')
+    },
+    quantity: {
+      id: fields.quantity,
+      label: 'Quantity',
+      width: '1fr',
+      type: 'unit',
+      locale,
+      unit: rowUnit,
+      editable: editableLine('number'),
+      editorProps: { min: 0, step: 0.01 }
+    },
+    unit: {
+      id: fields.unit,
+      label: 'Unit',
+      width: '.8fr',
+      editable: editableLine(hasChoices(units) ? 'select' : 'text'),
+      options: units
+    },
+    unitPrice: {
+      id: fields.unitPrice,
+      label: 'Unit price',
+      width: '1fr',
+      type: 'currency',
+      locale,
+      decimals,
+      currency: rowCurrency,
+      editable: editableLine('number'),
+      editorProps: { min: 0, step: 0.01 }
+    },
+    currency: {
+      id: fields.currency,
+      label: 'Currency',
+      width: '.8fr',
+      editable: editableLine(hasChoices(currencies) ? 'select' : 'text'),
+      options: currencies
+    },
+    total: {
+      id: fields.total,
+      label: 'Line total',
+      width: '1fr',
+      type: 'currency',
+      locale,
+      decimals,
+      currency: rowCurrency
+    }
+  };
+  return Object.entries(columns).map(([key, column]) => ({ ...column, ...(columnOverrides?.[key] ?? {}) }));
+}
+
+/** @param {unknown} value @returns {boolean} */
+function hasChoices(value) {
+  return Array.isArray(value) ? value.length > 0 : Boolean(value && typeof value === 'object' && Object.keys(value).length);
+}
+
+/** Missing billing operands stay missing; explicit numeric zero remains a valid value. @param {unknown} value @returns {number|null} */
+function billingNumber(value) {
+  if (value == null || typeof value === 'string' && value.trim() === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}

package/src/components/launcher/launcher.css

@@ -0,0 +1,210 @@
+.zx-launcher {
+  inline-size: min(760px, calc(100vw - (2 * var(--zx-space-4))));
+  max-block-size: min(720px, calc(100vh - (2 * var(--zx-space-6))));
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-xl);
+  background: var(--zx-color-bg-raised);
+  box-shadow: var(--zx-overlay-shadow);
+  color: var(--zx-color-text);
+  padding: 0;
+}
+
+.zx-launcher::backdrop {
+  background: var(--zx-color-bg-backdrop);
+}
+
+.zx-launcher__surface {
+  display: grid;
+  grid-template-rows: auto auto minmax(0, 1fr) auto;
+  max-block-size: inherit;
+}
+
+.zx-launcher__search {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: var(--zx-space-3);
+  border-block-end: 1px solid var(--zx-color-border);
+  padding: var(--zx-space-3) var(--zx-space-4);
+}
+
+.zx-launcher__search[data-shortcut="false"] {
+  grid-template-columns: auto minmax(0, 1fr) auto;
+}
+
+.zx-launcher__input {
+  min-inline-size: 0;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  color: inherit;
+  font-size: var(--zx-text-lg);
+}
+
+.zx-launcher__input:focus-visible {
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+.zx-launcher__input::-webkit-search-cancel-button { display: none; }
+
+.zx-launcher__shortcut,
+.zx-launcher__hints kbd {
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-radius-sm);
+  background: var(--zx-color-bg-muted);
+  color: var(--zx-color-text-muted);
+  font-family: var(--zx-font-mono);
+  font-size: var(--zx-text-xs);
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.zx-launcher__shortcut {
+  padding-inline: var(--zx-space-2);
+  white-space: nowrap;
+}
+
+.zx-launcher__status {
+  margin: 0;
+  padding: var(--zx-space-5);
+  color: var(--zx-color-text-muted);
+  text-align: center;
+}
+
+.zx-launcher__status[hidden] { display: none; }
+
+.zx-launcher__results {
+  min-block-size: 0;
+  overflow: auto;
+  padding: var(--zx-space-2);
+}
+
+.zx-launcher__group-label {
+  padding: var(--zx-space-3) var(--zx-space-3) var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-weight: 700;
+  letter-spacing: .04em;
+  text-transform: uppercase;
+}
+
+.zx-launcher__group[data-layout="grid"] {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(112px, 1fr));
+  gap: var(--zx-space-2);
+  padding: 0 var(--zx-space-1) var(--zx-space-2);
+}
+
+.zx-launcher__group[data-layout="grid"] .zx-launcher__group-label {
+  grid-column: 1 / -1;
+  padding-inline: var(--zx-space-2);
+}
+
+.zx-launcher__option {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-3);
+  inline-size: 100%;
+  min-block-size: calc(var(--zx-control-height) + var(--zx-space-2));
+  border: 0;
+  border-radius: var(--zx-radius-md);
+  background: transparent;
+  padding: var(--zx-space-2) var(--zx-space-3);
+  color: inherit;
+  text-align: start;
+  text-decoration: none;
+}
+
+.zx-launcher__option[aria-selected="true"],
+.zx-launcher__option:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-launcher__option[aria-current="page"] {
+  box-shadow: inset 2px 0 var(--zx-color-accent);
+}
+
+.zx-launcher__option[data-kind="application"] {
+  display: grid;
+  grid-template-rows: auto minmax(0, auto);
+  justify-items: center;
+  align-content: center;
+  min-block-size: 92px;
+  padding: var(--zx-space-3) var(--zx-space-2);
+  text-align: center;
+}
+
+.zx-launcher__option[data-kind="application"][aria-current="page"] {
+  box-shadow: inset 0 -2px var(--zx-color-accent);
+}
+
+.zx-launcher__option[data-kind="application"] .zx-launcher__icon {
+  min-block-size: 36px;
+  align-items: center;
+}
+
+.zx-launcher__option[data-kind="application"] .zx-launcher__copy {
+  inline-size: 100%;
+}
+
+.zx-launcher__option[data-kind="application"] .zx-launcher__description,
+.zx-launcher__option[data-kind="application"] .zx-launcher__badge {
+  display: none;
+}
+
+.zx-launcher__option[data-kind="application"] .zx-launcher__label {
+  font-size: var(--zx-text-sm);
+}
+
+.zx-launcher__option[aria-disabled="true"] {
+  color: var(--zx-color-text-muted);
+  cursor: not-allowed;
+  opacity: .65;
+}
+
+.zx-launcher__icon { display: inline-flex; flex: none; }
+.zx-launcher__copy { display: grid; min-inline-size: 0; gap: 2px; }
+.zx-launcher__label { overflow: hidden; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+.zx-launcher__description { overflow: hidden; color: var(--zx-color-text-muted); font-size: var(--zx-text-sm); text-overflow: ellipsis; white-space: nowrap; }
+.zx-launcher__badge { margin-inline-start: auto; color: var(--zx-color-text-muted); font-size: var(--zx-text-xs); }
+
+.zx-launcher__hints {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: end;
+  gap: var(--zx-space-4);
+  padding: var(--zx-space-2) var(--zx-space-4);
+  border-block-start: 1px solid var(--zx-color-border);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+}
+
+.zx-launcher__hints span {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+}
+
+.zx-launcher__hints kbd {
+  min-inline-size: 1.5rem;
+  padding-inline: 4px;
+  text-align: center;
+}
+
+@media (max-width: 520px) {
+  .zx-launcher__group[data-layout="grid"] {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+
+  .zx-launcher__shortcut {
+    display: none;
+  }
+
+  .zx-launcher__search {
+    grid-template-columns: auto minmax(0, 1fr) auto;
+  }
+
+  .zx-launcher__hints {
+    justify-content: center;
+  }
+}