### Install Project Dependencies

Source: https://github.com/graphieros/vue-data-ui/blob/master/manual-testing/README.md

Run this command to install all necessary project dependencies.

```sh
npm install
```

--------------------------------

### Start Development Server

Source: https://github.com/graphieros/vue-data-ui/wiki/Contributing-to-Vue-Data-UI

Start the development server and add the local package for testing.

```bash
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/graphieros/vue-data-ui/wiki/Contributing-to-Vue-Data-UI

Install project dependencies using npm.

```bash
npm i
```

--------------------------------

### Install vue-data-ui-cli

Source: https://github.com/graphieros/vue-data-ui/blob/master/llms.txt

Install the global command-line interface tool for VueDataUI chart generation.

```bash
npm install -g vue-data-ui-cli
```

--------------------------------

### Install vue-data-ui with npm

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Use this command to install the vue-data-ui package. This is the first step before importing components.

```bash
npm i vue-data-ui
```

--------------------------------

### Install Vue Data UI and Dependencies

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Install the main library and the optional jspdf for PDF export using npm.

```bash
npm install vue-data-ui
npm install jspdf  # Optional, required for PDF export
```

--------------------------------

### Get Theme Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Load a predefined theme configuration, for example, the 'dark' theme.

```javascript
getThemeConfig('dark')
```

--------------------------------

### Basic XY Chart Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/llms.txt

This example demonstrates how to set up a basic XY chart using the VueUiXy component. It includes a reactive dataset and minimal configuration for a line chart.

```vue
<template>
  <VueUiXy :dataset="dataset" :config="config" />
</template>

<script setup>
import { ref } from 'vue';
import { VueUiXy } from 'vue-data-ui';  // import the XY chart component

// Reactive dataset: array of points with minimal required attributes
const dataset = ref([
    { name: 'Serie A', series: [1, 2, 3, 5], type: 'line' },
    { name: 'Serie B', series: [13, 21, 3, 2], type: 'bar' },
    { name: 'Serie C', series: [8, 2, 3, 6], type: 'plot' },
]);

// Minimal config for the line chart (optional). The TS type for the config is VueUiXyConfig
const config = ref({
    chart: {
        fontFamily: "inherit",
        backgroundColor: "#FFFFFF",
        color: "#1A1A1A",
        grid: {
            showHorizontalLines: false,
            showVerticalLines: false,
            labels: {
                show: true, // shows datapoint labels if the 
                color: "#1A1A1A",
                xAxisLabels: {
                    values: ['01-01-2026', '02-01-2026', '03-01-2026', '04-01-2026'], // The values displayed on the x axis (time labels)
                    rotation: 0, // to rotate the x axis labels
                }
            }
        },
        title: {
            text: 'Title',
            color: '#1A1A1A'
        },
        bar: {      // Specific config for bar types
            labels: {
                show: true,
            }
        },
        line: {     // Specific config for line types
            labels: {
                show: true
            }
        },
        plot: {     // Specific config for plot types
            labels: {
                show: true
            }
        },
        tooltip: {
            show: true,
            customFormat: null, // Provide a custom html content with a callback, for example: ({ seriesIndex, datapoint, series, config, bars, lines, plots }) => { return `Your content` }
        }
    }
});
</script>
```

--------------------------------

### Example: Custom Tooltip Content

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Provides an example of implementing the `customFormat` option to render a custom HTML structure for tooltips, displaying series name and datapoint value.

```javascript
const config = ref({
  tooltip: {
    customFormat: ({ seriesIndex, datapoint, series, config }) => {
      return `<div class="custom-tooltip">
        <strong>${series.name}</strong>
        <p>Value: ${datapoint.value}</p>
      </div>`;
    }
  }
});
```

--------------------------------

### VueDataUi Usage Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Demonstrates how to use the VueDataUi component to render a specific chart type with provided dataset and configuration.

```html
<VueDataUi
  component="VueUiXy"
  :dataset="dataset"
  :config="config"
/>
```

--------------------------------

### Install Vue Data UI

Source: https://github.com/graphieros/vue-data-ui/blob/master/llms.txt

Install the vue-data-ui library using npm. This is the first step to integrating the library into your Vue 3 project.

```bash
npm install vue-data-ui
```

--------------------------------

### VueUiIcon Component Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Shows a basic usage of the VueUiIcon component to display an SVG icon with custom size and color.

```html
<VueUiIcon name="database" :size="32" stroke="#FF0000" />
```

--------------------------------

### Commit Message Conventions

Source: https://github.com/graphieros/vue-data-ui/blob/master/CONTRIBUTING.md

Examples of commit messages following the recommended format for clarity and consistency.

```bash
# Fix - {component name} - {description of the fix}
```

```bash
# New feature - {component name} - {description of the feature}
```

--------------------------------

### Example: Data Label Formatting

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Demonstrates how to use the `formatter` option to format data labels, converting large numbers into a more readable 'K' notation (e.g., thousands).

```javascript
const config = ref({
  label: {
    formatter: ({ value, config }) => {
      return `$${(value / 1000).toFixed(1)}K`;
    }
  }
});
```

--------------------------------

### Vue Data UI Installation and Import Options

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/05-types-and-configuration.md

Demonstrates various ways to import components, types, and utilities from the `vue-data-ui` package, including main package imports, individual component imports for tree-shaking, and utility imports.

```javascript
// Main package with all components
import { VueUiXy, VueUiDonut, /* ... */ } from 'vue-data-ui';
import type { VueUiXyConfig, VueUiXyDatasetItem } from 'vue-data-ui';

// Utilities
import { 
  getVueDataUiConfig,
  lightenColor,
  mergeConfigs,
  useObjectBindings,
  // ... 20+ utilities
} from 'vue-data-ui/utils';

// SSR support
import { VueUiXy } from 'vue-data-ui/ssr';

// Individual components (tree-shaking)
import VueUiXy from 'vue-data-ui/vue-ui-xy';

// Styles
import 'vue-data-ui/style.css';
```

--------------------------------

### CSV Export Format Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/05-types-and-configuration.md

Illustrates the default comma-separated value format for CSV exports.

```csv
Series 1,Series 2,Series 3
value1,value2,value3
value1,value2,value3
...
```

--------------------------------

### Sparkline Chart Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/llms.txt

This example shows how to use the VueUiSparkline component to render a sparkline chart. It includes a reactive dataset and a minimal configuration object. Ideal for embedding in dashboards or tables to indicate trends.

```vue
<template>
  <VueUiSparkline :dataset="dataset" :config="config" />
</template>

<script setup>
import { ref } from 'vue';
import { VueUiSparkline } from 'vue-data-ui';  // import the Sparkline component


// Reactive dataset: an array of objects of type VueUiSparklineDatasetItem
const dataset = ref([
    { period: 'January', value: 1 },
    { period: 'February', value: 2 },
    { period: 'March', value: 3 },
]);

// Minimal config example for the sparkline chart (optional). Full config type is VueUiSparklineConfig
const config = ref({
    type: 'line', // or 'bar'
    style: {
        area: {
            show: true,
        },
        dataLabel: {
            show: true
        },
        line: {
            color: '#6376DD'
        },
        plot: {
            show: true,
            radius: 4
        },
        title: {
            show: true,
            text: 'Title'
        },
        tooltip: {
            show: true
        },
        verticalIndicator: {
            show: true,
        }
    }
});
</script>
```

--------------------------------

### Minimal Reproduction Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

Use this Vue component structure to create a minimal, isolated example of a bug you are encountering. Ensure you import the necessary component and define your dataset.

```vue
<script setup>
import { ref } from 'vue';
import { VueUiXy } from 'vue-data-ui';

const dataset = ref([
  { name: 'A', values: [1, 2, 3] }
]);
</script>

<template>
  <VueUiXy :dataset="dataset" />
</template>
```

--------------------------------

### Get Image from Chart

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/05-types-and-configuration.md

Example of how to get an image representation of the chart with specified scale. This method returns a Promise.

```typescript
// getPrinting context
chartRef.value.getImage({
  scale: 2,           // 2x quality
  // returns Promise<ChartImage>
});
```

--------------------------------

### Installing jspdf for PDF Export

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

To enable PDF export functionality, ensure the `jspdf` library is installed in your project. This is a prerequisite for the export feature to work.

```bash
npm install jspdf
```

--------------------------------

### Run vue-data-ui-cli

Source: https://github.com/graphieros/vue-data-ui/blob/master/llms.txt

Execute the CLI tool in your project directory to start generating a chart component. Follow the prompts to configure the component type, reactivity, language, name, and location.

```bash
vdui-cli
```

--------------------------------

### Troubleshoot Cypress Missing Libraries on Linux

Source: https://github.com/graphieros/vue-data-ui/blob/master/CONTRIBUTING.md

Resolves an error where Cypress fails to start due to missing shared libraries on Linux (Ubuntu).

```bash
sudo apt-get update
sudo apt-get install -y libnspr4 libnss3 libxss1 libasound2t64 libatk-bridge2.0-0 libgtk-3-0 libgbm1
```

--------------------------------

### Basic Vue App Setup with Vue Data UI Components

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Register Vue Data UI components globally in your Vue application. Ensure the component CSS is imported.

```javascript
import { createApp } from 'vue';
import App from './App.vue';
import 'vue-data-ui/style.css';
import { VueUiXy, VueUiDonut } from 'vue-data-ui';

const app = createApp(App);
app.component('VueUiXy', VueUiXy);
app.component('VueUiDonut', VueUiDonut);
app.mount('#app');
```

--------------------------------

### Check Installed Package Version

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

Run this command in your project's terminal to check the currently installed version of the vue-data-ui package. This is useful information when reporting issues.

```bash
npm list vue-data-ui
```

--------------------------------

### Import All Utility Functions

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Imports all available utility functions from the vue-data-ui library. This is a common starting point for using multiple utilities.

```javascript
import {
    abbreviate,
    darkenColor,
    lightenColor,
    shiftColorHue,
    createTSpans,
    getCumulativeAverage,
    getCumulativeMedian,
} from 'vue-data-ui';
```

--------------------------------

### Multiline Label Support Example

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Demonstrates how to use newline characters (\n) within dataset names to display multiline labels in supported chart components.

```javascript
const dataset = ref([
  {
    name: "Line 1\nSubtitle",
    values: [...] 
  }
]);
```

--------------------------------

### JavaScript Usage Example for useObjectBindings

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Demonstrates how to use the useObjectBindings composable to flatten a reactive config object into computed refs for easy binding. It shows how to access nested properties using dot-delimited paths and use them with v-model in a template.

```javascript
import { ref, computed } from 'vue';
import { useObjectBindings, getVueDataUiConfig } from 'vue-data-ui/utils';

const config = ref(getVueDataUiConfig('vue_ui_donut'));
const bindings = useObjectBindings(config);

// Now bindings has computed refs for each leaf path:
// bindings["style.chart.backgroundColor"] → Ref<string>
// bindings["style.chart.color"] → Ref<string>

// Use in template with v-model:
// <input type="color" v-model="bindings['style.chart.backgroundColor'].value" />
```

--------------------------------

### Get Theme Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Fetches a complete theme configuration object for applying consistent styling. You can specify a theme name or use the default. Available themes include 'default', 'dark', 'zen', and others.

```typescript
function getThemeConfig(themeName?: string): object
```

```javascript
import { getThemeConfig } from 'vue-data-ui/utils';

const zenTheme = getThemeConfig('zen');
const config = ref({
  theme: 'zen',
  // ... other config
});
```

--------------------------------

### Navigate to Manual Testing Directory

Source: https://github.com/graphieros/vue-data-ui/blob/master/CONTRIBUTING.md

Change the current directory to the 'manual-testing' folder.

```bash
cd manual-testing
```

--------------------------------

### Build for Production

Source: https://github.com/graphieros/vue-data-ui/blob/master/manual-testing/README.md

This command type-checks, compiles, and minifies the project for production deployment.

```sh
npm run build
```

--------------------------------

### Apply Predefined Theme

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Use `getVueDataUiConfig` to load a predefined theme and override specific properties like 'theme'.

```javascript
const config = ref({
  ...getVueDataUiConfig('vue_ui_donut'),
  theme: 'dark'  // 'dark', 'zen', 'hack', 'concrete', etc.
});
```

--------------------------------

### Build for Production

Source: https://github.com/graphieros/vue-data-ui/wiki/Contributing-to-Vue-Data-UI

Build the library for production after all tests pass.

```bash
npm run prod
```

--------------------------------

### Get Default Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Retrieve the default configuration object for a specific chart type, such as 'vue_ui_xy'.

```javascript
getVueDataUiConfig('vue_ui_xy')
```

--------------------------------

### Build Local Distribution

Source: https://github.com/graphieros/vue-data-ui/wiki/Contributing-to-Vue-Data-UI

Create a local distribution build of the library.

```bash
npm run simple-build
```

--------------------------------

### Export Chart as PDF

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Generates a PDF file of the current chart. Ensure jspdf is installed via npm.

```javascript
// Make sure jspdf is installed
// npm install jspdf

const downloadPdf = async () => {
  await chartRef.value.generatePdf();
};
```

--------------------------------

### Importing Vue Data UI Components

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Demonstrates how to import individual components or specific component entry points from the vue-data-ui package. Also shows how to include the global styles.

```javascript
// Import individual components
import { VueUiXy, VueUiDonut } from 'vue-data-ui';

// Import from component entry points
import VueUiXy from 'vue-data-ui/vue-ui-xy';
import VueUiDonut from 'vue-data-ui/vue-ui-donut';

// Include styles
import 'vue-data-ui/style.css';
```

--------------------------------

### Enable Keyboard Navigation

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Configure accessibility features for keyboard navigation. This snippet sets up translations for guiding users.

```vue
<script setup>
import { ref } from 'vue';
import { getVueDataUiConfig } from 'vue-data-ui/utils';

const config = ref({
  ...getVueDataUiConfig('vue_ui_xy'),
  a11y: {
    translations: {
      keyboardNavigation: 'Use arrow keys to navigate between data points'
    }
  }
});
</script>

<template>
  <VueUiXy :dataset="dataset" :config="config">
    <template #hint="{ hint, isVisible }">
      <p v-if="isVisible" class="hint">{{ hint }}</p>
    </template>
  </VueUiXy>
</template>

<style scoped>
.hint {
  position: absolute;
  bottom: -40px;
  left: 0;
  font-size: 12px;
  color: #666;
}
</style>
```

--------------------------------

### Importing Vue Data UI Packages

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/00-index.md

Demonstrates how to import components and utilities from the main package, SSR-safe exports, and individual components for tree-shaking. Includes importing styles.

```javascript
// Main package (all components and utilities)
import { /* components */ } from 'vue-data-ui';
import { /* utilities */ } from 'vue-data-ui/utils';

// SSR-safe exports
import { /* components */ } from 'vue-data-ui/ssr';

// Individual components (tree-shaking)
import Component from 'vue-data-ui/vue-ui-component-name';

// Styles
import 'vue-data-ui/style.css';
```

--------------------------------

### Get Default Vue-Data-UI Config

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Retrieve the default configuration object for a specific component, such as 'vue_ui_xy', using the `getVueDataUiConfig` function.

```javascript
import { getVueDataUiConfig } from 'vue-data-ui';

const defaultConfigXy = getVueDataUiConfig('vue_ui_xy');
```

--------------------------------

### Apply Custom Theme with Color Overrides

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Sets up a custom theme for charts by merging default configurations with user-defined color overrides. Requires importing utility functions.

```javascript
import { getVueDataUiConfig, mergeConfigs } from 'vue-data-ui/utils';

const customTheme = getVueDataUiConfig('vue_ui_xy', {
  colorBackground: '#1A1A1A',
  colorTextPrimary: '#CD9077',
  colorTextSecondary: '#825848',
  colorGrid: '#CD9077',
  colorBorder: '#CD9077',
});

const config = computed(() => 
  mergeConfigs({
    defaultConfig: customTheme,
    userConfig: {
      chart: {
        title: { text: 'My Title' }
      }
    }
  })
);
```

--------------------------------

### Using VueUiXy Component with Default or Custom Config

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

Demonstrates how to use the VueUiXy component. It can be used with only a dataset, relying on default configurations, or with both dataset and a custom configuration object.

```vue
<!-- ✓ This works (uses defaults) -->
<VueUiXy :dataset="dataset" />

<!-- ✓ This also works (custom config) -->
<VueUiXy :dataset="dataset" :config="config" />
```

--------------------------------

### Get Cumulative Median

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Calculates the cumulative median of an array of numbers. Options are available to ignore invalid values or convert them to zero.

```javascript
import { getCumulativeMedian } from 'vue-data-ui';

// simple usage
const arr = [0, 1, 2, 3, 4];
const cumulativeMed = getCumulativeMedian({ values: arr });

// Ignore invalid values entirely
const arrWithInvalid = [1, null, 2, Infinity, NaN, undefined];
const cumulativeMedNoInvalid = getCumulativeMedian({
    values: arrWithInvalid,
    config: {
        keepInvalid: false,
    },
});

// Convert invalid values to zero
const cumulativeMedZeroed = getCumulativeMedian({
    values: arrWithInvalid,
    config: {
        convertInvalidToZero: true,
    },
});
```

--------------------------------

### Import VueDataUi

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Import the main VueDataUi component for dynamic chart rendering.

```javascript
import { VueDataUi } from 'vue-data-ui';
```

--------------------------------

### Create Custom Theme

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Define a custom theme by providing color values to `getVueDataUiConfig` and merge it with user configurations using `mergeConfigs`.

```javascript
import { getVueDataUiConfig, mergeConfigs } from 'vue-data-ui/utils';

const customTheme = getVueDataUiConfig('vue_ui_xy', {
  colorBackground: '#1A1A1A',
  colorTextPrimary: '#FFFFFF',
  colorTextSecondary: '#B0B0B0',
  colorBorder: '#404040'
});

const config = computed(() =>
  mergeConfigs({
    defaultConfig: customTheme,
    userConfig: {
      chart: { title: { text: 'My Chart' } }
    }
  })
);
```

--------------------------------

### Get Cumulative Average

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Calculates the cumulative average of an array of numbers. Options are available to ignore invalid values or convert them to zero.

```javascript
import { getCumulativeAverage } from 'vue-data-ui';

// simple usage
const arr = [0, 1, 2, 3, 4];
const cumulativeAvg = getCumulativeAverage({ values: arr });

// Ignore invalid values entirely
const arrWithInvalid = [1, null, 2, Infinity, NaN, undefined];
const cumulativeAvgNoInvalid = getCumulativeAverage({
    values: arrWithInvalid,
    config: {
        keepInvalid: false,
    },
});

// Convert invalid values to zero
const cumulativeAvgZeroed = getCumulativeAverage({
    values: arrWithInvalid,
    config: {
        convertInvalidToZero: true,
    },
});
```

--------------------------------

### Get Chart Data

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Retrieve the current dataset and configuration from a chart component. This is useful for further processing or displaying data outside the chart.

```javascript
const chartRef = ref(null);

onMounted(async () => {
  const { dataset, config } = await chartRef.value.getData();
  console.log(dataset, config);
});
```

--------------------------------

### Control Series Visibility

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Toggle the visibility of individual series in a chart. This example demonstrates showing and hiding a series using its name.

```vue
<script setup>
const chartRef = ref(null);

const toggleSeries = (name) => {
  chartRef.value.showSeries(name);
  chartRef.value.hideSeries(name);
};
</script>

<template>
  <VueUiXy ref="chartRef" :dataset="dataset" :config="config" />
  <button @click="toggleSeries('Series 1')">Toggle Series 1</button>
</template>
```

--------------------------------

### Vue Data UI Default Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/00-index.md

Shows how to initialize a configuration object using a default preset for a specific chart type.

```javascript
const config = ref(getVueDataUiConfig('vue_ui_donut'));
```

--------------------------------

### Get Color Palette

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Retrieves a color palette from the internal library using its index. Returns an array of color strings in HEX format.

```typescript
function getPalette(paletteIndex: number): string[]
```

--------------------------------

### Use Universal Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Demonstrates how to use the universal VueDataUi component to dynamically switch between different chart types.

```vue
<template>
  <VueDataUi
    :component="currentChart"
    :dataset="dataset"
    :config="config"
  />
</template>

<script setup>
import { ref } from 'vue';
import { VueDataUi } from 'vue-data-ui';

const currentChart = ref('VueUiXy');

// Switch between components dynamically
const switchChart = (name) => {
  currentChart.value = name;
};
</script>
```

--------------------------------

### PDF Generation

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Generate a PDF export of the chart. This feature requires `jspdf` to be installed as a peer dependency. The generated PDF is automatically downloaded with a filename and title.

```APIDOC
## PDF Generation

PDF export requires `jspdf` as a peer dependency.

### Installation

```bash
npm install jspdf
```

### Usage

- **generatePdf()**: Generates and downloads a PDF version of the chart.

```javascript
chartRef.value.generatePdf();
```

The PDF is automatically downloaded with appropriate filename and title.
```

--------------------------------

### Correct Import Path for jspdf

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

When using `jspdf` with `vue-data-ui`, you typically do not need to import it directly in your code. Simply installing the package is sufficient as `vue-data-ui` handles the integration.

```javascript
// ✗ Wrong
import jspdf from 'jspdf';  // May fail

// ✓ Correct (auto-detected by vue-data-ui)
// Just install jspdf, vue-data-ui handles it
```

--------------------------------

### Generate and Download Chart as PDF

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Initiate the generation and download of the chart as a PDF file. No specific options are detailed in this basic usage.

```javascript
await chartRef.value.generatePdf();
```

--------------------------------

### Get Line Count of Markdown Files in Terminal

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/README.md

Use the 'wc -l' command to count the total number of lines in all markdown files within the current directory.

```bash
wc -l *.md
```

--------------------------------

### Generate and Download Chart as Image

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Initiate the generation and download of the chart as an image file. Specific options may be available but are not detailed here.

```javascript
await chartRef.value.generateImage();
```

--------------------------------

### Using the Universal VueDataUi Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Utilize the VueDataUi universal component to render other components by specifying the 'component' prop. This requires importing VueDataUi and the CSS.

```javascript
<script setup>
import { ref } from "vue";
import { VueDataUi } from "vue-data-ui";
// Include the css;
import "vue-data-ui/style.css";

const config = ref({...});
const dataset = ref([...]);

</script>

<template>

  <VueDataUi
    component="VueUiXy"
    :config="config"
    :dataset="dataset"
  />

</template>
```

--------------------------------

### Configuring User Options for Context Menu

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Customize the context menu and user action buttons, including visibility, hover behavior, and available actions like PDF export or CSV download.

```javascript
const config = ref({
  userOptions: {
    show: true,                    // Show context menu
    showOnChartHover: false,       // Show only on hover
    keepStateOnChartLeave: true,   // Keep open when hovering out
    buttons: {
      pdf: true,
      img: true,
      csv: true,
      table: true,
      altCopy: false,
      fullscreen: true,
      annotator: true,
      // ... other buttons per component
    },
    callbacks: {
      pdf: ({ chartElement, imageUri, base64 }) => {},
      img: ({ chartElement, imageUri, base64 }) => {},
      csv: (csvStr) => {},
      altCopy: ({ dataset, config }) => {},
      // ... other callbacks
    },
    buttonTitles: {
      pdf: 'Download PDF',
      img: 'Download Image',
      // ... other titles
    }
  },
  // ... other config
});
```

--------------------------------

### Keyboard Navigation Hint Display

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Use the '#hint' slot to display navigation instructions for keyboard users. This is useful for guiding users on how to interact with the chart using arrow keys.

```html
<VueUiXy :dataset="dataset" :config="config">
  <template #hint="{ hint, isVisible }">
    <p v-if="isVisible">{{ hint }}</p>
  </template>
</VueUiXy>
```

--------------------------------

### VueUiTimer

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

The VueUiTimer component manages timer functionality, including start, pause, reset, restart, and lap events. It also offers slots for time display, controls, laps, and chart background.

```APIDOC
## VueUiTimer

### Description
Manages timer functionality with various control events and display slots.

### Emits / Exposed Methods
- `@start`
- `@pause`
- `@reset`
- `@restart`
- `@lap`

### Slots
- `#time`
- `#controls`
- `#laps`
- `#chart-background`
```

--------------------------------

### Import VueUi3dBar Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUi3dBar component for creating 3D perspective bar charts.

```javascript
import { VueUi3dBar } from 'vue-data-ui';
```

--------------------------------

### Get Chart Data with getData

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Use the `getData` method to retrieve the current data from a chart component. Ensure a ref is attached to the component and accessed within `onMounted` or a similar lifecycle hook.

```javascript
const componentRef = ref(null);

onMounted(async () => {
    if (componentRef) {
        const data = await componentRef.value.getData();
        console.log(data);
    }
});
```

--------------------------------

### Download Chart Image

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Initiate the download of the chart as an image file. This method likely triggers a browser download prompt.

```javascript
chartRef.value.generateImage()
```

--------------------------------

### Import VueUiOnion Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiOnion component for creating layered, onion-style charts composed of multiple nested rings.

```javascript
import { VueUiOnion } from 'vue-data-ui';
```

--------------------------------

### Get Default Chart Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Retrieves the default configuration object for a specified chart component type. Useful for initializing custom themes or extending default settings. Ensure the component type is valid.

```typescript
function getVueDataUiConfig(type: string, options?: object): object
```

```javascript
import { getVueDataUiConfig } from 'vue-data-ui/utils';

const defaultDonutConfig = getVueDataUiConfig('vue_ui_donut');
// Use the config:
const config = ref(defaultDonutConfig);
```

--------------------------------

### Responsive Configuration Interface

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/05-types-and-configuration.md

Defines settings for enabling responsive behavior in charts. When enabled, charts will adapt to container size changes. Ensure the container has fixed dimensions for this to work correctly.

```typescript
interface ResponsiveConfig {
  responsive?: boolean;  // Enable responsive mode (default: false)
  // When enabled, chart adapts to container size changes
  // Container must have fixed (not 100%) dimensions
}
```

--------------------------------

### Vue Data UI Template Ref Methods

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/00-index.md

Provides examples of using template refs to interact with chart components, including data retrieval, image export, PDF generation, series manipulation, and zoom operations.

```javascript
const chartRef = ref(null);
await chartRef.value.getData();           // Get current data
await chartRef.value.getImage();          // Get image
await chartRef.value.generatePdf();       // Export PDF
chartRef.value.showSeries('Series 1');    // Show series
chartRef.value.zoomIn();                  // Zoom operations
```

--------------------------------

### Merge Configurations

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Combine a default configuration with a user-defined configuration.

```javascript
mergeConfigs({ defaultConfig, userConfig })
```

--------------------------------

### Customize Context Menu Buttons in VueUiDonut

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Customize the text and behavior of context menu action buttons by using slots provided by the chart component. This example shows how to override the default text for PDF export and customize the fullscreen toggle.

```html
<VueUiDonut :config="config" :dataset="dataset">
  <template #optionPdf>
    DOWNLOAD PDF
  </template>
  
  <template #optionFullscreen="{ isFullscreen, toggleFullscreen }">
    <div @click="toggleFullscreen(isFullscreen ? 'out' : 'in')">
      {{ isFullscreen ? 'EXIT' : 'FULLSCREEN' }}
    </div>
  </template>
</VueUiDonut>
```

--------------------------------

### Flattening Reactive Objects with useObjectBindings

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Use this composable to flatten a reactive object into individual refs for each leaf property. This allows for easy binding to deeply nested values using their string paths. Ensure jspdf is installed if PDF generation is intended.

```javascript
import { useObjectBindings, getVueDataUiConfig } from 'vue-data-ui';

const config = ref(getVueDataUiConfig('vue_ui_donut')); // or your custom config for this component

const bindings = useObjectBindings(config);
// Now `bindings` has computed refs for each leaf path:
//   bindings["style.chart.backgroundColor"] → Ref<string>
//   bindings["style.chart.color"] → Ref<string>
//   bindings["customPalette"] → Ref<boolean>
//   by default, arrays are skipped:
//   no "customPalette.0", unless you disable skipArrays
```

--------------------------------

### Enable Debugging

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/README.md

To enable debugging, set the `debug` property to `true` in the configuration. This is useful for troubleshooting.

```javascript
config.debug = true
```

--------------------------------

### Importing Utility Functions

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Demonstrates how to import utility functions from 'vue-data-ui/utils' using named imports or a default export. Use named imports for specific functions like configuration or color adjustments.

```javascript
import {
  getVueDataUiConfig,
  lightenColor,
  darkenColor,
  // ... all utilities
} from 'vue-data-ui/utils';
```

```javascript
import vueDataUiUtilities from 'vue-data-ui/utils';
const config = vueDataUiUtilities.getVueDataUiConfig('vue_ui_xy');
```

--------------------------------

### Import VueUiDonutEvolution Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiDonutEvolution component to display the time-series evolution of donut charts across different periods.

```javascript
import { VueUiDonutEvolution } from 'vue-data-ui';
```

--------------------------------

### Create Word Cloud Dataset from Plain Text

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/01-utility-functions.md

Transforms plain text into a dataset suitable for VueUiWordCloud by counting word frequencies. Import from 'vue-data-ui/utils'.

```typescript
function createWordCloudDatasetFromPlainText(text: string): object[]
```

```javascript
import { createWordCloudDatasetFromPlainText } from 'vue-data-ui/utils';

const text = 'hello world hello vue vue data ui';
const dataset = createWordCloudDatasetFromPlainText(text);
// Result: [
//   { name: 'hello', value: 2 },
//   { name: 'world', value: 1 },
//   { name: 'vue', value: 2 },
//   { name: 'data', value: 1 },
//   { name: 'ui', value: 1 }
// ]
```

--------------------------------

### VueUiDashboard

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

The VueUiDashboard component emits a change event and provides slots for content, top, and bottom sections.

```APIDOC
## VueUiDashboard

### Description
Provides a dashboard interface with customizable content sections.

### Emits / Exposed Methods
- `@change`

### Slots
- `#content`
- `#top`
- `#bottom`
```

--------------------------------

### Applying a Theme

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Set a predefined theme for the component by specifying the 'theme' property in the config object. Supports multiple theme options.

```javascript
const config = ref({
  theme: 'dark',
  // ... other config
});
```

--------------------------------

### Import VueUiDonut Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiDonut component for creating classic donut or pie charts with a customizable inner radius.

```javascript
import { VueUiDonut } from 'vue-data-ui';
```

--------------------------------

### Generate and Download Chart as SVG

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Initiate the generation and download of the chart as an SVG file. This method is straightforward and does not appear to take any arguments.

```javascript
await chartRef.value.generateSvg();
```

--------------------------------

### Vue Data UI Reactive Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/00-index.md

Illustrates creating a reactive configuration object that updates based on external state, such as a dark mode toggle.

```javascript
const config = computed(() => ({
  ...getVueDataUiConfig('vue_ui_xy'),
  theme: isDarkMode.value ? 'dark' : 'default'
}));
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/graphieros/vue-data-ui/blob/master/CONTRIBUTING.md

Upload your local branch with changes to your forked repository.

```bash
git push origin my-branch-name
```

--------------------------------

### Generate PDF Method

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/03-ssr-and-advanced-features.md

Call this method to generate and download a PDF of the current chart. The PDF will have an appropriate filename and title.

```javascript
chartRef.value.generatePdf();
```

--------------------------------

### Import Specific Components in Files

Source: https://github.com/graphieros/vue-data-ui/blob/master/README.md

Import only the components you need directly into your Vue files. This is useful for optimizing bundle size.

```javascript
<script setup>
import {(VueUiRadar, VueUiXy)} from "vue-data-ui";
</script>
```

--------------------------------

### Import VueUiQuickChart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiQuickChart component, which intelligently selects the best visualization type (line, bar, or donut) based on the provided dataset structure.

```javascript
import { VueUiQuickChart } from 'vue-data-ui';
```

--------------------------------

### Import VueUiCirclePack Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiCirclePack component for creating hierarchical circle packing visualizations.

```javascript
import { VueUiCirclePack } from 'vue-data-ui';
```

--------------------------------

### generateImage(options?)

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/02-component-api-reference.md

Generates and downloads the chart as an image file.

```APIDOC
## generateImage(options?)

### Description
Generates and downloads chart as image file.

### Method
`generateImage(options?)`
```

--------------------------------

### Component Configuration Base Interface

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/05-types-and-configuration.md

Provides a hierarchical structure for component configurations, encompassing general settings, styling, user options, and accessibility features.

```typescript
interface ComponentConfig {
  loading?: boolean;
  debug?: boolean;
  theme?: string;
  responsive?: boolean;
  customPalette?: string[];
  downsample?: {
    threshold?: number;
  };
  style?: {
    chart?: {
      backgroundColor?: string;
      color?: string;
      // ... component-specific style options
    };
    title?: { /* ... */ };
    legend?: { /* ... */ };
    tooltip?: { /* ... */ };
  };
  userOptions?: {
    show?: boolean;
    showOnChartHover?: boolean;
    keepStateOnChartLeave?: boolean;
    buttons?: {
      pdf?: boolean;
      img?: boolean;
      csv?: boolean;
      // ... component-specific buttons
    };
    callbacks?: {
      pdf?: (options: any) => void;
      img?: (options: any) => void;
      csv?: (csvString: string) => void;
      // ... component-specific callbacks
    };
    buttonTitles?: {
      [key: string]: string;
    };
  };
  a11y?: {
    translations?: {
      keyboardNavigation?: string;
      tableAvailable?: string;
      tableCaption?: string;
    };
  };
  useCursorPointer?: boolean;
  // Component-specific fields...
}
```

--------------------------------

### Enabling Responsiveness for Charts

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/07-troubleshooting-and-errors.md

To make charts resize with their containers, set the `responsive` option to `true` in the configuration. Ensure the container has defined dimensions.

```javascript
// ✗ Missing responsive flag
const config = ref(getVueDataUiConfig('vue_ui_xy'));

// ✓ Enable responsive
const config = ref({
  ...getVueDataUiConfig('vue_ui_xy'),
  responsive: true
});
```

--------------------------------

### Import VueUiScatter Chart Component

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/04-chart-components-catalog.md

Import the VueUiScatter component for generating scatter plots used in correlation and distribution analysis.

```javascript
import { VueUiScatter } from 'vue-data-ui';
```

--------------------------------

### Vue Data UI Custom Theme Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/00-index.md

Demonstrates merging default configurations with user-defined settings to create a custom theme, including chart-specific options.

```javascript
const config = computed(() =>
  mergeConfigs({
    defaultConfig: getVueDataUiConfig('vue_ui_xy', { colorBackground: '#000' }),
    userConfig: { chart: { title: { text: 'My Chart' } } }
  })
);
```

--------------------------------

### Responsive Chart Configuration

Source: https://github.com/graphieros/vue-data-ui/blob/master/_autodocs/06-quick-reference.md

Enable responsive behavior for charts by setting the `responsive` option to `true`. Ensure the parent container has fixed width and height.

```javascript
const config = ref({
  ...getVueDataUiConfig('vue_ui_xy'),
  responsive: true
});
```

```vue
<template>
  <!-- Container MUST have fixed width and height -->
  <div style="width: 800px; height: 400px;">
    <VueUiXy :dataset="dataset" :config="config" />
  </div>
</template>
```