Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions docs/adr/0013-wsaudioplayer-control-visibility-props.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# 0013 — WSAudioPlayer control-visibility props

**Status:** accepted (interim split done); `controls` object proposed for after
release
**Date:** 2026-09-18
**Context:** written while adding loop + prev/next segment navigation to the
Add Audio Resource configure step (`ProjectResourceConfigure.tsx`), which needed
those controls without the auto-segment tool.

## The situation

`WSAudioPlayer` decides which toolbar/controls buttons to show from props that
follow three different conventions at once:

- **Positive capability flags** — `allowRecord`, `allowSegment`,
`allowAutoSegment`, `allowZoom`, `allowSpeed`, `allowDownload`,
`allowDeltaVoice`, `allowNoNoise`. This is the dominant pattern.
- **Negative override flags** — `hideToolbar`, `hideControls`, `hideZoom`,
`hideSegmentControls`, `hideSegmentReset`, `hideWaveformEditTools`. Read as
double negatives, and several only make sense in combination with an `allow*`
flag.
- **Callback-presence gating** — `onVersions`, `onSaveProgress`, `handleSave`,
`handleUpload`, `onSegmentUndo`. The button renders iff a handler was passed.

The immediate defect that prompted this ADR: **`allowAutoSegment` was
overloaded.** A single prop drove three unrelated things —

1. the loop toggle (`loopNode`),
2. the prev/next segment-navigation arrows (`prevRegionNode` / `nextRegionNode`),
3. the auto-segment barcode button and its parameters dialog (the `wsAutoSegment`
plumbing into `WSAudioPlayerSegment`).

The resource-configure step wants (1) and (2) but not (3). There was no way to
express that with the existing props. A first attempt added a `hideAutoSegment`
override flag, which worked but introduced a _fourth_ convention (a hide-flag
meaningful only together with an allow-flag) — exactly the kind of thing that
makes this component hard to reason about.

## Decision (done now)

Split the overloaded prop into two intention-revealing capability flags,
matching the dominant `allow*` convention:

- **`allowSegmentNav`** — show the loop toggle and prev/next arrows.
- **`allowAutoSegment`** — show _only_ the auto-segment barcode button and its
parameters dialog.

`hideAutoSegment` was removed. `PassageDetailPlayer` threads both flags through
to `WSAudioPlayer`.

### Call-site migration (all 5 consumers)

| Consumer | Before | After |
| ------------------------------------- | ------------------------------------------------- | ---------------------------------------------------- |
| `Transcriber.tsx` | `allowAutoSegment={true}` | `allowSegmentNav={true}` + `allowAutoSegment={true}` |
| `PassageDetailTranscribeMobile.tsx` | `allowAutoSegment={!isReadOnly && hasPermission}` | both, same condition |
| `PassageDetailItem.tsx` | `allowAutoSegment={segments !== undefined}` | both, same condition |
| `PassageDetailGuidedPhraseRecord.tsx` | `allowAutoSegment={false}` | unchanged (neither) |
| `ProjectResourceConfigure.tsx` | (new) | `allowSegmentNav` only |

The three transcriber-style sites keep today's behaviour by opting into both
flags; only the new resource-configure site takes navigation without the tool.

### Left as-is on purpose

The callback-presence gating (`onVersions`, `onSaveProgress`, …) is an
established idiom here and those controls genuinely cannot function without a
handler, so they were not churned. The `hide*` overrides that legitimately mean
"this host supplies its own version of this control" (e.g. `hideSegmentControls`
for Careful Speech) also stay.

## Considered and rejected (for now)

- **One boolean per control** (`allowLoop`, `allowSegmentNav`, `allowSplit`, …).
Maximum control but prop explosion; every call site sets a dozen booleans.
- **Slots / composition** (consumer passes toolbar children). Too large a
refactor for the benefit; overkill for a fixed control set.

## Proposed for after release — a `controls` config object

Once this release is out, consider replacing the scattered `allow*` / `hide*`
visibility flags with a single structured prop:

```ts
controls={{
loop, // loop toggle
segmentNav, // prev/next arrows
autoSegment, // barcode + params
split, // add/remove segment
zoom,
speed,
record,
// …
}}
```

optionally with a `mode` preset (`"transcribe" | "segmentReview" | "record" |
"playback"`) that expands to a default set, with the per-flag object as
overrides.

**Why after release, not now:** it touches every consumer of `WSAudioPlayer` and
`PassageDetailPlayer` and changes a widely-used public surface, so it deserves
its own change and its own regression pass — not a rider on a feature ticket
close to a release.

**The trade-off to weigh then** ("lose per-flag ergonomics unless you keep
escape hatches"): a bare `mode` preset reads cleanly at the call site but forces
every real screen that is _almost_ a preset into a new preset or a special case —
and this component's history is entirely such near-misses (resource-configure is
"transcribe minus the auto tool"; guided-record is "segments but no nav"). So a
preset alone would recreate the overload problem at a coarser grain. Keep the
per-flag object as the escape hatch (`mode` sets defaults, explicit flags win),
so a near-miss is one overridden flag rather than a new preset. Only a mode-plus-
override shape captures the ergonomic win without losing the fine control the
`allow*` flags give today.

Migration is cheap on the same axis this ADR already exercised: the visibility
flags have few consumers (5 for the segment flags), so a codemod or manual pass
per prop is tractable.
9 changes: 8 additions & 1 deletion localization/TranscriberAdmin-en-1.2.xliff
Original file line number Diff line number Diff line change
Expand Up @@ -6984,7 +6984,7 @@
</context-group>
</trans-unit>
<trans-unit id="passageDetailArtifacts.selectPassagesSub">
<source>Select this resource's passages.</source>
<source>Select the {0} and passages contained by this resource.</source>
<target/>
<context-group>
<context context-type="sourcefile">PassageMedia.tsx</context>
Expand Down Expand Up @@ -7116,6 +7116,13 @@
<context context-type="sourcefile">PassageMedia.tsx</context>
</context-group>
</trans-unit>
<trans-unit id="passageDetailArtifacts.uploadAsResources">
<source>Upload as {0} resources</source>
<target/>
<context-group>
<context context-type="sourcefile">ProjectResourceConfigure.tsx</context>
</context-group>
</trans-unit>
<trans-unit id="passageDetailArtifacts.uploadProject">
<source>Multiple {0} or Passages (General Resource)</source>
<target/>
Expand Down
8 changes: 7 additions & 1 deletion localization/TranscriberAdmin-en.xlf
Original file line number Diff line number Diff line change
Expand Up @@ -5988,7 +5988,7 @@
</unit>
<unit id="passageDetailArtifacts.selectPassagesSub">
<segment>
<source>Select this resource's passages.</source>
<source>Select the {0} and passages contained by this resource.</source>
<target/>
</segment>
</unit>
Expand Down Expand Up @@ -6100,6 +6100,12 @@
<target/>
</segment>
</unit>
<unit id="passageDetailArtifacts.uploadAsResources">
<segment>
<source>Upload as {0} resources</source>
<target/>
</segment>
</unit>
<unit id="passageDetailArtifacts.uploadProject">
<segment>
<source>Multiple {0} or Passages (General Resource)</source>
Expand Down
1 change: 0 additions & 1 deletion src/renderer/public/localization/strings157c002b.json

This file was deleted.

1 change: 1 addition & 0 deletions src/renderer/public/localization/stringsf1d2c668.json

Large diffs are not rendered by default.

15 changes: 13 additions & 2 deletions src/renderer/src/components/AlertDialog.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ interface IProps {
yesResponse: () => void;
noOnLeft?: boolean;
isDelete?: boolean;
/** Which action button is styled as primary (emphasized). Defaults to neither. */
primaryButton?: 'yes' | 'no';
}

function AlertDialog(props: IProps) {
Expand All @@ -50,6 +52,7 @@ function AlertDialog(props: IProps) {
noResponse,
noOnLeft,
isDelete,
primaryButton,
} = props;
const t: IAlertStrings = useSelector(alertSelector, shallowEqual);
const [open, setOpen] = useState(true);
Expand Down Expand Up @@ -106,11 +109,19 @@ function AlertDialog(props: IProps) {
</DialogContentText>
</DialogContent>
<StyledDialogActions noOnLeft={noOnLeft}>
<Button id="alertNo" onClick={handleNo}>
<Button
id="alertNo"
color={primaryButton === 'no' ? 'primary' : undefined}
onClick={handleNo}
>
Comment thread
Copilot marked this conversation as resolved.
Resolved
{no || t.no}
</Button>
{yes !== '' && (
<Button id="alertYes" onClick={handleYes}>
<Button
id="alertYes"
color={primaryButton === 'yes' ? 'primary' : undefined}
onClick={handleYes}
>
{yes || t.yes}
</Button>
)}
Expand Down
88 changes: 67 additions & 21 deletions src/renderer/src/components/MediaUpload.tsx
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
import { useEffect, useState } from 'react';
import { shallowEqual, useSelector } from 'react-redux';
import { IMediaUploadStrings } from '../model';
import { mediaUploadSelector } from '../selector';
import { IMediaUploadStrings, IPassageDetailArtifactsStrings } from '../model';
import { mediaUploadSelector, resourceSelector } from '../selector';
import BigDialog from '../hoc/BigDialog';
import { BigDialogBp } from '../hoc/BigDialogBp';
import MediaUploadContent from './MediaUploadContent';
import { useMobile } from '../utils';
import { FaithBridge } from '../assets/brands';
import { UploadType } from './UploadType';
import Confirm from './AlertDialog';

export const UriLinkType = 'text/uri-list';
export const MarkDownType = 'text/markdown';
Expand All @@ -33,6 +35,12 @@ interface IProps {
onValue?: ((value: string) => void) | undefined;
onNonAudio?: ((nonAudio: boolean) => void) | undefined;
audioOnly?: boolean | undefined;
/** Hide the bottom "Cancel" button (cancel is reached via the dialog's X). */
// I think we are moving towards using the dialog's X as the standard way to cancel instead of an explicit Cancel button.
// hopefully in the future we can remove the explicit Cancel button entirely.
hideCancel?: boolean | undefined;
Comment thread
Copilot marked this conversation as resolved.
Resolved
/** When set, always prompt to confirm before discarding on close (X/backdrop). */
confirmOnClose?: boolean | undefined;
}

function MediaUpload(props: IProps) {
Expand All @@ -55,9 +63,22 @@ function MediaUpload(props: IProps) {
onValue,
onNonAudio,
audioOnly,
hideCancel,
confirmOnClose,
} = props;
const { isMobile } = useMobile();
const t: IMediaUploadStrings = useSelector(mediaUploadSelector, shallowEqual);
const rt: IPassageDetailArtifactsStrings = useSelector(
resourceSelector,
shallowEqual
);
const [showConfirm, setShowConfirm] = useState(false);
// The dialog stays mounted across open/close, so a discard prompt left showing
// when `visible` flips off externally would reappear over the next upload.
// Clear it whenever the dialog is hidden.
useEffect(() => {
if (!visible) setShowConfirm(false);
}, [visible]);
const title = [
t.title,
t.resourceTitle,
Expand All @@ -73,12 +94,20 @@ function MediaUpload(props: IProps) {
'', // Burrito
t.pdfResourceTitle,
];
const handleCancel = () => {
const doCancel = () => {
if (cancelMethod) {
cancelMethod();
}
onVisible(false);
};
// The BigDialog X routes here; always confirm before discarding this step.
const handleCancel = () => {
if (confirmOnClose) {
setShowConfirm(true);
return;
}
doCancel();
};

return (
<BigDialog
Expand All @@ -87,24 +116,41 @@ function MediaUpload(props: IProps) {
title={title[uploadType] ?? ''}
bp={isMobile ? BigDialogBp.mobile : (bp ?? BigDialogBp.sm)}
Comment thread
Copilot marked this conversation as resolved.
Resolved
>
<MediaUploadContent
onVisible={onVisible}
uploadType={uploadType}
multiple={multiple}
uploadMethod={uploadMethod}
cancelMethod={cancelMethod}
cancelLabel={cancelLabel}
metaData={metaData}
ready={ready}
speaker={speaker}
onSpeaker={onSpeaker}
team={team}
onFiles={onFiles}
inValue={inValue}
onValue={onValue}
onNonAudio={onNonAudio}
audioOnly={audioOnly}
/>
<>
<MediaUploadContent
onVisible={onVisible}
uploadType={uploadType}
multiple={multiple}
uploadMethod={uploadMethod}
cancelMethod={cancelMethod}
cancelLabel={cancelLabel}
metaData={metaData}
ready={ready}
speaker={speaker}
onSpeaker={onSpeaker}
team={team}
onFiles={onFiles}
inValue={inValue}
onValue={onValue}
onNonAudio={onNonAudio}
audioOnly={audioOnly}
hideCancel={hideCancel}
/>
{showConfirm && (
<Confirm
title={rt.confirmCloseTitle}
text={rt.confirmClose}
no={rt.keepOpen}
primaryButton="no"
yes={rt.discardAndClose}
noResponse={() => setShowConfirm(false)}
yesResponse={() => {
setShowConfirm(false);
doCancel();
}}
/>
)}
</>
</BigDialog>
);
}
Expand Down
21 changes: 13 additions & 8 deletions src/renderer/src/components/MediaUploadContent.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,8 @@ interface IProps {
* but don't have time to check all the usages now. */

noWrapper?: boolean | undefined;
/** Hide the bottom "Cancel" button (cancel is reached via the dialog's X). */
hideCancel?: boolean | undefined;
}

function MediaUploadContent(props: IProps) {
Expand All @@ -201,6 +203,7 @@ function MediaUploadContent(props: IProps) {
controlsRef,
onSaveDisabled,
noWrapper,
hideCancel,
} = props;
const [name, setName] = useState('');
const [files, setFilesx] = useState<File[]>([]);
Expand Down Expand Up @@ -434,14 +437,16 @@ function MediaUploadContent(props: IProps) {
</DialogContent>
{!controlsRef && (
<DialogActions>
<Button
id="uploadCancel"
onClick={handleCancel}
variant="outlined"
color="primary"
>
{cancelLabel || t.cancel}
</Button>
{!hideCancel && (
<Button
id="uploadCancel"
onClick={handleCancel}
variant="outlined"
color="primary"
>
{cancelLabel || t.cancel}
</Button>
)}
<Button
id="uploadSave"
onClick={handleAddOrSave}
Expand Down
Loading
Loading