@genesislcap/foundation-events 14.67.2 → 14.67.3

package/dist/esm/eventEmitter/eventEmitterDI.js

@@ -1,5 +1,10 @@
 import { DI } from '@microsoft/fast-foundation';
 import { getBaseEmitArgs } from '../types';
+/**
+ * Default EventEmitterDI.
+ * @typeParam TEventDetailMap - The {@link EventDetailMap}.
+ * @public
+ */
 export class DefaultEventEmitterDI {
     emit(...args) {
         const [origin, ...rest] = args;
@@ -7,7 +12,16 @@ export class DefaultEventEmitterDI {
         return origin.$emit(type, detail, options);
     }
 }
+/**
+ * EventEmitterDI DI key.
+ * @internal
+ */
 export const EventEmitterDI = DI.createInterface((x) => x.singleton(DefaultEventEmitterDI));
+/**
+ * Register an emitter with the DI.
+ * @typeParam TEventDetailMap - The {@link EventDetailMap}.
+ * @public
+ */
 export const registerEmitter = () => {
     return DI.createInterface((x) => x.aliasTo(EventEmitterDI));
 };

package/dist/esm/eventEmitter/eventEmitterMixin.js

@@ -1,7 +1,60 @@
 import { getBaseEmitArgs, } from '../types';
-export const EventEmitter = (Base) => class extends Base {
-    $emit(...args) {
-        const [type, detail, options] = getBaseEmitArgs(...args);
-        return super.$emit(type, detail, options);
+/**
+ * EventEmitter mixin.
+ *
+ * @remarks
+ * Strongly types the components `$emit` method, allowing only the mapped events to be emitted.
+ *
+ * @example
+ * Apply mixin to the base {@link @microsoft/fast-element#FASTElement | FASTElement}
+ *
+ * # Import
+ * ```ts
+ * import { EventEmitter, SomeSystemLevelEventDetailMap } from '@genesislcap/foundation-events';
+ * import { StoreEventDetailMap, TradeEntryEventDetailMap } from '../store'; // < custom app level event maps
+ * ```
+ *
+ * # Create event map
+ * ```ts
+ * type EventMap = SomeSystemLevelEventDetailMap & StoreEventDetailMap & TradeEntryEventDetailMap;
+ * ```
+ *
+ * # Apply Mixin
+ * ```ts
+ * export class MyComponent extends EventEmitter<EventMap>(FASTElement) {
+ *   onSomeComponentEvent() {
+ *     this.$emit('some-allowed-event', { foo: 'expected data structure' });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Apply mixin to a class in the inheritance chain requires a second generic type param.
+ *
+ * # Apply Mixin to MyComponent that extends MyBaseComponent (which might be abstract). Mixin can be applied at different levels.
+ * # Please note there's a current limitation on retaining protected member access with this approach, so apply to base where possible.
+ * # Also, super classes cannot emit typed events via inheritance. Each level must have an explicit map. Devs can use a Union and Pick to create these.
+ * ```ts
+ * export class MyComponent extends EventEmitter<EventMap, MyBaseComponent>(MyBaseComponent) {}
+ * ```
+ *
+ * @privateRemarks
+ * Failed to retain protected member access when the mixin is applied while keeping the typed emitter, we can revisit if needed.
+ * So in the last example, if `MyBaseComponent` had a protected member, `MyComponent` wouldn't be able to access it with the mixin
+ * applied. Public members are fine. It may be a limitation of TypeScript. Suggestions welcome, but be warned it's a time sink.
+ *
+ * @typeParam TEventDetailMap - The {@link EventDetailMap}.
+ * @typeParam TTarget - The target class.
+ * @param Target - The class to apply the mixin to which ultimately extends {@link @microsoft/fast-element#FASTElement | FASTElement}.
+ * @public
+ */
+export const EventEmitter = (Target) => {
+    // @ts-ignore used here instead of `extends (Target as EventEmitterTarget<FASTElement>)` to avoid modifying return type
+    class Mixin extends Target {
+        $emit(...args) {
+            const [type, detail, options] = getBaseEmitArgs(...args);
+            return super.$emit(type, detail, options);
+        }
     }
+    return Mixin;
 };

package/dist/esm/index.js

@@ -1,2 +1,3 @@
 export * from './eventEmitter';
 export * from './types';
+export * from './utils';

package/dist/esm/types.js

@@ -1,6 +1,12 @@
+/**
+ * @public
+ */
 const isEmitOptions = (candidate) => (candidate === null || candidate === void 0 ? void 0 : candidate.hasOwnProperty('bubbles')) ||
     (candidate === null || candidate === void 0 ? void 0 : candidate.hasOwnProperty('cancelable')) ||
     (candidate === null || candidate === void 0 ? void 0 : candidate.hasOwnProperty('composed'));
+/**
+ * @public
+ */
 export const getBaseEmitArgs = (...args) => {
     let [type, detailOrOptions, options] = args;
     let detail = detailOrOptions;
@@ -13,9 +19,51 @@ export const getBaseEmitArgs = (...args) => {
     }
     return [type, detail, options];
 };
+/**
+ * @public
+ */
 export const customEvent = (ctx) => ctx.event;
+/**
+ * @public
+ */
 export const targetValue = (ctx) => ctx.event.target.value;
+/**
+ * @public
+ */
 export const targetFirstSelectedValue = (ctx) => { var _a, _b; return (_b = (_a = ctx.event.target) === null || _a === void 0 ? void 0 : _a.firstSelectedOption) === null || _b === void 0 ? void 0 : _b.value; };
+/**
+ * @internal
+ */
 const createChangeEmitter = (valueGetter) => (type, options) => (x, c) => x.$emit(String(type), valueGetter(c), options);
+/**
+ * `<input>` template emit helper.
+ *
+ * @remarks
+ * In some.template.ts file you create the helper upfront by passing in the full event map.
+ *
+ * @example
+ * ```ts
+ * const inputEmit = createInputEmitter<EventMap>();
+ * ...
+ * <zero-text-field @change="${inputEmit('some-input-changed')}">
+ * ```
+ *
+ * @public
+ */
 export const createInputEmitter = () => createChangeEmitter(targetValue);
+/**
+ * `<select>` template emit helper.
+ *
+ * @remarks
+ * In some.template.ts file you create the helper upfront by passing in the full event map.
+ *
+ * @example
+ * ```ts
+ * const selectEmit = createSelectEmitter<EventMap>();
+ * ...
+ * <zero-select @change="${selectEmit('some-select-changed')}">
+ * ```
+ *
+ * @public
+ */
 export const createSelectEmitter = () => createChangeEmitter(targetFirstSelectedValue);

package/dist/esm/utils/index.js

@@ -0,0 +1 @@
+export * from './logger';

package/dist/esm/utils/logger.js

@@ -0,0 +1,5 @@
+import { createLogger } from '@genesislcap/foundation-utils';
+/**
+ * @public
+ */
+export const logger = createLogger('foundation-events');