ui-soxo-bootstrap-core 2.6.40-dev.1 → 2.6.40-dev.12

package/core/modules/steps/progress-storage.js

@@ -1,140 +1,140 @@
-/**
- * Per-guest progress persistence helpers for ProcessStepsPage.
- *
- * Storage shape:
- *   key   = `processTimings_<processId>_<guestRef>` or
- *           `processActiveStep_<processId>_<guestRef>`
- *   value = `{ savedAt: <ms>, value: { guestRef, ... } }`
- *
- * The key scopes by guest AND the inner value carries the guest reference,
- * so reads can reject any entry that does not belong to the current guest —
- * guest A's progress can never be applied to guest B even if a key collision
- * somehow occurred.
- *
- * The TTL covers a working shift: a guest who walks away in the morning is
- * not coming back the same evening to resume. The sweep on mount drops any
- * entry past the TTL or stored in the legacy unwrapped shape.
- */
-
-export const PROGRESS_STORAGE_TTL_MS = 12 * 60 * 60 * 1000;
-export const PROGRESS_STORAGE_PREFIXES = ['processTimings_', 'processActiveStep_'];
-
-function hasLocalStorage() {
-  return typeof window !== 'undefined' && !!window.localStorage;
-}
-
-/**
- * Drop progress keys that are past their TTL or stored in the legacy shape
- * (which has no `savedAt` and therefore an unknowable age). Safe to call
- * during mount and again after a quota error to free room for a retry.
- */
-export function sweepStaleProgressKeys() {
-  if (!hasLocalStorage()) {
-    return;
-  }
-
-  try {
-    const cutoff = Date.now() - PROGRESS_STORAGE_TTL_MS;
-    const toRemove = [];
-
-    for (let index = 0; index < window.localStorage.length; index += 1) {
-      const key = window.localStorage.key(index);
-      if (!key) {
-        continue;
-      }
-      if (!PROGRESS_STORAGE_PREFIXES.some((prefix) => key.startsWith(prefix))) {
-        continue;
-      }
-
-      try {
-        const raw = window.localStorage.getItem(key);
-        if (!raw) {
-          continue;
-        }
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number' || parsed.savedAt < cutoff) {
-          toRemove.push(key);
-        }
-      } catch (parseError) {
-        toRemove.push(key);
-      }
-    }
-
-    toRemove.forEach((key) => window.localStorage.removeItem(key));
-  } catch (error) {
-    console.warn('Unable to sweep stale progress keys from local storage.', error);
-  }
-}
-
-/**
- * Read a stored progress entry. Returns the unwrapped inner `value` only
- * when the entry is present, well-formed, and within TTL; otherwise returns
- * `null` and removes the bad key as a side effect.
- *
- * Callers must additionally verify `value.guestRef === currentGuestRef`
- * before applying the result — the helper does not know the current guest.
- */
-export function readProgressEntry(key) {
-  if (!hasLocalStorage()) {
-    return null;
-  }
-
-  try {
-    const raw = window.localStorage.getItem(key);
-    if (!raw) {
-      return null;
-    }
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number') {
-      window.localStorage.removeItem(key);
-      return null;
-    }
-    if (Date.now() - parsed.savedAt > PROGRESS_STORAGE_TTL_MS) {
-      window.localStorage.removeItem(key);
-      return null;
-    }
-    return parsed.value;
-  } catch (error) {
-    return null;
-  }
-}
-
-/**
- * Write a stored progress entry with the current timestamp. On
- * `QuotaExceededError`, sweep stale keys once and retry — that keeps the
- * write path resilient on long-running kiosks without surfacing the error
- * to the user.
- */
-export function writeProgressEntry(key, value) {
-  if (!hasLocalStorage()) {
-    return;
-  }
-
-  const payload = JSON.stringify({ savedAt: Date.now(), value });
-
-  try {
-    window.localStorage.setItem(key, payload);
-  } catch (error) {
-    sweepStaleProgressKeys();
-    try {
-      window.localStorage.setItem(key, payload);
-    } catch (retryError) {
-      console.warn('Unable to persist progress to local storage.', retryError);
-    }
-  }
-}
-
-/**
- * Remove a progress entry. Safe to call when the entry does not exist.
- */
-export function clearProgressEntry(key) {
-  if (!hasLocalStorage()) {
-    return;
-  }
-
-  try {
-    window.localStorage.removeItem(key);
-  } catch (error) {
-    console.warn('Unable to clear progress entry from local storage.', error);
-  }
-}
+/**
+ * Per-guest progress persistence helpers for ProcessStepsPage.
+ *
+ * Storage shape:
+ *   key   = `processTimings_<processId>_<guestRef>` or
+ *           `processActiveStep_<processId>_<guestRef>`
+ *   value = `{ savedAt: <ms>, value: { guestRef, ... } }`
+ *
+ * The key scopes by guest AND the inner value carries the guest reference,
+ * so reads can reject any entry that does not belong to the current guest —
+ * guest A's progress can never be applied to guest B even if a key collision
+ * somehow occurred.
+ *
+ * The TTL covers a working shift: a guest who walks away in the morning is
+ * not coming back the same evening to resume. The sweep on mount drops any
+ * entry past the TTL or stored in the legacy unwrapped shape.
+ */
+
+export const PROGRESS_STORAGE_TTL_MS = 12 * 60 * 60 * 1000;
+export const PROGRESS_STORAGE_PREFIXES = ['processTimings_', 'processActiveStep_'];
+
+function hasLocalStorage() {
+  return typeof window !== 'undefined' && !!window.localStorage;
+}
+
+/**
+ * Drop progress keys that are past their TTL or stored in the legacy shape
+ * (which has no `savedAt` and therefore an unknowable age). Safe to call
+ * during mount and again after a quota error to free room for a retry.
+ */
+export function sweepStaleProgressKeys() {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  try {
+    const cutoff = Date.now() - PROGRESS_STORAGE_TTL_MS;
+    const toRemove = [];
+
+    for (let index = 0; index < window.localStorage.length; index += 1) {
+      const key = window.localStorage.key(index);
+      if (!key) {
+        continue;
+      }
+      if (!PROGRESS_STORAGE_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+        continue;
+      }
+
+      try {
+        const raw = window.localStorage.getItem(key);
+        if (!raw) {
+          continue;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number' || parsed.savedAt < cutoff) {
+          toRemove.push(key);
+        }
+      } catch (parseError) {
+        toRemove.push(key);
+      }
+    }
+
+    toRemove.forEach((key) => window.localStorage.removeItem(key));
+  } catch (error) {
+    console.warn('Unable to sweep stale progress keys from local storage.', error);
+  }
+}
+
+/**
+ * Read a stored progress entry. Returns the unwrapped inner `value` only
+ * when the entry is present, well-formed, and within TTL; otherwise returns
+ * `null` and removes the bad key as a side effect.
+ *
+ * Callers must additionally verify `value.guestRef === currentGuestRef`
+ * before applying the result — the helper does not know the current guest.
+ */
+export function readProgressEntry(key) {
+  if (!hasLocalStorage()) {
+    return null;
+  }
+
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) {
+      return null;
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number') {
+      window.localStorage.removeItem(key);
+      return null;
+    }
+    if (Date.now() - parsed.savedAt > PROGRESS_STORAGE_TTL_MS) {
+      window.localStorage.removeItem(key);
+      return null;
+    }
+    return parsed.value;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Write a stored progress entry with the current timestamp. On
+ * `QuotaExceededError`, sweep stale keys once and retry — that keeps the
+ * write path resilient on long-running kiosks without surfacing the error
+ * to the user.
+ */
+export function writeProgressEntry(key, value) {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  const payload = JSON.stringify({ savedAt: Date.now(), value });
+
+  try {
+    window.localStorage.setItem(key, payload);
+  } catch (error) {
+    sweepStaleProgressKeys();
+    try {
+      window.localStorage.setItem(key, payload);
+    } catch (retryError) {
+      console.warn('Unable to persist progress to local storage.', retryError);
+    }
+  }
+}
+
+/**
+ * Remove a progress entry. Safe to call when the entry does not exist.
+ */
+export function clearProgressEntry(key) {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  try {
+    window.localStorage.removeItem(key);
+  } catch (error) {
+    console.warn('Unable to clear progress entry from local storage.', error);
+  }
+}

package/core/modules/steps/readme.md

@@ -1,167 +1,167 @@
-## ProcessStepsPage
-
-`ProcessStepsPage` is a generic multi-step process runner used to render and track workflow steps.
-
-File: `core/modules/steps/steps.js`
-
-## What It Does
-
-- Loads process steps from `Dashboard.loadProcess(processId)`.
-- Dynamically renders step components using `related_page`.
-- Tracks step and process timings.
-- Supports `Next`, `Back`, `Skip`, `Finish`, and optional next-process start.
-- Supports timeline click navigation.
-- Supports keyboard navigation with `ArrowLeft` (previous) and `ArrowRight` (next).
-- Supports voice-controlled navigation through Gemini Live API command interpretation.
-- Supports step-level text-to-speech narration with optional auto narration.
-- Optionally opens process content in an external window.
-
-## Export
-
-`ProcessStepsPage` is exported from:
-
-```js
-core/modules/index.js
-```
-
-and can be imported as:
-
-```jsx
-import { ProcessStepsPage } from '.../core/modules';
-```
-
-## Props
-
-- `match`: Router match object.
-- `CustomComponents`: Map of custom step components keyed by component name.
-- `showExternalWindow`: Boolean to enable dual render in popup + main window after chaining process.
-- `ExternalWindowWidth`: Popup width.
-- `ExternalWindowHeight`: Popup height.
-- `history`: Router history (used for goBack on completion).
-
-All additional props are forwarded to dynamic step components.
-
-## URL Params Used
-
-`Location.search()` is used to read:
-
-- `processId`: Initial process to load.
-- `opb_id` or `reference_id`: Reference id for process log.
-- `opno` or `reference_number`: Reference number for process log.
-- `mode`: Passed to process log payload.
-
-## Step Contract (Expected Data Shape)
-
-Each step returned by backend is expected to include:
-
-- `step_id`: Unique step id.
-- `step_name`: Step title shown in UI.
-- `step_description`: Step subtitle shown in UI.
-- `related_page`: Component key to resolve from `CustomComponents` + generic components.
-- `config`: Optional props object spread into the dynamic step component.
-- `is_mandatory`: If `true`, step requires `onStepComplete()` before `Next` is enabled.
-- `allow_skip`: `'Y'` enables Skip button.
-- `order_seqtype`: `'E'` marks end-step and shows `Finish`.
-
-## Dynamic Step Rendering
-
-The active step component is resolved by:
-
-- `allComponents[step.related_page]`
-
-and rendered with:
-
-- `step`
-- `params` (parsed URL params)
-- `onStepComplete` callback
-- forwarded parent props
-- `step.config` spread values
-
-If no step exists, an empty state is shown.
-If component resolution fails, an empty state with missing component name is shown.
-
-## Timing Persistence
-
-Timings are stored in localStorage per process:
-
-- key: `processTimings_<processId>`
-
-Each timing entry:
-
-- `step_id`
-- `start_time`
-- `end_time`
-- `duration` (ms)
-- `status` (`completed` or `skipped`)
-
-On successful `Dashboard.processLog(payload)`, timings are cleared.
-On failure, timings are retained in localStorage.
-
-## Voice Control
-
-Voice commands supported:
-
-- `next`
-- `previous` / `back`
-- `skip`
-- `finish`
-- `repeat`
-- `go to step <number>`
-
-Voice flow:
-
-- Browser speech recognition captures spoken command.
-- Transcript is sent to Gemini Live API over WebSocket.
-- Gemini returns normalized navigation action.
-- Step navigation executes in `ProcessStepsPage`.
-
-Step narration:
-
-- Uses AI TTS providers (Gemini / ElevenLabs).
-- Can be triggered with `Read Step`.
-- Auto narration can be toggled on/off.
-
-### Voice Configuration
-
-- `REACT_APP_GEMINI_API_KEY`: Gemini API key (required for Gemini Live).
-- `REACT_APP_GEMINI_LIVE_MODEL`: Live model name (default: `gemini-live-2.5-flash-preview`).
-- `REACT_APP_GEMINI_LIVE_WS_ENDPOINT`: Optional custom Live WebSocket endpoint.
-- `REACT_APP_VOICE_COMMAND_LANG`: Speech recognition language (default: `en-US`).
-- `ELEVEN_LABS_KEY` or `ELEVENLABS_API_KEY`: ElevenLabs API key for narration provider `elevenlabs`.
-- `REACT_APP_ELEVENLABS_API_KEY`: Browser-safe ElevenLabs API key alternative.
-- `ELEVENLABS_VOICE_ID` / `ELEVEN_LABS_VOICE_ID` / `REACT_APP_ELEVENLABS_VOICE_ID`: Optional ElevenLabs voice id.
-- `REACT_APP_STEP_TTS_LANG`: Narration language (default: `en-US`).
-- `REACT_APP_STEP_TTS_RATE`: Narration speed (default: `1`).
-- `REACT_APP_STEP_TTS_PITCH`: Narration pitch (default: `1`).
-- `REACT_APP_OPENAI_REALTIME_TOKEN_ENDPOINT`: Backend endpoint that returns an OpenAI Realtime client secret for WebRTC.
-- `REACT_APP_OPENAI_REALTIME_MODEL`: Realtime model name (default: `gpt-realtime`).
-- `REACT_APP_OPENAI_REALTIME_VOICE`: Realtime voice name (default: `alloy`).
-- `REACT_APP_OPENAI_REALTIME_INSTRUCTIONS`: Optional system instructions for the conversation session.
-- `OPEN_AI_KEY` / `OPENAI_API_KEY`: OpenAI API key used when token endpoint is not configured.
-
-## Minimal Usage Example
-
-```jsx
-import React from 'react';
-import { ProcessStepsPage } from '../../modules';
-import SampleDetail from '../../modules/lab/components/sample-detail/sample-detail';
-import ResultDetail from '../../modules/lab/components/result-detail/result-detail';
-
-const CustomComponents = {
-  SampleDetail,
-  ResultDetail,
-};
-
-export default function ProcessPage(props) {
-  return <ProcessStepsPage {...props} CustomComponents={CustomComponents} showExternalWindow />;
-}
-```
-
-## Related Files
-
-- `core/modules/steps/steps.js`
-- `core/modules/steps/timeline.js`
-- `core/modules/steps/action-buttons.js`
-- `core/modules/steps/voice-navigation.js`
-- `core/modules/steps/openai-realtime.js`
-- `core/modules/steps/steps.scss`
+## ProcessStepsPage
+
+`ProcessStepsPage` is a generic multi-step process runner used to render and track workflow steps.
+
+File: `core/modules/steps/steps.js`
+
+## What It Does
+
+- Loads process steps from `Dashboard.loadProcess(processId)`.
+- Dynamically renders step components using `related_page`.
+- Tracks step and process timings.
+- Supports `Next`, `Back`, `Skip`, `Finish`, and optional next-process start.
+- Supports timeline click navigation.
+- Supports keyboard navigation with `ArrowLeft` (previous) and `ArrowRight` (next).
+- Supports voice-controlled navigation through Gemini Live API command interpretation.
+- Supports step-level text-to-speech narration with optional auto narration.
+- Optionally opens process content in an external window.
+
+## Export
+
+`ProcessStepsPage` is exported from:
+
+```js
+core/modules/index.js
+```
+
+and can be imported as:
+
+```jsx
+import { ProcessStepsPage } from '.../core/modules';
+```
+
+## Props
+
+- `match`: Router match object.
+- `CustomComponents`: Map of custom step components keyed by component name.
+- `showExternalWindow`: Boolean to enable dual render in popup + main window after chaining process.
+- `ExternalWindowWidth`: Popup width.
+- `ExternalWindowHeight`: Popup height.
+- `history`: Router history (used for goBack on completion).
+
+All additional props are forwarded to dynamic step components.
+
+## URL Params Used
+
+`Location.search()` is used to read:
+
+- `processId`: Initial process to load.
+- `opb_id` or `reference_id`: Reference id for process log.
+- `opno` or `reference_number`: Reference number for process log.
+- `mode`: Passed to process log payload.
+
+## Step Contract (Expected Data Shape)
+
+Each step returned by backend is expected to include:
+
+- `step_id`: Unique step id.
+- `step_name`: Step title shown in UI.
+- `step_description`: Step subtitle shown in UI.
+- `related_page`: Component key to resolve from `CustomComponents` + generic components.
+- `config`: Optional props object spread into the dynamic step component.
+- `is_mandatory`: If `true`, step requires `onStepComplete()` before `Next` is enabled.
+- `allow_skip`: `'Y'` enables Skip button.
+- `order_seqtype`: `'E'` marks end-step and shows `Finish`.
+
+## Dynamic Step Rendering
+
+The active step component is resolved by:
+
+- `allComponents[step.related_page]`
+
+and rendered with:
+
+- `step`
+- `params` (parsed URL params)
+- `onStepComplete` callback
+- forwarded parent props
+- `step.config` spread values
+
+If no step exists, an empty state is shown.
+If component resolution fails, an empty state with missing component name is shown.
+
+## Timing Persistence
+
+Timings are stored in localStorage per process:
+
+- key: `processTimings_<processId>`
+
+Each timing entry:
+
+- `step_id`
+- `start_time`
+- `end_time`
+- `duration` (ms)
+- `status` (`completed` or `skipped`)
+
+On successful `Dashboard.processLog(payload)`, timings are cleared.
+On failure, timings are retained in localStorage.
+
+## Voice Control
+
+Voice commands supported:
+
+- `next`
+- `previous` / `back`
+- `skip`
+- `finish`
+- `repeat`
+- `go to step <number>`
+
+Voice flow:
+
+- Browser speech recognition captures spoken command.
+- Transcript is sent to Gemini Live API over WebSocket.
+- Gemini returns normalized navigation action.
+- Step navigation executes in `ProcessStepsPage`.
+
+Step narration:
+
+- Uses AI TTS providers (Gemini / ElevenLabs).
+- Can be triggered with `Read Step`.
+- Auto narration can be toggled on/off.
+
+### Voice Configuration
+
+- `REACT_APP_GEMINI_API_KEY`: Gemini API key (required for Gemini Live).
+- `REACT_APP_GEMINI_LIVE_MODEL`: Live model name (default: `gemini-live-2.5-flash-preview`).
+- `REACT_APP_GEMINI_LIVE_WS_ENDPOINT`: Optional custom Live WebSocket endpoint.
+- `REACT_APP_VOICE_COMMAND_LANG`: Speech recognition language (default: `en-US`).
+- `ELEVEN_LABS_KEY` or `ELEVENLABS_API_KEY`: ElevenLabs API key for narration provider `elevenlabs`.
+- `REACT_APP_ELEVENLABS_API_KEY`: Browser-safe ElevenLabs API key alternative.
+- `ELEVENLABS_VOICE_ID` / `ELEVEN_LABS_VOICE_ID` / `REACT_APP_ELEVENLABS_VOICE_ID`: Optional ElevenLabs voice id.
+- `REACT_APP_STEP_TTS_LANG`: Narration language (default: `en-US`).
+- `REACT_APP_STEP_TTS_RATE`: Narration speed (default: `1`).
+- `REACT_APP_STEP_TTS_PITCH`: Narration pitch (default: `1`).
+- `REACT_APP_OPENAI_REALTIME_TOKEN_ENDPOINT`: Backend endpoint that returns an OpenAI Realtime client secret for WebRTC.
+- `REACT_APP_OPENAI_REALTIME_MODEL`: Realtime model name (default: `gpt-realtime`).
+- `REACT_APP_OPENAI_REALTIME_VOICE`: Realtime voice name (default: `alloy`).
+- `REACT_APP_OPENAI_REALTIME_INSTRUCTIONS`: Optional system instructions for the conversation session.
+- `OPEN_AI_KEY` / `OPENAI_API_KEY`: OpenAI API key used when token endpoint is not configured.
+
+## Minimal Usage Example
+
+```jsx
+import React from 'react';
+import { ProcessStepsPage } from '../../modules';
+import SampleDetail from '../../modules/lab/components/sample-detail/sample-detail';
+import ResultDetail from '../../modules/lab/components/result-detail/result-detail';
+
+const CustomComponents = {
+  SampleDetail,
+  ResultDetail,
+};
+
+export default function ProcessPage(props) {
+  return <ProcessStepsPage {...props} CustomComponents={CustomComponents} showExternalWindow />;
+}
+```
+
+## Related Files
+
+- `core/modules/steps/steps.js`
+- `core/modules/steps/timeline.js`
+- `core/modules/steps/action-buttons.js`
+- `core/modules/steps/voice-navigation.js`
+- `core/modules/steps/openai-realtime.js`
+- `core/modules/steps/steps.scss`