@nanoporetech-digital/components 3.4.0 → 3.5.0

package/dist/types/components/table/table-interface.d.ts

@@ -1,4 +1,5 @@
-import type { VNode } from '../../stencil-public-runtime';
+import type { JSXBase } from '../../stencil-public-runtime';
+import type { VNode, FunctionalComponent } from '../../stencil-public-runtime';
 export declare namespace TableTypes {
   /** The column property */
   type ColumnProp = string | number;
@@ -6,6 +7,10 @@ export declare namespace TableTypes {
   type Position = 'start' | 'end' | 'top' | 'bottom';
   /** A function to assess whether a rendered row will be pinned to the top or bottom */
   type PinFunc = (props?: RowDataSchemaModel) => Position;
+  /** Function called, via intersection observer, when an element's pinned status changes */
+  type PinnedCb = (positions: {
+    [key in Position]?: boolean;
+  }) => void;
   /** Potential column ordering options */
   type Order = 'asc' | 'desc' | undefined;
   /** Column filtering */
@@ -18,16 +23,10 @@ export declare namespace TableTypes {
     prop: TableTypes.Prop;
     order: TableTypes.Order;
   }
-  /** Potential html properties which can be passed to a row or column */
-  interface EleProps {
-    style?: {
-      [key: string]: string | undefined;
-    };
-    class?: {
-      [key: string]: boolean;
-    } | string;
-    [attr: string]: string | number | object | boolean | undefined;
-  }
+  /** Potential html properties which can be passed to a cell or column */
+  type CellProps = JSXBase.ThHTMLAttributes<HTMLTableCellElement>;
+  /** Potential html properties which can be passed to a row */
+  type RowProps = JSXBase.HTMLAttributes<HTMLTableRowElement>;
   /** data model passed to cell rendering functions */
   interface ColumnDataSchemaModel {
     /** The column property being iterated over */
@@ -50,7 +49,8 @@ export declare namespace TableTypes {
     /** The row being rendered. You *must* nest this in your render function otherwise it will not be shown */
     renderedRow?: VNode;
   }
-  /** A JSX `createElement` function passed to rendering functions
+  /** A JSX `createElement` function passed to rendering functions.
+   * You can use this to create markup outside of JSX environments
    * e.g. https://reactjs.org/docs/react-without-jsx.html */
   interface HFunc<T> {
     (tag: any): T;
@@ -77,7 +77,17 @@ export declare namespace TableTypes {
    * A row render function, called during a any row's render to the dom.
    * It can be used to add extra markup around any given table row
    **/
-  type RowTemplateFunc<T> = (createElement: HFunc<T>, props?: RowDataSchemaModel) => T | undefined;
+  type RowTemplateFunc<T> = (
+  /** use this to create markup outside of JSX environments
+   * e.g. https://reactjs.org/docs/react-without-jsx.html */
+  createElement: HFunc<T>, 
+  /** data passed to each template */
+  props: RowDataSchemaModel, 
+  /** a helper template to minimise boilerplate.
+   * A shortcut for `<td><div class="nano-tbl__cell-content"></div></td>` */
+  TableCell: FunctionalComponent<{
+    header?: boolean;
+  }>) => T | undefined;
   /**
    * A cell render function, called during any cell's render to the dom.
    * It can be used to add any markup within a table cell.
@@ -93,11 +103,11 @@ export declare namespace TableTypes {
    */
   type ColSortComparator = (prop: keyof RowData, order: Order) => (a: RowData, b: RowData) => number;
   /** A function which can be used to apply any html attribute/s onto a table cell `td` */
-  type PropertiesFunc = (props: ColumnDataSchemaModel) => EleProps | void | undefined;
+  type PropertiesFunc = (props: ColumnDataSchemaModel) => CellProps | void | undefined;
   /** A function which can be used to apply any html attribute/s onto a table head `th` */
-  type ColPropertiesFunc = (props: ColumnConfig) => EleProps | void | undefined;
+  type ColPropertiesFunc = (props: ColumnConfig) => CellProps | void | undefined;
   /** A function which can be used to apply any html attribute/s onto a table row `tr` */
-  type RowPropertiesFunc = (props: RowDataSchemaModel) => EleProps | void | undefined;
+  type RowPropertiesFunc = (props: RowDataSchemaModel) => RowProps | void | undefined;
   /** An individual table cell's data */
   type RowData = {
     [key: string | number]: any;
@@ -106,6 +116,8 @@ export declare namespace TableTypes {
   };
   /** A data property */
   type Prop = keyof TableTypes.RowData;
+  /** Valid column data types */
+  type ColumnType = 'text' | 'string' | 'number' | 'date' | 'unknown';
   /**
    * A table column's configuration
    */
@@ -114,14 +126,15 @@ export declare namespace TableTypes {
     title: string;
     /** The row's data property to retrieve per cell render */
     prop: keyof T;
-    /** The type of data. Will affect how it is sorted and available
-     * filter operations. Will be derived automatically by default */
-    type?: 'text' | 'string' | 'number' | 'date';
+    /** The type of data. Will affect how it is sorted and the available
+     * filter operations ('text' uses browser locale to compare).
+     * If none supplied, it will be derived by default using the first row of data retrieved. */
+    type?: ColumnType;
     /** Whether this column is horizontally pinned to viewport */
     pinned?: Position;
     /** Whether this column is a row header; the cell will render a `th` not a `td` */
     rowHeader?: boolean;
-    /** Whether this column can be ordered. Defaults to true */
+    /** Whether this column can be sorted. Defaults to true */
     sortable?: boolean;
     /** Current order of this column */
     order?: Order;
@@ -129,6 +142,8 @@ export declare namespace TableTypes {
     searchable?: boolean;
     /** Current filters applied to this column  */
     filter?: string;
+    /** Whether this column can be dragged to change column order */
+    draggable?: boolean;
     /**
      * A cell render function, called during any cell's render to the dom.
      * It can be used to add any markup within a table cell.
@@ -153,7 +168,7 @@ export declare namespace TableTypes {
    */
   interface RowRenderer {
     /** Function to decide whether the row is vertically pinned. */
-    pinned: PinFunc;
+    pinned?: PinFunc;
     /**
      * A row render function, called during a any row's render to the dom.
      * It can be used to add extra markup around any given table row
@@ -173,11 +188,11 @@ export declare namespace TableTypes {
      * A row render function, called during a any row's render to the dom.
      * It can be used to add extra markup around any given table row.
      * If used, and you want to see the rendered row, you *must* nest it within your
-     * jsx function
+     * jsx function e.g. `(h, props) => { return [props.renderedRow, <tr><td>Custom thing</td></tr>]}`
      **/
     template?: RowTemplateFunc<VNode | VNode[]>;
     /** A function which can be used to apply any html attribute/s onto a table row `tr` */
-    rowProperties?: () => EleProps | void | undefined;
+    rowProperties?: () => RowProps | void | undefined;
   }
   type TBody = {
     rows: TableTypes.NanoTable['rows'];

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

@@ -0,0 +1,18 @@
+import { FunctionalComponent, VNode } from '../../stencil-public-runtime';
+/**
+ * Renders a cell using a custom renderer if set.
+ * @param rowIndex - the current row index being rendered
+ * @param colIndex - the current column index being rendered
+ * @returns - a JSX node
+ */
+export declare function cellRender(rowIndex: number, colIndex: number): VNode;
+export declare const baseCellClasses: (colIndex: number, toString?: boolean) => string | {
+  [x: string]: boolean;
+};
+declare type TableCellProps = {
+  rowIndex: number;
+  colIndex: number;
+  nestedContent?: VNode;
+};
+export declare const TableCell: FunctionalComponent<TableCellProps>;
+export {};

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

@@ -8,10 +8,12 @@ import type { TableTypes } from '../../interface';
  *- Built-in column sort
  *- Easily swap in API / async based search / filter & sort
  *- Pin headers, footers, rows, columns
+ *- Drag-&-Drop columns to re-order
  *- Add custom rendering at every level
  *- Add custom properties at every level
  *
  * @slot caption - The table's caption. You must either use this or the `caption` attribute.
+ * @slot no-results - text to display when search or filtering yields no results
  */
 export declare class Table implements ComponentInterface {
   constructor();
@@ -65,6 +67,18 @@ export declare class Table implements ComponentInterface {
    * 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 */
   customSortFn?: (property: TableTypes.Prop, order: TableTypes.Order) => Promise<void>;
+  /**
+   * The default sortable option for all columns.
+   * `true` will enable column sorting unless you set `sortable: false` on a column
+   * `false` will disable column sorting unless you set `sortable: true` on a column
+   */
+  defaultSort: boolean;
+  /**
+   * The default draggable option for all columns.
+   * `true` will enable column drag-to-reorder unless you set `draggable: false` on a column
+   * `false` will disable column drag-to-reorder unless you set `draggable: true` on a column
+   */
+  defaultColDraggable: boolean;
   handleSearchTermChange(): void;
   /** Fired whenever a block is activated by scrolling into view / becoming visible
    * This could be leveraged for infinite scrolling / to fetch more data.
@@ -86,8 +100,20 @@ export declare class Table implements ComponentInterface {
     column: TableTypes.Prop;
     order: TableTypes.Order;
   }>;
+  /** Fired when a column has started dragging */
+  nanoTblColDrag: EventEmitter<{
+    column: TableTypes.Prop;
+  }>;
+  /** Fired when a column has been dropped (after dragging)
+   * `event.preventDefault()` to stop column re-order. */
+  nanoTblColDrop: EventEmitter<{
+    fromCol: TableTypes.Prop;
+    toCol: TableTypes.Prop;
+    fromIndex: number;
+    toIndex: number;
+  }>;
   /** Fired before a column is filtered.
-   * `event.preventDefault()` to stop filtering.  */
+   * `event.preventDefault()` to stop filtering. */
   nanoTblBeforeFilter: EventEmitter<{
     filters: TableTypes.Filter[];
   }>;
@@ -119,6 +145,11 @@ export declare class Table implements ComponentInterface {
    * @returns a promise which resolves when complete
    */
   addFilters(filters: TableTypes.Filter[], additive?: boolean): Promise<void>;
+  /** Remove filters from a column
+   * @param columnNames - the filters to apply
+   * @returns a promise which resolves when complete
+   */
+  removeFilters(columnNames: TableTypes.Prop[]): Promise<void>;
   host: HTMLNanoTableElement;
   private renderId;
   private store;
@@ -127,6 +158,7 @@ export declare class Table implements ComponentInterface {
   private currentSort;
   private tableEle;
   private topAnchorEle;
+  private tableWrapperEle;
   /** `tr` elements split into units - defined by `perPage`
     These are show / hidden for perf */
   blocks: TableTypes.TBody[];
@@ -145,6 +177,8 @@ export declare class Table implements ComponentInterface {
   private _isReady;
   scrollListener(): void;
   private handleReady;
+  private colDrag;
+  private colDrop;
   /**
    * Start a sort - can be cancelled by `preventDefault`
    * @param order - column order
@@ -197,6 +231,7 @@ export declare class Table implements ComponentInterface {
   /** Process slotted content */
   private processSlots;
   private handleColumnPinned;
+  private handleResizeChange;
   componentWillLoad(): Promise<void>;
   connectedCallback(): void;
   componentDidLoad(): void;

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

@@ -0,0 +1,16 @@
+import { FunctionalComponent } from '../../stencil-public-runtime';
+import type { TableTypes } from '../../interface';
+declare type TableColHeadProps = {
+  column: TableTypes.ColumnConfig;
+  headRenderer: TableTypes.HeadFootRenderer;
+  onColumnSortClick?: (order: TableTypes.Order, column: TableTypes.Prop, el: HTMLTableCellElement) => void;
+  onColumnPinned?: TableTypes.PinnedCb;
+  onColumnDrag?: (column: TableTypes.Prop, el: HTMLTableCellElement) => void;
+  onColumnDrop?: (fromColumn: TableTypes.Prop, toColumn: TableTypes.Prop, el: HTMLTableCellElement) => void;
+  defaults: {
+    draggable?: boolean;
+    sortable?: boolean;
+  };
+};
+export declare const TableColHead: FunctionalComponent<TableColHeadProps>;
+export {};

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

@@ -0,0 +1,15 @@
+import { FunctionalComponent } from '../../stencil-public-runtime';
+import type { TableTypes } from '../../interface';
+declare type TableRowProps = {
+  rowRenderer: TableTypes.RowRenderer;
+  rowIndex: number;
+  row: TableTypes.RowData;
+  onColumnPinned?: TableTypes.PinnedCb;
+};
+export declare const TableRow: FunctionalComponent<TableRowProps>;
+declare type TableHeadFootProps = {
+  rowRenderer: TableTypes.HeadFootRenderer;
+  onColumnPinned?: TableTypes.PinnedCb;
+};
+export declare const TableHeadFootRow: FunctionalComponent<TableHeadFootProps>;
+export {};

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

@@ -1,3 +1,102 @@
+import { VNode } from '../../stencil-public-runtime';
+import type { TableTypes } from '../../interface';
+declare type ValidRenderTypes = 'tr' | 'th' | 'td';
+/**
+ * Get a model object for custom cell / property renderers.
+ * @param rowIndex - the current row index being rendered
+ * @param colIndex - the current column index being rendered
+ * @returns a model object which will be passed to custom renderers
+ */
+export declare function colDataModel(rowIndex: number, colIndex: number): TableTypes.ColumnDataSchemaModel;
+/**
+ * Get a model object for custom row renderers.
+ * @param rowIndex
+ * @returns a model object passed to custom row renderers
+ */
+export declare function rowDataModel(rowIndex: number): TableTypes.RowDataSchemaModel;
+/**
+ * Merges 2 objects of properties together
+ * @param current - property object
+ * @param extra - additional object property
+ * @returns - merged properties that can be applied to a node
+ */
+export declare function mergeProperties<T extends TableTypes.CellProps | TableTypes.CellProps>(current: T, extra: T): T;
+/**
+ * Returns the current nano-table's stores.
+ * @returns the current nano-table stores
+ */
+export declare function fetchStores(): import("./table.store").TableStores;
+/**
+ * Merges any defined cell properties with properties
+ * required by `nano-table` functionality
+ * @param rowIndex - the current row index being rendered
+ * @param colIndex = the current column index being rendered
+ * @param defaultProps - default properties required by `nano-table`
+ * @returns - the merged properties that will be applied to a node
+ */
+export declare function mergeCellProperties(rowIndex: number, colIndex: number, defaultProps: TableTypes.CellProps): TableTypes.CellProps;
+/**
+ * Renders a table header (within a thead) using a custom template if set.
+ * @param col - the current column config object
+ * @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
+ * @param vPinned - whether element is currently pinned vertically to top or bottom
+ * @param toString - render as a string (defaults to class map)
+ */
+export declare function headerPinClasses(type: ValidRenderTypes, vPinned?: TableTypes.Position, toString?: false): {
+  [key: string]: boolean;
+};
+export declare function headerPinClasses(type: ValidRenderTypes, vPinned?: TableTypes.Position, toString?: true): string;
+/**
+ * Turns a class map {'string': boolean} to class string
+ * @param classes - the class map to convert
+ * @returns a class string
+ */
+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
+ * @returns - the closest scrolling parental element
+ */
 export declare function findScrollParent(element: HTMLElement): HTMLElement;
+/**
+ * Checks whether an element is currently viewable within the viewport
+ * @param el - element to check
+ * @param percentVisible - the percentage of the element that should be within the viewport
+ * @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

@@ -587,6 +587,8 @@ export namespace Components {
          */
         "setFocus": (day?: boolean, forceFocusVisible?: boolean) => Promise<void>;
     }
+    interface NanoDemo {
+    }
     interface NanoDetails {
         /**
           * Color to use from your application's color palette.
@@ -2031,6 +2033,14 @@ export namespace Components {
     property: TableTypes.Prop,
     order: TableTypes.Order
   ) => Promise<void>;
+        /**
+          * The default draggable option for all columns. `true` will enable column drag-to-reorder unless you set `draggable: false` on a column `false` will disable column drag-to-reorder unless you set `draggable: true` on a column
+         */
+        "defaultColDraggable": boolean;
+        /**
+          * The default sortable option for all columns. `true` will enable column sorting unless you set `sortable: false` on a column `false` will disable column sorting unless you set `sortable: true` on a column
+         */
+        "defaultSort": boolean;
         /**
           * Used for custom tfoot row rendering
          */
@@ -2051,6 +2061,12 @@ export namespace Components {
           * When loading rows asynchronously, this will render this number of placeholder rows
          */
         "placeholderSize": number;
+        /**
+          * Remove filters from a column
+          * @param columnNames - the filters to apply
+          * @returns a promise which resolves when complete
+         */
+        "removeFilters": (columnNames: TableTypes.Prop[]) => Promise<void>;
         /**
           * Remove any column filters currently applied
           * @returns a promise which resolves when complete
@@ -2368,6 +2384,12 @@ declare global {
         prototype: HTMLNanoDatePickerElement;
         new (): HTMLNanoDatePickerElement;
     };
+    interface HTMLNanoDemoElement extends Components.NanoDemo, HTMLStencilElement {
+    }
+    var HTMLNanoDemoElement: {
+        prototype: HTMLNanoDemoElement;
+        new (): HTMLNanoDemoElement;
+    };
     interface HTMLNanoDetailsElement extends Components.NanoDetails, HTMLStencilElement {
     }
     var HTMLNanoDetailsElement: {
@@ -2598,6 +2620,7 @@ declare global {
         "nano-datalist": HTMLNanoDatalistElement;
         "nano-date-input": HTMLNanoDateInputElement;
         "nano-date-picker": HTMLNanoDatePickerElement;
+        "nano-demo": HTMLNanoDemoElement;
         "nano-details": HTMLNanoDetailsElement;
         "nano-dialog": HTMLNanoDialogElement;
         "nano-drawer": HTMLNanoDrawerElement;
@@ -3219,6 +3242,8 @@ declare namespace LocalJSX {
          */
         "selectedDate"?: string;
     }
+    interface NanoDemo {
+    }
     interface NanoDetails {
         /**
           * Color to use from your application's color palette.
@@ -4752,6 +4777,14 @@ declare namespace LocalJSX {
     property: TableTypes.Prop,
     order: TableTypes.Order
   ) => Promise<void>;
+        /**
+          * The default draggable option for all columns. `true` will enable column drag-to-reorder unless you set `draggable: false` on a column `false` will disable column drag-to-reorder unless you set `draggable: true` on a column
+         */
+        "defaultColDraggable"?: boolean;
+        /**
+          * The default sortable option for all columns. `true` will enable column sorting unless you set `sortable: false` on a column `false` will disable column sorting unless you set `sortable: true` on a column
+         */
+        "defaultSort"?: boolean;
         /**
           * Used for custom tfoot row rendering
          */
@@ -4800,6 +4833,21 @@ declare namespace LocalJSX {
         "onNanoTblBlockRendered"?: (event: NanoTableCustomEvent<{
     block: number;
     totalBlocks: number;
+  }>) => void;
+        /**
+          * Fired when a column has started dragging
+         */
+        "onNanoTblColDrag"?: (event: NanoTableCustomEvent<{
+    column: TableTypes.Prop;
+  }>) => void;
+        /**
+          * Fired when a column has been dropped (after dragging) `event.preventDefault()` to stop column re-order.
+         */
+        "onNanoTblColDrop"?: (event: NanoTableCustomEvent<{
+    fromCol: TableTypes.Prop;
+    toCol: TableTypes.Prop;
+    fromIndex: number;
+    toIndex: number;
   }>) => void;
         /**
           * Fired when the table has done it's first complete render
@@ -4910,6 +4958,7 @@ declare namespace LocalJSX {
         "nano-datalist": NanoDatalist;
         "nano-date-input": NanoDateInput;
         "nano-date-picker": NanoDatePicker;
+        "nano-demo": NanoDemo;
         "nano-details": NanoDetails;
         "nano-dialog": NanoDialog;
         "nano-drawer": NanoDrawer;
@@ -4965,6 +5014,7 @@ declare module "@stencil/core" {
             "nano-datalist": LocalJSX.NanoDatalist & JSXBase.HTMLAttributes<HTMLNanoDatalistElement>;
             "nano-date-input": LocalJSX.NanoDateInput & JSXBase.HTMLAttributes<HTMLNanoDateInputElement>;
             "nano-date-picker": LocalJSX.NanoDatePicker & JSXBase.HTMLAttributes<HTMLNanoDatePickerElement>;
+            "nano-demo": LocalJSX.NanoDemo & JSXBase.HTMLAttributes<HTMLNanoDemoElement>;
             "nano-details": LocalJSX.NanoDetails & JSXBase.HTMLAttributes<HTMLNanoDetailsElement>;
             "nano-dialog": LocalJSX.NanoDialog & JSXBase.HTMLAttributes<HTMLNanoDialogElement>;
             "nano-drawer": LocalJSX.NanoDrawer & JSXBase.HTMLAttributes<HTMLNanoDrawerElement>;