@factorialco/f0-react 4.58.0 → 4.60.0

package/dist/f0.d.ts

@@ -123,6 +123,7 @@ import { PieChartProps } from './PieChart';
 import { PopoverContentProps } from '@radix-ui/react-popover';
 import { ProgressBarCellValue } from './f0';
 import { ProgressBarCellValue as ProgressBarCellValue_2 } from './types/progressBar';
+import { ProgressSeriesCellValue } from './types/progressSeries';
 import { Props as Props_2 } from './types';
 import { RadarChartProps } from './RadarChart';
 import * as React_2 from 'react';
@@ -1267,6 +1268,38 @@ export declare type AttachedFile = {
     errorMessage?: string;
 };
 
+/**
+ * Structured detail content for {@link F0AudioPlayerCardProps.content}.
+ *
+ * Pass a `summary` and/or a `transcription` string and the card builds the
+ * tabbed "View detail" panel for you, with labels pulled from translations
+ * (`audioPlayer.summary` / `audioPlayer.transcription`) — you no longer wire up
+ * the tabs yourself as with the deprecated `details` array.
+ *
+ * A transcription is what makes an audio-only recording accessible
+ * (WCAG 2.1 SC 1.2.1, Audio-only). When you omit `transcription`, the card
+ * still tries to derive one from the audio file's own text tracks; if none can
+ * be passed or derived, the recording is flagged in the accessibility checks.
+ *
+ * Both fields are localizable — pass a per-locale list
+ * (`[{ locale, label?, value }]`) to offer several languages, and a language
+ * selector appears in the detail panel (a single selection drives both tabs).
+ */
+export declare interface AudioPlayerContent {
+    /**
+     * Plain-text summary of the recording, shown in the "Summary" tab.
+     * Localizable.
+     */
+    summary?: Localized<string>;
+    /**
+     * Plain-text transcription of the recording, shown in the "Transcription"
+     * tab. Line breaks are preserved. When omitted, the card attempts to derive
+     * a transcription from the audio file's embedded/attached text tracks.
+     * Localizable.
+     */
+    transcription?: Localized<string>;
+}
+
 export declare interface AudioPlayerControls extends AudioPlayerState {
     play: () => void;
     pause: () => void;
@@ -1275,6 +1308,11 @@ export declare interface AudioPlayerControls extends AudioPlayerState {
     setPlaybackRate: (rate: number) => void;
 }
 
+/**
+ * @deprecated Prefer the structured `content` prop
+ * ({@link AudioPlayerContent}). The raw tab array is still honoured for now for
+ * backward compatibility, but will be removed in a future release.
+ */
 export declare interface AudioPlayerDetailTab {
     /** Stable value used to identify the tab. */
     value: string;
@@ -4528,7 +4566,15 @@ export declare const defaultTranslations: {
         readonly position: "{{current}} of {{total}}";
         readonly viewDetail: "View detail";
         readonly hideDetail: "Hide detail";
+        readonly viewTranscription: "View transcription";
+        readonly hideTranscription: "Hide transcription";
+        readonly viewSummary: "View summary";
+        readonly hideSummary: "Hide summary";
         readonly details: "Recording details";
+        readonly summary: "Summary";
+        readonly transcription: "Transcription";
+        readonly language: "Language";
+        readonly audio: "Audio";
     };
     readonly actions: {
         readonly add: "Add";
@@ -5069,6 +5115,10 @@ export declare const defaultTranslations: {
             readonly description: "Try a different date or fewer filters";
         };
     };
+    readonly progressSeries: {
+        readonly noData: "No data";
+        readonly canceled: "Canceled";
+    };
     readonly select: {
         readonly noResults: "No results found";
         readonly loadingMore: "Loading...";
@@ -5341,6 +5391,7 @@ export declare const defaultTranslations: {
         readonly paused: "Paused";
         readonly mute: "Mute";
         readonly unmute: "Unmute";
+        readonly noAudio: "No audio";
         readonly volume: "Volume";
         readonly seekLabel: "Seek";
         readonly enterFullscreen: "Enter fullscreen";
@@ -5348,6 +5399,12 @@ export declare const defaultTranslations: {
         readonly playbackSpeed: "Playback speed ({{rate}})";
         readonly playbackSpeedLabel: "Playback speed";
         readonly timeProgress: "{{current}} of {{total}}";
+        readonly captions: "Captions";
+        readonly audioDescription: "Audio description";
+        readonly audio: "Audio";
+        readonly subtitles: "Subtitles";
+        readonly settings: "Settings";
+        readonly off: "Off";
     };
 };
 
@@ -7108,10 +7165,23 @@ export declare interface F0AudioPlayerCardProps extends F0AudioPlayerProps {
      * is always rendered by the card.
      */
     actions?: AudioPlayerMenuAction[];
+    /**
+     * Structured detail content revealed by a "View detail" toggle in the header:
+     * a `summary` and/or a `transcription`. The card renders the tabs with
+     * translated labels. Providing a `transcription` (or shipping one in the
+     * audio file) keeps the recording accessible. Takes precedence over the
+     * deprecated `details` prop when both are set.
+     */
+    content?: AudioPlayerContent;
     /**
      * Tabbed detail content revealed by a "View detail" toggle in the header
      * (e.g. a Summary and a Transcript tab). When omitted or empty, no toggle and
      * no panel are rendered and the card behaves like a plain recording player.
+     *
+     * @deprecated Use the structured {@link F0AudioPlayerCardProps.content} prop
+     * instead (`{ summary, transcription }`). This raw tab array is still
+     * honoured for backward compatibility but will be removed in a future
+     * release.
      */
     details?: AudioPlayerDetailTab[];
     /**
@@ -7141,8 +7211,19 @@ export declare interface F0AudioPlayerProps extends WithDataTestIdProps, DataAtt
      * the URL the first time playback is requested. Use the function form for
      * on-demand credentials (e.g. presigned URLs) so the URL is only fetched on
      * user intent.
+     *
+     * Localizable — pass a per-locale list of dubbed recordings to offer
+     * selectable audio languages; a language selector then appears (in the card's
+     * kebab menu, or inline on the bare player).
+     */
+    src: Localized<string | (() => Promise<string>)>;
+    /**
+     * Initial language for localized content — the audio `src` and, on the card,
+     * the detail `content` (summary/transcription). Matched against the provided
+     * locales exactly or by primary subtag, then the viewer's browser language,
+     * then the first provided. Only relevant when more than one language is given.
      */
-    src: string | (() => Promise<string>);
+    defaultLanguage?: string;
     /**
      * Known total duration in seconds. Lets the player show the total time and an
      * active seek bar before the audio loads (e.g. with `preload="none"`).
@@ -11968,11 +12049,54 @@ export declare const F0VideoPlayer: WithDataTestIdReturnType_3<typeof F0VideoPla
  *   useRestrictForwardSeek  → blocks seeking past the furthest-watched point.
  *   <Controls>              → presentation only; interactions delegated back here.
  */
-declare function F0VideoPlayerInternal({ src, autoPlay, autoFocus, restrictForwardSeek, onTrackAction, onMilestone, onComplete, ...dataAttributes }: F0VideoPlayerProps): JSX_2.Element;
+declare function F0VideoPlayerInternal({ src, poster, silent, persistControls, content, defaultLanguage, autoPlay, autoFocus, restrictForwardSeek, onTrackAction, onMilestone, onComplete, ...dataAttributes }: F0VideoPlayerProps): JSX_2.Element;
 
 export declare interface F0VideoPlayerProps extends DataAttributes_2 {
-    /** Video source URL. */
-    src: string;
+    /**
+     * Video source URL. Localizable — pass a per-locale list of dubbed renditions
+     * to offer selectable audio languages; an "Audio" selector then appears,
+     * independent of the subtitle/caption language.
+     */
+    src: Localized<string>;
+    /**
+     * Initial language for localized content, matched against the provided
+     * locales exactly or by primary subtag, then the viewer's browser language,
+     * then the first provided. Applies to both the audio (`src`) and the text
+     * (`content`) language selections. Only relevant when more than one language
+     * is available.
+     */
+    defaultLanguage?: string;
+    /**
+     * Image URL shown while the video loads and before playback starts (the
+     * native `<video>` poster). Cleared by the browser once playback begins.
+     */
+    poster?: string;
+    /**
+     * Marks the video as having no audio (video-only). Captions (WCAG 2.1
+     * SC 1.2.2) don't apply to silent media, so this exempts the player from the
+     * captions requirement — `data-video-captions` is set to `"no-audio"` instead
+     * of `"missing"`. Note video-only content may still need a text/audio
+     * alternative for its visual information (SC 1.2.1) — audio description still
+     * works over a silent video (its description audio plays even though the video
+     * itself is muted). Browsers can't reliably detect the absence of audio before
+     * playback, so this is declared explicitly.
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Structured content for the player. Currently carries `captions` (a WebVTT
+     * URL or raw WebVTT string) shown over the video during playback and
+     * toggled with the "CC" control. When `captions` is omitted, captions
+     * embedded in the video file are used instead.
+     */
+    content?: VideoPlayerContent;
+    /**
+     * Keep the controls bar visible during playback instead of auto-hiding it.
+     * By default the controls show while the video is paused and auto-hide while
+     * it plays (revealing on hover or keyboard focus); set this to keep them
+     * visible the whole time. Default `false`.
+     */
+    persistControls?: boolean;
     /** Start playing on mount. Default `false`. */
     autoPlay?: boolean;
     /** Focus the player on mount so keyboard shortcuts work immediately. Default `false`. */
@@ -13311,7 +13435,7 @@ export declare function injectSectionEnds(items: FlatFormItem[], inSectionQuesti
  */
 export declare const Input: ForwardRefExoticComponent<Omit<F0TextInputProps, "ref"> & RefAttributes<HTMLInputElement>>;
 
-declare const Input_2: React_2.ForwardRefExoticComponent<Omit<React_2.InputHTMLAttributes<HTMLInputElement>, "onChange" | "size"> & Pick<InputFieldProps<string>, "label" | "onChange" | "size" | "icon" | "role" | "onFocus" | "onBlur" | "transparent" | "status" | "loading" | "disabled" | "maxLength" | "required" | "error" | "append" | "hideLabel" | "hint" | "labelIcon" | "onClickContent" | "readonly" | "clearable" | "autocomplete" | "onClear" | "isEmpty" | "emptyValue" | "hideMaxLength" | "appendTag" | "lengthProvider" | "buttonToggle"> & React_2.RefAttributes<HTMLInputElement>>;
+declare const Input_2: React_2.ForwardRefExoticComponent<Omit<React_2.InputHTMLAttributes<HTMLInputElement>, "onChange" | "size"> & Pick<InputFieldProps<string>, "label" | "onChange" | "size" | "icon" | "role" | "onFocus" | "onBlur" | "transparent" | "status" | "loading" | "disabled" | "maxLength" | "required" | "error" | "append" | "hideLabel" | "hint" | "isEmpty" | "labelIcon" | "onClickContent" | "readonly" | "clearable" | "autocomplete" | "onClear" | "emptyValue" | "hideMaxLength" | "appendTag" | "lengthProvider" | "buttonToggle"> & React_2.RefAttributes<HTMLInputElement>>;
 
 declare const INPUTFIELD_SIZES: readonly ["sm", "md"];
 
@@ -13697,6 +13821,26 @@ export declare interface LoadingStateProps {
     label: string;
 }
 
+/** A single value, or the same value provided in multiple languages. */
+declare type Localized<T> = T | LocalizedOption<T>[];
+
+/**
+ * Shared helpers for content that can be provided in one language (a plain
+ * value) or several (a list of per-locale entries) — used by the media players
+ * for captions, descriptions, transcriptions and summaries.
+ */
+declare interface LocalizedOption<T> {
+    /** BCP-47 language tag, e.g. `"en"`, `"es"`, `"en-US"`. */
+    locale: string;
+    /**
+     * Display label for the language picker. Defaults to the language name for
+     * `locale` (via `Intl.DisplayNames`), so this is only needed to override it.
+     */
+    label?: string;
+    /** The value for this locale. */
+    value: T;
+}
+
 export declare type LockedQuestionNotice = {
     description: string;
 };
@@ -17697,6 +17841,26 @@ export declare interface UseDataSourceItemNavigationReturn<R extends RecordType>
     previousItemUrl: string | null;
 }
 
+/**
+ * Derives a transcription from the audio element's text tracks, so a recording
+ * that ships its own transcript surfaces one even when the consumer doesn't
+ * pass `content.transcription`.
+ *
+ * Tracks are read in-band-first (embedded in the file), then from out-of-band
+ * `<track>` children as a fallback — both live on `audio.textTracks`. Cues load
+ * asynchronously, so the hook watches for tracks and cue changes and re-reads
+ * until it finds text.
+ *
+ * @param audioRef   ref to the player's `<audio>` element
+ * @param currentSrc the resolved source URL; derivation restarts when it
+ *                   changes so a new file's tracks replace the old ones
+ * @param enabled    when `false`, derivation is skipped (e.g. a transcription
+ *                   was already passed explicitly) and the hook returns
+ *                   `undefined`
+ * @returns the joined cue text, or `undefined` while none is available
+ */
+export declare const useDerivedTranscription: (audioRef: RefObject<HTMLAudioElement>, currentSrc: string | undefined, enabled: boolean) => string | undefined;
+
 export declare function useDndEvents(handler: (e: {
     phase: "start" | "over" | "drop" | "cancel";
     source: DragPayload;
@@ -18258,6 +18422,7 @@ declare const valueDisplayRenderers: {
     readonly person: (args: PersonCellValue_2, meta: ValueDisplayRendererContext_2) => JSX_2.Element;
     readonly percentage: (args: PercentageCellValue, meta: ValueDisplayRendererContext_2) => JSX_2.Element | null;
     readonly progressBar: (args: ProgressBarCellValue_2, _meta: ValueDisplayRendererContext_2) => JSX_2.Element | null;
+    readonly progressSeries: (args: ProgressSeriesCellValue, meta: ValueDisplayRendererContext_2) => JSX_2.Element;
     readonly barSeries: (args: BarSeriesCellValue, meta: ValueDisplayRendererContext_2) => JSX_2.Element;
     readonly categoryBarChart: (args: CategoryBarChartCellValue, meta: ValueDisplayRendererContext_2) => JSX_2.Element;
     readonly hourDistribution: (args: HourDistributionCellValue_2, meta: ValueDisplayRendererContext_2) => JSX_2.Element;
@@ -18287,6 +18452,56 @@ showRatio?: boolean;
 valueFormatter?: (value: string | number | undefined) => string | number;
 } & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
 
+/**
+ * Structured content for the video player.
+ *
+ * Every field accepts either a single value or a localized list
+ * (`[{ locale, label?, value }]`) — pass several languages and a language
+ * selector appears in the controls. A single shared selection drives captions,
+ * descriptions and the described source together (each falls back to its first
+ * entry for languages it doesn't provide). See `F0VideoPlayerProps.defaultLanguage`.
+ *
+ * `captions` are timed text shown over the video during playback (WCAG 2.1
+ * SC 1.2.2, Captions). Pass either a WebVTT resource URL or a raw WebVTT string
+ * (the player turns raw VTT into a blob track, so no CORS setup is needed); a
+ * remote URL requires the video host to allow cross-origin reads. When omitted,
+ * the player uses any caption/subtitle track embedded in the video file. A
+ * captions toggle in the controls shows/hides them (a filled glyph when on, a
+ * line glyph when off).
+ *
+ * Audio description (WCAG 2.1 SC 1.2.5) conveys on-screen visual information as
+ * audio, complementary to captions — both are independent and can be on at
+ * once. Provide it in one of two ways, toggled with the audio-description
+ * control (a filled "AD" badge when on, a line badge when off):
+ * - `describedSrc`: a pre-produced media rendition with description mixed into
+ *   the audio. Toggling swaps the source, preserving position and play state.
+ *   Highest quality; assumed the same length as `src`.
+ * - `descriptions`: a WebVTT `kind="descriptions"` script (URL or raw VTT),
+ *   delivered at runtime — the video pauses on each cue so the description can
+ *   be spoken (extended audio description), then resumes. Used only when
+ *   `describedSrc` is absent.
+ */
+export declare interface VideoPlayerContent {
+    /**
+     * WebVTT URL, or raw WebVTT content, for captions shown during playback.
+     * Localizable — pass a per-locale list to offer captions in several languages.
+     */
+    captions?: Localized<string>;
+    /**
+     * A pre-produced described media source (description mixed into the audio),
+     * swapped in when audio description is enabled. Takes precedence over
+     * `descriptions`. Should match `src`'s duration so the position carries
+     * across the swap. Localizable.
+     */
+    describedSrc?: Localized<string>;
+    /**
+     * WebVTT URL, or raw WebVTT content, of a `kind="descriptions"` script.
+     * Delivered at runtime with extended (pausing) audio description when no
+     * `describedSrc` is provided. Localizable.
+     */
+    descriptions?: Localized<string>;
+}
+
 declare type VisualizacionTypeDefinition<Props, Settings = Record<string, never>> = {
     render: (props: Props) => JSX.Element;
     name: string;