@voicenter-team/voicenter-ui-plus

v3.0.0

Published

7 days ago

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

0High
0Medium
0Low

Voicenter UI library for Vue

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

v3.0.0 is a tree-shaking release with breaking changes. See MIGRATION_v3.md. The separate *-extended package is gone — every component lives in this package now.

Installation

npm i @voicenter-team/voicenter-ui-plus
npm i vue@^3.5 element-plus @vueuse/core dayjs lodash-es libphonenumber-js maska

Sass compiler (build-time)

This library customizes element-plus theming via SCSS variable injection at build time. Your bundler needs to be able to compile SCSS. If your project doesn't already use Sass, add it as a dev dependency:

npm i -D sass-embedded

This is a build-time only requirement — it doesn't add anything to your runtime bundle. Most Vue 3 / Vite projects already have it.

Optional peer deps — install only for the heavy components you use:

| Component | Peer deps | |---|---| | VcPdfDocument | pdfjs-dist@^2.9.359 | | VcSoundPlayer | wavesurfer.js | | VcExcelFileUploader | xlsx | | VcImageUploader | vue-advanced-cropper | | VcHtmlEditor / VcJsonSchema | codemirror @codemirror/lang-html @codemirror/lang-json @codemirror/lang-markdown vue-codemirror6 | | VcMdEditor | @milkdown/crepe @milkdown/kit @milkdown/vue @prosemirror-adapter/vue |

If you're on Vite 8 / rolldown (and skipping some optional peers)

Vite 8's rolldown-based bundler validates named imports against optional-peer-dep stubs and fails the build with MISSING_EXPORT errors when a heavy component's peer is uninstalled — even when you don't use that component. Add the unused optional peers to build.rollupOptions.external in your vite.config.ts:

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
    plugins: [ vue() ],
    build: {
        rollupOptions: {
            external: [
                // List only the heavy peers you DON'T install
                /^@milkdown\//, /^@prosemirror/, /^@codemirror\//, /^codemirror/,
                /^vue-codemirror6/, /^vue-advanced-cropper/,
                'wavesurfer.js', 'xlsx', 'pdfjs-dist', /^pdfjs-dist\//
            ]
        }
    }
})

Earlier Vite versions (5, 6, 7 with rollup) and webpack 5+ don't require this — the older rollup variant warns but doesn't error on optional-peer named imports.

Usage

Tree-shake mode (recommended)

import { VcButton, VcInput } from '@voicenter-team/voicenter-ui-plus'
// Use as local components — no app.use() needed.

Bundlers drop unused components and their CSS. A consumer importing only VcButton ships ~50–150 KB JS + ~10–30 KB CSS.

Plugin mode (global registration)

import VoicenterUI from '@voicenter-team/voicenter-ui-plus/plugin'
import '@voicenter-team/voicenter-ui-plus/style.css'

app.use(VoicenterUI, {
    themeConfig,             // theme config (see below)
    lang: 'en',              // localization
    injectIconFont: true     // inject icon-font <link> tags into <head>
})

2.1. If you are using tailwind update your tailwind.config.js with:

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:

{
    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:

{
    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:

{
    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 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

'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

<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

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

// 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

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

Date Arithmetic

Adding/Subtracting Days

// 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

// 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

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

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

Date Comparisons

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

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 for interactive component examples and demos.

Project Documentation

For detailed technical documentation, see the docs/ directory:

Quick Start Guide - For developers working on the library
Integration Guide - For using the library in other projects
Architecture Overview - Project structure and technical details
Documentation Guide - Working with the documentation system

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Voicenter UI library for Vue

Installation

Sass compiler (build-time)

If you're on Vite 8 / rolldown (and skipping some optional peers)

Usage

Tree-shake mode (recommended)

Plugin mode (global registration)

Theming specification

Local

Remote

Custom JSON

Date Handling

Format Tokens

Common Formats

Usage Example

Date Utility Functions

Import Date Utilities

Basic Date Operations

Formatting Dates

Parsing Dates

Date Arithmetic

Adding/Subtracting Days

Adding/Subtracting Time Units

Time Operations

Getting Time Components

Setting Time

Date Comparisons

Complete Usage Example

Notes

Documentation

Live Documentation

Project Documentation