@dosgato/templating 0.0.1 → 0.0.4

package/dist/apitemplate.d.ts

@@ -0,0 +1,88 @@
+import { PageWithAncestors, ComponentData } from './component';
+import { LinkDefinition } from './links';
+export declare type APITemplateType = 'page' | 'component' | 'data';
+/**
+ * This interface lays out the structure the API needs for each template in the system.
+ */
+export interface APITemplate {
+    type: APITemplateType;
+    /**
+     * A unique string to globally identify this template across installations. Namespacing like
+     * edu.txstate.RichTextEditor could be useful but no special format is required.
+     */
+    templateKey: string;
+    /**
+     * Each template must declare its areas and the template keys of components that will be
+     * permitted inside each area. The list of allowed component templates can be updated beyond
+     * the list provided here. See templateRegistry.addAvailableComponent's comment for info on why.
+     */
+    areas: Record<string, string[]>;
+    /**
+     * Each template must provide a list of migrations for upgrading the data schema over time.
+     * Typically this will start as an empty array and migrations will be added as the template
+     * gets refactored.
+     */
+    migrations: Migration[];
+    /**
+     * Each template must provide a function that returns links from its data so that they
+     * can be indexed. Only fields that are links need to be returned. Links inside rich editor
+     * text will be extracted automatically from any text returned by getFulltext (see below)
+     */
+    getLinks: LinkGatheringFn;
+    /**
+     * Each template must provide the text from any text or rich editor data it possesses, so that
+     * the text can be decomposed into words and indexed for fulltext searches. Any text returned
+     * by this function will also be scanned for links.
+     */
+    getFulltext: FulltextGatheringFn;
+    /**
+     * Each template must provide a validation function so that the API can enforce its data is
+     * shaped properly. If there are no issues, it should return an empty object {}, otherwise it
+     * should return an object with keys that reference the path to the error and values that
+     * are an array of error messages pertaining to that path.
+     *
+     * For instance, if name is required and the user didn't provide one, you would return:
+     * { name: ['A name is required.'] }
+     *
+     * This method is async so that you can do things like look in the database for conflicting
+     * names.
+     */
+    validate: (data: any) => Promise<Record<string, string[]>>;
+    /**
+     * Hard-coded properties that may be set on page templates to influence the rendering of
+     * components on the page. For instance, a set of color choices that are customized for
+     * each template design. Components on the page may refer to the color information stored
+     * in the template during dialogs and while rendering. Changing to a different page template
+     * could then result in different color choices for components like buttons.
+     *
+     * Must be null for non-page templates.
+     */
+    templateProperties?: any;
+}
+/**
+ * In dosgato CMS, the data in the database is not altered except during user activity. This
+ * means that older records could have been saved when the schema expected by component
+ * rendering code was different than the date it's being rendered. To handle this, each
+ * page and component template is required to provide migrations responsible for
+ * transforming the data to the needed schema version.
+ *
+ * In order to support backwards compatibility, each API client will specify the date
+ * when the code was written, so that their assumptions about the schema will be
+ * frozen in time. This system means that migrations need to run backward as well as forward
+ * in time.
+ *
+ * The `up` method is for changing data from an older schema to a newer one. The
+ * `down` method is for changing data back from the newer schema to the older one.
+ * If a `down` method cannot be provided, the migration is considered to be a breaking
+ * change and anyone asking to rewind time to before the migration will receive an error.
+ *
+ * Your `up` and `down` methods will be applied to components in bottom-up fashion, so you
+ * can assume that any components inside one of your areas has already been processed.
+ */
+export interface Migration {
+    createdAt: Date;
+    up: (data: ComponentData, page: PageWithAncestors) => ComponentData | Promise<ComponentData>;
+    down: (data: ComponentData, page: PageWithAncestors) => ComponentData | Promise<ComponentData>;
+}
+export declare type LinkGatheringFn = (data: any) => LinkDefinition[];
+export declare type FulltextGatheringFn = (data: any) => string[];

package/dist/apitemplate.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component.d.ts

@@ -0,0 +1,119 @@
+import { Page } from './page';
+import { ResourceProvider } from './provider';
+/**
+ * This is the primary templating class to build your templates. Subclass it and provide
+ * at least a render function.
+ *
+ * During rendering, it will be "hydrated" - placed into a full page structure with its
+ * parent and child components linked.
+ */
+export declare abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends ResourceProvider {
+    static templateKey: string;
+    static templateName: string;
+    areas: Map<string, Component<any, any, any>[]>;
+    data: Omit<DataType, 'areas'>;
+    fetched: FetchedType;
+    renderCtx: RenderContextType;
+    path: string;
+    parent?: Component;
+    page?: Page;
+    hadError: boolean;
+    /**
+     * The first phase of rendering a component is the fetch phase. Each component may
+     * provide a fetch method that looks up data it needs from external sources. This step
+     * is FLAT - it will be executed concurrently for all the components on the page for
+     * maximum speed.
+     *
+     * Note that this.page will be available, along with its ancestors property containing
+     * all the data from ancestor pages, in case there is a need for inheritance. It is
+     * recommended to copy any needed data into the return object, as future phases will not
+     * want to resolve the inheritance again.
+     */
+    fetch(editMode: boolean): Promise<FetchedType>;
+    /**
+     * The second phase of rendering a component is the context phase. This step is TOP-DOWN,
+     * each component will receive the parent component's context, modify it as desired,
+     * and then pass context to its children.
+     *
+     * This is useful for rendering logic that is sensitive to where the component exists in
+     * the hierarchy of the page. For instance, if a parent component has used an h2 header
+     * already, it will want to inform its children so that they can use h3 next, and they inform
+     * their children that h4 is next, and so on. (Header level tracking is actually required in
+     * dosgato CMS.)
+     *
+     * This function may return a promise in case you need to do something asynchronous based on
+     * the context received from the parent, but use it sparingly since it will stall the process.
+     * Try to do all asynchronous work in the fetch phase.
+     */
+    setContext(renderCtxFromParent: RenderContextType, editMode: boolean): RenderContextType | Promise<RenderContextType>;
+    /**
+     * The final phase of rendering a component is the render phase. This step is BOTTOM-UP -
+     * components at the bottom of the hierarchy will be rendered first, and the result of the
+     * render will be passed to parent components so that the HTML can be included during the
+     * render of the parent component.
+     */
+    abstract render(renderedAreas: Map<string, string[]>, editMode: boolean): string;
+    /**
+     * Sometimes pages are requested with an alternate extension like .rss or .ics. In these
+     * situations, each component should consider whether it should output anything. For
+     * instance, if the extension is .rss and a component represents an article, it should
+     * probably output an RSS item. If you don't recognize the extension, just return
+     * super.renderVariation(extension, renderedAreas) to give your child components a chance to
+     * respond, or return empty string if you want your child components to be silent in all
+     * cases.
+     *
+     * This function will be run after the fetch phase. The context and html rendering phases
+     * will be skipped.
+     */
+    renderVariation(extension: string, renderedAreas: Map<string, string>): string;
+    constructor(data: DataType, path: string, parent: Component | undefined);
+    /**
+     * For logging errors during rendering without crashing the render. If your fetch, setContext,
+     * render, or renderVariation functions throw, the error will be logged but the page render will
+     * continue. You generally do not need to use this function, just throw when appropriate.
+     */
+    logError(e: Error): void;
+    protected passError(e: Error, path: string): void;
+    /**
+     * During rendering, each component should determine the CSS blocks that it needs. This may
+     * change depending on the data. For instance, if you need some CSS to style up an image, but
+     * only when the editor uploaded an image, you can check whether the image is present during
+     * the execution of this function.
+     *
+     * This is evaluated after the fetch and context phases but before the rendering phase. If you
+     * need any async data to make this determination, be sure to fetch it during the fetch phase.
+     */
+    cssBlocks(): string[];
+    /**
+     * Same as cssBlocks() but for javascript.
+     */
+    jsBlocks(): string[];
+}
+export interface PageRecord<DataType extends PageData = PageData> {
+    id: string;
+    linkId: string;
+    path: string;
+    data: DataType;
+}
+export interface PageWithAncestors<DataType extends PageData = PageData> extends PageRecord<DataType> {
+    ancestors: PageRecord<PageData>[];
+}
+export interface ComponentData {
+    templateKey: string;
+    areas: Record<string, ComponentData[]>;
+}
+export interface PageData extends ComponentData {
+    savedAtVersion: Date;
+}
+export interface ContextBase {
+    /**
+     * For accessibility, every component should consider whether it is creating headers
+     * using h1-h6 tags, and set the context for its children so that they will use the
+     * next higher number. For example, a page component might use h1 for the page title,
+     * in which case it should set headerLevel: 2 so that its child components will use
+     * h2 next. Those components in turn can increment headerLevel for their children.
+     *
+     * This way every page will have a perfect header tree and avoid complaints from WAVE.
+     */
+    headerLevel: number;
+}

package/dist/component.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Component = void 0;
+const page_1 = require("./page");
+const provider_1 = require("./provider");
+/**
+ * This is the primary templating class to build your templates. Subclass it and provide
+ * at least a render function.
+ *
+ * During rendering, it will be "hydrated" - placed into a full page structure with its
+ * parent and child components linked.
+ */
+class Component extends provider_1.ResourceProvider {
+    // the constructor is part of the recursive hydration mechanism: constructing
+    // a Component will also construct/hydrate all its child components
+    constructor(data, path, parent) {
+        var _a;
+        super();
+        // properties for use during hydration, you do not have to provide these when
+        // building a template, but you can use them in the functions you do provide
+        this.areas = new Map();
+        this.parent = parent;
+        const { areas, ...ownData } = data;
+        this.data = ownData;
+        this.path = path;
+        this.hadError = false;
+        let tmpParent = (_a = this.parent) !== null && _a !== void 0 ? _a : this;
+        while (!(tmpParent instanceof page_1.Page) && tmpParent.parent)
+            tmpParent = tmpParent.parent;
+        if (!(tmpParent instanceof page_1.Page))
+            throw new Error('Hydration failed, could not map component back to its page.');
+        this.page = tmpParent;
+    }
+    /**
+     * The first phase of rendering a component is the fetch phase. Each component may
+     * provide a fetch method that looks up data it needs from external sources. This step
+     * is FLAT - it will be executed concurrently for all the components on the page for
+     * maximum speed.
+     *
+     * Note that this.page will be available, along with its ancestors property containing
+     * all the data from ancestor pages, in case there is a need for inheritance. It is
+     * recommended to copy any needed data into the return object, as future phases will not
+     * want to resolve the inheritance again.
+     */
+    async fetch(editMode) {
+        return undefined;
+    }
+    /**
+     * The second phase of rendering a component is the context phase. This step is TOP-DOWN,
+     * each component will receive the parent component's context, modify it as desired,
+     * and then pass context to its children.
+     *
+     * This is useful for rendering logic that is sensitive to where the component exists in
+     * the hierarchy of the page. For instance, if a parent component has used an h2 header
+     * already, it will want to inform its children so that they can use h3 next, and they inform
+     * their children that h4 is next, and so on. (Header level tracking is actually required in
+     * dosgato CMS.)
+     *
+     * This function may return a promise in case you need to do something asynchronous based on
+     * the context received from the parent, but use it sparingly since it will stall the process.
+     * Try to do all asynchronous work in the fetch phase.
+     */
+    setContext(renderCtxFromParent, editMode) {
+        return renderCtxFromParent;
+    }
+    /**
+     * Sometimes pages are requested with an alternate extension like .rss or .ics. In these
+     * situations, each component should consider whether it should output anything. For
+     * instance, if the extension is .rss and a component represents an article, it should
+     * probably output an RSS item. If you don't recognize the extension, just return
+     * super.renderVariation(extension, renderedAreas) to give your child components a chance to
+     * respond, or return empty string if you want your child components to be silent in all
+     * cases.
+     *
+     * This function will be run after the fetch phase. The context and html rendering phases
+     * will be skipped.
+     */
+    renderVariation(extension, renderedAreas) {
+        return Array.from(renderedAreas.values()).join('');
+    }
+    /**
+     * For logging errors during rendering without crashing the render. If your fetch, setContext,
+     * render, or renderVariation functions throw, the error will be logged but the page render will
+     * continue. You generally do not need to use this function, just throw when appropriate.
+     */
+    logError(e) {
+        var _a;
+        this.hadError = true;
+        (_a = this.parent) === null || _a === void 0 ? void 0 : _a.passError(e, this.path);
+    }
+    // helper function for recursively passing the error up until it reaches the page
+    passError(e, path) {
+        var _a;
+        (_a = this.parent) === null || _a === void 0 ? void 0 : _a.passError(e, path);
+    }
+    /**
+     * During rendering, each component should determine the CSS blocks that it needs. This may
+     * change depending on the data. For instance, if you need some CSS to style up an image, but
+     * only when the editor uploaded an image, you can check whether the image is present during
+     * the execution of this function.
+     *
+     * This is evaluated after the fetch and context phases but before the rendering phase. If you
+     * need any async data to make this determination, be sure to fetch it during the fetch phase.
+     */
+    cssBlocks() {
+        return this.constructor.cssBlocks().keys();
+    }
+    /**
+     * Same as cssBlocks() but for javascript.
+     */
+    jsBlocks() {
+        return this.constructor.jsBlocks().keys();
+    }
+}
+exports.Component = Component;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './apitemplate';
+export * from './component';
+export * from './links';
+export * from './page';
+export * from './provider';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./apitemplate"), exports);
+__exportStar(require("./component"), exports);
+__exportStar(require("./links"), exports);
+__exportStar(require("./page"), exports);
+__exportStar(require("./provider"), exports);

package/{src/links.ts → dist/links.d.ts}

@@ -4,36 +4,33 @@
  * the link target anyway.
  */
 export interface AssetLink {
-  type: 'asset'
-  source: string
-  id: string // the asset's dataId
-  siteId: string
-  path: string
-  checksum: string
+    type: 'asset';
+    source: string;
+    id: string;
+    siteId: string;
+    path: string;
+    checksum: string;
 }
-
 /**
  * Some components (e.g. document list) can point at a folder instead of individual
  * assets, so we will want to track asset folders through moves, renames, and copies.
  * This link format supports all that.
  */
 export interface AssetFolderLink {
-  type: 'assetfolder'
-  id: string // the asset folder's guid
-  siteId: string
-  path: string
+    type: 'assetfolder';
+    id: string;
+    siteId: string;
+    path: string;
 }
-
 /**
  * A page link always points at the same pagetree as the page the link is on.
  */
 export interface PageLink {
-  type: 'page'
-  linkId: string
-  siteId: string
-  path: string
+    type: 'page';
+    linkId: string;
+    siteId: string;
+    path: string;
 }
-
 /**
  * The link format for external webpages. This format seems a little extra since
  * it's just a URL string. Why does it need to be an object with a type? However,
@@ -42,31 +39,28 @@ export interface PageLink {
  * the data a lot easier.
  */
 export interface WebLink {
-  type: 'url'
-  url: string
+    type: 'url';
+    url: string;
 }
-
 /**
  * Many components will point at data records. That's the whole idea. Site id is
  * required for all data links, it just might be null when the data being pointed at is
  * global data.
  */
 export interface DataLink {
-  type: 'data'
-  id: string // the data item's dataId
-  siteId: string|null // null if global data
-  path: string
+    type: 'data';
+    id: string;
+    siteId: string | null;
+    path: string;
 }
-
 /**
  * Just like with asset folders, we may have components that point at data folders. We
  * would like to keep the links working through moves, renames, and copies.
  */
 export interface DataFolderLink {
-  type: 'datafolder'
-  id: string // the asset folder's guid
-  siteId?: string // null if global data
-  path: string
+    type: 'datafolder';
+    id: string;
+    siteId?: string;
+    path: string;
 }
-
-export type LinkDefinition = AssetLink | AssetFolderLink | PageLink | WebLink | DataLink | DataFolderLink
+export declare type LinkDefinition = AssetLink | AssetFolderLink | PageLink | WebLink | DataLink | DataFolderLink;

package/dist/links.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/page.d.ts

@@ -0,0 +1,13 @@
+import { PageData, ContextBase, Component, PageRecord, PageWithAncestors } from './component';
+export declare abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
+    pagePath: string;
+    ancestors: PageRecord[];
+    /**
+     * we will fill this before rendering, stuff that dosgato knows needs to be added to
+     * the <head> element
+     * the page's render function must include it
+     */
+    headContent: string;
+    protected passError(e: Error, path: string): void;
+    constructor(page: PageWithAncestors<DataType>);
+}

package/dist/page.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = void 0;
+const component_1 = require("./component");
+class Page extends component_1.Component {
+    constructor(page) {
+        super(page.data, '/', undefined);
+        this.pagePath = page.path;
+        this.ancestors = page.ancestors;
+    }
+    passError(e, path) {
+        console.warn(`Recoverable issue occured during render of ${this.pagePath}. Component at ${path} threw the following error:`, e);
+    }
+}
+exports.Page = Page;

package/dist/provider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * This class is a parent class for Component, but it can also be used as a standalone
+ * if you are creating a set of templates with shared resources. This will be fairly
+ * typical for each entity running an instance and creating their own local templates. You'll
+ * probably want one place to set up very common resources like fontawesome or jquery, instead
+ * of having each and every component template provide them again and again.
+ *
+ * If you do this, don't forget to register the provider along with your templates!
+ */
+export declare abstract class ResourceProvider {
+    /**
+     * Each template should provide a map of CSS blocks where the map key is the unique name for
+     * the CSS and the value is the CSS itself. For instance, if a template needs CSS from a
+     * standard library like jquery-ui, it could include the full CSS for jquery-ui with 'jquery-ui'
+     * as the key. Other templates that depend on jquery-ui would also provide the CSS, but
+     * a page with both components would only include the CSS once, because they both called it
+     * 'jquery-ui'.
+     *
+     * A version string (e.g. '1.2.5') may be provided for each block. The block with the highest
+     * version number of any given name will be used. Other versions of that name will be ignored.
+     *
+     * For convenience you can either provide the `css` property with the CSS as a string, or the
+     * `path` property with the full server path to a CSS file (node's __dirname function will
+     * help you determine it). You MUST provide one or the other.
+     */
+    static cssBlocks: Map<string, {
+        css?: string;
+        path?: string;
+        version?: string;
+    }>;
+    /**
+     * Same as cssBlocks() but for javascript.
+     */
+    static jsBlocks: Map<string, {
+        js?: string;
+        path?: string;
+        version?: string;
+    }>;
+    /**
+     * If your template needs to serve any files, like fonts or images, you can provide
+     * a filesystem path in this static property and the files will be served by the rendering
+     * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
+     * available as soon as your template has been registered to the rendering server's templateRegistry.
+     *
+     * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
+     * to where you are writing your template class.
+     *
+     * The map name you pick should be globally unique and only collide with other templates as
+     * intended. For instance, the fontawesome font only needs to be provided once, even though
+     * several templates might depend on it. Setting the name as 'fontawesome5' on all three
+     * templates would ensure that the file would only be served once. Including the major version
+     * number is a good idea only if the major versions can coexist.
+     *
+     * Include a version number if applicable for the file you've included with your source. If
+     * multiple templates have a common file, the one that provides the highest version number will
+     * have its file served, while the others will be ignored.
+     *
+     * DO NOT change the mime type without changing the name. Other templates could end up with
+     * the wrong file extension.
+     */
+    static files: Map<string, {
+        path: string;
+        version?: string;
+        mime: string;
+    }>;
+    /**
+     * Template code will need to generate HTML and CSS that points at the static files
+     * provided above. In order to do so, we need information from the template registry (since
+     * we have to deduplicate with other registered templates at startup time).
+     *
+     * In order to avoid an ES6 dependency on the registry, we will have the registry write
+     * back to this map as templates are registered.
+     *
+     * Now when a template needs a web path to a resource to put into its HTML, it can do
+     * `<img src="${TemplateClass.webpath('keyname')}">`
+     */
+    static webpaths: Map<string, string>;
+    static webpath(name: string): string | undefined;
+}

package/dist/provider.js

@@ -0,0 +1,72 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceProvider = void 0;
+/**
+ * This class is a parent class for Component, but it can also be used as a standalone
+ * if you are creating a set of templates with shared resources. This will be fairly
+ * typical for each entity running an instance and creating their own local templates. You'll
+ * probably want one place to set up very common resources like fontawesome or jquery, instead
+ * of having each and every component template provide them again and again.
+ *
+ * If you do this, don't forget to register the provider along with your templates!
+ */
+class ResourceProvider {
+    static webpath(name) { return this.webpaths.get(name); }
+}
+exports.ResourceProvider = ResourceProvider;
+/**
+ * Each template should provide a map of CSS blocks where the map key is the unique name for
+ * the CSS and the value is the CSS itself. For instance, if a template needs CSS from a
+ * standard library like jquery-ui, it could include the full CSS for jquery-ui with 'jquery-ui'
+ * as the key. Other templates that depend on jquery-ui would also provide the CSS, but
+ * a page with both components would only include the CSS once, because they both called it
+ * 'jquery-ui'.
+ *
+ * A version string (e.g. '1.2.5') may be provided for each block. The block with the highest
+ * version number of any given name will be used. Other versions of that name will be ignored.
+ *
+ * For convenience you can either provide the `css` property with the CSS as a string, or the
+ * `path` property with the full server path to a CSS file (node's __dirname function will
+ * help you determine it). You MUST provide one or the other.
+ */
+ResourceProvider.cssBlocks = new Map();
+/**
+ * Same as cssBlocks() but for javascript.
+ */
+ResourceProvider.jsBlocks = new Map();
+/**
+ * If your template needs to serve any files, like fonts or images, you can provide
+ * a filesystem path in this static property and the files will be served by the rendering
+ * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
+ * available as soon as your template has been registered to the rendering server's templateRegistry.
+ *
+ * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
+ * to where you are writing your template class.
+ *
+ * The map name you pick should be globally unique and only collide with other templates as
+ * intended. For instance, the fontawesome font only needs to be provided once, even though
+ * several templates might depend on it. Setting the name as 'fontawesome5' on all three
+ * templates would ensure that the file would only be served once. Including the major version
+ * number is a good idea only if the major versions can coexist.
+ *
+ * Include a version number if applicable for the file you've included with your source. If
+ * multiple templates have a common file, the one that provides the highest version number will
+ * have its file served, while the others will be ignored.
+ *
+ * DO NOT change the mime type without changing the name. Other templates could end up with
+ * the wrong file extension.
+ */
+ResourceProvider.files = new Map();
+/**
+ * Template code will need to generate HTML and CSS that points at the static files
+ * provided above. In order to do so, we need information from the template registry (since
+ * we have to deduplicate with other registered templates at startup time).
+ *
+ * In order to avoid an ES6 dependency on the registry, we will have the registry write
+ * back to this map as templates are registered.
+ *
+ * Now when a template needs a web path to a resource to put into its HTML, it can do
+ * `<img src="${TemplateClass.webpath('keyname')}">`
+ */
+ResourceProvider.webpaths = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "A library to support building templates for dosgato CMS.",
   "exports": {
     "require": "./dist/index.js",
@@ -30,5 +30,8 @@
   "bugs": {
     "url": "https://github.com/txstate-etc/dosgato-templating/issues"
   },
-  "homepage": "https://github.com/txstate-etc/dosgato-templating#readme"
+  "homepage": "https://github.com/txstate-etc/dosgato-templating#readme",
+  "files": [
+    "dist", "dist-esm"
+  ]
 }

package/.eslintrc.json

@@ -1,15 +0,0 @@
-{
-  "extends": "standard-with-typescript",
-  "parserOptions": {
-      "project": "./tsconfig.eslint.json"
-  },
-  "rules": {
-    "@typescript-eslint/explicit-function-return-type": "off", // useless boilerplate
-    "@typescript-eslint/array-type": "off", // forces you to use Array<CustomType> instead of CustomType[], silly
-    "@typescript-eslint/no-non-null-assertion": "off", // disables using ! to mark something as non-null,
-                                                       // generally not avoidable without wasting cpu cycles on a check
-    "@typescript-eslint/no-unused-vars": "off", // typescript already reports this and VSCode darkens the variable
-    "@typescript-eslint/return-await": ["error", "always"], // allows you to accidentally break async stacktraces in node 14+
-    "@typescript-eslint/strict-boolean-expressions": "off" // we know how truthiness works, annoying to have to avoid
-  }
-}

package/src/component.ts

@@ -1,167 +0,0 @@
-import { Page } from './page'
-import { ResourceProvider } from './provider'
-
-/**
- * This is the primary templating class to build your templates. Subclass it and provide
- * at least a render function.
- *
- * During rendering, it will be "hydrated" - placed into a full page structure with its
- * parent and child components linked.
- */
-export abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends ResourceProvider {
-  // properties each template should provide
-  static templateKey: string
-  static templateName: string
-
-  // properties for use during hydration, you do not have to provide these when
-  // building a template, but you can use them in the functions you do provide
-  areas = new Map<string, Component[]>()
-  data: Omit<DataType, 'areas'>
-  fetched!: FetchedType
-  renderCtx!: RenderContextType
-  path: string
-  parent?: Component
-  page?: Page
-  hadError: boolean
-
-  /**
-   * The first phase of rendering a component is the fetch phase. Each component may
-   * provide a fetch method that looks up data it needs from external sources. This step
-   * is FLAT - it will be executed concurrently for all the components on the page for
-   * maximum speed.
-   *
-   * Note that this.page will be available, along with its ancestors property containing
-   * all the data from ancestor pages, in case there is a need for inheritance. It is
-   * recommended to copy any needed data into the return object, as future phases will not
-   * want to resolve the inheritance again.
-   */
-  async fetch (editMode: boolean) {
-    return undefined as unknown as FetchedType
-  }
-
-  /**
-   * The second phase of rendering a component is the context phase. This step is TOP-DOWN,
-   * each component will receive the parent component's context, modify it as desired,
-   * and then pass context to its children.
-   *
-   * This is useful for rendering logic that is sensitive to where the component exists in
-   * the hierarchy of the page. For instance, if a parent component has used an h2 header
-   * already, it will want to inform its children so that they can use h3 next, and they inform
-   * their children that h4 is next, and so on. (Header level tracking is actually required in
-   * dosgato CMS.)
-   *
-   * This function may return a promise in case you need to do something asynchronous based on
-   * the context received from the parent, but use it sparingly since it will stall the process.
-   * Try to do all asynchronous work in the fetch phase.
-   */
-  setContext (renderCtxFromParent: RenderContextType, editMode: boolean): RenderContextType|Promise<RenderContextType> {
-    return renderCtxFromParent
-  }
-
-  /**
-   * The final phase of rendering a component is the render phase. This step is BOTTOM-UP -
-   * components at the bottom of the hierarchy will be rendered first, and the result of the
-   * render will be passed to parent components so that the HTML can be included during the
-   * render of the parent component.
-   */
-  abstract render (renderedAreas: Map<string, string[]>, editMode: boolean): string
-
-  /**
-   * Sometimes pages are requested with an alternate extension like .rss or .ics. In these
-   * situations, each component should consider whether it should output anything. For
-   * instance, if the extension is .rss and a component represents an article, it should
-   * probably output an RSS item. If you don't recognize the extension, just return
-   * super.renderVariation(extension, renderedAreas) to give your child components a chance to
-   * respond, or return empty string if you want your child components to be silent in all
-   * cases.
-   *
-   * This function will be run after the fetch phase. The context and html rendering phases
-   * will be skipped.
-   */
-  renderVariation (extension: string, renderedAreas: Map<string, string>) {
-    return Array.from(renderedAreas.values()).join('')
-  }
-
-  // the constructor is part of the recursive hydration mechanism: constructing
-  // a Component will also construct/hydrate all its child components
-  constructor (data: DataType, path: string, parent: Component|undefined) {
-    super()
-    this.parent = parent
-    const { areas, ...ownData } = data
-    this.data = ownData
-    this.path = path
-    this.hadError = false
-    let tmpParent = this.parent ?? this
-    while (!(tmpParent instanceof Page) && tmpParent.parent) tmpParent = tmpParent.parent
-    if (!(tmpParent instanceof Page)) throw new Error('Hydration failed, could not map component back to its page.')
-    this.page = tmpParent
-  }
-
-  /**
-   * For logging errors during rendering without crashing the render. If your fetch, setContext,
-   * render, or renderVariation functions throw, the error will be logged but the page render will
-   * continue. You generally do not need to use this function, just throw when appropriate.
-   */
-  logError (e: Error) {
-    this.hadError = true
-    this.parent?.passError(e, this.path)
-  }
-
-  // helper function for recursively passing the error up until it reaches the page
-  protected passError (e: Error, path: string) {
-    this.parent?.passError(e, path)
-  }
-
-  /**
-   * During rendering, each component should determine the CSS blocks that it needs. This may
-   * change depending on the data. For instance, if you need some CSS to style up an image, but
-   * only when the editor uploaded an image, you can check whether the image is present during
-   * the execution of this function.
-   *
-   * This is evaluated after the fetch and context phases but before the rendering phase. If you
-   * need any async data to make this determination, be sure to fetch it during the fetch phase.
-   */
-  cssBlocks (): string[] {
-    return (this.constructor as any).cssBlocks().keys()
-  }
-
-  /**
-   * Same as cssBlocks() but for javascript.
-   */
-  jsBlocks (): string[] {
-    return (this.constructor as any).jsBlocks().keys()
-  }
-}
-
-export interface PageRecord<DataType extends PageData = PageData> {
-  id: string
-  linkId: string
-  path: string
-  data: DataType
-}
-
-export interface PageWithAncestors<DataType extends PageData = PageData> extends PageRecord<DataType> {
-  ancestors: PageRecord<PageData>[]
-}
-
-export interface ComponentData {
-  templateKey: string
-  areas: Record<string, ComponentData[]>
-}
-
-export interface PageData extends ComponentData {
-  savedAtVersion: Date
-}
-
-export interface ContextBase {
-  /**
-   * For accessibility, every component should consider whether it is creating headers
-   * using h1-h6 tags, and set the context for its children so that they will use the
-   * next higher number. For example, a page component might use h1 for the page title,
-   * in which case it should set headerLevel: 2 so that its child components will use
-   * h2 next. Those components in turn can increment headerLevel for their children.
-   *
-   * This way every page will have a perfect header tree and avoid complaints from WAVE.
-   */
-  headerLevel: number
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from './component'
-export * from './links'
-export * from './page'
-export * from './provider'
-export * from './template'

package/src/page.ts

@@ -1,23 +0,0 @@
-import { PageData, ContextBase, Component, PageRecord, PageWithAncestors } from './component'
-
-export abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
-  pagePath: string
-  ancestors: PageRecord[]
-
-  /**
-   * we will fill this before rendering, stuff that dosgato knows needs to be added to
-   * the <head> element
-   * the page's render function must include it
-   */
-  headContent!: string
-
-  protected passError (e: Error, path: string) {
-    console.warn(`Recoverable issue occured during render of ${this.pagePath}. Component at ${path} threw the following error:`, e)
-  }
-
-  constructor (page: PageWithAncestors<DataType>) {
-    super(page.data, '/', undefined)
-    this.pagePath = page.path
-    this.ancestors = page.ancestors
-  }
-}

package/src/provider.ts

@@ -1,72 +0,0 @@
-/* eslint-disable @typescript-eslint/no-extraneous-class */
-
-/**
- * This class is a parent class for Component, but it can also be used as a standalone
- * if you are creating a set of templates with shared resources. This will be fairly
- * typical for each entity running an instance and creating their own local templates. You'll
- * probably want one place to set up very common resources like fontawesome or jquery, instead
- * of having each and every component template provide them again and again.
- *
- * If you do this, don't forget to register the provider along with your templates!
- */
-export abstract class ResourceProvider {
-  /**
-   * Each template should provide a map of CSS blocks where the map key is the unique name for
-   * the CSS and the value is the CSS itself. For instance, if a template needs CSS from a
-   * standard library like jquery-ui, it could include the full CSS for jquery-ui with 'jquery-ui'
-   * as the key. Other templates that depend on jquery-ui would also provide the CSS, but
-   * a page with both components would only include the CSS once, because they both called it
-   * 'jquery-ui'.
-   *
-   * A version string (e.g. '1.2.5') may be provided for each block. The block with the highest
-   * version number of any given name will be used. Other versions of that name will be ignored.
-   *
-   * For convenience you can either provide the `css` property with the CSS as a string, or the
-   * `path` property with the full server path to a CSS file (node's __dirname function will
-   * help you determine it). You MUST provide one or the other.
-   */
-  static cssBlocks: Map<string, { css?: string, path?: string, version?: string }> = new Map()
-
-  /**
-   * Same as cssBlocks() but for javascript.
-   */
-  static jsBlocks: Map<string, { js?: string, path?: string, version?: string }> = new Map()
-
-  /**
-   * If your template needs to serve any files, like fonts or images, you can provide
-   * a filesystem path in this static property and the files will be served by the rendering
-   * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
-   * available as soon as your template has been registered to the rendering server's templateRegistry.
-   *
-   * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
-   * to where you are writing your template class.
-   *
-   * The map name you pick should be globally unique and only collide with other templates as
-   * intended. For instance, the fontawesome font only needs to be provided once, even though
-   * several templates might depend on it. Setting the name as 'fontawesome5' on all three
-   * templates would ensure that the file would only be served once. Including the major version
-   * number is a good idea only if the major versions can coexist.
-   *
-   * Include a version number if applicable for the file you've included with your source. If
-   * multiple templates have a common file, the one that provides the highest version number will
-   * have its file served, while the others will be ignored.
-   *
-   * DO NOT change the mime type without changing the name. Other templates could end up with
-   * the wrong file extension.
-   */
-  static files: Map<string, { path: string, version?: string, mime: string }> = new Map()
-
-  /**
-   * Template code will need to generate HTML and CSS that points at the static files
-   * provided above. In order to do so, we need information from the template registry (since
-   * we have to deduplicate with other registered templates at startup time).
-   *
-   * In order to avoid an ES6 dependency on the registry, we will have the registry write
-   * back to this map as templates are registered.
-   *
-   * Now when a template needs a web path to a resource to put into its HTML, it can do
-   * `<img src="${TemplateClass.webpath('keyname')}">`
-   */
-  static webpaths: Map<string, string> = new Map()
-  static webpath (name: string) { return this.webpaths.get(name) }
-}

package/src/template.ts

@@ -1,88 +0,0 @@
-import { PageWithAncestors, ComponentData } from './component'
-import { LinkDefinition } from './links'
-
-export type TemplateType = 'page'|'component'|'data'
-
-/**
- * This interface lays out the structure the API needs for each template in the system.
- */
-export interface Template {
-  type: TemplateType
-
-  /**
-   * A unique string to globally identify this template across installations. Namespacing like
-   * edu.txstate.RichTextEditor could be useful but no special format is required.
-   */
-  templateKey: string
-
-  /**
-   * Each template must declare its areas and the template keys of components that will be
-   * permitted inside each area. The list of allowed component templates can be updated beyond
-   * the list provided here. See templateRegistry.addAvailableComponent's comment for info on why.
-   */
-  areas: Record<string, string[]>
-
-  /**
-   * Each template must provide a list of migrations for upgrading the data schema over time.
-   * Typically this will start as an empty array and migrations will be added as the template
-   * gets refactored.
-   */
-  migrations: Migration[]
-
-  /**
-   * Each template must provide a function that returns links from its data so that they
-   * can be indexed. Only fields that are links need to be returned. Links inside rich editor
-   * text will be extracted automatically from any text returned by getFulltext (see below)
-   */
-  getLinks: LinkGatheringFn
-
-  /**
-   * Each template must provide the text from any text or rich editor data it possesses, so that
-   * the text can be decomposed into words and indexed for fulltext searches. Any text returned
-   * by this function will also be scanned for links.
-   */
-  getFulltext: FulltextGatheringFn
-
-  /**
-   * Each template must provide a validation function so that the API can enforce its data is
-   * shaped properly. If there are no issues, it should return an empty object {}, otherwise it
-   * should return an object with keys that reference the path to the error and values that
-   * are an array of error messages pertaining to that path.
-   *
-   * For instance, if name is required and the user didn't provide one, you would return:
-   * { name: ['A name is required.'] }
-   *
-   * This method is async so that you can do things like look in the database for conflicting
-   * names.
-   */
-  validate: (data: any) => Promise<Record<string, string[]>>
-}
-
-/**
- * In dosgato CMS, the data in the database is not altered except during user activity. This
- * means that older records could have been saved when the schema expected by component
- * rendering code was different than the date it's being rendered. To handle this, each
- * page and component template is required to provide migrations responsible for
- * transforming the data to the needed schema version.
- *
- * In order to support backwards compatibility, each API client will specify the date
- * when the code was written, so that their assumptions about the schema will be
- * frozen in time. This system means that migrations need to run backward as well as forward
- * in time.
- *
- * The `up` method is for changing data from an older schema to a newer one. The
- * `down` method is for changing data back from the newer schema to the older one.
- * If a `down` method cannot be provided, the migration is considered to be a breaking
- * change and anyone asking to rewind time to before the migration will receive an error.
- *
- * Your `up` and `down` methods will be applied to components in bottom-up fashion, so you
- * can assume that any components inside one of your areas has already been processed.
- */
-export interface Migration {
-  createdAt: Date
-  up: (data: ComponentData, page: PageWithAncestors) => ComponentData|Promise<ComponentData>
-  down: (data: ComponentData, page: PageWithAncestors) => ComponentData|Promise<ComponentData>
-}
-
-export type LinkGatheringFn = (data: any) => LinkDefinition[]
-export type FulltextGatheringFn = (data: any) => string[]

package/tsconfig.eslint.json

@@ -1,7 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "include": [
-    "src/**/*.ts",
-    "test/**/*.ts"
-  ]
-}

package/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2019",
-    "module": "commonjs",
-    "declaration": true,
-    "outDir": "./dist",
-    "strict": true,
-    "esModuleInterop": true
-  },
-  "include": ["src"]
-}