ds-smart-ui/README.md

Smart UI v1.0.5 — A production-ready React component library by PT Praisindo Teknologi. Covers inputs, navigation, data display, feedback, and layout with a unified design system, semantic Typography tokens, and full Storybook documentation.

<p><a target="_blank" href="https://app.eraser.io/workspace/zznMZKW2bQwnN4EatpJw" id="edit-in-eraser-github-link"><img alt="Edit in Eraser" src="https://firebasestorage.googleapis.com/v0/b/second-petal-295822.appspot.com/o/images%2Fgithub%2FOpen%20in%20Eraser.svg?alt=media&token=968381c8-a7e7-472a-8ed6-4a6626da5501"></a></p>

# Smart UI — React Component Library

> **PT Praisindo Teknologi** — Design System for modern React applications

[![npm latest](https://img.shields.io/npm/v/ds-smart-ui/latest?label=v1.0.5%20%28latest%29&color=blue)](https://www.npmjs.com/package/ds-smart-ui)
[![npm legacy](https://img.shields.io/npm/v/ds-smart-ui/legacy?label=v0.3.x%20%28legacy%29&color=gray)](https://www.npmjs.com/package/ds-smart-ui/v/legacy)
[![license](https://img.shields.io/npm/l/ds-smart-ui)](LICENSE)

---

## Versions

This package ships two long-term versions on the same npm package name:

| Tag | Version | Branch | Install |
|---|---|---|---|
| `latest` | **v1.0.5** | `main` | `npm install ds-smart-ui` |
| `legacy` | **v0.3.22** | `legacy` | `npm install ds-smart-ui@legacy` |

> **Existing projects on `^0.3.x` are safe** — npm semver will not auto-upgrade to v1.0.0 across a major version boundary.

---

## Installation

### v1.0.0 (Recommended — new projects)

```bash
npm install ds-smart-ui
```

### v0.3.22 (Legacy — existing projects)

```bash
npm install ds-smart-ui@legacy
# or pin to exact version
npm install ds-smart-ui@0.3.22
```

Import the stylesheet once at your app's entry point (both versions):

```js
import "ds-smart-ui/dist/style.css";
```

---

## Usage

```tsx
import { Button, Typography, CardTabs, Tabs } from "ds-smart-ui";

export default function App() {
  return (
    <>
      <Typography variant="h5" weight="bold">Hello Smart UI</Typography>
      <Button variant="contained" color="primary">Click me</Button>
    </>
  );
}
```

---

## What's New in v1.0.0

### Typography — Semantic variant system

Variant names are now semantic and consistent. Deprecated compound names (`b14Bold`, `b16`, `h6Bold`, etc.) are replaced with a `variant` + `weight` prop pair.

```tsx
// ✅ v1.0.0 — new
<Typography variant="body-md" weight="bold">Text</Typography>
<Typography variant="h6" weight="bold">Heading</Typography>

// ❌ v0.3.x — deprecated (still works but will warn)
<Typography variant="b14Bold">Text</Typography>
<Typography variant="h6Bold">Heading</Typography>
```

**Full variant mapping:**

| Old (v0.3.x) | New (v1.0.0) |
|---|---|
| `b14` | `variant="body-md"` |
| `b14Bold` | `variant="body-md" weight="bold"` |
| `b14Medium` | `variant="body-md" weight="medium"` |
| `b16` | `variant="body-lg"` |
| `b16Bold` | `variant="body-lg" weight="bold"` |
| `b12` | `variant="body-sm"` |
| `b10` | `variant="body-xs"` |
| `b8` | `variant="body-2xs"` |
| `h6Bold` | `variant="h6" weight="bold"` |
| `h5Bold` | `variant="h5" weight="bold"` |

---

### Checkbox — `variant` prop

New `variant` prop for button-like checkbox appearance:

```tsx
// Contained (default) — solid fill on check
<Checkbox variant="contained" color="primary" />

// Outlined — colored border, light bg on check
<Checkbox variant="outlined" color="primary" />
```

---

### ButtonGroup — `iconOnly` mode

Compact icon-only toggle group, perfect for grid/list view switchers:

```tsx
<ButtonGroup
  iconOnly
  outlined
  value={view}
  onChange={setView}
  options={[
    { id: "grid", label: "Grid View", icon: <Grid2X2 size={22} /> },
    { id: "list", label: "List View", icon: <List size={22} /> },
  ]}
/>
```

---

### CardTabs — `layout="icon-card"` mode

Vertical card layout with large icon box and centered label — ideal for file format pickers, payment method selectors:

```tsx
<CardTabs
  layout="icon-card"
  outlined
  selectedTab={tab}
  onTabChange={setTab}
  tabs={[
    { label: "Excel (.xlsx)", selectedTab: "xlsx", icon: <FileIcon />, permissions: true },
    { label: "PDF",           selectedTab: "pdf",  icon: <PdfIcon />,  permissions: true },
  ]}
/>
```

---

### Tabs — `size` and `tabRounded` props

Control tab button size and shape, plus improved hover/active badge state:

```tsx
// Underline style (default)
<Tabs tabs={tabs} selectedTab={tab} onTabChange={setTab} type="transparent" size="md" />

// Pill shape (scrollable chips)
<Tabs tabs={tabs} selectedTab={tab} onTabChange={setTab} type="soft" tabRounded="full" />

// Outlined cards
<Tabs tabs={tabs} selectedTab={tab} onTabChange={setTab} type="outlined" tabRounded="lg" />
```

Badge color adapts automatically: gray when inactive → outlined circle on hover → gray when active.

---

## Migration Guide (v0.3.x → v1.0.0)

### 1. Update Typography variants

Run a find-and-replace across your codebase:

| Find | Replace |
|---|---|
| `variant="b14"` | `variant="body-md"` |
| `variant="b14Bold"` | `variant="body-md" weight="bold"` |
| `variant="b16Bold"` | `variant="body-lg" weight="bold"` |
| `variant="h6Bold"` | `variant="h6" weight="bold"` |
| `variant="h5Bold"` | `variant="h5" weight="bold"` |

### 2. Checkbox `variant` default change

The `variant` prop default changed from `"default"` to `"contained"`. If you relied on the old plain appearance, add `variant="outlined"` or remove the prop entirely — `"contained"` is visually richer and is now the default.

### 3. No other breaking changes

All other components, props, and CSS tokens are backward compatible between v0.3.x and v1.0.0.

---

## Components

### Inputs
`Button` · `IconButton` · `TextField` · `NumberField` · `TextArea` · `Select` · `Select2` · `Checkbox` · `Radio` · `ToggleSwitch` · `DatePicker` · `DateRangePicker` · `UploadZone` · `Toolbar` · `AdvancedToolbar` · `ButtonGroup` · `SearchBar`

### Navigation
`Tabs` · `TabButton` · `CardTabs` · `Wizard` · `Drawer` · `DropdownMenu` · `Sidebar` · `Header`

### Data Display
`DataTable` · `Typography` · `Badge` · `Icon` · `SvgIcon` · `Divider` · `ListViewLabel`

### Feedback
`Alert` · `Dialog` · `DialogAction` · `DialogCheck` · `Skeleton`

### Surfaces
`Card` · `Box` · `Grid` · `Stack` · `Container` · `Scrollable`

### Theme
`ThemeProvider` · `generateColorPalette`

---

## Icons

We recommend [Lucide Icons](https://lucide.dev):

```bash
npm install lucide-react
```

```tsx
import { IconButton } from "ds-smart-ui";
import { X } from "lucide-react";

<IconButton iconStart={<X />} onClick={() => {}} />
```

---

## Changelog

### v1.0.4 — 17 July 2026

**Changes**
- **TabButton** — added backward compatibility for `size="xl"` (maps to `lg`)

---

### v1.0.3 — 17 July 2026

**New**
- **Badge** — `dot` prop: shows a small dot indicator on the left side of the badge. Dot size scales with badge size (6px sm, 8px md, 10px lg).
- **Component Size Guidelines** — standardized all component sizes across the design system:
  - **Tabs**: lg=52px/md, md=40px/sm, sm=38px/xs
  - **Button**: lg=56px/md, md=44px/sm, sm=36px/xs
  - **Badge**: lg=26px/sm, md=24px/xs, sm=22px/xxs
  - **Toggle Switch**: lg=32px, md=24px, sm=20px
  - **Radio/Checkbox**: lg=20px, md=16px, sm=14px
  - **Text Field**: lg=62px/md, md=52px/sm, sm=44px/xs (label always sm)

**Changes**
- **TabButton** — removed `xl` variant, updated lg/md/sm heights and font sizes
- **Button** — updated lg/md/sm heights and font sizes
- **Badge** — updated lg/md/sm heights and font sizes
- **Toggle Switch** — updated lg/md/sm heights and thumb sizes
- **Radio** — updated lg/md/sm sizes
- **Checkbox** — updated lg/md/sm sizes, default border-radius changed to `xs`
- **TextField/SearchBar/Select/Select2/TextArea/Autocomplete** — standardized font sizes (sm=xs, md=sm, lg=md)
- **DataTable Pagination** — "Rows per page" label font xs, pagination info font sm, pagination buttons height 36px with circle variant

---

### v1.0.2 — 8 July 2026

**Fixes**

- **Select2** — dropdown menu now renders as a floating portal (`menuPortalTarget={document.body}`, `menuPosition="fixed"`, `zIndex: 9999`) so opening it inside a Dialog/Modal no longer pushes modal content down or overlaps action buttons. Menu has its own internal scroll (`maxHeight: 220px`) independent of the dialog scroll.

---

### v1.0.1 — 8 July 2026

**New**
- **FilterChip** — new standalone component for rendering removable filter chips with label, icon, and onRemove support.

**Fixes**
- **AdvancedToolbar** — standardized border radius to `var(--border-radius-sm)` across filter button, column search, pending status select, and sort dropdown components for visual consistency.
- **ListViewLabel** — migrated to Typography `weight` props (`"bold"`, `"medium"`, `"regular"`) replacing deprecated compound variant names.

---

### v1.0.0 — 8 July 2026

**New**
- **Typography** — semantic variant system: `body-md`, `body-lg`, `body-sm`, `body-xs`, `body-2xs` + `weight` prop replaces deprecated compound names (`b14Bold`, `b16`, `h6Bold`, etc.)
- **Checkbox** — `variant` prop: `"contained"` (default, solid fill) and `"outlined"` (colored border, light bg) with soft shadow and `rounded` support
- **ButtonGroup** — `iconOnly` mode: compact icon-only toggle group with transparent inactive / solid primary active style; no border, `light-100` gray card background
- **CardTabs** — `layout="icon-card"` mode: vertical stacked layout (56×56 icon box + centered label); active icon box fills with `primary-500`; supports `fullWidth`
- **Tabs** — `size` prop (`"sm"` / `"md"` / `"lg"`); `tabRounded` prop for pill/card shapes; hover state with top-only `rounded-sm` bg; badge adapts (gray → outlined on hover → gray on active); active label is bold

**Breaking Changes**
- **Typography** — deprecated variant names (`b14`, `b14Bold`, `b16Bold`, `h6Bold`, etc.) emit console warnings. See [migration guide](#migration-guide-v03x--v100).
- **Checkbox** — `variant="default"` removed; use `"contained"` (same as new default) or `"outlined"`.

---

### v0.3.22 — 29 June 2026

**Fixes**
- **DialogAction** — fixed `flashMessage` variant title/description not staying centered for long, wrapping text.

---

### v0.3.21 — 24 June 2026

**Fixes**
- **DataTable** — fixed header cell content (label + sort icon) not respecting per-column `align` set via `muiTableHeadCellProps`.

---

### v0.3.20 — 22 June 2026

**Fixes**
- **DateRangePicker** — fixed double-calendar month navigation so the left and right panels always stay consecutive when clicking prev/next.
- **DateRangePicker** — consolidated double-calendar prev/next into a single pair of buttons.
- **DateRangePicker** — disabled the month/year label buttons in double-calendar mode.

---

### v0.3.19 — 17 June 2026

**Fixes**
- **Alert** — fixed layout when `title` is empty.

---

### v0.3.18 — 2 June 2026

**Fixes**
- **ThemeProvider / Theme** — synced `defaultTheme` typography font sizes to match `designTokens.css` exactly.
- **ListViewLabel** — increased CSS specificity for size modifiers.

---

### v0.3.17 — 26 May 2026

- **style**: normalize danger hex codes and update typography scale tokens
- **feat**: add action button support to `Alert` component

---

### v0.3.16 — 20 May 2026

- **feat**: add action grouping support and Markdown-style message formatting to `DialogAction`

---

### v0.3.15 — 18 May 2026

- **feat**: add `useLabelOnChip` support for dynamic chip labeling and fix `DataTable` selection column alignment

---

### v0.3.14 — 13 May 2026

**Optimizations**
- **DatePicker / DateRangePicker** — optimized UI compactness.

**Fixes**
- **DatePicker** — resolved dropdown width issue.
- **DateRangePicker** — updated minimum width constraints.

---

### v0.3.13 — 13 May 2026

**Fixes**
- **DatePicker / DateRangePicker** — implemented robust viewport constraint logic.
- **DateRangePicker** — migrated to portal-based rendering.

---

### v0.3.12 — 11 May 2026

**New Features**
- **DataTable** — added `dropdownAnchorOrigin` and `dropdownTransformOrigin` props.
- **DataTable** — implemented conditional tooltips for action buttons.

---

### v0.3.11 — 4 May 2026

**Fixes**
- **DatePicker / Autocomplete** — implemented portal-based rendering.
- **DatePicker** — added strict range validation.

---

### v0.3.10 — 27 April 2026

**Fixes**
- **Build / Dependencies** — resolved `eval` security warning in `lottie-web`.

**Optimizations**
- **Bundle Size** — reduced library bundle size by ~400kB.

---

### v0.3.9 — 16 April 2026

- **DataTable** — redesigned empty state with centered layout and customizable title/description.
- **DataTable** — implemented grouped property structures: `emptyState`, `retryButtonProps`.

---

### v0.3.8 — 14 April 2026

**New**
- **DataTable** — refined pagination layout.
- **Button / IconButton** — fully implemented `soft-outlined` variant for all color themes.

---

### v0.3.7 — 6 April 2026

**New**
- **Dialog** — added per-button color and variant props.

---

### v0.3.6 — 6 April 2026

**New**
- **AdvancedToolbar** — date filter chips auto-format ISO strings.
- **Utils** — added `formatDateYMD()` and `formatDateDisplay()` helpers.

---

### v0.3.5 — 30 March 2026

**New**
- **DataTable** — added `paginationRounded` prop.
- **UploadZone** — added `helperIcon` prop.

---

### v0.3.4 — 16 March 2026

**Fixes**
- **ButtonGroup** — fixed visual inconsistency for active + disabled state.

---

### v0.3.3 — 5 March 2026

**New**
- **AdvancedToolbar** — added `slotLeft` prop.
- **DateRangePicker** — added `customPresets` prop.

---

### v0.3.2 — 3 March 2026

**New**
- **Divider** — horizontal and vertical content separator.

**Accessibility**
- Added `aria-*` attributes across all input components, Tabs, Dialog, Button, Alert, Badge.

---

### v0.3.1 — 26 February 2026

**New**
- **DialogAction** — added status icons.
- **NumberField** — added `showRequired` prop.
- **ButtonGroup** — added `variant="tab"` with horizontal scroll.

---

### v0.3.0 — 24 February 2026

**New**
- **Dialog / DialogAction / DialogCheck** — added `rounded` prop.
- **DataTable** — added custom drag handle for column reordering.
- **Button** — added `soft-outlined` variant.

---

### v0.2.111 — 20 February 2026

**New**
- **Box**, **Grid**, **Stack**, **Container**, **Skeleton** — layout and utility components.
- **Select2** — debounced search input.
- **DialogCheck** — per-button variant, color, and rounded props.

---

### v0.2.110 — 12 February 2026

**New**
- **DataTable** — table footer with pagination and column pinning.
- **Select2** — pagination, infinite scroll, edit mode, and API-based search.

---

### v0.2.108 — 11 February 2026

**New**
- **validateProps** utility — type, range, pattern, and custom validator support.
- **ButtonGroup** — initial release.

---

### v0.2.107 — 10 February 2026

**New**
- **UploadZone** — drag-and-drop file upload with progress bar.
- **DialogAction** — added `children` slot for custom content.

---

### v0.2.106 — 26 January 2026

**New**
- **Drawer** — slide-in navigation drawer.
- **CardTabs / TabButton** — visual "pressed" state.

---

### v0.2.102 — 16 December 2025

**New**
- **ThemeProvider** — runtime theming with auto-generated palettes.
- **generateColorPalette()** utility.

---

### v0.2.101 — 2 December 2025

**New**
- Separated `required` and `showRequired` across all input components.

---

### v0.2.92 — 18 November 2025

**New**
- **Wizard** — sticky header, scroll spy, multi-action steps.

---

### v0.2.91 — 23 October 2025

**New**
- Smooth closing animations for `Dialog`, `DialogAction`, `DialogCheck`.

---

### v0.2.85 — 15 October 2025

**New**
- **DatePicker** and **DateRangePicker** — localization, double-calendar, quick presets, min/max validation.

---

### v0.2.65 — 2 September 2025

**New**
- **SmartDatePicker** — single/range date picker.
- **AdvancedToolbar** — active status switch, debounce search.

---

### v0.2.43 — 7 June 2025

**New**
- **HelperText** — shared helper/error text component.

---

### v0.2.33 — 16 May 2025

**New**
- **TextField** — show/hide toggle for password.
- **IconPicker** — SVG icon picker.

---

### v0.1.67 — 12 February 2025

**New**
- Design tokens — colors, font sizes, line-height, letter-spacing.

---

## License

MIT © [Anas Shofyan](https://github.com/anasshofyan) / PT Praisindo Teknologi

<!--- Eraser file: https://app.eraser.io/workspace/zznMZKW2bQwnN4EatpJw --->