@dosgato/templating 0.0.69 → 0.0.71

package/dist/component.d.ts

@@ -112,24 +112,21 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     renderVariation(extension: string): string;
     /**
      * helper function to print an area's component list, but you can also override this if you
-     * need to do something advanced like wrap each component in a div
+     * need to do something advanced
      */
-    renderComponents(components?: RenderedComponent[] | string, opts?: {
-        hideInheritBars?: boolean;
-        editBarOpts?: RenderAreaEditBarOpts;
-    }): string;
+    renderComponents(components?: RenderedComponent[] | string, opts?: RenderComponentsOpts): string;
     /**
      * helper function to print an area and set a minimum or maximum number of components
+     *
+     * In some cases you might be rendering the edit bars in a separate div instead of placing
+     * them above each component. For instance, a slider that only shows one slide at a time may
+     * prefer not to put bars with slides because that would mean only one bar is visible at a time
+     * and then there's no way to re-order slides.
+     *
+     * In that case you would call this.renderArea('areaname', { ..., skipEditBars: true }) first
+     * and then this.renderArea('areaname', { ..., skipContent: true }) in another place.
      */
-    renderArea(areaName: string, opts?: {
-        min?: number;
-        max?: number;
-        hideMaxWarning?: boolean;
-        maxWarning?: string;
-        hideInheritBars?: boolean;
-        newBarOpts?: NewBarOpts;
-        editBarOpts?: RenderAreaEditBarOpts;
-    }): string;
+    renderArea(areaName: string, opts?: RenderAreaOpts): 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
@@ -230,7 +227,7 @@ export interface PageRecord<DataType extends PageData = PageData> {
     linkId: string;
     createdAt: Date;
     modifiedAt: Date;
-    publishedAt: Date | null;
+    publishedAt?: Date;
     path: string;
     data: DataType;
     site: SiteInfo;
@@ -273,12 +270,89 @@ export interface EditBarOpts extends BarOpts {
     hideEdit?: boolean;
 }
 export interface RenderAreaEditBarOpts extends Omit<Omit<EditBarOpts, 'label'>, 'extraClass'> {
+    /**
+     * Since renderArea and renderComponents render a whole list of components,
+     * they accept functions for editBarOpts.label and editBarOpts.extraClass
+     *
+     * This way you can have labels and classes depend on the data of the component.
+     */
     label?: string | ((c: Component) => string);
+    /**
+     * Since renderArea and renderComponents render a whole list of components,
+     * they accept functions for editBarOpts.label and editBarOpts.extraClass
+     *
+     * This way you can have labels and classes depend on the data of the component.
+     */
     extraClass?: string | ((c: Component) => string);
 }
 export interface NewBarOpts extends BarOpts {
     disabled?: boolean;
 }
+export interface RenderComponentsOpts {
+    /**
+     * Hide bars entiredly for inherited items instead of allowing the user
+     * to link back to the creating page. Useful for headers and footers where it's
+     * obvious the entire site shares the data from the root page.
+     */
+    hideInheritBars?: boolean;
+    /**
+     * Do not print edit or new bars. Useful for components that have view-one-at-a-time
+     * subcomponents. If you don't move your editbars somewhere else, you'll be unable to
+     * re-order them easily.
+     */
+    skipBars?: boolean;
+    /**
+     * Do not print the content, only print edit and new bars. This is the other half
+     * of skipBars. You'd print bars in one place and content in another.
+     */
+    skipContent?: boolean;
+    /**
+     * Provide a function that wraps each component, e.g.
+     * (c: RenderedComponent) => `<li>${c.output}</li>`
+     */
+    wrap?: (c: RenderedComponent) => string;
+    /**
+     * Options for each edit bar; also accepts functions for label and extraClass
+     */
+    editBarOpts?: RenderAreaEditBarOpts;
+}
+export interface RenderAreaOpts extends RenderComponentsOpts {
+    /**
+     * Set a minimum number of components for the area.
+     *
+     * Enforcement of the minimum components is UI-only. It's possible for a
+     * page to be imported or updated via API with less than the minimum.
+     */
+    min?: number;
+    /**
+     * Set a maximum number of components for the area.
+     *
+     * Enforcement of the maximum components is UI-only. It's possible for a
+     * page to be imported or updated via API with more than the maximum.
+     */
+    max?: number;
+    /**
+     * Remove new bar when max is reached
+     *
+     * If you've set a max, the new bar will change to disabled and change its
+     * label when the max has been reached or exceeded. Set this true to completely
+     * remove the new bar instead.
+     */
+    hideMaxWarning?: boolean;
+    /**
+     * Set the maximum reached warning label
+     *
+     * If you've set a max, the new bar will change to disabled and change its
+     * label when the max has been reached or exceeded. Set this to adjust the
+     * wording of the maximum reached warning, when applicable.
+     */
+    maxWarning?: string;
+    /**
+     * Options to pass into the new bar. Note that some like 'disabled' will
+     * be overridden if you have set a max.
+     */
+    newBarOpts?: NewBarOpts;
+}
 export interface RenderedComponent<C extends Component = Component> {
     component: C;
     output: string;

package/dist/component.js

@@ -90,35 +90,46 @@ export class Component extends ResourceProvider {
     }
     /**
      * helper function to print an area's component list, but you can also override this if you
-     * need to do something advanced like wrap each component in a div
+     * need to do something advanced
      */
     renderComponents(components = [], opts) {
         if (!Array.isArray(components))
             components = this.renderedAreas.get(components) ?? [];
+        if (opts?.skipBars)
+            return components.map(c => opts.wrap?.(c) ?? c.output).join('');
         return components
-            .flatMap(c => c.component.inheritedFrom &&
-            opts?.hideInheritBars
-            ? [c.output]
+            .flatMap(c => c.component.inheritedFrom && opts?.hideInheritBars
+            ? [opts.skipContent ? '' : opts.wrap?.(c) ?? c.output]
             : [c.component.editBar({
                     ...opts?.editBarOpts,
                     label: typeof opts?.editBarOpts?.label === 'function' ? opts.editBarOpts.label(c.component) : opts?.editBarOpts?.label,
                     extraClass: typeof opts?.editBarOpts?.extraClass === 'function' ? opts.editBarOpts.extraClass(c.component) : opts?.editBarOpts?.extraClass
-                }), c.output]).join('');
+                }), opts?.skipContent ? '' : opts?.wrap?.(c) ?? c.output]).join('');
     }
     /**
      * helper function to print an area and set a minimum or maximum number of components
+     *
+     * In some cases you might be rendering the edit bars in a separate div instead of placing
+     * them above each component. For instance, a slider that only shows one slide at a time may
+     * prefer not to put bars with slides because that would mean only one bar is visible at a time
+     * and then there's no way to re-order slides.
+     *
+     * In that case you would call this.renderArea('areaname', { ..., skipEditBars: true }) first
+     * and then this.renderArea('areaname', { ..., skipContent: true }) in another place.
      */
     renderArea(areaName, opts) {
         const components = this.renderedAreas.get(areaName) ?? [];
         const ownedComponentCount = components.filter(c => !c.component.inheritedFrom).length;
         const full = !!(opts?.max && ownedComponentCount >= opts.max);
-        let output = this.renderComponents(components, { hideInheritBars: opts?.hideInheritBars, editBarOpts: { ...opts?.editBarOpts, disableDelete: ownedComponentCount <= (opts?.min ?? 0), disableDrop: full } });
-        if (full) {
-            if (!opts.hideMaxWarning)
-                output += this.newBar(areaName, { ...opts.newBarOpts, label: opts.maxWarning ?? 'Maximum Reached', disabled: true });
-        }
-        else {
-            output += this.newBar(areaName, opts?.newBarOpts);
+        let output = this.renderComponents(components, { ...opts, editBarOpts: { ...opts?.editBarOpts, disableDelete: ownedComponentCount <= (opts?.min ?? 0), disableDrop: full } });
+        if (!opts?.skipBars) {
+            if (full) {
+                if (!opts.hideMaxWarning)
+                    output += this.newBar(areaName, { ...opts.newBarOpts, label: opts.maxWarning ?? 'Maximum Reached', disabled: true });
+            }
+            else {
+                output += this.newBar(areaName, opts?.newBarOpts);
+            }
         }
         return output;
     }
@@ -175,7 +186,7 @@ export class Component extends ResourceProvider {
     editBar(opts = {}) {
         const options = { ...opts };
         options.label ?? (options.label = this.editLabel() ?? this.autoLabel);
-        options.extraClass ?? (options.extraClass = this.editClass());
+        options.extraClass = [options.extraClass, this.editClass()].filter(isNotBlank).join(' ');
         options.editMode ?? (options.editMode = this.editMode);
         options.inheritedFrom ?? (options.inheritedFrom = this.inheritedFrom);
         options.hideEdit = this.noData || options.hideEdit;
@@ -189,7 +200,7 @@ 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.extraClass ?? (options.extraClass = this.newClass(areaName));
+        options.extraClass = [options.extraClass, this.newClass(areaName)].filter(isNotBlank).join(' ');
         options.editMode ?? (options.editMode = this.editMode);
         return Component.newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), options);
     }

package/package.json

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