add skipProgress option to series instrument

[joshunrau]

Summary by CodeRabbit

• New Features

  • Added skipProgress capability for series instruments to enable automatic progression through steps without manual navigation.

• Refactor

  • Updated series instrument content structure to support additional configuration parameters in a more flexible format.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: eb662794-d7e3-4c5b-b99e-38a2c3adfa05

📥 Commits

Reviewing files that changed from the base of the PR and between 74d50d6 and d98605a.

📒 Files selected for processing (8)

• apps/api/src/gateway/gateway.synchronizer.ts
• apps/api/src/instruments/instruments.service.ts
• packages/instrument-library/src/series/DNP_HAPPINESS_QUESTIONNAIRE_WITH_CONSENT/index.ts
• packages/instrument-utils/src/guards.ts
• packages/react-core/src/components/InstrumentRenderer/SeriesInstrumentRenderer.tsx
• packages/react-core/src/hooks/useInterpretedInstrument.ts
• packages/runtime-core/src/types/instrument.series.ts
• packages/schemas/src/instrument/instrument.series.ts

---

Walkthrough

The PR extends SERIES instrument handling with a structured content format supporting an optional skipProgress flag. New type definitions, utility functions, and schema validators normalize content extraction, while the gateway synchronizer, instruments service, and React renderer are updated to use these abstractions. An example instrument definition adopts the new structure.

Changes

SERIES Instrument Skip-Progress Feature

Layer / File(s)	Summary
Type System & Schema Foundation packages/runtime-core/src/types/instrument.series.ts, packages/schemas/src/instrument/instrument.series.ts	SeriesInstrument.Content is now a union: array of scalars or object with items and optional params (containing skipProgress). Schemas updated to match the new structure.
Utility Extraction packages/instrument-utils/src/guards.ts	New public helpers: getSeriesInstrumentItems() and getSeriesInstrumentParams() normalize content into typed items and parameters.
React Hook Generification packages/react-core/src/hooks/useInterpretedInstrument.ts	useInterpretedInstrument becomes generic with type parameter TInstrument, returning InterpretedInstrumentState<TInstrument> for type-safe instrument access downstream.
Gateway & Service Integration apps/api/src/gateway/gateway.synchronizer.ts, apps/api/src/instruments/instruments.service.ts	Gateway and service extract seriesItems and params using the new utilities; length validation, ID generation, and record creation now use extracted items instead of raw content.
React Component Behavior packages/react-core/src/components/InstrumentRenderer/SeriesInstrumentRenderer.tsx	SeriesInstrumentRenderer computes skipProgress from root instrument params and auto-advances initial step when enabled; submit resets progress state only when skipProgress is false.
Example Instrument Update packages/instrument-library/src/series/DNP_HAPPINESS_QUESTIONNAIRE_WITH_CONSENT/index.ts	Instrument content migrated from plain array to object with items array and skipProgress flag in params.

Sequence Diagram

sequenceDiagram
    participant Gateway as Gateway<br/>Synchronizer
    participant Service as Instruments<br/>Service
    participant Utils as Instrument<br/>Utils
    participant Component as Series<br/>Renderer
    
    Gateway->>Utils: getSeriesInstrumentItems(content)
    Utils-->>Gateway: ScalarInstrumentInternal[]
    Gateway->>Gateway: Validate seriesItems.length
    Gateway->>Service: Create/update records with items
    
    Service->>Utils: getSeriesInstrumentItems(content)
    Utils-->>Service: Extract items
    Service->>Service: Generate IDs from items
    Service->>Service: Validate each item exists
    
    Note over Component: Bundle received
    Component->>Utils: getSeriesInstrumentParams(content)
    Utils-->>Component: { skipProgress?: boolean }
    Component->>Component: Compute skipProgress<br/>from root.DONE + params
    
    Note over Component: First step rendering
    alt skipProgress = true
        Component->>Component: Auto-advance to next step
        Component->>Component: Set isInstrumentInProgress=true
    else skipProgress = false
        Component->>Component: Show first step normally
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• DouglasNeuroInformatics/OpenDataCapture#1044: Modifies gateway synchronizer and instruments service with overlapping SERIES instrument extraction and ID generation logic.
• DouglasNeuroInformatics/OpenDataCapture#1283: Updates SeriesInstrument content type definition and related schema/runtime types.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gdevenyi]

Description?