@vashu96/ui 0.0.3 → 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vashu Chogada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,21 +1,56 @@
 # @vashu96/ui
 
-**Crystal Flat Design System** — A collection of high-quality, glassmorphism-inspired React components.
+**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.
+
+## Requirements
+
+This library requires the following peer dependencies to be installed in your project:
+
+- **React**: `^19.2.0`
+- **React DOM**: `^19.2.0`
+- **TanStack Table**: `^8.0.0` (Required for `DataTable` component)
 
 ## Installation
 
 ```bash
-npm install @vashu96/ui
+npm install @vashu96/ui @tanstack/react-table
 ```
 
+Check our `package.json` for all dependencies.
+
 ## 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
@@ -37,15 +72,114 @@ function MyComponent() {
 
 The library provides a comprehensive set of components:
 
-- **Layout**: `Card`, `SpotlightCard`, `Separator`, `Table`, `DataTable`, `Sidebar`, `Sheet`
-- **Forms**: `Button`, `Input`, `Textarea`, `Checkbox`, `Switch`, `Slider`, `Select`, `FormField`, `Label`
-- **Feedback**: `Badge`, `Alert`, `Toast`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`
-- **Overlay**: `Dialog`, `ConfirmDialog`, `Tooltip`, `Dropdown`, `Command`, `SearchCommand`
-- **Navigation**: `Tabs`, `Breadcrumb`, `Pagination`, `Tag`
+### 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`.
+
+## Publishing
+
+To publish a new version of the library to NPM, use the following commands:
+
+- **Patch release**: `npm run release` or `npm run release:patch` (e.g., v0.0.1 -> v0.0.2)
+- **Minor release**: `npm run release:minor` (e.g., v0.0.2 -> v0.1.0)
+- **Major release**: `npm run release:major` (e.g., v0.1.0 -> v1.0.0)
+
+These scripts will automatically:
 
-## Theme Support
+1. Build the production bundle.
+2. Increment the version in `package.json`.
+3. Create a git tag for the new version.
+4. Publish the package to NPM with public access.
 
-The library supports light and dark modes out of the box. Use the `data-theme="dark"` attribute on a parent element or the `html` tag to switch themes.
+> [!IMPORTANT]  
+> Ensure you are logged into NPM (`npm login`) and have a clean git working directory before running these commands.
 
 ## License
 

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,13 +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 };