@rt-tools/ui-kit-v2 0.25.0 → 0.26.0

package/types/rt-tools-ui-kit-v2-pdf-viewer.d.ts

@@ -0,0 +1,243 @@
+import * as i0 from "@angular/core";
+import { ElementRef, InjectionToken, Provider, Signal, WritableSignal } from "@angular/core";
+import { TRtKitLabelMap } from "@rt-tools/ui-kit-v2/core";
+/**
+ * Контракты полноэкранного просмотрщика документа PDF. Один корневой неймспейс с префиксом `I`.
+ */
+export declare namespace IRtPdfViewer {
+  /**
+   * Откуда взять документ: байты или адрес. Байты просмотрщик не отдаёт рисовальщику как есть —
+   * тот забирает буфер себе в поток, и скачать файл после этого было бы нечем. Отдаётся копия.
+   */
+  type Source = Uint8Array | ArrayBuffer | string;
+  /**
+   * Данные открытия: документ и имя файла.
+   *
+   * Имя показывается в полосе сверху и становится именем скачанного файла: адрес документа
+   * часто бывает подписанной ссылкой, и имени в нём нет.
+   */
+  interface Data {
+    readonly source: Source;
+    readonly fileName: string;
+  }
+  /** Что сейчас на месте страниц: индикатор, сами страницы или отказ. */
+  type Status = 'loading' | 'ready' | 'error';
+  /**
+   * Масштаб. «По ширине» хранится как режим, а не как число: окно меняет ширину, и страница
+   * обязана подстроиться под новую, а не остаться на числе, посчитанном для прежней.
+   */
+  type Zoom = {
+    readonly kind: 'fit';
+  } | {
+    readonly kind: 'percent';
+    readonly percent: number;
+  };
+  /** Размер страницы в пунктах документа — в единицах, в которых его пишет сам PDF. */
+  interface PageSize {
+    readonly width: number;
+    readonly height: number;
+  }
+  /** Размер места под страницу на экране, в CSS-пикселях. */
+  interface PageBox {
+    readonly index: number;
+    readonly width: number;
+    readonly height: number;
+  }
+  /**
+   * Настройки рисовальщика. Даёт их приложение через `provideRtPdfViewer()`: только оно знает,
+   * куда при сборке положен файл воркера.
+   */
+  interface Config {
+    /**
+     * Адрес файла воркера `pdf.worker.min.mjs`. Относительный адрес считается от `<base href>`
+     * страницы. Версия воркера обязана совпадать с версией `pdfjs-dist`, поэтому файл копируется
+     * из того же `node_modules`, а не берётся с чужого адреса.
+     */
+    readonly workerSrc: string;
+    /** Как загрузить рисовальщик. Умолчание — динамический `import('pdfjs-dist')`. */
+    readonly load: () => Promise<PdfJs>;
+    /** Каталог `cmaps/` пакета — нужен документам с азиатскими шрифтами без вложенных карт. */
+    readonly cMapUrl?: string;
+    /** Каталог `standard_fonts/` пакета — нужен документам на стандартных шрифтах без вложения. */
+    readonly standardFontDataUrl?: string;
+    /** Каталог `wasm/` пакета — нужен документам со снимками в JPEG 2000. */
+    readonly wasmUrl?: string;
+  }
+  /**
+   * Та часть `pdfjs-dist`, которой пользуется просмотрщик. Описана своими типами, а не взята из
+   * пакета: тогда типы кита не требуют пакета у того, кто просмотрщик не ставит, а в тесте
+   * рисовальщик подменяется объектом из нескольких функций.
+   */
+  interface PdfJs {
+    readonly GlobalWorkerOptions: {
+      workerSrc: string;
+    };
+    getDocument(params: DocumentParams): LoadingTask;
+  }
+  interface DocumentParams {
+    readonly url?: string;
+    readonly data?: Uint8Array;
+    readonly cMapUrl?: string;
+    readonly cMapPacked?: boolean;
+    readonly standardFontDataUrl?: string;
+    readonly wasmUrl?: string;
+  }
+  interface LoadingTask {
+    readonly promise: Promise<PdfDocument>;
+    destroy(): Promise<void>;
+  }
+  interface PdfDocument {
+    readonly numPages: number;
+    getPage(pageNumber: number): Promise<PdfPage>;
+    getData(): Promise<Uint8Array>;
+  }
+  interface PdfPage {
+    getViewport(params: {
+      scale: number;
+    }): Viewport;
+    render(params: RenderParams): RenderTask;
+  }
+  interface Viewport {
+    readonly width: number;
+    readonly height: number;
+  }
+  interface RenderParams {
+    readonly canvas: HTMLCanvasElement;
+    readonly viewport: Viewport;
+    readonly intent?: string;
+  }
+  interface RenderTask {
+    readonly promise: Promise<void>;
+    cancel(): void;
+  }
+  /** Печатный лист: разметка страниц картинками и уборка за ней. */
+  interface PrintSheet {
+    dispose(): void;
+  }
+}
+/**
+ * Полноэкранный просмотр документа PDF поверх `RtDialogService`.
+ *
+ * Страницы рисует `pdfjs-dist` — необязательная зависимость кита. Он грузится динамическим импортом
+ * только при открытии окна, поэтому вход `@rt-tools/ui-kit-v2/pdf-viewer` не утяжеляет бандл, пока
+ * окно не открыто. Рисуются только видимые страницы и их соседи, с плотностью точек экрана.
+ *
+ * `Esc`, блокировку прокрутки фона и затемнение даёт сам диалог; фокус после закрытия
+ * просмотрщик возвращает туда, откуда его открыли.
+ */
+export declare class RtPdfViewerComponent {
+  #private;
+  protected readonly t: Signal<TRtKitLabelMap>;
+  protected readonly scroller: Signal<ElementRef<HTMLElement> | undefined>;
+  protected readonly column: Signal<ElementRef<HTMLElement> | undefined>;
+  protected readonly pageNodes: Signal<readonly ElementRef<HTMLElement>[]>;
+  protected readonly canvases: Signal<readonly ElementRef<HTMLCanvasElement>[]>;
+  protected readonly fileName: string;
+  protected readonly status: WritableSignal<IRtPdfViewer.Status>;
+  protected readonly printing: WritableSignal<boolean>;
+  protected readonly zoom: WritableSignal<IRtPdfViewer.Zoom>;
+  /** Масштаб на экране в процентах — и для «по ширине», который хранится режимом */
+  protected readonly percent: Signal<number>;
+  protected readonly isFit: Signal<boolean>;
+  protected readonly zoomLabel: Signal<string>;
+  protected readonly canZoomIn: Signal<boolean>;
+  protected readonly canZoomOut: Signal<boolean>;
+  protected readonly boxes: Signal<IRtPdfViewer.PageBox[]>;
+  /** Видимая сейчас страница, с нуля */
+  protected readonly currentPage: WritableSignal<number>;
+  protected readonly counter: Signal<string>;
+  protected readonly pageOfLabel: Signal<string>;
+  constructor();
+  close(): void;
+  /** Esc закрывает только окно: окно под ним, например боковая панель, остаётся открытым */
+  protected onEscape(event: Event): void;
+  protected zoomIn(): void;
+  protected zoomOut(): void;
+  protected fitWidth(): void;
+  protected onScroll(): void;
+  protected onResize(): void;
+  /** Байты уходят как пришли, а адрес — байтами документа, если он уже загружен */
+  protected download(): Promise<void>;
+  /**
+   * Печать документа целиком, без полосы и плашки: страницы рисуются картинками в отдельный лист,
+   * и на время печати страница прячет всё, кроме него. Лист убирается после печати.
+   */
+  protected print(): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RtPdfViewerComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<RtPdfViewerComponent, "rt-pdf-viewer", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Чистая логика просмотрщика документа: шаги масштаба, начальный масштаб, номер видимой страницы и
+ * то, какие страницы стоит держать нарисованными.
+ */
+/** Ступени масштаба в процентах. Кнопки «−» и «+» ходят только по ним. */
+export declare const RT_PDF_ZOOM_STEPS: readonly number[];
+export declare const RT_PDF_ZOOM_MIN: number;
+export declare const RT_PDF_ZOOM_MAX: number;
+/**
+ * Сколько CSS-пикселей в пункте документа. Пункт — 1/72 дюйма, CSS-пиксель — 1/96: при 100%
+ * страница A4 на экране той же ширины, что на бумаге.
+ */
+export declare const RT_PDF_CSS_UNITS: number;
+/** Ширина окна, до которой документ открывается «по ширине» при любом размере страницы. */
+export declare const RT_PDF_NARROW_WIDTH: number;
+/**
+ * Следующая ступень масштаба. Шаг идёт от того, что на экране сейчас: из «по ширине» в 83% кнопка
+ * «+» ведёт на 100%, а «−» — на 75%, а не на ступень, соседнюю с последней выбранной руками.
+ */
+export declare function nextZoomStep(current: number, direction: 1 | -1): number;
+/** Есть ли куда увеличивать: на верхней границе кнопка «+» выключена. */
+export declare function canZoomIn(current: number): boolean;
+/** Есть ли куда уменьшать: на нижней границе кнопка «−» выключена. */
+export declare function canZoomOut(current: number): boolean;
+/**
+ * Масштаб «по ширине» в процентах: самая широкая страница занимает всё место столбца.
+ *
+ * Границами ступеней он не зажат. На телефоне страница A4 «по ширине» — около 45%, и зажать её до
+ * 50% значило бы вернуть горизонтальную прокрутку, ради которой режим и существует.
+ */
+export declare function fitWidthPercent(availableWidth: number, pages: readonly IRtPdfViewer.PageSize[]): number;
+/**
+ * С какого масштаба открыть документ. Узкий экран и страница, которая в 100% не влезает, —
+ * «по ширине»: иначе человек сначала видит обрезанный край листа. Остальные — в 100%.
+ */
+export declare function initialZoom(viewportWidth: number, availableWidth: number, pages: readonly IRtPdfViewer.PageSize[]): IRtPdfViewer.Zoom;
+/** Места под страницы на экране: от размера в пунктах и масштаба, в целых пикселях. */
+export declare function pageBoxes(pages: readonly IRtPdfViewer.PageSize[], percent: number): IRtPdfViewer.PageBox[];
+/**
+ * Номер страницы, которая видна сейчас, — с нуля. Это та, что занимает больше всего высоты окна;
+ * при прокрутке до конца — последняя, даже если она короче соседки: иначе счётчик никогда не
+ * показал бы «M / M» у документа с маленькой последней страницей. Документ, который виден целиком
+ * без прокрутки, стоит на первой: до конца его никто не прокручивал.
+ */
+export declare function visiblePageIndex(tops: readonly number[], heights: readonly number[], scrollTop: number, viewportHeight: number): number;
+/**
+ * Страницы, которые стоит нарисовать: видимые и по `overscan` соседних с каждой стороны. Документ
+ * в сотню страниц разом не рисуется — каждая страница это холст в мегабайты памяти.
+ */
+export declare function pagesToRender(tops: readonly number[], heights: readonly number[], scrollTop: number, viewportHeight: number, overscan?: number): number[];
+/**
+ * Куда прокрутить после смены масштаба, чтобы на экране осталось то же место той же страницы.
+ * Без этого увеличение уводило бы человека на несколько страниц вниз от того, что он читал.
+ */
+export declare function anchoredScrollTop(oldTop: number, oldHeight: number, oldScrollTop: number, newTop: number, newHeight: number): number;
+/** Подпись масштаба для плашки в процентах: «83%», а не «83.47%». */
+export declare function zoomPercentLabel(percent: number): string;
+/**
+ * Адрес воркера по умолчанию. Относительный: считается от `<base href>`, поэтому приложение под
+ * своим префиксом не правит его руками. Файл туда кладёт сборка приложения — см. обзор компонента.
+ */
+export declare const RT_PDF_VIEWER_WORKER_SRC: string;
+/** Настройки рисовальщика просмотрщика. Без провайдера — умолчания выше. */
+export declare const RT_PDF_VIEWER_CONFIG: InjectionToken<IRtPdfViewer.Config>;
+/**
+ * Настраивает просмотрщик: адрес воркера и каталоги данных `pdfjs-dist`. Незаданное берётся из
+ * умолчаний.
+ *
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *     providers: [provideRtPdfViewer({ workerSrc: 'static/pdf.worker.min.mjs' })],
+ * };
+ * ```
+ */
+export declare function provideRtPdfViewer(config: Partial<IRtPdfViewer.Config>): Provider;