@htlkg/components 0.0.1

package/src/data/Chart.md

@@ -0,0 +1,525 @@
+# Chart Component
+
+A powerful charting component for data visualization supporting multiple chart types (line, area, bar, scatter). Built on top of `uiChart` from `@hotelinking/ui` which uses ApexCharts internally.
+
+## Features
+
+- **Multiple chart types**: Line, area, bar, and scatter charts
+- **Interactive**: Hover tooltips, data point selection, zoom capabilities
+- **Time range selector**: Built-in time range buttons (24h, 7d, 1m, 3m, all)
+- **Date range support**: Custom date range selection
+- **Loading state**: Skeleton loader while data is fetching
+- **Empty state**: Displays message when no data is available
+- **Responsive**: Adapts to container size
+- **Horizontal/Vertical**: Support for horizontal bar charts
+- **Stacked charts**: Stack multiple series
+- **Annotations**: Add reference lines and labels
+- **NPS support**: Special mode for Net Promoter Score charts
+- **Customizable**: Full control over ApexCharts options
+- **Maximize**: Full-screen chart view
+- **Exposed methods**: Programmatic control via `refresh()`, `getChartId()`
+
+## Import
+
+```typescript
+import { Chart } from '@htlkg/components';
+import type { ChartSeries, ChartOptions, ChartDateRange, ChartAnnotation } from '@htlkg/components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | **required** | Unique identifier for the chart |
+| `title` | `string` | **required** | Chart title displayed at the top |
+| `series` | `ChartSeries[]` | **required** | Data series to display |
+| `type` | `'area' \| 'line' \| 'bar' \| 'scatter'` | `'line'` | Chart type |
+| `options` | `ChartOptions` | `undefined` | ApexCharts configuration options |
+| `loading` | `boolean` | `false` | Shows skeleton loader when true |
+| `empty` | `boolean` | `false` | Shows empty state when true |
+| `range` | `'24h' \| '7d' \| '1m' \| '3m' \| 'all'` | `undefined` | Selected time range |
+| `horizontal` | `boolean` | `false` | Horizontal orientation for bar charts |
+| `stacked` | `boolean` | `false` | Stack multiple series |
+| `height` | `number` | `undefined` | Custom chart height in pixels |
+| `labels` | `string[]` | `undefined` | X-axis labels |
+| `dates` | `ChartDateRange` | `undefined` | Date range for the chart |
+| `isNps` | `boolean` | `false` | Enable NPS (Net Promoter Score) mode |
+| `npsLiterals` | `NpsLiterals` | `undefined` | Labels for NPS chart sections |
+| `annotations` | `ChartAnnotation` | `undefined` | Reference lines and labels |
+
+### Type Definitions
+
+```typescript
+interface ChartSeries {
+  name: string;
+  type?: 'area' | 'line' | 'bar' | 'scatter';
+  data: number[];
+}
+
+interface ChartOptions {
+  xaxis?: {
+    tickAmount?: number;
+    decimalsInFloat?: number;
+    hideOverlappingLabels?: boolean;
+    type?: string;
+    max?: number;
+    categories?: string[];
+  };
+  tooltip?: {
+    intersect?: boolean;
+  };
+  [key: string]: any; // Supports all ApexCharts options
+}
+
+interface ChartDateRange {
+  from: Date | string;
+  to: Date | string;
+}
+
+interface ChartAnnotation {
+  text: string;
+  high: number;
+}
+
+interface NpsLiterals {
+  unhappy: string;
+  neutral: string;
+  happy: string;
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `range-selected` | `{ range: ChartDateRange; chartId: string }` | Emitted when time range is selected |
+| `chart-updated` | - | Emitted when chart data is updated |
+| `data-point-selection` | `any` | Emitted when user clicks on a data point |
+| `maximize` | `string` (chartId) | Emitted when maximize button is clicked |
+
+## Exposed Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `refresh()` | - | `void` | Triggers chart refresh |
+| `getChartId()` | - | `string` | Returns the chart ID |
+
+## Usage Examples
+
+### Basic Line Chart
+
+```vue
+<template>
+  <Chart
+    id="sales-chart"
+    title="Monthly Sales"
+    type="line"
+    :series="salesData"
+    :options="chartOptions"
+    :loading="loading"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+import type { ChartSeries, ChartOptions } from '@htlkg/components';
+
+const loading = ref(false);
+
+const salesData: ChartSeries[] = [
+  {
+    name: 'Revenue',
+    data: [30, 40, 45, 50, 49, 60, 70, 91, 125, 140, 165, 180]
+  }
+];
+
+const chartOptions: ChartOptions = {
+  xaxis: {
+    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 
+                 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+  },
+  tooltip: {
+    intersect: false
+  }
+};
+</script>
+```
+
+### Area Chart with Multiple Series
+
+```vue
+<template>
+  <Chart
+    id="traffic-chart"
+    title="Website Traffic"
+    type="area"
+    :series="trafficData"
+    :options="chartOptions"
+    :loading="loading"
+    @data-point-selection="handlePointClick"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+import type { ChartSeries } from '@htlkg/components';
+
+const loading = ref(false);
+
+const trafficData: ChartSeries[] = [
+  {
+    name: 'Visitors',
+    data: [30, 40, 45, 50, 49, 60, 70, 91, 125]
+  },
+  {
+    name: 'Page Views',
+    data: [50, 60, 70, 80, 75, 90, 100, 130, 180]
+  }
+];
+
+const chartOptions = {
+  xaxis: {
+    categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun', 'Mon', 'Tue']
+  }
+};
+
+function handlePointClick(data: any) {
+  console.log('Clicked data point:', data);
+}
+</script>
+```
+
+### Horizontal Bar Chart
+
+```vue
+<template>
+  <Chart
+    id="locations-chart"
+    title="Top Locations"
+    type="bar"
+    :series="locationsData"
+    :options="chartOptions"
+    :loading="loading"
+    horizontal
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+
+const loading = ref(false);
+
+const locationsData = [
+  {
+    name: 'Sessions',
+    data: [400, 300, 250, 200, 150]
+  }
+];
+
+const chartOptions = {
+  xaxis: {
+    categories: ['New York', 'London', 'Tokyo', 'Paris', 'Berlin']
+  }
+};
+</script>
+```
+
+### Stacked Bar Chart
+
+```vue
+<template>
+  <Chart
+    id="revenue-chart"
+    title="Revenue by Product"
+    type="bar"
+    :series="revenueData"
+    :options="chartOptions"
+    :loading="loading"
+    stacked
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+
+const loading = ref(false);
+
+const revenueData = [
+  {
+    name: 'Product A',
+    data: [44, 55, 41, 67, 22, 43]
+  },
+  {
+    name: 'Product B',
+    data: [13, 23, 20, 8, 13, 27]
+  },
+  {
+    name: 'Product C',
+    data: [11, 17, 15, 15, 21, 14]
+  }
+];
+
+const chartOptions = {
+  xaxis: {
+    categories: ['Q1', 'Q2', 'Q3', 'Q4', 'Q5', 'Q6']
+  }
+};
+</script>
+```
+
+### Chart with Time Range Selector
+
+```vue
+<template>
+  <Chart
+    id="analytics-chart"
+    title="Analytics Overview"
+    type="area"
+    :series="analyticsData"
+    :options="chartOptions"
+    :loading="loading"
+    :range="selectedRange"
+    @range-selected="handleRangeChange"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+import type { ChartDateRange } from '@htlkg/components';
+
+const loading = ref(false);
+const selectedRange = ref<'24h' | '7d' | '1m' | '3m' | 'all'>('7d');
+
+const analyticsData = [
+  {
+    name: 'Users',
+    data: [30, 40, 45, 50, 49, 60, 70]
+  }
+];
+
+const chartOptions = {
+  xaxis: {
+    categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+  }
+};
+
+function handleRangeChange(data: { range: ChartDateRange; chartId: string }) {
+  console.log('Range changed:', data.range);
+  // Fetch new data for the selected range
+  loading.value = true;
+  // await fetchData(data.range.from, data.range.to);
+  loading.value = false;
+}
+</script>
+```
+
+### Chart with Annotations
+
+```vue
+<template>
+  <Chart
+    id="performance-chart"
+    title="Performance Metrics"
+    type="line"
+    :series="performanceData"
+    :options="chartOptions"
+    :annotations="annotation"
+    :loading="loading"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+import type { ChartAnnotation } from '@htlkg/components';
+
+const loading = ref(false);
+
+const performanceData = [
+  {
+    name: 'Response Time',
+    data: [120, 150, 170, 140, 160, 180, 200, 190]
+  }
+];
+
+const chartOptions = {
+  xaxis: {
+    categories: ['00:00', '03:00', '06:00', '09:00', '12:00', '15:00', '18:00', '21:00']
+  }
+};
+
+const annotation: ChartAnnotation = {
+  text: 'Target: 150ms',
+  high: 150
+};
+</script>
+```
+
+### Empty State
+
+```vue
+<template>
+  <Chart
+    id="empty-chart"
+    title="No Data Available"
+    type="line"
+    :series="[]"
+    :loading="false"
+    :empty="true"
+  />
+</template>
+
+<script setup lang="ts">
+import { Chart } from '@htlkg/components';
+</script>
+```
+
+### Loading State
+
+```vue
+<template>
+  <Chart
+    id="loading-chart"
+    title="Loading Data..."
+    type="area"
+    :series="chartData"
+    :loading="isLoading"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { Chart } from '@htlkg/components';
+
+const isLoading = ref(true);
+const chartData = ref([]);
+
+onMounted(async () => {
+  // Simulate data loading
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  chartData.value = [
+    {
+      name: 'Data',
+      data: [10, 20, 30, 40, 50]
+    }
+  ];
+  isLoading.value = false;
+});
+</script>
+```
+
+### Programmatic Control
+
+```vue
+<template>
+  <div>
+    <button @click="refreshChart">Refresh Chart</button>
+    <Chart
+      ref="chartRef"
+      id="controlled-chart"
+      title="Controlled Chart"
+      type="line"
+      :series="chartData"
+      :loading="loading"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Chart } from '@htlkg/components';
+
+const chartRef = ref<InstanceType<typeof Chart>>();
+const loading = ref(false);
+const chartData = ref([
+  {
+    name: 'Series 1',
+    data: [10, 20, 30, 40, 50]
+  }
+]);
+
+function refreshChart() {
+  loading.value = true;
+  // Fetch new data
+  setTimeout(() => {
+    chartData.value = [
+      {
+        name: 'Series 1',
+        data: [15, 25, 35, 45, 55]
+      }
+    ];
+    chartRef.value?.refresh();
+    loading.value = false;
+  }, 1000);
+}
+</script>
+```
+
+## TypeScript Support
+
+The component is fully typed with TypeScript:
+
+```typescript
+import { Chart } from '@htlkg/components';
+import type { ChartSeries, ChartOptions, ChartDateRange } from '@htlkg/components';
+
+// Type-safe series
+const series: ChartSeries[] = [
+  {
+    name: 'Revenue',
+    type: 'area',
+    data: [100, 200, 300]
+  }
+];
+
+// Type-safe options
+const options: ChartOptions = {
+  xaxis: {
+    categories: ['Jan', 'Feb', 'Mar'],
+    tickAmount: 3
+  }
+};
+
+// Type-safe ref
+const chartRef = ref<InstanceType<typeof Chart>>();
+chartRef.value?.refresh();
+```
+
+## Best Practices
+
+1. **Provide meaningful titles**: Clear chart titles help users understand the data
+2. **Use appropriate chart types**: Line for trends, bar for comparisons, area for cumulative data
+3. **Limit data points**: Too many points can make charts hard to read
+4. **Use consistent colors**: Maintain color consistency across related charts
+5. **Add tooltips**: Enable tooltips for detailed information on hover
+6. **Handle empty states**: Always provide feedback when no data is available
+7. **Show loading states**: Use loading prop while fetching data
+8. **Responsive design**: Charts should adapt to container size
+9. **Accessibility**: Provide alternative text descriptions for screen readers
+10. **Performance**: For large datasets, consider data aggregation or pagination
+
+## Accessibility
+
+- Chart title is properly labeled
+- Interactive elements are keyboard accessible
+- Color is not the only means of conveying information
+- Consider providing data tables as alternatives for screen readers
+
+## Demo
+
+See the component in action at `/demo/components/chart`
+
+## Related Components
+
+- [DateRange](../forms/DateRange.md) - Often used to filter chart data
+- [Table](./Table.md) - Complementary data visualization
+- [DataList](./DataList.md) - Alternative list-based data display
+
+## ApexCharts Documentation
+
+For advanced customization, refer to the [ApexCharts documentation](https://apexcharts.com/docs/).

package/src/data/Chart.vue

@@ -0,0 +1,133 @@
+<template>
+  <uiChart
+    :id="id"
+    :title="title"
+    :type="type"
+    :series="series"
+    :options="options"
+    :loading="loading"
+    :empty="empty"
+    :range="range"
+    :horizontal="horizontal"
+    :stacked="stacked"
+    :height="height"
+    :labels="labels"
+    :dates="dates"
+    :isNps="isNps"
+    :npsLiterals="npsLiterals"
+    :annotations="annotations"
+    @selectedRange="handleRangeSelected"
+    @chartUpdated="handleChartUpdated"
+    @dataPointSelection="handleDataPointSelection"
+    @maximizeChart="handleMaximizeChart"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { uiChart } from '@hotelinking/ui';
+
+export interface ChartSeries {
+  name: string;
+  type?: 'area' | 'line' | 'bar' | 'scatter';
+  data: number[];
+}
+
+export interface ChartOptions {
+  xaxis?: {
+    tickAmount?: number;
+    decimalsInFloat?: number;
+    hideOverlappingLabels?: boolean;
+    type?: string;
+    max?: number;
+    categories?: string[];
+  };
+  tooltip?: {
+    intersect?: boolean;
+  };
+  [key: string]: any;
+}
+
+export interface ChartAnnotation {
+  text: string;
+  high: number;
+}
+
+export interface ChartDateRange {
+  from: Date | string;
+  to: Date | string;
+}
+
+export interface NpsLiterals {
+  unhappy: string;
+  neutral: string;
+  happy: string;
+}
+
+interface Props {
+  id: string;
+  title: string;
+  series: ChartSeries[];
+  type?: 'area' | 'line' | 'bar' | 'scatter';
+  options?: ChartOptions;
+  loading?: boolean;
+  empty?: boolean;
+  range?: '24h' | '7d' | '1m' | '3m' | 'all';
+  horizontal?: boolean;
+  stacked?: boolean;
+  height?: number;
+  labels?: string[];
+  dates?: ChartDateRange;
+  isNps?: boolean;
+  npsLiterals?: NpsLiterals;
+  annotations?: ChartAnnotation;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  type: 'line',
+  loading: false,
+  empty: false,
+  horizontal: false,
+  stacked: false,
+  isNps: false
+});
+
+const emit = defineEmits<{
+  'range-selected': [data: { range: ChartDateRange; chartId: string }];
+  'chart-updated': [];
+  'data-point-selection': [data: any];
+  'maximize': [chartId: string];
+}>();
+
+// Handle events from uiChart
+function handleRangeSelected(data: { range: ChartDateRange; chartId: string }) {
+  emit('range-selected', data);
+}
+
+function handleChartUpdated() {
+  emit('chart-updated');
+}
+
+function handleDataPointSelection(data: any) {
+  emit('data-point-selection', data);
+}
+
+function handleMaximizeChart(chartId: string) {
+  emit('maximize', chartId);
+}
+
+// Exposed methods
+function refresh() {
+  // Trigger chart refresh by emitting chart-updated
+  emit('chart-updated');
+}
+
+function getChartId() {
+  return props.id;
+}
+
+defineExpose({
+  refresh,
+  getChartId
+});
+</script>