@stacksjs/stx 0.2.4 → 0.2.6

package/dist/client/directive.d.ts

@@ -7,4 +7,4 @@ export declare function stxRouterHandler(_content: string, params: string[], _co
 /**
  * Custom directive for @stxRouter
  */
-export declare const stxRouterDirective: CustomDirective;
+export declare const stxRouterDirective: CustomDirective;

package/dist/client/index.d.ts

@@ -3,5 +3,10 @@
  * This can be injected into pages or served as a static file
  */
 export declare function getRouterScript(): string;
+/**
+ * STX Client-Side Modules
+ *
+ * Browser-side functionality for STX applications.
+ */
 export * from './router';
-export * from './directive';
+export * from './directive';

package/dist/client/router.d.ts

@@ -18,19 +18,11 @@ export declare interface RouterOptions {
   onError?: (error: Error, url: string) => void
 }
 declare class STXRouter {
-  private options: Required<RouterOptions>;
-  private cache: Map<string, CacheEntry>;
-  private isNavigating: any;
-  private currentUrl: string;
   constructor(options?: RouterOptions);
   init(): void;
-  navigate(url: string, pushState?: any): Promise<void>;
+  navigate(url: string, pushState?: boolean): Promise<void>;
   prefetch(url: string): Promise<void>;
   clearCache(): void;
-  private handleClick(event: MouseEvent): void;
-  private handlePopState(event: PopStateEvent): void;
-  private fetchPage(url: string): Promise<{ html: string; title: string } | null>;
-  private swapContent(content: { html: string; title: string }): Promise<void>;
-  private cacheCurrentPage(): void;
 }
-export { STXRouter };
+// Export for manual use
+export { STXRouter };

package/dist/client/stx-router.browser.d.ts

@@ -0,0 +1 @@
+

package/dist/client-script.d.ts

@@ -19,4 +19,5 @@ export declare interface ClientScriptOptions {
   eventBindings?: ParsedEvent[]
   autoImports?: boolean
   attrs?: string
-}
+  hasColonDirectives?: boolean
+}

package/dist/client.d.ts

@@ -13,8 +13,8 @@ export declare function preloadIslandHandlers(handlers: IslandHandlers): void;
 /**
  * Island handler registry
  */
-declare type IslandHandlers = Record<string, () => Promise<any>>
+declare type IslandHandlers = Record<string, () => Promise<any>>;
 /**
  * Island hydration function
  */
-declare type IslandHydrationFn = (element: any, props: any) => void | Promise<void>
+declare type IslandHydrationFn = (element: any, props: any) => void | Promise<void>;

package/dist/component-hmr.d.ts

@@ -73,10 +73,6 @@ export declare interface ComponentHMRConfig {
  * Global registry of component instances for HMR
  */
 declare class ComponentRegistry {
-  private instances: Map<string, ComponentInstance>;
-  private componentsByFile: Map<string, Set<string>>;
-  private stateSnapshots: Map<string, ComponentState>;
-  private config: Required<ComponentHMRConfig>;
   constructor(config?: ComponentHMRConfig);
   register(instance: ComponentInstance): void;
   unregister(instanceId: string): void;
@@ -84,8 +80,6 @@ declare class ComponentRegistry {
   getInstance(id: string): ComponentInstance | undefined;
   captureState(instanceId: string): void;
   restoreState(instanceId: string): boolean;
-  private defaultSerializeState(instance: ComponentInstance): ComponentState;
-  private defaultDeserializeState(state: ComponentState, instance: ComponentInstance): void;
   getAllInstances(): ComponentInstance[];
   clear(): void;
 }
@@ -93,28 +87,20 @@ declare class ComponentRegistry {
  * HMR Handler - processes component updates
  */
 export declare class ComponentHMRHandler {
-  private registry: ComponentRegistry;
-  private config: Required<ComponentHMRConfig>;
-  private pendingUpdates: Map<string, HMRUpdate>;
-  private updateQueue: Promise<void>;
   constructor(config?: ComponentHMRConfig);
   register(instance: ComponentInstance): void;
   unregister(instanceId: string): void;
   handleUpdate(update: HMRUpdate): Promise<void>;
-  private processUpdate(update: HMRUpdate): Promise<void>;
-  private updateInstance(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
-  private updateComponent(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
-  private updateStyles(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
-  private parseComponentCode(code: string): { html: string; script: string; style: string };
-  private executeScript(script: string, instance: ComponentInstance): Promise<void>;
-  private reinitializeInteractivity(instance: ComponentInstance): void;
   getRegistry(): ComponentRegistry;
   refresh(componentName: string): Promise<void>;
 }
+// =============================================================================
+// Exports
+// =============================================================================
 export default {
   ComponentHMRHandler,
   getHMRHandler,
   resetHMRHandler,
   generateHMRClientScript,
   wrapComponentForHMR,
-};
+};

package/dist/components.d.ts

@@ -25,4 +25,4 @@ export declare function applyPropDefaults(props: Record<string, any>, schema: Co
  * Register component directives
  */
 export declare function registerComponentDirectives(): CustomDirective[];
-export declare const componentDirective: CustomDirective;
+export declare const componentDirective: CustomDirective;

package/dist/composables/index.d.ts

@@ -1,3 +1,22 @@
+/**
+ * STX Composables
+ *
+ * Nuxt-style reactive utilities for browser APIs.
+ * These composables provide a streamlined, reactive interface to common browser features.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   useStorage,
+ *   useCookie,
+ *   useClipboard,
+ *   useMediaQuery,
+ *   useNetwork,
+ *   useWindowSize,
+ * } from '@stacksjs/stx/composables'
+ * ```
+ */
+// Storage
 export {
   useStorage,
   useLocalStorage,
@@ -9,6 +28,7 @@ export {
   type UseStorageOptions,
   type StorageRef,
 } from './use-storage';
+// Cookies
 export {
   useCookie,
   useCookies,
@@ -20,11 +40,13 @@ export {
   type CookieOptions,
   type CookieRef,
 } from './use-cookie';
+// Clipboard
 export {
   useClipboard,
   copyToClipboard,
   type ClipboardRef,
 } from './use-clipboard';
+// Media Queries
 export {
   useMediaQuery,
   usePreferredDark,
@@ -38,12 +60,14 @@ export {
   breakpoints,
   type MediaQueryRef,
 } from './use-media-query';
+// Network
 export {
   useNetwork,
   useOnline,
   type NetworkState,
   type NetworkRef,
 } from './use-network';
+// Window
 export {
   useWindowSize,
   useScroll,
@@ -56,6 +80,7 @@ export {
   type ScrollRef,
   type VisibilityRef,
 } from './use-window';
+// Geolocation
 export {
   useGeolocation,
   useGeolocationWatch,
@@ -66,6 +91,7 @@ export {
   type GeolocationOptions,
   type GeolocationRef,
 } from './use-geolocation';
+// Mouse & Pointer
 export {
   useMouse,
   useMouseInElement,
@@ -76,6 +102,7 @@ export {
   type ElementMouseState,
   type ElementMouseRef,
 } from './use-mouse';
+// Keyboard
 export {
   useKeyboard,
   useHotkey,
@@ -87,6 +114,7 @@ export {
   type KeyboardRef,
   type HotkeyOptions,
 } from './use-keyboard';
+// Intersection Observer
 export {
   useIntersectionObserver,
   useElementVisibility,
@@ -97,6 +125,7 @@ export {
   type IntersectionState,
   type IntersectionObserverRef,
 } from './use-intersection-observer';
+// Fetch & Async Data
 export {
   useFetch,
   useAsyncData,
@@ -107,6 +136,7 @@ export {
   type FetchState,
   type FetchRef,
 } from './use-fetch';
+// Fullscreen
 export {
   useFullscreen,
   toggleFullscreen,
@@ -115,6 +145,7 @@ export {
   type FullscreenOptions,
   type FullscreenRef,
 } from './use-fullscreen';
+// Notifications
 export {
   useNotification,
   notify,
@@ -126,6 +157,7 @@ export {
   type NotificationOptions,
   type NotificationRef,
 } from './use-notification';
+// Share
 export {
   useShare,
   share,
@@ -139,6 +171,7 @@ export {
   type ShareResult,
   type ShareRef,
 } from './use-share';
+// Permissions
 export {
   usePermission,
   usePermissions,
@@ -155,6 +188,7 @@ export {
   type PermissionRef,
   type MultiPermissionRef,
 } from './use-permissions';
+// Resize Observer
 export {
   useResizeObserver,
   useResizeObserverMultiple,
@@ -165,6 +199,7 @@ export {
   type ResizeObserverOptions,
   type ResizeObserverRef,
 } from './use-resize-observer';
+// Battery
 export {
   useBattery,
   getBatteryLevel,
@@ -173,6 +208,7 @@ export {
   type BatteryState,
   type BatteryRef,
 } from './use-battery';
+// Speech Recognition & Synthesis
 export {
   useSpeechRecognition,
   useSpeechSynthesis,
@@ -189,6 +225,7 @@ export {
   type SpeechSynthesisState,
   type SpeechSynthesisRef,
 } from './use-speech';
+// Broadcast Channel
 export {
   useBroadcastChannel,
   broadcast,
@@ -197,6 +234,7 @@ export {
   type BroadcastChannelOptions,
   type BroadcastChannelRef,
 } from './use-broadcast-channel';
+// WebSocket
 export {
   useWebSocket,
   isWebSocketSupported,
@@ -205,6 +243,7 @@ export {
   type WebSocketOptions,
   type WebSocketRef,
 } from './use-websocket';
+// Device Orientation & Motion
 export {
   useDeviceOrientation,
   useDeviceMotion,
@@ -218,6 +257,7 @@ export {
   type DeviceOrientationRef,
   type DeviceMotionRef,
 } from './use-device-orientation';
+// Mutation Observer
 export {
   useMutationObserver,
   useAttributeObserver,
@@ -228,6 +268,7 @@ export {
   type MutationObserverOptions,
   type MutationObserverRef,
 } from './use-mutation-observer';
+// Event Source (SSE)
 export {
   useEventSource,
   useSSE,
@@ -237,6 +278,7 @@ export {
   type EventSourceOptions,
   type EventSourceRef,
 } from './use-event-source';
+// Idle Detection
 export {
   useIdle,
   useIdleState,
@@ -246,6 +288,7 @@ export {
   type IdleOptions,
   type IdleRef,
 } from './use-idle';
+// Text Selection
 export {
   useTextSelection,
   useElementTextSelection,
@@ -255,6 +298,7 @@ export {
   type TextSelectionOptions,
   type TextSelectionRef,
 } from './use-text-selection';
+// Wake Lock
 export {
   useWakeLock,
   useAutoWakeLock,
@@ -263,6 +307,7 @@ export {
   type WakeLockState,
   type WakeLockRef,
 } from './use-wake-lock';
+// Eye Dropper (Color Picker)
 export {
   useEyeDropper,
   useColorHistory,
@@ -274,4 +319,72 @@ export {
   type EyeDropperResult,
   type EyeDropperOptions,
   type EyeDropperRef,
-} from './use-eye-dropper';
+} from './use-eye-dropper';
+// Router / Navigation
+export {
+  navigate,
+  goBack,
+  goForward,
+  useRoute,
+  useSearchParams,
+  type RouteInfo,
+  type SearchParamsRef,
+} from './use-router';
+// Data Fetching (Query / Mutation)
+export {
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseMutationOptions,
+  type UseMutationResult,
+} from './use-query';
+// Event Listener
+export {
+  useEventListener,
+  type UseEventListenerOptions,
+  type EventListenerRef,
+} from './use-event-listener';
+// Meta Tags
+export {
+  useMeta,
+  type UseMetaOptions,
+  type MetaRef,
+} from './use-meta';
+// Timers
+export {
+  useDebounce,
+  useDebouncedValue,
+  useThrottle,
+  useInterval,
+  useTimeout,
+  type DebouncedFn,
+  type ThrottledFn,
+  type DebouncedValueRef,
+  type IntervalOptions,
+  type IntervalRef,
+  type TimeoutRef,
+} from './use-timer';
+// Utilities
+export {
+  useToggle,
+  useCounter,
+  useClickOutside,
+  useFocus,
+  useAsync,
+  type ToggleRef,
+  type CounterOptions,
+  type CounterRef,
+  type ClickOutsideRef,
+  type FocusRef,
+  type AsyncState,
+  type AsyncRef,
+  type AsyncOptions,
+} from './use-utilities';
+// Color Mode
+export {
+  useColorMode,
+  useDark,
+  type ColorMode,
+  type ColorModeOptions,
+  type ColorModeRef,
+  type DarkRef,
+} from './use-color-mode';

package/dist/composables/use-battery.d.ts

@@ -43,4 +43,4 @@ export declare interface BatteryRef {
   getPercentage: () => number
   isLow: (threshold?: number) => boolean
   isCritical: () => boolean
-}
+}

package/dist/composables/use-broadcast-channel.d.ts

@@ -54,5 +54,5 @@ export declare interface BroadcastChannelRef<T = unknown> {
   close: () => void
   isSupported: () => boolean
 }
-declare type BroadcastEventType = 'message' | 'error'
-declare type BroadcastEventCallback = (data: MessageEvent) => void
+declare type BroadcastEventType = 'message' | 'error';
+declare type BroadcastEventCallback = (data: MessageEvent) => void;

package/dist/composables/use-clipboard.d.ts

@@ -31,4 +31,4 @@ export declare interface ClipboardRef {
   copy: (text: string) => Promise<boolean>
   read: () => Promise<string>
   subscribe: (callback: (text: string) => void) => () => void
-}
+}

package/dist/composables/use-color-mode.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Full-featured color-mode manager.
+ *
+ * @example
+ * ```ts
+ * const { mode, isDark, toggle, set } = useColorMode()
+ * toggle()           // switch light↔dark
+ * set('auto')        // follow system preference
+ * ```
+ */
+export declare function useColorMode(options?: ColorModeOptions): ColorModeRef;
+/**
+ * Convenience wrapper — just isDark, toggle, set.
+ *
+ * @example
+ * ```ts
+ * const { isDark, toggle } = useDark()
+ * toggle()
+ * ```
+ */
+export declare function useDark(options?: ColorModeOptions): DarkRef;
+export declare interface ColorModeOptions {
+  storageKey?: string
+  initialMode?: ColorMode
+  darkClass?: string
+  attribute?: string
+  disableTransitions?: boolean
+}
+export declare interface ColorModeRef {
+  readonly mode: 'light' | 'dark'
+  readonly preference: ColorMode
+  readonly isDark: boolean
+  set: (mode: ColorMode) => void
+  toggle: () => void
+  subscribe: (fn: (mode: 'light' | 'dark', preference: ColorMode) => void) => () => void
+}
+export declare interface DarkRef {
+  readonly isDark: boolean
+  toggle: () => void
+  set: (dark: boolean) => void
+  subscribe: (fn: (isDark: boolean) => void) => () => void
+}
+/**
+ * useColorMode / useDark — Theme management composables
+ *
+ * Detect system preference, persist user choice, toggle dark/light mode,
+ * and sync across tabs — all with auto-cleanup.
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export type ColorMode = 'light' | 'dark' | 'auto';

package/dist/composables/use-cookie.d.ts

@@ -67,4 +67,4 @@ export declare interface CookieRef<T> {
   set: (value: T, options?: CookieOptions) => void
   remove: () => void
   subscribe: (callback: (value: T | null, prev: T | null) => void) => () => void
-}
+}

package/dist/composables/use-device-orientation.d.ts

@@ -106,4 +106,4 @@ export declare interface DeviceMotionRef {
   subscribe: (fn: (state: DeviceMotionState) => void) => () => void
   isSupported: () => boolean
   requestPermission: () => Promise<boolean>
-}
+}

package/dist/composables/use-event-listener.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Attach an event listener with auto-cleanup.
+ *
+ * @example
+ * ```ts
+ * // Listen on window (default)
+ * useEventListener('resize', () => console.log('resized'))
+ *
+ * // Listen on document
+ * useEventListener('click', handler, { target: document })
+ *
+ * // Listen on a specific element by selector
+ * useEventListener('click', handler, { target: '#my-button' })
+ *
+ * // Manual removal
+ * const { remove } = useEventListener('scroll', handler)
+ * remove()
+ * ```
+ */
+export declare function useEventListener(event: string, handler: EventListenerOrEventListenerObject, options?: UseEventListenerOptions): EventListenerRef;
+/**
+ * useEventListener - Event listener composable with auto-cleanup
+ *
+ * Attaches event listeners and automatically removes them on component destroy.
+ * Replaces raw `window.addEventListener` / `document.addEventListener` usage.
+ */
+export declare interface UseEventListenerOptions {
+  target?: EventTarget | string
+  capture?: boolean
+  passive?: boolean
+  once?: boolean
+}
+export declare interface EventListenerRef {
+  remove: () => void
+}

package/dist/composables/use-event-source.d.ts

@@ -74,4 +74,4 @@ export declare interface EventSourceRef<T = unknown> {
  *
  * Reactive utilities for Server-Sent Events.
  */
-export type EventSourceStatus = 'connecting' | 'open' | 'closed' | 'error'
+export type EventSourceStatus = 'connecting' | 'open' | 'closed' | 'error';

package/dist/composables/use-eye-dropper.d.ts

@@ -95,13 +95,14 @@ export declare interface EyeDropperRef {
   open: () => Promise<string | null>
   isSupported: () => boolean
 }
+// Extend Window for EyeDropper
 declare interface EyeDropperConstructor {
   new (): {
     open: (options?: { signal?: AbortSignal }) => Promise<EyeDropperResult>
   }
 }
-declare namespace global {
+declare global {
   interface Window {
   EyeDropper?: EyeDropperConstructor
 }
-}
+}

package/dist/composables/use-fetch.d.ts

@@ -81,4 +81,4 @@ export declare interface FetchRef<T> {
   execute: () => Promise<void>
   abort: () => void
   isLoading: () => boolean
-}
+}

package/dist/composables/use-fullscreen.d.ts

@@ -44,4 +44,4 @@ export declare interface FullscreenRef {
   enter: () => Promise<void>
   exit: () => Promise<void>
   toggle: () => Promise<void>
-}
+}

package/dist/composables/use-geolocation.d.ts

@@ -59,4 +59,4 @@ export declare interface GeolocationRef {
   refresh: () => void
   pause: () => void
   resume: () => void
-}
+}

package/dist/composables/use-idle.d.ts

@@ -32,7 +32,7 @@ export declare function useIdle(options?: IdleOptions): IdleRef;
  * })
  * ```
  */
-export declare function useIdleState(timeout?: any): void;
+export declare function useIdleState(timeout?: number): void;
 /**
  * Track user's last active timestamp
  *
@@ -81,4 +81,4 @@ export declare interface IdleRef {
   subscribe: (fn: (state: IdleState) => void) => () => void
   reset: () => void
   isIdle: () => boolean
-}
+}

package/dist/composables/use-intersection-observer.d.ts

@@ -78,4 +78,4 @@ export declare interface IntersectionObserverRef {
   stop: () => void
   start: () => void
 }
-declare type IntersectionCallback = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void
+declare type IntersectionCallback = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;

package/dist/composables/use-keyboard.d.ts

@@ -35,7 +35,6 @@ export declare const shortcuts: {
   refresh: 'ctrl+r';
   escape: 'escape';
   enter: 'enter';
-  // Mac alternatives
   saveMac: 'meta+s';
   undoMac: 'meta+z';
   redoMac: 'meta+shift+z';
@@ -97,4 +96,4 @@ export declare interface HotkeyOptions {
   keyup?: boolean
   ignoreInputs?: boolean
 }
-declare type HotkeyCallback = (event: KeyboardEvent) => void
+declare type HotkeyCallback = (event: KeyboardEvent) => void;

package/dist/composables/use-media-query.d.ts

@@ -53,4 +53,4 @@ export declare const breakpoints: {
 export declare interface MediaQueryRef {
   matches: boolean
   subscribe: (callback: (matches: boolean) => void) => () => void
-}
+}

package/dist/composables/use-meta.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reactive meta tag management.
+ *
+ * @example
+ * ```ts
+ * const meta = useMeta({
+ *   title: 'My Page',
+ *   description: 'A page description',
+ *   og: { image: 'https://example.com/og.png' }
+ * })
+ *
+ * // Dynamic updates
+ * meta.setTitle('New Title')
+ * meta.setMeta('description', 'Updated description')
+ * meta.setOgMeta('image', 'https://example.com/new.png')
+ * ```
+ */
+export declare function useMeta(options?: UseMetaOptions): MetaRef;
+/**
+ * useMeta - Reactive meta tag management composable
+ *
+ * Provides clean APIs for managing `<meta>` tags without raw `document.querySelector`.
+ */
+export declare interface UseMetaOptions {
+  title?: string
+  description?: string
+  meta?: Record<string, string>
+  og?: Record<string, string>
+}
+export declare interface MetaRef {
+  setMeta: (name: string, content: string) => void
+  setOgMeta: (property: string, content: string) => void
+  removeMeta: (name: string) => void
+  setTitle: (title: string) => void
+}

package/dist/composables/use-mouse.d.ts

@@ -61,4 +61,4 @@ export declare interface ElementMouseRef {
   get: () => ElementMouseState
   subscribe: (fn: (state: ElementMouseState) => void) => () => void
   stop: () => void
-}
+}

package/dist/composables/use-mutation-observer.d.ts

@@ -98,4 +98,4 @@ export declare interface MutationObserverRef {
   disconnect: () => void
   takeRecords: () => MutationRecord[]
   isSupported: () => boolean
-}
+}