@nxgt/material-core 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @nxgt/material-core
 
+## 0.4.0
+
+### Minor Changes
+
+- [#431](https://github.com/softistx/nxgt-material/pull/431) [`bd58a6f`](https://github.com/softistx/nxgt-material/commit/bd58a6f67bdc25d4b4d0d7d88c52784869ad1529) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `DataTable` renders server-side data: one page from a loader, with the query in the URL. Everything is opt-in; a table that sets none of the new props renders and behaves as before.
+  
+  - `manual`: `data` is one server page, rendered as given — no client paging, sorting or filtering — and the footer becomes `DataTableServerFooter` (exported).
+  - `pagination={{ totalCount, offset, previous, next }}`: the server footer's range ("41–60 of 133", `material.table.pagination.range`) and Previous / Next, each an href (a real link, `rel="prev"` / `rel="next"`, that works with no JavaScript) or a callback (a button); disabled when absent and while `loading`.
+  - Controlled sorting: `sorting` + `onSortingChange(sorting)` in React, `v-model:sorting` in Vue. The headers show the sorting they are given; the callback receives the new `SortingState`, not an updater.
+  - `getRowId(row, index)` and controlled selection by id: `rowSelection` + `onRowSelectionChange(selection)` in React, `v-model:row-selection` in Vue. Ids of other pages are kept, and the server footer counts them all.
+  - `getRowHref(row)`: the first data cell becomes a link to the row's page, and a click anywhere else on the row (but on a control, in a portal, or at the end of a text selection) follows it. `onRowClick(row, event)` (`@row-click` in Vue) makes the row focusable and activatable with Enter.
+  - `linkComponent`: the link rendered for row and page links, given `href` (wrap React Router's `Link` or vue-router's `RouterLink`, which take `to`). Default: a plain `<a>`.
+  - `footer`: a render function (React, Vue) or the `#footer` slot (Vue) replaces the footer; `footer={false}` removes it.
+  - New `material.table.pagination.*` strings, in English and French: `label`, `range`, `range-open`, `total`, `selected`.
+  
+  `@nxgt/material-core` gains `/row-activation` (`isRowActivation`, `followRowLink`, `ROW_CONTROL_SELECTOR`, `ROW_LINK_SELECTOR`, `RowClick`): the clickable-row rule both libraries' `DataTable` use.
+
 ## 0.3.2
 
 ### Patch Changes

package/README.md

@@ -70,6 +70,7 @@ built-in.
 | `/pdf-viewer` | The PDF viewer's pure half: page geometry and fit (`readerFitScale`, `placeholderSize`, `rotatedSize`, `PdfPageSize`, `FitMode`), page sizes (`readPageSizes`, `createPageSizesLoader`), the scroll spy (`createScrollSpy`, `revealHit`, `scrollIntoArea`), the opening page's pin (`pinToPage`, whose optional `onRelease` runs once when it lets go, and `pinHolds`, whether the view is still where it puts the page), text search (`pageTextFromItems`, `findTextMatches`, `searchDocument`), `escapeHtml`, `mapPdfOutline` |
 | `/currency-digits` | `currencyFractionDigits` — the decimals `CurrencyField` shows |
 | `/field-blur-layers` | `layerOf`, `openerOf`, `FieldLayers` — whose overlay a layer of the page is, for a field's blur |
+| `/row-activation` | `isRowActivation`, `followRowLink`, `ROW_CONTROL_SELECTOR`, `ROW_LINK_SELECTOR`, `RowClick` — whether a click on a table row follows its link, and following it |
 | `/format-file-size` | `formatFileSize` — a byte count as `'1.5 KB'` |
 | `/slider-ticks` | `tickValues` — where a slider's tick marks sit |
 | `/date-range` | `DATE_RANGE_PRESET_IDS`, `presetRange`, `resolvePresetRange`, `isSameDayRange`, `isRangeDisabled`, `withTimeOf`, `endOfDayTime`, `clampRangeEnd`, `keepRangeTimes` and the types `DayRange`, `PartialDayRange`, `DateRangePreset`, `DateRangePresetId`, `DateRangePresetOption`, `DateRangeRules` — `DateRangeField`'s presets and times |
@@ -465,6 +466,24 @@ field.addEventListener('focusout', (event) => {
 });
 ```
 
+### A clickable table row: `/row-activation`
+
+A row whose first cell links to its page should follow that link on a click
+anywhere else on the row — but not on its checkbox or its buttons, not from
+a menu its cell opened into `<body>`, and not when the click ends a text
+selection. `isRowActivation` says whether a click is one; `followRowLink`
+clicks the row's link (`ROW_LINK_SELECTOR`) with the click's modifier keys,
+so a router's link navigates as it does on its own click. Both read the DOM
+when called, never at import.
+
+```ts
+import { followRowLink, isRowActivation } from '@nxgt/material-core/row-activation';
+
+row.addEventListener('click', (event) => {
+	if (isRowActivation(event, row)) followRowLink(row, event);
+});
+```
+
 ### Bundling pdfkit's fonts: `/vite`
 
 An SSR server bundled into a single file with no `node_modules` needs

package/dist/lib/row-activation.d.ts

@@ -0,0 +1,30 @@
+/** What a click inside a row must not activate the row from: its controls
+ * (checkboxes, buttons, links, menus, fields) and anything marked
+ * `data-row-click-ignore`. */
+export declare const ROW_CONTROL_SELECTOR: string;
+/** The row's own link, which a click on the row follows: the element marked
+ * `data-slot="data-table-row-link"`, else the first link of the cell marked
+ * `data-row-link-cell` (for a link component that drops the `data-slot` it
+ * is given). */
+export declare const ROW_LINK_SELECTOR = "[data-slot=\"data-table-row-link\"],[data-row-link-cell] a[href]";
+/** The parts of a click this module reads. */
+export type RowClick = {
+    target: EventTarget | null;
+    button: number;
+    defaultPrevented: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+};
+/** Whether `event`, a click that reached `row`, activates the row: a primary
+ * click, not handled yet, inside the row's own DOM (not in a portal its
+ * cells opened), not on one of its controls, and not the end of a text
+ * selection in it. */
+export declare function isRowActivation(event: RowClick, row: Element): boolean;
+/** Follows the row's link (`ROW_LINK_SELECTOR`) as if it had been clicked,
+ * with the modifier keys of `event`: a router's link navigates as it does on
+ * its own click, Ctrl/Cmd+click opens a tab where the browser allows it.
+ * `false` when the row has no link. */
+export declare function followRowLink(row: Element, event: RowClick): boolean;
+//# sourceMappingURL=row-activation.d.ts.map

package/dist/lib/row-activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-activation.d.ts","sourceRoot":"","sources":["../../src/lib/row-activation.ts"],"names":[],"mappings":"AAIA;;8BAE8B;AAC9B,eAAO,MAAM,oBAAoB,QAgBtB,CAAC;AAEZ;;;gBAGgB;AAChB,eAAO,MAAM,iBAAiB,qEACmC,CAAC;AAElE,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAMF;;;sBAGsB;AACtB,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAgBtE;AAED;;;uCAGuC;AACvC,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAgBpE"}

package/dist/lib/row-activation.js

@@ -0,0 +1,62 @@
+// src/lib/row-activation.ts
+var ROW_CONTROL_SELECTOR = [
+  "a[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "label",
+  "summary",
+  '[contenteditable="true"]',
+  '[role="button"]',
+  '[role="checkbox"]',
+  '[role="link"]',
+  '[role="menuitem"]',
+  '[role="switch"]',
+  '[role="combobox"]',
+  "[data-row-click-ignore]"
+].join(",");
+var ROW_LINK_SELECTOR = '[data-slot="data-table-row-link"],[data-row-link-cell] a[href]';
+function isElement(target) {
+  return target !== null && typeof target.closest === "function";
+}
+function isRowActivation(event, row) {
+  if (event.defaultPrevented || event.button !== 0)
+    return false;
+  const { target } = event;
+  if (!isElement(target) || !row.contains(target))
+    return false;
+  const control = target.closest(ROW_CONTROL_SELECTOR);
+  if (control && control !== row && row.contains(control))
+    return false;
+  const selection = row.ownerDocument?.getSelection?.();
+  if (selection && !selection.isCollapsed && selection.anchorNode && row.contains(selection.anchorNode)) {
+    return false;
+  }
+  return true;
+}
+function followRowLink(row, event) {
+  const link = row.querySelector(ROW_LINK_SELECTOR);
+  const view = row.ownerDocument?.defaultView;
+  if (!link || !view)
+    return false;
+  link.dispatchEvent(new view.MouseEvent("click", {
+    bubbles: true,
+    cancelable: true,
+    button: 0,
+    ctrlKey: event.ctrlKey,
+    metaKey: event.metaKey,
+    shiftKey: event.shiftKey,
+    altKey: event.altKey
+  }));
+  return true;
+}
+export {
+  ROW_CONTROL_SELECTOR,
+  ROW_LINK_SELECTOR,
+  followRowLink,
+  isRowActivation
+};
+
+//# debugId=B5C72BCA21047D6B64756E2164756E21
+//# sourceMappingURL=row-activation.js.map

package/dist/lib/row-activation.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/row-activation.ts"],
+  "sourcesContent": [
+    "// A clickable table row: a click anywhere on the row, but on a control of its\n// own, does what the row's link (or its click handler) does. Shared by both\n// libraries' `DataTable`. Reads the DOM only when called, never at import.\n\n/** What a click inside a row must not activate the row from: its controls\n * (checkboxes, buttons, links, menus, fields) and anything marked\n * `data-row-click-ignore`. */\nexport const ROW_CONTROL_SELECTOR = [\n\t'a[href]',\n\t'button',\n\t'input',\n\t'select',\n\t'textarea',\n\t'label',\n\t'summary',\n\t'[contenteditable=\"true\"]',\n\t'[role=\"button\"]',\n\t'[role=\"checkbox\"]',\n\t'[role=\"link\"]',\n\t'[role=\"menuitem\"]',\n\t'[role=\"switch\"]',\n\t'[role=\"combobox\"]',\n\t'[data-row-click-ignore]',\n].join(',');\n\n/** The row's own link, which a click on the row follows: the element marked\n * `data-slot=\"data-table-row-link\"`, else the first link of the cell marked\n * `data-row-link-cell` (for a link component that drops the `data-slot` it\n * is given). */\nexport const ROW_LINK_SELECTOR =\n\t'[data-slot=\"data-table-row-link\"],[data-row-link-cell] a[href]';\n\n/** The parts of a click this module reads. */\nexport type RowClick = {\n\ttarget: EventTarget | null;\n\tbutton: number;\n\tdefaultPrevented: boolean;\n\tctrlKey?: boolean;\n\tmetaKey?: boolean;\n\tshiftKey?: boolean;\n\taltKey?: boolean;\n};\n\nfunction isElement(target: EventTarget | null): target is Element {\n\treturn target !== null && typeof (target as Element).closest === 'function';\n}\n\n/** Whether `event`, a click that reached `row`, activates the row: a primary\n * click, not handled yet, inside the row's own DOM (not in a portal its\n * cells opened), not on one of its controls, and not the end of a text\n * selection in it. */\nexport function isRowActivation(event: RowClick, row: Element): boolean {\n\tif (event.defaultPrevented || event.button !== 0) return false;\n\tconst { target } = event;\n\tif (!isElement(target) || !row.contains(target)) return false;\n\tconst control = target.closest(ROW_CONTROL_SELECTOR);\n\tif (control && control !== row && row.contains(control)) return false;\n\tconst selection = row.ownerDocument?.getSelection?.();\n\tif (\n\t\tselection &&\n\t\t!selection.isCollapsed &&\n\t\tselection.anchorNode &&\n\t\trow.contains(selection.anchorNode)\n\t) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n\n/** Follows the row's link (`ROW_LINK_SELECTOR`) as if it had been clicked,\n * with the modifier keys of `event`: a router's link navigates as it does on\n * its own click, Ctrl/Cmd+click opens a tab where the browser allows it.\n * `false` when the row has no link. */\nexport function followRowLink(row: Element, event: RowClick): boolean {\n\tconst link = row.querySelector(ROW_LINK_SELECTOR);\n\tconst view = row.ownerDocument?.defaultView;\n\tif (!link || !view) return false;\n\tlink.dispatchEvent(\n\t\tnew view.MouseEvent('click', {\n\t\t\tbubbles: true,\n\t\t\tcancelable: true,\n\t\t\tbutton: 0,\n\t\t\tctrlKey: event.ctrlKey,\n\t\t\tmetaKey: event.metaKey,\n\t\t\tshiftKey: event.shiftKey,\n\t\t\taltKey: event.altKey,\n\t\t}),\n\t);\n\treturn true;\n}\n"
+  ],
+  "mappings": ";AAOO,IAAM,uBAAuB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,EAAE,KAAK,GAAG;AAMH,IAAM,oBACZ;AAaD,SAAS,SAAS,CAAC,QAA+C;AAAA,EACjE,OAAO,WAAW,QAAQ,OAAQ,OAAmB,YAAY;AAAA;AAO3D,SAAS,eAAe,CAAC,OAAiB,KAAuB;AAAA,EACvE,IAAI,MAAM,oBAAoB,MAAM,WAAW;AAAA,IAAG,OAAO;AAAA,EACzD,QAAQ,WAAW;AAAA,EACnB,IAAI,CAAC,UAAU,MAAM,KAAK,CAAC,IAAI,SAAS,MAAM;AAAA,IAAG,OAAO;AAAA,EACxD,MAAM,UAAU,OAAO,QAAQ,oBAAoB;AAAA,EACnD,IAAI,WAAW,YAAY,OAAO,IAAI,SAAS,OAAO;AAAA,IAAG,OAAO;AAAA,EAChE,MAAM,YAAY,IAAI,eAAe,eAAe;AAAA,EACpD,IACC,aACA,CAAC,UAAU,eACX,UAAU,cACV,IAAI,SAAS,UAAU,UAAU,GAChC;AAAA,IACD,OAAO;AAAA,EACR;AAAA,EACA,OAAO;AAAA;AAOD,SAAS,aAAa,CAAC,KAAc,OAA0B;AAAA,EACrE,MAAM,OAAO,IAAI,cAAc,iBAAiB;AAAA,EAChD,MAAM,OAAO,IAAI,eAAe;AAAA,EAChC,IAAI,CAAC,QAAQ,CAAC;AAAA,IAAM,OAAO;AAAA,EAC3B,KAAK,cACJ,IAAI,KAAK,WAAW,SAAS;AAAA,IAC5B,SAAS;AAAA,IACT,YAAY;AAAA,IACZ,QAAQ;AAAA,IACR,SAAS,MAAM;AAAA,IACf,SAAS,MAAM;AAAA,IACf,UAAU,MAAM;AAAA,IAChB,QAAQ,MAAM;AAAA,EACf,CAAC,CACF;AAAA,EACA,OAAO;AAAA;",
+  "debugId": "B5C72BCA21047D6B64756E2164756E21",
+  "names": []
+}

package/docs/roadmap.md

@@ -31,6 +31,10 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **Clickable table rows** (`/row-activation`) — whether a click on a row
+  should follow its link (not on a control, not in a portal, not the end of
+  a text selection) and following it with the click's modifier keys, for
+  both libraries' `DataTable`. 0.4.0.
 - **Date range presets and times** (`/date-range`) — the built-in presets'
   ranges, whether a field's rules rule a range out, and the time of day on
   each end, for both libraries' `DateRangeField`. 0.3.0.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, the date range presets, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {
@@ -93,6 +93,11 @@
 			"import": "./dist/lib/field-blur-layers.js",
 			"default": "./dist/lib/field-blur-layers.js"
 		},
+		"./row-activation": {
+			"types": "./dist/lib/row-activation.d.ts",
+			"import": "./dist/lib/row-activation.js",
+			"default": "./dist/lib/row-activation.js"
+		},
 		"./format-file-size": {
 			"types": "./dist/lib/format-file-size.d.ts",
 			"import": "./dist/lib/format-file-size.js",
@@ -172,6 +177,7 @@
 			"src/lib/pdf-download.ts",
 			"src/lib/currency-digits.ts",
 			"src/lib/field-blur-layers.ts",
+			"src/lib/row-activation.ts",
 			"src/lib/format-file-size.ts",
 			"src/lib/slider-ticks.ts",
 			"src/lib/date-range.ts",