diff --git a/src/docs/components/InfiniteScrollDemo.tsx b/src/docs/components/InfiniteScrollDemo.tsx
new file mode 100644
index 0000000..8203269
--- /dev/null
+++ b/src/docs/components/InfiniteScrollDemo.tsx
@@ -0,0 +1,101 @@
+import React, { useState, useCallback } from "react";
+import { ScrollArea, ScrollElement } from "@/components/ScrollArea";
+import { useTheme } from "@/theme";
+
+export const InfiniteScrollDemo: React.FC = () => {
+ const { theme } = useTheme();
+ const [items, setItems] = useState(
+ Array.from({ length: 8 }, (_, i) => ({
+ id: i + 1,
+ title: `Item ${i + 1}`,
+ type: (["up", "fade", "scale", "blur", "left", "right"] as const)[i % 6],
+ })),
+ );
+ const [loading, setLoading] = useState(false);
+
+ const loadMore = useCallback(() => {
+ if (loading) return;
+ setLoading(true);
+ setTimeout(() => {
+ setItems((prev) => {
+ const start = prev.length;
+ const next = Array.from({ length: 5 }, (_, i) => ({
+ id: start + i + 1,
+ title: `Item ${start + i + 1}`,
+ type: (["up", "fade", "scale", "blur", "left", "right"] as const)[
+ (start + i) % 6
+ ],
+ }));
+ return [...prev, ...next];
+ });
+ setLoading(false);
+ }, 600);
+ }, [loading]);
+
+ const handleScroll = useCallback(
+ (e: React.UIEvent) => {
+ const el = e.currentTarget;
+ if (el.scrollTop + el.clientHeight >= el.scrollHeight - 40) {
+ loadMore();
+ }
+ },
+ [loadMore],
+ );
+
+ return (
+
+
+
+ {items.length} items loaded
+
+
+ Scroll to bottom to load more
+
+
+
+
+ {items.map((item) => (
+
+
+ {item.title}
+
+ {item.type}
+
+
+
+ ))}
+ {loading && (
+
+ Loading more...
+
+ )}
+
+
= ({
+ title,
+ description,
+}) => {
+ const { theme } = useTheme();
+
+ return (
+
+
+
+ UI
+
+
+ Awesome UI
+
+
+
{title}
+
+ {description}
+
+
= ({ props }) => {
className="hover:bg-black/5 dark:hover:bg-white/[0.02] transition-colors group"
>
{prop.name}
diff --git a/src/docs/pages/Accordion.mdx b/src/docs/pages/Accordion.mdx
index 9fbe312..dc1fd43 100644
--- a/src/docs/pages/Accordion.mdx
+++ b/src/docs/pages/Accordion.mdx
@@ -2,70 +2,65 @@ import { Accordion } from '@/components/Accordion';
import { Typography } from '@/components/Typography';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Accordions are vertically collapsing containers that manage large amounts of content in a compact footprint. They are perfect for FAQ sections, settings panels, and detail-rich lists.
+
- This library is a collection of high-performance, theme-aware React components
- styled with Tailwind CSS and advanced CSS animations.
+Click the header to expand or collapse the content.
+
+
+ A collection of theme-aware React components.
`}>
-
What is this UI Library?}
- subtitle="Frequently Asked Questions"
+ What is this library?}
+ subtitle="FAQ"
>
-
- Our library is built on top of modern standards using React and Tailwind.
- Every component is designed to be accessible, performant, and deeply customizable
- via our integrated theming engine.
+
+ A collection of accessible, theme-aware React components built with Tailwind CSS.
- Content here...
+
+ Content...
`}>
-
+
- Modify your theme and layout preferences here.
+ Adjust theme and layout preferences.
- Manage your data and notification settings.
+ Manage data and notification settings.
-### Default Open & Disabled
-Control the initial state or prevent user interaction.
+## Default Open & Disabled
...
-... `}>
-
-
- This accordion starts in the open state.
+... `}>
+
+
+ This section starts expanded.
- You cannot open this section until criteria are met.
+ Cannot be toggled.
+
+Pass a `src` for an image, `displayName` for initials, or nothing for the default icon.
+
+
+
+
`}>
+
diff --git a/src/docs/pages/Badge.mdx b/src/docs/pages/Badge.mdx
index e66ed85..9ffe242 100644
--- a/src/docs/pages/Badge.mdx
+++ b/src/docs/pages/Badge.mdx
@@ -1,61 +1,53 @@
import { Badge } from '@/components/Badge';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Badges are compact status indicators that highlight metadata, status, or counts. They are designed to stand out without disrupting the layout flow.
+
-## Basic Usage
-Use badges to represent states like progress, success, or urgency.
+## Variants
-
Updated
+Color-coded badges for different statuses.
+
+New
Online
-High Priority `}>
-
-
New Feature
-
System Online
-
Maintenance
-
Security Risk
+
Pending
+
Critical `}>
+
+ New
+ Online
+ Pending
+ Critical
-## Customization
-### Sizes
-Badges come in three sizes to fit different contexts.
+## Sizes
Small
Medium
Large `}>
-
-
Small Label
-
Standard Badge
-
Hero Badge
+
+ Small
+ Medium
+ Large
-### Outline Style
-For a more subtle look, use the `outline` variant.
+## Outline & Loading
-
Secondary`}>
-
+
Draft
+Loading `}>
+
Draft
Archived
+ Loading
-### Loading State
-Badges support a built-in skeleton state for when data is still fetching.
-
-
Placeholder`}>
-
- Loading...
- Large Loading
-
-
-
-## Reference
+## Props
diff --git a/src/docs/pages/Button.mdx b/src/docs/pages/Button.mdx
index 878bb3e..fd0a2e7 100644
--- a/src/docs/pages/Button.mdx
+++ b/src/docs/pages/Button.mdx
@@ -1,76 +1,74 @@
import { Button } from '@/components/Button';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Buttons are fundamental interactive elements that trigger actions, submit forms, or navigate the user. Our design system provides a rich set of variants, sizes, and states to fit every functional requirement.
+
## Variants
-Use different variants to signal the importance of an action and maintain visual hierarchy.
+
+Each variant signals a different level of emphasis.
Primary
Secondary
Outline
Ghost `}>
-
-
Primary Action
+
+ Primary
Secondary
Outline
- Ghost Link
+ Ghost
-## States
-### Loading & Disabled
-Handle asynchronous operations and form validation gracefully.
+## Loading & Disabled
+
+Shows a spinner during async operations. Disabled prevents interaction.
-
Processing...
-Action Locked `}>
-
-
Loading State
-
Disabled View
-
Secondary Load
+
Saving...
+Unavailable `}>
+
+ Saving...
+ Unavailable
+ Loading
-## Customization
-### Sizes
-Buttons support three sizes: `sm`, `md` (default), and `lg`.
+## Sizes
+
+Three sizes: `sm` for toolbars, `md` for forms, `lg` for landing pages.
Small
Medium
Large `}>
-
-
Small (Compact UI)
-
Medium (Standard)
-
Large (Landing Page)
+
+ Small
+ Medium
+ Large
-### Semantic Colors
-Communicate success, warning, or danger states instantly.
+## Semantic Colors
-
Save Changes
-Reset Data
-Delete Account `}>
-
-
Success Action
-
Warning Notice
-
Delete Item
+Convey intent at a glance — success, warning, or danger.
+
+
Save
+Reset
+Delete `}>
+
+ Save
+ Reset
+ Delete
-## Best Practices
-- **Labeling**: Use clear, actionable verbs (e.g., "Save", "Create", "Post").
-- **Hierarchy**: Use only one Primary button per view to draw focus.
-- **Accessibility**: All buttons are keyboard navigable and support `aria-label` for icons.
-
-## Reference
+## Props
diff --git a/src/docs/pages/Checkbox.mdx b/src/docs/pages/Checkbox.mdx
index 927d6ee..2eb9abc 100644
--- a/src/docs/pages/Checkbox.mdx
+++ b/src/docs/pages/Checkbox.mdx
@@ -1,39 +1,44 @@
import { Checkbox } from '@/components/Checkbox';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Checkboxes allow users to select one or more items from a set.
+
## Basic Usage
+
`}>
-## States
-Checkboxes can have descriptions, show errors, or be indeterminate.
+## With Description
-
`}>
-
-### Indeterminate
+## Indeterminate
+
+Used for "select all" when only some children are checked.
+
`}>
## Sizes
+
`}>
-
+
@@ -42,10 +47,10 @@ Checkboxes can have descriptions, show errors, or be indeterminate.
## Props
diff --git a/src/docs/pages/Input.mdx b/src/docs/pages/Input.mdx
index 84cb3e5..05672ac 100644
--- a/src/docs/pages/Input.mdx
+++ b/src/docs/pages/Input.mdx
@@ -1,71 +1,69 @@
import { Input } from '@/components/Input';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Inputs are fundamental form components for collecting user text, numbers, or passwords. They provide built-in validation feedback, icon support, and theme-aware styling.
+
## Basic Usage
-A standard input includes a label, a placeholder, and optional helper text.
-
`}>
-
-## Customization
-### Icons & Loading
-Enhance meaning with leading or trailing icons, or show a loading indicator.
+## Icons & Loading
+
+Add context with leading/trailing icons, or show a spinner during validation.
🔍} placeholder="Search..." />
-
🔍} placeholder="Search components..." />
-
👁️} type="password" placeholder="••••••••" />
-
+
`}>
+
+
-### Validation States
-Clear visual cues help users correct errors or confirm success.
+## Validation
-
`}>
+Error messages replace helper text and recolor the border.
+
+
`}>
-
-### Sizes
-Inputs support three sizes: `sm`, `md` (default), and `lg`.
+## Sizes
-
-
-
`}>
-
-
-
-
+
+
+
`}>
+
+
-## Reference
+## Props
diff --git a/src/docs/pages/Modal.mdx b/src/docs/pages/Modal.mdx
index 3785f9c..06488a2 100644
--- a/src/docs/pages/Modal.mdx
+++ b/src/docs/pages/Modal.mdx
@@ -1,53 +1,51 @@
import { ModalDemo } from '../components/ModalDemo';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Modals are overlay windows used to focus the user's attention on a specific task or information. They block interaction with the rest of the application until closed.
+
## Basic Usage
-Use the `isOpen` and `onClose` props to control the modal's state.
-
setIsOpen(true)}>Open Modal
+ setIsOpen(false)}
- title="Confirmation"
->
- Are you sure you want to proceed with this action?
+ setIsOpen(true)}>Open
+ setIsOpen(false)} title="Confirm">
+ Are you sure?
`}>
-
-## Customization
-### Modal Sizes
-Modals support multiple widths: `sm`, `md` (default), `lg`, and `xl`.
+## Sizes
+
+Four widths: `sm`, `md`, `lg`, and `xl`.
-
-
-
+
+
-### Header Configuration
-You can toggle the close button or change the title.
+## Without Close Button
+
+Set `showCloseButton={false}` to require an explicit action.
-
`}>
-
+
`}>
+
## Props
void', required: true, description: 'Function called when the modal is closed via backdrop, escape, or close button.' },
- { name: 'title', type: 'string', description: 'Header text for the modal.' },
- { name: 'size', type: '"sm" | "md" | "lg" | "xl"', defaultValue: '"md"', description: 'Width of the modal container.' },
- { name: 'showCloseButton', type: 'boolean', defaultValue: 'true', description: 'Shows the "X" button in the top right.' },
- { name: 'preventBackdropClose', type: 'boolean', defaultValue: 'false', description: 'Disables closing the modal when clicking outside.' },
- { name: 'preventEscapeClose', type: 'boolean', defaultValue: 'false', description: 'Disables closing the modal when pressing the Escape key.' },
+ { name: 'isOpen', type: 'boolean', required: true, description: 'Controls visibility.' },
+ { name: 'onClose', type: '() => void', required: true, description: 'Called on close.' },
+ { name: 'title', type: 'string', description: 'Header text.' },
+ { name: 'size', type: '"sm" | "md" | "lg" | "xl"', defaultValue: '"md"', description: 'Dialog width.' },
+ { name: 'showCloseButton', type: 'boolean', defaultValue: 'true', description: 'Shows the X button.' },
+ { name: 'preventBackdropClose', type: 'boolean', defaultValue: 'false', description: 'Disables backdrop click close.' },
+ { name: 'preventEscapeClose', type: 'boolean', defaultValue: 'false', description: 'Disables Escape key close.' },
]} />
diff --git a/src/docs/pages/RadioGroup.mdx b/src/docs/pages/RadioGroup.mdx
index 60ca291..eb4dc08 100644
--- a/src/docs/pages/RadioGroup.mdx
+++ b/src/docs/pages/RadioGroup.mdx
@@ -1,76 +1,62 @@
import { RadioGroup } from '@/components/RadioGroup';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Radio groups allow users to select a single option from a set of choices.
+
-
-
- Item 1
-
-
- Item 2
-
-
{
+ const el = e.currentTarget;
+ if (el.scrollTop + el.clientHeight >= el.scrollHeight - 40) {
+ loadMore(); // fetch and append items
+ }
+ };
+
+ return (
+
+ {items.map(item => (
+
+ {item.title}
+
+ ))}
+
+ );
+}`}>
+
+
+## Vertical Scroll
+
+Items animate as they enter the viewport. Scroll down through the list.
+
+
+ Item 1
Item 2
Item 3
-
+
+
- Scroll slowly to see the reveal animation
+
+ Scroll down to see each animation
+
- Item 2 (Reveal Up)
+ Reveal Up
+
+
+ Reveal Down
- Item 3 (Fade In)
+ Fade In
+
+
+ Scale Pop
- Item 4 (Blur Entrance)
+ Blur Entrance
+
+
+ From Left
+
+
+ From Right
+
+
+ Another Up
+
+
+ Another Scale
+
+
+ Another Blur
+
+
+ End of list
-## Customization
-### Animation Presets
-You can specify the entrance effect per item.
+## Horizontal Scroll
+
+Set a wide inner container to enable horizontal scrolling.
-| Type | Description |
+
+
+`}>
+
+
+
+
+
Card 1
+
Scroll right
+
+
+
+
Card 2
+
Horizontal reveal
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Animation Types
+
+| Type | Effect |
| :--- | :--- |
-| `up` / `down` | Horizontal slide with fade |
-| `left` / `right` | Vertical slide with fade |
-| `fade` | Simple opacity transition |
-| `scale` | Zoom-in effect |
-| `blur` | Soft blur-to-clear transition |
-
-## Reference
-### ScrollArea Props
+| `up` / `down` | Slide with fade |
+| `left` / `right` | Horizontal slide |
+| `fade` | Opacity only |
+| `scale` | Zoom in |
+| `blur` | Blur to clear |
+
+## Props
+
+### ScrollArea
-### ScrollAreaItem Props
+### ScrollElement
diff --git a/src/docs/pages/Skeleton.mdx b/src/docs/pages/Skeleton.mdx
index 028d0c8..fa8bd93 100644
--- a/src/docs/pages/Skeleton.mdx
+++ b/src/docs/pages/Skeleton.mdx
@@ -1,68 +1,62 @@
import { Skeleton } from '@/components/Skeleton';
import { ComponentPreview } from '../components/ComponentPreview';
import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
-Skeletons are used to indicate that a piece of content is loading. They provide a better user experience than blank spaces or spinners by maintaining the layout's structural integrity.
+
## Basic Usage
-Skeletons can mimic any shape from text lines to profile pictures.
+
+Combine shapes to mock a content card during loading.
`}>
-
-
-
+
-## Customization
-### Animation Presets
-Choose between a smooth pulse or a dynamic wave effect.
+## Animations
+
+Wave sweeps across the surface. Pulse fades in and out. None is static.
-
-
+
+
`}>
-
+
- Wave (Default)
- Wave
+
- Pulse
- Pulse
+
- Static
- None
+
-### Shape Variants
-| Variant | Description |
-| :--- | :--- |
-| `text` | Simulates a line of text with specific scale and radius. |
-| `circular` | Perfect for avatars or round icon placeholders. |
-| `rectangular` | Standard box shape for images or large blocks. |
-| `rounded` | Rectangular with a larger 12px border radius. |
-
-## Reference
+## Props
diff --git a/src/docs/pages/Theming.mdx b/src/docs/pages/Theming.mdx
index 3245d89..b8056b8 100644
--- a/src/docs/pages/Theming.mdx
+++ b/src/docs/pages/Theming.mdx
@@ -1,51 +1,219 @@
import { Button } from '@/components/Button';
+import { Badge } from '@/components/Badge';
+import { Input } from '@/components/Input';
import { ComponentPreview } from '../components/ComponentPreview';
+import { PropsTable } from '../components/PropsTable';
-The library is built on a robust, token-based theming system that supports light mode, dark mode, and custom brand overrides.
+The library ships with a robust, token-based theming system. Every component reads its colors from a centralized theme, so one change updates everything.
-## Theme Provider
-To use the theme system, wrap your application in the `ThemeProvider`.
+## Quick Start
+
+Wrap your app in `ThemeProvider` to enable theming across all components.
```tsx
import { ThemeProvider } from 'ui-library';
function App() {
return (
-
-
+
);
}
```
-## How it Works
-The theme system uses **CSS Variables** defined in `:root` and `.dark` classes (or custom theme classes). This means:
-- **No extra JS weight** for runtime style calculations.
-- **Zero Flash of Unstyled Content** (FOUC).
-- **Infinite customization** — just override the CSS variables.
+## Architecture
+
+The theme system is built on three layers:
+
+| Layer | Purpose | Example |
+| :--- | :--- | :--- |
+| **Palette** | Raw color scales (50–900) | `primary.500`, `error.600` |
+| **Tokens** | Semantic roles that reference palette values | `background`, `accent`, `border` |
+| **CSS Variables** | Applied to `:root` for zero-JS styling | `--color-background`, `--color-accent` |
+
+This means:
+- **No runtime style calculations** — components read CSS variables directly.
+- **Zero FOUC** — variables are set before first paint.
+- **Full customization** — override any layer to match your brand.
+
+## Color Modes
+
+Toggle between light and dark modes with a single hook call.
+
+
+ Current: {theme.colorMode}
+
+ );
+}`}>
+
+
+ Use the toggle in the top-right header to switch modes.
+
+
## Dynamic Overrides
-You can live-update the theme programmatically using the `useTheme` hook. This is what powers the theme picker in the Playground.
+
+Override the theme at runtime using `overrideTheme`. This is how the color picker on the home page works.
+
+```tsx
+import { useTheme } from 'ui-library';
+
+function BrandSwitcher() {
+ const { overrideTheme, resetTheme } = useTheme();
+
+ const applyBrand = () => {
+ overrideTheme({
+ palette: {
+ primary: { 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8' }
+ },
+ tokens: {
+ accent: '#2563eb',
+ accentHover: '#1d4ed8',
+ }
+ });
+ };
+
+ return (
+ <>
+ Apply Blue Brand
+ Reset
+
+ );
+}
+```
+
+Partial overrides are deep-merged — you only need to specify the values you want to change.
+
+## Registering Custom Themes
+
+Create a fully custom theme and register it so it can be activated by name.
```tsx
-const { overrideTheme, resetTheme } = useTheme();
+import { registerTheme, type ThemeConfig } from 'ui-library';
-const oceanTheme = {
+const corporateTheme: ThemeConfig = {
+ name: 'corporate',
+ colorMode: 'light',
palette: {
- primary: { 500: '#0077ff' }
- }
+ primary: { 50: '#eff6ff', 100: '#dbeafe', /* ...full scale */ },
+ success: { /* ... */ },
+ warning: { /* ... */ },
+ error: { /* ... */ },
+ info: { /* ... */ },
+ },
+ neutral: { /* 50–900 gray scale */ },
+ tokens: {
+ background: '#ffffff',
+ surface: '#f8fafc',
+ foreground: '#0f172a',
+ foregroundMuted: '#64748b',
+ accent: '#2563eb',
+ // ...all semantic tokens
+ },
+ shape: {
+ radiusSm: '0.25rem',
+ radiusMd: '0.5rem',
+ radiusLg: '0.75rem',
+ radiusFull: '9999px',
+ },
+ typography: {
+ fontFamilySans: '"Inter", sans-serif',
+ fontFamilyMono: '"Fira Code", monospace',
+ },
};
- overrideTheme(oceanTheme)}>Go Blue
+// Register before rendering
+registerTheme(corporateTheme);
+
+// Then activate it
+const { setTheme } = useTheme();
+setTheme('corporate');
```
-## Color Modes
-Toggle between light and dark modes with a single call.
+## Semantic Tokens
-
- {theme.colorMode === 'light' ? 'Switch to Dark' : 'Switch to Light'}
-`}>
- Try toggling the mode using the button in the top-right of the docs!
-
+
+ {children}
+
+ );
+}
+```
+
+## CSS Variables Reference
+
+All theme values are applied as CSS custom properties on `:root`. You can use them directly in your own CSS or Tailwind classes.
+
+```css
+/* Use in your own stylesheets */
+.my-card {
+ background: var(--color-surface);
+ border: 1px solid var(--color-border);
+ color: var(--color-foreground);
+ border-radius: var(--radius-md);
+}
+```
+
+| Variable | Source |
+| :--- | :--- |
+| `--color-background` | `tokens.background` |
+| `--color-surface` | `tokens.surface` |
+| `--color-foreground` | `tokens.foreground` |
+| `--color-border` | `tokens.border` |
+| `--color-accent` | `tokens.accent` |
+| `--color-ring` | `tokens.ring` |
+| `--color-primary-500` | `palette.primary.500` |
+| `--radius-sm` / `md` / `lg` | `shape.radius*` |
+| `--font-sans` / `--font-mono` | `typography.fontFamily*` |
diff --git a/src/docs/pages/ThemingPage.tsx b/src/docs/pages/ThemingPage.tsx
new file mode 100644
index 0000000..1eec50c
--- /dev/null
+++ b/src/docs/pages/ThemingPage.tsx
@@ -0,0 +1,444 @@
+import React, { useState } from "react";
+import { useTheme } from "@/theme";
+import { Button } from "@/components/Button";
+import { Badge } from "@/components/Badge";
+import { Input } from "@/components/Input";
+import { PageHeader } from "../components/PageHeader";
+
+const BRAND_PRESETS = [
+ { name: "Pink", color: "#ec4899" },
+ { name: "Blue", color: "#3b82f6" },
+ { name: "Violet", color: "#8b5cf6" },
+ { name: "Emerald", color: "#10b981" },
+ { name: "Orange", color: "#f97316" },
+];
+
+function hexToHSL(hex: string): [number, number, number] {
+ const r = parseInt(hex.slice(1, 3), 16) / 255;
+ const g = parseInt(hex.slice(3, 5), 16) / 255;
+ const b = parseInt(hex.slice(5, 7), 16) / 255;
+ const max = Math.max(r, g, b),
+ min = Math.min(r, g, b);
+ const l = (max + min) / 2;
+ if (max === min) return [0, 0, l];
+ const d = max - min;
+ const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+ let h = 0;
+ if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+ else if (max === g) h = ((b - r) / d + 2) / 6;
+ else h = ((r - g) / d + 4) / 6;
+ return [h * 360, s * 100, l * 100];
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+ s /= 100;
+ l /= 100;
+ const a = s * Math.min(l, 1 - l);
+ const f = (n: number) => {
+ const k = (n + h / 30) % 12;
+ const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+ return Math.round(255 * Math.max(0, Math.min(1, color)))
+ .toString(16)
+ .padStart(2, "0");
+ };
+ return `#${f(0)}${f(8)}${f(4)}`;
+}
+
+function generateScale(hex: string) {
+ const [h, s] = hexToHSL(hex);
+ return {
+ 50: hslToHex(h, Math.min(100, s * 1.1), 97),
+ 100: hslToHex(h, Math.min(100, s * 1.1), 93),
+ 200: hslToHex(h, Math.min(100, s), 85),
+ 300: hslToHex(h, Math.min(100, s * 0.95), 73),
+ 400: hslToHex(h, Math.min(100, s * 0.9), 60),
+ 500: hex,
+ 600: hslToHex(h, Math.min(100, s * 0.95), 42),
+ 700: hslToHex(h, Math.min(100, s * 0.9), 34),
+ 800: hslToHex(h, Math.min(100, s * 0.85), 26),
+ 900: hslToHex(h, Math.min(100, s * 0.8), 18),
+ };
+}
+
+const CodeBlock: React.FC<{ children: string }> = ({ children }) => {
+ const { theme } = useTheme();
+ const [copied, setCopied] = useState(false);
+
+ return (
+
+
+ {children}
+
+
{
+ navigator.clipboard.writeText(children);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1500);
+ }}
+ className="absolute top-3 right-3 text-xs font-medium px-2.5 py-1 rounded-md transition-colors"
+ style={{
+ backgroundColor: copied
+ ? "rgba(74, 222, 128, 0.15)"
+ : "rgba(255,255,255,0.08)",
+ color: copied ? "#4ade80" : "#999",
+ }}
+ >
+ {copied ? "Copied!" : "Copy"}
+
+
+ {title}
+ {description && (
+
+ {description}
+
+ )}
+ {children}
+
+ );
+};
+
+export const ThemingPage: React.FC = () => {
+ const { theme, overrideTheme, resetTheme, toggleColorMode } = useTheme();
+ const [activePreset, setActivePreset] = useState(theme.palette.primary[500]);
+
+ const applyColor = (color: string) => {
+ setActivePreset(color);
+ const scale = generateScale(color);
+ overrideTheme({
+ palette: { primary: scale },
+ tokens: { accent: scale[600], accentHover: scale[700], ring: scale[500] },
+ });
+ };
+
+ return (
+
+
+
+ {/* Installation */}
+
+ {`npm install awesome-ui-library`}
+
+
+ {/* Setup */}
+
+ {`import { ThemeProvider } from 'awesome-ui-library';
+
+function App() {
+ return (
+
+
+ );
+}`}
+
+
+ {/* How it works */}
+
+
+ {[
+ {
+ step: "1",
+ layer: "Palette",
+ desc: "Raw color scales from 50 to 900.",
+ code: "palette.primary[500]",
+ },
+ {
+ step: "2",
+ layer: "Tokens",
+ desc: "Semantic roles like accent and border.",
+ code: "tokens.accent",
+ },
+ {
+ step: "3",
+ layer: "CSS Variables",
+ desc: "Injected into :root. No JS at render time.",
+ code: "--color-accent",
+ },
+ ].map((item) => (
+
+
+
+ {item.step}
+
+ {item.layer}
+
+
+ {item.desc}
+
+
+ {item.code}
+
+
+ ))}
+
+
+ {/* Color Modes */}
+
+
+
+
+ Active:{" "}
+
+ {theme.colorMode}
+
+
+
+ Try it — the entire site will adapt.
+
+
+
+ Switch to {theme.colorMode === "light" ? "Dark" : "Light"}
+
+
{`const { toggleColorMode } = useTheme();
+toggleColorMode(); // light ↔ dark`}
+
+
+ {/* Live Brand Switcher */}
+
+
+ {/* Brand pills */}
+
+ {BRAND_PRESETS.map((p) => (
+ applyColor(p.color)}
+ className="flex items-center gap-2 px-3 py-1.5 rounded-md border text-xs font-medium transition-colors"
+ style={{
+ borderColor:
+ activePreset === p.color ? p.color : theme.tokens.border,
+ backgroundColor:
+ activePreset === p.color ? `${p.color}15` : "transparent",
+ color:
+ activePreset === p.color
+ ? p.color
+ : theme.tokens.foreground,
+ }}
+ >
+
+ ))}
+ {
+ resetTheme();
+ setActivePreset("#ec4899");
+ }}
+ className="px-3 py-1.5 rounded-md border text-xs font-medium"
+ style={{
+ borderColor: theme.tokens.border,
+ color: theme.tokens.foregroundMuted,
+ }}
+ >
+ Reset
+
+
+
+ {/* Live preview */}
+
+
+
+ Primary
+
+
+ Outline
+
+
+ Ghost
+
+
+
+ Active
+ Online
+ Pending
+
+
+
+
+ {/* Generated palette */}
+
+
+ {([50, 100, 200, 300, 400, 500, 600, 700, 800, 900] as const).map(
+ (shade) => (
+
+
+ {shade}
+
+
+ ),
+ )}
+
+
+
{`const { overrideTheme } = useTheme();
+
+overrideTheme({
+ palette: {
+ primary: { 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8' }
+ },
+ tokens: {
+ accent: '#2563eb',
+ accentHover: '#1d4ed8',
+ }
+});`}
+
+
+ {/* Hooks API */}
+
+
+
+
useTheme()
+
+ Full control — read the theme, switch modes, apply overrides, or
+ reset.
+
+
+
+
useTokens()
+
+ Just the semantic tokens. Use when a component only needs color
+ values.
+
+
+
{`// Full access
+const { theme, setTheme, toggleColorMode, overrideTheme, resetTheme } = useTheme();
+
+// Just colors
+const tokens = useTokens();
+// tokens.background, tokens.accent, tokens.border, ...`}
+
+
+ {/* CSS Variables */}
+
+ {`.card {
+ background: var(--color-surface);
+ border: 1px solid var(--color-border);
+ color: var(--color-foreground);
+ border-radius: var(--radius-md);
+}
+
+/* Available variables:
+ --color-background, --color-surface, --color-foreground
+ --color-border, --color-accent, --color-ring
+ --color-primary-50 through --color-primary-900
+ --radius-sm, --radius-md, --radius-lg
+ --font-sans, --font-mono
+*/`}
+
+
Display 1
Display 2 `}>
-
+
Display 1
Display 2
-## Heading Variants
-Standard headings from H1 to H6.
+## Headings
+
+Semantic headings H1 through H3.
Heading 1
Heading 2
Heading 3 `}>
-
+
Heading 1
Heading 2
Heading 3
-## Body & Support
-Text styles for paragraphs, captions, and overlines.
+## Body & Caption
-
Body 1: The standard paragraph style.
-Body 2: A slightly smaller paragraph style.
-Caption: Smallest text for meta info. `}>
-
-
Body 1: The standard paragraph style.
-
Body 2: A slightly smaller paragraph style.
-
Caption: Smallest text for meta info.
+Paragraph and meta text styles.
+
+
Body 1
+Body 2
+Caption `}>
+
+ Body 1 — standard paragraph text.
+ Body 2 — smaller secondary text.
+ Caption — metadata and labels.
-## Custom Weights
-You can override the default weight of any variant.
+## Weight Overrides
+
+Override the default weight on any variant.
Bold H4
Thin H4 `}>
-
+
Bold H4
Thin H4
@@ -54,8 +59,8 @@ You can override the default weight of any variant.
## Props
diff --git a/src/mdx.d.ts b/src/mdx.d.ts
new file mode 100644
index 0000000..2e0f342
--- /dev/null
+++ b/src/mdx.d.ts
@@ -0,0 +1,5 @@
+declare module "*.mdx" {
+ import type { ComponentType } from "react";
+ const Component: ComponentType;
+ export default Component;
+}
diff --git a/tailwind.config.js b/tailwind.config.js
index 5bd1efd..aba1a96 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -1,6 +1,6 @@
/** @type {import('tailwindcss').Config} */
export default {
- content: ['./src/**/*.{js,ts,jsx,tsx}'],
+ content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
darkMode: 'class',
theme: {
extend: {
@@ -12,7 +12,6 @@ export default {
border: 'var(--color-border)',
accent: 'var(--color-accent)',
ring: 'var(--color-ring)',
- // ...etc
},
borderRadius: {
sm: 'var(--radius-sm)',
@@ -25,5 +24,7 @@ export default {
},
},
},
- plugins: [],
+ plugins: [
+ require('@tailwindcss/typography'),
+ ],
};
\ No newline at end of file
diff --git a/vite.config.ts b/vite.config.ts
index 913be53..428baae 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -11,13 +11,13 @@ const __dirname = dirname(__filename);
// https://vite.dev/config/
export default defineConfig({
plugins: [
+ mdx(),
react(),
dts({
include: ["src"],
- exclude: ["**/*.test.tsx", "**/*.test.ts"],
+ exclude: ["**/*.test.tsx", "**/*.test.ts", "**/*.mdx"],
rollupTypes: false,
}),
- mdx(),
],
resolve: {
alias: {
From 0cb37bb74a777baac608556048fc12b5e82e8d02 Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sat, 21 Mar 2026 20:24:05 +0530
Subject: [PATCH 07/15] feat: popover component
---
package-lock.json | 60 ++++++
package.json | 1 +
src/Playground.tsx | 268 ++++++++++++++++++++++++
src/components/Button/Button.tsx | 4 +-
src/components/Input/index.ts | 3 +-
src/components/Popover/Popover.tsx | 142 +++++++++++++
src/components/Popover/Popover.types.ts | 62 ++++++
7 files changed, 537 insertions(+), 3 deletions(-)
create mode 100644 src/components/Popover/Popover.tsx
create mode 100644 src/components/Popover/Popover.types.ts
diff --git a/package-lock.json b/package-lock.json
index f6da95a..19ea8f7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,7 @@
"name": "ui-library",
"version": "0.0.0",
"dependencies": {
+ "@floating-ui/react": "^0.27.19",
"react": "^19.2.0",
"react-dom": "^19.2.0"
},
@@ -1051,6 +1052,59 @@
}
}
},
+ "node_modules/@floating-ui/core": {
+ "version": "1.7.5",
+ "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.5.tgz",
+ "integrity": "sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@floating-ui/utils": "^0.2.11"
+ }
+ },
+ "node_modules/@floating-ui/dom": {
+ "version": "1.7.6",
+ "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.6.tgz",
+ "integrity": "sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@floating-ui/core": "^1.7.5",
+ "@floating-ui/utils": "^0.2.11"
+ }
+ },
+ "node_modules/@floating-ui/react": {
+ "version": "0.27.19",
+ "resolved": "https://registry.npmjs.org/@floating-ui/react/-/react-0.27.19.tgz",
+ "integrity": "sha512-31B8h5mm8YxotlE7/AU/PhNAl8eWxAmjL/v2QOxroDNkTFLk3Uu82u63N3b6TXa4EGJeeZLVcd/9AlNlVqzeog==",
+ "license": "MIT",
+ "dependencies": {
+ "@floating-ui/react-dom": "^2.1.8",
+ "@floating-ui/utils": "^0.2.11",
+ "tabbable": "^6.0.0"
+ },
+ "peerDependencies": {
+ "react": ">=17.0.0",
+ "react-dom": ">=17.0.0"
+ }
+ },
+ "node_modules/@floating-ui/react-dom": {
+ "version": "2.1.8",
+ "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.8.tgz",
+ "integrity": "sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==",
+ "license": "MIT",
+ "dependencies": {
+ "@floating-ui/dom": "^1.7.6"
+ },
+ "peerDependencies": {
+ "react": ">=16.8.0",
+ "react-dom": ">=16.8.0"
+ }
+ },
+ "node_modules/@floating-ui/utils": {
+ "version": "0.2.11",
+ "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.11.tgz",
+ "integrity": "sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==",
+ "license": "MIT"
+ },
"node_modules/@humanfs/core": {
"version": "0.19.1",
"resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz",
@@ -8040,6 +8094,12 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/tabbable": {
+ "version": "6.4.0",
+ "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.4.0.tgz",
+ "integrity": "sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==",
+ "license": "MIT"
+ },
"node_modules/tailwind-merge": {
"version": "3.4.0",
"resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.4.0.tgz",
diff --git a/package.json b/package.json
index 61c8274..d3aecff 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,7 @@
"test:coverage": "vitest run --coverage"
},
"dependencies": {
+ "@floating-ui/react": "^0.27.19",
"react": "^19.2.0",
"react-dom": "^19.2.0"
},
diff --git a/src/Playground.tsx b/src/Playground.tsx
index e202742..bd0bc20 100644
--- a/src/Playground.tsx
+++ b/src/Playground.tsx
@@ -12,6 +12,7 @@ import Checkbox from "@/components/Checkbox";
import { ScrollArea, ScrollElement } from "@/components/ScrollArea";
import RadioGroup from "@/components/RadioGroup";
import Switch from "@/components/Switch/Switch";
+import Popover from "@/components/Popover/Popover";
import reactLogo from "@/assets/react.svg";
import type { ThemeOverride } from "@/theme";
@@ -1657,6 +1658,273 @@ export default function Playground() {
+
+
+ Popover
+
+
+ Smart, accessible floating popovers powered by @floating-ui/react.
+
+
+
+
+
+
+ Interactive Popover
+
+
+ This popover handles clicks naturally. Notice how focus is
+ trapped correctly.
+
+
+
+ Acknowledge
+
+
+ Open Dialog Popover
+
+
+
+
+ Aligned Top
+
+
+ Fades and shifts if screen is too small.
+
+ Top Info
+
+
+
+ Real-World Use Cases
+
+
+
+ {/* Real Case 1: Profile Menu */}
+
+
+ Profile Menu
+
+
+
+
+ John Doe
+
+
+ john.doe@enterprise.com
+
+
+
+ Account Settings
+
+
+ Billing & Teams
+
+
+ Help & Support
+
+
+
+ Sign Out
+
+
+ }
+ >
+
+
+
+
+ {/* Real Case 2: Advanced Filter */}
+
+ }
+ >
+
+ Dimensions{" "}
+
+ 3
+
+
+
+
+
+ System Info Tooltip
+
+
+
+
+
+ Systems Operational
+
+
+ All database clusters and API endpoints are currently
+ reporting 100% uptime in the US-East region.
+
+
+ View Detailed Status →
+
+
+ i
+
+
+
+
+
+
{/* Modal */}
(
{isLoading ? (
<>
{children} }
+ {children}
) : (
<>
@@ -185,7 +185,7 @@ const Button = forwardRef(
{prefixIcon}
)}
- {children && {children} }
+ {children}
{suffixIcon && (
((props, ref) => {
+ const {
+ children,
+ id,
+ isOpen,
+ defaultOpen,
+ onOpenChange,
+ content,
+ placement = "bottom",
+ offset = 8,
+ showArrow = false,
+ disabled = false,
+ className,
+ } = props;
+
+ // Manage local state if not controlled
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
+ const open = isOpen !== undefined ? isOpen : internalOpen;
+
+ const handleOpenChange = (newOpen: boolean) => {
+ if (!disabled) {
+ setInternalOpen(newOpen);
+ onOpenChange?.(newOpen);
+ }
+ };
+
+ const {
+ refs: floatingRefs,
+ floatingStyles,
+ context,
+ } = useFloating({
+ open: open,
+ onOpenChange: handleOpenChange,
+ placement,
+ middleware: [offsetMiddleware(offset), flip(), shift()],
+ whileElementsMounted: autoUpdate,
+ });
+
+ // Destructure setters to avoid ESLint false-positives regarding accessing refs during render
+ const { setReference, setFloating } = floatingRefs;
+
+ const mergedRef = useMergeRefs([setReference, ref]);
+
+ const click = useClick(context, { enabled: !disabled });
+ const dismiss = useDismiss(context);
+ const role = useRole(context);
+
+ const { getReferenceProps, getFloatingProps } = useInteractions([
+ click,
+ dismiss,
+ role,
+ ]);
+
+ // Beautiful smooth entry/exit animations
+ const { isMounted, styles: transitionStyles } = useTransitionStyles(context, {
+ duration: {
+ open: 200,
+ close: 150,
+ },
+ initial: {
+ opacity: 0,
+ transform: "scale(0.95) translateY(-5px)",
+ },
+ });
+
+ // Handle React component children (like ) vs simple text children
+ const isReactChild = React.isValidElement<{
+ disabled?: boolean;
+ [key: string]: unknown;
+ }>(children);
+
+ // Prepare properties for the child component, cleanly bypassing ESLint ref scanning false-positives
+ const childProps = isReactChild
+ ? getReferenceProps({
+ id,
+ disabled: disabled || children.props.disabled,
+ ...children.props,
+ })
+ : {};
+
+ // Dynamically assign the ref to bypass strict AST static analysis
+ if (isReactChild) {
+ (childProps as Record).ref = mergedRef;
+ }
+
+ return (
+ <>
+ {/* Accessibility Fix: Prevent nested focusable elements by using cloneElement for valid React components, or a native html button for raw text */}
+ {isReactChild ? (
+ React.cloneElement(children, childProps)
+ ) : (
+
+ {children}
+
+ )}
+ {isMounted && (
+
+
+
+
+ {content}
+ {showArrow && (
+
Arrow Placeholder
+ )}
+
+
+
+ )}
+
+ );
+});
+
+export default Popover;
diff --git a/src/components/Popover/Popover.types.ts b/src/components/Popover/Popover.types.ts
new file mode 100644
index 0000000..80bb7b8
--- /dev/null
+++ b/src/components/Popover/Popover.types.ts
@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+import type { Placement } from "@floating-ui/react";
+
+export interface PopoverProps {
+ id?: string;
+
+ /**
+ * The trigger element (like a Button)
+ */
+ children: ReactNode;
+
+ /**
+ * The content inside the popover menu
+ */
+ content: ReactNode;
+
+ /**
+ * Alignment of the popover around the trigger.
+ * e.g., 'bottom', 'top-start', 'right-end'
+ * @default "bottom"
+ */
+ placement?: Placement;
+
+ /**
+ * Use for a *controlled* popover (you manage the state)
+ */
+ isOpen?: boolean;
+
+ /**
+ * Use for an *uncontrolled* popover (it manages its own state)
+ * @default false
+ */
+ defaultOpen?: boolean;
+
+ /**
+ * Callback fired when the open state changes
+ */
+ onOpenChange?: (open: boolean) => void;
+
+ /**
+ * Gap between the trigger and the popover menu in pixels
+ * @default 8
+ */
+ offset?: number;
+
+ /**
+ * Shows a little floating arrow pointing to the trigger
+ * @default false
+ */
+ showArrow?: boolean;
+
+ /**
+ * Prevents the popover from opening if true
+ * @default false
+ */
+ disabled?: boolean;
+
+ /**
+ * Additional Tailwind classes for the popover content box
+ */
+ className?: string;
+}
From 5940a9cb819c6215f3a7adf16810bdbfc5e8faee Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:57:55 +0530
Subject: [PATCH 08/15] fix: added sideeffect in package file
---
package.json | 3 +++
1 file changed, 3 insertions(+)
diff --git a/package.json b/package.json
index ae3239d..fa01f39 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,9 @@
"private": true,
"version": "0.0.0",
"type": "module",
+ "sideEffects": [
+ "*.css"
+ ],
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
From eb8aefa598a151cb70948b9113a8c6a1702cda5d Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:59:14 +0530
Subject: [PATCH 09/15] fix: popover component enhancement
---
src/components/Popover/Popover.tsx | 189 +++++++++++++++++-------
src/components/Popover/Popover.types.ts | 58 ++++----
src/components/Popover/index.ts | 2 +
3 files changed, 162 insertions(+), 87 deletions(-)
create mode 100644 src/components/Popover/index.ts
diff --git a/src/components/Popover/Popover.tsx b/src/components/Popover/Popover.tsx
index 3060b77..ce37d08 100644
--- a/src/components/Popover/Popover.tsx
+++ b/src/components/Popover/Popover.tsx
@@ -1,4 +1,4 @@
-import React, { forwardRef, useState } from "react";
+import React, { forwardRef, useState, useId, useCallback } from "react";
import type { PopoverProps } from "./Popover.types";
import {
useFloating,
@@ -6,6 +6,7 @@ import {
offset as offsetMiddleware,
flip,
shift,
+ arrow as arrowMiddleware,
useClick,
useDismiss,
useRole,
@@ -14,14 +15,25 @@ import {
useMergeRefs,
useTransitionStyles,
FloatingPortal,
+ FloatingArrow,
} from "@floating-ui/react";
+import { useRef } from "react";
+import { useTheme } from "@/theme";
+import { cn } from "@/utils";
+
+const ARROW_HEIGHT = 8;
+const ARROW_WIDTH = 8;
+const ARROW_OFFSET = ARROW_HEIGHT;
const Popover = forwardRef((props, ref) => {
+ const { theme } = useTheme();
+ const generatedId = useId();
+
const {
children,
- id,
+ id = generatedId,
isOpen,
- defaultOpen,
+ defaultOpen = false,
onOpenChange,
content,
placement = "bottom",
@@ -29,39 +41,50 @@ const Popover = forwardRef((props, ref) => {
showArrow = false,
disabled = false,
className,
+ zIndex = 1000,
} = props;
- // Manage local state if not controlled
const [internalOpen, setInternalOpen] = useState(defaultOpen);
- const open = isOpen !== undefined ? isOpen : internalOpen;
+ const isControlled = isOpen !== undefined;
+ const open = isControlled ? isOpen : internalOpen;
- const handleOpenChange = (newOpen: boolean) => {
- if (!disabled) {
- setInternalOpen(newOpen);
+ const handleOpenChange = useCallback(
+ (newOpen: boolean) => {
+ if (disabled) return;
+ if (!isControlled) setInternalOpen(newOpen);
onOpenChange?.(newOpen);
- }
- };
+ },
+ [disabled, isControlled, onOpenChange],
+ );
+
+ const arrowRef = useRef(null);
const {
refs: floatingRefs,
floatingStyles,
context,
} = useFloating({
- open: open,
+ open,
onOpenChange: handleOpenChange,
placement,
- middleware: [offsetMiddleware(offset), flip(), shift()],
+ middleware: [
+ offsetMiddleware(offset + (showArrow ? ARROW_OFFSET : 0)),
+ flip({ fallbackAxisSideDirection: "start" }),
+ shift({ padding: 8 }),
+ // eslint-disable-next-line react-hooks/refs
+ ...(showArrow
+ ? [arrowMiddleware({ element: arrowRef, padding: 8 })]
+ : []),
+ ],
whileElementsMounted: autoUpdate,
});
- // Destructure setters to avoid ESLint false-positives regarding accessing refs during render
const { setReference, setFloating } = floatingRefs;
-
const mergedRef = useMergeRefs([setReference, ref]);
const click = useClick(context, { enabled: !disabled });
- const dismiss = useDismiss(context);
- const role = useRole(context);
+ const dismiss = useDismiss(context, { outsidePressEvent: "mousedown" });
+ const role = useRole(context, { role: "dialog" });
const { getReferenceProps, getFloatingProps } = useInteractions([
click,
@@ -69,68 +92,118 @@ const Popover = forwardRef((props, ref) => {
role,
]);
- // Beautiful smooth entry/exit animations
const { isMounted, styles: transitionStyles } = useTransitionStyles(context, {
- duration: {
- open: 200,
- close: 150,
- },
- initial: {
+ duration: { open: 180, close: 120 },
+ initial: ({ side }) => ({
opacity: 0,
- transform: "scale(0.95) translateY(-5px)",
- },
+ transform: {
+ top: "scale(0.97) translateY(4px)",
+ bottom: "scale(0.97) translateY(-4px)",
+ left: "scale(0.97) translateX(4px)",
+ right: "scale(0.97) translateX(-4px)",
+ }[side],
+ }),
});
- // Handle React component children (like ) vs simple text children
+ const arrowFill = theme.tokens.elevated;
+
const isReactChild = React.isValidElement<{
disabled?: boolean;
[key: string]: unknown;
}>(children);
- // Prepare properties for the child component, cleanly bypassing ESLint ref scanning false-positives
- const childProps = isReactChild
- ? getReferenceProps({
- id,
- disabled: disabled || children.props.disabled,
- ...children.props,
- })
- : {};
+ const referenceProps = getReferenceProps({
+ id,
+ ...(isReactChild ? children.props : {}),
+ ...(isReactChild && { disabled: disabled || children.props.disabled }),
+ });
- // Dynamically assign the ref to bypass strict AST static analysis
- if (isReactChild) {
- (childProps as Record).ref = mergedRef;
- }
+ const trigger = isReactChild ? (
+ // eslint-disable-next-line react-hooks/refs
+ React.cloneElement(children, {
+ ...referenceProps,
+ ref: mergedRef,
+ } as Partial<{ disabled?: boolean; [key: string]: unknown }> & {
+ ref: typeof mergedRef;
+ })
+ ) : (
+ }
+ id={id}
+ type="button"
+ disabled={disabled}
+ className={cn(
+ "inline-flex cursor-pointer select-none",
+ "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2",
+ "focus-visible:ring-[var(--ring-color)]",
+ disabled && "pointer-events-none opacity-50",
+ )}
+ aria-expanded={open}
+ aria-haspopup="dialog"
+ {...(referenceProps as React.ButtonHTMLAttributes)}
+ >
+ {children}
+
+ );
+
+ // ─── Render ──────────────────────────────────────────────────────────────
return (
<>
- {/* Accessibility Fix: Prevent nested focusable elements by using cloneElement for valid React components, or a native html button for raw text */}
- {isReactChild ? (
- React.cloneElement(children, childProps)
- ) : (
-
- {children}
-
- )}
+ {trigger}
+
{isMounted && (
-
+
-
- {content}
- {showArrow && (
-
Arrow Placeholder
+
+ {content}
+
+ {showArrow && (
+
+ )}
@@ -139,4 +212,6 @@ const Popover = forwardRef
((props, ref) => {
);
});
+Popover.displayName = "Popover";
+
export default Popover;
diff --git a/src/components/Popover/Popover.types.ts b/src/components/Popover/Popover.types.ts
index 80bb7b8..da90781 100644
--- a/src/components/Popover/Popover.types.ts
+++ b/src/components/Popover/Popover.types.ts
@@ -1,62 +1,60 @@
-import type { ReactNode } from "react";
import type { Placement } from "@floating-ui/react";
export interface PopoverProps {
- id?: string;
-
- /**
- * The trigger element (like a Button)
- */
- children: ReactNode;
-
- /**
- * The content inside the popover menu
- */
- content: ReactNode;
+ /** The trigger element. A valid React element gets cloneElement'd; raw text/nodes get wrapped in a . */
+ children: React.ReactNode;
- /**
- * Alignment of the popover around the trigger.
- * e.g., 'bottom', 'top-start', 'right-end'
- * @default "bottom"
- */
- placement?: Placement;
+ /** Optional id forwarded to the trigger. Defaults to a stable generated id. */
+ id?: string;
/**
- * Use for a *controlled* popover (you manage the state)
+ * Controlled open state. When provided the component becomes fully controlled
+ * and you must manage state changes via `onOpenChange`.
*/
isOpen?: boolean;
- /**
- * Use for an *uncontrolled* popover (it manages its own state)
- * @default false
- */
+ /** Uncontrolled initial open state. Ignored when `isOpen` is provided. */
defaultOpen?: boolean;
+ /** Callback fired whenever the popover requests an open-state change. */
+ onOpenChange?: (open: boolean) => void;
+
+ /** The content rendered inside the floating panel. */
+ content: React.ReactNode;
+
/**
- * Callback fired when the open state changes
+ * Preferred placement relative to the trigger.
+ * Floating UI will automatically flip/shift if there isn't enough space.
+ * @default "bottom"
*/
- onOpenChange?: (open: boolean) => void;
+ placement?: Placement;
/**
- * Gap between the trigger and the popover menu in pixels
+ * Gap in pixels between the trigger and the floating panel.
+ * When `showArrow` is true the arrow height is added on top of this value automatically.
* @default 8
*/
offset?: number;
/**
- * Shows a little floating arrow pointing to the trigger
+ * Render a directional arrow pointing from the panel toward the trigger.
+ * Uses Floating UI's `` and inherits theme colours.
* @default false
*/
showArrow?: boolean;
/**
- * Prevents the popover from opening if true
+ * When true the trigger interaction is disabled and open-state changes are ignored.
* @default false
*/
disabled?: boolean;
+ /** Extra class names forwarded to the inner panel wrapper. */
+ className?: string;
+
/**
- * Additional Tailwind classes for the popover content box
+ * CSS z-index of the floating panel.
+ * @default 1000
*/
- className?: string;
+ zIndex?: number;
}
diff --git a/src/components/Popover/index.ts b/src/components/Popover/index.ts
new file mode 100644
index 0000000..0571505
--- /dev/null
+++ b/src/components/Popover/index.ts
@@ -0,0 +1,2 @@
+export { default as Popover } from "./Popover";
+export * from "./Popover.types";
From ee802c90132f2c5cd74e5208abc769e05b877108 Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sun, 22 Mar 2026 00:00:36 +0530
Subject: [PATCH 10/15] fix: eslint issues fix
---
src/components/Popover/Popover.tsx | 3 ++-
src/components/Switch/Switch.tsx | 2 +-
src/components/Switch/index.ts | 2 +-
3 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/src/components/Popover/Popover.tsx b/src/components/Popover/Popover.tsx
index ce37d08..e14cfe9 100644
--- a/src/components/Popover/Popover.tsx
+++ b/src/components/Popover/Popover.tsx
@@ -71,10 +71,11 @@ const Popover = forwardRef((props, ref) => {
offsetMiddleware(offset + (showArrow ? ARROW_OFFSET : 0)),
flip({ fallbackAxisSideDirection: "start" }),
shift({ padding: 8 }),
- // eslint-disable-next-line react-hooks/refs
+ /* eslint-disable react-hooks/refs */
...(showArrow
? [arrowMiddleware({ element: arrowRef, padding: 8 })]
: []),
+ /* eslint-enable react-hooks/refs */
],
whileElementsMounted: autoUpdate,
});
diff --git a/src/components/Switch/Switch.tsx b/src/components/Switch/Switch.tsx
index 0ba564b..1c5a2a2 100644
--- a/src/components/Switch/Switch.tsx
+++ b/src/components/Switch/Switch.tsx
@@ -7,7 +7,7 @@ import {
helperSizeClasses,
trackSizeClasses,
} from "./Switch.constants";
-import Skeleton from "../Skeleton";
+import { Skeleton } from "../Skeleton";
const Switch = forwardRef((props, ref) => {
const {
diff --git a/src/components/Switch/index.ts b/src/components/Switch/index.ts
index 76fefc6..5d9be1a 100644
--- a/src/components/Switch/index.ts
+++ b/src/components/Switch/index.ts
@@ -1,2 +1,2 @@
-export { default } from "./Switch";
+export { default as Switch } from "./Switch";
export * from "./Switch.types";
From 2a7b802420b3797aa6126b162c122a3e5435e97c Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sun, 22 Mar 2026 00:01:24 +0530
Subject: [PATCH 11/15] docs: documentation for switch and popover
---
src/docs/DocsApp.tsx | 14 +++
src/docs/DocsLayout.tsx | 2 +
src/docs/pages/Popover.mdx | 213 +++++++++++++++++++++++++++++++++++++
src/docs/pages/Switch.mdx | 44 ++++++++
4 files changed, 273 insertions(+)
create mode 100644 src/docs/pages/Popover.mdx
create mode 100644 src/docs/pages/Switch.mdx
diff --git a/src/docs/DocsApp.tsx b/src/docs/DocsApp.tsx
index 324cb09..1ba2886 100644
--- a/src/docs/DocsApp.tsx
+++ b/src/docs/DocsApp.tsx
@@ -16,8 +16,10 @@ const AvatarDocs = lazy(() => import("./pages/Avatar.mdx"));
const BadgeDocs = lazy(() => import("./pages/Badge.mdx"));
const CheckboxDocs = lazy(() => import("./pages/Checkbox.mdx"));
const ModalDocs = lazy(() => import("./pages/Modal.mdx"));
+const PopoverDocs = lazy(() => import("./pages/Popover.mdx"));
const ScrollAreaDocs = lazy(() => import("./pages/ScrollArea.mdx"));
const SkeletonDocs = lazy(() => import("./pages/Skeleton.mdx"));
+const SwitchDocs = lazy(() => import("./pages/Switch.mdx"));
const TypographyDocs = lazy(() => import("./pages/Typography.mdx"));
const ThemingPage = lazy(() =>
import("./pages/ThemingPage").then((m) => ({ default: m.ThemingPage })),
@@ -59,6 +61,11 @@ const components = [
path: "/docs/modal",
description: "Accessible dialog overlays",
},
+ {
+ name: "Popover",
+ path: "/docs/popover",
+ description: "Contextual floating menus",
+ },
{
name: "Radio Group",
path: "/docs/radio-group",
@@ -74,6 +81,11 @@ const components = [
path: "/docs/skeleton",
description: "Loading placeholders",
},
+ {
+ name: "Switch",
+ path: "/docs/switch",
+ description: "Instant setting toggles",
+ },
{
name: "Typography",
path: "/docs/typography",
@@ -604,8 +616,10 @@ export const DocsApp: React.FC = () => {
Account Settings Profile
+`}>
+
+
+ Account Settings
+ View and update your profile.
+ Manage Account
+ Profile
+
+
+
+
+---
+
+## Anatomy
+
+The popover is composed of two parts that live in separate parts of the DOM: a **trigger** (your `children`) and a **floating panel** (your `content`, portalled to ``). An optional arrow bridges the visual gap between them.
+
+---
+
+## Placements & Arrows
+
+You can control alignment and whether an arrow points directly back to the trigger.
+
+
Additional detailed info goes here. Arrow Attached
+`}>
+
+
Additional detailed info goes here. Arrow Attached
+
+
+
+---
+
+## Controlled state
+
+Use `isOpen` + `onOpenChange` when you need external control — for instance, to close the
+popover programmatically after a form submission.
+
+
+
+ This popover is fully controlled.
+ setOpen(false)}>Close
+
+ }
+ >
+
Controlled trigger
+
+
setOpen(true)}>
+ Open from outside
+
+
+
+ This popover is fully controlled.
+ setOpen(false)}>Close
+ Controlled trigger
+
+ setOpen(true)}>
+ Open from outside
+
+
+ );
+ }}
+
+
+---
+
+## Disabled state
+
+Set `disabled` to prevent the popover from opening. The trigger is also visually muted
+and non-interactive.
+
+
You won't see this. }
+>
+
Disabled trigger
+`}>
+
You won't see this. Disabled trigger
+
+
+
+---
+
+## Nested popovers
+
+Popovers can be nested — each manages its own open state independently. Click outside the
+outermost panel to close all of them. Use `zIndex` to stack panels correctly.
+
+
+ Parent popover
+
+ Child popover
+ Nested content here.
+
+ Hover for child →
+
+
+ Open parent
+`}>
+
+ Parent popover
+
+ Child popover
+ Nested content here.
+
+ Open child →
+
+
+ Open parent
+
+
+
+---
+
+## Props
+
+
.' },
+ { name: 'content', type: 'ReactNode', description: 'The content rendered inside the floating panel.' },
+ { name: 'placement', type: 'Placement', defaultValue: '"bottom"', description: 'Preferred placement relative to the trigger. Floating UI will flip/shift automatically if there is not enough space.' },
+ { name: 'isOpen', type: 'boolean', description: 'Controlled open state. Requires onOpenChange to be provided.' },
+ { name: 'defaultOpen', type: 'boolean', defaultValue: 'false', description: 'Initial open state for uncontrolled usage.' },
+ { name: 'onOpenChange', type: '(open: boolean) => void', description: 'Callback fired when the open state changes.' },
+ { name: 'offset', type: 'number', defaultValue: '8', description: 'Gap in px between trigger and panel. Arrow height is added automatically when showArrow is true.' },
+ { name: 'showArrow', type: 'boolean', defaultValue: 'false', description: 'Renders a directional arrow pointing from the panel toward the trigger.' },
+ { name: 'disabled', type: 'boolean', defaultValue: 'false', description: 'Prevents the popover from opening and mutes the trigger.' },
+ { name: 'className', type: 'string', description: 'Extra class names forwarded to the inner panel wrapper.' },
+ { name: 'zIndex', type: 'number', defaultValue: '1000', description: 'CSS z-index of the floating panel. Increase when nesting inside other layered elements.' },
+ { name: 'id', type: 'string', description: 'Optional id forwarded to the trigger. Defaults to a stable React-generated id.' },
+]} />
\ No newline at end of file
diff --git a/src/docs/pages/Switch.mdx b/src/docs/pages/Switch.mdx
new file mode 100644
index 0000000..a3db004
--- /dev/null
+++ b/src/docs/pages/Switch.mdx
@@ -0,0 +1,44 @@
+import { Switch } from '@/components/Switch';
+import { ComponentPreview } from '../components/ComponentPreview';
+import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
+
+
+
+
+
+## Sizes & States
+
+You can provide physical sizes, disabled states, and contextual errors or loading skeletons.
+
+
+
+
+
+## Props
+ void', description: 'Callback fired on toggle.' },
+ { name: 'disabled', type: 'boolean', defaultValue: 'false', description: 'Prevents interaction.' },
+ { name: 'size', type: '"small" | "medium" | "large"', defaultValue: '"medium"', description: 'Physical size of the switch.' },
+ { name: 'label', type: 'ReactNode', description: 'Main label text.' },
+ { name: 'description', type: 'ReactNode', description: 'Contextual sub-label text.' },
+ { name: 'helperText', type: 'ReactNode', description: 'Text below the switch.' },
+ { name: 'error', type: 'ReactNode', description: 'Error state message.' },
+ { name: 'isLoading', type: 'boolean', defaultValue: 'false', description: 'Displays skeleton loader.' },
+]} />
From 47802641bff43865612da34e0a5e75dd8f5a7a41 Mon Sep 17 00:00:00 2001
From: ABILASH <114130954+Abilash-19@users.noreply.github.com>
Date: Sun, 22 Mar 2026 14:57:08 +0530
Subject: [PATCH 12/15] feat: dropdown component
---
src/Playground.tsx | 141 ++++++++++++
src/assets/Icons/CheckIcon.tsx | 11 +-
src/components/Dropdown/Dropdown.constants.ts | 16 ++
src/components/Dropdown/Dropdown.tsx | 210 ++++++++++++++++++
src/components/Dropdown/Dropdown.types.ts | 49 ++++
src/components/Popover/Popover.tsx | 9 +-
src/components/Popover/Popover.types.ts | 6 +
7 files changed, 438 insertions(+), 4 deletions(-)
create mode 100644 src/components/Dropdown/Dropdown.constants.ts
create mode 100644 src/components/Dropdown/Dropdown.tsx
create mode 100644 src/components/Dropdown/Dropdown.types.ts
diff --git a/src/Playground.tsx b/src/Playground.tsx
index 5422579..fd5aa6a 100644
--- a/src/Playground.tsx
+++ b/src/Playground.tsx
@@ -14,6 +14,7 @@ import { ScrollArea, ScrollElement } from "@/components/ScrollArea";
import { RadioGroup } from "@/components/RadioGroup";
import Switch from "@/components/Switch/Switch";
import Popover from "@/components/Popover/Popover";
+import { Dropdown } from "@/components/Dropdown/Dropdown";
import reactLogo from "@/assets/react.svg";
import type { ThemeOverride } from "@/theme";
@@ -170,6 +171,7 @@ export default function Playground() {
const [isSimulatingData, setIsSimulatingData] = useState(true);
const [radioValue, setRadioValue] = useState("option-1");
+ const [dropdownValue, setDropdownValue] = useState("");
const [switchState, setSwitchState] = useState(false);
const [checkedItems, setCheckedItems] = useState({
@@ -1933,6 +1935,145 @@ export default function Playground() {
+
+
+ Dropdown Menus
+
+
+ Highly accessible, themeable select menus with support for labels,
+ validation, and loading states.
+
+
+
+
+ {/* Column 1: Configurable Examples */}
+
+
+
+
+
+ setDropdownValue(val)}
+ />
+ {dropdownValue && (
+
+ Output: {dropdownValue}
+
+ )}
+
+
+
+
+
+
+
+
+
+
+
+ {/* Column 2: Visual Variations */}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
{/* Modal */}
{
+export const CheckIcon = ({
+ size,
+ className,
+}: {
+ size?: string;
+ className?: string;
+}) => {
return (
,
+ { height: string; width: string }
+> = {
+ sm: { height: "28px", width: "100%" },
+ md: { height: "32px", width: "100%" },
+ lg: { height: "36px", width: "100%" },
+};
+
+export const DROPDOWN_SIZE_MAP = {
+ sm: "h-8 px-2 text-xs",
+ md: "h-10 px-3 text-sm",
+ lg: "h-12 px-4 text-base",
+};
diff --git a/src/components/Dropdown/Dropdown.tsx b/src/components/Dropdown/Dropdown.tsx
new file mode 100644
index 0000000..3bd30f1
--- /dev/null
+++ b/src/components/Dropdown/Dropdown.tsx
@@ -0,0 +1,210 @@
+import {
+ forwardRef,
+ useCallback,
+ useState,
+ useId,
+ useRef,
+ useLayoutEffect,
+} from "react";
+import type { DropdownProps } from "./Dropdown.types";
+import { Skeleton } from "../Skeleton";
+import { SKELETON_SIZE_MAP, DROPDOWN_SIZE_MAP } from "./Dropdown.constants";
+import { Popover } from "../Popover";
+import { useTheme } from "@/theme";
+import { cn } from "@/utils";
+import { Chevron } from "@/assets/Icons/Chevron";
+import { CheckIcon } from "@/assets/Icons/CheckIcon";
+
+const Dropdown = forwardRef((props, ref) => {
+ const generatedId = useId();
+ const {
+ id = generatedId,
+ options,
+ size = "md",
+ isLoading,
+ onChange,
+ label,
+ required = false,
+ selectedValue,
+ defaultOpen,
+ isOpen,
+ error,
+ disabled,
+ offset = 4,
+ className,
+ zIndex,
+ } = props;
+ const { theme } = useTheme();
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
+ const buttonRef = useRef(null);
+ const [triggerWidth, setTriggerWidth] = useState();
+ const isControlled = isOpen !== undefined;
+ const open = isControlled ? isOpen : internalOpen;
+
+ useLayoutEffect(() => {
+ const updateWidth = () => {
+ if (buttonRef.current) {
+ setTriggerWidth(buttonRef.current.offsetWidth);
+ }
+ };
+
+ updateWidth();
+ window.addEventListener("resize", updateWidth);
+ return () => window.removeEventListener("resize", updateWidth);
+ }, [open]);
+
+ const handleOpenChange = useCallback(
+ (newOpen: boolean) => {
+ if (disabled) return;
+ if (!isControlled) setInternalOpen(newOpen);
+ },
+ [disabled, isControlled],
+ );
+
+ const handleSelect = useCallback(
+ (newValue: string) => {
+ if (disabled) return;
+ onChange?.(newValue);
+ handleOpenChange(false);
+ },
+ [disabled, onChange, handleOpenChange],
+ );
+
+ if (isLoading) {
+ return (
+
+ {label && (
+
+ {label}
+ {required && * }
+
+ )}
+
+ {options.map((option) => (
+ handleSelect(option.value)}
+ className={cn(
+ "px-3 py-2 text-sm text-left transition-colors outline-none flex items-center justify-between",
+ option.value === selectedValue
+ ? "bg-primary-50 text-primary-900 font-medium"
+ : "text-[var(--text)] hover:bg-gray-100",
+ option.disabled && "opacity-50 cursor-not-allowed",
+ )}
+ >
+ {option.label}
+ {option.value === selectedValue && (
+
+ ))}
+ {
+ // Handle both local ref and forwarded ref
+ (buttonRef as any).current = node;
+ if (typeof ref === "function") {
+ ref(node);
+ } else if (ref) {
+ (ref as any).current = node;
+ }
+ }}
+ type="button"
+ role="combobox"
+ aria-expanded={open}
+ aria-haspopup="listbox"
+ aria-controls={listboxId}
+ disabled={disabled}
+ className={cn(
+ "flex items-center justify-between w-full border border-[var(--border)]",
+ "focus:outline-none focus:ring-2 focus:ring-[var(--ring)] focus:border-transparent",
+ "hover:bg-[var(--bg-hover)] rounded-[var(--radius)] transition-all",
+ DROPDOWN_SIZE_MAP[size],
+ !selectedLabel ? "text-[var(--placeholder)]" : "text-[var(--text)]",
+ disabled && "opacity-50 cursor-not-allowed",
+ className,
+ )}
+ style={themeStyles}
+ >
+ {selectedLabel || "Select option"}
+
+
+ {error && typeof error === "string" && (
+
+ {error}
+
+ )}
+ ((props, ref) => {
disabled = false,
className,
zIndex = 1000,
+ usePortal = true,
+ portalContainer,
} = props;
const [internalOpen, setInternalOpen] = useState(defaultOpen);
@@ -149,12 +151,15 @@ const Popover = forwardRef((props, ref) => {
// ─── Render ──────────────────────────────────────────────────────────────
+ const ContentWrapper = usePortal ? FloatingPortal : React.Fragment;
+ const portalProps = usePortal ? { root: portalContainer } : {};
+
return (
<>
{trigger}
{isMounted && (
-
+
((props, ref) => {
)}
-
+
)}
);
diff --git a/src/components/Popover/Popover.types.ts b/src/components/Popover/Popover.types.ts
index da90781..86858ea 100644
--- a/src/components/Popover/Popover.types.ts
+++ b/src/components/Popover/Popover.types.ts
@@ -57,4 +57,10 @@ export interface PopoverProps {
* @default 1000
*/
zIndex?: number;
+
+ /** Use React Portal? */
+ usePortal?: boolean;
+
+ /** Portal container element */
+ portalContainer?: HTMLElement | null;
}
From 223f0108ab06058f5fbec68238cda231ac58d551 Mon Sep 17 00:00:00 2001
From: Abilash-Workhall
Date: Sun, 22 Mar 2026 17:29:53 +0530
Subject: [PATCH 13/15] fix: theming fixed and added surface theme pick option
in docs
---
src/docs/pages/ThemingPage.tsx | 499 ++++++++++++++++++++++++++++++---
src/theme/ThemeProvider.tsx | 9 +
tailwind.config.js | 12 +
3 files changed, 485 insertions(+), 35 deletions(-)
diff --git a/src/docs/pages/ThemingPage.tsx b/src/docs/pages/ThemingPage.tsx
index 1eec50c..4617191 100644
--- a/src/docs/pages/ThemingPage.tsx
+++ b/src/docs/pages/ThemingPage.tsx
@@ -1,8 +1,12 @@
import React, { useState } from "react";
import { useTheme } from "@/theme";
+import type { SemanticTokens } from "@/theme";
import { Button } from "@/components/Button";
import { Badge } from "@/components/Badge";
import { Input } from "@/components/Input";
+import { Checkbox } from "@/components/Checkbox";
+import { Dropdown } from "@/components/Dropdown/Dropdown";
+import Switch from "@/components/Switch/Switch";
import { PageHeader } from "../components/PageHeader";
const BRAND_PRESETS = [
@@ -11,6 +15,13 @@ const BRAND_PRESETS = [
{ name: "Violet", color: "#8b5cf6" },
{ name: "Emerald", color: "#10b981" },
{ name: "Orange", color: "#f97316" },
+ { name: "Red", color: "#ef4444" },
+ { name: "Cyan", color: "#06b6d4" },
+ { name: "Rose", color: "#f43f5e" },
+ { name: "Indigo", color: "#6366f1" },
+ { name: "Amber", color: "#f59e0b" },
+ { name: "Teal", color: "#14b8a6" },
+ { name: "Lime", color: "#84cc16" },
];
function hexToHSL(hex: string): [number, number, number] {
@@ -117,9 +128,384 @@ const Section: React.FC<{
);
};
+// ─── Dark Theme Presets ────────────────────────────────────────────────────
+
+interface ThemePreset {
+ name: string;
+ description: string;
+ preview: [string, string, string]; // 3 colors for the preview swatch
+ neutral: Record;
+ tokens: Partial;
+}
+
+const DARK_PRESETS: ThemePreset[] = [
+ {
+ name: "Midnight",
+ description: "Pure black with neutral grays",
+ preview: ["#080808", "#181818", "#f2f2f2"],
+ neutral: {
+ 50: "#080808",
+ 100: "#101010",
+ 200: "#181818",
+ 300: "#202020",
+ 400: "#383838",
+ 500: "#585858",
+ 600: "#787878",
+ 700: "#a0a0a0",
+ 800: "#c8c8c8",
+ 900: "#f2f2f2",
+ },
+ tokens: {
+ background: "#080808",
+ surface: "#101010",
+ surfaceHover: "#181818",
+ elevated: "#181818",
+ foreground: "#f2f2f2",
+ foregroundMuted: "#a0a0a0",
+ foregroundSubtle: "#787878",
+ foregroundInverse: "#0b0f14",
+ border: "#202020",
+ borderSubtle: "#181818",
+ borderStrong: "#383838",
+ input: "#181818",
+ inputHover: "#202020",
+ inputFocus: "#101010",
+ ringOffset: "#101010",
+ },
+ },
+ {
+ name: "Ocean",
+ description: "Deep blue-tinted dark theme",
+ preview: ["#0a1628", "#111d33", "#e2e8f0"],
+ neutral: {
+ 50: "#0a1628",
+ 100: "#0f1d2e",
+ 200: "#111d33",
+ 300: "#1a2a42",
+ 400: "#2a3f5f",
+ 500: "#4a6182",
+ 600: "#6b82a0",
+ 700: "#8fa3bb",
+ 800: "#c4d1de",
+ 900: "#e2e8f0",
+ },
+ tokens: {
+ background: "#0a1628",
+ surface: "#0f1d2e",
+ surfaceHover: "#111d33",
+ elevated: "#111d33",
+ foreground: "#e2e8f0",
+ foregroundMuted: "#8fa3bb",
+ foregroundSubtle: "#6b82a0",
+ foregroundInverse: "#0a1628",
+ border: "#1a2a42",
+ borderSubtle: "#111d33",
+ borderStrong: "#2a3f5f",
+ input: "#111d33",
+ inputHover: "#1a2a42",
+ inputFocus: "#0f1d2e",
+ ringOffset: "#0f1d2e",
+ },
+ },
+ {
+ name: "Slate",
+ description: "Cool gray with blue undertones",
+ preview: ["#0f172a", "#1e293b", "#f1f5f9"],
+ neutral: {
+ 50: "#0f172a",
+ 100: "#1e293b",
+ 200: "#1e293b",
+ 300: "#334155",
+ 400: "#475569",
+ 500: "#64748b",
+ 600: "#94a3b8",
+ 700: "#cbd5e1",
+ 800: "#e2e8f0",
+ 900: "#f1f5f9",
+ },
+ tokens: {
+ background: "#0f172a",
+ surface: "#1e293b",
+ surfaceHover: "#273549",
+ elevated: "#1e293b",
+ foreground: "#f1f5f9",
+ foregroundMuted: "#94a3b8",
+ foregroundSubtle: "#64748b",
+ foregroundInverse: "#0f172a",
+ border: "#334155",
+ borderSubtle: "#1e293b",
+ borderStrong: "#475569",
+ input: "#1e293b",
+ inputHover: "#334155",
+ inputFocus: "#1e293b",
+ ringOffset: "#1e293b",
+ },
+ },
+ {
+ name: "Violet Night",
+ description: "Dark purple-tinted surfaces",
+ preview: ["#0e0a1a", "#1a1425", "#ede9fe"],
+ neutral: {
+ 50: "#0e0a1a",
+ 100: "#141020",
+ 200: "#1a1425",
+ 300: "#251e35",
+ 400: "#3b3255",
+ 500: "#5b5278",
+ 600: "#7c739a",
+ 700: "#a09abc",
+ 800: "#cbc5de",
+ 900: "#ede9fe",
+ },
+ tokens: {
+ background: "#0e0a1a",
+ surface: "#141020",
+ surfaceHover: "#1a1425",
+ elevated: "#1a1425",
+ foreground: "#ede9fe",
+ foregroundMuted: "#a09abc",
+ foregroundSubtle: "#7c739a",
+ foregroundInverse: "#0e0a1a",
+ border: "#251e35",
+ borderSubtle: "#1a1425",
+ borderStrong: "#3b3255",
+ input: "#1a1425",
+ inputHover: "#251e35",
+ inputFocus: "#141020",
+ ringOffset: "#141020",
+ },
+ },
+ {
+ name: "Emerald Dark",
+ description: "Forest green undertones",
+ preview: ["#071210", "#0d1f1b", "#ecfdf5"],
+ neutral: {
+ 50: "#071210",
+ 100: "#0a1a17",
+ 200: "#0d1f1b",
+ 300: "#162e28",
+ 400: "#264a40",
+ 500: "#3d6b5e",
+ 600: "#5a8c7c",
+ 700: "#86b5a2",
+ 800: "#b8d8ca",
+ 900: "#ecfdf5",
+ },
+ tokens: {
+ background: "#071210",
+ surface: "#0a1a17",
+ surfaceHover: "#0d1f1b",
+ elevated: "#0d1f1b",
+ foreground: "#ecfdf5",
+ foregroundMuted: "#86b5a2",
+ foregroundSubtle: "#5a8c7c",
+ foregroundInverse: "#071210",
+ border: "#162e28",
+ borderSubtle: "#0d1f1b",
+ borderStrong: "#264a40",
+ input: "#0d1f1b",
+ inputHover: "#162e28",
+ inputFocus: "#0a1a17",
+ ringOffset: "#0a1a17",
+ },
+ },
+ {
+ name: "Warm Dark",
+ description: "Cozy dark with warm brown tones",
+ preview: ["#120f0b", "#1c1814", "#faf5ef"],
+ neutral: {
+ 50: "#120f0b",
+ 100: "#181510",
+ 200: "#1c1814",
+ 300: "#2a2520",
+ 400: "#3e3830",
+ 500: "#5c5448",
+ 600: "#7a7165",
+ 700: "#a09688",
+ 800: "#c8bfb2",
+ 900: "#faf5ef",
+ },
+ tokens: {
+ background: "#120f0b",
+ surface: "#181510",
+ surfaceHover: "#1c1814",
+ elevated: "#1c1814",
+ foreground: "#faf5ef",
+ foregroundMuted: "#a09688",
+ foregroundSubtle: "#7a7165",
+ foregroundInverse: "#120f0b",
+ border: "#2a2520",
+ borderSubtle: "#1c1814",
+ borderStrong: "#3e3830",
+ input: "#1c1814",
+ inputHover: "#2a2520",
+ inputFocus: "#181510",
+ ringOffset: "#181510",
+ },
+ },
+];
+
+const LIGHT_PRESETS: ThemePreset[] = [
+ {
+ name: "Default",
+ description: "Clean white with neutral grays",
+ preview: ["#fbfaf9", "#ffffff", "#111827"],
+ neutral: {
+ 50: "#fbfaf9",
+ 100: "#f3f4f6",
+ 200: "#e5e7eb",
+ 300: "#d1d5db",
+ 400: "#9ca3af",
+ 500: "#6b7280",
+ 600: "#4b5563",
+ 700: "#374151",
+ 800: "#1f2937",
+ 900: "#111827",
+ },
+ tokens: {
+ background: "#fbfaf9",
+ surface: "#ffffff",
+ surfaceHover: "#f3f4f6",
+ elevated: "#ffffff",
+ foreground: "#111827",
+ foregroundMuted: "#6b7280",
+ foregroundSubtle: "#9ca3af",
+ foregroundInverse: "#ffffff",
+ border: "#e5e7eb",
+ borderSubtle: "#f3f4f6",
+ borderStrong: "#9ca3af",
+ input: "#ffffff",
+ inputHover: "#fbfaf9",
+ inputFocus: "#ffffff",
+ ringOffset: "#ffffff",
+ },
+ },
+ {
+ name: "Snow Blue",
+ description: "Soft blue-tinted light theme",
+ preview: ["#f0f4f8", "#ffffff", "#1a2b4a"],
+ neutral: {
+ 50: "#f0f4f8",
+ 100: "#e8edf2",
+ 200: "#d5dce6",
+ 300: "#b8c4d4",
+ 400: "#8a9ab5",
+ 500: "#5d7096",
+ 600: "#445a7a",
+ 700: "#344763",
+ 800: "#25344c",
+ 900: "#1a2b4a",
+ },
+ tokens: {
+ background: "#f0f4f8",
+ surface: "#ffffff",
+ surfaceHover: "#e8edf2",
+ elevated: "#ffffff",
+ foreground: "#1a2b4a",
+ foregroundMuted: "#5d7096",
+ foregroundSubtle: "#8a9ab5",
+ foregroundInverse: "#ffffff",
+ border: "#d5dce6",
+ borderSubtle: "#e8edf2",
+ borderStrong: "#8a9ab5",
+ input: "#ffffff",
+ inputHover: "#f0f4f8",
+ inputFocus: "#ffffff",
+ ringOffset: "#ffffff",
+ },
+ },
+ {
+ name: "Warm Sand",
+ description: "Warm cream backgrounds",
+ preview: ["#faf6f0", "#ffffff", "#2d1f10"],
+ neutral: {
+ 50: "#faf6f0",
+ 100: "#f3ede4",
+ 200: "#e5ddd0",
+ 300: "#d1c5b4",
+ 400: "#a89680",
+ 500: "#7a6b58",
+ 600: "#5c4f3e",
+ 700: "#443a2e",
+ 800: "#322b20",
+ 900: "#2d1f10",
+ },
+ tokens: {
+ background: "#faf6f0",
+ surface: "#ffffff",
+ surfaceHover: "#f3ede4",
+ elevated: "#ffffff",
+ foreground: "#2d1f10",
+ foregroundMuted: "#7a6b58",
+ foregroundSubtle: "#a89680",
+ foregroundInverse: "#ffffff",
+ border: "#e5ddd0",
+ borderSubtle: "#f3ede4",
+ borderStrong: "#a89680",
+ input: "#ffffff",
+ inputHover: "#faf6f0",
+ inputFocus: "#ffffff",
+ ringOffset: "#ffffff",
+ },
+ },
+];
+
+// ─── Theme Preset Card ────────────────────────────────────────────────────
+
+const PresetCard: React.FC<{
+ preset: ThemePreset;
+ active: boolean;
+ onSelect: () => void;
+}> = ({ preset, active, onSelect }) => {
+ const { theme } = useTheme();
+ return (
+
+ {/* Preview swatches */}
+
+ {preset.preview.map((c, i) => (
+
+ ))}
+
{preset.name}
+
+ {preset.description}
+
+
+ );
+};
+
+// ─── Main Page ────────────────────────────────────────────────────────────
+
export const ThemingPage: React.FC = () => {
const { theme, overrideTheme, resetTheme, toggleColorMode } = useTheme();
const [activePreset, setActivePreset] = useState(theme.palette.primary[500]);
+ const [activeVariation, setActiveVariation] = useState(null);
+ const [ddValue, setDdValue] = useState("");
+ const [switchOn, setSwitchOn] = useState(false);
+ const [checked, setChecked] = useState(true);
+
+ const variations = theme.colorMode === "dark" ? DARK_PRESETS : LIGHT_PRESETS;
const applyColor = (color: string) => {
setActivePreset(color);
@@ -130,6 +516,20 @@ export const ThemingPage: React.FC = () => {
});
};
+ const applyVariation = (preset: ThemePreset) => {
+ setActiveVariation(preset.name);
+ overrideTheme({
+ neutral: preset.neutral as unknown as typeof theme.neutral,
+ tokens: preset.tokens,
+ });
+ };
+
+ const handleReset = () => {
+ setActivePreset("#ec4899");
+ setActiveVariation(null);
+ resetTheme();
+ };
+
return (
))}
{
- resetTheme();
- setActivePreset("#ec4899");
- }}
+ onClick={handleReset}
className="px-3 py-1.5 rounded-md border text-xs font-medium"
style={{
borderColor: theme.tokens.border,
@@ -307,12 +704,47 @@ toggleColorMode(); // light ↔ dark`}
+ {/* Theme Variations */}
+
+
+ {theme.colorMode === "dark" ? "Dark" : "Light"} Theme Variations
+
+
+ {variations.map((preset) => (
+
applyVariation(preset)}
+ />
+ ))}
+
+
+
+ Live Preview
+
+
Primary
+
+ Secondary
+
Outline
@@ -320,43 +752,40 @@ toggleColorMode(); // light ↔ dark`}
Ghost
+
+
+
Active
Online
Pending
-
-
- {/* Generated palette */}
-
-
- {([50, 100, 200, 300, 400, 500, 600, 700, 800, 900] as const).map(
- (shade) => (
-
-
- {shade}
-
-
- ),
- )}
+
+
+
+
{`const { overrideTheme } = useTheme();
diff --git a/src/theme/ThemeProvider.tsx b/src/theme/ThemeProvider.tsx
index 057af43..8da5e99 100644
--- a/src/theme/ThemeProvider.tsx
+++ b/src/theme/ThemeProvider.tsx
@@ -116,6 +116,15 @@ export function ThemeProvider({
);
if (nextTheme) {
setActiveThemeName(nextTheme.name);
+ // Keep palette (primary color) but clear surface overrides
+ setOverride((prev) => {
+ if (!prev?.palette) return null;
+ const kept = { palette: prev.palette };
+ if (storageKey) {
+ localStorage.setItem(`${storageKey}-override`, JSON.stringify(kept));
+ }
+ return kept;
+ });
if (storageKey) localStorage.setItem(storageKey, nextTheme.name);
}
}, [theme.colorMode, storageKey]);
diff --git a/tailwind.config.js b/tailwind.config.js
index aba1a96..6877844 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -12,6 +12,18 @@ export default {
border: 'var(--color-border)',
accent: 'var(--color-accent)',
ring: 'var(--color-ring)',
+ primary: {
+ 50: 'var(--color-primary-50)',
+ 100: 'var(--color-primary-100)',
+ 200: 'var(--color-primary-200)',
+ 300: 'var(--color-primary-300)',
+ 400: 'var(--color-primary-400)',
+ 500: 'var(--color-primary-500)',
+ 600: 'var(--color-primary-600)',
+ 700: 'var(--color-primary-700)',
+ 800: 'var(--color-primary-800)',
+ 900: 'var(--color-primary-900)',
+ },
},
borderRadius: {
sm: 'var(--radius-sm)',
From 59b14bcb345270436cef1029b3243c03d7aa3f91 Mon Sep 17 00:00:00 2001
From: Abilash-Workhall
Date: Sun, 22 Mar 2026 17:30:54 +0530
Subject: [PATCH 14/15] feat: dropdown component and documentation
---
src/Playground.tsx | 355 ++++++++----
src/assets/Icons/CheckIcon.tsx | 2 +-
src/assets/Icons/SearchIcon.tsx | 22 +
src/components/Dropdown/Dropdown.tsx | 555 ++++++++++++++-----
src/components/Dropdown/Dropdown.types.ts | 21 +-
src/components/Popover/Popover.tsx | 88 ++-
src/components/Popover/Popover.types.ts | 14 +
src/docs/DocsApp.tsx | 624 ++++++++++++++++++++--
src/docs/DocsLayout.tsx | 1 +
src/docs/components/ComponentPreview.tsx | 4 +-
src/docs/components/DropdownDemo.tsx | 234 ++++++++
src/docs/pages/Dropdown.mdx | 140 +++++
12 files changed, 1767 insertions(+), 293 deletions(-)
create mode 100644 src/assets/Icons/SearchIcon.tsx
create mode 100644 src/docs/components/DropdownDemo.tsx
create mode 100644 src/docs/pages/Dropdown.mdx
diff --git a/src/Playground.tsx b/src/Playground.tsx
index fd5aa6a..c3f5343 100644
--- a/src/Playground.tsx
+++ b/src/Playground.tsx
@@ -172,6 +172,7 @@ export default function Playground() {
const [isSimulatingData, setIsSimulatingData] = useState(true);
const [radioValue, setRadioValue] = useState("option-1");
const [dropdownValue, setDropdownValue] = useState("");
+ const [paymentValue, setPaymentValue] = useState("");
const [switchState, setSwitchState] = useState(false);
const [checkedItems, setCheckedItems] = useState({
@@ -1942,135 +1943,263 @@ export default function Playground() {
>
- Dropdown Menus
+ Dropdown
- Highly accessible, themeable select menus with support for labels,
- validation, and loading states.
+ Accessible select menus with keyboard navigation, validation, sizes,
+ and loading states.
-
- {/* Column 1: Configurable Examples */}
-
-
-
-
-
- setDropdownValue(val)}
- />
- {dropdownValue && (
-
- Output: {dropdownValue}
-
- )}
-
+
+ {/* Interactive */}
+
+
+
+
+
+ setDropdownValue(val)}
+ />
+ {dropdownValue && (
+
+ Selected: {dropdownValue}
+
+ )}
-
-
-
-
+
-
- {/* Column 2: Visual Variations */}
-
-
-
-
+
-
-
-
-
+
setPaymentValue(val)}
+ options={[
+ {
+ label: "Credit Card",
+ value: "card",
+ icon: (
+
+
+ ),
+ },
+ {
+ label: "PayPal",
+ value: "paypal",
+ icon: (
+
+
+ ),
+ },
+ {
+ label: "Bank Transfer",
+ value: "bank",
+ icon: (
+
+
+ ),
+ },
+ {
+ label: "Crypto",
+ value: "crypto",
+ icon: (
+
+
+ ),
+ disabled: true,
+ },
+ ]}
+ />
+
+ {/* States */}
+
+
+
+
+
+
+ {/* Sizes */}
+
+
+
+
+
diff --git a/src/assets/Icons/CheckIcon.tsx b/src/assets/Icons/CheckIcon.tsx
index 7eeef65..9d7f29d 100644
--- a/src/assets/Icons/CheckIcon.tsx
+++ b/src/assets/Icons/CheckIcon.tsx
@@ -10,7 +10,7 @@ export const CheckIcon = ({
return (
{
+ return (
+
+
+ );
+};
diff --git a/src/components/Dropdown/Dropdown.tsx b/src/components/Dropdown/Dropdown.tsx
index 3bd30f1..6e13244 100644
--- a/src/components/Dropdown/Dropdown.tsx
+++ b/src/components/Dropdown/Dropdown.tsx
@@ -1,24 +1,34 @@
import {
forwardRef,
useCallback,
- useState,
+ useEffect,
useId,
+ useMemo,
useRef,
- useLayoutEffect,
+ useState,
} from "react";
+import {
+ autoUpdate,
+ flip,
+ offset as offsetMiddleware,
+ size as sizeMiddleware,
+ useFloating,
+} from "@floating-ui/react";
import type { DropdownProps } from "./Dropdown.types";
+import { DROPDOWN_SIZE_MAP, SKELETON_SIZE_MAP } from "./Dropdown.constants";
import { Skeleton } from "../Skeleton";
-import { SKELETON_SIZE_MAP, DROPDOWN_SIZE_MAP } from "./Dropdown.constants";
-import { Popover } from "../Popover";
import { useTheme } from "@/theme";
import { cn } from "@/utils";
import { Chevron } from "@/assets/Icons/Chevron";
-import { CheckIcon } from "@/assets/Icons/CheckIcon";
+import { SearchIcon } from "@/assets/Icons/SearchIcon";
+import { Input } from "@/components/Input";
+
+/* ─── Dropdown ─────────────────────────────────────────────────────────────── */
const Dropdown = forwardRef((props, ref) => {
- const generatedId = useId();
+ const uid = useId();
const {
- id = generatedId,
+ id = uid,
options,
size = "md",
isLoading,
@@ -33,43 +43,239 @@ const Dropdown = forwardRef((props, ref) => {
offset = 4,
className,
zIndex,
+ placeholder = "Select option",
+ searchable = false,
+ searchPlaceholder = "Search...",
} = props;
+
const { theme } = useTheme();
- const [internalOpen, setInternalOpen] = useState(defaultOpen);
- const buttonRef = useRef(null);
- const [triggerWidth, setTriggerWidth] = useState();
- const isControlled = isOpen !== undefined;
- const open = isControlled ? isOpen : internalOpen;
-
- useLayoutEffect(() => {
- const updateWidth = () => {
- if (buttonRef.current) {
- setTriggerWidth(buttonRef.current.offsetWidth);
+ const isDark = theme.colorMode === "dark";
+
+ /* ── state ─────────────────────────────────────────────────────────────── */
+
+ const [internalOpen, setInternalOpen] = useState(defaultOpen ?? false);
+ const [highlighted, setHighlighted] = useState(-1);
+ const [search, setSearch] = useState("");
+ const triggerRef = useRef(null);
+ const panelRef = useRef(null);
+ const searchRef = useRef(null);
+
+ const controlled = isOpen !== undefined;
+ const open = controlled ? isOpen : internalOpen;
+
+ /* ── filtered options ────────────────────────────────────────────────────── */
+
+ const filtered = useMemo(() => {
+ if (!searchable || !search.trim()) return options;
+ const q = search.toLowerCase();
+ return options.filter((o) => {
+ const text = typeof o.label === "string" ? o.label : String(o.label);
+ return text.toLowerCase().includes(q);
+ });
+ }, [options, search, searchable]);
+
+ /* ── floating-ui ───────────────────────────────────────────────────────── */
+
+ const { refs, floatingStyles } = useFloating({
+ open,
+ placement: "bottom-start",
+ middleware: [
+ offsetMiddleware(offset),
+ flip({ fallbackAxisSideDirection: "start" }),
+ sizeMiddleware({
+ apply({ rects, elements }) {
+ Object.assign(elements.floating.style, {
+ width: `${rects.reference.width}px`,
+ maxWidth: `${rects.reference.width}px`,
+ });
+ },
+ }),
+ ],
+ whileElementsMounted: autoUpdate,
+ });
+
+ /* ── toggle / select ───────────────────────────────────────────────────── */
+
+ const toggle = useCallback(
+ (next: boolean) => {
+ if (disabled) return;
+ if (!controlled) setInternalOpen(next);
+ if (next) {
+ const idx = options.findIndex((o) => o.value === selectedValue);
+ setHighlighted(idx >= 0 ? idx : -1);
+ setSearch("");
+ } else {
+ setHighlighted(-1);
+ setSearch("");
}
+ },
+ [disabled, controlled, options, selectedValue],
+ );
+
+ const select = useCallback(
+ (v: string) => {
+ if (disabled) return;
+ onChange?.(v);
+ toggle(false);
+ triggerRef.current?.focus();
+ },
+ [disabled, onChange, toggle],
+ );
+
+ /* ── side-effects ──────────────────────────────────────────────────────── */
+
+ // Focus search input when panel opens
+ useEffect(() => {
+ if (open && searchable) {
+ requestAnimationFrame(() => searchRef.current?.focus());
+ }
+ }, [open, searchable]);
+
+ // Close on outside click
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: PointerEvent) => {
+ const t = e.target as Node;
+ if (triggerRef.current?.contains(t) || panelRef.current?.contains(t))
+ return;
+ toggle(false);
};
+ document.addEventListener("pointerdown", handler);
+ return () => document.removeEventListener("pointerdown", handler);
+ }, [open, toggle]);
- updateWidth();
- window.addEventListener("resize", updateWidth);
- return () => window.removeEventListener("resize", updateWidth);
- }, [open]);
+ // Scroll highlighted item into view
+ useEffect(() => {
+ if (!open || highlighted < 0 || !panelRef.current) return;
+ const items =
+ panelRef.current.querySelectorAll("button[data-item]");
+ items[highlighted]?.scrollIntoView({ block: "nearest" });
+ }, [highlighted, open]);
- const handleOpenChange = useCallback(
- (newOpen: boolean) => {
- if (disabled) return;
- if (!isControlled) setInternalOpen(newOpen);
+ /* ── keyboard ──────────────────────────────────────────────────────────── */
+
+ const step = useCallback(
+ (from: number, dir: 1 | -1) => {
+ const list = filtered;
+ let i = from;
+ for (const _ of list) {
+ void _;
+ i += dir;
+ if (i >= list.length) i = 0;
+ if (i < 0) i = list.length - 1;
+ if (!list[i]?.disabled) return i;
+ }
+ return from;
},
- [disabled, isControlled],
+ [filtered],
);
- const handleSelect = useCallback(
- (newValue: string) => {
+ const handleKeyDown = useCallback(
+ (e: React.KeyboardEvent) => {
if (disabled) return;
- onChange?.(newValue);
- handleOpenChange(false);
+ const list = filtered;
+ switch (e.key) {
+ case "ArrowDown":
+ e.preventDefault();
+ if (!open) {
+ toggle(true);
+ setHighlighted(
+ Math.max(
+ list.findIndex((o) => o.value === selectedValue),
+ 0,
+ ),
+ );
+ } else {
+ setHighlighted((p) => step(p, 1));
+ }
+ break;
+ case "ArrowUp":
+ e.preventDefault();
+ if (!open) {
+ toggle(true);
+ setHighlighted(list.length - 1);
+ } else {
+ setHighlighted((p) => step(p, -1));
+ }
+ break;
+ case "Enter":
+ e.preventDefault();
+ if (open && highlighted >= 0) {
+ const o = list[highlighted];
+ if (o && !o.disabled) select(o.value);
+ } else if (!open) {
+ toggle(true);
+ }
+ break;
+ case " ":
+ // Allow space in search input
+ if (searchable && open) return;
+ e.preventDefault();
+ if (open && highlighted >= 0) {
+ const o = list[highlighted];
+ if (o && !o.disabled) select(o.value);
+ } else if (!open) {
+ toggle(true);
+ }
+ break;
+ case "Escape":
+ if (open) {
+ e.preventDefault();
+ toggle(false);
+ triggerRef.current?.focus();
+ }
+ break;
+ case "Home":
+ if (open) {
+ e.preventDefault();
+ const f = list.findIndex((o) => !o.disabled);
+ if (f >= 0) setHighlighted(f);
+ }
+ break;
+ case "End":
+ if (open) {
+ e.preventDefault();
+ const l = [...list].reverse().findIndex((o) => !o.disabled);
+ if (l >= 0) setHighlighted(list.length - 1 - l);
+ }
+ break;
+ }
+ },
+ [
+ disabled,
+ open,
+ filtered,
+ selectedValue,
+ highlighted,
+ toggle,
+ select,
+ step,
+ searchable,
+ ],
+ );
+
+ /* ── ref merging ───────────────────────────────────────────────────────── */
+
+ const setTrigger = useCallback(
+ (n: HTMLButtonElement | null) => {
+ triggerRef.current = n;
+ refs.setReference(n);
+ if (typeof ref === "function") ref(n);
+ else if (ref) ref.current = n;
+ },
+ [ref, refs],
+ );
+
+ const setPanel = useCallback(
+ (n: HTMLDivElement | null) => {
+ panelRef.current = n;
+ refs.setFloating(n);
},
- [disabled, onChange, handleOpenChange],
+ [refs],
);
+ /* ── loading ───────────────────────────────────────────────────────────── */
+
if (isLoading) {
return (
((props, ref) => {
);
}
- const selectedOption = options.find((o) => o.value === selectedValue);
- const selectedLabel = selectedOption?.label;
-
- const themeStyles = {
- "--radius": theme.shape.radiusMd,
- "--border": error ? theme.palette.error[500] : theme.tokens.borderStrong,
- "--ring": error ? theme.palette.error[500] : theme.tokens.ring,
- "--bg": theme.tokens.input,
- "--bg-hover": theme.tokens.inputHover,
- "--text": theme.tokens.foreground,
- "--placeholder": theme.tokens.foregroundSubtle,
- "--label": theme.tokens.foreground,
- "--error": theme.palette.error[500],
- "--helper": theme.tokens.foregroundMuted,
- "--elevated": theme.tokens.elevated,
- } as React.CSSProperties;
+ /* ── derived ───────────────────────────────────────────────────────────── */
+ const chosen = options.find((o) => o.value === selectedValue);
const listboxId = `${id}-listbox`;
+ const vars = {
+ "--dd-radius": theme.shape.radiusMd,
+ "--dd-radius-lg": theme.shape.radiusLg,
+ "--dd-border": error ? theme.palette.error[500] : theme.tokens.borderStrong,
+ "--dd-border-subtle": theme.tokens.borderSubtle,
+ "--dd-ring": error ? theme.palette.error[500] : theme.tokens.ring,
+ "--dd-bg": theme.tokens.input,
+ "--dd-bg-hover": theme.tokens.inputHover,
+ "--dd-text": theme.tokens.foreground,
+ "--dd-placeholder": theme.tokens.foregroundSubtle,
+ "--dd-label": theme.tokens.foreground,
+ "--dd-error": theme.palette.error[500],
+ "--dd-elevated": theme.tokens.elevated,
+ "--dd-muted": theme.tokens.foregroundMuted,
+ "--dd-accent": theme.tokens.accent,
+ "--dd-item-bg": `${theme.tokens.accent}18`,
+ "--dd-hover-bg": `${theme.tokens.foreground}0f`,
+ "--dd-panel-bg": theme.tokens.elevated,
+ "--dd-panel-border": theme.tokens.borderSubtle,
+ "--dd-panel-shadow": isDark
+ ? `0 8px 32px ${theme.neutral[50]}80`
+ : `0 8px 32px ${theme.neutral[400]}14`,
+ } as React.CSSProperties;
+
+ /* ── render ────────────────────────────────────────────────────────────── */
+
return (
-
+
{label && (
{label}
- {required && * }
+ {required && * }
)}
-
- {options.map((option) => (
- handleSelect(option.value)}
- className={cn(
- "px-3 py-2 text-sm text-left transition-colors outline-none flex items-center justify-between",
- option.value === selectedValue
- ? "bg-primary-50 text-primary-900 font-medium"
- : "text-[var(--text)] hover:bg-gray-100",
- option.disabled && "opacity-50 cursor-not-allowed",
- )}
- >
- {option.label}
- {option.value === selectedValue && (
-
- ))}
-
- }
- >
+
+
+ {/* ── trigger ──────────────────────────────────────────────────── */}
{
- // Handle both local ref and forwarded ref
- (buttonRef as any).current = node;
- if (typeof ref === "function") {
- ref(node);
- } else if (ref) {
- (ref as any).current = node;
- }
- }}
+ ref={setTrigger}
type="button"
- role="combobox"
aria-expanded={open}
aria-haspopup="listbox"
- aria-controls={listboxId}
+ aria-controls={open ? listboxId : undefined}
disabled={disabled}
+ onClick={() => toggle(!open)}
+ onKeyDown={!searchable || !open ? handleKeyDown : undefined}
className={cn(
- "flex items-center justify-between w-full border border-[var(--border)]",
- "focus:outline-none focus:ring-2 focus:ring-[var(--ring)] focus:border-transparent",
- "hover:bg-[var(--bg-hover)] rounded-[var(--radius)] transition-all",
+ "flex items-center justify-between w-full",
+ "border border-[var(--dd-border)] bg-[var(--dd-bg)]",
+ "focus:outline-none focus:ring-2 focus:ring-[var(--dd-ring)] focus:border-transparent",
+ "hover:bg-[var(--dd-bg-hover)]",
+ "rounded-[var(--dd-radius)] transition-all duration-150",
DROPDOWN_SIZE_MAP[size],
- !selectedLabel ? "text-[var(--placeholder)]" : "text-[var(--text)]",
+ chosen ? "text-[var(--dd-text)]" : "text-[var(--dd-placeholder)]",
disabled && "opacity-50 cursor-not-allowed",
className,
)}
- style={themeStyles}
>
- {selectedLabel || "Select option"}
+
+ {chosen?.icon && (
+
+ {chosen.icon}
+
+ )}
+ {chosen?.label || placeholder}
+
-
+
+ {/* ── panel ────────────────────────────────────────────────────── */}
+ {open && (
+
+
+ {/* ── search input ─────────────────────────────────────── */}
+ {searchable && (
+
+
+ )}
+
+ {/* ── options list ─────────────────────────────────────── */}
+
+ {filtered.length === 0 ? (
+
+ {searchable && search
+ ? "No results found"
+ : "No options available"}
+
+ ) : (
+ filtered.map((option, i) => {
+ const active = option.value === selectedValue;
+ const lit = i === highlighted;
+
+ return (
+
select(option.value)}
+ onMouseEnter={() => setHighlighted(i)}
+ onMouseLeave={() => setHighlighted(-1)}
+ className={cn(
+ "text-[13px] text-left outline-none",
+ "flex items-center justify-between",
+ "mx-1 px-2 py-1.5 rounded-sm",
+ "transition-colors duration-75",
+
+ active && [
+ "bg-[var(--dd-item-bg)] backdrop-blur-sm",
+ "text-[var(--dd-accent)]",
+ "font-medium",
+ ],
+
+ !active && "text-[var(--dd-text)]",
+
+ lit &&
+ !active &&
+ "bg-[var(--dd-hover-bg)] backdrop-blur-sm",
+ !active &&
+ !option.disabled &&
+ "hover:bg-[var(--dd-hover-bg)] hover:backdrop-blur-sm",
+
+ option.disabled
+ ? "opacity-40 cursor-not-allowed"
+ : "cursor-pointer",
+ )}
+ style={{ width: "calc(100% - 8px)" }}
+ >
+
+ {option.icon && (
+
+ {option.icon}
+
+ )}
+ {option.label}
+
+ {active && (
+
+
+
+
+ )}
+
+ );
+ })
+ )}
+
+
+
+ )}
+
+
{error && typeof error === "string" && (
-
+
{error}
)}
@@ -207,4 +516,6 @@ const Dropdown = forwardRef((props, ref) => {
);
});
+Dropdown.displayName = "Dropdown";
+
export { Dropdown };
diff --git a/src/components/Dropdown/Dropdown.types.ts b/src/components/Dropdown/Dropdown.types.ts
index 4245014..078c984 100644
--- a/src/components/Dropdown/Dropdown.types.ts
+++ b/src/components/Dropdown/Dropdown.types.ts
@@ -2,6 +2,8 @@ export interface DropdownOption {
label: React.ReactNode;
value: string;
disabled?: boolean;
+ /** Icon element rendered before the label */
+ icon?: React.ReactNode;
}
export interface DropdownProps {
@@ -16,25 +18,28 @@ export interface DropdownProps {
/** Loading state */
isLoading?: boolean;
- /** Loading state */
+ /** Size variant */
size?: "sm" | "md" | "lg";
- /** Open state change handler */
+ /** Value change handler */
onChange?: (value: string) => void;
label?: React.ReactNode;
required?: boolean;
- /** Open state change handler */
+ /** Currently selected value */
selectedValue?: string;
- /** Trigger element */
+ /** List of options */
options: DropdownOption[];
- /** Trigger element */
+ /** Error message */
error?: string;
+ /** Placeholder text when no option is selected */
+ placeholder?: string;
+
/** Disable dropdown */
disabled?: boolean;
@@ -46,4 +51,10 @@ export interface DropdownProps {
/** z-index */
zIndex?: number;
+
+ /** Enable search/filter input inside the dropdown */
+ searchable?: boolean;
+
+ /** Placeholder for the search input */
+ searchPlaceholder?: string;
}
diff --git a/src/components/Popover/Popover.tsx b/src/components/Popover/Popover.tsx
index fb722c0..92b12bf 100644
--- a/src/components/Popover/Popover.tsx
+++ b/src/components/Popover/Popover.tsx
@@ -6,6 +6,7 @@ import {
offset as offsetMiddleware,
flip,
shift,
+ size as sizeMiddleware,
arrow as arrowMiddleware,
useClick,
useDismiss,
@@ -44,6 +45,8 @@ const Popover = forwardRef((props, ref) => {
zIndex = 1000,
usePortal = true,
portalContainer,
+ matchTriggerWidth = false,
+ keepTriggerFocus = false,
} = props;
const [internalOpen, setInternalOpen] = useState(defaultOpen);
@@ -73,6 +76,17 @@ const Popover = forwardRef((props, ref) => {
offsetMiddleware(offset + (showArrow ? ARROW_OFFSET : 0)),
flip({ fallbackAxisSideDirection: "start" }),
shift({ padding: 8 }),
+ ...(matchTriggerWidth
+ ? [
+ sizeMiddleware({
+ apply({ rects, elements }) {
+ Object.assign(elements.floating.style, {
+ width: `${rects.reference.width}px`,
+ });
+ },
+ }),
+ ]
+ : []),
/* eslint-disable react-hooks/refs */
...(showArrow
? [arrowMiddleware({ element: arrowRef, padding: 8 })]
@@ -85,9 +99,14 @@ const Popover = forwardRef((props, ref) => {
const { setReference, setFloating } = floatingRefs;
const mergedRef = useMergeRefs([setReference, ref]);
- const click = useClick(context, { enabled: !disabled });
+ const click = useClick(context, {
+ enabled: !disabled,
+ keyboardHandlers: !keepTriggerFocus,
+ });
const dismiss = useDismiss(context, { outsidePressEvent: "mousedown" });
- const role = useRole(context, { role: "dialog" });
+ const role = useRole(context, {
+ role: keepTriggerFocus ? "listbox" : "dialog",
+ });
const { getReferenceProps, getFloatingProps } = useInteractions([
click,
@@ -160,16 +179,12 @@ const Popover = forwardRef((props, ref) => {
{isMounted && (
-
+ {keepTriggerFocus ? (
((props, ref) => {
"rounded-[var(--popover-radius)]",
"shadow-[var(--popover-shadow)]",
"outline-none overflow-hidden",
- "min-w-[8rem]",
+ !matchTriggerWidth && "min-w-[8rem]",
className,
)}
role="presentation"
@@ -211,7 +226,60 @@ const Popover = forwardRef((props, ref) => {
/>
)}
-
+ ) : (
+
+
+
+ {content}
+
+
+ {showArrow && (
+
+ )}
+
+ )}
)}
diff --git a/src/components/Popover/Popover.types.ts b/src/components/Popover/Popover.types.ts
index 86858ea..bd6345e 100644
--- a/src/components/Popover/Popover.types.ts
+++ b/src/components/Popover/Popover.types.ts
@@ -63,4 +63,18 @@ export interface PopoverProps {
/** Portal container element */
portalContainer?: HTMLElement | null;
+
+ /**
+ * When true the floating panel will match the width of the trigger element.
+ * Useful for dropdowns / selects.
+ * @default false
+ */
+ matchTriggerWidth?: boolean;
+
+ /**
+ * When true, focus stays on the trigger instead of moving into the floating panel.
+ * Useful for combobox/dropdown patterns where keyboard is handled on the trigger.
+ * @default false
+ */
+ keepTriggerFocus?: boolean;
}
diff --git a/src/docs/DocsApp.tsx b/src/docs/DocsApp.tsx
index 1ba2886..4ab5521 100644
--- a/src/docs/DocsApp.tsx
+++ b/src/docs/DocsApp.tsx
@@ -15,6 +15,7 @@ const AccordionDocs = lazy(() => import("./pages/Accordion.mdx"));
const AvatarDocs = lazy(() => import("./pages/Avatar.mdx"));
const BadgeDocs = lazy(() => import("./pages/Badge.mdx"));
const CheckboxDocs = lazy(() => import("./pages/Checkbox.mdx"));
+const DropdownDocs = lazy(() => import("./pages/Dropdown.mdx"));
const ModalDocs = lazy(() => import("./pages/Modal.mdx"));
const PopoverDocs = lazy(() => import("./pages/Popover.mdx"));
const ScrollAreaDocs = lazy(() => import("./pages/ScrollArea.mdx"));
@@ -51,6 +52,11 @@ const components = [
path: "/docs/checkbox",
description: "Multi-select form controls",
},
+ {
+ name: "Dropdown",
+ path: "/docs/dropdown",
+ description: "Select menus with keyboard navigation",
+ },
{
name: "Input",
path: "/docs/input",
@@ -151,6 +157,534 @@ function generatePaletteFromColor(hex: string) {
};
}
+// ─── Surface Theme Presets ─────────────────────────────────────────────────
+
+interface SurfacePreset {
+ name: string;
+ description: string;
+ preview: [string, string, string];
+ neutral: Record
;
+ tokens: Record;
+}
+
+const DARK_SURFACE_PRESETS: SurfacePreset[] = [
+ {
+ name: "Midnight",
+ description: "Pure black",
+ preview: ["#080808", "#181818", "#f2f2f2"],
+ neutral: {
+ 50: "#080808",
+ 100: "#101010",
+ 200: "#181818",
+ 300: "#202020",
+ 400: "#383838",
+ 500: "#585858",
+ 600: "#787878",
+ 700: "#a0a0a0",
+ 800: "#c8c8c8",
+ 900: "#f2f2f2",
+ },
+ tokens: {
+ background: "#080808",
+ surface: "#101010",
+ surfaceHover: "#181818",
+ elevated: "#181818",
+ foreground: "#f2f2f2",
+ foregroundMuted: "#a0a0a0",
+ foregroundSubtle: "#787878",
+ border: "#202020",
+ borderSubtle: "#181818",
+ borderStrong: "#383838",
+ input: "#181818",
+ inputHover: "#202020",
+ inputFocus: "#101010",
+ },
+ },
+ {
+ name: "Charcoal",
+ description: "Soft dark gray",
+ preview: ["#121212", "#1e1e1e", "#e8e8e8"],
+ neutral: {
+ 50: "#121212",
+ 100: "#1a1a1a",
+ 200: "#1e1e1e",
+ 300: "#2c2c2c",
+ 400: "#404040",
+ 500: "#5e5e5e",
+ 600: "#808080",
+ 700: "#a8a8a8",
+ 800: "#d0d0d0",
+ 900: "#e8e8e8",
+ },
+ tokens: {
+ background: "#121212",
+ surface: "#1a1a1a",
+ surfaceHover: "#1e1e1e",
+ elevated: "#1e1e1e",
+ foreground: "#e8e8e8",
+ foregroundMuted: "#a8a8a8",
+ foregroundSubtle: "#808080",
+ border: "#2c2c2c",
+ borderSubtle: "#1e1e1e",
+ borderStrong: "#404040",
+ input: "#1e1e1e",
+ inputHover: "#2c2c2c",
+ inputFocus: "#1a1a1a",
+ },
+ },
+ {
+ name: "Ocean",
+ description: "Deep blue",
+ preview: ["#0a1628", "#111d33", "#e2e8f0"],
+ neutral: {
+ 50: "#0a1628",
+ 100: "#0f1d2e",
+ 200: "#111d33",
+ 300: "#1a2a42",
+ 400: "#2a3f5f",
+ 500: "#4a6182",
+ 600: "#6b82a0",
+ 700: "#8fa3bb",
+ 800: "#c4d1de",
+ 900: "#e2e8f0",
+ },
+ tokens: {
+ background: "#0a1628",
+ surface: "#0f1d2e",
+ surfaceHover: "#111d33",
+ elevated: "#111d33",
+ foreground: "#e2e8f0",
+ foregroundMuted: "#8fa3bb",
+ foregroundSubtle: "#6b82a0",
+ border: "#1a2a42",
+ borderSubtle: "#111d33",
+ borderStrong: "#2a3f5f",
+ input: "#111d33",
+ inputHover: "#1a2a42",
+ inputFocus: "#0f1d2e",
+ },
+ },
+ {
+ name: "Glass Blue",
+ description: "Frosted blue glass",
+ preview: ["#0c1929", "#132640", "#dbeafe"],
+ neutral: {
+ 50: "#0c1929",
+ 100: "#102030",
+ 200: "#132640",
+ 300: "#1c3554",
+ 400: "#2b4d75",
+ 500: "#3e6a9a",
+ 600: "#5b8aba",
+ 700: "#8cb4da",
+ 800: "#bcd5f0",
+ 900: "#dbeafe",
+ },
+ tokens: {
+ background: "#0c1929",
+ surface: "#102030",
+ surfaceHover: "#162d48",
+ elevated: "#132640",
+ foreground: "#dbeafe",
+ foregroundMuted: "#8cb4da",
+ foregroundSubtle: "#5b8aba",
+ border: "#1e3a5c",
+ borderSubtle: "#162d48",
+ borderStrong: "#2b4d75",
+ input: "#132640",
+ inputHover: "#1c3554",
+ inputFocus: "#102030",
+ },
+ },
+ {
+ name: "Slate",
+ description: "Cool blue-gray",
+ preview: ["#0f172a", "#1e293b", "#f1f5f9"],
+ neutral: {
+ 50: "#0f172a",
+ 100: "#1e293b",
+ 200: "#1e293b",
+ 300: "#334155",
+ 400: "#475569",
+ 500: "#64748b",
+ 600: "#94a3b8",
+ 700: "#cbd5e1",
+ 800: "#e2e8f0",
+ 900: "#f1f5f9",
+ },
+ tokens: {
+ background: "#0f172a",
+ surface: "#1e293b",
+ surfaceHover: "#273549",
+ elevated: "#1e293b",
+ foreground: "#f1f5f9",
+ foregroundMuted: "#94a3b8",
+ foregroundSubtle: "#64748b",
+ border: "#334155",
+ borderSubtle: "#1e293b",
+ borderStrong: "#475569",
+ input: "#1e293b",
+ inputHover: "#334155",
+ inputFocus: "#1e293b",
+ },
+ },
+ {
+ name: "Violet",
+ description: "Purple tint",
+ preview: ["#0e0a1a", "#1a1425", "#ede9fe"],
+ neutral: {
+ 50: "#0e0a1a",
+ 100: "#141020",
+ 200: "#1a1425",
+ 300: "#251e35",
+ 400: "#3b3255",
+ 500: "#5b5278",
+ 600: "#7c739a",
+ 700: "#a09abc",
+ 800: "#cbc5de",
+ 900: "#ede9fe",
+ },
+ tokens: {
+ background: "#0e0a1a",
+ surface: "#141020",
+ surfaceHover: "#1a1425",
+ elevated: "#1a1425",
+ foreground: "#ede9fe",
+ foregroundMuted: "#a09abc",
+ foregroundSubtle: "#7c739a",
+ border: "#251e35",
+ borderSubtle: "#1a1425",
+ borderStrong: "#3b3255",
+ input: "#1a1425",
+ inputHover: "#251e35",
+ inputFocus: "#141020",
+ },
+ },
+ {
+ name: "Rose Dark",
+ description: "Warm rose tint",
+ preview: ["#1a0a10", "#261218", "#fce7f3"],
+ neutral: {
+ 50: "#1a0a10",
+ 100: "#201015",
+ 200: "#261218",
+ 300: "#3a1c25",
+ 400: "#552a38",
+ 500: "#7a4055",
+ 600: "#a06078",
+ 700: "#c08898",
+ 800: "#dbb0be",
+ 900: "#fce7f3",
+ },
+ tokens: {
+ background: "#1a0a10",
+ surface: "#201015",
+ surfaceHover: "#261218",
+ elevated: "#261218",
+ foreground: "#fce7f3",
+ foregroundMuted: "#c08898",
+ foregroundSubtle: "#a06078",
+ border: "#3a1c25",
+ borderSubtle: "#261218",
+ borderStrong: "#552a38",
+ input: "#261218",
+ inputHover: "#3a1c25",
+ inputFocus: "#201015",
+ },
+ },
+ {
+ name: "Forest",
+ description: "Deep green",
+ preview: ["#071210", "#0d1f1b", "#ecfdf5"],
+ neutral: {
+ 50: "#071210",
+ 100: "#0a1a17",
+ 200: "#0d1f1b",
+ 300: "#162e28",
+ 400: "#264a40",
+ 500: "#3d6b5e",
+ 600: "#5a8c7c",
+ 700: "#86b5a2",
+ 800: "#b8d8ca",
+ 900: "#ecfdf5",
+ },
+ tokens: {
+ background: "#071210",
+ surface: "#0a1a17",
+ surfaceHover: "#0d1f1b",
+ elevated: "#0d1f1b",
+ foreground: "#ecfdf5",
+ foregroundMuted: "#86b5a2",
+ foregroundSubtle: "#5a8c7c",
+ border: "#162e28",
+ borderSubtle: "#0d1f1b",
+ borderStrong: "#264a40",
+ input: "#0d1f1b",
+ inputHover: "#162e28",
+ inputFocus: "#0a1a17",
+ },
+ },
+ {
+ name: "Warm",
+ description: "Cozy brown",
+ preview: ["#120f0b", "#1c1814", "#faf5ef"],
+ neutral: {
+ 50: "#120f0b",
+ 100: "#181510",
+ 200: "#1c1814",
+ 300: "#2a2520",
+ 400: "#3e3830",
+ 500: "#5c5448",
+ 600: "#7a7165",
+ 700: "#a09688",
+ 800: "#c8bfb2",
+ 900: "#faf5ef",
+ },
+ tokens: {
+ background: "#120f0b",
+ surface: "#181510",
+ surfaceHover: "#1c1814",
+ elevated: "#1c1814",
+ foreground: "#faf5ef",
+ foregroundMuted: "#a09688",
+ foregroundSubtle: "#7a7165",
+ border: "#2a2520",
+ borderSubtle: "#1c1814",
+ borderStrong: "#3e3830",
+ input: "#1c1814",
+ inputHover: "#2a2520",
+ inputFocus: "#181510",
+ },
+ },
+ {
+ name: "Onyx",
+ description: "True black OLED",
+ preview: ["#000000", "#0a0a0a", "#fafafa"],
+ neutral: {
+ 50: "#000000",
+ 100: "#050505",
+ 200: "#0a0a0a",
+ 300: "#151515",
+ 400: "#2a2a2a",
+ 500: "#505050",
+ 600: "#707070",
+ 700: "#999999",
+ 800: "#c0c0c0",
+ 900: "#fafafa",
+ },
+ tokens: {
+ background: "#000000",
+ surface: "#050505",
+ surfaceHover: "#0a0a0a",
+ elevated: "#0a0a0a",
+ foreground: "#fafafa",
+ foregroundMuted: "#999999",
+ foregroundSubtle: "#707070",
+ border: "#151515",
+ borderSubtle: "#0a0a0a",
+ borderStrong: "#2a2a2a",
+ input: "#0a0a0a",
+ inputHover: "#151515",
+ inputFocus: "#050505",
+ },
+ },
+];
+
+const LIGHT_SURFACE_PRESETS: SurfacePreset[] = [
+ {
+ name: "Default",
+ description: "Clean white",
+ preview: ["#fbfaf9", "#ffffff", "#111827"],
+ neutral: {
+ 50: "#fbfaf9",
+ 100: "#f3f4f6",
+ 200: "#e5e7eb",
+ 300: "#d1d5db",
+ 400: "#9ca3af",
+ 500: "#6b7280",
+ 600: "#4b5563",
+ 700: "#374151",
+ 800: "#1f2937",
+ 900: "#111827",
+ },
+ tokens: {
+ background: "#fbfaf9",
+ surface: "#ffffff",
+ surfaceHover: "#f3f4f6",
+ elevated: "#ffffff",
+ foreground: "#111827",
+ foregroundMuted: "#6b7280",
+ foregroundSubtle: "#9ca3af",
+ border: "#e5e7eb",
+ borderSubtle: "#f3f4f6",
+ borderStrong: "#9ca3af",
+ input: "#ffffff",
+ inputHover: "#fbfaf9",
+ inputFocus: "#ffffff",
+ },
+ },
+ {
+ name: "Snow Blue",
+ description: "Cool blue tint",
+ preview: ["#f0f4f8", "#ffffff", "#1a2b4a"],
+ neutral: {
+ 50: "#f0f4f8",
+ 100: "#e8edf2",
+ 200: "#d5dce6",
+ 300: "#b8c4d4",
+ 400: "#8a9ab5",
+ 500: "#5d7096",
+ 600: "#445a7a",
+ 700: "#344763",
+ 800: "#25344c",
+ 900: "#1a2b4a",
+ },
+ tokens: {
+ background: "#f0f4f8",
+ surface: "#ffffff",
+ surfaceHover: "#e8edf2",
+ elevated: "#ffffff",
+ foreground: "#1a2b4a",
+ foregroundMuted: "#5d7096",
+ foregroundSubtle: "#8a9ab5",
+ border: "#d5dce6",
+ borderSubtle: "#e8edf2",
+ borderStrong: "#8a9ab5",
+ input: "#ffffff",
+ inputHover: "#f0f4f8",
+ inputFocus: "#ffffff",
+ },
+ },
+ {
+ name: "Warm Sand",
+ description: "Soft cream",
+ preview: ["#faf6f0", "#ffffff", "#2d1f10"],
+ neutral: {
+ 50: "#faf6f0",
+ 100: "#f3ede4",
+ 200: "#e5ddd0",
+ 300: "#d1c5b4",
+ 400: "#a89680",
+ 500: "#7a6b58",
+ 600: "#5c4f3e",
+ 700: "#443a2e",
+ 800: "#322b20",
+ 900: "#2d1f10",
+ },
+ tokens: {
+ background: "#faf6f0",
+ surface: "#ffffff",
+ surfaceHover: "#f3ede4",
+ elevated: "#ffffff",
+ foreground: "#2d1f10",
+ foregroundMuted: "#7a6b58",
+ foregroundSubtle: "#a89680",
+ border: "#e5ddd0",
+ borderSubtle: "#f3ede4",
+ borderStrong: "#a89680",
+ input: "#ffffff",
+ inputHover: "#faf6f0",
+ inputFocus: "#ffffff",
+ },
+ },
+ {
+ name: "Lavender",
+ description: "Soft purple tint",
+ preview: ["#f5f3ff", "#ffffff", "#1e1040"],
+ neutral: {
+ 50: "#f5f3ff",
+ 100: "#ede9fe",
+ 200: "#ddd6fe",
+ 300: "#c4b5fd",
+ 400: "#a78bfa",
+ 500: "#7c5cbf",
+ 600: "#5b4399",
+ 700: "#453378",
+ 800: "#2e2254",
+ 900: "#1e1040",
+ },
+ tokens: {
+ background: "#f5f3ff",
+ surface: "#ffffff",
+ surfaceHover: "#ede9fe",
+ elevated: "#ffffff",
+ foreground: "#1e1040",
+ foregroundMuted: "#5b4399",
+ foregroundSubtle: "#a78bfa",
+ border: "#ddd6fe",
+ borderSubtle: "#ede9fe",
+ borderStrong: "#a78bfa",
+ input: "#ffffff",
+ inputHover: "#f5f3ff",
+ inputFocus: "#ffffff",
+ },
+ },
+ {
+ name: "Mint",
+ description: "Fresh green tint",
+ preview: ["#f0fdf4", "#ffffff", "#052e16"],
+ neutral: {
+ 50: "#f0fdf4",
+ 100: "#dcfce7",
+ 200: "#bbf7d0",
+ 300: "#86efac",
+ 400: "#4ade80",
+ 500: "#22c55e",
+ 600: "#16a34a",
+ 700: "#15803d",
+ 800: "#166534",
+ 900: "#052e16",
+ },
+ tokens: {
+ background: "#f0fdf4",
+ surface: "#ffffff",
+ surfaceHover: "#dcfce7",
+ elevated: "#ffffff",
+ foreground: "#052e16",
+ foregroundMuted: "#16a34a",
+ foregroundSubtle: "#4ade80",
+ border: "#bbf7d0",
+ borderSubtle: "#dcfce7",
+ borderStrong: "#4ade80",
+ input: "#ffffff",
+ inputHover: "#f0fdf4",
+ inputFocus: "#ffffff",
+ },
+ },
+ {
+ name: "Rose",
+ description: "Warm pink tint",
+ preview: ["#fff1f2", "#ffffff", "#4c0519"],
+ neutral: {
+ 50: "#fff1f2",
+ 100: "#ffe4e6",
+ 200: "#fecdd3",
+ 300: "#fda4af",
+ 400: "#fb7185",
+ 500: "#f43f5e",
+ 600: "#e11d48",
+ 700: "#be123c",
+ 800: "#9f1239",
+ 900: "#4c0519",
+ },
+ tokens: {
+ background: "#fff1f2",
+ surface: "#ffffff",
+ surfaceHover: "#ffe4e6",
+ elevated: "#ffffff",
+ foreground: "#4c0519",
+ foregroundMuted: "#be123c",
+ foregroundSubtle: "#fb7185",
+ border: "#fecdd3",
+ borderSubtle: "#ffe4e6",
+ borderStrong: "#fb7185",
+ input: "#ffffff",
+ inputHover: "#fff1f2",
+ inputFocus: "#ffffff",
+ },
+ },
+];
+
const CopyInstallButton: React.FC = () => {
const { theme } = useTheme();
const [copied, setCopied] = useState(false);
@@ -307,49 +841,56 @@ const ColorPicker: React.FC = () => {
- {/* Palette preview with clickable shades */}
+ {/* Theme Variations */}
-
-
- Generated Palette
-
-
- {copied && copied !== "hex"
- ? `Copied ${copied}!`
- : "Click a shade to copy"}
-
+
+ {theme.colorMode === "dark" ? "Dark" : "Light"} Surface Themes
-
- {([50, 100, 200, 300, 400, 500, 600, 700, 800, 900] as const).map(
- (shade) => {
- const shadeColor =
- theme.palette.primary[
- shade as keyof typeof theme.palette.primary
- ];
- return (
-
copyColor(shadeColor, String(shade))}
- title={`${shade}: ${shadeColor}`}
- >
-
- {shade}
-
-
- );
- },
- )}
+
+ {(theme.colorMode === "dark"
+ ? DARK_SURFACE_PRESETS
+ : LIGHT_SURFACE_PRESETS
+ ).map((preset) => (
+
{
+ overrideTheme({
+ neutral: preset.neutral as unknown as typeof theme.neutral,
+ tokens: preset.tokens,
+ });
+ }}
+ className="rounded-md border p-2 text-left transition-all hover:border-[var(--color-accent)]"
+ style={{
+ borderColor: theme.tokens.border,
+ backgroundColor: theme.tokens.surface,
+ }}
+ >
+
+ {preset.preview.map((c, i) => (
+
+ ))}
+
+ {preset.name}
+
+
+ {preset.description}
+
+
+ ))}
@@ -615,6 +1156,7 @@ export const DocsApp: React.FC = () => {
} />
} />
} />
+
} />
} />
} />
} />
diff --git a/src/docs/DocsLayout.tsx b/src/docs/DocsLayout.tsx
index 2815098..19aec0c 100644
--- a/src/docs/DocsLayout.tsx
+++ b/src/docs/DocsLayout.tsx
@@ -19,6 +19,7 @@ const navigation = [
{ name: "Badge", path: "/docs/badge" },
{ name: "Button", path: "/docs/button" },
{ name: "Checkbox", path: "/docs/checkbox" },
+ { name: "Dropdown", path: "/docs/dropdown" },
{ name: "Input", path: "/docs/input" },
{ name: "Modal", path: "/docs/modal" },
{ name: "Popover", path: "/docs/popover" },
diff --git a/src/docs/components/ComponentPreview.tsx b/src/docs/components/ComponentPreview.tsx
index a8f613b..e1aa054 100644
--- a/src/docs/components/ComponentPreview.tsx
+++ b/src/docs/components/ComponentPreview.tsx
@@ -24,16 +24,18 @@ export const ComponentPreview: React.FC
= ({
return (
{/* Preview */}
{
+ const [value, setValue] = useState("");
+
+ return (
+
+
+ Selected: {value}
+
+ )}
+
+ );
+};
+
+export const IconDemo: React.FC = () => {
+ const [value, setValue] = useState("");
+
+ return (
+
+
+
+
+ ),
+ },
+ {
+ label: "Crypto",
+ value: "crypto",
+ icon: (
+
+
+ ),
+ disabled: true,
+ },
+ ]}
+ />
+
+ );
+};
+
+const COUNTRIES = [
+ "United States",
+ "United Kingdom",
+ "Canada",
+ "Germany",
+ "France",
+ "Japan",
+ "Australia",
+ "Brazil",
+ "India",
+ "South Korea",
+ "Mexico",
+ "Italy",
+ "Spain",
+ "Netherlands",
+ "Sweden",
+ "Norway",
+ "Switzerland",
+ "Singapore",
+ "New Zealand",
+ "Argentina",
+];
+
+export const ScrollDemo: React.FC = () => {
+ const [value, setValue] = useState("");
+
+ return (
+
+ ({
+ label: c,
+ value: c.toLowerCase().replace(/\s+/g, "-"),
+ }))}
+ />
+
+ );
+};
+
+export const SearchDemo: React.FC = () => {
+ const [value, setValue] = useState("");
+
+ return (
+
+ ({
+ label: c,
+ value: c.toLowerCase().replace(/\s+/g, "-"),
+ }))}
+ />
+
+ );
+};
+
+export const SizesDemo: React.FC = () => (
+
+);
+
+export const StatesDemo: React.FC = () => (
+
+
+);
diff --git a/src/docs/pages/Dropdown.mdx b/src/docs/pages/Dropdown.mdx
new file mode 100644
index 0000000..df7accf
--- /dev/null
+++ b/src/docs/pages/Dropdown.mdx
@@ -0,0 +1,140 @@
+import { Dropdown } from '@/components/Dropdown/Dropdown';
+import { ComponentPreview } from '../components/ComponentPreview';
+import { PropsTable } from '../components/PropsTable';
+import { PageHeader } from '../components/PageHeader';
+import { BasicDemo, IconDemo, ScrollDemo, SearchDemo, SizesDemo, StatesDemo } from '../components/DropdownDemo';
+
+
+
+## Basic Usage
+
+Use `selectedValue` and `onChange` to control the selected option. Options support `label`, `value`, and `disabled`.
+
+
`}>
+
+
+
+## With Icons
+
+Each option can include an `icon` prop. The icon is displayed in both the trigger and the dropdown list.
+
+
},
+ { label: "Bank Transfer", value: "bank", icon:
},
+ { label: "Crypto", value: "crypto", icon:
, disabled: true },
+ ]}
+ selectedValue={value}
+ onChange={setValue}
+/>`}>
+
+
+
+## Searchable
+
+Add `searchable` to enable a filter input inside the panel. Options are filtered as you type, with keyboard navigation still fully supported.
+
+
({ label: c, value: c.toLowerCase() }))}
+ selectedValue={value}
+ onChange={setValue}
+/>`}>
+
+
+## Scrollable List
+
+When options exceed the panel height, a themed scrollbar appears. Keyboard navigation (Arrow keys, Home, End) auto-scrolls the highlighted item into view.
+
+
({ label: c, value: c.toLowerCase() }))}
+ selectedValue={value}
+ onChange={setValue}
+/>`}>
+
+
+## Sizes
+
+Three size variants: `sm`, `md` (default), and `lg`.
+
+
+
+
`}>
+
+
+
+## States
+
+Error validation, disabled state, and loading skeleton.
+
+
+
+
`}>
+
+
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Arrow Down` | Open dropdown / highlight next option |
+| `Arrow Up` | Open dropdown / highlight previous option |
+| `Enter` / `Space` | Select highlighted option / open dropdown |
+| `Escape` | Close dropdown |
+| `Home` | Jump to first enabled option |
+| `End` | Jump to last enabled option |
+| Type characters | Filter options (when `searchable` is enabled) |
+
+## Props
+
+
void', description: 'Callback fired when an option is selected.' },
+ { name: 'placeholder', type: 'string', defaultValue: '"Select option"', description: 'Placeholder text when no option is selected.' },
+ { name: 'searchable', type: 'boolean', defaultValue: 'false', description: 'Enables a search input inside the dropdown panel.' },
+ { name: 'searchPlaceholder', type: 'string', defaultValue: '"Search..."', description: 'Placeholder for the search input.' },
+ { name: 'label', type: 'ReactNode', description: 'Label rendered above the trigger.' },
+ { name: 'required', type: 'boolean', defaultValue: 'false', description: 'Shows a required indicator on the label.' },
+ { name: 'size', type: '"sm" | "md" | "lg"', defaultValue: '"md"', description: 'Size variant of the trigger.' },
+ { name: 'error', type: 'string', description: 'Error message displayed below the trigger.' },
+ { name: 'disabled', type: 'boolean', defaultValue: 'false', description: 'Disables the dropdown.' },
+ { name: 'isLoading', type: 'boolean', defaultValue: 'false', description: 'Shows a skeleton loader.' },
+ { name: 'isOpen', type: 'boolean', description: 'Controlled open state.' },
+ { name: 'defaultOpen', type: 'boolean', defaultValue: 'false', description: 'Initial open state (uncontrolled).' },
+ { name: 'offset', type: 'number', defaultValue: '4', description: 'Gap between trigger and panel in pixels.' },
+ { name: 'zIndex', type: 'number', defaultValue: '50', description: 'CSS z-index of the dropdown panel.' },
+ { name: 'className', type: 'string', description: 'Custom class for the trigger button.' },
+]} />
+
+### DropdownOption
+
+
Date: Sun, 22 Mar 2026 17:37:15 +0530
Subject: [PATCH 15/15] fix: test case
---
src/components/Checkbox/Checkbox.test.tsx | 2 +-
src/components/RadioGroup/RadioGroup.test.tsx | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/components/Checkbox/Checkbox.test.tsx b/src/components/Checkbox/Checkbox.test.tsx
index a1e79b7..f379ccc 100644
--- a/src/components/Checkbox/Checkbox.test.tsx
+++ b/src/components/Checkbox/Checkbox.test.tsx
@@ -1,6 +1,6 @@
import { render, screen, fireEvent } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
-import Checkbox from "./Checkbox";
+import { Checkbox } from "./Checkbox";
import { ThemeProvider } from "@/theme";
const renderWithTheme = (ui: React.ReactElement) => {
diff --git a/src/components/RadioGroup/RadioGroup.test.tsx b/src/components/RadioGroup/RadioGroup.test.tsx
index 5677804..ed09631 100644
--- a/src/components/RadioGroup/RadioGroup.test.tsx
+++ b/src/components/RadioGroup/RadioGroup.test.tsx
@@ -1,6 +1,6 @@
import { render, screen, fireEvent } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
-import RadioGroup from "./RadioGroup";
+import { RadioGroup } from "./RadioGroup";
import { ThemeProvider } from "../../theme";
const options = [