@openleaf-editor/plugins-table 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -0,0 +1,98 @@
+# @openleaf-editor/plugins-table
+
+Opt-in table editing: cell selection, column resizing, property dialogs,
+captions, an insert grid, a context menu, and the row and column commands.
+
+> **Editor output is untrusted input.** Whatever the editor produces — and
+> whatever a user pasted into it — must be sanitized **on your server** before it
+> is stored or rendered as HTML. Client-side sanitization is a user-experience
+> feature, not a security control: anything the editor strips can be put back
+> with developer tools, because the editor runs under the user's control.
+>
+> [`@openleaf-editor/sanitize`](https://github.com/PeytonNowlin/openleaf/tree/main/packages/sanitize) ships the
+> canonical allowlist as data and generates configuration for DOMPurify, Python
+> `bleach` and PHP HTMLPurifier from it, so client and server enforce the same
+> rules. Read [SECURITY.md](https://github.com/PeytonNowlin/openleaf/blob/main/SECURITY.md) before you ship.
+
+## Install
+
+```sh
+npm install @openleaf-editor/plugins-table@beta
+```
+
+Keep every `@openleaf-editor/*` package on the same version. They pin each other
+exactly, so mixing versions installs two copies of the schema and the toolbar
+registry -- and a node built by one is not a node type the other accepts.
+
+## Use it
+
+With a bundler:
+
+```ts
+import { installTableEditing } from '@openleaf-editor/plugins-table'
+installTableEditing()
+```
+
+With a script tag, load it after the core bundle -- it borrows the first one's
+ProseMirror runtime rather than shipping a second copy:
+
+```html
+<script src="/js/openleaf.min.js"></script>
+<script src="/js/openleaf-tables.min.js"></script>
+```
+
+Then name the controls you want in the `toolbar` attribute. Installing the
+plugin registers capability; it does not rearrange your toolbar.
+
+## The schema is not in here
+
+Table node types live in [`@openleaf-editor/core`](../core), and that was not the
+original plan. The fidelity harness changed it: without them a `<table>` in stored
+content is claimed by the preservation layer and becomes an opaque, uneditable
+card. Faithful, and useless.
+
+So the split falls at the editing machinery instead. Every deployment reads and
+writes tables; only the ones that want table *editing* download this.
+
+## Captions and colgroup
+
+Both round-trip byte-for-byte, as furniture attributes on the table node rather
+than child nodes. They render but are not editable in place: a caption has to be a
+child node for that, and `prosemirror-tables` derives its cell map from
+`table.childCount`, so it needs an upstream fix first. The caption dialog is how
+you change one meanwhile.
+
+Inserting or deleting a column reindexes a stored `<colgroup>` with the cells.
+Without that, every remaining column inherited the previous `<col>`'s width and
+class. Column resize still patches widths onto the same elements, so the two
+paths do not fight.
+
+## License
+
+Apache-2.0.
+
+## Toolbar item ids
+
+Installing registers the controls; it does not rearrange a custom toolbar. Name
+the ones you want in the element's `toolbar` attribute:
+
+| Id | Control |
+| --- | --- |
+| `insertTable` | Insert-table grid |
+| `tableProperties` | Table properties dialog |
+| `rowProperties` | Row properties dialog |
+| `cellProperties` | Cell properties dialog |
+| `tableCaption` | Caption dialog |
+| `addRowBefore`, `addRowAfter`, `deleteRow` | Row commands. They keep `headerRows` / `footerRows` in step so `<thead>` and `<tfoot>` stay on the header and footer rows the author actually has. |
+| `addColumnBefore`, `addColumnAfter`, `deleteColumn` | Column commands |
+| `mergeCells`, `splitCell` | Cell merge and split |
+| `toggleHeaderRow` | Promote or demote the header row |
+| `deleteTable` | Delete the whole table |
+
+```html
+<openleaf-editor for="body"
+  toolbar="bold italic | insertTable tableProperties | source">
+</openleaf-editor>
+```
+
+An id nothing has registered logs a warning rather than being skipped silently.

package/dist/commands.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Table commands that are not already in `prosemirror-tables`.
+ *
+ * Property edits, caption/colgroup, nested insert and vertical alignment live
+ * here so a test can apply them without standing up a toolbar. Column insert and
+ * delete also reindex the stored colgroup here: the upstream commands only move
+ * cells, and `colgroupFromCellWidths` never runs unless a cell already has
+ * `colwidth`.
+ */
+import type { Node, ResolvedPos } from 'prosemirror-model';
+import type { Command, EditorState } from 'prosemirror-state';
+import { Plugin } from 'prosemirror-state';
+export declare function inTable(state: EditorState): boolean;
+export declare function findRole($pos: ResolvedPos, role: 'table' | 'row' | 'cell' | 'header_cell'): {
+    node: Node;
+    pos: number;
+    depth: number;
+} | null;
+export declare function findTable($pos: ResolvedPos): {
+    node: Node;
+    pos: number;
+    depth: number;
+} | null;
+export declare function findRow($pos: ResolvedPos): {
+    node: Node;
+    pos: number;
+    depth: number;
+} | null;
+export declare function findCell($pos: ResolvedPos): {
+    node: Node;
+    pos: number;
+    depth: number;
+} | null;
+export declare function insertTable(rows?: number, cols?: number): Command;
+export declare function withCellScope(command: Command): Command;
+export declare const addColumnAfter: Command;
+export declare const addColumnBefore: Command;
+export declare const deleteColumn: Command;
+export declare const addRowAfter: Command;
+export declare const addRowBefore: Command;
+export declare const deleteRow: Command;
+export declare const toggleHeaderRow: Command;
+export declare function selectedCellPositions(state: EditorState): number[];
+/**
+ * Patch declarations onto a style attribute, validating every value written.
+ *
+ * The validation is here rather than in each caller because this is the choke
+ * point: a value reaches the stored style attribute only through this function,
+ * and `serializeDeclarations` joins on `;`, so an unchecked value carrying one
+ * becomes extra declarations. `padding: 0;position:fixed;inset:0` is a
+ * page-covering overlay, written from a property dialog and saved.
+ *
+ * `safeTableStyleValue` is core's own parse-path validator, so a dialog cannot
+ * disagree with the schema about what an acceptable value is.
+ */
+export declare function mergeStyle(existing: string | null | undefined, patch: Record<string, string | null>): string | null;
+/** A style value the schema will keep, or null. For a dialog's commit step. */
+export declare function styleValueOrNull(property: string, value: string | undefined): string | null;
+export declare function setTableAttrs(attrs: Record<string, unknown>): Command;
+export declare function setRowAttrs(attrs: Record<string, unknown>): Command;
+export declare function setCellAttrs(attrs: Record<string, unknown>): Command;
+export declare function setCellVerticalAlign(value: string | null): Command;
+export declare function captionTextFromHtml(html: string | null | undefined): string;
+export declare function captionHtmlFromText(text: string, previous: string | null | undefined): string | null;
+export declare function setTableCaption(text: string): Command;
+export declare function colgroupHtmlFromWidths(widths: Array<string | null | undefined>): string | null;
+/**
+ * Column widths, one per column.
+ *
+ * `span` is honoured: `<col span="2" width="120">` sets two columns to 120, not
+ * one. Reading the elements positionally would report the second column as
+ * having no width, and then saving would write that back.
+ */
+export declare function widthsFromColgroup(html: string | null | undefined, columns: number): string[];
+/**
+ * Write widths into an existing colgroup rather than replacing it.
+ *
+ * Inherited markup carries more than widths -- `<colgroup class="layout">`,
+ * `<col span="2">`, whatever else a previous CMS wrote -- and the table
+ * properties dialog saves the whole table, so rebuilding the colgroup from
+ * widths alone dropped all of it on a save that changed nothing else.
+ *
+ * An unchanged set of widths returns the stored markup untouched, so saving the
+ * dialog is genuinely a no-op. When a width does change, the existing elements
+ * are patched: a spanned `<col>` keeps its span while its columns still agree,
+ * and is split into one `<col>` per column -- carrying its other attributes --
+ * only when they no longer do.
+ */
+export declare function colgroupHtmlWithWidths(existing: string | null | undefined, widths: Array<string | null | undefined>): string | null;
+/**
+ * Insert a bare `<col>` so columns after `at` keep the `<col>` they already had.
+ *
+ * A spanned element that covers `at` is split around the insertion rather than
+ * widened: the new column must not inherit the neighbour's class or width, which
+ * is the same shift insert-without-a-patch produced for unspanned columns.
+ */
+export declare function colgroupHtmlInsertColumn(existing: string | null | undefined, at: number): string | null;
+/**
+ * Drop the `<col>` covering column `at`, or decrement its `span` when it covers
+ * more than one column.
+ */
+export declare function colgroupHtmlDeleteColumn(existing: string | null | undefined, at: number): string | null;
+export declare function setTableColgroup(widths: Array<string | null | undefined>): Command;
+/**
+ * Keep `<colgroup>` in lockstep with column resizing.
+ *
+ * `prosemirror-tables` writes `colwidth` onto cells. That is enough for the
+ * editor; it is not enough for stored HTML, whose column widths live on
+ * `<col>`. Updating the furniture attribute after a resize is what makes
+ * colgroup a first-class editing feature rather than a round-trip souvenir.
+ *
+ * Authored colgroups that are not the product of a resize are left alone:
+ * inventing `<col>` elements for a table that never had widths would change
+ * markup we had no reason to touch.
+ */
+export declare function colgroupSyncPlugin(): Plugin;
+export declare function emptyToNull(value: string | undefined): string | null;
+export declare function colorOrNull(value: string | undefined): string | null;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}