@dosgato/templating 0.0.70 → 0.0.72

package/dist/component.d.ts

@@ -112,14 +112,9 @@ 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;
-        skipBars?: boolean;
-        skipContent?: 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
      *
@@ -131,17 +126,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * 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;
-        skipBars?: boolean;
-        skipContent?: 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
@@ -285,12 +270,93 @@ 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.
+     * (output: string) => `<li>${output}</li>`
+     *
+     * Note that the wrap will also go around the edit bar.
+     *
+     * If you need it (unlikely), the full component object is provided as a second parameter.
+     */
+    wrap?: (output: string, c: Component) => 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

@@ -1,5 +1,6 @@
 import { isNotBlank } from 'txstate-utils';
 import { ResourceProvider } from './provider.js';
+function defaultWrap(output) { return output; }
 /**
  * This is the primary templating class to build your templates. Subclass it and provide
  * at least a render function.
@@ -90,21 +91,22 @@ 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) ?? [];
+        const wrap = opts?.wrap ?? defaultWrap;
         if (opts?.skipBars)
-            return components.map(c => c.output).join('');
+            return components.map(c => wrap(c.output, c.component)).join('');
         return components
-            .flatMap(c => c.component.inheritedFrom && opts?.hideInheritBars
-            ? [opts.skipContent ? '' : c.output]
-            : [c.component.editBar({
+            .map(c => c.component.inheritedFrom && opts?.hideInheritBars
+            ? (opts.skipContent ? '' : wrap(c.output, c.component))
+            : wrap([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
-                }), opts?.skipContent ? '' : c.output]).join('');
+                }), opts?.skipContent ? '' : c.output].join(''), c.component)).join('');
     }
     /**
      * helper function to print an area and set a minimum or maximum number of components
@@ -121,7 +123,7 @@ export class Component extends ResourceProvider {
         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, skipBars: opts?.skipBars, skipContent: opts?.skipContent, editBarOpts: { ...opts?.editBarOpts, disableDelete: ownedComponentCount <= (opts?.min ?? 0), disableDrop: full } });
+        let output = this.renderComponents(components, { ...opts, editBarOpts: { ...opts?.editBarOpts, disableDelete: ownedComponentCount <= (opts?.min ?? 0), disableDrop: full } });
         if (!opts?.skipBars) {
             if (full) {
                 if (!opts.hideMaxWarning)
@@ -186,7 +188,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;
@@ -200,7 +202,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.70",
+  "version": "0.0.72",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {