ng-fusion-ui
Version:
Angular data table library!
97 lines (96 loc) • 4.13 kB
TypeScript
type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date;
export type FieldPath<T> = {
[K in keyof T & string]: T[K] extends Primitive | Array<any> ? K : `${K}.${FieldPath<T[K]>}`;
}[keyof T & string];
/**
* Creates a row class resolver that maps a row's field value to a CSS class name.
*
* Use this helper to easily produce a function you can pass to the table's
* `rowClass` input. The returned resolver reads the specified `field` from the
* row object, stringifies it, looks it up in `map` and returns the matching
* class name or the provided `fallback`.
*
* Notes:
* - The function performs a direct property access: `(row as any)[field]`.
* - Map keys are matched against the stringified field value (numbers/booleans
* are converted to strings).
* - If the field is nested (e.g. `user.name`) use `rowClassByPath` instead.
* - CSS classes returned by the resolver must be defined in the consumer
* application's styles — the library does not inject those rules.
*
* Example:
* ```ts
* // rows: Array<{ sex: 'male'|'female' }>
* rowClass = rowClassByField('sex', {
* female: 'row-female',
* male: 'row-male'
* }, '');
* ```
*
* @param field Property name on the row objects to check
* @param map Mapping from stringified field values to CSS class names
* @param fallback Optional fallback class when no mapping matches (default: '')
* @returns A function `(row: T) => string` that resolves the class name
*/
export declare function rowClassByField<T extends object>(field: keyof T & string, map: Record<string, string>, fallback?: string): (row: T) => string;
/**
* Creates a row class resolver that reads a nested field (dot-path) from a row
* object and maps its stringified value to a CSS class name.
*
* This helper is useful when the value you want to base row styling on lives
* on a nested property (for example `user.status` or `address.country.code`).
* The `path` supports simple dot-notation and is resolved with a safe reduce
* (it will tolerate missing intermediate objects).
*
* Behavior notes:
* - The resolved field value is converted to a string and matched against the
* provided `map` keys.
* - If no mapping matches, the `fallback` value is returned (defaults to `''`).
* - The returned CSS class must be defined by the consumer application — the
* library does not provide styling for custom class names.
*
* Example (rows where `sex` is a nested property):
* ```ts
* // rows: Array<{ user: { sex: 'male'|'female' } }>
* rowClass = rowClassByPath('user.sex', {
* female: 'row-female',
* male: 'row-male'
* }, '');
* ```
*
* @param path Dot-separated path to the property on the row objects
* @param map Mapping from stringified values to CSS class names
* @param fallback Optional fallback class when no mapping matches (default: '')
* @returns A function `(row: T) => string` that resolves the class name
*/
export declare function rowClassByPath<T extends object>(path: FieldPath<T>, map: Record<string, string>, fallback?: string): (row: T) => string;
/**
* Creates a strongly typed field path factory for a specific row type.
*
* This helper is used to create type-safe string paths that reference
* properties of a data model (including nested properties), while
* keeping the runtime value a simple string.
*
* It improves developer experience by:
* - validating field paths at compile time
* - preventing typos in nested property paths
* - keeping IDE autocompletion and hover information clean
*
* ## Usage
* ```ts
* const fieldOf = fieldPathOf<Person>();
*
* const name = fieldOf('name'); // ✅ valid
* const city = fieldOf('address.city'); // ✅ valid
* const wrong = fieldOf('address.cito'); // ❌ compile-time error
* ```
*
* The returned value is a string at runtime and can be safely used for:
* - column definitions
* - sorting and filtering
* - backend queries
*
* @typeParam T The row data type used to validate field paths.
*/
export declare function fieldPathOf<T>(): <P extends string & FieldPath<T>>(path: P) => P;
export {};