From 3bfc23a55c6af56f00e4c055092cc561f38211ee Mon Sep 17 00:00:00 2001 From: relliv Date: Mon, 4 Nov 2024 17:30:20 +0300 Subject: [PATCH] Add vue documentation --- docs/docs/angular/installation.mdx | 6 +- docs/docs/vue/_category_.json | 8 ++ docs/docs/vue/demo.mdx | 9 ++ docs/docs/vue/installation.mdx | 61 +++++++++++ docs/docs/vue/usage-options.mdx | 22 ++++ docs/docs/vue/usage.mdx | 165 +++++++++++++++++++++++++++++ docs/src/css/custom.css | 9 ++ 7 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 docs/docs/vue/_category_.json create mode 100644 docs/docs/vue/demo.mdx create mode 100644 docs/docs/vue/installation.mdx create mode 100644 docs/docs/vue/usage-options.mdx create mode 100644 docs/docs/vue/usage.mdx diff --git a/docs/docs/angular/installation.mdx b/docs/docs/angular/installation.mdx index 0b2eddf..079d246 100644 --- a/docs/docs/angular/installation.mdx +++ b/docs/docs/angular/installation.mdx @@ -26,17 +26,19 @@ npm i @ngeenx/nx-angular-calendar-heatmap This library requires **[tippy.js](https://atomiks.github.io/tippyjs/)** and **[luxon](https://moment.github.io/luxon/#/)** (*the successor to Moment.js*) as **peer dependencies**. We are using `tippy.js` for the tooltip and `luxon` for date time manipulation. +Also, we need `@ngeenx/nx-calendar-heatmap-utils` for the calendar heatmap utils. + You can install them using the following commands: ```bash -pnpm i tippy.js luxon @ngeenx/nx-calendar-heatmap-utils +pnpm i @ngeenx/nx-calendar-heatmap-utils tippy.js luxon ``` ```bash -npm i tippy.js luxon @ngeenx/nx-calendar-heatmap-utils +npm i @ngeenx/nx-calendar-heatmap-utils tippy.js luxon ``` diff --git a/docs/docs/vue/_category_.json b/docs/docs/vue/_category_.json new file mode 100644 index 0000000..83a4f90 --- /dev/null +++ b/docs/docs/vue/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Vue", + "position": 2, + "link": { + "type": "generated-index", + "description": "Installation and usage of Angular Calendar Heatmap component" + } +} diff --git a/docs/docs/vue/demo.mdx b/docs/docs/vue/demo.mdx new file mode 100644 index 0000000..ca48199 --- /dev/null +++ b/docs/docs/vue/demo.mdx @@ -0,0 +1,9 @@ +--- +sidebar_position: 2 +--- + +# ▶️ Demo + +**[⚡️ Play on StackBlitz](https://stackblitz.com/edit/nx-angular-svg-loaders-demo)** + + diff --git a/docs/docs/vue/installation.mdx b/docs/docs/vue/installation.mdx new file mode 100644 index 0000000..079d246 --- /dev/null +++ b/docs/docs/vue/installation.mdx @@ -0,0 +1,61 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 📦 Installation + +Install the **primary** package using your package manager of choice. + + + + ```bash +pnpm i @ngeenx/nx-angular-calendar-heatmap + ``` + + + ```bash +npm i @ngeenx/nx-angular-calendar-heatmap + ``` + + + +## Peer Dependencies + +This library requires **[tippy.js](https://atomiks.github.io/tippyjs/)** and **[luxon](https://moment.github.io/luxon/#/)** (*the successor to Moment.js*) as **peer dependencies**. We are using `tippy.js` for the tooltip and `luxon` for date time manipulation. + +Also, we need `@ngeenx/nx-calendar-heatmap-utils` for the calendar heatmap utils. + +You can install them using the following commands: + + + + ```bash +pnpm i @ngeenx/nx-calendar-heatmap-utils tippy.js luxon + ``` + + + ```bash +npm i @ngeenx/nx-calendar-heatmap-utils tippy.js luxon + ``` + + + +## Types + +Optionally, you can install the types for `luxon` using the following commands: + + + + ```bash +pnpm i @types/luxon -D + ``` + + + ```bash +npm i @types/luxon -D + ``` + + diff --git a/docs/docs/vue/usage-options.mdx b/docs/docs/vue/usage-options.mdx new file mode 100644 index 0000000..a2c3c9c --- /dev/null +++ b/docs/docs/vue/usage-options.mdx @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +--- + +# 🛠️ Options + +You can customize the Calendar Heatmap by providing the following options: + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `type` | `HeatMapCalendarType` | **must provide with config** | `WEEKLY`\|`MONTHLY`\|`YEARLY` | +| `startDate` | `DateTime` | **must provide with config** | The start date of the calendar. | +| `cellSize` | Number (*as px*) | optional (`15`) | Day cell size (*also you can configure with `overWritedDayStyle` option*) | +| `colors` | `IHeatmapColor[]` | optional | Heatmap colors for each level range. | +| `hideEmptyDays` | `Boolean` | optional (`false`) | Empty days (*only start and end end month*) for filler days. | +| `overWritedDayStyle` | `Object` | optional | Style each day with inline style object. | +| `heatmapLegend` | `IHeatmapLegend` | optional | Configure `display`, `direction` and `tooltipFormatter` of heatmap calendar legend. | +| `locale` | `String` | optional (`"en"`) | Specify the locale for the calendar (*weekday and month names*). | +| `i18n` | `ILocale` | optional | Custom locale for the calendar texts (*min, max, less, more, etc.*). | +| `tippyProps` | `Props` (*from tippy*) | optional | Tippy.js props for the tooltip. | +| `tooltip` | `IHeatmapTooltip` | optional | Configure the tooltip for the heatmap (*unit, display state, date format and custom formatter*). | +| `onClick` | `(day: IHeatmapDay) => void` | optional | Handle click event for each day. | diff --git a/docs/docs/vue/usage.mdx b/docs/docs/vue/usage.mdx new file mode 100644 index 0000000..f23220c --- /dev/null +++ b/docs/docs/vue/usage.mdx @@ -0,0 +1,165 @@ +--- +sidebar_position: 3 +--- + +# 🚀 Usage + +Use the following steps to use the Calendar Heatmap in your Angular project. + +## Import + +Import `NxCalendarHeatmapComponent` component in your Angular module or standalone component. + +```ts title="app.component.ts" +import { Component } from "@angular/core"; +import { CommonModule } from "@angular/common"; +import { RouterModule } from "@angular/router"; + +// highlight-next-line +import { NxCalendarHeatmapComponent } from "@ngeenx/nx-angular-calendar-heatmap"; + +@Component({ + standalone: true, + imports: [ + RouterModule, + CommonModule, + + // ... + + // highlight-next-line + NxCalendarHeatmapComponent + ], + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.scss", +}) +export class AppComponent { + // ... + + // highlight-next-line + public startDate: DateTime = DateTime.now().startOf("year"); + // highlight-next-line + public heatmapData: IHeatmapDay[] = []; + // highlight-next-line + public options: ICalendarHeatmapOptions; + + // ... +} +``` + +```html title="app.component.html" + + +// highlight-next-line + + // highlight-next-line +
+ // highlight-next-line + Learn how we count contributions + // highlight-next-line +
+// highlight-next-line + + + +``` + +## Data Source + +`data` property is an array of `IHeatmapDay` objects. Each object represents a day in the heatmap (*dates must sort in ascending order*). + +:::info[Data Source] + +Data must be provided by the parent component. There is no internal API call to fetch the data or date ordering features. In this case provided data must cover the selected calendar type and day order. + +::: + +```ts title="app.component.ts" +import { Component } from "@angular/core"; +import { CommonModule } from "@angular/common"; +import { RouterModule } from "@angular/router"; + +// highlight-next-line +import { IHeatmapDay, ICalendarHeatmapOptions } from "@ngeenx/nx-angular-calendar-heatmap"; + +@Component({ + standalone: true, + imports: [ + // ... + // highlight-next-line + NxCalendarHeatmapComponent + ], + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.scss", +}) +export class AppComponent { + // ... + + public startDate: DateTime = DateTime.now().startOf("year"); + public heatmapData: IHeatmapDay[] = []; + public options: ICalendarHeatmapOptions; + + // highlight-next-line + public ngOnInit(): void { + // highlight-next-line + this.options = { + // highlight-next-line + type: HeatMapCalendarType.YEARLY, + // highlight-next-line + startDate: this.startDate, + // highlight-next-line + }; + // highlight-next-line + + // highlight-next-line + this.heatmapData = this.generateHeatmapData(this.startDate); + // highlight-next-line + } + + // random data generator for yearly view + private generateHeatmapData(startDate: DateTime): IHeatmapDay[] { + // get end of the year + const endDate = startDate.endOf("year"); + // get days between start and end date + const daysBetween = Math.floor(endDate.diff(startDate, "days").days); + const heatmap: IHeatmapDay[] = []; + + let currentDate = startDate; + + // generate random data for each day + for (let i = 0; i <= daysBetween; i++) { + const value = Math.floor(Math.random() * 101); + + const day: IHeatmapDay = { + date: currentDate, + count: value, + data: { + index: i, + value, + }, + }; + + heatmap.push(day); + + // text day + currentDate = currentDate.plus({ days: 1 }); + } + + // then return the generated data to bind to the heatmap component + return heatmap; + } +} +``` + +:::note + +`generateHeatmapData` is a helper function to generate random data for the heatmap. You can replace this function with your own data source. +::: + diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 09b4816..dce4aac 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -37,3 +37,12 @@ backgroundcolor: #f4f4f48a; padding: 10px; } + +.embed-iframe { + width: 100%; + height: 500px; + border: 0; + borderRadius: 4px; + border: 1px solid rgba(0,0,0,.125); + overflow: hidde; +}