@dosgato/templating 0.0.22 → 0.0.25

package/dist/apitemplate.d.ts

@@ -1,6 +1,16 @@
-import { PageWithAncestors, ComponentData } from './component.js';
+import { PageRecord, ComponentData, PageData } from './component.js';
 import { LinkDefinition } from './links.js';
 export declare type APITemplateType = 'page' | 'component' | 'data';
+declare enum MessageType {
+    ERROR = "error",
+    WARNING = "warning",
+    SUCCESS = "success"
+}
+interface Feedback {
+    type: `${MessageType}`;
+    path?: string;
+    message: string;
+}
 /**
  * This interface lays out the structure the API needs for each template in the system.
  */
@@ -41,17 +51,22 @@ export interface APITemplate {
     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.
+     * shaped properly.
+     *
+     * Each entry in the return array can have a type of error, warning, or success. Errors
+     * represent a validation failure and mean that saving will not succeed. Warnings are shown
+     * to the editor but do not prevent saving. Success messages postively affirm valid input - for
+     * instance, a name they chose is available.
      *
-     * For instance, if name is required and the user didn't provide one, you would return:
-     * { name: ['A name is required.'] }
+     * As an example, if name is required and the user didn't provide one, you would return:
+     * [{ type: 'error', path: 'name', message: 'A name is required.' }]
      *
      * This method is async so that you can do things like look in the database for conflicting
-     * names.
+     * names. The full page data, the path to this component, and a GraphQL query executor are
+     * available as parameters in case you need them. Keep in mind that the current editor MUST
+     * have access to any data you attempt to query in GraphQL.
      */
-    validate: (data: any) => Promise<Record<string, string[]>>;
+    validate: (data: ComponentData, query: <T>(query: string, variables?: any) => Promise<T>, page: PageData, path: string) => Promise<Feedback[]>;
     /**
      * 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
@@ -85,8 +100,8 @@ export interface APITemplate {
  */
 export interface Migration {
     createdAt: Date;
-    up: (data: ComponentData, page: PageWithAncestors) => ComponentData | Promise<ComponentData>;
-    down: (data: ComponentData, page: PageWithAncestors) => ComponentData | Promise<ComponentData>;
+    up: (data: ComponentData, page: PageRecord) => ComponentData | Promise<ComponentData>;
+    down: (data: ComponentData, page: PageRecord) => ComponentData | Promise<ComponentData>;
 }
 export declare type LinkGatheringFn = (data: any) => LinkDefinition[];
 export declare type FulltextGatheringFn = (data: any) => string[];
@@ -102,3 +117,4 @@ export declare function extractLinksFromText(text: string): LinkDefinition[];
 export declare function getKeywords(text: string, options?: {
     stopwords?: boolean;
 }): string[];
+export {};

package/dist/apitemplate.js

@@ -1,4 +1,10 @@
 import { stopwords } from './stopwords.js';
+var MessageType;
+(function (MessageType) {
+    MessageType["ERROR"] = "error";
+    MessageType["WARNING"] = "warning";
+    MessageType["SUCCESS"] = "success";
+})(MessageType || (MessageType = {}));
 /**
  * This function is used by API template definitions to help them identify links inside large blocks
  * of text and return them for indexing.

package/dist/component.d.ts

@@ -1,6 +1,6 @@
 import { EditBarOpts } from './editbar.js';
-import { LinkDefinition } from './links.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.
+     */
+    api: APIClient;
+    /**
+     * 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.
      */
-    resolveLink: (link: string | LinkDefinition, absolute?: boolean) => Promise<string>;
+    getRootPageData: () => Promise<PageData>;
     /**
-     * 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 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.
      */
-    processRich: (text: string) => Promise<string>;
+    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>;
     /**
@@ -146,9 +166,6 @@ export interface PageRecord<DataType extends PageData = PageData> {
     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[]>;
@@ -156,6 +173,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
@@ -170,7 +191,6 @@ export interface ContextBase {
 }
 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
@@ -178,5 +198,5 @@ export declare abstract class Page<DataType extends PageData = any, FetchedType
      */
     headContent: string;
     protected passError(e: Error, path: string): void;
-    constructor(page: PageWithAncestors<DataType>);
+    constructor(page: PageRecord<DataType>);
 }

package/dist/component.js

@@ -33,10 +33,13 @@ export class Component extends 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;
@@ -164,7 +167,6 @@ export class Page extends 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);

package/dist/render.d.ts

@@ -1,5 +1,83 @@
-import { ContextBase } from './component.js';
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.22",
+  "version": "0.0.25",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {