# Voicenter UI library for Vue
This is Vue 3.x + Typescript component library made for Voicenter systems

## Installation
1. run `yarn add @voicenter-team/voicenter-ui-plus` or `npm i @voicenter-team/voicenter-ui-plus`
2. In main js/ts file add
```js
import '@voicenter-team/voicenter-ui-plus/library/style.css'
import VoicenterUI from '@voicenter-team/voicenter-ui-plus'

app.use(VoicenterUI, {
    components: [], // Here you can pass list of components which you wan't to be globally registered. If empty - will register globally all
    themeConfig, // Pass the configuration of the theme
    lang: 'en', // Pass the language for app localization
    injectIconFont: true, // Will load the icons fonts by adding link elements to head block, library does include the icon fonts in style.css by default, this option should be used in cases like creating custom elements where shadow dom does not support font-family declaration
})
```
2.1. If you are using tailwind update your `tailwind.config.js` with:
```js
const voiceTailwindScheme = require('@voicenter-team/voicenter-ui-plus/src/theme/tailwindScheme')

module.exports = {
  ...yourConfiguration,
  theme: {
    colors: {
      ...voiceTailwindScheme
    },
    borderColor: {
      ...voiceTailwindScheme
    }
  }
}
```

### Theming specification
The `themeConfig` which is passed as options to the VoicenterUI `vue.use` data could have the following specifications:

### Local
**Config:**
```js
{
    type: 'local'
    themeName: 'red' | 'blue' | '...'
    onSetupCallback: () => {
        console.log('Loaded!')
    }
}
```
**Description:**

Such configuration will append to the document element the CSS variables from one of the configuration passed in `themeName` parameter which it will get from theme specification delivered alongside with library 

**Params:**
- **themeName**
  - The name of the theme to be injected
- **onSetupCallback**
  - The function which will be called right after the variables will be injected into the document element. First parameter of which is the theme object which was set up

### Remote
**Config:**
```js
{
    type: 'remote'
    brandingSectionName: 'someName'
    apiUrl: 'someUrl'
    brandingSectionName: {
        property: 'data'
    }
    onSetupCallback: () => {
        console.log('Loaded!')
    }
}
```
**Description:**

Such configuration will initiate the call to the specified apiUrl in order to retrieve the JSON object with key-value properties of the CSS variables to inject to document element 

**Params:**
- **brandingSectionName**
  - [Optional] The name of the section (tagSection) in the database configuration which will be passed to the API in payload and on response retrieved replaced from resulted values
- **apiUrl**
  - The API url to which the POST request will be initiated
- **onSetupCallback**
  - The function which will be called right after the variables will be injected into the document element. First parameter of which is the theme object which was set up
- **brandingSectionName**
  - [Optional] The payload data that will be sent to the request

### Custom JSON
**Config:**
```js
{
    type: 'customJson'
    config: {
        black: '#000000'
    }
    onSetupCallback: () => {
      console.log('Loaded!')
    }
}
```
**Description:**

Such configuration will initiate the styling with custom provided theme

**Params:**
- **config**
  - The object where the key is the variable to be set and the value is the variable value. Check the [themes object](https://github.com/VoicenterTeam/voicenter-ui-plus/blob/master/src/theme/themes.json) to check existing variables
- **onSetupCallback**
  - The function which will be called right after the variables will be injected into the document element. First parameter of which is the theme object which was set up

## Date Handling

This library uses **dayjs** for all date operations and formatting. When working with date-related components, use dayjs format tokens (NOT date-fns format tokens).

### Format Tokens

**Important**: Use dayjs format tokens:
- `DD` - Day of month (2 digits) - **NOT** `dd`
- `YYYY` - 4-digit year - **NOT** `yyyy`
- `MM` - Month (2 digits)
- `HH` - 24-hour format
- `mm` - Minutes
- `ss` - Seconds

### Common Formats

```typescript
'DD/MM/YYYY'           // 31/12/2024
'DD-MM-YYYY'           // 31-12-2024
'YYYY-MM-DD'           // 2024-12-31
'DD/MM/YYYY, HH:mm'    // 31/12/2024, 14:30
'DD/MM/YYYY HH:mm:ss'  // 31/12/2024 14:30:45
```

### Usage Example

```vue
<VcDatePicker
  v-model="date"
  format="DD/MM/YYYY"
  input-date-format="DD/MM/YYYY"
  input-time-format="HH:mm"
/>
```

## Date Utility Functions

The library provides a comprehensive set of date utility functions built on dayjs. These utilities are available for use in external projects.

### Import Date Utilities

```typescript
import {
  formatDate,
  parseDate,
  addDays,
  subtractDays,
  getHours,
  getMinutes,
  getSeconds,
  setTime,
  isAfter,
  isSameAfter,
  isBefore,
  isSameBefore,
  format,
  add,
  sub,
  addFp,
  subFp
} from '@voicenter-team/voicenter-ui-plus'
```

### Basic Date Operations

#### Formatting Dates

```typescript
// Format a date with default format (YYYY-MM-DD)
const formatted = formatDate(new Date())
// Result: "2024-12-31"

// Format with custom format
const custom = formatDate(new Date(), 'DD/MM/YYYY')
// Result: "31/12/2024"

// Using format function (alias)
const formatted2 = format(new Date(), 'DD/MM/YYYY HH:mm')
// Result: "31/12/2024 14:30"
```

#### Parsing Dates

```typescript
// Parse a date string with format
const date = parseDate('31/12/2024', 'DD/MM/YYYY')
// Returns: Date object
```

### Date Arithmetic

#### Adding/Subtracting Days

```typescript
// Add days
const futureDate = addDays(new Date(), 7)
// Returns: Date 7 days from now

// Subtract days
const pastDate = subtractDays(new Date(), 5)
// Returns: Date 5 days ago
```

#### Adding/Subtracting Time Units

```typescript
// Add multiple time units
const newDate = add(new Date(), {
  years: 1,
  months: 2,
  days: 5,
  hours: 3,
  minutes: 30
})

// Subtract multiple time units
const earlierDate = sub(new Date(), {
  weeks: 2,
  days: 3,
  hours: 12
})

// Functional programming style (reversed arguments)
const fpDate = addFp({ days: 7 }, new Date())
const fpDate2 = subFp({ hours: 5 }, new Date())
```

### Time Operations

#### Getting Time Components

```typescript
const date = new Date('2024-12-31T14:30:45')

const hours = getHours(date)    // 14
const minutes = getMinutes(date) // 30
const seconds = getSeconds(date) // 45
```

#### Setting Time

```typescript
// Set time on a date (returns new Date object)
const newDate = setTime(new Date(), {
  hours: 14,
  minutes: 30,
  seconds: 0
})
```

### Date Comparisons

```typescript
const date1 = new Date('2024-12-31')
const date2 = new Date('2025-01-01')

// Check if date1 is after date2
const isLater = isAfter(date1, date2, 'day')
// Returns: false

// Check if date1 is same or after date2
const isSameOrLater = isSameAfter(date1, date2, 'day')
// Returns: false

// Check if date1 is before date2
const isEarlier = isBefore(date1, date2, 'day')
// Returns: true

// Check if date1 is same or before date2
const isSameOrEarlier = isSameBefore(date1, date2, 'day')
// Returns: true
```

**Comparison Units**: The comparison functions accept a `units` parameter (default: `'minute'`). Valid units:
- `'year'`, `'month'`, `'week'`, `'day'`
- `'hour'`, `'minute'`, `'second'`

### Complete Usage Example

```typescript
import {
  formatDate,
  addDays,
  isAfter,
  format,
  add,
  getHours,
  setTime
} from '@voicenter-team/voicenter-ui-plus'

// Format today's date
const today = formatDate(new Date(), 'DD/MM/YYYY')

// Get date 30 days from now
const futureDate = addDays(new Date(), 30)

// Check if a date is in the future
const isFuture = isAfter(futureDate, new Date(), 'day')

// Add 2 weeks and 3 days
const deadline = add(new Date(), {
  weeks: 2,
  days: 3
})

// Get current hour
const currentHour = getHours(new Date())

// Set specific time
const meetingTime = setTime(new Date(), {
  hours: 14,
  minutes: 30
})

// Format the result
const formattedDeadline = format(deadline, 'DD/MM/YYYY HH:mm')
```

### Notes

- All functions accept `Date`, `string`, or `number` as date input
- All date manipulation functions return new `Date` objects (immutable)
- Format strings use dayjs format tokens (see Format Tokens section above)
- These utilities are built on dayjs and maintain compatibility with dayjs format patterns

## Documentation

### Live Documentation
Visit [documentation](https://voicenter-ui.netlify.app/) for interactive component examples and demos.

## Migration Notes

### Wizard step hooks rename

- `beforeStepFn` is renamed to `validateStepFn`.
- `onEnterStepFn` is renamed to `initStepFn`.
- Backward compatibility is preserved for now, but new code should use the new names.
- Wizard documentation examples already use the new hook names.

### Project Documentation
For detailed technical documentation, see the [`docs/`](./docs/) directory:

- **[Quick Start Guide](./docs/AGENTS_QUICK_START.md)** - For developers working on the library
- **[Integration Guide](./docs/AGENTS_INTEGRATION_GUIDE.md)** - For using the library in other projects
- **[Architecture Overview](./docs/ARCHITECTURE.md)** - Project structure and technical details
- **[Documentation Guide](./docs/DOCUMENTATION_GUIDE.md)** - Working with the documentation system
