{"id":19711595,"url":"https://github.com/wjsoftware/wjfe-dataview","last_synced_at":"2025-06-14T13:38:40.082Z","repository":{"id":240596457,"uuid":"803045913","full_name":"WJSoftware/wjfe-dataview","owner":"WJSoftware","description":"Svelte v5 table component suitable for examination of extensive tabular data.","archived":false,"fork":false,"pushed_at":"2025-03-10T21:05:51.000Z","size":1442,"stargazers_count":15,"open_issues_count":7,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T17:08:11.913Z","etag":null,"topics":["data-visualization","svelte","sveltekit","table","tabular-data"],"latest_commit_sha":null,"homepage":"https://wjsoftware.github.io/wjfe-dataview/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WJSoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-20T00:26:55.000Z","updated_at":"2025-04-28T22:19:30.000Z","dependencies_parsed_at":"2024-05-30T08:33:43.218Z","dependency_job_id":null,"html_url":"https://github.com/WJSoftware/wjfe-dataview","commit_stats":null,"previous_names":["wjsoftware/wj-dataview"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/WJSoftware/wjfe-dataview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WJSoftware%2Fwjfe-dataview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WJSoftware%2Fwjfe-dataview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WJSoftware%2Fwjfe-dataview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WJSoftware%2Fwjfe-dataview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WJSoftware","download_url":"https://codeload.github.com/WJSoftware/wjfe-dataview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WJSoftware%2Fwjfe-dataview/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259824769,"owners_count":22917340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-visualization","svelte","sveltekit","table","tabular-data"],"created_at":"2024-11-11T22:12:36.849Z","updated_at":"2025-06-14T13:38:40.059Z","avatar_url":"https://github.com/WJSoftware.png","language":"TypeScript","readme":"# @wjfe/dataview\n\n\u003e Svelte v5 table component suitable for examination of extensive tabular data.\n\n## Overview\n\nThe data view component renders a table with functionality suitable for close examination of the presented data.  It \nprovides conveniences like pinnable columns and row highlighting on hover, useful to users when following data with \ntheir eyes.\n\n\u003e **[Demo Website](https://wjsoftware.github.io/wjfe-dataview)**\n\nThe component tries to be as unopinionated as possible in terms of styling and tries to provide as little styling as \npossible.  Certain features, however, impose some appearance requirements.  For example, pinning columns in the grid \nrequires opaque background colors or else the data from other columns will be seen through the pinned columns when \nthe data view is scrolled horizontally.\n\nTo theme the table to your needs or otherwise make it play well with your styling framework of choice (Bootstrap, \nTailwind CSS, Bulma, etc.), you may style it in accordance to what is shown in the \n**[Theming the Data View](#theming-the-data-view)** section.\n\n## Quickstart\n\nInstall the package:\n\n```powershell\nnpm i @wjfe/dataview\n```\n\nNow import the data view component and use it:\n\n```typescript\nimport { WjDataView } from '@wjfe/dataview';\n```\n\nThe only two required properties are `columns` and `data`.  The former defines the columns in the data view; the \nlatter provides the data that shows in each column.  By default, the `key` property of each column is treated as the \nkey to retrieve data from the data row, but this can be overridden by providing `get` functions.\n\nEach column must have the `key` and the `text` properties.  Any other property is optional.\n\nEach data object (the rows) must have an `id` property of type `number` or `string`, and the `wjdv` property, which is \nan object that holds operational data for each row.  The `defineData()` function is a helper function that helps you \nfulfill these 2 requirements.  The `id` values are meant to be unique amongst the data set.\n\n\u003e **IMPORTANT**:  Always bind `columns` and `data`.  The data view control will mutate properties inside this data, \n\u003e so the best practice is to bind.\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n    import { WjDataView, defineData } from '@wjfe/dataview';\n    import { type MyDataModel } from 'path/to/my-model-types.js';\n\n    type MyColumn = WjDvColumn\u003cMyDataModel\u003e;\n    const columns = $state\u003cMyColumn[]\u003e([\n        {\n            key: 'id',\n            text: 'ID'\n        },\n        {\n            key: 'tagName',\n            text: 'Tag'\n        }\n    ]);\n    // Obtain the data somehow.  This could be part of the results of the universal or server load() SvelteKit \n    // function, or could be obtained in non-SvelteKit projects with a fetch() call.\n    const dataFromApi = getDataSomehow();\n    // Now ensure the data fulfills the component requirements using \"defineData\":\n    let data = $state(defineData\u003cMyDataModel\u003e(dataFromApi));\n    // The model type here ------^^^^^^^^^^^ may not be needed if you have properly typed the `getDataSomehow()` \n    // function or the `dataFromApi` variable.\n\u003c/script\u003e\n\n...\n\u003cWjDataView bind:columns bind:data\u003e\n    \u003c!-- snippets go here --\u003e\n\u003c/WjDataView\u003e\n```\n\nThis example would render the data view with two columns, whose captions will read `ID` and `Tag`.  The data shown in \neach column will be extracted from the `MyDataModel.id` and `MyDataModel.tagName` properties of each of the data \nobjects in the `data` array.\n\n\u003e The `defineData()` function mutates the data for performance reasons.  It works the items directly as opposed to \n\u003e cloning them.  Also, the same array is returned for the same performance reasons.\n\n## Theming the Data View\n\nAs stated in the overview, the data view's appearance can be customized.  The component has been styled using CSS \nvariables with some defaults.  If you wish, you may redefine the variables at will (the variables are listed at the \nend of the section), but it is best to use the theme component `WjDataViewTheme` that provides a friendlier way than \ndirectly defining the CSS variables.\n\n### The WjDataViewTheme Component\n\nThis component is a mere convenience to setting up themes for data view components.  It works by defining the CSS \nvariables in a `\u003cdiv\u003e` element with its CSS `display` attribute set to `contents` that wraps the target `WjDataView` \ncomponent.\n\n\u003e **TIP**:  The `WjDataViewTheme` component doesn't have to be the immediate parent of a `WjDataView`.  It can be \n\u003e placed higher in the hierarchy to, for example, cover more than one `WjDataView` component.\n\nThe theme component has a single `theme` property of type `Theme`:\n\n```typescript\nexport type ComponentColor = {\n    backgroundColor?: string;\n    opacity?: number;\n    color?: string;\n};\n\nexport type ResizerColor = {\n    backgroundColor?: string;\n    borderColor?: string;\n};\n\nexport type BorderDefinition = {\n    width?: string;\n    style?: 'dashed' | 'dotted' | 'double' | 'groove' | 'inset' | 'outset' | 'ridge' | 'solid' | 'unset';\n    color?: string;\n};\n\nexport type Theme = {\n    table?: ComponentColor;\n    stripes?: ComponentColor;\n    rowTracking?: ComponentColor;\n    rowSelection?: ComponentColor;\n    pinnedColumnsDivider?: BorderDefinition,\n    resizer?: {\n        width?: string;\n        overlay?: {\n            opacity?: number;\n            item?: ResizerColor;\n            positiveDelta?: ResizerColor;\n            negativeDelta?: ResizerColor;\n        }\n    };\n    gridBorders?: BorderDefinition;\n};\n```\n\nWhile the amount of properties is large, each one of them are optional.  Simply set the properties that you wish to \ncustomize.  The properties that aren't set will take the default value documented in the table further down.\n\nFor example, Bootstrap consumers might want to ensure that the data view always uses the body's background color.  In \nthis case, we could create the following theme in a `dataViewThemes.ts` (potential) file:\n\n```typescript\nimport { type Theme } from '@wjfe/dataview';\n\nexport const bootstrapTheme: Theme = {\n    table: {\n        backgroundColor: 'var(--bs-body-bg-rgb)'\n    },\n    stripes: {\n        backgroundColor: 'var(--bs-emphasis-color-rgb)'\n    },\n    rowTracking: {\n        backgroundColor: 'var(--bs-primary-rgb)',\n        opacity: 0.2\n    },\n    rowSelection: {\n        backgroundColor: 'var(--bs-row-selection-bg-color-rgb)',\n    }\n};\n```\n\n\u003e This is the actual modification set in the demonstration page.  The first three variables are provided by Bootstrap, \n\u003e while the last one (`--bs-row-selection-bg-color-rgb`) is defined inside the demo project.\n\nAs seen, one can take advantage of CSS variables to define values.  Bootstrap provides light and dark modes, and these \nvariables have different definitions depending on the mode, making the data view's theme immediately responsive to \nmode selection changes.\n\nThis is not perfect, however, because Bootstrap doesn't have `-rgb` variables for every color, so not everything goes \nas smoothly.  Create CSS variables that adjust to the color mode to perfect the theme.  For example, the last one has \nbeen defined as:\n\n```scss\n.theme-def {\n    --bs-row-selection-bg-color-rgb: 221, 235, 255;\n    \n    :global([data-bs-theme=\"dark\"]) \u0026 {\n        --bs-row-selection-bg-color-rgb: 21, 35, 55;\n    }\n}\n```\n\nWith this technique, we can create fully responsive themes for the data view component.\n\n\u003e **IMPORTANT**:  All background colors are composed using the provided color and an opacity value.  This is why the \n\u003e color must be specified in RGB format, or with a CSS variable that defines it in RGB format.  Formats like `#rrggbb` \n\u003e simply won't work.\n\nUse the `WjDataViewTheme` component as a wrapper for any `WjDataView` components that you may have.  This wrapper \ndoesn't have to be the immediate parent, so put it wherever is best according to your needs.\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n    import { bootstrapTheme } from '../dataViewThemes.js';\n\u003c/script\u003e\n\n\u003cWjDataViewTheme theme={bootstrapTheme}\u003e\n    \u003cWjDataView ...\u003e\n        \u003c!-- Snippets go here --\u003e\n    \u003c/WjDataView\u003e\n\u003c/WjDataViewTheme\u003e\n```\n\nThe complete list of CSS variables that can be set for the data view component are:\n\n| CSS Variable | Light Default | Dark Default | Description |\n| - | - | - | - |\n| `--wjdv-bg-color-rgb` | `255, 255, 255` | `0, 0, 0` | Data view's background color. |\n| `--wjdv-bg-opacity` | `1` | `1` | Background's opacity. |\n| `--wjdv-fg-color` | `inherit` | `inherit` | Foreground (or text) color.  Usually this one doesn't need to be set. |\n| `--wjdv-striping-bg-color-rgb` | `0, 0, 0` | `255, 255, 255` | Striping background color.  Set the opacity as well. |\n| `--wjdv-striping-bg-opacity` | `0.04` | `0.07` | Striping background color's opacity. |\n| `--wjdv-striping-fg-color` | `inherit` | `inherit` | Foreground (or text) color for striped rows. |\n| `--wjdv-rowtracking-bg-color-rgb` | `0, 0, 0` | `255, 255, 255` | Background color for row tracking. |\n| `--wjdv-rowtracking-bg-opacity` | `0.07` | `0.15` | Opacity for row tracking.  Usually set higher than the striping one or the effect doesn't look very good. |\n| `--wjdv-rowtracking-fg-color` | `inherit` | `inherit` | Foreground (or text) color for tracked rows. |\n| `--wjdv-sticky-divider-width` | `0.1em` | `0.1em` | Width of the border that divides pinned columns from unpinned ones. |\n| `--wjdv-sticky-divider-style` | `solid` | `solid` | Style of the border that divides pinned columns from unpinned ones. |\n| `--wjdv-sticky-divider-color` | `darkgray` | `lightgray` | Color of the border that divides pinned columns from unpinned ones. |\n| `--wjdv-resizer-width` | `0.4em` | `0.4em` | Column resizer's width. |\n| `--wjdv-resizer-overlay-opacity` | `0.7` | `0.7` | Opacity of the entire resizer overlay. |\n| `--wjdv-resizer-overlay-bg-color` | `lightblue` | `#0578ea` | Background color of the overlay section that represents the original column's size. |\n| `--wjdv-resizer-overlay-border-color` | `blue` | `#13aeff` | Border color of the overlay section that represents the original column's size. |\n| `--wjdv-resizer-deltapos-bg-color` | `lightgreen` | `lightgreen` | Background color of the overlay section that represents the column's size increase. |\n| `--wjdv-resizer-deltapos-border-color` | `green` | `green` | Border color of the overlay section that represents the column's size increase. |\n| `--wjdv-resizer-deltaneg-bg-color` | `pink` | `pink` | Background color of the overlay section that represents the column's size reduction. |\n| `--wjdv-resizer-deltaneg-border-color` | `red` | `red` | Border color of the overlay section that represents the column's size reduction. |\n| `--wjdv-selected-bg-color-rgb` | `227, 240, 254` | `15, 25, 74` | Background color of rows that have been selected. |\n| `--wjdv-selected-bgopacity` | `1` | `1` | Background opacity of rows that have been selected. |\n| `--wjdv-selected-fg-color` | `inherit` | `inherit` | Foreground color of rows that have been selected. |\n| `--wjdv-grid-line-width` | `0.01em` | `0.01em` | Width of the table's border lines. |\n| `--wjdv-grid-line-style` | `solid` | `solid` | Style used in the table's border lines. |\n| `--wjdv-grid-line-color` | `currentColor` | `currentColor` | Color used in the table's border lines. |\n| `--wjdv-i-filler-color` | `#ddd` | `#ddd` | Color used to render the pattern in filler columns. |\n| `--wjdv-filler-pattern-size` | `5px` | `5px` | Size of the pattern in filler columns. |\n\n### Styling the Header Row\n\nThe header row, as row, cannot be styled.  What can be styled is the individual header cells.  This is due to the \nnature of the structure around the pinnable columns feature.\n\nThe most common thing to do here is to add some background coloring to the header cells, so they appear different to the \ndata cells.  This in itself is complicated because pinned cells must be guaranteed a fully opaque background color or \nelse the non-pinned columns will be seen through them when scrolling horizontally.\n\nBut when there's will there's a way:  I learned from the Bootstrap team that one can simulate a background color using \n`box-shadow` (this technique is revealed in Intellisense on the `headerClass` property of the component):\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n    import { bootstrapTheme } from '../dataViewThemes.js';\n\u003c/script\u003e\n\n\u003cWjDataViewTheme theme={bootstrapTheme} headerClass=\"header-background\"\u003e\n    \u003cWjDataView ...\u003e\n        \u003c!-- Snippets go here --\u003e\n    \u003c/WjDataView\u003e\n\u003c/WjDataViewTheme\u003e\n\n\u003cstyle\u003e\n    :global(.header-background) {\n        box-shadow: 0 9999px 9999px rgba(0, 0, 0, 0.07) inset;\n    }\n\u003c/style\u003e\n```\n\nThis will shade the header cells darker.  On a white background, this will make the cells look gray; on a black \nbackground the color selection must be a light one (not black as in the example) so the cells are shaded lighter and \ncan stand out.\n\nIf you **must** set `background-color`, you'll have to fight the component using `!important`:\n\n```svelte\n\u003cstyle\u003e\n    :global(.header-background) {\n        background-color: #ddd !important;\n    }\n\u003c/style\u003e\n```\n\nRemember:  If you set the background color, it must be opaque so pinned columns work as expected.\n\n## Cross Column Synchronization\n\n\u003e Since **v0.13.0**\n\nIt is possible to synchronize any property of a column with the same property in the column object of another dataview \ninstance, up to the point where they can be visually aligned.  This is a desirable feature in master-child scenarios \nbecause users can have related columns perfectly aligned between master and child tables.  See \n[this detailed README](./docs/ColSync.md) to learn how to make use of this one-in-a-kind feature.\n\n## Reference\n\n### Props\n\n| Property | Type | Default Value | Bindable | Description |\n| - | - | - | - | - |\n| `columns` | `WjDvColumn\u003cTCol, TRow\u003e[]` | (none) | Yes | Defines the columns the data view component will create. |\n| `data` | `WjDvRow\u003cTRow\u003e[]` | (none) | Yes | The data that is shown by the data view component. |\n| `get` | `(row: TRow, key: string) =\u003e any` | (function) | | Function that retrieves a column's value using the row and provided key for columns that don't provide one. |\n| `defaultWidth` | `number` | `10` | | The width for colums that don't specify its own width, in `em`'s. |\n| `rowTracking` | `boolean` | `true` | | Turns the row tracking feature on and off. |\n| `rowSelectionBg` | `boolean` | `true` | | Turns the row-highlighting-on-selection feature on and off. |\n| `striped` | `boolean` | `true` | | Turns the striping of rows on and off. |\n| `pinnedDivider` | `boolean` | `true` | | Turns the divider between pinned and unpinned columns on and off. |\n| `class` | `string` | `undefined` | | Additional CSS classes that are applied to the data view's viewport (the top-level element). |\n| `headerClass` | `string` | `undefined` | | Adds additional CSS classes to the individual header cells. |\n| `controlColumn` | `ControlColumn\u003cTRow, TCol\u003e` | `undefined` | Yes | Specifies the shape of the control column, which an extra column that is always the first pinned column. |\n| `noViewport` | `boolean` | `false` | | Allows the exclusion of the component's viewport. |\n `propSpreadingTarget` | `PropSpreadingTarget` | `root` | | Establishes the target for property spreading. |\n| `fillerPattern` | `'checkered' \\| 'diagstriped' \\| 'triangles'` | `'diagstriped'` | | Sets the desired pattern for the filler columns that may appear when columns are cross-synchronized. |\n\n### Snippets\n\n| Name | Parameters | Description |\n| - | - | - |\n| `headerCell` | `ColumnContext\u003cTRow, TCol\u003e` | Renders header cells' content.  The snippet is passed the column definition. |\n| `dataCell` | `DataCellContext\u003cTRow, TCol\u003e` | Renders data cells' content.  The snippet is passed the column definition and the data object for the row being rendered. |\n| `rowExpansion` | `RowContext\u003cTRow\u003e` | Renders arbitrary content immediately below the data cells of the row.  It is only rendered when `WjDvRow\u003cTRow\u003e.wjdv.expanded` is `true`. |\n| `controlHeaderCell` | (none) | Renders the contents of the control column's header cell. |\n| `controlDataCell` | `RowContext\u003cTRow\u003e` | Renders the contents of the control column's data cells. |\n| `caption` | (none) | Renders the content of the data view's caption. |\n\n### Events\n\nNone.\n\n## Roadmap\n\n- [x] Scrollable viewport\n- [x] Striped look\n- [x] Row highlighting effect on hover\n- [x] Column alignment\n- [x] Text wrap control\n- [x] Hideable columns\n- [x] Pinnable columns\n- [x] Customizable appearance\n- [x] Theme component\n- [x] headerCell snippet\n- [x] dataCell snippet\n- [x] Resizable columns\n- [x] Expansible rows\n- [x] Row selection\n- [x] Control column\n- [x] Header styling\n- [x] Cross Column Synchronization\n- [ ] Make cell/row/column padding themeable\n- [ ] dataRow snippet (complex)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwjsoftware%2Fwjfe-dataview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwjsoftware%2Fwjfe-dataview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwjsoftware%2Fwjfe-dataview/lists"}