@dosgato/templating 0.0.20 → 0.0.23

package/dist/apitemplate.d.ts

@@ -1,5 +1,5 @@
-import { PageWithAncestors, ComponentData } from './component';
-import { LinkDefinition } from './links';
+import { PageWithAncestors, ComponentData } from './component.js';
+import { LinkDefinition } from './links.js';
 export declare type APITemplateType = 'page' | 'component' | 'data';
 /**
  * This interface lays out the structure the API needs for each template in the system.

package/dist/apitemplate.js

@@ -1,26 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getKeywords = exports.extractLinksFromText = void 0;
-const stopwords_1 = require("./stopwords");
+import { stopwords } from './stopwords.js';
 /**
  * This function is used by API template definitions to help them identify links inside large blocks
  * of text and return them for indexing.
  */
-function extractLinksFromText(text) {
+export function extractLinksFromText(text) {
     const matches = text.matchAll(/{.*"type"\s?:\s+"\w+".*?}/gi);
     return Array.from(matches).map(m => JSON.parse(m[0]));
 }
-exports.extractLinksFromText = extractLinksFromText;
 /**
  * This function is used by API template definitions to help them identify all the searchable
  * words in a large block of text and return them for indexing.
  */
-function getKeywords(text, options) {
+export function getKeywords(text, options) {
     return Array.from(new Set(text
         .toLocaleLowerCase()
         .normalize('NFD').replace(/\p{Diacritic}/gu, '')
         .split(/[^\w-]+/)
         .flatMap(word => word.includes('-') ? word.split('-').concat(word.replace('-', '')) : [word])
-        .filter(word => word.length > 2 && (options?.stopwords === false || !stopwords_1.stopwords[word]) && isNaN(Number(word)))));
+        .filter(word => word.length > 2 && (options?.stopwords === false || !stopwords[word]) && isNaN(Number(word)))));
 }
-exports.getKeywords = getKeywords;

package/dist/component.d.ts

@@ -1,6 +1,6 @@
-import { EditBarOpts } from './editbar';
-import { LinkDefinition } from './links';
-import { ResourceProvider } from './provider';
+import { EditBarOpts } from './editbar.js';
+import { ResourceProvider } from './provider.js';
+import { APIClient } from './render.js';
 /**
  * This is the primary templating class to build your templates. Subclass it and provide
  * at least a render function.
@@ -20,28 +20,48 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     page?: Page;
     hadError: boolean;
     /**
-     * This function will be provided by the rendering server and should be used inside your fetch,
-     * method to convert a link, as input by a user, into a URL suitable for an href, or optionally
-     * an absolute URL suitable for a backend http request or non-HTML document like an RSS feed.
+     * The rendering server will provide an instance of the APIClient interface so that
+     * you can run any API GraphQL query you like in your `fetch` function. There are also
+     * some useful methods there like processRich to help you convert links in rich text
+     * strings.
+     *
+     * Do NOT mutate data received from the API as it may be cached and given to other
+     * Component instances that run the same type of query.
      */
-    resolveLink: (link: string | LinkDefinition, absolute?: boolean) => Promise<string>;
+    api: APIClient;
     /**
-     * This function will be provided by the rendering server and should be used inside your fetch
-     * method to prepare editor-provided HTML for rendering. It will do things like find and resolve
-     * link definitions in the internal dosgato format and clean up tags that were accidentally left
-     * open to protect overall page integrity.
+     * Retrieve the data for the root page of the page this component is on. Useful for
+     * implementing inheritance schemes.
+     *
+     * This function will be provided by the rendering service.
+     *
+     * Do NOT mutate the data returned by this function, as it may be cached and given to
+     * other Component instances.
      */
-    processRich: (text: string) => Promise<string>;
+    getRootPageData: () => Promise<PageData>;
+    /**
+     * Retrieve the data for all ancestor pages of the page this component is on. Useful
+     * for implementing inheritance schemes.
+     *
+     * This function will be provided by the rendering service.
+     *
+     * Do NOT mutate the data returned by this function, as it may be cached and given to
+     * other Component instances.
+     */
+    getAncestorPageData: () => Promise<PageData[]>;
     /**
      * 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.
+     * Place any needed data into the return object, and it will be available to you as `this.fetched`
+     * during the rendering phase.
+     *
+     * Note that this.page will be available, and getRootPageData and getAncestorPageData are
+     * available in case there is a need for inheritance. If you need to inherit entire components,
+     * you may add them to your this.areas map, e.g.
+     * `this.areas.get('myarea').push(new Component(inheritedData, this.path + '/myarea/inherit1', this))`
      */
     fetch(editMode: boolean): Promise<FetchedType>;
     /**
@@ -156,6 +176,10 @@ export interface ComponentData {
 export interface PageData extends ComponentData {
     savedAtVersion: Date;
 }
+export interface DataData {
+    templateKey: string;
+    savedAtVersion: Date;
+}
 export interface ContextBase {
     /**
      * For accessibility, every component should consider whether it is creating headers

package/dist/component.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Page = exports.Component = void 0;
-const editbar_1 = require("./editbar");
-const provider_1 = require("./provider");
+import { editBar, newBar } from './editbar.js';
+import { ResourceProvider } from './provider.js';
 /**
  * This is the primary templating class to build your templates. Subclass it and provide
  * at least a render function.
@@ -10,7 +7,7 @@ const provider_1 = require("./provider");
  * 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 {
+export class Component extends 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) {
@@ -36,10 +33,13 @@ class Component extends provider_1.ResourceProvider {
      * 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.
+     * Place any needed data into the return object, and it will be available to you as `this.fetched`
+     * during the rendering phase.
+     *
+     * Note that this.page will be available, and getRootPageData and getAncestorPageData are
+     * available in case there is a need for inheritance. If you need to inherit entire components,
+     * you may add them to your this.areas map, e.g.
+     * `this.areas.get('myarea').push(new Component(inheritedData, this.path + '/myarea/inherit1', this))`
      */
     async fetch(editMode) {
         return undefined;
@@ -150,7 +150,7 @@ class Component extends provider_1.ResourceProvider {
     editBar(opts = {}) {
         opts.label ?? (opts.label = this.editLabel());
         opts.extraClass ?? (opts.extraClass = this.editClass());
-        return (0, editbar_1.editBar)(this.path, opts);
+        return editBar(this.path, opts);
     }
     /**
      * Components may override this function to provide a custom new bar
@@ -160,11 +160,10 @@ class Component extends provider_1.ResourceProvider {
     newBar(areaName, opts = {}) {
         opts.label ?? (opts.label = this.newLabel(areaName));
         opts.extraClass ?? (opts.extraClass = this.newClass(areaName));
-        return (0, editbar_1.newBar)(this.path + '.' + areaName, opts);
+        return newBar(this.path + '.' + areaName, opts);
     }
 }
-exports.Component = Component;
-class Page extends Component {
+export class Page extends Component {
     constructor(page) {
         super(page.data, '/', undefined);
         this.pagePath = page.path;
@@ -174,4 +173,3 @@ class Page extends Component {
         console.warn(`Recoverable issue occured during render of ${this.pagePath}. Component at ${path} threw the following error:`, e);
     }
 }
-exports.Page = Page;

package/dist/editbar.js

@@ -1,28 +1,23 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.newBar = exports.editBar = void 0;
-const txstate_utils_1 = require("txstate-utils");
-function editBar(path, opts) {
+import { htmlEncode, randomid } from 'txstate-utils';
+export function editBar(path, opts) {
     if (!opts.editMode)
         return '';
-    const id = (0, txstate_utils_1.randomid)();
+    const id = randomid();
     return `
-<div class="dg-edit-bar ${opts.extraClass ?? ''}" data-path="${(0, txstate_utils_1.htmlEncode)(path)}" draggable="true" ondragstart="window.dgEditing.drag(event)" ondragover="window.dgEditing.over(event)" ondragend="window.dgEditing.drop(event)">
-  <span id="${id}" class="dg-edit-bar-label">${(0, txstate_utils_1.htmlEncode)(opts.label)}</span>
+<div class="dg-edit-bar ${opts.extraClass ?? ''}" data-path="${htmlEncode(path)}" draggable="true" ondragstart="window.dgEditing.drag(event)" ondragover="window.dgEditing.over(event)" ondragend="window.dgEditing.drop(event)">
+  <span id="${id}" class="dg-edit-bar-label">${htmlEncode(opts.label)}</span>
   <button onclick="window.dgEditing.edit(event)" aria-describedby="${id}">Edit</button>
   <button onclick="window.dgEditing.move(event)" aria-describedby="${id}">Move</button>
   <button onclick="window.dgEditing.del(event)" aria-describedby="${id}">Trash</button>
 </div>
   `.trim();
 }
-exports.editBar = editBar;
-function newBar(path, opts) {
+export function newBar(path, opts) {
     if (!opts.editMode)
         return '';
     return `
-<div role="button" onclick="window.dgEditing.create(event)" class="dg-new-bar ${opts.extraClass ?? ''}" data-path="${(0, txstate_utils_1.htmlEncode)(path)}">
-  ${(0, txstate_utils_1.htmlEncode)(opts.label)}
+<div role="button" onclick="window.dgEditing.create(event)" class="dg-new-bar ${opts.extraClass ?? ''}" data-path="${htmlEncode(path)}">
+  ${htmlEncode(opts.label)}
 </div>
   `.trim();
 }
-exports.newBar = newBar;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export * from './apitemplate';
-export * from './component';
-export * from './links';
-export * from './provider';
-export * from './uitemplate';
+export * from './apitemplate.js';
+export * from './component.js';
+export * from './links.js';
+export * from './provider.js';
+export * from './render.js';
+export * from './stopwords.js';
+export * from './uitemplate.js';

package/dist/index.js

@@ -1,21 +1,7 @@
-"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("./provider"), exports);
-__exportStar(require("./uitemplate"), exports);
+export * from './apitemplate.js';
+export * from './component.js';
+export * from './links.js';
+export * from './provider.js';
+export * from './render.js';
+export * from './stopwords.js';
+export * from './uitemplate.js';

package/dist/links.js

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

package/dist/provider.js

@@ -1,7 +1,4 @@
-"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
@@ -11,10 +8,9 @@ exports.ResourceProvider = void 0;
  *
  * If you do this, don't forget to register the provider along with your templates!
  */
-class ResourceProvider {
+export 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

package/dist/render.d.ts

@@ -1,5 +1,83 @@
-import { ContextBase } from './component';
+import { ContextBase, DataData, PageData } from './component.js';
+import { AssetLink, DataFolderLink, DataLink, LinkDefinition } from './links.js';
 export declare function printHeader(ctx: ContextBase, content: string): string;
 export declare function advanceHeader(ctx: ContextBase, content?: string): {
     headerLevel: number;
 };
+export interface PictureResize {
+    /** the width of this particular resize */
+    width: number;
+    /** the URL to this particular resize, relative or absolute depends on options used */
+    src: string;
+}
+export interface PictureAttributes {
+    /** string appropriate for the src attribute of the default <img> tag */
+    src: string;
+    /** string appropriate for the srcset attribute of the default <img> tag, or use widths array to reconstruct */
+    srcset: string;
+    /** a list of available widths in case you want to filter some out and recreate the srcset */
+    widths: PictureResize[];
+    /** alternative text stored with the image in its asset repository, may be overridden by local alt text */
+    alt?: string;
+    /** the original intrinsic width of the image uploaded by the editor */
+    width: number;
+    /** the original intrinsic height of the image uploaded by the editor */
+    height: number;
+    /** a list of alternate formats like AVIF or WEBP and their resizes, useful for creating <source> tags */
+    alternates: {
+        /** the mime type of this alternate source, useful for the type attribute on a <source> tag */
+        mime: string;
+        /** the full srcset for the <source> tag, or use widths array to reconstruct */
+        srcset: string;
+        /** a list of available widths in case you want to filter some out and recreate the srcset */
+        widths: PictureResize[];
+    }[];
+}
+export interface APIClient {
+    /**
+     * Run any query against the API.
+     *
+     * Will be authenticated as appropriate - anonymous during published renders, as the editor
+     * during preview renders.
+     */
+    query: <T = any>(query: string, variables?: any) => Promise<T>;
+    /**
+     * This function will be provided by the rendering server and should be used inside your fetch,
+     * method to convert a link, as input by a user, into a URL suitable for an href, or optionally
+     * an absolute URL suitable for a backend http request or non-HTML document like an RSS feed.
+     */
+    resolveLink: (link: string | LinkDefinition, absolute?: boolean) => Promise<string>;
+    /**
+     * This function will be provided by the rendering server and should be used inside your fetch
+     * method to prepare editor-provided HTML for rendering. It will do things like find and resolve
+     * link definitions in the internal dosgato format and clean up tags that were accidentally left
+     * open to protect overall page integrity.
+     */
+    processRich: (text: string) => Promise<string>;
+    /**
+     * This function will retrieve information about an image to help you construct responsive HTML
+     * for a <picture> element including the <img> and all <source> tags.
+     *
+     * The alt text it returns will be the default alternative text from the asset repository. Alt
+     * text gathered from a template's dialog should generally take precedence (though the dialog may
+     * preload the alt text field with the asset repository default).
+     */
+    getImgAttributes: (link: string | AssetLink, absolute?: boolean) => Promise<PictureAttributes>;
+    /** Get the data for a specific page. Will be dataloaded. */
+    getPageData: ({ id, path }: {
+        id?: string;
+        path?: string;
+    }) => Promise<PageData>;
+    /**
+     * Get data items
+     *
+     * Returns an array in case link is a DataFolderLink. If link is a DataLink, will return an
+     * array with length <= 1.
+     */
+    getDataByLink: (link: string | DataLink | DataFolderLink) => Promise<DataData[]>;
+    /**
+     * Get data by full path including site. Use '/global' for global data. If path refers
+     * to a specific data item, will return an array with length <= 1.
+     */
+    getDataByPath: (templateKey: string, path: string) => Promise<DataData[]>;
+}

package/dist/render.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.advanceHeader = exports.printHeader = void 0;
-const txstate_utils_1 = require("txstate-utils");
-function printHeader(ctx, content) {
-    if ((0, txstate_utils_1.isBlank)(content))
+import { isBlank } from 'txstate-utils';
+export function printHeader(ctx, content) {
+    if (isBlank(content))
         return '';
     const level = (ctx.headerLevel ?? 0) + 1;
     if (level < 1)
@@ -12,11 +9,9 @@ function printHeader(ctx, content) {
         return `<h6>${content}</h1>`;
     return `<h${level}>${content}</h${level}>`;
 }
-exports.printHeader = printHeader;
-function advanceHeader(ctx, content) {
+export function advanceHeader(ctx, content) {
     const ret = { ...ctx };
-    if (!(0, txstate_utils_1.isBlank)(content))
+    if (!isBlank(content))
         ret.headerLevel = (ret.headerLevel ?? 0) + 1;
     return ret;
 }
-exports.advanceHeader = advanceHeader;

package/dist/stopwords.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.stopwords = void 0;
-exports.stopwords = {
+export const stopwords = {
     myself: true,
     our: true,
     ours: true,

package/dist/uitemplate.js

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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.20",
+  "version": "0.0.23",
   "description": "A library to support building templates for dosgato CMS.",
+  "type": "module",
   "exports": {
-    "require": "./dist/index.js",
-    "import": "./dist-esm/index.js"
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
   },
   "types": "dist/index.d.ts",
   "scripts": {
@@ -36,6 +37,6 @@
   },
   "homepage": "https://github.com/txstate-etc/dosgato-templating#readme",
   "files": [
-    "dist", "dist-esm"
+    "dist"
   ]
 }

package/dist-esm/index.js

@@ -1,7 +0,0 @@
-import all from '../dist/index.js'
-
-export const ResourceProvider = all.ResourceProvider
-export const Component = all.Component
-export const Page = all.Page
-export const extractLinksFromText = all.extractLinksFromText
-export const getKeywords = all.getKeywords

package/dist-esm/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}