npm package: @maropost-ui/liquidsky-ui
Description: Shared UI components, composables, and utils for Vue + Vuetify
Latest version: 0.1.25

# @maropost-ui/liquidsky-ui

A shared UI component library, composables, and utilities for Vue 3 + Vuetify applications. This package provides reusable components and common functionality to accelerate development across multiple frontend applications.


[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![Vue 3](https://img.shields.io/badge/Vue-3.5-green.svg)](https://vuejs.org/)
[![Vuetify](https://img.shields.io/badge/Vuetify-3.7-purple.svg)](https://vuetifyjs.com/)
[![vue Router](https://img.shields.io/badge/vue--router-4.4.5-orange.svg)](https://router.vuejs.org/)


## Features

- **🎨 UI Components**: Pre-built, accessible Vue components built with Vuetify
- **🔧 Composables**: Reusable Vue 3 composition API functions
- **📦 Directives**: Custom Vue directives for enhanced functionality
- **📝 TypeScript Support**: Full TypeScript definitions and type safety
- **📖 Documentation**: Auto-generated component documentation

## Peer Dependencies

The following packages are required as peer dependencies:

- `vue` (^3.5.11) - Vue.js framework
- `vue-router` (^4.4.5) - Vue router
- `date-fns-tz` (^3.2.0) - Date utilities with timezone support
- `lz-string` (^1.5.0) - String compression library

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


## Quick Start

```bash
npm install @maropost-ui/liquidsky-ui
```
```typescript
import { AppBreadcrumb } from '@maropost-ui/liquidsky-ui'
```

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


## @maropost-ui/liquidsky-ui Local Development Guide
Use these methods to test @maropost-ui/liquidsky-ui changes in your consuming project (e.g., commerce-frontend or commerce-backoffice) without publishing to npm. Both leverage npm's linking and packaging features for rapid iteration in your app workflow.



### 🚀 Method 1: npm link (Recommended for Active Development)
Creates a symlink for instant hot-reloading of changes.

> **Note:** This method does **not** work well with Webpack. If you are using Vite, this is the preferred approach. Otherwise, use Method 2.

#### Steps:

1. **Clone the repository:**
   ```bash
   git clone <repo-url> liquidsky-frontend
   cd liquidsky-frontend
   git checkout main
   ```

2. **Install dependencies and build the package:**
   ```bash
   npm install
   npm run dev
   ```

3. **Create a local npm link:**
   ```bash
   npm link
   ```

4. **In your consuming project (e.g., `commerce-frontend`):**
   ```bash
   cd /path/to/your/consuming-project
   npm link @maropost-ui/liquidsky-ui
   ```

Now, any changes you make in the `liquidsky-frontend` package will be reflected in your consuming project after rebuilding the library. This is useful for rapid development and testing across multiple projects locally.

### 📦 Method 2: Local npm pack (For Stable Builds)
Generates a distributable .tgz file for one-off installs.

#### Step 1: Clone and build the library
```bash
git clone <repo-url> liquidsky-frontend
cd liquidsky-frontend
git checkout main
npm install
npm run build
```
#### Step 2: Create package
```bash
npm pack
Creates liquidsky-ui-<version>.tgz.
```

#### Step 3: Install in consuming project
```bash
cd /path/to/commerce-backoffice  # or your project
npm install ../../path/to/liquidsky-frontend/liquidsky-ui-<version>.tgz
```

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


## Updating and Publishing Liquidsky Package with npm

### ✅ 1. Commit changes including version update

Before publishing, make sure everything is committed and pushed to your
`main` branch.

-   Update your code
-   Then update the version in `package.json`

You can do it manually or run:

``` bash
npm version patch --no-git-tag-version   # bug fixes
npm version minor --no-git-tag-version   # new features
npm version major --no-git-tag-version   # breaking changes
```
- Then run `npm run changelog:generate` to generate `changelog.md` file

Commit and push everything:

``` bash
git add .
git commit -m "feat: update package (vX.X.X)"
git push origin main
```


### ✅ 2. Login to npm

If not already logged in:

``` bash
npm login
```

### ✅ 3. Publish your package

Run:

``` bash
npm publish
```

For scoped packages:

``` bash
npm publish --access public
```


✅ That's it --- your changes are now live.

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


## Documentation

This package features automated Storybook documentation that stays synchronized with your components and keeps docs always up-to-date with your code.

```bash 
# Start Storybook dev server (recommended for development)
npm run storybook

# Build Storybook for static deployment
npm run storybook:build
```

Default URL: http://localhost:6006

### 📂 Story Organization

```
stories/
├── custom-components/   # Component stories
│   ├── AppBreadcrumbs.stories.ts
│   └── AppDropdown.stories.tsx
├── composables/         # Composables stories
|── Directive 
|── vuetify-components   # All vuetify component stories 
├── utils/               # Utility stories
```

## Best Practices for Auto-Documentation

### 1. Use JSDoc Comments

```typescript
/**
 * @description Search functionality composable with route integration
 * @example
 * ```typescript
 * const { keyword, submitSearch } = useSearch()
 * submitSearch()
 * ```
 */
export function useSearch(): SearchInterface
```

### 2. Document Component Props

```typescript
export interface SearchBarProps {
  /** Search placeholder text */
  placeholder?: string
  /** Enable automatic route integration */
  useRouteIntegration?: boolean
}
```

### 3. Provide Usage Examples

```vue
<!--
Usage Example:
<TheSearchBar 
  placeholder="Search products..."
  @search="handleSearch"
/>
-->
```

### 4. Use TypeScript Types

```typescript
// Explicit return types help documentation
export function useValidation(): ValidationInterface {
  // ...
}
```

## Contributing

1. Follow the existing code style and patterns
2. Add JSDoc comments for new functions and components
3. Update this README when adding new features
4. Ensure all components are properly typed with TypeScript