Added a ton of documentation; made the failure message configurable.

web/src/elements/cards/AggregateCard.ts

@@ -16,20 +16,55 @@ export interface IAggregateCard {
     leftJustified?: boolean;
 }
 
+/**
+ * class AggregateCard
+ * element ak-aggregate-card
+ *
+ * @slot - The main content of the card
+ *
+ * Card component with a specific layout for quick informational blurbs
+ */
 @customElement("ak-aggregate-card")
 export class AggregateCard extends AKElement implements IAggregateCard {
+    /**
+     * If this contains an `fa-` style string, the FontAwesome icon specified will be shown next to
+     * the header.
+     *
+     * @attr
+     */ 
     @property()
     icon?: string;
 
+    /**
+     * The title of the card.
+     *
+     * @attr
+     */ 
     @property()
     header?: string;
 
+    /**
+     * If this is non-empty, a link icon will be shown in the upper-right corner of the card.
+     *
+     * @attr
+     */ 
     @property()
     headerLink?: string;
 
+    /**
+     * If this is non-empty, a small-text footer will be shown at the bottom of the card
+     *
+     * @attr
+     */ 
     @property()
     subtext?: string;
 
+    /**
+     * If this is set, the contents of the card will be left-justified; otherwise they will be
+     * centered by default.
+     *
+     * @attr
+     */ 
     @property({ type: Boolean, attribute: "left-justified" })
     leftJustified = false;
 

web/src/elements/cards/AggregatePromiseCard.ts

@@ -9,13 +9,38 @@ import { until } from "lit/directives/until.js";
 
 export interface IAggregatePromiseCard extends IAggregateCard {
     promise?: Promise<Record<string, unknown>>;
+    failureMessage?: string;
 }
 
+/**
+ * class AggregatePromiseCard
+ * element ak-aggregate-card-promise
+ *
+ * Card component with a specific layout for quick informational blurbs, fills in its main content
+ * with the results of a promise; shows a spinner when the promise has not yet resolved. Inherits
+ * from [AggregateCard](./AggregateCard.ts).
+ */
+
 @customElement("ak-aggregate-card-promise")
 export class AggregatePromiseCard extends AggregateCard implements IAggregatePromiseCard {
+
+    /**
+     * If this contains an `fa-` style string, the FontAwesome icon specified will be shown next to
+     * the header.
+     *
+     * @attr
+     */ 
     @property({ attribute: false })
     promise?: Promise<Record<string, unknown>>;
 
+    /**
+     * The error message if the promise is rejected or throws an exception. 
+     *
+     * @attr
+     */ 
+    @property()
+    failureMessage = msg("Operation failed to complete");
+
     async promiseProxy(): Promise<TemplateResult | typeof nothing> {
         if (!this.promise) {
             return nothing;
@@ -25,9 +50,7 @@ export class AggregatePromiseCard extends AggregateCard implements IAggregatePro
             return html`<i class="fa fa-check-circle"></i>&nbsp;${value.toString()}`;
         } catch (error: unknown) {
             console.warn(error);
-            return html`<i class="fa fa-exclamation-circle"></i>&nbsp;${msg(
+            return html`<i class="fa fa-exclamation-circle"></i>&nbsp;${this.failureMessage}`;
-                    "Operation failed to complete",
-                )}`;
         }
     }
 

web/src/elements/cards/stories/AggregatePromiseCard.stories.ts

@@ -20,6 +20,7 @@ const metadata: Meta<AggregatePromiseCard> = {
         headerLink: { control: "text" },
         subtext: { control: "text" },
         leftJustified: { control: "boolean" },
+        failureMessage: { control: "text" },
     },
 };
 
@@ -68,8 +69,9 @@ export const PromiseRejected: StoryObj = {
         headerLink: undefined,
         subtext: "Demo has an eight second delay until rejection",
         leftJustified: false,
+        failureMessage: undefined,
     },
-    render: ({ icon, header, headerLink, subtext, leftJustified }: IAggregatePromiseCard) => {
+    render: ({ icon, header, headerLink, subtext, leftJustified, failureMessage }: IAggregatePromiseCard) => {
         const runThis = (timeout: number, value: string) =>
             new Promise((_resolve, reject) => setTimeout(reject, timeout, value));
 
@@ -86,6 +88,7 @@ export const PromiseRejected: StoryObj = {
                 headerLink=${ifDefined(headerLink)}
                 subtext=${ifDefined(subtext)}
 icon=${ifDefined(icon)}
+failureMessage=${ifDefined(failureMessage)}
                 ?left-justified=${leftJustified}
                 .promise=${runThis(8000, text)}
             >