diff --git a/README.md b/README.md index 1527827169..5876fd0fd8 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ Try other [TanStack](https://tanstack.com) libraries: You may know **TanStack Table** by our adapter names, too! +- [Angular Table](https://tanstack.com/table/v8/docs/adapters/angular-table) - [Qwik Table](https://tanstack.com/table/v8/docs/adapters/qwik-table) - [**React Table**](https://tanstack.com/table/v8/docs/adapters/react-table) - [Solid Table](https://tanstack.com/table/v8/docs/adapters/solid-table) @@ -115,6 +116,7 @@ Install one of the following packages based on your framework of choice: ```bash # Npm +npm install @tanstack/angular-table npm install @tanstack/qwik-table npm install @tanstack/react-table npm install @tanstack/solid-table diff --git a/docs/config.json b/docs/config.json index a5836173ad..1abd067c77 100644 --- a/docs/config.json +++ b/docs/config.json @@ -125,6 +125,15 @@ } ], "frameworks": [ + { + "label": "angular", + "children": [ + { + "label": "Table State", + "to": "framework/angular/guide/table-state" + } + ] + }, { "label": "qwik", "children": [ @@ -357,8 +366,8 @@ "label": "Grouping" }, { - "to": "framework/angular/examples/selection", - "label": "Selection" + "to": "framework/angular/examples/row-selection", + "label": "Row Selection" } ] }, diff --git a/docs/framework/angular/guide/table-state.md b/docs/framework/angular/guide/table-state.md new file mode 100644 index 0000000000..26f915b948 --- /dev/null +++ b/docs/framework/angular/guide/table-state.md @@ -0,0 +1,178 @@ +--- +title: Table State (Angular) Guide +--- + +## Table State (Angular) Guide + +TanStack Table has a simple underlying internal state management system to store and manage the state of the table. It also lets you selectively pull out any state that you need to manage in your own state management. This guide will walk you through the different ways in which you can interact with and manage the state of the table. + +### Accessing Table State + +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. + +```ts +this.table = createAngularTable({ + data: this.data, + columns: columns, + //... +}) + +console.log(this.table.getState()) //access the entire internal state +console.log(this.table.getState().rowSelection) //access just the row selection state +``` + +### Custom Initial State + +If all you need to do for certain states is customize their initial default values, you still do not need to manage any of the state yourself. You can simply set values in the `initialState` option of the table instance. + +```jsx +const table = useAngularTable({ + columns, + data, + initialState: { + columnOrder: ['age', 'firstName', 'lastName'], //customize the initial column order + columnVisibility: { + id: false //hide the id column by default + }, + expanded: true, //expand all rows by default + sorting: [ + { + id: 'age', + desc: true //sort by age in descending order by default + } + ] + }, + //... +}) +``` + +> **Note**: Only specify each particular state in either `initialState` or `state`, but not both. If you pass in a particular state value to both `initialState` and `state`, the initialized state in `state` will take overwrite any corresponding value in `initialState`. + +### Controlled State + +If you need easy access to the table state in other areas of your application, TanStack Table makes it easy to control and manage any or all of the table state in your own state management system. You can do this by passing in your own state and state management functions to the `state` and `on[State]Change` table options. + +#### Individual Controlled State + +You can control just the state that you need easy access to. You do NOT have to control all of the table state if you do not need to. It is recommended to only control the state that you need on a case-by-case basis. + +In order to control a particular state, you need to both pass in the corresponding `state` value and the `on[State]Change` function to the table instance. + +Let's take filtering, sorting, and pagination as an example in a "manual" server-side data fetching scenario. You can store the filtering, sorting, and pagination state in your own state management, but leave out any other state like column order, column visibility, etc. if your API does not care about those values. + +```jsx +const columnFilters = Angular.useSignal([]) //no default filters +const sorting = Angular.useSignal([{ + id: 'age', + desc: true, //sort by age in descending order by default +}]) +const pagination = Angular.useSignal({ pageIndex: 0, pageSize: 15 }) + +//Use our controlled state values to fetch data +const tableQuery = useQuery({ + queryKey: ['users', columnFilters.value, sorting.value, pagination.value], + queryFn: () => fetchUsers(columnFilters.value, sorting.value, pagination.value), + //... +}) + +const table = useAngularTable({ + columns: columns.value, + data: tableQuery.data, + //... + state: { + columnFilters: columnFilters.value, //pass controlled state back to the table (overrides internal state) + sorting: sorting.value, + pagination: pagination.value, + }, + onColumnFiltersChange: updater => { + columnFilters.value = updater instanceOf Function ? updater(columnFilters.value) : updater //hoist columnFilters state into our own state management + }, + onSortingChange: updater => { + sorting.value = updater instanceOf Function ? updater(sorting.value) : updater + }, + onPaginationChange: updater => { + pagination.value = updater instanceOf Function ? updater(pagination.value) : updater + }, +}) +//... +``` + +#### Fully Controlled State + +Alternatively, you can control the entire table state with the `onStateChange` table option. It will hoist out the entire table state into your own state management system. Be careful with this approach, as you might find that raising some frequently changing state values up a component tree, like `columnSizingInfo` state`, might cause bad performance issues. + +A couple of more tricks may be needed to make this work. If you use the `onStateChange` table option, the initial values of the `state` must be populated with all of the relevant state values for all of the features that you want to use. You can either manually type out all of the initial state values, or use the `table.setOptions` API in a special way as shown below. + +```jsx +//create a table instance with default state values +const table = useAngularTable({ + columns, + data, + //... Note: `state` values are NOT passed in yet +}) + + +const sate = Angular.useSignal({ + ...table.initialState, //populate the initial state with all of the default state values from the table instance + pagination: { + pageIndex: 0, + pageSize: 15 //optionally customize the initial pagination state. + } +}) + +//Use the table.setOptions API to merge our fully controlled state onto the table instance +table.setOptions(prev => ({ + ...prev, //preserve any other options that we have set up above + state: state.value, //our fully controlled state overrides the internal state + onStateChange: updater => { + state.value = updater instanceOf Function ? updater(state.value) : updater //any state changes will be pushed up to our own state management + }, +})) +``` + +### On State Change Callbacks + +So far, we have seen the `on[State]Change` and `onStateChange` table options work to "hoist" the table state changes into our own state management. However, there are a few things about these using these options that you should be aware of. + +#### 1. **State Change Callbacks MUST have their corresponding state value in the `state` option**. + +Specifying an `on[State]Change` callback tells the table instance that this will be a controlled state. If you do not specify the corresponding `state` value, that state will be "frozen" with its initial value. + +```jsx +const sorting = Angular.useSignal([]) +//... +const table = useAngularTable({ + columns, + data, + //... + state: { + sorting: sorting.value, //required because we are using `onSortingChange` + }, + onSortingChange: updater => { + sorting.value = updater instanceOf Function ? updater(sorting) : updater //makes the `state.sorting` controlled + }, +}) +``` + +#### 2. **Updaters can either be raw values or callback functions**. + +The `on[State]Change` and `onStateChange` callbacks work exactly like the `setState` functions in React. The updater values can either be a new state value or a callback function that takes the previous state value and returns the new state value. + +What implications does this have? It means that if you want to add in some extra logic in any of the `on[State]Change` callbacks, you can do so, but you need to check whether or not the new incoming updater value is a function or value. + +This is why you will see the `updater instanceOf Function ? updater(state.value) : updater` pattern in the examples above. This pattern checks if the updater is a function, and if it is, it calls the function with the previous state value to get the new state value. + +### State Types + +All complex states in TanStack Table have their own TypeScript types that you can import and use. This can be handy for ensuring that you are using the correct data structures and properties for the state values that you are controlling. + +```tsx +import { useAngularTable, SortingState } from '@tanstack/angular-table' +//... +const sorting = Angular.useSignal([ + { + id: 'age', //you should get autocomplete for the `id` and `desc` properties + desc: true, + } +]) +``` \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index 4f01c59376..f25d1cc263 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -10,7 +10,7 @@ While TanStack Table is written in [TypeScript](https://www.typescriptlang.org/) ## Headless -As it was mentioned extensively in the [Intro](./guide/introduction) section, TanStack Table is **headless**. This means that it doesn't render any DOM elements, and instead relies on you, the UI/UX developer to provide the table's markup and styles. This is a great way to build a table that can be used in any UI framework, including React, Vue, Solid, Svelte, Qwik, and even JS-to-native platforms like React Native! +As it was mentioned extensively in the [Intro](./guide/introduction) section, TanStack Table is **headless**. This means that it doesn't render any DOM elements, and instead relies on you, the UI/UX developer to provide the table's markup and styles. This is a great way to build a table that can be used in any UI framework, including React, Vue, Solid, Svelte, Qwik, Angular, and even JS-to-native platforms like React Native! ## Core Objects and Types diff --git a/examples/angular/basic/package.json b/examples/angular/basic/package.json index 92f84854ea..71341dff29 100644 --- a/examples/angular/basic/package.json +++ b/examples/angular/basic/package.json @@ -1,5 +1,5 @@ { - "name": "basic", + "name": "tanstack-table-example-angular-basic", "version": "0.0.0", "scripts": { "ng": "ng", @@ -18,9 +18,8 @@ "@angular/platform-browser": "^17.3.1", "@angular/platform-browser-dynamic": "^17.3.1", "@angular/router": "^17.3.1", - "@tanstack/angular-table": "^8.12.0", + "@tanstack/angular-table": "^8.14.0", "rxjs": "~7.8.1", - "tslib": "^2.6.2", "zone.js": "~0.14.4" }, "devDependencies": { @@ -34,6 +33,7 @@ "karma-coverage": "~2.2.1", "karma-jasmine": "~5.1.0", "karma-jasmine-html-reporter": "~2.1.0", + "tslib": "^2.6.2", "typescript": "5.4.3" } } diff --git a/examples/angular/grouping/package.json b/examples/angular/grouping/package.json index f712d95f5b..1cf0ed1644 100644 --- a/examples/angular/grouping/package.json +++ b/examples/angular/grouping/package.json @@ -1,5 +1,5 @@ { - "name": "grouping", + "name": "tanstack-table-example-angular-grouping", "version": "0.0.0", "scripts": { "ng": "ng", @@ -19,9 +19,8 @@ "@angular/platform-browser-dynamic": "^17.3.1", "@angular/router": "^17.3.1", "@faker-js/faker": "^8.4.1", - "@tanstack/angular-table": "^8.12.0", + "@tanstack/angular-table": "^8.14.0", "rxjs": "~7.8.1", - "tslib": "^2.6.2", "zone.js": "~0.14.4" }, "devDependencies": { @@ -35,6 +34,7 @@ "karma-coverage": "~2.2.1", "karma-jasmine": "~5.1.0", "karma-jasmine-html-reporter": "~2.1.0", + "tslib": "^2.6.2", "typescript": "5.4.3" } } diff --git a/examples/angular/selection/.editorconfig b/examples/angular/row-selection/.editorconfig similarity index 100% rename from examples/angular/selection/.editorconfig rename to examples/angular/row-selection/.editorconfig diff --git a/examples/angular/selection/.gitignore b/examples/angular/row-selection/.gitignore similarity index 100% rename from examples/angular/selection/.gitignore rename to examples/angular/row-selection/.gitignore diff --git a/examples/angular/selection/.vscode/extensions.json b/examples/angular/row-selection/.vscode/extensions.json similarity index 100% rename from examples/angular/selection/.vscode/extensions.json rename to examples/angular/row-selection/.vscode/extensions.json diff --git a/examples/angular/selection/.vscode/launch.json b/examples/angular/row-selection/.vscode/launch.json similarity index 100% rename from examples/angular/selection/.vscode/launch.json rename to examples/angular/row-selection/.vscode/launch.json diff --git a/examples/angular/selection/.vscode/tasks.json b/examples/angular/row-selection/.vscode/tasks.json similarity index 100% rename from examples/angular/selection/.vscode/tasks.json rename to examples/angular/row-selection/.vscode/tasks.json diff --git a/examples/angular/selection/README.md b/examples/angular/row-selection/README.md similarity index 100% rename from examples/angular/selection/README.md rename to examples/angular/row-selection/README.md diff --git a/examples/angular/selection/angular.json b/examples/angular/row-selection/angular.json similarity index 100% rename from examples/angular/selection/angular.json rename to examples/angular/row-selection/angular.json diff --git a/examples/angular/selection/package.json b/examples/angular/row-selection/package.json similarity index 91% rename from examples/angular/selection/package.json rename to examples/angular/row-selection/package.json index ca028b57df..287b798902 100644 --- a/examples/angular/selection/package.json +++ b/examples/angular/row-selection/package.json @@ -1,5 +1,5 @@ { - "name": "selection", + "name": "tanstack-table-example-angular-row-selection", "version": "0.0.0", "scripts": { "ng": "ng", @@ -19,7 +19,7 @@ "@angular/platform-browser-dynamic": "^17.3.1", "@angular/router": "^17.3.1", "@faker-js/faker": "^8.4.1", - "@tanstack/angular-table": "^8.12.0", + "@tanstack/angular-table": "^8.14.0", "rxjs": "~7.8.1", "tslib": "^2.6.2", "zone.js": "~0.14.4" diff --git a/examples/angular/selection/src/app/app.component.html b/examples/angular/row-selection/src/app/app.component.html similarity index 100% rename from examples/angular/selection/src/app/app.component.html rename to examples/angular/row-selection/src/app/app.component.html diff --git a/examples/angular/selection/src/app/app.component.scss b/examples/angular/row-selection/src/app/app.component.scss similarity index 100% rename from examples/angular/selection/src/app/app.component.scss rename to examples/angular/row-selection/src/app/app.component.scss diff --git a/examples/angular/selection/src/app/app.component.ts b/examples/angular/row-selection/src/app/app.component.ts similarity index 100% rename from examples/angular/selection/src/app/app.component.ts rename to examples/angular/row-selection/src/app/app.component.ts diff --git a/examples/angular/selection/src/app/app.config.ts b/examples/angular/row-selection/src/app/app.config.ts similarity index 100% rename from examples/angular/selection/src/app/app.config.ts rename to examples/angular/row-selection/src/app/app.config.ts diff --git a/examples/angular/selection/src/app/app.routes.ts b/examples/angular/row-selection/src/app/app.routes.ts similarity index 100% rename from examples/angular/selection/src/app/app.routes.ts rename to examples/angular/row-selection/src/app/app.routes.ts diff --git a/examples/angular/selection/src/app/columns.ts b/examples/angular/row-selection/src/app/columns.ts similarity index 100% rename from examples/angular/selection/src/app/columns.ts rename to examples/angular/row-selection/src/app/columns.ts diff --git a/examples/angular/selection/src/app/filter.ts b/examples/angular/row-selection/src/app/filter.ts similarity index 100% rename from examples/angular/selection/src/app/filter.ts rename to examples/angular/row-selection/src/app/filter.ts diff --git a/examples/angular/selection/src/app/mockdata.ts b/examples/angular/row-selection/src/app/mockdata.ts similarity index 100% rename from examples/angular/selection/src/app/mockdata.ts rename to examples/angular/row-selection/src/app/mockdata.ts diff --git a/examples/angular/selection/src/assets/.gitkeep b/examples/angular/row-selection/src/assets/.gitkeep similarity index 100% rename from examples/angular/selection/src/assets/.gitkeep rename to examples/angular/row-selection/src/assets/.gitkeep diff --git a/examples/angular/selection/src/favicon.ico b/examples/angular/row-selection/src/favicon.ico similarity index 100% rename from examples/angular/selection/src/favicon.ico rename to examples/angular/row-selection/src/favicon.ico diff --git a/examples/angular/selection/src/index.html b/examples/angular/row-selection/src/index.html similarity index 100% rename from examples/angular/selection/src/index.html rename to examples/angular/row-selection/src/index.html diff --git a/examples/angular/selection/src/main.ts b/examples/angular/row-selection/src/main.ts similarity index 100% rename from examples/angular/selection/src/main.ts rename to examples/angular/row-selection/src/main.ts diff --git a/examples/angular/selection/src/styles.scss b/examples/angular/row-selection/src/styles.scss similarity index 100% rename from examples/angular/selection/src/styles.scss rename to examples/angular/row-selection/src/styles.scss diff --git a/examples/angular/selection/tsconfig.app.json b/examples/angular/row-selection/tsconfig.app.json similarity index 100% rename from examples/angular/selection/tsconfig.app.json rename to examples/angular/row-selection/tsconfig.app.json diff --git a/examples/angular/selection/tsconfig.json b/examples/angular/row-selection/tsconfig.json similarity index 100% rename from examples/angular/selection/tsconfig.json rename to examples/angular/row-selection/tsconfig.json diff --git a/examples/angular/selection/tsconfig.spec.json b/examples/angular/row-selection/tsconfig.spec.json similarity index 100% rename from examples/angular/selection/tsconfig.spec.json rename to examples/angular/row-selection/tsconfig.spec.json diff --git a/packages/angular-table/package.json b/packages/angular-table/package.json index 72eb32e636..93cb0c8fef 100644 --- a/packages/angular-table/package.json +++ b/packages/angular-table/package.json @@ -1,6 +1,6 @@ { "name": "@tanstack/angular-table", - "version": "8.13.2", + "version": "8.14.0", "description": "Headless UI for building powerful tables & datagrids for Angular.", "author": "Tanner Linsley", "license": "MIT", diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index b22414c617..22da78fa62 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,8 +1,8 @@ packages: - 'packages/*' + - 'examples/angular/*' - 'examples/qwik/*' - 'examples/react/*' - 'examples/solid/*' - 'examples/svelte/*' - 'examples/vue/*' - - 'examples/angular/*'