@@ -11,9 +11,14 @@ import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
1111import { watch } from '../internal/watch.js' ;
1212import { DEFAULT_COLUMN_CONFIG , PIPELINE } from '../internal/constants.js' ;
1313import { registerGridIcons } from '../internal/icon-registry.js' ;
14- import { asArray , getFilterOperandsFor } from '../internal/utils.js' ;
15-
16- import type { ColumnConfig , GridRemoteConfig , GridSortingConfig , Keys } from '../internal/types.js' ;
14+ import { asArray , autoGenerateColumns , getFilterOperandsFor } from '../internal/utils.js' ;
15+
16+ import type {
17+ ColumnConfiguration ,
18+ GridRemoteConfig ,
19+ GridSortConfiguration ,
20+ Keys ,
21+ } from '../internal/types.js' ;
1722import type { FilterExpressionTree } from '../operations/filter/tree.js' ;
1823import type { FilterExpression } from '../operations/filter/types.js' ;
1924import type { SortExpression } from '../operations/sort/types.js' ;
@@ -49,18 +54,76 @@ defineComponents(
4954 IgcDropdownItemComponent ,
5055) ;
5156
57+ /**
58+ * Event object for the filtering event of the grid.
59+ */
5260export interface ApexFilteringEvent < T extends object > {
61+ /**
62+ * The filter expression to apply.
63+ */
5364 expression : FilterExpression < T > ;
65+ /**
66+ * The filter state of the column.
67+ */
5468 state : FilterExpressionTree < T > ;
5569}
5670
5771// TODO: Subject to change as these are way too generic names
72+ /**
73+ * Events for the apex-grid.
74+ */
5875export interface ApexGridEventMap < T extends object > {
76+ /**
77+ * Emitted when sorting is initiated through the UI.
78+ * Returns the sort expression which will be used for the operation.
79+ *
80+ * @remarks
81+ * The event is cancellable which prevents the operation from being applied.
82+ * The expression can be modified prior to the operation running.
83+ *
84+ * @event
85+ */
5986 sorting : CustomEvent < SortExpression < T > > ;
87+ /**
88+ * Emitted when a sort operation initiated through the UI has completed.
89+ * Returns the sort expression used for the operation.
90+ *
91+ * @event
92+ */
6093 sorted : CustomEvent < SortExpression < T > > ;
94+ /**
95+ * Emitted when filtering is initiated through the UI.
96+ *
97+ * @remarks
98+ * The event is cancellable which prevents the operation from being applied.
99+ * The expression can be modified prior to the operation running.
100+ *
101+ * @event
102+ */
61103 filtering : CustomEvent < ApexFilteringEvent < T > > ;
104+ /**
105+ * Emitted when a filter operation initiated through the UI has completed.
106+ * Returns the filter state for the affected column.
107+ *
108+ * @event
109+ */
62110 filtered : CustomEvent < FilterExpressionTree < T > > ;
63111}
112+
113+ /**
114+ * Apex grid is a web component for displaying data in a tabular format quick and easy.
115+ *
116+ * Out of the box it provides row virtualization, sort and filter operations (client and server side),
117+ * the ability to template cells and headers and column hiding.
118+ *
119+ * @element apex-grid
120+ *
121+ * @fires sorting - Emitted when sorting is initiated through the UI.
122+ * @fires sorted - Emitted when a sort operation initiated through the UI has completed.
123+ * @fires filtering - Emitted when filtering is initiated through the UI.
124+ * @fires filtered - Emitted when a filter operation initiated through the UI has completed.
125+ *
126+ */
64127@themes ( {
65128 bootstrap,
66129 fluent,
@@ -107,31 +170,78 @@ export default class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
107170 @queryAll ( ApexGridRow . is )
108171 protected _rows ! : NodeListOf < ApexGridRow < T > > ;
109172
173+ /** Column configuration for the grid. */
110174 @property ( { attribute : false } )
111- public columns : Array < ColumnConfig < T > > = [ ] ;
175+ public columns : Array < ColumnConfiguration < T > > = [ ] ;
112176
177+ /** The data source for the grid. */
113178 @property ( { attribute : false } )
114179 public data : Array < T > = [ ] ;
115180
181+ /**
182+ * Whether the grid will try to "resolve" its column configuration based on the passed
183+ * data source.
184+ *
185+ * @remarks
186+ * This is a one-time operation which is executed when the grid is initially added to the DOM.
187+ * Passing an empty data source or having a late bound data source (such as a HTTP request) will usually
188+ * result in empty column configuration for the grid.
189+ *
190+ * This property is ignored if any existing column configuration already exists in the grid.
191+ */
192+ @property ( { type : Boolean , attribute : 'auto-generate' } )
193+ public autoGenerate = false ;
194+
195+ /** Sort configuration property for the grid. */
116196 @property ( { attribute : false } )
117- public sortingConfig : GridSortingConfig = {
197+ public sortConfiguration : GridSortConfiguration = {
118198 multiple : true ,
119199 triState : true ,
120200 } ;
121201
202+ /**
203+ * Configuration object which controls remote data operations for the grid.
204+ */
122205 @property ( { attribute : false } )
123- public remoteConfig ?: GridRemoteConfig < T > ;
124-
206+ public remoteConfiguration ?: GridRemoteConfig < T > ;
207+
208+ /**
209+ * Set sort state for the apex grid.
210+ *
211+ * @remarks
212+ *
213+ */
125214 @property ( { attribute : false } )
126215 public sortExpressions : SortExpression < T > [ ] = [ ] ;
127216
217+ /**
218+ * Set filter state for the apex grid.
219+ */
128220 @property ( { attribute : false } )
129221 public filterExpressions : FilterExpression < T > [ ] = [ ] ;
130222
223+ /**
224+ * Returns the collection of rendered row elements in the grid.
225+ *
226+ * @remarks
227+ * Since the grid has virtualization, this property returns only the currently rendered
228+ * chunk of elements in the DOM.
229+ */
131230 public get rows ( ) {
132231 return Array . from ( this . _rows ) ;
133232 }
134233
234+ /**
235+ * Returns the state of the data source after sort/filter operations
236+ * have been applied.
237+ */
238+ public get dataView ( ) : ReadonlyArray < T > {
239+ return this . dataState ;
240+ }
241+
242+ /**
243+ * The total number of items in the {@link ApexGrid.dataView} collection.
244+ */
135245 public get totalItems ( ) {
136246 return this . dataState . length ;
137247 }
@@ -141,6 +251,11 @@ export default class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
141251 registerGridIcons ( ) ;
142252 }
143253
254+ public override connectedCallback ( ) {
255+ super . connectedCallback ( ) ;
256+ autoGenerateColumns ( this ) ;
257+ }
258+
144259 public override requestUpdate (
145260 name ?: PropertyKey ,
146261 oldValue ?: unknown ,
@@ -166,7 +281,7 @@ export default class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
166281 }
167282
168283 @watch ( 'columns' )
169- protected watchColumns ( _ : ColumnConfig < T > [ ] , newConfig : ColumnConfig < T > [ ] = [ ] ) {
284+ protected watchColumns ( _ : ColumnConfiguration < T > [ ] , newConfig : ColumnConfiguration < T > [ ] = [ ] ) {
170285 this . columns = newConfig . map ( config => ( { ...DEFAULT_COLUMN_CONFIG , ...config } ) ) ;
171286 }
172287
@@ -186,6 +301,9 @@ export default class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
186301 ) ;
187302 }
188303
304+ /**
305+ * Performs a filter operation in the grid based on the passed expression(s).
306+ */
189307 public filter ( config : FilterExpression < T > | FilterExpression < T > [ ] ) {
190308 this . stateController . filtering . filter (
191309 asArray ( config ) . map ( each =>
@@ -198,17 +316,26 @@ export default class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
198316 ) ;
199317 }
200318
201- public sort ( expressions : Partial < SortExpression < T > > | Partial < SortExpression < T > > [ ] ) {
202- this . stateController . sorting . sort ( expressions as SortExpression < T > [ ] ) ;
319+ /**
320+ * Performs a sort operation in the grid based on the passed expression(s).
321+ */
322+ public sort ( expressions : SortExpression < T > | SortExpression < T > [ ] ) {
323+ this . stateController . sorting . sort ( expressions ) ;
203324 }
204325
326+ /**
327+ * Returns a {@link ColumnConfiguration} for a given column.
328+ */
205329 public getColumn ( id : Keys < T > | number ) {
206330 return typeof id === 'number'
207331 ? this . columns . at ( id )
208332 : this . columns . find ( ( { key } ) => key === id ) ;
209333 }
210334
211- public updateColumn ( key : Keys < T > , config : Partial < ColumnConfig < T > > ) {
335+ /**
336+ * Updates the column configuration of the grid.
337+ */
338+ public updateColumn ( key : Keys < T > , config : Partial < ColumnConfiguration < T > > ) {
212339 // Check and reset data operation states
213340 // TODO: Run `pipeline` updates ?
214341 if ( ! config . sort ) {
0 commit comments