@dosgato/templating 0.0.38 → 0.0.41

package/dist/component.d.ts

@@ -1,4 +1,3 @@
-import { EditBarOpts } from './editbar.js';
 import { ResourceProvider } from './provider.js';
 import { APIClient } from './render.js';
 /**
@@ -9,8 +8,15 @@ import { APIClient } from './render.js';
  * parent and child components linked.
  */
 export declare abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends ResourceProvider {
+    /**
+     * Provide this when you create a template to identify what you are defining.
+     */
     static templateKey: string;
-    static templateName: string;
+    /**
+     * These functions will be provided by the rendering server
+     */
+    static editBar: (path: string, opts: EditBarOpts) => string;
+    static newBar: (path: string, opts: EditBarOpts) => string;
     areas: Map<string, Component<any, any, any>[]>;
     data: Omit<DataType, 'areas'>;
     fetched: FetchedType;
@@ -19,6 +25,26 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     parent?: Component;
     page?: Page;
     hadError: boolean;
+    autoLabel: () => string;
+    autoNewLabel: () => string;
+    /**
+     * 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?: string;
+    /**
+     * 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: boolean;
     /**
      * 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
@@ -49,6 +75,13 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * other Component instances.
      */
     getAncestorPageData: () => Promise<PageData[]>;
+    /**
+     * 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 the data in your fetch phase and then call this function within your fetch
+     * to let the renderer know it needs to hydrate them and include them in the render.
+     */
+    registerInherited: (area: string, components: ComponentData[], top?: true) => void;
     /**
      * 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
@@ -63,7 +96,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * 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>;
+    fetch(): Promise<FetchedType>;
     /**
      * 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
@@ -79,14 +112,14 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * 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, editMode: boolean): RenderContextType | Promise<RenderContextType>;
+    setContext(renderCtxFromParent: RenderContextType): RenderContextType | Promise<RenderContextType>;
     /**
      * 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
      * render will be passed to parent components so that the HTML can be included during the
      * render of the parent component.
      */
-    abstract render(renderedAreas: Map<string, string[]>, editMode: boolean): string;
+    abstract render(renderedAreas: Map<string, RenderedComponent[]>): string;
     /**
      * Sometimes pages are requested with an alternate extension like .rss or .ics. In these
      * situations, each component should consider whether it should output anything. For
@@ -100,7 +133,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * will be skipped.
      */
     renderVariation(extension: string, renderedAreas: Map<string, string>): string;
-    constructor(data: DataType, path: string, parent: Component | undefined);
+    constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean);
     /**
      * 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
@@ -108,6 +141,9 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      */
     logError(e: Error): void;
     protected passError(e: Error, path: string): void;
+    renderComponents(components?: RenderedComponent[], opts?: {
+        hideInheritBars?: boolean;
+    }): string;
     /**
      * During rendering, each component should determine the CSS blocks that it needs. This may
      * change depending on the data. For instance, if you need some CSS to style up an image, but
@@ -124,11 +160,11 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     jsBlocks(): string[];
     /**
      * Components may override this function to give their edit bars a custom
-     * label instead of using the templateName property
+     * label instead of using the template name
      *
      * For instance, you could return this.data.title
      */
-    editLabel(): string;
+    editLabel(): undefined;
     /**
      * Components may override this function to give their edit bars a custom
      * CSS class
@@ -141,7 +177,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * For instance, an area that only accepts 'layout' components could
      * return "Add Layout"
      */
-    newLabel(areaName: string): string;
+    newLabel(areaName: string): undefined;
     /**
      * Components may override this function to give their new bars a custom
      * CSS class
@@ -189,6 +225,16 @@ export interface ContextBase {
      */
     headerLevel: number;
 }
+export interface EditBarOpts {
+    extraClass?: string;
+    label?: string;
+    editMode?: boolean;
+    inheritedFrom?: string;
+}
+export interface RenderedComponent<C extends Component = Component> {
+    component: C;
+    html: string;
+}
 export declare abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
     pagePath: string;
     /**
@@ -198,5 +244,5 @@ export declare abstract class Page<DataType extends PageData = any, FetchedType
      */
     headContent: string;
     protected passError(e: Error, path: string): void;
-    constructor(page: PageRecord<DataType>);
+    constructor(page: PageRecord<DataType>, editMode: boolean);
 }

package/dist/component.js

@@ -1,5 +1,4 @@
 import { isNotBlank } from 'txstate-utils';
-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
@@ -11,11 +10,12 @@ import { ResourceProvider } from './provider.js';
 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) {
+    constructor(data, path, parent, editMode) {
         super();
         // properties for use during hydration, 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();
+        this.editMode = editMode;
         this.parent = parent;
         const { areas, ...ownData } = data;
         this.data = ownData;
@@ -42,7 +42,7 @@ export class Component extends ResourceProvider {
      * 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) {
+    async fetch() {
         return undefined;
     }
     /**
@@ -60,7 +60,7 @@ export class Component extends ResourceProvider {
      * 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, editMode) {
+    setContext(renderCtxFromParent) {
         return renderCtxFromParent;
     }
     /**
@@ -91,6 +91,11 @@ export class Component extends ResourceProvider {
     passError(e, path) {
         this.parent?.passError(e, path);
     }
+    // helper function to help you print an area, but you can also override this if you
+    // need to do something advanced like wrap each component in a div
+    renderComponents(components = [], opts) {
+        return components.flatMap(c => c.component.inheritedFrom && opts?.hideInheritBars ? [c.html] : [c.component.editBar(), c.html]).join('');
+    }
     /**
      * During rendering, each component should determine the CSS blocks that it needs. This may
      * change depending on the data. For instance, if you need some CSS to style up an image, but
@@ -111,13 +116,12 @@ export class Component extends ResourceProvider {
     }
     /**
      * Components may override this function to give their edit bars a custom
-     * label instead of using the templateName property
+     * label instead of using the template name
      *
      * For instance, you could return this.data.title
      */
     editLabel() {
-        const This = this.constructor;
-        return This.templateName;
+        return undefined;
     }
     /**
      * Components may override this function to give their edit bars a custom
@@ -134,7 +138,7 @@ export class Component extends ResourceProvider {
      * return "Add Layout"
      */
     newLabel(areaName) {
-        return 'Add Content';
+        return undefined;
     }
     /**
      * Components may override this function to give their new bars a custom
@@ -149,9 +153,11 @@ export class Component extends ResourceProvider {
      * Generally should not be overridden - override editLabel and editClass instead
      */
     editBar(opts = {}) {
-        opts.label ?? (opts.label = this.editLabel());
+        opts.label ?? (opts.label = this.editLabel() ?? this.autoLabel());
         opts.extraClass ?? (opts.extraClass = this.editClass());
-        return editBar(this.path, opts);
+        opts.editMode ?? (opts.editMode = this.editMode);
+        opts.inheritedFrom ?? (opts.inheritedFrom = this.inheritedFrom);
+        return Component.editBar(this.path, opts);
     }
     /**
      * Components may override this function to provide a custom new bar
@@ -159,14 +165,16 @@ export class Component extends ResourceProvider {
      * Generally should not be overridden - override newLabel and newClass instead
      */
     newBar(areaName, opts = {}) {
-        opts.label ?? (opts.label = this.newLabel(areaName));
+        opts.label ?? (opts.label = this.newLabel(areaName) ?? this.autoNewLabel());
         opts.extraClass ?? (opts.extraClass = this.newClass(areaName));
-        return newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), opts);
+        opts.editMode ?? (opts.editMode = this.editMode);
+        opts.inheritedFrom ?? (opts.inheritedFrom = this.inheritedFrom);
+        return Component.newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), opts);
     }
 }
 export class Page extends Component {
-    constructor(page) {
-        super(page.data, '', undefined);
+    constructor(page, editMode) {
+        super(page.data, '', undefined, editMode);
         this.pagePath = page.path;
     }
     passError(e, path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.38",
+  "version": "0.0.41",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {
@@ -18,7 +18,7 @@
     "txstate-utils": "^1.7.1"
   },
   "devDependencies": {
-    "eslint-config-standard-with-typescript": "^21.0.1",
+    "eslint-config-standard-with-typescript": "^22.0.0",
     "typescript": "^4.4.2"
   },
   "repository": {

package/dist/editbar.d.ts

@@ -1,11 +0,0 @@
-export interface EditBarOpts {
-    extraClass?: string;
-    label?: string;
-    editMode?: boolean;
-}
-export declare function editBar(path: string, opts: EditBarOpts & {
-    label: string;
-}): string;
-export declare function newBar(path: string, opts: EditBarOpts & {
-    label: string;
-}): string;

package/dist/editbar.js

@@ -1,23 +0,0 @@
-import { htmlEncode, randomid } from 'txstate-utils';
-export function editBar(path, opts) {
-    if (!opts.editMode)
-        return '';
-    const id = randomid();
-    return `
-<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();
-}
-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="${htmlEncode(path)}">
-  ${htmlEncode(opts.label)}
-</div>
-  `.trim();
-}