@dosgato/templating 1.1.15 → 1.1.16

package/dist/apitemplate.d.ts

@@ -18,7 +18,7 @@ export interface ValidationFeedback {
  * API to make sure it hasn't been used already.
  */
 export interface PageExtras<DataType = PageData> {
-    /** A function for executing a graphql query to acquire more information than is already at hand. */
+    /** A function for executing a graphql query to acquire more information than is already at hand. Queries are executed by the system user, so be careful with it. */
     query: GraphQLQueryFn;
     /** The site id in which the page lives or is being created. Null if we are validating creation of a site. */
     siteId?: string;
@@ -331,10 +331,3 @@ export type AnyMigration = ComponentMigration | PageMigration | DataMigration;
 export type LinkGatheringFn<DataType> = (data: DataType) => (LinkDefinition | string | undefined)[];
 export type FulltextGatheringFn<DataType> = (data: DataType) => (string | undefined)[];
 export type GraphQLQueryFn = <T>(query: string, variables?: any) => Promise<T>;
-/**
- * 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.
- */
-export declare function getKeywords(text?: string, options?: {
-    stopwords?: boolean;
-}): string[];

package/dist/apitemplate.js

@@ -1,21 +1,6 @@
-import { stopwordSet } from './stopwords.js';
 export var ValidationMessageType;
 (function (ValidationMessageType) {
     ValidationMessageType["ERROR"] = "error";
     ValidationMessageType["WARNING"] = "warning";
     ValidationMessageType["SUCCESS"] = "success";
 })(ValidationMessageType || (ValidationMessageType = {}));
-/**
- * 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.
- */
-export function getKeywords(text, options) {
-    if (!text)
-        return [];
-    return Array.from(new Set(text
-        .normalize('NFD').replace(/\p{Diacritic}/gu, '')
-        .toLocaleLowerCase()
-        .split(/[^\w-]+/)
-        .flatMap(word => word.includes('-') ? word.split('-').concat(word.replace('-', '')) : [word])
-        .filter(word => word.length > 2 && (options?.stopwords === false || !stopwordSet.has(word)) && isNaN(Number(word)))));
-}

package/dist/component.js

@@ -9,6 +9,44 @@ function defaultWrap(info) { return info.output; }
  * parent and child components linked.
  */
 export class Component extends ResourceProvider {
+    /**
+     * Provide this when you create a template to identify what you are defining.
+     */
+    static templateKey;
+    /**
+     * 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;
+    /**
+     * This property will be set during page render and you may refer to it at any time to
+     * determine whether you are doing your work in edit mode or regular rendering mode.
+     * The editBar and newBar methods will automatically use it to blank out the editing UI.
+     */
+    editMode;
+    /**
+     * The extension of the variation currently being rendered.
+     *
+     * See 'renderVariation' and 'variationsToFetch' for more discussion of variations.
+     */
+    extension;
+    /**
+     * When hydrating an inherited component, the renderer will set this to the id of the page it
+     * came from. You may use this information in any of the phases to alter your behavior if needed.
+     *
+     * For instance, you may decide that your fetch function needs some extra information from the
+     * originating page instead of the page you're being inherited into (your `this.page` will
+     * be the page currently being rendered, NOT the page the inheritable component came from).
+     *
+     * This property is also used to alter the edit bar. Inherited components may never be edited
+     * except on their original page, so the edit bar will render with a link to the original page.
+     */
+    inheritedFrom;
     /**
      * 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
@@ -51,6 +89,17 @@ export class Component extends ResourceProvider {
      * '.js.map', you should receive 'js.map'.
      */
     shouldFetchVariation(extension) { return extension === 'html'; }
+    /**
+     * Some components may be inheritable to subpages within the same site. For instance, a site's
+     * social media links may appear on every page's footer. To accomplish this in your template,
+     * you need to fetch ancestor page data in your fetch phase, identify the component data you want
+     * to inherit, and then call this function within your fetch to let the renderer know it needs to
+     * process those components (hydrate them, call their fetch functions, and include them in the render).
+     *
+     * The inherited components will be added to the appropriate area's array in the renderedAreas
+     * parameter of your render function.
+     */
+    registerInherited;
     /**
      * Inherit components from another page with matching area
      *
@@ -85,6 +134,44 @@ export class Component extends ResourceProvider {
     setContext(renderCtxFromParent, areaName) {
         return renderCtxFromParent;
     }
+    /**
+     * This function will be provided by the rendering server and should be used inside your fetch
+     * method to prepare editor-provided HTML for later rendering. It will do things like find and
+     * resolve link definitions in the internal dosgato format.
+     */
+    fetchRichText;
+    /**
+     * This function will be provided by the rendering server and should be used during the render
+     * phase to clean up editor-provided HTML. It will do things like clean up tags that were accidentally
+     * left open to protect overall page integrity, and fix header levels for accessibility.
+     *
+     * For instance, an editor supplies a title to be placed above some rich editor content. The
+     * title uses an <h2>, so the headers inside the rich editor content should start at <h3> and
+     * should not use <h1> or <h2>.
+     *
+     * Setting headerLevel: 3 instructs the renderRichText function to analyze and rebalance the header
+     * structure of the content so that if it had an h2, it woud be replaced with an h3. Additionally,
+     * if the user skipped a header level (a WCAG violation) that situation will be repaired as well
+     * as possible.
+     *
+     * If you do not provide a headerLevel, the one from `this.renderCtx` will be used. However, if you
+     * provide a non-blank value for `advanceHeader`, the headerLevel from `this.renderCtx` + 1 will be used.
+     *
+     * This way you can easily render a piece of rich text in a component that has an optional title:
+     *
+     * this.renderRichText(this.data.richtext, { advanceHeader: this.data.title })
+     *
+     * If this.data.title is non-blank, the rich text will be balanced below it, but if it is blank,
+     * it will be balanced at the level the title would have had.
+     */
+    renderRichText;
+    /**
+     * When we give editors the ability to enter raw HTML, we still need to minimally process it to
+     * protect the rest of the page from unclosed tags and other syntax problems, but we don't want
+     * to muck around with headers or links, so this function will be provided by the render server
+     * and will only do the parsing and reconstruction part
+     */
+    renderRawHTML;
     /**
      * If you are rendering a variation for a component that has areas and children,
      * you can call Component.renderVariation(extension, this.renderedAreas) to help you easily
@@ -207,6 +294,17 @@ export class Component extends ResourceProvider {
      * CSS class
      */
     editClass() { return undefined; }
+    /**
+     * Override with `true` to indicate that this template never accepts data from editors
+     *
+     * Its edit bar will not have a pencil icon.
+     */
+    noData = false;
+    /**
+     * Override with `true` to indicate that this template renders its own edit bar
+     * so that the parent component will avoid rendering it
+     */
+    renderIncludesEditBar = false;
     /**
      * Components may override this function to give their new bars a custom
      * label
@@ -227,10 +325,10 @@ export class Component extends ResourceProvider {
      */
     editBar(opts = {}) {
         const options = { ...opts };
-        options.label ?? (options.label = this.editLabel() ?? this.autoLabel);
+        options.label ??= this.editLabel() ?? this.autoLabel;
         options.extraClass = [options.extraClass, this.editClass()].filter(isNotBlank).join(' ');
-        options.editMode ?? (options.editMode = this.editMode);
-        options.inheritedFrom ?? (options.inheritedFrom = this.inheritedFrom);
+        options.editMode ??= this.editMode;
+        options.inheritedFrom ??= this.inheritedFrom;
         options.hideEdit = this.noData || options.hideEdit;
         return Component.editBar(this.path, options);
     }
@@ -241,29 +339,21 @@ export class Component extends ResourceProvider {
      */
     newBar(areaName, opts = {}) {
         const options = { ...opts };
-        options.label ?? (options.label = this.newLabel(areaName) ?? (this.areas.size > 1 ? `Add ${areaName} Content` : `Add ${this.autoLabel} Content`));
+        options.label ??= this.newLabel(areaName) ?? (this.areas.size > 1 ? `Add ${areaName} Content` : `Add ${this.autoLabel} Content`);
         options.extraClass = [options.extraClass, this.newClass(areaName)].filter(isNotBlank).join(' ');
-        options.editMode ?? (options.editMode = this.editMode);
+        options.editMode ??= this.editMode;
         return Component.newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), options);
     }
+    /**
+     * These functions will be provided by the rendering server to assist in the
+     * rendering process.
+     */
+    static editBar;
+    static newBar;
     // the constructor is part of the recursive hydration mechanism: constructing
     // a Component will also construct/hydrate all its child components
     constructor(data, path, parent, editMode, extension) {
         super();
-        /**
-         * Override with `true` to indicate that this template never accepts data from editors
-         *
-         * Its edit bar will not have a pencil icon.
-         */
-        this.noData = false;
-        /**
-         * Override with `true` to indicate that this template renders its own edit bar
-         * so that the parent component will avoid rendering it
-         */
-        this.renderIncludesEditBar = false;
-        // Properties provided during the rendering process. 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(); // a Map of area names and the array of hydrated components in each
         this.editMode = editMode;
         this.extension = extension;
         this.parent = parent;
@@ -278,6 +368,35 @@ export class Component extends ResourceProvider {
             throw new Error('Hydration failed, could not map component back to its page.');
         this.page = tmpParent;
     }
+    // Properties provided during the rendering process. 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(); // a Map of area names and the array of hydrated components in each
+    data; // the component data
+    fetched; // where we store the output from your `fetched` method
+    renderCtx; // where we store the output from your `setContext` method
+    path; // the dot-separated path to this component within the page data
+    parent; // the hydrated parent component of this component
+    page; // the hydrated page component this component lives in
+    renderedAreas; // render server sets this just before `render` is called
+    hadError; // will be true if the fetch encountered an error, render will be skipped
+    autoLabel; // the rendering server will fetch template names and fill this
+    reqHeaders; // the HTTP headers of the request being processed, in case it would change the render
+    reqQuery; // the URL of the request being processed, so you can access the query or do routing work
+    // the index of this component in its area, after inheritance has occurred
+    // because we are waiting for inheritance, this will be undefined until the render phase
+    // it's also undefined for page templates but I'm intentionally making it non-optional
+    // because it would be non-sensical to try to use in a page template anyway
+    indexInArea;
+    /**
+     * the full array of components in the same area as this component, including self
+     *
+     * empty for page component
+     */
+    siblings;
+    /** the component before this one inside the area, null if this component is first */
+    prevSibling;
+    /** the component after this one inside the area, null if this component is last */
+    nextSibling;
     /**
      * 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
@@ -293,6 +412,15 @@ export class Component extends ResourceProvider {
     }
 }
 export class Page extends Component {
+    /**
+     * The page id in case you need to pass it to the API, e.g. this.api.getRootPage(this.id)
+     * in a page template or this.api.getRootPage(this.page.id) in a component template.
+     */
+    id;
+    /**
+     * Other data we've already collected about the page being rendered, in case it's needed.
+     */
+    pageInfo;
     /**
      * A convenience to get the page title.
      *
@@ -301,6 +429,43 @@ export class Page extends Component {
     get title() {
         return this.pageInfo.data.title ?? titleCase(this.pageInfo.name);
     }
+    /**
+     * This will be filled by the rendering server. The template properties are described
+     * over in apitemplate.ts in the comment for APIPageTemplate.templateProperties.
+     *
+     * The properties will appear in the GraphQL API and the rendering server will automatically
+     * download them and provide them here so all you need to do as a template developer is
+     * reference the values in your fetch/setContext/render functions.
+     */
+    templateProperties;
+    /**
+     * This is a bunch of javascript and CSS and meta tags managed by the DosGato engine. It will
+     * be filled by the rendering server and your render function for your page template
+     * should place include it in the <head> element
+     */
+    headContent;
+    /**
+     * This method will be provided to page templates by the render server. You may call it
+     * at any time during fetch, context, or render, to set an HTTP header on the response
+     */
+    addHeader;
+    /**
+     * This method will be provided to page templates by the render server. You may call it to set
+     * the HTTP response status at any time during the fetch, context, or render.
+     */
+    setStatus;
+    /**
+     * URL for the currently rendering page
+     *
+     * The URL currently being rendered. For instance, if we are in edit mode it would begin
+     * with /.edit/ or in preview mode, /.preview/. Useful for referencing variations of the
+     * current page.
+     *
+     * Does not include hash or querystring.
+     *
+     * Also see `variationUrl` below.
+     */
+    url;
     /**
      * Get a URL for the current page with a different extension
      */

package/dist/index.d.ts

@@ -3,5 +3,4 @@ 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

@@ -3,5 +3,4 @@ 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/provider.js

@@ -9,80 +9,80 @@
  * If you do this, don't forget to register the provider along with your templates!
  */
 export 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 (NOT URL) to a CSS file (node's __dirname function will
+     * help you determine it). You MUST provide one or the other.
+     *
+     * You may also set `async` to true if a css block is not needed for the initial render of
+     * the page. For instance, if your component has a modal that the user can trigger, you can
+     * defer the CSS for that modal since it will not be needed until the page has gone interactive
+     * and the user has clicked something.
+     */
+    static cssBlocks = new Map();
+    /**
+     * A template can provide SASS mixins and functions for use by other SASS-based CSS
+     * blocks.
+     *
+     * These includes can be utilized by other SASS with the SASS `@use` and `@include`
+     * commands, e.g.
+     * ```
+     * @use 'my-mixin-name' as mx;
+     * .someclass { @include mx.somemixin(); }
+     * ```
+     * In this case `my-mixin-name` is the key used for this Map.
+     */
+    static scssIncludes = new Map();
+    /**
+     * Same as cssBlocks() but for javascript.
+     *
+     * In this case `async` is much more useful, as most javascript is interactive and could run
+     * after the page renders. Any code that adds event observers or the like should be marked with
+     * async to improve the initial render time.
+     */
+    static 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.
+     *
+     * 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 = 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, and the structure
+     * of the webpath in general is the render server's concern).
+     *
+     * 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 = new Map();
     static webpath(name) { return this.webpaths.get(name); }
 }
-/**
- * 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 (NOT URL) to a CSS file (node's __dirname function will
- * help you determine it). You MUST provide one or the other.
- *
- * You may also set `async` to true if a css block is not needed for the initial render of
- * the page. For instance, if your component has a modal that the user can trigger, you can
- * defer the CSS for that modal since it will not be needed until the page has gone interactive
- * and the user has clicked something.
- */
-ResourceProvider.cssBlocks = new Map();
-/**
- * A template can provide SASS mixins and functions for use by other SASS-based CSS
- * blocks.
- *
- * These includes can be utilized by other SASS with the SASS `@use` and `@include`
- * commands, e.g.
- * ```
- * @use 'my-mixin-name' as mx;
- * .someclass { @include mx.somemixin(); }
- * ```
- * In this case `my-mixin-name` is the key used for this Map.
- */
-ResourceProvider.scssIncludes = new Map();
-/**
- * Same as cssBlocks() but for javascript.
- *
- * In this case `async` is much more useful, as most javascript is interactive and could run
- * after the page renders. Any code that adds event observers or the like should be marked with
- * async to improve the initial render time.
- */
-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.
- *
- * 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, and the structure
- * of the webpath in general is the render server's concern).
- *
- * 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": "1.1.15",
+  "version": "1.1.16",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {

package/dist/stopwords.d.ts

@@ -1,2 +0,0 @@
-export declare const stopwords: Record<string, boolean>;
-export declare const stopwordSet: Set<string>;

package/dist/stopwords.js

@@ -1,154 +0,0 @@
-export const stopwords = {
-    myself: true,
-    our: true,
-    ours: true,
-    ourselves: true,
-    you: true,
-    your: true,
-    yours: true,
-    yourself: true,
-    yourselves: true,
-    him: true,
-    his: true,
-    himself: true,
-    she: true,
-    her: true,
-    hers: true,
-    herself: true,
-    its: true,
-    itself: true,
-    they: true,
-    them: true,
-    their: true,
-    theirs: true,
-    themselves: true,
-    what: true,
-    which: true,
-    who: true,
-    whom: true,
-    this: true,
-    that: true,
-    these: true,
-    those: true,
-    are: true,
-    was: true,
-    were: true,
-    been: true,
-    being: true,
-    have: true,
-    has: true,
-    had: true,
-    having: true,
-    does: true,
-    did: true,
-    doing: true,
-    the: true,
-    and: true,
-    but: true,
-    because: true,
-    until: true,
-    while: true,
-    for: true,
-    with: true,
-    about: true,
-    against: true,
-    between: true,
-    into: true,
-    through: true,
-    during: true,
-    before: true,
-    after: true,
-    above: true,
-    below: true,
-    from: true,
-    down: true,
-    out: true,
-    off: true,
-    over: true,
-    under: true,
-    again: true,
-    further: true,
-    then: true,
-    once: true,
-    here: true,
-    there: true,
-    when: true,
-    where: true,
-    why: true,
-    how: true,
-    all: true,
-    any: true,
-    both: true,
-    each: true,
-    few: true,
-    more: true,
-    most: true,
-    other: true,
-    some: true,
-    such: true,
-    nor: true,
-    not: true,
-    only: true,
-    own: true,
-    same: true,
-    than: true,
-    too: true,
-    very: true,
-    can: true,
-    will: true,
-    just: true,
-    don: true,
-    should: true,
-    now: true,
-    // HTML
-    div: true,
-    span: true,
-    img: true,
-    abbr: true,
-    area: true,
-    main: true,
-    aside: true,
-    blockquote: true,
-    button: true,
-    caption: true,
-    code: true,
-    del: true,
-    strong: true,
-    font: true,
-    embed: true,
-    fieldset: true,
-    form: true,
-    figure: true,
-    iframe: true,
-    label: true,
-    input: true,
-    script: true,
-    nav: true,
-    select: true,
-    option: true,
-    picture: true,
-    pre: true,
-    small: true,
-    style: true,
-    svg: true,
-    sub: true,
-    table: true,
-    tbody: true,
-    href: true,
-    src: true,
-    srcset: true,
-    class: true,
-    textarea: true,
-    title: true,
-    onclick: true,
-    www: true,
-    com: true,
-    // LinkDefinition
-    siteId: true,
-    path: true,
-    type: true,
-    assetId: true,
-    linkId: true,
-    url: true
-};
-export const stopwordSet = new Set(Object.keys(stopwords));