@netless/app-presentation 0.1.0-beta.0

package/README.md

@@ -0,0 +1,36 @@
+# @netless/app-presentation
+
+A [Netless App](https://github.com/netless-io/netless-app) that display multiple images as presentation slides.
+
+## Install
+
+<pre>npm add <strong>@netless/app-presentation</strong></pre>
+
+## Usage
+
+```js
+import { register } from "@netless/fastboard"
+import { install } from "@netless/app-presentation"
+
+install(register, { as: 'DocsViewer' })
+```
+
+## Develop
+
+See [Write you a Netless App](https://github.com/netless-io/fastboard/blob/main/docs/en/app.md).
+
+To only develop the UI part, run:
+
+```bash
+$ pnpm build
+$ pnpm dev
+```
+
+Then goto http://localhost:5173/ to see the app locally.
+
+To develop it in a real whiteboard room, add a file .env.local containing the room's uuid and token,
+then goto http://localhost:5173/e2e/.
+
+## License
+
+MIT @ [netless](https://github.com/netless-io)

package/build.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import * as rollup from 'rollup'
+import * as esbuild from 'esbuild'
+import * as dts from '@hyrious/dts'
+import * as SASS from 'sass'
+import { version, peerDependencies } from './package.json'
+import { createRequire } from 'node:module'
+
+const sass = (): esbuild.Plugin => ({
+  name: 'inline-sass',
+  setup({ onLoad, esbuild }) {
+    onLoad({ filter: /\.scss/ }, async args => {
+      if (args.suffix !== '?inline') return
+      const { css } = SASS.compile(args.path, { style: 'compressed' })
+      const { outputFiles } = await esbuild.build({
+        stdin: {
+          contents: css,
+          loader: 'css',
+          resolveDir: path.dirname(args.path),
+          sourcefile: args.path,
+        },
+        logLevel: 'silent',
+        bundle: true,
+        minify: true,
+        write: false,
+        outdir: 'dist',
+      })
+      const contents = outputFiles[0].text.trimEnd()
+      return { contents, loader: 'text' }
+    })
+  }
+})
+
+// vanilla-lazyload has "browser": "dist/file.min.js", which is not ESM
+// correct it by choosing the "module" field
+const lazyload = (): esbuild.Plugin => ({
+  name: 'lazyload',
+  setup({ onResolve }) {
+    const require = createRequire(import.meta.url)
+    onResolve({ filter: /^vanilla-lazyload$/ }, args => {
+      const cjs = require.resolve(args.path)
+      const esm = cjs.replace('lazyload.min.js', 'lazyload.esm.js')
+      return { path: esm }
+    })
+  }
+})
+
+fs.rmSync('dist', { recursive: true, force: true })
+
+let bundle = await rollup.rollup({
+  input: 'src/index.ts',
+  external: ['jspdf'],
+  plugins: [{
+    name: 'esbuild',
+    async load(id) {
+      const { outputFiles } = await esbuild.build({
+        entryPoints: [id],
+        bundle: true,
+        format: 'esm',
+        outfile: id.replace(/\.ts$/, '.js'),
+        sourcemap: true,
+        write: false,
+        target: ['es2017'],
+        plugins: [sass(), lazyload()],
+        define: {
+          __VERSION__: JSON.stringify(version)
+        },
+        external: Object.keys({
+          '@netless/window-manager': '*',
+          ...peerDependencies,
+        })
+      })
+      let code: any, map: any
+      for (const { path, text } of outputFiles) {
+        if (path.endsWith('.map')) map = text;
+        else code = text;
+      }
+      return { code, map }
+    }
+  }]
+})
+
+await Promise.all([
+  bundle.write({ file: 'dist/index.mjs', format: 'es', sourcemap: true, sourcemapExcludeSources: true }),
+  bundle.write({ file: 'dist/index.js', format: 'cjs', sourcemap: true, sourcemapExcludeSources: true, interop: 'auto', exports: 'named' }),
+  bundle.write({ file: 'dist/index.global.js', format: 'iife', name: 'NetlessAppPresentation', exports: 'named' }),
+])
+
+await bundle.close()
+
+// replace `import('jspdf')` in global js with `window.jspdf`
+let code = fs.readFileSync('dist/index.global.js', 'utf-8')
+code = code.replace(`await import('jspdf')`, `jspdf`)
+fs.writeFileSync('dist/index.global.js', code)
+
+if (process.env.DTS != '0')
+  await dts.build('src/index.ts', 'dist/index.d.ts', { exclude: ['@netless/window-manager'] })

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+import { View, AppContext, NetlessApp, WindowManager } from '@netless/window-manager';
+
+/**
+ * A function that can be called to dispose resources.
+ */
+type Disposer<T = any> = () => T;
+/**
+ * An object that has a `dispose` method to dispose resources.
+ */
+interface IDisposable<T = any> {
+    dispose(): T;
+}
+/**
+ * A union type of {@link Disposer} and {@link IDisposable} which can be called to dispose resources.
+ */
+type DisposableType<T = any> = Disposer<T> | IDisposable<T>;
+/**
+ * A combination of {@link Disposer} and {@link IDisposable}.
+ * It can be called to dispose resources or call the `dispose` method to dispose resources.
+ */
+interface DisposableDisposer<T = any> {
+    (): T;
+    dispose(): T;
+}
+
+/**
+ * A Disposable Store is an {@link IDisposable} that manages {@link Disposer}s and {@link IDisposable}s.
+ *
+ * All {@link Disposer}s and {@link IDisposable}s in the store will be invoked(`flush`) when the store is disposed.
+ *
+ * A {@link DisposableStore} is also a {@link Disposer}, which means it can be the `dispose` method of an {@link IDisposable}.
+ *
+ * A {@link DisposableStore} is also an {@link IDisposable}, which means it can be managed by another {@link DisposableStore}.
+ *
+ */
+interface DisposableStore extends DisposableDisposer {
+    /**
+     * Flush and clear all of the {@link Disposer}s and {@link IDisposable}s in the store.
+     */
+    (): void;
+    /**
+     * Get the number of {@link DisposableType}s in the store.
+     */
+    size(): number;
+    /**
+     * Add a {@link DisposableType} to the store.
+     *
+     * Do nothing if the {@link DisposableType} is already in the store.
+     *
+     * @param disposable A {@link DisposableType} .
+     * @returns The same {@link DisposableType} .
+     */
+    add<T extends DisposableType>(disposable: T): T;
+    /**
+     * Add multiple {@link DisposableType}s to the store.
+     *
+     * Do nothing if a {@link DisposableType} is already in the store.
+     *
+     * @param disposables An array of {@link DisposableType}s.
+     * @returns The same array of {@link DisposableType}s.
+     */
+    add<T extends DisposableType[]>(disposables: T): T;
+    /**
+     * Add each {@link DisposableType} to the store.
+     *
+     * Do nothing if a {@link DisposableType} is already in the store.
+     *
+     * @param disposables An array of {@link DisposableType}s.
+     * @returns The same array of {@link DisposableType}s.
+     */
+    add<T extends DisposableType>(disposables: T | T[]): T | T[];
+    /**
+     * Invoke the executor function and add the returned {@link DisposableType} to the store.
+     *
+     * Do nothing if the {@link DisposableType} is already in the store.
+     *
+     * @param executor A function that returns a {@link DisposableType}.
+     * @returns The returned {@link DisposableType}.
+     */
+    make<T extends DisposableType>(executor: () => T): T;
+    /**
+     * Invoke the executor function and add the returned {@link DisposableType} to the store.
+     *
+     * Do nothing if `null | undefined` is returned or the returned {@link DisposableType} is already in the store.
+     *
+     * @param executor A function that returns either a {@link DisposableType} or `null`.
+     * @returns The returned {@link DisposableType}, or `undefined` if the executor returns `null`.
+     */
+    make<T extends DisposableType>(executor: () => T | null | undefined | void): T | void;
+    /**
+     * Invoke the executor function and add each {@link DisposableType} in the returned array to the store.
+     *
+     * Do nothing if a {@link DisposableType} is already in the store.
+     *
+     * @param executor A function that returns an array of {@link DisposableType}s.
+     * @returns The returned array of {@link DisposableType}s.
+     */
+    make<T extends DisposableType[]>(executor: () => T): T;
+    /**
+     * Invoke the executor function and the returned {@link DisposableType}s to the store. Do nothing if `undefined | null` is returned.
+     *
+     * Do nothing if a {@link DisposableType} is already in the store.
+     *
+     * @param executor A function that returns either an array of {@link DisposableType}s or `undefined | null`.
+     * @returns The returned array of {@link DisposableType}s, or `undefined` if the executor returns `undefined | null`.
+     */
+    make<T extends DisposableType[]>(executor: () => T | null | void | undefined): T | void;
+    /**
+     * Invoke the executor function and the returned {@link DisposableType}s to the store. Do nothing if `undefined | null` is returned.
+     *
+     * Do nothing if a {@link DisposableType} is already in the store.
+     *
+     * @param executor A function that returns either an array of {@link DisposableType}s or `undefined | null`.
+     * @returns The returned array of {@link DisposableType}s, or `undefined` if the executor returns `undefined | null`.
+     */
+    make<T extends DisposableType>(executor: () => T | T[] | null | void | undefined): T | T[] | void;
+    /**
+     * Check if a {@link DisposableType} is in the store.
+     *
+     * @param disposable The {@link DisposableType}.
+     * @returns `true` if the {@link DisposableType} is in the store, otherwise `false`.
+     */
+    has(disposable: DisposableType): boolean;
+    /**
+     * Remove the {@link DisposableType} from the store. Does not invoke the removed {@link DisposableType}.
+     *
+     * @param disposable The {@link DisposableType} to be flushed.
+     * @returns `true` if the {@link DisposableType} is found and removed, otherwise `false`.
+     */
+    remove(disposable: DisposableType): boolean;
+    /**
+     * Invoke the {@link DisposableType} and remove it from the store at the specific key.
+     *
+     * @param disposable The {@link DisposableType} to be flushed. Flush all if omitted.
+     */
+    flush(disposable?: DisposableType): void;
+    /**
+     * Flush and clear all of the {@link Disposer}s and {@link IDisposable}s in the store.
+     */
+    dispose(this: void): void;
+}
+
+interface ILazyLoadInstance {
+  /**
+   * Make LazyLoad to re-check the DOM for `elements_selector` elements inside its `container`.
+   *
+   * ### Use case
+   *
+   * Update LazyLoad after you added or removed DOM elements to the page.
+   */
+  update: (elements?: NodeListOf<HTMLElement>) => void;
+
+  /**
+   * Destroys the instance, unsetting instance variables and removing listeners.
+   *
+   * ### Use case
+   *
+   * Free up some memory. Especially useful for Single Page Applications.
+   */
+  destroy: () => void;
+
+  /**
+   * Loads all the lazy elements right away and stop observing them,
+   * no matter if they are inside or outside the viewport,
+   * no matter if they are hidden or visible.
+   *
+   * ### Use case
+   *
+   * To load all the remaining elements in advance
+   */
+  loadAll: () => void;
+
+  /**
+   * Restores DOM to its original state. Note that it doesn't destroy LazyLoad,
+   * so you probably want to use it along with destroy().
+   *
+   * ### Use case
+   *
+   * Reset the DOM before a soft page navigation (SPA) occures, e.g. using TurboLinks.
+   */
+  restoreAll: () => void;
+
+  /**
+   * The number of elements that are currently downloading from the network
+   * (limitedly to the ones managed by the instance of LazyLoad).
+   * This is particularly useful to understand whether
+   * or not is safe to destroy this instance of LazyLoad.
+   */
+  loadingCount: number;
+
+  /**
+   * The number of elements that haven't been lazyloaded yet
+   * (limitedly to the ones managed by the instance of LazyLoad)
+   */
+  toLoadCount: number;
+}
+
+declare class Preload implements IDisposable {
+    readonly pages: PresentationPage[];
+    readonly links: HTMLLinkElement[];
+    head: number;
+    tail: number;
+    timer: number;
+    get done(): boolean;
+    constructor(pages: PresentationPage[]);
+    touch(index: number): void;
+    handler(): void;
+    dispose(): void;
+}
+
+interface PresentationPage {
+    src: string;
+    width: number;
+    height: number;
+    thumbnail?: string | undefined;
+}
+interface PresentationConfig {
+    readonly pages: PresentationPage[];
+    readonly readonly?: boolean;
+}
+/**
+ * Standalone presentation slide viewer.
+ *
+ * ```html
+ * <div class="netless-app-presentation">
+ *   <div class="netless-app-presentation-content netless-app-presentation-readonly">
+ *     <div class="netless-app-presentation-preview-mask"></div>
+ *     <div class="netless-app-presentation-preview">
+ *       <a class="netless-app-presentation-preview-page">
+ *         <img :data-src="thumbnail || src">
+ *         <span class="netless-app-presentation-preview-page-name">1</span>
+ *       </a>
+ *     </div>
+ *     <div class="netless-app-presentation-image">
+ *       <img :src="src">
+ *     </div>
+ *     <div class="netless-app-presentation-wb-view" style="pointer-events: auto"></div>
+ *   </div>
+ *   <div class="netless-app-presentation-footer netless-app-presentation-readonly">
+ *     <button class="netless-app-presentation-footer-btn netless-app-presentation-btn-sidebar">
+ *       <svg class="netless-app-presentation-footer-icon-sidebar"></svg>
+ *     </button>
+ *     <div class="netless-app-presentation-page-jumps">
+ *       <button-page-back />
+ *       <button-page-next />
+ *     </div>
+ *     <div class="netless-app-presentation-page-number">
+ *       <input class="netless-app-presentation-page-number-input">
+ *       <span> / 10</span>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ */
+declare class Presentation implements IDisposable<void> {
+    readonly namespace = "netless-app-presentation";
+    readonly dispose: DisposableStore;
+    readonly pages: PresentationPage[];
+    readonly preload: Preload;
+    dom: Element | DocumentFragment;
+    contentDOM: HTMLDivElement;
+    previewDOM: HTMLDivElement;
+    imageDOM: HTMLDivElement;
+    image: HTMLImageElement;
+    whiteboardDOM: HTMLDivElement;
+    footerDOM: HTMLDivElement;
+    pageNumberInputDOM: HTMLInputElement;
+    readonly: boolean;
+    initialized: boolean;
+    showPreview: boolean;
+    pageIndex: number;
+    previewLazyload: ILazyLoadInstance | null;
+    constructor(config: PresentationConfig);
+    initialize(): void;
+    setDOM(dom: Element | DocumentFragment): void;
+    setReadonly(readonly: boolean): void;
+    setPageIndex(pageIndex: number): void;
+    togglePreview(showPreview?: boolean): void;
+    onNewPageIndex(index: number, _origin: "navigation" | "keydown" | "input" | "preview"): void;
+    page(): PresentationPage | undefined;
+    updateImage(): void;
+    private c;
+    private isEditable;
+    private x_oss_process;
+}
+
+declare const __inline: string;
+
+type Logger = (...data: any[]) => void;
+interface PresentationAppOptions {
+    log?: Logger;
+}
+interface PresentationController {
+    readonly app: Presentation;
+    readonly view: View;
+    readonly context: AppContext;
+    /** Returns false if failed to jump (either because out of bounds or lack of permissions). */
+    jumpPage(index: number): boolean;
+    /** Returns false if failed to jump */
+    prevPage(): boolean;
+    /** Returns false if failed to jump */
+    nextPage(): boolean;
+    /** `index` ranges from 0 to `length - 1` */
+    pageState(): {
+        index: number;
+        length: number;
+    };
+    toPdf(): Promise<{
+        pdf: ArrayBuffer;
+        title: string;
+    } | null>;
+    log: Logger;
+}
+
+declare const NetlessAppPresentation: NetlessApp<{}, unknown, PresentationAppOptions, PresentationController>;
+type RegisterFn = typeof WindowManager["register"];
+interface InstallOptions {
+    /**
+     * Register as another "kind", to hijack existing apps.
+     * The default kind is "Presentation".
+     *
+     * @example "DocsViewer"
+     */
+    as?: string;
+}
+/**
+ * Call `register({ kind: "Presentation", src: NetlessAppPresentation })` to register this app.
+ * Optionally accepts an options object to override the default kind.
+ *
+ * @example install(register, { as: "DocsViewer" })
+ */
+declare const install: (register: RegisterFn, options?: InstallOptions) => Promise<void>;
+
+declare const version: string;
+
+export { type InstallOptions, type Logger, NetlessAppPresentation, Presentation, type PresentationAppOptions, type PresentationConfig, type PresentationController, type PresentationPage, type RegisterFn, NetlessAppPresentation as default, install, __inline as styles, version };