@vyriy/event 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @vyriy/event
+
+Shared helpers for building and dispatching `CustomEvent` in Vyriy microfrontends.
+
+## Purpose
+
+This package implements two small outbound event helper groups aligned with the openmfe event rules:
+
+- `custom` validates and dispatches microfrontend-owned custom events
+- `analytics` creates and dispatches the standard `openmfe.analytics` event
+
+Invalid input throws an `Error`.
+
+The root package entry point re-exports both groups for backwards-compatible imports.
+
+## Install
+
+With npm:
+
+```bash
+npm install @vyriy/event
+```
+
+With Yarn:
+
+```bash
+yarn add @vyriy/event
+```
+
+## Event Naming Rules
+
+Regular custom event names must:
+
+- use lowercase latin letters, numbers, dashes, and dots
+- start with the microfrontend tag name
+- contain at least one additional name level
+- start and end with a lowercase latin letter
+
+Example of a valid event name:
+
+```text
+mf-shell.checkout.completed
+```
+
+## Usage
+
+Create a validated event:
+
+```ts
+import { createCustomEvent } from '@vyriy/event';
+
+const event = createCustomEvent('mf-shell', 'mf-shell.checkout.completed', {
+  orderId: '42',
+});
+```
+
+Dispatch an event from the microfrontend element itself:
+
+```ts
+import { dispatchCustomEvent } from '@vyriy/event';
+
+const element = document.querySelector('mf-shell');
+
+dispatchCustomEvent(element!, 'mf-shell.checkout.completed', {
+  orderId: '42',
+});
+```
+
+Emit the standard openmfe analytics event:
+
+```ts
+import { dispatchAnalyticsEvent } from '@vyriy/event';
+
+const element = document.querySelector('mf-shell');
+
+dispatchAnalyticsEvent(element!, {
+  name: 'checkout_submit',
+  action: 'submit form',
+  category: 'checkout',
+  variant: 'b',
+  data: {
+    step: 2,
+  },
+});
+```
+
+This produces a `CustomEvent` with the fixed name `openmfe.analytics` and a `detail` payload like:
+
+```ts
+{
+  name: 'checkout_submit',
+  origin: 'mf-shell',
+  id: 'checkout-widget',
+  variant: 'b',
+  action: 'submit form',
+  category: 'checkout',
+  data: {
+    step: 2,
+  },
+}
+```
+
+When `id`, `variant`, or `category` are not available, they are set to `null`. During dispatch, `origin` is inferred from the element `tagName`, and `id` is inferred from the element `id` unless explicitly provided.
+
+## API
+
+Root entry:
+
+- `@vyriy/event` re-exports the public `custom` and `analytics` helpers
+- `validateEventName(origin, name)` validates and normalizes a regular custom event name
+- `createCustomEvent(origin, name, detail, options?)` creates a validated custom `CustomEvent`
+- `dispatchCustomEvent(target, name, detail, options?)` creates and dispatches a validated custom event on the provided target
+- `createAnalyticsEvent(origin, input, options?)` creates the standard `openmfe.analytics` event
+- `dispatchAnalyticsEvent(target, input, options?)` creates and dispatches the standard analytics event
+
+## Exported Types
+
+- `CustomEventTargetLike`
+- `CustomEventOptions`
+- `AnalyticsEventTargetLike`
+- `AnalyticsEventOptions`
+- `AnalyticsInput<Data>`
+- `AnalyticsDetail<Data>`

package/analytics/constants.d.ts

@@ -0,0 +1 @@
+export declare const OPENMFE_ANALYTICS_EVENT_NAME = "openmfe.analytics";

package/analytics/constants.js

@@ -0,0 +1 @@
+export const OPENMFE_ANALYTICS_EVENT_NAME = 'openmfe.analytics';

package/analytics/event.d.ts

@@ -0,0 +1,3 @@
+import type { CreateAnalyticsEvent, DispatchAnalyticsEvent } from './types.js';
+export declare const createAnalyticsEvent: CreateAnalyticsEvent;
+export declare const dispatchAnalyticsEvent: DispatchAnalyticsEvent;

package/analytics/event.js

@@ -0,0 +1,31 @@
+import { OPENMFE_ANALYTICS_EVENT_NAME } from './constants.js';
+import { readAnalyticsId, readOriginFromTarget } from './target.js';
+import { assertNonEmpty, normalizeOrigin } from './validation.js';
+export const createAnalyticsEvent = (origin, input, options = {}) => {
+    const normalizedOrigin = normalizeOrigin(origin);
+    const name = assertNonEmpty(input.name, 'Analytics event detail.name');
+    const action = assertNonEmpty(input.action, 'Analytics event detail.action');
+    const id = input.id ?? null;
+    const category = input.category ?? null;
+    const variant = input.variant ?? null;
+    return new CustomEvent(OPENMFE_ANALYTICS_EVENT_NAME, {
+        ...options,
+        detail: {
+            action,
+            category,
+            data: input.data,
+            id,
+            name,
+            origin: normalizedOrigin,
+            variant,
+        },
+    });
+};
+export const dispatchAnalyticsEvent = (target, input, options = {}) => {
+    const event = createAnalyticsEvent(readOriginFromTarget(target), {
+        ...input,
+        id: readAnalyticsId(target, input),
+    }, options);
+    target.dispatchEvent(event);
+    return event;
+};

package/analytics/index.d.ts

@@ -0,0 +1,2 @@
+export { createAnalyticsEvent, dispatchAnalyticsEvent } from './event.js';
+export type * from './types.js';

package/analytics/index.js

@@ -0,0 +1 @@
+export { createAnalyticsEvent, dispatchAnalyticsEvent } from './event.js';

package/analytics/target.d.ts

@@ -0,0 +1,4 @@
+import type { AnalyticsEventTargetLike, AnalyticsInput } from './types.js';
+export declare const readOriginFromTarget: (target: AnalyticsEventTargetLike) => string;
+export declare const readIdFromTarget: (target: AnalyticsEventTargetLike) => string | null;
+export declare const readAnalyticsId: <Data>(target: AnalyticsEventTargetLike, input: AnalyticsInput<Data>) => string | null;

package/analytics/target.js

@@ -0,0 +1,18 @@
+import { normalizeOrigin } from './validation.js';
+export const readOriginFromTarget = (target) => {
+    const tagName = target.tagName ?? '';
+    return normalizeOrigin(tagName);
+};
+export const readIdFromTarget = (target) => {
+    if (typeof target.id !== 'string') {
+        return null;
+    }
+    const normalized = target.id.trim();
+    return normalized || null;
+};
+export const readAnalyticsId = (target, input) => {
+    if ('id' in input) {
+        return input.id ?? null;
+    }
+    return readIdFromTarget(target);
+};

package/analytics/types.d.ts

@@ -0,0 +1,28 @@
+export type AnalyticsEventTargetLike = Pick<EventTarget, 'dispatchEvent'> & {
+    id?: string;
+    tagName?: string;
+};
+export type AnalyticsEventOptions = {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+};
+export type AnalyticsDetail<Data = Record<string, unknown>> = {
+    name: string;
+    origin: string;
+    id: string | null;
+    variant: string | null;
+    action: string;
+    category: string | null;
+    data: Data;
+};
+export type AnalyticsInput<Data = Record<string, unknown>> = {
+    name: string;
+    id?: string | null;
+    variant?: string | null;
+    action: string;
+    category?: string | null;
+    data: Data;
+};
+export type CreateAnalyticsEvent = <Data>(origin: string, input: AnalyticsInput<Data>, options?: AnalyticsEventOptions) => CustomEvent<AnalyticsDetail<Data>>;
+export type DispatchAnalyticsEvent = <Data>(target: AnalyticsEventTargetLike, input: AnalyticsInput<Data>, options?: AnalyticsEventOptions) => CustomEvent<AnalyticsDetail<Data>>;

package/analytics/validation.d.ts

@@ -0,0 +1,2 @@
+export declare const assertNonEmpty: (value: string, label: string) => string;
+export declare const normalizeOrigin: (origin: string) => string;

package/analytics/validation.js

@@ -0,0 +1,14 @@
+export const assertNonEmpty = (value, label) => {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error(`${label} must not be empty.`);
+    }
+    return normalized;
+};
+export const normalizeOrigin = (origin) => {
+    const normalized = assertNonEmpty(origin, 'Event origin').toLowerCase();
+    if (!/^[a-z](?:[a-z0-9-]*[a-z])?$/.test(normalized)) {
+        throw new Error(`Invalid event origin "${origin}". Origins must contain only lowercase latin letters, numbers, and dashes, and must start and end with a lowercase latin letter.`);
+    }
+    return normalized;
+};

package/custom/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const OPENMFE_NAME_PATTERN: RegExp;
+export declare const TAG_NAME_PATTERN: RegExp;

package/custom/constants.js

@@ -0,0 +1,2 @@
+export const OPENMFE_NAME_PATTERN = /^[a-z](?:[a-z0-9-]*[a-z])?(?:\.[a-z](?:[a-z0-9-]*[a-z])?)+$/;
+export const TAG_NAME_PATTERN = /^[a-z](?:[a-z0-9-]*[a-z])?$/;

package/custom/event.d.ts

@@ -0,0 +1,3 @@
+import type { CreateCustomEvent, DispatchCustomEvent } from './types.js';
+export declare const createCustomEvent: CreateCustomEvent;
+export declare const dispatchCustomEvent: DispatchCustomEvent;

package/custom/event.js

@@ -0,0 +1,11 @@
+import { readOriginFromTarget } from './target.js';
+import { validateEventName } from './validation.js';
+export const createCustomEvent = (origin, name, detail, options = {}) => new CustomEvent(validateEventName(origin, name), {
+    ...options,
+    detail,
+});
+export const dispatchCustomEvent = (target, name, detail, options = {}) => {
+    const event = createCustomEvent(readOriginFromTarget(target), name, detail, options);
+    target.dispatchEvent(event);
+    return event;
+};

package/custom/index.d.ts

@@ -0,0 +1,3 @@
+export { createCustomEvent, dispatchCustomEvent } from './event.js';
+export { validateEventName } from './validation.js';
+export type * from './types.js';

package/custom/index.js

@@ -0,0 +1,2 @@
+export { createCustomEvent, dispatchCustomEvent } from './event.js';
+export { validateEventName } from './validation.js';

package/custom/target.d.ts

@@ -0,0 +1,2 @@
+import type { CustomEventTargetLike } from './types.js';
+export declare const readOriginFromTarget: (target: CustomEventTargetLike) => string;

package/custom/target.js

@@ -0,0 +1,5 @@
+import { normalizeOrigin } from './validation.js';
+export const readOriginFromTarget = (target) => {
+    const tagName = target.tagName ?? '';
+    return normalizeOrigin(tagName);
+};

package/custom/types.d.ts

@@ -0,0 +1,11 @@
+export type CustomEventTargetLike = Pick<EventTarget, 'dispatchEvent'> & {
+    tagName?: string;
+};
+export type CustomEventOptions = {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+};
+export type ValidateEventName = (origin: string, name: string) => string;
+export type CreateCustomEvent = <Detail>(origin: string, name: string, detail: Detail, options?: CustomEventOptions) => CustomEvent<Detail>;
+export type DispatchCustomEvent = <Detail>(target: CustomEventTargetLike, name: string, detail: Detail, options?: CustomEventOptions) => CustomEvent<Detail>;

package/custom/validation.d.ts

@@ -0,0 +1,4 @@
+import type { ValidateEventName } from './types.js';
+export declare const assertNonEmpty: (value: string, label: string) => string;
+export declare const normalizeOrigin: (origin: string) => string;
+export declare const validateEventName: ValidateEventName;

package/custom/validation.js

@@ -0,0 +1,27 @@
+import { OPENMFE_NAME_PATTERN, TAG_NAME_PATTERN } from './constants.js';
+export const assertNonEmpty = (value, label) => {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error(`${label} must not be empty.`);
+    }
+    return normalized;
+};
+export const normalizeOrigin = (origin) => {
+    const normalized = assertNonEmpty(origin, 'Event origin').toLowerCase();
+    if (!TAG_NAME_PATTERN.test(normalized)) {
+        throw new Error(`Invalid event origin "${origin}". Origins must contain only lowercase latin letters, numbers, and dashes, and must start and end with a lowercase latin letter.`);
+    }
+    return normalized;
+};
+export const validateEventName = (origin, name) => {
+    const normalizedOrigin = normalizeOrigin(origin);
+    const normalizedName = assertNonEmpty(name, 'Event name').toLowerCase();
+    if (!OPENMFE_NAME_PATTERN.test(normalizedName)) {
+        throw new Error(`Invalid event name "${name}". Event names must use reverse domain notation with lowercase latin letters, numbers, dashes, and dots.`);
+    }
+    const [rootName] = normalizedName.split('.');
+    if (rootName !== normalizedOrigin) {
+        throw new Error(`Invalid event name "${name}". Event names must start with the microfrontend tag name "${normalizedOrigin}".`);
+    }
+    return normalizedName;
+};

package/index.d.ts

@@ -0,0 +1,4 @@
+export { createAnalyticsEvent, dispatchAnalyticsEvent } from './analytics/index.js';
+export type { AnalyticsDetail, AnalyticsEventOptions, AnalyticsEventTargetLike, AnalyticsInput, CreateAnalyticsEvent, DispatchAnalyticsEvent, } from './analytics/index.js';
+export { createCustomEvent, dispatchCustomEvent, validateEventName } from './custom/index.js';
+export type { CreateCustomEvent, CustomEventOptions, CustomEventTargetLike, DispatchCustomEvent, ValidateEventName, } from './custom/index.js';

package/index.js

@@ -0,0 +1,2 @@
+export { createAnalyticsEvent, dispatchAnalyticsEvent } from './analytics/index.js';
+export { createCustomEvent, dispatchCustomEvent, validateEventName } from './custom/index.js';

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@vyriy/event",
+  "version": "0.1.9",
+  "description": "Shared event package for Vyriy projects",
+  "type": "module",
+  "main": "./index.js",
+  "license": "MIT",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./analytics/constants": {
+      "types": "./analytics/constants.d.ts",
+      "import": "./analytics/constants.js",
+      "default": "./analytics/constants.js"
+    },
+    "./analytics/constants.js": {
+      "types": "./analytics/constants.d.ts",
+      "import": "./analytics/constants.js",
+      "default": "./analytics/constants.js"
+    },
+    "./analytics/event": {
+      "types": "./analytics/event.d.ts",
+      "import": "./analytics/event.js",
+      "default": "./analytics/event.js"
+    },
+    "./analytics/event.js": {
+      "types": "./analytics/event.d.ts",
+      "import": "./analytics/event.js",
+      "default": "./analytics/event.js"
+    },
+    "./analytics/index": {
+      "types": "./analytics/index.d.ts",
+      "import": "./analytics/index.js",
+      "default": "./analytics/index.js"
+    },
+    "./analytics/index.js": {
+      "types": "./analytics/index.d.ts",
+      "import": "./analytics/index.js",
+      "default": "./analytics/index.js"
+    },
+    "./analytics/target": {
+      "types": "./analytics/target.d.ts",
+      "import": "./analytics/target.js",
+      "default": "./analytics/target.js"
+    },
+    "./analytics/target.js": {
+      "types": "./analytics/target.d.ts",
+      "import": "./analytics/target.js",
+      "default": "./analytics/target.js"
+    },
+    "./analytics/validation": {
+      "types": "./analytics/validation.d.ts",
+      "import": "./analytics/validation.js",
+      "default": "./analytics/validation.js"
+    },
+    "./analytics/validation.js": {
+      "types": "./analytics/validation.d.ts",
+      "import": "./analytics/validation.js",
+      "default": "./analytics/validation.js"
+    },
+    "./custom/constants": {
+      "types": "./custom/constants.d.ts",
+      "import": "./custom/constants.js",
+      "default": "./custom/constants.js"
+    },
+    "./custom/constants.js": {
+      "types": "./custom/constants.d.ts",
+      "import": "./custom/constants.js",
+      "default": "./custom/constants.js"
+    },
+    "./custom/event": {
+      "types": "./custom/event.d.ts",
+      "import": "./custom/event.js",
+      "default": "./custom/event.js"
+    },
+    "./custom/event.js": {
+      "types": "./custom/event.d.ts",
+      "import": "./custom/event.js",
+      "default": "./custom/event.js"
+    },
+    "./custom/index": {
+      "types": "./custom/index.d.ts",
+      "import": "./custom/index.js",
+      "default": "./custom/index.js"
+    },
+    "./custom/index.js": {
+      "types": "./custom/index.d.ts",
+      "import": "./custom/index.js",
+      "default": "./custom/index.js"
+    },
+    "./custom/target": {
+      "types": "./custom/target.d.ts",
+      "import": "./custom/target.js",
+      "default": "./custom/target.js"
+    },
+    "./custom/target.js": {
+      "types": "./custom/target.d.ts",
+      "import": "./custom/target.js",
+      "default": "./custom/target.js"
+    },
+    "./custom/validation": {
+      "types": "./custom/validation.d.ts",
+      "import": "./custom/validation.js",
+      "default": "./custom/validation.js"
+    },
+    "./custom/validation.js": {
+      "types": "./custom/validation.d.ts",
+      "import": "./custom/validation.js",
+      "default": "./custom/validation.js"
+    },
+    "./index": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index.js": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  }
+}