@dataverse-kit/grid-kit 0.1.0

package/dist/index.esm.js

@@ -0,0 +1,2783 @@
+import { formatDateTime, formatDate, formatNumber, formatCurrency, exportToFile, generateDefaultFilename } from '@khester/dynamics-utils';
+export { getContrastColor, normalizeHexColor } from '@khester/dynamics-utils';
+import { EditableTextCell, TextCell, LinkCell, EditableLookupCell, LookupCell, EditableOptionSetCell, OptionSetCell, EditableNumberCell, CurrencyCell, NumberCell, EditableDateCell, DateCell, ToggleCell, IconCell, ProgressBarCell, ColoredCell, EditableRatingCell, RatingCell, CompositeCell, getDetailsListStyles } from '@khester/dynamics-cell-renderers';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React, { useState, useRef, useCallback, useEffect, useMemo } from 'react';
+import { Callout, DirectionalHint, Dialog, DialogType, Text, Separator, ChoiceGroup, Checkbox, TextField, DialogFooter, PrimaryButton, DefaultButton, ContextualMenu, Stack, CommandBar, SearchBox, Panel, PanelType, IconButton, Dropdown, DatePicker, Selection, ShimmeredDetailsList, DetailsListLayoutMode, SelectionMode, mergeStyles, Spinner, ActionButton, Icon } from '@fluentui/react';
+
+/**
+ * Framework-agnostic value coercion. No React / no Fluent imports (enforced by
+ * the package ESLint guard on src/core/**).
+ */
+function toNumber(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function toBool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    const s = String(value).toLowerCase();
+    return s === 'true' || s === '1' || s === 'yes';
+}
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (value === null || value === undefined || value === '')
+        return null;
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+function toDisplayString(value) {
+    return value !== null && value !== undefined ? String(value) : '';
+}
+
+/**
+ * Framework-agnostic threshold resolution (progress / KPI coloring).
+ */
+/**
+ * Resolve a value to a threshold level.
+ * - `direction: 'desc'` (default): lower is worse (e.g. completion %).
+ * - `direction: 'asc'`: higher is worse (e.g. error count).
+ */
+function resolveThreshold(value, thresholds, direction = 'desc') {
+    if (!thresholds)
+        return 'ok';
+    const { warning, danger } = thresholds;
+    if (direction === 'desc') {
+        if (danger !== undefined && value <= danger)
+            return 'danger';
+        if (warning !== undefined && value <= warning)
+            return 'warning';
+    }
+    else {
+        if (danger !== undefined && value >= danger)
+            return 'danger';
+        if (warning !== undefined && value >= warning)
+            return 'warning';
+    }
+    return 'ok';
+}
+
+/**
+ * Framework-agnostic cell-color resolution. Wraps (does not reimplement)
+ * @khester/dynamics-utils contrast + hex helpers.
+ */
+/** Resolve the background color for a cell value, or undefined for none. */
+function resolveCellColor(value, res) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (res.getBackgroundColor)
+        return res.getBackgroundColor(value);
+    if (res.colorMap) {
+        const key = typeof value === 'number' ? value : String(value);
+        return res.colorMap[key];
+    }
+    return undefined;
+}
+
+/**
+ * Framework-agnostic display-value formatting. Wraps @khester/dynamics-utils.
+ *
+ * This produces the FALLBACK `formattedValue` only — adapters prefer a
+ * host-supplied value (e.g. Dataverse `@OData…FormattedValue`) when present and
+ * never recompute over it.
+ */
+/** Compute a fallback display string for a value given its renderer type. */
+function computeFormattedValue(value, rendererType, config = {}) {
+    if (value === null || value === undefined || value === '')
+        return '';
+    const { currencyCode = 'USD', locale = 'en-US', dateOptions } = config;
+    switch (rendererType) {
+        case 'currency': {
+            const n = toNumber(value);
+            return n === null ? toDisplayString(value) : formatCurrency(n, currencyCode, locale);
+        }
+        case 'number': {
+            const n = toNumber(value);
+            return n === null ? toDisplayString(value) : formatNumber(n, locale);
+        }
+        case 'date':
+            return formatDate(String(value), locale, dateOptions);
+        case 'datetime':
+            return formatDateTime(String(value), locale);
+        default:
+            return toDisplayString(value);
+    }
+}
+
+/**
+ * Framework-agnostic footer aggregates. No React / no Fluent imports (enforced by
+ * the package ESLint guard on src/core/**). Used by the host footer renderers.
+ */
+/**
+ * Compute one aggregate over a column's values.
+ * - `count` counts ALL rows (including null/empty values).
+ * - `sum`/`avg`/`min`/`max` consider only numeric-coercible values; over an empty
+ *   numeric set they return `null` (so a footer renders blank, never NaN/Infinity).
+ * Implemented with a single pass (no `Math.min(...nums)` spread, which blows the
+ * argument limit on large grids).
+ */
+function computeAggregate(items, fieldName, fn) {
+    if (fn === 'count')
+        return items.length;
+    let count = 0;
+    let sum = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const item of items) {
+        const n = toNumber(item?.[fieldName]);
+        if (n === null)
+            continue;
+        count++;
+        sum += n;
+        if (n < min)
+            min = n;
+        if (n > max)
+            max = n;
+    }
+    if (count === 0)
+        return null;
+    switch (fn) {
+        case 'sum':
+            return sum;
+        case 'avg':
+            return sum / count;
+        case 'min':
+            return min;
+        case 'max':
+            return max;
+        default:
+            return null;
+    }
+}
+/** Compute aggregates for every column that declared one → `{ fieldName: { fn, value } }`. */
+function computeAggregates(items, columns) {
+    const out = {};
+    for (const col of columns) {
+        if (col.aggregate) {
+            out[col.fieldName] = { fn: col.aggregate, value: computeAggregate(items, col.fieldName, col.aggregate) };
+        }
+    }
+    return out;
+}
+/**
+ * Per-group aggregates over a contiguous, group-ordered item array. `ranges` are
+ * `{ key, startIndex, count }` (the buckets from `buildGroups`); each group's
+ * rows are `orderedItems.slice(startIndex, startIndex + count)`. Returns
+ * `{ [groupKey]: { [fieldName]: { fn, value } } }`. Pure (no Fluent types) so it
+ * stays in framework-agnostic core and is unit-testable.
+ */
+function computeGroupAggregates(orderedItems, ranges, columns) {
+    const out = {};
+    for (const r of ranges) {
+        out[r.key] = computeAggregates(orderedItems.slice(r.startIndex, r.startIndex + r.count), columns);
+    }
+    return out;
+}
+
+/**
+ * Framework-agnostic filter model + predicate engine. No React / no Fluent
+ * imports (enforced by the package ESLint guard on src/core/**).
+ *
+ * The operator vocabulary uses FetchXML names (`eq`/`like`/`begins-with`/…) so a
+ * consumer can map a `GridFilterModel` onto a server-side FetchXML / OData query
+ * (e.g. `@dataverse-kit/runtime`) 1:1 — grid-kit applies it client-side here.
+ */
+const NO_VALUE_OPS = new Set(['null', 'not-null']);
+const MULTI_VALUE_OPS = new Set(['in', 'not-in']);
+/** Whether `operator` needs an operand value (false for `null`/`not-null`). */
+function operatorRequiresValue(operator) {
+    return !NO_VALUE_OPS.has(operator);
+}
+/** Whether `operator` takes a list of values (`in`/`not-in`). */
+function operatorIsMultiValue(operator) {
+    return MULTI_VALUE_OPS.has(operator);
+}
+/** A condition is applied only when fully specified (gates incomplete rows out). */
+function isConditionComplete(c) {
+    if (!c.fieldName || !c.operator)
+        return false;
+    if (!operatorRequiresValue(c.operator))
+        return true;
+    if (operatorIsMultiValue(c.operator))
+        return Array.isArray(c.values) && c.values.length > 0;
+    return c.value !== undefined && c.value !== null && c.value !== '';
+}
+const isEmpty = (v) => v === null || v === undefined || v === '';
+const asText = (v) => toDisplayString(v).toLowerCase();
+/**
+ * Compare raw vs operand numerically, else by date. `undefined` ⇒ not comparable.
+ * Number-first is deliberate: a bare-year operand like `"2024"` compares as the
+ * number 2024 (the date editor always emits a full `YYYY-MM-DD`, never a bare year).
+ */
+function compare(raw, operand) {
+    const a = toNumber(raw);
+    const b = toNumber(operand);
+    if (a !== null && b !== null)
+        return a === b ? 0 : a < b ? -1 : 1;
+    const da = toDate(raw);
+    const db = toDate(operand);
+    if (da && db) {
+        // Compare at UTC calendar-day granularity — the filter UI picks a day, not an
+        // instant — so a date-only operand matches a stored datetime on the same day
+        // and the result is timezone-stable (no off-by-one across the date line).
+        const ta = Date.UTC(da.getUTCFullYear(), da.getUTCMonth(), da.getUTCDate());
+        const tb = Date.UTC(db.getUTCFullYear(), db.getUTCMonth(), db.getUTCDate());
+        return ta === tb ? 0 : ta < tb ? -1 : 1;
+    }
+    return undefined;
+}
+/** Loose equality: numeric when both coerce to numbers, else case-insensitive text. */
+function looseEq(raw, operand) {
+    const a = toNumber(raw);
+    const b = toNumber(operand);
+    if (a !== null && b !== null)
+        return a === b;
+    return asText(raw) === operand.trim().toLowerCase();
+}
+/**
+ * Equality used by `eq`/`ne`/`in`/`not-in`. Boolean operands (`'true'`/`'false'`
+ * from the Yes/No editor) compare via `toBool`, so a row stored as a JS boolean,
+ * `1`/`0`, or `'1'`/`'0'` (a Dataverse bit field) all match. Otherwise: text/numeric
+ * loose-equality, then a date/number `compare` so a `Date` (or date-string) still
+ * matches by calendar day — without this, `eq` on a date column never matched.
+ */
+function valuesEqual(raw, operand) {
+    if (operand === 'true' || operand === 'false')
+        return toBool(raw) === (operand === 'true');
+    if (looseEq(raw, operand))
+        return true;
+    return compare(raw, operand) === 0;
+}
+/**
+ * Evaluate one condition against a raw field value. Equality/relational compares
+ * are coercion-based: when both sides parse as numbers they compare numerically
+ * (so a numeric-looking text id like `'007'` equals `'7'`), dates compare by day,
+ * else case-insensitive text. Assumes a complete condition (see
+ * `isConditionComplete`) — `applyFilters` drops incomplete ones first; calling this
+ * directly on e.g. a `not-in` with no `values` returns `true` (matches everything).
+ */
+function evalCondition(raw, c) {
+    const operand = c.value ?? '';
+    switch (c.operator) {
+        case 'null':
+            return isEmpty(raw);
+        case 'not-null':
+            return !isEmpty(raw);
+        case 'eq':
+            return valuesEqual(raw, operand);
+        case 'ne':
+            return !valuesEqual(raw, operand);
+        case 'like':
+            return asText(raw).includes(operand.toLowerCase());
+        case 'not-like':
+            return !asText(raw).includes(operand.toLowerCase());
+        case 'begins-with':
+            return asText(raw).startsWith(operand.toLowerCase());
+        case 'ends-with':
+            return asText(raw).endsWith(operand.toLowerCase());
+        case 'in':
+            return (c.values ?? []).some((v) => valuesEqual(raw, v));
+        case 'not-in':
+            return !(c.values ?? []).some((v) => valuesEqual(raw, v));
+        case 'gt': {
+            const r = compare(raw, operand);
+            return r !== undefined && r > 0;
+        }
+        case 'ge':
+        case 'on-or-after': {
+            const r = compare(raw, operand);
+            return r !== undefined && r >= 0;
+        }
+        case 'lt': {
+            const r = compare(raw, operand);
+            return r !== undefined && r < 0;
+        }
+        case 'le':
+        case 'on-or-before': {
+            const r = compare(raw, operand);
+            return r !== undefined && r <= 0;
+        }
+        default:
+            return true;
+    }
+}
+function defaultGetValue(item, fieldName) {
+    return item && typeof item === 'object' ? item[fieldName] : undefined;
+}
+/**
+ * Filter `items` by `model` (client-side, in-memory). Incomplete conditions are
+ * ignored; with no complete condition the input is returned unchanged. `match`
+ * `'all'` ⇒ every condition must pass (AND); `'any'` ⇒ at least one (OR).
+ */
+function applyFilters(items, model, getValue = defaultGetValue) {
+    if (!model)
+        return items;
+    const active = model.conditions.filter(isConditionComplete);
+    if (active.length === 0)
+        return items;
+    const matchAll = model.match !== 'any';
+    return items.filter((item) => matchAll
+        ? active.every((c) => evalCondition(getValue(item, c.fieldName), c))
+        : active.some((c) => evalCondition(getValue(item, c.fieldName), c)));
+}
+
+/** grid-kit renderer type → canonical library field type. */
+const RENDERER_TO_FIELDTYPE = {
+    text: 'text',
+    link: 'link',
+    lookup: 'lookup',
+    optionset: 'optionset',
+    currency: 'currency',
+    number: 'number',
+    date: 'date',
+    datetime: 'datetime',
+    boolean: 'toggle',
+    toggle: 'toggle',
+    icon: 'icon',
+    progress: 'progressBar',
+    coloredCell: 'coloredCell',
+    rating: 'rating',
+    composite: 'composite',
+    // 'fileDrop' is grid-kit-native (FileDropCell) and never goes through the
+    // canonical-lib wrapper, so this entry is just to satisfy the exhaustive map.
+    fileDrop: 'text',
+};
+function rendererToFieldType(type) {
+    return RENDERER_TO_FIELDTYPE[type] ?? 'text';
+}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Map a grid-kit column (renderer type + config bag) onto an IReusableColumn.
+ * `rendererConfig` keys accept both a short form (`max`, `color`) and the
+ * canonical IReusableColumn name (`progressMax`, `progressColor`).
+ */
+function toReusableColumn(column) {
+    const c = (column.rendererConfig ?? {});
+    const base = {
+        key: column.key,
+        name: column.name,
+        fieldName: column.fieldName,
+        minWidth: column.minWidth ?? 100,
+        maxWidth: column.maxWidth,
+        isResizable: column.isResizable ?? true,
+        fieldType: rendererToFieldType(column.rendererType),
+        editable: !!column.editorType && column.editorType !== 'none' && !column.isLocked,
+        onLinkClick: column.onLinkClick,
+        validate: column.validate,
+    };
+    switch (column.rendererType) {
+        case 'currency':
+            base.currencyCode = c.currencyCode;
+            base.locale = c.locale;
+            break;
+        case 'number':
+            base.locale = c.locale;
+            break;
+        case 'progress':
+            base.progressMax = c.max ?? c.progressMax;
+            base.progressColor = c.color ?? c.progressColor;
+            base.showProgressLabel = c.showLabel ?? c.showProgressLabel;
+            break;
+        case 'coloredCell':
+            base.colorMap = c.colorMap;
+            base.getBackgroundColor = c.getBackgroundColor;
+            break;
+        case 'optionset':
+            base.optionSetOptions = c.options ?? c.optionSetOptions;
+            base.colorMap = c.colorMap;
+            base.optionSetMultiSelect = c.multiSelect ?? c.optionSetMultiSelect;
+            break;
+        case 'rating':
+            base.ratingMax = c.max ?? c.ratingMax;
+            base.ratingColor = c.color ?? c.ratingColor;
+            base.ratingAllowHalf = c.allowHalf ?? c.ratingAllowHalf;
+            base.ratingStyle = c.style ?? c.ratingStyle;
+            base.ratingFaceCount = c.faceCount ?? c.ratingFaceCount;
+            base.ratingUseSentimentColor = c.useSentimentColor ?? c.ratingUseSentimentColor;
+            break;
+        case 'composite':
+            base.compositeSlots = c.slots ?? c.compositeSlots;
+            base.compositeLayout = c.layout ?? c.compositeLayout;
+            base.compositeGap = c.gap ?? c.compositeGap;
+            break;
+        case 'icon':
+            base.iconName = c.iconName;
+            base.iconTitle = c.iconTitle;
+            base.onIconClick = c.onIconClick ?? column.onLinkClick;
+            break;
+        case 'toggle':
+        case 'boolean':
+            base.toggleOnText = c.onText ?? c.toggleOnText;
+            base.toggleOffText = c.offText ?? c.toggleOffText;
+            base.onToggleChange = c.onToggleChange;
+            break;
+        case 'lookup':
+            base.lookupDisplayField = c.displayField ?? c.lookupDisplayField;
+            base.lookupEntitySetName = c.entitySetName ?? c.lookupEntitySetName;
+            base.lookupSearchField = c.searchField ?? c.lookupSearchField;
+            base.lookupTargetEntity = c.targetEntity ?? c.lookupTargetEntity;
+            base.lookupPrimaryIdAttribute = c.primaryIdAttribute ?? c.lookupPrimaryIdAttribute;
+            base.lookupFilter = c.filter ?? c.lookupFilter;
+            base.lookupSelectFields = c.selectFields ?? c.lookupSelectFields;
+            base.lookupSearch = c.searchLookup ?? c.lookupSearch;
+            break;
+        case 'link':
+            base.openInNewTab = c.openInNewTab;
+            base.isRecordLink = c.isRecordLink;
+            base.recordEntityLogicalName = c.recordEntityLogicalName;
+            break;
+    }
+    if (c.formatValue && !base.formatValue)
+        base.formatValue = c.formatValue;
+    return base;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+const noop = () => undefined;
+/** Ensure the row exposes a `.key` (some canonical editable cells require it). */
+function ensureKey(item, key) {
+    if (item && typeof item === 'object' && item.key !== undefined)
+        return item;
+    return { ...item, key };
+}
+/**
+ * Bridge the display value into the canonical renderer's `formatValue` path so
+ * read cells honor the right label instead of re-deriving from the raw code.
+ * Precedence: user-provided formatValue > host-supplied formatted value
+ * (Dataverse optionset/lookup label) > optionset value→label map > the
+ * computed fallback for numeric/date types (which also fixes numeric-string
+ * values that the canonical Currency/Number cells would otherwise render as '-').
+ * Mutates the freshly-mapped column (a new object per render — safe).
+ */
+function applyDisplayValue(column, props) {
+    if (column.formatValue)
+        return; // explicit user formatter wins
+    if (props.suppliedFormattedValue) {
+        const s = props.suppliedFormattedValue;
+        column.formatValue = () => s;
+        return;
+    }
+    switch (column.fieldType) {
+        case 'optionset': {
+            const opts = column.optionSetOptions;
+            if (opts && opts.length) {
+                column.formatValue = (v) => {
+                    const o = opts.find((opt) => String(opt.value) === String(v));
+                    return o ? o.label : v !== null && v !== undefined && v !== '' ? String(v) : '-';
+                };
+            }
+            return;
+        }
+        case 'currency':
+        case 'number':
+        case 'date':
+        case 'datetime': {
+            const fv = props.formattedValue;
+            column.formatValue = () => fv || '-';
+            return;
+        }
+        default:
+            return;
+    }
+}
+/** Read-only wrapper: maps GridCellProps → the canonical CellRendererProps. */
+function makeReadWrapper(Comp, displayName) {
+    const Wrapped = (props) => {
+        const column = toReusableColumn(props.column);
+        applyDisplayValue(column, props);
+        // Editable toggles render an interactive ToggleCell (no editable variant
+        // exists); wire its change back to the grid's onValueChange so edits persist.
+        if (column.editable && !column.onToggleChange && props.onValueChange) {
+            const onVC = props.onValueChange;
+            const original = props.value;
+            column.onToggleChange = (key, fieldName, v) => onVC(key, fieldName, v, original);
+        }
+        const cellProps = {
+            item: props.item,
+            column,
+            value: props.value,
+            itemKey: props.itemKey,
+        };
+        return jsx(Comp, { ...cellProps });
+    };
+    Wrapped.displayName = displayName;
+    return Wrapped;
+}
+/** Editable wrapper: threads edit-state onto the canonical editable cell props. */
+function makeEditWrapper(Comp, displayName) {
+    const Wrapped = (props) => {
+        const column = toReusableColumn(props.column);
+        applyDisplayValue(column, props); // read-mode display of an editable cell
+        const item = ensureKey(props.item, props.itemKey);
+        const editProps = {
+            item,
+            column,
+            value: props.value,
+            itemKey: props.itemKey,
+            isEditMode: props.isEditing ?? false,
+            isDirty: props.isDirty ?? false,
+            editedValue: props.editedValue,
+            onValueChange: props.onValueChange ?? noop,
+            errorMessage: props.errorMessage,
+            onValidationError: props.onValidationError,
+        };
+        return jsx(Comp, { ...editProps });
+    };
+    Wrapped.displayName = displayName;
+    return Wrapped;
+}
+
+function normalizeExt(ext) {
+    const e = ext.toLowerCase();
+    return e.startsWith('.') ? e : `.${e}`;
+}
+/**
+ * Whether a file name matches an accept list of extensions (case-insensitive,
+ * leading dot optional). Empty/undefined accept = anything. Exported for reuse
+ * in custom drop targets.
+ */
+function isFileAccepted(name, accept) {
+    if (!accept || accept.length === 0)
+        return true;
+    const lower = name.toLowerCase();
+    return accept.some((ext) => lower.endsWith(normalizeExt(ext)));
+}
+/**
+ * HTML5 file-drop behavior for a grid cell or row. Tracks drag depth (so the
+ * highlight doesn't flicker over child elements), validates the dropped files
+ * against `accept`, and exposes the drag-over state + the handler props to spread
+ * onto a wrapper element. Pure HTML5 — no drag library.
+ */
+function useFileDrop(opts) {
+    const { onDrop, accept, multiple = false, disabled, onReject } = opts;
+    const [isDragOver, setIsDragOver] = useState(false);
+    const depth = useRef(0);
+    const onDragEnter = useCallback((e) => {
+        if (disabled)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        depth.current += 1;
+        setIsDragOver(true);
+    }, [disabled]);
+    const onDragOver = useCallback((e) => {
+        if (disabled)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        e.dataTransfer.dropEffect = 'copy';
+    }, [disabled]);
+    const onDragLeave = useCallback((e) => {
+        if (disabled)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        depth.current = Math.max(0, depth.current - 1);
+        if (depth.current === 0)
+            setIsDragOver(false);
+    }, [disabled]);
+    const onDropHandler = useCallback((e) => {
+        if (disabled)
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        depth.current = 0;
+        setIsDragOver(false);
+        const all = Array.from(e.dataTransfer.files ?? []);
+        if (all.length === 0)
+            return;
+        const valid = all.filter((f) => isFileAccepted(f.name, accept));
+        if (valid.length === 0) {
+            onReject?.(accept && accept.length ? `Only ${accept.join(', ')} files are allowed.` : 'File not allowed.');
+            return;
+        }
+        onDrop(multiple ? valid : [valid[0]]);
+    }, [disabled, accept, multiple, onDrop, onReject]);
+    return {
+        isDragOver,
+        dragProps: { onDragEnter, onDragOver, onDragLeave, onDrop: onDropHandler },
+    };
+}
+
+/**
+ * Wraps any content as an HTML5 file-drop target with a drag-over highlight.
+ * Use inside a custom cell renderer (or directly) to accept files dropped from
+ * the OS onto a cell. The `fileDrop` registry cell type uses this internally.
+ */
+const DroppableCell = ({ children, className, style, variant = 'highlight', ...opts }) => {
+    const { isDragOver, dragProps } = useFileDrop(opts);
+    const active = isDragOver && !opts.disabled;
+    return (jsx("div", { ...dragProps, className: className, style: {
+            display: 'flex',
+            alignItems: 'center',
+            height: '100%',
+            width: '100%',
+            borderRadius: 4,
+            outline: active && variant === 'highlight' ? '2px solid #0078d4' : '2px solid transparent',
+            background: active ? 'rgba(0,120,212,0.08)' : 'transparent',
+            boxShadow: active && variant === 'highlight' ? '0 0 6px 1px rgba(0,120,212,0.4)' : 'none',
+            transition: 'background 80ms ease-out, box-shadow 80ms ease-out, outline-color 80ms ease-out',
+            ...style,
+        }, children: children }));
+};
+
+/**
+ * Grid-kit-native cell renderer for `rendererType: 'fileDrop'`. Renders the cell
+ * as a droppable target; on drop it calls `rendererConfig.onDrop(files, item,
+ * fieldName)`. Unlike the other built-ins it does NOT wrap a canonical renderer.
+ */
+const FileDropCell = (props) => {
+    const cfg = (props.column.rendererConfig ?? {});
+    const field = props.column.fieldName;
+    // Explicit label wins; else show the cell's value; else the drop hint.
+    // (formattedValue is '' — not undefined — when the value is empty, so use `||`.)
+    const text = cfg.label ?? (props.formattedValue || 'Drop file');
+    return (jsx(DroppableCell, { accept: cfg.accept, multiple: cfg.multiple, onDrop: (files) => cfg.onDrop?.(files, props.item, field), onReject: cfg.onReject ? (reason) => cfg.onReject(reason, props.item, field) : undefined, style: { justifyContent: 'center', cursor: 'copy', fontSize: 13, color: '#605e5c' }, children: jsx("span", { children: text }) }));
+};
+
+/**
+ * The cell-renderer registry — the single source of truth that both grid hosts
+ * (DetailsList adapter + GridCustomizer overrides) consume. Maps each
+ * `CellRendererType` to a read (and optional edit) wrapper over the canonical
+ * @khester/dynamics-cell-renderers components.
+ */
+function buildDefaults() {
+    const m = new Map();
+    m.set('text', {
+        read: makeReadWrapper(TextCell, 'GridKit(text)'),
+        edit: makeEditWrapper(EditableTextCell, 'GridKit(edit:text)'),
+    });
+    m.set('link', { read: makeReadWrapper(LinkCell, 'GridKit(link)') });
+    // Editable lookup is fetch-free: the consumer supplies `searchLookup(term)` on
+    // the column's rendererConfig (mapped to `column.lookupSearch`), so the cell
+    // never needs an apiService. A column opts in with editorType:'lookup'.
+    m.set('lookup', {
+        read: makeReadWrapper(LookupCell, 'GridKit(lookup)'),
+        edit: makeEditWrapper(EditableLookupCell, 'GridKit(edit:lookup)'),
+    });
+    m.set('optionset', {
+        read: makeReadWrapper(OptionSetCell, 'GridKit(optionset)'),
+        edit: makeEditWrapper(EditableOptionSetCell, 'GridKit(edit:optionset)'),
+    });
+    m.set('currency', {
+        read: makeReadWrapper(CurrencyCell, 'GridKit(currency)'),
+        edit: makeEditWrapper(EditableNumberCell, 'GridKit(edit:currency)'),
+    });
+    m.set('number', {
+        read: makeReadWrapper(NumberCell, 'GridKit(number)'),
+        edit: makeEditWrapper(EditableNumberCell, 'GridKit(edit:number)'),
+    });
+    m.set('date', {
+        read: makeReadWrapper(DateCell, 'GridKit(date)'),
+        edit: makeEditWrapper(EditableDateCell, 'GridKit(edit:date)'),
+    });
+    m.set('datetime', {
+        read: makeReadWrapper(DateCell, 'GridKit(datetime)'),
+        edit: makeEditWrapper(EditableDateCell, 'GridKit(edit:datetime)'),
+    });
+    m.set('boolean', { read: makeReadWrapper(ToggleCell, 'GridKit(boolean)') });
+    m.set('toggle', { read: makeReadWrapper(ToggleCell, 'GridKit(toggle)') });
+    m.set('icon', { read: makeReadWrapper(IconCell, 'GridKit(icon)') });
+    m.set('progress', { read: makeReadWrapper(ProgressBarCell, 'GridKit(progress)') });
+    m.set('coloredCell', { read: makeReadWrapper(ColoredCell, 'GridKit(coloredCell)') });
+    // Rating is click-to-set editable (stars or sentiment emoji). Opt in with
+    // editorType:'number'; rendererConfig.style:'emoji' switches to faces.
+    m.set('rating', {
+        read: makeReadWrapper(RatingCell, 'GridKit(rating)'),
+        edit: makeEditWrapper(EditableRatingCell, 'GridKit(edit:rating)'),
+    });
+    m.set('composite', { read: makeReadWrapper(CompositeCell, 'GridKit(composite)') });
+    // grid-kit-native (not a canonical-lib wrapper): a per-cell file-drop target.
+    m.set('fileDrop', { read: FileDropCell });
+    return m;
+}
+/**
+ * Create a cell-renderer registry with all built-ins, optionally overridden.
+ * Consumers can also call `registry.register(type, { read, edit })` later to
+ * override a built-in or add a brand-new cell type.
+ */
+function createCellRegistry(overrides) {
+    const map = buildDefaults();
+    if (overrides) {
+        for (const [key, reg] of Object.entries(overrides))
+            map.set(key, reg);
+    }
+    const registry = {
+        get: (type) => map.get(type),
+        register: (type, reg) => {
+            map.set(type, reg);
+        },
+        resolve: (column, editable) => {
+            const reg = map.get(column.rendererType);
+            if (!reg) {
+                // Unknown renderer type → safe text fallback (no silent blank cells).
+                // Read 'text' live so a consumer's register('text', …) override is honored.
+                // eslint-disable-next-line no-console
+                if (typeof console !== 'undefined') {
+                    console.warn(`[grid-kit] No renderer registered for "${column.rendererType}"; using text.`);
+                }
+                return map.get('text').read;
+            }
+            const canEdit = editable &&
+                !!column.editorType &&
+                column.editorType !== 'none' &&
+                !column.isLocked &&
+                !!reg.edit;
+            return (canEdit ? reg.edit : reg.read);
+        },
+    };
+    return registry;
+}
+
+/**
+ * `Xrm.Navigation.navigateTo` wrapper — open a record form, web resource, or
+ * custom page from a grid. Loose-typed (NO `@types/xrm` dependency). On localhost
+ * or when Xrm is unavailable (Storybook / tests / non-model-driven host) it logs a
+ * no-op and resolves, so consumers can wire navigation unconditionally.
+ *
+ * Lives OUTSIDE src/core/ on purpose: it touches `window`/`Xrm` (a side-effectful
+ * host concern), whereas core/ is v9-portable pure logic.
+ */
+function getXrm() {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.Xrm;
+}
+/** Mirror the ServiceFactory localhost check used across the kit. */
+function isLocalhost() {
+    if (typeof window === 'undefined' || !window.location)
+        return false;
+    const h = window.location.hostname;
+    return h === 'localhost' || h === '127.0.0.1';
+}
+/** Map a `NavTarget` → an Xrm `pageInput` object. */
+function toPageInput(target) {
+    switch (target.pageType) {
+        case 'entityrecord':
+            return { pageType: 'entityrecord', entityName: target.entityName, entityId: target.entityId };
+        case 'webresource':
+            return { pageType: 'webresource', webresourceName: target.webresourceName, data: target.data };
+        case 'custom':
+            return { pageType: 'custom', name: target.name, entityName: target.entityName, recordId: target.entityId };
+        default:
+            return {};
+    }
+}
+/**
+ * Navigate to `target` via `Xrm.Navigation.navigateTo`. No-ops (console.log) on
+ * localhost or when Xrm is unavailable. Always resolves (never throws) so a
+ * cell-click handler can call it without a try/catch.
+ *
+ * The options the platform receives are the explicit `navigationOptions` arg if
+ * given, else `target.navigationOptions` — so callers that only have a
+ * `NavTarget` (cell-click synthesis, the "Open" command) still get dialog/size
+ * control by attaching options to the target.
+ */
+async function navigateToTarget(target, navigationOptions) {
+    const xrm = getXrm();
+    const options = navigationOptions ?? target.navigationOptions;
+    if (isLocalhost() || !xrm?.Navigation?.navigateTo) {
+        // eslint-disable-next-line no-console
+        if (typeof console !== 'undefined') {
+            console.log('[grid-kit] navigateTo (no-op — localhost or no Xrm):', target, options);
+        }
+        return;
+    }
+    try {
+        await xrm.Navigation.navigateTo(toPageInput(target), options);
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        if (typeof console !== 'undefined')
+            console.error('[grid-kit] navigateTo failed:', err);
+    }
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Read a row field value. */
+function getFieldValue(item, fieldName) {
+    return item && typeof item === 'object' ? item[fieldName] : undefined;
+}
+/**
+ * Host-supplied formatted value (Dataverse `@OData…FormattedValue` sibling key),
+ * if present. Adapters prefer this over recomputing.
+ */
+function getSuppliedFormattedValue(item, fieldName) {
+    if (!item || typeof item !== 'object')
+        return undefined;
+    const fv = item[`${fieldName}@OData.Community.Display.V1.FormattedValue`];
+    return fv !== undefined && fv !== null ? String(fv) : undefined;
+}
+// Stable synthetic keys for rows that lack a `key` — keeps edit-state per-row
+// instead of collapsing every keyless row to '' (which caused cross-row edit
+// bleed). Same object identity ⇒ same key across renders.
+const SYNTH_KEYS = new WeakMap();
+let synthCounter = 0;
+let warnedMissingKey = false;
+function defaultGetKey(item) {
+    const k = item?.key;
+    if (k !== undefined && k !== null && k !== '')
+        return String(k);
+    if (item && typeof item === 'object') {
+        let s = SYNTH_KEYS.get(item);
+        if (!s) {
+            s = '__gridkit_row_' + ++synthCounter;
+            SYNTH_KEYS.set(item, s);
+            if (!warnedMissingKey && typeof console !== 'undefined') {
+                warnedMissingKey = true;
+                console.warn('[grid-kit] Rows are missing a `key`; using synthetic keys. Pass `getKey` or give each row a stable `key` for reliable selection/editing.');
+            }
+        }
+        return s;
+    }
+    return String(k ?? '');
+}
+function rendererFormatConfig(column) {
+    const c = (column.rendererConfig ?? {});
+    return { currencyCode: c.currencyCode, locale: c.locale };
+}
+/** Build the normalized cell contract for one (column, row) pair. */
+function buildCellProps(column, item, ctx) {
+    const getKey = ctx.getKey ?? defaultGetKey;
+    const itemKey = getKey(item);
+    const value = getFieldValue(item, column.fieldName);
+    // Navigation: for link/lookup cells with no explicit onLinkClick, synthesize one
+    // from the grid-level `navigateTo` resolver. Done here (the seam both host
+    // adapters share) so DetailsList + GridCustomizer get nav parity for free.
+    let effectiveColumn = column;
+    if (ctx.navigateTo &&
+        !column.onLinkClick &&
+        (column.rendererType === 'link' || column.rendererType === 'lookup')) {
+        const resolve = ctx.navigateTo;
+        effectiveColumn = {
+            ...column,
+            onLinkClick: (it) => {
+                const target = resolve(it);
+                if (target)
+                    void navigateToTarget(target);
+            },
+        };
+    }
+    const supplied = ctx.formattedValueAccessor
+        ? ctx.formattedValueAccessor(item, column)
+        : getSuppliedFormattedValue(item, column.fieldName);
+    const formattedValue = supplied ?? computeFormattedValue(value, column.rendererType, rendererFormatConfig(column));
+    return {
+        value,
+        formattedValue,
+        suppliedFormattedValue: supplied,
+        item,
+        itemKey,
+        column: effectiveColumn,
+        isEditing: ctx.isEditing?.(itemKey, column.fieldName) ?? false,
+        isDirty: ctx.isDirty?.(itemKey, column.fieldName) ?? false,
+        editedValue: ctx.getEditedValue?.(itemKey, column.fieldName),
+        errorMessage: ctx.getError?.(itemKey, column.fieldName),
+        onValueChange: ctx.onValueChange,
+        onValidationError: ctx.onValidationError,
+        onEditStart: ctx.onEditStart ? () => ctx.onEditStart(itemKey, column.fieldName) : undefined,
+        onEditEnd: ctx.onEditEnd ? () => ctx.onEditEnd(itemKey, column.fieldName) : undefined,
+    };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+const FOCUSABLE = 'input, textarea, select, button, [tabindex]:not([tabindex="-1"])';
+/** True when focus moved into a Fluent v8 portal (Dropdown/Calendar/Lookup
+ * option lists render in a Layer/Callout OUTSIDE the cell's DOM subtree). */
+function isInFluentPortal(node) {
+    const el = node;
+    return !!el?.closest?.('.ms-Layer, .ms-Callout');
+}
+/**
+ * Wraps an editable cell that is currently in edit mode. On mount (i.e. when the
+ * cell enters edit mode) it focuses the first focusable control, and it exits
+ * edit mode on Enter/Escape or on blur to outside — but NOT when focus moves into
+ * a Fluent portal (otherwise picking a Dropdown/Calendar/Lookup option would
+ * close the editor before the value commits).
+ */
+const EditCellWrapper = ({ onExit, children }) => {
+    const ref = useRef(null);
+    useEffect(() => {
+        ref.current?.querySelector(FOCUSABLE)?.focus();
+    }, []);
+    return (jsx("div", { ref: ref, style: { height: '100%' }, onKeyDown: (e) => {
+            if (e.key === 'Enter' || e.key === 'Escape')
+                onExit();
+        }, onBlur: (e) => {
+            const next = e.relatedTarget;
+            if (isInFluentPortal(next))
+                return; // selecting a portal option, not exiting
+            if (!e.currentTarget.contains(next))
+                onExit();
+        }, children: children }));
+};
+
+/**
+ * Wraps a cell in a hover-triggered Fluent v8 `Callout` showing preview content
+ * (e.g. a lookup's related-record fields). Consumed by `toDetailsListColumns` for
+ * any `ColumnDef` that declares `calloutContent` — the host wiring that the
+ * `ColumnDef.calloutContent`/`dismissMode`/`timeoutDuration` contract was always
+ * meant to drive (it was previously declared-but-unconsumed).
+ */
+function CalloutCell({ children, renderContent, dismissMode = 'mouseleave', timeoutDuration = 200, }) {
+    const [open, setOpen] = useState(false);
+    const anchorRef = useRef(null);
+    const timer = useRef(null);
+    const clearTimer = useCallback(() => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+    }, []);
+    // Clear any pending dismiss timer on unmount (cells unmount on scroll in a
+    // virtualized DetailsList) so a stale callback can't setState after unmount.
+    useEffect(() => clearTimer, [clearTimer]);
+    const onEnter = useCallback(() => {
+        clearTimer();
+        setOpen(true);
+    }, [clearTimer]);
+    const onLeave = useCallback(() => {
+        if (dismissMode === 'timeout') {
+            clearTimer();
+            timer.current = setTimeout(() => setOpen(false), timeoutDuration);
+        }
+        else {
+            setOpen(false);
+        }
+    }, [clearTimer, dismissMode, timeoutDuration]);
+    // Keep the callout open while the pointer is over its content (timeout mode only).
+    const calloutHover = dismissMode === 'timeout' ? { onMouseEnter: clearTimer, onMouseLeave: onLeave } : {};
+    return (jsxs("span", { ref: anchorRef, onMouseEnter: onEnter, onMouseLeave: onLeave, style: { display: 'inline-block', width: '100%' }, children: [children, open && anchorRef.current && (jsx(Callout, { target: anchorRef.current, directionalHint: DirectionalHint.bottomLeftEdge, isBeakVisible: false, gapSpace: 0, onDismiss: () => setOpen(false), ...calloutHover, children: jsx("div", { style: { padding: 12, maxWidth: 320 }, children: renderContent() }) }))] }));
+}
+
+/** Wrap a rendered cell in a hover-preview callout when the column declares `calloutContent`. */
+function withCallout(column, item, rendered) {
+    if (!column.calloutContent)
+        return rendered;
+    return (jsx(CalloutCell, { renderContent: () => column.calloutContent(item), dismissMode: column.dismissMode, timeoutDuration: column.timeoutDuration, children: rendered }));
+}
+function toDetailsListColumns(columns, ctx) {
+    return columns.map((column) => {
+        const sortable = column.isSortable && !!ctx.onSortChange;
+        return {
+            key: column.key,
+            name: column.name,
+            fieldName: column.fieldName,
+            minWidth: column.minWidth ?? 100,
+            maxWidth: column.maxWidth,
+            isResizable: column.isResizable ?? true,
+            isSorted: ctx.sort?.fieldName === column.fieldName,
+            isSortedDescending: ctx.sort?.fieldName === column.fieldName && ctx.sort?.direction === 'desc',
+            columnActionsMode: sortable ? undefined : 0, // 0 = disabled when not sortable
+            onColumnClick: sortable
+                ? () => {
+                    const nextDir = ctx.sort?.fieldName === column.fieldName && ctx.sort?.direction === 'asc' ? 'desc' : 'asc';
+                    ctx.onSortChange(column.fieldName, nextDir);
+                }
+                : undefined,
+            onRender: (item) => {
+                if (item === undefined || item === null)
+                    return null;
+                // Escape hatch: fully custom render bypasses the registry.
+                if (column.onRender)
+                    return column.onRender(item);
+                const props = buildCellProps(column, item, ctx);
+                const Renderer = ctx.registry.resolve(column, !!ctx.editable);
+                const cell = jsx(Renderer, { ...props });
+                // Per-cell click-to-edit affordance: editable columns enter edit mode on
+                // click (one cell at a time) and exit on Enter/Escape/blur. Only cell
+                // types that actually have an edit renderer get the affordance — toggle/
+                // boolean are already interactive in read mode and ignore edit state.
+                // With editTrigger 'always' (or non-editable columns) the cell renders plainly.
+                const isEditableCell = !!ctx.editable &&
+                    !!column.editorType &&
+                    column.editorType !== 'none' &&
+                    !column.isLocked &&
+                    !!ctx.registry.get(column.rendererType)?.edit &&
+                    (ctx.editTrigger ?? 'click') === 'click';
+                // Resolve the cell to its rendered form (plain / editing / click-to-edit),
+                // then apply the hover-preview callout once so it composes with any path.
+                let rendered;
+                if (!isEditableCell) {
+                    rendered = cell;
+                }
+                else if (props.isEditing) {
+                    rendered = jsx(EditCellWrapper, { onExit: () => props.onEditEnd?.(), children: cell });
+                }
+                else {
+                    rendered = (jsx("div", { role: "button", tabIndex: 0, title: "Click to edit", style: { height: '100%', cursor: 'text', display: 'flex', alignItems: 'center' }, onClick: () => props.onEditStart?.(), onKeyDown: (e) => {
+                            if (e.key === 'Enter' || e.key === 'F2')
+                                props.onEditStart?.();
+                        }, children: cell }));
+                }
+                return withCallout(column, item, rendered);
+            },
+        };
+    });
+}
+
+function toGridCustomizerOverrides(columns, registry, options = {}) {
+    const overrides = {};
+    for (const column of columns) {
+        const Override = (gc) => {
+            const value = gc.value;
+            // Trust the platform's formatted value; only fall back when absent.
+            const formattedValue = gc.formattedValue ??
+                computeFormattedValue(value, column.rendererType, {
+                    currencyCode: column.rendererConfig?.currencyCode,
+                    locale: column.rendererConfig?.locale,
+                });
+            const props = {
+                value,
+                formattedValue,
+                suppliedFormattedValue: gc.formattedValue,
+                item: gc.rowData,
+                itemKey: gc.entityId,
+                column,
+                isEditing: gc.isEditing,
+                // The platform GC host owns dirty/validation state, so these are not
+                // available on this path (unlike the DetailsList host's useEditState).
+                isDirty: undefined,
+                editedValue: undefined,
+                errorMessage: undefined,
+                onValidationError: undefined,
+                // The GC host's onChange takes only the new value, so fieldName +
+                // originalValue from grid-kit's 4-arg signature are intentionally dropped.
+                onValueChange: gc.onChange ? (_rk, _fn, v) => gc.onChange(v) : undefined,
+                onEditStart: gc.onEditStart,
+                onEditEnd: gc.onEditEnd,
+            };
+            const Renderer = registry.resolve(column, !!gc.isEditing);
+            return jsx(Renderer, { ...props });
+        };
+        Override.displayName = `GcOverride(${column.fieldName})`;
+        overrides[column.fieldName] = Override;
+        if (options.keyByDataType) {
+            overrides[column.rendererType] = overrides[column.rendererType] ?? Override;
+        }
+    }
+    return overrides;
+}
+
+/**
+ * Map form-runtime's narrow `rendererType` + separate `dataType` onto grid-kit's
+ * 15-literal `CellRendererType`. form-runtime keeps the two separate (a column
+ * can be `rendererType:'text'` + `dataType:'numeric'`), so a naive 1:1 map would
+ * render numbers / links / toggles as plain text.
+ */
+function mapFormRuntimeRendererType(rendererType, dataType) {
+    switch (rendererType) {
+        case 'lookup':
+            return 'lookup';
+        case 'optionset':
+            return 'optionset';
+        case 'currency':
+            return 'currency';
+        case 'progress':
+            return 'progress';
+        case 'date':
+            return dataType === 'datetime' ? 'datetime' : 'date';
+        case 'datetime':
+            return 'datetime';
+        case 'boolean':
+            return 'boolean';
+        case 'rating':
+            return 'rating';
+        case 'composite':
+            return 'composite';
+        case 'text':
+        default:
+            switch (dataType) {
+                case 'numeric':
+                    return 'number';
+                case 'currency':
+                    return 'currency';
+                case 'date':
+                    return 'date';
+                case 'datetime':
+                    return 'datetime';
+                case 'boolean':
+                    return 'boolean';
+                case 'url':
+                case 'email':
+                    return 'link';
+                // No standalone image renderer — show the URL as text (use a composite
+                // 'image' slot for an actual thumbnail).
+                case 'image':
+                    return 'text';
+                default:
+                    return 'text';
+            }
+    }
+}
+function mapEditorType(editorType) {
+    switch (editorType) {
+        case 'text':
+            return 'text';
+        case 'number':
+            return 'number';
+        case 'date':
+            return 'date';
+        case 'dropdown':
+            return 'dropdown';
+        case 'toggle':
+            return 'toggle';
+        case 'lookup':
+            return 'lookup';
+        case 'none':
+            return 'none';
+        default:
+            return undefined;
+    }
+}
+function fromGridCustomizerColumn(col) {
+    return {
+        key: col.id ?? col.fieldName,
+        fieldName: col.fieldName,
+        name: col.displayName,
+        rendererType: mapFormRuntimeRendererType(col.rendererType, col.dataType),
+        rendererConfig: col.rendererConfig,
+        editorType: mapEditorType(col.editorType),
+        isLocked: col.isLocked,
+        width: col.width,
+        minWidth: col.minWidth,
+        maxWidth: col.maxWidth,
+        isResizable: col.isResizable,
+        isSortable: col.isSortable,
+        isFilterable: col.isFilterable,
+        aggregate: col.aggregateFunction,
+    };
+}
+function fromGridCustomizerDefinition(def) {
+    return (def.columns ?? []).map((c) => fromGridCustomizerColumn(c));
+}
+
+/** Default nested display mode by parent grid type (mirrors form-runtime's v11→v12 migration). */
+function defaultNestedMode(gridType) {
+    if (gridType === 'focused-view')
+        return 'detail-pane';
+    if (gridType === 'card-list')
+        return 'side-panel';
+    return 'inline';
+}
+/** Build a FocusedViewConfig from a definition's focused-view settings (config or legacy fields). */
+function toFocusedViewConfig(fv) {
+    if (fv?.config)
+        return fv.config;
+    const rows = [
+        fv?.primaryNameField
+            ? { id: 'primary', primaryField: { fieldName: fv.primaryNameField, label: 'Name' } }
+            : undefined,
+        ...(fv?.summaryFields ?? []).map((s, i) => ({
+            id: `s${i}`,
+            primaryField: { fieldName: s.fieldName, label: s.label },
+        })),
+    ].filter(Boolean);
+    return { rows: rows.length ? rows : [{ id: 'primary', primaryField: { fieldName: 'name', label: 'Name' } }] };
+}
+/**
+ * Resolve a grid definition into the host + props grid-kit should render.
+ * `nestedGridId` (with `opts.resolveNested`) wraps the result in a NestedGrid;
+ * otherwise the `gridType` selects card / focused-view / readonly / data.
+ */
+function resolveGridFromDefinition(def, items, opts = {}) {
+    const columns = fromGridCustomizerDefinition(def);
+    const base = {
+        items,
+        columns,
+        editable: def.gridType === 'editable' || (!!def.isEditable && def.gridType !== 'readonly'),
+        selectionMode: def.gridType === 'readonly' ? 'none' : def.selectionMode ?? 'none',
+        alternateRowColors: def.alternateRowColors,
+    };
+    if (def.nestedGridId && opts.resolveNested) {
+        const { childColumns, getChildren } = opts.resolveNested(def);
+        const nested = {
+            mode: def.nestedDisplay?.mode ?? defaultNestedMode(def.gridType),
+            childColumns,
+            getChildren,
+            panelSize: def.nestedDisplay?.panelSize,
+            hoverDelay: def.nestedDisplay?.hoverDelay,
+            calloutMaxRows: def.nestedDisplay?.calloutMaxRows,
+            triggerLabel: def.nestedDisplay?.triggerLabel,
+            triggerIcon: def.nestedDisplay?.triggerIcon,
+            childSelectionMode: def.nestedDisplay?.childSelectionMode,
+            childSelectionGating: def.nestedSelectionMode,
+            childEditable: def.nestedDisplay?.childEditable,
+            childEditTrigger: def.nestedDisplay?.childEditTrigger,
+        };
+        // A focused-view parent with a detail-pane child is a master-detail layout.
+        if (def.gridType === 'focused-view') {
+            return { host: 'focused-view', props: { ...base, focusedView: toFocusedViewConfig(def.focusedView), nested } };
+        }
+        return { host: 'nested', props: { ...base, nested } };
+    }
+    switch (def.gridType) {
+        case 'card-list':
+            return {
+                host: 'card',
+                props: {
+                    ...base,
+                    card: {
+                        cardsPerRow: def.cardView?.cardsPerRow,
+                        cardHeight: def.cardView?.cardHeight,
+                        titleField: def.cardView?.titleField,
+                        subtitleField: def.cardView?.subtitleField,
+                        imageField: def.cardView?.imageField,
+                    },
+                },
+            };
+        case 'focused-view':
+            return { host: 'focused-view', props: { ...base, focusedView: toFocusedViewConfig(def.focusedView) } };
+        case 'readonly':
+            return { host: 'readonly', props: base };
+        case 'editable':
+        case 'standard':
+        default:
+            return { host: 'data', props: base };
+    }
+}
+
+/**
+ * Grid export helper — a thin wrapper over `@khester/dynamics-utils` export
+ * utilities that maps grid-kit `ColumnDef`s onto the export `ExportColumn` shape.
+ *
+ * Kept OUT of `src/core/` (which is for v9-portable pure logic): this triggers a
+ * browser download (`document` / `URL.createObjectURL`), a side-effectful host
+ * concern.
+ */
+/**
+ * Map grid-kit columns → dynamics-utils `ExportColumn[]`.
+ * `ExportColumn.key` is the DATA field (so it reads `item[fieldName]`), and the
+ * export formatter expects a canonical field type — reuse `rendererToFieldType`
+ * rather than the grid-kit `rendererType` vocabulary. The grid-kit-native
+ * `fileDrop` column has no exportable value and is skipped.
+ */
+function toExportColumns(columns) {
+    return columns
+        .filter((c) => c.rendererType !== 'fileDrop')
+        .map((c) => ({
+        key: c.fieldName,
+        name: c.name,
+        fieldType: rendererToFieldType(c.rendererType),
+    }));
+}
+/**
+ * Export grid rows to a CSV or JSON file (CSV = formatted strings, JSON = raw
+ * values — see dynamics-utils). The consumer passes exactly the rows to export
+ * (current page, all items, or the selection).
+ */
+function exportGrid(items, columns, format = 'csv', filename) {
+    exportToFile(items, toExportColumns(columns), format, filename ?? generateDefaultFilename('grid-export'));
+}
+
+const FORMAT_OPTIONS = {
+    csv: { key: 'csv', text: 'CSV', iconProps: { iconName: 'ExcelDocument' } },
+    json: { key: 'json', text: 'JSON', iconProps: { iconName: 'Code' } },
+};
+/** Strip characters illegal in filenames. */
+function sanitizeFilename(name) {
+    return name.replace(/[<>:"/\\|?*]/g, '');
+}
+/**
+ * The export subset for a column selection: drops `fileDrop` columns (no
+ * exportable value) and keeps only columns whose `key` is in `selectedKeys`.
+ * Pure — the dialog's column-picker decision, extracted for testability.
+ */
+function resolveExportColumns(columns, selectedKeys) {
+    return columns.filter((c) => c.rendererType !== 'fileDrop' && selectedKeys.has(c.key));
+}
+/**
+ * Export dialog with format choice, a column picker (Select-all / indeterminate),
+ * and a filename field. Exports the scoped `items` through `exportGrid`. The
+ * turnkey `GridProps.exportConfig` split-button opens this when `dialog: true`.
+ */
+function GridExportDialog({ isOpen, onClose, items, columns, defaultFilename = 'grid-export', formats = ['csv', 'json'], }) {
+    const exportable = useMemo(() => columns.filter((c) => c.rendererType !== 'fileDrop'), [columns]);
+    const [format, setFormat] = useState(formats[0] ?? 'csv');
+    const [filename, setFilename] = useState(() => generateDefaultFilename(defaultFilename));
+    const [selected, setSelected] = useState(() => new Set(exportable.map((c) => c.key)));
+    // Reset to defaults each time the dialog opens. Prop changes (formats /
+    // defaultFilename / columns) while it stays OPEN are intentionally ignored.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        setFormat(formats[0] ?? 'csv');
+        setFilename(generateDefaultFilename(defaultFilename));
+        setSelected(new Set(exportable.map((c) => c.key)));
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- reset only on the open transition
+    }, [isOpen]);
+    const allSelected = exportable.length > 0 && selected.size === exportable.length;
+    const someSelected = selected.size > 0 && selected.size < exportable.length;
+    const selectedColumns = useMemo(() => resolveExportColumns(columns, selected), [columns, selected]);
+    const toggleAll = useCallback((_, checked) => {
+        setSelected(checked ? new Set(exportable.map((c) => c.key)) : new Set());
+    }, [exportable]);
+    const toggleColumn = useCallback((key, checked) => {
+        setSelected((prev) => {
+            const next = new Set(prev);
+            if (checked)
+                next.add(key);
+            else
+                next.delete(key);
+            return next;
+        });
+    }, []);
+    const handleExport = useCallback(() => {
+        if (selectedColumns.length === 0 || items.length === 0 || !filename.trim())
+            return;
+        exportGrid(items, selectedColumns, format, filename.trim());
+        onClose();
+    }, [items, selectedColumns, format, filename, onClose]);
+    const formatChoices = formats.map((f) => FORMAT_OPTIONS[f]).filter(Boolean);
+    return (jsxs(Dialog, { hidden: !isOpen, onDismiss: onClose, dialogContentProps: { type: DialogType.normal, title: 'Export', closeButtonAriaLabel: 'Close' }, modalProps: { isBlocking: false, styles: { main: { maxWidth: 480, minWidth: 380 } } }, children: [jsx("div", { style: { textAlign: 'center', padding: 10, background: '#f3f2f1', borderRadius: 4 }, children: jsxs(Text, { variant: "mediumPlus", children: ["Exporting ", jsx("strong", { children: items.length }), " ", items.length === 1 ? 'row' : 'rows'] }) }), jsx(Separator, {}), formatChoices.length > 1 && (jsxs("div", { style: { marginBottom: 12 }, children: [jsx(Text, { block: true, styles: { root: { fontWeight: 600, marginBottom: 6 } }, children: "Format" }), jsx(ChoiceGroup, { selectedKey: format, options: formatChoices, onChange: (_, o) => o && setFormat(o.key) })] })), jsxs("div", { style: { marginBottom: 12 }, children: [jsx(Text, { block: true, styles: { root: { fontWeight: 600, marginBottom: 6 } }, children: "Columns" }), jsxs("div", { style: { maxHeight: 200, overflowY: 'auto', border: '1px solid #edebe9', borderRadius: 4, background: '#faf9f8' }, children: [jsx("div", { style: { padding: '8px 12px', borderBottom: '1px solid #edebe9' }, children: jsx(Checkbox, { label: "Select all", checked: allSelected, indeterminate: someSelected, onChange: toggleAll }) }), exportable.map((c) => (jsx("div", { style: { padding: '4px 12px' }, children: jsx(Checkbox, { label: c.name, checked: selected.has(c.key), onChange: (_, ck) => toggleColumn(c.key, !!ck) }) }, c.key)))] }), jsxs(Text, { variant: "small", styles: { root: { color: '#605e5c', paddingTop: 4, display: 'block' } }, children: [selected.size, " of ", exportable.length, " columns"] })] }), jsx(TextField, { label: "Filename", value: filename, onChange: (_, v) => setFilename(sanitizeFilename(v ?? '')), suffix: `.${format}`, description: "Invalid characters are removed." }), jsxs(DialogFooter, { children: [jsx(PrimaryButton, { text: "Export", iconProps: { iconName: 'Download' }, onClick: handleExport, disabled: selectedColumns.length === 0 || items.length === 0 || !filename.trim() }), jsx(DefaultButton, { text: "Cancel", onClick: onClose })] })] }));
+}
+
+const cellKey = (rowKey, fieldName) => `${rowKey}::${fieldName}`;
+function useEditState() {
+    const [edits, setEdits] = useState({});
+    const [errors, setErrors] = useState({});
+    const [active, setActive] = useState(null);
+    const onValueChange = useCallback((rowKey, fieldName, value, originalValue) => {
+        setEdits((prev) => ({ ...prev, [cellKey(rowKey, fieldName)]: { value, original: originalValue } }));
+    }, []);
+    const onValidationError = useCallback((rowKey, fieldName, message) => {
+        setErrors((prev) => {
+            const k = cellKey(rowKey, fieldName);
+            if (!message) {
+                if (!(k in prev))
+                    return prev;
+                const next = { ...prev };
+                delete next[k];
+                return next;
+            }
+            return { ...prev, [k]: message };
+        });
+    }, []);
+    const isDirty = useCallback((rowKey, fieldName) => cellKey(rowKey, fieldName) in edits, [edits]);
+    const getEditedValue = useCallback((rowKey, fieldName) => edits[cellKey(rowKey, fieldName)]?.value, [edits]);
+    const getError = useCallback((rowKey, fieldName) => errors[cellKey(rowKey, fieldName)], [errors]);
+    const isActiveCell = useCallback((rowKey, fieldName) => active === cellKey(rowKey, fieldName), [active]);
+    const setActiveCell = useCallback((rowKey, fieldName) => setActive(cellKey(rowKey, fieldName)), []);
+    const clearActiveCell = useCallback(() => setActive(null), []);
+    const getChanges = useCallback(() => {
+        const out = {};
+        for (const k of Object.keys(edits)) {
+            const sep = k.indexOf('::');
+            const rowKey = k.slice(0, sep);
+            const fieldName = k.slice(sep + 2);
+            (out[rowKey] = out[rowKey] ?? {})[fieldName] = edits[k].value;
+        }
+        return out;
+    }, [edits]);
+    const reset = useCallback(() => {
+        setEdits({});
+        setErrors({});
+        setActive(null);
+    }, []);
+    const hasErrors = Object.keys(errors).length > 0;
+    // Stable object identity: only changes when edits/errors/active change (the
+    // derived callbacks change identity then), so the grid's ctx/columns recompute
+    // on real edit-state changes, not on every render.
+    return useMemo(() => ({
+        onValueChange,
+        onValidationError,
+        isDirty,
+        getEditedValue,
+        getError,
+        isActiveCell,
+        setActiveCell,
+        clearActiveCell,
+        getChanges,
+        hasErrors,
+        reset,
+    }), [
+        onValueChange,
+        onValidationError,
+        isDirty,
+        getEditedValue,
+        getError,
+        isActiveCell,
+        setActiveCell,
+        clearActiveCell,
+        getChanges,
+        hasErrors,
+        reset,
+    ]);
+}
+
+/**
+ * Builds the per-render `GridRenderContext` shared by every grid host
+ * (DataGrid, CardGrid, GroupedGrid, …). Resolves the registry + key accessor,
+ * threads edit-state, and wires per-cell click-to-edit so all hosts behave
+ * identically. Extracted from DataGrid so the hosts don't each re-implement it.
+ */
+function useGridContext(props, edit) {
+    const { registry: providedRegistry, editable, editTrigger, sort, onSortChange, getKey, onValueChange, navigateTo } = props;
+    const registry = useMemo(() => providedRegistry ?? createCellRegistry(), [providedRegistry]);
+    const getKeyFn = useMemo(() => getKey ?? defaultGetKey, [getKey]);
+    const trigger = editTrigger ?? 'click';
+    const ctx = useMemo(() => ({
+        registry,
+        editable,
+        editTrigger: trigger,
+        getKey: getKeyFn,
+        sort,
+        onSortChange,
+        navigateTo,
+        // Per-cell: only the active cell is in edit mode. 'always': every editable cell.
+        isEditing: (rk, fn) => !!editable && (trigger === 'always' || edit.isActiveCell(rk, fn)),
+        isDirty: edit.isDirty,
+        getEditedValue: edit.getEditedValue,
+        getError: edit.getError,
+        onValueChange: (rk, fn, v, ov) => {
+            edit.onValueChange(rk, fn, v, ov);
+            onValueChange?.(rk, fn, v, ov);
+        },
+        onValidationError: edit.onValidationError,
+        onEditStart: (rk, fn) => edit.setActiveCell(rk, fn),
+        onEditEnd: () => edit.clearActiveCell(),
+    }), [registry, editable, trigger, getKeyFn, sort, onSortChange, edit, onValueChange, navigateTo]);
+    return { registry, getKeyFn, ctx };
+}
+
+/**
+ * Pure projection of a row's `RowCommand[]` → Fluent `ContextualMenu` items for a
+ * given row. Commands whose `visible(item)` returns `false` are dropped; `disabled`
+ * is resolved per row; `onClick` is bound to the row and chained with `onAfter`
+ * (used by the host to dismiss the menu). No React / no rendering — unit-testable in
+ * grid-kit's node test env (the type-only Fluent import has no runtime cost).
+ */
+function buildRowMenuItems(commands, item, onAfter) {
+    return commands
+        .filter((c) => c.visible?.(item) !== false)
+        .map((c) => ({
+        key: c.key,
+        text: c.text,
+        iconProps: c.iconName ? { iconName: c.iconName } : undefined,
+        disabled: c.disabled?.(item) ?? false,
+        onClick: () => {
+            c.onClick(item);
+            onAfter();
+        },
+    }));
+}
+
+/**
+ * Right-click row context menu for the DetailsList-backed hosts (`DataGrid`,
+ * `NestedInline`). Wire the returned `onItemContextMenu` onto `ShimmeredDetailsList`
+ * and render `contextMenuElement` alongside it.
+ *
+ * Backward-compat: when `rowCommands` is unset/empty, `onItemContextMenu` is
+ * `undefined`, so the host attaches no handler and the native browser context menu is
+ * left intact for existing consumers. When set, the handler stores the clicked row +
+ * the cursor event and returns `false` to suppress the native menu (Fluent calls
+ * `preventDefault` unless the handler returns a truthy value — do NOT return `true`).
+ */
+function useRowContextMenu(rowCommands) {
+    const [menu, setMenu] = useState(null);
+    const enabled = !!rowCommands && rowCommands.length > 0;
+    const onItemContextMenu = enabled
+        ? (item, _index, ev) => {
+            if (item == null || ev == null)
+                return;
+            setMenu({ item, target: ev });
+            return false; // suppress the native browser menu
+        }
+        : undefined;
+    const contextMenuElement = enabled && menu ? (jsx(ContextualMenu, { target: menu.target, items: buildRowMenuItems(rowCommands, menu.item, () => setMenu(null)), onDismiss: () => setMenu(null) })) : null;
+    return { onItemContextMenu, contextMenuElement };
+}
+
+/**
+ * Grid toolbar: a command bar (left) + optional search box (right).
+ */
+const GridToolbar = ({ config }) => {
+    const items = (config.commands ?? []).map((c) => ({
+        key: c.key,
+        text: c.text,
+        iconProps: c.iconName ? { iconName: c.iconName } : undefined,
+        onClick: c.onClick,
+        disabled: c.disabled,
+        split: c.split,
+        subMenuProps: c.subMenuProps,
+    }));
+    return (jsxs(Stack, { horizontal: true, horizontalAlign: "space-between", verticalAlign: "center", tokens: { childrenGap: 8 }, styles: { root: { paddingBottom: 4 } }, children: [jsx(Stack.Item, { grow: true, children: items.length > 0 ? (jsx(CommandBar, { items: items, styles: { root: { padding: 0, height: 36 } } })) : (jsx("span", {})) }), config.showSearch && (jsx(SearchBox, { placeholder: config.searchPlaceholder ?? 'Search', onChange: (_, v) => config.onSearch?.(v ?? ''), styles: { root: { width: 240 } } }))] }));
+};
+
+/**
+ * Presentational pager shared by all hosts. The consumer pre-slices `items` to
+ * the page; this only renders the page indicator + prev/next controls.
+ */
+const GridPaginationFooter = ({ pagination, onPageChange }) => {
+    const { currentPage, pageSize, totalItems } = pagination;
+    const totalPages = Math.max(1, Math.ceil(totalItems / Math.max(1, pageSize)));
+    return (jsxs(Stack, { horizontal: true, verticalAlign: "center", horizontalAlign: "end", tokens: { childrenGap: 8 }, styles: { root: { paddingTop: 8 } }, children: [jsx(Text, { variant: "small", children: `Page ${currentPage} of ${totalPages} · ${totalItems} item${totalItems === 1 ? '' : 's'}` }), jsx(DefaultButton, { text: "Previous", iconProps: { iconName: 'ChevronLeft' }, disabled: currentPage <= 1, onClick: () => onPageChange?.(currentPage - 1) }), jsx(DefaultButton, { text: "Next", iconProps: { iconName: 'ChevronRight' }, disabled: currentPage >= totalPages, onClick: () => onPageChange?.(currentPage + 1) })] }));
+};
+
+const AGG_LABEL = {
+    sum: 'Σ',
+    avg: 'avg',
+    count: 'count',
+    min: 'min',
+    max: 'max',
+};
+/** Format one aggregate cell: `<label> <value>` (currency sum → currency, etc.). */
+function aggregateCellText(col, agg) {
+    if (!agg)
+        return '';
+    let text = '';
+    if (col.aggregateFormat) {
+        text = col.aggregateFormat(agg.value, agg.fn);
+    }
+    else if (agg.value === null) {
+        text = '';
+    }
+    else if (agg.fn === 'count') {
+        text = String(agg.value);
+    }
+    else {
+        const cfg = (col.rendererConfig ?? {});
+        text = computeFormattedValue(agg.value, col.rendererType, {
+            currencyCode: cfg.currencyCode,
+            locale: cfg.locale,
+        });
+    }
+    return `${AGG_LABEL[agg.fn]} ${text}`.trim();
+}
+/**
+ * Presentational aggregate row: one cell per column (text only for columns that
+ * declared an `aggregate`), constrained to each column's min/max width and offset
+ * by `leadingSpacer`. Shared by the grid footer and per-group subtotal footers.
+ *
+ * Column alignment vs the DetailsList's justified layout is approximate (a known
+ * visual limitation); `leadingSpacer` offsets leading control columns (selection
+ * checkbox, group-expand chevron).
+ */
+function AggregateRow(props) {
+    const { columns, aggregates, leadingSpacer, background } = props;
+    return (jsxs(Stack, { horizontal: true, verticalAlign: "center", role: "row", styles: { root: { borderTop: '1px solid #edebe9', background: background ?? '#faf9f8', minHeight: 32 } }, children: [leadingSpacer ? jsx("div", { role: "presentation", style: { width: leadingSpacer, flexShrink: 0 } }) : null, columns.map((col) => {
+                const label = aggregateCellText(col, aggregates[col.fieldName]);
+                return (jsx("div", { role: "gridcell", title: label || undefined, style: {
+                        minWidth: col.minWidth ?? 100,
+                        maxWidth: col.maxWidth,
+                        width: col.maxWidth ?? col.minWidth ?? 100,
+                        padding: '4px 8px',
+                        fontSize: 12,
+                        fontWeight: 600,
+                        color: '#323130',
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                    }, children: label }, col.key));
+            })] }));
+}
+/**
+ * Footer row of per-column aggregates, rendered as a sibling Stack BELOW the
+ * DetailsList (Fluent v8 has no first-class footer-row API; mirrors how
+ * GridPaginationFooter mounts).
+ *
+ * Aggregates over exactly the `items` passed — the displayed (filtered) page by
+ * default, or the full dataset when the host is given `aggregateItems` (cross-page
+ * grand totals). `leadingSpacer` offsets a leading selection-check column.
+ */
+function GridAggregateFooter(props) {
+    const { items, columns, leadingSpacer } = props;
+    const aggregates = useMemo(() => computeAggregates(items, columns), [items, columns]);
+    return jsx(AggregateRow, { columns: columns, aggregates: aggregates, leadingSpacer: leadingSpacer });
+}
+
+/**
+ * Project a column list to its visible, ordered subset per `visibleOrder` (keys
+ * not in `columns` are skipped; columns not in `visibleOrder` are hidden). Pure —
+ * the chooser's effect on the rendered grid, extracted for testability.
+ */
+function orderVisibleColumns(columns, visibleOrder) {
+    const byKey = new Map(columns.map((c) => [c.key, c]));
+    return visibleOrder.map((k) => byKey.get(k)).filter((c) => !!c);
+}
+const rowStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    padding: '4px 0',
+    borderBottom: '1px solid #f3f2f1',
+};
+const sectionTitle = { root: { fontWeight: 600, color: '#605e5c', padding: '8px 0 4px' } };
+/**
+ * Column chooser panel: show/hide grid columns and reorder the shown ones.
+ * Edits a working copy and commits on Apply (reset on each open). At least one
+ * column must stay shown.
+ */
+function GridColumnChooser({ isOpen, onClose, columns, visibleOrder, onApply, }) {
+    const [working, setWorking] = useState(visibleOrder);
+    // Reset the working copy each time the panel opens.
+    useEffect(() => {
+        if (isOpen)
+            setWorking(visibleOrder);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- reset only on the open transition
+    }, [isOpen]);
+    const byKey = useMemo(() => new Map(columns.map((c) => [c.key, c])), [columns]);
+    const shown = working.map((k) => byKey.get(k)).filter((c) => !!c);
+    const hidden = columns.filter((c) => !working.includes(c.key));
+    const show = useCallback((key) => {
+        setWorking((prev) => (prev.includes(key) ? prev : [...prev, key]));
+    }, []);
+    const hide = useCallback((key) => {
+        setWorking((prev) => (prev.length <= 1 ? prev : prev.filter((k) => k !== key)));
+    }, []);
+    const move = useCallback((key, dir) => {
+        setWorking((prev) => {
+            const i = prev.indexOf(key);
+            const j = i + dir;
+            if (i < 0 || j < 0 || j >= prev.length)
+                return prev;
+            const next = [...prev];
+            [next[i], next[j]] = [next[j], next[i]];
+            return next;
+        });
+    }, []);
+    const showAll = useCallback(() => setWorking(columns.map((c) => c.key)), [columns]);
+    const reset = useCallback(() => setWorking(visibleOrder), [visibleOrder]);
+    const apply = useCallback(() => {
+        if (working.length === 0)
+            return;
+        onApply(working);
+        onClose();
+    }, [working, onApply, onClose]);
+    return (jsxs(Panel, { isOpen: isOpen, onDismiss: onClose, type: PanelType.medium, headerText: "Columns", isFooterAtBottom: true, onRenderFooterContent: () => (jsxs(Stack, { horizontal: true, horizontalAlign: "end", tokens: { childrenGap: 8 }, styles: { root: { padding: '12px 24px', borderTop: '1px solid #edebe9' } }, children: [jsx(DefaultButton, { text: "Cancel", onClick: onClose }), jsx(PrimaryButton, { text: "Apply", onClick: apply, disabled: working.length === 0 })] })), children: [jsxs(Stack, { horizontal: true, tokens: { childrenGap: 8 }, styles: { root: { padding: '8px 0' } }, children: [jsx(DefaultButton, { text: "Show all", onClick: showAll, disabled: hidden.length === 0 }), jsx(DefaultButton, { text: "Reset", onClick: reset })] }), jsxs(Text, { block: true, styles: sectionTitle, children: ["Shown (", shown.length, ")"] }), shown.map((c, i) => (jsxs("div", { style: rowStyle, children: [jsx(IconButton, { iconProps: { iconName: 'ChevronUp' }, ariaLabel: `Move ${c.name} up`, onClick: () => move(c.key, -1), disabled: i === 0, styles: { root: { height: 28, width: 28 } } }), jsx(IconButton, { iconProps: { iconName: 'ChevronDown' }, ariaLabel: `Move ${c.name} down`, onClick: () => move(c.key, 1), disabled: i === shown.length - 1, styles: { root: { height: 28, width: 28 } } }), jsx(Checkbox, { checked: true, ariaLabel: `Hide ${c.name}`, onChange: () => hide(c.key), disabled: shown.length === 1, styles: { root: { marginLeft: 4 } } }), jsx("span", { style: { flex: 1, marginLeft: 8 }, children: c.name })] }, c.key))), jsx(Separator, {}), jsxs(Text, { block: true, styles: sectionTitle, children: ["Hidden (", hidden.length, ")"] }), hidden.length === 0 ? (jsx(Text, { variant: "small", styles: { root: { color: '#a19f9d' } }, children: "All columns are shown." })) : (hidden.map((c) => (jsxs("div", { style: rowStyle, children: [jsx(Checkbox, { checked: false, ariaLabel: `Show ${c.name}`, onChange: () => show(c.key) }), jsx("span", { style: { flex: 1, marginLeft: 8 }, children: c.name })] }, c.key))))] }));
+}
+
+/** Map a column's renderer type onto a filter field-type bucket. */
+function fieldTypeForRenderer(rendererType) {
+    switch (rendererToFieldType(rendererType)) {
+        case 'number':
+        case 'progressBar':
+        case 'rating':
+            return 'number';
+        case 'currency':
+            return 'currency';
+        case 'date':
+        case 'datetime':
+            return 'date';
+        case 'toggle':
+            return 'boolean';
+        case 'optionset':
+            return 'optionset';
+        case 'lookup':
+            return 'lookup';
+        default:
+            return 'text';
+    }
+}
+const OPS_BY_TYPE = {
+    text: ['eq', 'ne', 'like', 'not-like', 'begins-with', 'ends-with', 'null', 'not-null'],
+    number: ['eq', 'ne', 'gt', 'ge', 'lt', 'le', 'null', 'not-null'],
+    currency: ['eq', 'ne', 'gt', 'ge', 'lt', 'le', 'null', 'not-null'],
+    date: ['eq', 'ne', 'on-or-after', 'on-or-before', 'gt', 'lt', 'null', 'not-null'],
+    boolean: ['eq', 'ne'],
+    optionset: ['eq', 'ne', 'in', 'not-in', 'null', 'not-null'],
+    lookup: ['eq', 'ne', 'like', 'null', 'not-null'],
+};
+const OP_LABELS = {
+    eq: 'Equals',
+    ne: 'Does Not Equal',
+    like: 'Contains',
+    'not-like': 'Does Not Contain',
+    'begins-with': 'Begins With',
+    'ends-with': 'Ends With',
+    gt: 'Greater Than',
+    ge: 'Greater Or Equal',
+    lt: 'Less Than',
+    le: 'Less Or Equal',
+    'on-or-after': 'On Or After',
+    'on-or-before': 'On Or Before',
+    in: 'Is One Of',
+    'not-in': 'Is Not One Of',
+    null: 'Is Empty',
+    'not-null': 'Is Not Empty',
+};
+/** Operators for a field type, with display labels (date relabels gt/lt to After/Before). */
+function getOperatorsForFieldType(t) {
+    return OPS_BY_TYPE[t].map((op) => {
+        const label = t === 'date' && op === 'gt' ? 'After' : t === 'date' && op === 'lt' ? 'Before' : OP_LABELS[op];
+        return { op, label };
+    });
+}
+/** Read optionset choices off a column's renderer config (both key shapes). */
+function normalizeOptions(col) {
+    const cfg = (col.rendererConfig ?? {});
+    const raw = cfg.optionSetOptions ?? cfg.options;
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw
+        .map((o) => {
+        const opt = o;
+        const key = opt.key ?? opt.value;
+        if (key === undefined || key === null)
+            return undefined;
+        const text = opt.text ?? opt.label ?? key;
+        return { key: String(key), text: String(text) };
+    })
+        .filter((o) => !!o);
+}
+function toFilterField(col) {
+    let fieldType = fieldTypeForRenderer(col.rendererType);
+    const options = fieldType === 'optionset' ? normalizeOptions(col) : undefined;
+    // An optionset column with no declared choices behaves as text — otherwise its
+    // `in`/`not-in` operators would render a text box that writes `value`, never the
+    // `values` they require, leaving the condition permanently incomplete.
+    if (fieldType === 'optionset' && (!options || options.length === 0))
+        fieldType = 'text';
+    return { key: col.fieldName, text: col.name, fieldType, options };
+}
+/** Format a Date as a local calendar day (YYYY-MM-DD) — avoids the toISOString UTC shift. */
+function toDateOnly(d) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/** Parse a YYYY-MM-DD (or ISO) value into a LOCAL Date for the picker (round-trips the day). */
+function parseDateValue(value) {
+    if (!value)
+        return undefined;
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+    const d = m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : new Date(value);
+    return Number.isNaN(d.getTime()) ? undefined : d;
+}
+/** Per-condition value editor — switches on the column's field type + operator. */
+function ValueEditor({ field, condition, onChange, }) {
+    const fieldType = field?.fieldType ?? 'text';
+    if (fieldType === 'boolean') {
+        return (jsx(Dropdown, { ariaLabel: "Value", selectedKey: condition.value ?? null, options: [
+                { key: 'true', text: 'Yes' },
+                { key: 'false', text: 'No' },
+            ], onChange: (_, o) => o && onChange({ value: String(o.key) }), styles: { root: { width: 120 } } }));
+    }
+    if (fieldType === 'optionset' && field?.options) {
+        if (operatorIsMultiValue(condition.operator)) {
+            return (jsx(Dropdown, { multiSelect: true, ariaLabel: "Values", selectedKeys: condition.values ?? [], options: field.options, onChange: (_, o) => {
+                    if (!o)
+                        return;
+                    const prev = condition.values ?? [];
+                    const key = String(o.key);
+                    onChange({ values: o.selected ? [...prev, key] : prev.filter((k) => k !== key) });
+                }, styles: { root: { width: 190 } } }));
+        }
+        return (jsx(Dropdown, { ariaLabel: "Value", selectedKey: condition.value ?? null, options: field.options, onChange: (_, o) => o && onChange({ value: String(o.key) }), styles: { root: { width: 190 } } }));
+    }
+    if (fieldType === 'date') {
+        return (jsx(DatePicker, { ariaLabel: "Value", value: parseDateValue(condition.value), onSelectDate: (d) => onChange({ value: d ? toDateOnly(d) : undefined }), styles: { root: { width: 170 } } }));
+    }
+    const isNumeric = fieldType === 'number' || fieldType === 'currency';
+    return (jsx(TextField, { ariaLabel: "Value", type: isNumeric ? 'number' : 'text', value: condition.value ?? '', placeholder: fieldType === 'lookup' ? 'Text or GUID' : undefined, onChange: (_, v) => onChange({ value: v ?? '' }), styles: { root: { width: 170 } } }));
+}
+/** One filter row: column → operator → value editor → remove. */
+function ConditionRow({ condition, fields, onChange, onRemove, }) {
+    const field = fields.find((f) => f.key === condition.fieldName);
+    const fieldType = field?.fieldType ?? 'text';
+    const operators = getOperatorsForFieldType(fieldType);
+    const onFieldChange = (key) => {
+        const next = fields.find((f) => f.key === key);
+        const firstOp = next ? getOperatorsForFieldType(next.fieldType)[0].op : 'eq';
+        onChange({ fieldName: key, operator: firstOp, value: undefined, values: undefined });
+    };
+    return (jsxs(Stack, { horizontal: true, verticalAlign: "start", tokens: { childrenGap: 8 }, styles: { root: { padding: '2px 0' } }, children: [jsx(Dropdown, { ariaLabel: "Column", placeholder: "Select a column", selectedKey: condition.fieldName || null, options: fields.map((f) => ({ key: f.key, text: f.text })), onChange: (_, o) => o && onFieldChange(String(o.key)), styles: { root: { width: 170 } } }), jsx(Dropdown, { ariaLabel: "Operator", selectedKey: condition.operator, disabled: !condition.fieldName, options: operators.map((o) => ({ key: o.op, text: o.label })), onChange: (_, o) => o && onChange({ operator: o.key, value: undefined, values: undefined }), styles: { root: { width: 150 } } }), condition.fieldName && operatorRequiresValue(condition.operator) && (jsx(ValueEditor, { field: field, condition: condition, onChange: onChange })), jsx(IconButton, { iconProps: { iconName: 'Delete' }, ariaLabel: "Remove condition", title: "Remove condition", onClick: onRemove })] }));
+}
+let rowSeq = 0;
+const makeRow = (cond) => ({ id: ++rowSeq, cond });
+/**
+ * Filter-builder panel: build field/operator/value conditions combined by All/Any
+ * (AND/OR). Edits a working copy and commits on Apply (reset on each open).
+ * Incomplete rows are dropped on Apply. The actual row filtering is done by the
+ * pure `applyFilters` (src/core/filter.ts); this panel only produces the model.
+ */
+function GridFilterBuilder({ isOpen, onClose, columns, model, onApply, }) {
+    const fields = useMemo(() => {
+        const seen = new Set();
+        const out = [];
+        for (const col of columns) {
+            if (col.isFilterable === false || col.rendererType === 'fileDrop')
+                continue;
+            if (seen.has(col.fieldName))
+                continue;
+            seen.add(col.fieldName);
+            out.push(toFilterField(col));
+        }
+        return out;
+    }, [columns]);
+    const [match, setMatch] = useState(model.match);
+    const [rows, setRows] = useState(() => model.conditions.map(makeRow));
+    // Reset the working copy each time the panel opens (mirrors GridColumnChooser).
+    useEffect(() => {
+        if (isOpen) {
+            setMatch(model.match);
+            setRows(model.conditions.map(makeRow));
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- reset only on the open transition
+    }, [isOpen]);
+    const addCondition = () => setRows((rs) => [...rs, makeRow({ fieldName: '', operator: 'eq' })]);
+    const updateCondition = (id, patch) => setRows((rs) => rs.map((r) => (r.id === id ? { ...r, cond: { ...r.cond, ...patch } } : r)));
+    const removeCondition = (id) => setRows((rs) => rs.filter((r) => r.id !== id));
+    const clearAll = () => setRows([]);
+    const apply = () => {
+        onApply({ match, conditions: rows.map((r) => r.cond).filter(isConditionComplete) });
+        onClose();
+    };
+    return (jsxs(Panel, { isOpen: isOpen, onDismiss: onClose, type: PanelType.medium, headerText: "Edit filters", isFooterAtBottom: true, onRenderFooterContent: () => (jsxs(Stack, { horizontal: true, horizontalAlign: "end", tokens: { childrenGap: 8 }, styles: { root: { padding: '12px 24px', borderTop: '1px solid #edebe9' } }, children: [jsx(DefaultButton, { text: "Cancel", onClick: onClose }), jsx(PrimaryButton, { text: "Apply", onClick: apply })] })), children: [rows.length > 1 && (jsx(Dropdown, { label: "Match", selectedKey: match, options: [
+                    { key: 'all', text: 'All conditions (AND)' },
+                    { key: 'any', text: 'Any condition (OR)' },
+                ], onChange: (_, o) => o && setMatch(o.key), styles: { root: { width: 220, padding: '8px 0' } } })), rows.length === 0 ? (jsx(Text, { variant: "small", styles: { root: { color: '#a19f9d', display: 'block', padding: '8px 0' } }, children: "No filters. Add a condition to narrow the rows." })) : (jsx(Stack, { tokens: { childrenGap: 4 }, styles: { root: { padding: '8px 0' } }, children: rows.map((r) => (jsx(ConditionRow, { condition: r.cond, fields: fields, onChange: (patch) => updateCondition(r.id, patch), onRemove: () => removeCondition(r.id) }, r.id))) })), jsxs(Stack, { horizontal: true, tokens: { childrenGap: 8 }, styles: { root: { padding: '8px 0' } }, children: [jsx(DefaultButton, { iconProps: { iconName: 'Add' }, text: "Add condition", onClick: addCondition, disabled: fields.length === 0 }), rows.length > 0 && jsx(DefaultButton, { text: "Clear all", onClick: clearAll })] })] }));
+}
+
+// Shared helpers for the additive, default-off `fill`/`height` grid props (v1b).
+// `fill` makes a host fill its container (flex column at `height`, default 100%) and
+// scroll its list/cards region internally — so a grid dropped into a surface-kit
+// Section / Dialog / Panel scrolls inside the surface while the toolbar + footers
+// (and the surface's own footer) stay fixed. All default-off → unchanged when unset.
+//
+// Consumer contract: the container MUST have a resolved height (a flex/grid parent or
+// an explicit height) — `height: '100%'` against an auto-height parent renders nothing.
+// v1 limitation: the DetailsList column header scrolls with the body (not pinned via
+// ScrollablePane/Sticky); the surface-integration goal (grid scrolls so the surface
+// footer stays put) is still met.
+/** Stack root styles for a host that should fill its container. `undefined` when not filling. */
+function fillStackStyles(fill, height) {
+    return fill ? { root: { height: height ?? '100%', display: 'flex', flexDirection: 'column', minHeight: 0 } } : undefined;
+}
+/** Wraps the scrollable region (list/cards) so it grows + scrolls inside a `fill` host; passthrough otherwise. */
+const FillRegion = ({ fill, children }) => fill ? jsx("div", { style: { flex: 1, minHeight: 0, overflow: 'auto' }, children: children }) : jsx(Fragment, { children: children });
+
+/** Wraps a rendered DetailsList row as a file-drop target. */
+function RowFileDropTarget({ item, config, children, }) {
+    const { isDragOver, dragProps } = useFileDrop({
+        onDrop: (files) => config.onDrop(item, files),
+        accept: config.accept,
+        multiple: config.multiple,
+        onReject: config.onReject ? (reason) => config.onReject(item, reason) : undefined,
+    });
+    return (
+    // role="presentation" so the wrapper doesn't add a node to the grid's ARIA
+    // row structure — the DetailsRow inside keeps role="row".
+    jsx("div", { ...dragProps, role: "presentation", style: {
+            outline: isDragOver ? '2px solid #0078d4' : '2px solid transparent',
+            background: isDragOver ? 'rgba(0,120,212,0.06)' : undefined,
+            transition: 'background 80ms ease-out, outline-color 80ms ease-out',
+        }, children: children }));
+}
+// One-time dev warning: client-side filtering over a consumer-pre-sliced page is
+// inconsistent with pagination.totalItems. Fired once per process.
+let warnedFilterPaging = false;
+function mapSelectionMode$2(mode) {
+    switch (mode) {
+        case 'single':
+            return SelectionMode.single;
+        case 'multiple':
+            return SelectionMode.multiple;
+        case 'none':
+        default:
+            return SelectionMode.none;
+    }
+}
+/**
+ * Flat / editable grid host built on Fluent v8 `ShimmeredDetailsList`. Columns
+ * come from the registry via `toDetailsListColumns`; inline edit-state from
+ * `useEditState` (per-cell click-to-edit by default). Card / grouped / nested
+ * layouts are separate hosts that reuse the same registry + render context.
+ */
+function DataGrid(props) {
+    const { items, columns, selectionMode = 'none', onSelectionChanged, isLoading, pagination, onPageChange, aggregateItems, toolbar, onActiveItemChanged, compact, rowFileDrop, exportConfig, alternateRowColors, navigateTo, onRowNavigate, rowCommands, columnChooser, onColumnOrderChange, filterBuilder, onFilterChange, fill, height, } = props;
+    const edit = useEditState();
+    const { getKeyFn, ctx } = useGridContext(props, edit);
+    const { onItemContextMenu, contextMenuElement } = useRowContextMenu(rowCommands);
+    // Null-safe row key: with `enableShimmer`, Fluent calls getKey on UNDEFINED
+    // placeholder rows — never let a consumer's getKey (e.g. `r => r.key`) crash
+    // on those during loading.
+    const safeRowKey = (it, index) => it == null ? `__gridkit_shimmer_${index ?? 0}` : getKeyFn(it);
+    // Fluent Selection so consumers can read selected rows via onSelectionChanged.
+    const onSelectionChangedRef = useRef(onSelectionChanged);
+    onSelectionChangedRef.current = onSelectionChanged;
+    const selectionRef = useRef();
+    if (!selectionRef.current) {
+        selectionRef.current = new Selection({
+            getKey: (it, index) => safeRowKey(it, index),
+            onSelectionChanged: () => onSelectionChangedRef.current?.(selectionRef.current.getSelection()),
+        });
+    }
+    // Column chooser: the visible+ordered column keys (default all). Reconciles when
+    // the `columns` prop changes — new keys appended (visible), removed keys dropped.
+    const [visibleOrder, setVisibleOrder] = useState(() => columns.map((c) => c.key));
+    useEffect(() => {
+        setVisibleOrder((prev) => {
+            const keys = new Set(columns.map((c) => c.key));
+            const kept = prev.filter((k) => keys.has(k));
+            const added = columns.map((c) => c.key).filter((k) => !prev.includes(k));
+            const next = [...kept, ...added];
+            return next.length === prev.length && next.every((k, i) => k === prev[i]) ? prev : next;
+        });
+    }, [columns]);
+    const [columnChooserOpen, setColumnChooserOpen] = useState(false);
+    const effectiveColumns = useMemo(() => (columnChooser ? orderVisibleColumns(columns, visibleOrder) : columns), [columnChooser, columns, visibleOrder]);
+    // Filter builder: the applied model + the filtered row set. Filtering changes
+    // the row SET (unlike the chooser's purely-visual column projection), so
+    // effectiveItems feeds the list, aggregate footer, AND export scope together.
+    const [filterModel, setFilterModel] = useState({ match: 'all', conditions: [] });
+    const [filterBuilderOpen, setFilterBuilderOpen] = useState(false);
+    const effectiveItems = useMemo(() => (filterBuilder ? applyFilters(items, filterModel) : items), [filterBuilder, items, filterModel]);
+    const activeFilterCount = useMemo(() => filterModel.conditions.filter(isConditionComplete).length, [filterModel]);
+    // Footer aggregate source: the displayed (filtered) page by default, or the full
+    // `aggregateItems` dataset for cross-page grand totals — with the active filter
+    // applied to it too, so the grand total reflects the filter across all pages.
+    const aggregateSource = useMemo(() => aggregateItems ? (filterBuilder ? applyFilters(aggregateItems, filterModel) : aggregateItems) : effectiveItems, [aggregateItems, filterBuilder, filterModel, effectiveItems]);
+    useEffect(() => {
+        if (filterBuilder && pagination && !warnedFilterPaging && typeof console !== 'undefined') {
+            warnedFilterPaging = true;
+            console.warn('[grid-kit] filterBuilder filters the in-memory `items` (the current page when paginated), ' +
+                'so the visible/footer/export counts can disagree with pagination.totalItems. For ' +
+                'server-side filtering, read onFilterChange and re-query instead.');
+        }
+    }, [filterBuilder, pagination]);
+    const dlColumns = useMemo(() => toDetailsListColumns(effectiveColumns, ctx), [effectiveColumns, ctx]);
+    // Turnkey export. selectionRef.getSelection() is safe even when selectionMode
+    // is 'none' (returns []). Scope: 'all' = every row; 'selected' = only the
+    // selection (no-op when empty / not selectable); default = selection if any,
+    // else all.
+    // NOTE: export uses the FULL `columns`, independent of the column chooser's
+    // on-screen visibility — you export the whole dataset; the export dialog has
+    // its own column picker for narrowing the output. Rows, however, DO honor the
+    // filter builder (`effectiveItems`) — you export what the filter shows.
+    const exportFormats = exportConfig?.formats ?? ['csv', 'json'];
+    const [exportDialogOpen, setExportDialogOpen] = useState(false);
+    const scopedRows = useCallback(() => {
+        const selected = (selectionRef.current?.getSelection() ?? []);
+        if (exportConfig?.scope === 'all')
+            return effectiveItems;
+        if (exportConfig?.scope === 'selected')
+            return selected;
+        return selected.length > 0 ? selected : effectiveItems;
+    }, [effectiveItems, exportConfig]);
+    const doExport = useCallback((format) => {
+        const rows = scopedRows();
+        if (rows.length === 0)
+            return;
+        exportGrid(rows, columns, format, exportConfig?.filename);
+    }, [columns, exportConfig, scopedRows]);
+    const exportCommand = !exportConfig?.enabled
+        ? undefined
+        : exportConfig.dialog
+            ? {
+                // Dialog mode — a single "Export…" button opening the column/format picker.
+                key: '__gridkit_export__',
+                text: 'Export…',
+                iconName: 'Download',
+                onClick: () => setExportDialogOpen(true),
+            }
+            : {
+                key: '__gridkit_export__',
+                text: 'Export',
+                iconName: 'Download',
+                split: exportFormats.length > 1,
+                onClick: () => doExport(exportFormats[0]),
+                subMenuProps: exportFormats.length > 1
+                    ? {
+                        items: exportFormats.map((f) => ({
+                            key: f,
+                            text: f.toUpperCase(),
+                            iconProps: { iconName: f === 'csv' ? 'ExcelDocument' : 'Code' },
+                            onClick: () => doExport(f),
+                        })),
+                    }
+                    : undefined,
+            };
+    // "Open" navigation command — navigates the selected row (else the active one).
+    const activeItemRef = useRef(undefined);
+    const openCommand = navigateTo
+        ? {
+            key: '__gridkit_open__',
+            text: 'Open',
+            iconName: 'OpenInNewWindow',
+            onClick: () => {
+                const selected = (selectionRef.current?.getSelection() ?? []);
+                const target = selected[0] ?? activeItemRef.current;
+                if (!target)
+                    return;
+                const nav = navigateTo(target);
+                if (nav)
+                    void navigateToTarget(nav);
+            },
+        }
+        : undefined;
+    // "Columns" command — opens the column chooser panel.
+    const columnsCommand = columnChooser
+        ? {
+            key: '__gridkit_columns__',
+            text: 'Columns',
+            iconName: 'ColumnOptions',
+            onClick: () => setColumnChooserOpen(true),
+        }
+        : undefined;
+    // "Filters" command — opens the filter builder panel (shows the active count).
+    const filtersCommand = filterBuilder
+        ? {
+            key: '__gridkit_filters__',
+            text: activeFilterCount ? `Filters (${activeFilterCount})` : 'Filters',
+            iconName: 'Filter',
+            onClick: () => setFilterBuilderOpen(true),
+        }
+        : undefined;
+    const injectedCommands = [
+        exportCommand,
+        openCommand,
+        columnsCommand,
+        filtersCommand,
+    ].filter(Boolean);
+    const effectiveToolbar = toolbar || injectedCommands.length
+        ? { ...toolbar, commands: [...injectedCommands, ...(toolbar?.commands ?? [])] }
+        : undefined;
+    // Compose alternate-row tint + whole-row file-drop into ONE onRenderRow (both
+    // want it). Return undefined when neither is set so Fluent uses its optimized
+    // default-row path. Tint by passing fresh `styles` to defaultRender — never
+    // mutate rowProps.styles (it is optional and may be a style function).
+    const onRenderRow = useMemo(() => rowFileDrop || alternateRowColors
+        ? (rowProps, defaultRender) => {
+            if (!rowProps || !defaultRender)
+                return null;
+            const rendered = alternateRowColors
+                ? defaultRender({
+                    ...rowProps,
+                    styles: {
+                        root: {
+                            backgroundColor: rowProps.itemIndex % 2 === 0 ? alternateRowColors.even : alternateRowColors.odd,
+                        },
+                    },
+                })
+                : defaultRender(rowProps);
+            return rowFileDrop ? (jsx(RowFileDropTarget, { item: rowProps.item, config: rowFileDrop, children: rendered })) : (rendered);
+        }
+        : undefined, [rowFileDrop, alternateRowColors]);
+    return (jsxs(Stack, { styles: fillStackStyles(fill, height), children: [effectiveToolbar && jsx(GridToolbar, { config: effectiveToolbar }), jsx(FillRegion, { fill: fill, children: jsx(ShimmeredDetailsList, { items: effectiveItems, columns: dlColumns, selectionMode: mapSelectionMode$2(selectionMode), selection: selectionMode !== 'none' ? selectionRef.current : undefined, enableShimmer: isLoading, layoutMode: DetailsListLayoutMode.justified, compact: compact, getKey: (it, index) => safeRowKey(it, index), setKey: "grid-kit", onRenderRow: onRenderRow, onActiveItemChanged: (item, index) => {
+                        activeItemRef.current = item;
+                        onActiveItemChanged?.(item, index);
+                    }, onItemInvoked: onRowNavigate ? (item) => onRowNavigate(item) : undefined, onItemContextMenu: onItemContextMenu, styles: getDetailsListStyles(), ariaLabelForShimmer: "Loading data", ariaLabelForGrid: "Grid" }) }), contextMenuElement, effectiveColumns.some((c) => c.aggregate) && (jsx(GridAggregateFooter, { items: aggregateSource, columns: effectiveColumns, leadingSpacer: selectionMode !== 'none' ? 48 : 0 })), pagination && jsx(GridPaginationFooter, { pagination: pagination, onPageChange: onPageChange }), exportConfig?.dialog && (jsx(GridExportDialog, { isOpen: exportDialogOpen, onClose: () => setExportDialogOpen(false), items: exportDialogOpen ? scopedRows() : [], columns: columns, defaultFilename: exportConfig.filename, formats: exportFormats })), columnChooser && (jsx(GridColumnChooser, { isOpen: columnChooserOpen, onClose: () => setColumnChooserOpen(false), columns: columns, visibleOrder: visibleOrder, onApply: (order) => {
+                    setVisibleOrder(order);
+                    onColumnOrderChange?.(order);
+                } })), filterBuilder && (jsx(GridFilterBuilder, { isOpen: filterBuilderOpen, onClose: () => setFilterBuilderOpen(false), columns: columns, model: filterModel, onApply: (m) => {
+                    setFilterModel(m);
+                    onFilterChange?.(m);
+                } }))] }));
+}
+
+/**
+ * Read-only grid: `<DataGrid>` with selection off, editing off, and command-bar
+ * commands stripped (search is kept). Mirrors the Grid Customizer's "Read-Only
+ * Grid" type — a presentation preset, no extra config.
+ */
+function ReadOnlyGrid(props) {
+    const toolbar = props.toolbar
+        ? { showSearch: props.toolbar.showSearch, searchPlaceholder: props.toolbar.searchPlaceholder, onSearch: props.toolbar.onSearch }
+        : undefined;
+    return jsx(DataGrid, { ...props, selectionMode: "none", editable: false, toolbar: toolbar });
+}
+
+// Shared card-layout primitives for the card hosts (`<CardGrid>` flat cards +
+// `<NestedCardParent>` expandable parent cards). The derivation is a PURE function
+// (no hooks) so it's unit-testable without a DOM; the mergeStyles classes are shared
+// so the two hosts can't drift apart visually.
+const cardClass = mergeStyles({
+    border: '1px solid #edebe9',
+    borderRadius: 4,
+    padding: 12,
+    background: '#fff',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 6,
+    boxShadow: '0 1px 2px rgba(0,0,0,0.06)',
+});
+const cardImageClass = mergeStyles({
+    width: '100%',
+    height: 96,
+    objectFit: 'cover',
+    borderRadius: 2,
+    marginBottom: 4,
+});
+const bodyRowClass = mergeStyles({
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: 8,
+    fontSize: 13,
+});
+/**
+ * PURE derivation of a card layout from columns + config — no React hooks, so it's
+ * directly unit-testable. Hosts wrap the call in their own `useMemo`. titleField
+ * defaults to the first column; bodyColumns defaults to all columns except the
+ * title/subtitle/image fields (explicit `bodyFields` are honored verbatim).
+ */
+function resolveCardLayout(columns, card) {
+    const cardsPerRow = card?.cardsPerRow ?? 3;
+    const titleField = card?.titleField ?? columns[0]?.fieldName;
+    const { subtitleField, imageField, cardHeight } = card ?? {};
+    const byField = new Map();
+    columns.forEach((c) => byField.set(c.fieldName, c));
+    const explicit = card?.bodyFields;
+    const bodyColumns = explicit
+        ? explicit.map((f) => byField.get(f)).filter(Boolean)
+        : columns.filter((c) => !new Set([titleField, subtitleField, imageField].filter(Boolean)).has(c.fieldName));
+    return { cardsPerRow, titleField, subtitleField, imageField, cardHeight, byField, bodyColumns };
+}
+
+/**
+ * Card-view grid host. Renders each row as a card; every field value goes
+ * through the SAME cell registry as `<DataGrid>` (so status badges, currency,
+ * ratings, etc. look identical). Mirrors the Grid Customizer's "Card List" type.
+ *
+ * Selection is checkbox-based (manual Set), independent of Fluent's DetailsList
+ * Selection.
+ */
+function CardGrid(props) {
+    const { items, columns, card, selectionMode = 'none', onSelectionChanged, toolbar, pagination, onPageChange, onActiveItemChanged, fill, height, } = props;
+    const edit = useEditState();
+    const { getKeyFn, ctx } = useGridContext(props, edit);
+    // Card layout derivation is shared (and unit-tested) via resolveCardLayout —
+    // identical to the prior inline derivation, so rendered output is unchanged.
+    const { cardsPerRow, titleField, subtitleField, imageField, cardHeight, byField, bodyColumns } = useMemo(() => resolveCardLayout(columns, card), [columns, card]);
+    const [selected, setSelected] = useState(new Set());
+    const renderField = (col, item) => {
+        if (!col)
+            return null;
+        const cellProps = buildCellProps(col, item, ctx);
+        const Renderer = ctx.registry.resolve(col, false); // cards render read-only
+        return jsx(Renderer, { ...cellProps });
+    };
+    const rawValue = (item, field) => {
+        if (!field)
+            return '';
+        const v = item[field];
+        return v == null ? '' : String(v);
+    };
+    const toggleSelect = (item, checked) => {
+        const key = getKeyFn(item);
+        setSelected((prev) => {
+            const next = new Set(selectionMode === 'single' ? [] : prev);
+            if (checked)
+                next.add(key);
+            else
+                next.delete(key);
+            onSelectionChanged?.(items.filter((it) => next.has(getKeyFn(it))));
+            return next;
+        });
+    };
+    return (jsxs(Stack, { styles: fillStackStyles(fill, height), children: [toolbar && jsx(GridToolbar, { config: toolbar }), jsx(FillRegion, { fill: fill, children: jsx("div", { style: {
+                        display: 'grid',
+                        gridTemplateColumns: `repeat(${cardsPerRow}, minmax(0, 1fr))`,
+                        gap: 12,
+                        paddingTop: 4,
+                    }, children: items.map((item) => {
+                        const key = getKeyFn(item);
+                        return (jsxs("div", { className: cardClass, style: cardHeight ? { height: cardHeight } : undefined, onClick: () => onActiveItemChanged?.(item), children: [jsxs(Stack, { horizontal: true, horizontalAlign: "space-between", verticalAlign: "start", children: [jsx(Text, { variant: "mediumPlus", styles: { root: { fontWeight: 600 } }, children: renderField(byField.get(titleField ?? ''), item) ?? rawValue(item, titleField) }), selectionMode !== 'none' && (
+                                        // Stop the click from bubbling to the card's onActiveItemChanged.
+                                        jsx("span", { onClick: (e) => e.stopPropagation(), children: jsx(Checkbox, { checked: selected.has(key), onChange: (_, checked) => toggleSelect(item, checked), ariaLabel: "Select card" }) }))] }), imageField && rawValue(item, imageField) && (jsx("img", { className: cardImageClass, src: rawValue(item, imageField), alt: "" })), subtitleField && (jsx(Text, { variant: "small", styles: { root: { color: '#605e5c' } }, children: rawValue(item, subtitleField) })), bodyColumns.map((col) => (jsxs("div", { className: bodyRowClass, children: [jsx(Text, { variant: "small", styles: { root: { color: '#605e5c' } }, children: col.name }), jsx("span", { children: renderField(col, item) })] }, col.key)))] }, key));
+                    }) }) }), pagination && jsx(GridPaginationFooter, { pagination: pagination, onPageChange: onPageChange })] }));
+}
+
+/**
+ * Bucket rows by `group.groupBy` into a contiguous, ordered array plus the
+ * Fluent v8 `IGroup[]` describing each bucket's range. Fluent's grouped
+ * DetailsList requires the items array to be ordered so each group's
+ * `startIndex`/`count` is contiguous — this guarantees that. Pure + exported so
+ * it's unit-testable and reusable.
+ */
+function buildGroups(items, group) {
+    const buckets = new Map();
+    for (const it of items) {
+        const v = it[group.groupBy];
+        const k = v == null ? '(Blank)' : String(v);
+        let arr = buckets.get(k);
+        if (!arr) {
+            arr = [];
+            buckets.set(k, arr);
+        }
+        arr.push(it);
+    }
+    const orderedItems = [];
+    const groups = [];
+    const showCount = group.showCount !== false;
+    let start = 0;
+    for (const [k, rows] of buckets) {
+        const label = group.getGroupLabel ? group.getGroupLabel(rows[0][group.groupBy], rows) : k;
+        groups.push({
+            key: k,
+            name: showCount ? `${label} (${rows.length})` : label,
+            startIndex: start,
+            count: rows.length,
+            level: 0,
+            isCollapsed: group.collapsedByDefault ?? false,
+        });
+        orderedItems.push(...rows);
+        start += rows.length;
+    }
+    return { orderedItems, groups };
+}
+
+function mapSelectionMode$1(mode) {
+    return mode === 'multiple' ? SelectionMode.multiple : mode === 'single' ? SelectionMode.single : SelectionMode.none;
+}
+// Approx. widths used to left-align a group subtotal under its rows (column
+// alignment under justified layout is approximate — see GridAggregateFooter).
+const SELECTION_COLUMN_WIDTH = 48;
+const GROUP_CHEVRON_WIDTH = 36;
+/**
+ * Grouped grid host. Buckets rows by `group.groupBy` into a contiguous,
+ * ordered list and renders a Fluent v8 grouped `DetailsList` (collapsible
+ * groups + count badges), reusing the same columns/registry as `<DataGrid>`.
+ */
+function GroupedGrid(props) {
+    const { items, columns, group, selectionMode = 'none', isLoading, pagination, onPageChange, aggregateItems, toolbar, compact, alternateRowColors, fill, height, rowCommands } = props;
+    const edit = useEditState();
+    const { ctx } = useGridContext(props, edit);
+    const dlColumns = useMemo(() => toDetailsListColumns(columns, ctx), [columns, ctx]);
+    // Per-row right-click menu (DetailsList path, same as DataGrid/NestedInline). No-op when
+    // rowCommands is unset (onItemContextMenu is undefined → no handler attached).
+    const { onItemContextMenu, contextMenuElement } = useRowContextMenu(rowCommands);
+    // Bucket by groupBy → ordered items + IGroup[] (DetailsList needs contiguous
+    // group ranges). See buildGroups (pure + unit-tested).
+    const { orderedItems, groups } = useMemo(() => buildGroups(items, group), [items, group]);
+    const hasAggregate = columns.some((c) => c.aggregate);
+    // Per-group subtotals: aggregate each group's slice (keyed by group key).
+    const groupAggregates = useMemo(() => group.showGroupAggregates && hasAggregate
+        ? computeGroupAggregates(orderedItems, groups.map((g) => ({ key: g.key, startIndex: g.startIndex, count: g.count })), columns)
+        : {}, [group.showGroupAggregates, hasAggregate, orderedItems, groups, columns]);
+    // Overall footer source: all displayed groups by default, or the full
+    // `aggregateItems` dataset for cross-page grand totals. Note: per-group subtotals
+    // always aggregate the displayed (page) rows of each group — only the overall
+    // footer goes cross-page.
+    const footerItems = aggregateItems ?? orderedItems;
+    // Approx. left offset for a group subtotal: selection checkbox + group-expand chevron.
+    const groupLeadingSpacer = (selectionMode !== 'none' ? SELECTION_COLUMN_WIDTH : 0) + GROUP_CHEVRON_WIDTH;
+    // Alt-row tint (file-drop isn't supported on grouped grids). Striping is by the
+    // flattened row index across groups.
+    const onRenderRow = useMemo(() => alternateRowColors
+        ? (rowProps, defaultRender) => {
+            if (!rowProps || !defaultRender)
+                return null;
+            return defaultRender({
+                ...rowProps,
+                styles: {
+                    root: {
+                        backgroundColor: rowProps.itemIndex % 2 === 0 ? alternateRowColors.even : alternateRowColors.odd,
+                    },
+                },
+            });
+        }
+        : undefined, [alternateRowColors]);
+    return (jsxs(Stack, { styles: fillStackStyles(fill, height), children: [toolbar && jsx(GridToolbar, { config: toolbar }), jsx(FillRegion, { fill: fill, children: jsx(ShimmeredDetailsList, { items: orderedItems, columns: dlColumns, groups: groups, selectionMode: mapSelectionMode$1(selectionMode), layoutMode: DetailsListLayoutMode.justified, compact: compact, setKey: "grid-kit-grouped", onRenderRow: onRenderRow, onItemContextMenu: onItemContextMenu, styles: getDetailsListStyles(), ariaLabelForGrid: "Grouped grid", groupProps: {
+                        showEmptyGroups: false,
+                        // Render a subtotal under each EXPANDED group. Fluent v8 calls the group
+                        // footer renderer even for collapsed groups, so guard on isCollapsed —
+                        // otherwise a subtotal floats under a collapsed header whose rows are hidden.
+                        onRenderFooter: group.showGroupAggregates && hasAggregate
+                            ? (gprops) => gprops?.group && !gprops.group.isCollapsed ? (jsx(AggregateRow, { columns: columns, aggregates: groupAggregates[gprops.group.key] ?? {}, leadingSpacer: groupLeadingSpacer, background: "#f3f2f1" })) : null
+                            : undefined,
+                    }, enableShimmer: isLoading }) }), contextMenuElement, hasAggregate && (jsx(GridAggregateFooter, { items: footerItems, columns: columns, leadingSpacer: selectionMode !== 'none' ? 48 : 0 })), pagination && jsx(GridPaginationFooter, { pagination: pagination, onPageChange: onPageChange })] }));
+}
+
+/**
+ * Lazily resolves a nested grid's children per parent row. `getChildren` may
+ * return a sync array or a promise; results are cached by row key. grid-kit
+ * never fetches — this just normalizes the consumer-supplied resolver and tracks
+ * loading. Call `ensure(key, parent)` on demand (row expand / panel open / hover).
+ */
+function useChildren(getChildren) {
+    const [cache, setCache] = useState({});
+    const cacheRef = useRef(cache);
+    cacheRef.current = cache;
+    // Guard against setState after unmount (e.g. host swapped while a child fetch
+    // is in flight) — mirrors NestedTriggerCell / DetailPaneChildren.
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const ensure = useCallback((key, parent) => {
+        if (cacheRef.current[key])
+            return;
+        const result = getChildren(parent);
+        if (Array.isArray(result)) {
+            setCache((p) => ({ ...p, [key]: { loading: false, rows: result } }));
+        }
+        else {
+            setCache((p) => ({ ...p, [key]: { loading: true, rows: [] } }));
+            Promise.resolve(result).then((rows) => {
+                if (mounted.current)
+                    setCache((p) => ({ ...p, [key]: { loading: false, rows } }));
+            });
+        }
+    }, [getChildren]);
+    const get = useCallback((key) => cache[key], [cache]);
+    return { get, ensure };
+}
+
+// Leading control-column widths the parent footer must skip to line up its cells
+// with the data columns: the selection checkbox (Fluent default ~48px, present
+// only when the parent grid is selectable) and the always-present expand chevron.
+const SELECTION_CHECKBOX_WIDTH = 48;
+const EXPAND_CHEVRON_WIDTH = 32;
+function mapSelectionMode(mode) {
+    return mode === 'multiple' ? SelectionMode.multiple : mode === 'single' ? SelectionMode.single : SelectionMode.none;
+}
+/**
+ * Inline nested grid: a chevron column expands each parent row to reveal its
+ * child grid indented beneath (Fluent `onRenderRow`). Children resolve lazily on
+ * first expand.
+ *
+ * Known limitation: an expanded row's height varies with its child grid, which
+ * defeats Fluent v8 DetailsList row-height virtualization — fine for typical
+ * subgrid sizes; for very large parent lists prefer side-panel / hover-callout.
+ */
+function NestedInline(props) {
+    const { parentProps, ctx, getKeyFn } = props;
+    const { items, columns, nested, selectionMode, isLoading, compact, alternateRowColors, pagination, onPageChange, aggregateItems, onSelectionChanged, rowCommands, } = parentProps;
+    const { onItemContextMenu, contextMenuElement } = useRowContextMenu(rowCommands);
+    const [expanded, setExpanded] = useState(new Set());
+    const { get, ensure } = useChildren(nested.getChildren);
+    // Forward parent-row selection to the consumer (DataGrid does this; inline did
+    // not). A ref keeps the once-created Selection's callback from going stale when
+    // the prop changes (mirrors DataGrid's onSelectionChangedRef).
+    const onSelectionChangedRef = useRef(onSelectionChanged);
+    onSelectionChangedRef.current = onSelectionChanged;
+    // 'requires-parent' gating: a parent's child grid is only selectable while the
+    // parent row is selected. Needs a managed parent Selection (the parent grid
+    // must be selectable). Tracks selected parent keys to re-gate children on change.
+    const gating = nested.childSelectionGating ?? 'independent';
+    const parentSelectable = mapSelectionMode(selectionMode) !== SelectionMode.none;
+    const [selectedParentKeys, setSelectedParentKeys] = useState(new Set());
+    const selectionRef = useRef();
+    if (!selectionRef.current) {
+        selectionRef.current = new Selection({
+            getKey: (it, index) => it == null ? `__shimmer_${index ?? 0}` : getKeyFn(it),
+            onSelectionChanged: () => {
+                const sel = selectionRef.current.getSelection();
+                setSelectedParentKeys(new Set(sel.map((it) => getKeyFn(it))));
+                onSelectionChangedRef.current?.(sel);
+            },
+        });
+    }
+    // Surface the silent misconfiguration: gating needs a selectable parent grid.
+    React.useEffect(() => {
+        if (gating === 'requires-parent' && !parentSelectable && typeof console !== 'undefined') {
+            console.warn("[grid-kit] childSelectionGating 'requires-parent' has no effect: the parent grid is not selectable. Set the nested grid's selectionMode to 'single' or 'multiple'.");
+        }
+    }, [gating, parentSelectable]);
+    const toggle = useCallback((key, item) => {
+        setExpanded((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else {
+                next.add(key);
+                ensure(key, item);
+            }
+            return next;
+        });
+    }, [ensure]);
+    const dlColumns = useMemo(() => {
+        const chevron = {
+            key: '__expand',
+            name: '',
+            fieldName: '__expand',
+            minWidth: 32,
+            maxWidth: 32,
+            isResizable: false,
+            onRender: (item) => {
+                if (!item)
+                    return null;
+                const key = getKeyFn(item);
+                const open = expanded.has(key);
+                return (jsx(IconButton, { iconProps: { iconName: open ? 'ChevronDown' : 'ChevronRight' }, ariaLabel: open ? 'Collapse' : 'Expand', styles: { root: { height: 28, width: 28 } }, onClick: (e) => {
+                        e.stopPropagation();
+                        toggle(key, item);
+                    } }));
+            },
+        };
+        return [chevron, ...toDetailsListColumns(columns, ctx)];
+    }, [columns, ctx, expanded, getKeyFn, toggle]);
+    const onRenderRow = useCallback((rowProps, defaultRender) => {
+        if (!rowProps || !defaultRender)
+            return null;
+        const parent = rowProps.item;
+        const key = getKeyFn(parent);
+        // Tint the parent row only (not the expansion wrapper) — pass fresh styles.
+        const row = alternateRowColors
+            ? defaultRender({
+                ...rowProps,
+                styles: {
+                    root: {
+                        backgroundColor: rowProps.itemIndex % 2 === 0 ? alternateRowColors.even : alternateRowColors.odd,
+                    },
+                },
+            })
+            : defaultRender(rowProps);
+        if (!expanded.has(key))
+            return row;
+        const entry = get(key);
+        // requires-parent: child selectable only while THIS parent row is selected.
+        const childMode = gating === 'requires-parent' && !selectedParentKeys.has(key) ? 'none' : nested.childSelectionMode;
+        return (jsxs("div", { children: [row, jsx("div", { onContextMenu: (e) => e.stopPropagation(), style: { padding: '8px 8px 8px 48px', background: '#faf9f8', borderBottom: '1px solid #edebe9' }, children: !entry || entry.loading ? (jsx(Spinner, { label: "Loading related records\u2026" })) : (jsx(DataGrid, { items: entry.rows, columns: nested.childColumns, registry: nested.childRegistry, compact: true, selectionMode: childMode, onSelectionChanged: nested.onChildSelectionChanged
+                            ? (sel) => nested.onChildSelectionChanged(parent, sel)
+                            : undefined, editable: nested.childEditable, editTrigger: nested.childEditTrigger, onValueChange: nested.onChildValueChange
+                            ? (rk, fn, v, ov) => nested.onChildValueChange(parent, rk, fn, v, ov)
+                            : undefined })) })] }));
+    }, [expanded, get, getKeyFn, nested, alternateRowColors, gating, selectedParentKeys]);
+    // Parent-level footers (mirrors DataGrid): aggregate row when any parent column
+    // declares an `aggregate`, then the pager. Aggregates over `aggregateItems`
+    // (cross-page grand totals) when given, else the displayed parent rows. The
+    // footer cells skip the selection checkbox + expand chevron so they line up
+    // with the data columns.
+    const hasAggregate = columns.some((c) => c.aggregate);
+    const footerLeadingSpacer = (parentSelectable ? SELECTION_CHECKBOX_WIDTH : 0) + EXPAND_CHEVRON_WIDTH;
+    return (jsxs(Fragment, { children: [jsx(ShimmeredDetailsList, { items: items, columns: dlColumns, onRenderRow: onRenderRow, selectionMode: mapSelectionMode(selectionMode), selection: parentSelectable ? selectionRef.current : undefined, enableShimmer: isLoading, layoutMode: DetailsListLayoutMode.justified, compact: compact, setKey: "grid-kit-nested-inline", getKey: (it, index) => (it == null ? `__shimmer_${index ?? 0}` : getKeyFn(it)), onItemContextMenu: onItemContextMenu, styles: getDetailsListStyles(), ariaLabelForGrid: "Nested grid" }), contextMenuElement, hasAggregate && (jsx(GridAggregateFooter, { items: aggregateItems ?? items, columns: columns, leadingSpacer: footerLeadingSpacer })), pagination && jsx(GridPaginationFooter, { pagination: pagination, onPageChange: onPageChange })] }));
+}
+
+/**
+ * Card-parent nested grid (`parentLayout: 'cards'`): each parent row renders as a
+ * card that expands IN PLACE to reveal its child grid below the card fields. Reuses
+ * the shared card layout (`resolveCardLayout` + classes) for the card body and the
+ * lazy `useChildren` hook for child resolution (grid-kit never fetches). v8-only.
+ *
+ * `nested.mode` does NOT apply to card parents — `<NestedGrid>` routes here on
+ * `parentLayout === 'cards'` BEFORE the mode discriminator, so the side-panel /
+ * hover-callout trigger machinery is bypassed.
+ *
+ * v1 limitation: `childSelectionGating: 'requires-parent'` is unsupported here — cards
+ * use a manual checkbox `Set`, not a Fluent DetailsList `Selection` to gate against —
+ * so it's treated as `'independent'` with a one-time `console.warn`.
+ */
+function NestedCardParent(props) {
+    const { parentProps, ctx, getKeyFn } = props;
+    const { items, columns, nested, selectionMode = 'none', onSelectionChanged, toolbar, pagination, onPageChange, aggregateItems, fill, height, rowCommands, } = parentProps;
+    // Per-row right-click menu (parity with DataGrid/NestedInline). For these raw-div
+    // cards we invoke the hook fn from a native onContextMenu and suppress the browser
+    // menu with e.preventDefault() ourselves (the hook's `return false` only matters to
+    // Fluent's DetailsList onItemContextMenu contract).
+    const { onItemContextMenu, contextMenuElement } = useRowContextMenu(rowCommands);
+    const { cardsPerRow, titleField, subtitleField, imageField, cardHeight, byField, bodyColumns } = useMemo(() => resolveCardLayout(columns, nested.parentCard), [columns, nested.parentCard]);
+    // Parent footers (parity with NestedInline / CardGrid): aggregate row when any
+    // parent column declares an `aggregate`, then the pager. No DetailsList leading
+    // control columns on a card grid, so the aggregate footer has no leading spacer.
+    const hasAggregate = columns.some((c) => c.aggregate);
+    const [selected, setSelected] = useState(new Set());
+    const [expanded, setExpanded] = useState(new Set());
+    const { get, ensure } = useChildren(nested.getChildren);
+    // requires-parent gating needs a Fluent Selection over the parent rows; cards have
+    // none, so surface the unsupported config and fall back to independent selection.
+    React.useEffect(() => {
+        if (nested.childSelectionGating === 'requires-parent' && typeof console !== 'undefined') {
+            console.warn("[grid-kit] childSelectionGating 'requires-parent' is unsupported for card parents (cards have no Fluent Selection); treating as 'independent'.");
+        }
+    }, [nested.childSelectionGating]);
+    const renderField = (col, item) => {
+        if (!col)
+            return null;
+        const cellProps = buildCellProps(col, item, ctx);
+        const Renderer = ctx.registry.resolve(col, false); // cards render read-only
+        return jsx(Renderer, { ...cellProps });
+    };
+    const rawValue = (item, field) => {
+        if (!field)
+            return '';
+        const v = item[field];
+        return v == null ? '' : String(v);
+    };
+    const toggleSelect = (item, checked) => {
+        const key = getKeyFn(item);
+        setSelected((prev) => {
+            const next = new Set(selectionMode === 'single' ? [] : prev);
+            if (checked)
+                next.add(key);
+            else
+                next.delete(key);
+            onSelectionChanged?.(items.filter((it) => next.has(getKeyFn(it))));
+            return next;
+        });
+    };
+    const toggleExpand = useCallback((key, item) => {
+        setExpanded((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else {
+                next.add(key);
+                ensure(key, item);
+            }
+            return next;
+        });
+    }, [ensure]);
+    return (jsxs(Stack, { styles: fillStackStyles(fill, height), children: [toolbar && jsx(GridToolbar, { config: toolbar }), jsx(FillRegion, { fill: fill, children: jsx("div", { style: {
+                        display: 'grid',
+                        gridTemplateColumns: `repeat(${cardsPerRow}, minmax(0, 1fr))`,
+                        gap: 12,
+                        paddingTop: 4,
+                    }, children: items.map((item) => {
+                        const key = getKeyFn(item);
+                        const open = expanded.has(key);
+                        const entry = open ? get(key) : undefined;
+                        return (jsxs("div", { className: cardClass, style: cardHeight ? { height: cardHeight } : undefined, onClick: () => toggleExpand(key, item), 
+                            // Right-click anywhere on the card opens its row menu. The card is the
+                            // row-equivalent target, so the title/body cells, chevron, and checkbox
+                            // below keep only their onClick stopPropagation — a right-click on them
+                            // intentionally bubbles here (preventDefault suppresses the browser/anchor
+                            // menu). Do NOT add onContextMenu guards there or the menu dies on cells.
+                            // The expanded child region DOES stop it (see below).
+                            onContextMenu: onItemContextMenu
+                                ? (e) => {
+                                    e.preventDefault();
+                                    onItemContextMenu(item, undefined, e.nativeEvent);
+                                }
+                                : undefined, children: [jsxs(Stack, { horizontal: true, horizontalAlign: "space-between", verticalAlign: "start", children: [jsxs(Stack, { horizontal: true, verticalAlign: "center", tokens: { childrenGap: 4 }, children: [jsx(IconButton, { iconProps: { iconName: open ? 'ChevronDown' : 'ChevronRight' }, ariaLabel: open ? 'Collapse' : 'Expand', styles: { root: { height: 24, width: 24 } }, onClick: (e) => {
+                                                        e.stopPropagation();
+                                                        toggleExpand(key, item);
+                                                    } }), jsx(Text, { variant: "mediumPlus", styles: { root: { fontWeight: 600 } }, children: jsx("span", { onClick: (e) => e.stopPropagation(), children: renderField(byField.get(titleField ?? ''), item) ?? rawValue(item, titleField) }) })] }), selectionMode !== 'none' && (
+                                        // Stop the click from bubbling to the card's expand toggle.
+                                        jsx("span", { onClick: (e) => e.stopPropagation(), children: jsx(Checkbox, { checked: selected.has(key), onChange: (_, checked) => toggleSelect(item, checked), ariaLabel: "Select card" }) }))] }), imageField && rawValue(item, imageField) && (jsx("img", { className: cardImageClass, src: rawValue(item, imageField), alt: "" })), subtitleField && (jsx(Text, { variant: "small", styles: { root: { color: '#605e5c' } }, children: rawValue(item, subtitleField) })), bodyColumns.map((col) => (jsxs("div", { className: bodyRowClass, children: [jsx(Text, { variant: "small", styles: { root: { color: '#605e5c' } }, children: col.name }), jsx("span", { onClick: (e) => e.stopPropagation(), children: renderField(col, item) })] }, col.key))), open && (jsx("div", { style: { paddingTop: 8, marginTop: 4, borderTop: '1px solid #edebe9' }, onClick: (e) => e.stopPropagation(), 
+                                    // The child <DataGrid> renders INSIDE this card's DOM, so a right-click
+                                    // on a child row would otherwise bubble to the card's onContextMenu and
+                                    // fire the PARENT card's menu for the wrong record (the #93 / 2a8ff381
+                                    // lesson; mirrors NestedInline's inline child-region guard). Children
+                                    // have no own menu in v1 → the native browser menu is left intact here.
+                                    onContextMenu: (e) => e.stopPropagation(), children: !entry || entry.loading ? (jsx(Spinner, { label: "Loading related records\u2026" })) : (jsx(DataGrid, { items: entry.rows, columns: nested.childColumns, registry: nested.childRegistry, compact: true, selectionMode: nested.childSelectionMode, onSelectionChanged: nested.onChildSelectionChanged
+                                            ? (sel) => nested.onChildSelectionChanged(item, sel)
+                                            : undefined, editable: nested.childEditable, editTrigger: nested.childEditTrigger, onValueChange: nested.onChildValueChange
+                                            ? (rk, fn, v, ov) => nested.onChildValueChange(item, rk, fn, v, ov)
+                                            : undefined })) }))] }, key));
+                    }) }) }), hasAggregate && (jsx(GridAggregateFooter, { items: aggregateItems ?? items, columns: columns, leadingSpacer: 0 })), pagination && jsx(GridPaginationFooter, { pagination: pagination, onPageChange: onPageChange }), contextMenuElement] }));
+}
+
+/**
+ * Resolve a nested trigger label, substituting the `{count}` token. When the
+ * count isn't known yet (children not loaded), the token is dropped and extra
+ * whitespace collapsed (e.g. "View {count} related" → "View related").
+ */
+function formatTriggerLabel(label, count) {
+    const base = label ?? 'View {count} related';
+    if (count === undefined) {
+        return base.replace(/\{count\}\s*/g, '').replace(/\s+/g, ' ').trim();
+    }
+    return base.replace(/\{count\}/g, String(count));
+}
+/** Map a side-panel size token to a Fluent v8 `PanelType`. */
+function panelTypeFor(size) {
+    return size === 'small' ? PanelType.smallFixedFar : size === 'large' ? PanelType.large : PanelType.medium;
+}
+
+/**
+ * Per-parent-row trigger cell for `side-panel` and `hover-callout` nested modes.
+ * Children are resolved **lazily** — on click (panel) or first hover (callout) —
+ * so a 50-row page doesn't fire 50 fetches up front.
+ */
+function NestedTriggerCell(props) {
+    const { parent, nested } = props;
+    const [entry, setEntry] = useState(null);
+    const [open, setOpen] = useState(false);
+    const [hovered, setHovered] = useState(false);
+    const hostRef = useRef(null);
+    const hoverTimer = useRef();
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            if (hoverTimer.current)
+                clearTimeout(hoverTimer.current);
+        };
+    }, []);
+    // Resolve children once, on demand.
+    const load = useCallback(() => {
+        setEntry((prev) => {
+            if (prev)
+                return prev;
+            const result = nested.getChildren(parent);
+            if (Array.isArray(result))
+                return { loading: false, rows: result };
+            Promise.resolve(result).then((rows) => mounted.current && setEntry({ loading: false, rows }));
+            return { loading: true, rows: [] };
+        });
+    }, [parent, nested]);
+    const count = entry && !entry.loading ? entry.rows.length : undefined;
+    if (nested.mode === 'hover-callout') {
+        const max = nested.calloutMaxRows ?? 5;
+        const preview = entry ? entry.rows.slice(0, max) : [];
+        return (jsxs("div", { ref: hostRef, style: { display: 'inline-block' }, onMouseEnter: () => {
+                load();
+                hoverTimer.current = setTimeout(() => mounted.current && setHovered(true), nested.hoverDelay ?? 300);
+            }, onMouseLeave: () => {
+                if (hoverTimer.current)
+                    clearTimeout(hoverTimer.current);
+                setHovered(false);
+            }, children: [jsx(Text, { variant: "small", styles: { root: { background: '#edebe9', borderRadius: 10, padding: '2px 10px', cursor: 'default' } }, children: entry?.loading ? '…' : count !== undefined ? `${count} related` : 'related' }), hovered && entry && !entry.loading && entry.rows.length > 0 && (jsx(Callout, { target: hostRef.current, onDismiss: () => setHovered(false), directionalHint: DirectionalHint.bottomLeftEdge, isBeakVisible: false, gapSpace: 4, children: jsxs("div", { style: { padding: 8, minWidth: 360, maxWidth: 560 }, children: [jsx(ReadOnlyGrid, { items: preview, columns: nested.childColumns, registry: nested.childRegistry, compact: true }), entry.rows.length > max && (jsxs(Text, { variant: "small", styles: { root: { color: '#605e5c', paddingTop: 4 } }, children: ["+", entry.rows.length - max, " more"] }))] }) }))] }));
+    }
+    // side-panel (default for triggered modes) — fetch on open.
+    const label = formatTriggerLabel(nested.triggerLabel, count);
+    return (jsxs(Fragment, { children: [jsx(ActionButton, { iconProps: { iconName: nested.triggerIcon ?? 'OpenPaneMirrored' }, onClick: () => {
+                    load();
+                    setOpen(true);
+                }, styles: { root: { height: 28 } }, children: label }), jsx(Panel, { isOpen: open, onDismiss: () => setOpen(false), type: panelTypeFor(nested.panelSize), headerText: label, closeButtonAriaLabel: "Close", children: !entry || entry.loading ? (jsx(Spinner, { label: "Loading related records\u2026" })) : (jsx(DataGrid, { items: entry.rows, columns: nested.childColumns, registry: nested.childRegistry, compact: true, selectionMode: nested.childSelectionMode, onSelectionChanged: nested.onChildSelectionChanged ? (sel) => nested.onChildSelectionChanged(parent, sel) : undefined, editable: nested.childEditable, editTrigger: nested.childEditTrigger, onValueChange: nested.onChildValueChange
+                        ? (rk, fn, v, ov) => nested.onChildValueChange(parent, rk, fn, v, ov)
+                        : undefined })) })] }));
+}
+
+/**
+ * Nested / expandable grid host. Dispatch order:
+ * 1. `parentLayout === 'cards'` — each parent is a card that expands in place
+ *    (`<NestedCardParent>`); `mode` is ignored.
+ * Otherwise, parents are rows and child records surface per `nested.mode`:
+ * - `inline`        — chevron expands the child grid under the row
+ * - `side-panel`    — a trigger opens a Fluent Panel with the child grid
+ * - `hover-callout` — a count badge shows a compact callout of top-N rows
+ * - `detail-pane`   — falls back to `side-panel` here (use `<FocusedViewGrid>`
+ *                     for true master-detail with a detail-pane child)
+ *
+ * grid-kit never fetches — `nested.getChildren(parent)` (sync or async) owns it.
+ */
+function NestedGrid(props) {
+    const { columns, nested } = props;
+    const edit = useEditState();
+    const { getKeyFn, ctx } = useGridContext(props, edit);
+    // Append a trigger column for the non-inline modes (its cell manages its own
+    // panel/callout). Built before any early return to keep hook order stable.
+    const triggeredColumns = useMemo(() => {
+        const trigger = {
+            key: '__nested',
+            fieldName: '__nested',
+            name: 'Related',
+            rendererType: 'text',
+            minWidth: 160,
+            onRender: (item) => jsx(NestedTriggerCell, { parent: item, nested: nested }),
+        };
+        return [...columns, trigger];
+    }, [columns, nested]);
+    // Card parents win over `mode`: each parent renders as a card that expands in place.
+    if (nested.parentLayout === 'cards') {
+        return jsx(NestedCardParent, { parentProps: props, ctx: ctx, getKeyFn: getKeyFn });
+    }
+    if (nested.mode === 'inline') {
+        return jsx(NestedInline, { parentProps: props, ctx: ctx, getKeyFn: getKeyFn });
+    }
+    // side-panel, hover-callout (and detail-pane fallback) → DataGrid + trigger column
+    return jsx(DataGrid, { ...props, columns: triggeredColumns });
+}
+
+const railClass = mergeStyles({ width: 320, minWidth: 260, borderRight: '1px solid #edebe9', overflowY: 'auto' });
+const railItemBase = {
+    padding: '10px 12px',
+    borderBottom: '1px solid #f3f2f1',
+    cursor: 'pointer',
+    display: 'flex',
+    gap: 10,
+    alignItems: 'flex-start',
+};
+const detailRowClass = mergeStyles({
+    display: 'flex',
+    justifyContent: 'space-between',
+    gap: 12,
+    padding: '6px 0',
+    borderBottom: '1px solid #f3f2f1',
+    fontSize: 13,
+});
+/**
+ * Focused-view / master-detail host. A left rail of summary items (each rendered
+ * from `focusedView.rows`) drives a right detail pane (the active record's
+ * `detailFields`, each value through the registry). When a `nested` config with
+ * `mode: 'detail-pane'` is supplied, the child grid renders inside the pane.
+ */
+function FocusedViewGrid(props) {
+    const { items, columns, focusedView, nested, onActiveItemChanged, fill, height, rowCommands } = props;
+    // The detail pane renders read-only (registry.resolve(col, false)); useEditState
+    // is threaded only because useGridContext bundles it — no inline editing here.
+    const edit = useEditState();
+    const { getKeyFn, ctx } = useGridContext(props, edit);
+    // Per-row right-click menu on the left rail (parity with DataGrid/NestedInline). The
+    // rail items are raw divs, so we invoke the hook fn from a native onContextMenu and
+    // suppress the browser menu with e.preventDefault() (the hook's `return false` only
+    // matters to Fluent's DetailsList contract). No child stopPropagation is needed: the
+    // detail pane is a SIBLING of the rail (not nested inside a rail item), unlike the
+    // inline child grids in NestedInline / NestedCardParent.
+    const { onItemContextMenu, contextMenuElement } = useRowContextMenu(rowCommands);
+    const [activeKey, setActiveKey] = useState(() => (items[0] ? getKeyFn(items[0]) : undefined));
+    const [search, setSearch] = useState('');
+    const byField = useMemo(() => {
+        const m = new Map();
+        columns.forEach((c) => m.set(c.fieldName, c));
+        return m;
+    }, [columns]);
+    const filtered = useMemo(() => {
+        const q = search.trim().toLowerCase();
+        if (!q)
+            return items;
+        const fields = focusedView.rows.flatMap((r) => [r.primaryField.fieldName, r.secondaryField?.fieldName].filter(Boolean));
+        return items.filter((it) => fields.some((f) => String(getFieldValue(it, f) ?? '').toLowerCase().includes(q)));
+    }, [items, search, focusedView.rows]);
+    const active = useMemo(() => items.find((it) => getKeyFn(it) === activeKey), [items, activeKey, getKeyFn]);
+    const detailColumns = useMemo(() => {
+        if (!focusedView.detailFields)
+            return columns;
+        return focusedView.detailFields.map((f) => byField.get(f)).filter(Boolean);
+    }, [focusedView.detailFields, byField, columns]);
+    const fieldText = (item, field) => {
+        if (!field)
+            return '';
+        const v = getFieldValue(item, field.fieldName);
+        return v == null ? '' : String(v);
+    };
+    const select = (item) => {
+        setActiveKey(getKeyFn(item));
+        onActiveItemChanged?.(item);
+    };
+    const renderDetailValue = (col, item) => {
+        const cellProps = buildCellProps(col, item, ctx);
+        const Renderer = ctx.registry.resolve(col, false);
+        return jsx(Renderer, { ...cellProps });
+    };
+    return (jsxs(Fragment, { children: [jsxs(Stack, { horizontal: true, styles: { root: { border: '1px solid #edebe9', borderRadius: 4, height: height ?? (fill ? '100%' : 460) } }, children: [jsxs("div", { className: railClass, children: [jsx("div", { style: { padding: 8, borderBottom: '1px solid #edebe9' }, children: jsx(SearchBox, { placeholder: "Search", onChange: (_, v) => setSearch(v ?? ''), underlined: true }) }), filtered.map((item) => {
+                                const key = getKeyFn(item);
+                                const isActive = key === activeKey;
+                                return (jsxs("div", { style: { ...railItemBase, background: isActive ? '#e1efff' : undefined, borderLeft: isActive ? '3px solid #0078d4' : '3px solid transparent' }, onClick: () => select(item), onContextMenu: onItemContextMenu
+                                        ? (e) => {
+                                            e.preventDefault();
+                                            onItemContextMenu(item, undefined, e.nativeEvent);
+                                        }
+                                        : undefined, children: [focusedView.rows[0]?.iconName && jsx(Icon, { iconName: focusedView.rows[0].iconName, styles: { root: { fontSize: 18, color: '#0078d4' } } }), jsx(Stack, { tokens: { childrenGap: 2 }, children: focusedView.rows.map((row) => (jsxs("div", { children: [jsx(Text, { variant: "medium", styles: { root: { fontWeight: 600 } }, children: fieldText(item, row.primaryField) }), row.secondaryField && (jsx(Text, { variant: "small", styles: { root: { color: '#605e5c', paddingLeft: 6 } }, children: fieldText(item, row.secondaryField) }))] }, row.id))) })] }, key));
+                            })] }), jsx("div", { style: { flex: 1, padding: 16, overflowY: 'auto' }, children: !active ? (jsx(Text, { variant: "medium", styles: { root: { color: '#605e5c' } }, children: "Select a record to see its details." })) : focusedView.childOnly ? (
+                        // childOnly: the pane IS the related-records grid — no title heading, no
+                        // detail-field list, no "Related" subheading. Pure master/detail.
+                        nested ? (jsx(DetailPaneChildren, { parent: active, nested: nested })) : (jsx(Text, { variant: "medium", styles: { root: { color: '#605e5c' } }, children: "No related records configured." }))) : (jsxs(Stack, { tokens: { childrenGap: 4 }, children: [jsx(Text, { variant: "large", styles: { root: { fontWeight: 600, marginBottom: 8 } }, children: fieldText(active, focusedView.rows[0]?.primaryField) }), detailColumns.map((col) => (jsxs("div", { className: detailRowClass, children: [jsx(Text, { variant: "small", styles: { root: { color: '#605e5c' } }, children: col.name }), jsx("span", { children: renderDetailValue(col, active) })] }, col.key))), nested && nested.mode === 'detail-pane' && (jsxs("div", { style: { paddingTop: 16 }, children: [jsx(Text, { variant: "mediumPlus", styles: { root: { fontWeight: 600 } }, children: "Related" }), jsx(DetailPaneChildren, { parent: active, nested: nested })] }))] })) })] }), contextMenuElement] }));
+}
+/** Resolves + renders the detail-pane child grid for the active record. */
+function DetailPaneChildren(props) {
+    const { parent, nested } = props;
+    const [rows, setRows] = useState(null);
+    React.useEffect(() => {
+        let alive = true;
+        const result = nested.getChildren(parent);
+        if (Array.isArray(result))
+            setRows(result);
+        else {
+            setRows(null);
+            Promise.resolve(result).then((r) => alive && setRows(r));
+        }
+        return () => {
+            alive = false;
+        };
+    }, [parent, nested]);
+    if (rows === null)
+        return jsx(Text, { variant: "small", children: "Loading\u2026" });
+    return (jsx(DataGrid, { items: rows, columns: nested.childColumns, registry: nested.childRegistry, compact: true, selectionMode: nested.childSelectionMode, onSelectionChanged: nested.onChildSelectionChanged ? (sel) => nested.onChildSelectionChanged(parent, sel) : undefined, editable: nested.childEditable, editTrigger: nested.childEditTrigger, onValueChange: nested.onChildValueChange
+            ? (rk, fn, v, ov) => nested.onChildValueChange(parent, rk, fn, v, ov)
+            : undefined }));
+}
+
+export { CardGrid, DataGrid, DataGrid as DetailsGrid, DroppableCell, FileDropCell, FocusedViewGrid, GridColumnChooser, GridExportDialog, GridFilterBuilder, GridToolbar, GroupedGrid, NestedGrid, ReadOnlyGrid, applyFilters, buildCellProps, buildGroups, computeAggregate, computeAggregates, computeFormattedValue, computeGroupAggregates, createCellRegistry, defaultGetKey, evalCondition, exportGrid, fieldTypeForRenderer, fromGridCustomizerColumn, fromGridCustomizerDefinition, getFieldValue, getOperatorsForFieldType, getSuppliedFormattedValue, isConditionComplete, isFileAccepted, makeEditWrapper, makeReadWrapper, mapFormRuntimeRendererType, navigateToTarget, operatorIsMultiValue, operatorRequiresValue, orderVisibleColumns, rendererToFieldType, resolveCellColor, resolveExportColumns, resolveGridFromDefinition, resolveThreshold, toBool, toDate, toDetailsListColumns, toDisplayString, toExportColumns, toGridCustomizerOverrides, toNumber, toReusableColumn, useChildren, useEditState, useFileDrop, useGridContext };
+//# sourceMappingURL=index.esm.js.map