@fluxlay/react 0.1.6

package/LICENSE.txt

@@ -0,0 +1,4 @@
+Copyright (c) Fluxlay. All rights reserved.
+
+This software is provided under the Fluxlay Terms of Service.
+Full terms: https://fluxlay.com/legal/terms

package/README.md

@@ -0,0 +1,113 @@
+# @fluxlay/react
+
+SDK for building [Fluxlay](https://fluxlay.com) wallpapers with React.
+
+## Installation
+
+```sh
+npm install @fluxlay/react
+# or
+pnpm add @fluxlay/react
+```
+
+Also import the stylesheet in your entry file:
+
+```ts
+import "@fluxlay/react/dist/sdk.css";
+```
+
+## API
+
+### `useBackendMouse()`
+
+Subscribes to the global mouse position streamed from the Fluxlay backend. The Y axis is inverted so that positive values point upward (standard mathematical coordinates).
+
+```tsx
+import { useBackendMouse } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { x, y } = useBackendMouse();
+  return <div style={{ transform: `translate(${x}px, ${y}px)` }} />;
+}
+```
+
+### `useShell(commandId, options?)`
+
+Executes a shell command declared in `fluxlay.yaml` and optionally renders its output into a terminal.
+
+```tsx
+import { useShell } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { result, isRunning } = useShell("my-command", {
+    refreshInterval: 5000, // re-run every 5 seconds
+  });
+  return <pre>{result?.stdout}</pre>;
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `refreshInterval` | `number` | `30000` | Auto-refresh interval in ms. `0` to disable. |
+| `showStdout` | `boolean` | `true` | Write stdout to the linked terminal. |
+| `showStderr` | `boolean` | `false` | Write stderr to the linked terminal. |
+| `terminal` | `TerminalInstance` | — | Terminal instance from `useTerminal`. |
+| `columns` | `number` | — | Pseudo-terminal column width. |
+| `lines` | `number` | — | Pseudo-terminal row height. |
+
+Returns `{ execute, isRunning, error, result }`.
+
+### `useTerminal(options?)`
+
+Creates a read-only xterm terminal. Attach `terminalRef` to a `<div>` container.
+
+```tsx
+import { useTerminal, useShell, TerminalThemes } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { terminalRef, instance } = useTerminal({
+    fontSize: 13,
+    theme: TerminalThemes.tokyoNight,
+  });
+  useShell("my-command", { terminal: instance });
+  return <div ref={terminalRef} />;
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fontSize` | `number` | `12` | Font size in pixels. |
+| `fontFamily` | `string` | system monospace | CSS font-family string. |
+| `theme` | `ITheme` | `TerminalThemes.dark.default` | xterm color theme. |
+
+Returns `{ terminalRef, instance }`.
+
+### `runShell(commandId, options?)`
+
+Low-level function to run a shell command imperatively.
+
+```ts
+import { runShell } from "@fluxlay/react";
+
+const result = await runShell("my-command", { columns: 80, lines: 24 });
+console.log(result.stdout);
+```
+
+### `TerminalThemes`
+
+Pre-built xterm color themes to pass to `useTerminal`.
+
+| Key | Variants |
+|-----|----------|
+| `dark` | `default`, `modern` |
+| `light` | `default`, `modern` |
+| `nord` | — |
+| `dracula` | — |
+| `gruvbox` | `dark`, `light` |
+| `solarized` | `dark`, `light` |
+| `oneDark` | — |
+| `catppuccin` | `latte`, `frappe`, `macchiato`, `mocha` |
+| `monokaiPro` | — |
+| `tokyoNight` | — |
+| `nightOwl` | — |
+| `everforest` | `dark`, `light` |

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import { FitAddon } from '@xterm/addon-fit';
+import { ITheme } from '@xterm/xterm';
+import { RefObject } from 'react';
+import { Terminal } from '@xterm/xterm';
+
+/**
+ * Runs a pre-declared shell command from fluxlay.yaml.
+ *
+ * @param commandId The ID of the command declared in the manifest's `shell` section.
+ * @param options Options for command execution.
+ * @returns The standard output and error of the command.
+ * @throws An error if the command fails or the ID is invalid.
+ */
+export declare function runShell(commandId: string, options?: ShellOptions): Promise<ShellResult>;
+
+/** Options that control how a shell command is executed. */
+export declare interface ShellOptions {
+    /** Number of columns (character width) of the pseudo-terminal. */
+    columns?: number;
+    /** Number of rows (line height) of the pseudo-terminal. */
+    lines?: number;
+}
+
+/** The result returned after executing a shell command. */
+export declare interface ShellResult {
+    /** Standard output produced by the command. */
+    stdout: string;
+    /** Standard error produced by the command. */
+    stderr: string;
+    /** Exit status code of the process, or `null` if the process was terminated by a signal. */
+    statusCode: number | null;
+    /** Whether the command exited successfully (status code 0). */
+    success: boolean;
+    /** Signal number that terminated the process, or `null` if it exited normally. */
+    signal: number | null;
+}
+
+/** Holds the xterm {@link Terminal} and its associated {@link FitAddon}. */
+export declare interface TerminalInstance {
+    /** The underlying xterm Terminal instance. */
+    terminal: Terminal;
+    /** The FitAddon used to resize the terminal to match its container element. */
+    fitAddon: FitAddon;
+}
+
+/**
+ * Collection of pre-built xterm color themes.
+ *
+ * Pass any of these values to the `theme` option of {@link useTerminal}.
+ *
+ * @example
+ * ```tsx
+ * const { terminalRef, instance } = useTerminal({
+ *   theme: TerminalThemes.dracula,
+ * });
+ * ```
+ */
+export declare const TerminalThemes: {
+    /** Dark themes with a transparent background. */
+    readonly dark: {
+        /** Default dark theme using Tailwind color palette. */
+        readonly default: ITheme;
+        /** Modern dark theme using Slate/Rose color palette. */
+        readonly modern: ITheme;
+    };
+    /** Light themes. */
+    readonly light: {
+        /** Default light theme. */
+        readonly default: ITheme;
+        /** Modern light theme. */
+        readonly modern: ITheme;
+    };
+    /** Nord theme — an arctic, north-bluish color palette. */
+    readonly nord: ITheme;
+    /** Dracula theme — a dark theme with vivid accent colors. */
+    readonly dracula: ITheme;
+    /** Gruvbox themes — a retro groove color scheme. */
+    readonly gruvbox: {
+        /** Gruvbox dark variant. */
+        readonly dark: ITheme;
+        /** Gruvbox light variant. */
+        readonly light: ITheme;
+    };
+    /** Solarized themes — a precision color scheme with reduced brightness. */
+    readonly solarized: {
+        /** Solarized dark variant. */
+        readonly dark: ITheme;
+        /** Solarized light variant. */
+        readonly light: ITheme;
+    };
+    /** One Dark theme — based on Atom's One Dark syntax theme. */
+    readonly oneDark: ITheme;
+    /** Catppuccin themes — a soothing pastel color scheme. */
+    readonly catppuccin: {
+        /** Catppuccin Latte — the light variant. */
+        readonly latte: ITheme;
+        /** Catppuccin Frappé — a cool medium-dark variant. */
+        readonly frappe: ITheme;
+        /** Catppuccin Macchiato — a warm medium-dark variant. */
+        readonly macchiato: ITheme;
+        /** Catppuccin Mocha — the darkest variant. */
+        readonly mocha: ITheme;
+    };
+    /** Monokai Pro theme — a refined dark theme inspired by Monokai. */
+    readonly monokaiPro: ITheme;
+    /** Tokyo Night theme — a dark theme inspired by Tokyo city lights. */
+    readonly tokyoNight: ITheme;
+    /** Night Owl theme — optimized for late-night coding with low brightness. */
+    readonly nightOwl: ITheme;
+    /** Everforest themes — a green-tinted theme inspired by forests. */
+    readonly everforest: {
+        /** Everforest dark variant. */
+        readonly dark: ITheme;
+        /** Everforest light variant. */
+        readonly light: ITheme;
+    };
+};
+
+/**
+ * React hook that subscribes to global mouse position events streamed from
+ * the Fluxlay backend.
+ *
+ * The Y axis is inverted so that positive values point upward, matching a
+ * standard mathematical coordinate system rather than the screen coordinate
+ * system where Y grows downward.
+ *
+ * The subscription is scoped to the window identified by the `window_label`
+ * query parameter of the current URL, defaulting to `"main"`.
+ *
+ * @returns The current mouse position as `{ x, y }`.
+ */
+export declare function useBackendMouse(): {
+    x: number;
+    y: number;
+};
+
+/**
+ * React hook that executes a pre-declared Fluxlay shell command and
+ * optionally renders its output into an xterm terminal.
+ *
+ * The command runs once on mount and is re-executed whenever `commandId`
+ * changes or the `refreshInterval` elapses.
+ *
+ * @param commandId The ID of the command declared in `fluxlay.yaml`.
+ * @param options Configuration options for execution and display behaviour.
+ * @returns An object containing:
+ *   - `execute` – manually triggers the command.
+ *   - `isRunning` – `true` while the command is in progress.
+ *   - `error` – error message string when the last execution failed, otherwise `null`.
+ *   - `result` – the {@link ShellResult} of the last completed execution, or `null`.
+ */
+export declare function useShell(commandId: string, options?: UseShellOptions): {
+    execute: () => Promise<void>;
+    isRunning: boolean;
+    error: string | null;
+    result: ShellResult | null;
+};
+
+/** Options for the {@link useShell} hook. */
+export declare interface UseShellOptions extends ShellOptions {
+    /**
+     * Interval in milliseconds at which the command is automatically re-executed.
+     * Set to `0` to disable auto-refresh.
+     * @defaultValue 30000
+     */
+    refreshInterval?: number;
+    /**
+     * Whether to write the command's stdout to the linked terminal.
+     * @defaultValue true
+     */
+    showStdout?: boolean;
+    /**
+     * Whether to write the command's stderr to the linked terminal.
+     * @defaultValue false
+     */
+    showStderr?: boolean;
+    /**
+     * Optional terminal instance returned by {@link useTerminal}.
+     * When provided, command output is rendered directly into the terminal and
+     * the terminal dimensions are used as the pseudo-terminal size.
+     */
+    terminal?: TerminalInstance | null;
+}
+
+/**
+ * React hook that creates and manages a read-only xterm terminal rendered
+ * inside a `<div>` element.
+ *
+ * The terminal is configured for display-only use: stdin is disabled, the
+ * cursor is hidden, and the scrollback buffer is removed. Custom CSS overrides
+ * are injected into `document.head` to make the terminal behave as an inline
+ * block that expands to fill its container width.
+ *
+ * The terminal is disposed and the injected styles are removed when the
+ * component unmounts or when `fontSize` / `fontFamily` change.
+ *
+ * @param options Display configuration for the terminal.
+ * @returns An object containing:
+ *   - `terminalRef` – a React ref that must be attached to the container `<div>`.
+ *   - `instance` – the {@link TerminalInstance} once the terminal is mounted, or `null`.
+ */
+export declare function useTerminal(options?: UseTerminalOptions): {
+    terminalRef: RefObject<HTMLDivElement | null>;
+    instance: TerminalInstance | null;
+};
+
+/** Options for the {@link useTerminal} hook. */
+export declare interface UseTerminalOptions {
+    /**
+     * Font size in pixels used by the terminal.
+     * @defaultValue 12
+     */
+    fontSize?: number;
+    /**
+     * CSS font-family string applied to the terminal.
+     * Defaults to a system monospace font stack.
+     */
+    fontFamily?: string;
+    /**
+     * Color theme applied to the terminal.
+     * @defaultValue {@link TerminalThemes.dark.default}
+     */
+    theme?: ITheme;
+}
+
+export { }