@dosgato/templating 0.0.84 → 0.0.86

package/dist/component.d.ts

@@ -121,21 +121,46 @@ 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.
+     */
+    renderRichText: (html: string, opts?: {
+        headerLevel?: number;
+    }) => 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

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): string;
-export declare function advanceHeader(ctx: ContextBase, content?: string): {
-    headerLevel: number;
-};
+export declare function printHeader(ctx: ContextBase, content: string | undefined | null, attributes?: Record<string, string>): string;
+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,17 +1,17 @@
-import { isBlank } from 'txstate-utils';
-export function printHeader(ctx, content) {
+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 = isNotEmpty(attributes) ? ' ' + Object.entries(attributes).map(([key, val]) => `${key}="${htmlEncode(val)}"`).join(' ') : '';
     if (level < 1)
-        return `<h1>${content}</h1>`;
+        return `<h1${attr}>${content}</h1>`;
     if (level > 6)
-        return `<h6>${content}</h6>`;
-    return `<h${level}>${content}</h${level}>`;
+        return `<h6${attr}>${content}</h6>`;
+    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 ?? 0) + 1;
+    return ctx;
 }

package/dist/uitemplate.d.ts

@@ -27,10 +27,15 @@ export interface UITemplate {
      * - data: ComponentData, the current data on the page, should not be mutated during editing,
      *   undefined when creating
      * - page: DialogPageProp, the current page so that you can reference the full page data or
-     *   make a further graphql query based on its id/path.
+     *   make a further graphql query based on its id/path. Component dialogs only, page and data
+     *   dialogs do not receive this prop
      * - templateProperties: the template properties for the current page template, so you can make
-     *   things like color pickers that visually match the colors of the current page template
+     *   things like color pickers that visually match the colors of the current page template.
+     *   Data dialogs do not receive this.
      * - environmentConfig: base URLs in case you need to generate a link to the API or something
+     *
+     * In addition to the props, you may import the `dialogQuery` function (see below) to send
+     * requests to the API.
      */
     dialog?: new (...args: any[]) => any;
     /**
@@ -64,7 +69,7 @@ export interface UITemplate {
 }
 /**
  * This is a type for the data that will be passed to dialog Svelte components as
- * the `page` prop.
+ * the `page` prop. Note that page template dialogs do NOT receive this prop.
  */
 export interface DialogPageProp {
     id: string;

package/package.json

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