Break apart view.ts into multiple files.

src/view/media-classifier.ts

@@ -0,0 +1,53 @@
+import { ModifyInterface } from '../utils/basic.js';
+import { ViewMedia, FrigateEventViewMedia, FrigateRecordingViewMedia } from './media';
+
+export class ViewMediaClassifier {
+  public static isFrigateMedia(
+    media: ViewMedia,
+  ): media is FrigateEventViewMedia | FrigateRecordingViewMedia {
+    return this.isFrigateEvent(media) || this.isFrigateRecording(media);
+  }
+  public static isFrigateEvent(media: ViewMedia): media is FrigateEventViewMedia {
+    return media instanceof FrigateEventViewMedia;
+  }
+  public static isFrigateRecording(
+    media: ViewMedia,
+  ): media is FrigateRecordingViewMedia {
+    return media instanceof FrigateRecordingViewMedia;
+  }
+
+  // Typescript conveniences.
+  public static isMediaWithStartEndTime(media: ViewMedia): media is ModifyInterface<
+    ViewMedia,
+    {
+      getStartTime(): Date;
+      getEndTime(): Date;
+    }
+  > {
+    return !!media.getStartTime() && !!media.getEndTime();
+  }
+  public static isMediaWithStartTime(media: ViewMedia): media is ModifyInterface<
+    ViewMedia,
+    {
+      getStartTime(): Date;
+    }
+  > {
+    return !!media.getStartTime();
+  }
+  public static isMediaWithEndTime(media: ViewMedia): media is ModifyInterface<
+    ViewMedia,
+    {
+      getEndTime(): Date;
+    }
+  > {
+    return !!media.getEndTime();
+  }
+  public static isMediaWithID(media: ViewMedia): media is ModifyInterface<
+    ViewMedia,
+    {
+      getID(): string;
+    }
+  > {
+    return !!media.getID();
+  }
+}

src/view/media-queries-classifier.ts

@@ -0,0 +1,15 @@
+import { EventMediaQueries, MediaQueries, RecordingMediaQueries } from './media-queries';
+
+export class MediaQueriesClassifier {
+  public static areEventQueries(
+    queries?: MediaQueries | null,
+  ): queries is EventMediaQueries {
+    return queries instanceof EventMediaQueries;
+  }
+
+  public static areRecordingQueries(
+    queries?: MediaQueries | null,
+  ): queries is RecordingMediaQueries {
+    return queries instanceof RecordingMediaQueries;
+  }
+}

src/view/media-queries-results.ts

@@ -0,0 +1,91 @@
+import clone from 'lodash-es/clone.js';
+import { ViewMedia } from './media.js';
+
+export class MediaQueriesResults {
+  protected _results: ViewMedia[] | null = null;
+  protected _resultsTimestamp: Date | null = null;
+  protected _selectedIndex: number | null = null;
+
+  constructor(results?: ViewMedia[], selectedIndex?: number | null) {
+    if (results) {
+      this.setResults(results);
+    }
+    if (selectedIndex !== undefined) {
+      this.selectResult(selectedIndex);
+    }
+  }
+
+  public clone(): MediaQueriesResults {
+    // Shallow clone -- will reuse the same _results object (as there are no
+    // methods that support modification of the results themselves, and since
+    // changing the selectedIndex on a consistent set of results is a common
+    // operation).
+    return clone(this);
+  }
+
+  public getResults(): ViewMedia[] | null {
+    return this._results;
+  }
+  public getResultsCount(): number {
+    return this._results?.length ?? 0;
+  }
+  public hasResults(): boolean {
+    return !!this._results;
+  }
+  public setResults(results: ViewMedia[]) {
+    this._results = results;
+    this._resultsTimestamp = new Date();
+  }
+  public getResult(index?: number): ViewMedia | null {
+    if (!this._results || index === undefined) {
+      return null;
+    }
+    return this._results[index];
+  }
+  public getSelectedResult(): ViewMedia | null {
+    return this._selectedIndex === null ? null : this.getResult(this._selectedIndex);
+  }
+  public getSelectedIndex(): number | null {
+    return this._selectedIndex;
+  }
+  public hasSelectedResult(): boolean {
+    return this.getSelectedResult() !== null;
+  }
+  public resetSelectedResult(): MediaQueriesResults {
+    this._selectedIndex = null;
+    return this;
+  }
+  public getResultsTimestamp(): Date | null {
+    return this._resultsTimestamp;
+  }
+
+  public selectResult(index: number | null): MediaQueriesResults {
+    if (
+      index === null ||
+      (this._results && index >= 0 && index < this._results.length)
+    ) {
+      this._selectedIndex = index;
+    }
+    return this;
+  }
+  public selectResultIfFound(func: (media: ViewMedia) => boolean): MediaQueriesResults {
+    for (const [index, result] of this._results?.entries() ?? []) {
+      if (func(result)) {
+        this._selectedIndex = index;
+        break;
+      }
+    }
+    return this;
+  }
+  public selectBestResult(
+    func: (media: ViewMedia[]) => number | null,
+  ): MediaQueriesResults {
+    if (this._results) {
+      const resultIndex = func(this._results);
+      if (resultIndex !== null) {
+        this._selectedIndex = resultIndex;
+      }
+    }
+    return this;
+  }
+}

src/view/media-queries.ts

@@ -0,0 +1,61 @@
+import isEqual from 'lodash-es/isEqual';
+import cloneDeep from 'lodash-es/cloneDeep.js';
+import { EventQuery, MediaQuery, RecordingQuery } from '../camera/types.js';
+
+export type MediaQueries = EventMediaQueries | RecordingMediaQueries;
+
+export class MediaQueriesBase<T extends MediaQuery> {
+  protected _queries: T[] | null = null;
+
+  protected constructor(queries?: T[]) {
+    if (queries) {
+      this._queries = queries;
+    }
+  }
+
+  public clone(): MediaQueriesBase<T> {
+    return cloneDeep(this);
+  }
+
+  public isEqual(that: MediaQueries): boolean {
+    return isEqual(this.getQueries(), that.getQueries());
+  }
+
+  public getQueries(): T[] | null {
+    return this._queries;
+  }
+
+  public setQueries(queries: T[]): void {
+    this._queries = queries;
+  }
+
+  public setQueriesTime(start: Date, end: Date) {
+    for (const query of this._queries ?? []) {
+      query.start = start;
+      query.end = end;
+    }
+  }
+}
+
+export class EventMediaQueries extends MediaQueriesBase<EventQuery> {
+  constructor(queries?: EventQuery[]) {
+    super(queries);
+  }
+
+  public convertToClipsQueries(): void {
+    for (const query of this._queries ?? []) {
+      delete query.hasSnapshot;
+      query.hasClip = true;
+    }
+  }
+
+  public clone(): EventMediaQueries {
+    return cloneDeep(this);
+  }
+}
+
+export class RecordingMediaQueries extends MediaQueriesBase<RecordingQuery> {
+  constructor(queries?: RecordingQuery[]) {
+    super(queries);
+  }
+}

src/view/media.ts

@@ -0,0 +1,276 @@
+import fromUnixTime from 'date-fns/fromUnixTime';
+import isEqual from 'lodash-es/isEqual';
+import { BrowseMediaSource, CameraConfig, MEDIA_TYPE_IMAGE } from '../types.js';
+import {
+  getEventMediaContentID,
+  getEventThumbnailURL,
+  getEventTitle,
+  getRecordingMediaContentID,
+  getRecordingTitle,
+} from '../camera/frigate/util.js';
+import { FrigateEvent, FrigateRecording } from '../camera/frigate/types.js';
+
+export type ViewMediaType = 'clip' | 'snapshot' | 'recording';
+export type ViewMediaSourceType = FrigateEvent | FrigateRecording | BrowseMediaSource;
+
+class ViewMediaBase<T extends ViewMediaSourceType> {
+  protected _mediaType: ViewMediaType;
+  protected _cameraID: string;
+  protected _source: T;
+
+  constructor(mediaType: ViewMediaType, cameraID: string, source: T) {
+    this._mediaType = mediaType;
+    this._cameraID = cameraID;
+    this._source = source;
+  }
+
+  public isEvent(): boolean {
+    return this._mediaType === 'clip' || this._mediaType === 'snapshot';
+  }
+  public isRecording(): boolean {
+    return this._mediaType === 'recording';
+  }
+  public isClip(): boolean {
+    return this._mediaType === 'clip';
+  }
+  public isSnapshot(): boolean {
+    return this._mediaType === 'snapshot';
+  }
+  public getContentType(): 'image' | 'video' {
+    return this._mediaType === 'snapshot' ? 'image' : 'video';
+  }
+  public getCameraID(): string {
+    return this._cameraID;
+  }
+  public getMediaType(): ViewMediaType {
+    return this._mediaType;
+  }
+  public isVideo(): boolean {
+    return this.isClip() || this.isRecording();
+  }
+  public getSource(): T {
+    return this._source;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getID(_cameraConfig?: CameraConfig): string | null {
+    return null;
+  }
+  public getStartTime(): Date | null {
+    return null;
+  }
+  public getEndTime(): Date | null {
+    return null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getContentID(_cameraConfig?: CameraConfig): string | null {
+    return null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getTitle(_cameraConfig?: CameraConfig): string | null {
+    return null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getThumbnail(_cameraConfig?: CameraConfig): string | null {
+    return null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public isGroupableWith(that: ViewMedia): boolean {
+    return (
+      this.getMediaType() === that.getMediaType() &&
+      isEqual(this.getWhere(), that.getWhere()) &&
+      isEqual(this.getWhat(), that.getWhat())
+    );
+  }
+  public isFavorite(): boolean | null {
+    return null;
+  }
+
+  // Sets the favorite attribute (if any). This purely sets the media item as a
+  // favorite in JS.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public setFavorite(_favorite: boolean): void {
+    return;
+  }
+  public getWhat(): string[] | null {
+    return null;
+  }
+  public getWhere(): string[] | null {
+    return null;
+  }
+  public getScore(): number | null {
+    return null;
+  }
+  public getEventCount(): number | null {
+    return null;
+  }
+}
+
+// Creates a 'public interface only' version of ViewMediaBase for use elsewhere
+// (typescript struggles with the ViewMediaClassifier classification functions
+// used above if the object has data elements).
+export type ViewMedia = {
+  [P in keyof ViewMediaBase<ViewMediaSourceType>]: ViewMediaBase<ViewMediaSourceType>[P];
+};
+
+export class HomeAssistantBrowserViewMedia extends ViewMediaBase<BrowseMediaSource> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getID(_cameraConfig?: CameraConfig): string | null {
+    return this._source.media_content_id;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getContentID(_cameraConfig?: CameraConfig): string | null {
+    return this._source.media_content_id;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getTitle(_cameraConfig?: CameraConfig): string | null {
+    return this._source.title;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getThumbnail(_cameraConfig?: CameraConfig): string | null {
+    return this._source.thumbnail;
+  }
+}
+
+export class FrigateEventViewMedia extends ViewMediaBase<FrigateEvent> {
+  public hasClip(): boolean {
+    return !!this._source.has_clip;
+  }
+  public getClipEquivalent(): ViewMedia | null {
+    if (!this.hasClip()) {
+      return null;
+    }
+    return ViewMediaFactory.createViewMediaFromFrigateEvent(
+      'clip',
+      this._cameraID,
+      this._source,
+    );
+  }
+  public getStartTime(): Date {
+    return fromUnixTime(this._source.start_time);
+  }
+  public getEndTime(): Date | null {
+    return this._source.end_time ? fromUnixTime(this._source.end_time) : null;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getID(_cameraConfig?: CameraConfig): string {
+    return this._source.id;
+  }
+  public getContentID(cameraConfig?: CameraConfig): string | null {
+    if (
+      !cameraConfig ||
+      !cameraConfig.frigate.client_id ||
+      !cameraConfig.frigate.camera_name
+    ) {
+      return null;
+    }
+    return getEventMediaContentID(
+      cameraConfig.frigate.client_id,
+      cameraConfig.frigate.camera_name,
+      this._source,
+      this.isClip() ? 'clips' : 'snapshots',
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getTitle(_cameraConfig?: CameraConfig): string | null {
+    return getEventTitle(this._source);
+  }
+
+  public getThumbnail(cameraConfig?: CameraConfig): string | null {
+    if (cameraConfig?.frigate.client_id) {
+      return getEventThumbnailURL(cameraConfig.frigate.client_id, this._source);
+    }
+    return null;
+  }
+  public isFavorite(): boolean | null {
+    return this._source.retain_indefinitely ?? null;
+  }
+  public setFavorite(favorite: boolean): void {
+    this._source.retain_indefinitely = favorite;
+  }
+  public getWhat(): string[] | null {
+    return [this._source.label];
+  }
+  public getWhere(): string[] | null {
+    const zones = this._source.zones;
+    return zones.length ? zones : null;
+  }
+  public getScore(): number | null {
+    return this._source.top_score;
+  }
+}
+
+export class FrigateRecordingViewMedia extends ViewMediaBase<FrigateRecording> {
+  public getID(cameraConfig?: CameraConfig): string | null {
+    // ID name is derived from the real camera name (not CameraID) since the
+    // recordings for the same camera across multiple zones will be the same and
+    // can be dedup'd from this id.
+    if (cameraConfig) {
+      return `${cameraConfig.frigate?.client_id ?? ''}/${
+        cameraConfig.frigate.camera_name ?? ''
+      }/${this._source.start_time}/${this._source.end_time}}`;
+    }
+    return null;
+  }
+  public getStartTime(): Date {
+    return fromUnixTime(this._source.start_time);
+  }
+  public getEndTime(): Date {
+    return fromUnixTime(this._source.end_time);
+  }
+  public getContentID(cameraConfig?: CameraConfig): string | null {
+    if (
+      !cameraConfig ||
+      !cameraConfig.frigate.client_id ||
+      !cameraConfig.frigate.camera_name
+    ) {
+      return null;
+    }
+    return getRecordingMediaContentID(
+      cameraConfig.frigate.client_id,
+      cameraConfig.frigate.camera_name,
+      this._source,
+    );
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public getTitle(_cameraConfig?: CameraConfig): string | null {
+    return getRecordingTitle(this._source);
+  }
+  public getEventCount(): number {
+    return this._source.events;
+  }
+}
+
+export class ViewMediaFactory {
+  static createViewMediaFromFrigateEvent(
+    type: 'clip' | 'snapshot',
+    cameraID: string,
+    event: FrigateEvent,
+  ): ViewMedia | null {
+    if (
+      (type === 'clip' && event.has_clip) ||
+      (type === 'snapshot' && event.has_snapshot)
+    ) {
+      return new FrigateEventViewMedia(type, cameraID, event);
+    }
+    return null;
+  }
+
+  static createViewMediaFromFrigateRecording(
+    cameraID: string,
+    recording: FrigateRecording,
+  ): ViewMedia | null {
+    return new FrigateRecordingViewMedia('recording', cameraID, recording);
+  }
+
+  static createViewMediaFromBrowseMediaSource(
+    cameraID: string,
+    browseMedia: BrowseMediaSource,
+  ): ViewMedia | null {
+    return new HomeAssistantBrowserViewMedia(
+      browseMedia.media_content_type === MEDIA_TYPE_IMAGE ? 'snapshot' : 'clip',
+      cameraID,
+      browseMedia,
+    );
+  }
+}

src/view/view.ts

@@ -0,0 +1,231 @@
+// Easy:
+//  - TODO: Refactor thumbnailsControlSchema to all use the shortform for other thumbnail users beyond live.
+//  - TODO: limit param in recordings should do something
+//  - TODO: Should be able to set live media to 'all' and have it work.
+//  - TODO: Are there elements of ViewMedia (e.g. getEventCount) that should be moved into subclasses (e.g. a recording subclass).
+//  - TODO: In MediaQueriesBase, do we need to generic? Just have T be a MediaQuery?
+//  - TODO: In the viewer @click handlers should I use this.selected instead of calling carouselScrollPrevious()
+
+// Medium:
+//  - TODO: Callers of all async methods of data-engine need to catch errors.
+//  - TODO: Add garbage collecting of segments not present in the recording summaries anymore.
+//  - TODO: Do I need to dedup recordings? (i.e. multiple zones on same camera may need to be dedup'd somewhere before returning the view). The media getID() call may be useful for this.
+//  - TODO: Do a fresh media query in the viewer on snapshot click, since the first query may (e.g.) only have requested events with snapshots (which would miss an event with just a clip).
+//  - TODO: Move view/ stuff into a view directory.
+//  - TODO: Move frigate specific view-media under the camera manager.
+//  - TODO: ts-prune https://camchenry.com/blog/deleting-dead-code-in-typescript
+
+// Hard:
+//  - TODO: Implement dragging the timeline seeking forward in both Frigate recordings & events.
+//  - TODO: Implement gallery.
+//  - TODO: Remove FrigateBrowseMediaSource if not necessary (post-gallery).
+//  - TODO: In generateMediaViewerContext there is an assumption that recordings start/end on the hour, which is true for Frigate but that assumption should be in the engine.
+//  - TODO: What should the timeline do when an event is clicked on that is not in the queryResults (or if queryResults is empty)?
+//  - TODO: Should the timeline data source clear events (as it currently does) when the query changes?
+
+import { ViewContext } from 'view';
+import {
+  FrigateCardUserSpecifiedView,
+  FrigateCardView,
+  FRIGATE_CARD_VIEWS_USER_SPECIFIED,
+  FRIGATE_CARD_VIEW_DEFAULT,
+} from '../types.js';
+import { dispatchFrigateCardEvent } from '../utils/basic.js';
+import { MediaQueries } from './media-queries';
+import { MediaQueriesResults } from './media-queries-results';
+
+export interface ViewEvolveParameters {
+  view?: FrigateCardView;
+  camera?: string;
+  query?: MediaQueries | null;
+  queryResults?: MediaQueriesResults | null;
+  context?: ViewContext | null;
+}
+
+export interface ViewParameters extends ViewEvolveParameters {
+  view: FrigateCardView;
+  camera: string;
+}
+
+export class View {
+  public view: FrigateCardView;
+  public camera: string;
+  public query: MediaQueries | null;
+  public queryResults: MediaQueriesResults | null;
+  public context: ViewContext | null;
+
+  constructor(params: ViewParameters) {
+    this.view = params.view;
+    this.camera = params.camera;
+    this.query = params.query ?? null;
+    this.queryResults = params.queryResults ?? null;
+    this.context = params.context ?? null;
+  }
+
+  /**
+   * Selects the best view for a non-Frigate camera.
+   * @param view The wanted view.
+   * @returns The closest view supported by the non-Frigate camera.
+   */
+  public static selectBestViewForNonFrigateCameras(view: FrigateCardView) {
+    return ['timeline', 'image'].includes(view) ? view : FRIGATE_CARD_VIEW_DEFAULT;
+  }
+
+  /**
+   * Selects the best view for a user specified view.
+   * @param view The wanted view.
+   * @returns The closest view supported that is user changeable.
+   */
+  public static selectBestViewForUserSpecified(view: FrigateCardView) {
+    return FRIGATE_CARD_VIEWS_USER_SPECIFIED.includes(
+      view as FrigateCardUserSpecifiedView,
+    )
+      ? view
+      : FRIGATE_CARD_VIEW_DEFAULT;
+  }
+
+  /**
+   * Detect if a view change represents a major "media change" for the given
+   * view.
+   * @param prev The previous view.
+   * @param curr The current view.
+   * @returns True if the view change is a real media change.
+   */
+  public static isMediaChange(prev?: View, curr?: View): boolean {
+    return (
+      !prev ||
+      !curr ||
+      prev.view !== curr.view ||
+      prev.camera !== curr.camera ||
+      // When in the live view, the target contains the events that happened in
+      // the past -- not reflective of the actual live media viewer.
+      (curr.view !== 'live' &&
+        (prev.queryResults !== curr.queryResults ||
+          prev.queryResults?.getSelectedResult() !==
+            curr.queryResults?.getSelectedResult()))
+    );
+  }
+
+  /**
+   * Clone a view.
+   */
+  public clone(): View {
+    return new View({
+      view: this.view,
+      camera: this.camera,
+      query: this.query?.clone() ?? null,
+      queryResults: this.queryResults?.clone() ?? null,
+      // target: this.target,
+      // targetIndex: this.targetIndex,
+      // targetFingerprint: this.targetFingerprint,
+      context: this.context,
+    });
+  }
+
+  /**
+   * Evolve this view by changing parameters and returning a new view.
+   * @param params Parameters to change.
+   * @returns A new evolved view.
+   */
+  public evolve(params: ViewEvolveParameters): View {
+    return new View({
+      view: params.view !== undefined ? params.view : this.view,
+      camera: params.camera !== undefined ? params.camera : this.camera,
+      query: params.query !== undefined ? params.query : this.query?.clone() ?? null,
+      queryResults:
+        params.queryResults !== undefined
+          ? params.queryResults
+          : this.queryResults?.clone() ?? null,
+      context: params.context !== undefined ? params.context : this.context,
+    });
+  }
+
+  /**
+   * Merge view contexts.
+   * @param context The context to merge in.
+   * @returns This view.
+   */
+  public mergeInContext(context?: ViewContext): View {
+    this.context = { ...this.context, ...context };
+    return this;
+  }
+
+  /**
+   * Remove a context key.
+   * @param key The key to remove.
+   * @returns This view.
+   */
+  public removeContext(key: keyof ViewContext): View {
+    if (this.context) {
+      delete this.context[key];
+    }
+    return this;
+  }
+
+  /**
+   * Determine if current view matches a named view.
+   */
+  public is(name: string): boolean {
+    return this.view == name;
+  }
+
+  /**
+   * Determine if a view is a gallery.
+   */
+  public isGalleryView(): boolean {
+    return ['clips', 'snapshots', 'recordings'].includes(this.view);
+  }
+
+  /**
+   * Determine if a view is of a piece of media (including the media viewer,
+   * live view, image view -- anything that can create a MediaLoadedInfo event).
+   */
+  public isAnyMediaView(): boolean {
+    return this.isViewerView() || this.is('live') || this.is('image');
+  }
+
+  /**
+   * Determine if a view is for the media viewer.
+   */
+  public isViewerView(): boolean {
+    return ['clip', 'snapshot', 'media', 'recording'].includes(this.view);
+  }
+
+  /**
+   * Get the default media type for this view if available.
+   * @returns Whether the default media is `clips`, `snapshots`, `recordings` or unknown
+   * (`null`).
+   */
+  public getDefaultMediaType(): 'clips' | 'snapshots' | 'recordings' | null {
+    if (['clip', 'clips'].includes(this.view)) {
+      return 'clips';
+    }
+    if (['snapshot', 'snapshots'].includes(this.view)) {
+      return 'snapshots';
+    }
+    if (['recording', 'recordings'].includes(this.view)) {
+      return 'recordings';
+    }
+    return null;
+  }
+
+  /**
+   * Dispatch an event to request a view change.
+   * @param target The target dispatching the event.
+   */
+  public dispatchChangeEvent(target: EventTarget): void {
+    dispatchFrigateCardEvent(target, 'view:change', this);
+  }
+}
+
+/**
+ * Dispatch an event to change the view context.
+ * @param target The EventTarget to send the event from.
+ * @param context The context to change.
+ */
+export const dispatchViewContextChangeEvent = (
+  target: EventTarget,
+  context: ViewContext,
+): void => {
+  dispatchFrigateCardEvent(target, 'view:change-context', context);
+};