name: DataGrid

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.

editing:
  formTypes: [text, number, select, checkbox, radio, switch, textarea, date, datetime, TagsInput, DatePicker, ColorPicker, IconPicker]
  rule: Double-click an editable cell, then click outside the editor or press Enter to save its bound value.

filtering:
  rule: Click a column header, enter a value in its menu, and the grid filters immediately. Use the menu controls for sort and reset.

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.
  onScroll: Refresh the virtual row window after scrolling.

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

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

related:
  - ../base/AutoForm.yaml
  - ../base/Modal.yaml
  - ../base/Dialog.yaml
  - ../../utilities/VirtualScroll.yaml
  - ../base/Resizer.yaml
  - ../form/DatePicker.yaml
  - ../form/ColorPicker.yaml
  - ../form/IconPicker.yaml
  - ../form/TagsInput.yaml

rules:
  - Bind fields and list with $.state.fields and $.state.list.
  - Give the DataGrid or its parent an explicit height so virtual scrolling has a viewport.
  - Treat underscore-prefixed state fields as internal read-only diagnostics.
  - Custom field editors must be registered in AutoForm before use.

example: |
  <script>
  const orderFields = [
    { id: 'name', name: 'Name', type: 'text', settings: { formType: 'text' } },
    { id: 'total', name: 'Total', type: 'number', settings: { formType: 'number', prefix: '$', decimals: 2 } },
    { id: 'status', name: 'Status', type: 'text', settings: { formType: 'select', options: ['draft', 'paid'] } },
    { id: 'paid', name: 'Paid', type: 'boolean', settings: { formType: 'switch' } },
    { id: 'tags', name: 'Tags', type: 'object', settings: { formType: 'TagsInput' } },
    { id: 'due', name: 'Due', type: 'date', settings: { formType: 'DatePicker' } }
  ]
  const orders = [{ name: 'Ada', total: 42, status: 'paid', paid: true, tags: ['priority'], due: '2026-07-12' }]
  const saveRows = rows => console.log(rows)
  </script>
  <div style="height: 480px">
    <DataGrid id="orders" editable $.state.fields="orderFields" $.state.list="orders" $onsave="saveRows(event.detail.list)"></DataGrid>
  </div>

tests:
  - DataGrid.test.html