react-time-machine-js 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# react-time-machine-js
+
+A React component package that provides a ready-to-drop-in dev widget for any React app, powered by [time-machine-js](https://www.npmjs.com/package/time-machine-js).
+
+It provides a minimal UI to control the global `Date.now()` patch, allowing you to simulate different points in time (flowing or frozen) during development.
+
+## Installation
+
+```bash
+npm install react-time-machine-js
+```
+
+> [!NOTE]
+> `react` and `react-dom` (>=17) are peer dependencies and must be provided by the consumer.
+
+## Usage
+
+Render the `<TimeMachine />` component anywhere in your app. It is recommended to wrap it in a development guard.
+
+```tsx
+import { TimeMachine } from 'react-time-machine-js';
+
+function App() {
+  return (
+    <div>
+      {/* ... your app ... */}
+      
+      {process.env.NODE_ENV === 'development' && <TimeMachine />}
+    </div>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Widget corner position. |
+| `storageKey` | `string` | `'__timeMachine__'` | LocalStorage key for persistence. |
+| `onTravel` | `(timestamp: number, mode: 'flowing' | 'frozen') => void` | - | Callback on activation. |
+| `onReturnToPresent` | `() => void` | - | Callback on reset. |
+
+## Behavior
+
+- **Auto-Restore**: On mount, the component automatically restores any saved state from `localStorage`.
+- **Auto-Cleanup**: On unmount, the component calls `returnToPresent()` to restore the native `Date.now()`.
+- **Persistence**: Clicking "Activate" saves the state to `localStorage`. Clicking "Reset" clears the saved state.
+- **Sync**: The widget polls the current simulated time every second to keep the status display in sync.
+
+## Styling
+
+Styles are fully self-contained using inline CSS. No external stylesheets or configuration required. The widget uses a high z-index (`9999`) to stay on top of your application.
+
+## License
+
+MIT

package/dist/TimeMachine.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import './TimeMachine.css';
+export interface TimeMachineProps {
+    /**
+     * Position of the widget on the screen.
+     * @default 'bottom-right'
+     */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * The localStorage key used to persist the time machine state.
+     * @default '__timeMachine__'
+     */
+    storageKey?: string;
+    /**
+     * Callback fired when a new time/mode is activated.
+     */
+    onTravel?: (timestamp: number, mode: 'flowing' | 'frozen') => void;
+    /**
+     * Callback fired when the time machine is reset.
+     */
+    onReturnToPresent?: () => void;
+}
+export declare const TimeMachine: React.FC<TimeMachineProps>;

package/dist/TimeMachine.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { travel, returnToPresent, isActive, save, restore, getMode } from 'time-machine-js';
+import './TimeMachine.css';
+let isRestored = false;
+export const TimeMachine = ({ position = 'bottom-right', storageKey = '__timeMachine__', onTravel, onReturnToPresent, }) => {
+    if (!isRestored) {
+        restore(storageKey);
+        isRestored = true;
+    }
+    const [isExpanded, setIsExpanded] = useState(false);
+    const [active, setActive] = useState(isActive());
+    const [displayTime, setDisplayTime] = useState(Date.now());
+    const [mode, setMode] = useState('flowing');
+    const [inputTime, setInputTime] = useState('');
+    useEffect(() => {
+        const update = () => {
+            setActive(isActive());
+            setDisplayTime(Date.now());
+        };
+        const interval = setInterval(update, 1000);
+        return () => clearInterval(interval);
+    }, []);
+    useEffect(() => {
+        return () => {
+            returnToPresent();
+        };
+    }, []);
+    const handleToggleExpand = () => {
+        if (!isExpanded) {
+            const now = new Date();
+            const pad = (n) => n.toString().padStart(2, '0');
+            const localStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}`;
+            setInputTime(localStr);
+            const currentMode = getMode();
+            if (currentMode) {
+                setMode(currentMode);
+            }
+        }
+        setIsExpanded(!isExpanded);
+    };
+    const handleActivate = () => {
+        const timestamp = new Date(inputTime).getTime();
+        if (isNaN(timestamp))
+            return;
+        travel(timestamp, mode);
+        save(storageKey);
+        setActive(true);
+        if (onTravel)
+            onTravel(timestamp, mode);
+    };
+    const handleReset = () => {
+        returnToPresent();
+        localStorage.removeItem(storageKey);
+        setActive(false);
+        if (onReturnToPresent)
+            onReturnToPresent();
+    };
+    const getStatusText = () => {
+        if (!active)
+            return '● Real time';
+        const dateStr = new Date(displayTime).toLocaleString();
+        return `● ${mode.charAt(0).toUpperCase() + mode.slice(1)}: ${dateStr}`;
+    };
+    return (_jsxs("div", { className: `time-machine-widget position-${position}`, children: [_jsx("div", { className: "time-machine-status-bar", onClick: handleToggleExpand, children: _jsx("span", { className: active ? 'time-machine-status-bar-active' : 'time-machine-status-bar-inactive', children: getStatusText() }) }), _jsxs("div", { className: `time-machine-panel ${!isExpanded ? 'time-machine-panel-hidden' : ''}`, children: [_jsxs("div", { className: "time-machine-input-group", children: [_jsx("label", { children: "Target Date/Time:" }), _jsx("input", { type: "datetime-local", className: "time-machine-input", value: inputTime, onChange: (e) => setInputTime(e.target.value) })] }), _jsxs("div", { className: "time-machine-input-group", children: [_jsx("label", { children: "Mode:" }), _jsxs("div", { className: "time-machine-toggle", children: [_jsx("div", { className: `time-machine-toggle-option ${mode === 'flowing' ? 'time-machine-toggle-option-active' : ''}`, onClick: () => setMode('flowing'), children: "Flowing" }), _jsx("div", { className: `time-machine-toggle-option ${mode === 'frozen' ? 'time-machine-toggle-option-active' : ''}`, onClick: () => setMode('frozen'), children: "Frozen" })] })] }), _jsx("button", { className: "time-machine-button", onClick: handleActivate, children: "Activate" }), active && (_jsx("button", { className: "time-machine-button time-machine-button-reset", onClick: handleReset, children: "Reset to Present" }))] })] }));
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './TimeMachine';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './TimeMachine';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "react-time-machine-js",
+  "version": "1.0.0",
+  "description": "Ready-to-drop-in React dev widget for time-machine-js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "time-machine",
+    "testing",
+    "development",
+    "date-monkey-patch"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WilliamPinto-Olmos/react-time-machine-js.git"
+  },
+  "dependencies": {
+    "time-machine-js": "latest"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/TimeMachine.css

@@ -0,0 +1,105 @@
+.time-machine-widget {
+  position: fixed;
+  z-index: 9999;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 12px;
+  background-color: rgba(0, 0, 0, 0.85);
+  color: #fff;
+  border-radius: 4px;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.5);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid rgba(255,255,255,0.1);
+  transition: all 0.2s ease-in-out;
+  user-select: none;
+}
+
+.time-machine-widget.position-bottom-right { bottom: 20px; right: 20px; }
+.time-machine-widget.position-bottom-left { bottom: 20px; left: 20px; }
+.time-machine-widget.position-top-right { top: 20px; right: 20px; }
+.time-machine-widget.position-top-left { top: 20px; left: 20px; }
+
+.time-machine-status-bar {
+  padding: 8px 12px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  white-space: nowrap;
+  font-weight: 500;
+}
+
+.time-machine-status-bar-active {
+  color: #10b981;
+}
+
+.time-machine-status-bar-inactive {
+  color: #6b7280;
+}
+
+.time-machine-panel {
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  border-top: 1px solid rgba(255,255,255,0.1);
+  width: 240px;
+}
+
+.time-machine-panel-hidden {
+  display: none !important;
+}
+
+.time-machine-input-group {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.time-machine-input {
+  background-color: #333;
+  border: 1px solid #444;
+  color: #fff;
+  padding: 4px 8px;
+  border-radius: 3px;
+  font-size: 12px;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.time-machine-toggle {
+  display: flex;
+  background-color: #222;
+  border-radius: 3px;
+  padding: 2px;
+}
+
+.time-machine-toggle-option {
+  flex: 1;
+  padding: 4px;
+  text-align: center;
+  cursor: pointer;
+  border-radius: 2px;
+  background-color: transparent;
+  transition: background 0.2s;
+}
+
+.time-machine-toggle-option-active {
+  background-color: #444;
+}
+
+.time-machine-button {
+  background-color: #3d82f6;
+  color: #fff;
+  border: none;
+  padding: 6px 12px;
+  border-radius: 3px;
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: bold;
+}
+
+.time-machine-button-reset {
+  background-color: #ef4444;
+}

package/src/TimeMachine.tsx

@@ -0,0 +1,147 @@
+import React, { useState, useEffect } from 'react';
+import { travel, returnToPresent, getOffset, isActive, save, restore, TimeMachineMode, getMode } from 'time-machine-js';
+import './TimeMachine.css';
+
+export interface TimeMachineProps {
+  /**
+   * Position of the widget on the screen.
+   * @default 'bottom-right'
+   */
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  /**
+   * The localStorage key used to persist the time machine state.
+   * @default '__timeMachine__'
+   */
+  storageKey?: string;
+  /**
+   * Callback fired when a new time/mode is activated.
+   */
+  onTravel?: (timestamp: number, mode: 'flowing' | 'frozen') => void;
+  /**
+   * Callback fired when the time machine is reset.
+   */
+  onReturnToPresent?: () => void;
+}
+
+let isRestored = false;
+
+export const TimeMachine: React.FC<TimeMachineProps> = ({
+  position = 'bottom-right',
+  storageKey = '__timeMachine__',
+  onTravel,
+  onReturnToPresent,
+}) => {
+  if (!isRestored) {
+    restore(storageKey);
+    isRestored = true;
+  }
+
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [active, setActive] = useState(isActive());
+  const [displayTime, setDisplayTime] = useState(Date.now());
+  const [mode, setMode] = useState<TimeMachineMode>('flowing');
+  const [inputTime, setInputTime] = useState('');
+
+  useEffect(() => {
+    const update = () => {
+      setActive(isActive());
+      setDisplayTime(Date.now());
+    };
+
+    const interval = setInterval(update, 1000);
+    return () => clearInterval(interval);
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      returnToPresent();
+    };
+  }, []);
+
+  const handleToggleExpand = () => {
+    if (!isExpanded) {
+      const now = new Date();
+      const pad = (n: number) => n.toString().padStart(2, '0');
+      const localStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}`;
+      setInputTime(localStr);
+      const currentMode = getMode();
+      if (currentMode) {
+        setMode(currentMode);
+      }
+    }
+    setIsExpanded(!isExpanded);
+  };
+
+  const handleActivate = () => {
+    const timestamp = new Date(inputTime).getTime();
+    if (isNaN(timestamp)) return;
+
+    travel(timestamp, mode);
+    save(storageKey);
+    setActive(true);
+    if (onTravel) onTravel(timestamp, mode);
+  };
+
+  const handleReset = () => {
+    returnToPresent();
+    localStorage.removeItem(storageKey);
+    setActive(false);
+    if (onReturnToPresent) onReturnToPresent();
+  };
+
+  const getStatusText = () => {
+    if (!active) return '● Real time';
+    const dateStr = new Date(displayTime).toLocaleString();
+    return `● ${mode.charAt(0).toUpperCase() + mode.slice(1)}: ${dateStr}`;
+  };
+
+  return (
+    <div className={`time-machine-widget position-${position}`}>
+      <div className="time-machine-status-bar" onClick={handleToggleExpand}>
+        <span className={active ? 'time-machine-status-bar-active' : 'time-machine-status-bar-inactive'}>
+          {getStatusText()}
+        </span>
+      </div>
+      
+      <div className={`time-machine-panel ${!isExpanded ? 'time-machine-panel-hidden' : ''}`}>
+        <div className="time-machine-input-group">
+          <label>Target Date/Time:</label>
+          <input 
+            type="datetime-local" 
+            className="time-machine-input"
+            value={inputTime} 
+            onChange={(e) => setInputTime(e.target.value)}
+          />
+        </div>
+
+        <div className="time-machine-input-group">
+          <label>Mode:</label>
+          <div className="time-machine-toggle">
+            <div 
+              className={`time-machine-toggle-option ${mode === 'flowing' ? 'time-machine-toggle-option-active' : ''}`}
+              onClick={() => setMode('flowing')}
+            >
+              Flowing
+            </div>
+            <div 
+              className={`time-machine-toggle-option ${mode === 'frozen' ? 'time-machine-toggle-option-active' : ''}`}
+              onClick={() => setMode('frozen')}
+            >
+              Frozen
+            </div>
+          </div>
+        </div>
+
+        <button className="time-machine-button" onClick={handleActivate}>
+          Activate
+        </button>
+
+        {active && (
+          <button className="time-machine-button time-machine-button-reset" onClick={handleReset}>
+            Reset to Present
+          </button>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/index.ts

@@ -0,0 +1 @@
+export * from './TimeMachine';

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "declaration": true,
+    "outDir": "dist",
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}