portal-design-system 0.0.970 → 0.0.972

package/README.md

@@ -1,14 +1,41 @@
-
 # Portal Design System
 
-A type-safe Vue 3 UI component library built with Tailwind CSS and isolated styles for easy integration into projects.
+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](#features)
+- [Quick Overview](#quick-overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Components](#components)
+- [Inputs](#inputs)
+- [Overlays](#overlays)
+- [Directives](#directives)
+- [Composables](#composables)
+- [Styling & CSS](#styling--css)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#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 (prefixed utilities for isolation)
-- Language: TypeScript
-- Distribution: ESM / CJS + CSS + types
+- **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
 
@@ -20,11 +47,7 @@ npm install portal-design-system
 yarn add portal-design-system
 # or
 pnpm add portal-design-system
-```
-
-If you use Bun:
-
-```bash
+# or
 bun add portal-design-system
 ```
 
@@ -56,29 +79,32 @@ import { Button } from 'portal-design-system'
 
 ## Quick Start
 
-1. Import the compiled CSS (one-time in your app entry, e.g. `main.ts`):
+### 1. Import Styles (one-time in your app entry)
 
 ```ts
+// main.ts
 import 'portal-design-system/styles'
 ```
 
-2. Use components in your Vue app:
+### 2. Use Components in Your Vue App
 
 ```vue
 <script setup lang="ts">
-import { Button } from 'portal-design-system'
+import { Button, Input, Select } from 'portal-design-system'
 </script>
 
 <template>
-  <div class="portal-design-system">
-    <Button variant="primary">Primary</Button>
+  <div>
+    <Button variant="primary" text="Click Me" />
+    <Input placeholder="Enter text..." />
+    <Select :options="options" />
   </div>
 </template>
 ```
 
-### Web Components (optional)
+### 3. Optional: Web Components (Shadow DOM)
 
-The library can expose Web Components (Shadow DOM) for full style encapsulation. Register them when needed:
+For full style encapsulation with Web Components:
 
 ```html
 <script type="module">
@@ -89,62 +115,299 @@ The library can expose Web Components (Shadow DOM) for full style encapsulation.
 <pds-button variant="primary">Shadow Button</pds-button>
 ```
 
+## Components
+
+### Core Components
+
+#### **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
+
+### **v-tooltip**
+- Tooltip directive for displaying contextual help text
+- Usage:
+  ```vue
+  <button v-tooltip="'Help text'">Hover me</button>
+  <!-- or -->
+  <button v-tooltip="{ content: 'Help text', placement: 'top' }">Hover me</button>
+  ```
+- 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
+
+### **tooltip.ts**
+- 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:
+
+### **useOutsideClick**
+- Detects clicks outside of a DOM element
+- Usage:
+  ```ts
+  const elementRef = ref<HTMLElement>()
+  useOutsideClick(elementRef, () => {
+    // Handle outside click
+  })
+  ```
+- Useful for closing dropdowns, modals, and menus
+
+### **useOverlay**
+- Manages overlay/modal state and behavior
+- Handles backdrop interaction logic
+
+### **useWindowScroll**
+- 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:
+
+### **styles.css**
+- Main stylesheet
+- Contains base styles, resets, and Tailwind imports
+- One-time import in app entry point
+
+### **tooltip.css**
+- Tooltip-specific styles
+- Classes: `.h-tooltip`, `.vue-tooltip-hidden`, `.vue-tooltip-visible`
+- Includes arrow styling and placement modifiers
+- **Z-index:** 100000
+
+### **transition.css**
+- Vue transition classes
+- Smooth animations for component entry/exit
+
+### **vue-datepicker.css**
+- Datepicker calendar styling
+- Integration with DateInput component
+
+### **dev-express.css**
+- 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
+# Start dev server with Vite
 npm run dev
+# or with Bun
+bun run dev
 
-# Build library
+# Build library for production
 npm run build
 
-# Type check
+# Type check entire codebase
 npm run type-check
 
-# Preview production build
+# Preview production build locally
 npm run preview
 ```
 
-If you prefer Bun, you can run `bun` equivalents where appropriate.
-
-## Package Exports
-
-The package exposes the components and styles. Import styles directly with:
+### Project Structure
 
-```ts
-import 'portal-design-system/styles'
+```
+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
 ```
 
-Import components by name from the package root.
+### Build Output
 
-## Included Components (high level)
+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
 
-- `Button`
-- `Input`, `Select`, `CountryCode` (inputs)
-- `Tabs`, `Badge`, `Dialog`, `Dropdown`, `DataGrid`, `DurationTimeline`, `Text`, `Iconsax`
+### Configuration Files
 
-See the `src/components` folder for the full list and examples.
+- `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 repo and create a branch for your change.
-2. Install dependencies and run the dev server.
-3. Add tests or examples for new components.
-4. Open a PR with a clear description of your change.
-
-Please run the type checker before opening a PR:
-
-```bash
-npm run type-check
-```
+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
+
+### Before Submitting a PR
+
+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
 
 ---
-If you'd like any extra sections (changelog, CI badges, examples), tell me which details to include.
+
+For questions, feature requests, or bug reports, please open an issue on the repository.

package/dist/components/Pagination.vue.d.ts

@@ -2,6 +2,7 @@ import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOp
 type __VLS_Props = {
     total: number;
     maximumVisiblePages?: number;
+    allowedPageSizes?: (5 | 10 | 15 | 20 | 50)[];
 };
 type __VLS_PublicProps = {
     'take'?: number;