@nanoporetech-digital/components 5.1.3 → 5.2.1

package/dist/types/components/table/table.pin-service.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Manages the complex business of table 'pinning'; sticking columns and rows to the scrolling parent element.
+ *
+ * *knowing* when an element is pinned is tricky.
+ * Managing the display of multiple, side-by-side pinned elements is trickier still.
+ *
+ * Pinning table columns are very different from pinning table rows:
+ * - Rows are actual elements we can select, measure and apply styles to.
+ * - Columns are disparate collections of elements that are much harder to select, measure and apply styles to.
+ *
+ * With this in mind, how columns and rows are pinned is different:
+ * Rows can have changes applied directly, Columns have changes applied via dynamic stylesheets.
+ *
+ * The service is slightly opinionated on how it pins rows and columns (with some room for override):
+ * - Pinned columns are stuck consecutively, without overlapping.
+ * e.g. If column 'name' and 'surname' are both `pin: 'start'`; 'surname' will display **next** to name.
+ * Both columns are important for context
+ *
+ * - Pinned rows are set to overlap *when* they have the same ancestor,
+ * and stuck consecutively when they have a different ancestor.
+ * e.g. `tbody > tr.pin ~ tr.pin` the second row will **overlap** the first; it's unlikely both rows will be important for context.
+ * `thead > tr.pin`, `tbody > tr.pin`. Both rows are required for context so will require next to each other.
+ *
+ * Devs can override this behaviour by setting `--pin-start`, `--pin-end`, `--pin-top`, `--pin-bottom` custom vars.
+ */
+export declare class TablePinService {
+  private cachedColMeta;
+  private tableId;
+  private tableEle;
+  private scrollElement;
+  private startColumns;
+  private endColumns;
+  private topRows;
+  private bottomRows;
+  private tableDims;
+  constructor(table: HTMLTableElement, scrollElement: HTMLElement);
+  private get pinnedStart();
+  private set pinnedStart(value);
+  private _pinnedStart;
+  /**
+   * Called when columns are either pinned or unpinned.
+   * Attaches a tiny stylesheet to target the 'last' start column.
+   * (e.g. We only want to apply drop shadow on last pinned start column - not all pinned columns)
+   */
+  private handlePinnedStartChange;
+  private get pinnedEnd();
+  private set pinnedEnd(value);
+  private _pinnedEnd;
+  /**
+   * Called when columns are either pinned or unpinned.
+   * Attaches a tiny stylesheet to target the 'first' end column.
+   * (e.g. We only want to apply drop shadow on first pinned end column - not all pinned columns)
+   */
+  private handlePinnedEndChange;
+  private get cssColDimensionCacheKey();
+  private set cssColDimensionCacheKey(value);
+  private _cssColDimensionCacheKey;
+  /**
+   * To only generate column dimension styles when necessary we
+   * maintain a cache key string via serialised column meta.
+   * Only when this key changes do we generate a new stylesheet
+   */
+  private generateCssCacheKey;
+  /**
+   * Generates pinned column width offset styles
+   * so pinned columns can appear stuck together,
+   * then attaches a stylesheet.
+   */
+  private createPinnedColDimensionStyles;
+  private getParentOffsets;
+  /**
+   * Loops through all 'top' & 'bottom' rows (on scroll or resize)
+   * Manages their visual state by applying classes on stuck / unstuck
+   * And their pinned offset / distance
+   */
+  assessRows(): void;
+  /**
+   * Loops through all 'start' & 'end' columns (on scroll or resize)
+   * Caches meta about each column (e.g. size, position-index)
+   * and decides which columns are pinned
+   */
+  assessCols(): Promise<void>;
+  private cacheX;
+  private cacheY;
+  onScroll(pos: {
+    x: number;
+    y: number;
+  }): void;
+  onResize(): void;
+}

package/dist/types/components/table/table.row.d.ts

@@ -4,12 +4,13 @@ type TableRowProps = {
   rowRenderer: TableTypes.RowRenderer;
   rowIndex: number;
   rowModel: TableTypes.RowData;
-  onColumnPinned?: TableTypes.PinnedCb;
+  onRowPinned?: TableTypes.PinnedCb;
 };
 export declare const TableRow: FunctionalComponent<TableRowProps>;
 type TableHeadFootProps = {
   rowRenderer: TableTypes.HeadFootRenderer;
-  onColumnPinned?: TableTypes.PinnedCb;
+  onRowPinned?: TableTypes.PinnedCb;
+  onColPinned?: TableTypes.PinnedCb;
 };
 export declare const TableHeadFootRow: FunctionalComponent<TableHeadFootProps>;
 export {};

package/dist/types/components/table/table.utils.d.ts

@@ -41,20 +41,6 @@ export declare function mergeCellProperties(rowIndex: number, colIndex: number,
  * @returns - a JSX node
  */
 export declare function colheadFootRender(col: TableTypes.ColumnConfig): VNode;
-/**
- * Adds element to Intersection Observer. Fires when element changes on the x axis
- * @param el - an element to observe
- * @param pos - the edge to watch (start or end)
- * @param cb - callback when an intersection state changes.
- */
-export declare function addHObserver(el: HTMLTableCellElement, pos: TableTypes.Position, cb: TableTypes.PinnedCb): void;
-/**
- * Adds element to Intersection Observer. Fires when element changes on the y axis
- * @param el - an element to observe
- * @param pos - the edge to watch (start or end)
- * @param cb - callback when an intersection state changes.
- */
-export declare function addVObserver(el: HTMLTableCellElement, pos: TableTypes.Position, cb: TableTypes.PinnedCb): void;
 /**
  * Renders a class string or map for pinned classes on the v axis.
  * @param type - element tagName
@@ -74,11 +60,6 @@ export declare function headerPinClasses(type: ValidRenderTypes, vPinned?: Table
 export declare function classListToStr(classes: {
   [key: string]: boolean;
 }): string;
-/**
- * Detects the current scroll speed as a number.
- * Use within a scroll listener
- */
-export declare const detectScrollSpeed: () => number;
 /**
  * Attempts to find the closes scrolling parental element
  * @param element - the element from which to traverse up the DOM
@@ -92,12 +73,4 @@ export declare function findScrollParent(element: HTMLElement): HTMLElement;
  * @returns true if the element's area percentage is visible
  */
 export declare function isInViewport(el: Element, percentVisible?: number): boolean;
-/**
- * Immutable array re-order
- * @param from - the index to move from
- * @param to - the index to move to
- * @param arr - the array to re-order
- * @returns - a new, re-orderd array
- */
-export declare function arrMove(from: number, to: number, arr: any[]): any[];
 export {};

package/dist/types/components.d.ts

@@ -2294,9 +2294,9 @@ export namespace Components {
         "scrollParent"?: HTMLElement | Document;
         "setTriggerPos": (offset: number | { v: number; h: number; }) => Promise<number | { v: number; h: number; }>;
         /**
-          * Upon being stuck, attach the sticker to another sticker element. A JS query selector that returns a <nano-sticker>
+          * Upon being stuck, attach the sticker to another sticker element. JS query selector string or DOM element pointing to a `<nano-sticker>`
          */
-        "stickTo": string;
+        "stickTo": string | HTMLNanoStickerElement;
     }
     interface NanoTab {
         /**
@@ -2393,6 +2393,10 @@ export namespace Components {
           * @returns a promise which resolves when complete
          */
         "addSort": (column: TableTypes.Prop, order: TableTypes.Order) => Promise<void>;
+        /**
+          * @readonly - shows the currently applied filters
+         */
+        "appliedFilters": Filter[];
         /**
           * The number of total blocks currently rendered in the table. @readonly
          */
@@ -2406,11 +2410,15 @@ export namespace Components {
          */
         "columns": TableTypes.NanoTable<any>['columns'];
         /**
-          * A custom filtering function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsey, the sort will be performed by the component. A good use-case would be performing the filter on a server / via fetch. Then on success, updating the table's data via the `rows` property
+          * A custom filtering function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsy, the sort will be performed by the component. A good use-case would be performing the filter on a server / via fetch. Then on success, updating the table's data via the `rows` property
          */
         "customFilterFn"?: (
     filters: TableTypes.Filter[]
   ) => Promise<true | TableTypes.Falsy>;
+        /**
+          * Function called whenever `col.cellTemplate` renders an unknown object. The function should render a valid HTMLElement to the cell arg. Example usage - render JSX from a 3rd party lib and append the result to the cell element.
+         */
+        "customRenderer": (node: any, cell: HTMLElement) => void;
         /**
           * A custom sorting function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsey, the sort will be performed by the component. A good use-case would be performing the sort on a server / via fetch. Then on success, updating the table's data via the `rows` property
          */
@@ -2430,9 +2438,8 @@ export namespace Components {
           * Used for custom thead row rendering
          */
         "headRender": TableTypes.HeadFootRenderer;
-        "jsxRenderer": TableTypes.HFunc<any>;
         /**
-          * Will show a loading state when set to true. By default, will be shown automatically if `rows` is a promise waiting to resolve or when performing custom filtering or sorting. *Note* when set manually, will overwrite any internal loading state. Set to 'undefined' to revert to default behaviour.
+          * Will show a loading state when set to true. By default, will be shown automatically if `rows` is a promise waiting to resolve / or falsy *or* when performing custom filtering or sorting. *Note* when set manually, will overwrite any internal loading state. Set to 'undefined' to revert to default behaviour.
          */
         "loading": boolean;
         /**
@@ -2486,7 +2493,7 @@ export namespace Components {
         "type": 'grid' | 'table';
         /**
           * Updates a row model at a given index
-          * @param row - the row to update. *Note* - this should come from the `col.cellTemplate` or `row.rowRender.template`  `rowModel` property - rows are augmented with certain properties to aid with efficient rendering
+          * @param row - the row to update.
           * @param rowIndex - the row index to insert this row
          */
         "updateRow": (row: TableTypes.RowData, rowIndex: number) => Promise<void>;
@@ -5198,6 +5205,10 @@ declare namespace LocalJSX {
           * Fire `nanoResizeContentFitChange` events notifying whether content currently fits or does not on the x, y or both axis'. Also makes the `content-fit-...` slots available
          */
         "notifyContentFit"?: 'x' | 'y' | 'xy';
+        /**
+          * Fires after any resizing
+         */
+        "onNanoResize"?: (event: NanoResizeObserveCustomEvent<ResizeObserverEntry[]>) => void;
         /**
           * Fires when the content either begins or stops fitting. Will only work when `notifyContentFit` is set.
          */
@@ -5679,9 +5690,9 @@ declare namespace LocalJSX {
          */
         "scrollParent"?: HTMLElement | Document;
         /**
-          * Upon being stuck, attach the sticker to another sticker element. A JS query selector that returns a <nano-sticker>
+          * Upon being stuck, attach the sticker to another sticker element. JS query selector string or DOM element pointing to a `<nano-sticker>`
          */
-        "stickTo"?: string;
+        "stickTo"?: string | HTMLNanoStickerElement;
     }
     interface NanoTab {
         /**
@@ -5774,6 +5785,10 @@ declare namespace LocalJSX {
      * - Add custom properties at every level
      */
     interface NanoTable {
+        /**
+          * @readonly - shows the currently applied filters
+         */
+        "appliedFilters"?: Filter[];
         /**
           * The number of total blocks currently rendered in the table. @readonly
          */
@@ -5787,11 +5802,15 @@ declare namespace LocalJSX {
          */
         "columns"?: TableTypes.NanoTable<any>['columns'];
         /**
-          * A custom filtering function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsey, the sort will be performed by the component. A good use-case would be performing the filter on a server / via fetch. Then on success, updating the table's data via the `rows` property
+          * A custom filtering function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsy, the sort will be performed by the component. A good use-case would be performing the filter on a server / via fetch. Then on success, updating the table's data via the `rows` property
          */
         "customFilterFn"?: (
     filters: TableTypes.Filter[]
   ) => Promise<true | TableTypes.Falsy>;
+        /**
+          * Function called whenever `col.cellTemplate` renders an unknown object. The function should render a valid HTMLElement to the cell arg. Example usage - render JSX from a 3rd party lib and append the result to the cell element.
+         */
+        "customRenderer"?: (node: any, cell: HTMLElement) => void;
         /**
           * A custom sorting function. Should return a promise. If the promise resolves as `true` the column UI will be updated. If the promise resolves as falsey, the sort will be performed by the component. A good use-case would be performing the sort on a server / via fetch. Then on success, updating the table's data via the `rows` property
          */
@@ -5811,9 +5830,8 @@ declare namespace LocalJSX {
           * Used for custom thead row rendering
          */
         "headRender"?: TableTypes.HeadFootRenderer;
-        "jsxRenderer"?: TableTypes.HFunc<any>;
         /**
-          * Will show a loading state when set to true. By default, will be shown automatically if `rows` is a promise waiting to resolve or when performing custom filtering or sorting. *Note* when set manually, will overwrite any internal loading state. Set to 'undefined' to revert to default behaviour.
+          * Will show a loading state when set to true. By default, will be shown automatically if `rows` is a promise waiting to resolve / or falsy *or* when performing custom filtering or sorting. *Note* when set manually, will overwrite any internal loading state. Set to 'undefined' to revert to default behaviour.
          */
         "loading"?: boolean;
         /**

package/dist/types/utils/events.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Add multiple event listeners with the same callback function
+ * @param el the element which emits events
+ * @param events the event names to listen to (string separated by a space)
+ * @param fn the function to call
+ * @param opts the event options to apply
+ */
+export declare function addListeners(el: Element | Document, events: string, fn: (e: Event) => void, opts?: AddEventListenerOptions): void;
+/**
+ * Remove multiple event listeners with the same callback function
+ * @param el the element which emits events
+ * @param events the event names to listen to (string separated by a space)
+ * @param fn the function to call
+ */
+export declare function removeListeners(el: Element | Document, events: string, fn: (e: Event) => void): void;

package/dist/types/utils/throttle.d.ts

@@ -14,4 +14,4 @@ export declare const debounce: (callback: (...args: any[]) => void, wait?: numbe
  * @param delay how long to delay before calling the function
  * @returns a throttled function to call as often as required
  */
-export declare function throttle(callback: (...args: [any]) => void, delay: number): (...args: any[]) => void;
+export declare const throttle: (callback: any, delay: any) => (...args: any[]) => any;

package/docs-json.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2023-07-13T16:29:40",
+  "timestamp": "2023-08-03T13:31:21",
   "compiler": {
     "name": "@stencil/core",
     "version": "2.23.0",
@@ -12284,6 +12284,15 @@
       ],
       "methods": [],
       "events": [
+        {
+          "event": "nanoResize",
+          "detail": "ResizeObserverEntry[]",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true,
+          "docs": "Fires after any resizing",
+          "docsTags": []
+        },
         {
           "event": "nanoResizeContentFitChange",
           "detail": "{ x: boolean; y: boolean; }",
@@ -15046,13 +15055,16 @@
         },
         {
           "name": "stickTo",
-          "type": "string",
+          "type": "HTMLNanoStickerElement | string",
           "mutable": false,
           "attr": "stick-to",
           "reflectToAttr": false,
-          "docs": "Upon being stuck, attach the sticker to another sticker element.\nA JS query selector that returns a <nano-sticker>",
+          "docs": "Upon being stuck, attach the sticker to another sticker element.\nJS query selector string or DOM element pointing to a `<nano-sticker>`",
           "docsTags": [],
           "values": [
+            {
+              "type": "HTMLNanoStickerElement"
+            },
             {
               "type": "string"
             }
@@ -15950,6 +15962,29 @@
       ],
       "usage": {},
       "props": [
+        {
+          "name": "appliedFilters",
+          "type": "Filter[]",
+          "mutable": false,
+          "reflectToAttr": false,
+          "docs": "",
+          "docsTags": [
+            {
+              "name": "readonly",
+              "text": "- shows the currently applied filters"
+            }
+          ],
+          "default": "[]",
+          "values": [
+            {
+              "type": "Filter[]"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": true,
+          "setter": false
+        },
         {
           "name": "blocksLength",
           "type": "number",
@@ -16009,7 +16044,7 @@
           "type": "(filters: Filter[]) => Promise<true | Falsy>",
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "A custom filtering function. Should return a promise.\nIf the promise resolves as `true` the column UI will be updated.\nIf the promise resolves as falsey, the sort will be performed by the component.\nA good use-case would be performing the filter on a server / via fetch.\nThen on success, updating the table's data via the `rows` property",
+          "docs": "A custom filtering function. Should return a promise.\nIf the promise resolves as `true` the column UI will be updated.\nIf the promise resolves as falsy, the sort will be performed by the component.\nA good use-case would be performing the filter on a server / via fetch.\nThen on success, updating the table's data via the `rows` property",
           "docsTags": [],
           "values": [
             {
@@ -16024,6 +16059,23 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "customRenderer",
+          "type": "(node: any, cell: HTMLElement) => void",
+          "mutable": false,
+          "reflectToAttr": false,
+          "docs": "Function called whenever `col.cellTemplate` renders an unknown object.\nThe function should render a valid HTMLElement to the cell arg.\nExample usage - render JSX from a 3rd party lib and append the result to the cell element.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "(node: any, cell: HTMLElement) => void"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "customSortFn",
           "type": "(property: keyof RowGeneric, order: Order) => Promise<true | Falsy>",
@@ -16099,30 +16151,13 @@
           "getter": false,
           "setter": false
         },
-        {
-          "name": "jsxRenderer",
-          "type": "HFunc<any>",
-          "mutable": false,
-          "reflectToAttr": false,
-          "docs": "",
-          "docsTags": [],
-          "values": [
-            {
-              "type": "HFunc<any>"
-            }
-          ],
-          "optional": false,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "loading",
           "type": "boolean",
           "mutable": false,
           "attr": "loading",
           "reflectToAttr": false,
-          "docs": "Will show a loading state when set to true.\nBy default, will be shown automatically if `rows` is a promise waiting to resolve\nor when performing custom filtering or sorting.\n*Note* when set manually, will overwrite any internal loading state.\nSet to 'undefined' to revert to default behaviour.",
+          "docs": "Will show a loading state when set to true.\nBy default, will be shown automatically if `rows` is a promise waiting to resolve / or falsy\n*or* when performing custom filtering or sorting.\n*Note* when set manually, will overwrite any internal loading state.\nSet to 'undefined' to revert to default behaviour.",
           "docsTags": [],
           "default": "undefined",
           "values": [
@@ -16143,7 +16178,7 @@
           "reflectToAttr": false,
           "docs": "To improve performance, data is split into blocks\nwhich are shown / hidden and rendered as they become visible.\nUse this to control the number of hits within a block -\nA block should fill a scrolling viewport.\nThe less perBlock the better for performance",
           "docsTags": [],
-          "default": "40",
+          "default": "50",
           "values": [
             {
               "type": "number"
@@ -16415,7 +16450,7 @@
           "docsTags": [
             {
               "name": "param",
-              "text": "row - the row to update.\n*Note* - this should come from the `col.cellTemplate` or `row.rowRender.template`  `rowModel` property\n- rows are augmented with certain properties to aid with efficient rendering"
+              "text": "row - the row to update."
             },
             {
               "name": "param",

package/docs-vscode.json

@@ -2681,7 +2681,7 @@
         },
         {
           "name": "stick-to",
-          "description": "Upon being stuck, attach the sticker to another sticker element.\nA JS query selector that returns a <nano-sticker>"
+          "description": "Upon being stuck, attach the sticker to another sticker element.\nJS query selector string or DOM element pointing to a `<nano-sticker>`"
         }
       ]
     },
@@ -2838,7 +2838,7 @@
         },
         {
           "name": "loading",
-          "description": "Will show a loading state when set to true.\nBy default, will be shown automatically if `rows` is a promise waiting to resolve\nor when performing custom filtering or sorting.\n*Note* when set manually, will overwrite any internal loading state.\nSet to 'undefined' to revert to default behaviour."
+          "description": "Will show a loading state when set to true.\nBy default, will be shown automatically if `rows` is a promise waiting to resolve / or falsy\n*or* when performing custom filtering or sorting.\n*Note* when set manually, will overwrite any internal loading state.\nSet to 'undefined' to revert to default behaviour."
         },
         {
           "name": "per-block",