@dosgato/templating 0.0.85 → 0.0.87

package/dist/component.d.ts

@@ -11,7 +11,7 @@ import { APIClient } from './render.js';
  * 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 {
+export declare abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = ContextBase> extends ResourceProvider {
     /**
      * Provide this when you create a template to identify what you are defining.
      */
@@ -121,21 +121,55 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
         filter?: (c: T) => boolean;
     }): void;
     /**
-     * The second phase of rendering a component is the context phase. This step is TOP-DOWN and
-     * NON-MUTATING. Each component will receive the parent component's context and then pass a
-     * NEW context object to its children.
+     * The second phase of rendering a component is the context phase. This step is TOP-DOWN.
+     * Each component will receive context from the parent component and then pass a new context
+     * object to its own 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 supported by default in
-     * dosgato CMS.)
+     * dosgato CMS - see printHeader() and advanceHeader())
      *
      * 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): RenderContextType | Promise<RenderContextType>;
+    setContext(renderCtxFromParent: RenderContextType, areaName: string): RenderContextType | Promise<RenderContextType>;
+    /**
+     * 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: (text: string) => Promise<void>;
+    /**
+     * 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: (html: string, opts?: {
+        headerLevel?: number;
+        advanceHeader?: string | undefined | null;
+    }) => string;
     /**
      * 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
@@ -239,7 +273,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     static editBar: (path: string, opts: EditBarOpts) => string;
     static newBar: (path: string, opts: NewBarOpts) => string;
     constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean);
-    areas: Map<string, Component<any, any, any>[]>;
+    areas: Map<string, Component<any, any, ContextBase>[]>;
     data: Omit<DataType, 'areas'>;
     fetched: FetchedType;
     renderCtx: RenderContextType;
@@ -306,6 +340,7 @@ export interface ContextBase {
      * This way every page will have a perfect header tree and avoid complaints from WAVE.
      */
     headerLevel: number;
+    [keys: string]: any;
 }
 interface BarOpts {
     editMode?: boolean;

package/dist/component.js

@@ -73,21 +73,21 @@ export class Component extends ResourceProvider {
         this.registerInherited(areaName, components, page.id, opts?.mode);
     }
     /**
-     * The second phase of rendering a component is the context phase. This step is TOP-DOWN and
-     * NON-MUTATING. Each component will receive the parent component's context and then pass a
-     * NEW context object to its children.
+     * The second phase of rendering a component is the context phase. This step is TOP-DOWN.
+     * Each component will receive context from the parent component and then pass a new context
+     * object to its own 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 supported by default in
-     * dosgato CMS.)
+     * dosgato CMS - see printHeader() and advanceHeader())
      *
      * 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) {
+    setContext(renderCtxFromParent, areaName) {
         return renderCtxFromParent;
     }
     /**

package/dist/render.d.ts

@@ -1,9 +1,7 @@
 import { ContextBase, DataData, PageData, PageRecord, PageRecordOptionalData } from './component.js';
 import { AssetLink, DataFolderLink, DataLink, LinkDefinition, PageLink } from './links.js';
 export declare function printHeader(ctx: ContextBase, content: string | undefined | null, attributes?: Record<string, string>): string;
-export declare function advanceHeader(ctx: ContextBase, content: string | undefined | null): {
-    headerLevel: number;
-};
+export declare function advanceHeader<T extends ContextBase>(ctx: T, content: string | undefined | null): T;
 export interface PictureResize {
     /** the width of this particular resize */
     width: number;
@@ -88,13 +86,6 @@ export interface APIClient {
         absolute?: boolean;
         extension?: string;
     }) => 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.

package/dist/render.js

@@ -1,9 +1,9 @@
-import { htmlEncode, isBlank } from 'txstate-utils';
+import { htmlEncode, isBlank, isNotEmpty } from 'txstate-utils';
 export function printHeader(ctx, content, attributes) {
     if (isBlank(content))
         return '';
-    const level = (ctx.headerLevel ?? 0) + 1;
-    const attr = attributes ? ' ' + Object.entries(attributes).map(([key, val]) => `${key}="${htmlEncode(val)}"`).join(' ') : '';
+    const level = ctx.headerLevel ?? 1;
+    const attr = isNotEmpty(attributes) ? ' ' + Object.entries(attributes).map(([key, val]) => `${key}="${htmlEncode(val)}"`).join(' ') : '';
     if (level < 1)
         return `<h1${attr}>${content}</h1>`;
     if (level > 6)
@@ -11,8 +11,7 @@ export function printHeader(ctx, content, attributes) {
     return `<h${level}${attr}>${content}</h${level}>`;
 }
 export function advanceHeader(ctx, content) {
-    const ret = { ...ctx };
     if (!isBlank(content))
-        ret.headerLevel = (ret.headerLevel ?? 0) + 1;
-    return ret;
+        ctx.headerLevel = (ctx.headerLevel ?? 1) + 1;
+    return ctx;
 }

package/package.json

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