presenter 0.2.1 → 0.2.3

package/README.md

@@ -6,17 +6,35 @@ This library is still in development and its API may change at any time.
 
 ## Getting Started
 
-### Installing Presenter.js
+### Quick Start
 
-Install Presenter.js via `npm`.
+The simplest way to get started with a Presenter.js presentation is via
+`npm create presenter`.
 
+```bash
+$ npm create presenter
 ```
+
+Running `npm create presenter` will prompt you to enter a project name and will
+then create a new presentation with Presenter.js, written in TypeScript and
+built with Webpack.
+
+After creating the new presentation, `cd` into the directory and run
+`npm run serve` to run the presentation. Edit `src/index.ts` to make changes
+to your presentation.
+
+### Installing Presenter.js Manually
+
+Presenter.js can also be installed manually via `npm`.
+
+```bash
 $ npm install presenter
 ```
 
 ### Sample Usage
 
-Create a presentation by specifying a list of slides, where each slide may contain objects and animations.
+Create a presentation by specifying a list of slides, where each slide may
+contain objects and animations.
 
 ```javascript
 import { Presentation, Slide, Text } from "presenter";

package/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./presentation/presentation";
+export * from "./presentation/slide";
+export * from "./presentation/object";
+export * from "./objects/arrow";
+export * from "./objects/group";
+export * from "./objects/image";
+export * from "./objects/line";
+export * from "./objects/paragraph";
+export * from "./objects/polygon";
+export * from "./objects/text";
+export * from "./objects/rectangle";
+export * from "./objects/vectorGraphic";
+export * from "./util/animation";
+export * from "./util/position";
+export * from "./util/richText";

package/dist/src/objects/arrow.d.ts

@@ -0,0 +1,36 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+import { AnimationProps } from "../util/animation";
+import { Position } from "../util/position";
+import { Line } from "./line";
+import { Polygon } from "./polygon";
+export interface ArrowProps extends ObjectProps {
+    start: Position;
+    end: Position;
+    color: string;
+    width: number;
+    arrowSize: number;
+}
+export declare class Arrow extends SlideObject<ArrowProps> {
+    line: Line | null;
+    arrowhead: Polygon | null;
+    constructor(props?: Partial<ArrowProps>);
+    tagName(): string;
+    /**
+     * Computes coordinates for the line and arrowhead of the arrow.
+     */
+    calculateShapes(props: ArrowProps): {
+        line: {
+            start: Position;
+            end: {
+                x: number;
+                y: number;
+            };
+        };
+        arrowhead: Position[];
+    };
+    children(): Node[];
+    /**
+     * Returns animations for changes in arrowhead.
+     */
+    animations(arrowProps: Partial<ArrowProps>, animationParams?: anime.AnimeParams): AnimationProps[];
+}

package/dist/src/objects/group.d.ts

@@ -0,0 +1,16 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+export interface GroupProps extends ObjectProps {
+    /**
+     * A positioned group places the group's anchor at a particular coordinate.
+     * A non-positioned group uses the position as an offset for its children.
+     */
+    positioned: boolean;
+    objects: SlideObject<any>[];
+}
+export declare class Group extends SlideObject<GroupProps> {
+    constructor(objects: SlideObject<any>[], props?: Partial<GroupProps>, positioned?: boolean | null);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+    additionalAttributes(): Partial<Record<string, string>>;
+    children(): Node[];
+}

package/dist/src/objects/image.d.ts

@@ -0,0 +1,11 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+export interface ImageProps extends ObjectProps {
+    href: string;
+    width: number;
+    height: number;
+}
+export declare class Image extends SlideObject<ImageProps> {
+    constructor(href: string, props?: Partial<ImageProps>);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+}

package/dist/src/objects/line.d.ts

@@ -0,0 +1,13 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+import { Position } from "../util/position";
+export interface LineProps extends ObjectProps {
+    start: Position;
+    end: Position;
+    color: string;
+    width: number;
+}
+export declare class Line extends SlideObject<LineProps> {
+    constructor(props?: Partial<LineProps>);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+}

package/dist/src/objects/paragraph.d.ts

@@ -0,0 +1,17 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+export interface ParagraphProps extends ObjectProps {
+    content: string | string[];
+    width: number;
+    height: number;
+    fontSize: number;
+    fontFamily: string;
+    color: string;
+}
+export declare class Paragraph extends SlideObject<ParagraphProps> {
+    constructor(content: string | string[], props?: Partial<ParagraphProps>);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+    children(): Node[];
+    additionalAttributes(): Partial<Record<string, string>>;
+    requiresChildrenUpdate(props: Partial<ParagraphProps>): boolean;
+}

package/dist/src/objects/polygon.d.ts

@@ -0,0 +1,13 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+import { Position } from "../util/position";
+export interface PolygonProps extends ObjectProps {
+    points: Position[];
+    fill: string;
+    borderWidth: number;
+    borderColor: string;
+}
+export declare class Polygon extends SlideObject<PolygonProps> {
+    constructor(points: Position[], props?: Partial<PolygonProps>);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+}

package/dist/src/objects/rectangle.d.ts

@@ -0,0 +1,14 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+export interface RectangleProps extends ObjectProps {
+    fill: string;
+    width: number;
+    height: number;
+    rounding: number;
+    borderWidth: number;
+    borderColor: string;
+}
+export declare class Rectangle extends SlideObject<RectangleProps> {
+    constructor(props?: Partial<RectangleProps>);
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+}

package/dist/src/objects/text.d.ts

@@ -0,0 +1,29 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+import { RichTextSpan } from "../util/richText";
+export type TextContent = string | (string | RichTextSpan[])[];
+export interface TextProps extends ObjectProps {
+    content: TextContent;
+    fontStyle: string;
+    fontWeight: string | number;
+    fontSize: number;
+    fontFamily: string;
+    color: string;
+    dominantBaseline: string;
+    textDecoration: string;
+    align: "left" | "center" | "right";
+    lineSpacing: string;
+}
+export declare class Text extends SlideObject<TextProps> {
+    constructor(content: TextContent, props?: Partial<TextProps>);
+    isRichText(): boolean;
+    tagName(): string;
+    attributes(): Partial<Record<string, string>>;
+    /**
+     * Text elements return position as additional attributes since computing text
+     * size and position requires other properties to be set first.
+     */
+    additionalAttributes(): Partial<Record<string, string>>;
+    styles(): Partial<Record<string, string>>;
+    children(): Node[];
+    requiresChildrenUpdate(props: Partial<TextProps>): boolean;
+}

package/dist/src/objects/vectorGraphic.d.ts

@@ -0,0 +1,14 @@
+import { ObjectProps, SlideObject } from "../presentation/object";
+export interface VectorGraphicProps extends ObjectProps {
+    svg: string;
+    width: number;
+    height: number;
+}
+export declare class VectorGraphic extends SlideObject<VectorGraphicProps> {
+    parsedChildren: Node[];
+    constructor(svg: string, props?: Partial<VectorGraphicProps>);
+    tagName(): string;
+    createElement(): SVGElement;
+    attributes(): Partial<Record<string, string>>;
+    children(): Node[];
+}

package/dist/src/presentation/object.d.ts

@@ -0,0 +1,122 @@
+import { BoundingBox, Position } from "../util/position";
+import { Presentation } from "./presentation";
+import { AnimationProps, BuildFunction } from "../util/animation";
+export interface ObjectProps {
+    position: Position | null;
+    opacity?: number;
+    anchor: "topleft" | "top" | "topright" | "left" | "center" | "right" | "bottomleft" | "bottom" | "bottomright";
+}
+export declare class SlideObject<Props extends ObjectProps> {
+    /**
+     * Starting values for each property.
+     */
+    initialProps: Props;
+    /**
+     * Current values for each property.
+     */
+    props: Props;
+    _presentation: Presentation | null;
+    _element: SVGElement | null;
+    _children: Node[];
+    /**
+     * Initializes a new object to include on a slide.
+     * @param props Object properties.
+     */
+    constructor(props: Partial<Props>);
+    /**
+     * Returns the tag name of the element.
+     * @returns Tag name.
+     */
+    tagName(): string;
+    /**
+     * Returns the DOM attributes that should be set for the element.
+     * @returns Object with attribute names and values.
+     */
+    attributes(): Partial<Record<string, string>>;
+    /**
+     * Returns additional DOM attributes to be set for the element.
+     * Some attributes can't be computed until after an element's other properties are set:
+     * e.g. text position depends on content and font size.
+     * Additional attributes are computed after all other attributes, styles, and children.
+     * @returns Object with attribute names and values.
+     */
+    additionalAttributes(): Partial<Record<string, string>>;
+    /**
+     * Returns the styles that should be set for the element.
+     * @returns Object with style names and values.
+     */
+    styles(): Partial<Record<string, string>>;
+    /**
+     * Returns the children that should be rendered for the object.
+     * @returns Array of SVG elements.
+     */
+    children(): Node[];
+    /**
+     * Given a set of prop updates, checks if the children of the object need to be updated.
+     * @param props Properties to update.
+     * @returns Boolean indicating whether children need to be updated.
+     */
+    requiresChildrenUpdate(props: Partial<Props>): boolean;
+    /**
+     * Given a particular initial bounding box, returns the DOM position attributes that should be set for the element.
+     * @param bbox Bounding box.
+     * @returns Object with attribute names and values.
+     */
+    positionAttributes(bbox: BoundingBox): any;
+    /**
+     * Re-generates the SVG element for the object.
+     * @param presentation Presentation object.
+     * @returns SVG element.
+     */
+    generate(presentation: Presentation): SVGElement;
+    /**
+     * Creates a new HTML element for the object.
+     */
+    createElement(): SVGElement;
+    /**
+     * Returns the element for the object.
+     * @returns SVG element.
+     */
+    element(): SVGElement;
+    /**
+     * Returns an animation to perform.
+     * @param props Properties of object to change.
+     * @param animationParams Animation behavior parameters.
+     * @returns Animation properties.
+     */
+    animation(props: Partial<Props>, animationParams?: anime.AnimeParams, delay?: number | null, animate?: boolean): AnimationProps;
+    /**
+     * Returns an update animation that skips the animation and just performs the change.
+     * @param props Properties of object to change.
+     */
+    update(props: Partial<Props>, delay?: number | null): AnimationProps;
+    /**
+     * Performs an animation on the object.
+     */
+    animate(props: Partial<Props>, animationParams?: anime.AnimeParams): BuildFunction;
+    /**
+     * Sets properties of the object.
+     */
+    set(props: Partial<Props>): BuildFunction;
+    /**
+     * Animates a movement of the object.
+     */
+    move(position: Position, animationParams?: anime.AnimeParams): BuildFunction;
+    /**
+     * Allow for x and y values to be interpreted as percentages of total width/height.
+     */
+    positionInPresentation(position: Position): Position;
+    /**
+     * Adjusts a bounding box to be anchored given the object's vertical and horizontal anchor settings.
+     * @param bbox Bounding box to anchor.
+     * @returns Anchored bounding box.
+     */
+    anchorBoundingBox(bbox: BoundingBox): BoundingBox;
+    /**
+     * Computes a bounding box for a given element given its rendered size and defined position.
+     * @param element Element for which to compute size.
+     * @param children Custom children to use when computing bounding box.
+     * @returns
+     */
+    computeRenderedBoundingBox(element: SVGGraphicsElement, children?: Node[] | null): BoundingBox;
+}

package/dist/src/presentation/presentation.d.ts

@@ -0,0 +1,99 @@
+import { BoundingBox } from "../util/position";
+import { Slide } from "./slide";
+export interface PresentationOptions {
+    /**
+     * Width of the presentation.
+     */
+    width: number;
+    /**
+     * Height of the presentation.
+     */
+    height: number;
+    /**
+     * Slide color for the presentation.
+     */
+    backgroundColor: string;
+}
+interface PresentationState {
+    currentSlide: number;
+}
+export declare class Presentation {
+    /**
+     * Title of the presentation.
+     */
+    title: string;
+    /**
+     * Element where presentation should be mounted.
+     */
+    element: HTMLElement;
+    /**
+     * SVG container element.
+     */
+    container: HTMLElement;
+    /**
+     * Parent SVG element of presentation.
+     */
+    svg: SVGSVGElement | null;
+    /**
+     * Shadow SVG element, not displayed and used for calculating sizes.
+     */
+    shadow: SVGSVGElement | null;
+    /**
+     * Presentation settings.
+     */
+    options: PresentationOptions;
+    /**
+     * Bounds of presentation.
+     */
+    boundingBox: BoundingBox;
+    /**
+     * Presentation slides.
+     */
+    slides: Slide[];
+    /**
+     * Presentation state.
+     */
+    presentationState: PresentationState;
+    /**
+     *
+     * @param title Title of the presentation.
+     */
+    constructor(title: string, slides: Slide[], element: HTMLElement, options?: Partial<PresentationOptions>);
+    present(): void;
+    /**
+     * Sets up keyboard commands for the presentation.
+     */
+    setupKeyboardCommands(): void;
+    /**
+     * Updates the size of the parent SVG element.
+     *
+     * The size of the parent SVG element needs to be updated.
+     */
+    updateSVGContainerSize(): void;
+    /**
+     * Advances to next animation in slide, or next slide if there is no next animation.
+     * Returns true if we were able to successfully advance.
+     * @param includeIntermediateBuilds Determines whether to progress through builds.
+     */
+    next(includeIntermediateBuilds: boolean): boolean;
+    /**
+     * Goes back to the previous slide.
+     * @param includeIntermediateBuilds Determines whether to progress through builds.
+     */
+    previous(includeIntermediateBuilds: boolean): void;
+    /**
+     * Checks if the presentation takes the entire document body.
+     * @returns True if the presentation takes the entire document body.
+     */
+    isFullBodyPresentation(): boolean;
+    /**
+     * Computes the current size of an element in the DOM.
+     * Optionally accepts a custom list of children to see what the size of an
+     * element would be with different children.
+     * @param element Element to compute size of.
+     * @param children Custom children to use for element.
+     * @returns BoundingBox
+     */
+    computeRenderedBoundingBox(element: SVGGraphicsElement, children?: Node[] | null): BoundingBox;
+}
+export {};

package/dist/src/presentation/slide.d.ts

@@ -0,0 +1,23 @@
+import { BuildFunction } from "../util/animation";
+import { SlideObject } from "./object";
+import { Presentation } from "./presentation";
+export interface SlideProps {
+}
+export declare class Slide {
+    objects: SlideObject<any>[];
+    animations: BuildFunction[];
+    animationIndex: number;
+    /**
+     * Property for use during development/debugging only.
+     * Manually set this property to a build function index
+     * to debug a specific animation.
+     */
+    debugAnimation: number | null;
+    constructor(objects: SlideObject<any>[], animations?: BuildFunction[]);
+    render(presentation: Presentation, animationIndex?: number): void;
+    nextAnimation(presentation: Presentation): boolean;
+    /**
+     * Sleep for a specified number of milliseconds in an animation.
+     */
+    sleep(ms: number): Promise<unknown>;
+}

package/dist/src/util/animation.d.ts

@@ -0,0 +1,37 @@
+import anime from "animejs/lib/anime.es.js";
+/**
+ * Data needed to process an animation.
+ */
+export interface AnimationProps {
+    /**
+     * Whether to animate the change.
+     */
+    animate?: boolean;
+    element?: HTMLElement | SVGElement;
+    attributes?: Record<string, string>;
+    styles?: Record<string, string>;
+    animationParams?: anime.AnimeParams;
+    children?: Node[];
+    /**
+     * Delay, in milliseconds.
+     */
+    delay?: number;
+}
+/**
+ * Function that performs an animation on an element.
+ */
+export type Animator = (props: AnimationProps | AnimationProps[]) => Promise<void>;
+/**
+ * Function that possibly applies a sequence of animations.
+ */
+export type BuildFunction = (animate: Animator) => void;
+/**
+ * Perform an animation on an element.
+ * @param props Animation properties.
+ */
+export declare const performAnimation: Animator;
+/**
+ * Performs animations by skipping the animation duration and jumping to end of animation.
+ * @param props Animation properties.
+ */
+export declare const skipAnimation: Animator;

package/dist/src/util/position.d.ts

@@ -0,0 +1,11 @@
+export interface Position {
+    x: number;
+    y: number;
+}
+export declare class BoundingBox {
+    origin: Position;
+    width: number;
+    height: number;
+    constructor(origin: Position, width: number, height: number);
+    static fromElement(element: SVGGraphicsElement): BoundingBox;
+}

package/dist/src/util/richText.d.ts

@@ -0,0 +1,18 @@
+export interface RichTextProps {
+    fontStyle?: string;
+    fontWeight?: string | number;
+    fontSize?: number;
+    fontFamily?: string;
+    textDecoration?: string;
+    color?: string;
+    dy?: number;
+}
+export type RichTextSpan = string | [string, RichTextProps];
+/**
+ * Creates a text node with spaces replaced by non-breaking spaces.
+ */
+export declare function createSpacePreservingTextNode(text: string): Text;
+/**
+ * Given rich text configuration, returns the corresponding tspan nodes.
+ */
+export declare function generateTextNodes(lines: (string | RichTextSpan[])[], lineSpacing?: string, anchor?: "start" | "middle" | "end"): Node[];

package/dist/webpack.config.d.ts

@@ -17,6 +17,6 @@ export namespace module {
     let rules: {
         test: RegExp;
         use: string;
-        exclude: RegExp;
+        exclude: RegExp[];
     }[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "presenter",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A JavaScript presentation library",
   "main": "dist/presenter.js",
   "types": "dist/src/index.d.ts",
@@ -19,6 +19,13 @@
     "url": "https://github.com/brianyu28/presenter/issues"
   },
   "homepage": "https://github.com/brianyu28/presenter#readme",
+  "license": "GPL-3.0-or-later",
+  "files": [
+    "./dist/"
+  ],
+  "dependencies": {
+    "animejs": "^3.2.2"
+  },
   "devDependencies": {
     "@types/animejs": "^3.1.12",
     "husky": "^9.1.7",
@@ -31,8 +38,5 @@
   },
   "lint-staged": {
     "**/*": "prettier --write --ignore-unknown"
-  },
-  "dependencies": {
-    "animejs": "^3.2.2"
   }
 }

package/.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

package/.prettierrc

@@ -1 +0,0 @@
-{}

package/dist/dist/presenter.d.ts

@@ -1 +0,0 @@
-export let Presenter: {};

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "declaration": true,
-    "outDir": "./dist/",
-    "noImplicitAny": true,
-    "module": "es6",
-    "moduleResolution": "node",
-    "target": "es5",
-    "allowJs": true
-  },
-  "exclude": ["./examples"]
-}

package/webpack.config.js

@@ -1,32 +0,0 @@
-const path = require("path");
-
-module.exports = {
-  mode: process.env.NODE_ENV || "development",
-  entry: "./src/index.ts",
-  output: {
-    filename: "presenter.js",
-    path: path.resolve(__dirname, "dist"),
-    library: "Presenter",
-    libraryTarget: "umd",
-    globalObject: "this",
-  },
-  watchOptions: {
-    ignored: [
-      "**/node_modules",
-      path.resolve(__dirname, "dist"),
-      path.resolve(__dirname, "examples"),
-    ],
-  },
-  resolve: {
-    extensions: [".ts", ".js"],
-  },
-  module: {
-    rules: [
-      {
-        test: /\.ts$/,
-        use: "ts-loader",
-        exclude: /node_modules/,
-      },
-    ],
-  },
-};