@zeyos/zx 4.3.4 → 4.4.0

package/src/components/calendar/calendar.js

@@ -1,6 +1,7 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
+import { printf } from '../../core/i18n.js';
 import {
   CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey,
   calendarEventIntersects, calendarEventSpansDays, calendarPageDate, calendarRange,
@@ -189,7 +190,7 @@ export class Calendar extends Component {
       ref: 'views',
       class: 'zx-calendar__views',
       role: 'group',
-      ariaLabel: 'Calendar view'
+      ariaLabel: this._message('calendar.viewSwitch', 'Calendar view')
     }, this._views.map((view) => h('button', {
       type: 'button',
       class: 'zx-calendar__view-button',
@@ -643,7 +644,7 @@ export class Calendar extends Component {
             eventCount: String(count)
           },
           ariaCurrent: sameCalendarDay(day, this._now()) ? 'date' : null,
-          ariaLabel: `${this._format(day, { dateStyle: 'full' })}, ${count} ${count === 1 ? 'event' : 'events'}`,
+          ariaLabel: this._dayCountLabel(day, count),
           disabled: this.options.disabled
         }, this._format(day, { day: 'numeric' })));
       }
@@ -708,7 +709,7 @@ export class Calendar extends Component {
             activity: String(Math.min(3, count))
           },
           ariaCurrent: sameCalendarDay(day, this._now()) ? 'date' : null,
-          ariaLabel: `${this._format(day, { dateStyle: 'full' })}, ${count} ${count === 1 ? 'event' : 'events'}`,
+          ariaLabel: this._dayCountLabel(day, count),
           disabled: this.options.disabled
         }, String(day.getDate())));
       }
@@ -1473,6 +1474,35 @@ export class Calendar extends Component {
       if (!this._destroyed) this.refs.status.textContent = message;
     });
   }
+
+  /**
+   * Names a month or year cell by its date and how many events it holds. Singular and plural are
+   * separate keys because a language that inflects the noun cannot reach it from one template.
+   * @param {Date} day Day the cell stands for.
+   * @param {number} count Events on that day.
+   * @returns {string}
+   */
+  _dayCountLabel(day, count) {
+    const date = this._format(day, { dateStyle: 'full' });
+    return count === 1
+      ? this._message('calendar.dayEvent', '%1, %2 event', date, count)
+      : this._message('calendar.dayEvents', '%1, %2 events', date, count);
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   *
+   * Distinct from `msg()`: the built-in `msg` option answers the calendar's own vocabulary, so a
+   * dotted key falls past it to the host translator, which is what these strings never had.
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
 }
 
 /** @param {unknown} value @returns {CalendarView[]} */

package/src/components/card/card.js

@@ -86,7 +86,7 @@ export class Card extends Component {
         ref: 'actions',
         class: 'zx-card__actions',
         role: 'group',
-        ariaLabel: 'Card actions',
+        ariaLabel: this._message('card.actions', 'Card actions'),
         hidden: true
       });
       const content = h('div', { ref: 'content', class: 'zx-card__content', hidden: true });
@@ -225,6 +225,17 @@ export class Card extends Component {
     if (!this.refs.header) return;
     this.refs.header.hidden = this._title === '' && this.refs.actions.childElementCount === 0;
   }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @returns {string}
+   */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
 }
 
 /** @param {Element} host @param {CardContent} content @param {string} label */

package/src/components/card-view/card-view.css

@@ -589,3 +589,4 @@
     min-block-size: 44px;
   }
 }
+.zx-card-view .zx-record-card[data-selection-trigger="card"] { cursor: pointer; }

package/src/components/card-view/card-view.js

@@ -1,6 +1,6 @@
 // @ts-check
 import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
-import { RecordView, readViewField } from '../view/record-view.js';
+import { normalizeViewFieldControls, RecordView, readViewField } from '../view/record-view.js';
 import {
   createRecordCard, resolveRecordActions
 } from './record-card.js';
@@ -21,10 +21,13 @@ import {
  * @property {import('../view/record-view.js').ViewSort|null} [sort=null] Initial shared sort.
  * @property {'local'|'server'} [sortMode='local'] Local sorting or event-only server sorting.
  * @property {false|'single'|'multi'} [selectable=false] Record selection behavior.
+ * @property {'checkbox'|'card'} [selectionTrigger='checkbox'] Select through a checkbox or the non-interactive card surface.
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Preferred shared field order.
  * @property {string[]} [hiddenFields=[]] Initially hidden metadata fields.
- * @property {boolean} [fieldControls=true] Whether to expose shared field controls.
+ * @property {boolean|import('../view/record-view.js').ViewFieldControlsConfig} [fieldControls=true]
+ * Whether to expose shared field controls. `true` renders the chooser in the card toolbar and
+ * `false` omits it; an object customises its `label` and mounts it into `target`.
  * @property {string|Node|(()=>string|Node)|null} [emptyText=null] Empty-result content.
  * @property {RecordCardValueSource} [titleField=null] Title field id or explicit resolver.
  * @property {RecordCardValueSource} [subtitleField=null] Subtitle field id or explicit resolver.
@@ -79,6 +82,7 @@ export class CardView extends RecordView {
   /** @type {Readonly<CardViewOptions & RecordViewOptions>} */
   static defaults = {
     ...RecordView.defaults,
+    selectionTrigger: 'checkbox',
     titleField: null,
     subtitleField: null,
     preview: undefined,
@@ -124,10 +128,12 @@ export class CardView extends RecordView {
       this._initRecordView(root);
       root.setAttribute('aria-label', String(options.label || 'Card view'));
       const sort = h('label', { ref: 'sortWrap', class: 'zx-card-view__sort' },
-        h('span', { class: 'zx-card-view__sort-label' }, 'Sort'),
-        h('select', { ref: 'sort', ariaLabel: 'Sort cards' }));
+        h('span', { class: 'zx-card-view__sort-label' }, this._message('cardView.sort', 'Sort')),
+        h('select', { ref: 'sort', ariaLabel: this._message('cardView.sortCards', 'Sort cards') }));
       const toolbar = h('div', { class: 'zx-record-view__toolbar zx-card-view__toolbar' }, sort);
-      if (this.options.fieldControls) toolbar.append(this._createViewFieldControls('Fields'));
+      if (normalizeViewFieldControls(this.options.fieldControls).enabled) {
+        this._mountViewFieldControls(toolbar);
+      }
       const content = h('div', { ref: 'content', class: 'zx-card-view__content' });
       root.replaceChildren(toolbar, content);
       this.listen(this.refs.sort, 'change', () => this._changeCardSort());
@@ -140,6 +146,7 @@ export class CardView extends RecordView {
       this._renderCards();
       return root;
     } catch (error) {
+      this._removeViewFieldControls();
       if (!created) restoreTarget(root, this._cardOriginal);
       throw error;
     }
@@ -212,16 +219,18 @@ export class CardView extends RecordView {
     if (!this.refs?.sort || !this.refs?.sortWrap) return;
     const select = /** @type {HTMLSelectElement} */ (this.refs.sort);
     const sort = this.getSort();
-    const options = [h('option', { value: '', selected: sort === null }, 'Unsorted')];
+    const options = [h('option', {
+      value: '', selected: sort === null
+    }, this._message('cardView.unsorted', 'Unsorted'))];
     for (const field of this.getFields().filter((candidate) => candidate.sortable)) {
       options.push(h('option', {
         selected: sort?.id === field.id && sort.dir === 'asc',
         dataset: { sortId: field.id, sortDir: 'asc' }
-      }, `${field.label} (ascending)`));
+      }, this._message('cardView.sortAscending', '%1 (ascending)', field.label)));
       options.push(h('option', {
         selected: sort?.id === field.id && sort.dir === 'desc',
         dataset: { sortId: field.id, sortDir: 'desc' }
-      }, `${field.label} (descending)`));
+      }, this._message('cardView.sortDescending', '%1 (descending)', field.label)));
     }
     select.replaceChildren(...options);
     /** @type {HTMLElement} */ (this.refs.sortWrap).hidden = options.length === 1;
@@ -286,6 +295,7 @@ export class CardView extends RecordView {
         link: options.link,
         actions: options.actions,
         selectable: this.options.selectable,
+        selectionTrigger: options.selectionTrigger,
         selected: this._isViewSelected(id),
         variant: this._cardVariant,
         headingLevel: this._cardHeadingLevel
@@ -355,6 +365,11 @@ export class CardView extends RecordView {
       return;
     }
     if (isInteractiveWithin(target, card) || hasCardTextSelection(card)) return;
+    if (this.options.selectable && this._cardOptions().selectionTrigger === 'card') {
+      this.toggleSelection(id, { range: event.shiftKey });
+      card.focus({ preventScroll: true });
+      return;
+    }
     this._activateCard(record, id, index, event);
     if (this.options.selectable === 'single') this.toggleSelection(id, { selected: true });
   }
@@ -381,7 +396,8 @@ export class CardView extends RecordView {
     const id = this._viewRecordId(record);
     if (event.key === 'Enter') {
       event.preventDefault();
-      this._activateCard(record, id, index, event);
+      if (this.options.selectable && this._cardOptions().selectionTrigger === 'card') this.toggleSelection(id);
+      else this._activateCard(record, id, index, event);
     } else if (event.key === ' ' && this.options.selectable) {
       event.preventDefault();
       this.toggleSelection(id);

package/src/components/card-view/record-card.js

@@ -62,6 +62,7 @@ import { readViewField, renderViewField } from '../view/record-view.js';
  * @property {RecordCardLink|((record:ViewRecord,index:number)=>RecordCardLink)} [link]
  * @property {RecordCardAction[]|((record:ViewRecord,index:number)=>RecordCardAction[])} [actions=[]]
  * @property {false|'single'|'multi'} [selectable=false] Selection presentation.
+ * @property {'checkbox'|'card'} [selectionTrigger='checkbox'] Selection affordance for owning views.
  * @property {boolean} [selected=false] Current selection state.
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
  * @property {1|2|3|4|5|6} [headingLevel=3] Card title heading level.
@@ -84,7 +85,8 @@ import { readViewField, renderViewField } from '../view/record-view.js';
  *
  * The returned `<li>` belongs in a semantic `<ul>`/`<ol>`. When selectable its global
  * `aria-description` announces selection without applying the unsupported `aria-selected` state
- * to a listitem; multi-selection also adds a native checkbox. It deliberately remains a listitem
+ * to a listitem; multi-selection adds a native checkbox unless the owner opts into card-surface
+ * selection. It deliberately remains a listitem
  * rather than becoming an ARIA option because cards may contain native links and buttons, which
  * the listbox pattern does not permit inside an option. Preview images are paired with a stable
  * fallback. The owning component listens for image `error` and marks the fallback.
@@ -129,7 +131,7 @@ export function createRecordCard(record, index, options = {}) {
   const titleRow = titlePrefix
     ? h('div', { class: 'zx-record-card__title-row' }, titlePrefix, heading)
     : heading;
-  const selection = selectable === 'multi' ? h('label', {
+  const selection = selectable === 'multi' && options.selectionTrigger !== 'card' ? h('label', {
     class: 'zx-record-card__selection'
   }, h('input', {
     type: 'checkbox',
@@ -154,10 +156,12 @@ export function createRecordCard(record, index, options = {}) {
     tabindex: 0,
     ariaDescription: selectable ? selected ? 'Selected' : 'Not selected' : undefined,
     ariaLabelledby: headingId,
+    ariaKeyshortcuts: selectable && options.selectionTrigger === 'card' ? 'Space Enter' : undefined,
     dataset: {
       recordIndex: String(index),
       variant: normalizeVariant(options.variant),
-      selected: String(selected)
+      selected: String(selected),
+      selectionTrigger: selectable && options.selectionTrigger === 'card' ? 'card' : 'checkbox'
     }
   }, preview ? createPreview(preview) : null, body));
   return card;

package/src/components/code-editor/code-editor.css

@@ -0,0 +1,67 @@
+.zx-code-editor {
+  overflow: hidden;
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+}
+
+.zx-code-editor:focus-within {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-code-editor__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--zx-space-3);
+  min-block-size: var(--zx-control-height);
+  padding-inline: var(--zx-space-3);
+  border-block-end: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-subtle);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+}
+
+.zx-code-editor__language {
+  overflow: hidden;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-overflow: ellipsis;
+  text-transform: uppercase;
+  text-wrap: nowrap;
+}
+
+.zx-code-editor__position {
+  font-variant-numeric: tabular-nums;
+  text-wrap: nowrap;
+}
+
+.zx-code-editor__input {
+  display: block;
+  inline-size: 100%;
+  min-block-size: calc(var(--zx-control-height) * 4);
+  resize: vertical;
+  padding: var(--zx-space-3);
+  border: 0;
+  border-radius: 0;
+  outline: 0;
+  background: transparent;
+  box-shadow: none;
+  color: var(--zx-color-text);
+  font-family: var(--zx-font-mono);
+  font-size: var(--zx-text-sm);
+  line-height: 1.55;
+  tab-size: 2;
+}
+
+.zx-code-editor__input:focus-visible {
+  box-shadow: none;
+}
+
+.zx-code-editor[data-readonly="true"] {
+  background: var(--zx-color-bg-subtle);
+}
+
+.zx-code-editor[data-disabled="true"] {
+  opacity: 0.6;
+}

package/src/components/code-editor/code-editor.js

@@ -0,0 +1,288 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+
+/**
+ * @typedef {Object} CodeEditorOptions
+ * @property {unknown} [value=''] Initial text.
+ * @property {string} [name=''] Form field name.
+ * @property {string} [language='text'] Language identifier shown to the user and exposed as data.
+ * @property {string} [label='Code editor'] Accessible editor label.
+ * @property {string} [placeholder=''] Placeholder text.
+ * @property {number} [rows=12] Visible textarea rows.
+ * @property {string} [indent='\t'] Text inserted by Tab and removed by Shift+Tab.
+ * @property {'off'|'soft'|'hard'} [wrap='off'] Textarea wrapping behavior.
+ * @property {boolean} [spellcheck=false] Whether browser spellcheck is enabled.
+ * @property {boolean} [readOnly=false] Whether content can be selected but not changed.
+ * @property {boolean} [disabled=false] Whether the editor is disabled.
+ * @property {boolean} [status=true] Whether the line/column status is visible.
+ * @property {(event: CustomEvent<{value:string}>) => void} [oninput] Input listener.
+ * @property {(event: CustomEvent<{value:string}>) => void} [onchange] Change listener.
+ */
+
+/**
+ * Dependency-free source editor for structured text, Markdown, JSON and code. It deliberately uses
+ * a native textarea: values remain text-safe, browser undo and IME behavior stay intact, and Tab /
+ * Shift+Tab provide predictable indentation without a third-party editor runtime.
+ * @fires CodeEditor#input
+ * @fires CodeEditor#change
+ * @extends {Component<CodeEditorOptions>}
+ */
+export class CodeEditor extends Component {
+  static cssName = 'code-editor';
+
+  /** @type {CodeEditorOptions} */
+  static defaults = {
+    value: '',
+    name: '',
+    language: 'text',
+    label: 'Code editor',
+    placeholder: '',
+    rows: 12,
+    indent: '\t',
+    wrap: 'off',
+    spellcheck: false,
+    readOnly: false,
+    disabled: false,
+    status: true
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    this._initialChildren = this._createdRoot ? [] : [...root.childNodes];
+    this._initialAttributes = new Map(['data-language', 'data-readonly', 'data-disabled']
+      .map((name) => [name, root.getAttribute(name)]));
+    this._language = normalizeLanguage(this.options.language);
+    this._languageLabel = h('span', { class: 'zx-code-editor__language' }, this._language);
+    this._position = h('span', {
+      class: 'zx-code-editor__position',
+      role: 'status',
+      ariaLive: 'polite'
+    });
+    this._header = h('div', { class: 'zx-code-editor__header' }, this._languageLabel,
+      this.options.status ? this._position : null);
+    this._input = /** @type {HTMLTextAreaElement} */ (h('textarea', {
+      class: 'zx-code-editor__input',
+      name: this.options.name ? String(this.options.name) : undefined,
+      ariaLabel: String(this.options.label ?? 'Code editor'),
+      placeholder: String(this.options.placeholder ?? ''),
+      rows: normalizeRows(this.options.rows),
+      wrap: normalizeWrap(this.options.wrap),
+      spellcheck: Boolean(this.options.spellcheck),
+      readOnly: Boolean(this.options.readOnly),
+      disabled: Boolean(this.options.disabled),
+      autocomplete: 'off',
+      autocapitalize: 'off'
+    }));
+    this._input.value = String(this.options.value ?? '');
+    root.dataset.language = this._language;
+    root.dataset.readonly = String(Boolean(this.options.readOnly));
+    root.dataset.disabled = String(Boolean(this.options.disabled));
+    root.replaceChildren(this._header, this._input);
+
+    this.listen(this._input, 'keydown', (event) => this._handleKeydown(event));
+    this.listen(this._input, 'input', () => {
+      this._updatePosition();
+      this.emit('input', { value: this.getValue() });
+    });
+    this.listen(this._input, 'change', () => this.emit('change', { value: this.getValue() }));
+    for (const type of ['click', 'keyup', 'select', 'focus']) {
+      this.listen(this._input, type, () => this._updatePosition());
+    }
+    this._updatePosition();
+    return root;
+  }
+
+  /** @returns {string} */
+  getValue() { return this._input.value; }
+
+  /**
+   * Replaces the editor text.
+   * @param {unknown} value New value.
+   * @param {{silent?:boolean}} [options={}] Suppress the `change` event.
+   * @returns {this}
+   */
+  setValue(value, { silent = false } = {}) {
+    const next = String(value ?? '');
+    if (this._input.value === next) return this;
+    this._input.value = next;
+    this._updatePosition();
+    if (!silent) this.emit('change', { value: next });
+    return this;
+  }
+
+  /** @param {unknown} language New language identifier. @returns {this} */
+  setLanguage(language) {
+    this._language = normalizeLanguage(language);
+    this.el.dataset.language = this._language;
+    this._languageLabel.textContent = this._language;
+    return this;
+  }
+
+  /** @returns {this} */
+  focus() { this._input.focus(); return this; }
+
+  /** @returns {this} */
+  enable() { this._input.disabled = false; this.el.dataset.disabled = 'false'; return this; }
+
+  /** @returns {this} */
+  disable() { this._input.disabled = true; this.el.dataset.disabled = 'true'; return this; }
+
+  /** @param {boolean} value Read-only state. @returns {this} */
+  setReadOnly(value) {
+    this._input.readOnly = Boolean(value);
+    this.el.dataset.readonly = String(Boolean(value));
+    return this;
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  _handleKeydown(event) {
+    if (event.key !== 'Tab' || event.altKey || event.ctrlKey || event.metaKey ||
+        this._input.readOnly || this._input.disabled) return;
+    const indent = String(this.options.indent ?? '\t');
+    if (!indent) return;
+    event.preventDefault();
+    const result = indentSelection(
+      this._input.value,
+      this._input.selectionStart ?? 0,
+      this._input.selectionEnd ?? 0,
+      indent,
+      event.shiftKey
+    );
+    if (result.value === this._input.value) return;
+    this._input.value = result.value;
+    this._input.setSelectionRange(result.start, result.end);
+    this._updatePosition();
+    this.emit('input', { value: this.getValue() });
+  }
+
+  /** @returns {void} */
+  _updatePosition() {
+    if (!this.options.status) return;
+    const position = editorPosition(this._input.value, this._input.selectionStart ?? 0,
+      this._input.selectionEnd ?? 0);
+    this._position.textContent = position.lines > 1
+      ? `Ln ${position.line}, Col ${position.column} · ${position.lines} lines selected`
+      : `Ln ${position.line}, Col ${position.column}`;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (!this._createdRoot) {
+      this.el.replaceChildren(...this._initialChildren);
+      for (const [name, value] of this._initialAttributes) {
+        if (value === null) this.el.removeAttribute(name);
+        else this.el.setAttribute(name, value);
+      }
+    }
+    super.destroy();
+  }
+}
+
+/**
+ * Applies Tab or Shift+Tab to a textarea selection.
+ * @param {string} value Complete source value.
+ * @param {number} start Selection start.
+ * @param {number} end Selection end.
+ * @param {string} indent Indentation text.
+ * @param {boolean} outdent Whether to remove indentation.
+ * @returns {{value:string,start:number,end:number}}
+ */
+export function indentSelection(value, start, end, indent = '\t', outdent = false) {
+  const source = String(value ?? '');
+  const unit = String(indent ?? '');
+  const from = clampIndex(start, source.length);
+  const to = clampIndex(end, source.length);
+  if (!unit) return { value: source, start: from, end: to };
+
+  if (from === to && !outdent) {
+    return {
+      value: source.slice(0, from) + unit + source.slice(to),
+      start: from + unit.length,
+      end: from + unit.length
+    };
+  }
+
+  const lineStart = source.lastIndexOf('\n', Math.max(0, from - 1)) + 1;
+  let lineEnd = source.indexOf('\n', to);
+  if (lineEnd < 0) lineEnd = source.length;
+  const block = source.slice(lineStart, lineEnd);
+  const lines = block.split('\n');
+  let removedFirst = 0;
+  let delta = 0;
+  const transformed = lines.map((line, index) => {
+    if (!outdent) {
+      delta += unit.length;
+      return unit + line;
+    }
+    const removed = removableIndent(line, unit);
+    if (index === 0) removedFirst = removed;
+    delta -= removed;
+    return line.slice(removed);
+  }).join('\n');
+  const nextStart = outdent
+    ? Math.max(lineStart, from - Math.min(removedFirst, from - lineStart))
+    : from + unit.length;
+  return {
+    value: source.slice(0, lineStart) + transformed + source.slice(lineEnd),
+    start: nextStart,
+    end: Math.max(nextStart, to + delta)
+  };
+}
+
+/** @param {string} value @param {number} start @param {number} end @returns {{line:number,column:number,lines:number}} */
+export function editorPosition(value, start, end = start) {
+  const source = String(value ?? '');
+  const from = clampIndex(start, source.length);
+  const to = clampIndex(end, source.length);
+  const before = source.slice(0, from);
+  return {
+    line: before.split('\n').length,
+    column: from - before.lastIndexOf('\n'),
+    lines: source.slice(from, to).split('\n').length
+  };
+}
+
+/** @param {string} line @param {string} indent @returns {number} */
+function removableIndent(line, indent) {
+  if (line.startsWith(indent)) return indent.length;
+  if (indent === '\t') return line.startsWith('\t') ? 1 : Math.min(/^ +/.exec(line)?.[0].length ?? 0, 2);
+  return Math.min(/^\s+/.exec(line)?.[0].length ?? 0, indent.length);
+}
+
+/** @param {unknown} value @returns {string} */
+function normalizeLanguage(value) {
+  const language = String(value ?? 'text').trim().toLowerCase();
+  return /^[a-z0-9][a-z0-9+_.-]*$/.test(language) ? language : 'text';
+}
+
+/** @param {unknown} value @returns {number} */
+function normalizeRows(value) {
+  const rows = Number(value);
+  return Number.isFinite(rows) ? Math.max(2, Math.min(100, Math.round(rows))) : 12;
+}
+
+/** @param {unknown} value @returns {'off'|'soft'|'hard'} */
+function normalizeWrap(value) {
+  return ['off', 'soft', 'hard'].includes(String(value)) ? /** @type {'off'|'soft'|'hard'} */ (value) : 'off';
+}
+
+/** @param {unknown} value @param {number} length @returns {number} */
+function clampIndex(value, length) {
+  const number = Number(value);
+  return Math.max(0, Math.min(length, Number.isFinite(number) ? Math.round(number) : 0));
+}
+
+/**
+ * Code editor input event.
+ * @event CodeEditor#input
+ * @type {CustomEvent<{value:string}>}
+ */
+
+/**
+ * Code editor committed change event.
+ * @event CodeEditor#change
+ * @type {CustomEvent<{value:string}>}
+ */

package/src/components/code-editor/field-adapter.js

@@ -0,0 +1,34 @@
+import { CodeEditor } from './code-editor.js';
+import { Field } from '../field/field.js';
+
+/**
+ * Registers the CodeEditor-backed `code` field type.
+ * @returns {void}
+ */
+export function registerCodeEditorFieldAdapter() {
+  Field.register('code', (field, options) => {
+    const editor = field.own(new CodeEditor(null, {
+      label: options.label ? String(options.label) : 'Code editor',
+      placeholder: options.placeholder,
+      readOnly: Boolean(options.props?.readOnly),
+      disabled: Boolean(options.disabled),
+      ...(options.props ?? {}),
+      value: options.value
+    }));
+    let setting = false;
+    editor.on('input', (event) => {
+      if (!setting) field.emit('change', { value: event.detail.value });
+    });
+    return {
+      el: editor.el,
+      get: () => editor.getValue(),
+      set: (value) => {
+        setting = true;
+        try { editor.setValue(value, { silent: true }); }
+        finally { setting = false; }
+      },
+      focus: () => editor.focus(),
+      setDisabled: (value) => (value ? editor.disable() : editor.enable())
+    };
+  });
+}