argus-table 0.1.0 → 0.2.1

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Joessst-Dev/argus-table/main/brand/argus-table-logo.svg" alt="Argus Table" width="240" height="240">
+</p>
+
 # argus-table
 
 `<argus-table>` is a data table web component built with Lit and TanStack. It works in any framework, or none.
@@ -5,7 +9,7 @@
 - **Virtualized rows:** 100,000 rows scroll smoothly, and the DOM stays the same size.
 - **Pinned columns** at the start or end, which mirror in right-to-left layouts.
 - **Sorting and resizing:** by mouse or keyboard, controlled or uncontrolled.
-- **Accessible:** the WAI-ARIA grid pattern, with one tab stop and arrow-key navigation.
+- **Accessible:** the WAI-ARIA grid pattern, with one tab stop and keyboard navigation by cell, row, page and corner.
 - **Plain CSS styling:** `--argus-*` tokens and `::part()` names. Cell content is light DOM, so your own CSS and components work inside cells.
 
 **[Docs and live examples](https://joessst-dev.github.io/argus-table/)** · [GitHub](https://github.com/Joessst-Dev/argus-table)
@@ -47,6 +51,25 @@ npm i argus-table @argus-table/themes
 - **Label:** give it a name with `aria-label` or `aria-labelledby`.
 - **Columns and data** are JavaScript properties, because they hold objects and functions.
 - **Cells:** a column's `cell` function can return a string, a number, a DOM node or a Lit template.
+- **Theme:** `default.css` is neutral and uses the page's font. `material.css` is a Material-inspired alternative (load Roboto yourself). Both are optional, and the table is usable without either.
+
+## Rows from a server
+
+For more rows than you want to send at once, set `dataSource` instead of `data`. The table asks for the pages in view as the user scrolls, shows skeleton rows until they arrive, and aborts requests for pages that scroll away:
+
+```js
+table.dataSource = {
+  pageSize: 100,
+  async getRows({ start, end, sorting, signal }) {
+    const params = new URLSearchParams({ offset: start, limit: end - start });
+    if (sorting[0]) params.set('sort', `${sorting[0].id}:${sorting[0].desc ? 'desc' : 'asc'}`);
+    const res = await fetch(`/api/orders?${params}`, { signal });
+    return res.json(); // { rows, total? }
+  },
+};
+```
+
+`end` is exclusive. Without a `total`, the table grows as pages arrive and stops at a page with fewer rows than it asked for. Sorting happens on the server. A page that fails fires `argus-load-error` and shows a Retry button; `table.refresh()` loads the rows in view again.
 
 ## Without a bundler
 
@@ -62,6 +85,6 @@ The CDN build has every dependency bundled:
 
 ## Status
 
-This is v0.1, an early release. Names can still change before 1.0. Infinite loading, pinned rows, auto column widths, column reordering and framework wrappers come in v0.2. See the [roadmap](https://github.com/Joessst-Dev/argus-table/blob/main/docs/plan/plan/12-roadmap.md).
+This is an early release. Names can still change before 1.0. Pinned rows, auto column widths, column reordering and framework wrappers come in v0.2. See the [roadmap](https://github.com/Joessst-Dev/argus-table/blob/main/docs/plan/plan/12-roadmap.md).
 
 MIT licensed.

package/dist/announce.js

@@ -0,0 +1,27 @@
+// src/announce.ts
+var region;
+/**
+* Says something to screen readers through a polite live region. The region
+* lives in the document body, not in the table: a grid may only own rows, so a
+* status element inside it would break the grid's structure. One region serves
+* every table on the page. It is visually hidden with inline styles, so page
+* CSS can't reveal it.
+*/
+function announce(doc, message) {
+	if (!region?.isConnected || region.ownerDocument !== doc) {
+		region = doc.createElement("div");
+		region.setAttribute("aria-live", "polite");
+		region.setAttribute("aria-atomic", "true");
+		region.dataset.argusAnnouncer = "";
+		region.style.cssText = "position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap";
+		doc.body.append(region);
+	}
+	const target = region;
+	target.textContent = "";
+	setTimeout(() => {
+		target.textContent = message;
+	}, 50);
+}
+export { announce };
+
+//# sourceMappingURL=announce.js.map

package/dist/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","names":[],"sources":["../src/announce.ts"],"sourcesContent":["let region: HTMLElement | undefined;\n\n/**\n * Says something to screen readers through a polite live region. The region\n * lives in the document body, not in the table: a grid may only own rows, so a\n * status element inside it would break the grid's structure. One region serves\n * every table on the page. It is visually hidden with inline styles, so page\n * CSS can't reveal it.\n */\nexport function announce(doc: Document, message: string): void {\n  if (!region?.isConnected || region.ownerDocument !== doc) {\n    region = doc.createElement('div');\n    region.setAttribute('aria-live', 'polite');\n    region.setAttribute('aria-atomic', 'true');\n    region.dataset.argusAnnouncer = '';\n    region.style.cssText =\n      'position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap';\n    doc.body.append(region);\n  }\n  const target = region;\n  // A new text node each time, so the same message twice is still announced.\n  target.textContent = '';\n  setTimeout(() => {\n    target.textContent = message;\n  }, 50);\n}\n"],"mappings":";AAAA,IAAI;;;;;;;;AASJ,SAAgB,SAAS,KAAe,SAAuB;CAC7D,IAAI,CAAC,QAAQ,eAAe,OAAO,kBAAkB,KAAK;EACxD,SAAS,IAAI,cAAc,KAAK;EAChC,OAAO,aAAa,aAAa,QAAQ;EACzC,OAAO,aAAa,eAAe,MAAM;EACzC,OAAO,QAAQ,iBAAiB;EAChC,OAAO,MAAM,UACX;EACF,IAAI,KAAK,OAAO,MAAM;CACxB;CACA,MAAM,SAAS;CAEf,OAAO,cAAc;CACrB,iBAAiB;EACf,OAAO,cAAc;CACvB,GAAG,EAAE;AACP"}

package/dist/argus-column.js

@@ -0,0 +1,121 @@
+import __decorate from "./_virtual/_@oxc-project_runtime@0.156.0/helpers/esm/decorate.js";
+import { ReactiveElement, html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { templateContent } from "lit/directives/template-content.js";
+// src/argus-column.ts
+/**
+* Tables watching their `<argus-column>` children, by table element. Columns
+* call their parent's entry when they connect, disconnect or change, so the
+* table needs no MutationObserver on its own children (which would fire on
+* every light-DOM cell render while scrolling).
+*/
+var watchers = /* @__PURE__ */ new WeakMap();
+/** Calls `onChange` whenever an `<argus-column>` child of `host` is added, removed, moved or changed. */
+function watchColumns(host, onChange) {
+	watchers.set(host, onChange);
+}
+function unwatchColumns(host) {
+	watchers.delete(host);
+}
+function notify(parent) {
+	if (parent) watchers.get(parent)?.();
+}
+/** `width` attribute: `"90"` or `"90px"` → 90, `"auto"`, `"2fr"` → `{ flex: 2 }`. */
+var widthConverter = { fromAttribute(value) {
+	if (value === null) return void 0;
+	const text = value.trim().toLowerCase();
+	if (text === "auto") return "auto";
+	const match = /^(\d*\.?\d+)(px|fr)?$/.exec(text);
+	if (!match) return void 0;
+	const n = Number(match[1]);
+	return match[2] === "fr" ? { flex: n } : n;
+} };
+/**
+* Boolean attribute with a default that may be `true`: absent → unset (the
+* default applies), `"false"` → `false`, anything else → `true`.
+*/
+var flagConverter = { fromAttribute(value) {
+	return value === null ? void 0 : value.trim().toLowerCase() !== "false";
+} };
+var ArgusColumn = class ArgusColumn extends ReactiveElement {
+	constructor(..._args) {
+		super(..._args);
+		this.columnId = "";
+		this.#parent = null;
+		this.#children = new MutationObserver(() => {
+			this.#def = void 0;
+			this.requestUpdate();
+		});
+	}
+	#parent;
+	#def;
+	#children;
+	/** Data only: no shadow root, nothing rendered. */
+	createRenderRoot() {
+		return this;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.#children.observe(this, { childList: true });
+		this.#parent = this.parentElement;
+		notify(this.#parent);
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.#children.disconnect();
+		const parent = this.#parent;
+		this.#parent = null;
+		notify(parent);
+	}
+	/**
+	* The column as the table reads it. Unset fields stay `undefined`, which the
+	* table reads as its defaults. An unknown `pin` is ignored and an unknown
+	* `align` falls back to `start`.
+	*/
+	toColumnDef() {
+		if (this.#def) return this.#def;
+		const template = [...this.children].find((c) => c instanceof HTMLTemplateElement);
+		return this.#def = {
+			id: this.columnId,
+			header: this.header,
+			accessor: this.accessor,
+			cell: this.cell ?? (template && (() => html`${templateContent(template)}`)),
+			width: this.width,
+			minWidth: this.minWidth,
+			maxWidth: this.maxWidth,
+			pin: this.pin,
+			align: this.align,
+			sortable: this.sortable,
+			resizable: this.resizable,
+			reorderable: this.reorderable
+		};
+	}
+	willUpdate() {
+		this.#def = void 0;
+	}
+	updated() {
+		notify(this.#parent);
+	}
+};
+__decorate([property({ attribute: "column-id" })], ArgusColumn.prototype, "columnId", void 0);
+__decorate([property()], ArgusColumn.prototype, "header", void 0);
+__decorate([property()], ArgusColumn.prototype, "accessor", void 0);
+__decorate([property({ attribute: false })], ArgusColumn.prototype, "cell", void 0);
+__decorate([property({ converter: widthConverter })], ArgusColumn.prototype, "width", void 0);
+__decorate([property({
+	attribute: "min-width",
+	type: Number
+})], ArgusColumn.prototype, "minWidth", void 0);
+__decorate([property({
+	attribute: "max-width",
+	type: Number
+})], ArgusColumn.prototype, "maxWidth", void 0);
+__decorate([property()], ArgusColumn.prototype, "pin", void 0);
+__decorate([property()], ArgusColumn.prototype, "align", void 0);
+__decorate([property({ converter: flagConverter })], ArgusColumn.prototype, "sortable", void 0);
+__decorate([property({ converter: flagConverter })], ArgusColumn.prototype, "resizable", void 0);
+__decorate([property({ converter: flagConverter })], ArgusColumn.prototype, "reorderable", void 0);
+ArgusColumn = __decorate([customElement("argus-column")], ArgusColumn);
+export { ArgusColumn, unwatchColumns, watchColumns };
+
+//# sourceMappingURL=argus-column.js.map

package/dist/argus-column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argus-column.js","names":["_decorate"],"sources":["../src/argus-column.ts"],"sourcesContent":["import { html, ReactiveElement, type ComplexAttributeConverter } from 'lit';\nimport { customElement, property } from 'lit/decorators.js';\nimport { templateContent } from 'lit/directives/template-content.js';\nimport type {\n  CellContent,\n  CellContext,\n  ColumnAlign,\n  ColumnDef,\n  ColumnPin,\n  ColumnWidth,\n} from './types.js';\n\n/**\n * Tables watching their `<argus-column>` children, by table element. Columns\n * call their parent's entry when they connect, disconnect or change, so the\n * table needs no MutationObserver on its own children (which would fire on\n * every light-DOM cell render while scrolling).\n */\nconst watchers = new WeakMap<Element, () => void>();\n\n/** Calls `onChange` whenever an `<argus-column>` child of `host` is added, removed, moved or changed. */\nexport function watchColumns(host: Element, onChange: () => void): void {\n  watchers.set(host, onChange);\n}\n\nexport function unwatchColumns(host: Element): void {\n  watchers.delete(host);\n}\n\nfunction notify(parent: Element | null): void {\n  if (parent) watchers.get(parent)?.();\n}\n\n/** `width` attribute: `\"90\"` or `\"90px\"` → 90, `\"auto\"`, `\"2fr\"` → `{ flex: 2 }`. */\nconst widthConverter: ComplexAttributeConverter<ColumnWidth | undefined> = {\n  fromAttribute(value) {\n    if (value === null) return undefined;\n    const text = value.trim().toLowerCase();\n    if (text === 'auto') return 'auto';\n    const match = /^(\\d*\\.?\\d+)(px|fr)?$/.exec(text);\n    if (!match) return undefined;\n    const n = Number(match[1]);\n    return match[2] === 'fr' ? { flex: n } : n;\n  },\n};\n\n/**\n * Boolean attribute with a default that may be `true`: absent → unset (the\n * default applies), `\"false\"` → `false`, anything else → `true`.\n */\nconst flagConverter: ComplexAttributeConverter<boolean | undefined> = {\n  fromAttribute(value) {\n    return value === null ? undefined : value.trim().toLowerCase() !== 'false';\n  },\n};\n\n/**\n * One column of the parent `<argus-table>`, written as markup instead of an entry in\n * its `columns` property. It is data only and renders nothing.\n *\n * Only direct children of the table count, in document order. A non-empty `columns`\n * property wins over the children. Adding, removing, moving or changing a column\n * updates the table; sizes, order and sorting are kept by `column-id`.\n *\n * A `<template>` child is the content of every cell in the column (static: the same\n * for each row). Set the `cell` property for content that depends on the row.\n *\n * @summary Declarative column of an `<argus-table>`.\n */\n@customElement('argus-column')\nexport class ArgusColumn<T = unknown> extends ReactiveElement {\n  /** Stable key, used in state objects, events and persistence. Must be unique within the table. */\n  @property({ attribute: 'column-id' })\n  columnId = '';\n\n  /** Header content: text as an attribute; a Lit template, a node or a function as a property. */\n  @property()\n  header?: CellContent | (() => CellContent);\n\n  /**\n   * How to read the cell value: a property path such as `customer.name`, or (as a\n   * property) a function of the row and its index.\n   */\n  @property()\n  accessor?: string | ((row: T, index: number) => unknown);\n\n  /** Cell content from the row: `(row, context) => content`. Property only; wins over a `<template>` child. */\n  @property({ attribute: false })\n  cell?: (row: T, context: CellContext<T>) => CellContent;\n\n  /** Width: `90` (px), `auto` to fit the content, or `2fr` for a share of the free space. Default: 150 px. */\n  @property({ converter: widthConverter })\n  width?: ColumnWidth;\n\n  /** Lower bound for resizing and for flex columns, in px. Default: 40. */\n  @property({ attribute: 'min-width', type: Number })\n  minWidth?: number;\n\n  /** Upper bound for resizing, in px. Default: no limit. */\n  @property({ attribute: 'max-width', type: Number })\n  maxWidth?: number;\n\n  /** Pins the column to the `start` or `end` side. */\n  @property()\n  pin?: ColumnPin;\n\n  /** Text alignment: `start`, `center` or `end`. Default: `start`. */\n  @property()\n  align?: ColumnAlign;\n\n  /** Whether the header can be clicked to sort. Default: `false`. */\n  @property({ converter: flagConverter })\n  sortable?: boolean;\n\n  /** Whether the column can be resized. Default: `true`; `resizable=\"false\"` turns it off. */\n  @property({ converter: flagConverter })\n  resizable?: boolean;\n\n  /** Whether the column can be moved. Default: `true`; `reorderable=\"false\"` turns it off. */\n  @property({ converter: flagConverter })\n  reorderable?: boolean;\n\n  #parent: Element | null = null;\n  #def: ColumnDef<T> | undefined;\n  readonly #children = new MutationObserver(() => {\n    this.#def = undefined;\n    this.requestUpdate();\n  });\n\n  /** Data only: no shadow root, nothing rendered. */\n  protected override createRenderRoot(): HTMLElement {\n    return this;\n  }\n\n  override connectedCallback(): void {\n    super.connectedCallback();\n    this.#children.observe(this, { childList: true });\n    this.#parent = this.parentElement;\n    notify(this.#parent);\n  }\n\n  override disconnectedCallback(): void {\n    super.disconnectedCallback();\n    this.#children.disconnect();\n    const parent = this.#parent;\n    this.#parent = null;\n    notify(parent);\n  }\n\n  /**\n   * The column as the table reads it. Unset fields stay `undefined`, which the\n   * table reads as its defaults. An unknown `pin` is ignored and an unknown\n   * `align` falls back to `start`.\n   */\n  toColumnDef(): ColumnDef<T> {\n    if (this.#def) return this.#def;\n    const template = [...this.children].find((c) => c instanceof HTMLTemplateElement);\n    return (this.#def = {\n      id: this.columnId,\n      header: this.header,\n      accessor: this.accessor,\n      cell: this.cell ?? (template && (() => html`${templateContent(template)}`)),\n      width: this.width,\n      minWidth: this.minWidth,\n      maxWidth: this.maxWidth,\n      pin: this.pin,\n      align: this.align,\n      sortable: this.sortable,\n      resizable: this.resizable,\n      reorderable: this.reorderable,\n    });\n  }\n\n  protected override willUpdate(): void {\n    this.#def = undefined;\n  }\n\n  protected override updated(): void {\n    notify(this.#parent);\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'argus-column': ArgusColumn;\n  }\n}\n"],"mappings":"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"}