@stacksjs/stx 0.1.16 → 0.2.3

package/dist/client/directive.d.ts

@@ -0,0 +1,10 @@
+import type { CustomDirective } from '../types';
+/**
+ * Handler for @stxRouter directive
+ * Injects the SPA router script into the page
+ */
+export declare function stxRouterHandler(_content: string, params: string[], _context: Record<string, unknown>, _filePath: string): Promise<string>;
+/**
+ * Custom directive for @stxRouter
+ */
+export declare const stxRouterDirective: CustomDirective;

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generate the browser router script as a string
+ * This can be injected into pages or served as a static file
+ */
+export declare function getRouterScript(): string;
+export * from './router';
+export * from './directive';

package/dist/client/router.d.ts

@@ -0,0 +1,36 @@
+export declare function initRouter(options?: RouterOptions): STXRouter;
+export declare function getRouter(): STXRouter | null;
+/**
+ * STX Client-Side Router
+ *
+ * Lightweight SPA router for STX applications.
+ * Intercepts navigation, fetches pages via AJAX, and swaps content.
+ */
+export declare interface RouterOptions {
+  container?: string
+  linkSelector?: string
+  loadingClass?: string
+  viewTransitions?: boolean
+  cache?: boolean
+  scrollToTop?: boolean
+  onBeforeNavigate?: (url: string) => boolean | void
+  onAfterNavigate?: (url: string) => void
+  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>;
+  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 };

package/dist/client-script.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedEvent } from './events';
+/**
+ * Transform a <script client> block's content into a fully processed <script> tag.
+ *
+ * - Auto-imports from 'stx' and '@stacksjs/browser' (no explicit imports needed)
+ * - Resolves `import { x } from '@stores'` to runtime store access
+ * - Appends event binding code inside the script scope
+ * - Wraps everything in a scoped IIFE
+ *
+ * @param scriptContent - The raw content inside <script client>...</script>
+ * @param options - Event bindings and other processing options
+ * @returns A complete `<script>...</script>` tag ready for browser injection
+ */
+export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): string;
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ClientScriptOptions {
+  eventBindings?: ParsedEvent[]
+  autoImports?: boolean
+  attrs?: string
+}

package/dist/component-hmr.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Generate the HMR client script for browser
+ */
+export declare function generateHMRClientScript(wsPort: number): string;
+/**
+ * Generate component wrapper code for HMR support
+ */
+export declare function wrapComponentForHMR(componentId: string, componentName: string, html: string, script: string): string;
+/**
+ * Get or create global HMR handler
+ */
+export declare function getHMRHandler(config?: ComponentHMRConfig): ComponentHMRHandler;
+/**
+ * Reset global HMR handler
+ */
+export declare function resetHMRHandler(): void;
+/**
+ * Component HMR (Hot Module Replacement)
+ *
+ * Provides React Fast Refresh / Vue HMR-style hot reloading for stx components.
+ * Updates component code without losing component state or unmounting.
+ *
+ * ## Features
+ *
+ * - State preservation during component updates
+ * - Selective component re-rendering
+ * - Error recovery with state restoration
+ * - Integration with stx reactivity system
+ * - Support for nested component updates
+ *
+ * ## Usage
+ *
+ * Component HMR is automatically enabled in development mode. No configuration needed.
+ *
+ * @module component-hmr
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ComponentState {
+  refs: Record<string, unknown>
+  reactiveObjects: Record<string, unknown>
+  custom: Record<string, unknown>
+  timestamp: number
+}
+export declare interface ComponentInstance {
+  id: string
+  name: string
+  element: HTMLElement | null
+  state: ComponentState
+  isMounted: boolean
+  props: Record<string, unknown>
+  children: Map<string, ComponentInstance>
+  setup?: () => void | Promise<void>
+  render?: () => string
+  cleanup?: () => void
+}
+export declare interface HMRUpdate {
+  file: string
+  code: string
+  type: 'full' | 'partial' | 'style'
+  timestamp: number
+}
+export declare interface ComponentHMRConfig {
+  preserveState?: boolean
+  maxStateAge?: number
+  errorRecovery?: boolean
+  verbose?: boolean
+  serializeState?: (instance: ComponentInstance) => ComponentState
+  deserializeState?: (state: ComponentState, instance: ComponentInstance) => void
+}
+/**
+ * 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;
+  getInstancesByFile(file: string): ComponentInstance[];
+  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;
+}
+/**
+ * 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>;
+}
+export default {
+  ComponentHMRHandler,
+  getHMRHandler,
+  resetHMRHandler,
+  generateHMRClientScript,
+  wrapComponentForHMR,
+};

package/dist/components.d.ts

@@ -1,4 +1,26 @@
-import type { CustomDirective } from './types';
+import type { ComponentPropsSchema, CustomDirective } from './types';
+/**
+ * Validate component props against a schema
+ *
+ * @param props - The props to validate
+ * @param schema - The props schema
+ * @param componentName - Component name for error messages
+ * @returns Array of validation errors (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const schema: ComponentPropsSchema = {
+ *   title: { type: 'string', required: true },
+ *   count: { type: 'number', default: 0 }
+ * }
+ * const errors = validateComponentProps({ title: 'Hello' }, schema, 'MyComponent')
+ * ```
+ */
+export declare function validateComponentProps(props: Record<string, any>, schema: ComponentPropsSchema, componentName: string): string[];
+/**
+ * Apply default values to props from schema
+ */
+export declare function applyPropDefaults(props: Record<string, any>, schema: ComponentPropsSchema): Record<string, any>;
 /**
  * Register component directives
  */

package/dist/composables/index.d.ts

@@ -0,0 +1,277 @@
+export {
+  useStorage,
+  useLocalStorage,
+  useSessionStorage,
+  clearStorage,
+  getStorageKeys,
+  getStorageSize,
+  type StorageType,
+  type UseStorageOptions,
+  type StorageRef,
+} from './use-storage';
+export {
+  useCookie,
+  useCookies,
+  getCookie,
+  setCookie,
+  removeCookie,
+  parseCookies,
+  clearCookies,
+  type CookieOptions,
+  type CookieRef,
+} from './use-cookie';
+export {
+  useClipboard,
+  copyToClipboard,
+  type ClipboardRef,
+} from './use-clipboard';
+export {
+  useMediaQuery,
+  usePreferredDark,
+  usePreferredLight,
+  usePreferredReducedMotion,
+  usePreferredContrast,
+  useBreakpoint,
+  useIsMobile,
+  useIsTablet,
+  useIsDesktop,
+  breakpoints,
+  type MediaQueryRef,
+} from './use-media-query';
+export {
+  useNetwork,
+  useOnline,
+  type NetworkState,
+  type NetworkRef,
+} from './use-network';
+export {
+  useWindowSize,
+  useScroll,
+  useVisibility,
+  useTitle,
+  useFavicon,
+  type WindowSize,
+  type ScrollPosition,
+  type WindowSizeRef,
+  type ScrollRef,
+  type VisibilityRef,
+} from './use-window';
+export {
+  useGeolocation,
+  useGeolocationWatch,
+  getCurrentPosition,
+  calculateDistance,
+  type GeolocationCoords,
+  type GeolocationState,
+  type GeolocationOptions,
+  type GeolocationRef,
+} from './use-geolocation';
+export {
+  useMouse,
+  useMouseInElement,
+  usePointer,
+  type MouseState,
+  type MouseOptions,
+  type MouseRef,
+  type ElementMouseState,
+  type ElementMouseRef,
+} from './use-mouse';
+export {
+  useKeyboard,
+  useHotkey,
+  useKeyPressed,
+  useKeySequence,
+  shortcuts,
+  type KeyboardState,
+  type KeyboardOptions,
+  type KeyboardRef,
+  type HotkeyOptions,
+} from './use-keyboard';
+export {
+  useIntersectionObserver,
+  useElementVisibility,
+  useLazyLoad,
+  useInfiniteScroll,
+  useIntersectionObserverMultiple,
+  type IntersectionObserverOptions,
+  type IntersectionState,
+  type IntersectionObserverRef,
+} from './use-intersection-observer';
+export {
+  useFetch,
+  useAsyncData,
+  usePost,
+  clearFetchCache,
+  prefetch,
+  type FetchOptions,
+  type FetchState,
+  type FetchRef,
+} from './use-fetch';
+export {
+  useFullscreen,
+  toggleFullscreen,
+  isInFullscreen,
+  type FullscreenState,
+  type FullscreenOptions,
+  type FullscreenRef,
+} from './use-fullscreen';
+export {
+  useNotification,
+  notify,
+  canNotify,
+  requestNotificationPermission,
+  notifications,
+  type NotificationPermission,
+  type NotificationState,
+  type NotificationOptions,
+  type NotificationRef,
+} from './use-notification';
+export {
+  useShare,
+  share,
+  shareURL,
+  shareText,
+  shareFiles,
+  shareCurrentPage,
+  shareWithFallback,
+  createShareableFile,
+  type ShareData,
+  type ShareResult,
+  type ShareRef,
+} from './use-share';
+export {
+  usePermission,
+  usePermissions,
+  isPermissionGranted,
+  hasCameraPermission,
+  hasMicrophonePermission,
+  hasGeolocationPermission,
+  hasNotificationPermission,
+  requestMediaPermissions,
+  permissionGroups,
+  type PermissionName,
+  type PermissionState,
+  type PermissionStatus,
+  type PermissionRef,
+  type MultiPermissionRef,
+} from './use-permissions';
+export {
+  useResizeObserver,
+  useResizeObserverMultiple,
+  useElementSize,
+  hasResizeObserver,
+  type ResizeObserverSize,
+  type ResizeObserverState,
+  type ResizeObserverOptions,
+  type ResizeObserverRef,
+} from './use-resize-observer';
+export {
+  useBattery,
+  getBatteryLevel,
+  isCharging,
+  hasBattery,
+  type BatteryState,
+  type BatteryRef,
+} from './use-battery';
+export {
+  useSpeechRecognition,
+  useSpeechSynthesis,
+  isSpeechRecognitionSupported,
+  isSpeechSynthesisSupported,
+  speak,
+  stopSpeaking,
+  getVoices,
+  type SpeechRecognitionOptions,
+  type SpeechRecognitionState,
+  type SpeechRecognitionResult,
+  type SpeechRecognitionRef,
+  type SpeechSynthesisOptions,
+  type SpeechSynthesisState,
+  type SpeechSynthesisRef,
+} from './use-speech';
+export {
+  useBroadcastChannel,
+  broadcast,
+  isBroadcastChannelSupported,
+  type BroadcastChannelState,
+  type BroadcastChannelOptions,
+  type BroadcastChannelRef,
+} from './use-broadcast-channel';
+export {
+  useWebSocket,
+  isWebSocketSupported,
+  type WebSocketStatus,
+  type WebSocketState,
+  type WebSocketOptions,
+  type WebSocketRef,
+} from './use-websocket';
+export {
+  useDeviceOrientation,
+  useDeviceMotion,
+  useParallax,
+  isDeviceOrientationSupported,
+  isDeviceMotionSupported,
+  requestOrientationPermission,
+  requestMotionPermission,
+  type DeviceOrientationState,
+  type DeviceMotionState,
+  type DeviceOrientationRef,
+  type DeviceMotionRef,
+} from './use-device-orientation';
+export {
+  useMutationObserver,
+  useAttributeObserver,
+  useChildListObserver,
+  useTextObserver,
+  isMutationObserverSupported,
+  type MutationObserverState,
+  type MutationObserverOptions,
+  type MutationObserverRef,
+} from './use-mutation-observer';
+export {
+  useEventSource,
+  useSSE,
+  isEventSourceSupported,
+  type EventSourceStatus,
+  type EventSourceState,
+  type EventSourceOptions,
+  type EventSourceRef,
+} from './use-event-source';
+export {
+  useIdle,
+  useIdleState,
+  useLastActive,
+  useAutoLogout,
+  type IdleState,
+  type IdleOptions,
+  type IdleRef,
+} from './use-idle';
+export {
+  useTextSelection,
+  useElementTextSelection,
+  useSelectionPopup,
+  useCopySelection,
+  type TextSelectionState,
+  type TextSelectionOptions,
+  type TextSelectionRef,
+} from './use-text-selection';
+export {
+  useWakeLock,
+  useAutoWakeLock,
+  useConditionalWakeLock,
+  isWakeLockSupported,
+  type WakeLockState,
+  type WakeLockRef,
+} from './use-wake-lock';
+export {
+  useEyeDropper,
+  useColorHistory,
+  pickColor,
+  hexToRgb,
+  hexToHsl,
+  isEyeDropperSupported,
+  type EyeDropperState,
+  type EyeDropperResult,
+  type EyeDropperOptions,
+  type EyeDropperRef,
+} from './use-eye-dropper';

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

@@ -0,0 +1,46 @@
+/**
+ * Monitor battery status
+ */
+export declare function useBattery(): BatteryRef;
+/**
+ * Get battery level as percentage
+ */
+export declare function getBatteryLevel(): Promise<number | null>;
+/**
+ * Check if device is charging
+ */
+export declare function isCharging(): Promise<boolean | null>;
+/**
+ * Check if Battery API is available
+ */
+export declare function hasBattery(): boolean;
+/**
+ * useBattery - Battery Status API wrapper
+ *
+ * Monitor device battery status reactively.
+ *
+ * @example
+ * ```ts
+ * const battery = useBattery()
+ * battery.subscribe(state => {
+ *   console.log('Battery level:', state.level * 100 + '%')
+ *   console.log('Charging:', state.charging)
+ *   console.log('Time to full:', state.chargingTime)
+ *   console.log('Time to empty:', state.dischargingTime)
+ * })
+ * ```
+ */
+export declare interface BatteryState {
+  charging: boolean
+  chargingTime: number
+  dischargingTime: number
+  level: number
+}
+export declare interface BatteryRef {
+  get: () => BatteryState
+  subscribe: (fn: (state: BatteryState) => void) => () => void
+  isSupported: () => boolean
+  getPercentage: () => number
+  isLow: (threshold?: number) => boolean
+  isCritical: () => boolean
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Check if BroadcastChannel is supported
+ */
+export declare function isBroadcastChannelSupported(): boolean;
+/**
+ * Create a reactive BroadcastChannel for cross-tab communication
+ *
+ * @example
+ * ```ts
+ * const channel = useBroadcastChannel('my-channel')
+ *
+ * // Subscribe to state changes
+ * channel.subscribe((state) => {
+ *   console.log('Last message:', state.lastMessage)
+ * })
+ *
+ * // Post a message to all tabs
+ * channel.post({ type: 'sync', data: { user: 'John' } })
+ *
+ * // Close when done
+ * channel.close()
+ * ```
+ */
+export declare function useBroadcastChannel<T = unknown>(channelName: string, options?: BroadcastChannelOptions): BroadcastChannelRef<T>;
+/**
+ * Simple one-shot broadcast to all tabs
+ *
+ * @example
+ * ```ts
+ * broadcast('app-events', { type: 'logout' })
+ * ```
+ */
+export declare function broadcast<T = unknown>(channelName: string, message: T): void;
+/**
+ * Broadcast Channel Composables
+ *
+ * Reactive utilities for cross-tab/window communication using the BroadcastChannel API.
+ */
+export declare interface BroadcastChannelState<T = unknown> {
+  isSupported: boolean
+  isClosed: boolean
+  channel: BroadcastChannel | null
+  lastMessage: T | null
+  error: Error | null
+}
+export declare interface BroadcastChannelOptions {
+  onMessage?: (event: MessageEvent) => void
+  onError?: (event: MessageEvent) => void
+}
+export declare interface BroadcastChannelRef<T = unknown> {
+  get: () => BroadcastChannelState<T>
+  subscribe: (fn: (state: BroadcastChannelState<T>) => void) => () => void
+  post: (message: T) => void
+  close: () => void
+  isSupported: () => boolean
+}
+declare type BroadcastEventType = 'message' | 'error'
+declare type BroadcastEventCallback = (data: MessageEvent) => void

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

@@ -0,0 +1,34 @@
+/**
+ * Create a clipboard helper
+ *
+ * @example
+ * ```ts
+ * const clipboard = useClipboard()
+ *
+ * // Copy text
+ * await clipboard.copy('Hello World')
+ *
+ * // Check if copy was successful
+ * if (clipboard.copied) {
+ *   console.log('Copied!')
+ * }
+ * ```
+ */
+export declare function useClipboard(options?: { timeout?: number }): ClipboardRef;
+/**
+ * Copy text to clipboard (one-shot helper)
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
+/**
+ * useClipboard - Reactive clipboard composable
+ *
+ * Provides easy access to the Clipboard API with fallbacks.
+ */
+export declare interface ClipboardRef {
+  text: string
+  isSupported: boolean
+  copied: boolean
+  copy: (text: string) => Promise<boolean>
+  read: () => Promise<string>
+  subscribe: (callback: (text: string) => void) => () => void
+}