@matboks/template-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./template.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./template.js";

package/dist/template.d.ts

@@ -0,0 +1,66 @@
+import { Resolution } from "@matboks/utilities";
+import { MakeOptionalRequiredIfIn } from "./types.js";
+import { Context } from "./utilities/context.js";
+type TemplateOptions = {
+    projectName: string;
+    aspectRatio?: number;
+    resolution?: number;
+    container?: HTMLElement;
+    animate?: boolean;
+    numFrames?: number;
+    fps?: number;
+    numLoops?: number;
+    enableSVGExport?: boolean;
+    seed?: number;
+};
+type DrawFunction = (data: Context) => void;
+type SetupFunction = (data: Context) => DrawFunction | void;
+declare const defaultOptions: {
+    aspectRatio: number;
+    container: HTMLElement;
+    animate: boolean;
+    fps: number;
+    numLoops: number;
+    enableSVGExport: true;
+    seed: number;
+};
+type OptionsWithDefaults = MakeOptionalRequiredIfIn<TemplateOptions, typeof defaultOptions>;
+export declare class Template {
+    options: OptionsWithDefaults;
+    canvas: HTMLCanvasElement;
+    rawCtx: CanvasRenderingContext2D;
+    get ctx(): CanvasRenderingContext2D;
+    setup?: SetupFunction;
+    draw?: DrawFunction;
+    private isSetup;
+    private isAnimating;
+    animationFrame: number;
+    realTime: number;
+    private previousTime;
+    resolution: Resolution;
+    seed: number;
+    isDebug: boolean;
+    rafId: number;
+    private templateContext;
+    private svgHandler?;
+    constructor(options: TemplateOptions);
+    static create(options: TemplateOptions): Template;
+    updateDocumentTitle(): void;
+    private getFrameInfo;
+    setupSVG(): void;
+    setOptionsToInitial(): void;
+    initialize(): void;
+    render(): void;
+    handleSetup(): void;
+    drawFrame(): void;
+    startAnimation(): void;
+    stopAnimation(): void;
+    finishAnimation(): void;
+    restart(): void;
+    setupResizeListener(): void;
+    resizeCanvas(): void;
+    private syncCanvasInternalResolution;
+    setupKeyListeners(): void;
+    getSVG(): string;
+}
+export {};

package/dist/template.js

@@ -0,0 +1,260 @@
+import { Resolution } from "@matboks/utilities";
+import { searchParams } from "./utilities/search-params.js";
+import { getMaximumAvailableResolution, savePNG, saveSVG, openCanvasInNewTab, createHTMLElements, assignDefined, setTheme, debounce } from "./utilities/helpers.js";
+import { context } from "./utilities/context.js";
+import { createSVGHandler } from "./utilities/svg.js";
+const defaultOptions = {
+    aspectRatio: 1,
+    container: document.body,
+    animate: false,
+    fps: 60,
+    numLoops: 1,
+    enableSVGExport: true,
+    seed: 0,
+};
+export class Template {
+    get ctx() { return this.options.enableSVGExport ? this.svgHandler.ctx2DProxy : this.rawCtx; }
+    constructor(options) {
+        this.isSetup = false;
+        this.isAnimating = false;
+        this.animationFrame = 0;
+        this.realTime = 0;
+        this.previousTime = null;
+        this.rafId = -1;
+        const parsedOptions = assignDefined(defaultOptions, options, {
+            seed: searchParams.get("seed", parseInt),
+            animate: searchParams.get("animate", (v) => v === "true"),
+            resolution: searchParams.get("resolution", parseInt)
+        });
+        this.options = parsedOptions;
+        this.isDebug = searchParams.get("debug", (v) => v === "true") ?? false;
+        this.updateDocumentTitle();
+    }
+    static create(options) {
+        const template = new Template(options);
+        template.initialize();
+        return template;
+    }
+    updateDocumentTitle() {
+        const { projectName } = this.options;
+        if (this.isAnimating) {
+            document.title = `${this.getFrameInfo()} - ${this.options.projectName}`;
+        }
+        else {
+            document.title = projectName;
+        }
+    }
+    getFrameInfo() {
+        const { animationFrame, options: { numFrames, numLoops } } = this;
+        if (numFrames) {
+            if (numLoops > 1) {
+                const currentLoop = Math.floor(animationFrame / (numFrames + 1)) + 1;
+                const currentFrame = (animationFrame + 1) % (numFrames + 1);
+                return `#${currentLoop} ${currentFrame} / ${numFrames}`;
+            }
+            else {
+                return `${animationFrame} / ${numFrames}`;
+            }
+        }
+        else {
+            return animationFrame.toString();
+        }
+    }
+    setupSVG() {
+        const svgHandler = createSVGHandler(this.rawCtx);
+        this.svgHandler = svgHandler;
+    }
+    setOptionsToInitial() {
+        const { seed, animate } = this.options;
+        this.seed = seed;
+        this.isAnimating = animate;
+    }
+    initialize() {
+        this.setOptionsToInitial();
+        const { container } = this.options;
+        const { root, canvas } = createHTMLElements();
+        setTheme(container);
+        container.append(root);
+        this.canvas = canvas;
+        this.rawCtx = this.canvas.getContext("2d");
+        // TODO Resize listener triggers initial render. Is this intuitive?
+        this.setupResizeListener();
+        this.setupKeyListeners();
+    }
+    render() {
+        // debugger
+        if (this.options.animate) {
+            this.startAnimation();
+        }
+        else {
+            requestAnimationFrame(() => this.drawFrame());
+        }
+    }
+    handleSetup() {
+        if (this.isSetup)
+            return;
+        this.rawCtx.reset();
+        if (this.options.enableSVGExport)
+            this.setupSVG();
+        this.templateContext = context(this);
+        const drawFunction = this.setup?.(this.templateContext);
+        this.isSetup = true;
+        if (drawFunction)
+            this.draw = drawFunction;
+    }
+    drawFrame() {
+        this.handleSetup();
+        const { previousTime, isAnimating } = this;
+        const currentTime = performance.now() / 1000;
+        if (isAnimating && previousTime && currentTime - previousTime < 1 / this.options.fps) {
+            this.rafId = requestAnimationFrame(() => this.drawFrame());
+            return;
+        }
+        if (previousTime)
+            this.realTime += currentTime - previousTime;
+        this.previousTime = currentTime;
+        this.draw?.(this.templateContext);
+        if (this.isAnimating) {
+            const { numFrames, numLoops } = this.options;
+            this.animationFrame++;
+            this.updateDocumentTitle();
+            if (numFrames && this.animationFrame === numFrames * numLoops) {
+                this.finishAnimation();
+            }
+            else {
+                this.rafId = requestAnimationFrame(() => this.drawFrame());
+            }
+        }
+        else {
+            document.complete = true;
+        }
+    }
+    startAnimation() {
+        this.rafId = requestAnimationFrame(() => this.drawFrame());
+        this.isAnimating = true;
+    }
+    stopAnimation() {
+        cancelAnimationFrame(this.rafId);
+        this.isAnimating = false;
+    }
+    finishAnimation() {
+        this.stopAnimation();
+        document.complete = true;
+    }
+    restart() {
+        this.stopAnimation();
+        this.isSetup = false;
+        this.animationFrame = 0;
+        this.realTime = 0;
+        this.previousTime = null;
+        this.render();
+    }
+    setupResizeListener() {
+        const { canvas } = this;
+        const containerResizeObserver = new ResizeObserver(debounce(() => this.resizeCanvas(), 100));
+        containerResizeObserver.observe(canvas.parentElement.parentElement);
+        this.resizeCanvas();
+    }
+    resizeCanvas() {
+        const { canvas, options } = this;
+        const frame = canvas.parentElement;
+        const { clientWidth, clientHeight } = frame.parentElement;
+        const framePadding = parseInt(getComputedStyle(frame).padding);
+        const { width, height } = getMaximumAvailableResolution(new Resolution(clientWidth - 2 * framePadding, clientHeight - 2 * framePadding), options.aspectRatio);
+        if (canvas.clientWidth === width && canvas.clientHeight === height)
+            return;
+        canvas.style.width = `${width}px`;
+        canvas.style.height = `${height}px`;
+        this.syncCanvasInternalResolution();
+    }
+    syncCanvasInternalResolution() {
+        const { canvas, options } = this;
+        let width, height;
+        if (!options.resolution) {
+            ({ width, height } = canvas.getBoundingClientRect());
+            width = Math.round(devicePixelRatio * width);
+            height = Math.round(devicePixelRatio * height);
+        }
+        else {
+            const { resolution, aspectRatio } = options;
+            [width, height] = aspectRatio > 1 ?
+                [resolution, resolution / aspectRatio] :
+                [aspectRatio * resolution, resolution];
+        }
+        canvas.width = width;
+        canvas.height = height;
+        this.resolution = new Resolution(width, height);
+        this.restart();
+    }
+    setupKeyListeners() {
+        const { canvas, seed, options } = this;
+        const getSeed = () => searchParams.get("seed", parseInt) ?? 0;
+        // TODO make syncronisation of values more robust (options and searchParams)
+        window.addEventListener("keydown", (event) => {
+            switch (event.key) {
+                case "a": {
+                    const animate = this.options.animate = searchParams.toggle("animate");
+                    if (animate) {
+                        this.startAnimation();
+                    }
+                    else {
+                        this.stopAnimation();
+                    }
+                    break;
+                }
+                case "n": {
+                    this.seed = searchParams.set("seed", getSeed() - 1);
+                    this.restart();
+                    break;
+                }
+                case "m": {
+                    this.seed = searchParams.set("seed", getSeed() + 1);
+                    this.restart();
+                    break;
+                }
+                case "d": {
+                    this.isDebug = searchParams.toggle("debug");
+                    break;
+                }
+                case "t": {
+                    // Darkmode
+                    const value = localStorage.getItem("theme");
+                    if (!value || value === "light") {
+                        this.options.container.classList.add("dark-template");
+                        localStorage.setItem("theme", "dark");
+                    }
+                    else {
+                        this.options.container.classList.remove("dark-template");
+                        localStorage.setItem("theme", "light");
+                    }
+                    break;
+                }
+                case "c": {
+                    this.setOptionsToInitial();
+                    searchParams.clearAll();
+                    this.restart();
+                    break;
+                }
+                case "s": {
+                    const filename = [options.projectName, seed, options.resolution].filter((v) => v).join("-");
+                    savePNG(filename, this);
+                    break;
+                }
+                case "v": {
+                    const filename = [options.projectName, seed].filter((v) => v).join("-");
+                    saveSVG(filename, this);
+                    break;
+                }
+                case "o": {
+                    openCanvasInNewTab(canvas);
+                    break;
+                }
+            }
+        });
+    }
+    getSVG() {
+        if (!this.svgHandler)
+            throw new Error("SVG is not enabled");
+        return this.svgHandler.getSVG();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type MakeOptionalRequiredIfIn<A, B> = Required<Pick<A, Extract<keyof A, keyof B> & {
+    [K in keyof A]-?: {} extends Pick<A, K> ? K : never;
+}[keyof A]>> & Omit<A, {
+    [K in keyof A]-?: {} extends Pick<A, K> ? (K extends keyof B ? K : never) : never;
+}[keyof A]>;

package/dist/types.js

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

package/dist/utilities/context.d.ts

@@ -0,0 +1,17 @@
+import { Template } from "../template.js";
+export declare function context(template: Template): {
+    template: Template;
+    ctx: CanvasRenderingContext2D;
+    clear: (backgroundStyle?: string) => void;
+    isolate: (fn: () => void) => void;
+    stopAnimation: () => void;
+    stopWhen: (condition: boolean) => void;
+    readonly frameTime: number;
+    readonly realTime: number;
+    readonly progress: number;
+    readonly frame: number;
+    readonly resolution: import("@matboks/utilities").Resolution;
+    readonly seed: number;
+    readonly isDebug: boolean;
+};
+export type Context = ReturnType<typeof context>;

package/dist/utilities/context.js

@@ -0,0 +1,49 @@
+import { mod } from "@matboks/utilities";
+// TODO differentiate between frameTime (frame / fps) and progressionTime (frame / numFrames)
+export function context(template) {
+    const { ctx, options } = template;
+    const isolate = (fn) => {
+        ctx.save();
+        fn();
+        ctx.restore();
+    };
+    const clear = (backgroundStyle) => {
+        const { width, height } = template.resolution;
+        isolate(() => {
+            ctx.resetTransform();
+            if (backgroundStyle) {
+                ctx.fillStyle = backgroundStyle;
+                ctx.fillRect(0, 0, width, height);
+            }
+            else {
+                ctx.clearRect(0, 0, width, height);
+            }
+        });
+    };
+    const stopAnimation = () => {
+        template.finishAnimation();
+    };
+    const stopWhen = (condition) => {
+        if (condition)
+            stopAnimation();
+    };
+    return {
+        template, ctx,
+        clear, isolate,
+        stopAnimation, stopWhen,
+        get frameTime() {
+            return template.animationFrame / options.fps;
+        },
+        get realTime() {
+            return template.realTime;
+        },
+        get progress() {
+            const { numFrames } = options;
+            return numFrames ? mod(template.animationFrame, numFrames) / numFrames : 0;
+        },
+        get frame() { return template.animationFrame; },
+        get resolution() { return template.resolution; },
+        get seed() { return template.seed; },
+        get isDebug() { return template.isDebug; }
+    };
+}

package/dist/utilities/helpers.d.ts

@@ -0,0 +1,18 @@
+import { Resolution } from "@matboks/utilities";
+import { Template } from "../template.js";
+export declare function getMaximumAvailableResolution(availableSpace: Resolution, aspectRatio: number): Resolution;
+export declare function savePNG(filename: string, template: Template): void;
+export declare function saveSVG(filename: string, template: Template): void;
+export declare function openCanvasInNewTab(canvas: HTMLCanvasElement): void;
+export declare function createHTMLElements(): {
+    root: HTMLDivElement;
+    canvas: HTMLCanvasElement;
+};
+type NonNullish<T> = Exclude<T, null | undefined>;
+type MergeDefined<T extends Record<PropertyKey, any>[], R = {}> = T extends [infer F, ...infer Rest] ? MergeDefined<Rest extends Record<PropertyKey, any>[] ? Rest : [], {
+    [K in keyof R | keyof F]: K extends keyof F ? NonNullish<F[K]> extends never ? R extends Record<K, any> ? R[K] : F[K] : NonNullish<F[K]> : R extends Record<K, any> ? R[K] : never;
+}> : R;
+export declare function assignDefined<const T extends Record<string, any>[]>(...objects: T): MergeDefined<T>;
+export declare function setTheme(container: HTMLElement): void;
+export declare function debounce(fn: () => void, ms: number): () => void;
+export {};

package/dist/utilities/helpers.js

@@ -0,0 +1,129 @@
+import { Resolution } from "@matboks/utilities";
+export function getMaximumAvailableResolution(availableSpace, aspectRatio) {
+    const { width: availableWidth, height: availableHeight } = availableSpace;
+    const [width, height] = (aspectRatio * availableHeight > availableWidth ?
+        [availableWidth, availableWidth / aspectRatio] :
+        [aspectRatio * availableHeight, availableHeight]).map(Math.round);
+    return new Resolution(width, height);
+}
+export function savePNG(filename, template) {
+    const link = document.createElement("a");
+    link.setAttribute('download', `${filename}.png`);
+    const data = template.canvas.toDataURL("image/png").replace("image/png", "image/octet-stream");
+    ;
+    link.setAttribute('href', data);
+    link.click();
+    link.remove();
+}
+export function saveSVG(filename, template) {
+    const link = document.createElement("a");
+    link.setAttribute('download', `${filename}.svg`);
+    const data = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(template.getSVG());
+    link.setAttribute('href', data);
+    link.click();
+    link.remove();
+}
+export function openCanvasInNewTab(canvas) {
+    const data = canvas.toDataURL("png");
+    const img = new Image();
+    img.src = data;
+    const newWindow = window.open();
+    img.style.maxHeight = "100%";
+    newWindow.document.body.style.margin = "0";
+    newWindow.document.body.innerHTML = img.outerHTML;
+}
+export function createHTMLElements() {
+    const cssId = "_" + crypto.randomUUID().slice(0, 8);
+    const template = document.createElement("template");
+    template.innerHTML = `
+    <div class="template ${cssId}">
+      <div class="container ${cssId}">
+        <div class="frame ${cssId}">
+          <canvas class="canvas ${cssId}"></canvas>
+        </div>
+      </div>
+    </div>
+    `;
+    const styleElement = document.createElement("style");
+    styleElement.textContent = `
+    
+
+    .template.${cssId} {
+      box-sizing: border-box;
+      width: 100dvw;
+      height: 100dvh;
+
+      background-color: var(--background-color);
+      padding-inline: 5dvw;
+      padding-block: 5dvh;
+
+      display: flex;
+      justify-content: center;
+      align-items: center;
+    }
+
+    :root {
+      --background-color: #fafafa;
+    }
+
+    .dark-template {
+      --background-color: #1a191e;
+    }
+
+    .container.${cssId} {
+      width: 100%;
+      height: 100%;
+
+      display: flex;
+      justify-content: center;
+      align-items: center;
+    }
+
+    .frame.${cssId} {
+      display: flex;
+      box-shadow: 0 0 15px rgba(0, 0, 0, 0.15);
+
+      padding: 10px;
+
+      background-color: white;
+    }
+
+    .canvas.${cssId} {
+      outline: 1px solid rgba(0, 0, 0, 0.07);
+    }
+  `;
+    document.head.appendChild(styleElement);
+    const root = template.content.children[0];
+    const canvas = root.querySelector("canvas");
+    return { root, canvas };
+}
+// Like Object.assign, but does not overwrite defined values with null or undefined
+export function assignDefined(...objects) {
+    const result = {};
+    for (const obj of objects) {
+        for (const key in obj) {
+            const value = obj[key];
+            if (value !== null && value !== undefined) {
+                result[key] = value;
+            }
+            else if (!(key in result)) {
+                // Keep initial null/undefined only if no earlier non-nullish existed
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+export function setTheme(container) {
+    if (localStorage.getItem("theme") === "dark") {
+        container.classList.add("dark-template");
+    }
+}
+export function debounce(fn, ms) {
+    let timeoutId = null;
+    return function () {
+        if (timeoutId !== null)
+            clearTimeout(timeoutId);
+        timeoutId = window.setTimeout(fn, ms);
+    };
+}

package/dist/utilities/search-params.d.ts

@@ -0,0 +1,10 @@
+export declare class SearchParams {
+    url: URL;
+    get(name: string): string | null;
+    get<R>(name: string, parser: (value: string) => R): R | null;
+    clearAll(): void;
+    pushToHistory(): void;
+    toggle(name: string): boolean;
+    set<T>(name: string, value: T): T;
+}
+export declare const searchParams: SearchParams;

package/dist/utilities/search-params.js

@@ -0,0 +1,48 @@
+export class SearchParams {
+    constructor() {
+        this.url = new URL(window.location.toString());
+    }
+    get(name, parser) {
+        const value = this.url.searchParams.get(name);
+        if (!value)
+            return null;
+        if (parser) {
+            return parser(value);
+        }
+        return value;
+    }
+    clearAll() {
+        this.url.search = "";
+        this.pushToHistory();
+    }
+    pushToHistory() {
+        const path = this.url.toString();
+        window.history.pushState({ path }, "", path);
+    }
+    toggle(name) {
+        const { searchParams } = this.url;
+        let state;
+        if (searchParams.get(name) === "true") {
+            searchParams.delete(name);
+            state = false;
+        }
+        else {
+            searchParams.set(name, "true");
+            state = true;
+        }
+        this.pushToHistory();
+        return state;
+    }
+    set(name, value) {
+        const { searchParams } = this.url;
+        if (value === null || value === undefined) {
+            searchParams.delete(name);
+        }
+        else {
+            searchParams.set(name, value.toString());
+        }
+        this.pushToHistory();
+        return value;
+    }
+}
+export const searchParams = new SearchParams();

package/dist/utilities/svg.d.ts

@@ -0,0 +1,13 @@
+import { Context as SVGContext } from "svgcanvas";
+type SVGCommand = (svgCtx: SVGContext) => void;
+export declare class SVGHandler {
+    svgCtx: SVGContext;
+    ctx2DProxy: CanvasRenderingContext2D;
+    drawCommands: Array<SVGCommand>;
+    constructor(ctx: CanvasRenderingContext2D);
+    pushCommand(command: SVGCommand): void;
+    private applyCommands;
+    getSVG(): string;
+}
+export declare function createSVGHandler(ctx: CanvasRenderingContext2D): SVGHandler;
+export {};

package/dist/utilities/svg.js

@@ -0,0 +1,77 @@
+// @ts-ignore
+import { Context as SVGContext } from "svgcanvas";
+export class SVGHandler {
+    constructor(ctx) {
+        this.drawCommands = [];
+        const { width, height } = ctx.canvas;
+        this.svgCtx = new SVGContext({ ctx, width, height });
+    }
+    pushCommand(command) {
+        this.drawCommands.push(command);
+    }
+    applyCommands() {
+        for (const command of this.drawCommands)
+            command(this.svgCtx);
+        this.drawCommands = [];
+    }
+    getSVG() {
+        this.applyCommands();
+        const { svgCtx } = this;
+        const svg = svgCtx.getSvg();
+        const scale = this.svgCtx.getTransform().a;
+        // Fix dash array not being scaled by transform. Note: lineDashOffset is not handled
+        for (const element of svg.querySelectorAll("[stroke-dasharray]")) {
+            const newValues = element.getAttribute("stroke-dasharray").split(",").map((v) => scale * parseFloat(v));
+            element.setAttribute("stroke-dasharray", newValues.join(","));
+        }
+        return svgCtx.getSerializedSvg();
+    }
+}
+export function createSVGHandler(ctx) {
+    const svgHandler = new SVGHandler(ctx);
+    svgHandler.ctx2DProxy = new Proxy(ctx, {
+        get(target, prop, receiver) {
+            // First retrieve the underlying value from the real canvas context
+            const value = Reflect.get(target, prop, receiver);
+            // If it's a function, wrap it so both contexts are called
+            if (typeof value === "function") {
+                return function (...args) {
+                    // Call original Canvas 2D method
+                    const result = value.apply(target, args);
+                    // Call SVG counterpart ONLY if it exists and is a function
+                    svgHandler.pushCommand((svgContext) => {
+                        const svgFn = svgContext[prop];
+                        if (typeof svgFn === "function") {
+                            svgFn.apply(svgContext, args);
+                        }
+                    });
+                    return result;
+                };
+            }
+            // Otherwise: plain property -> return the real property value
+            return value;
+        },
+        set(target, prop, newValue) {
+            // First update the original canvas context
+            target[prop] = newValue;
+            // Mirror to SVG context if that property exists
+            svgHandler.pushCommand((svgContext) => {
+                if (prop in svgContext) {
+                    try {
+                        // Some SVG context properties may be read-only -> guard with try
+                        svgContext[prop] = newValue;
+                    }
+                    catch {
+                        // silently ignore if readonly
+                    }
+                }
+            });
+            return true;
+        },
+        has(target, prop) {
+            // Behave like a normal CanvasRenderingContext2D
+            return prop in target;
+        }
+    });
+    return svgHandler;
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@matboks/template-core",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "devDependencies": {
+    "typescript": "~5.6.2",
+    "vite": "^6.0.1"
+  },
+  "dependencies": {
+    "svgcanvas": "^2.6.0",
+    "@matboks/utilities": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}