@raxrai/stylelab-ui 0.3.1 → 0.4.0

package/README.md

@@ -49,6 +49,8 @@ export default function RootLayout({ children }) {
 }
 ```
 
+Optional props: `storageKey` (default `"stylelab-theme"`) for the localStorage key; `persistTheme` (default `true`). When `persistTheme={false}`, the provider does not read or write localStorage (theme is fixed to `defaultTheme` unless you change it in memory).
+
 ### 3. Use components
 
 ```tsx
@@ -73,7 +75,7 @@ export function MyPage() {
 
 **Components:** Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, CommandPalette, DashboardShell, DataTable, DocumentAccordion, Dropdown, Flashcard, GraphicCard, Input, Modal, Navbar, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, Tabs, Terminal, Timeline, Toast, Toggle, Tooltip.
 
-**Global:** ThemeProvider, useTheme, getThemeClass, THEMES, StyleLabTheme, cn, getNextListIndex, useFocusTrap, useClickOutside, useKeyboardNavigation.
+**Global:** ThemeProvider, useTheme, getThemeClass, THEMES, StyleLabTheme, cn, mergeRefs, getNextListIndex, useFocusTrap, useClickOutside, useKeyboardNavigation. Component roots support **ref** forwarding and **style** / **className** (consumer `className` applied last for overrides).
 
 - **See all components and try themes:** [stylelab.rajarai.com](https://stylelab.rajarai.com)
 - **Full API (props, types, hooks):** [docs/COMPONENTS.md](docs/COMPONENTS.md) in this repo.
@@ -185,9 +187,12 @@ Implements focus trap and scroll lock when open.
 
 ### Dropdown
 
+**Two usage patterns:** (1) **Default trigger** — omit `trigger`; the component shows a button with the selected label or `placeholder`. (2) **Custom trigger** — pass `trigger` with your own element (e.g. a Button or icon); the same list opens on activation.
+
 | Prop           | Type                    | Default | Description              |
 |----------------|-------------------------|---------|--------------------------|
-| `trigger`     | `ReactNode`             | —       | Button / element to open |
+| `trigger`     | `ReactNode`             | —       | Custom trigger; omit for default (placeholder/selected label) |
+| `placeholder` | `string`                | `"Select…"` | Shown when no value selected (default trigger only) |
 | `items`       | `{ value, label, disabled? }[]` | — | Options               |
 | `value` / `defaultValue` | `string`        | —       | Controlled / initial     |
 | `onValueChange`| `(value: string) => void` | —     | Selection callback       |
@@ -200,10 +205,11 @@ Keyboard: Enter/Space to open, Arrows to move, Enter to select, Escape to close.
 ## Utilities & hooks
 
 ```tsx
-import { cn, useFocusTrap, useClickOutside, useKeyboardNavigation, getNextListIndex } from "@raxrai/stylelab-ui";
+import { cn, mergeRefs, useFocusTrap, useClickOutside, useKeyboardNavigation, getNextListIndex } from "@raxrai/stylelab-ui";
 ```
 
 - **cn(...)** – clsx + tailwind-merge for class names.
+- **mergeRefs(...refs)** – Combines multiple refs (e.g. forwarded ref + internal ref). Use when a component needs to forward a ref and also attach its own ref.
 - **useFocusTrap(active, options?)** – Traps focus in a container ref (e.g. Modal).
 - **useClickOutside(ref(s), handler, options?)** – Fires when click is outside ref(s).
 - **useKeyboardNavigation({ onEscape, onArrowLeft, onArrowRight, ... })** – Document-level key handlers.
@@ -213,6 +219,17 @@ import { cn, useFocusTrap, useClickOutside, useKeyboardNavigation, getNextListIn
 
 ## Changelog
 
+### [0.4.0]
+
+- **Overrides + refs** — Component roots consistently support `style`, consumer `className` overrides (consumer class last), and ref forwarding across the library.
+- **Theme fixes** — Card no longer forces text color; Button `ghost` uses `text-inherit` so it can inherit parent text color.
+- **Accessibility** — ProgressBar now supports ARIA progress attributes; Toast supports Escape-to-dismiss; Tooltip uses `aria-describedby` when visible.
+- **Exports** — `mergeRefs` and common component prop types are re-exported from the package entry.
+
+### [0.3.2]
+
+- **ThemeProvider** — Optional `persistTheme` prop (default `true`). When `persistTheme={false}`, the provider does not read from or write to localStorage: theme stays at `defaultTheme` unless changed in memory. Use for fixed-theme pages (e.g. landing, docs) or nested providers where only the inner tree should persist. Optional `storageKey` (default `"stylelab-theme"`) still applies when `persistTheme` is true.
+
 ### [0.3.1]
 
 - **Dropdown** — `disabled` prop: when true, the dropdown does not open and the trigger is non-interactive (opacity, cursor, no popover). Use for empty or loading state.