@inglorious/ui 9.2.0 → 9.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "9.2.0",
+  "version": "9.4.0",
   "description": "A design system for Inglorious Web with render-function components and customizable themes",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -315,7 +315,7 @@
     "@iconify-icons/fa7-regular": "^2.0.0",
     "@iconify-icons/fa7-solid": "^2.0.0",
     "@iconify-icons/material-symbols": "^2.0.6",
-    "@inglorious/charts": "12.1.0",
+    "@inglorious/charts": "12.2.1",
     "@inglorious/eslint-config": "1.2.0",
     "@inglorious/store": "12.0.0",
     "@inglorious/vite-plugin-jsx": "2.0.5",

package/src/controls/input/template.js

@@ -93,6 +93,7 @@ export const Input = {
       type, // eslint-disable-line no-unused-vars
       name = "",
       label,
+      ariaLabel,
       hint, // eslint-disable-line no-unused-vars
       messageId,
       inputType = "text",
@@ -129,7 +130,7 @@ export const Input = {
         id=${controlId || nothing}
         name=${name}
         type=${inputType}
-        aria-label=${fallbackLabel(controlId, label)}
+        aria-label=${ariaLabel || fallbackLabel(controlId, label)}
         aria-describedby=${messageId || nothing}
         aria-invalid=${error ? "true" : "false"}
         .value=${value}

package/src/data-display/data-grid/base.css

@@ -35,9 +35,16 @@
     gap: var(--iw-space-2);
   }
 
-  .iw-data-grid-filter-range-input {
-    min-width: 0;
+  /* The two ends of a range share the column; native date and number
+     fields would otherwise keep a width of their own and spill out. */
+  .iw-data-grid-filter-range > .iw-input {
     flex: 1 1 0;
+    min-width: 0;
+
+    .iw-input-frame,
+    .iw-input-control {
+      min-width: 0;
+    }
   }
 
   .iw-data-grid-row {
@@ -48,6 +55,10 @@
     display: flex;
   }
 
+  .iw-data-grid-edits-actions {
+    display: flex;
+  }
+
   .iw-data-grid-column-resizer {
     position: absolute;
     inset: 0 0 0 auto;

package/src/data-display/data-grid/data-grid.stories.js

@@ -74,6 +74,45 @@ export const Default = {
   },
 }
 
+/** Editable columns: change cells, then reset or save the edits in the footer. */
+export const Editable = {
+  args: {
+    ...Default.args,
+    id: "dataGridEditable",
+    search: null,
+    selection: [],
+    columns: [
+      { id: "name", title: "Name", isSortable: true, isEditable: true },
+      { id: "age", title: "Age", type: "number", isEditable: true },
+      {
+        id: "active",
+        title: "Active",
+        type: "boolean",
+        width: 100,
+        isEditable: true,
+      },
+      {
+        id: "role",
+        title: "Role",
+        width: 140,
+        isEditable: true,
+        options: [
+          { value: "Admin", label: "Admin" },
+          { value: "User", label: "User" },
+        ],
+      },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Columns with `isEditable` put an editor in each cell, by type, or a drop-down with `options`. Edits stay apart from the rows, counted in the footer, until saved.",
+      },
+    },
+  },
+}
+
 export const Paginated = {
   args: {
     ...Default.args,

package/src/data-display/data-grid/filters/range.js

@@ -19,7 +19,6 @@ export const RangeFilter = {
         placeholder: column.filter.placeholder ?? "≥",
         size: "sm",
         isFullWidth: true,
-        className: "iw-data-grid-filter-range-input",
         onChange: (value) => {
           const formattedValue = value ? format(value, column.type) : null
           entity.onFilterChange?.({
@@ -34,7 +33,6 @@ export const RangeFilter = {
         placeholder: column.filter.placeholder ?? "≤",
         size: "sm",
         isFullWidth: true,
-        className: "iw-data-grid-filter-range-input",
         onChange: (value) => {
           const formattedValue = value ? format(value, column.type) : null
           entity.onFilterChange?.({

package/src/data-display/data-grid/handlers.js

@@ -3,7 +3,12 @@
  * @typedef {import('../../../types/data-display/data-grid').Column} Column
  */
 
-import { getRowKeyValue, getRows, getTotalRows } from "./helpers.js"
+import {
+  getEditedRows,
+  getRowKeyValue,
+  getRows,
+  getTotalRows,
+} from "./helpers.js"
 
 const MIN_COLUMN_WIDTH = 72
 const VIRTUAL_START = 0
@@ -285,6 +290,43 @@ export function selectionClear(entity) {
   entity.selection.length = 0
 }
 
+/**
+ * Records the user's edit of a cell, kept apart from the rows until saved. An
+ * edit back to the row's own value is no edit at all.
+ * @param {DataGridEntity} entity
+ * @param {{ rowId: string|number, columnId: string, value: any }} payload
+ */
+export function cellChange(entity, { rowId, columnId, value }) {
+  const row = entity.rows.find((item) => getRowKeyValue(entity, item) === rowId)
+  if (!row) return
+
+  entity.edits ??= {}
+  const edits = (entity.edits[rowId] ??= {})
+  if (isSameValue(row[columnId], value)) {
+    delete edits[columnId]
+  } else {
+    edits[columnId] = value
+  }
+  if (!Object.keys(edits).length) delete entity.edits[rowId]
+}
+
+/**
+ * Drops every unsaved edit.
+ * @param {DataGridEntity} entity
+ */
+export function editsReset(entity) {
+  entity.edits = {}
+}
+
+/**
+ * Writes the unsaved edits into the rows.
+ * @param {DataGridEntity} entity
+ */
+export function editsSave(entity) {
+  entity.rows = getEditedRows(entity)
+  entity.edits = {}
+}
+
 /**
  * Handles the scroll event to update the virtualized visible range.
  * @param {DataGridEntity} entity
@@ -394,6 +436,7 @@ function initDataGrid(entity) {
   }
   entity.selection ??= []
   entity.selectionAnchor ??= null
+  entity.edits ??= {}
   entity.isMultiSelect ??= true
   entity.isVirtualized ??= false
 
@@ -457,7 +500,7 @@ function getDefaultColumnFilter(type) {
  */
 function getDefaultColumnWidth(filterType) {
   if (filterType === "number") return 70
-  if (filterType === "range") return 120
+  if (filterType === "range") return 160
   if (filterType === "select") return 70
   if (filterType === "date") return 120
   if (filterType === "time") return 120
@@ -521,3 +564,14 @@ function assertRowKeys(entity) {
     seen.add(rowKey)
   })
 }
+
+/**
+ * Whether two cell values are the same, dates by their time.
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+function isSameValue(a, b) {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  return Object.is(a, b)
+}

package/src/data-display/data-grid/helpers.js

@@ -8,6 +8,57 @@ export function getRowKeyValue(entity, row) {
   return row?.[entity.rowId]
 }
 
+/**
+ * A cell's value as shown: the user's unsaved edit if there is one, else the
+ * row's own.
+ * @param {TableEntity} entity
+ * @param {any} row
+ * @param {string} columnId
+ * @returns {any}
+ */
+export function getCellValue(entity, row, columnId) {
+  const edits = entity.edits?.[getRowKeyValue(entity, row)]
+  return edits && Object.hasOwn(edits, columnId)
+    ? edits[columnId]
+    : row?.[columnId]
+}
+
+/**
+ * Whether a cell has an unsaved edit.
+ * @param {TableEntity} entity
+ * @param {any} row
+ * @param {string} columnId
+ * @returns {boolean}
+ */
+export function isCellEdited(entity, row, columnId) {
+  const edits = entity.edits?.[getRowKeyValue(entity, row)]
+  return Boolean(edits && Object.hasOwn(edits, columnId))
+}
+
+/**
+ * How many cells have unsaved edits.
+ * @param {TableEntity} entity
+ * @returns {number}
+ */
+export function getEditCount(entity) {
+  return Object.values(entity.edits ?? {}).reduce(
+    (count, edits) => count + Object.keys(edits).length,
+    0,
+  )
+}
+
+/**
+ * Every row with its unsaved edits applied, in the rows' own order.
+ * @param {TableEntity} entity
+ * @returns {any[]}
+ */
+export function getEditedRows(entity) {
+  return entity.rows.map((row) => {
+    const edits = entity.edits?.[getRowKeyValue(entity, row)]
+    return edits ? { ...row, ...edits } : row
+  })
+}
+
 /**
  * Gets the processed rows (filtered, searched, sorted, paginated).
  * @param {TableEntity} entity
@@ -69,7 +120,7 @@ export function getPaginationInfo(entity) {
  * @returns {"asc"|"desc"|null}
  */
 export function getSortDirection(entity, columnId) {
-  const sort = entity.sorts.find((s) => s.column === columnId)
+  const sort = entity.sorts?.find((s) => s.column === columnId)
   return sort?.direction || null
 }
 
@@ -136,7 +187,7 @@ export function isSomeSelected(entity) {
  * @returns {any[]}
  */
 function applyFilters(entity, rows) {
-  if (!Object.keys(entity.filters).length) {
+  if (!Object.keys(entity.filters ?? {}).length) {
     return rows
   }
 
@@ -201,7 +252,7 @@ function applySearch(entity, rows) {
  * @returns {any[]}
  */
 function applySorts(entity, rows) {
-  if (!entity.sorts.length) {
+  if (!entity.sorts?.length) {
     return rows
   }
 

package/src/data-display/data-grid/index.js

@@ -19,6 +19,9 @@ export const DataGrid = {
       onPagePrev: () => api.notify(`#${id}:pagePrev`),
       onPageSizeChange: (pageSize) =>
         api.notify(`#${id}:pageSizeChange`, pageSize),
+      onCellChange: (payload) => api.notify(`#${id}:cellChange`, payload),
+      onEditsReset: () => api.notify(`#${id}:editsReset`),
+      onEditsSave: () => api.notify(`#${id}:editsSave`),
       onVirtualMount: (containerEl) =>
         api.notify(`#${id}:virtualMount`, containerEl),
       onVirtualScroll: (containerEl) =>
@@ -30,6 +33,10 @@ export const DataGrid = {
 }
 
 export const {
+  getCellValue,
+  getEditCount,
+  getEditedRows,
+  isCellEdited,
   getPaginationInfo,
   getRows,
   isSomeSelected,

package/src/data-display/data-grid/style.css

@@ -1,6 +1,7 @@
 @import "../../controls/input/style.css";
 @import "../../controls/select/style.css";
 @import "../../controls/button/style.css";
+@import "../../controls/checkbox/style.css";
 @import "../../navigation/pagination/style.css";
 
 @import "./base";

package/src/data-display/data-grid/template.js

@@ -10,16 +10,21 @@ import { classMap } from "@inglorious/web/directives/class-map"
 import { repeat } from "@inglorious/web/directives/repeat"
 import { when } from "@inglorious/web/directives/when"
 
+import { Button } from "../../controls/button/index.js"
+import { Checkbox } from "../../controls/checkbox/index.js"
 import { Input } from "../../controls/input/index.js"
 import { Select } from "../../controls/select/index.js"
 import { Pagination } from "../../navigation/pagination/index.js"
 import { VirtualList } from "../virtual-list/index.js"
 import { Filters } from "./filters/index.js"
 import {
+  getCellValue,
+  getEditCount,
   getPaginationInfo,
   getRowKeyValue,
   getRows,
   getSortDirection,
+  isCellEdited,
 } from "./helpers.js"
 
 const DIVISOR = 2
@@ -27,6 +32,14 @@ const DIVISOR = 2
 const PRETTY_PAGE = 1
 const FIRST_PAGE = 0
 const LAST_PAGE = 1
+const ONE_EDIT = 1
+const WEB_URL = /^https?:\/\//i
+/** Fields edit dates as `YYYY-MM-DD`. */
+const DATE_LENGTH = 10
+const DATE_PART_LENGTH = 2
+/** Date's months count from zero, people's from one. */
+const MONTH_OFFSET = 1
+const INPUT_TYPES = { number: "number", date: "date", url: "url" }
 
 export const DataGrid = {
   /**
@@ -67,7 +80,7 @@ export const DataGrid = {
    */
   renderHeader(props) {
     return html`<div class="iw-data-grid-header">
-      ${props.search && this.renderToolbar?.(props)}
+      ${when(props.search, () => this.renderToolbar?.(props))}
       <div class="iw-data-grid-header-row">
         ${repeat(
           props.columns,
@@ -108,7 +121,10 @@ export const DataGrid = {
         @click=${() => column.isSortable && props.onSortChange?.(column.id)}
         class="iw-data-grid-header-title"
       >
-        ${column.title} ${getSortIcon(getSortDirection(props, column.id))}
+        ${column.title}
+        ${when(column.isSortable, () =>
+          getSortIcon(getSortDirection(props, column.id)),
+        )}
       </div>
 
       ${when(column.isFilterable, () => Filters.render(props, column))}
@@ -225,7 +241,11 @@ export const DataGrid = {
         props.columns,
         (column) => column.id,
         (column, index) =>
-          this.renderCell?.(props, { cell: row[column.id], index }),
+          this.renderCell?.(props, {
+            cell: getCellValue(props, row, column.id),
+            index,
+            row,
+          }),
       )}
     </div>`
   },
@@ -235,25 +255,86 @@ export const DataGrid = {
    * Override to customize per-column cell structure.
    * @param {DataGridProps} props The data grid props.
    * @param {object} payload The payload.
-   * @param {any} payload.cell The cell data.
+   * @param {any} payload.cell The cell data, with any unsaved edit.
    * @param {number} payload.index The column index.
+   * @param {Row} payload.row The row the cell is in.
    * @returns {TemplateResult} The rendered cell.
    */
-  renderCell(props, { cell, index }) {
+  renderCell(props, { cell, index, row }) {
     const column = props.columns[index]
+    const isEditable = Boolean(column.isEditable && row)
 
+    // Typing in a cell's editor is not picking its row.
     return html`<div
       class="iw-data-grid-cell ${classMap({
         "iw-data-grid-cell-number": column.type === "number",
         "iw-data-grid-cell-date": column.type === "date",
         "iw-data-grid-cell-boolean": column.type === "boolean",
+        "iw-data-grid-cell-editable": isEditable,
+        "iw-data-grid-cell-edited":
+          isEditable && isCellEdited(props, row, column.id),
       })}"
       style=${getColumnStyle(column)}
+      @click=${isEditable ? (event) => event.stopPropagation() : undefined}
     >
-      ${this.renderValue?.(props, { value: cell, column, index })}
+      ${when(
+        isEditable,
+        () => this.renderEditor?.(props, { value: cell, column, row, index }),
+        () => this.renderValue?.(props, { value: cell, column, index }),
+      )}
     </div>`
   },
 
+  /**
+   * Renders the field that edits a cell of an `isEditable` column: a
+   * drop-down when the column has `options`, a checkbox for booleans, a date
+   * or number field for those types, and a text field otherwise.
+   * Override to edit some columns differently.
+   * @param {DataGridProps} props The data grid props.
+   * @param {object} payload The payload.
+   * @param {any} payload.value The cell's value, with any unsaved edit.
+   * @param {Column} payload.column The column definition.
+   * @param {Row} payload.row The row the cell is in.
+   * @returns {TemplateResult} The rendered editor.
+   */
+  renderEditor(props, { value, column, row }) {
+    const change = (next) =>
+      props.onCellChange?.({
+        rowId: getRowKeyValue(props, row),
+        columnId: column.id,
+        value: next,
+      })
+
+    if (column.options) {
+      return Select.render({
+        size: "sm",
+        ariaLabel: column.title,
+        value: value ?? "",
+        options: column.options,
+        isFullWidth: true,
+        onChange: change,
+      })
+    }
+
+    if (column.type === "boolean") {
+      return Checkbox.render({
+        "aria-label": column.title,
+        isChecked: Boolean(value),
+        onChange: change,
+      })
+    }
+
+    const saved = row[column.id]
+    return Input.render({
+      size: "sm",
+      ariaLabel: column.title,
+      inputType: INPUT_TYPES[column.type] ?? "text",
+      value: column.type === "date" ? toDateField(value) : (value ?? ""),
+      isFullWidth: true,
+      onChange: (text) => change(fromField(text, column.type, saved)),
+    })
+  },
+
   /**
    * Renders the raw cell value for a column.
    * Override to format values or inject custom content.
@@ -262,8 +343,16 @@ export const DataGrid = {
    * @param {any} payload.value The value to render.
    * @returns {any} The value to be rendered.
    */
-  renderValue(_props, { value }) {
-    return value
+  renderValue(_props, { value, column }) {
+    // A link only for a web address: a `javascript:` one must not run.
+    return when(
+      column.type === "url" && WEB_URL.test(String(value ?? "")),
+      () =>
+        html`<a href=${value} target="_blank" rel="noopener noreferrer"
+          >${value}</a
+        >`,
+      () => value,
+    )
   },
 
   /**
@@ -274,22 +363,57 @@ export const DataGrid = {
    */
   renderFooter(props) {
     const pagination = getPaginationInfo(props)
+    const editCount = getEditCount(props)
 
-    if (!pagination) {
+    if (!pagination && !editCount) {
       return null
     }
 
     return html`<div class="iw-data-grid-footer">
-      <div class="iw-data-grid-footer-row">
-        <div>
-          ${pagination.start + PRETTY_PAGE} to ${pagination.end} of
-          ${pagination.totalRows} entries
-        </div>
-
-        ${this.renderPagination?.(props, pagination)}
-        ${when(pagination.pageSizes, () =>
-          this.renderPageSize?.(props, pagination),
-        )}
+      ${when(editCount, () => this.renderEdits?.(props, editCount))}
+      ${when(
+        pagination,
+        () =>
+          html`<div class="iw-data-grid-footer-row">
+            <div>
+              ${pagination.start + PRETTY_PAGE} to ${pagination.end} of
+              ${pagination.totalRows} entries
+            </div>
+
+            ${this.renderPagination?.(props, pagination)}
+            ${when(pagination.pageSizes, () =>
+              this.renderPageSize?.(props, pagination),
+            )}
+          </div>`,
+      )}
+    </div>`
+  },
+
+  /**
+   * Renders the bar that counts the unsaved edits, with buttons to reset or
+   * save them. Shown only while there are edits.
+   * @param {DataGridProps} props The data grid props.
+   * @param {number} editCount How many cells have unsaved edits.
+   * @returns {TemplateResult} The rendered bar.
+   */
+  renderEdits(props, editCount) {
+    return html`<div class="iw-data-grid-footer-row iw-data-grid-edits">
+      <div role="status">
+        ${editCount} ${editCount === ONE_EDIT ? "change" : "changes"}
+      </div>
+      <div class="iw-data-grid-edits-actions">
+        ${Button.render({
+          children: "Reset",
+          variant: "ghost",
+          size: "sm",
+          onClick: () => props.onEditsReset?.(),
+        })}
+        ${Button.render({
+          children: props.saveLabel ?? "Save changes",
+          color: "primary",
+          size: "sm",
+          onClick: () => props.onEditsSave?.(),
+        })}
       </div>
     </div>`
   },
@@ -471,3 +595,38 @@ function getVirtualizationState(props, totalItems) {
     visibleRange: { start, end },
   }
 }
+
+/**
+ * A date, in whatever form a row keeps it, as a date field shows it.
+ * @param {Date|number|string|null|undefined} value
+ * @returns {string}
+ */
+function toDateField(value) {
+  if (value == null || value === "") return ""
+  if (typeof value === "string") return value.slice(0, DATE_LENGTH)
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return ""
+  const pad = (part) => String(part).padStart(DATE_PART_LENGTH, "0")
+  return `${date.getFullYear()}-${pad(date.getMonth() + MONTH_OFFSET)}-${pad(date.getDate())}`
+}
+
+/**
+ * What a field holds, back in the form the row kept the value in: a number,
+ * or a date as a `Date`, a timestamp or a string, as it was. A date that had
+ * a time of day keeps it.
+ * @param {string} text
+ * @param {string} type The column's type.
+ * @param {any} saved The row's own value.
+ * @returns {any}
+ */
+function fromField(text, type, saved) {
+  if (type === "number") return text === "" ? null : Number(text)
+  if (type !== "date") return text
+  if (text === "") return null
+  if (!(saved instanceof Date) && typeof saved !== "number") return text
+
+  const [year, month, day] = text.split("-").map(Number)
+  const date = new Date(saved)
+  date.setFullYear(year, month - MONTH_OFFSET, day)
+  return saved instanceof Date ? date : date.getTime()
+}

package/src/data-display/data-grid/theme.css

@@ -145,4 +145,21 @@
       );
     }
   }
+
+  /* An editor fills its cell, which keeps less padding around it. */
+  .iw-data-grid-cell-editable {
+    padding: var(--iw-space-2);
+  }
+
+  .iw-data-grid-cell-edited {
+    background: color-mix(in srgb, var(--iw-color-warning) 12%, transparent);
+  }
+
+  .iw-data-grid-edits {
+    gap: var(--iw-space-3);
+
+    & + .iw-data-grid-footer-row {
+      margin-block-start: var(--iw-space-3);
+    }
+  }
 }

package/src/examples/dashboard/primitive-section.js

@@ -41,20 +41,20 @@ export const PrimitiveSection = {
                 variant: "h4",
                 children: showEmpty ? "Choose a Primitive" : name,
               }),
-              category
-                ? Typography.render({
-                    variant: "body2",
-                    color: "secondary",
-                    children: `Category: ${category}`,
-                  })
-                : "",
-              summary
-                ? Typography.render({
-                    variant: "body1",
-                    color: "secondary",
-                    children: summary,
-                  })
-                : "",
+              when(category, () =>
+                Typography.render({
+                  variant: "body2",
+                  color: "secondary",
+                  children: `Category: ${category}`,
+                }),
+              ),
+              when(summary, () =>
+                Typography.render({
+                  variant: "body1",
+                  color: "secondary",
+                  children: summary,
+                }),
+              ),
             ],
           }),
           Card.render({
@@ -99,61 +99,61 @@ export const PrimitiveSection = {
               `,
             }),
           }),
-          showEmpty
-            ? ""
-            : Card.render({
-                padding: "xl",
-                className: "iw-primitive-example",
-                children: Flex.render({
-                  direction: "column",
-                  gap: "md",
-                  children: [
-                    Typography.render({
-                      variant: "h6",
-                      children: "Example",
-                    }),
-                    Grid.render({
-                      minColumnWidth: "18rem",
-                      gap: "lg",
-                      children: [
-                        Flex.render({
-                          direction: "column",
-                          gap: "sm",
-                          children: [
-                            Typography.render({
-                              variant: "body2",
-                              color: "secondary",
-                              children: "Code",
-                            }),
-                            html`<pre class="iw-primitive-code"><code>${
-                              exampleCode ?? "// Example coming soon."
-                            }</code></pre>`,
-                          ],
-                        }),
-                        Flex.render({
-                          direction: "column",
-                          gap: "sm",
-                          children: [
-                            Typography.render({
-                              variant: "body2",
-                              color: "secondary",
-                              children: "Result",
-                            }),
-                            html`<div class="iw-primitive-preview">
-                              ${
-                                examplePreview ??
-                                html`<div class="iw-primitive-preview-empty">
-                                  Preview coming soon.
-                                </div>`
-                              }
-                            </div>`,
-                          ],
-                        }),
-                      ],
-                    }),
-                  ],
-                }),
+          when(!showEmpty, () =>
+            Card.render({
+              padding: "xl",
+              className: "iw-primitive-example",
+              children: Flex.render({
+                direction: "column",
+                gap: "md",
+                children: [
+                  Typography.render({
+                    variant: "h6",
+                    children: "Example",
+                  }),
+                  Grid.render({
+                    minColumnWidth: "18rem",
+                    gap: "lg",
+                    children: [
+                      Flex.render({
+                        direction: "column",
+                        gap: "sm",
+                        children: [
+                          Typography.render({
+                            variant: "body2",
+                            color: "secondary",
+                            children: "Code",
+                          }),
+                          html`<pre class="iw-primitive-code"><code>${
+                            exampleCode ?? "// Example coming soon."
+                          }</code></pre>`,
+                        ],
+                      }),
+                      Flex.render({
+                        direction: "column",
+                        gap: "sm",
+                        children: [
+                          Typography.render({
+                            variant: "body2",
+                            color: "secondary",
+                            children: "Result",
+                          }),
+                          html`<div class="iw-primitive-preview">
+                            ${
+                              examplePreview ??
+                              html`<div class="iw-primitive-preview-empty">
+                                Preview coming soon.
+                              </div>`
+                            }
+                          </div>`,
+                        ],
+                      }),
+                    ],
+                  }),
+                ],
               }),
+            }),
+          ),
         ],
       }),
     })

package/types/controls/input.d.ts

@@ -20,6 +20,8 @@ export interface InputProps {
   value?: string
   placeholder?: string
   label?: string
+  /** Names the field for assistive tech when it has no visible `label`. */
+  ariaLabel?: string
   hint?: string
   error?: string
   size?: "sm" | "md" | "lg"

package/types/data-display/data-grid.d.ts

@@ -26,7 +26,11 @@ export interface DataGridVirtualization {
 export interface Column {
   id: string
   title: string
-  type?: "string" | "number" | "boolean" | "date"
+  /**
+   * `"url"` cells show web addresses as links. A date column's editor gives
+   * back dates in the form the row keeps them: `Date`, timestamp or string.
+   */
+  type?: "string" | "number" | "boolean" | "date" | "url"
   isSortable?: boolean
   isFilterable?: boolean
   filter?: {
@@ -42,6 +46,13 @@ export interface Column {
    * - number / CSS length string: fixed width
    */
   width?: number | string
+  /**
+   * Lets the user edit the column's cells: a text, number or date field by
+   * its `type`, a checkbox for booleans, or a drop-down with `options`.
+   */
+  isEditable?: boolean
+  /** The values an editable cell can take, picked from a drop-down. */
+  options?: SelectOption[]
   formatter?: string | ((value: any) => any)
   sortFn?: (a: Row, b: Row) => number
   filterFn?: (row: Row, filterValue: any) => boolean
@@ -52,7 +63,7 @@ export interface Column {
 export interface DataGridProps<T extends Row = Row> {
   id?: string
   type: string
-  data: T[]
+  rows: T[]
   columns: Column[]
   sorts: { column: string; direction: "asc" | "desc" }[]
   filters: Record<string, any>
@@ -65,6 +76,20 @@ export interface DataGridProps<T extends Row = Row> {
   pagination?: { page: number; pageSize: number; pageSizes: number[] } | null
   rowId?: string
   isMultiSelect: boolean
+  /**
+   * The user's unsaved edits, by row key and column id, shown over the rows
+   * until saved. Sorting, filtering and search go by the saved values.
+   */
+  edits?: Record<string | number, Record<string, any>>
+  /** The label of the button that saves the edits. Defaults to "Save changes". */
+  saveLabel?: string
+  onCellChange?: (payload: {
+    rowId: string | number
+    columnId: string
+    value: any
+  }) => void
+  onEditsReset?: () => void
+  onEditsSave?: () => void
   onSortChange?: (columnId: string) => void
   onFilterChange?: (payload: { columnId: string; value: any }) => void
   onSearchChange?: (value: string) => void
@@ -122,6 +147,15 @@ export type DataGridType = {
   rowsToggleAll(entity: DataGridProps): void
   rowsSelectAll(entity: DataGridProps): void
   selectionClear(entity: DataGridProps): void
+  /** Records an edit of a cell; an edit back to the saved value drops it. */
+  cellChange(
+    entity: DataGridProps,
+    payload: { rowId: string | number; columnId: string; value: any },
+  ): void
+  /** Drops every unsaved edit. */
+  editsReset(entity: DataGridProps): void
+  /** Writes the unsaved edits into the rows. */
+  editsSave(entity: DataGridProps): void
   virtualMount(entity: DataGridProps, containerEl: HTMLElement): void
   virtualScroll(entity: DataGridProps, containerEl: HTMLElement): void
   render(entity: DataGridProps, api: Api): TemplateResult
@@ -141,9 +175,15 @@ export type DataGridType = {
   ): TemplateResult
   renderCell(
     entity: DataGridProps,
-    payload: { cell: any; index: number },
+    payload: { cell: any; index: number; row?: Row },
     api: Api,
   ): TemplateResult
+  renderEditor(
+    entity: DataGridProps,
+    payload: { value: any; column: Column; row: Row; index: number },
+    api: Api,
+  ): TemplateResult
+  renderEdits(entity: DataGridProps, editCount: number): TemplateResult
   renderValue(
     entity: DataGridProps,
     payload: { value: any; column: Column; index: number },
@@ -181,3 +221,21 @@ export declare function getSortDirection(
 ): "asc" | "desc" | null
 export declare function isAllSelected(entity: DataGridProps): boolean
 export declare function isSomeSelected(entity: DataGridProps): boolean
+/** A cell's value as shown: its unsaved edit, or the row's own. */
+export declare function getCellValue(
+  entity: DataGridProps,
+  row: Row,
+  columnId: string,
+): any
+/** Whether a cell has an unsaved edit. */
+export declare function isCellEdited(
+  entity: DataGridProps,
+  row: Row,
+  columnId: string,
+): boolean
+/** How many cells have unsaved edits. */
+export declare function getEditCount(entity: DataGridProps): number
+/** Every row with its unsaved edits applied. */
+export declare function getEditedRows<T extends Row = Row>(
+  entity: DataGridProps<T>,
+): T[]