@vashu96/ui 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,158 @@
+# @vashu96/ui
+
+**Crystal Flat Design System** — A collection of high-quality, glassmorphism-inspired React components. Built with React, TypeScript, and modern CSS.
+
+## Features
+
+- **Glassmorphism**: Beautiful, translucent UI elements.
+- **Dynamic Theming**: Built-in support for light/dark modes and custom color schemes.
+- **Accessible**: Follows WAI-ARIA patterns.
+- **Type-Safe**: Written in TypeScript with full type definitions.
+
+## Installation
+
+```bash
+npm install @vashu96/ui
+```
+
+## Setup
+
+### 1. Import Styles
+
+Import the global styles in your main entry point (e.g., `main.tsx` or `App.tsx`):
+
+```tsx
+import "@vashu96/ui/styles.css";
+```
+
+### 2. Wrap with ThemeProvider
+
+To enable dynamic theming and utilizing the color system, wrap your application with the `ThemeProvider`:
+
+```tsx
+import { ThemeProvider } from "@vashu96/ui";
+
+function App() {
+  return (
+    <ThemeProvider defaultMode="system" storageKey="vashu-ui-theme">
+      <YourApp />
+    </ThemeProvider>
+  );
+}
+```
+
+## Usage
+
+```tsx
+import { Button, Card, SpotlightCard } from "@vashu96/ui";
+
+function MyComponent() {
+  return (
+    <Card variant="glass">
+      <SpotlightCard>
+        <h2>Hello World</h2>
+        <Button variant="primary">Click Me</Button>
+      </SpotlightCard>
+    </Card>
+  );
+}
+```
+
+## Components
+
+The library provides a comprehensive set of components:
+
+### Layout
+
+- `Card` - Versatile container with glass variants.
+- `SpotlightCard` - Card with mouse-tracking spotlight effect.
+- `Separator` - Visual divider.
+- `Sheet` - Slide-out modal/drawer.
+- `Sidebar` - Application sidebar navigation.
+- `TOC` - Table of Contents for document navigation.
+
+### Forms
+
+- `Button` - Interactive button with multiple variants.
+- `Input` - Text input field.
+- `Textarea` - Multi-line text input.
+- `Checkbox` - Selection control.
+- `Switch` - Toggle switch.
+- `Slider` - Range slider.
+- `Select` - Dropdown selection.
+- `FormField` - Wrapper for form controls with labels and error states.
+- `Label` - Text label for form elements.
+
+### Feedback
+
+- `Badge` - Status indicator.
+- `Alert` - Urgent information banner.
+- `Toast` - Temporary notification.
+- `Progress` - Progress bar.
+- `Spinner` - Loading indicator.
+- `Skeleton` - Loading placeholder.
+- `EmptyState` - Placeholder for empty data sets.
+
+### Overlay
+
+- `Dialog` - Modal dialog window.
+- `ConfirmDialog` - Pre-configured confirmation modal.
+- `Tooltip` - Information popup on hover.
+- `Dropdown` - Menu for actions or selection.
+- `Command` - Command palette/menu.
+- `SearchCommand` - Specialized search command interface.
+
+### Navigation
+
+- `Tabs` - Tabbed interface.
+- `Breadcrumb` - Path navigation.
+- `Pagination` - Page navigation for lists.
+- `Tag` - Categorization tag.
+
+### Data Display
+
+- `Table` - Simple data table.
+- `DataTable` - Advanced table with sorting, filtering, and pagination.
+- `Avatar` - User profile image/initials.
+
+## Theming System
+
+The library includes a powerful dynamic theming system accessible via `useThemeContext`.
+
+### ThemeProvider Props
+
+| Prop           | Type                            | Default          | Description                              |
+| -------------- | ------------------------------- | ---------------- | ---------------------------------------- |
+| `defaultMode`  | `'light' \| 'dark' \| 'system'` | `'system'`       | Initial color mode.                      |
+| `defaultColor` | `ColorSchemeInput`              | `PRESETS.indigo` | Initial primary color.                   |
+| `storageKey`   | `string`                        | `'theme'`        | Key to use for localStorage persistence. |
+
+### Using the Context
+
+You can control the theme programmatically using the `useThemeContext` hook:
+
+```tsx
+import { useThemeContext, PRESETS } from "@vashu96/ui";
+
+function ThemeSwitcher() {
+  const { mode, setMode, setColors } = useThemeContext();
+
+  return (
+    <div>
+      <button onClick={() => setMode(mode === "dark" ? "light" : "dark")}>
+        Toggle Mode
+      </button>
+      <button onClick={() => setColors(PRESETS.rose)}>Set Rose Theme</button>
+    </div>
+  );
+}
+```
+
+### Color Presets
+
+Available presets via `PRESETS`:
+`indigo`, `emerald`, `rose`, `amber`, `cyan`, `violet`, `sky`, `fuchsia`, `orange`, `teal`.
+
+## License
+
+MIT

package/dist/Alert.d.ts

@@ -1,12 +1,32 @@
 import { ReactNode, HTMLAttributes } from 'react';
 type AlertVariant = "info" | "success" | "warning" | "danger";
 interface AlertProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The visual style of the alert.
+     * @default "info"
+     */
     variant?: AlertVariant;
+    /**
+     * Optional title for the alert.
+     */
     title?: string;
+    /**
+     * Custom icon. If not provided, a default icon is used based on the variant.
+     */
     icon?: ReactNode;
+    /**
+     * Whether the alert can be dismissed.
+     * @default false
+     */
     dismissible?: boolean;
+    /**
+     * Callback when the alert is dismissed.
+     */
     onDismiss?: () => void;
     children?: ReactNode;
 }
+/**
+ * Alert component for displaying messages.
+ */
 declare const Alert: import('react').ForwardRefExoticComponent<AlertProps & import('react').RefAttributes<HTMLDivElement>>;
 export { Alert, type AlertProps, type AlertVariant };

package/dist/Avatar.d.ts

@@ -1,10 +1,26 @@
 import { HTMLAttributes } from 'react';
 type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 interface AvatarProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Image source URL.
+     */
     src?: string;
+    /**
+     * Alt text for the image. Also used for fallback initials if `fallback` is not provided.
+     */
     alt?: string;
+    /**
+     * Explicit fallback text (e.g. initials).
+     */
     fallback?: string;
+    /**
+     * Size of the avatar.
+     * @default "md"
+     */
     size?: AvatarSize;
 }
+/**
+ * Avatar component with image and fallback support.
+ */
 declare const Avatar: import('react').ForwardRefExoticComponent<AvatarProps & import('react').RefAttributes<HTMLDivElement>>;
 export { Avatar, type AvatarProps, type AvatarSize };

package/dist/Badge.d.ts

@@ -1,7 +1,14 @@
 import { HTMLAttributes } from 'react';
 type BadgeVariant = "default" | "success" | "warning" | "danger" | "info";
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    /**
+     * The visual style of the badge.
+     * @default "default"
+     */
     variant?: BadgeVariant;
 }
+/**
+ * Small count and labeling component.
+ */
 declare const Badge: import('react').ForwardRefExoticComponent<BadgeProps & import('react').RefAttributes<HTMLSpanElement>>;
 export { Badge, type BadgeProps, type BadgeVariant };

package/dist/Breadcrumb.d.ts

@@ -1,12 +1,37 @@
 import { ReactNode, HTMLAttributes } from 'react';
+/**
+ * Breadcrumb navigation container.
+ */
 declare const Breadcrumb: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & import('react').RefAttributes<HTMLElement>>;
+/**
+ * Ordered list container for breadcrumb items.
+ */
 declare const BreadcrumbList: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLOListElement> & import('react').RefAttributes<HTMLOListElement>>;
+/**
+ * Individual item in the breadcrumb list.
+ */
 declare const BreadcrumbItem: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLLIElement> & import('react').RefAttributes<HTMLLIElement>>;
 interface BreadcrumbLinkProps extends HTMLAttributes<HTMLAnchorElement> {
+    /**
+     * Link URL.
+     */
     href?: string;
+    /**
+     * Whether the link is active/hovered.
+     */
     active?: boolean;
+    /**
+     * Whether this is the current page. Rendering as a span instead of a link.
+     */
+    isCurrent?: boolean;
 }
+/**
+ * Navigation link or current page indicator.
+ */
 declare const BreadcrumbLink: import('react').ForwardRefExoticComponent<BreadcrumbLinkProps & import('react').RefAttributes<HTMLAnchorElement>>;
+/**
+ * Visual separator between breadcrumb items.
+ */
 declare function BreadcrumbSeparator({ children, className, }: {
     children?: ReactNode;
     className?: string;

package/dist/Button.d.ts

@@ -2,9 +2,25 @@ import { ButtonHTMLAttributes } from 'react';
 type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
 type ButtonSize = "sm" | "md" | "lg";
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * The visual style of the button.
+     * @default "primary"
+     */
     variant?: ButtonVariant;
+    /**
+     * The size of the button.
+     * @default "md"
+     */
     size?: ButtonSize;
+    /**
+     * Whether the button is in a loading state.
+     * Disables the button and shows a spinner.
+     * @default false
+     */
     loading?: boolean;
 }
+/**
+ * Interactive button component with support for multiple variants, sizes, and loading states.
+ */
 declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
 export { Button, type ButtonProps, type ButtonVariant, type ButtonSize };

package/dist/Card.d.ts

@@ -1,8 +1,19 @@
 import { HTMLAttributes } from 'react';
 type CardVariant = "glass" | "solid" | "outline";
 interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The visual style of the card.
+     * @default "glass"
+     */
     variant?: CardVariant;
+    /**
+     * Padding size for the card content.
+     * @default "md"
+     */
     padding?: "none" | "sm" | "md" | "lg";
 }
+/**
+ * Versatile container component with multiple visual variants and padding options.
+ */
 declare const Card: import('react').ForwardRefExoticComponent<CardProps & import('react').RefAttributes<HTMLDivElement>>;
 export { Card, type CardProps, type CardVariant };

package/dist/Checkbox.d.ts

@@ -1,7 +1,17 @@
 import { InputHTMLAttributes } from 'react';
 interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    /**
+     * Label text to align with the checkbox.
+     */
     label?: string;
+    /**
+     * If true, the checkbox appears in an indeterminate state.
+     * Useful for "select all" scenarios.
+     */
     indeterminate?: boolean;
 }
+/**
+ * Checkbox component with support for indeterminate state and labels.
+ */
 declare const Checkbox: import('react').ForwardRefExoticComponent<CheckboxProps & import('react').RefAttributes<HTMLInputElement>>;
 export { Checkbox, type CheckboxProps };

package/dist/Command.d.ts

@@ -9,13 +9,39 @@ interface CommandItem {
     disabled?: boolean;
 }
 interface CommandProps {
+    /**
+     * Whether the command palette is open.
+     */
     open: boolean;
+    /**
+     * Callback to close the command palette.
+     */
     onClose: () => void;
+    /**
+     * List of items to search/display.
+     */
     items: CommandItem[];
+    /**
+     * Placeholder text for the input.
+     * @default "Type a command or search…"
+     */
     placeholder?: string;
+    /**
+     * Message to display when no results are found.
+     * @default "No results found."
+     */
     emptyMessage?: string;
+    /**
+     * Whether the results are loading.
+     */
     loading?: boolean;
+    /**
+     * Callback for query changes (if handling filtering externally).
+     */
     onQueryChange?: (query: string) => void;
 }
+/**
+ * Command palette component (Cmd+K style).
+ */
 declare function Command({ open, onClose, items, placeholder, emptyMessage, loading, onQueryChange, }: CommandProps): import('react').ReactPortal | null;
 export { Command, type CommandProps, type CommandItem };

package/dist/ConfirmDialog.d.ts

@@ -1,13 +1,47 @@
 interface ConfirmDialogProps {
+    /**
+     * Whether the dialog is open.
+     */
     open: boolean;
+    /**
+     * Callback to close the dialog.
+     */
     onClose: () => void;
+    /**
+     * Callback when the confirm button is clicked.
+     */
     onConfirm: () => void | Promise<void>;
+    /**
+     * Title of the confirmation dialog.
+     */
     title: string;
+    /**
+     * Description of the confirmation action.
+     */
     description: string;
+    /**
+     * Text for the confirm button.
+     * @default "Confirm"
+     */
     confirmText?: string;
+    /**
+     * Text for the cancel button.
+     * @default "Cancel"
+     */
     cancelText?: string;
+    /**
+     * Visual variant of the confirm button.
+     * @default "default"
+     */
     variant?: "danger" | "default";
+    /**
+     * Whether the confirm action is loading.
+     * @default false
+     */
     loading?: boolean;
 }
+/**
+ * A pre-composed Dialog for confirmation actions.
+ */
 export declare function ConfirmDialog({ open, onClose, onConfirm, title, description, confirmText, cancelText, variant, loading, }: ConfirmDialogProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/DataTable.d.ts

@@ -1,9 +1,23 @@
 import { ColumnDef, Column } from '@tanstack/react-table';
 interface DataTableProps<TData, TValue> {
+    /**
+     * Column definitions for the table.
+     */
     columns: ColumnDef<TData, TValue>[];
+    /**
+     * Data array to display.
+     */
     data: TData[];
+    /**
+     * Placeholder text for the global search input.
+     * @default "Search..."
+     */
     searchPlaceholder?: string;
 }
+/**
+ * Advanced data table with sorting, filtering, selection, and pagination.
+ * Built on top of TanStack Table.
+ */
 export declare function DataTable<TData, TValue>({ columns, data, searchPlaceholder, }: DataTableProps<TData, TValue>): import("react/jsx-runtime").JSX.Element;
 export declare function DataTableColumnHeader<TData, TValue>({ column, title, }: {
     column: Column<TData, TValue>;

package/dist/Dialog.d.ts

@@ -1,15 +1,44 @@
 import { ReactNode, HTMLAttributes } from 'react';
 type DialogSize = "sm" | "md" | "lg";
 interface DialogProps {
+    /**
+     * Whether the dialog is open.
+     */
     open: boolean;
+    /**
+     * Callback to close the dialog.
+     */
     onClose: () => void;
+    /**
+     * Size of the dialog.
+     * @default "md"
+     */
     size?: DialogSize;
     children: ReactNode;
 }
+/**
+ * Modal dialog component.
+ * Uses native <dialog> element.
+ */
 declare function Dialog({ open, onClose, size, children }: DialogProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Header section for the Dialog.
+ */
 declare const DialogHeader: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Footer section for the Dialog.
+ */
 declare const DialogFooter: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Title element for the Dialog.
+ */
 declare const DialogTitle: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & import('react').RefAttributes<HTMLHeadingElement>>;
+/**
+ * Description element for the Dialog.
+ */
 declare const DialogDescription: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & import('react').RefAttributes<HTMLParagraphElement>>;
+/**
+ * Close button for the Dialog.
+ */
 declare function DialogClose({ children, className, ...props }: HTMLAttributes<HTMLButtonElement>): import("react/jsx-runtime").JSX.Element;
 export { Dialog, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose, type DialogProps, type DialogSize, };

package/dist/Dropdown.d.ts

@@ -2,16 +2,37 @@ import { ReactNode, HTMLAttributes } from 'react';
 interface DropdownProps {
     children: ReactNode;
 }
+/**
+ * Dropdown menu container.
+ * Manages open/close state.
+ */
 declare function Dropdown({ children }: DropdownProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Trigger button for the Dropdown.
+ */
 declare const DropdownTrigger: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLButtonElement> & import('react').RefAttributes<HTMLButtonElement>>;
 interface DropdownMenuProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Alignment of the menu relative to the trigger.
+     * @default "left"
+     */
     align?: "left" | "right";
 }
+/**
+ * Content container for the Dropdown.
+ * Uses a portal to render outside the DOM hierarchy.
+ */
 declare function DropdownMenu({ align, className, children, ...props }: DropdownMenuProps): import('react').ReactPortal | null;
 interface DropdownItemProps extends HTMLAttributes<HTMLDivElement> {
     disabled?: boolean;
+    /**
+     * Whether the item represents a destructive action.
+     */
     destructive?: boolean;
 }
+/**
+ * Individual interactive item in a DropdownMenu.
+ */
 declare const DropdownItem: import('react').ForwardRefExoticComponent<DropdownItemProps & import('react').RefAttributes<HTMLDivElement>>;
 declare function DropdownSeparator({ className }: {
     className?: string;

package/dist/EmptyState.d.ts

@@ -1,9 +1,24 @@
 import { HTMLAttributes, ReactNode } from 'react';
 interface EmptyStateProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Icon or illustration to display.
+     */
     icon?: ReactNode;
+    /**
+     * Main title text.
+     */
     title: string;
+    /**
+     * Helper description text.
+     */
     description?: string;
+    /**
+     * Optional action button or link.
+     */
     action?: ReactNode;
 }
+/**
+ * Component for displaying empty states with an optional action.
+ */
 declare const EmptyState: import('react').ForwardRefExoticComponent<EmptyStateProps & import('react').RefAttributes<HTMLDivElement>>;
 export { EmptyState, type EmptyStateProps };

package/dist/FormField.d.ts

@@ -1,11 +1,33 @@
 import { ReactNode } from 'react';
 interface FormFieldProps {
+    /**
+     * Label text for the field.
+     */
     label?: string;
+    /**
+     * Error message or boolean indicating error state.
+     */
     error?: string | boolean;
+    /**
+     * Helper text description.
+     */
     description?: string;
+    /**
+     * The form control element (Input, Select, etc.).
+     */
     children: ReactNode;
+    /**
+     * Additional CSS classes.
+     */
     className?: string;
+    /**
+     * ID of the element the label is bound to.
+     * If not provided, a unique ID is generated.
+     */
     htmlFor?: string;
 }
+/**
+ * Wrapper component for form controls that handles labels, error messages, and descriptions.
+ */
 export declare function FormField({ label, error, description, children, className, htmlFor, }: FormFieldProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/Input.d.ts

@@ -1,6 +1,16 @@
 import { InputHTMLAttributes } from 'react';
 interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    /**
+     * Error message to display below the input.
+     * If provided, the input border will turn red.
+     */
     error?: string;
 }
+/**
+ * Text input component with built-in error handling and consistent styling.
+ *
+ * @example
+ * <Input placeholder="Enter your name" error={errors.name} />
+ */
 declare const Input: import('react').ForwardRefExoticComponent<InputProps & import('react').RefAttributes<HTMLInputElement>>;
 export { Input, type InputProps };

package/dist/Label.d.ts

@@ -1,7 +1,20 @@
 import { LabelHTMLAttributes } from 'react';
 interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
+    /**
+     * Whether the field is required.
+     * Adds an asterisk or other indicator.
+     * @default false
+     */
     required?: boolean;
+    /**
+     * Whether the associated field has an error.
+     * Changes the label color to danger.
+     * @default false
+     */
     error?: boolean;
 }
+/**
+ * Text label component for form inputs.
+ */
 declare const Label: import('react').ForwardRefExoticComponent<LabelProps & import('react').RefAttributes<HTMLLabelElement>>;
 export { Label, type LabelProps };

package/dist/Pagination.d.ts

@@ -1,9 +1,25 @@
 import { HTMLAttributes } from 'react';
 interface PaginationProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * The current page number (1-indexed).
+     */
     page: number;
+    /**
+     * Total number of pages.
+     */
     totalPages: number;
+    /**
+     * Callback when the page changes.
+     */
     onPageChange: (page: number) => void;
+    /**
+     * Number of sibling pages to show around the current page.
+     * @default 1
+     */
     siblingCount?: number;
 }
+/**
+ * Pagination control for data lists.
+ */
 declare function Pagination({ page, totalPages, onPageChange, siblingCount, className, ...props }: PaginationProps): import("react/jsx-runtime").JSX.Element;
 export { Pagination, type PaginationProps };