@fluxlay/react 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -9,10 +9,16 @@ declare interface AudioInfo {
     rms: number;
     /** Peak volume level (0.0 - 1.0). */
     peak: number;
-    /** Frequency spectrum split into 32 logarithmically-scaled bands (0.0 - 1.0 each). */
+    /** Frequency spectrum split into logarithmically-scaled bands (0.0 - 1.0 each). The number of bands is configurable via `useAudio({ numBands })`. */
     spectrum: number[];
 }
 
+/** Options for the audio stream. */
+export declare interface AudioOptions {
+    /** Number of frequency spectrum bands. Default is 32. */
+    numBands?: number;
+}
+
 /** Storage information for a single disk/volume. */
 declare interface DiskInfo {
     /** Mount point path (e.g. "/", "/home"). */
@@ -47,6 +53,15 @@ declare interface MediaMetadataInfo {
     isPlaying: boolean;
 }
 
+/** Options for the media metadata stream. */
+export declare interface MediaMetadataOptions {
+    /** Polling interval in milliseconds. Default is 1000. */
+    intervalMs?: number;
+}
+
+/** Custom property values set by the end user via the Fluxlay settings UI. */
+declare type PropertyValues = Record<string, number | string | boolean>;
+
 /**
  * Runs a pre-declared shell command from fluxlay.yaml.
  *
@@ -135,6 +150,26 @@ declare interface SystemMonitorInfo {
     kernelVersion: string;
 }
 
+/** Polling interval options for each system monitor category (in milliseconds). */
+export declare interface SystemMonitorOptions {
+    /** CPU usage polling interval in ms. */
+    cpuIntervalMs?: number;
+    /** Memory usage polling interval in ms. */
+    memoryIntervalMs?: number;
+    /** Network throughput polling interval in ms. */
+    networkIntervalMs?: number;
+    /** Disk I/O polling interval in ms. */
+    diskIoIntervalMs?: number;
+    /** Disk space polling interval in ms. */
+    diskSpaceIntervalMs?: number;
+    /** Battery status polling interval in ms. */
+    batteryIntervalMs?: number;
+    /** Process count polling interval in ms. */
+    processIntervalMs?: number;
+    /** Load average polling interval in ms. */
+    loadAverageIntervalMs?: number;
+}
+
 /** Holds the xterm {@link Terminal} and its associated {@link FitAddon}. */
 export declare interface TerminalInstance {
     /** The underlying xterm Terminal instance. */
@@ -223,9 +258,10 @@ export declare const TerminalThemes: {
  * Returns the current audio state including RMS volume, peak level,
  * and frequency spectrum data, useful for building audio visualizers.
  *
+ * @param options - Optional audio configuration.
  * @returns The current audio info as `{ rms, peak, spectrum }`.
  */
-export declare function useAudio(): AudioInfo;
+export declare function useAudio(options?: AudioOptions): AudioInfo;
 
 /**
  * React hook that subscribes to media metadata streamed from the
@@ -236,9 +272,10 @@ export declare function useAudio(): AudioInfo;
  * album artwork, and playback state — useful for building
  * music-reactive wallpapers.
  *
+ * @param options - Optional media metadata configuration.
  * @returns The current media metadata info.
  */
-export declare function useMediaMetadata(): MediaMetadataInfo;
+export declare function useMediaMetadata(options?: MediaMetadataOptions): MediaMetadataInfo;
 
 /**
  * React hook that subscribes to global mouse position events streamed from
@@ -258,6 +295,18 @@ export declare function useMousePosition(): {
     y: number;
 };
 
+/**
+ * React hook that provides the current custom property values defined
+ * in the wallpaper manifest and customized by the end user.
+ *
+ * Fetches initial values on mount and subscribes to real-time updates
+ * via the properties stream.
+ *
+ * @typeParam T - Shape of the property values object.
+ * @returns The current property values typed as `T`.
+ */
+export declare function useProperties<T extends PropertyValues = PropertyValues>(): T;
+
 /**
  * React hook that executes a pre-declared Fluxlay shell command and
  * optionally renders its output into an xterm terminal.
@@ -314,9 +363,10 @@ export declare interface UseShellOptions extends ShellOptions {
  * battery status, and network throughput — useful for building
  * system-reactive wallpapers (e.g. cyberpunk HUDs, hardware monitors).
  *
+ * @param options - Optional polling interval configuration for each category.
  * @returns The current system monitor info.
  */
-export declare function useSystemMonitor(): SystemMonitorInfo;
+export declare function useSystemMonitor(options?: SystemMonitorOptions): SystemMonitorInfo;
 
 /**
  * React hook that creates and manages a read-only xterm terminal rendered