@kushagradhawan/kookie-ui 0.1.41 → 0.1.43

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

@@ -0,0 +1,339 @@
+import { z } from 'zod';
+
+/**
+ * BaseButton Zod schema - Single source of truth for all button component props
+ *
+ * This schema defines the core button functionality used by Button, IconButton,
+ * ToggleButton, and ToggleIconButton components. It ensures consistency across
+ * the design system and provides machine-readable validation.
+ *
+ * @example
+ * ```tsx
+ * // Basic validation
+ * const props = BaseButtonSchema.parse({ size: '2', variant: 'solid' });
+ *
+ * // With responsive props
+ * const responsiveProps = BaseButtonSchema.parse({
+ *   size: { initial: '1', sm: '2', md: '3' },
+ *   variant: 'solid'
+ * });
+ * ```
+ */
+export const BaseButtonSchema = z
+  .object({
+    /**
+     * Polymorphic rendering - render as different HTML elements
+     * @default 'button'
+     */
+    as: z.string().optional().describe('HTML element type to render as'),
+
+    /**
+     * Use asChild to merge props with child element
+     * @default false
+     */
+    asChild: z
+      .boolean()
+      .optional()
+      .describe('Merge props with child element instead of rendering wrapper'),
+
+    /**
+     * Button size for responsive design and interface density
+     * Supports responsive objects: { initial: '1', sm: '2', md: '3', lg: '4' }
+     * @default '2'
+     */
+    size: z
+      .union([
+        z.enum(['1', '2', '3', '4']),
+        z.object({
+          initial: z.enum(['1', '2', '3', '4']).optional(),
+          sm: z.enum(['1', '2', '3', '4']).optional(),
+          md: z.enum(['1', '2', '3', '4']).optional(),
+          lg: z.enum(['1', '2', '3', '4']).optional(),
+          xl: z.enum(['1', '2', '3', '4']).optional(),
+        }),
+      ])
+      .default('2')
+      .describe('Button size for responsive design and interface density'),
+
+    /**
+     * Visual variant that determines the button's appearance and context
+     * @default 'solid'
+     */
+    variant: z
+      .enum(['classic', 'solid', 'soft', 'surface', 'outline', 'ghost', 'override'])
+      .default('solid')
+      .describe("Visual variant that determines the button's appearance and context"),
+
+    /**
+     * Accent color for the button
+     */
+    color: z
+      .enum([
+        'tomato',
+        'red',
+        'ruby',
+        'crimson',
+        'pink',
+        'plum',
+        'purple',
+        'violet',
+        'iris',
+        'indigo',
+        'blue',
+        'cyan',
+        'teal',
+        'jade',
+        'green',
+        'grass',
+        'brown',
+        'orange',
+        'sky',
+        'mint',
+        'lime',
+        'yellow',
+        'amber',
+        'gold',
+        'bronze',
+        'gray',
+      ])
+      .optional()
+      .describe('Accent color for the button'),
+
+    /**
+     * High contrast mode for better accessibility
+     * @default false
+     */
+    highContrast: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('High contrast mode for better accessibility'),
+
+    /**
+     * Border radius for the button
+     */
+    radius: z
+      .enum(['none', 'small', 'medium', 'large', 'full'])
+      .optional()
+      .describe('Border radius for the button'),
+
+    /**
+     * Loading state that shows a spinner and disables interaction
+     * Automatically sets disabled=true and provides accessibility announcements
+     * @default false
+     */
+    loading: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('Loading state that shows a spinner and disables interaction'),
+
+    /**
+     * Full width mode that expands the button to fill its container
+     * Useful for mobile layouts and form submissions
+     * @default false
+     */
+    fullWidth: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('Full width mode that expands the button to fill its container'),
+
+    /**
+     * Material type for visual rendering and depth effects
+     * Controls how the button renders its visual elements
+     */
+    material: z
+      .enum(['solid', 'translucent'])
+      .optional()
+      .describe('Material type for visual rendering and depth effects'),
+
+    /**
+     * Panel background type (deprecated)
+     * @deprecated Use `material` prop instead. This prop will be removed in a future version.
+     */
+    panelBackground: z
+      .enum(['solid', 'translucent'])
+      .optional()
+      .describe('Panel background type (deprecated - use material instead)'),
+
+    /**
+     * Flush mode that removes visual padding for seamless text integration
+     * Only effective with ghost variant
+     * @default false
+     */
+    flush: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('Flush mode that removes visual padding for seamless text integration'),
+
+    /**
+     * Disabled state
+     * @default false
+     */
+    disabled: z.boolean().optional().default(false).describe('Disabled state'),
+
+    /**
+     * Type attribute for form buttons
+     * @default 'button'
+     */
+    type: z
+      .enum(['button', 'submit', 'reset'])
+      .optional()
+      .describe('Type attribute for form buttons'),
+
+    /**
+     * Additional CSS class name
+     */
+    className: z.string().optional().describe('Additional CSS class name'),
+
+    /**
+     * Inline styles
+     */
+    style: z
+      .record(z.string(), z.union([z.string(), z.number()]))
+      .optional()
+      .describe('Inline styles'),
+
+    /**
+     * Click handler
+     */
+    onClick: z.function().optional().describe('Click handler'),
+
+    /**
+     * Focus handler
+     */
+    onFocus: z.function().optional().describe('Focus handler'),
+
+    /**
+     * Blur handler
+     */
+    onBlur: z.function().optional().describe('Blur handler'),
+
+    /**
+     * Mouse enter handler
+     */
+    onMouseEnter: z.function().optional().describe('Mouse enter handler'),
+
+    /**
+     * Mouse leave handler
+     */
+    onMouseLeave: z.function().optional().describe('Mouse leave handler'),
+
+    /**
+     * Key down handler
+     */
+    onKeyDown: z.function().optional().describe('Key down handler'),
+
+    /**
+     * Key up handler
+     */
+    onKeyUp: z.function().optional().describe('Key up handler'),
+
+    /**
+     * Form submission handler
+     */
+    onSubmit: z.function().optional().describe('Form submission handler'),
+
+    /**
+     * Tab index for keyboard navigation
+     */
+    tabIndex: z.number().optional().describe('Tab index for keyboard navigation'),
+
+    /**
+     * ARIA label for accessibility
+     */
+    'aria-label': z.string().optional().describe('ARIA label for accessibility'),
+
+    /**
+     * ARIA labelled by reference
+     */
+    'aria-labelledby': z.string().optional().describe('ARIA labelled by reference'),
+
+    /**
+     * ARIA described by reference
+     */
+    'aria-describedby': z.string().optional().describe('ARIA described by reference'),
+
+    /**
+     * ARIA expanded state
+     */
+    'aria-expanded': z.boolean().optional().describe('ARIA expanded state'),
+
+    /**
+     * ARIA pressed state
+     */
+    'aria-pressed': z.boolean().optional().describe('ARIA pressed state'),
+
+    /**
+     * ARIA current state
+     */
+    'aria-current': z
+      .union([z.boolean(), z.enum(['page', 'step', 'location', 'date', 'time'])])
+      .optional()
+      .describe('ARIA current state'),
+
+    /**
+     * ARIA controls reference
+     */
+    'aria-controls': z.string().optional().describe('ARIA controls reference'),
+
+    /**
+     * ARIA owns reference
+     */
+    'aria-owns': z.string().optional().describe('ARIA owns reference'),
+
+    /**
+     * Data attributes
+     */
+    'data-*': z.record(z.string(), z.string()).optional().describe('Data attributes'),
+
+    /**
+     * ID attribute
+     */
+    id: z.string().optional().describe('ID attribute'),
+
+    /**
+     * Title attribute for tooltip
+     */
+    title: z.string().optional().describe('Title attribute for tooltip'),
+
+    /**
+     * Role attribute
+     */
+    role: z.string().optional().describe('Role attribute'),
+
+    /**
+     * Children elements
+     */
+    children: z.any().optional().describe('Children elements'),
+  })
+  .strict();
+
+/**
+ * Type derived from BaseButton Zod schema
+ * This ensures type safety and consistency with the schema
+ */
+export type BaseButtonProps = z.infer<typeof BaseButtonSchema>;
+
+/**
+ * Development-only helper to validate and normalize 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 = parseBaseButtonProps({ size: 'invalid', variant: 'solid' });
+ * // Throws: "Invalid enum value. Expected '1' | '2' | '3' | '4', received 'invalid'"
+ * ```
+ */
+export function parseBaseButtonProps(props: unknown): BaseButtonProps {
+  if (process.env.NODE_ENV === 'development') {
+    return BaseButtonSchema.parse(props);
+  }
+  return props as BaseButtonProps;
+}

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