@inglorious/ui 9.1.1 → 9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "9.1.1",
+  "version": "9.3.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.0",
     "@inglorious/eslint-config": "1.2.0",
     "@inglorious/store": "12.0.0",
     "@inglorious/vite-plugin-jsx": "2.0.5",

package/src/controls/checkbox/checkbox.stories.js

@@ -12,6 +12,12 @@ export default {
       description: "A line of detail under the label.",
     },
     name: { control: "text", description: "Native HTML name attribute." },
+    variant: {
+      control: "select",
+      options: ["default", "card"],
+      description:
+        "`card` draws the checkbox as a card, outlined while checked.",
+    },
     isChecked: { control: "boolean", description: "Current checked state." },
     isDisabled: { control: "boolean", description: "Disables interaction." },
     isRequired: { control: "boolean", description: "Marks input as required." },
@@ -60,3 +66,13 @@ WithDescription.args = {
   name: "summary",
   description: "An email every Monday with last week's totals.",
 }
+
+export const Card = {}
+Card.args = {
+  ...Default.args,
+  label: "Breakfast",
+  name: "breakfast",
+  description: "Served from 7 to 10, €12",
+  variant: "card",
+  isChecked: true,
+}

package/src/controls/checkbox/style.css

@@ -38,6 +38,30 @@
     font-size: var(--iw-font-size-lg);
   }
 
+  .iw-checkbox-media {
+    display: block;
+    margin-block-end: var(--iw-space-2);
+
+    img {
+      display: block;
+      max-inline-size: 100%;
+      border-radius: var(--iw-radius-sm);
+    }
+  }
+
+  &.iw-checkbox-card {
+    display: flex;
+    align-items: flex-start;
+    padding: var(--iw-space-3);
+    border: 1px solid var(--iw-color-border);
+    border-radius: var(--iw-radius-md);
+
+    &:has(:checked) {
+      border-color: var(--iw-checkbox-accent);
+      background: color-mix(in srgb, var(--iw-checkbox-accent) 8%, transparent);
+    }
+  }
+
   &.iw-checkbox-disabled {
     opacity: 0.6;
     cursor: not-allowed;

package/src/controls/checkbox/template.js

@@ -23,6 +23,8 @@ export function render(props) {
     name = "",
     label = "",
     description,
+    media,
+    variant = "default",
     isChecked = false,
     isDisabled = false,
     isRequired = false,
@@ -39,6 +41,7 @@ export function render(props) {
   const classes = {
     "iw-checkbox": true,
     "iw-checkbox-disabled": isDisabled,
+    "iw-checkbox-card": variant === "card",
     [`iw-checkbox-${color}`]: color !== "primary",
     [`iw-checkbox-${size}`]: size !== "md",
   }
@@ -57,11 +60,21 @@ export function render(props) {
         ${ref((element) => applyElementProps(element, rest))}
       />
       ${when(
-        description,
+        description || media,
         () =>
           html`<span class="iw-checkbox-text">
+            ${when(
+              media,
+              () => html`<span class="iw-checkbox-media">${media}</span>`,
+            )}
             <span class="iw-checkbox-label">${label}</span>
-            <span class="iw-checkbox-description">${description}</span>
+            ${when(
+              description,
+              () =>
+                html`<span class="iw-checkbox-description"
+                  >${description}</span
+                >`,
+            )}
           </span>`,
         () => html`<span class="iw-checkbox-label">${label}</span>`,
       )}

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/controls/radio-group/radio-group.stories.js

@@ -14,6 +14,11 @@ export default {
       options: ["column", "row"],
       description: "Layout direction for options.",
     },
+    variant: {
+      control: "select",
+      options: ["default", "card"],
+      description: "`card` draws each option as a card in a grid.",
+    },
     color: {
       control: "select",
       options: ["primary", "secondary", "success", "warning", "error", "info"],
@@ -72,3 +77,17 @@ WithDescriptions.args = {
     { label: "Express", value: "express", description: "Next day, €9" },
   ],
 }
+
+export const Cards = {}
+Cards.args = {
+  ...Default.args,
+  label: "Room",
+  name: "room",
+  value: "double",
+  variant: "card",
+  options: [
+    { label: "Single", value: "single", description: "One bed, €80" },
+    { label: "Double", value: "double", description: "Two beds, €120" },
+    { label: "Suite", value: "suite", description: "With a view, €200" },
+  ],
+}

package/src/controls/radio-group/style.css

@@ -70,4 +70,34 @@
   &.iw-radio-group-info {
     --iw-radio-accent: var(--iw-color-info);
   }
+
+  /* After the directions, which it overrides with a grid. */
+  &.iw-radio-group-card {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr));
+    gap: var(--iw-space-3);
+
+    .iw-radio-option {
+      align-items: flex-start;
+      padding: var(--iw-space-3);
+      border: 1px solid var(--iw-color-border);
+      border-radius: var(--iw-radius-md);
+
+      &:has(:checked) {
+        border-color: var(--iw-radio-accent);
+        background: color-mix(in srgb, var(--iw-radio-accent) 8%, transparent);
+      }
+    }
+  }
+
+  .iw-radio-media {
+    display: block;
+    margin-block-end: var(--iw-space-2);
+
+    img {
+      display: block;
+      max-inline-size: 100%;
+      border-radius: var(--iw-radius-sm);
+    }
+  }
 }

package/src/controls/radio-group/template.js

@@ -25,6 +25,7 @@ export function render(props) {
     value,
     options = [],
     direction = "column",
+    variant = "default",
     color = "primary",
     isDisabled = false,
     onChange,
@@ -38,6 +39,7 @@ export function render(props) {
   const rootClasses = {
     "iw-radio-group": true,
     [`iw-radio-group-${direction}`]: true,
+    "iw-radio-group-card": variant === "card",
     [`iw-radio-group-${color}`]: color !== "primary",
     "iw-radio-group-disabled": isDisabled,
   }
@@ -56,6 +58,7 @@ export function render(props) {
         const {
           label: optionLabel,
           description: optionDescription,
+          media,
           value: optionValue,
           isDisabled: optionDisabled = false,
           ...optionRest
@@ -75,11 +78,21 @@ export function render(props) {
               ${ref((element) => applyElementProps(element, optionRest))}
             />
             ${when(
-              optionDescription,
+              optionDescription || media,
               () =>
                 html`<span class="iw-radio-text">
+                  ${when(
+                    media,
+                    () => html`<span class="iw-radio-media">${media}</span>`,
+                  )}
                   <span>${optionLabel}</span>
-                  <span class="iw-radio-description">${optionDescription}</span>
+                  ${when(
+                    optionDescription,
+                    () =>
+                      html`<span class="iw-radio-description"
+                        >${optionDescription}</span
+                      >`,
+                  )}
                 </span>`,
               () => html`<span>${optionLabel}</span>`,
             )}

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

@@ -10,6 +10,10 @@ export default {
   render: createRender(Chip),
   argTypes: {
     children: { control: "text", description: "Chip label content." },
+    isSelected: {
+      control: "boolean",
+      description: "Makes the chip a toggle button, pressed while true.",
+    },
     icon: {
       control: false,
       description: "Shown before the label, such as an `Icon.render(...)`.",
@@ -72,3 +76,12 @@ export const WithIcon = {
     color: "success",
   },
 }
+
+export const Selectable = {
+  args: {
+    ...Default.args,
+    children: "Vegan",
+    isRemovable: false,
+    isSelected: true,
+  },
+}

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

@@ -64,6 +64,28 @@
     border-radius: var(--iw-radius-none);
   }
 
+  &.iw-chip-selectable {
+    border: 1px solid var(--iw-color-border);
+    font: inherit;
+    font-size: var(--iw-font-size-sm);
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: 2px solid var(--iw-color-primary);
+      outline-offset: 2px;
+    }
+
+    &:disabled {
+      opacity: 0.6;
+      cursor: not-allowed;
+    }
+  }
+
+  &.iw-chip-selected {
+    border-color: var(--iw-color-primary);
+    background: color-mix(in srgb, var(--iw-color-primary) 20%, transparent);
+  }
+
   &.iw-chip-primary {
     background: color-mix(in srgb, var(--iw-color-primary) 20%, transparent);
   }

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

@@ -21,6 +21,8 @@ export function render(props) {
     color = "default",
     size = "md",
     shape = "pill",
+    isSelected,
+    isDisabled = false,
     onClick,
   } = props
 
@@ -31,9 +33,30 @@ export function render(props) {
     [`iw-chip-shape-${shape}`]: shape !== "pill",
   }
 
+  const content = html`${when(
+      icon,
+      () => html`<span class="iw-chip-icon" aria-hidden="true">${icon}</span>`,
+    )} <span class="iw-chip-label">${children}</span>`
+
+  // A chip that can be picked is a toggle button, pressed while selected.
+  if (isSelected !== undefined) {
+    return html`<button
+      type="button"
+      class=${classMap({
+        ...classes,
+        "iw-chip-selectable": true,
+        "iw-chip-selected": isSelected,
+      })}
+      aria-pressed=${String(isSelected)}
+      ?disabled=${isDisabled}
+      @click=${onClick}
+    >
+      ${content}
+    </button>`
+  }
+
   return html`<span class=${classMap(classes)}>
-    ${when(icon, () => html`<span class="iw-chip-icon" aria-hidden="true">${icon}</span>`)}
-    <span class="iw-chip-label">${children}</span>
+    ${content}
     ${when(
       isRemovable,
       () =>

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

@@ -48,6 +48,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/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 (Object.is(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
 

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,7 @@ const DIVISOR = 2
 const PRETTY_PAGE = 1
 const FIRST_PAGE = 0
 const LAST_PAGE = 1
+const ONE_EDIT = 1
 
 export const DataGrid = {
   /**
@@ -67,7 +73,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 +114,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 +234,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 +248,87 @@ 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 isNumber = column.type === "number"
+    return Input.render({
+      size: "sm",
+      ariaLabel: column.title,
+      inputType: isNumber ? "number" : column.type === "date" ? "date" : "text",
+      value: value == null ? "" : String(value),
+      isFullWidth: true,
+      onChange: (text) =>
+        change(isNumber ? (text === "" ? null : Number(text)) : text),
+    })
+  },
+
   /**
    * Renders the raw cell value for a column.
    * Override to format values or inject custom content.
@@ -274,22 +349,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>`
   },

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/checkbox.d.ts

@@ -6,6 +6,10 @@ export interface CheckboxProps {
   label?: string
   /** A line of detail under the label. */
   description?: string
+  /** Shown above the label, such as an icon or an image. */
+  media?: TemplateResult
+  /** `"card"` draws the checkbox as a card, outlined while checked. */
+  variant?: "default" | "card"
   isChecked?: boolean
   isDisabled?: boolean
   isRequired?: boolean

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/controls/radio-group.d.ts

@@ -4,6 +4,8 @@ export interface RadioOption {
   label: string
   /** A line of detail under the label. */
   description?: string
+  /** Shown above the label, such as an icon or an image. */
+  media?: TemplateResult
   value: string
   isDisabled?: boolean
   [key: string]: unknown
@@ -16,6 +18,8 @@ export interface RadioGroupProps {
   value?: string
   options?: RadioOption[]
   direction?: "column" | "row"
+  /** `"card"` draws each option as a card in a grid, outlined while checked. */
+  variant?: "default" | "card"
   color?: "primary" | "secondary" | "success" | "warning" | "error" | "info"
   isDisabled?: boolean
   onChange?: (value: string) => void

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

@@ -16,6 +16,13 @@ export interface ChipProps {
     | "info"
   size?: "sm" | "md" | "lg"
   shape?: "pill" | "rounded" | "square"
+  /**
+   * Makes the chip a toggle button, pressed while true, for picking options:
+   * `onClick` toggles it. Left out, the chip is a plain label.
+   */
+  isSelected?: boolean
+  /** Only for a chip with `isSelected`. */
+  isDisabled?: boolean
   onClick?: () => void
   [key: string]: unknown
 }

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

@@ -42,6 +42,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 +59,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 +72,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 +143,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 +171,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 +217,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[]