@mieweb/ui 0.10.0-dev.14 → 0.10.0-dev.16

package/dist/{chunk-XEAT7XJG.cjs.map → chunk-VLBUT2QM.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/MediaPlayer/MediaPlayer.tsx"],"names":["cva","React","useMediaTransport","jsx","jsxs","Button"],"mappings":"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","file":"chunk-XEAT7XJG.cjs","sourcesContent":["import * as React from 'react';\nimport { cva, type VariantProps } from 'class-variance-authority';\n\nimport { Button } from '../Button';\nimport { useMediaTransport } from '../../hooks/useMediaTransport';\n\n// ============================================================================\n// Types & Interfaces\n// ============================================================================\n\nexport type MediaPlayerState =\n  | 'idle'\n  | 'loading'\n  | 'playing'\n  | 'paused'\n  | 'error';\n\nexport type MediaKind = 'video' | 'audio';\n\n/** Ref handle for controlling {@link MediaPlayer} programmatically. */\nexport interface MediaPlayerRef {\n  /** Seek to a specific time in milliseconds. */\n  seekToMs: (timeMs: number) => void;\n  /** Start playback. */\n  play: () => void;\n  /** Pause playback. */\n  pause: () => void;\n  /** Get current playback time in milliseconds. */\n  getCurrentTimeMs: () => number;\n  /** Get total duration in milliseconds. */\n  getDurationMs: () => number;\n  /** Whether playback is currently paused. */\n  isPaused: () => boolean;\n  /** Set playback speed multiplier. */\n  setPlaybackRate: (rate: number) => void;\n  /**\n   * The underlying media element.\n   * Escape hatch for host integrations (e.g. thumbnail capture); prefer the\n   * typed methods above for playback control.\n   */\n  mediaElement: HTMLVideoElement | HTMLAudioElement | null;\n}\n\nexport interface MediaPlayerProps extends VariantProps<\n  typeof mediaPlayerVariants\n> {\n  /** Media source URL. */\n  src: string;\n  /** Force the media kind; when omitted it is inferred from the src extension. */\n  kind?: MediaKind;\n  /** Whether to show native controls (default `true`). */\n  controls?: boolean;\n  /** Callback when playback state changes. */\n  onStateChange?: (state: MediaPlayerState) => void;\n  /** Callback when playback ends. */\n  onEnded?: () => void;\n  /** Callback when an error occurs. */\n  onError?: (error: Error) => void;\n  /** Callback on time updates (milliseconds). */\n  onTimeUpdate?: (currentTimeMs: number, durationMs: number) => void;\n  /** Additional class name. */\n  className?: string;\n  /** Accessible label for the media element. */\n  'aria-label'?: string;\n  /**\n   * Transitional: exposes the raw media element to legacy consumers.\n   * Prefer {@link MediaPlayerRef} for playback control.\n   */\n  mediaElementRef?: React.RefObject<HTMLVideoElement | HTMLAudioElement | null>;\n}\n\n// ============================================================================\n// Variants\n// ============================================================================\n\nconst mediaPlayerVariants = cva(\n  'flex h-full w-full items-center justify-center',\n  {\n    variants: {\n      variant: {\n        plain: '',\n        card: 'rounded-xl border border-border bg-card text-card-foreground p-2',\n      },\n    },\n    defaultVariants: {\n      variant: 'plain',\n    },\n  }\n);\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nconst VIDEO_EXTENSIONS = /\\.(mp4|mov|avi|webm|mkv|m4v)$/i;\n\n/** Infer media kind from a URL's file extension; defaults to audio. */\nexport function inferMediaKind(src: string): MediaKind {\n  // Strip any query string / fragment before matching. Testing the extension\n  // against the full URL required a trailing `.*`, which backtracks\n  // polynomially on crafted inputs (ReDoS); splitting first is linear.\n  const path = src.split(/[?#]/, 1)[0];\n  return VIDEO_EXTENSIONS.test(path) ? 'video' : 'audio';\n}\n\n// ============================================================================\n// Component\n// ============================================================================\n\n/**\n * Media playback surface for audio and video with a shared imperative handle.\n *\n * Renders a native `<video>` or `<audio>` element (kind inferred from the src\n * extension unless forced) with themed error/retry handling. Playback state and\n * controls come from the shared {@link useMediaTransport} hook and are exposed\n * through {@link MediaPlayerRef} (all times in milliseconds) — consumers should\n * not reach into the DOM element directly.\n */\nexport const MediaPlayer = React.forwardRef<MediaPlayerRef, MediaPlayerProps>(\n  (\n    {\n      src,\n      kind,\n      controls = true,\n      variant,\n      onStateChange,\n      onEnded,\n      onError,\n      onTimeUpdate,\n      className,\n      'aria-label': ariaLabel,\n      mediaElementRef,\n    },\n    ref\n  ) => {\n    const [error, setError] = React.useState<string | null>(null);\n\n    // A failed load must not outlive its src: clearing on change lets a host\n    // swap in a corrected URL without being trapped on the error surface\n    // (which unmounts the media element, so the new src would never load).\n    React.useEffect(() => {\n      setError(null);\n    }, [src]);\n    const resolvedKind = kind ?? inferMediaKind(src);\n\n    const transport = useMediaTransport({\n      onTimeUpdate,\n      onStateChange,\n      onEnded,\n      onError: (err) => {\n        setError('Unable to load media. The server may be unavailable.');\n        onError?.(err);\n      },\n      endedState: 'paused',\n      errorLabel: `media: ${src}`,\n    });\n\n    const { setMediaElement, mediaElement } = transport;\n\n    const setElement = React.useCallback(\n      (el: HTMLVideoElement | HTMLAudioElement | null) => {\n        setMediaElement(el);\n        if (mediaElementRef) {\n          (mediaElementRef as React.MutableRefObject<typeof el>).current = el;\n        }\n      },\n      [setMediaElement, mediaElementRef]\n    );\n\n    React.useImperativeHandle(\n      ref,\n      (): MediaPlayerRef => ({\n        seekToMs: transport.seekToMs,\n        play: transport.play,\n        pause: transport.pause,\n        getCurrentTimeMs: transport.getCurrentTimeMs,\n        getDurationMs: transport.getDurationMs,\n        isPaused: transport.isPaused,\n        setPlaybackRate: transport.setPlaybackRate,\n        get mediaElement() {\n          return mediaElement;\n        },\n      }),\n      [transport, mediaElement]\n    );\n\n    const handleRetry = React.useCallback(() => {\n      setError(null);\n      mediaElement?.load();\n    }, [mediaElement]);\n\n    const sharedMediaProps = {\n      src,\n      controls,\n      'aria-label': ariaLabel,\n    };\n\n    if (error) {\n      return (\n        <div className={mediaPlayerVariants({ variant, className })}>\n          <div\n            role=\"alert\"\n            className=\"border-destructive/30 bg-destructive/10 flex min-h-36 flex-col items-center justify-center gap-3 rounded-lg border p-8 text-center\"\n          >\n            {/* destructive-700/300 instead of the base token: #dc2626 on the\n                destructive/10 tint is 4.14:1 — below WCAG AA (axe: color-contrast). */}\n            <p className=\"text-destructive-700 dark:text-destructive-300 m-0 text-sm\">\n              {error}\n            </p>\n            {/* bg-background: the outline button is transparent, and its text on\n                the destructive/10 tint sits exactly at the 4.5:1 AA boundary. */}\n            <Button\n              variant=\"outline\"\n              size=\"sm\"\n              className=\"bg-background\"\n              onClick={handleRetry}\n            >\n              Retry\n            </Button>\n          </div>\n        </div>\n      );\n    }\n\n    return (\n      <div className={mediaPlayerVariants({ variant, className })}>\n        {resolvedKind === 'video' ? (\n          // Generic media surface: caption tracks belong to the consumer's media\n          // resource and are supplied via children, not this transport component.\n          // eslint-disable-next-line jsx-a11y/media-has-caption\n          <video\n            ref={setElement as React.Ref<HTMLVideoElement>}\n            playsInline\n            className=\"h-auto max-h-full w-auto max-w-full object-contain\"\n            {...sharedMediaProps}\n          />\n        ) : (\n          // eslint-disable-next-line jsx-a11y/media-has-caption\n          <audio\n            ref={setElement as React.Ref<HTMLAudioElement>}\n            className=\"my-4 w-[90%] max-w-lg\"\n            {...sharedMediaProps}\n          />\n        )}\n      </div>\n    );\n  }\n);\n\nMediaPlayer.displayName = 'MediaPlayer';\n\nexport { mediaPlayerVariants };\n"]}
+{"version":3,"sources":["../src/components/MediaPlayer/MediaPlayer.tsx"],"names":["cva","React","useMediaTransport","jsx","jsxs","Button"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAM,mBAAA,GAAsBA,0BAAA;AAAA,EAC1B,gDAAA;AAAA,EACA;AAAA,IACE,QAAA,EAAU;AAAA,MACR,OAAA,EAAS;AAAA,QACP,KAAA,EAAO,EAAA;AAAA,QACP,IAAA,EAAM;AAAA;AACR,KACF;AAAA,IACA,eAAA,EAAiB;AAAA,MACf,OAAA,EAAS;AAAA;AACX;AAEJ;AAMA,IAAM,gBAAA,GAAmB,gCAAA;AAGlB,SAAS,eAAe,GAAA,EAAwB;AAIrD,EAAA,MAAM,OAAO,GAAA,CAAI,KAAA,CAAM,MAAA,EAAQ,CAAC,EAAE,CAAC,CAAA;AACnC,EAAA,OAAO,gBAAA,CAAiB,IAAA,CAAK,IAAI,CAAA,GAAI,OAAA,GAAU,OAAA;AACjD;AAeO,IAAM,WAAA,GAAoBC,gBAAA,CAAA,UAAA;AAAA,EAC/B,CACE;AAAA,IACE,GAAA;AAAA,IACA,IAAA;AAAA,IACA,QAAA,GAAW,IAAA;AAAA,IACX,OAAA;AAAA,IACA,aAAA;AAAA,IACA,OAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA;AAAA,IACA,SAAA;AAAA,IACA,YAAA,EAAc,SAAA;AAAA,IACd;AAAA,KAEF,GAAA,KACG;AACH,IAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAUA,0BAAwB,IAAI,CAAA;AAK5D,IAAMA,2BAAU,MAAM;AACpB,MAAA,QAAA,CAAS,IAAI,CAAA;AAAA,IACf,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AACR,IAAA,MAAM,YAAA,GAAe,IAAA,IAAQ,cAAA,CAAe,GAAG,CAAA;AAE/C,IAAA,MAAM,YAAYC,mCAAA,CAAkB;AAAA,MAClC,YAAA;AAAA,MACA,aAAA;AAAA,MACA,OAAA;AAAA,MACA,OAAA,EAAS,CAAC,GAAA,KAAQ;AAChB,QAAA,QAAA,CAAS,sDAAsD,CAAA;AAC/D,QAAA,OAAA,GAAU,GAAG,CAAA;AAAA,MACf,CAAA;AAAA,MACA,UAAA,EAAY,QAAA;AAAA,MACZ,UAAA,EAAY,UAAU,GAAG,CAAA;AAAA,KAC1B,CAAA;AAED,IAAA,MAAM,EAAE,eAAA,EAAiB,YAAA,EAAa,GAAI,SAAA;AAE1C,IAAA,MAAM,UAAA,GAAmBD,gBAAA,CAAA,WAAA;AAAA,MACvB,CAAC,EAAA,KAAmD;AAClD,QAAA,eAAA,CAAgB,EAAE,CAAA;AAClB,QAAA,IAAI,eAAA,EAAiB;AACnB,UAAC,gBAAsD,OAAA,GAAU,EAAA;AAAA,QACnE;AAAA,MACF,CAAA;AAAA,MACA,CAAC,iBAAiB,eAAe;AAAA,KACnC;AAEA,IAAMA,gBAAA,CAAA,mBAAA;AAAA,MACJ,GAAA;AAAA,MACA,OAAuB;AAAA,QACrB,UAAU,SAAA,CAAU,QAAA;AAAA,QACpB,MAAM,SAAA,CAAU,IAAA;AAAA,QAChB,OAAO,SAAA,CAAU,KAAA;AAAA,QACjB,kBAAkB,SAAA,CAAU,gBAAA;AAAA,QAC5B,eAAe,SAAA,CAAU,aAAA;AAAA,QACzB,UAAU,SAAA,CAAU,QAAA;AAAA,QACpB,iBAAiB,SAAA,CAAU,eAAA;AAAA,QAC3B,IAAI,YAAA,GAAe;AACjB,UAAA,OAAO,YAAA;AAAA,QACT;AAAA,OACF,CAAA;AAAA,MACA,CAAC,WAAW,YAAY;AAAA,KAC1B;AAEA,IAAA,MAAM,WAAA,GAAoBA,6BAAY,MAAM;AAC1C,MAAA,QAAA,CAAS,IAAI,CAAA;AACb,MAAA,YAAA,EAAc,IAAA,EAAK;AAAA,IACrB,CAAA,EAAG,CAAC,YAAY,CAAC,CAAA;AAEjB,IAAA,MAAM,gBAAA,GAAmB;AAAA,MACvB,GAAA;AAAA,MACA,QAAA;AAAA,MACA,YAAA,EAAc;AAAA,KAChB;AAEA,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,uBACEE,cAAA,CAAC,SAAI,SAAA,EAAW,mBAAA,CAAoB,EAAE,OAAA,EAAS,SAAA,EAAW,CAAA,EACxD,QAAA,kBAAAC,eAAA;AAAA,QAAC,KAAA;AAAA,QAAA;AAAA,UACC,IAAA,EAAK,OAAA;AAAA,UACL,SAAA,EAAU,oIAAA;AAAA,UAIV,QAAA,EAAA;AAAA,4BAAAD,cAAA,CAAC,GAAA,EAAA,EAAE,SAAA,EAAU,4DAAA,EACV,QAAA,EAAA,KAAA,EACH,CAAA;AAAA,4BAGAA,cAAA;AAAA,cAACE,wBAAA;AAAA,cAAA;AAAA,gBACC,OAAA,EAAQ,SAAA;AAAA,gBACR,IAAA,EAAK,IAAA;AAAA,gBACL,SAAA,EAAU,eAAA;AAAA,gBACV,OAAA,EAAS,WAAA;AAAA,gBACV,QAAA,EAAA;AAAA;AAAA;AAED;AAAA;AAAA,OACF,EACF,CAAA;AAAA,IAEJ;AAEA,IAAA,uBACEF,cAAA,CAAC,SAAI,SAAA,EAAW,mBAAA,CAAoB,EAAE,OAAA,EAAS,SAAA,EAAW,CAAA,EACvD,QAAA,EAAA,YAAA,KAAiB,OAAA;AAAA;AAAA;AAAA;AAAA,sBAIhBA,cAAA;AAAA,QAAC,OAAA;AAAA,QAAA;AAAA,UACC,GAAA,EAAK,UAAA;AAAA,UACL,WAAA,EAAW,IAAA;AAAA,UACX,SAAA,EAAU,oDAAA;AAAA,UACT,GAAG;AAAA;AAAA;AACN;AAAA;AAAA,sBAGAA,cAAA;AAAA,QAAC,OAAA;AAAA,QAAA;AAAA,UACC,GAAA,EAAK,UAAA;AAAA,UACL,SAAA,EAAU,uBAAA;AAAA,UACT,GAAG;AAAA;AAAA;AACN,KAAA,EAEJ,CAAA;AAAA,EAEJ;AACF;AAEA,WAAA,CAAY,WAAA,GAAc,aAAA","file":"chunk-VLBUT2QM.cjs","sourcesContent":["import * as React from 'react';\nimport { cva, type VariantProps } from 'class-variance-authority';\n\nimport { Button } from '../Button';\nimport { useMediaTransport } from '../../hooks/useMediaTransport';\n\n// ============================================================================\n// Types & Interfaces\n// ============================================================================\n\nexport type MediaPlayerState =\n  | 'idle'\n  | 'loading'\n  | 'playing'\n  | 'paused'\n  | 'error';\n\nexport type MediaKind = 'video' | 'audio';\n\n/** Ref handle for controlling {@link MediaPlayer} programmatically. */\nexport interface MediaPlayerRef {\n  /** Seek to a specific time in milliseconds. */\n  seekToMs: (timeMs: number) => void;\n  /** Start playback. */\n  play: () => void;\n  /** Pause playback. */\n  pause: () => void;\n  /** Get current playback time in milliseconds. */\n  getCurrentTimeMs: () => number;\n  /** Get total duration in milliseconds. */\n  getDurationMs: () => number;\n  /** Whether playback is currently paused. */\n  isPaused: () => boolean;\n  /** Set playback speed multiplier. */\n  setPlaybackRate: (rate: number) => void;\n  /**\n   * The underlying media element.\n   * Escape hatch for host integrations (e.g. thumbnail capture); prefer the\n   * typed methods above for playback control.\n   */\n  mediaElement: HTMLVideoElement | HTMLAudioElement | null;\n}\n\nexport interface MediaPlayerProps extends VariantProps<\n  typeof mediaPlayerVariants\n> {\n  /** Media source URL. */\n  src: string;\n  /** Force the media kind; when omitted it is inferred from the src extension. */\n  kind?: MediaKind;\n  /** Whether to show native controls (default `true`). */\n  controls?: boolean;\n  /** Callback when playback state changes. */\n  onStateChange?: (state: MediaPlayerState) => void;\n  /** Callback when playback ends. */\n  onEnded?: () => void;\n  /** Callback when an error occurs. */\n  onError?: (error: Error) => void;\n  /** Callback on time updates (milliseconds). */\n  onTimeUpdate?: (currentTimeMs: number, durationMs: number) => void;\n  /** Additional class name. */\n  className?: string;\n  /** Accessible label for the media element. */\n  'aria-label'?: string;\n  /**\n   * Transitional: exposes the raw media element to legacy consumers.\n   * Prefer {@link MediaPlayerRef} for playback control.\n   */\n  mediaElementRef?: React.RefObject<HTMLVideoElement | HTMLAudioElement | null>;\n}\n\n// ============================================================================\n// Variants\n// ============================================================================\n\nconst mediaPlayerVariants = cva(\n  'flex h-full w-full items-center justify-center',\n  {\n    variants: {\n      variant: {\n        plain: '',\n        card: 'rounded-xl border border-border bg-card text-card-foreground p-2',\n      },\n    },\n    defaultVariants: {\n      variant: 'plain',\n    },\n  }\n);\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nconst VIDEO_EXTENSIONS = /\\.(mp4|mov|avi|webm|mkv|m4v)$/i;\n\n/** Infer media kind from a URL's file extension; defaults to audio. */\nexport function inferMediaKind(src: string): MediaKind {\n  // Strip any query string / fragment before matching. Testing the extension\n  // against the full URL required a trailing `.*`, which backtracks\n  // polynomially on crafted inputs (ReDoS); splitting first is linear.\n  const path = src.split(/[?#]/, 1)[0];\n  return VIDEO_EXTENSIONS.test(path) ? 'video' : 'audio';\n}\n\n// ============================================================================\n// Component\n// ============================================================================\n\n/**\n * Media playback surface for audio and video with a shared imperative handle.\n *\n * Renders a native `<video>` or `<audio>` element (kind inferred from the src\n * extension unless forced) with themed error/retry handling. Playback state and\n * controls come from the shared {@link useMediaTransport} hook and are exposed\n * through {@link MediaPlayerRef} (all times in milliseconds) — consumers should\n * not reach into the DOM element directly.\n */\nexport const MediaPlayer = React.forwardRef<MediaPlayerRef, MediaPlayerProps>(\n  (\n    {\n      src,\n      kind,\n      controls = true,\n      variant,\n      onStateChange,\n      onEnded,\n      onError,\n      onTimeUpdate,\n      className,\n      'aria-label': ariaLabel,\n      mediaElementRef,\n    },\n    ref\n  ) => {\n    const [error, setError] = React.useState<string | null>(null);\n\n    // A failed load must not outlive its src: clearing on change lets a host\n    // swap in a corrected URL without being trapped on the error surface\n    // (which unmounts the media element, so the new src would never load).\n    React.useEffect(() => {\n      setError(null);\n    }, [src]);\n    const resolvedKind = kind ?? inferMediaKind(src);\n\n    const transport = useMediaTransport({\n      onTimeUpdate,\n      onStateChange,\n      onEnded,\n      onError: (err) => {\n        setError('Unable to load media. The server may be unavailable.');\n        onError?.(err);\n      },\n      endedState: 'paused',\n      errorLabel: `media: ${src}`,\n    });\n\n    const { setMediaElement, mediaElement } = transport;\n\n    const setElement = React.useCallback(\n      (el: HTMLVideoElement | HTMLAudioElement | null) => {\n        setMediaElement(el);\n        if (mediaElementRef) {\n          (mediaElementRef as React.MutableRefObject<typeof el>).current = el;\n        }\n      },\n      [setMediaElement, mediaElementRef]\n    );\n\n    React.useImperativeHandle(\n      ref,\n      (): MediaPlayerRef => ({\n        seekToMs: transport.seekToMs,\n        play: transport.play,\n        pause: transport.pause,\n        getCurrentTimeMs: transport.getCurrentTimeMs,\n        getDurationMs: transport.getDurationMs,\n        isPaused: transport.isPaused,\n        setPlaybackRate: transport.setPlaybackRate,\n        get mediaElement() {\n          return mediaElement;\n        },\n      }),\n      [transport, mediaElement]\n    );\n\n    const handleRetry = React.useCallback(() => {\n      setError(null);\n      mediaElement?.load();\n    }, [mediaElement]);\n\n    const sharedMediaProps = {\n      src,\n      controls,\n      'aria-label': ariaLabel,\n    };\n\n    if (error) {\n      return (\n        <div className={mediaPlayerVariants({ variant, className })}>\n          <div\n            role=\"alert\"\n            className=\"border-destructive/30 bg-destructive/10 flex min-h-36 flex-col items-center justify-center gap-3 rounded-lg border p-8 text-center\"\n          >\n            {/* destructive-700/300 instead of the base token: #dc2626 on the\n                destructive/10 tint is 4.14:1 — below WCAG AA (axe: color-contrast). */}\n            <p className=\"text-destructive-700 dark:text-destructive-300 m-0 text-sm\">\n              {error}\n            </p>\n            {/* bg-background: the outline button is transparent, and its text on\n                the destructive/10 tint sits exactly at the 4.5:1 AA boundary. */}\n            <Button\n              variant=\"outline\"\n              size=\"sm\"\n              className=\"bg-background\"\n              onClick={handleRetry}\n            >\n              Retry\n            </Button>\n          </div>\n        </div>\n      );\n    }\n\n    return (\n      <div className={mediaPlayerVariants({ variant, className })}>\n        {resolvedKind === 'video' ? (\n          // Generic media surface: caption tracks belong to the consumer's media\n          // resource and are supplied via children, not this transport component.\n          // eslint-disable-next-line jsx-a11y/media-has-caption\n          <video\n            ref={setElement as React.Ref<HTMLVideoElement>}\n            playsInline\n            className=\"h-auto max-h-full w-auto max-w-full object-contain\"\n            {...sharedMediaProps}\n          />\n        ) : (\n          // eslint-disable-next-line jsx-a11y/media-has-caption\n          <audio\n            ref={setElement as React.Ref<HTMLAudioElement>}\n            className=\"my-4 w-[90%] max-w-lg\"\n            {...sharedMediaProps}\n          />\n        )}\n      </div>\n    );\n  }\n);\n\nMediaPlayer.displayName = 'MediaPlayer';\n\nexport { mediaPlayerVariants };\n"]}