npm package: @nomadx/table
Description: Stencil Component Starter
Author: Nate Moore
Latest version: 0.3.3-alpha

[![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRjt9Cjwvc3R5bGU%2BCjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywzNzMuOWMwLDM3LjYtNTUuMSw2OC42LTkyLjcsNjguNkgxODAuNGMtMzcuOSwwLTkyLjctMzAuNy05Mi43LTY4LjZ2LTMuNmgzMzYuOVYzNzMuOXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDI5Mi4xSDE4MC40Yy0zNy42LDAtOTIuNy0zMS05Mi43LTY4LjZ2LTMuNkgzMzJjMzcuNiwwLDkyLjcsMzEsOTIuNyw2OC42VjI5Mi4xeiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMTQxLjdIODcuN3YtMy42YzAtMzcuNiw1NC44LTY4LjYsOTIuNy02OC42SDMzMmMzNy45LDAsOTIuNywzMC43LDkyLjcsNjguNlYxNDEuN3oiLz4KPC9zdmc%2BCg%3D%3D&colorA=16161d&style=flat-square)](https://github.com/ionic-team/stencil)
![Built for Accessibility](https://img.shields.io/badge/-Built_For_Accessibility-_.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDI0IDUxMiI+PGRlZnM+PHN0eWxlPi5he2ZpbGw6I2ZmZjt9PC9zdHlsZT48L2RlZnM+PHRpdGxlPmxvZ28td2hpdGU8L3RpdGxlPjxwYXRoIGNsYXNzPSJhIiBkPSJNMjYyLjYsMjYyLjc3cTE1LTEuODEsMjEuNzctNC41NywxMi4wOC00Ljc1LDE0LjI3LTE0LjgyLDIuNTctMTIuMjUtNC45NC0xNi45M3QtMjQtNC42NnEtMTguNDgsMC0yOC4xOCw5LjE1LTYuNzcsNi43Ni0xMS4xNiwxOC4yOUgxODAuMDhxNy4zMi0yNi4xNiwyMy43OC00MywyNi4zNS0yNi4zNiw3Ni42Ny0yNi4zNSwzMi43NSwwLDU1LjQ0LDEzdDE1LDQ5TDMzMS4zOSwzMzMuNHEtMiw5LjUxLTQuMzksMjMuMDUtMS42NSwxMC4yNC4wOSwxMy45MWExMy41NCwxMy41NCwwLDAsMCw2LjMxLDZsLTEuNDYsNy42OEgyNzUuMjJhNTIuNzcsNTIuNzcsMCwwLDEtLjkxLTExLjM0cS4xOC01LjMxLDEuMDktMTIuMDhhMTQ3Ljk0LDE0Ny45NCwwLDAsMS0yOS4wOSwxOS45NCw4Ny40LDg3LjQsMCwwLDEtNDAuMjUsOS43cS0yNy4wOCwwLTQxLjQ0LTE1LjQ2VDE1Ni4yOSwzMzFxNy44OC0zNi43OCwzOS43MS01My4yNCwxNy4zNy05LDQ4LjQ4LTEyLjgxWm0yNi41MywyNC4zNGE2Ny44LDY3LjgsMCwwLDEtMTEsNSw5OS4zMiw5OS4zMiwwLDAsMS0xNC42NCwzLjU3bC0xMi4wNywyLjE5cS0xNy4yLDIuOTQtMjUuMjUsNy4xNGEzMSwzMSwwLDAsMC0xNi42NSwyMi4xNHEtMi45NCwxMy4zNSwzLjIsMTkuM3QxNi43NCw1Ljk1cTE2LjgzLDAsMzMuMTItOS44OHQyMi41LTM2LjA1Wk03MjkuNCw0MjguNTJsNi41OC4zNmE4My41LDgzLjUsMCwwLDAsMTQuNjQtLjU1LDMyLjE1LDMyLjE1LDAsMCwwLDEyLjYzLTQuMjFxNS4yOS0zLjExLDExLjM0LTEzYzQtNi41OCw5Ljg2LTE2LjgsOS42MS0xOC4yN0w3NTUuMywxODQuNjVoNThsMTIuMjYsMTQ3LjFMODk4LDE4NC42NWg1NS40NEw4NDMuMywzODAuNzljLTIxLjIyLDM3LjgxLTQwLjU3LDY3LjQ2LTUwLjE0LDc2LjU0Uzc2Ny4yNyw0NzEsNzQ0LjIyLDQ3MXEtNywwLTExLjE2LS4wOXQtMTIuNDUtLjY0Wk01MzIsMzQ4SDQ4Mi4wNmw0OC42OS0yMjkuMjNINDg3LjM5cS0uNzQsMy40OC00LjM5LDEwLjYxYTU4LjMyLDU4LjMyLDAsMCwxLTE0LjI4LDE5LDYyLjYsNjIuNiwwLDAsMS0yOC41NCwxMy45cS0xMC4yNCwyLjItMzUuMzEsMy4zbC03LjUsMzUuNDloNjIuMzlMNDI4LjYyLDM0OEgzNzkuMzVsLTcuODgsMzYuMDVINDIxdjBINDc0LjR2MGg0OS43MVptMTgxLjkzLS4wOEg2NjRsNDguNjktMjI5LjcxSDY2OS4zMnEtLjc0LDMuNS00LjM5LDEwLjY0YTU4LjYyLDU4LjYyLDAsMCwxLTE0LjI3LDE5LjA3LDYyLjY4LDYyLjY4LDAsMCwxLTI4LjU1LDEzLjkzcS0xMC4yNSwyLjItMzUuMzEsMy4zbC03LjUsMzUuNTdoNjIuMzlsLTMxLjE0LDE0Ny4ySDU2MS4yOGwtNy44OCwzNi4xM2g0OS41MXYwaDUzLjQzdjBINzA2WiIvPjxwYXRoIGNsYXNzPSJhIiBkPSJNOTQ3LjEyLDgzLjI4bDE5LjcxLTM2LjA1SDEzMy40OWEzMi4yOCwzMi4yOCwwLDAsMC0zMS41OCwyNS42M0wyNi40OSw0MzEuMzJhMzIuMjgsMzIuMjgsMCwwLDAsMzEuNTksMzguOTJINjY1LjQ5bDcuODgtMzYuMDVINjMuMDZMMTM2Ljg5LDgzLjI4WiIvPjwvc3ZnPg==&logoWidth=28&colorA=20c997&colorB=343a40&style=flat-square)
![Status](https://img.shields.io/badge/Status-Alpha-red.svg?style=flat-square)

# @nomadx/table

`<nomadx-table>` is a set of vanilla web-components to simplify the creation of accessible, responsive HTML tables.

[Try the demo!](TODO)

### For Developers:

The `<nomadx-table>` component automatically creates rich HTML tables from your dataset. The flexible `<nomadx-table-data>` component allows you to generate tables through simple markup or bind data from Javascript, supporting CSV or TSV format, Markdown, JSON Arrays, and 2D Arrays.

Here's a minimal example using CSV format in your markup:
```html 
<nomadx-table>
  <nomadx-table-data>
    Column A, Column B, Column C, Column D
    0, true, Hello, World!
    2, false, Foobar, Bazbing
  </nomadx-table-data>
</nomadx-table>
```

By specifying attributes on the `<nomadx-table>` element, you can control which columns are `sortable`, which are `fixed-width` (the default is responsive), if the table is `striped`, and more. More information in the [API section](#api) below.

### For Your Users:

All Nomadx elements come pre-baked with `a11y` best practices like roving focus, keyboard-only navigation, and screen-reader support. Our goal is to make tables that work exactly like you'd expect them to, so we followed the [W3C's Best Practices](https://www.w3.org/TR/2017/NOTE-wai-aria-practices-1.1-20171214/examples/grid/dataGrids.html) and then added even more functionality (like beautiful clipboard support, meta sequences for keyboards, and more.)

## Using this component

### Script tag

- [Publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages)
- Drop this `<script src='https://unpkg.com/@nomadx/table@0.0.1/dist/index.js'></script>` in the head of your index.html
- Then you can use the element anywhere in your template, JSX, html etc

### Node Modules
- Run `npm install @nomadx/table --save`
- Put a script tag similar to this `<script src='node_modules/@nomadx/table/dist/index.js'></script>` in the head of your index.html
- Then you can use the element anywhere in your template, JSX, html etc

### In a stencil-starter app
- Run `npm install @nomadx/table --save`
- Add an import to the npm packages `import '@nomadx/table';`
- Then you can use the element anywhere in your template, JSX, html etc

## Data Input
### via Markup

```html
<!-- CSV Format -->
<nomadx-table>
  <nomadx-table-data>
    Column A, Column B, Column C, Column D
    0, true, Hello, World!
    2, false, Foobar, Bazbing
  </nomadx-table-data>
</nomadx-table>

<!-- TSV Format -->
<nomadx-table>
  <nomadx-table-data>
    Column A&Tab;Column B&Tab;Column C&Tab;Column D
    0&Tab;true&Tab;Hello&Tab;World!
    2&Tab;false&Tab;Foobar&Tab;Bazbing
  </nomadx-table-data>
</nomadx-table>

<!-- GFM Table Format -->
<nomadx-table>
  <nomadx-table-data>
    | Column A | Column B | Column C | Column D |
    |----------|----------|----------|----------|
    | 0        | true     | Hello    | World!   |
    | 2        | false    | Foobar   | Bazbing  |
  </nomadx-table-data>
</nomadx-table>

<!-- 2D Array or JSON Array via JSX -->
<nomadx-table>
  <nomadx-table-data data={myData}> </nomadx-table-data>
</nomadx-table>
```

### via Javascript
```ts
const tableA = document.querySelector('nomadx-table-data#table-a');
const my2DArray = [
  ['Column A', 'Column B', 'Column C', 'Column D'],
  [0, true, 'Hello', 'World!'],
  [2, false, 'Foobar', 'Bazbing']
]
tableA.onComponentReady().then(() => {
  tableA.data = my2DArray;
})

const tableB = document.querySelector('nomadx-table-data#table-b');
const myJSONArray = [
  { 'Column A': 0, 'Column B': true, 'Column C': 'Hello', 'Column D': 'World!' }
  { 'Column A': 2, 'Column B': false, 'Column C': 'Foobar', 'Column D': 'Bazbing' }
]
tableB.onComponentReady().then(() => {
  tableB.data = myJSONArray;
})
```

## API
`<nomadx-table>` Attributes

| Attribute   	            | Value                                	| Default 	|
|-------------------------	|--------------------------------------	|---------	|
| [name](#name)             | string                               	| ""      	|
| [striped](#striped)     	| present\|'true'\|'false'               	| false   	|
| [sortable](#sortable)    	| present\|'true'\|'false'\|'0 1 2 3 ...' 	| false   	|
| [fixed-width](#fixed-width) | present\|'true'\|'false'\|'0 1 2 3 ...' 	| false   	|

### Name
Setting a name for the table is highly reccommended for accessibility. This will automatically be read to any users interacting with your project via assistive technology.

Note that there is no need to include the word `"Table"` in the name, because screen readers will automatically announce that the element is a table.
```html
<nomadx-table name="Orders"></nomadx-table>
```

### Striped
Nomadx tables are not striped by default, but this can easily be enabled by including a `striped` attribute.
```html
<nomadx-table striped></nomadx-table>         <!-- Will be striped -->

<nomadx-table striped="true"></nomadx-table>  <!-- Will be striped -->

<nomadx-table striped="false"></nomadx-table> <!-- Will NOT be striped -->
```

### Sortable
Nomadx tables make it easy to enable per-column sorting through the `sortable` attribute. By default, no columns will be sortable, but including the attribute or setting it to `"true"` will enable sorting for all columns. You may also specify a list of columns indexes for which sorting should be enabled. 

*Please note that the first column has an index of 1*

```html
<nomadx-table sortable></nomadx-table>         <!-- All columns will be sortable -->

<nomadx-table sortable="true"></nomadx-table>  <!-- All columns will be sortable -->

<nomadx-table sortable="false"></nomadx-table> <!-- No columns will be sortable -->

<nomadx-table sortable="1 2 3"></nomadx-table> <!-- Columns 1, 2, and 3 will be sortable -->

<nomadx-table sortable="1 3 5"></nomadx-table> <!-- Columns 1, 3, and 5 will be sortable -->
```

### Fixed Width
Nomadx tables are responsive by default, but if you'd like to make any column fixed-width, it is simple to do so with the `fixed-width` attribute. This operates in a similar way to `sortable` (above).

*Please note that the first column has an index of 1*

```html
<nomadx-table fixed-width></nomadx-table>         <!-- All columns will be fixed-width -->

<nomadx-table fixed-width="true"></nomadx-table>  <!-- All columns will be fixed-width -->

<nomadx-table fixed-width="false"></nomadx-table> <!-- No columns will be fixed-width -->

<nomadx-table fixed-width="1 2 3"></nomadx-table> <!-- Columns 1, 2, and 3 will be fixed-width -->

<nomadx-table fixed-width="1 3 5"></nomadx-table> <!-- Columns 1, 3, and 5 will be fixed-width -->
```

In order to specify the width of the column, simple use CSS to set a `--fixed-width` variable on the column, either via `:nth-child` or via `column-[name]`.
```css
nomadx-table .column:nth-of-type(1) {
  --fixed-width: 128px;
}

/* 
 * Class Selector is "column-" followed by the column header's content formatted to kebab case
 * In this example, the column header is "My Awesome Column"
 */
nomadx-table .column-my-awesome-column {
  --fixed-width: 128px;
}
```

## Styling
`<nomadx-table>` offers a number of CSS variables to modify the default styling of the table.

| Variable   	                                | Default Value       |
|-------------------------------------------- |-------------------- |
| --row-background-color                      | #fff;               | 
| --stripe-background-color                   | #fafafa;            | 
| --focused-row-background-color              | #e1f5fe;            | 
| --focused-stripe-background-color           | #e1f5fe;            |
| --table-border                              | 1px solid #dfe2e5;  | 
| --cell-padding                              | 12px;               | 
| --sort-active-color                         | #000;               |