hazo_ui 2.8.1 → 2.11.0

package/CHANGE_LOG.md

@@ -0,0 +1,319 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.11.0] - 2026-05-16
+
+### Fixed
+- **Button inline-style fallback rendering as transparent** — the v2-era inline-style fallback used bare `var(--primary)` etc., which resolved to invalid CSS when consumers (per shadcn convention) store CSS variables as raw HSL channels (e.g. `--primary: 222.2 47.4% 11.2%`). All `Button` variants (default, destructive, outline, secondary) now wrap their fallback values in `hsl(...)`, matching the documented theme convention and Tailwind preset. Buttons rendered as transparent rectangles with text-only labels before this fix.
+- `destructive` variant's inline-style `color` switched from hardcoded `"white"` to `hsl(var(--destructive-foreground))` for theme consistency.
+
+### Notes
+- No API changes — pure visual fix. Consumers on the standard shadcn theme convention will see Buttons render correctly without any further changes.
+- Consumers who set CSS variables as full color values (hex/rgb) instead of HSL channels should override via the `style` prop (this was never the documented convention).
+
+## [2.10.0] - 2026-05-16
+
+### Added
+- **State primitives sub-module** — `Skeleton`, `SkeletonCircle`, `SkeletonBar`, `SkeletonRect`, `SkeletonGroup` with shimmer animation (respects `prefers-reduced-motion`).
+- `EmptyState` component (icon + title + description + action).
+- `ErrorBanner` component with `severity: 'warning' | 'error'`, auto icon, optional title/action/dismiss.
+- `ErrorPage` component for full-page error fallback (title, description, errorCode, correlationId, actions).
+- `LoadingTimeout` wrapper with 5s/15s/30s escalation (silent → gentle → firm → expired).
+- `ProgressiveImage` (grey → blur LQIP → sharp).
+- `HazoUiToaster` + `successToast(opts)` + `errorToast(opts)` imperative helpers — wraps `sonner`.
+- `useLoadingState()` hook — `{ isLoading, setLoading, withLoading }`.
+- `useErrorDisplay()` hook — passive `{ error, setError, clearError }`.
+
+### Changed
+- Added `sonner ^2.0.7` to dependencies.
+- Added `@keyframes hazo-shimmer` and `.hazo-shimmer` utility class to `src/styles/hazo-ui.css`.
+
+### Notes
+- All new components use shadcn semantic tokens (`bg-muted`, `bg-destructive`, etc.) and direct utility classes for amber tones (no `--warning` token assumed).
+- Components are exported flat & unprefixed from the top-level barrel — matches the existing `Button`/`Spinner`/`Card` convention.
+
+## [2.9.0] - 2026-05-12
+
+### Added
+- **Drawer primitive** (`src/components/ui/drawer.tsx`): vaul-backed bottom sheet component following the shadcn/ui Drawer pattern. Exports `Drawer`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`, `DrawerHeader`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`. Uses dynamic viewport units (`max-h-[96dvh]`) so iOS Safari's address-bar toggling doesn't crop the sheet.
+- **`useMediaQuery` hook** (`src/hooks/use_media_query.ts`): SSR-safe React hook returning whether a CSS media query matches. Re-renders on match changes. Use to fork mobile/desktop rendering (e.g. swap `Dialog` ↔ `Drawer` at `(max-width: 640px)`).
+- **New dependency**: `vaul@^1.1.2` (~6 KB gz, MIT). React/react-dom peers are already covered by hazo_ui's existing peer range.
+
+### Notes for consumers
+- The Drawer is intended for mobile bottom sheets. On desktop, prefer `Dialog`. Pattern:
+  ```typescript
+  import { Drawer, Dialog, useMediaQuery } from "hazo_ui";
+  const is_mobile = useMediaQuery("(max-width: 640px)");
+  const Shell = is_mobile ? Drawer : Dialog;
+  ```
+- Snap points, side-anchored drawers (`top`/`left`/`right`), and nested drawers are not in scope for this primitive — pass through to vaul's API directly if needed in the meantime.
+
+## [2.8.0] - 2026-05-11
+
+### Added
+- **shadcn/ui Primitive Re-exports (9 new primitives)**: AlertDialog, ButtonGroup, Card, Collapsible, ScrollArea, Separator, Spinner, Toggle, ToggleGroup
+  - All new primitives follow the existing shadcn/ui pattern and are re-exported from the package root
+  - Enables sibling hazo_* packages to import these UI primitives from a single source without managing separate Radix UI dependencies
+- **6 new Radix UI dependencies**: `@radix-ui/react-alert-dialog`, `@radix-ui/react-collapsible`, `@radix-ui/react-scroll-area`, `@radix-ui/react-separator`, `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group`
+
+### Fixed
+- **CardTitle ref type**: Corrected generic type from `HTMLParagraphElement` to `HTMLHeadingElement` — the rendered element is `<h3>` so the ref must be typed accordingly
+
+## [2.7.3] - 2026-05-10
+
+### Changed
+- **BREAKING (build/styling)**: Migrated internal build pipeline to **Tailwind CSS v4** (`tailwindcss@^4.2.4`).
+  - Replaced `tailwindcss-animate` with `tw-animate-css@^1.4.0`
+  - Replaced PostCSS plugins `tailwindcss + autoprefixer` with single `@tailwindcss/postcss` plugin (Lightning CSS handles vendor prefixing)
+  - Updated `src/styles/globals.css` to use Tailwind v4 entry: `@import "tailwindcss"` + `@import "tw-animate-css"` (replaces `@tailwind base/components/utilities`)
+  - Updated `tailwind.preset.js` to be v4-compatible (removed `tailwindcss-animate` plugin import)
+  - Bumped canonical workspace versions: `clsx@^2.1.1`, `tailwind-merge@^3.5.0`, `lucide-react@^0.553.0`, `typescript@^5.7.2`, `@types/react@^18.3.3`
+- Dev-app migrated to Tailwind v4 mirror of the library configuration
+- `HazoUiTextbox` / `HazoUiTextarea` test pages updated to use object-form `color` prop (`{ bg, fg, border }`) for prefixes — aligns with the production pill color model
+
+### Migration Notes for Consumers
+- If you use the published `tailwind.preset.js`, no API changes are required.
+- If you previously installed `tailwindcss-animate` for hazo_ui, replace it with `tw-animate-css` and load via `@import "tw-animate-css";` in your CSS.
+- Tailwind v4 consumers must keep the `@source "../node_modules/hazo_ui/dist";` directive (already documented).
+
+## [2.7.2] - 2026-03-31
+
+### Added
+- **HazoUiPillRadio**: Pill-shaped radio selection component
+  - Optional icons (react-icons compatible)
+  - Customizable accent colors per option
+  - Size variants (sm / md / lg)
+  - Horizontal or vertical layout
+  - Equal-width option for uniform pill widths
+  - Auto-fit vertical layout
+
+## [2.7.1] - 2026-03-27
+
+### Changed
+- **BREAKING**: Renamed `DialogVariant` value `'danger'` to `'destructive'` in HazoUiDialog for consistency with HazoUiConfirmDialog
+- Extracted shared `ANIMATION_PRESETS` and `resolve_animation_classes` into `src/lib/animations.ts` (used by both dialog components)
+- Removed dead `example_component` placeholder from source
+
+### Added
+- Re-exported `ANIMATION_PRESETS` and `resolve_animation_classes` from package root for consumer use
+- Added `.superpowers` and `design` to `.npmignore`
+
+### Removed
+- Unnecessary `esbuild` devDependency (tsup bundles its own)
+
+## [2.7.0] - 2026-03-26
+
+### Added
+- **HazoUiConfirmDialog**: Compact confirmation dialog with variant-driven styling
+  - Variant system: default, destructive, warning, info, success
+  - Accent top border colored by variant
+  - Async `onConfirm` with auto-loading state
+  - Configurable buttons (confirm + optional cancel)
+  - ReactNode children or simple description string
+  - Focus management: cancel button receives focus for destructive/warning variants
+- **shadcn/ui Primitive Re-exports**: All shadcn/ui base components now re-exported from hazo_ui
+  - Accordion, Button, Calendar, Checkbox, Command, DropdownMenu, HoverCard, Input, Label, Popover, RadioGroup, Select, Switch, Tabs, Textarea, Tooltip
+  - Enables sibling hazo_* packages to import UI primitives from a single source
+- New Radix UI dependencies: `@radix-ui/react-accordion`, `@radix-ui/react-checkbox`, `@radix-ui/react-dropdown-menu`, `@radix-ui/react-hover-card`
+
+## [2.6.6] - 2026-03-25
+
+### Fixed
+- Dialog title overlapping close button and not word-wrapping
+
+## [2.6.5] - 2026-03-24
+
+### Added
+- `fixedSize` prop on HazoUiDialog — when true, `sizeHeight` becomes a fixed height instead of maxHeight
+
+## [2.6.4] - 2026-03-23
+
+### Fixed
+- Button styling in dialog footer
+
+## [2.6.3] - 2026-03-22
+
+### Added
+- Dialog `variant` prop with preset color themes (info, success, warning, destructive)
+- Global `hazo_ui_config` system for theming buttons and headers
+- Per-component color override props
+
+## [2.6.2] - 2026-03-21
+
+### Added
+- Compositional Dialog API: re-exported shadcn/ui Dialog primitives as `HazoUiDialogRoot`, `HazoUiDialogContent`, etc. for complex layouts
+
+## [2.6.0] - 2026-03-20
+
+### Added
+- **HazoUiDialog**: Standardized dialog component with comprehensive features
+  - Standardized header/footer layout with customizable content area
+  - Flexible animation system (9 presets + custom Tailwind classes)
+  - Responsive sizing with viewport-relative dimensions
+  - Background overlay customization
+  - CSS variable-based theming
+  - Header bar mode with colored full-width header
+  - Loading state and custom footer content support
+
+## [2.5.2] - 2026-03-19
+
+### Added
+- Documentation updates for HazoUiDialog
+
+## [2.5.1] - 2026-03-18
+
+### Added
+- `instance_id` prop documentation for command components
+
+## [2.5.0] - 2026-03-17
+
+### Added
+- Multiple simultaneous command instances support
+
+## [2.4.0] - 2026-03-15
+
+### Added
+- **HazoUiCommand**: Headless command/mention system for Tiptap
+  - Command pill rendering with prefix-based colors
+  - Popover suggestion menu
+  - Multiple prefix support (@, #, /, etc.)
+  - `parse_commands_from_text` and `text_to_tiptap_content` utilities
+- **HazoUiTextbox**: Single-line input with command pill support
+- **HazoUiTextarea**: Multi-line input with command pill support
+
+## [2.3.0] - 2026-03-10
+
+### Added
+- **HazoUiRte**: Rich Text Editor component based on Tiptap v3
+  - Variable insertion system
+  - File attachment support
+  - HTML and plain text output modes
+  - Comprehensive toolbar with formatting options
+  - Font size and font family extensions
+- Tailwind preset type declarations (`tailwind.preset.d.ts`)
+
+### Fixed
+- SSR hydration issues
+
+## [2.2.0] - 2025-12-17
+
+### Added
+- **HazoUiMultiFilterDialog**: Added optional `title` prop (default: "Filter") to customize dialog title
+- **HazoUiMultiFilterDialog**: Added optional `description` prop (default: "Add multiple fields to filter by...") to customize dialog description
+- **HazoUiMultiSortDialog**: Added optional `title` prop (default: "Sort") to customize dialog title
+- **HazoUiMultiSortDialog**: Added optional `description` prop (default: "Add multiple fields to sort by...") to customize dialog description
+- **CommandItem**: Added hover styling (`hover:bg-accent hover:text-accent-foreground cursor-pointer`) for better user experience
+- **Documentation**: Added troubleshooting entries for dialog backdrop and dropdown styling issues
+
+**Design Decision**: The `title` and `description` props were added to provide better customization flexibility for different use cases. For example, a product filtering dialog might want to display "Filter Products" instead of the generic "Filter", making the interface more contextual and user-friendly. These props maintain backward compatibility by providing sensible defaults.
+
+## [2.1.2] - 2025-12-17
+
+### Added
+- Color support enhancements
+
+## [2.1.0] - 2025-12-17
+
+### Added
+- **HazoUiFlexInput**: New enhanced input component with type validation, character restrictions, and error messaging
+  - Supports multiple input types: mixed (text), numeric, alpha (letters only), and email
+  - Real-time character filtering for numeric and alpha types
+  - Validation on blur with clear error messages
+  - Numeric constraints: min/max value validation and decimal precision control
+  - Length constraints: configurable minimum and maximum character lengths
+  - Custom regex pattern support
+  - Optional format guide helper text
+  - Fully typed TypeScript interfaces
+
+**Design Decision**: HazoUiFlexInput extends the shadcn Input component to provide comprehensive validation without requiring external form libraries. The validation-on-blur approach prevents disruptive real-time error messages while users are typing, improving the overall user experience.
+
+## [2.0.0] - 2025-12-17
+
+### Added
+- **HazoUiFlexRadio**: New flexible radio button/icon selection component
+  - Support for single and multi-selection modes
+  - Layout options: horizontal or vertical
+  - Style variants: radio button style or icon-only button style
+  - Integration with react-icons library (supports 10+ icon sets: fa, md, hi, bi, ai, bs, fi, io, ri, tb)
+  - Label control with show/hide options
+  - Tooltips with 1-second delay
+  - Fully controlled component with value/onChange pattern
+  - TypeScript support with complete type definitions
+  - Accessibility features using Radix UI primitives
+
+**Design Decision**: HazoUiFlexRadio was designed to provide maximum flexibility for both traditional radio button interfaces and modern icon-based selection patterns. The dual-mode support (single/multi selection) reduces the need for separate checkbox implementations.
+
+## [1.0.0] - 2025-12-17
+
+### Added
+- **HazoUiMultiFilterDialog**: Multi-field filtering component
+  - Support for text, number, combobox, boolean, and date field types
+  - Operator support for number and date fields (equals, greater than, less than, etc.)
+  - Dynamic field addition and removal
+  - Built-in field validation for text length, number ranges, and decimal precision
+  - Visual feedback with active filters tooltip
+  - Clear all filters functionality
+  - Responsive design for mobile and desktop
+  - TypeScript support with complete interfaces
+  - Accessibility using Radix UI primitives
+
+- **HazoUiMultiSortDialog**: Multi-field sorting component with drag-and-drop
+  - Multiple sort fields with priority ordering
+  - Drag-and-drop reordering using @dnd-kit
+  - Direction toggle for each field (ascending/descending)
+  - Visual feedback during drag operations
+  - Clear all sorts functionality
+  - Tooltip display of active sort configuration
+  - Keyboard navigation support
+  - Responsive design
+  - TypeScript support
+  - Accessibility features
+
+- **Base UI Components**: Shadcn/ui components integration
+  - Button, Dialog, Command, Popover, Select, Input, Label, Switch, Tooltip, Calendar
+  - Tailwind CSS theming with CSS variable support
+  - Light and dark mode support
+
+- **Build Configuration**:
+  - tsup bundler for ESM + CJS outputs
+  - TypeScript declarations generation
+  - Tree-shakeable exports
+  - "use client" directive for Next.js compatibility
+
+- **Development Tools**:
+  - Storybook integration for component development
+  - Next.js dev app for integration testing
+  - TypeScript strict mode
+  - ESLint configuration
+
+**Design Decision**: The library was built on shadcn/ui and Radix UI primitives to ensure accessibility, maintainability, and consistency with modern React patterns. The choice of @dnd-kit for drag-and-drop provides excellent accessibility support compared to alternatives like react-beautiful-dnd.
+
+## [Unreleased]
+
+### Planned
+- Additional field types for filtering (time, datetime, multi-select)
+- Preset filter configurations for common use cases
+- Export/import filter configurations
+- Advanced sort options (null handling, case sensitivity)
+- Performance optimizations for large datasets
+
+---
+
+## Version History Reference
+
+- **2.7.3** - Tailwind v4 migration (internal build), tw-animate-css, canonical version sync
+- **2.7.2** - HazoUiPillRadio component
+- **2.7.1** - Rename 'danger' to 'destructive', extract shared animations, shadcn/ui re-exports
+- **2.7.0** - HazoUiConfirmDialog, shadcn/ui primitive re-exports
+- **2.6.x** - HazoUiDialog variants, compositional API, fixedSize, bug fixes
+- **2.5.x** - Multiple command instances, dialog docs
+- **2.4.0** - HazoUiCommand, HazoUiTextbox, HazoUiTextarea
+- **2.3.0** - HazoUiRte rich text editor
+- **2.2.0** - Customizable dialog titles and descriptions
+- **2.1.0** - HazoUiFlexInput component
+- **2.0.0** - HazoUiFlexRadio component
+- **1.0.0** - Initial release with filter and sort dialogs

package/README.md

@@ -202,6 +202,22 @@ The following components support both global config and prop-level color overrid
 
 - **[HazoUiConfirmDialog](#hazouiconfirmdialog)** - A compact, opinionated confirmation dialog with accent top border, variant system (destructive, warning, info, success), async loading support, and configurable buttons. Perfect for delete confirmations, unsaved changes warnings, and simple acknowledgments.
 
+- **[Drawer](#drawer)** - A `vaul`-backed bottom sheet primitive for mobile UIs. Pair with `useMediaQuery` to swap between `Dialog` and `Drawer` based on viewport width.
+
+### State Primitives (v2.10.0)
+
+Lightweight, opinionated components for the four ubiquitous async states: **loading**, **empty**, **error**, and **success**.
+
+- **[Skeleton](#skeleton)** family (`Skeleton`, `SkeletonCircle`, `SkeletonBar`, `SkeletonRect`, `SkeletonGroup`) - Shimmer placeholders. Respects `prefers-reduced-motion`.
+- **[EmptyState](#emptystate)** - Icon + title + description + CTA for empty lists, search misses, no-data screens.
+- **[ErrorBanner](#errorbanner)** - Inline `warning` or `error` strip with optional title, action button, and dismiss.
+- **[ErrorPage](#errorpage)** - Full-page error fallback with title, description, error code tag, correlation id, and CTAs.
+- **[LoadingTimeout](#loadingtimeout)** - Wraps a loading region and escalates messaging at 5s / 15s / 30s thresholds before showing a retry banner.
+- **[ProgressiveImage](#progressiveimage)** - Three-stage image render: grey placeholder → blurred LQIP → sharp final image.
+- **[HazoUiToaster + toast helpers](#toasts-hazouitoaster--successtoast--errortoast)** - `sonner`-backed toaster with `successToast()` and `errorToast()` imperative helpers.
+- **[useLoadingState](#useloadingstate)** hook - `{ isLoading, setLoading, withLoading }` with an async wrapper.
+- **[useErrorDisplay](#useerrordisplay)** hook - Passive `{ error, setError, clearError }` that coerces `Error` instances to strings.
+
 ### shadcn/ui Primitive Re-exports
 
 All shadcn/ui base components are re-exported from hazo_ui, so sibling hazo_* packages (and consumers) can import UI primitives from a single source without installing shadcn/ui separately:
@@ -2965,6 +2981,340 @@ function FormDialog() {
 | `footerClassName` | `string` | - | Footer CSS classes |
 | `showCloseButton` | `boolean` | `true` | Show X close button |
 
+## Drawer
+
+A vaul-backed bottom sheet primitive. Intended for mobile UIs; on desktop, prefer `Dialog`.
+
+```typescript
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerClose,
+  useMediaQuery,
+} from "hazo_ui";
+
+function Example() {
+  const is_mobile = useMediaQuery("(max-width: 640px)");
+
+  if (!is_mobile) {
+    // Render a Dialog instead on desktop
+    return null;
+  }
+
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <button>Open</button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Title</DrawerTitle>
+          <DrawerDescription>Optional description</DrawerDescription>
+        </DrawerHeader>
+        <DrawerFooter>
+          <DrawerClose asChild>
+            <button>Close</button>
+          </DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  );
+}
+```
+
+**Behavior:**
+- Drag the grab handle downward to dismiss
+- ESC closes
+- Click overlay to dismiss
+- `max-h-[96dvh]` keeps the sheet usable on iOS Safari when the address bar toggles
+- Focus trap, `aria-labelledby`, and background `aria-hidden` are wired automatically by vaul
+
+**Not yet supported (deferred):** snap points, side-anchored drawers, nested drawers.
+
+---
+
+## State Primitives
+
+Components and hooks for the four ubiquitous async states. All are exported flat (unprefixed) from the package root — `import { Skeleton, EmptyState, ErrorBanner, ErrorPage, LoadingTimeout, ProgressiveImage, HazoUiToaster, successToast, errorToast, useLoadingState, useErrorDisplay } from "hazo_ui"`.
+
+### Skeleton
+
+Shimmer placeholders for loading content. The shimmer animation respects `prefers-reduced-motion` (renders as a static grey block instead).
+
+```tsx
+import { Skeleton, SkeletonCircle, SkeletonBar, SkeletonRect, SkeletonGroup } from "hazo_ui";
+
+<SkeletonGroup label="Loading user profile">
+  <div className="flex items-center gap-3">
+    <SkeletonCircle size={40} />
+    <div className="flex-1 space-y-2">
+      <SkeletonBar width="60%" height={14} />
+      <SkeletonBar width="40%" height={10} />
+    </div>
+  </div>
+  <SkeletonRect height={120} radius={8} />
+</SkeletonGroup>
+```
+
+| Variant | Props |
+|---|---|
+| `Skeleton` | All standard `<div>` props. Base shimmer block. |
+| `SkeletonCircle` | `size?: number` (default 40), `className?: string` |
+| `SkeletonBar` | `width?: number \| string` (default "100%"), `height?: number` (default 12), `className?: string` |
+| `SkeletonRect` | `width?`, `height?`, `radius?: number \| string` (default 6), `className?: string` |
+| `SkeletonGroup` | `label?: string` (default "Loading content"), `children: ReactNode` — wraps a region with `role="status"` + `aria-busy` + visually-hidden label. |
+
+### EmptyState
+
+Standardized empty-list / no-data / no-results display.
+
+```tsx
+import { EmptyState, Button } from "hazo_ui";
+import { InboxIcon } from "lucide-react";
+
+<EmptyState
+  icon={<InboxIcon />}
+  title="No messages yet"
+  description="When you receive a message, it'll show up here."
+  action={<Button onClick={onCompose}>Send your first message</Button>}
+  size="md"
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | **required** | Main heading |
+| `icon` | `ReactNode` | — | Icon element (recommended 48×48) |
+| `description` | `ReactNode` | — | Secondary description |
+| `action` | `ReactNode` | — | CTA region (typically a `<Button>`) |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Visual size for inline cards (`sm`) vs full pages (`lg`) |
+| `className` | `string` | — | Additional classes |
+
+### ErrorBanner
+
+Inline error or warning strip. `role="alert"`, with `aria-live="assertive"` for errors / `"polite"` for warnings.
+
+```tsx
+import { ErrorBanner, Button } from "hazo_ui";
+
+<ErrorBanner
+  severity="error"
+  title="Couldn't save your changes"
+  message="We hit a network error. Your draft is safe locally."
+  action={<Button size="sm" onClick={onRetry}>Retry</Button>}
+  onDismiss={() => setBannerVisible(false)}
+/>
+
+<ErrorBanner severity="warning" message="Your session expires in 2 minutes." />
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `message` | `ReactNode` | **required** | Body text |
+| `severity` | `"warning" \| "error"` | `"error"` | Drives colour & icon |
+| `title` | `string` | — | Bold heading above the message |
+| `icon` | `ReactNode` | auto | Override the auto-selected `AlertTriangle` / `OctagonAlert` |
+| `action` | `ReactNode` | — | CTA region (typically a `<Button>`) |
+| `onDismiss` | `() => void` | — | When provided, renders a dismiss X button |
+| `className` | `string` | — | Additional classes |
+
+### ErrorPage
+
+Full-page error fallback, ideal for route-level error boundaries.
+
+```tsx
+import { ErrorPage, Button } from "hazo_ui";
+
+<ErrorPage
+  title="Something went wrong"
+  description="We couldn't load this page. The issue has been reported."
+  errorCode="500"
+  correlationId="req_a8f3c12e4d"
+  actions={
+    <>
+      <Button onClick={onRetry}>Try again</Button>
+      <Button variant="outline" onClick={onGoHome}>Go home</Button>
+    </>
+  }
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `"Something went wrong"` | Main heading |
+| `description` | `ReactNode` | — | Explanation paragraph(s) |
+| `errorCode` | `string` | — | Short symbolic code rendered as a tag (`"500"`, `"NOT_FOUND"`) |
+| `correlationId` | `string` | — | Correlation id (typically from `hazo_logs`) — rendered in a copyable mono block |
+| `actions` | `ReactNode` | — | CTA region |
+| `illustration` | `ReactNode` | `<OctagonAlert />` | Override the default icon |
+| `className` | `string` | — | Additional classes |
+
+### LoadingTimeout
+
+Wraps a loading region and escalates messaging if the load takes too long. Four phases:
+
+| Phase | When | What renders |
+|---|---|---|
+| `silent` | 0 – 5s | The provided `skeleton` (no message) |
+| `gentle` | 5s – 15s | Skeleton + "Loading {label}…" |
+| `firm` | 15s – 30s | Skeleton + "Still working on it — almost there." |
+| `expired` | 30s+ | `<ErrorBanner severity="error">` with a "Try again" button |
+
+```tsx
+import { LoadingTimeout, SkeletonGroup, SkeletonBar } from "hazo_ui";
+
+<LoadingTimeout
+  active={isLoading}
+  label="dashboard"
+  onRetry={refetch}
+  skeleton={
+    <SkeletonGroup>
+      <SkeletonBar width="80%" />
+      <SkeletonBar width="60%" />
+    </SkeletonGroup>
+  }
+>
+  <Dashboard data={data} />
+</LoadingTimeout>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `active` | `boolean` | **required** | When `true`, runs the timeout escalation; when `false`, renders `children` |
+| `children` | `ReactNode` | — | Content shown when `active` is `false` |
+| `skeleton` | `ReactNode` | — | Placeholder rendered during the `silent`/`gentle`/`firm` phases |
+| `onRetry` | `() => void` | — | Called when the user clicks Retry in the `expired` phase |
+| `thresholds` | `{ gentle?, firm?, expired? }` | `{5000, 15000, 30000}` | Override timeout thresholds (ms) |
+| `label` | `string` | `"content"` | Used in gentle/firm/expired messages |
+| `className` | `string` | — | Additional classes |
+
+### ProgressiveImage
+
+Three-stage image render: grey placeholder → blurred low-quality image (`lqip`) → sharp final image. Sets a stable container box so layout doesn't shift.
+
+```tsx
+import { ProgressiveImage } from "hazo_ui";
+
+<ProgressiveImage
+  src="/photos/large.jpg"
+  lqip="data:image/jpeg;base64,/9j/4AAQ…"
+  alt="Sunset over the lake"
+  width={400}
+  height={300}
+  fit="cover"
+  loading="lazy"
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | **required** | Final image src |
+| `alt` | `string` | **required** | Alt text (empty string allowed for decorative) |
+| `width` | `number \| string` | **required** | Container width (px or any CSS length) |
+| `height` | `number \| string` | **required** | Container height |
+| `lqip` | `string` | — | Low-quality placeholder (data URL or tiny image URL) |
+| `loading` | `"eager" \| "lazy"` | `"lazy"` | Native loading attribute |
+| `fit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | Object-fit for the final image |
+| `onLoad` | `() => void` | — | Called when the final image loads |
+| `onError` | `() => void` | — | Called if the final image errors |
+| `className` | `string` | — | Additional classes |
+
+### Toasts (HazoUiToaster + successToast / errorToast)
+
+A `sonner`-backed toaster plus two opinionated imperative helpers.
+
+**Mount the toaster once** near the root of your app:
+
+```tsx
+import { HazoUiToaster } from "hazo_ui";
+
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <HazoUiToaster position="bottom-right" />
+    </>
+  );
+}
+```
+
+**Fire toasts imperatively from anywhere:**
+
+```tsx
+import { successToast, errorToast } from "hazo_ui";
+
+await save();
+successToast({ title: "Saved", description: "Your changes have been published." });
+
+try { await sync(); } catch (e) {
+  errorToast({
+    title: "Sync failed",
+    description: "Check your connection and try again.",
+    action: { label: "Retry", onClick: () => sync() },
+  });
+}
+```
+
+`HazoUiToaster` props:
+
+| Prop | Type | Default |
+|---|---|---|
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "top-center" \| "bottom-center"` | `"bottom-right"` |
+| `closeButton` | `boolean` | `true` |
+| `visibleToasts` | `number` | `5` |
+
+`ToastOptions` (for `successToast` / `errorToast`):
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | **required** |
+| `description` | `string` | — |
+| `duration` | `number` (ms) | `3000` success / `5000` error |
+| `action` | `{ label: string; onClick: () => void }` | — |
+
+Also exports `rawToast` (re-export of sonner's `toast`) for advanced use cases.
+
+### useLoadingState
+
+Hook that returns a controlled loading flag plus an async wrapper.
+
+```tsx
+import { useLoadingState } from "hazo_ui";
+
+const { isLoading, setLoading, withLoading } = useLoadingState(false);
+
+async function onSubmit() {
+  await withLoading(async () => {
+    await api.save(data);
+  });
+}
+
+return <Button disabled={isLoading} onClick={onSubmit}>{isLoading ? "Saving…" : "Save"}</Button>;
+```
+
+Returns `{ isLoading: boolean; setLoading: (v: boolean) => void; withLoading: <T>(fn: () => Promise<T>) => Promise<T> }`. `withLoading` sets the flag to `true` before the call and clears it in a `finally` block — even on errors.
+
+### useErrorDisplay
+
+Passive error state. Coerces `Error` instances to their `.message`, strings pass through, anything else is `String()`-cast.
+
+```tsx
+import { useErrorDisplay, ErrorBanner } from "hazo_ui";
+
+const { error, setError, clearError } = useErrorDisplay();
+
+try { await save(); } catch (e) { setError(e); }
+
+return error ? <ErrorBanner message={error} onDismiss={clearError} /> : null;
+```
+
+Returns `{ error: string | null; setError: (v: unknown) => void; clearError: () => void }`. Pass `null` (or any nullish value) to `setError` to clear.
+
 ---
 
 ## Troubleshooting