+
+
+
+
+
+
[ Index ]
+ + + + + +## Description + +`@proangular/pro-table` is a **type-safe, Angular 20–first abstraction** over +Angular Material’s table. It’s designed for apps using **standalone components, +signals, and the new control-flow syntax** so you can wire up robust data grids +quickly without giving up control of your data model or rendering. The component +keeps Material’s performance and accessibility surface, while adding +strongly-typed columns, selection, copy-on-click, expandable detail rows, and a +clean sorting contract that **emits intent** instead of mutating your data for +you. + +### Why it’s useful (technical) + +- **Compile-time guarantees for columns & data** + Columns are declared as `TableColumn[ Index ]
+ + + + + +## Installation + +Using Node Package Manager ([NPM][url-node-js]) in a new terminal window run the +following commands to install the required dependencies. + +### Prerequisites + +**Angular Material** + +More information on theming Angular Material: +https://material.angular.io/guide/theming + +```bash +ng add @angular/material +``` + +### Install Pro Table Components + +```bash +ng add @proangular/pro-table@latest +``` + +or + +```bash +npm install @proangular/pro-table --save +``` + +[ Index ]
+ + + + + +## Usage + +### Importing + +Import the table component to use in your Angular application where used: + +```diff ++ import { TableComponent } from '@proangular/pro-table'; + +// For modules +@NgModule({ + ... + imports: [ ++ TableComponent, + ... + ], +}) + +// For standalone components +@Component({ + ... + imports: [ ++ TableComponent, + ... + ], +}) + +// Markup usage ++[ Index ]
+ + + + + +### Expandable Rows + +```html +{{ data | json }}
+[ Index ]
+ + + + + +### API + +Input Bindings + +| Input | Type | Default Value | Required | Description | +| ---------------------- | --------------- | ---------------------- | -------- | ------------------------------------------------------ | +| `columns` | `TableColumn[]` | N/A | True | Table column definitions mapped to keys in the `data`. | +| `data` | `any[]` | N/A | True | Table data array to display. | +| `highlightOddRows` | `boolean` | `false` | False | Highlight odd rows. | +| `maxSelectableRows` | `number` | No limit | False | Maximum number of selectable rows. | +| `placeholderEmptyData` | `string` | `N/A` | False | Placeholder text when no data is available for a cell. | +| `placeholderEmptyList` | `string` | `No items to display.` | False | Placeholder text when data array is empty. | +| `placeholderLoading` | `string` | `Loading...` | False | Placeholder text when data is loading. | +| `rowClickEnabled` | `boolean` | `false` | False | Enable row click event. | +| `selectable` | `boolean` | `false` | False | Enable row selection. | +| `stickyHeader` | `boolean` | `false` | False | Enable sticky table header. | +| `trackByFn` | `function` | Default `trackBy` (id) | False | Custom trackBy function for rows. | + +Event Handling + +| Event | Description | +| ----------------- | ----------------------------------------------------------- | +| `rowClick` | Emits if a row is clicked when `rowClickEnabled` is true. | +| `rowSelectChange` | Emits if a row selection changes when `selectable` is true. | +| `sortChange` | Emits when sort changes. | + +[ Index ]
+ + + + + +## Compatibility + +| Angular version | @proangular/pro-table | Install | +| --------------- | --------------------- | -------------------------------- | +| v20 | v20.x.x | ng add @proangular/pro-table@^20 | +| v19 | ------ | Untested | +| v18 | ------ | Untested | +| v17 | ------ | Untested | + +[ Index ]
+ + + + + +## Contributions + +Please submit all issues, and feature requests here: +[https://github.com/ProAngular/pro-table/issues][url-new-issue] + +Contribution: + +1. Clone the repo and create a new branch: + +- `git clone https://github.com/ProAngular/pro-table.git` +- `git checkout -b username/feature-or-bug-description` + +2. Bump up the version of package in `package.json` and `package-lock.json`, + commit all changes, push. + +- `git add -A` +- `git commit -m "My commit message"` +- `git push origin username/feature-or-bug-description` + +3. Submit code in published PR for review and approval. Add a good description + and link any possible user stories or bugs. + +- [Create a new pull request](https://github.com/ProAngular/pro-table/compare). + +4. Allow CI actions to completely run and verify files. +5. Add/ping reviewers and await approval. + +Thank you for any and all contributions! + +[ Index ]
+ + + + + +## Licensing + +This project is licensed under the **MIT** License. See the +[LICENSE](LICENSE.md) file for the pertaining license text. + +`SPDX-License-Identifier: MIT` + +[ Index ]
+ + + + + +## Wrapping Up + +Thank you to the entire Angular team and community for such a great framework to +build upon. If you have any questions, please let me know by opening an issue +[here][url-new-issue]. + +| Type | Info | +| :------------------------------------------------------------------------ | :------------------------------------------------------------- | +|
| webmaster@codytolene.com |
+| 
| https://github.com/sponsors/CodyTolene |
+| 
| https://www.buymeacoffee.com/codytolene |
+| 
| bc1qfx3lvspkj0q077u3gnrnxqkqwyvcku2nml86wmudy7yf2u8edmqq0a5vnt |
+
+Fin. Happy programming friend!
+
+Cody Tolene
+
+
+
+[img-info]: .github/images/ng-icons/info.svg
+[url-demo]: https://www.ProAngular.com/demos/pro-table
+[url-example-table-code]: src/app/table-example/table-example.component.html
+[url-new-issue]: https://github.com/ProAngular/pro-table/issues
+[url-node-js]: https://nodejs.org/
diff --git a/angular.json b/angular.json
new file mode 100644
index 0000000..2c95a5e
--- /dev/null
+++ b/angular.json
@@ -0,0 +1,142 @@
+{
+ "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+ "version": 1,
+ "newProjectRoot": "projects",
+ "projects": {
+ "pro-table": {
+ "projectType": "application",
+ "schematics": {
+ "@schematics/angular:component": {
+ "style": "scss"
+ }
+ },
+ "root": "",
+ "sourceRoot": "src",
+ "prefix": "app",
+ "architect": {
+ "build": {
+ "builder": "@angular/build:application",
+ "options": {
+ "outputPath": "dist/pro-table",
+ "index": "src/index.html",
+ "browser": "src/main.ts",
+ "polyfills": [
+ "zone.js"
+ ],
+ "tsConfig": "tsconfig.app.json",
+ "inlineStyleLanguage": "scss",
+ "assets": [
+ {
+ "glob": "**/*",
+ "input": "public"
+ }
+ ],
+ "styles": [
+ "src/styles.scss"
+ ],
+ "scripts": []
+ },
+ "configurations": {
+ "production": {
+ "budgets": [
+ {
+ "type": "initial",
+ "maximumWarning": "1.5mb",
+ "maximumError": "2mb"
+ },
+ {
+ "type": "anyComponentStyle",
+ "maximumWarning": "4kB",
+ "maximumError": "8kB"
+ }
+ ],
+ "outputHashing": "all"
+ },
+ "development": {
+ "optimization": false,
+ "extractLicenses": false,
+ "sourceMap": true
+ }
+ },
+ "defaultConfiguration": "production"
+ },
+ "serve": {
+ "builder": "@angular/build:dev-server",
+ "configurations": {
+ "production": {
+ "buildTarget": "pro-table:build:production"
+ },
+ "development": {
+ "buildTarget": "pro-table:build:development"
+ }
+ },
+ "defaultConfiguration": "development"
+ },
+ "extract-i18n": {
+ "builder": "@angular/build:extract-i18n"
+ },
+ "test": {
+ "builder": "@angular/build:karma",
+ "options": {
+ "polyfills": [
+ "zone.js",
+ "zone.js/testing"
+ ],
+ "tsConfig": "tsconfig.spec.json",
+ "inlineStyleLanguage": "scss",
+ "assets": [
+ {
+ "glob": "**/*",
+ "input": "public"
+ }
+ ],
+ "styles": [
+ "src/styles.scss"
+ ],
+ "scripts": []
+ }
+ },
+ "lint": {
+ "builder": "@angular-eslint/builder:lint",
+ "options": {
+ "lintFilePatterns": [
+ "src/**/*.ts",
+ "src/**/*.html"
+ ]
+ }
+ }
+ }
+ }
+ },
+ "cli": {
+ "schematicCollections": [
+ "@angular-eslint/schematics"
+ ]
+ },
+ "schematics": {
+ "@schematics/angular:component": {
+ "type": "component"
+ },
+ "@schematics/angular:directive": {
+ "type": "directive"
+ },
+ "@schematics/angular:service": {
+ "type": "service"
+ },
+ "@schematics/angular:guard": {
+ "typeSeparator": "."
+ },
+ "@schematics/angular:interceptor": {
+ "typeSeparator": "."
+ },
+ "@schematics/angular:module": {
+ "typeSeparator": "."
+ },
+ "@schematics/angular:pipe": {
+ "typeSeparator": "."
+ },
+ "@schematics/angular:resolver": {
+ "typeSeparator": "."
+ }
+ }
+}
diff --git a/eslint.config.js b/eslint.config.js
new file mode 100644
index 0000000..972bf9d
--- /dev/null
+++ b/eslint.config.js
@@ -0,0 +1,224 @@
+// @ts-check
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const angular = require('angular-eslint');
+
+module.exports = tseslint.config(
+ {
+ files: ['**/*.ts'],
+ extends: [
+ eslint.configs.recommended,
+ ...tseslint.configs.recommended,
+ ...tseslint.configs.stylistic,
+ ...angular.configs.tsRecommended,
+ ],
+ processor: angular.processInlineTemplates,
+ rules: {
+ // Component selectors should follow given naming rules.
+ // @see http://codelyzer.com/rules/component-selector/
+ '@angular-eslint/component-selector': [
+ 'error',
+ {
+ type: 'element',
+ prefix: 'pro',
+ style: 'kebab-case',
+ },
+ ],
+ // Directive selectors should follow given naming rules.
+ // @see http://codelyzer.com/rules/directive-selector/
+ '@angular-eslint/directive-selector': [
+ 'error',
+ {
+ type: 'attribute',
+ prefix: 'pro',
+ style: 'camelCase',
+ },
+ ],
+ // Prefer to declare @Output as readonly since they are not supposed
+ // to be reassigned.
+ // @see http://codelyzer.com/rules/prefer-output-readonly/
+ '@angular-eslint/prefer-output-readonly': ['error'],
+ // Enforce use of component selector rules.
+ // @see http://codelyzer.com/rules/component-selector/
+ '@angular-eslint/use-component-selector': ['error'],
+ // Disallows using ViewEncapsulation.None.
+ // @see http://codelyzer.com/rules/use-component-view-encapsulation/
+ '@angular-eslint/use-component-view-encapsulation': ['error'],
+ // Ensure that components implement life cycle interfaces if they use
+ // them.
+ // @see http://codelyzer.com/rules/use-life-cycle-interface/
+ '@angular-eslint/use-lifecycle-interface': ['error'],
+ // Require consistently using either T[] or Arrayng add @proangular/pro-table
+ 
+
+ 
+
+ |
+ |
+
+ |
+ + {{ column.label }} + | +
+ @let data = getData(dataSourceItem, column.key);
+ @switch (getTypeOf(data)) {
+ @case ('datetime') {
+
+ {{ data | dateTime: 'MM/dd/yyyy, hh:mm a' }}
+
+ }
+ @case ('date') {
+ {{ getDate(data) | date: 'MM/dd/yyyy' }}
+ }
+ @case ('object') {
+ @if (isTableTemplateRefObject(data)) {
+ @let tableTemplateRefObject = data;
+ |
+ + + | +
|---|
| + {{ placeholderEmptyList }} + | +
{{ placeholderLoading }}
+} @else { +Failed to load data.
+} diff --git a/src/app/public/table/table.component.scss b/src/app/public/table/table.component.scss new file mode 100644 index 0000000..48ea610 --- /dev/null +++ b/src/app/public/table/table.component.scss @@ -0,0 +1,111 @@ +$table-bg: var(--mat-table-background-color); + +:host { + background: $table-bg; + display: block; + overflow-x: auto; + overflow-y: auto; +} + +:host.clickable tr:not(.expandable-row).mat-mdc-row { + cursor: pointer; +} + +table { + background: $table-bg; + border-collapse: collapse; + width: 100%; + + ng-deep thead { + background: $table-bg; + + > tr { + background: $table-bg; + } + } + + td, + th { + text-align: left; + padding: 0.5rem; + border: none; + } + + td.copyable:hover { + cursor: pointer; + text-decoration: underline; + } + + tr.expandable-row { + height: 0; + max-height: 0; + min-height: 0; + + > td { + margin: 0; + padding: 0; + height: 0; + } + } + + td { + background-color: inherit; + + button.expandable-row-button { + margin: 0 0 0 0.25rem; + padding: 0; + background: transparent; + border: 0; + cursor: pointer; + } + + > div.expandable-row-details { + background-color: inherit; + display: flex; + overflow: hidden; + width: 100%; + + > div { + width: 100%; + } + } + } +} + +table tr.mat-mdc-row.even { + background: $table-bg; +} + +:host.highlight-odd-rows table tr.mat-mdc-row.odd { + background: color-mix(in srgb, $table-bg 90%, black 10%); +} + +/* Fallback for browsers without color-mix */ +@supports not (background: color-mix(in srgb, black, white)) { + :host.highlight-odd-rows table tr.mat-mdc-row.odd { + position: relative; + } + + :host.highlight-odd-rows table tr.mat-mdc-row.odd::before { + content: ''; + position: absolute; + inset: 0; + background: rgba(0, 0, 0, 0.1); + pointer-events: none; + } +} + +table td { + background-color: inherit; +} + +tr.empty > td, +p.loading { + padding: 1rem; +} + +::ng-deep pro-table { + .mat-mdc-table thead > tr > th.mat-sort-header { + background: var(--mat-table-background-color); + } +} diff --git a/src/app/public/table/table.component.ts b/src/app/public/table/table.component.ts new file mode 100644 index 0000000..42ebeb5 --- /dev/null +++ b/src/app/public/table/table.component.ts @@ -0,0 +1,421 @@ +import { DateTime } from 'luxon'; +import { + BehaviorSubject, + ReplaySubject, + combineLatest, + filter, + firstValueFrom, + map, + shareReplay, +} from 'rxjs'; + +import { Clipboard } from '@angular/cdk/clipboard'; +import { BooleanInput, coerceBooleanProperty } from '@angular/cdk/coercion'; +import { CommonModule } from '@angular/common'; +import { + ChangeDetectionStrategy, + Component, + DestroyRef, + ElementRef, + EventEmitter, + HostBinding, + Input, + OnInit, + Output, + TrackByFunction, + booleanAttribute, + inject, + numberAttribute, +} from '@angular/core'; +import { takeUntilDestroyed } from '@angular/core/rxjs-interop'; +import { MatCheckboxModule } from '@angular/material/checkbox'; +import { MatPaginator } from '@angular/material/paginator'; +import { MatSnackBar } from '@angular/material/snack-bar'; +import { MatSortModule, Sort } from '@angular/material/sort'; +import { MatTableDataSource, MatTableModule } from '@angular/material/table'; +import { MatTooltipModule } from '@angular/material/tooltip'; + +import { DateTimePipe } from '../pipes'; +import { + DefinedPrimitive, + NestedKeysOfString, + TableColumn, + TableSortChangeEvent, + TableTemplateReferenceExpandableObject, + TableTemplateReferenceObject, +} from '../types'; +import { + isNonEmptyPrimitive, + isNonEmptyString, + isNonEmptyValue, +} from '../utilities'; +import { TABLE_ANIMATIONS } from './table-animations'; + +/** + * A custom table component wrapper for Angular Material's table component. + * + * @see https://material.angular.dev/components/table/overview + */ +@Component({ + selector: 'pro-table[columns][data]', + standalone: true, + imports: [ + CommonModule, + MatTableModule, + MatSortModule, + MatCheckboxModule, + MatTooltipModule, + DateTimePipe, + ], + templateUrl: './table.component.html', + styleUrls: ['./table.component.scss'], + changeDetection: ChangeDetectionStrategy.OnPush, + animations: TABLE_ANIMATIONS, +}) +export class TableComponent{{ pretifyJson(data) }}
+