@alankrit2/ui 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @alankrit/ui
+
+Production-quality, headless, accessible React UI components built with TypeScript.
+
+## Features
+
+- 🎨 **Headless** - Unstyled components that you can customize however you want
+- ♿ **Accessible** - WAI-ARIA compliant with full keyboard navigation
+- 🎯 **TypeScript** - Fully typed API with excellent IntelliSense support
+- 🪶 **Lightweight** - Zero dependencies (except React peer deps)
+- 🔧 **Flexible** - Controlled and uncontrolled modes, compound components, asChild pattern
+- 🌙 **Theme-ready** - Works seamlessly with any styling solution
+
+## Installation
+
+```bash
+npm install @alankrit/ui
+# or
+pnpm add @alankrit/ui
+# or
+yarn add @alankrit/ui
+```
+
+## Peer Dependencies
+
+This library requires React 18+ or React 19+:
+
+```bash
+npm install react react-dom
+```
+
+## Components
+
+### Dialog
+
+A fully accessible modal dialog component.
+
+```tsx
+import { Dialog } from '@alankrit/ui';
+
+function MyApp() {
+  return (
+    <Dialog>
+      <Dialog.Trigger asChild>
+        <button>Open Dialog</button>
+      </Dialog.Trigger>
+
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
+        
+        <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 rounded-lg">
+          <Dialog.Title className="text-xl font-bold">
+            Dialog Title
+          </Dialog.Title>
+          
+          <Dialog.Description className="mt-2 text-gray-600">
+            Dialog description goes here.
+          </Dialog.Description>
+
+          <div className="mt-4 flex gap-2">
+            <Dialog.Close asChild>
+              <button>Cancel</button>
+            </Dialog.Close>
+            <button>Confirm</button>
+          </div>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+#### Controlled Mode
+
+```tsx
+import { useState } from 'react';
+import { Dialog } from '@alankrit/ui';
+
+function ControlledDialog() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Open</button>
+      
+      <Dialog open={open} onOpenChange={setOpen}>
+        <Dialog.Portal>
+          <Dialog.Overlay className="fixed inset-0 bg-black/50" />
+          <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6">
+            <Dialog.Title>Controlled Dialog</Dialog.Title>
+            <Dialog.Close asChild>
+              <button>Close</button>
+            </Dialog.Close>
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog>
+    </>
+  );
+}
+```
+
+## API Reference
+
+### Dialog
+
+Root component that manages dialog state.
+
+**Props:**
+- `open?: boolean` - Controlled open state
+- `defaultOpen?: boolean` - Default open state (uncontrolled)
+- `onOpenChange?: (open: boolean) => void` - Callback when open state changes
+
+### Dialog.Trigger
+
+Button that opens the dialog.
+
+**Props:**
+- `asChild?: boolean` - Merge props with child element instead of rendering a button
+
+### Dialog.Portal
+
+Renders children in a portal outside the DOM hierarchy.
+
+**Props:**
+- `container?: HTMLElement` - Portal container (defaults to `document.body`)
+
+### Dialog.Overlay
+
+Semi-transparent backdrop. Clicking it closes the dialog.
+
+### Dialog.Content
+
+Main dialog content container with focus management and ARIA attributes.
+
+**Props:**
+- `onEscapeKeyDown?: (event: KeyboardEvent) => void` - Callback when Escape is pressed
+- `onOverlayClick?: (event: MouseEvent) => void` - Callback when overlay is clicked
+
+### Dialog.Title
+
+Dialog title, automatically linked via `aria-labelledby`.
+
+### Dialog.Description
+
+Dialog description, automatically linked via `aria-describedby`.
+
+### Dialog.Close
+
+Button that closes the dialog.
+
+**Props:**
+- `asChild?: boolean` - Merge props with child element instead of rendering a button
+
+## Accessibility
+
+All components follow WAI-ARIA best practices:
+
+- ✅ Focus trap - Focus stays inside dialog when open
+- ✅ Focus return - Focus returns to trigger on close
+- ✅ Keyboard navigation - Escape to close, Tab to cycle
+- ✅ ARIA attributes - Proper roles and labels
+- ✅ Screen reader support - Fully accessible to assistive technologies
+
+## Styling
+
+This library is headless, meaning it provides zero styles. You can style components using:
+
+- **Tailwind CSS** - Add utility classes directly
+- **CSS Modules** - Import and apply CSS modules
+- **Styled Components** - Wrap components with styled-components
+- **Emotion** - Use the css prop or styled API
+- **Plain CSS** - Add className and style with regular CSS
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { DialogProps, DialogContentProps } from '@alankrit/ui';
+```
+
+## License
+
+MIT © alankrit
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Links
+
+- [GitHub Repository](https://github.com/alankrit/ui)
+- [Documentation](https://github.com/alankrit/ui#readme)
+- [Report Issues](https://github.com/alankrit/ui/issues)

package/dist/index.d.mts

@@ -0,0 +1,211 @@
+import * as React$1 from 'react';
+
+interface DialogProps {
+    /** Controlled open state */
+    open?: boolean;
+    /** Default open state for uncontrolled mode */
+    defaultOpen?: boolean;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Dialog content */
+    children: React$1.ReactNode;
+}
+interface DialogTriggerProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render as child element instead of button wrapper */
+    asChild?: boolean;
+    children: React$1.ReactNode;
+}
+interface DialogPortalProps {
+    /** Portal container element */
+    container?: HTMLElement;
+    children: React$1.ReactNode;
+}
+interface DialogOverlayProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    children?: React$1.ReactNode;
+}
+interface DialogContentProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /** Callback when Escape key is pressed */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /** Callback when overlay is clicked */
+    onOverlayClick?: (event: React$1.MouseEvent) => void;
+    children: React$1.ReactNode;
+}
+interface DialogTitleProps extends React$1.HTMLAttributes<HTMLHeadingElement> {
+    children: React$1.ReactNode;
+}
+interface DialogDescriptionProps extends React$1.HTMLAttributes<HTMLParagraphElement> {
+    children: React$1.ReactNode;
+}
+interface DialogCloseProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render as child element instead of button wrapper */
+    asChild?: boolean;
+    children: React$1.ReactNode;
+}
+
+/**
+ * Dialog Trigger Component
+ *
+ * Button that opens the dialog when clicked.
+ * Supports asChild pattern for custom elements.
+ *
+ * @example
+ * <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+ *
+ * // With asChild
+ * <Dialog.Trigger asChild>
+ *   <button className="custom-button">Open</button>
+ * </Dialog.Trigger>
+ */
+declare const DialogTrigger: React$1.ForwardRefExoticComponent<DialogTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Dialog Portal Component
+ *
+ * Renders children in a portal outside the DOM hierarchy.
+ * Only renders when dialog is open.
+ *
+ * @example
+ * <Dialog.Portal>
+ *   <Dialog.Overlay />
+ *   <Dialog.Content>...</Dialog.Content>
+ * </Dialog.Portal>
+ */
+declare function DialogPortal({ container, children }: DialogPortalProps): React$1.ReactPortal | null;
+/**
+ * Dialog Overlay Component
+ *
+ * Semi-transparent backdrop behind the dialog.
+ * Clicking it closes the dialog.
+ *
+ * @example
+ * <Dialog.Overlay style={{ backgroundColor: 'rgba(0, 0, 0, 0.5)' }} />
+ */
+declare const DialogOverlay: React$1.ForwardRefExoticComponent<DialogOverlayProps & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * Dialog Content Component
+ *
+ * Main container for dialog content.
+ * Implements focus trap, keyboard handling, and ARIA attributes.
+ *
+ * @example
+ * <Dialog.Content>
+ *   <Dialog.Title>Title</Dialog.Title>
+ *   <Dialog.Description>Description</Dialog.Description>
+ *   <Dialog.Close>Close</Dialog.Close>
+ * </Dialog.Content>
+ */
+declare const DialogContent: React$1.ForwardRefExoticComponent<DialogContentProps & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * Dialog Title Component
+ *
+ * Title for the dialog, linked via aria-labelledby.
+ *
+ * @example
+ * <Dialog.Title>Confirm Action</Dialog.Title>
+ */
+declare const DialogTitle: React$1.ForwardRefExoticComponent<DialogTitleProps & React$1.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Dialog Description Component
+ *
+ * Description for the dialog, linked via aria-describedby.
+ *
+ * @example
+ * <Dialog.Description>This action cannot be undone.</Dialog.Description>
+ */
+declare const DialogDescription: React$1.ForwardRefExoticComponent<DialogDescriptionProps & React$1.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Dialog Close Component
+ *
+ * Button that closes the dialog when clicked.
+ * Supports asChild pattern for custom elements.
+ *
+ * @example
+ * <Dialog.Close>Cancel</Dialog.Close>
+ *
+ * // With asChild
+ * <Dialog.Close asChild>
+ *   <button className="custom-button">Close</button>
+ * </Dialog.Close>
+ */
+declare const DialogClose: React$1.ForwardRefExoticComponent<DialogCloseProps & React$1.RefAttributes<HTMLButtonElement>>;
+interface DialogComponent extends React$1.FC<DialogProps> {
+    Trigger: typeof DialogTrigger;
+    Portal: typeof DialogPortal;
+    Overlay: typeof DialogOverlay;
+    Content: typeof DialogContent;
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+    Close: typeof DialogClose;
+}
+declare const _default: DialogComponent;
+
+interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+}
+
+declare const Button: React$1.ForwardRefExoticComponent<ButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
+
+interface UseControlledOptions<T> {
+    /** Controlled value */
+    value?: T;
+    /** Default value for uncontrolled mode */
+    defaultValue?: T;
+    /** Change handler */
+    onChange?: (value: T) => void;
+}
+/**
+ * Hook for managing controlled/uncontrolled state pattern.
+ * Supports both controlled (value + onChange) and uncontrolled (defaultValue) modes.
+ *
+ * @example
+ * // Controlled
+ * const [value, setValue] = useControlled({ value: externalValue, onChange: setExternalValue });
+ *
+ * // Uncontrolled
+ * const [value, setValue] = useControlled({ defaultValue: false });
+ */
+declare function useControlled<T>({ value: valueProp, defaultValue, onChange, }: UseControlledOptions<T>): [T, (newValue: T) => void];
+
+/**
+ * Hook for trapping focus within a container.
+ * Handles Tab/Shift+Tab cycling and prevents focus escape.
+ *
+ * @param containerRef - Ref to the container element
+ * @param enabled - Whether the focus trap is active
+ * @param autoFocus - Whether to auto-focus the first element on mount
+ */
+declare function useFocusTrap(containerRef: React$1.RefObject<HTMLElement | null>, enabled?: boolean, autoFocus?: boolean): void;
+
+/**
+ * Hook for handling Escape key press events.
+ * Automatically cleans up event listener on unmount.
+ */
+declare function useEscapeKeydown(handler: (event: KeyboardEvent) => void, enabled?: boolean): void;
+
+/**
+ * Hook for preventing body scroll when a modal/dialog is open.
+ * This is an accessibility requirement to prevent background scrolling.
+ */
+declare function useBodyScrollLock(enabled?: boolean): void;
+
+/**
+ * Hook for generating stable, unique IDs.
+ * Uses React's useId when available, with a fallback for older versions.
+ */
+declare function useStableId(idProp?: string): string;
+
+interface SlotProps extends React$1.HTMLAttributes<HTMLElement> {
+    children?: React$1.ReactNode;
+}
+/**
+ * Slot component for the asChild pattern.
+ * When asChild is true, merges props with the child element instead of rendering a wrapper.
+ */
+declare const Slot: React$1.ForwardRefExoticComponent<SlotProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Composes multiple refs into a single ref callback.
+ * Useful when you need to forward a ref while also using it internally.
+ */
+declare function composeRefs<T>(...refs: Array<React.Ref<T> | undefined>): (node: T | null) => void;
+
+export { Button, type ButtonProps, _default as Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogOverlayProps, type DialogPortalProps, type DialogProps, type DialogTitleProps, type DialogTriggerProps, Slot, composeRefs, useBodyScrollLock, useControlled, useEscapeKeydown, useFocusTrap, useStableId };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import * as React$1 from 'react';
+
+interface DialogProps {
+    /** Controlled open state */
+    open?: boolean;
+    /** Default open state for uncontrolled mode */
+    defaultOpen?: boolean;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Dialog content */
+    children: React$1.ReactNode;
+}
+interface DialogTriggerProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render as child element instead of button wrapper */
+    asChild?: boolean;
+    children: React$1.ReactNode;
+}
+interface DialogPortalProps {
+    /** Portal container element */
+    container?: HTMLElement;
+    children: React$1.ReactNode;
+}
+interface DialogOverlayProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    children?: React$1.ReactNode;
+}
+interface DialogContentProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /** Callback when Escape key is pressed */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /** Callback when overlay is clicked */
+    onOverlayClick?: (event: React$1.MouseEvent) => void;
+    children: React$1.ReactNode;
+}
+interface DialogTitleProps extends React$1.HTMLAttributes<HTMLHeadingElement> {
+    children: React$1.ReactNode;
+}
+interface DialogDescriptionProps extends React$1.HTMLAttributes<HTMLParagraphElement> {
+    children: React$1.ReactNode;
+}
+interface DialogCloseProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render as child element instead of button wrapper */
+    asChild?: boolean;
+    children: React$1.ReactNode;
+}
+
+/**
+ * Dialog Trigger Component
+ *
+ * Button that opens the dialog when clicked.
+ * Supports asChild pattern for custom elements.
+ *
+ * @example
+ * <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+ *
+ * // With asChild
+ * <Dialog.Trigger asChild>
+ *   <button className="custom-button">Open</button>
+ * </Dialog.Trigger>
+ */
+declare const DialogTrigger: React$1.ForwardRefExoticComponent<DialogTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Dialog Portal Component
+ *
+ * Renders children in a portal outside the DOM hierarchy.
+ * Only renders when dialog is open.
+ *
+ * @example
+ * <Dialog.Portal>
+ *   <Dialog.Overlay />
+ *   <Dialog.Content>...</Dialog.Content>
+ * </Dialog.Portal>
+ */
+declare function DialogPortal({ container, children }: DialogPortalProps): React$1.ReactPortal | null;
+/**
+ * Dialog Overlay Component
+ *
+ * Semi-transparent backdrop behind the dialog.
+ * Clicking it closes the dialog.
+ *
+ * @example
+ * <Dialog.Overlay style={{ backgroundColor: 'rgba(0, 0, 0, 0.5)' }} />
+ */
+declare const DialogOverlay: React$1.ForwardRefExoticComponent<DialogOverlayProps & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * Dialog Content Component
+ *
+ * Main container for dialog content.
+ * Implements focus trap, keyboard handling, and ARIA attributes.
+ *
+ * @example
+ * <Dialog.Content>
+ *   <Dialog.Title>Title</Dialog.Title>
+ *   <Dialog.Description>Description</Dialog.Description>
+ *   <Dialog.Close>Close</Dialog.Close>
+ * </Dialog.Content>
+ */
+declare const DialogContent: React$1.ForwardRefExoticComponent<DialogContentProps & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * Dialog Title Component
+ *
+ * Title for the dialog, linked via aria-labelledby.
+ *
+ * @example
+ * <Dialog.Title>Confirm Action</Dialog.Title>
+ */
+declare const DialogTitle: React$1.ForwardRefExoticComponent<DialogTitleProps & React$1.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Dialog Description Component
+ *
+ * Description for the dialog, linked via aria-describedby.
+ *
+ * @example
+ * <Dialog.Description>This action cannot be undone.</Dialog.Description>
+ */
+declare const DialogDescription: React$1.ForwardRefExoticComponent<DialogDescriptionProps & React$1.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Dialog Close Component
+ *
+ * Button that closes the dialog when clicked.
+ * Supports asChild pattern for custom elements.
+ *
+ * @example
+ * <Dialog.Close>Cancel</Dialog.Close>
+ *
+ * // With asChild
+ * <Dialog.Close asChild>
+ *   <button className="custom-button">Close</button>
+ * </Dialog.Close>
+ */
+declare const DialogClose: React$1.ForwardRefExoticComponent<DialogCloseProps & React$1.RefAttributes<HTMLButtonElement>>;
+interface DialogComponent extends React$1.FC<DialogProps> {
+    Trigger: typeof DialogTrigger;
+    Portal: typeof DialogPortal;
+    Overlay: typeof DialogOverlay;
+    Content: typeof DialogContent;
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+    Close: typeof DialogClose;
+}
+declare const _default: DialogComponent;
+
+interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    asChild?: boolean;
+}
+
+declare const Button: React$1.ForwardRefExoticComponent<ButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
+
+interface UseControlledOptions<T> {
+    /** Controlled value */
+    value?: T;
+    /** Default value for uncontrolled mode */
+    defaultValue?: T;
+    /** Change handler */
+    onChange?: (value: T) => void;
+}
+/**
+ * Hook for managing controlled/uncontrolled state pattern.
+ * Supports both controlled (value + onChange) and uncontrolled (defaultValue) modes.
+ *
+ * @example
+ * // Controlled
+ * const [value, setValue] = useControlled({ value: externalValue, onChange: setExternalValue });
+ *
+ * // Uncontrolled
+ * const [value, setValue] = useControlled({ defaultValue: false });
+ */
+declare function useControlled<T>({ value: valueProp, defaultValue, onChange, }: UseControlledOptions<T>): [T, (newValue: T) => void];
+
+/**
+ * Hook for trapping focus within a container.
+ * Handles Tab/Shift+Tab cycling and prevents focus escape.
+ *
+ * @param containerRef - Ref to the container element
+ * @param enabled - Whether the focus trap is active
+ * @param autoFocus - Whether to auto-focus the first element on mount
+ */
+declare function useFocusTrap(containerRef: React$1.RefObject<HTMLElement | null>, enabled?: boolean, autoFocus?: boolean): void;
+
+/**
+ * Hook for handling Escape key press events.
+ * Automatically cleans up event listener on unmount.
+ */
+declare function useEscapeKeydown(handler: (event: KeyboardEvent) => void, enabled?: boolean): void;
+
+/**
+ * Hook for preventing body scroll when a modal/dialog is open.
+ * This is an accessibility requirement to prevent background scrolling.
+ */
+declare function useBodyScrollLock(enabled?: boolean): void;
+
+/**
+ * Hook for generating stable, unique IDs.
+ * Uses React's useId when available, with a fallback for older versions.
+ */
+declare function useStableId(idProp?: string): string;
+
+interface SlotProps extends React$1.HTMLAttributes<HTMLElement> {
+    children?: React$1.ReactNode;
+}
+/**
+ * Slot component for the asChild pattern.
+ * When asChild is true, merges props with the child element instead of rendering a wrapper.
+ */
+declare const Slot: React$1.ForwardRefExoticComponent<SlotProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Composes multiple refs into a single ref callback.
+ * Useful when you need to forward a ref while also using it internally.
+ */
+declare function composeRefs<T>(...refs: Array<React.Ref<T> | undefined>): (node: T | null) => void;
+
+export { Button, type ButtonProps, _default as Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogOverlayProps, type DialogPortalProps, type DialogProps, type DialogTitleProps, type DialogTriggerProps, Slot, composeRefs, useBodyScrollLock, useControlled, useEscapeKeydown, useFocusTrap, useStableId };