Files
Tom Moor 49aee74190 feat: Add filtering to tables in the editor (#14625)
* feat: Add filtering to tables in the editor

* Show the column filter button on header hover in edit mode

* Keep the filter button shown while its menu is open

* Move focusEditor to its own module

* Anchor the filter menu to the filter button

* Address review feedback on table filtering

* Show the filter button background while its menu is open

* Always show the filter button background with its icon

* Remove value counts and hide Clear when there is no filter

* Translations

* placeholder
2026-11-18 22:37:15 -05:00

469 lines
14 KiB
TypeScript

import type { Attrs, Node, Schema } from "prosemirror-model";
import { TableMap, type MutableAttrs } from "prosemirror-tables";
import { Decoration, type EditorView } from "prosemirror-view";
import { isBrowser } from "../../utils/browser";
import { isNearWhite, toHexColor, validateColorHex } from "../../utils/color";
import type { TableFilter, TableLayout, NodeAttrMark } from "../types";
import { readableColor } from "polished";
export interface TableAttrs {
layout: TableLayout | null;
filters: TableFilter[] | null;
}
export interface CellAttrs {
colspan: number;
rowspan: number;
colwidth: number[] | null;
alignment: "center" | "left" | "right" | null;
marks?: NodeAttrMark[];
}
const ALLOWED_ALIGNMENTS = new Set(["left", "center", "right"]);
/**
* Validates an alignment attribute value.
*
* @param value the value to validate.
* @returns true if the value is a safe alignment or null.
*/
export const isValidCellAlignment = (
value: unknown
): value is "left" | "center" | "right" | null =>
value === null ||
(typeof value === "string" && ALLOWED_ALIGNMENTS.has(value));
/**
* Validates a colspan or rowspan attribute value. A cell with any other span
* is left out of the table map and cannot be found by position.
*
* @param value the value to validate.
* @returns true if the value is a positive integer.
*/
export const isValidCellSpan = (value: unknown): value is number =>
typeof value === "number" && Number.isInteger(value) && value >= 1;
/**
* Validates a table cell's `marks` attribute against the given schema. Checks
* that the value is an array of well-formed mark objects whose type exists in
* the schema, and — for `background` marks — that the color is a valid hex
* value. `null` and `undefined` are both considered valid (the attribute is
* optional).
*
* @param value the value to validate.
* @param schema The editor schema, used to check mark types are registered.
* Optional — when absent, mark-type registration is not checked.
* @returns true if the value is a valid marks array, null, or undefined.
*/
export const isValidCellMarks = (
value: unknown,
schema?: Schema
): value is NodeAttrMark[] | null | undefined => {
if (value === undefined || value === null) {
return true;
}
if (!Array.isArray(value)) {
return false;
}
const marks = schema?.marks;
return value.every((mark) => {
if (!mark || typeof mark !== "object") {
return false;
}
const type = (mark as NodeAttrMark).type;
if (typeof type !== "string") {
return false;
}
if (marks && !Object.prototype.hasOwnProperty.call(marks, type)) {
return false;
}
const attrs = (mark as NodeAttrMark).attrs;
if (attrs !== undefined && (typeof attrs !== "object" || attrs === null)) {
return false;
}
if (type === "background") {
return typeof attrs?.color === "string" && validateColorHex(attrs.color);
}
return true;
});
};
/**
* Reads a background color styled on a cell by an external application, such as
* a spreadsheet or word processor, so that it is retained when pasting.
*
* @param dom DOM node to read the background from
* @returns The background in hex notation, or null when there is none worth keeping
*/
function getCellBackground(dom: HTMLElement): string | null {
const background = dom.style.backgroundColor;
if (!background || isNearWhite(background)) {
return null;
}
return toHexColor(background);
}
/**
* Helper to get cell attributes from a DOM node, used when pasting table content.
*
* @param dom DOM node to get attributes from
* @returns Cell attributes
*/
export function getCellAttrs(dom: HTMLElement | string): Attrs {
if (typeof dom === "string") {
return {};
}
const widthAttr = dom.getAttribute("data-colwidth");
const widths =
widthAttr && /^\d+(,\d+)*$/.test(widthAttr)
? widthAttr.split(",").map(Number)
: null;
const colspanAttr = Number(dom.getAttribute("colspan"));
const colspan = isValidCellSpan(colspanAttr) ? colspanAttr : 1;
const rowspanAttr = Number(dom.getAttribute("rowspan"));
const bgColor = dom.getAttribute("data-bgcolor") ?? getCellBackground(dom);
return {
colspan,
rowspan: isValidCellSpan(rowspanAttr) ? rowspanAttr : 1,
colwidth: widths && widths.length === colspan ? widths : null,
alignment:
dom.style.textAlign === "center"
? "center"
: dom.style.textAlign === "right"
? "right"
: null,
marks:
bgColor && validateColorHex(bgColor)
? [
{
type: "background",
attrs: {
color: bgColor,
},
},
]
: undefined,
} satisfies CellAttrs;
}
/**
* Helper to serialize cell attributes on a node, used when copying table content.
*
* @param node Node to get attributes from
* @returns Attributes for the cell
*/
export function setCellAttrs(node: Node): Attrs {
const attrs: MutableAttrs = {};
if (node.attrs.colspan !== 1) {
attrs.colspan = node.attrs.colspan;
}
if (node.attrs.rowspan !== 1) {
attrs.rowspan = node.attrs.rowspan;
}
if (isValidCellAlignment(node.attrs.alignment) && node.attrs.alignment) {
attrs.style = `text-align: ${node.attrs.alignment};`;
}
if (node.attrs.colwidth) {
if (isBrowser) {
attrs["data-colwidth"] = node.attrs.colwidth.map(Number).join(",");
} else {
attrs.style =
((attrs.style as string) ?? "") +
`min-width: ${Number(node.attrs.colwidth[0])}px;`;
}
}
if (Array.isArray(node.attrs.marks)) {
const backgroundMark = node.attrs.marks.find(
(mark: NodeAttrMark) =>
mark?.type === "background" &&
typeof mark.attrs?.color === "string" &&
validateColorHex(mark.attrs.color)
);
if (backgroundMark) {
const color = backgroundMark.attrs!.color as string;
attrs["data-bgcolor"] = color;
attrs.style =
((attrs.style as string) ?? "") +
`--cell-bg-color: ${color}; --cell-text-color: ${readableColor(color)};`;
}
}
return attrs;
}
/**
* Position a table grip or insert button on one of the rows or columns that a
* merged cell spans. The position is set with CSS custom properties that are
* percentages of the cell size.
*
* @param element The element to position.
* @param offset The index of the row or column within the cell.
* @param sizes The relative size of each row or column that the cell spans.
*/
export function setSpanPosition(
element: HTMLElement,
offset: number,
sizes: number[]
): void {
if (sizes.length < 2) {
return;
}
const total = sizes.reduce((sum, size) => sum + size, 0);
const start = sizes.slice(0, offset).reduce((sum, size) => sum + size, 0);
const end = start + sizes[offset];
element.style.setProperty("--span-start", `${(start / total) * 100}%`);
element.style.setProperty("--span-size", `${(sizes[offset] / total) * 100}%`);
element.style.setProperty("--span-end", `${100 - (end / total) * 100}%`);
}
/**
* Get the rows or columns spanned by the cell that covers the given row and
* column.
*
* @param map The table map.
* @param row A row covered by the cell.
* @param col A column covered by the cell.
* @param axis Whether to get the spanned rows or columns.
* @returns The first spanned index, and the index after the last one.
*/
export function getCellSpan(
map: TableMap,
row: number,
col: number,
axis: "row" | "column"
): { start: number; end: number } {
const pos = map.map[row * map.width + col];
const at = (index: number) =>
axis === "row"
? map.map[index * map.width + col]
: map.map[row * map.width + index];
const length = axis === "row" ? map.height : map.width;
let start = axis === "row" ? row : col;
let end = start + 1;
while (start > 0 && at(start - 1) === pos) {
start--;
}
while (end < length && at(end) === pos) {
end++;
}
return { start, end };
}
/**
* Get the cells that start in a row, skipping cells that span into it from a
* row above.
*
* @param map The table map.
* @param row The index of the row.
* @returns The positions of the cells relative to the table start, in order.
*/
export function getCellsStartingInRow(map: TableMap, row: number): number[] {
const cells: number[] = [];
for (let col = 0; col < map.width;) {
if (getCellSpan(map, row, col, "row").start === row) {
cells.push(map.map[row * map.width + col]);
}
col = getCellSpan(map, row, col, "column").end;
}
return cells;
}
/**
* Get the cells that start in a column, skipping cells that span into it from
* a column before.
*
* @param map The table map.
* @param col The index of the column.
* @returns The positions of the cells relative to the table start, in order.
*/
export function getCellsStartingInColumn(map: TableMap, col: number): number[] {
const cells: number[] = [];
for (let row = 0; row < map.height;) {
if (getCellSpan(map, row, col, "column").start === col) {
cells.push(map.map[row * map.width + col]);
}
row = getCellSpan(map, row, col, "row").end;
}
return cells;
}
/**
* Keep a table grip or insert button positioned on one of the rows or columns
* that a merged cell spans, by measuring the rendered rows or columns whenever
* the table or cell is resized.
*
* @param element The element to position, placed at the start of the cell.
* @param view The editor view.
* @param getPos A function that returns the position of the element.
* @param axis Whether the cell spans rows or columns.
* @param offset The index of the row or column within the cell.
*/
export function trackSpanPosition(
element: HTMLElement,
view: EditorView,
getPos: () => number | undefined,
axis: "row" | "column",
offset: number
): void {
if (typeof ResizeObserver === "undefined") {
return;
}
const observer = new ResizeObserver(() => {
const pos = getPos();
const sizes =
pos === undefined ? undefined : measureSpan(view, pos - 1, axis);
if (sizes) {
setSpanPosition(element, offset, sizes);
}
});
// The element is not in the document until the widget is mounted.
const frame = requestAnimationFrame(() => {
const cell = element.closest("td, th");
const table = cell?.closest("table");
if (cell && table) {
observer.observe(cell);
observer.observe(table);
}
});
spanTrackers.set(element, () => {
cancelAnimationFrame(frame);
observer.disconnect();
});
}
/**
* Stop keeping an element positioned, see trackSpanPosition.
*
* @param element The positioned element.
*/
export function untrackSpanPosition(element: globalThis.Node): void {
spanTrackers.get(element)?.();
spanTrackers.delete(element);
}
/**
* Get the relative width of each column that a cell spans, using the stored
* column widths when they are available.
*
* @param node The cell node.
* @param colspan The number of columns that the cell spans.
* @returns The relative width of each spanned column.
*/
export function getColumnSizes(node: Node | null, colspan: number): number[] {
const colwidth: unknown = node?.attrs.colwidth;
if (
Array.isArray(colwidth) &&
colwidth.length === colspan &&
colwidth.every((width) => typeof width === "number" && width > 0)
) {
return colwidth;
}
return Array.from({ length: colspan }, () => 1);
}
/**
* Create a widget decoration at the start of a table cell, such as a grip or
* an insert button. The widget is placed before the cell content, so
* ProseMirror does not mistake it for the first block of the cell.
*
* @param cellPos The position of the cell.
* @param toDOM The function or element that renders the widget.
* @param spec The widget options.
* @returns The widget decoration.
*/
export function cellWidget(
cellPos: number,
toDOM: Parameters<typeof Decoration.widget>[1],
spec?: Parameters<typeof Decoration.widget>[2]
): Decoration {
return Decoration.widget(cellPos + 1, toDOM, { ...spec, side: -1 });
}
const spanTrackers = new WeakMap<globalThis.Node, () => void>();
/**
* Measure the rendered size of each row or column that a cell spans.
*
* @param view The editor view.
* @param cellPos The position of the cell.
* @param axis Whether to measure rows or columns.
* @returns The size of each spanned row or column, or undefined if one of them
* cannot be measured.
*/
function measureSpan(
view: EditorView,
cellPos: number,
axis: "row" | "column"
): number[] | undefined {
const $cell = view.state.doc.resolve(cellPos);
const table = $cell.node(-1);
if (table?.type.spec.tableRole !== "table") {
return undefined;
}
const tableStart = $cell.start(-1);
const map = TableMap.get(table);
// The cell is in the first column when it spans rows, and in the first row
// when it spans columns.
const length = axis === "row" ? map.height : map.width;
const stride = axis === "row" ? map.width : 1;
let index = 0;
while (index < length && map.map[index * stride] !== cellPos - tableStart) {
index++;
}
if (index === length) {
return undefined;
}
const span =
axis === "row"
? getCellSpan(map, index, 0, "row")
: getCellSpan(map, 0, index, "column");
const sizes: number[] = [];
if (axis === "row") {
let rowPos = tableStart;
for (let row = 0; row < span.end; row++) {
if (row >= span.start) {
const dom = view.nodeDOM(rowPos);
if (!(dom instanceof HTMLElement)) {
return undefined;
}
sizes.push(dom.getBoundingClientRect().height);
}
rowPos += table.child(row).nodeSize;
}
} else {
for (let col = span.start; col < span.end; col++) {
// Measure a cell that only covers this column.
let width: number | undefined;
for (let row = 0; row < map.height && width === undefined; row++) {
const { start, end } = getCellSpan(map, row, col, "column");
const dom =
start === col && end === col + 1
? view.nodeDOM(tableStart + map.map[row * map.width + col])
: undefined;
if (dom instanceof HTMLElement) {
width = dom.getBoundingClientRect().width;
}
}
if (width === undefined) {
return undefined;
}
sizes.push(width);
}
}
return sizes.every((size) => size > 0) ? sizes : undefined;
}