@sinequa/atomic-angular 1.14.1 → 1.15.0

package/elements/index.d.ts

@@ -1,9 +1,14 @@
-import { UpdateContainerInput } from '@sinequa/atomic';
+import { UpdateContainerInput, UploadJobStatus } from '@sinequa/atomic';
 import { EnvironmentProviders } from '@angular/core';
 
-type TooltipPlacement = 'top' | 'right' | 'left' | 'bottom';
+type TooltipPlacement = "top" | "right" | "left" | "bottom";
 interface TooltipController {
-    attach(el: HTMLElement, text: string, placement?: TooltipPlacement, condition?: () => boolean): void;
+    /**
+     * Shows a tooltip on hover. `key` is a catalog key, not literal text, and is
+     * resolved on every hover — so a tooltip attached once still follows a later
+     * language change without re-attaching anything.
+     */
+    attach(el: HTMLElement, key: string, placement?: TooltipPlacement, condition?: () => boolean): void;
     position(trigger: HTMLElement, placement?: TooltipPlacement): void;
     el: HTMLSpanElement;
 }
@@ -12,7 +17,7 @@ interface MobileSheetController {
     close(): void;
 }
 
-type ContainerRole = 'creator' | 'owner' | 'reader';
+type ContainerRole = "creator" | "owner" | "reader";
 interface Collection {
     id: string;
     name: string;
@@ -24,7 +29,6 @@ interface Collection {
     ownerIds: string[];
     readerIds: string[];
     currentUserRole: ContainerRole;
-    favorited: boolean;
 }
 interface CollectionDocument {
     _id: string;
@@ -34,8 +38,10 @@ interface CollectionDocument {
     date: string;
     size?: string;
     source?: string;
-    status?: 'uploading' | 'indexing' | 'error' | null;
+    status?: "uploading" | "indexing" | "error" | null;
     uploadedBy?: string;
+    percent?: number;
+    jobId?: string;
 }
 declare class CollectionsStore extends EventTarget {
     collections: Collection[];
@@ -52,12 +58,15 @@ declare class CollectionsStore extends EventTarget {
     fetchContainer(id: string): Promise<Collection>;
     get hasMoreCollections(): boolean;
     ensureLoaded(): Promise<Collection[]>;
+    reload(): Promise<Collection[]>;
     load(): Promise<Collection[]>;
     loadMore(): Promise<Collection[]>;
-    create({ name, desc, tags }: {
+    create({ name, desc, tags, owners, readers }: {
         name: string;
         desc?: string;
         tags?: string[];
+        owners?: string[];
+        readers?: string[];
     }): Promise<Collection>;
     update(id: string, patch: UpdateContainerInput): Promise<Collection | null>;
     remove(ids: string[]): Promise<{
@@ -67,7 +76,6 @@ declare class CollectionsStore extends EventTarget {
             error: string;
         }[];
     }>;
-    toggleFavorite(id: string): boolean | undefined;
     getDocuments(collectionId: string): CollectionDocument[];
     hasMoreDocuments(collectionId: string): boolean;
     loadDocuments(collectionId: string): Promise<CollectionDocument[]>;
@@ -86,23 +94,73 @@ interface TrackerFileInput {
     name: string;
     type: string;
 }
+/**
+ * What the tracker's connection banner is currently saying. Emitted whenever the
+ * situation changes, and `null` once everything is healthy again.
+ */
+interface ConnectionNotice {
+    /**
+     * - `retrying` - a transfer is waiting out `retryAtMs` before its next attempt;
+     * - `reconnecting` - a session recovery is in flight;
+     * - `signed-out` - recovery came back negative; nothing moves until the user
+     *   signs in again.
+     */
+    phase: "retrying" | "reconnecting" | "signed-out";
+    /** Transfers held up by this. 0 when only the status poll is affected. */
+    uploads: number;
+    /** 1-based number of the attempt about to be made, and the budget it comes from. */
+    attempt: number;
+    maxAttempts: number;
+    /** Epoch ms of the next attempt - the countdown's target (`retrying` only). */
+    retryAtMs?: number;
+    /** Epoch ms at which the retry budget runs out (`retrying` only). */
+    budgetEndsAtMs?: number;
+    /** Epoch ms the connection was first reported lost - drives "lost N ago". */
+    sinceMs: number;
+    /**
+     * Re-runs the recovery, for the banner's Retry button. Carried on the payload
+     * rather than published as another controller method because it is the one
+     * thing the banner can DO, and it is meaningless without the notice it belongs
+     * to. Absent when there is nothing useful to retry.
+     */
+    retry?(): void;
+}
 interface UploadTrackerController {
     addFiles(trackerDocs: TrackerFileInput[], colId: string, colName: string): void;
     onProgress(docId: string, pct: number): void;
     onIndexing(docId: string): void;
     onComplete(docId: string): void;
     onError(docId: string): void;
+    /**
+     * Feeds in the job-level half of the status API: per-file error messages and
+     * rejections, which only `GET .../document-upload/status` reports.
+     *
+     * Optional on purpose - this interface is published from index.ts and driven
+     * by hand by the demo app's /document-upload tester, so a required method
+     * would be a breaking change for it. Returns whether anything actually
+     * changed, which paces the poller; `void` is accepted so an implementation
+     * that does not care still satisfies the type.
+     */
+    onJobUpdate?(jobs: UploadJobStatus[]): boolean | void;
+    /**
+     * Drives the connection banner. `null` clears it.
+     *
+     * Optional for the same reason as `onJobUpdate` - this interface is published
+     * from index.ts and driven by hand by the demo app's /document-upload tester.
+     */
+    onConnectionChange?(notice: ConnectionNotice | null): void;
 }
 
 interface CollectionsHost extends HTMLElement {
     readonly shadowRoot: ShadowRoot;
     _pickerContainer: HTMLDivElement;
     _tooltip: TooltipController;
-    _colCurrentView: 'grid' | 'list';
+    _colCurrentView: "grid" | "list";
     _colGridBuilt: boolean;
     _colListBuilt: boolean;
     _showList(): Promise<void>;
     _hideList(): void;
+    _refreshList?(): Promise<void>;
     _buildCollectionCard(col: Collection): HTMLElement;
     _updateColTabCounts(): void;
     _applyColFilters?(): void;
@@ -111,7 +169,7 @@ interface CollectionsHost extends HTMLElement {
     _closeColDeleteModal(): void;
     _currentCol: Collection | null;
     _currentDocs: CollectionDocument[];
-    _cdvCurrentView: 'grid' | 'list';
+    _cdvCurrentView: "grid" | "list";
     _cdvListBuilt: boolean;
     _openColDetail(col: Collection): void;
     _closeColDetail(): void;
@@ -125,6 +183,8 @@ interface CollectionsHost extends HTMLElement {
     _closeColDocPreview(): void;
     _syncColDocPreviewView(): void;
     _uploadTracker: UploadTrackerController;
+    _startUploadPolling?(): void;
+    _stopUploadPolling?(): void;
 }
 
 interface Passage {
@@ -143,7 +203,7 @@ declare class LexiqCollectionsElement extends HTMLElement implements Collections
     _initialized: boolean;
     _pickerContainer: HTMLDivElement;
     _tooltip: TooltipController;
-    _colCurrentView: 'grid' | 'list';
+    _colCurrentView: "grid" | "list";
     _colGridBuilt: boolean;
     _colListBuilt: boolean;
     _showList: () => Promise<void>;
@@ -155,7 +215,7 @@ declare class LexiqCollectionsElement extends HTMLElement implements Collections
     _closeColDeleteModal: () => void;
     _currentCol: Collection | null;
     _currentDocs: CollectionDocument[];
-    _cdvCurrentView: 'grid' | 'list';
+    _cdvCurrentView: "grid" | "list";
     _cdvListBuilt: boolean;
     _openColDetail: (col: Collection) => void;
     _closeColDetail: () => void;
@@ -167,8 +227,11 @@ declare class LexiqCollectionsElement extends HTMLElement implements Collections
     _closeColDocPreview: () => void;
     _syncColDocPreviewView: () => void;
     _uploadTracker: UploadTrackerController;
+    _startUploadPolling?: () => void;
+    _stopUploadPolling?: () => void;
     constructor();
     connectedCallback(): void;
+    disconnectedCallback(): void;
     showList(): Promise<void>;
     hideList(): void;
     showDetail(collectionId: string): Promise<void>;
@@ -178,7 +241,7 @@ declare class LexiqCollectionsElement extends HTMLElement implements Collections
     get collections(): Collection[];
 }
 
-type IncomingDocument = Partial<Pick<CollectionDocument, '_id'>> & Omit<CollectionDocument, '_id'>;
+type IncomingDocument = Partial<Pick<CollectionDocument, "_id">> & Omit<CollectionDocument, "_id">;
 interface PickerOptions {
     mobileSheet?: MobileSheetController | null;
     root?: ShadowRoot | null;
@@ -196,6 +259,7 @@ declare class LexiqCollectionPickerElement extends HTMLElement {
     private _container;
     constructor();
     connectedCallback(): void;
+    disconnectedCallback(): void;
     private _withEvents;
     openSaveCard(anchorEl: HTMLElement, opts?: Partial<PickerOptions>): void;
     closeSaveCard(anchorEl?: HTMLElement | null): void;
@@ -232,9 +296,38 @@ declare function defineLexiqCollectionPicker(tagName?: string): void;
 declare function defineLexiqCollectionMentionList(tagName?: string): void;
 declare function registerLexiqCollectionsElements(): void;
 
+/** Values substituted into `{placeholder}` slots of a catalog entry. */
+type TranslateParams = Record<string, string | number>;
+/**
+ * Resolves a catalog key (unscoped, e.g. `list.title`) against the host's
+ * translation engine. Returns `undefined` when the host cannot resolve the
+ * key, which makes the bundled English catalog take over.
+ */
+type Translator = (key: string, params?: TranslateParams) => string | undefined;
+/** The active BCP 47 language tag, for `Intl` formatters used across the views. */
+declare function getLang(): string;
+/**
+ * Installs the host's translation engine and language, then re-translates every
+ * connected element in place. Call it again on every language change.
+ *
+ * @param next - Resolver for catalog keys, or null to return to bundled English.
+ * @param lang - BCP 47 tag of the language `next` resolves into.
+ */
+declare function setTranslator(next: Translator | null, lang: string): void;
+/**
+ * Switches the language used for plural selection and `Intl` formatting, and
+ * re-translates connected elements. Prefer {@link setTranslator}; this is for
+ * hosts that translate through a resolver whose language changes behind it.
+ *
+ * @param lang - BCP 47 tag, e.g. `fr` or `fr-FR`.
+ */
+declare function setLang(lang: string): void;
+
 /**
  * Registers the LexiQ Collections native Custom Elements when the Angular
- * application environment initializes. Add to an app/route `providers` array:
+ * application environment initializes, and — when the host app uses Transloco —
+ * bridges its translations into the elements. Add to an app/route `providers`
+ * array:
  *
  * ```ts
  * export const appConfig: ApplicationConfig = {
@@ -243,8 +336,11 @@ declare function registerLexiqCollectionsElements(): void;
  * ```
  *
  * Components using the tags still need `schemas: [CUSTOM_ELEMENTS_SCHEMA]`.
+ *
+ * Transloco is optional: without it the elements fall back to their bundled
+ * English catalog, which is why nothing under `internal/` imports it.
  */
 declare function provideLexiqCollectionsElements(): EnvironmentProviders;
 
-export { LexiqCollectionMentionListElement, LexiqCollectionPickerElement, LexiqCollectionsElement, store as collectionsStore, defineLexiqCollectionMentionList, defineLexiqCollectionPicker, defineLexiqCollections, provideLexiqCollectionsElements, registerLexiqCollectionsElements };
-export type { Collection, CollectionDocument, ContainerRole, PickerOptions, RefDocument };
+export { LexiqCollectionMentionListElement, LexiqCollectionPickerElement, LexiqCollectionsElement, store as collectionsStore, defineLexiqCollectionMentionList, defineLexiqCollectionPicker, defineLexiqCollections, getLang, provideLexiqCollectionsElements, registerLexiqCollectionsElements, setLang, setTranslator };
+export type { Collection, CollectionDocument, ConnectionNotice, ContainerRole, PickerOptions, RefDocument, TranslateParams, Translator, UploadTrackerController };