@memberjunction/ng-timeline 2.122.0 → 2.122.2

package/dist/lib/timeline-group.d.ts

@@ -0,0 +1,387 @@
+/**
+ * @fileoverview TimelineGroup class for configuring timeline data sources.
+ *
+ * The TimelineGroup class defines how data is loaded and displayed in the timeline.
+ * It supports both MemberJunction BaseEntity objects and plain JavaScript objects,
+ * making it usable in any Angular application.
+ *
+ * @module @memberjunction/ng-timeline/timeline-group
+ */
+import { TimelineCardConfig, TimelineEventConfig } from './types';
+/**
+ * Extracts a field value from a record, supporting both BaseEntity and plain objects.
+ *
+ * For BaseEntity objects (detected by presence of `.Get()` method), uses the `.Get()` method.
+ * For plain JavaScript objects, uses standard bracket notation.
+ *
+ * @param record - The source record (BaseEntity or plain object)
+ * @param fieldName - The name of the field to extract
+ * @returns The field value, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * // Works with BaseEntity
+ * const entity = await md.GetEntityObject<TaskEntity>('Tasks');
+ * const name = getFieldValue(entity, 'Name');  // Uses entity.Get('Name')
+ *
+ * // Works with plain objects
+ * const obj = { name: 'My Task', status: 'Open' };
+ * const name = getFieldValue(obj, 'name');  // Uses obj['name']
+ * ```
+ */
+export declare function getFieldValue(record: any, fieldName: string): unknown;
+/**
+ * Extracts an ID from a record, trying common ID field names.
+ *
+ * @param record - The source record
+ * @param idFieldName - Optional explicit ID field name
+ * @returns The record ID as a string, or a generated fallback ID
+ */
+export declare function getRecordId(record: any, idFieldName?: string): string;
+/**
+ * Configures a data source for the timeline component.
+ *
+ * TimelineGroup defines how records are loaded, which fields to display,
+ * and how they should be styled. Multiple groups can be used to display
+ * different types of events on the same timeline.
+ *
+ * @typeParam T - The type of the source records. Defaults to `any` for maximum
+ *                flexibility. MemberJunction users can specify BaseEntity subclasses
+ *                for full type safety.
+ *
+ * @example Basic usage with plain objects
+ * ```typescript
+ * interface MyEvent {
+ *   id: string;
+ *   title: string;
+ *   eventDate: Date;
+ *   description: string;
+ * }
+ *
+ * const group = new TimelineGroup<MyEvent>();
+ * group.DataSourceType = 'array';
+ * group.EntityObjects = myEventsArray;
+ * group.TitleFieldName = 'title';
+ * group.DateFieldName = 'eventDate';
+ * group.DescriptionFieldName = 'description';
+ * ```
+ *
+ * @example MemberJunction usage with BaseEntity
+ * ```typescript
+ * import { TaskEntity } from '@memberjunction/core-entities';
+ *
+ * const group = new TimelineGroup<TaskEntity>();
+ * group.EntityName = 'Tasks';
+ * group.DataSourceType = 'entity';
+ * group.Filter = "Status = 'Open'";
+ * group.TitleFieldName = 'Name';
+ * group.DateFieldName = 'DueDate';
+ * ```
+ *
+ * @example With full configuration
+ * ```typescript
+ * const group = new TimelineGroup<TaskEntity>();
+ * group.EntityName = 'Tasks';
+ * group.TitleFieldName = 'Name';
+ * group.DateFieldName = 'CompletedAt';
+ * group.SubtitleFieldName = 'Category';
+ * group.DescriptionFieldName = 'Description';
+ * group.DisplayIcon = 'fa-solid fa-check-circle';
+ * group.DisplayColor = '#4caf50';
+ * group.GroupLabel = 'Completed Tasks';
+ *
+ * group.CardConfig = {
+ *   collapsible: true,
+ *   defaultExpanded: false,
+ *   summaryFields: [
+ *     { fieldName: 'AssignedTo', label: 'Assignee', icon: 'fa-solid fa-user' },
+ *     { fieldName: 'Priority', icon: 'fa-solid fa-flag' }
+ *   ],
+ *   actions: [
+ *     { id: 'view', label: 'View', variant: 'primary' },
+ *     { id: 'edit', label: 'Edit', variant: 'secondary' }
+ *   ]
+ * };
+ *
+ * group.EventConfigFunction = (task) => ({
+ *   icon: task.Priority === 'High' ? 'fa-solid fa-exclamation' : undefined,
+ *   color: task.Status === 'Overdue' ? '#f44336' : undefined
+ * });
+ * ```
+ */
+export declare class TimelineGroup<T = any> {
+    /**
+     * The MemberJunction entity name for this group.
+     * Required when `DataSourceType` is `'entity'`.
+     *
+     * @example 'Tasks', 'AI Agents', 'Users'
+     */
+    EntityName?: string;
+    /**
+     * How data is provided to the timeline.
+     * - `'array'`: Data is provided via the `EntityObjects` array (works with any object type)
+     * - `'entity'`: Data is loaded using MemberJunction's RunView (requires MJ core)
+     *
+     * @default 'entity'
+     */
+    DataSourceType: 'array' | 'entity';
+    /**
+     * SQL WHERE clause filter for entity queries.
+     * Only used when `DataSourceType` is `'entity'`.
+     *
+     * @example "Status = 'Open' AND Priority = 'High'"
+     */
+    Filter?: string;
+    /**
+     * Pre-loaded data array.
+     * Used when `DataSourceType` is `'array'`, or populated after loading when using `'entity'`.
+     */
+    EntityObjects: T[];
+    /**
+     * SQL ORDER BY clause for entity queries.
+     * Only used when `DataSourceType` is `'entity'`.
+     *
+     * @example 'CreatedAt DESC', 'Priority ASC, DueDate DESC'
+     */
+    OrderBy?: string;
+    /**
+     * Maximum number of records to load per batch.
+     * Used for virtual scrolling.
+     *
+     * @default undefined (uses component's virtualScroll.batchSize)
+     */
+    MaxRecords?: number;
+    /**
+     * Field name for the event title.
+     * This is the primary text displayed on each timeline card.
+     *
+     * @required
+     */
+    TitleFieldName: string;
+    /**
+     * Field name for the event date.
+     * Used for chronological ordering and date display.
+     *
+     * @required
+     */
+    DateFieldName: string;
+    /**
+     * Field name for the subtitle.
+     * Displayed below the title in smaller text.
+     */
+    SubtitleFieldName?: string;
+    /**
+     * Field name for the description/body text.
+     * Displayed in the card body when expanded.
+     */
+    DescriptionFieldName?: string;
+    /**
+     * Field name containing an image URL.
+     * When set, displays an image in the card.
+     */
+    ImageFieldName?: string;
+    /**
+     * Field name for the unique record ID.
+     * Defaults to 'ID' or 'id' if not specified.
+     */
+    IdFieldName?: string;
+    /**
+     * Icon display mode.
+     * - `'standard'`: Uses a default icon based on the group index
+     * - `'custom'`: Uses the icon specified in `DisplayIcon`
+     *
+     * @default 'standard'
+     */
+    DisplayIconMode: 'standard' | 'custom';
+    /**
+     * Custom icon class (Font Awesome).
+     * Only used when `DisplayIconMode` is `'custom'`.
+     *
+     * @example 'fa-solid fa-check', 'fa-regular fa-calendar'
+     */
+    DisplayIcon?: string;
+    /**
+     * Color assignment mode.
+     * - `'auto'`: System assigns colors based on group index
+     * - `'manual'`: Uses the color specified in `DisplayColor`
+     *
+     * @default 'auto'
+     */
+    DisplayColorMode: 'auto' | 'manual';
+    /**
+     * Custom color for this group's markers and accents.
+     * Only used when `DisplayColorMode` is `'manual'`.
+     * Any valid CSS color value.
+     *
+     * @example '#4caf50', 'rgb(66, 135, 245)', 'var(--primary-color)'
+     */
+    DisplayColor?: string;
+    /**
+     * Human-readable label for this group.
+     * Used in legends, headers, or when distinguishing multiple groups.
+     *
+     * @example 'Completed Tasks', 'System Events', 'User Activities'
+     */
+    GroupLabel?: string;
+    /**
+     * Card display configuration for this group.
+     * Defines how event cards are rendered.
+     * If not set, uses the component's `defaultCardConfig`.
+     */
+    CardConfig?: TimelineCardConfig;
+    /**
+     * Custom function to generate the event summary/description.
+     * Takes precedence over `DescriptionFieldName`.
+     *
+     * @param record - The source record
+     * @returns HTML string or plain text to display
+     *
+     * @example
+     * ```typescript
+     * group.SummaryFunction = (task) => {
+     *   return `<strong>${task.Status}</strong>: ${task.Description}`;
+     * };
+     * ```
+     */
+    SummaryFunction?: (record: T) => string;
+    /**
+     * Custom function to configure individual events.
+     * Allows per-event customization of icons, colors, and actions.
+     *
+     * @param record - The source record
+     * @returns Configuration overrides for this event
+     *
+     * @example
+     * ```typescript
+     * group.EventConfigFunction = (task) => ({
+     *   icon: task.Priority === 'High' ? 'fa-solid fa-exclamation' : undefined,
+     *   color: task.IsOverdue ? '#f44336' : undefined,
+     *   actions: task.CanEdit ? [{ id: 'edit', label: 'Edit' }] : []
+     * });
+     * ```
+     */
+    EventConfigFunction?: (record: T) => TimelineEventConfig;
+    /**
+     * Gets the effective card configuration, merging with defaults.
+     *
+     * @returns The merged card configuration
+     */
+    getEffectiveCardConfig(): TimelineCardConfig;
+    /**
+     * Extracts a field value from a record in this group.
+     *
+     * @param record - The source record
+     * @param fieldName - The field name to extract
+     * @returns The field value
+     */
+    getValue(record: T, fieldName: string): unknown;
+    /**
+     * Gets the ID of a record in this group.
+     *
+     * @param record - The source record
+     * @returns The record ID
+     */
+    getId(record: T): string;
+    /**
+     * Gets the title from a record.
+     *
+     * @param record - The source record
+     * @returns The title string
+     */
+    getTitle(record: T): string;
+    /**
+     * Gets the date from a record.
+     *
+     * @param record - The source record
+     * @returns The date object
+     */
+    getDate(record: T): Date;
+    /**
+     * Gets the subtitle from a record.
+     *
+     * @param record - The source record
+     * @returns The subtitle string, or undefined
+     */
+    getSubtitle(record: T): string | undefined;
+    /**
+     * Gets the description from a record.
+     *
+     * @param record - The source record
+     * @returns The description string, or undefined
+     */
+    getDescription(record: T): string | undefined;
+    /**
+     * Gets the image URL from a record.
+     *
+     * @param record - The source record
+     * @returns The image URL, or undefined
+     */
+    getImageUrl(record: T): string | undefined;
+    /**
+     * Gets the event configuration for a specific record.
+     *
+     * @param record - The source record
+     * @returns The event configuration (from EventConfigFunction or defaults)
+     */
+    getEventConfig(record: T): TimelineEventConfig;
+    /**
+     * Creates a TimelineGroup from MemberJunction RunViewParams.
+     *
+     * This is a convenience method for MemberJunction applications.
+     * It loads data immediately and returns a configured group.
+     *
+     * **Note**: This method requires `@memberjunction/core` to be available.
+     * It will throw an error if used in non-MJ applications.
+     *
+     * @param params - RunView parameters for loading data
+     * @returns A configured TimelineGroup with loaded data
+     *
+     * @example
+     * ```typescript
+     * const group = await TimelineGroup.FromView<TaskEntity>({
+     *   EntityName: 'Tasks',
+     *   ExtraFilter: "Status = 'Open'",
+     *   OrderBy: 'DueDate DESC'
+     * });
+     * group.TitleFieldName = 'Name';
+     * group.DateFieldName = 'DueDate';
+     * ```
+     */
+    static FromView<T = any>(params: {
+        EntityName?: string;
+        ExtraFilter?: string;
+        OrderBy?: string;
+        MaxRows?: number;
+        [key: string]: unknown;
+    }): Promise<TimelineGroup<T>>;
+    /**
+     * Creates a TimelineGroup from a plain array of objects.
+     *
+     * This is a convenience method that sets up the group for array-based data.
+     *
+     * @param data - Array of objects to display
+     * @param config - Configuration for field mappings
+     * @returns A configured TimelineGroup
+     *
+     * @example
+     * ```typescript
+     * const group = TimelineGroup.FromArray(myEvents, {
+     *   titleField: 'name',
+     *   dateField: 'eventDate',
+     *   descriptionField: 'details'
+     * });
+     * ```
+     */
+    static FromArray<T = any>(data: T[], config: {
+        titleField: string;
+        dateField: string;
+        subtitleField?: string;
+        descriptionField?: string;
+        imageField?: string;
+        idField?: string;
+        groupLabel?: string;
+        icon?: string;
+        color?: string;
+    }): TimelineGroup<T>;
+}
+//# sourceMappingURL=timeline-group.d.ts.map

package/dist/lib/timeline-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-group.d.ts","sourceRoot":"","sources":["../../src/lib/timeline-group.ts"],"names":[],"mappings":"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"}