@kushagradhawan/kookie-ui 0.1.41 → 0.1.42

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

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import { BaseButtonSchema } from './base-button.schema.js';
+
+/**
+ * Button Zod schema - Single source of truth for Button component props
+ *
+ * The Button component is the primary interactive element in the Kookie User Interface.
+ * It provides six visual variants, four sizes, comprehensive color options, and built-in
+ * tooltip support. The component automatically handles icon sizing, supports responsive
+ * layouts, and provides accessibility compliance out of the box.
+ *
+ * @example
+ * ```tsx
+ * // Basic button validation
+ * const props = ButtonSchema.parse({ variant: 'solid', size: '2' });
+ *
+ * // Button with tooltip
+ * const tooltipProps = ButtonSchema.parse({
+ *   tooltip: 'Save your progress',
+ *   tooltipSide: 'top'
+ * });
+ *
+ * // Polymorphic button as link
+ * const linkProps = ButtonSchema.parse({
+ *   as: 'a',
+ *   href: '/dashboard',
+ *   children: 'Go to Dashboard'
+ * });
+ * ```
+ */
+export const ButtonSchema = 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'),
+
+  /**
+   * Override styles for different interaction states
+   */
+  overrideStyles: z
+    .object({
+      /** Default/idle state styles */
+      normal: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Hover state styles */
+      hover: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Active (mouse down) state styles */
+      active: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Toggle pressed state styles (data-state="on") */
+      pressed: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Open state styles (e.g., when used as a trigger) */
+      open: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Disabled state styles */
+      disabled: z
+        .object({
+          color: z.string().optional(),
+          background: z.string().optional(),
+          backgroundColor: z.string().optional(),
+          boxShadow: z.string().optional(),
+          filter: z.string().optional(),
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+          opacity: z.union([z.string(), z.number()]).optional(),
+        })
+        .optional(),
+      /** Focus-visible outline styles */
+      focus: z
+        .object({
+          outline: z.string().optional(),
+          outlineOffset: z.string().optional(),
+        })
+        .optional(),
+    })
+    .optional()
+    .describe('Override styles for different interaction states'),
+}).strict();
+
+/**
+ * Type derived from Button Zod schema
+ * This ensures type safety and consistency with the schema
+ */
+export type ButtonProps = z.infer<typeof ButtonSchema>;
+
+/**
+ * Development-only helper to validate and normalize Button 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 validatedProps = parseButtonProps({
+ *   variant: 'invalid',
+ *   tooltipSide: 'invalid'
+ * });
+ * // Throws validation errors for invalid enum values
+ * ```
+ */
+export function parseButtonProps(props: unknown): ButtonProps {
+  if (process.env.NODE_ENV === 'development') {
+    return ButtonSchema.parse(props);
+  }
+  return props as ButtonProps;
+}

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

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { BaseButtonSchema } from './base-button.schema.js';
+
+/**
+ * IconButton Zod schema - Single source of truth for IconButton component props
+ *
+ * IconButton is a specialized button component designed for icon-only interactions.
+ * It requires proper accessibility attributes to meet WCAG guidelines and provides
+ * comprehensive tooltip support for better user experience.
+ *
+ * Key features:
+ * - Required accessibility attributes (aria-label, aria-labelledby, or children)
+ * - Tooltip support for better UX
+ * - Inherits all BaseButton functionality
+ * - Optimized for icon-only interactions
+ *
+ * @example
+ * ```tsx
+ * // Basic icon button with aria-label
+ * const props = IconButtonSchema.parse({
+ *   'aria-label': 'Close dialog',
+ *   variant: 'ghost'
+ * });
+ *
+ * // Icon button with tooltip
+ * const tooltipProps = IconButtonSchema.parse({
+ *   'aria-label': 'Settings',
+ *   tooltip: 'Open settings menu',
+ *   tooltipSide: 'right'
+ * });
+ *
+ * // Icon button with children (fallback accessibility)
+ * const childrenProps = IconButtonSchema.parse({
+ *   children: <SettingsIcon />,
+ *   variant: 'soft'
+ * });
+ * ```
+ */
+export const IconButtonSchema = 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)'),
+}).refine((data) => data['aria-label'] || data['aria-labelledby'] || data.children, {
+  message:
+    "IconButton must have either 'aria-label', 'aria-labelledby', or 'children' for accessibility",
+  path: ['aria-label', 'aria-labelledby', 'children'],
+});
+
+/**
+ * Type derived from IconButton Zod schema
+ * This ensures type safety and consistency with the schema
+ */
+export type IconButtonProps = z.infer<typeof IconButtonSchema>;
+
+/**
+ * Development-only helper to validate and normalize IconButton 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 validatedProps = parseIconButtonProps({
+ *   variant: 'ghost'
+ *   // Missing accessibility - will throw error
+ * });
+ * // Throws: "IconButton must have either 'aria-label', 'aria-labelledby', or 'children' for accessibility"
+ *
+ * const validProps = parseIconButtonProps({
+ *   'aria-label': 'Close',
+ *   variant: 'ghost'
+ * });
+ * ```
+ */
+export function parseIconButtonProps(props: unknown): IconButtonProps {
+  if (process.env.NODE_ENV === 'development') {
+    return IconButtonSchema.parse(props);
+  }
+  return props as IconButtonProps;
+}

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