repository·master·Indexed 25 days ago
https://github.com/wa0x6e/cal-heatmapA JavaScript library for creating highly customizable time-series calendar heatmaps to visualize data density over time, similar to GitHub's contribution graph. Version 4.3.0-beta.4 supports animated date navigation, locale and timezone support, a plugin system, and various temporal granularities from minutes to years.
The project uses a custom Jest configuration for end-to-end (E2E) testing. Key settings include using jsdom as the test environment, a ts-jest preset for ESM support, and specific patterns for detecting E2E test files located in the e2e/ directory.
export default {
clearMocks: true,
coverageProvider: 'v8',
globalSetup: './test/e2e/utils/setup.js',
globalTeardown: './test/e2e/utils/teardown.js',
preset: 'ts-jest/presets/default-esm',
roots: [
"./test"
],
testEnvironment: 'jsdom',
testRegex: ['e2e/(.*).test.ts'],
// ... other settings
};The OptionsType object is the primary configuration interface for Cal-Heatmap. You can initialize or update settings using the init() method of the Options class.
Key configuration groups include:
itemSelector: A CSS selector or DOM element where the heatmap will be appended.domain: Settings for the main time units (e.g., weeks, months), including type, gutter, padding, and label options.subDomain: Settings for the individual cells within a domain, including type, width, height, gutter, radius, and label.date: Controls the time range, including start, min, max, highlight (array of Dates), locale, and timezone.data: Configures the data source (source, type), mapping keys (x, y), and aggregation (groupY).scale: Configures color schemes and opacity.theme: Set to 'light' or 'dark'.verticalOrientation: Boolean to switch between horizontal and vertical layouts.When no options are provided, Cal-Heatmap uses the following default values. These constants define the initial behavior for domains, subdomains, animation, and selection:
'hour''minute'10, Height 10, Gutter 2, Radius 0200ms12'#cal-heatmap''light''en'The default color scale configuration used for heatmap intensity is:
'red''YlOrBr''quantize'[0, 100]moduleNameMapper to resolve .js extensions in imports and mocks SCSS files. It also uses ts-jest with useESM: true to transform TypeScript files.CalHeatmap which is the main class used to instantiate heatmaps, and a named export VERSION containing the current library version string.The init(opts?: DeepPartial<OptionsType>) method is used to apply a configuration object to the Options instance. It merges the provided opts with the existing defaults. Note that for arrays, the provided srcValue will overwrite the default rather than merging elements.
When calling init(), the class also automatically runs pre-processors and calculates internal dimensions for labels and scales.
The set(key: string, value: any): boolean method allows you to update a specific configuration property.
isEqual).true if the value was changed, and false if it remained the same or the key does not exist.key, the value is passed through the pre-processor before being set.Cal-Heatmap provides a collection of built-in templates for different time granularities. These templates can be used to define the layout of the heatmap. The available templates are:
minuteTemplate: For minute-level granularity.hourTemplate: For hour-level granularity.dayTemplate: For day-level granularity.xDayTemplate: For multi-day granularity.ghDayTemplate: GitHub-style day granularity.weekTemplate: For week-level granularity.monthTemplate: For month-level granularity.yearTemplate: For year-level granularity.You can define custom rendering logic by creating a Template function. This function receives the DateHelper and OptionsType and returns a TemplateResult.
export type Template = {
(dateHelper: DateHelper, options: OptionsType): TemplateResult;
};
export type TemplateResult = {
name: string;
parent?: string;
allowedDomainType: DomainType[];
rowsCount: (ts: Timestamp) => number;
columnsCount: (ts: Timestamp) => number;
mapping: (startTimestamp: Timestamp, endTimestamp: Timestamp) => SubDomain[];
extractUnit: (ts: Timestamp) => Timestamp;
};SubDomain objects returned by the mapping function define the coordinates and values for cells:
t: Timestampx: numbery: numberv: number | string | null (optional value)The CalHeatmap class is the primary entry point for the library. You can instantiate it using new CalHeatmap() and use its methods to render, navigate, and manipulate the heatmap.
paint(options?: DeepPartial<OptionsType>, plugins?: IPlugin[]): Promise<unknown>: Renders the heatmap with the provided options and optional plugins.next(n?: number): Promise<unknown>: Moves the calendar to the next period.previous(n?: number): Promise<unknown>: Moves the calendar to the previous period.jumpTo(date: Date, reset?: boolean): Promise<unknown>: Jumps the calendar to a specific date.fill(dataSource?: OptionsType['data']['source']): Promise<unknown>: Fills the heatmap with new data.destroy(): Promise<unknown>: Destroys the heatmap instance.addTemplates(templates: Template | Template[]): void: Registers new templates for rendering.on(name: string, fn: () => any): void: Registers an event listener via the internal eventEmitter.dimensions(): Dimensions: Returns the current width and height of the heatmap.