@internetarchive/collection-browser 3.3.2 → 3.3.3

package/dist/src/models.d.ts

@@ -0,0 +1,302 @@
+import type { TemplateResult } from 'lit';
+import type { MediaType } from '@internetarchive/field-parsers';
+import { AggregationSortType, HitType, SearchReview, SearchResult, SortDirection } from '@internetarchive/search-service';
+/**
+ * Different types of tile overlays, corresponding to the above flags.
+ */
+export type TileOverlayType = 'login-required' | 'content-warning';
+export declare const TILE_OVERLAY_TEXT: Record<TileOverlayType, string>;
+export declare const TILE_OVERLAY_ICONS: Record<TileOverlayType, TemplateResult>;
+/**
+ * What type of request produced a given set of hits:
+ *  - `search_query`: Hits produced by an explicit user query and/or applied filters on any page
+ *  - `collection_members`: Hits produced for a collection page without any query or filters
+ *  - `profile_tab`: Hits produced for a tab of the profile page without any query or filters
+ *  - `unknown`: Hits produced via any other means
+ */
+export type HitRequestSource = 'search_query' | 'collection_members' | 'profile_tab' | 'unknown';
+/**
+ * Class for converting & storing raw search results in the correct format for UI tiles.
+ */
+export declare class TileModel {
+    /** For TV hits. List of identifiers for any commercials contained. */
+    adIds?: string[];
+    averageRating?: number;
+    /** For Web Archive hits on profile pages. List of capture dates for the current URL. */
+    captureDates?: Date[];
+    /** Whether this tile is currently checked for item management functions */
+    checked: boolean;
+    collectionIdentifier?: string;
+    collectionName?: string;
+    collectionFilesCount: number;
+    collections: string[];
+    collectionSize: number;
+    commentCount: number;
+    creator?: string;
+    creators: string[];
+    /** A string representation of the publication date, used strictly for passing preformatted dates to the parent */
+    dateStr?: string;
+    /** Date added to public search (software-defined) [from MD field: addeddate] */
+    dateAdded?: Date;
+    /** Date archived (software-defined) item created on archive.org [from MD field: publicdate] */
+    dateArchived?: Date;
+    /** Date work published in the world (user-defined) [from MD field: date] */
+    datePublished?: Date;
+    /** Date reviewed (user-created) most recent review [from MD field: reviewdate] */
+    dateReviewed?: Date;
+    description?: string;
+    /** For TV hits. List of URLs for any fact-checks of the contained clips. */
+    factChecks?: string[];
+    favCount: number;
+    hitRequestSource: HitRequestSource;
+    hitType?: HitType;
+    href?: string;
+    identifier?: string;
+    /** Whether this model represents a TV clip */
+    isClip?: boolean;
+    issue?: string;
+    itemCount: number;
+    mediatype: MediaType;
+    review?: SearchReview;
+    source?: string;
+    snippets?: string[];
+    subjects: string[];
+    thumbnailUrl?: string;
+    title: string;
+    tvClipCount?: number;
+    viewCount?: number;
+    volume?: string;
+    weeklyViewCount?: number;
+    loginRequired: boolean;
+    contentWarning: boolean;
+    constructor(result: SearchResult, hitRequestSource?: HitRequestSource);
+    /**
+     * Copies the contents of this TileModel onto a new instance
+     */
+    clone(): TileModel;
+    /**
+     * Whether this model represents the result of a TV search query.
+     */
+    get isTvSearchResult(): boolean;
+    /**
+     * Determines the appropriate tile flags for the given search result
+     * (login required and/or content warning)
+     */
+    private getFlags;
+    private static cleanIdentifier;
+}
+export type RequestKind = 'full' | 'hits' | 'aggregations';
+export type CollectionDisplayMode = 'grid' | 'list-compact' | 'list-detail';
+export type TileDisplayMode = 'grid' | 'list-compact' | 'list-detail' | 'list-header';
+/**
+ * This is mainly used to set the cookies for the collection display mode.
+ *
+ * It allows the user to set different modes for different contexts (collection page, search page, profile page etc).
+ */
+export type CollectionBrowserContext = 'collection' | 'search' | 'profile';
+/**
+ * The sort fields shown in the sort filter bar
+ */
+export declare enum SortField {
+    'default' = "default",
+    'unrecognized' = "unrecognized",
+    'relevance' = "relevance",
+    'alltimeview' = "alltimeview",
+    'weeklyview' = "weeklyview",
+    'title' = "title",
+    'date' = "date",
+    'datearchived' = "datearchived",
+    'datereviewed' = "datereviewed",
+    'dateadded' = "dateadded",
+    'datefavorited' = "datefavorited",
+    'creator' = "creator"
+}
+/**
+ * Views-related sort fields
+ */
+export declare const ALL_VIEWS_SORT_FIELDS: readonly [SortField.weeklyview, SortField.alltimeview];
+export type ViewsSortField = (typeof ALL_VIEWS_SORT_FIELDS)[number];
+/**
+ * Date-related sort fields
+ */
+export declare const ALL_DATE_SORT_FIELDS: readonly [SortField.datefavorited, SortField.date, SortField.datearchived, SortField.datereviewed, SortField.dateadded];
+export type DateSortField = (typeof ALL_DATE_SORT_FIELDS)[number];
+export interface SortOption {
+    /**
+     * The SortField enum member corresponding to this option.
+     */
+    field: SortField;
+    /**
+     * The default sort direction to apply when this sort option is first selected.
+     */
+    defaultSortDirection: SortDirection | null;
+    /**
+     * Whether this sort option allows its sort direction to be changed from the default.
+     */
+    canSetDirection: boolean;
+    /**
+     * Whether this sort option may appear in the sort bar.
+     */
+    shownInSortBar: boolean;
+    /**
+     * Whether this sort option should be saved to the URL.
+     * If false, then no `sort` param will be added to the URL when this sort option
+     * is selected.
+     */
+    shownInURL: boolean;
+    /**
+     * Whether this sort option is passed to the search service.
+     * If false, then no sort param will be passed to the search service at all when
+     * this sort option is selected.
+     */
+    handledBySearchService: boolean;
+    /**
+     * The string identifying this sort field to the search service & backend API.
+     */
+    searchServiceKey?: string;
+    /**
+     * The human-readable name to use for this option in the sort bar (if applicable).
+     */
+    displayName: string;
+    /**
+     * A list of URL param keys that should be mapped to this sort option.
+     * E.g., both `title` and `titleSorter` in the URL map to the `SortField.title` option.
+     */
+    urlNames: (string | null | undefined)[];
+}
+export declare const SORT_OPTIONS: Record<SortField, SortOption>;
+/**
+ * Returns the SortOption corresponding to the given API sort name, or
+ * the "unrecognized" SortOption if none matches.
+ */
+export declare function sortOptionFromAPIString(sortName?: string | null): SortOption;
+export declare const defaultSortAvailability: Record<SortField, boolean>;
+export declare const favoritesSortAvailability: Record<SortField, boolean>;
+export declare const tvSortAvailability: Record<SortField, boolean>;
+export declare const defaultProfileElementSorts: Record<string, Exclude<SortField, SortField.default>>;
+/** A union of the fields that permit prefix filtering (e.g., alphabetical filtering) */
+export type PrefixFilterType = 'title' | 'creator';
+/** A map from prefixes (e.g., initial letters) to the number of items matching that prefix */
+export type PrefixFilterCounts = Record<string, number>;
+/**
+ * A map from prefix filter types to the corresponding aggregation keys
+ * that are needed to fetch the filter counts from the backend.
+ */
+export declare const prefixFilterAggregationKeys: Record<PrefixFilterType, string>;
+/**
+ * Different facet loading strategies that can be used with collection browser.
+ *  - `eager`: Facet data is always loaded as soon as a search is performed
+ *  - `lazy-mobile`: In the desktop layout, functions exactly as `eager`.
+ *     In the mobile layout, facet data will only be loaded once the "Filters" accordion is opened.
+ *  - `opt-in-or-login`: Same as `opt-in` for guest users not logged into an account, but same as `eager` for
+ *     any logged in user.
+ *  - `opt-in`: In the desktop layout, facet data will only be loaded after the user presses a "Load Facets" button.
+ *     In the mobile layout, functions exactly as `lazy-mobile`.
+ *  - `off`: Facet data will never be loaded, and a message will be displayed in place of facets
+ *     indicating that they are unavailable.
+ */
+export type FacetLoadStrategy = 'eager' | 'lazy-mobile' | 'opt-in-or-login' | 'opt-in' | 'off';
+/**
+ * Union of the facet types that are available in the sidebar.
+ */
+export type FacetOption = 'subject' | 'lending' | 'mediatype' | 'language' | 'creator' | 'collection' | 'year' | 'program' | 'person' | 'sponsor';
+export type SelectedFacetState = 'selected' | 'hidden';
+export type FacetState = SelectedFacetState | 'none';
+export interface FacetBucket {
+    key: string;
+    count: number;
+    state: FacetState;
+    displayText?: string;
+    extraNote?: string;
+}
+export interface FacetGroup {
+    title: string;
+    key: FacetOption;
+    buckets: FacetBucket[];
+}
+/**
+ * Information about a user interaction event on a facet.
+ */
+export type FacetEventDetails = {
+    /**
+     * The type of facet that was interacted with (e.g., 'mediatype', 'language', ...).
+     */
+    facetType: FacetOption;
+    /**
+     * The bucket corresponding to the facet that was interacted with, including the
+     * updated state of the facet after the interaction.
+     */
+    bucket: FacetBucket;
+    /**
+     * Whether the interaction occurred on a negative facet.
+     */
+    negative: boolean;
+};
+export type FacetValue = string;
+export type SelectedFacets = Partial<Record<FacetOption, Record<FacetValue, FacetBucket>>>;
+export declare const getDefaultSelectedFacets: () => Required<SelectedFacets>;
+/**
+ * For TV search results, what types of TV clips to restrict the results to.
+ */
+export type TvClipFilterType = 'all' | 'commercials' | 'factchecks' | 'quotes';
+/**
+ * Map from TV clip filter types to their corresponding URL params
+ */
+export declare const tvClipFiltersToURLParams: Record<TvClipFilterType, string>;
+/**
+ * Map from allowed TV filtering parameters in the URL to their corresponding filter type
+ */
+export declare const tvClipURLParamsToFilters: Record<string, TvClipFilterType>;
+/**
+ * Facet display order when presenting results for all search types *except* TV (see below).
+ */
+export declare const defaultFacetDisplayOrder: FacetOption[];
+/**
+ * Specialized facet ordering when displaying TV search results
+ */
+export declare const tvFacetDisplayOrder: FacetOption[];
+/**
+ * Human-readable titles for each facet group.
+ */
+export declare const facetTitles: Record<FacetOption, string>;
+/**
+ * The default sort type to use for each facet type
+ */
+export declare const defaultFacetSort: Record<FacetOption, AggregationSortType>;
+/**
+ * The sort type corresponding to facet bucket values, for each facet type
+ * (i.e., the opposite of "sort by count" for that type).
+ */
+export declare const valueFacetSort: Record<FacetOption, AggregationSortType>;
+export type LendingFacetKey = 'is_lendable' | 'is_borrowable' | 'available_to_borrow' | 'is_browsable' | 'available_to_browse' | 'is_readable' | 'available_to_waitlist';
+/**
+ * Maps valid lending keys to whether they should be visible in the facet sidebar
+ */
+export declare const lendingFacetKeysVisibility: Record<LendingFacetKey, boolean>;
+/**
+ * Maps valid, visible lending keys to their facet sidebar display text
+ */
+export declare const lendingFacetDisplayNames: Partial<Record<LendingFacetKey, string>>;
+/**
+ * A record of which admin-only collections should be suppressed from being displayed
+ * as facets or in an item's list of collections.
+ */
+export declare const suppressedCollections: Record<string, boolean>;
+/**
+ * A record of manageable item
+ */
+export interface ManageableItem {
+    identifier: string;
+    title?: string;
+    dateStr?: string;
+    date?: string;
+}
+/**
+ * Possible states for whether & how the user has overridden their user preference
+ * for blurring behavior on tiles with sensitive content.
+ *  - `no-override`: The user has not overridden their user preference, so simply
+ *    respect the preference as given.
+ *  - `on`: The user has overridden their preference and wants tile blurring enabled.
+ *  - `off`: The user has overridden their preference and wants tile blurring disabled.
+ */
+export type TileBlurOverrideState = 'no-override' | 'on' | 'off';