sibujs 1.0.0-beta.1

package/dist/browser.d.cts

@@ -0,0 +1,174 @@
+/**
+ * media returns a reactive boolean that tracks whether a CSS media query matches.
+ * Uses `window.matchMedia` and listens to `change` events for live updates.
+ *
+ * @param query CSS media query string (e.g. "(max-width: 768px)")
+ * @returns Object with reactive matches getter and dispose function for cleanup
+ */
+declare function media(query: string): {
+    matches: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * resize tracks the dimensions of a target element reactively.
+ * Uses the ResizeObserver API to monitor size changes.
+ *
+ * @param target Reactive getter returning the HTMLElement to observe (or null)
+ * @returns Object with reactive width/height getters and a dispose function
+ */
+declare function resize(target: () => HTMLElement | null): {
+    width: () => number;
+    height: () => number;
+    dispose: () => void;
+};
+
+/**
+ * scroll tracks the scroll position of a target element or the window.
+ * Returns reactive x/y scroll positions and an isScrolling indicator
+ * that resets after 150ms of inactivity.
+ *
+ * @param target Optional reactive getter for the scroll target element.
+ *               If omitted or returns null, tracks window scroll.
+ * @returns Object with reactive x, y, isScrolling getters and a dispose function
+ */
+declare function scroll(target?: () => HTMLElement | null): {
+    x: () => number;
+    y: () => number;
+    isScrolling: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * online returns a reactive boolean tracking the browser's online/offline status.
+ * Wraps `navigator.onLine` with online/offline event listeners.
+ *
+ * @returns Object with reactive online getter and dispose function for cleanup
+ */
+declare function online(): {
+    online: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * geo provides reactive access to the device's geographic position.
+ * Uses `navigator.geolocation.watchPosition` for continuous updates.
+ *
+ * @param options Optional PositionOptions for the geolocation API
+ * @returns Object with reactive latitude, longitude, accuracy, error getters and dispose
+ */
+declare function geo(options?: PositionOptions): {
+    latitude: () => number | null;
+    longitude: () => number | null;
+    accuracy: () => number | null;
+    error: () => GeolocationPositionError | null;
+    dispose: () => void;
+};
+
+/**
+ * battery provides reactive access to the Battery Status API.
+ * Returns reactive getters for battery level, charging status, and timing.
+ *
+ * @returns Object with reactive battery state getters, supported flag, and dispose
+ */
+declare function battery(): {
+    level: () => number | null;
+    charging: () => boolean | null;
+    chargingTime: () => number | null;
+    dischargingTime: () => number | null;
+    supported: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * idle tracks user idle state based on mouse, keyboard, and touch activity.
+ * Returns a reactive boolean that is true when the user has been idle
+ * for the specified timeout duration.
+ *
+ * @param timeout Idle timeout in milliseconds (default: 60000)
+ * @returns Object with reactive idle getter and dispose function for cleanup
+ */
+declare function idle(timeout?: number): {
+    idle: () => boolean;
+    dispose: () => void;
+};
+
+type PermissionState = "granted" | "denied" | "prompt" | "unsupported";
+/**
+ * permissions queries and reactively tracks a browser permission status.
+ * Uses `navigator.permissions.query` and listens for state changes.
+ *
+ * @param name The permission name to query (e.g. "camera", "microphone", "geolocation")
+ * @returns Object with reactive state getter and dispose function
+ */
+declare function permissions(name: string): {
+    state: () => PermissionState;
+    dispose: () => void;
+};
+
+/**
+ * clipboard provides reactive access to the async Clipboard API.
+ * Tracks the last copied text and provides a `copied` indicator
+ * that resets after 2 seconds.
+ *
+ * @returns Object with reactive text getter, copy function, copied indicator, and dispose
+ */
+declare function clipboard(): {
+    text: () => string;
+    copy: (text: string) => Promise<void>;
+    copied: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * draggable makes an element draggable and tracks its dragging state.
+ * Sets the `draggable` attribute and attaches dragstart/dragend listeners.
+ * Serializes the provided data as JSON into the dataTransfer.
+ *
+ * @param element Reactive getter returning the HTMLElement to make draggable (or null)
+ * @param data Optional data payload to transfer on drag
+ * @returns Object with reactive isDragging getter and dispose function
+ */
+declare function draggable(element: () => HTMLElement | null, data?: unknown): {
+    isDragging: () => boolean;
+    dispose: () => void;
+};
+/**
+ * dropZone turns an element into a drop zone and tracks drag-over state.
+ * Listens for dragenter, dragleave, dragover, and drop events.
+ * Calls options.onDrop with the parsed data payload and the DragEvent.
+ *
+ * @param element Reactive getter returning the HTMLElement to use as drop zone (or null)
+ * @param options Object with onDrop callback receiving the transferred data and event
+ * @returns Object with reactive isOver getter and dispose function
+ */
+declare function dropZone(element: () => HTMLElement | null, options: {
+    onDrop: (data: unknown, event: DragEvent) => void;
+}): {
+    isOver: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * title sets `document.title` reactively. Accepts a static string
+ * or a reactive getter function. Returns a dispose function that
+ * restores the previous document title.
+ *
+ * @param title Static string or reactive getter for the document title
+ * @returns Dispose function that restores the original title
+ */
+declare function title(value: string | (() => string)): () => void;
+
+/**
+ * colorScheme returns a reactive getter tracking the user's
+ * preferred color scheme (light or dark).
+ * Uses `matchMedia("(prefers-color-scheme: dark)")` and listens for changes.
+ *
+ * @returns Object with reactive scheme getter and dispose function for cleanup
+ */
+declare function colorScheme(): {
+    scheme: () => "light" | "dark";
+    dispose: () => void;
+};
+
+export { battery, clipboard, colorScheme, draggable, dropZone, geo, idle, media, online, permissions, resize, scroll, title };

package/dist/browser.d.ts

@@ -0,0 +1,174 @@
+/**
+ * media returns a reactive boolean that tracks whether a CSS media query matches.
+ * Uses `window.matchMedia` and listens to `change` events for live updates.
+ *
+ * @param query CSS media query string (e.g. "(max-width: 768px)")
+ * @returns Object with reactive matches getter and dispose function for cleanup
+ */
+declare function media(query: string): {
+    matches: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * resize tracks the dimensions of a target element reactively.
+ * Uses the ResizeObserver API to monitor size changes.
+ *
+ * @param target Reactive getter returning the HTMLElement to observe (or null)
+ * @returns Object with reactive width/height getters and a dispose function
+ */
+declare function resize(target: () => HTMLElement | null): {
+    width: () => number;
+    height: () => number;
+    dispose: () => void;
+};
+
+/**
+ * scroll tracks the scroll position of a target element or the window.
+ * Returns reactive x/y scroll positions and an isScrolling indicator
+ * that resets after 150ms of inactivity.
+ *
+ * @param target Optional reactive getter for the scroll target element.
+ *               If omitted or returns null, tracks window scroll.
+ * @returns Object with reactive x, y, isScrolling getters and a dispose function
+ */
+declare function scroll(target?: () => HTMLElement | null): {
+    x: () => number;
+    y: () => number;
+    isScrolling: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * online returns a reactive boolean tracking the browser's online/offline status.
+ * Wraps `navigator.onLine` with online/offline event listeners.
+ *
+ * @returns Object with reactive online getter and dispose function for cleanup
+ */
+declare function online(): {
+    online: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * geo provides reactive access to the device's geographic position.
+ * Uses `navigator.geolocation.watchPosition` for continuous updates.
+ *
+ * @param options Optional PositionOptions for the geolocation API
+ * @returns Object with reactive latitude, longitude, accuracy, error getters and dispose
+ */
+declare function geo(options?: PositionOptions): {
+    latitude: () => number | null;
+    longitude: () => number | null;
+    accuracy: () => number | null;
+    error: () => GeolocationPositionError | null;
+    dispose: () => void;
+};
+
+/**
+ * battery provides reactive access to the Battery Status API.
+ * Returns reactive getters for battery level, charging status, and timing.
+ *
+ * @returns Object with reactive battery state getters, supported flag, and dispose
+ */
+declare function battery(): {
+    level: () => number | null;
+    charging: () => boolean | null;
+    chargingTime: () => number | null;
+    dischargingTime: () => number | null;
+    supported: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * idle tracks user idle state based on mouse, keyboard, and touch activity.
+ * Returns a reactive boolean that is true when the user has been idle
+ * for the specified timeout duration.
+ *
+ * @param timeout Idle timeout in milliseconds (default: 60000)
+ * @returns Object with reactive idle getter and dispose function for cleanup
+ */
+declare function idle(timeout?: number): {
+    idle: () => boolean;
+    dispose: () => void;
+};
+
+type PermissionState = "granted" | "denied" | "prompt" | "unsupported";
+/**
+ * permissions queries and reactively tracks a browser permission status.
+ * Uses `navigator.permissions.query` and listens for state changes.
+ *
+ * @param name The permission name to query (e.g. "camera", "microphone", "geolocation")
+ * @returns Object with reactive state getter and dispose function
+ */
+declare function permissions(name: string): {
+    state: () => PermissionState;
+    dispose: () => void;
+};
+
+/**
+ * clipboard provides reactive access to the async Clipboard API.
+ * Tracks the last copied text and provides a `copied` indicator
+ * that resets after 2 seconds.
+ *
+ * @returns Object with reactive text getter, copy function, copied indicator, and dispose
+ */
+declare function clipboard(): {
+    text: () => string;
+    copy: (text: string) => Promise<void>;
+    copied: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * draggable makes an element draggable and tracks its dragging state.
+ * Sets the `draggable` attribute and attaches dragstart/dragend listeners.
+ * Serializes the provided data as JSON into the dataTransfer.
+ *
+ * @param element Reactive getter returning the HTMLElement to make draggable (or null)
+ * @param data Optional data payload to transfer on drag
+ * @returns Object with reactive isDragging getter and dispose function
+ */
+declare function draggable(element: () => HTMLElement | null, data?: unknown): {
+    isDragging: () => boolean;
+    dispose: () => void;
+};
+/**
+ * dropZone turns an element into a drop zone and tracks drag-over state.
+ * Listens for dragenter, dragleave, dragover, and drop events.
+ * Calls options.onDrop with the parsed data payload and the DragEvent.
+ *
+ * @param element Reactive getter returning the HTMLElement to use as drop zone (or null)
+ * @param options Object with onDrop callback receiving the transferred data and event
+ * @returns Object with reactive isOver getter and dispose function
+ */
+declare function dropZone(element: () => HTMLElement | null, options: {
+    onDrop: (data: unknown, event: DragEvent) => void;
+}): {
+    isOver: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * title sets `document.title` reactively. Accepts a static string
+ * or a reactive getter function. Returns a dispose function that
+ * restores the previous document title.
+ *
+ * @param title Static string or reactive getter for the document title
+ * @returns Dispose function that restores the original title
+ */
+declare function title(value: string | (() => string)): () => void;
+
+/**
+ * colorScheme returns a reactive getter tracking the user's
+ * preferred color scheme (light or dark).
+ * Uses `matchMedia("(prefers-color-scheme: dark)")` and listens for changes.
+ *
+ * @returns Object with reactive scheme getter and dispose function for cleanup
+ */
+declare function colorScheme(): {
+    scheme: () => "light" | "dark";
+    dispose: () => void;
+};
+
+export { battery, clipboard, colorScheme, draggable, dropZone, geo, idle, media, online, permissions, resize, scroll, title };