feat: make FlashMessage component generic for type-safe custom fields

Author: aklkv

README.md

@@ -29,6 +29,7 @@ This ember addon adds a flash message service and component to your app.
   - [TypeScript](#typescript)
     - [Basic Usage](#basic-usage)
     - [Custom Fields with Generics](#custom-fields-with-generics)
+    - [Typing Dynamically Registered Methods](#typing-dynamically-registered-methods)
   - [Displaying flash messages](#displaying-flash-messages)
     - [Custom `close` action](#custom-close-action)
     - [Styling with Foundation or Bootstrap](#styling-with-foundation-or-bootstrap)
@@ -499,6 +500,58 @@ this.flashMessages.success('Oops', {
 });
 ```
 
+Custom fields are also type-safe in templates. The `FlashMessage` component exposes the properly typed flash object with your custom fields:
+
+```gjs
+import { FlashMessage } from 'ember-cli-flash';
+
+<template>
+  {{#each this.flashMessages.queue as |flash|}}
+    <FlashMessage @flash={{flash}} as |component flash close|>
+      {{flash.message}}
+      {{flash.category}}  {{! ✓ Typed as 'system' | 'user' | 'background' | undefined }}
+      {{#if flash.action}}
+        <button type="button" {{on "click" flash.action}}>Action</button>
+      {{/if}}
+    </FlashMessage>
+  {{/each}}
+</template>
+```
+
+### Typing Dynamically Registered Methods
+
+When you configure custom `types` in `flashMessageDefaults`, the service dynamically creates convenience methods for each type at runtime. The base class already declares types for the default methods (`success`, `info`, `warning`, `danger`, `alert`, `secondary`), but TypeScript doesn't automatically recognize any custom types you add.
+
+To get type safety for custom type methods, declare them explicitly in your service subclass:
+
+```typescript
+import { FlashMessagesService } from 'ember-cli-flash';
+import type { FlashObjectOptions } from 'ember-cli-flash';
+
+interface CustomFlashFields {
+  id?: string;
+  category?: string;
+}
+
+type Options = FlashObjectOptions & CustomFlashFields;
+
+export default class MyFlashMessages extends FlashMessagesService<CustomFlashFields> {
+  // Only declare custom types not in the base class
+  // (success, info, warning, danger, alert, secondary are already typed)
+  declare error: (message: string, options?: Options) => this;
+  declare custom: (message: string, options?: Options) => this;
+
+  get flashMessageDefaults() {
+    return {
+      ...super.flashMessageDefaults,
+      types: ['error', 'success', 'warning', 'custom'],
+    };
+  }
+}
+```
+
+This pattern uses TypeScript's `declare` keyword to inform the type system about methods that exist at runtime but aren't defined in the base class types.
+
 ## Displaying flash messages
 
 Then, to display somewhere in your app, add this to your component:

UPGRADING.md

@@ -132,8 +132,14 @@ Register custom types for your application:
 ```typescript
 // app/services/flash-messages.ts
 import { FlashMessagesService } from 'ember-cli-flash';
+import type { FlashObjectOptions } from 'ember-cli-flash';
 
 export default class FlashMessages extends FlashMessagesService {
+  // Declare custom types for TypeScript (base types like success, warning are already typed)
+  declare notice: (message: string, options?: FlashObjectOptions) => this;
+  declare error: (message: string, options?: FlashObjectOptions) => this;
+  declare system: (message: string, options?: FlashObjectOptions) => this;
+
   get flashMessageDefaults() {
     return {
       ...super.flashMessageDefaults,
@@ -247,6 +253,17 @@ const flash = this.flashMessages.findBy('id', 'save-notification');
 this.flashMessages.removeBy('userId', 123);
 ```
 
+The `FlashMessage` component is also generic and infers the type from the `@flash` arg, giving you type-safe access to custom fields in templates:
+
+```gjs
+{{#each this.flashMessages.queue as |flash|}}
+  <FlashMessage @flash={{flash}} as |component flash close|>
+    {{flash.message}}
+    {{flash.actionUrl}}  {{! ✓ Typed as string | undefined }}
+  </FlashMessage>
+{{/each}}
+```
+
 ### New Methods: `findBy` and `removeBy`
 
 Two new methods have been added to the service for finding and removing flash messages by any field:

demo-app/components/demo-examples.gts

@@ -76,6 +76,19 @@ export default class DemoExamples extends Component {
     });
   };
 
+  // Custom typed methods (declared in service)
+  showError = () => {
+    this.flashMessages.error('Something went wrong!', {
+      category: 'system',
+    });
+  };
+
+  showNotice = () => {
+    this.flashMessages.notice('Did you know? This is a custom notice type.', {
+      timeout: 5000,
+    });
+  };
+
   // Custom fields with generics
   showWithCustomFields = () => {
     this.flashMessages.success('Message with custom fields', {
@@ -319,17 +332,35 @@ export default class DemoExamples extends Component {
       <p class="text-muted small mb-3">
         Use
         <code>add()</code>
-        with any Bootstrap alert type or your own custom types
+        with any Bootstrap alert type, or declare custom types in your service
       </p>
-      <button
-        type="button"
-        class="btn btn-secondary"
-        {{on "click" this.showCustomType}}
-      >
-        Show Secondary Type
-      </button>
-      <pre><code>this.flashMessages.add({ message: 'Custom type message', type:
-          'secondary', timeout: 4000, });</code></pre>
+      <div class="btn-group-example mb-2">
+        <button
+          type="button"
+          class="btn btn-secondary"
+          {{on "click" this.showCustomType}}
+        >
+          Secondary (via add)
+        </button>
+        <button
+          type="button"
+          class="btn btn-danger"
+          {{on "click" this.showError}}
+        >
+          Error (custom type)
+        </button>
+        <button
+          type="button"
+          class="btn btn-light"
+          {{on "click" this.showNotice}}
+        >
+          Notice (custom type)
+        </button>
+      </div>
+      <pre><code>// Custom types declared in service: // declare error:
+          (message: string, options?: Options) => this;
+          this.flashMessages.error('Something went wrong!');
+          this.flashMessages.notice('Did you know?');</code></pre>
     </section>
 
     {{! TypeScript Generics }}

demo-app/components/flash-container.gts

@@ -16,7 +16,17 @@ export default class FlashContainer extends Component {
           <div class="d-flex justify-content-between align-items-start">
             <div>
               <strong>{{component.flashType}}</strong>
-              <p class="mb-0 mt-1">{{flashData.message}}</p>
+              {{#if flashData.category}}
+                <span class="badge bg-secondary ms-2">
+                  {{flashData.category}}
+                </span>
+              {{/if}}
+              <p class="mb-0 mt-1">
+                {{flashData.message}}
+              </p>
+              {{#if flashData.id}}
+                <small class="text-muted">ID: {{flashData.id}}</small>
+              {{/if}}
             </div>
             <button
               type="button"

demo-app/services/flash-messages.ts

@@ -1,5 +1,7 @@
 import FlashMessagesService from '#src/services/flash-messages.ts';
 
+import type { FlashObjectOptions } from '#src/flash/object.ts';
+
 /**
  * Custom fields interface for our flash messages.
  * This demonstrates TypeScript generics support.
@@ -15,13 +17,24 @@ export interface CustomFlashFields {
   onAction?: () => void;
 }
 
+/** Options type combining flash options with custom fields */
+type Options = FlashObjectOptions<CustomFlashFields> & CustomFlashFields;
+
 /**
  * Extended FlashMessages service demonstrating:
  * - TypeScript generics for custom fields
  * - Custom default configuration
  * - Custom convenience methods
+ * - Dynamically registered custom types
  */
 export default class MyFlashMessagesService extends FlashMessagesService<CustomFlashFields> {
+  /**
+   * Declare custom types not in the base class.
+   * Base class already declares: success, info, warning, danger, alert, secondary
+   */
+  declare error: (message: string, options?: Options) => this;
+  declare notice: (message: string, options?: Options) => this;
+
   /**
    * Override defaults to customize behavior
    */
@@ -30,6 +43,17 @@ export default class MyFlashMessagesService extends FlashMessagesService<CustomF
       ...super.flashMessageDefaults,
       timeout: 4000,
       showProgress: false,
+      // Add custom types (base types are included automatically)
+      types: [
+        'success',
+        'info',
+        'warning',
+        'danger',
+        'alert',
+        'secondary',
+        'error',
+        'notice',
+      ],
     };
   }
 

package.json

@@ -86,7 +86,7 @@
     "@embroider/compat": "^4.1.13",
     "@embroider/core": "^4.4.3",
     "@embroider/macros": "^1.19.7",
-    "@embroider/vite": "^1.5.1",
+    "@embroider/vite": "^1.5.2",
     "@eslint/js": "^9.39.2",
     "@glimmer/component": "^2.0.0",
     "@glint/ember-tsc": "^1.1.1",
@@ -111,7 +111,7 @@
     "globals": "^17.3.0",
     "prettier": "^3.8.1",
     "prettier-plugin-ember-template-tag": "^2.1.3",
-    "publint": "^0.3.16",
+    "publint": "^0.3.17",
     "qunit": "^2.25.0",
     "qunit-dom": "^3.5.0",
     "release-plan": "^0.17.4",
@@ -125,7 +125,7 @@
     "@embroider/macros": "^1.13.2",
     "ember-modifier": ">= 4.0.0"
   },
-  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264",
+  "packageManager": "pnpm@10.29.1+sha512.48dae233635a645768a3028d19545cacc1688639eeb1f3734e42d6d6b971afbf22aa1ac9af52a173d9c3a20c15857cfa400f19994d79a2f626fcc73fccda9bbc",
   "engines": {
     "node": ">= 24",
     "pnpm": ">= 10"

pnpm-lock.yaml

@@ -8,20 +8,28 @@ import { modifier } from 'ember-modifier';
 import type { Timer } from '@ember/runloop';
 import type FlashObject from '../flash/object.ts';
 
-export interface FlashMessageSignature {
+// FlashObject with custom properties from T accessible in yielded block
+type FlashWithCustomProps<T extends Record<string, unknown>> = FlashObject<T> &
+  T;
+
+export interface FlashMessageSignature<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> {
   Args: {
-    flash: FlashObject;
+    flash: FlashObject<T>;
     messageStyle?: 'bootstrap' | 'foundation';
     messageStylePrefix?: string;
     exitingClass?: string;
   };
   Element: HTMLDivElement;
   Blocks: {
-    default: [FlashMessage, FlashObject, onClose: () => void];
+    default: [FlashMessage<T>, FlashWithCustomProps<T>, onClose: () => void];
   };
 }
 
-export default class FlashMessage extends Component<FlashMessageSignature> {
+export default class FlashMessage<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> extends Component<FlashMessageSignature<T>> {
   @tracked active = false;
   @tracked pendingSet: Timer | undefined;
   @tracked _mouseEnterHandler: ((event?: Event) => void) | undefined;
@@ -31,6 +39,11 @@ export default class FlashMessage extends Component<FlashMessageSignature> {
     return this.args.messageStyle ?? 'bootstrap';
   }
 
+  // Expose flash with custom properties typed (for yielding to blocks)
+  get flash(): FlashWithCustomProps<T> {
+    return this.args.flash as FlashWithCustomProps<T>;
+  }
+
   get showProgress() {
     return this.args.flash.showProgress;
   }
@@ -167,7 +180,7 @@ export default class FlashMessage extends Component<FlashMessageSignature> {
       {{this.bindEvents}}
     >
       {{#if (has-block)}}
-        {{yield this @flash this.onClose}}
+        {{yield this this.flash this.onClose}}
       {{else}}
         {{@flash.message}}
         {{#if this.showProgressBar}}

src/components/flash-message.gts

@@ -42,8 +42,8 @@ export default class FlashObject<
   // Defaults to true in test environment via @embroider/macros
   static isTimeoutDisabled = defaultDisableTimeout;
 
-  // Index signature for custom properties from T
-  [key: string]: unknown;
+  // Note: Custom properties from T are copied at runtime in constructor
+  // TypeScript sees them via FlashObject<T> & T intersection in service/component
 
   @tracked exiting = false;