From 234d52de3bb91c6664af32403bec9889af0faa50 Mon Sep 17 00:00:00 2001
From: Ken Sternberg <ken@goauthentik.io>
Date: Tue, 14 May 2024 16:38:44 -0700
Subject: [PATCH] Added a ton of documentation; made the failure message
 configurable.

---
 web/src/elements/cards/AggregateCard.ts       | 35 +++++++++++++++++++
 .../elements/cards/AggregatePromiseCard.ts    | 29 +++++++++++++--
 .../stories/AggregatePromiseCard.stories.ts   |  7 ++--
 3 files changed, 66 insertions(+), 5 deletions(-)

diff --git a/web/src/elements/cards/AggregateCard.ts b/web/src/elements/cards/AggregateCard.ts
index 44916f7945..847b2c5d83 100644
--- a/web/src/elements/cards/AggregateCard.ts
+++ b/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;
 
diff --git a/web/src/elements/cards/AggregatePromiseCard.ts b/web/src/elements/cards/AggregatePromiseCard.ts
index 45205e4eb9..e7170cd020 100644
--- a/web/src/elements/cards/AggregatePromiseCard.ts
+++ b/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(
-                    "Operation failed to complete",
-                )}`;
+            return html`<i class="fa fa-exclamation-circle"></i>&nbsp;${this.failureMessage}`;
         }
     }
 
diff --git a/web/src/elements/cards/stories/AggregatePromiseCard.stories.ts b/web/src/elements/cards/stories/AggregatePromiseCard.stories.ts
index 016f28929c..32dd0f0f0f 100644
--- a/web/src/elements/cards/stories/AggregatePromiseCard.stories.ts
+++ b/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));
 
@@ -85,7 +87,8 @@ export const PromiseRejected: StoryObj = {
                 header=${ifDefined(header)}
                 headerLink=${ifDefined(headerLink)}
                 subtext=${ifDefined(subtext)}
-                icon=${ifDefined(icon)}
+icon=${ifDefined(icon)}
+failureMessage=${ifDefined(failureMessage)}
                 ?left-justified=${leftJustified}
                 .promise=${runThis(8000, text)}
             >