pptx-angular-viewer 0.1.0

package/types/pptx-angular-viewer.d.ts

@@ -0,0 +1,406 @@
+import * as pptx_viewer_core from 'pptx-viewer-core';
+import { PptxSlide, PptxTheme, PptxSlideMaster, PptxElement } from 'pptx-viewer-core';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+
+/**
+ * Theme configuration types for the PowerPoint viewer.
+ *
+ * All color values accept any valid CSS color string:
+ * hex (`#6366f1`), rgb (`rgb(99 102 241)`), hsl (`hsl(239 84% 67%)`),
+ * oklch (`oklch(0.585 0.233 277)`), named colors, etc.
+ *
+ * Framework-agnostic — shared by the React, Vue, and Angular bindings.
+ */
+/**
+ * Semantic color tokens for the viewer UI.
+ *
+ * These map to CSS custom properties (`--pptx-<token>`) and drive all
+ * UI component colors. The naming follows the shadcn/ui convention so
+ * that Tailwind + shadcn users get a familiar experience.
+ */
+interface ViewerThemeColors {
+    /** Page / root background */
+    background: string;
+    /** Default text color */
+    foreground: string;
+    /** Card / panel surface */
+    card: string;
+    /** Text on card surfaces */
+    cardForeground: string;
+    /** Popover / dropdown surface */
+    popover: string;
+    /** Text inside popovers */
+    popoverForeground: string;
+    /** Primary action color (buttons, active indicators) */
+    primary: string;
+    /** Text on primary-colored backgrounds */
+    primaryForeground: string;
+    /** Secondary / subdued action color */
+    secondary: string;
+    /** Text on secondary backgrounds */
+    secondaryForeground: string;
+    /** Muted / disabled surface */
+    muted: string;
+    /** Text on muted surfaces (also used for secondary text) */
+    mutedForeground: string;
+    /** Accent / hover-highlight surface */
+    accent: string;
+    /** Text on accent surfaces */
+    accentForeground: string;
+    /** Destructive / danger action color */
+    destructive: string;
+    /** Text on destructive backgrounds */
+    destructiveForeground: string;
+    /** Default border color */
+    border: string;
+    /** Input field border color */
+    input: string;
+    /** Focus ring color */
+    ring: string;
+}
+/**
+ * Full viewer theme configuration.
+ *
+ * Every property is optional — unset values fall back to the built-in
+ * dark theme defaults.
+ */
+interface ViewerTheme {
+    /** Semantic UI colors. Each key maps to a `--pptx-<key>` CSS custom property. */
+    colors?: Partial<ViewerThemeColors>;
+    /** Base border-radius value (e.g. `"0.5rem"`, `"8px"`). */
+    radius?: string;
+    /**
+     * Escape hatch: arbitrary CSS custom properties to set on the viewer
+     * root element. Keys should include the `--` prefix.
+     *
+     * @example
+     * ```ts
+     * { "--my-custom-shadow": "0 4px 12px rgba(0,0,0,0.5)" }
+     * ```
+     */
+    cssVars?: Record<string, string>;
+}
+
+/**
+ * Default dark-theme color values.
+ *
+ * These correspond to the built-in dark UI of the PowerPoint viewer and
+ * use Tailwind's gray palette as the neutral scale with indigo as the
+ * primary accent.
+ */
+declare const defaultThemeColors: ViewerThemeColors;
+/** Default border-radius. */
+declare const defaultRadius = "0.5rem";
+
+/**
+ * Convert a `ViewerTheme` into a flat `Record<string, string>` of CSS
+ * custom properties (including the `--` prefix) ready to be spread onto
+ * a `style` attribute.
+ *
+ * Only properties that differ from the built-in defaults are emitted when
+ * `omitDefaults` is true (the default).
+ */
+declare function themeToCssVars(theme: ViewerTheme | undefined, omitDefaults?: boolean): Record<string, string>;
+/**
+ * Build the complete set of CSS custom properties with all defaults.
+ * Useful for generating a full fallback stylesheet.
+ */
+declare function defaultCssVars(): Record<string, string>;
+
+/**
+ * Framework-agnostic public types shared by the viewer bindings.
+ *
+ * These were duplicated in the React (`types-ui.ts`) and Vue (`viewer/types.ts`)
+ * packages; this is the canonical copy. Each binding layers its own
+ * framework-specific prop/event/handle types on top of these.
+ */
+/** Canvas dimensions in pixels. */
+interface CanvasSize {
+    width: number;
+    height: number;
+}
+/** Collaboration role within a session. */
+type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
+/**
+ * Real-time collaboration configuration.
+ *
+ * The collaboration runtime (Yjs) is not yet ported to every binding — this
+ * type exists so the public prop surface stays identical across React, Vue,
+ * and Angular.
+ */
+interface CollaborationConfig {
+    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
+    roomId: string;
+    /** WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com"). */
+    serverUrl: string;
+    /** Display name for the local user. */
+    userName: string;
+    /** Avatar URL for the local user (optional). */
+    userAvatar?: string;
+    /** Hex colour for the local user's cursor/presence indicator. */
+    userColor?: string;
+    /** Optional authentication token sent with the WebSocket handshake. */
+    authToken?: string;
+    /** Role in the session — defaults to `'collaborator'`. */
+    role?: CollaborationRole;
+}
+
+/**
+ * Scalar viewer defaults shared by the UI bindings.
+ *
+ * Subset of the React package's `constants/scalar.ts` that the Vue and Angular
+ * viewers also need. Additional constant groups (toolbar presets, shape styles,
+ * transitions, etc.) remain per-binding until those features are ported.
+ */
+/** Default slide canvas width in pixels when the file declares none. */
+declare const DEFAULT_CANVAS_WIDTH = 1280;
+/** Default slide canvas height in pixels when the file declares none. */
+declare const DEFAULT_CANVAS_HEIGHT = 720;
+/** Fallback text colour. */
+declare const DEFAULT_TEXT_COLOR = "#111827";
+/** Fallback shape fill colour. */
+declare const DEFAULT_FILL_COLOR = "#3b82f6";
+/** Fallback shape stroke colour. */
+declare const DEFAULT_STROKE_COLOR = "#1f2937";
+
+/**
+ * `LoadContentService` — Angular port of the React `useLoadContent` hook and
+ * the Vue `useLoadContent` composable.
+ *
+ * Parses `.pptx` bytes into reactive signals via the framework-agnostic
+ * `PptxHandler` from `pptx-viewer-core`. All heavy lifting (ZIP, XML parse,
+ * theme/master/layout resolution, media extraction) lives in core and the
+ * pure helpers live in `pptx-viewer-shared`; this service only wires the async
+ * load into Angular signals and manages Blob-URL / handler lifecycle.
+ *
+ * Provide it at the component level so its lifetime tracks the host viewer:
+ * `@Component({ providers: [LoadContentService] })`.
+ *
+ * This is the viewer-first subset; the React hook also populated ~25 extra
+ * pieces of presentation metadata (sections, custom shows, embedded fonts,
+ * digital signatures, …). Those are tracked in PORTING.md and added here as
+ * the corresponding features are ported.
+ */
+declare class LoadContentService {
+    /** Parsed slides (with image Blob URLs patched in). */
+    readonly slides: _angular_core.WritableSignal<PptxSlide[]>;
+    /** Slide canvas size in pixels. */
+    readonly canvasSize: _angular_core.WritableSignal<CanvasSize>;
+    /** Resolved presentation theme. */
+    readonly theme: _angular_core.WritableSignal<PptxTheme | undefined>;
+    /** Slide masters (for placeholder/background resolution). */
+    readonly slideMasters: _angular_core.WritableSignal<PptxSlideMaster[]>;
+    /** Archive-path → displayable URL map for media + poster frames. */
+    readonly mediaDataUrls: _angular_core.WritableSignal<Map<string, string>>;
+    /** True while a load is in flight. */
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    /** Error message from the last failed load, or null. */
+    readonly error: _angular_core.WritableSignal<string | null>;
+    /** True when the file is password-protected and could not be opened. */
+    readonly isEncrypted: _angular_core.WritableSignal<boolean>;
+    /** Number of loaded slides. */
+    readonly slideCount: _angular_core.Signal<number>;
+    private handler;
+    private renderToken;
+    private activeBlobUrls;
+    constructor();
+    /** Serialise the current presentation back to `.pptx` bytes. */
+    getContent(): Promise<Uint8Array>;
+    /** Parse the supplied `.pptx` bytes into the reactive signals. */
+    load(raw: Uint8Array | ArrayBuffer | null | undefined): Promise<void>;
+    private disposeHandler;
+    private revokeBlobUrls;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<LoadContentService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<LoadContentService>;
+}
+
+/**
+ * PowerPointViewerComponent — Angular port of the React `PowerPointViewer.tsx`
+ * and Vue `PowerPointViewer.vue`.
+ *
+ * Top-level orchestrator that loads `.pptx` bytes and renders the slides with
+ * navigation and zoom. This is the viewer-first milestone of the port: the
+ * React component additionally composes a full editor (toolbar, inspector
+ * panels, dialogs, presentation mode, collaboration, export). The roadmap and
+ * per-area status live in `packages/angular/PORTING.md`.
+ *
+ * Conventions vs. React/Vue:
+ *  - React `forwardRef` handle / Vue `defineExpose` → public {@link getContent}
+ *    method (reach it via a template ref or `viewChild`).
+ *  - React callback props / Vue emits → Angular `output()` events.
+ *  - React theme context / Vue provide-inject → `themeStyle` CSS vars applied to
+ *    the root element (app-wide sharing via `provideViewerTheme`).
+ */
+declare class PowerPointViewerComponent {
+    /** PowerPoint content as Uint8Array (or ArrayBuffer). */
+    readonly content: _angular_core.InputSignal<ArrayBuffer | Uint8Array<ArrayBufferLike> | null>;
+    /** Whether editing actions are enabled. (Editor chrome not yet ported.) */
+    readonly canEdit: _angular_core.InputSignal<boolean>;
+    /** Optional class applied to the root element. */
+    readonly class: _angular_core.InputSignal<string>;
+    /** Theme configuration for customising the viewer's appearance. */
+    readonly theme: _angular_core.InputSignal<ViewerTheme | undefined>;
+    /** Optional real-time collaboration config (accepted for API parity; not yet implemented). */
+    readonly collaboration: _angular_core.InputSignal<CollaborationConfig | undefined>;
+    /** Fired when the active slide changes. */
+    readonly activeSlideChange: _angular_core.OutputEmitterRef<number>;
+    /** Fired when the unsaved-changes flag toggles. (Editing not yet ported.) */
+    readonly dirtyChange: _angular_core.OutputEmitterRef<boolean>;
+    /** Fired when the in-memory content changes after edits. (Editing not yet ported.) */
+    readonly contentChange: _angular_core.OutputEmitterRef<Uint8Array<ArrayBufferLike>>;
+    protected readonly loader: LoadContentService;
+    protected readonly activeSlideIndex: _angular_core.WritableSignal<number>;
+    protected readonly slideCount: _angular_core.Signal<number>;
+    protected readonly activeSlide: _angular_core.Signal<pptx_viewer_core.PptxSlide>;
+    protected readonly rootStyle: _angular_core.Signal<Record<string, string>>;
+    protected readonly zoom: _angular_core.WritableSignal<number>;
+    protected readonly zoomPercent: _angular_core.Signal<number>;
+    constructor();
+    /** Serialise the current presentation to `.pptx` bytes (imperative handle). */
+    getContent(): Promise<Uint8Array>;
+    goTo(index: number): void;
+    goPrev(): void;
+    goNext(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomReset(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PowerPointViewerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PowerPointViewerComponent, "pptx-viewer", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "canEdit": { "alias": "canEdit"; "required": false; "isSignal": true; }; "class": { "alias": "class"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; "collaboration": { "alias": "collaboration"; "required": false; "isSignal": true; }; }, { "activeSlideChange": "activeSlideChange"; "dirtyChange": "dirtyChange"; "contentChange": "contentChange"; }, never, never, true, never>;
+}
+
+/**
+ * Basic, framework-agnostic style computation for slide elements, returning
+ * `[ngStyle]`-compatible maps.
+ *
+ * This mirrors the Vue package's `element-style.ts` (and a deliberately small
+ * subset of the React `viewer/utils/*` style layer). It is enough to position
+ * and paint text boxes, basic preset shapes, and images. Advanced visuals
+ * (gradients, custom geometry clip-paths, shadows, 3D, image effects, text
+ * warp) are tracked in PORTING.md.
+ *
+ * Long term the *logic* here is a shared-extraction candidate — only the
+ * return type (CSS map shape) differs per framework — so a future refactor
+ * could hoist a neutral core into `pptx-viewer-shared`.
+ */
+/** `[ngStyle]`-compatible style map. */
+type StyleMap = Record<string, string | number>;
+/**
+ * Absolute container style: position, size, rotation, flip, opacity, z-index.
+ * Mirrors the essentials of the React `getContainerStyle`.
+ */
+declare function getContainerStyle(el: PptxElement, zIndex: number): StyleMap;
+/**
+ * Fill / stroke / corner-radius for shape-like elements. Returns an empty
+ * object when the element carries no shape styling.
+ */
+declare function getShapeFillStrokeStyle(el: PptxElement): StyleMap;
+/**
+ * Text block style for elements that carry text. Mirrors the essentials of the
+ * React `getTextStyleForElement`.
+ */
+declare function getTextBlockStyle(el: PptxElement): StyleMap;
+/** Resolve a displayable image source for picture/image/media poster frames. */
+declare function getImageSrc(el: PptxElement, mediaDataUrls: Map<string, string>): string | undefined;
+
+/**
+ * SlideCanvasComponent — Angular port of the React `SlideCanvas.tsx` and Vue
+ * `SlideCanvas.vue` (viewer-first subset).
+ *
+ * Renders the active slide as a fixed-size stage scaled by `zoom`, with each
+ * element absolutely positioned. The React version additionally layered in
+ * rulers, grid, guides, marquee/selection, connector-creation, drawing, and
+ * collaboration overlays — all tracked in PORTING.md.
+ */
+declare class SlideCanvasComponent {
+    readonly slide: _angular_core.InputSignal<PptxSlide | undefined>;
+    readonly canvasSize: _angular_core.InputSignal<CanvasSize>;
+    readonly mediaDataUrls: _angular_core.InputSignal<Map<string, string>>;
+    readonly zoom: _angular_core.InputSignal<number>;
+    readonly elements: _angular_core.Signal<pptx_viewer_core.PptxElement[]>;
+    readonly wrapperStyle: _angular_core.Signal<StyleMap>;
+    readonly stageStyle: _angular_core.Signal<StyleMap>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SlideCanvasComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SlideCanvasComponent, "pptx-slide-canvas", never, { "slide": { "alias": "slide"; "required": false; "isSignal": true; }; "canvasSize": { "alias": "canvasSize"; "required": true; "isSignal": true; }; "mediaDataUrls": { "alias": "mediaDataUrls"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface TextRun {
+    text: string;
+    style: StyleMap;
+}
+/**
+ * ElementRendererComponent — Angular port of the React `ElementRenderer.tsx`
+ * and the Vue `ElementRenderer.vue`.
+ *
+ * Renders a single slide element by its `type` discriminant (viewer-first
+ * subset):
+ *  - `text` / `shape`    → positioned box with fill/stroke + rich text
+ *  - `picture` / `image` → `<img>`
+ *  - `media`             → poster frame (`<img>`) — playback TODO
+ *  - `group`             → recursive children (self-referencing selector)
+ *  - everything else     → labelled placeholder (TODO, see PORTING.md)
+ *
+ * Interaction (selection, resize, inline editing), connectors, charts, tables,
+ * SmartArt, ink, OLE, and 3D are not yet ported.
+ */
+declare class ElementRendererComponent {
+    readonly element: _angular_core.InputSignal<PptxElement>;
+    readonly mediaDataUrls: _angular_core.InputSignal<Map<string, string>>;
+    readonly zIndex: _angular_core.InputSignal<number>;
+    readonly containerStyle: _angular_core.Signal<StyleMap>;
+    readonly shapeContainerStyle: _angular_core.Signal<StyleMap>;
+    readonly textStyle: _angular_core.Signal<StyleMap>;
+    readonly imageSrc: _angular_core.Signal<string | undefined>;
+    readonly children: _angular_core.Signal<PptxElement[]>;
+    readonly isShapeLike: _angular_core.Signal<boolean>;
+    readonly isImageLike: _angular_core.Signal<boolean>;
+    readonly paragraphs: _angular_core.Signal<TextRun[][]>;
+    readonly hasText: _angular_core.Signal<boolean>;
+    readonly placeholderLabel: _angular_core.Signal<string>;
+    private segmentStyle;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ElementRendererComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ElementRendererComponent, "pptx-element-renderer", never, { "element": { "alias": "element"; "required": true; "isSignal": true; }; "mediaDataUrls": { "alias": "mediaDataUrls"; "required": false; "isSignal": true; }; "zIndex": { "alias": "zIndex"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Theme system for the Angular PowerPoint viewer.
+ *
+ * Angular counterpart of the React `ViewerThemeProvider` / `useViewerTheme`
+ * context and the Vue `provide`/`inject` theme provider. The `ViewerTheme`
+ * type, default palette, and `themeToCssVars` helper are framework-agnostic
+ * and live in `pptx-viewer-shared`.
+ */
+/** DI token carrying the active `ViewerTheme` (or `undefined`). */
+declare const VIEWER_THEME: InjectionToken<ViewerTheme | undefined>;
+/**
+ * Provide a `ViewerTheme` to a subtree.
+ *
+ * Typically you do **not** need this — passing a `theme` input to
+ * `<pptx-viewer>` is sufficient. Use this to share a theme across multiple
+ * viewers or a wider component subtree.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideViewerTheme({ colors: { primary: '#6366f1' } })],
+ * });
+ * ```
+ */
+declare function provideViewerTheme(theme: ViewerTheme | undefined): Provider;
+/**
+ * Build an `[ngStyle]`-compatible map of CSS custom properties for a theme.
+ * Returns an empty object when the theme contributes no variables.
+ */
+declare function themeStyle(theme: ViewerTheme | undefined): Record<string, string>;
+
+/**
+ * Join class values into a single space-separated string, skipping falsy
+ * entries. A dependency-free analogue of the React/Vue packages' `cn`
+ * (clsx + tailwind-merge); the Angular viewer uses plain scoped CSS rather
+ * than Tailwind utility classes, so de-duplication is not required.
+ */
+type ClassValue = string | number | false | null | undefined;
+declare function cn(...values: ClassValue[]): string;
+
+export { DEFAULT_CANVAS_HEIGHT, DEFAULT_CANVAS_WIDTH, DEFAULT_FILL_COLOR, DEFAULT_STROKE_COLOR, DEFAULT_TEXT_COLOR, ElementRendererComponent, LoadContentService, PowerPointViewerComponent, SlideCanvasComponent, VIEWER_THEME, cn, defaultCssVars, defaultRadius, defaultThemeColors, getContainerStyle, getImageSrc, getShapeFillStrokeStyle, getTextBlockStyle, provideViewerTheme, themeStyle, themeToCssVars };
+export type { CanvasSize, ClassValue, CollaborationConfig, CollaborationRole, StyleMap, ViewerTheme, ViewerThemeColors };