@kushagradhawan/kookie-ui 0.1.41 → 0.1.43

package/src/components/schemas/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Button component schemas - Single source of truth for all button-related components
+ *
+ * This module exports Zod schemas for all button components, providing:
+ * - Type-safe prop validation
+ * - Machine-readable JSON schema generation
+ * - Development-time prop validation
+ * - Consistent API across all button variants
+ *
+ * @example
+ * ```tsx
+ * import { ButtonSchema, parseButtonProps } from './schemas';
+ *
+ * // Type-safe prop validation
+ * const props = ButtonSchema.parse({ variant: 'solid', size: '2' });
+ *
+ * // Development-time validation
+ * const validatedProps = parseButtonProps(userProps);
+ * ```
+ */
+
+// Base schemas
+export { BaseButtonSchema, parseBaseButtonProps } from './base-button.schema.js';
+export type { BaseButtonProps } from './base-button.schema.js';
+
+// Button schemas
+export { ButtonSchema, parseButtonProps } from './button.schema.js';
+export type { ButtonProps } from './button.schema.js';
+
+// IconButton schemas
+export { IconButtonSchema, parseIconButtonProps } from './icon-button.schema.js';
+export type { IconButtonProps } from './icon-button.schema.js';
+
+// ToggleButton schemas
+export { ToggleButtonSchema, parseToggleButtonProps } from './toggle-button.schema.js';
+export type { ToggleButtonProps } from './toggle-button.schema.js';
+
+// ToggleIconButton schemas
+export { ToggleIconButtonSchema, parseToggleIconButtonProps } from './toggle-icon-button.schema.js';
+export type { ToggleIconButtonProps } from './toggle-icon-button.schema.js';
+
+/**
+ * Generic parseProps helper for development-time validation
+ *
+ * This function provides a type-safe way to validate props in development mode.
+ * It should only be used in development as it adds runtime overhead.
+ *
+ * @param schema - Zod schema to validate against
+ * @param props - Props to validate
+ * @returns Validated and normalized props
+ *
+ * @example
+ * ```tsx
+ * import { parseProps } from './schemas';
+ * import { ButtonSchema } from './schemas';
+ *
+ * // In development, this will validate props and show helpful errors
+ * const validatedProps = parseProps(ButtonSchema, userProps);
+ * ```
+ */
+export function parseProps<T>(schema: z.ZodSchema<T>, props: unknown): T {
+  if (process.env.NODE_ENV === 'development') {
+    return schema.parse(props);
+  }
+  return props as T;
+}
+
+import { z } from 'zod';

package/src/components/schemas/toggle-button.schema.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { ButtonSchema } from './button.schema.js';
+
+/**
+ * ToggleButton Zod schema - Single source of truth for ToggleButton component props
+ *
+ * ToggleButton extends Button with toggle functionality using Radix UI's Toggle primitive.
+ * It provides proper accessibility announcements, controlled/uncontrolled state management,
+ * and seamless integration with the existing Button component.
+ *
+ * Key features:
+ * - Controlled and uncontrolled state management
+ * - Live accessibility announcements for screen readers
+ * - Automatic state validation and warnings
+ * - Seamless integration with Button props and styling
+ * - Proper ARIA attributes for toggle functionality
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled toggle button
+ * const props = ToggleButtonSchema.parse({
+ *   defaultPressed: false,
+ *   variant: 'outline'
+ * });
+ *
+ * // Controlled toggle button
+ * const controlledProps = ToggleButtonSchema.parse({
+ *   pressed: true,
+ *   onPressedChange: (pressed) => console.log(pressed),
+ *   variant: 'soft'
+ * });
+ *
+ * // Toggle button with tooltip
+ * const tooltipProps = ToggleButtonSchema.parse({
+ *   defaultPressed: false,
+ *   tooltip: 'Toggle dark mode',
+ *   children: 'Dark Mode'
+ * });
+ * ```
+ */
+export const ToggleButtonSchema = ButtonSchema.extend({
+  /**
+   * Controlled pressed state
+   * When provided, the component is controlled and the pressed state is managed externally
+   */
+  pressed: z.boolean().optional().describe('Controlled pressed state'),
+
+  /**
+   * Callback when pressed state changes
+   * Called with the new pressed state when the toggle is activated
+   */
+  onPressedChange: z.function().optional().describe('Callback when pressed state changes'),
+
+  /**
+   * Default pressed state for uncontrolled usage
+   * Used as the initial pressed state when the component is uncontrolled
+   */
+  defaultPressed: z.boolean().optional().describe('Default pressed state for uncontrolled usage'),
+})
+  .refine(
+    (data) => {
+      // If pressed is provided, onPressedChange should also be provided for controlled usage
+      if (data.pressed !== undefined && data.onPressedChange === undefined) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'When using controlled mode (pressed prop), onPressedChange must also be provided',
+      path: ['onPressedChange'],
+    },
+  )
+  .refine(
+    (data) => {
+      // Cannot have both controlled and uncontrolled props
+      if (data.pressed !== undefined && data.defaultPressed !== undefined) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message:
+        'Cannot use both controlled (pressed) and uncontrolled (defaultPressed) props together',
+      path: ['pressed', 'defaultPressed'],
+    },
+  );
+
+/**
+ * Type derived from ToggleButton Zod schema
+ * This ensures type safety and consistency with the schema
+ */
+export type ToggleButtonProps = z.infer<typeof ToggleButtonSchema>;
+
+/**
+ * Development-only helper to validate and normalize ToggleButton props
+ * This function should only be used in development mode
+ *
+ * @param props - Props to validate and normalize
+ * @returns Validated and normalized props
+ *
+ * @example
+ * ```tsx
+ * // In development, this will validate props and show helpful errors
+ * const invalidProps = parseToggleButtonProps({
+ *   pressed: true,
+ *   defaultPressed: false
+ *   // Missing onPressedChange and conflicting controlled/uncontrolled
+ * });
+ * // Throws: "Cannot use both controlled (pressed) and uncontrolled (defaultPressed) props together"
+ *
+ * const validProps = parseToggleButtonProps({
+ *   pressed: true,
+ *   onPressedChange: (pressed) => setPressed(pressed)
+ * });
+ * ```
+ */
+export function parseToggleButtonProps(props: unknown): ToggleButtonProps {
+  if (process.env.NODE_ENV === 'development') {
+    return ToggleButtonSchema.parse(props);
+  }
+  return props as ToggleButtonProps;
+}

package/src/components/schemas/toggle-icon-button.schema.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+import { BaseButtonSchema } from './base-button.schema.js';
+
+/**
+ * ToggleIconButton Zod schema - Single source of truth for ToggleIconButton component props
+ *
+ * ToggleIconButton extends IconButton with toggle functionality using Radix UI's Toggle primitive.
+ * It provides proper accessibility announcements, controlled/uncontrolled state management,
+ * and seamless integration with the existing IconButton component.
+ *
+ * Key features:
+ * - Required accessibility attributes (aria-label, aria-labelledby, or children)
+ * - Controlled and uncontrolled state management
+ * - Live accessibility announcements for screen readers
+ * - Tooltip support for better UX
+ * - Proper ARIA attributes for toggle functionality
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled toggle icon button
+ * const props = ToggleIconButtonSchema.parse({
+ *   'aria-label': 'Toggle sidebar',
+ *   defaultPressed: false,
+ *   variant: 'ghost'
+ * });
+ *
+ * // Controlled toggle icon button
+ * const controlledProps = ToggleIconButtonSchema.parse({
+ *   'aria-label': 'Toggle dark mode',
+ *   pressed: true,
+ *   onPressedChange: (pressed) => setDarkMode(pressed),
+ *   variant: 'soft'
+ * });
+ *
+ * // Toggle icon button with tooltip
+ * const tooltipProps = ToggleIconButtonSchema.parse({
+ *   'aria-label': 'Toggle notifications',
+ *   defaultPressed: false,
+ *   tooltip: 'Toggle notification settings',
+ *   tooltipSide: 'right'
+ * });
+ * ```
+ */
+export const ToggleIconButtonSchema = BaseButtonSchema.extend({
+  /**
+   * Content to display in the tooltip on hover/focus
+   */
+  tooltip: z.string().optional().describe('Content to display in the tooltip on hover/focus'),
+
+  /**
+   * Side of the button where the tooltip should appear
+   * @default 'top'
+   */
+  tooltipSide: z
+    .enum(['top', 'right', 'bottom', 'left'])
+    .optional()
+    .default('top')
+    .describe('Side of the button where the tooltip should appear'),
+
+  /**
+   * Alignment of the tooltip relative to the button
+   * @default 'center'
+   */
+  tooltipAlign: z
+    .enum(['start', 'center', 'end'])
+    .optional()
+    .default('center')
+    .describe('Alignment of the tooltip relative to the button'),
+
+  /**
+   * Delay before showing the tooltip (in milliseconds)
+   */
+  tooltipDelayDuration: z
+    .number()
+    .optional()
+    .describe('Delay before showing the tooltip (in milliseconds)'),
+
+  /**
+   * Whether to disable hoverable content behavior
+   * @default false
+   */
+  tooltipDisableHoverableContent: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Whether to disable hoverable content behavior'),
+
+  /**
+   * ARIA label for accessibility (required if no aria-labelledby or children)
+   * Icon buttons must have an accessible name to meet WCAG guidelines
+   */
+  'aria-label': z.string().optional().describe('ARIA label for accessibility'),
+
+  /**
+   * ARIA labelled by reference (required if no aria-label or children)
+   * Icon buttons must have an accessible name to meet WCAG guidelines
+   */
+  'aria-labelledby': z.string().optional().describe('ARIA labelled by reference'),
+
+  /**
+   * Children elements (required if no aria-label or aria-labelledby)
+   * Icon buttons must have an accessible name to meet WCAG guidelines
+   */
+  children: z
+    .any()
+    .optional()
+    .describe('Children elements (required for accessibility if no aria-label)'),
+
+  /**
+   * Controlled pressed state
+   * When provided, the component is controlled and the pressed state is managed externally
+   */
+  pressed: z.boolean().optional().describe('Controlled pressed state'),
+
+  /**
+   * Callback when pressed state changes
+   * Called with the new pressed state when the toggle is activated
+   */
+  onPressedChange: z.function().optional().describe('Callback when pressed state changes'),
+
+  /**
+   * Default pressed state for uncontrolled usage
+   * Used as the initial pressed state when the component is uncontrolled
+   */
+  defaultPressed: z.boolean().optional().describe('Default pressed state for uncontrolled usage'),
+})
+  .refine((data: any) => data['aria-label'] || data['aria-labelledby'] || data.children, {
+    message:
+      "ToggleIconButton must have either 'aria-label', 'aria-labelledby', or 'children' for accessibility",
+    path: ['aria-label', 'aria-labelledby', 'children'],
+  })
+  .refine(
+    (data: any) => {
+      // If pressed is provided, onPressedChange should also be provided for controlled usage
+      if (data.pressed !== undefined && data.onPressedChange === undefined) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'When using controlled mode (pressed prop), onPressedChange must also be provided',
+      path: ['onPressedChange'],
+    },
+  )
+  .refine(
+    (data: any) => {
+      // Cannot have both controlled and uncontrolled props
+      if (data.pressed !== undefined && data.defaultPressed !== undefined) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message:
+        'Cannot use both controlled (pressed) and uncontrolled (defaultPressed) props together',
+      path: ['pressed', 'defaultPressed'],
+    },
+  );
+
+/**
+ * Type derived from ToggleIconButton Zod schema
+ * This ensures type safety and consistency with the schema
+ */
+export type ToggleIconButtonProps = z.infer<typeof ToggleIconButtonSchema>;
+
+/**
+ * Development-only helper to validate and normalize ToggleIconButton props
+ * This function should only be used in development mode
+ *
+ * @param props - Props to validate and normalize
+ * @returns Validated and normalized props
+ *
+ * @example
+ * ```tsx
+ * // In development, this will validate props and show helpful errors
+ * const invalidProps = parseToggleIconButtonProps({
+ *   pressed: true,
+ *   defaultPressed: false
+ *   // Missing onPressedChange, conflicting controlled/uncontrolled, and missing accessibility
+ * });
+ * // Throws multiple validation errors
+ *
+ * const validProps = parseToggleIconButtonProps({
+ *   'aria-label': 'Toggle menu',
+ *   pressed: true,
+ *   onPressedChange: (pressed) => setMenuOpen(pressed)
+ * });
+ * ```
+ */
+export function parseToggleIconButtonProps(props: unknown): ToggleIconButtonProps {
+  if (process.env.NODE_ENV === 'development') {
+    return ToggleIconButtonSchema.parse(props);
+  }
+  return props as ToggleIconButtonProps;
+}

package/src/components/sheet.css

@@ -1,10 +1,10 @@
 :where(.rt-SheetContent) {
   position: fixed !important;
   /* Use physical properties to integrate with width/height responsive utilities */
-  width: var(--width, 90vw) !important;
-  max-width: var(--max-width, 100vw) !important;
-  height: 100vh !important;
-  max-height: 100vh !important;
+  width: var(--width, 90vw);
+  max-width: var(--max-width, 100vw);
+  height: 100vh;
+  max-height: 100vh;
   margin: 0 !important;
   border-radius: 0 !important;
   will-change: transform;
@@ -34,9 +34,9 @@
   left: 0 !important;
   right: 0 !important;
   bottom: auto !important;
-  width: auto !important;
-  max-width: none !important;
-  height: var(--height, 75vh) !important;
+  width: auto;
+  max-width: none;
+  height: var(--height, 75vh);
   margin: 0 !important;
   border-start-start-radius: 0;
   border-start-end-radius: 0;
@@ -46,9 +46,9 @@
   left: 0 !important;
   right: 0 !important;
   top: auto !important;
-  width: auto !important;
-  max-width: none !important;
-  height: var(--height, 75vh) !important;
+  width: auto;
+  max-width: none;
+  height: var(--height, 75vh);
   margin: 0 !important;
   border-end-start-radius: 0;
   border-end-end-radius: 0;
@@ -56,7 +56,6 @@
 
 /* Overlay adjustments: avoid double-fade jank from base dialog */
 .rt-SheetOverlay::before {
-  opacity: 1 !important;
   backdrop-filter: var(--backdrop-filter-components) !important;
 }
 
@@ -83,31 +82,49 @@
   }
 
   .rt-SheetContent:where([data-state='open'][data-side='start']) {
-    animation-name: rt-sheet-open-from-start, rt-fade-in !important;
+    /* OPEN: slide first (no fade yet) */
+    animation-name: rt-sheet-open-from-start !important;
   }
   .rt-SheetContent:where([data-state='closed'][data-side='start']) {
-    animation-name: rt-sheet-close-to-start, rt-fade-out !important;
+    /* CLOSED: delay slide until content fade-out finishes */
+    animation-name: rt-sheet-close-to-start !important;
+    animation-delay: var(--motion-duration-small);
   }
 
   .rt-SheetContent:where([data-state='open'][data-side='end']) {
-    animation-name: rt-sheet-open-from-end, rt-fade-in !important;
+    animation-name: rt-sheet-open-from-end !important;
   }
   .rt-SheetContent:where([data-state='closed'][data-side='end']) {
-    animation-name: rt-sheet-close-to-end, rt-fade-out !important;
+    animation-name: rt-sheet-close-to-end !important;
+    animation-delay: var(--motion-duration-small);
   }
 
   .rt-SheetContent:where([data-state='open'][data-side='top']) {
-    animation-name: rt-sheet-open-from-top, rt-fade-in !important;
+    animation-name: rt-sheet-open-from-top !important;
   }
   .rt-SheetContent:where([data-state='closed'][data-side='top']) {
-    animation-name: rt-sheet-close-to-top, rt-fade-out !important;
+    animation-name: rt-sheet-close-to-top !important;
+    animation-delay: var(--motion-duration-small);
   }
 
   .rt-SheetContent:where([data-state='open'][data-side='bottom']) {
-    animation-name: rt-sheet-open-from-bottom, rt-fade-in !important;
+    animation-name: rt-sheet-open-from-bottom !important;
   }
   .rt-SheetContent:where([data-state='closed'][data-side='bottom']) {
-    animation-name: rt-sheet-close-to-bottom, rt-fade-out !important;
+    animation-name: rt-sheet-close-to-bottom !important;
+    animation-delay: var(--motion-duration-small);
+  }
+
+  /* OPEN: fade in inner content after slide completes */
+  .rt-SheetContent:where([data-state='open']) > * {
+    opacity: 0;
+    animation: rt-fade-in var(--motion-duration-small) var(--motion-spring-snappy) both;
+    animation-delay: var(--motion-duration-medium);
+  }
+
+  /* CLOSED: fade out inner content immediately, then container slides */
+  .rt-SheetContent:where([data-state='closed']) > * {
+    animation: rt-fade-out var(--motion-duration-small) var(--motion-spring-snappy) both;
   }
 }
 
@@ -115,4 +132,7 @@
   .rt-SheetContent {
     animation: none !important;
   }
+  .rt-SheetContent > * {
+    animation: none !important;
+  }
 }

package/src/components/sheet.tsx

@@ -42,6 +42,7 @@ import type { DialogContentOwnProps } from './dialog.props.js';
 import { Theme } from './theme.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
+import { useBodyPointerEventsCleanup } from '../hooks/use-body-pointer-events-cleanup.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 
@@ -132,10 +133,10 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>(
     );
 
     const materialValue = React.useMemo(() => {
-      if (resolvedMaterial !== undefined) {
+      if (resolvedPanelBackground !== undefined) {
         if (process.env.NODE_ENV !== 'production') {
           console.warn(
-            'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use `material` prop instead.',
+            'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use the `material` prop instead.',
           );
         }
       }
@@ -175,13 +176,65 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>(
       }
     }
 
+    // Focus management and stuck pointer-events cleanup like Dialog
+    const contentRef = React.useRef<HTMLDivElement>(null);
+    const combinedRef = React.useMemo(
+      () => (node: HTMLDivElement | null) => {
+        contentRef.current = node;
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
+        }
+      },
+      [forwardedRef],
+    );
+
+    useBodyPointerEventsCleanup();
+
+    React.useEffect(() => {
+      if (typeof window === 'undefined') return;
+      const content = contentRef.current;
+      if (!content) return;
+
+      const focusableElements = content.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+      );
+
+      if (focusableElements.length === 0) return;
+
+      const firstElement = focusableElements[0] as HTMLElement;
+      const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === 'Tab') {
+          if (event.shiftKey) {
+            if (document.activeElement === firstElement) {
+              event.preventDefault();
+              lastElement.focus();
+            }
+          } else if (document.activeElement === lastElement) {
+            event.preventDefault();
+            firstElement.focus();
+          }
+        }
+      };
+
+      content.addEventListener('keydown', handleKeyDown);
+      firstElement.focus();
+
+      return () => {
+        content.removeEventListener('keydown', handleKeyDown);
+      };
+    }, []);
+
     return (
       <DialogPrimitive.Portal container={container} forceMount={forceMount}>
         <Theme asChild>
           <DialogPrimitive.Overlay className="rt-BaseDialogOverlay rt-DialogOverlay rt-SheetOverlay">
             <DialogPrimitive.Content
               {...contentProps}
-              ref={forwardedRef}
+              ref={combinedRef}
               className={classNames(
                 'rt-BaseDialogContent',
                 'rt-SheetContent',
@@ -191,6 +244,9 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>(
               data-side={normalizedSide}
               data-material={materialValue}
               data-panel-background={materialValue}
+              tabIndex={-1}
+              role="dialog"
+              aria-modal="true"
             />
           </DialogPrimitive.Overlay>
         </Theme>
@@ -244,4 +300,7 @@ export type {
   SheetRootProps as RootProps,
   SheetTriggerProps as TriggerProps,
   SheetContentProps as ContentProps,
+  SheetTitleProps as TitleProps,
+  SheetDescriptionProps as DescriptionProps,
+  SheetCloseProps as CloseProps,
 };