origam 2.3.0 → 2.6.1

package/dist/src/interfaces/Media/media-controller.interface.d.ts

@@ -0,0 +1,159 @@
+import type { ICommonsComponentProps, IMediaPlayerMethods, IMediaPlayerState } from '../../interfaces';
+import type { TAudioLoopMode, TQualityOption } from '../../types';
+/**
+ * Props for `<OrigamMediaController>` — the universal media-controls
+ * shell consumed by `<OrigamVideo>` and `<OrigamAudio>`. Both parents
+ * own the `<video>` / `<audio>` element AND the playlist (when one);
+ * the Controller is purely presentational and emits intents the
+ * parent acts on.
+ *
+ * The audio-specific contracts (playlist navigation, tri-state loop,
+ * shuffle) ship as opt-in props so video consumers see zero
+ * regression — pass `:show-loop="false"` etc to keep the legacy
+ * video toolbar unchanged.
+ *
+ * Defaults are inlined inside `withDefaults` (cf. CLAUDE.md
+ * `withDefaults` rule) — this interface only types the public API.
+ */
+export interface IMediaControllerProps extends ICommonsComponentProps {
+    /** Reactive media state from `useMediaPlayer()` (or any
+     *  specialisation: `useVideoPlayer`, `useAudioPlayer`). Required. */
+    state: IMediaPlayerState;
+    /** Imperative methods from `useMediaPlayer()`. Required. */
+    methods: IMediaPlayerMethods;
+    /** YouTube-style overlay mode: the shell sits on top of the media
+     *  surface with a dark gradient and auto-hides on `visible=false`.
+     *  When `false`, the shell renders as a regular always-on toolbar.
+     *
+     *  @default false */
+    inset?: boolean;
+    /** Visibility flag driven by the parent's autohide logic.
+     *
+     *  @default true */
+    visible?: boolean;
+    /** Available playback rates exposed via the config menu.
+     *
+     *  @default [0.5, 0.75, 1, 1.25, 1.5, 2] */
+    playbackRates?: ReadonlyArray<number>;
+    /** Enable the cast / AirPlay button (Remote Playback API).
+     *
+     *  @default false */
+    allowRemotePlayback?: boolean;
+    /** Adds a "Download" row to the config menu.
+     *
+     *  @default false */
+    downloadable?: boolean;
+    /** URL surfaced to the consumer when "Download" is clicked.
+     *
+     *  @default null */
+    downloadUrl?: string | null;
+    /** Suggested filename written to the `<a download="…">` attribute.
+     *
+     *  @default undefined */
+    downloadFilename?: string;
+    /** Optional list of quality variants. When the array exposes ≥ 2
+     *  entries, a "Quality" drill-down appears in the config menu.
+     *
+     *  @default [] */
+    qualityOptions?: ReadonlyArray<TQualityOption>;
+    /** Currently-active quality identifier.
+     *
+     *  @default null */
+    currentQuality?: string | null;
+    /** Show the "previous" transport button. The parent listens to
+     *  the `previous` emit and decides whether to skip back 10s
+     *  (single-track) or jump to the previous playlist track.
+     *
+     *  @default false */
+    showPrevious?: boolean;
+    /** Show the "next" transport button. Parent owns the action.
+     *
+     *  @default false */
+    showNext?: boolean;
+    /** Show the tri-state loop button (none → all → one → none).
+     *
+     *  @default false */
+    showLoop?: boolean;
+    /** Show the shuffle toggle button.
+     *
+     *  @default false */
+    showShuffle?: boolean;
+    /** Current loop mode. Supports `v-model:loopMode`. The Controller
+     *  cycles this on click; the parent observes and applies its
+     *  playlist / `<audio loop>` policy.
+     *
+     *  @default 'none' */
+    loopMode?: TAudioLoopMode;
+    /** Current shuffle state. Supports `v-model:shuffle`. The
+     *  Controller toggles on click; the parent reads and switches its
+     *  next-track resolution accordingly.
+     *
+     *  @default false */
+    shuffle?: boolean;
+}
+/**
+ * Emits surfaced by `<OrigamMediaController>`. The shell calls
+ * `methods.*` directly for the basic ops (toggle play, seek, set
+ * volume, set rate, toggle mute, request cast) — those don't bubble.
+ *
+ * The emits below are the ones the PARENT must handle because the
+ * Controller doesn't own enough context:
+ *   - `quality-change` — parent owns the `<source>` swap logic.
+ *   - `download`       — parent owns the URL fetch / anchor click.
+ *   - `previous` / `next` — parent owns the playlist or skip-time
+ *                            policy.
+ *   - `update:loopMode` / `update:shuffle` — two-way binding for the
+ *                                            transport toggles.
+ */
+export interface IMediaControllerEmits {
+    (e: 'quality-change', quality: string): void;
+    (e: 'download'): void;
+    (e: 'previous'): void;
+    (e: 'next'): void;
+    (e: 'update:loopMode', mode: TAudioLoopMode): void;
+    (e: 'update:shuffle', shuffle: boolean): void;
+}
+/**
+ * Scoped slots exposed by `<OrigamMediaController>`. Consumers
+ * inject media-specific blocks (`<OrigamAudio>` injects header +
+ * waveform + footer; `<OrigamVideo>` injects captions/PiP/fullscreen
+ * through `extraControlsRight`).
+ */
+export interface IMediaControllerSlots {
+    /** Block rendered ABOVE the scrubber row. `<OrigamAudio>` injects
+     *  the cover + metadata strip here; `<OrigamVideo>` typically
+     *  leaves it empty. */
+    header?: () => any;
+    /** Replaces the default `<OrigamMediaScrubber>` scrubber row.
+     *  Receives `{ state, methods }` so the consumer can paint a
+     *  custom scrubber (audio waveform via SliderField variant=audio,
+     *  for example) while still routing seeks through `methods.seek`. */
+    waveform?: (bindings: {
+        state: IMediaPlayerState;
+        methods: IMediaPlayerMethods;
+    }) => any;
+    /** Block rendered BELOW the transport row. `<OrigamAudio>` injects
+     *  the playlist list here. */
+    footer?: () => any;
+    /** Buttons rendered at the start of the transport row, before the
+     *  play button. `<OrigamAudio>` can inject custom shuffle / queue
+     *  buttons here when the default `showShuffle` placement doesn't
+     *  fit. */
+    'prepend-transport'?: () => any;
+    /** Buttons rendered at the end of the transport row, after the
+     *  config menu. Consumers add custom buttons (favourite, queue,
+     *  …) here. */
+    'append-transport'?: () => any;
+    /** Additional buttons rendered on the left side of the toolbar,
+     *  AFTER the time display. Legacy slot — prefer `prepend-transport`. */
+    extraControlsLeft?: () => any;
+    /** Additional buttons rendered on the right side of the toolbar,
+     *  BEFORE the config menu. `<OrigamVideo>` injects its captions /
+     *  PiP / fullscreen buttons here. */
+    extraControlsRight?: () => any;
+    /** Extra rows in the config menu (audio output device, subtitle
+     *  track selector, …). Receives `{ closeMenu }`. */
+    configExtra?: (bindings: {
+        closeMenu: () => void;
+    }) => any;
+}

package/dist/src/interfaces/Media/media-player.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Media/media-player.interface.d.ts

@@ -0,0 +1,121 @@
+import type { Ref } from 'vue';
+/**
+ * Reactive state surface returned by `useMediaPlayer` — the
+ * media-agnostic base shared between `useVideoPlayer` and
+ * `useAudioPlayer`. Fields below describe state that applies to both
+ * `HTMLVideoElement` and `HTMLAudioElement`; video-specific extensions
+ * (`fullscreen`, `pip`) live in `IVideoPlayerState`.
+ */
+export interface IMediaPlayerState {
+    /** True while the element is decoding frames / producing audio. */
+    playing: Ref<boolean>;
+    /** True when playback is paused (or has not started yet). */
+    paused: Ref<boolean>;
+    /** Current playhead position in seconds. */
+    currentTime: Ref<number>;
+    /**
+     * Total duration in seconds. `NaN` until metadata loads. Can be
+     * `Infinity` for live streams — consumers must guard `max` UI
+     * bindings with `Number.isFinite()`.
+     */
+    duration: Ref<number>;
+    /**
+     * End of the buffered range in seconds (the right edge of the last
+     * contiguous chunk the browser can play without stalling).
+     */
+    buffered: Ref<number>;
+    /** Volume between 0 and 1 — independent from `muted`. */
+    volume: Ref<number>;
+    /** True when the output is muted. Independent from `volume`. */
+    muted: Ref<boolean>;
+    /** True once metadata has loaded and `duration` is finite. */
+    ready: Ref<boolean>;
+    /** True between `loadstart` and `loadedmetadata` (or `waiting`). */
+    loading: Ref<boolean>;
+    /** Last media error captured by the composable, if any. */
+    error: Ref<MediaError | Error | null>;
+    /** Current playback rate. `1` = normal speed. */
+    playbackRate: Ref<number>;
+    /** True when at least one Remote Playback device is reachable. */
+    remoteAvailable: Ref<boolean>;
+    /** Connection state of the Remote Playback session. */
+    remoteState: Ref<'disconnected' | 'connecting' | 'connected'>;
+}
+/**
+ * Imperative methods returned by `useMediaPlayer`. Media-agnostic
+ * subset — every method maps 1:1 to the standard `HTMLMediaElement`
+ * API. Video-specific commands (`toggleFullscreen`, `togglePip`,
+ * `enterFullscreen`, …) live in `IVideoPlayerMethods`.
+ */
+export interface IMediaPlayerMethods {
+    /** Resolve once `el.play()` has settled (or the call has been
+     *  swallowed into `state.error`). */
+    play: () => Promise<void>;
+    /** Pause playback. Returns synchronously. */
+    pause: () => void;
+    /** Toggle between play and pause based on the current `playing`
+     *  state. Convenience over `if (playing) pause() else play()`. */
+    toggle: () => Promise<void>;
+    /** Seek to `seconds`, clamped to `[0, duration]`. */
+    seek: (seconds: number) => void;
+    /** Set the volume, clamped to `[0, 1]`. Un-mutes when raising
+     *  the volume from zero. */
+    setVolume: (value: number) => void;
+    /** Flip the muted flag on the element. */
+    toggleMute: () => void;
+    /** Force a reload of the underlying media element. */
+    load: () => void;
+    /** Jump backward by `seconds`, clamped to [0, duration]. */
+    skipBackward: (seconds: number) => void;
+    /** Jump forward by `seconds`, clamped to [0, duration]. */
+    skipForward: (seconds: number) => void;
+    /** Set the playback rate, clamped to `[0.25, 4]`. */
+    setPlaybackRate: (rate: number) => void;
+    /** Open the native cast / AirPlay device picker. No-op when the
+     *  Remote Playback API is unavailable. */
+    requestRemotePlayback: () => Promise<void>;
+    /** Force-disconnect any active Remote Playback session. No-op
+     *  when no session is active or the API is unavailable. */
+    stopRemotePlayback: () => Promise<void>;
+}
+/**
+ * Shared media event signatures. Composables themselves do NOT emit —
+ * consumers wire their own emits from the state refs. This interface
+ * is kept for documentation + for components that want to surface
+ * the same shape on their public emit contract.
+ */
+export interface IMediaPlayerEmits {
+    (e: 'play'): void;
+    (e: 'pause'): void;
+    (e: 'ended'): void;
+    (e: 'timeupdate', currentTime: number): void;
+    (e: 'volumechange', volume: number): void;
+    (e: 'loadedmetadata', payload: {
+        duration: number;
+    }): void;
+    (e: 'error', err: MediaError | Error): void;
+    /** Two-way binding for the playback rate. The component DOES NOT
+     *  set this in response to the consumer's prop changes — only when
+     *  the user picks a rate from the config menu. */
+    (e: 'update:playbackRate', rate: number): void;
+}
+/**
+ * Options accepted by `useMediaPlayer`. The composable is media-agnostic
+ * — `mediaRef` accepts any `HTMLMediaElement` (audio OR video).
+ */
+export interface IUseMediaPlayerOptions {
+    /** Suppress autoplay when the user has requested reduced motion. */
+    autoplay?: boolean;
+    /** Initial muted state. */
+    muted?: boolean;
+    /** Loop on `ended`. */
+    loop?: boolean;
+    /** Buffering hint. */
+    preload?: 'none' | 'metadata' | 'auto';
+    /**
+     * Resolves to the `HTMLMediaElement` to drive. When omitted, the
+     * composable creates an empty ref and expects the consumer to
+     * `bind` it on a `<video ref>` / `<audio ref>` themselves.
+     */
+    mediaRef?: Ref<HTMLMediaElement | null>;
+}

package/dist/src/interfaces/Media/media-scrubber.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Media/media-scrubber.interface.d.ts

@@ -0,0 +1,137 @@
+import type { IColorProps, ICommonsComponentProps, IRoundedProps } from '../../interfaces';
+import type { TMediaScrubberOrientation } from '../../types';
+/**
+ * Props for `<OrigamMediaScrubber>` — a headless, media-agnostic
+ * value-on-a-track widget. Owns NO state: the parent controls
+ * `modelValue` and listens to `update:modelValue` / `change` / `drag*`
+ * / `hover` events. Used internally by `<OrigamVideo>` (and soon
+ * `<OrigamAudio>`) for the timeline AND the volume slider — both share
+ * the exact same drag / keyboard / ARIA pipeline; only the orientation
+ * and the `buffered` channel differ.
+ *
+ * Defaults are inlined inside `withDefaults` (cf. CLAUDE.md
+ * `withDefaults` rule) — this interface only types the public API.
+ */
+export interface IMediaScrubberProps extends ICommonsComponentProps, IColorProps, IRoundedProps {
+    /**
+     * Current value, between `min` and `max`. Supports `v-model`.
+     * The component never mutates this directly — every change is
+     * surfaced via `update:modelValue` so the parent stays the
+     * single source of truth.
+     */
+    modelValue: number;
+    /**
+     * Lower bound of the value range.
+     *
+     * @default 0
+     */
+    min?: number;
+    /**
+     * Upper bound of the value range. Required to compute the thumb
+     * position. Passing `0` (or any value `<= min`) freezes the
+     * scrubber at the start.
+     */
+    max: number;
+    /**
+     * Discrete step. `0` (default) means continuous — pointer events
+     * emit the raw float; positive values snap each emission to the
+     * nearest multiple.
+     *
+     * @default 0
+     */
+    step?: number;
+    /**
+     * Optional buffered position (typically the end of the browser's
+     * media buffer). Renders the `__buffer` bar from `min` up to
+     * `buffered`. Pass `undefined` to hide the bar entirely.
+     */
+    buffered?: number;
+    /**
+     * Layout axis. Horizontal = YouTube timeline shape, Vertical =
+     * volume / level meter shape (top of track = `max`,
+     * bottom of track = `min`).
+     *
+     * @default 'horizontal'
+     */
+    orientation?: TMediaScrubberOrientation;
+    /**
+     * Disables pointer + keyboard interaction. The element drops out
+     * of the tab order (`tabindex="-1"`) and pointer events become
+     * no-ops; styling stays untouched so consumers can paint their
+     * own disabled state via `:has(.origam-media-scrubber--disabled)`
+     * or similar.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Hides the thumb at rest and reveals it on hover / focus / drag —
+     * the YouTube pattern. When `false`, the thumb is always visible.
+     *
+     * @default false
+     */
+    showThumbOnHoverOnly?: boolean;
+    /**
+     * Shows a tooltip above the cursor (horizontal only) reflecting
+     * the hovered value. Content can be overridden via the `#tooltip`
+     * slot.
+     *
+     * @default false
+     */
+    showHoverTooltip?: boolean;
+    /**
+     * Formatter for the default hover tooltip label. Receives the
+     * hovered value, returns the string to render.
+     *
+     * @default value => String(value)
+     */
+    formatHoverTooltip?: (value: number) => string;
+    /**
+     * Accessibility label — read by screen readers when the
+     * scrubber gains focus. Always pass a translated string here.
+     * Declared optional to allow Volar to map the kebab-case `:aria-label`
+     * attribute from parent templates without a required-prop error.
+     */
+    ariaLabel?: string;
+    /**
+     * Optional human-readable representation of the current value
+     * (e.g. `"1:23"` for a timestamp, `"45 %"` for a volume).
+     * Mapped to `aria-valuetext`.
+     */
+    ariaValueText?: string;
+    /**
+     * Optional `data-cy` test selector forwarded by the parent
+     * (`OrigamMediaController`, `OrigamMediaVolumeControl`) as a
+     * camelCase Vue prop. Passed through `$attrs` to the host element.
+     */
+    dataCy?: string;
+}
+/**
+ * Emits for `<OrigamMediaScrubber>`.
+ */
+export interface IMediaScrubberEmits {
+    /** Live value update — fires during drag, keyboard, and click. */
+    (e: 'update:modelValue', value: number): void;
+    /** Commit event — fires on pointerup / pointercancel after a drag. */
+    (e: 'change', value: number): void;
+    /** Drag has started (pointerdown captured). */
+    (e: 'dragstart'): void;
+    /** Drag has ended (pointerup / pointercancel). */
+    (e: 'dragend'): void;
+    /** Hover position — fires with the hovered value on pointermove,
+     *  and with `null` on pointerleave (cursor left the track). */
+    (e: 'hover', value: number | null): void;
+}
+/**
+ * Slot signatures for `<OrigamMediaScrubber>`.
+ */
+export interface IMediaScrubberSlots {
+    /**
+     * Hover-tooltip body. Receives the hovered value. Only rendered
+     * when `showHoverTooltip=true` AND the cursor sits over the
+     * track (horizontal orientation).
+     */
+    tooltip?: (bindings: {
+        value: number;
+    }) => any;
+}

package/dist/src/interfaces/Media/media-volume-control.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Media/media-volume-control.interface.d.ts

@@ -0,0 +1,68 @@
+import type { ICommonsComponentProps } from '../../interfaces';
+/**
+ * Props for `<OrigamMediaVolumeControl>` — the mute / unmute button
+ * AND the YouTube-style vertical scrubber tooltip that opens on
+ * hover above it.
+ *
+ * Owns:
+ *  - the off/low/medium/high icon swap (driven by `volume` + `muted`),
+ *  - the resolvedVolume collapse (slider sits at 0 when muted=true so
+ *    the user can drag-up to unmute in a single gesture),
+ *  - the tooltip percentage formatter.
+ *
+ * Does NOT own the underlying `methods.toggleMute()` /
+ * `methods.setVolume()` calls — emits `update:muted` and
+ * `update:volume` so the parent stays the source of truth for
+ * media-side mutations.
+ */
+export interface IMediaVolumeControlProps extends ICommonsComponentProps {
+    /**
+     * Linear volume in `[0, 1]`. Typically `state.volume.value`.
+     * Required.
+     */
+    volume: number;
+    /**
+     * Whether the media is muted. When `true`, the slider collapses
+     * to 0 (resolvedVolume rule) and the icon becomes VOLUME_OFF.
+     * Required.
+     */
+    muted: boolean;
+    /**
+     * `aria-label` rendered on the toggle button when the media is
+     * NOT muted (clicking will mute). Already-translated. Required.
+     */
+    muteLabel: string;
+    /**
+     * `aria-label` rendered on the toggle button when the media IS
+     * muted (clicking will unmute). Already-translated. Required.
+     */
+    unmuteLabel: string;
+    /**
+     * `aria-label` rendered on the vertical scrubber inside the
+     * tooltip. Already-translated. Required.
+     */
+    volumeLabel: string;
+    /**
+     * Optional `data-cy` prefix used on the toggle button. The
+     * tooltip wrapper + scrubber expose their own selectors via
+     * convention (`${dataCy}-wrapper`, `${dataCy}-scrubber`).
+     *
+     * @default 'origam-media-volume-control'
+     */
+    dataCy?: string;
+}
+/**
+ * Emits surfaced by `<OrigamMediaVolumeControl>`. The atom does NOT
+ * call `methods.*` directly; the parent owns the media-side
+ * mutations.
+ */
+export interface IMediaVolumeControlEmits {
+    /** The mute toggle button was clicked. Payload is the proposed
+     *  new muted state (i.e. `!muted`). */
+    (e: 'update:muted', muted: boolean): void;
+    /** The vertical scrubber moved. Payload is the new linear
+     *  volume in `[0, 1]`. The parent must call `setVolume()` AND
+     *  toggle mute as appropriate (rising from 0 → unmute, falling
+     *  to 0 → mute). */
+    (e: 'update:volume', volume: number): void;
+}

package/dist/src/interfaces/Menu/menu.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IListItemProps, IListProps, IOverlayProps } from '../../interfaces';
+import type { ICommonsComponentEmits, IListItemProps, IListProps, IOverlayProps } from '../../interfaces';
 export interface IMenuProvide {
     register(): void;
     unregister(): void;
@@ -7,3 +7,9 @@ export interface IMenuProvide {
 export interface IMenuProps extends IOverlayProps, IListProps, IListItemProps {
     id?: string;
 }
+/** Emits fired by `<OrigamMenu>` — v-model on the open state plus the
+ *  native `contextmenu` bubble forwarded for parents that want to
+ *  show their own context menu instead. */
+export interface IMenuEmits extends ICommonsComponentEmits {
+    (e: 'contextmenu', event: MouseEvent): void;
+}

package/dist/src/interfaces/Messages/messages.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITransitionComponentProps } from '../../interfaces';
-export interface IMessagesProps extends ICommonsComponentProps, ITagProps, ITransitionComponentProps, IColorProps, IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, IDensityProps, IElevationProps {
+import type { IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, ITransitionComponentProps, ITypographyProps } from '../../interfaces';
+export interface IMessagesProps extends ICommonsComponentProps, ITagProps, ITransitionComponentProps, IColorProps, IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, IDensityProps, IElevationProps, ITypographyProps {
     active?: boolean;
     messages?: Array<string> | string;
 }

package/dist/src/interfaces/NumberField/number-field.interface.d.ts

@@ -1,6 +1,6 @@
-import type { IAdjacentInnerProps, IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IFieldEmits, IFieldProps, IFieldSlots, IInputEmits, IInputProps, IInputSlots, IMarginProps, IPaddingProps, IRoundedProps, IVariantProps } from "../../interfaces";
+import type { IFieldEmits, IFieldProps, IFieldSlots, IInputEmits, IInputProps, IInputSlots, IVariantProps } from "../../interfaces";
 import type { TIcon } from "../../types";
-export interface INumberFieldProps extends ICommonsComponentProps, IColorProps, IDensityProps, IFieldProps, IInputProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IVariantProps, IAdjacentInnerProps {
+export interface INumberFieldProps extends IFieldProps, IInputProps, IVariantProps {
     autofocus?: boolean;
     placeholder?: string;
     persistentPlaceholder?: boolean;
@@ -33,7 +33,7 @@ export interface INumberFieldSlots extends IFieldSlots, Omit<IInputSlots, 'defau
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
     increment?: (data: {

package/dist/src/interfaces/NumberFormat/number-format.interface.cjs

@@ -0,0 +1 @@
+"use strict";