@sakoa/ui 0.1.0

package/dist/composables/useIntersectionObserver.d.ts

@@ -0,0 +1,156 @@
+import { Ref, MaybeRef, DeepReadonly } from 'vue';
+export interface IntersectionObserverOptions {
+    /** The element that is used as the viewport. Defaults to the browser viewport. */
+    root?: MaybeRef<HTMLElement | null>;
+    /** Margin around the root. Can be values similar to CSS margin. */
+    rootMargin?: string;
+    /** A single number or array of thresholds (0.0 to 1.0) */
+    threshold?: number | number[];
+    /** Whether to start observing immediately */
+    immediate?: boolean;
+    /** Callback when intersection changes */
+    onChange?: (entries: IntersectionObserverEntry[]) => void;
+}
+export interface UseIntersectionObserverReturn {
+    /** Whether the element is currently visible */
+    isVisible: DeepReadonly<Ref<boolean>>;
+    /** The current intersection entry */
+    entry: DeepReadonly<Ref<IntersectionObserverEntry | null>>;
+    /** The intersection ratio (0.0 to 1.0) */
+    ratio: DeepReadonly<Ref<number>>;
+    /** Stop observing */
+    stop: () => void;
+    /** Start observing */
+    start: () => void;
+    /** Whether the observer is currently active */
+    isActive: Ref<boolean>;
+}
+export interface UseIntersectionObserverMultipleReturn {
+    /** Map of element to visibility state */
+    entries: DeepReadonly<Ref<Map<Element, IntersectionObserverEntry>>>;
+    /** Stop observing all elements */
+    stop: () => void;
+    /** Start observing all elements */
+    start: () => void;
+    /** Whether the observer is currently active */
+    isActive: Ref<boolean>;
+    /** Check if a specific element is visible */
+    isElementVisible: (element: Element) => boolean;
+}
+/**
+ * Observe an element's intersection with its parent or the viewport.
+ * Useful for lazy loading, infinite scroll, and scroll animations.
+ *
+ * @example
+ * // Basic usage with template ref
+ * const targetRef = ref<HTMLElement>()
+ * const { isVisible } = useIntersectionObserver(targetRef)
+ *
+ * // In template:
+ * <div ref="targetRef">
+ *   <img v-if="isVisible" :src="imageSrc" />
+ * </div>
+ *
+ * @example
+ * // With threshold
+ * const { isVisible, ratio } = useIntersectionObserver(targetRef, {
+ *   threshold: 0.5 // Trigger when 50% visible
+ * })
+ *
+ * @example
+ * // With root margin for early triggering
+ * const { isVisible } = useIntersectionObserver(targetRef, {
+ *   rootMargin: '100px' // Trigger 100px before entering viewport
+ * })
+ *
+ * @example
+ * // With callback
+ * const { isVisible } = useIntersectionObserver(targetRef, {
+ *   onChange: (entries) => {
+ *     entries.forEach(entry => {
+ *       console.log('Visibility changed:', entry.isIntersecting)
+ *     })
+ *   }
+ * })
+ *
+ * @example
+ * // Manual control
+ * const { isVisible, stop, start } = useIntersectionObserver(targetRef, {
+ *   immediate: false
+ * })
+ *
+ * // Start observing later
+ * onMounted(() => {
+ *   start()
+ * })
+ *
+ * // Stop observing
+ * onBeforeUnmount(() => {
+ *   stop()
+ * })
+ */
+export declare function useIntersectionObserver(target: MaybeRef<HTMLElement | null | undefined>, options?: IntersectionObserverOptions): UseIntersectionObserverReturn;
+/**
+ * Observe multiple elements at once.
+ * More efficient than creating multiple observers.
+ *
+ * @example
+ * const elements = ref<HTMLElement[]>([])
+ * const { entries, isElementVisible } = useIntersectionObserverMultiple(elements)
+ *
+ * // Check specific element
+ * const isFirstVisible = computed(() => {
+ *   return elements.value[0] ? isElementVisible(elements.value[0]) : false
+ * })
+ *
+ * @example
+ * // Lazy load images
+ * const imageRefs = ref<HTMLImageElement[]>([])
+ *
+ * const { entries } = useIntersectionObserverMultiple(imageRefs, {
+ *   rootMargin: '50px',
+ *   onChange: (entries) => {
+ *     entries.forEach(entry => {
+ *       if (entry.isIntersecting) {
+ *         const img = entry.target as HTMLImageElement
+ *         img.src = img.dataset.src || ''
+ *       }
+ *     })
+ *   }
+ * })
+ */
+export declare function useIntersectionObserverMultiple(targets: MaybeRef<(HTMLElement | null | undefined)[]>, options?: IntersectionObserverOptions): UseIntersectionObserverMultipleReturn;
+/**
+ * Simple visibility check - triggers once when element becomes visible.
+ * Useful for one-time animations or analytics tracking.
+ *
+ * @example
+ * const targetRef = ref<HTMLElement>()
+ * const hasBeenSeen = useElementVisibility(targetRef)
+ *
+ * watch(hasBeenSeen, (visible) => {
+ *   if (visible) {
+ *     trackImpression()
+ *   }
+ * })
+ *
+ * @example
+ * // With threshold
+ * const isHalfVisible = useElementVisibility(targetRef, { threshold: 0.5 })
+ */
+export declare function useElementVisibility(target: MaybeRef<HTMLElement | null | undefined>, options?: Pick<IntersectionObserverOptions, 'root' | 'rootMargin' | 'threshold'>): DeepReadonly<Ref<boolean>>;
+/**
+ * Track when an element has been seen at least once.
+ * The value stays true once the element becomes visible.
+ *
+ * @example
+ * const targetRef = ref<HTMLElement>()
+ * const hasBeenSeen = useElementHasBeenSeen(targetRef)
+ *
+ * // Trigger animation once
+ * <div ref="targetRef" :class="{ 'animate-in': hasBeenSeen }">
+ *   Content
+ * </div>
+ */
+export declare function useElementHasBeenSeen(target: MaybeRef<HTMLElement | null | undefined>, options?: Pick<IntersectionObserverOptions, 'root' | 'rootMargin' | 'threshold'>): DeepReadonly<Ref<boolean>>;
+export default useIntersectionObserver;

package/dist/composables/useLocalStorage.d.ts

@@ -0,0 +1,120 @@
+import { Ref } from 'vue';
+export interface Serializer<T> {
+    /** Deserialize value from string */
+    read: (value: string) => T;
+    /** Serialize value to string */
+    write: (value: T) => string;
+}
+export interface StorageOptions<T> {
+    /** Custom serializer for the value */
+    serializer?: Serializer<T>;
+    /** Whether to sync across tabs (localStorage only) */
+    syncTabs?: boolean;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to write the default value if the key doesn't exist */
+    writeDefaults?: boolean;
+    /** Whether to listen for storage changes */
+    listenToStorageChanges?: boolean;
+    /** Merge function for deep objects */
+    mergeDefaults?: boolean | ((storageValue: T, defaults: T) => T);
+}
+export interface UseStorageReturn<T> {
+    /** The reactive storage value */
+    value: Ref<T>;
+    /** Remove the value from storage */
+    remove: () => void;
+    /** Check if the key exists in storage */
+    exists: () => boolean;
+    /** Force refresh the value from storage */
+    refresh: () => void;
+}
+export declare const jsonSerializer: Serializer<any>;
+export declare const stringSerializer: Serializer<string>;
+export declare const numberSerializer: Serializer<number>;
+export declare const booleanSerializer: Serializer<boolean>;
+/**
+ * Reactive localStorage with cross-tab synchronization.
+ *
+ * @example
+ * // Basic usage
+ * const { value: user } = useLocalStorage('user', { name: 'Guest' })
+ *
+ * // Update value
+ * user.value.name = 'John'
+ *
+ * @example
+ * // With custom serializer
+ * const { value } = useLocalStorage('date', new Date(), {
+ *   serializer: {
+ *     read: (v) => new Date(v),
+ *     write: (v) => v.toISOString()
+ *   }
+ * })
+ *
+ * @example
+ * // String value
+ * const { value: token } = useLocalStorage('token', '')
+ *
+ * @example
+ * // With error handling
+ * const { value, remove, exists } = useLocalStorage('settings', {}, {
+ *   onError: (error) => console.error('Storage error:', error)
+ * })
+ *
+ * // Check if exists
+ * if (exists()) {
+ *   console.log('Settings found')
+ * }
+ *
+ * // Remove from storage
+ * remove()
+ */
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: StorageOptions<T>): UseStorageReturn<T>;
+/**
+ * Reactive sessionStorage with the same API as useLocalStorage.
+ * Note: sessionStorage does not sync across tabs.
+ *
+ * @example
+ * // Basic usage
+ * const { value: session } = useSessionStorage('session', { id: null })
+ *
+ * @example
+ * // Form state that persists during the session
+ * const { value: formData } = useSessionStorage('checkout-form', {
+ *   step: 1,
+ *   items: []
+ * })
+ *
+ * @example
+ * // Temporary authentication state
+ * const { value: auth, remove } = useSessionStorage('temp-auth', {
+ *   token: null,
+ *   expires: null
+ * })
+ *
+ * // Clear on logout
+ * function logout() {
+ *   remove()
+ * }
+ */
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<StorageOptions<T>, 'syncTabs'>): UseStorageReturn<T>;
+/**
+ * Create a storage composable for a custom storage implementation.
+ *
+ * @example
+ * // Custom storage implementation
+ * const memoryStorage: Storage = {
+ *   data: new Map(),
+ *   getItem(key) { return this.data.get(key) ?? null },
+ *   setItem(key, value) { this.data.set(key, value) },
+ *   removeItem(key) { this.data.delete(key) },
+ *   clear() { this.data.clear() },
+ *   get length() { return this.data.size },
+ *   key(index) { return Array.from(this.data.keys())[index] ?? null }
+ * }
+ *
+ * const { value } = createStorage('key', 'default', memoryStorage)
+ */
+export declare function createStorage<T>(key: string, defaultValue: T, storage: Storage | null, options?: StorageOptions<T>): UseStorageReturn<T>;
+export default useLocalStorage;

package/dist/composables/useMediaQuery.d.ts

@@ -0,0 +1,115 @@
+import { Ref, DeepReadonly } from 'vue';
+export type MediaQueryInput = string | Record<string, string>;
+export interface UseMediaQueryReturn {
+    /** Whether the media query matches */
+    matches: DeepReadonly<Ref<boolean>>;
+    /** The original query string */
+    query: string;
+}
+export type UseMediaQueryObjectReturn<T extends Record<string, string>> = {
+    [K in keyof T]: DeepReadonly<Ref<boolean>>;
+};
+export declare const breakpoints: {
+    /** Extra small devices (phones, 480px and below) */
+    readonly xs: "(max-width: 480px)";
+    /** Small devices (phones, 640px and below) */
+    readonly sm: "(max-width: 640px)";
+    /** Medium devices (tablets, 768px and below) */
+    readonly md: "(max-width: 768px)";
+    /** Large devices (desktops, 1024px and below) */
+    readonly lg: "(max-width: 1024px)";
+    /** Extra large devices (large desktops, 1280px and below) */
+    readonly xl: "(max-width: 1280px)";
+    /** 2x Extra large devices (1536px and below) */
+    readonly '2xl': "(max-width: 1536px)";
+    /** Mobile and up */
+    readonly 'sm-up': "(min-width: 640px)";
+    /** Tablet and up */
+    readonly 'md-up': "(min-width: 768px)";
+    /** Desktop and up */
+    readonly 'lg-up': "(min-width: 1024px)";
+    /** Large desktop and up */
+    readonly 'xl-up': "(min-width: 1280px)";
+    /** Prefers dark mode */
+    readonly dark: "(prefers-color-scheme: dark)";
+    /** Prefers light mode */
+    readonly light: "(prefers-color-scheme: light)";
+    /** Prefers reduced motion */
+    readonly reducedMotion: "(prefers-reduced-motion: reduce)";
+    /** Portrait orientation */
+    readonly portrait: "(orientation: portrait)";
+    /** Landscape orientation */
+    readonly landscape: "(orientation: landscape)";
+    /** Touch device (primary input is touch) */
+    readonly touch: "(hover: none) and (pointer: coarse)";
+    /** Mouse/pointer device */
+    readonly mouse: "(hover: hover) and (pointer: fine)";
+    /** High resolution display */
+    readonly retina: "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
+};
+export type BreakpointKey = keyof typeof breakpoints;
+/**
+ * Reactive media query composable
+ *
+ * @example
+ * // Single query
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ *
+ * if (isMobile.value) {
+ *   // Mobile layout
+ * }
+ *
+ * @example
+ * // Using predefined breakpoints
+ * import { useMediaQuery, breakpoints } from 'saka-ui'
+ *
+ * const isDark = useMediaQuery(breakpoints.dark)
+ * const isMobile = useMediaQuery(breakpoints.md)
+ *
+ * @example
+ * // Multiple queries
+ * const { isMobile, isTablet, isDesktop } = useMediaQueries({
+ *   isMobile: '(max-width: 767px)',
+ *   isTablet: '(min-width: 768px) and (max-width: 1023px)',
+ *   isDesktop: '(min-width: 1024px)'
+ * })
+ */
+export declare function useMediaQuery(query: string): DeepReadonly<Ref<boolean>>;
+/**
+ * Multiple media queries at once
+ *
+ * @example
+ * const { isMobile, isTablet, isDesktop } = useMediaQueries({
+ *   isMobile: '(max-width: 767px)',
+ *   isTablet: '(min-width: 768px) and (max-width: 1023px)',
+ *   isDesktop: '(min-width: 1024px)'
+ * })
+ */
+export declare function useMediaQueries<T extends Record<string, string>>(queries: T): UseMediaQueryObjectReturn<T>;
+/**
+ * Common responsive breakpoint helpers
+ *
+ * @example
+ * const { isMobile, isTablet, isDesktop } = useBreakpoints()
+ *
+ * // In template
+ * <MobileNav v-if="isMobile" />
+ * <DesktopNav v-else />
+ */
+export declare function useBreakpoints(): UseMediaQueryObjectReturn<{
+    isMobile: string;
+    isTablet: string;
+    isDesktop: string;
+    isTouch: string;
+    isDark: string;
+    prefersReducedMotion: string;
+}>;
+/**
+ * Check a predefined breakpoint
+ *
+ * @example
+ * const isMobile = useBreakpoint('md')
+ * const isDark = useBreakpoint('dark')
+ */
+export declare function useBreakpoint(key: BreakpointKey): DeepReadonly<Ref<boolean>>;
+export default useMediaQuery;

package/dist/composables/useTheme.d.ts

@@ -0,0 +1,8 @@
+export type Theme = 'light' | 'dark' | 'system';
+export declare function applyTheme(t: Theme): void;
+export declare function useTheme(): {
+    theme: import('vue').Ref<Theme, Theme>;
+    toggleTheme: () => void;
+    setTheme: (t: Theme) => void;
+};
+export declare function initTheme(): void;