@momentum-ui/web-components 2.5.4 → 2.5.7

package/src/components/table/tokens/lm-table-tokens.js

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+const colors = require("@momentum-ui/tokens/dist/colors.json");
+
+const table = {
+  prefix: "lm",
+  component: "table",
+  header: {
+    "bg-color": {
+      light: colors.gray["05"].name,
+      dark: colors.gray["95"].name
+    }
+  },
+  hover: {
+    "bg-color": {
+      light: colors.gray[10].name,
+      dark: colors.gray[90].name
+    }
+  },
+  pressed: {
+    "bg-color": {
+      light: colors.gray[20].name,
+      dark: colors.gray[80].name
+    }
+  },
+  "border-color": {
+    light: colors.gray[20].name,
+    dark: colors.gray[80].name
+  },
+  "text-color": {
+    light: colors.gray[70].name,
+    dark: colors.gray[40].name
+  },
+  stripped: {
+    "bg-color": {
+      light: colors.gray[10].name,
+      dark: colors.gray[80].name
+    }
+  }
+}
+
+module.exports = table;

package/src/components/table/tokens/md-table-tokens.js

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+const colors = require("@momentum-ui/tokens/dist/colors.json");
+
+const table = {
+  prefix: "md",
+  component: "table",
+  header: {
+    "bg-color": {
+      light: colors.gray[10].name,
+      dark: colors.gray[80].name
+    }
+  },
+  hover: {
+    "bg-color": {
+      light: colors.blue[20].name,
+      dark: colors.blue[90].name
+    }
+  },
+  pressed: {
+    "bg-color": {
+      light: colors.gray[20].name,
+      dark: colors.gray[90].name
+    }
+  },
+  "border-color": {
+    light: colors.gray[10].name,
+    dark: colors.gray[80].name
+  },
+  "text-color": {
+    light: colors.gray[80].name,
+    dark: colors.gray[40].name
+  },
+  stripped: {
+    "bg-color": {
+      light: colors.gray[20].name,
+      dark: colors.gray[70].name
+    }
+  }
+}
+
+module.exports = table;

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

@@ -0,0 +1,232 @@
+# 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;
+  };
+};
+```
+
+### 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,239 @@
+# 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;
+  };
+};
+```
+
+### 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 };
+};
+```