Portal Design System

A type-safe, production-ready Vue 3 UI component library built with Tailwind CSS, TypeScript, and isolated styles for easy integration into projects. Features a comprehensive collection of reusable components, composables, directives, and utilities.

Table of Contents

- Features
- Quick Overview
- Installation
- Quick Start
- Components
- Inputs
- Overlays
- Directives
- Composables
- Styling & CSS
- Development
- Contributing
- License

Features

- Vue 3 + TypeScript - Full type safety with modern Vue 3 Composition API
- Tailwind CSS - Utility-first styling with prefixed classes for isolation
- ESM/CJS Distribution - Works with all module systems
- Component Flexibility - Regular Vue components + Web Components support
- Icon Support - Integrated Iconsax icons with customizable styling
- Accessible - Built with accessibility in mind
- Production Ready - Thoroughly tested components with real-world use cases

Quick Overview

- Framework: Vue 3 (Composition API)
- Styling: Tailwind CSS 4+ (prefixed utilities for isolation)
- Language: TypeScript 5+
- Build Tool: Vite 6
- Distribution: ESM / CJS + CSS + Type Definitions
- Package Version: 0.0.972

Installation

Install the package from npm (or use your preferred package manager):

``bash
npm install portal-design-system


or

yarn add portal-design-system

or

pnpm add portal-design-system

or

bun add portal-design-system
`

$3

If you use the DataGrid component, you must also install DevExtreme and its Vue bindings:

`bash
npm install devextreme devextreme-vue devextreme-aspnet-data-nojquery
`

Then import it separately:

`vue



`

Note: DataGrid is exported as a separate entry point to avoid bundling DevExtreme in projects that don't use it. This keeps the main library lightweight.

Quick Start

$3

`ts
// main.ts
import 'portal-design-system/styles'
`

$3

`vue



`

$3

For full style encapsulation with Web Components:

`html


Shadow Button
`

Components

$3

#### Button
- Versatile button component with multiple variants, sizes, and states
- Props: variant (primary, secondary, etc.), size, radius, loading, disabled, text, icon
- Supports icons, loading states, and router links
- Customizable appearance with classList and iconConfig

#### Badge
- Lightweight label component for tagging and highlighting
- Props: color, text, icon, iconPosition, size
- Supports custom icons (Iconsax) with color customization
- Flexible sizing and styling

#### Text
- Typography component for consistent text styling
- Supports various text sizes and font weights
- Built for semantic HTML and accessibility

#### Iconsax
- Icon component wrapper for Iconsax icon library
- Props: name, color, size, type (linear, outline, bold, bulk, broken, two-tone)
- Seamless integration with other components

#### IconsaxFont
- Alternative Iconsax implementation using font-based icons

#### Tabs
- Tab navigation component with animated indicator
- Features: Smooth sliding indicator, responsive spacing, customizable colors
- Generic TypeScript support for flexible tab data structures
- Props: tabs, indicatorColor, spacing
- v-model support for active tab state

#### Dropdown
- Dropdown/menu component for filtering and selection
- Customizable trigger and menu items
- Position-aware placement

#### Pagination
- Navigation component for paginated content
- Props: currentPage, totalPages, pageSize
- Event handlers for page changes

#### DurationTimeline
- Timeline visualization component
- Ideal for showing time-based events or durations
- Customizable styling and event markers

#### DataGrid
- Enterprise-grade data table component (requires DevExtreme)
- Full support for sorting, filtering, paging
- Exported separately to keep main bundle lightweight

Inputs

Located in src/components/inputs/, these form control components provide flexible input handling:

#### Input
- Basic text input field
- Props: placeholder, disabled, readonly, type, value
- Validation support with Error component
- Full accessibility features

#### Select
- Dropdown select component
- Props: options, modelValue, placeholder, disabled, multiple
- Type-safe with SelectOptionType interface
- Supports custom slots for option rendering

#### DateInput
- Date picker component
- Built-in calendar UI
- Customizable date format
- Min/max date validation support

#### CountryCode
- Specialized select for country code selection
- Pre-populated with country data
- Flag emoji display support
- Props: modelValue for selected country code

#### RadioGroup
- Radio button group component
- Props: options, modelValue
- Grouped radio options for single selection
- Supports custom styling

#### Label
- Form label component
- Associated with form inputs via for attribute
- Proper accessibility support

#### Error
- Error message display component
- Integrates with form validation
- Styling for error states

Overlays

Located in src/components/overlays/, these modal and panel components:

#### Dialog
- Modal dialog component for important user interactions
- Features: Backdrop overlay, close on escape, customizable content
- Props: title, visible, closable, backdropClosable
- Slot-based content structure

#### Drawer
- Side panel component sliding from edge
- Props: title, visible, position (left, right, top, bottom)
- Similar slot structure to Dialog
- Smooth animations and transitions

#### Heading
- Dialog/Drawer title component
- Semantic heading element with consistent styling

Directives

$3


- Tooltip directive for displaying contextual help text
- Usage:
`vue
Hover me

Hover me
`
- Modifiers: .top, .bottom, .left, .right, .auto
- Sub-modifiers: .start, .end (for positioning variants)
- Props: delay, offset, class, placement
- Default z-index: 100000 (high stacking context)
- Features: Smooth transitions, arrow indicator, customizable styling

$3

- Core tooltip class implementation
- Uses PopperJS for intelligent positioning
- Handles show/hide logic with delay support

Composables

Located in src/components/composables/, reusable Vue 3 Composition API utilities:

$3


- Detects clicks outside of a DOM element
- Usage:
`ts
const elementRef = ref()
useOutsideClick(elementRef, () => {
// Handle outside click
})
`
- Useful for closing dropdowns, modals, and menus

$3

- Manages overlay/modal state and behavior
- Handles backdrop interaction logic

$3

- Detects and reacts to window scroll events
- Props: element, callback, options
- Useful for lazy loading and infinite scroll patterns

Styling & CSS

The library includes comprehensive CSS organization:

$3

- Main stylesheet
- Contains base styles, resets, and Tailwind imports
- One-time import in app entry point

$3

- Tooltip-specific styles
- Classes: .h-tooltip, .vue-tooltip-hidden, .vue-tooltip-visible
- Includes arrow styling and placement modifiers
- Z-index: 100000

$3

- Vue transition classes
- Smooth animations for component entry/exit

$3

- Datepicker calendar styling
- Integration with DateInput component

$3

- DevExtreme DataGrid styling customizations
- Required when using DataGrid component

Types

Located in src/types/, comprehensive TypeScript definitions:

- button-types.ts - Button variant and size enums
- text-types.ts - Typography type definitions
- iconsax-types.ts - Icon name types
- dev-express-types.ts - DataGrid type definitions
- index.ts - Core interface definitions (e.g., SelectOptionType)
- components.d.ts - Vue component auto-registration types
- vue.d.ts - Vue augmentation types

Development

Common development tasks (scripts available in package.json):

`bash


Start dev server with Vite

npm run dev

or with Bun

bun run dev

Build library for production

npm run build

Type check entire codebase

npm run type-check

Preview production build locally

npm run preview
`

$3

`
src/
├── components/ # Vue components
│ ├── inputs/ # Form input components
│ ├── overlays/ # Modal/panel components
│ ├── composables/ # Vue 3 Composition API utilities
│ ├── examples/ # Component usage examples
│ └── *.vue # Core components
├── directives/ # Vue directives (tooltip)
├── types/ # TypeScript type definitions
├── css/ # Stylesheets
│ ├── styles.css
│ ├── tooltip.css
│ ├── transition.css
│ └── vue-datepicker.css
├── utils/ # Utility functions (currently empty)
├── index.ts # Main entry point
└── example.ts # Example usage
`

$3

The library builds to dist/ with:
- dist/index.js - ES Module
- dist/index.cjs - CommonJS
- dist/index.d.ts - Type Definitions
- dist/styles.css - Compiled Styles

$3

- vite.config.ts - Vite build configuration
- tailwind.config.js - Tailwind CSS configuration
- tsconfig.json - TypeScript configuration
- package.json - Dependencies and scripts

Contributing

Contributions are welcome! Typical workflow:

1. Fork the repository and create a feature branch
2. Install dependencies and run the dev server:
`bash
npm install
npm run dev
`
3. Make your changes to components, directives, or utilities
4. Add examples or update component documentation
5. Run type checker to ensure no TypeScript errors:
`bash
npm run type-check
``
6. Test your changes in the dev environment
7. Open a Pull Request with a clear description of changes

$3

Please ensure:
- All TypeScript errors are resolved
- Components follow existing patterns and conventions
- Props are properly typed with interfaces
- Documentation comments are added for complex logic
- CSS follows Tailwind utility-first approach with logical properties (RTL-safe)

License

MIT

---

For questions, feature requests, or bug reports, please open an issue on the repository.