Skip to content

Commit 6b88cc5

Browse files
CodyToleneCodyTolene
committed
Add README
1 parent 47aa713 commit 6b88cc5

File tree

1 file changed

+99
-19
lines changed

1 file changed

+99
-19
lines changed

‎README.md‎

Lines changed: 99 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,11 @@
3737
- [Prerequisites](#prerequisites)
3838
- [Install Pro Table Components](#install-pro-table-components)
3939
- [Usage](#usage)
40+
- [Importing](#importing)
41+
- [Expandable Rows](#expandable-rows)
42+
- [API](#api)
4043
- [Compatibility](#compatibility)
41-
- [Development](#development)
44+
- [Contributions](#contributions)
4245
- [Licensing](#licensing)
4346
- [Wrapping Up](#wrapping-up)
4447

@@ -60,11 +63,60 @@ https://www.ProAngular.com/demos/pro-table
6063

6164
## Description <a name="description"></a>
6265

63-
This project...
64-
65-
The components included in this project are:
66-
67-
- **TableComponent**: ...
66+
`@proangular/pro-table` is a **type-safe, Angular 20–first abstraction** over
67+
Angular Material’s table. It’s designed for apps using **standalone components,
68+
signals, and the new control-flow syntax** so you can wire up robust data grids
69+
quickly without giving up control of your data model or rendering. The component
70+
keeps Material’s performance and accessibility surface, while adding
71+
strongly-typed columns, selection, copy-on-click, expandable detail rows, and a
72+
clean sorting contract that **emits intent** instead of mutating your data for
73+
you.
74+
75+
### Why it’s useful (technical)
76+
77+
- **Compile-time guarantees for columns & data**
78+
Columns are declared as `TableColumn<T>`, where `key` is tied to your row
79+
model `T`. That prevents typos and drift between your data and headers.
80+
81+
- **Sorting as a pure UI signal**
82+
The table **does not** reorder your data. Instead it emits a
83+
`TableSortChangeEvent<T>` with a typed key and direction; you decide how to
84+
sort (or not) in your host component. This keeps business logic out of the
85+
view layer and plays well with signals/NgRx/etc.
86+
87+
- **Expandable rows that are template-driven**
88+
Provide a `TemplateRef` per row and the table renders it in a dedicated detail
89+
row using `multiTemplateDataRows`. Expansion is reference-based, so you can
90+
attach any context object you like.
91+
92+
- **Selection with guardrails**
93+
Built-in single/multi select with a master checkbox, an optional **max
94+
selectable** limit, and an emitted list of selected rows without leaking table
95+
internals to the host.
96+
97+
- **Great DX for common table chores**
98+
One-line **copy-to-clipboard** per column (with tooltip and snack-bar
99+
feedback), sticky headers, row click events, and cell placeholders for empty
100+
values. These affordances reduce the “glue code” you normally write around
101+
`MatTable`.
102+
103+
- **Built for Angular 20 patterns**
104+
Uses **OnPush** change detection, `@if/@for/@let` in templates, and small
105+
reactive streams (`BehaviorSubject/ReplaySubject` + `shareReplay`) to keep
106+
updates efficient. The example shows **signals** + `effect()` integrating
107+
cleanly with the component’s inputs.
108+
109+
### Features
110+
111+
- Strong typing for both column definitions and row data (`TableColumn<T>`)
112+
- Opt-in selection with max count and `rowSelectChange` events
113+
- Click-to-copy per column with tooltip and snackbar feedback
114+
- Sticky header option
115+
- **Expandable** detail rows via `TemplateRef` + `multiTemplateDataRows` with
116+
animations
117+
- **Sort intent** via `sortChange` events no data mutation, you stay in control
118+
- Works seamlessly with standalone components, signals, and Material’s
119+
`MatSort`/`MatTable`
68120

69121
<p align="right">[ <a href="#index">Index</a> ]</p>
70122

@@ -108,7 +160,7 @@ npm install @proangular/pro-table --save
108160

109161
## Usage <a name="usage"></a>
110162

111-
### Importing and Usage <a name="importing-and-usage"></a>
163+
### Importing <a name="importing"></a>
112164

113165
Import the table component to use in your Angular application where used:
114166

@@ -137,25 +189,53 @@ Import the table component to use in your Angular application where used:
137189
+ <pro-table [columns]="columns" [data]="data" />
138190
```
139191

192+
<p align="right">[ <a href="#index">Index</a> ]</p>
193+
194+
<!---------------------------------------------------------------------------->
195+
<!---------------------------------------------------------------------------->
196+
<!---------------------------------------------------------------------------->
197+
198+
### Expandable Rows <a name="expandable-rows"></a>
199+
200+
```html
201+
<pro-table [columns]="columns()" [data]="rowsWithDetailTemplate()" />
202+
203+
<ng-template #detailTemplate let-data="data">
204+
<pre>{{ data | json }}</pre>
205+
</ng-template>
206+
```
207+
208+
Map your data to include a template field typed as
209+
`TableTemplateReferenceExpandableObject` if you want per-row detail. The table
210+
uses `multiTemplateDataRows` and a detail row with `expandedDetail` to render
211+
the template when expanded.
212+
140213
> ![Info][img-info] See example table code [here][url-example-table-code], or a
141-
> live demo [here][url-demo].
214+
> live [demo][url-demo].
215+
216+
<p align="right">[ <a href="#index">Index</a> ]</p>
217+
218+
<!---------------------------------------------------------------------------->
219+
<!---------------------------------------------------------------------------->
220+
<!---------------------------------------------------------------------------->
142221

143222
### API <a name="api"></a>
144223

145224
Input Bindings
146225

147226
| Input | Type | Default Value | Required | Description |
148227
| ---------------------- | --------------- | ---------------------- | -------- | ------------------------------------------------------ |
149-
| `columns` | `TableColumn[]` | N/A | | Table column definitions mapped to keys in the `data`. |
150-
| `data` | `any[]` | N/A | | Table data array to display. |
151-
| `highlightOddRows` | `boolean` | `false` | | Highlight odd rows. |
152-
| `maxSelectableRows` | `number` | No limit | | Maximum number of selectable rows. |
153-
| `placeholderEmptyData` | `string` | `N/A` | | Placeholder text when no data is available for a cell. |
154-
| `placeholderEmptyList` | `string` | `No items to display.` | | Placeholder text when data array is empty. |
155-
| `placeholderLoading` | `string` | `Loading...` | | Placeholder text when data is loading. |
156-
| `rowClickEnabled` | `boolean` | `false` | | Enable row click event. |
157-
| `selectable` | `boolean` | `false` | | Enable row selection. |
158-
| `stickyHeader` | `boolean` | `false` | | Enable sticky table header. |
228+
| `columns` | `TableColumn[]` | N/A | True | Table column definitions mapped to keys in the `data`. |
229+
| `data` | `any[]` | N/A | True | Table data array to display. |
230+
| `highlightOddRows` | `boolean` | `false` | False | Highlight odd rows. |
231+
| `maxSelectableRows` | `number` | No limit | False | Maximum number of selectable rows. |
232+
| `placeholderEmptyData` | `string` | `N/A` | False | Placeholder text when no data is available for a cell. |
233+
| `placeholderEmptyList` | `string` | `No items to display.` | False | Placeholder text when data array is empty. |
234+
| `placeholderLoading` | `string` | `Loading...` | False | Placeholder text when data is loading. |
235+
| `rowClickEnabled` | `boolean` | `false` | False | Enable row click event. |
236+
| `selectable` | `boolean` | `false` | False | Enable row selection. |
237+
| `stickyHeader` | `boolean` | `false` | False | Enable sticky table header. |
238+
| `trackByFn` | `function` | Default `trackBy` (id) | False | Custom trackBy function for rows. |
159239

160240
Event Handling
161241

@@ -186,7 +266,7 @@ Event Handling
186266
<!---------------------------------------------------------------------------->
187267
<!---------------------------------------------------------------------------->
188268

189-
## Development <a name="development"></a>
269+
## Contributions <a name="contributions"></a>
190270

191271
Please submit all issues, and feature requests here:
192272
[https://github.com/ProAngular/pro-table/issues][url-new-issue]

0 commit comments

Comments
 (0)