apex-grid 1.1.0 → 2.0.0

package/internal/column-types.js

@@ -0,0 +1,268 @@
+import { html, nothing } from 'lit';
+import { ref } from 'lit/directives/ref.js';
+import { renderIcon } from './icons.js';
+const RATING_DEFAULT_MAX = 5;
+function getRatingMax(column) {
+    const max = typeof column.max === 'number' ? Math.floor(column.max) : RATING_DEFAULT_MAX;
+    return max > 0 ? max : RATING_DEFAULT_MAX;
+}
+function clampRating(value, max) {
+    const n = typeof value === 'number' ? value : Number(value ?? 0);
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > max)
+        return max;
+    return Math.round(n);
+}
+export function getSelectOptions(column) {
+    const raw = column.options ?? [];
+    return raw.map((entry) => {
+        if (entry !== null && typeof entry === 'object' && 'value' in entry) {
+            const opt = entry;
+            return { value: opt.value, label: opt.label ?? String(opt.value) };
+        }
+        return { value: entry, label: String(entry) };
+    });
+}
+const selectType = {
+    display(ctx) {
+        const opts = getSelectOptions(ctx.column);
+        const match = opts.find((o) => o.value === ctx.value);
+        const label = match?.label ?? (ctx.value == null ? '' : String(ctx.value));
+        return html `<span part="select-label">${label}</span>`;
+    },
+    editor(ctx) {
+        const opts = getSelectOptions(ctx.column);
+        const current = ctx.value;
+        const match = opts.find((o) => o.value === current);
+        const label = match?.label ?? (current == null ? '' : String(current));
+        const selectedIdx = Math.max(0, opts.findIndex((o) => o.value === current));
+        const mountPopover = (el) => {
+            if (!el)
+                return;
+            const popover = el;
+            if (popover.dataset.apexFocused)
+                return;
+            popover.dataset.apexFocused = '1';
+            const items = Array.from(popover.querySelectorAll('[part~="select-option"]'));
+            items[selectedIdx]?.focus();
+        };
+        const handleKeydown = (event) => {
+            const target = event.target;
+            const list = target.closest('[part~="select-popover"]');
+            if (!list)
+                return;
+            const items = Array.from(list.querySelectorAll('[part~="select-option"]'));
+            const idx = items.indexOf(target);
+            if (idx < 0)
+                return;
+            if (event.key === 'ArrowDown') {
+                event.preventDefault();
+                event.stopPropagation();
+                items[Math.min(idx + 1, items.length - 1)]?.focus();
+            }
+            else if (event.key === 'ArrowUp') {
+                event.preventDefault();
+                event.stopPropagation();
+                items[Math.max(idx - 1, 0)]?.focus();
+            }
+            else if (event.key === 'Home') {
+                event.preventDefault();
+                event.stopPropagation();
+                items[0]?.focus();
+            }
+            else if (event.key === 'End') {
+                event.preventDefault();
+                event.stopPropagation();
+                items[items.length - 1]?.focus();
+            }
+            else if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                event.stopPropagation();
+                ctx.commit(opts[idx].value);
+            }
+        };
+        return html `<span part="select-label">${label}</span>
+      <div
+        part="select-popover"
+        role="listbox"
+        @keydown=${handleKeydown}
+        ${ref(mountPopover)}
+      >
+        ${opts.map((o, i) => html `<div
+            part=${o.value === current ? 'select-option selected' : 'select-option'}
+            role="option"
+            aria-selected=${o.value === current ? 'true' : 'false'}
+            tabindex=${i === selectedIdx ? '0' : '-1'}
+            data-apex-editor=${i === selectedIdx ? '' : nothing}
+            @click=${() => ctx.commit(o.value)}
+          >
+            ${o.label}
+          </div>`)}
+      </div>`;
+    },
+};
+export function parseDate(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    if (typeof value === 'number') {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    if (typeof value === 'string') {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        if (match) {
+            const [, y, m, d] = match;
+            const date = new Date(Number(y), Number(m) - 1, Number(d));
+            return Number.isNaN(date.getTime()) ? null : date;
+        }
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}
+function toDateInputValue(date) {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, '0');
+    const d = String(date.getDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+}
+function formatDateValue(value, style) {
+    const date = parseDate(value);
+    if (!date)
+        return '';
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: style,
+    }).format(date);
+}
+function commitDateInSameShape(original, next) {
+    if (next === null)
+        return null;
+    if (original instanceof Date)
+        return next;
+    if (typeof original === 'number')
+        return next.getTime();
+    return toDateInputValue(next);
+}
+const dateType = {
+    display(ctx) {
+        const style = ctx.column.format ?? 'medium';
+        return html `${formatDateValue(ctx.value, style)}`;
+    },
+    editor(ctx) {
+        const initial = parseDate(ctx.value);
+        const initialInput = initial ? toDateInputValue(initial) : '';
+        const handleChange = (event) => {
+            const raw = event.target.value;
+            const next = raw ? parseDate(raw) : null;
+            ctx.commit(commitDateInSameShape(ctx.value, next));
+        };
+        const handleKeydown = (event) => {
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                event.stopPropagation();
+                const raw = event.target.value;
+                const next = raw ? parseDate(raw) : null;
+                ctx.commit(commitDateInSameShape(ctx.value, next));
+            }
+        };
+        return html `<input
+      type="date"
+      part="editor"
+      data-apex-editor
+      .value=${initialInput}
+      @change=${handleChange}
+      @keydown=${handleKeydown}
+    />`;
+    },
+};
+const ratingType = {
+    display(ctx) {
+        const max = getRatingMax(ctx.column);
+        const value = clampRating(ctx.value, max);
+        const stars = Array.from({ length: max }, (_, i) => i < value);
+        return html `<span part="rating" role="img" aria-label="${value} of ${max}">
+      ${stars.map((filled) => html `<span part=${filled ? 'rating-star filled' : 'rating-star'} aria-hidden="true">
+            ${renderIcon('star')}
+          </span>`)}
+    </span>`;
+    },
+    editor(ctx) {
+        const max = getRatingMax(ctx.column);
+        const current = clampRating(ctx.value, max);
+        const focusRank = Math.max(current, 1);
+        const commitTo = (next) => ctx.commit(clampRating(next, max));
+        const stars = Array.from({ length: max }, (_, i) => i + 1);
+        return html `<span
+      part="rating-editor"
+      role="radiogroup"
+      aria-label="Rating"
+    >
+      ${stars.map((rank) => html `<button
+          type="button"
+          part=${rank <= current ? 'rating-star filled selected' : 'rating-star'}
+          role="radio"
+          aria-checked=${rank === current}
+          aria-label=${`${rank} of ${max}`}
+          data-rating-value=${rank}
+          data-apex-editor=${rank === focusRank ? '' : nothing}
+          @click=${() => commitTo(rank === current ? 0 : rank)}
+        >
+          ${renderIcon('star')}
+        </button>`)}
+    </span>`;
+    },
+};
+const booleanType = {
+    display(ctx) {
+        const truthy = ctx.value === true;
+        const editable = typeof ctx.commit === 'function';
+        return html `<input
+      type="checkbox"
+      part=${truthy ? 'boolean-mark checked' : 'boolean-mark'}
+      .checked=${truthy}
+      tabindex=${editable ? '0' : '-1'}
+      aria-readonly=${editable ? 'false' : 'true'}
+      aria-label=${truthy ? 'true' : 'false'}
+      @click=${(event) => {
+            event.stopPropagation();
+        }}
+      @change=${editable
+            ? (event) => {
+                const next = event.target.checked;
+                ctx.commit?.(next);
+            }
+            : undefined}
+    />`;
+    },
+};
+const imageType = {
+    display(ctx) {
+        const value = ctx.value;
+        if (value == null || value === '')
+            return html ``;
+        const shape = ctx.column.shape ?? 'square';
+        const colAny = ctx.column;
+        const alt = colAny.alt ?? String(colAny.key ?? '');
+        return html `<img
+      part=${shape === 'circle' ? 'image circle' : 'image'}
+      src=${String(value)}
+      alt=${alt}
+      loading="lazy"
+    />`;
+    },
+};
+const BUILTIN_TYPES = {
+    select: selectType,
+    rating: ratingType,
+    date: dateType,
+    boolean: booleanType,
+    image: imageType,
+};
+export function getColumnTypeRenderer(type) {
+    return type ? BUILTIN_TYPES[type] : undefined;
+}
+//# sourceMappingURL=column-types.js.map

package/internal/column-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-types.js","sourceRoot":"","sources":["../../src/internal/column-types.ts"],"names":[],"mappings":"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","sourcesContent":["import { html, nothing, type TemplateResult } from 'lit';\nimport { ref } from 'lit/directives/ref.js';\nimport type ApexGridCell from '../components/cell.js';\nimport type ApexGridRow from '../components/row.js';\nimport { renderIcon } from './icons.js';\nimport type { ColumnConfiguration } from './types.js';\n\nconst RATING_DEFAULT_MAX = 5;\n\nfunction getRatingMax(column: { max?: number }): number {\n  const max = typeof column.max === 'number' ? Math.floor(column.max) : RATING_DEFAULT_MAX;\n  return max > 0 ? max : RATING_DEFAULT_MAX;\n}\n\nfunction clampRating(value: unknown, max: number): number {\n  const n = typeof value === 'number' ? value : Number(value ?? 0);\n  if (!Number.isFinite(n)) return 0;\n  if (n < 0) return 0;\n  if (n > max) return max;\n  return Math.round(n);\n}\n\n/**\n * An option entry for a `'select'` column. May be either a bare value (the\n * displayed label is `String(value)`) or an explicit `{ value, label }` pair.\n */\nexport type SelectOption<V = unknown> = V | { value: V; label?: string };\n\n/**\n * The flat, non-distributive cell context handed to a column-type renderer's\n * `display` function. Mirrors {@link ApexCellContext} but uses `unknown` for\n * `value` so renderers can author against a single shape without\n * conditional-type narrowing in generic positions.\n */\nexport interface ColumnTypeCellContext<T extends object> {\n  parent: ApexGridCell<T>;\n  row: ApexGridRow<T>;\n  column: ColumnConfiguration<T>;\n  value: unknown;\n  /**\n   * Commits a new value for this cell without entering edit mode. Only\n   * present when the column is editable. Used by interactive display\n   * widgets like the boolean checkbox.\n   */\n  commit?(value: unknown): Promise<boolean>;\n}\n\n/**\n * Cell context handed to a column-type renderer's `editor` function. Adds the\n * `commit` / `cancel` helpers wired through {@link EditingController}.\n */\nexport interface ColumnTypeEditorContext<T extends object> extends ColumnTypeCellContext<T> {\n  commit(value: unknown): Promise<boolean>;\n  cancel(): void;\n}\n\n/**\n * Built-in column-type renderer contract. A renderer can supply either a\n * display template, an editor template, or both. Cells fall back to the\n * column's `cellTemplate` / `editorTemplate` / built-in primitive editor if\n * the renderer is absent.\n */\nexport interface ColumnTypeRenderer<T extends object> {\n  /**\n   * Renders the display (read-only) representation of the cell.\n   *\n   * @remarks\n   * Called when the cell is not in edit mode and the column has no\n   * `cellTemplate`. Return any lit-renderable value.\n   */\n  display?(ctx: ColumnTypeCellContext<T>): TemplateResult | unknown;\n\n  /**\n   * Renders the inline editor while the cell is in edit mode.\n   *\n   * @remarks\n   * Called when the cell is in edit mode and the column has no\n   * `editorTemplate`. The returned template SHOULD include `data-apex-editor`\n   * on its focusable element so the cell auto-focuses it. The editor is\n   * responsible for calling `ctx.commit(value)` / `ctx.cancel()`.\n   */\n  editor?(ctx: ColumnTypeEditorContext<T>): TemplateResult | unknown;\n}\n\ninterface NormalizedSelectOption {\n  value: unknown;\n  label: string;\n}\n\n/**\n * Normalizes a column's `options` configuration into a uniform\n * `{ value, label }[]` list. Accepts both bare-value entries and explicit\n * `{ value, label }` pairs.\n */\nexport function getSelectOptions(column: { options?: SelectOption[] }): NormalizedSelectOption[] {\n  const raw = column.options ?? [];\n  return raw.map((entry) => {\n    if (entry !== null && typeof entry === 'object' && 'value' in entry) {\n      const opt = entry as { value: unknown; label?: string };\n      return { value: opt.value, label: opt.label ?? String(opt.value) };\n    }\n    return { value: entry, label: String(entry) };\n  });\n}\n\nconst selectType: ColumnTypeRenderer<object> = {\n  display(ctx) {\n    const opts = getSelectOptions(ctx.column as { options?: SelectOption[] });\n    const match = opts.find((o) => o.value === ctx.value);\n    const label = match?.label ?? (ctx.value == null ? '' : String(ctx.value));\n    // Closed-state display is intentionally plain text — the cell reads as\n    // a normal value cell until the user double-clicks to edit. The\n    // dropdown affordance appears only in edit mode (the listbox popover).\n    return html`<span part=\"select-label\">${label}</span>`;\n  },\n\n  editor(ctx) {\n    const opts = getSelectOptions(ctx.column as { options?: SelectOption[] });\n    const current = ctx.value;\n    const match = opts.find((o) => o.value === current);\n    const label = match?.label ?? (current == null ? '' : String(current));\n    const selectedIdx = Math.max(\n      0,\n      opts.findIndex((o) => o.value === current)\n    );\n\n    // The popover is rendered as a `position: absolute` child of the cell\n    // (the cell host is `position: relative`). That positions it relative\n    // to the cell regardless of how the row is laid out — important\n    // because the virtualizer applies `transform: translate` to each row,\n    // which would re-anchor a `position: fixed` descendant onto the row.\n    // The cell-level SCSS lifts `overflow: hidden` for select-type editing\n    // cells so the popover can extend below the cell's box.\n    const mountPopover = (el: Element | undefined) => {\n      if (!el) return;\n      const popover = el as HTMLElement;\n      if (popover.dataset.apexFocused) return;\n      popover.dataset.apexFocused = '1';\n      const items = Array.from(popover.querySelectorAll<HTMLElement>('[part~=\"select-option\"]'));\n      items[selectedIdx]?.focus();\n    };\n\n    const handleKeydown = (event: KeyboardEvent) => {\n      const target = event.target as HTMLElement;\n      const list = target.closest('[part~=\"select-popover\"]') as HTMLElement | null;\n      if (!list) return;\n      const items = Array.from(list.querySelectorAll<HTMLElement>('[part~=\"select-option\"]'));\n      const idx = items.indexOf(target);\n      if (idx < 0) return;\n      if (event.key === 'ArrowDown') {\n        event.preventDefault();\n        event.stopPropagation();\n        items[Math.min(idx + 1, items.length - 1)]?.focus();\n      } else if (event.key === 'ArrowUp') {\n        event.preventDefault();\n        event.stopPropagation();\n        items[Math.max(idx - 1, 0)]?.focus();\n      } else if (event.key === 'Home') {\n        event.preventDefault();\n        event.stopPropagation();\n        items[0]?.focus();\n      } else if (event.key === 'End') {\n        event.preventDefault();\n        event.stopPropagation();\n        items[items.length - 1]?.focus();\n      } else if (event.key === 'Enter' || event.key === ' ') {\n        event.preventDefault();\n        event.stopPropagation();\n        ctx.commit(opts[idx].value);\n      }\n      // Escape / Tab fall through to the cell-level handler which cancels /\n      // exits — we don't consume them here so the standard exit flow applies.\n    };\n\n    return html`<span part=\"select-label\">${label}</span>\n      <div\n        part=\"select-popover\"\n        role=\"listbox\"\n        @keydown=${handleKeydown}\n        ${ref(mountPopover)}\n      >\n        ${opts.map(\n          (o, i) => html`<div\n            part=${o.value === current ? 'select-option selected' : 'select-option'}\n            role=\"option\"\n            aria-selected=${o.value === current ? 'true' : 'false'}\n            tabindex=${i === selectedIdx ? '0' : '-1'}\n            data-apex-editor=${i === selectedIdx ? '' : nothing}\n            @click=${() => ctx.commit(o.value)}\n          >\n            ${o.label}\n          </div>`\n        )}\n      </div>`;\n  },\n};\n\n/**\n * Parses a stored cell value into a `Date`, or `null` when the value can't be\n * resolved to a real date.\n *\n * @remarks\n * Accepts `Date` instances, ISO/parseable strings, and millisecond\n * timestamps. `YYYY-MM-DD` strings are interpreted as **floating dates**\n * (local midnight) rather than UTC midnight, so they render on the same\n * calendar day in every timezone.\n */\nexport function parseDate(value: unknown): Date | null {\n  if (value instanceof Date) {\n    return Number.isNaN(value.getTime()) ? null : value;\n  }\n  if (typeof value === 'number') {\n    const d = new Date(value);\n    return Number.isNaN(d.getTime()) ? null : d;\n  }\n  if (typeof value === 'string') {\n    const match = /^(\\d{4})-(\\d{2})-(\\d{2})$/.exec(value);\n    if (match) {\n      const [, y, m, d] = match;\n      const date = new Date(Number(y), Number(m) - 1, Number(d));\n      return Number.isNaN(date.getTime()) ? null : date;\n    }\n    const date = new Date(value);\n    return Number.isNaN(date.getTime()) ? null : date;\n  }\n  return null;\n}\n\nfunction toDateInputValue(date: Date): string {\n  const y = date.getFullYear();\n  const m = String(date.getMonth() + 1).padStart(2, '0');\n  const d = String(date.getDate()).padStart(2, '0');\n  return `${y}-${m}-${d}`;\n}\n\nfunction formatDateValue(value: unknown, style: string): string {\n  const date = parseDate(value);\n  if (!date) return '';\n  return new Intl.DateTimeFormat(undefined, {\n    dateStyle: style as Intl.DateTimeFormatOptions['dateStyle'],\n  }).format(date);\n}\n\n/**\n * Returns a `next` value cast to the same shape as `original` (Date / number\n * timestamp / ISO string). Empty inputs commit `null` regardless of the\n * source shape, which is the simplest \"clear\" semantics.\n */\nfunction commitDateInSameShape(original: unknown, next: Date | null): unknown {\n  if (next === null) return null;\n  if (original instanceof Date) return next;\n  if (typeof original === 'number') return next.getTime();\n  return toDateInputValue(next);\n}\n\nconst dateType: ColumnTypeRenderer<object> = {\n  display(ctx) {\n    const style = (ctx.column as { format?: string }).format ?? 'medium';\n    return html`${formatDateValue(ctx.value, style)}`;\n  },\n\n  editor(ctx) {\n    const initial = parseDate(ctx.value);\n    const initialInput = initial ? toDateInputValue(initial) : '';\n\n    const handleChange = (event: Event) => {\n      const raw = (event.target as HTMLInputElement).value;\n      const next = raw ? parseDate(raw) : null;\n      ctx.commit(commitDateInSameShape(ctx.value, next));\n    };\n    // Escape / Tab / focus-out are handled at the cell level; we only need\n    // Enter here to commit the typed value without waiting for `change`.\n    const handleKeydown = (event: KeyboardEvent) => {\n      if (event.key === 'Enter') {\n        event.preventDefault();\n        event.stopPropagation();\n        const raw = (event.target as HTMLInputElement).value;\n        const next = raw ? parseDate(raw) : null;\n        ctx.commit(commitDateInSameShape(ctx.value, next));\n      }\n    };\n    return html`<input\n      type=\"date\"\n      part=\"editor\"\n      data-apex-editor\n      .value=${initialInput}\n      @change=${handleChange}\n      @keydown=${handleKeydown}\n    />`;\n  },\n};\n\nconst ratingType: ColumnTypeRenderer<object> = {\n  display(ctx) {\n    const max = getRatingMax(ctx.column as { max?: number });\n    const value = clampRating(ctx.value, max);\n    const stars = Array.from({ length: max }, (_, i) => i < value);\n    return html`<span part=\"rating\" role=\"img\" aria-label=\"${value} of ${max}\">\n      ${stars.map(\n        (filled) =>\n          html`<span part=${filled ? 'rating-star filled' : 'rating-star'} aria-hidden=\"true\">\n            ${renderIcon('star')}\n          </span>`\n      )}\n    </span>`;\n  },\n\n  editor(ctx) {\n    const max = getRatingMax(ctx.column as { max?: number });\n    const current = clampRating(ctx.value, max);\n    const focusRank = Math.max(current, 1);\n\n    const commitTo = (next: number) => ctx.commit(clampRating(next, max));\n\n    // Escape / Tab / focus-out are handled at the cell level — no per-editor\n    // handlers needed here. Clicking a star is the primary commit action;\n    // clicking the currently-rated star clears the rating back to 0, which\n    // is the only way to get below 1 once any star is set.\n    const stars = Array.from({ length: max }, (_, i) => i + 1);\n    return html`<span\n      part=\"rating-editor\"\n      role=\"radiogroup\"\n      aria-label=\"Rating\"\n    >\n      ${stars.map(\n        (rank) => html`<button\n          type=\"button\"\n          part=${rank <= current ? 'rating-star filled selected' : 'rating-star'}\n          role=\"radio\"\n          aria-checked=${rank === current}\n          aria-label=${`${rank} of ${max}`}\n          data-rating-value=${rank}\n          data-apex-editor=${rank === focusRank ? '' : nothing}\n          @click=${() => commitTo(rank === current ? 0 : rank)}\n        >\n          ${renderIcon('star')}\n        </button>`\n      )}\n    </span>`;\n  },\n};\n\nconst booleanType: ColumnTypeRenderer<object> = {\n  display(ctx) {\n    const truthy = ctx.value === true;\n    const editable = typeof ctx.commit === 'function';\n    // For editable boolean cells the display IS the interactive control —\n    // a single click toggles and commits via `ctx.commit`, no edit mode\n    // dance and no visual reflow. For non-editable cells the checkbox\n    // reads as a state indicator (tabindex=-1, aria-readonly, pointer-\n    // events disabled via SCSS).\n    return html`<input\n      type=\"checkbox\"\n      part=${truthy ? 'boolean-mark checked' : 'boolean-mark'}\n      .checked=${truthy}\n      tabindex=${editable ? '0' : '-1'}\n      aria-readonly=${editable ? 'false' : 'true'}\n      aria-label=${truthy ? 'true' : 'false'}\n      @click=${(event: Event) => {\n        // Keep the click inside the cell — we don't want it to bubble into\n        // the grid body-click handler twice or trigger edit-mode logic.\n        event.stopPropagation();\n      }}\n      @change=${\n        editable\n          ? (event: Event) => {\n              const next = (event.target as HTMLInputElement).checked;\n              ctx.commit?.(next);\n            }\n          : undefined\n      }\n    />`;\n  },\n  // No `editor` — boolean cells never enter edit mode (the display widget\n  // commits directly). Programmatic `editCell` on a boolean column is a\n  // no-op as far as the user can see.\n};\n\nconst imageType: ColumnTypeRenderer<object> = {\n  display(ctx) {\n    const value = ctx.value;\n    if (value == null || value === '') return html``;\n    const shape = (ctx.column as { shape?: 'square' | 'circle' }).shape ?? 'square';\n    const colAny = ctx.column as { alt?: string; key?: unknown };\n    const alt = colAny.alt ?? String(colAny.key ?? '');\n    return html`<img\n      part=${shape === 'circle' ? 'image circle' : 'image'}\n      src=${String(value)}\n      alt=${alt}\n      loading=\"lazy\"\n    />`;\n  },\n  // Editing an image URL is just text editing — fall through to the default\n  // text editor for `editable: true` image columns.\n};\n\nconst BUILTIN_TYPES: Record<string, ColumnTypeRenderer<object>> = {\n  select: selectType,\n  rating: ratingType,\n  date: dateType,\n  boolean: booleanType,\n  image: imageType,\n};\n\n/**\n * Returns the built-in renderer for a column `type`, or `undefined` when the\n * type has no built-in display/editor (the cell falls back to plain text /\n * the primitive editor in that case).\n */\nexport function getColumnTypeRenderer<T extends object>(\n  type?: string\n): ColumnTypeRenderer<T> | undefined {\n  return type ? (BUILTIN_TYPES[type] as unknown as ColumnTypeRenderer<T> | undefined) : undefined;\n}\n"]}

package/internal/export.d.ts

@@ -0,0 +1,106 @@
+import type { ApexGrid } from '../components/grid.js';
+import type { ColumnConfiguration, Keys } from './types.js';
+/**
+ * Primitive cell values supported by the export pipeline.
+ *
+ * @remarks
+ * Returned by the default formatter and accepted from user-supplied formatters.
+ * `Date` is preserved (not stringified) so that XLSX export can write it as a
+ * native date cell instead of inline text.
+ */
+export type ExportCellValue = string | number | boolean | Date | null | undefined;
+/**
+ * Which row set should drive the export.
+ *
+ * - `'view'` (default) — post-filter, post-sort rows across all pages.
+ * - `'all'` — the raw `data` array as supplied by the consumer.
+ * - `'page'` — only the rows in the current page slice.
+ * - `'selected'` — the current row selection (insertion order).
+ */
+export type ExportSource = 'view' | 'all' | 'page' | 'selected';
+/**
+ * Options shared by all export targets.
+ */
+export interface ExportOptions<T extends object> {
+    /** Output filename, without extension. Defaults to `'data'`. */
+    filename?: string;
+    /** Row set to export. Defaults to `'view'`. */
+    source?: ExportSource;
+    /**
+     * Column keys to include. When omitted, every visible non-hidden column with
+     * `exportable !== false` is exported, in display order.
+     */
+    columns?: ReadonlyArray<Keys<T>>;
+    /** Whether to emit a header row. Defaults to `true`. */
+    includeHeader?: boolean;
+    /**
+     * Per-cell value formatter. Receives the column configuration, the raw value
+     * from the record, and the record itself. Return one of {@link ExportCellValue}
+     * (return a `Date` to keep date typing in XLSX).
+     */
+    formatter?: (column: ColumnConfiguration<T>, value: unknown, row: T) => ExportCellValue;
+}
+/**
+ * Options for {@link ApexGrid.exportToCSV}.
+ */
+export interface CSVExportOptions<T extends object> extends ExportOptions<T> {
+    /** Field delimiter. Defaults to `','`. */
+    delimiter?: string;
+    /**
+     * Prepend a UTF-8 byte-order mark so Excel auto-detects the encoding when
+     * opening the file. Defaults to `true`.
+     */
+    bom?: boolean;
+    /** Line separator. Defaults to `'\r\n'` (RFC 4180). */
+    newline?: string;
+}
+/**
+ * Options for {@link ApexGrid.exportToXLSX}.
+ */
+export interface XLSXExportOptions<T extends object> extends ExportOptions<T> {
+    /** Worksheet tab name. Defaults to `'Sheet1'`. Trimmed to 31 chars. */
+    sheetName?: string;
+}
+/**
+ * Resolves the columns that should appear in the export, in display order.
+ */
+export declare function resolveExportColumns<T extends object>(grid: ApexGrid<T>, opts: ExportOptions<T>): Array<ColumnConfiguration<T>>;
+/**
+ * Resolves the rows that should appear in the export.
+ */
+export declare function resolveExportRows<T extends object>(grid: ApexGrid<T>, source?: ExportSource): ReadonlyArray<T>;
+/**
+ * Returns the column's display label, used as the header cell value.
+ */
+export declare function getColumnLabel<T extends object>(column: ColumnConfiguration<T>): string;
+/**
+ * Default cell-value formatter. Mirrors the on-screen rendering for each
+ * column type while keeping primitive types primitive (so number/boolean/date
+ * survive into XLSX as native cells instead of strings).
+ */
+export declare function defaultExportFormat<T extends object>(column: ColumnConfiguration<T>, value: unknown): ExportCellValue;
+/**
+ * Resolves the export value for a single cell, applying the user-supplied
+ * formatter when present and falling back to {@link defaultExportFormat}.
+ */
+export declare function resolveExportValue<T extends object>(column: ColumnConfiguration<T>, row: T, opts: ExportOptions<T>): ExportCellValue;
+/** Formats a `Date` into the configured date style for CSV output. */
+export declare function formatDateForCSV<T extends object>(column: ColumnConfiguration<T>, value: Date): string;
+/**
+ * Builds the CSV string for the grid without triggering a download.
+ *
+ * @remarks
+ * Useful when consumers want to ship the bytes through their own transport
+ * (clipboard, HTTP upload). The {@link ApexGrid.exportToCSV} method calls
+ * this and then triggers a browser download.
+ */
+export declare function buildCSV<T extends object>(grid: ApexGrid<T>, opts?: CSVExportOptions<T>): string;
+/**
+ * Triggers a browser download for the given payload.
+ *
+ * @remarks
+ * Falls back to a no-op when called outside the browser (during SSR or unit
+ * tests on JSDOM without a body), so consumers can still call the public
+ * export API safely.
+ */
+export declare function downloadBlob(filename: string, content: string | Uint8Array, mimeType: string): void;

package/internal/export.js

@@ -0,0 +1,122 @@
+import { getDisplayColumns } from './utils.js';
+export function resolveExportColumns(grid, opts) {
+    const all = getDisplayColumns(grid.columns).filter((column) => !column.hidden && column.exportable !== false);
+    if (!opts.columns?.length)
+        return all;
+    const keys = new Set(opts.columns);
+    return all.filter((column) => keys.has(column.key));
+}
+export function resolveExportRows(grid, source = 'view') {
+    switch (source) {
+        case 'all':
+            return grid.data;
+        case 'page':
+            return grid.pageItems;
+        case 'selected':
+            return grid.selectedRows;
+        default:
+            return grid.dataView;
+    }
+}
+export function getColumnLabel(column) {
+    return column.headerText ?? String(column.key);
+}
+const DATE_STYLE_MAP = {
+    short: 'short',
+    medium: 'medium',
+    long: 'long',
+    full: 'full',
+};
+export function defaultExportFormat(column, value) {
+    if (value === null || value === undefined)
+        return '';
+    switch (column.type) {
+        case 'select': {
+            const found = column.options?.find((option) => {
+                if (option && typeof option === 'object' && 'value' in option) {
+                    return option.value === value;
+                }
+                return option === value;
+            });
+            if (found && typeof found === 'object' && 'label' in found) {
+                const label = found.label;
+                if (typeof label === 'string' && label.length > 0)
+                    return label;
+            }
+            return typeof value === 'number' || typeof value === 'boolean' ? value : String(value);
+        }
+        case 'date': {
+            if (value instanceof Date)
+                return value;
+            const parsed = new Date(value);
+            return Number.isNaN(parsed.getTime()) ? String(value) : parsed;
+        }
+        case 'boolean':
+            return Boolean(value);
+        case 'number':
+        case 'rating': {
+            const n = Number(value);
+            return Number.isFinite(n) ? n : '';
+        }
+        default:
+            return typeof value === 'number' || typeof value === 'boolean' ? value : String(value);
+    }
+}
+export function resolveExportValue(column, row, opts) {
+    const raw = row[column.key];
+    return opts.formatter ? opts.formatter(column, raw, row) : defaultExportFormat(column, raw);
+}
+export function formatDateForCSV(column, value) {
+    const style = DATE_STYLE_MAP[column.format ?? 'medium'];
+    try {
+        return new Intl.DateTimeFormat(undefined, { dateStyle: style }).format(value);
+    }
+    catch {
+        return value.toISOString();
+    }
+}
+function escapeCSVCell(value, delimiter) {
+    if (value === null || value === undefined || value === '')
+        return '';
+    const text = value instanceof Date ? value.toISOString() : String(value);
+    const needsQuoting = text.includes(delimiter) || text.includes('"') || text.includes('\n') || text.includes('\r');
+    return needsQuoting ? `"${text.replace(/"/g, '""')}"` : text;
+}
+export function buildCSV(grid, opts = {}) {
+    const delimiter = opts.delimiter ?? ',';
+    const newline = opts.newline ?? '\r\n';
+    const includeHeader = opts.includeHeader ?? true;
+    const columns = resolveExportColumns(grid, opts);
+    const rows = resolveExportRows(grid, opts.source);
+    const lines = [];
+    if (includeHeader) {
+        lines.push(columns.map((column) => escapeCSVCell(getColumnLabel(column), delimiter)).join(delimiter));
+    }
+    for (const row of rows) {
+        const cells = columns.map((column) => {
+            let value = resolveExportValue(column, row, opts);
+            if (value instanceof Date) {
+                value = formatDateForCSV(column, value);
+            }
+            return escapeCSVCell(value, delimiter);
+        });
+        lines.push(cells.join(delimiter));
+    }
+    const body = lines.join(newline);
+    return opts.bom === false ? body : `\uFEFF${body}`;
+}
+export function downloadBlob(filename, content, mimeType) {
+    if (typeof document === 'undefined' || typeof URL?.createObjectURL !== 'function')
+        return;
+    const blob = new Blob([content], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = filename;
+    anchor.style.display = 'none';
+    document.body.appendChild(anchor);
+    anchor.click();
+    document.body.removeChild(anchor);
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+//# sourceMappingURL=export.js.map

package/internal/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/internal/export.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ApexGrid } from '../components/grid.js';\nimport type { ColumnConfiguration, ColumnDateFormat, Keys } from './types.js';\nimport { getDisplayColumns } from './utils.js';\n\n/**\n * Primitive cell values supported by the export pipeline.\n *\n * @remarks\n * Returned by the default formatter and accepted from user-supplied formatters.\n * `Date` is preserved (not stringified) so that XLSX export can write it as a\n * native date cell instead of inline text.\n */\nexport type ExportCellValue = string | number | boolean | Date | null | undefined;\n\n/**\n * Which row set should drive the export.\n *\n * - `'view'` (default) — post-filter, post-sort rows across all pages.\n * - `'all'` — the raw `data` array as supplied by the consumer.\n * - `'page'` — only the rows in the current page slice.\n * - `'selected'` — the current row selection (insertion order).\n */\nexport type ExportSource = 'view' | 'all' | 'page' | 'selected';\n\n/**\n * Options shared by all export targets.\n */\nexport interface ExportOptions<T extends object> {\n  /** Output filename, without extension. Defaults to `'data'`. */\n  filename?: string;\n  /** Row set to export. Defaults to `'view'`. */\n  source?: ExportSource;\n  /**\n   * Column keys to include. When omitted, every visible non-hidden column with\n   * `exportable !== false` is exported, in display order.\n   */\n  columns?: ReadonlyArray<Keys<T>>;\n  /** Whether to emit a header row. Defaults to `true`. */\n  includeHeader?: boolean;\n  /**\n   * Per-cell value formatter. Receives the column configuration, the raw value\n   * from the record, and the record itself. Return one of {@link ExportCellValue}\n   * (return a `Date` to keep date typing in XLSX).\n   */\n  formatter?: (column: ColumnConfiguration<T>, value: unknown, row: T) => ExportCellValue;\n}\n\n/**\n * Options for {@link ApexGrid.exportToCSV}.\n */\nexport interface CSVExportOptions<T extends object> extends ExportOptions<T> {\n  /** Field delimiter. Defaults to `','`. */\n  delimiter?: string;\n  /**\n   * Prepend a UTF-8 byte-order mark so Excel auto-detects the encoding when\n   * opening the file. Defaults to `true`.\n   */\n  bom?: boolean;\n  /** Line separator. Defaults to `'\\r\\n'` (RFC 4180). */\n  newline?: string;\n}\n\n/**\n * Options for {@link ApexGrid.exportToXLSX}.\n */\nexport interface XLSXExportOptions<T extends object> extends ExportOptions<T> {\n  /** Worksheet tab name. Defaults to `'Sheet1'`. Trimmed to 31 chars. */\n  sheetName?: string;\n}\n\n/**\n * Resolves the columns that should appear in the export, in display order.\n */\nexport function resolveExportColumns<T extends object>(\n  grid: ApexGrid<T>,\n  opts: ExportOptions<T>\n): Array<ColumnConfiguration<T>> {\n  const all = getDisplayColumns(grid.columns).filter(\n    (column) => !column.hidden && column.exportable !== false\n  );\n  if (!opts.columns?.length) return all;\n  const keys = new Set(opts.columns as Keys<T>[]);\n  return all.filter((column) => keys.has(column.key));\n}\n\n/**\n * Resolves the rows that should appear in the export.\n */\nexport function resolveExportRows<T extends object>(\n  grid: ApexGrid<T>,\n  source: ExportSource = 'view'\n): ReadonlyArray<T> {\n  switch (source) {\n    case 'all':\n      return grid.data;\n    case 'page':\n      return grid.pageItems;\n    case 'selected':\n      return grid.selectedRows;\n    default:\n      return grid.dataView;\n  }\n}\n\n/**\n * Returns the column's display label, used as the header cell value.\n */\nexport function getColumnLabel<T extends object>(column: ColumnConfiguration<T>): string {\n  return column.headerText ?? String(column.key);\n}\n\nconst DATE_STYLE_MAP: Record<ColumnDateFormat, Intl.DateTimeFormatOptions['dateStyle']> = {\n  short: 'short',\n  medium: 'medium',\n  long: 'long',\n  full: 'full',\n};\n\n/**\n * Default cell-value formatter. Mirrors the on-screen rendering for each\n * column type while keeping primitive types primitive (so number/boolean/date\n * survive into XLSX as native cells instead of strings).\n */\nexport function defaultExportFormat<T extends object>(\n  column: ColumnConfiguration<T>,\n  value: unknown\n): ExportCellValue {\n  if (value === null || value === undefined) return '';\n  switch (column.type) {\n    case 'select': {\n      const found = column.options?.find((option) => {\n        if (option && typeof option === 'object' && 'value' in option) {\n          return (option as { value: unknown }).value === value;\n        }\n        return option === value;\n      });\n      if (found && typeof found === 'object' && 'label' in found) {\n        const label = (found as { label?: unknown }).label;\n        if (typeof label === 'string' && label.length > 0) return label;\n      }\n      return typeof value === 'number' || typeof value === 'boolean' ? value : String(value);\n    }\n    case 'date': {\n      if (value instanceof Date) return value;\n      const parsed = new Date(value as string | number);\n      return Number.isNaN(parsed.getTime()) ? String(value) : parsed;\n    }\n    case 'boolean':\n      return Boolean(value);\n    case 'number':\n    case 'rating': {\n      const n = Number(value);\n      return Number.isFinite(n) ? n : '';\n    }\n    default:\n      return typeof value === 'number' || typeof value === 'boolean' ? value : String(value);\n  }\n}\n\n/**\n * Resolves the export value for a single cell, applying the user-supplied\n * formatter when present and falling back to {@link defaultExportFormat}.\n */\nexport function resolveExportValue<T extends object>(\n  column: ColumnConfiguration<T>,\n  row: T,\n  opts: ExportOptions<T>\n): ExportCellValue {\n  const raw = (row as Record<string, unknown>)[column.key as string];\n  return opts.formatter ? opts.formatter(column, raw, row) : defaultExportFormat(column, raw);\n}\n\n/** Formats a `Date` into the configured date style for CSV output. */\nexport function formatDateForCSV<T extends object>(\n  column: ColumnConfiguration<T>,\n  value: Date\n): string {\n  const style = DATE_STYLE_MAP[column.format ?? 'medium'];\n  try {\n    return new Intl.DateTimeFormat(undefined, { dateStyle: style }).format(value);\n  } catch {\n    return value.toISOString();\n  }\n}\n\nfunction escapeCSVCell(value: ExportCellValue, delimiter: string): string {\n  if (value === null || value === undefined || value === '') return '';\n  const text = value instanceof Date ? value.toISOString() : String(value);\n  const needsQuoting =\n    text.includes(delimiter) || text.includes('\"') || text.includes('\\n') || text.includes('\\r');\n  return needsQuoting ? `\"${text.replace(/\"/g, '\"\"')}\"` : text;\n}\n\n/**\n * Builds the CSV string for the grid without triggering a download.\n *\n * @remarks\n * Useful when consumers want to ship the bytes through their own transport\n * (clipboard, HTTP upload). The {@link ApexGrid.exportToCSV} method calls\n * this and then triggers a browser download.\n */\nexport function buildCSV<T extends object>(\n  grid: ApexGrid<T>,\n  opts: CSVExportOptions<T> = {}\n): string {\n  const delimiter = opts.delimiter ?? ',';\n  const newline = opts.newline ?? '\\r\\n';\n  const includeHeader = opts.includeHeader ?? true;\n  const columns = resolveExportColumns(grid, opts);\n  const rows = resolveExportRows(grid, opts.source);\n\n  const lines: string[] = [];\n  if (includeHeader) {\n    lines.push(\n      columns.map((column) => escapeCSVCell(getColumnLabel(column), delimiter)).join(delimiter)\n    );\n  }\n  for (const row of rows) {\n    const cells = columns.map((column) => {\n      let value = resolveExportValue(column, row, opts);\n      if (value instanceof Date) {\n        value = formatDateForCSV(column, value);\n      }\n      return escapeCSVCell(value, delimiter);\n    });\n    lines.push(cells.join(delimiter));\n  }\n\n  const body = lines.join(newline);\n  return opts.bom === false ? body : `\\uFEFF${body}`;\n}\n\n/**\n * Triggers a browser download for the given payload.\n *\n * @remarks\n * Falls back to a no-op when called outside the browser (during SSR or unit\n * tests on JSDOM without a body), so consumers can still call the public\n * export API safely.\n */\nexport function downloadBlob(\n  filename: string,\n  content: string | Uint8Array,\n  mimeType: string\n): void {\n  if (typeof document === 'undefined' || typeof URL?.createObjectURL !== 'function') return;\n  // BlobPart accepts both string and Uint8Array; the cast quiets TS' strict\n  // overload resolution which prefers ArrayBufferView only.\n  const blob = new Blob([content as BlobPart], { type: mimeType });\n  const url = URL.createObjectURL(blob);\n  const anchor = document.createElement('a');\n  anchor.href = url;\n  anchor.download = filename;\n  anchor.style.display = 'none';\n  document.body.appendChild(anchor);\n  anchor.click();\n  document.body.removeChild(anchor);\n  setTimeout(() => URL.revokeObjectURL(url), 0);\n}\n"]}