@momentum-ui/web-components 2.14.11 → 2.14.13

package/src/components/table-advanced/TableAdvanced.md

@@ -0,0 +1,233 @@
+# Advanced Table Component
+
+This will render "classic" HTML `<table>` described in `config` property and filled with `data`.
+
+## Properties
+
+| Name     | Type                | Description                                       |
+| :------- | :------------------ | :------------------------------------------------ |
+| `config` | [`Config`](#config) | Table columns configuration object **[required]** |
+| `data`   | [`Data`](#data)     | Table rows data **[required]**                    |
+
+### Config
+
+Configure columns and additional features here. Number of columns must match parsed data row length.
+
+```ts
+type Config = {
+  // will make table "fixed" on scroll
+  isStickyHeader?: boolean;
+
+  cols: {
+    // REQUIRED - Please see "Column Definition" downstairs
+    define: Column[];
+    isDraggable?: boolean;
+    isResizable?: boolean;
+    // column with this ID will be collapsed
+    collapse?: ColId;
+  };
+
+  rows?: {
+    isDraggable?: boolean;
+    selectable?: "none" | "single" | "multiple";
+  };
+
+  // Please see "Templates" downstairs
+  cellTemplates?: Record<string, CellTemplate>;
+
+  default?: {
+    // set default "filter" and "sorting" fro all columns that has this props undefined
+    col?: ColumnDefaults;
+
+    // column with this ID will be sorted on table creation
+    sort?: {
+      colId: ColId;
+      order: SortOrder;
+    };
+
+    // column with this ID will be sorted on table creation
+    filter?: {
+      colId: ColId;
+      input: string;
+      selectedIndex: number;
+    };
+  };
+
+  // will add caption and summary to table (accessibility)
+  head?: {
+    caption?: string;
+    summary?: string;
+    tableDescription?: string;
+  };
+};
+```
+
+### Column Definition
+
+You **need** to define columns of your table. Number of columns must correspond to provided [`Data`](#data).  
+You can define column:
+
+```ts
+type Column = {
+  // please provide unique ID
+  id: string;
+  title: string;
+  width?: string;
+  sorter?: "byString" | "byNumber" | SortComparator;
+  // see "custom filters" downstairs
+  filters?: "forString" | "forNumber" | Filter.Options[];
+  // this will make column <th scope="row"> not <td>
+  isHeader?: boolean;
+};
+```
+
+Or column group:
+
+```ts
+type ColumnGroup = {
+  groupName: string;
+  children: Column[];
+};
+```
+
+### Custom filters for column
+
+Here is an example how to define your own set of filters for column.
+
+```ts
+import { Filter } from "./src/filter"; // Keep type import as a relative path
+
+const config: TableAdvanced.Config = {
+  cols: {
+    define: [
+      {
+        id: "col1",
+        title: "Title",
+        filters: [
+          Filter.OPTIONS.contains,
+          Filter.OPTIONS.notContains,
+          {
+            label: "Second Char is",
+            input: { placeholder: "Second char", maxlength: 1 },
+            predicate: (content, input) => (content.length > 1 ? content[1] == input : false)
+          }
+        ]
+      }
+    ]
+  }
+};
+```
+
+## Data
+
+Data is **required** property and can be provided in form of:  
+  
+`string[][]` - outer array is *rows* inner array is *columns*. Inner arrays must contain number of elements that is equal to **column** definitions.  
+`string[]` - must contain number of elements equal to **rows \* columns**.  
+`string` - in CSV format with number of columns equal to **column** definitions.
+
+- if you have `string[][]` with [3][10] elements you need to define 3 columns and you will get 10 rows
+- if you have `string[]` with [4] elements you need to define 1 or 2 or 4 columns an you will get 4, 2, 1 rows correspondingly
+
+## Templates
+
+Templates feature will give you ability to customize any cell of your table with HTML.
+
+First you need to set anchors in your data. In this example they are **_tmp_** and **_tmpCb_**.
+
+```ts
+const data = {
+  list2d: [
+    ["sample _tmp_ text", "1", "_tmp_"],
+    ["_tmpCb_ sample text", "1", "2"]
+  ]
+};
+```
+
+Provide `<templates>` for that anchors.
+
+```html
+<md-table-advanced .config="${conf}" .data="${data}">
+  <template id="template1">
+    <div>template content</div>
+  </template>
+
+  <template id="template2">
+    <span class="sp"></span>
+    <button>btn</button>
+  </template>
+</md-table-advanced>
+```
+
+templates configuration
+
+```ts
+const conf: TableAdvanced.Config = {
+  cols: {
+    define: [
+      { id: "col1", title: "Col 1" },
+      { id: "col2", title: "Col 2" },
+      { id: "col3", title: "Col 3" }
+    ]
+  },
+  cellTemplates: {
+    _tmp_: { templateName: "template1" },
+    _tmpCb_: {
+      templateName: "template2",
+      // by default template is inserted to anchor position inside cell text
+      // with this option cell content will be replaced by template content
+      contentUse: "replace",
+      // here you can use vanilla JS to do anything
+      templateCb: ({ fragment, content, row, col }) => {
+        const span = fragment.querySelector<HTMLElement>(".sp")!;
+        const button = fragment.querySelector<HTMLButtonElement>("button")!;
+
+        span.innerText = `${content}[${row},${col}]`;
+        button.addEventListener("click", () => console.log("click"));
+      }
+    }
+  }
+};
+```
+
+### How filtering and sorting works with templates
+
+Say for example your template will look like this:
+
+```html
+<template id="t1"><img src="url"/></template>
+```
+
+There is no way to sort or filter it properly. So for sorting and filtering we are using cell content(`string`) instead.
+
+- for example you have `"sample _t1_ text"` cell content. `"sample text"` will be used.
+
+Along with `templateCb` you can use `contentCb`. This will let you customize cell content.
+
+```ts
+const conf: TableAdvanced.Config = {
+  cellTemplates: {
+    _tmp_: {
+      templateName: "t1",
+      contentCb: ({ content, row, col }) => `${content}[${row}][${col}]`
+    }
+  }
+};
+```
+
+## Events
+
+TableAdvanced can fire `md-table-advanced-change` event.
+
+```ts
+type ChangeEvent = Event & {
+  detail:
+    | { type: "filter-on"; filter: Filter.Options; input: string }
+    | { type: "filter-off"; filter: Filter.Options }
+    | { type: "sort"; order: SortOrder }
+    | { type: "select"; index: number }
+    | { type: "multi-select"; rows: number[] }
+    | { type: "expand"; row: number }
+    | { type: "collapse"; row: number };
+};
+```

package/src/components/table-advanced/TableAdvanced.mdx

@@ -0,0 +1,240 @@
+# Advanced Table Component
+
+The **Advance Table** component is intended for presenting tabular data organized in rows and columns.
+Table cells can include text or arbitrary UI components.
+The data contained in a **Advance Table** is managed using `data` property. `config` property define essential configuration to component.
+
+## Properties
+
+| Name     | Type                | Description                                       |
+| :-------: | :------------------: | :------------------------------------------------:|
+| `config` | [`Config`](#config) | Table columns configuration object **[required]** |
+| `data`   | [`Data`](#data)     | Table rows data **[required]**                    |
+
+### Config
+
+Data is **[required]** property.
+Configure columns and additional features here. Number of columns must match parsed data row length. All keys provided with `?` (question mark) is optional and can be skipped.
+
+```ts
+type Config = {
+  // Will make table "fixed" on scroll
+  isStickyHeader?: boolean;
+
+  cols: {
+    // REQUIRED - Please see "Column Definition" downstairs
+    define: Column[];
+    // Enable native browser drag-and-drop features for table columns.
+    isDraggable?: boolean;
+    // Enable native browser resize features for table columns.
+    isResizable?: boolean;
+    // Column with this ID will be collapsed
+    collapse?: ColId;
+  };
+
+  rows?: {
+    // Enable native browser drag-and-drop features for table rows.
+    isDraggable?: boolean;
+    // Selects cell or ranges of cell, i.e. a rectangular block of cells
+    selectable?: "none" | "single" | "multiple";
+  };
+
+  // Please see "Templates" downstairs
+  cellTemplates?: Record<string, CellTemplate>;
+
+  default?: {
+    // Set default "filter" and "sorting" for all columns that has this props undefined
+    col?: ColumnDefaults;
+
+    // Column with this ID will be sorted on table creation (ID must be unique)
+    sort?: {
+      colId: ColId;
+      order: SortOrder;
+    };
+
+    // Column with this ID will be sorted on table creation (ID must be unique)
+    filter?: {
+      colId: ColId;
+      input: string;
+      selectedIndex: number;
+    };
+  };
+
+  // Will add caption and summary to table (accessibility)
+  head?: {
+    caption?: string;
+    summary?: string;
+    tableDescription?: string;
+  };
+};
+```
+
+### Column Definition
+
+You **need** to define columns of your table.
+Number of columns must correspond to provided [`Data`](#data).
+You can define column:
+
+```ts
+type Column = {
+  // Please provide unique ID
+  id: string;
+  title: string;
+  width?: string;
+  sorter?: "byString" | "byNumber" | SortComparator;
+  // See "custom filters" downstairs
+  filters?: "forString" | "forNumber" | Filter.Options[];
+  // This will make column <th scope="row"> not <td>
+  isHeader?: boolean;
+};
+```
+
+Or column group:
+
+```ts
+type ColumnGroup = {
+  groupName: string;
+  children: Column[];
+};
+```
+
+### Custom filters for column
+
+Here is an example how to define your own set of filters to column.
+
+```ts
+import { Filter } from "@/components/table-advanced/src/filter";
+
+const config: TableAdvanced.Config = {
+  cols: {
+    define: [
+      {
+        id: "col1",
+        title: "Title",
+        filters: [
+          Filter.OPTIONS.contains,
+          Filter.OPTIONS.notContains,
+          {
+            label: "Second Char is",
+            input: { placeholder: "Second Сhar", maxlength: 1 },
+            predicate: (content, input) => (content.length > 1 ? content[1] == input : false)
+          }
+        ]
+      }
+    ]
+  }
+};
+```
+
+## Data
+
+Data is **required** property.
+
+`string[][]` - outer array is rows inner array is columns. Inner arrays must contain number of elements that is equal to **column** definitions.
+`string[]` - must contain number of elements equal to **rows \* columns**.
+`string` - in CSV format with number of columns equal to **column** definitions.
+
+- if you have `string[][]` with [3][10] elements you need to define 3 columns and you will get 10 rows
+- if you have `string[]` with [4] elements you need to define 1 or 2 or 4 columns an you will get 4, 2, 1 rows correspondingly
+
+## Templates
+
+Templates feature will give you ability to customize any cell of your table with HTML. However, the HTML [template](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement) has a [content](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement/content) property, which is a read-only [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) containing the DOM subtree which the template represents.
+Note that directly using the value of the content could lead to unexpected behavior, because DocumentFragment is not a valid target for various events, as such it is often preferable to clone or refer to the elements within it.
+
+First you need to set anchors in your data.
+In this example they are **_tmp_** and **_tmpCb_**.
+
+```ts
+const data = {
+  list2d: [
+    ["sample _tmp_ text", "1", "_tmp_"],
+    ["_tmpCb_ sample text", "1", "2"]
+  ]
+};
+```
+
+Provide `<templates>` for that anchors.
+
+```html
+<md-table-advanced .config="${conf}" .data="${data}">
+  <template id="template1">[OK]</template>
+  <template id="template2">
+    <span class="sp"></span>
+    <button>btn</button>
+  </template>
+</md-table-advanced>
+```
+
+Configure callbacks
+
+```ts
+const conf: TableAdvanced.Config = {
+  cols: {
+    define: [
+      { id: "col1", title: "Col 1" },
+      { id: "col2", title: "Col 2" },
+      { id: "col3", title: "Col 3" }
+    ]
+  },
+  cellTemplates: {
+    _tmp_: { templateName: "template1" },
+    _tmp2_: {
+      templateName: "template2",
+      // By default template is inserted to anchor position inside cell text
+      // With this option cell content will be replaced by template content
+      contentUse: "replace",
+      // With this callback, you can apply any changes for template content after it inserted to the DOM
+      templateCb: ({ fragment, content, row, col }) => {
+        const span = fragment.querySelector<HTMLElement>(".sp")!;
+        const button = fragment.querySelector<HTMLButtonElement>("button")!;
+
+        span.innerText = `${content}[${row},${col}]`;
+        button.addEventListener("click", () => console.log("click"));
+      }
+    }
+  }
+};
+```
+
+### How filtering and sorting works with templated cell
+
+Say for example your template will look like this:
+
+```html
+<template id="t1"><img src="url"/></template>
+```
+
+There is no way to sort or filter it properly.
+So for sorting and filtering we are using cell content(`string`) instead.
+
+- For example you have `"sample _t1_ text"` cell content. `"sample text"` will be used.
+
+Along with `templateCb` you can use `contentCb`. This will let you customize cell content.
+```ts
+const conf: TableAdvanced.Config = {
+  cellTemplates: {
+    _tmp_: {
+      templateName: "t1",
+      contentCb: ({ content, row, col }) => `${content}[${row}][${col}]`
+    }
+  }
+};
+```
+
+## Events
+
+TableAdvanced can fire `md-table-advanced-change` event.
+
+```ts
+type ChangeEvent = Event & {
+  detail:
+    | { type: "filter-on"; filter: Filter.Options; input: string }
+    | { type: "filter-off"; filter: Filter.Options }
+    | { type: "sort"; order: SortOrder }
+    | { type: "select"; index: number }
+    | { type: "multi-select"; rows: number[] }
+    | { type: "expand"; row: number }
+    | { type: "collapse"; row: number };
+};
+```

package/src/components/table-advanced/TableAdvanced.stories.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) Cisco Systems, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import "@/components/table-advanced/TableAdvanced";
+import { ThemeNameValues } from "@/components/theme/Theme";
+import { Args, Meta } from "@storybook/web-components";
+import { html } from "lit-element";
+import { TableAdvanced as TableAdvancedType } from "./TableAdvanced"; // Keep type import as a relative path
+import mdx from "./TableAdvanced.mdx";
+
+export const TableAdvanced = (args: Args) => {
+  const DefaultAdvancedTable: { config: TableAdvancedType.Config; data: TableAdvancedType.Data } = {
+    config: {
+      isStickyHeader: args.stickheader,
+
+      rows: {
+        isDraggable: args.dragRow,
+        selectable: "single"
+      },
+
+      head: {
+        caption: args.caption,
+        summary: args.sum
+      },
+
+      cellTemplates: { "00:52": { templateName: "tmp1" } },
+
+      cols: {
+        isDraggable: args.dragCol,
+        isResizable: args.resize,
+        define: [
+          { id: "col-ani", title: "ANI", sorter: "byString" },
+          { id: "col-stage", title: "Abandoment Statge", filters: "forString" },
+          { id: "col-transfer", title: "Transfer", sorter: "byNumber" },
+          { id: "col-wait", title: "Total Wait Time" },
+          { id: "col-back", title: "Call Back Received", filters: "forString" },
+          { id: "col-time", title: "Call Back Time" }
+        ]
+      }
+    },
+    data: {
+      list2d: [
+        ["12345670", "IRV", "0", "00:45", "Yes", "12:34 PM"],
+        ["12345671", "QWT (1-5 min)", "0", "00:20", "No", "Follow-up"],
+        ["12345672", "QWT (5-10 min)", "1", "01:15", "Yes", "09:30 AM"],
+        ["12345673", "QWT > 10 min", "2", "00:35", "No", "11:25 PM"],
+        ["12345674", "QWT > 10 min", "1", "00:15", "Yes", "Follow-up"],
+        ["12345675", "IRV", "2", "00:23", "Yes", "Follow-up"],
+        ["12345676", "QWT (1-5 min)", "0", "00:52", "No", "10:16 AM"],
+        ["12345677", "IRV", "1", "00:25", "Yes", "Follow-up"],
+        ["12345678", "QWT (1-5 min)", "2", "01:05", "No", "03:34 PM"],
+        ["12345679", "QWT (5-10 min)", "2", "00:35", "Yes", "02:12 AM"],
+        ["12345680", "QWT (1-5 min)", "1", "00:41", "No", "Follow-up"]
+      ]
+    }
+  };
+
+  const ColapseData: { config: TableAdvancedType.Config; data: TableAdvancedType.Data } = {
+    config: {
+      isStickyHeader: args.stickheader,
+
+      rows: {
+        isDraggable: args.dragRow,
+        selectable: "single"
+      },
+
+      cols: {
+        isDraggable: args.dragCol,
+        isResizable: args.resize,
+        collapse: "col-ani",
+        define: [
+          { id: "col-ani", title: "ANI", sorter: "byString" },
+          { id: "col-stage", title: "Abandoment Statge", filters: "forString" },
+          { id: "col-transfer", title: "Transfer", sorter: "byNumber" },
+          { id: "col-wait", title: "Total Wait Time" },
+          { id: "col-back", title: "Call Back Received", filters: "forString" },
+          { id: "col-time", title: "Call Back Time" }
+        ]
+      }
+    },
+    data: {
+      list2d: [
+        ["12345670", "IRV", "0", "00:45", "Yes", "12:34 PM"],
+        ["12345671", "QWT (1-5 min)", "0", "00:20", "No", "Follow-up"],
+        ["12345672", "QWT (5-10 min)", "1", "01:15", "Yes", "09:30 AM"],
+        ["12345673", "QWT > 10 min", "2", "00:35", "No", "11:25 PM"],
+        ["12345674", "QWT > 10 min", "1", "00:15", "Yes", "Follow-up"],
+        ["12345675", "IRV", "2", "00:23", "Yes", "Follow-up"],
+        ["12345675", "IRV", "2", "00:23", "Yes", "Follow-up"],
+        ["12345675", "IRV", "2", "00:23", "Yes", "Follow-up"],
+        ["12345676", "QWT (1-5 min)", "0", "00:52", "No", "10:16 AM"],
+        ["12345677", "IRV", "1", "00:25", "Yes", "Follow-up"],
+        ["12345678", "QWT (1-5 min)", "2", "01:05", "No", "03:34 PM"],
+        ["12345679", "QWT (5-10 min)", "2", "00:35", "Yes", "02:12 AM"],
+        ["12345680", "QWT (1-5 min)", "1", "00:41", "No", "Follow-up"]
+      ]
+    }
+  };
+
+  return html`
+    <md-theme class="theme-toggle" id="table" ?darkTheme=${args.darkTheme} theme=${args.theme}>
+      ${args.customize
+        ? html`
+            <div style="${args.stickheader ? `height: 350px; overflow: hidden; overflow-y: auto;` : ``}">
+              <md-table-advanced
+                style="${args.collapse ? `display: block;` : `display: none;`}"
+                .config=${ColapseData.config}
+                .data=${ColapseData.data}
+              >
+              </md-table-advanced>
+              <md-table-advanced
+                style="${args.collapse ? `display: none;` : `display: block;`}"
+                .config=${DefaultAdvancedTable.config}
+                .data=${DefaultAdvancedTable.data}
+              >
+                <template id="tmp1">
+                  <div style="background: yellow">[OK]</div>
+                </template>
+              </md-table-advanced>
+            </div>
+          `
+        : html`
+            <div style="${args.stickheader ? `height: 350px; overflow: hidden; overflow-y: auto;` : ``}">
+              <md-table-advanced
+                style="${args.collapse ? `display: block;` : `display: none;`}"
+                .config=${ColapseData.config}
+                .data=${ColapseData.data}
+              >
+              </md-table-advanced>
+              <md-table-advanced
+                style="${args.collapse ? `display: none;` : `display: block;`}"
+                .config=${DefaultAdvancedTable.config}
+                .data=${DefaultAdvancedTable.data}
+              >
+              </md-table-advanced>
+            </div>
+          `}
+    </md-theme>
+  `;
+};
+
+const meta: Meta = {
+  title: "Components/Table Advanced",
+  component: "md-table-advanced",
+  render: TableAdvanced,
+  argTypes: {
+    theme: { control: { type: "select", options: ThemeNameValues }, defaultValue: "lumos" },
+    darkTheme: { control: "boolean" },
+    customize: { control: "boolean", description: "Use custom template for replace", defaultValue: false }
+  },
+  parameters: {
+    a11y: {
+      element: "md-table-advanced"
+    },
+    docs: {
+      page: mdx
+    }
+  }
+};
+
+export default meta;