@catalystsoftware/ui 1.0.0

package/components/catalyst-ui/hooks/use-copy-to-clipboard.tsx

@@ -0,0 +1,419 @@
+ 
+import * as React from "react"
+
+
+/**
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ useCopyToClipboard Hook ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ★ ━━━━ ☆ ━━━━  ━━━━ ☆ ━━━━ ★
+* useCopyToClipboard: A React hook for copying text to clipboard with timeout and callbacks
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Basic Usage ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* const { isCopied, copyToClipboard } = useCopyToClipboard()
+* 
+* return (
+*   <button onClick={() => copyToClipboard('Hello World')}>
+*     {isCopied ? 'Copied!' : 'Copy Text'}
+*   </button>
+* )
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ With Custom Timeout ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // 2 second timeout
+* const { copyToClipboard } = useCopyToClipboard({ 
+*   timeout: 2000 
+* })
+* 
+* // 10 second timeout (for important info)
+* const { copyToClipboard } = useCopyToClipboard({ 
+*   timeout: 10000 
+* })
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ With Callback ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* const { copyToClipboard } = useCopyToClipboard({
+*   onCopy: () => {
+*     // Show success toast
+*     toast.success('Copied to clipboard!')
+*     
+*     // Track analytics event
+*     analytics.track('text_copied')
+*     
+*     // Update UI state
+*     setShowCopiedFeedback(true)
+*   }
+* })
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ In Component Examples ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // Copy button component
+* function CopyButton({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <button
+*       onClick={() => copyToClipboard(text)}
+*       className={isCopied ? 'copied' : ''}
+*     >
+*       {isCopied ? '✓ Copied' : 'Copy'}
+*     </button>
+*   )
+* }
+* 
+* // Code snippet with copy
+* function CodeSnippet({ code }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard({
+*     timeout: 3000,
+*     onCopy: () => console.log('Code copied:', code)
+*   })
+*   
+*   return (
+*     <div className="code-block">
+*       <pre>{code}</pre>
+*       <button onClick={() => copyToClipboard(code)}>
+*         {isCopied ? 'Copied!' : 'Copy Code'}
+*       </button>
+*     </div>
+*   )
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Multiple Copy Instances ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // Track which item was copied
+* function CopyList({ items }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <ul>
+*       {items.map((item) => (
+*         <li key={item.id}>
+*           {item.text}
+*           <button 
+*             onClick={() => copyToClipboard(item.text)}
+*             aria-label={`Copy ${item.name}`}
+*           >
+*             {isCopied === item.text ? '✓' : 'Copy'}
+*           </button>
+*         </li>
+*       ))}
+*     </ul>
+*   )
+* }
+* 
+* // Compare current copied text
+* function isCurrentlyCopied(text) {
+*   return isCopied === text
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ With UI Feedback Patterns ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // Tooltip feedback
+* function CopyWithTooltip({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <Tooltip content={isCopied ? 'Copied!' : 'Click to copy'}>
+*       <button onClick={() => copyToClipboard(text)}>
+*         {text}
+*       </button>
+*     </Tooltip>
+*   )
+* }
+* 
+* // Icon feedback
+* function CopyIconButton({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <button onClick={() => copyToClipboard(text)}>
+*       {isCopied ? <CheckIcon /> : <CopyIcon />}
+*     </button>
+*   )
+* }
+* 
+* // Toast notification
+* function CopyWithToast({ text }) {
+*   const { copyToClipboard } = useCopyToClipboard({
+*     onCopy: () => toast('Copied to clipboard!')
+*   })
+*   
+*   return (
+*     <button onClick={() => copyToClipboard(text)}>
+*       Copy
+*     </button>
+*   )
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Hook Return Values ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```typescript
+* interface UseCopyToClipboardReturn {
+*   // The currently copied text (null if nothing copied or timeout expired)
+*   isCopied: string | null
+*   
+*   // Function to copy text to clipboard
+*   copyToClipboard: (value: string) => void
+* }
+* 
+* // Usage example
+* const { isCopied, copyToClipboard } = useCopyToClipboard(options)
+* 
+* // Check if specific text is currently copied
+* const isThisCopied = isCopied === 'specific text'
+* 
+* // Check if anything is copied
+* const hasCopied = isCopied !== null
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Hook Options ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```typescript
+* interface UseCopyToClipboardOptions {
+*   // Time in milliseconds before resetting copied state (default: 4000)
+*   timeout?: number
+*   
+*   // Callback function triggered after successful copy
+*   onCopy?: () => void
+* }
+* 
+* // Examples of different configurations
+* const defaultOptions = {} // Uses default 4000ms timeout
+* 
+* const shortFeedback = { timeout: 1000 } // Quick feedback
+* 
+* const withAnalytics = {
+*   timeout: 5000,
+*   onCopy: () => trackEvent('copy_action')
+* }
+* 
+* const withMultipleCallbacks = {
+*   onCopy: () => {
+*     showToast()
+*     trackAnalytics()
+*     updateUIState()
+*   }
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Error Handling ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // Safe copy with error handling
+* function SafeCopyButton({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   const handleCopy = () => {
+*     try {
+*       copyToClipboard(text)
+*     } catch (error) {
+*       console.error('Failed to copy:', error)
+*       // Show error message to user
+*       toast.error('Failed to copy to clipboard')
+*     }
+*   }
+*   
+*   return (
+*     <button onClick={handleCopy}>
+*       {isCopied ? 'Copied!' : 'Copy'}
+*     </button>
+*   )
+* }
+* 
+* // Check clipboard API support
+* function CopyButton({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   const isClipboardSupported = 
+*     typeof window !== 'undefined' && 
+*     navigator?.clipboard?.writeText
+*   
+*   if (!isClipboardSupported) {
+*     return <span>Clipboard not supported in this browser</span>
+*   }
+*   
+*   return (
+*     <button onClick={() => copyToClipboard(text)}>
+*       {isCopied ? 'Copied!' : 'Copy'}
+*     </button>
+*   )
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Advanced Usage Patterns ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // Debounced copy (prevent rapid clicks)
+* function DebouncedCopyButton({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   const [isDebouncing, setIsDebouncing] = useState(false)
+*   
+*   const handleCopy = () => {
+*     if (isDebouncing) return
+*     
+*     setIsDebouncing(true)
+*     copyToClipboard(text)
+*     
+*     setTimeout(() => {
+*       setIsDebouncing(false)
+*     }, 1000)
+*   }
+*   
+*   return (
+*     <button 
+*       onClick={handleCopy}
+*       disabled={isDebouncing}
+*     >
+*       {isDebouncing ? 'Copying...' : isCopied ? 'Copied!' : 'Copy'}
+*     </button>
+*   )
+* }
+* 
+* // Copy with confirmation
+* function CopyWithConfirmation({ text }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   const [showConfirm, setShowConfirm] = useState(false)
+*   
+*   const handleCopy = () => {
+*     if (text.length > 1000) {
+*       setShowConfirm(true)
+*     } else {
+*       copyToClipboard(text)
+*     }
+*   }
+*   
+*   return (
+*     <>
+*       <button onClick={handleCopy}>
+*         Copy
+*       </button>
+*       
+*       {showConfirm && (
+*         <ConfirmationDialog
+*           onConfirm={() => {
+*             copyToClipboard(text)
+*             setShowConfirm(false)
+*           }}
+*           onCancel={() => setShowConfirm(false)}
+*         />
+*       )}
+*     </>
+*   )
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Integration Examples ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* ```jsx
+* // In a form field
+* function CopyableInput({ value }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <div className="input-group">
+*       <input type="text" value={value} readOnly />
+*       <button 
+*         onClick={() => copyToClipboard(value)}
+*         className={isCopied ? 'success' : ''}
+*       >
+*         {isCopied ? '✓' : 'Copy'}
+*       </button>
+*     </div>
+*   )
+* }
+* 
+* // In a data table
+* function DataTable({ rows }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   return (
+*     <table>
+*       <tbody>
+*         {rows.map(row => (
+*           <tr key={row.id}>
+*             <td>{row.value}</td>
+*             <td>
+*               <button 
+*                 onClick={() => copyToClipboard(row.value)}
+*                 aria-label={`Copy ${row.name}`}
+*               >
+*                 {isCopied === row.value ? 'Copied' : 'Copy'}
+*               </button>
+*             </td>
+*           </tr>
+*         ))}
+*       </tbody>
+*     </table>
+*   )
+* }
+* 
+* // With rich text/html
+* function CopyHTMLContent({ html }) {
+*   const { isCopied, copyToClipboard } = useCopyToClipboard()
+*   
+*   const handleCopyHTML = async () => {
+*     // Convert HTML to plain text for clipboard
+*     const plainText = html.replace(/<[^>]*>/g, '')
+*     copyToClipboard(plainText)
+*   }
+*   
+*   return (
+*     <div>
+*       <div dangerouslySetInnerHTML={{ __html: html }} />
+*       <button onClick={handleCopyHTML}>
+*         {isCopied ? 'Copied as text' : 'Copy text content'}
+*       </button>
+*     </div>
+*   )
+* }
+* ```
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Browser Support Notes ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* - **Modern Browsers**: Full support in Chrome, Firefox, Safari, Edge
+* - **HTTPS Requirement**: Clipboard API requires secure context (HTTPS)
+* - **User Permission**: Some browsers may require user permission
+* - **Fallback Consideration**: Consider fallback for older browsers
+* 
+* ★ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━ Best Practices ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ☆ ━━━━━━━━━━━━━━ ★                  
+* 1. **Provide Visual Feedback**: Always show when text is copied
+* 2. **Use Appropriate Timeout**: Match timeout to user reading speed
+* 3. **Handle Empty Values**: Check for empty or null text
+* 4. **Add Accessibility**: Include ARIA labels for screen readers
+* 5. **Consider Context**: Show what was copied (especially in lists)
+* 6. **Error Recovery**: Provide fallback options if clipboard fails
+* 7. **Security**: Be cautious with sensitive data in clipboard
+* 
+*/
+
+
+export function useCopyToClipboard({
+  timeout = 4000,
+  onCopy,
+}: {
+  timeout?: number
+  onCopy?: () => void
+} = {}) {
+  const [isCopied, setIsCopied] =React.useState<string | null>(null)
+
+  const copyToClipboard = (value: string) => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      return
+    }
+
+    if (!value) return
+
+    navigator.clipboard.writeText(value).then(() => {
+      setIsCopied(value)
+
+      if (onCopy) {
+        onCopy()
+      }
+
+      setTimeout(() => {
+        setIsCopied(null)
+      }, timeout)
+    }, console.error)
+  }
+
+  return { isCopied, copyToClipboard }
+}

package/components/catalyst-ui/hooks/use-counter.tsx

@@ -0,0 +1,13 @@
+// app/hooks/index.ts
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export function useCounter(initialValue = 0, step = 1) {
+  const [count, setCount] = useState<number>(initialValue);
+
+  const increment = useCallback(() => setCount(c => c + step), [step]);
+  const decrement = useCallback(() => setCount(c => c - step), [step]);
+  const reset = useCallback(() => setCount(initialValue), [initialValue]);
+  const setValue = useCallback((value: number) => setCount(value), []);
+
+  return { count, increment, decrement, reset, setValue } as const;
+}

package/components/catalyst-ui/hooks/use-event-listener.tsx

@@ -0,0 +1,23 @@
+import { useEffect, RefObject } from 'react';
+
+export function useEventListener<K extends keyof HTMLElementEventMap>(
+  eventName: K,
+  handler: (event: HTMLElementEventMap[K]) => void,
+  element?: RefObject<HTMLElement>,
+  options?: boolean | AddEventListenerOptions
+) {
+  useEffect(() => {
+    const targetElement = element?.current || window;
+    
+    if (!targetElement?.addEventListener) return;
+    
+    const eventListener = (event: HTMLElementEventMap[K]) => handler(event);
+    
+    targetElement.addEventListener(eventName, eventListener, options);
+    
+    return () => {
+      targetElement.removeEventListener(eventName, eventListener, options);
+    };
+  }, [eventName, handler, element, options]);
+}
+

package/components/catalyst-ui/hooks/use-export-markdown.tsx

@@ -0,0 +1,47 @@
+import { useCallback } from 'react';
+
+export function useExportMarkdown() {
+  const exportMarkdown = useCallback((content: string, filename: string = 'document.md') => {
+    try {
+      if (!content) {
+        console.warn('No content provided for export');
+        return;
+      }
+
+      const blob = new Blob([content], { type: 'text/markdown' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = filename.endsWith('.md') ? filename : `${filename}.md`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+
+      setTimeout(() => URL.revokeObjectURL(url), 100);
+    } catch (error) {
+      console.error('Failed to export markdown:', error);
+    }
+  }, []);
+
+  return exportMarkdown;
+}
+
+
+/**
+ * import { useExportMarkdown } from './hooks/useExportMarkdown';
+
+function MyComponent() {
+  const exportMarkdown = useExportMarkdown();
+  const [markdown, setMarkdown] = useState('');
+
+  const handleExport = () => {
+    exportMarkdown(markdown, 'custom-filename.md');
+  };
+
+  return (
+    <button onClick={handleExport}>
+      Export as Markdown
+    </button>
+  );
+}
+ */

package/components/catalyst-ui/hooks/use-focus.tsx

@@ -0,0 +1,17 @@
+import { FocusProps, useFocus as useAriaFocus } from 'react-aria';
+import { useRef } from 'react';
+
+export interface UseFocusOptions extends FocusProps {
+  isDisabled?: boolean;
+}
+
+export function useFocus(props: UseFocusOptions = {}) {
+  const ref = useRef<HTMLElement>(null);
+  const { focusProps, isFocused } = useAriaFocus(props, ref);
+  
+  return {
+    focusProps,
+    isFocused,
+    ref
+  };
+}

package/components/catalyst-ui/hooks/use-interval.tsx

@@ -0,0 +1,23 @@
+// app/hooks/index.ts
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export function useInterval(callback: () => void, delay: number | null) {
+  const savedCallback = useRef<() => void>();
+
+  useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    function tick() {
+      if (savedCallback.current) {
+        savedCallback.current();
+      }
+    }
+
+    if (delay !== null) {
+      const id = setInterval(tick, delay);
+      return () => clearInterval(id);
+    }
+  }, [delay]);
+}

package/components/catalyst-ui/hooks/use-is-client.tsx

@@ -0,0 +1,16 @@
+import React, { useEffect, useState } from 'react'
+import { cn } from '~/components/catalyst-ui/utils'
+
+function useIsClient(): boolean {
+  const [isClient, setIsClient] = useState(false)
+
+  useEffect(() => {
+    setIsClient(true)
+  }, [])
+
+  return isClient
+}
+
+
+ 
+export { useIsClient }

package/components/catalyst-ui/hooks/use-media-query.tsx

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+export function useMediaQuery(query: string) {
+  const [value, setValue] = React.useState(false)
+
+  React.useEffect(() => {
+    function onChange(event: MediaQueryListEvent) {
+      setValue(event.matches)
+    }
+
+    const result = matchMedia(query)
+    result.addEventListener("change", onChange)
+    setValue(result.matches)
+
+    return () => result.removeEventListener("change", onChange)
+  }, [query])
+
+  return value
+}

package/components/catalyst-ui/hooks/use-mobile.tsx

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/components/catalyst-ui/hooks/use-resize-observer.tsx

@@ -0,0 +1,81 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { cn } from '~/components/catalyst-ui/utils'
+
+type BoxModel = 'content-box' | 'border-box' | 'device-pixel-content-box'
+
+type Size = {
+  width: number
+  height: number
+}
+
+type UseResizeObserverOptions<T extends HTMLElement> = {
+  ref: React.RefObject<T>
+  onResize?: (size: Size) => void
+  box?: BoxModel
+}
+
+type UseResizeObserverReturn = {
+  width: number | undefined
+  height: number | undefined
+}
+
+function useResizeObserver<T extends HTMLElement = HTMLElement>(
+  options: UseResizeObserverOptions<T>
+): UseResizeObserverReturn {
+  const { ref, onResize, box = 'content-box' } = options
+  const [size, setSize] = useState<Size | undefined>(undefined)
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+
+    if (typeof window === 'undefined' || !window.ResizeObserver) {
+      return
+    }
+
+    const resizeObserver = new ResizeObserver((entries) => {
+      if (!Array.isArray(entries) || !entries.length) {
+        return
+      }
+
+      const entry = entries[0]
+      let width: number
+      let height: number
+
+      if (box === 'border-box') {
+        width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
+        height = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height
+      } else if (box === 'device-pixel-content-box') {
+        width = entry.devicePixelContentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
+        height = entry.devicePixelContentBoxSize?.[0]?.blockSize ?? entry.contentRect.height
+      } else {
+        width = entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
+        height = entry.contentBoxSize?.[0]?.blockSize ?? entry.contentRect.height
+      }
+
+      const newSize = { width, height }
+
+      if (onResize) {
+        onResize(newSize)
+      } else {
+        setSize(newSize)
+      }
+    })
+
+    resizeObserver.observe(element, { box })
+
+    return () => {
+      resizeObserver.disconnect()
+    }
+  }, [ref, box, onResize])
+
+  return {
+    width: size?.width,
+    height: size?.height,
+  }
+}
+
+
+ 
+
+export { useResizeObserver, }