name: DataTable

attributes:
  editable:
    type: boolean
    behavior: Enable row, field, cell, and save controls.

state:
  fields: Array of column definitions; assign before list.
  list: Array of row objects; each key matches a field id.
  _originalList: Internal unfiltered row snapshot.
  sortConfig: "{ fieldId, direction }"
  filterConfig: Per-field filter configuration.
  selectedRowCount: Selected row count.
  isDirty: Whether edits are pending save.

field:
  required: [id, name]
  fields:
    id: Unique column id and row value key.
    name: Header label.
    type: Source value type.
    memo: Field description.
    settings: "{ width, pinned, formType, options, decimals, prefix, suffix, thousandSep, labelOn, labelOff }"
    formatter: Function receiving value and field.

methods:
  addRow: Add an empty row.
  deleteSelectedRow: Delete selected rows.
  saveChanges: Dispatch save.
  addField: Add a field.
  editField: Edit the active field.
  deleteField: Delete the active field.
  editCell: Open a cell editor.
  applySortFilter: Apply current or supplied sorting and filters.

events:
  save:
    detail: "{ list, fields }"
  savefields:
    detail: fields
  remove:
    detail: "{ items }"

global:
  DataTable:
    methods:
      registerFieldType: Register a field type configuration.
      getFieldTypes: Return registered field types.

related:
  - AutoForm.yaml
  - ../utilities/VirtualScroll.yaml
  - Resizer.yaml

rules:
  - Bind fields and list with $.state.fields and $.state.list.
  - Treat underscore-prefixed state fields as internal read-only diagnostics.
  - Custom field editors must be registered in AutoForm before use.

example: |
  <DataTable id="orders" editable></DataTable>
  <script>
  const table = document.querySelector('#orders')
  table.state.fields = [
    { id: 'name', name: 'Name', type: 'text' },
    { id: 'total', name: 'Total', type: 'number' }
  ]
  table.state.list = [{ name: 'Ada', total: 42 }]
  table.addEventListener('save', event => saveRows(event.detail.list))
  </script>

tests:
  - apigo.cc/web/dataTable/test/all.spec.js
  - apigo.cc/web/dataTable/test/correctness.spec.js
  - apigo.cc/web/dataTable/test/validation.spec.js