element/ak-empty-state: consistency check

# What

- Removes the unused Interface declaration
- Harmonizes the sizes: Component, Template, and Builder all agree “large” is the default
- Change ‘no-icon’ boolean attribute to ‘text-only’ (HTML tries to “use positive names for attributes”)
- Fixes some of the rendering issues in the builder:
  - Fix “secondary-actions” slot name
  - Use `<h2>` with string-only title
  - Use `<p>` with string-only body
  - Use `<ak-icon>` with string-only icon
  - Remove unloved console.log() :-)
  - Add story to Storybook “builder” section to show string-only usage

Author: kensternberg-authentik

src/ak-empty-state/ak-empty-state.builder.ts

@@ -2,15 +2,14 @@ import "./ak-empty-state.component.js";
 
 import { EmptyState } from "./ak-empty-state.component.js";
 
+import { match, P } from "ts-pattern";
+
 import { html, TemplateResult } from "lit";
 import { ifDefined } from "lit/directives/if-defined.js";
 
 /* The `pick`ed fields here correspond to their types in the EmptyState class above. */
 
-export interface EmptyStateProps extends Partial<
-    Pick<EmptyState, "size" | "loading" | "textOnly" | "spinnerOnly">
-> {
-    fullHeight?: boolean;
+export interface EmptyStateSlots {
     icon?: string | TemplateResult;
     title?: string | TemplateResult;
     body?: string | TemplateResult;
@@ -19,39 +18,55 @@ export interface EmptyStateProps extends Partial<
     secondaryActions?: string | TemplateResult;
 }
 
-const SLOTNAMES: (keyof EmptyStateProps)[] = [
+export type EmptyStateProps = Partial<
+    Pick<EmptyState, "size" | "loading" | "textOnly" | "spinnerOnly">
+> &
+    EmptyStateSlots & { fullHeight?: boolean };
+
+const SLOTNAMES: (keyof EmptyStateSlots)[] = [
     "icon",
     "title",
     "body",
     "footer",
     "actions",
     "secondaryActions",
-];
+] as const;
+
+type SlotName = (typeof SLOTNAMES)[number];
+
+type SlotContent = string | TemplateResult | undefined;
 
 /**
  * @summary Helper function to create an EmptyState component programmatically
  *
  * @returns {TemplateResult} A Lit template result containing the configured ak-empty-state element
  *
+ * NOTE: This function does not edit TemplateResults passed in. If you pass in a TemplateResult, it
+ * *must* indicated what slot it's being added to, even if you think the prop should handle it.
+ *
  * @see {@link EmptyState} - The underlying web component
  */
 export function akEmptyState(options: EmptyStateProps) {
     const slots = SLOTNAMES.filter((s) => !!options[s]);
 
+    const slotRenderer = (s: string, c: string | TemplateResult) => html`<div slot=${s}>${c}</div>`;
+
+    const slotHandler = (s: SlotName) =>
+        match<[SlotContent, SlotName], SlotContent>([options[s], s])
+            .with([P.string, "secondaryActions"], ([c]) => slotRenderer("secondary-actions", c))
+            .with([P.string, "title"], ([c]) => html`<h2 slot="title">${c}</h2>`)
+            .with([P.string, "body"], ([c]) => html`<p slot="body">${c}</p>`)
+            .with(
+                [P.string, "icon"],
+                ([option]) => html`<ak-icon slot="icon" icon=${option}></ak-icon>`,
+            )
+            .with([P.string, P._], ([option, s]) => slotRenderer(s, option))
+            .otherwise(() => options[s]);
+
     let opts = {
         ...options,
-        ...Object.fromEntries(
-            slots.map((s) => [
-                s,
-                typeof options[s] === "string"
-                    ? html`<div slot=${s === "secondaryActions" ? "secondary-actions" : s}>
-                          ${options[s]}
-                      </div>`
-                    : options[s],
-            ]),
-        ),
+        ...Object.fromEntries(slots.map((s) => [s, slotHandler(s)])),
     };
-    console.log(opts);
 
     const { size, fullHeight, spinnerOnly, textOnly, loading } = opts;
 

src/ak-empty-state/ak-empty-state.component.ts

@@ -19,6 +19,7 @@ import { property } from "lit/decorators.js";
  * @attr {boolean} spinner-only - Shows only the spinner, not the (localized) text "Loading..." when `loading` is true
  * @attr {boolean} text-only - Hides the default icon when true
  * @attr {boolean} full-height - Makes component take full height of container
+ * @attr {string} icon - The name of an icon, as understood by ak-icon. NOTE: if both this attribute and the `icon` slot are used, the slot takes priority.
  *
  * @slot icon - Icon displayed at the top of the empty state
  * @slot title - Title describing the empty state

src/ak-empty-state/ak-empty-state.stories.ts

@@ -262,8 +262,8 @@ export const SizeVariants: Story = {
             </div>
 
             <div>
-                <h3>Default (large)</h3>
-                <ak-empty-state>
+                <h3>Medium</h3>
+                <ak-empty-state size="md">
                     <h2 slot="title">No results found</h2>
                     <p slot="body">
                         No results match the filter criteria. Clear all filters and try again.
@@ -275,8 +275,8 @@ export const SizeVariants: Story = {
             </div>
 
             <div>
-                <h3>Large</h3>
-                <ak-empty-state size="lg">
+                <h3>Large (Default)</h3>
+                <ak-empty-state>
                     <h2 slot="title">No results found</h2>
                     <p slot="body">
                         No results match the filter criteria. Clear all filters and try again.
@@ -332,6 +332,30 @@ export const HelperFunction: Story = {
                     ><button>Secondary Action</button>`,
                 footer: html`<a href="#" slot="footer">Learn more about this state</a>`,
             })}
+            ${akEmptyState({
+                size: "lg",
+                fullHeight: false,
+                title: html`<h2 slot="title">AKIcon Token Usage</h2>`,
+                icon: "fas fa-face-dizzy",
+                body: html`<p slot="body">
+                    What the empty state looks like if you pass an ak-icon token to ak-empty-state's
+                    builder's
+                    <kbd>icon</kbd> field.
+                </p>`,
+                actions: html`<button slot="actions">Primary Action</button
+                    ><button>Secondary Action</button>`,
+                footer: html`<a href="#" slot="footer">Learn more about this state</a>`,
+            })}
+            ${akEmptyState({
+                size: "lg",
+                fullHeight: false,
+                title: "Just With Strings",
+                icon: "fas fa-meteor",
+                body: "Using the sweet meteor of doom to demonstrate what this looks like using mostly string arguments to the builder.",
+                actions: html`<button slot="actions">Primary Action</button
+                    ><button>Secondary Action</button>`,
+                footer: "Nothing more need be said.",
+            })}
         </div>
     `,
 };

src/ak-empty-state/ak-empty-state.template.ts

@@ -5,10 +5,14 @@ import { html, nothing } from "lit";
 
 export const emptyStateSizes = ["xs", "sm", "md", "lg", "xl"] as const;
 export type EmptyStateSize = (typeof emptyStateSizes)[number];
-const DEFAULT_SIZE_INDEX = emptyStateSizes.indexOf("md");
+const DEFAULT_SIZE_INDEX = emptyStateSizes.indexOf("lg");
 const isEmptyStateSize = (s?: string): s is EmptyStateSize =>
     typeof s === "string" && s.trim() !== "" && emptyStateSizes.includes(s as EmptyStateSize);
 
+// The size of the spinner and the icon do not automatically scale with the size of the EmptyState
+// object itself. After much experimentation, the design team has settled on the pattern below as
+// having the best aesthetics.
+
 const spinnerSizes = ["md", "lg", "lg", "xl", "xl"];
 const iconSizes = ["sm", "md", "lg", "xl", "6x"];
 
@@ -17,7 +21,7 @@ function iconTemplate(
     icon: string | undefined,
     skipIcon: boolean,
     isLoading: boolean,
-    size: EmptyStateSize,
+    size: EmptyStateSize
 ) {
     if (useSlot) {
         return html`<div part="icon"><slot name="icon"></slot></div>`;
@@ -63,8 +67,7 @@ const secondaryActionsTemplate = (has: boolean) =>
           </div>`
         : nothing;
 
-const footerTemplate = (has: boolean) =>
-    has ? html`<div part="footer"><slot name="footer"></slot></div>` : nothing;
+const footerTemplate = (has: boolean) => (has ? html`<div part="footer"><slot name="footer"></slot></div>` : nothing);
 
 interface EmptyStateTemplateProps {
     hasTitle: boolean;
@@ -109,8 +112,7 @@ export function template(props: EmptyStateTemplateProps) {
                 ${bodyTemplate(hasBody, showLoading)}
                 ${hasFooter
                     ? html` <div part="footer">
-                          ${actionsTemplate(hasActions)}
-                          ${secondaryActionsTemplate(hasSecondaryActions)}
+                          ${actionsTemplate(hasActions)} ${secondaryActionsTemplate(hasSecondaryActions)}
                           ${footerTemplate(hasFooterContent)}
                       </div>`
                     : nothing}

src/ak-empty-state/ak-empty-state.test.ts

@@ -113,15 +113,15 @@ describe("ak-empty-state component", () => {
         await expect.element(iconSlot).toBeInTheDocument();
     });
 
-    it("should render custom icon even when no-icon is true", async () => {
+    it("should render custom icon even when text-only is true", async () => {
         render(
-            html`<ak-empty-state no-icon>
+            html`<ak-empty-state text-only>
                 <div slot="icon">
                     <svg viewBox="0 0 24 24">
                         <path d="M12 2L1 21h22L12 2z" />
                     </svg>
                 </div>
-                <h2 slot="title">Custom icon with no-icon</h2>
+                <h2 slot="title">Custom icon with text-only setting</h2>
             </ak-empty-state>`,
         );