npm package: @grandbazar/ui-baza
Description: A lightweight and modular UI kit for building modern, accessible web interfaces. Designed for flexibility, scalability, and developer happiness.
Author: grandbazar
Latest version: 1.2.6

# UI Baza

A lightweight and modular UI kit for building modern, accessible web interfaces. Designed for flexibility, scalability, and developer happiness.

## 📦 Installation

```bash
npm install @grandbazar/ui-baza
```

```bash
yarn add @grandbazar/ui-baza
```

```bash
pnpm add @grandbazar/ui-baza
```

## 🔧 Usage

```tsx
import { Button } from '@grandbazar/ui-baza';

function App() {
  return (
    <Button onClick={() => alert('Hello!')}>
      Click me
    </Button>
  );
}
```

### CSS Import

**Important:** UI Baza uses CSS cascade layers for proper style isolation. Import the styles with the lowest priority to allow your local variables to override library defaults:

```css
@layer ui_baza_reset, ui_baza_tokens, base, theme, ui_baza_components, components, utilities;

@import '@grandbazar/ui-baza/css';
```

### Customizing Design Tokens

You can override the default design tokens by defining your own CSS variables after importing the library:

```css
:root {
  /* Override color tokens */
  --color-neutral: #1a1a1a;
  --color-accent: #0066ff;
  
  /* Override radius tokens */
  --radius-xs: 4px;
  --radius-sm: 6px;
  --radius-md: 8px;
  --radius-lg: 10px;
  --radius-xl: 12px;
  --radius-2xl: 14px;
  --radius-3xl: 16px;
  --radius-4xl: 24px;
  --radius-5xl: 32px;
  --radius-tooltip: 10px;
  --radius-content-xl: 24px;
  --radius-content-lg: 18px;
  --radius-content-md: 16px;
  --radius-content-sm: 14px;
  --radius-content-xs: 12px;
  --radius-image-xl: 18px;
  --radius-image-lg: 16px;
  --radius-image-md: 14px;
  --radius-image-sm: 12px;
  --radius-image-xs: 10px;
  --radius-image-2xs: 8px;
  --radius-image-3xs: 6px;
}
```

## 🛠️ Development

### Prerequisites

- Node.js 22+
- npm/yarn/pnpm

### Getting Started

```bash
# Clone the repository
git clone https://gitlab.itglobal.com/itgold/gb/ui-baza.git

# Install dependencies
npm install

# Start Storybook for development
npm run dev
```

### Available Scripts

- `npm run dev` - Starts the local Storybook server, use this to develop and preview your components.
- `npm run start` - Start Storybook server from built static files.
- `npm run test` - Runs all your tests with vitest.
- `npm run test:watch` - Runs tests in watch mode.
- `npm run build:lib` - Builds your component library with Vite.
- `npm run build:storybook` - Builds your Storybook as a static web application.
- `npm run lint` - Run ESLint.
- `npm run format` - Format code with Prettier.
- `npm run prepare` - Setup Husky git hooks.
- `npm run version:patch` - Bump patch version.
- `npm run version:minor` - Bump minor version.
- `npm run version:major` - Bump major version.
- `npm run prepare:publish` - Build the library for publishing.
- `npm run publish:public` - Publish to npm with public access.
- `npm run release` - Complete release workflow: build, commit, push, and publish.

### Building

```bash
npm run build:lib
```

## 📚 Components

Currently available components:

- **Badge** - Compact label component for statuses, counts, and tags with various visual styles.
- **Breadcrumbs** - Navigation component showing the user's location within the site hierarchy with support for custom separators. Implemented using Compound Components pattern.
- **Button** - Flexible button component with various styles and states.
- **Checkbox** - Custom checkbox with state support, custom labels, and full styling.
- **Chip** - Compact element for displaying tags, filters, or selections.
- **Counter** - Compact visual indicator for displaying short numeric values like notification counts, unread messages, or status badges.
- **DatePicker** - Flexible date picker component with calendar interface, date ranges, and internationalization support. Implemented using Compound Components pattern.
- **DropdownMenu** - Flexible dropdown menu with support for submenus, custom triggers, and rich content. Implemented using Compound Components pattern.
- **RadioButton** - Radio button component for single selection from multiple options.
- **Search** - Search input field with icon and clear button. Supports two modes: default (inline icon) and custom (separate search button).
- **SegmentControl** - Segmented control component for single selection from multiple options with visual button group interface. Implemented using Compound Components pattern.
- **Switch** - Toggle switch component for binary on/off states with smooth animations.
- **Tag** - Elements for visual marking using keywords. Help with quick recognition, differentiation, and sorting or navigation through content.
- **TextField** - Input field component with validation, labels, and various input types support. Implemented using Compound Components pattern.
- **Pagination** - Navigation component for multi-page content with customizable appearance and behavior.
- **ProgressBar** - Progress indicator component with linear and step-based variants. Supports multiple sizes and full ARIA accessibility. Implemented using Compound Components pattern.
- **Tooltip** - Lightweight tooltip component for contextual hints and helper text.

More components coming soon! 🎉

## 🎨 Icons

All icons are exported from `@grandbazar/ui-baza` and accept standard SVG props (`React.SVGProps<SVGSVGElement>`):

- **IconArrow** - Arrow for direction and navigation.
- **IconArrowCircle** - Arrow in a circle for compact actions.
- **IconArrowCircleUp** - Up arrow in a circle for scroll-to-top actions.
- **IconArrowDiagonal** - Diagonal arrow for external links.
- **IconArrowUTurn** - U-turn arrow for return/undo style actions.
- **IconBell** - Notification icon.
- **IconBox** - Box/package icon for products and inventory.
- **IconCalendar** - Date and schedule icon.
- **IconCharacteristic** - Generic attribute/specification marker.
- **IconCheck** - Confirmation checkmark.
- **IconCheckCircle** - Checkmark in a circle for success states.
- **IconChevron** - Chevron for dropdowns and directional hints.
- **IconChevronDouble** - Double chevron for fast navigation.
- **IconClock** - Time/duration icon.
- **IconCollapse** - Collapse/expand state icon.
- **IconCopy** - Copy/duplicate action icon.
- **IconDots** - "More actions" menu icon.
- **IconDownload** - Download action icon.
- **IconEye** - Visibility and preview icon.
- **IconFace** - Face/emotion icon for feedback states.
- **IconFile** - File/document icon.
- **IconFilters** - Filter controls icon.
- **IconGear** - Settings/configuration icon.
- **IconHanger** - Catalog/fashion category icon.
- **IconHome** - Main page/navigation root icon.
- **IconInfo** - Informational hint icon.
- **IconLogOut** - Sign-out action icon.
- **IconMail** - Email/message icon.
- **IconMinus** - Remove/decrease action icon.
- **IconOneCircle** - Number marker in a circle.
- **IconPerson** - User/profile icon.
- **IconPhone** - Phone/call icon.
- **IconPlus** - Add/increase action icon.
- **IconPrize** - Reward/bonus icon.
- **IconProject** - Project/layers icon.
- **IconQRCode** - QR code icon.
- **IconRequest** - Request/workflow icon.
- **IconResizeCorner** - Corner resize handle icon.
- **IconScan** - Scan/recognition icon.
- **IconSearch** - Search icon.
- **IconShopping** - Shopping/cart icon.
- **IconSort** - Sort icon.
- **IconStar** - Favorite/rating icon.
- **IconSticker** - Label/sticker icon.
- **IconStop** - Stop/cancel action icon.
- **IconSwitch** - Toggle/switch state icon.
- **IconXMark** - Close/remove icon.
- **IconXMarkCircle** - Close icon in a circle.
- **IconLogo** - Brand icons namespace.

### Icon Variants

Some icons provide variants via Compound Components pattern, for example:

- **IconArrowCircleUp.Filled** - Filled scroll-up action variant.
- **IconArrowDiagonal.Up** - Upward diagonal direction variant.
- **IconEye.Off** - Visibility-off/hidden state variant.
- **IconFace.Sad** - Negative feedback/emotion variant.
- **IconFace.Smile** - Positive feedback/emotion variant.
- **IconXMark.Small** - Compact close icon for tight layouts.

Brand icons are available under `IconLogo`:

- **IconLogo.Google** - Google brand mark.
- **IconLogo.Telegram** - Telegram brand mark.
- **IconLogo.VK** - VK brand mark.
- **IconLogo.Yandex** - Yandex brand mark.

```tsx
import { IconCheck, IconShopping, IconFace, IconLogo } from '@grandbazar/ui-baza';

function Example() {
  return (
    <div>
      <IconCheck style={{ color: 'green', width: 16, height: 16 }} />
      <IconShopping style={{ color: 'blue', width: 20, height: 20 }} />
      <IconShopping.Filled style={{ color: 'red', width: 24, height: 24 }} />
      <IconFace.Sad style={{ color: '#6b7280', width: 24, height: 24 }} />
      <IconLogo.Google style={{ width: 24, height: 24 }} />
    </div>
  );
}
```

All icons use `currentColor` for easy theming and styling.

## 🔗 Links

- [Homepage](https://grandbazar.io/ui-baza)
- [Repository](https://gitlab.itglobal.com/itgold/gb/ui-baza)
- [Grandbazar](https://grandbazar.io)

## 📄 License

MIT © [Grandbazar](https://grandbazar.io)