ui-soxo-bootstrap-core 2.6.1-dev.2 → 2.6.1-dev.20

package/core/modules/steps/readme.md

@@ -0,0 +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`