@wix/editor-react-components 1.2748.0 → 1.2749.0

package/dist/site/components/VideoScrub/timeframes/TimeframeLayer.d.ts

@@ -0,0 +1,22 @@
+import { default as React, AriaAttributes, ReactNode } from 'react';
+export type TimeframeLayerItem = {
+    /** The timeframe's `timeframeIdentifier` (runtime props have no `_id`). Never the index: that would mix up container state after a split. */
+    key: string;
+    content: ReactNode;
+};
+export type TimeframeLayerProps = {
+    /** Same order as the timeframes. */
+    items: ReadonlyArray<TimeframeLayerItem>;
+    activeIndex: number | undefined;
+    className?: string;
+    /**
+     * The layer's label, from the parent's `a11y` data (already converted with
+     * `convertA11yKeysToHtmlFormat`). Focus falls back to the layer, so it needs a name.
+     */
+    a11yAttributes?: AriaAttributes;
+};
+/**
+ * Shows the active timeframe's content on top of the video. All items stay mounted (the inactive
+ * ones hidden) on purpose: the server HTML then holds every timeframe's content, for SEO.
+ */
+export declare function TimeframeLayer({ items, activeIndex, className, a11yAttributes, }: TimeframeLayerProps): React.JSX.Element;

package/dist/site/components/VideoScrub/timeframes/edit.d.ts

@@ -0,0 +1,86 @@
+import { Timeframe, NewTimeframe, Result, NewTimeframeId, Rules } from './types';
+/**
+ * One timeframe from 0 to DEFAULT_TIMEFRAME_MS (or the whole video if it is shorter), with a new
+ * timeframeIdentifier. No container key, so the editor makes an empty one. A video shorter than
+ * MIN_LENGTH_MS has room for no timeframe, so the list is empty.
+ */
+export declare function createInitial(durationMs: number, { newTimeframeId, }?: {
+    newTimeframeId?: NewTimeframeId;
+}): Array<NewTimeframe>;
+/**
+ * A new timeframe that starts at `atMs`, in a gap. Its length is DEFAULT_TIMEFRAME_MS, or less when
+ * the next timeframe or the end of the video comes first. It fails with insideTimeframe when `atMs`
+ * is inside a timeframe (a timeframe's own end is not inside it), and with noRoom when less than
+ * MIN_LENGTH_MS fits. No container key, so the editor makes an empty one.
+ * `result.index` is the new timeframe's position.
+ */
+export declare function add(list: ReadonlyArray<Timeframe>, atMs: number, rules: Rules): Result;
+/** Cuts the timeframe that contains `atMs` in two. In a gap it fails with inGap. */
+export declare function split(list: ReadonlyArray<Timeframe>, atMs: number, rules: Rules): Result;
+export type Edge = 'start' | 'end';
+/**
+ * Drags one edge of `list[index]` to `atMs`. Moving into a gap changes only this timeframe. When the
+ * edge reaches a neighbor, it keeps pushing: the neighbor's touching edge moves too, so the
+ * neighbor gets shorter. It never pushes past one neighbor. It fails with tooShort when this
+ * timeframe or the neighbor would be under MIN_LENGTH_MS; use edgeLimits to clamp a drag first.
+ */
+export declare function resizeEdge(list: ReadonlyArray<Timeframe>, index: number, edge: Edge, atMs: number, rules: Rules): Result;
+/**
+ * The range `resizeEdge` accepts for one edge: this timeframe and the neighbor it may push both keep
+ * MIN_LENGTH_MS, and the edge stays inside `[0, durationMs]`. Undefined for an unknown index.
+ * On broken saved data `minMs` can be more than `maxMs`: then no drag is possible.
+ */
+export declare function edgeLimits(list: ReadonlyArray<Timeframe>, index: number, edge: Edge, rules: Rules): {
+    minMs: number;
+    maxMs: number;
+} | undefined;
+/**
+ * The `startMs` range `moveTimeframe` can reach for `list[index]`, keeping its length. It may push
+ * every timeframe before it to 0 and every timeframe after it to durationMs, so: from the total
+ * length of the timeframes before it, to durationMs minus its own length and the total length of
+ * the timeframes after it. Gaps do not count, because a push uses them up. Undefined for an unknown
+ * index. On broken saved data (timeframes longer than the video) `minMs` can be more than `maxMs`.
+ */
+export declare function moveLimits(list: ReadonlyArray<Timeframe>, index: number, rules: Rules): {
+    minMs: number;
+    maxMs: number;
+} | undefined;
+/**
+ * Moves the whole timeframe `list[index]` so it starts at `startMs`, keeping its length. When it
+ * reaches a neighbor it pushes it, and that neighbor pushes the next one, as a chain: each pushed
+ * timeframe keeps its length, gaps are used up first, and a timeframe moves only when it is reached.
+ * `startMs` is clamped to moveLimits, so the last pushed timeframe stops at 0 or at durationMs.
+ * The order never changes and `result.index` is `index`. Only times change; `_id`,
+ * `timeframeIdentifier`, `name` and `container` stay. Errors: notFound, badTime (not a whole
+ * number), and the usual result checks (on broken saved data, see moveLimits).
+ */
+export declare function moveTimeframe(list: ReadonlyArray<Timeframe>, index: number, startMs: number, rules: Rules): Result;
+/**
+ * Removes a timeframe and leaves a gap: no neighbor gets its time. Removing the only timeframe is
+ * fine (an empty list is valid). `result.index` is the position the removed item had, moved back
+ * by one when it was last, so it points at a neighbor; it is -1 when the list is now empty.
+ * It does not check the result: it works on a broken list, so users can repair old data.
+ * Run validate on result.list to see the problems that are still there.
+ */
+export declare function remove(list: ReadonlyArray<Timeframe>, _id: string): Result;
+type TimeframePatch = {
+    name?: string | undefined;
+    /** `null` removes it, back to the default (1). */
+    scrollSensitivity?: number | null | undefined;
+};
+/**
+ * Changes only `name` and `scrollSensitivity`; an undefined value keeps the old one. Times change
+ * only through add, split, resizeEdge, moveTimeframe and remove. A name that is not a string fails
+ * with badItem (validate checks it; the editor crashes on it). Two items with this _id fail with
+ * duplicateId.
+ */
+export declare function update(list: ReadonlyArray<Timeframe>, _id: string, patch: TimeframePatch, rules: Rules): Result;
+/**
+ * A guard for a video length that is a little off (the 1 ms rounding of ms → s → ms). Any timeframe
+ * that ends past `rules.durationMs` is cut to end there. It never resets and never makes a timeframe
+ * longer: a longer video just has a gap at the end. It drops nothing: an item that starts at or
+ * after `durationMs` is a tooShort error, and so is an item that would get under MIN_LENGTH_MS.
+ * An empty list comes back as it is. The result is checked like every other write.
+ */
+export declare function fitToDuration(list: ReadonlyArray<Timeframe>, rules: Rules): Result;
+export {};

package/dist/site/components/VideoScrub/timeframes/index.d.ts

@@ -0,0 +1,13 @@
+export type { Timeframe, TimeframeError, TimeframeErrorCode, TimeframeTiming, NewTimeframe, NewTimeframeId, Result, Rules, } from './types';
+export { DEFAULT_TIMEFRAME_MS, MAX_COUNT, MIN_LENGTH_MS } from './types';
+export { parseList, toMs } from './parse';
+export type { ParsedList } from './parse';
+export { createTimeframeId } from './timeframeId';
+export { validate } from './validate';
+export { add, createInitial, edgeLimits, fitToDuration, moveTimeframe, moveLimits, remove, resizeEdge, split, update, } from './edit';
+export type { Edge } from './edit';
+export { activeAt } from './query';
+export { watchVideoTime } from './watchVideoTime';
+export { useActiveTimeframeIndex } from './useActiveTimeframeIndex';
+export { TimeframeLayer } from './TimeframeLayer';
+export type { TimeframeLayerItem, TimeframeLayerProps } from './TimeframeLayer';

package/dist/site/components/VideoScrub/timeframes/parse.d.ts

@@ -0,0 +1,26 @@
+import { Timeframe, TimeframeError, NewTimeframeId } from './types';
+/**
+ * Video seconds to whole milliseconds, rounded down. A non-finite input gives NaN.
+ * The tiny 1e-6 keeps exact ms safe through ms → s → ms: 8.033 * 1000 is 8032.999… in floating point.
+ */
+export declare const toMs: (seconds: number) => number;
+export type ParsedList = {
+    list: Array<Timeframe>;
+    errors: Array<TimeframeError>;
+    /**
+     * Items that got a new timeframeIdentifier: theirs was missing, or an earlier item already had it
+     * (for example an item the editor duplicated). Not an error: write the list back once so the ids
+     * are saved. Until then each parse makes different ids.
+     */
+    addedKeys: Array<{
+        _id: string;
+        timeframeIdentifier: string;
+    }>;
+};
+/**
+ * The only way editor data enters the module. It never throws and never checks order, overlap or length (that is validate).
+ * `undefined` / `null` (no timeframes saved yet) gives an empty list with no errors.
+ */
+export declare function parseList(data: unknown, { newTimeframeId, }?: {
+    newTimeframeId?: NewTimeframeId;
+}): ParsedList;

package/dist/site/components/VideoScrub/timeframes/query.d.ts

@@ -0,0 +1,7 @@
+import { TimeframeTiming } from './types';
+/**
+ * The timeframe showing at `timeMs`: the one with `startMs <= timeMs < endMs`. In a gap, undefined
+ * (nothing is shown over the video). At or after `durationMs` (the video ended), the timeframe that
+ * ends at the end of the video; if none does, the end is a gap.
+ */
+export declare function activeAt<T extends TimeframeTiming>(list: ReadonlyArray<T>, timeMs: number, durationMs: number): T | undefined;

package/dist/site/components/VideoScrub/timeframes/timeframeId.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A new timeframeIdentifier: crypto.randomUUID when it exists, else a small fallback that is
+ * unique enough inside one list (time + counter + random).
+ */
+export declare function createTimeframeId(): string;

package/dist/site/components/VideoScrub/timeframes/types.d.ts

@@ -0,0 +1,64 @@
+/** A timeframe that the editor has saved. */
+export type Timeframe = {
+    /** The editor's own id. Not in runtime props, so never use it as a React key. */
+    _id: string;
+    /** Our own stable id. Saved as a text field; use it as the React key. */
+    timeframeIdentifier: string;
+    /**
+     * Owner-only label ("Title" in the panel); may be ''. Called `name` because the editor's array
+     * indicator reads `item.name` (and crashes on undefined).
+     */
+    name: string;
+    /** Integer, inclusive. */
+    startMs: number;
+    /** Integer, exclusive. */
+    endMs: number;
+    /** Opaque ref; the editor owns the real container. */
+    container?: string;
+    /** Stored only; missing = 1. */
+    scrollSensitivity?: number;
+};
+/** An item this module asks the editor to create. No _id. */
+export type NewTimeframe = Omit<Timeframe, '_id'>;
+/** Makes a new timeframeIdentifier. Inject one in tests to get fixed ids. */
+export type NewTimeframeId = () => string;
+/** `durationMs` must be a finite, positive whole number. */
+export type Rules = {
+    durationMs: number;
+    newTimeframeId?: NewTimeframeId;
+};
+/** The only fields `activeAt` needs. */
+export type TimeframeTiming = Pick<NewTimeframe, 'startMs' | 'endMs'>;
+export declare const MIN_LENGTH_MS = 100;
+export declare const MAX_COUNT = 40;
+/**
+ * The class on the element that wraps each timeframe's container. The manifest's container
+ * `selector` points at it, like Accordion's `.item-content`. The editor needs this selector to find
+ * each container. (Saves can still fail with SCHEMA_REFERENCES_NOT_FOUND; that is a server bug.)
+ */
+export declare const TIMEFRAME_CONTENT_CLASS = "timeframe-content";
+/** Length of a new timeframe from createInitial and add, when there is room. */
+export declare const DEFAULT_TIMEFRAME_MS = 5000;
+export type TimeframeErrorCode = 'badTime' | 'tooShort' | 'outOfRange' | 'notSorted' | 'overlap' | 'tooMany' | 'notFound' | 'onBoundary' | 'inGap' | 'insideTimeframe' | 'noRoom' | 'badSensitivity' | 'badItem' | 'badKey' | 'duplicateKey' | 'duplicateId';
+export type TimeframeError = {
+    code: TimeframeErrorCode;
+    /**
+     * Position in the list, or -1 for whole-list problems. For a parseList `badItem` it is the
+     * position in the raw editor data: that item is not in `parsed.list`, which is also sorted.
+     */
+    index: number;
+    _id?: string;
+};
+export type Result = {
+    ok: true;
+    list: Array<Timeframe | NewTimeframe>;
+    index: number;
+} | {
+    ok: false;
+    errors: Array<TimeframeError>;
+};
+export declare const timeframeError: (code: TimeframeErrorCode, index: number, _id?: unknown) => TimeframeError;
+/** A video length the rules accept: a positive whole number of ms. */
+export declare const isDuration: (durationMs: number | undefined) => durationMs is number;
+export declare function assertDuration(durationMs: number): void;
+export declare function assertList(list: unknown): void;

package/dist/site/components/VideoScrub/timeframes/useActiveTimeframeIndex.d.ts

@@ -0,0 +1,8 @@
+import { TimeframeTiming } from './types';
+/**
+ * The index of the timeframe showing in `video` now. It re-renders only when the index changes.
+ * `durationMs` comes from the data. Undefined or invalid gives undefined.
+ * Before a video is attached (and on the server), it is the timeframe at time 0.
+ * Pass a stable `timeframes` array (memoized): a new array restarts the video listeners.
+ */
+export declare function useActiveTimeframeIndex<T extends TimeframeTiming>(timeframes: ReadonlyArray<T>, video: HTMLVideoElement | null, durationMs: number | undefined): number | undefined;

package/dist/site/components/VideoScrub/timeframes/validate.d.ts

@@ -0,0 +1,17 @@
+import { TimeframeError, NewTimeframe, Rules } from './types';
+type Item = NewTimeframe & {
+    _id?: string;
+};
+/**
+ * Like validate, but without checking durationMs. For internal use. By default one error per item
+ * (the first problem); `all` gives every problem, which the edits need to compare before and after.
+ */
+export declare function collectErrors(list: ReadonlyArray<Item>, durationMs: number, { all }?: {
+    all?: boolean;
+}): Array<TimeframeError>;
+/**
+ * Checks a list: sorted by startMs, no overlap (touching is fine), every timeframe at least
+ * MIN_LENGTH_MS and inside `[0, durationMs]`. Gaps and an empty list are valid.
+ */
+export declare function validate(list: ReadonlyArray<Item>, rules: Rules): Array<TimeframeError>;
+export {};

package/dist/site/components/VideoScrub/timeframes/watchVideoTime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Calls onTimeMs with toMs(video.currentTime) and video.ended whenever either may have changed.
+ * `ended` is true when the video is scrubbed to the end, and currentTime may stop a bit before the
+ * real end, so a caller that needs "the end" should check `ended`, not the time.
+ * Returns stop(), which is safe to call twice.
+ */
+export declare function watchVideoTime(video: HTMLVideoElement, onTimeMs: (timeMs: number, ended: boolean) => void): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/editor-react-components",
-  "version": "1.2748.0",
+  "version": "1.2749.0",
   "description": "React components for the Wix Editor",
   "license": "MIT",
   "type": "module",
@@ -222,5 +222,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "falconPackageHash": "f5b0ee95fa88e0d111bf5af6485d76c7e88ea2863896a437aa511f30"
+  "falconPackageHash": "4308638f3d5b885f504d39750fffccea1e3377db04ca7104e417300c"
 }