@smartsoft001-mobilems/objects-shell-angular 2.125.0 → 2.126.0

package/types/smartsoft001-mobilems-objects-shell-angular.d.ts

@@ -1,10 +1,10 @@
 import * as i0 from '@angular/core';
-import { TemplateRef, ModuleWithProviders, Signal, AfterViewInit, WritableSignal } from '@angular/core';
+import { TemplateRef, ModuleWithProviders, Signal, AfterViewInit, WritableSignal, OnInit, ResourceRef } from '@angular/core';
 import * as _smartsoft001_crud_shell_angular from '@smartsoft001/crud-shell-angular';
 import { ICrudModuleOptionsWithoutRoutng, CrudFacade, State as State$1, CrudListPageBaseComponent, CrudItemPageBaseComponent, CrudService, ICrudFilter } from '@smartsoft001/crud-shell-angular';
 import { IEntity } from '@smartsoft001/domain-core';
 import * as i1$1 from '@smartsoft001-mobilems/angular';
-import { FiltersBaseComponent, CrudBaseService, SeoService, TranslationService, ICatalogOptions, ICatalog } from '@smartsoft001-mobilems/angular';
+import { FiltersBaseComponent, CrudBaseService, SeoService, TranslationService, IDictionaryPage, ICatalogOptions, ICatalog, ISeoMetadata, INamedEntrySource, INamedEntryParts } from '@smartsoft001-mobilems/angular';
 import * as i1 from '@angular/common';
 import { MsObject } from '@smartsoft001-mobilems/objects-domain';
 import * as dist_packages_objects_domain_src from 'dist/packages/objects/domain/src';
@@ -14,6 +14,7 @@ import * as _ngrx_store from '@ngrx/store';
 import { Action } from '@ngrx/store';
 import { MsFile } from '@smartsoft001-mobilems/models';
 import { ListMode } from '@smartsoft001/angular';
+import { Observable } from 'rxjs';
 
 declare class FiltersComponent extends FiltersBaseComponent<MsObject> {
     static ɵfac: i0.ɵɵFactoryDeclaration<FiltersComponent, never>;
@@ -126,17 +127,113 @@ declare abstract class ObjectsItemComponent extends CrudItemPageBaseComponent<Ms
     facade: ObjectsFacade;
     readonly loading: i0.Signal<boolean>;
     readonly item: i0.Signal<MsObject>;
+    /** @deprecated No museum uses it; download the card through the app's own download service. */
     readonly isPdfDownloading: i0.WritableSignal<boolean>;
     protected constructor();
+    /** @deprecated No museum uses it; download the card through the app's own download service. */
     onDownload(): Promise<void>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ObjectsItemComponent, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<ObjectsItemComponent, never, never, {}, {}, never, never, true, never>;
 }
 
-declare const SERVICES: (typeof ObjectsService | {
-    provide: typeof CrudService;
-    useClass: typeof ObjectsService;
-})[];
+/** Response of `GET object/:id/related`. */
+interface IObjectRelated {
+    objects: Array<{
+        id: number | string;
+    }>;
+    collections: Array<{
+        id: number | string;
+    }>;
+    articles: Array<{
+        id: number | string;
+    }>;
+}
+/**
+ * A public (thematic) collection from the `GET public-collections/page/{n}`
+ * list — as much as the object card ("Related collections") and the filters
+ * panel need.
+ */
+interface IObjectCollectionSummary {
+    id: number | string;
+    title: string;
+    publicationDate: string | null;
+    /** Number of objects in the collection — the page size of the membership check. */
+    itemCount: number | null;
+}
+/**
+ * Segregations of the `ArchaeologicalData` dictionary — per the MobileMS task
+ * (Kanbanize 50040, MOB-1844): site towns, periods (epochs) and cultures.
+ */
+type ArchaeologicalSegregation = 'ArcheoTown' | 'ArcheoPeriod' | 'ArcheoCulture';
+/**
+ * `ObjectsService` plus the reads of the object details page and the filter
+ * dictionaries. A subclass, so `ObjectsService` (the `CrudService` of the
+ * objects module) stays unchanged. Request URLs, parameter order included,
+ * are transfer cache keys: keep them as they are.
+ */
+declare class ObjectsDataService extends ObjectsService {
+    private readonly objectsDataIsServer;
+    /**
+     * Counts a visit of the object card: `POST api/object/:id/visit`. Browser
+     * only — the caller runs it under `isPlatformBrowser` and catches its errors.
+     */
+    logVisit(id: number | string): Promise<void>;
+    /**
+     * "You may also be interested in" — `GET object/:id/related` (objects,
+     * collections, articles). A network error (status 0) is retried once; any
+     * other error, or a second failed request, goes on to the `rxResource`
+     * (error state — the section stays hidden, `reload()` retries). In dev mode
+     * the error is logged, except a 404 on the server: there `related` starts
+     * next to the card (MOB-1850), so a missing object gives two 404s and the
+     * card view shows the error. In the browser `related` follows the card — a
+     * 404 is unexpected there and stays in the console.
+     */
+    getRelated(id: number | string): Observable<IObjectRelated>;
+    /**
+     * One page of the public collections list, newest publication first
+     * (`sort=publicationDate-desc`), with the phrase in `filter[phrase]` (the
+     * "Field description" document: "Search in collections: filter:phrase").
+     * 404 `NO_RESULTS_FOR_GIVEN_QUERY` is an empty page, any other error propagates.
+     */
+    loadPublicCollectionsPage(page?: number, query?: string): Observable<{
+        items: IObjectCollectionSummary[];
+        totalPagesCount: number;
+    }>;
+    /**
+     * Public collections as the dictionary of the "Thematic collection" field in
+     * the advanced filters (MOB-1844): `filter[entryCollections]` in
+     * `search/Object` takes ids from `public-collections`, not from the
+     * `ECollection` dictionary.
+     */
+    loadCollectionsDictionary(page?: number, query?: string): Observable<IDictionaryPage>;
+    /**
+     * Dictionary of the "Archaeological filters" fields (MOB-1844). In Muza it is
+     * `ArchaeologicalData` segregated into `ArcheoTown|ArcheoPeriod|ArcheoCulture`
+     * (Kanbanize 50040), but MobileMS exposed each segregation as its own
+     * dictionary type: `dictionary/ArcheoTown/search/page/{n}` (develop
+     * 2026-10-21 — the type is recognised, `ArchaeologicalData` still 409). Same
+     * path and shape as the framework's `DataService.loadFilterDictionary`. Until
+     * production has these types the API answers 409 and the field shows a load error.
+     */
+    loadArchaeologicalDictionary(segregation: ArchaeologicalSegregation, page?: number, query?: string): Observable<IDictionaryPage>;
+    /** All public collections (consecutive pages of the list). */
+    loadAllPublicCollections(): Observable<IObjectCollectionSummary[]>;
+    /**
+     * "Related collections" of the object card per the "Field description"
+     * document: `search/Object` with `filter[entryCollections]`, sorted by
+     * publication date. The API gives no reverse direction (`portalCollections`
+     * and `related.collections` are empty also for objects in a collection), so
+     * for each public collection we check whether its objects contain this
+     * object — a few collections at a time, in list order. A collection that
+     * could not be checked is skipped; a failed list means no section (an empty
+     * list), not a page error.
+     */
+    loadRelatedCollections(objectId: number | string): Observable<IObjectCollectionSummary[]>;
+    /** Whether `search/Object` with the collection's `filter[entryCollections]` contains the object; an error → unknown → `false`. */
+    private objectsDataCollectionContains;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ObjectsDataService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ObjectsDataService>;
+}
 
 type SortType = 'random' | 'date-asc' | 'date-desc' | 'name-asc' | 'name-desc';
 type IKeyValue = {
@@ -252,6 +349,41 @@ interface ISpecificObject extends MsObject {
     shareMuseumObjectMultimediaEnabled?: boolean;
 }
 
+/** A gallery item (full size, for fullscreen). */
+interface IObjectGalleryItem {
+    title?: string;
+    image?: MsFile;
+    file?: MsFile;
+}
+/**
+ * Shared listing of an object's media (the main image + `additionalImages`
+ * filtered by `formFeature`) — used by the details page image viewer
+ * (MOB-1801), the hero gallery, the thumbnails and the HD images section.
+ */
+declare class ObjectMediaService {
+    private readonly objectMediaFileUrl;
+    /** Gallery items (full size, for fullscreen). */
+    galleryItems(obj: MsObject | undefined, types: FormFeatureType[], includeMainImage?: boolean): IObjectGalleryItem[];
+    /** Thumbnail URLs (`cache` mode + a forced `.jpg` for the CDN). */
+    thumbnailUrls(obj: MsObject | undefined, types: FormFeatureType[], includeMainImage?: boolean): string[];
+    /**
+     * Whether the object has files of the types (video, 3D model) — by
+     * `filePath`, because `FileUrlService` returns a placeholder for
+     * non-image extensions.
+     */
+    hasFiles(obj: MsObject | undefined, types: FormFeatureType[]): boolean;
+    private objectMediaAdditional;
+    /** Replaces the extension with `.jpg` — CDN cache compatibility. */
+    private objectMediaJpg;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ObjectMediaService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ObjectMediaService>;
+}
+
+declare const SERVICES: (typeof ObjectsService | {
+    provide: typeof CrudService;
+    useClass: typeof ObjectsService;
+})[];
+
 /**
  * Filter defaults of the objects list (Muzeum Podlasia): 20 objects per page,
  * newest first. **The key order is part of the contract** — the first read
@@ -384,5 +516,198 @@ declare abstract class ObjectsCatalogBaseComponent extends ObjectsListComponent
     static ɵdir: i0.ɵɵDirectiveDeclaration<ObjectsCatalogBaseComponent, never, never, {}, {}, never, never, true, never>;
 }
 
-export { AdvancedFilterType, ComponentsModule, FiltersComponent, FormFeatureType, ListComponent, MULTIMEDIA_DICTIONARY, OBJECTS_CATALOG_DEFAULTS, OBJECTS_CATALOG_SEO, ObjectsCatalogBaseComponent, ObjectsFacade, ObjectsItemComponent, ObjectsListComponent, ObjectsModule, ObjectsService, ObjectsSharedModule, SERVICES, getObjectsState, getReducer, initialState };
-export type { FileType, IAnimationObject, IKeyValue, IModel3DObject, IMultimediaDictionaryItem, IObjectsCatalogLoadMore, IObjectsCatalogOptions, IObjectsCatalogSeo, ISpecificObject, SortType, State };
+/** Options of an object details page, passed to `super(options)`. */
+interface IObjectDetailsOptions {
+    /** Translation key of the site name in the title. Default `MODEL.mainTitle`. */
+    siteNameKey?: string;
+    /** Opt-in „You may also be interested in” (`GET object/:id/related`). Default `false`. */
+    related?: boolean;
+    /** Opt-in „Related collections” (reverse `search/Object` lookup, browser only). Default `false`. */
+    relatedCollections?: boolean;
+}
+/**
+ * Base of an object details page (`/obiekty/:id`, MOB-1801), from Muzeum
+ * Podlasia's item page: the SEO (also in SSR), the item effect with the
+ * `onObjectShown` hook (default: scroll to the top in the browser), the
+ * browser-only visit counter, `hasError`, `retryLoad`, `altTitle` and two
+ * opt-in resources — `related` and `relatedCollections`. The page keeps its
+ * template.
+ *
+ * ```ts
+ * // Muzeum Podlasia
+ * export class ItemComponent extends ObjectDetailsBaseComponent {
+ *   constructor() {
+ *     super({ related: true, relatedCollections: true });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ObjectDetailsBaseComponent extends ObjectsItemComponent implements OnInit {
+    protected readonly objectDetailsService: ObjectsDataService;
+    private readonly objectDetailsSeoService;
+    private readonly objectDetailsFileUrl;
+    private readonly objectDetailsDocument;
+    private readonly objectDetailsBrowser;
+    private readonly objectDetailsServer;
+    private readonly objectDetailsOptions;
+    /** Object id from the route (`/obiekty/:id` and `/obiekty/:id/:slug`). */
+    private readonly objectDetailsRouteId;
+    /**
+     * Id for „related” (MOB-1850). On the server from the route:
+     * `GET object/:id/related` starts together with `GET object/:id`, so SSR
+     * waits for the longer of the two requests, not their sum (card 5233:
+     * ~400 → ~290 ms locally). In the browser unchanged — after the card (no
+     * extra 404 for a missing object, „Try again” works as before). A
+     * non-numeric id waits for the card. `computed`, because `rxResource`
+     * does not compare the `params` result — every change of a read signal
+     * would repeat the request.
+     */
+    private readonly objectDetailsRelatedId;
+    /** The card failed — „related” started on the server has nothing to wait for. */
+    private readonly objectDetailsCardFailed$;
+    readonly hasError: Signal<any>;
+    /** The object title without markup — image `alt`s. `''` without an object. */
+    readonly altTitle: Signal<string>;
+    /**
+     * „You may also be interested in” — `GET object/:id/related`, only with
+     * the `related` option. A card error stops the request (the error page
+     * waits neither for „related” nor for its retry after a network error);
+     * the resource then ends in an error state, the section is gone anyway.
+     */
+    readonly related: ResourceRef<IObjectRelated | undefined>;
+    /**
+     * „Related collections” per the „Field description” document: thematic
+     * collections whose `search/Object` with `filter[entryCollections]`
+     * contains the object (the service gives an empty list also after an
+     * error — the section then disappears). Only with the
+     * `relatedCollections` option and only in the browser: the reverse lookup
+     * is one `search/Object` request per collection, and its responses (full
+     * object cards) must not reach SSR nor the transfer cache HTML — the
+     * server renders without this section, the client adds it after
+     * hydration.
+     */
+    readonly relatedCollections: ResourceRef<IObjectCollectionSummary[]>;
+    protected constructor(options?: IObjectDetailsOptions);
+    /**
+     * Visit counter — browser only (SSR would count the visit a second time),
+     * and its error (e.g. a 429 of the API limit) must neither reach the
+     * console as an unhandled `HttpErrorResponse` nor break the view. Once per
+     * page instance: in-page navigation to another object sends no new visit.
+     */
+    ngOnInit(): void;
+    retryLoad(): void;
+    /** SEO of the object: `<title> - <site>`, description, image and its alt. */
+    protected objectDetailsSeo(item: MsObject): ISeoMetadata;
+    /**
+     * Called (untracked) after the SEO for every object the facade selects.
+     * Default: scroll to the top in the browser. Override to keep the scroll
+     * on a re-read of the same card (MOB-1961) or to reset a gallery.
+     */
+    protected onObjectShown(item: MsObject): void;
+    private objectDetailsFetchSsrSeo;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ObjectDetailsBaseComponent, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ObjectDetailsBaseComponent, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Generic readers of an object card from `GET object/:id` for a details page
+ * (MOB-1801), per the MobileMS „Opis pól” document (2026-10-05). A field
+ * without data gives an empty list — the template then hides the whole row
+ * with its label, nothing is made up. The layout groupings (header facts,
+ * metrics columns, hero crops) stay in each museum.
+ */
+/** A field value: `name [role] (comment)`; `nameKey` — a translation instead of the name. */
+type ObjectDetailValue = INamedEntryParts & {
+    nameKey?: string;
+};
+/** A related link (article, collection) of the details page. */
+interface IObjectDetailLink {
+    id: number | string;
+    title: string;
+    route: string;
+}
+/** One bibliography item; `permalink` makes it a link. */
+interface IObjectBibliographyEntry {
+    text: string;
+    permalink: string | null;
+}
+/**
+ * The card fields these tools read. Both `MsObject` and a museum's wider card
+ * type (e.g. Podlasie's `ObjectCard`) are assignable to it.
+ */
+interface IObjectDetailSource {
+    title?: string | null;
+    name?: string | null;
+    noEvidence?: string | null;
+    seriesTitles?: ReadonlyArray<INamedEntrySource | null | undefined> | null;
+    bibliographyMNK?: string | null | ReadonlyArray<string | {
+        text?: string | null;
+        permalink?: string | null;
+    }>;
+    publicDescriptions?: ReadonlyArray<{
+        text?: string | null;
+    } | null> | null;
+    description?: string | null;
+    articles?: ReadonlyArray<{
+        id: number | string;
+        title?: string | null;
+    }> | null;
+}
+/** The object title — the document says `name`, the details API returns `title`. */
+declare function objectTitle(obj: IObjectDetailSource): string;
+/** Header tags: `seriesTitles` (the `Cycle` dictionary) → a list with the `cycles` filter. */
+declare function tagValues(obj: IObjectDetailSource): ObjectDetailValue[];
+/** Inventory number: `noEvidence`. */
+declare function inventoryValues(obj: IObjectDetailSource): ObjectDetailValue[];
+/**
+ * Bibliography as in OSSO (`museum-objects` item/main-tab): every
+ * `bibliographyMNK[]` entry is a separate item, and its `text` (HTML from the
+ * API) goes whole — OSSO does not split the text on full stops. An entry
+ * without text is dropped; `permalink` makes the item a link.
+ */
+declare function bibliography(obj: IObjectDetailSource): IObjectBibliographyEntry[];
+/**
+ * Description (HTML from the API): `publicDescriptions[].text` (the
+ * popular-science description), and without it `description` (the physical
+ * description) — the „Opis pól” rule of MOB-1563 („popular-science
+ * description, and if there is none — the physical one”); object 5233 has
+ * only `description` (MOB-1801). The description does not depend on media.
+ */
+declare function descriptionHtml(obj: IObjectDetailSource): string[];
+/**
+ * „Powiązane artykuły” — the card's `articles` field; the title without HTML
+ * (MOB-1845). `routePrefix` is the articles list route of the museum.
+ */
+declare function relatedArticles(obj: IObjectDetailSource, routePrefix?: string): IObjectDetailLink[];
+
+/**
+ * „Zapytaj o obiekt” keys (MOB-1869) — the mail address and text live in the
+ * CMS translations, so a museum changes them without a deployment.
+ */
+declare const ASK_ABOUT_OBJECT_KEYS: {
+    readonly email: "DETAILS_PAGE.detail.askEmail";
+    readonly subject: "DETAILS_PAGE.detail.askSubject";
+    readonly body: "DETAILS_PAGE.detail.askBody";
+    readonly objectWithInventory: "DETAILS_PAGE.detail.askObjectWithInventory";
+    readonly portal: "MODEL.mainTitle";
+};
+/** `TranslateService.instant` — a key without a translation comes back as itself. */
+type AskTranslate = (key: string, params?: Record<string, string>) => string;
+interface IAskAboutObject {
+    /** The title without HTML. */
+    title: string;
+    inventory?: string | null;
+    /** The full address of the object card on the portal. */
+    url?: string | null;
+}
+/**
+ * The `mailto:` of the „Zapytaj o obiekt” button: the address from
+ * `askEmail`, the subject with the title (and the inventory number), the body
+ * with a greeting, the object, a link and room for the question. Without a
+ * valid address — `null` (no button); a missing subject or body is simply
+ * skipped. Body lines break as CRLF, as RFC 6068 requires.
+ */
+declare function askAboutObjectHref(translate: AskTranslate, object: IAskAboutObject): string | null;
+
+export { ASK_ABOUT_OBJECT_KEYS, AdvancedFilterType, ComponentsModule, FiltersComponent, FormFeatureType, ListComponent, MULTIMEDIA_DICTIONARY, OBJECTS_CATALOG_DEFAULTS, OBJECTS_CATALOG_SEO, ObjectDetailsBaseComponent, ObjectMediaService, ObjectsCatalogBaseComponent, ObjectsDataService, ObjectsFacade, ObjectsItemComponent, ObjectsListComponent, ObjectsModule, ObjectsService, ObjectsSharedModule, SERVICES, askAboutObjectHref, bibliography, descriptionHtml, getObjectsState, getReducer, initialState, inventoryValues, objectTitle, relatedArticles, tagValues };
+export type { ArchaeologicalSegregation, AskTranslate, FileType, IAnimationObject, IAskAboutObject, IKeyValue, IModel3DObject, IMultimediaDictionaryItem, IObjectBibliographyEntry, IObjectCollectionSummary, IObjectDetailLink, IObjectDetailSource, IObjectDetailsOptions, IObjectGalleryItem, IObjectRelated, IObjectsCatalogLoadMore, IObjectsCatalogOptions, IObjectsCatalogSeo, ISpecificObject, ObjectDetailValue, SortType, State };