@digitaldefiance/i18n-lib 3.8.16 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "3.8.16",
+  "version": "4.0.0",
   "description": "i18n library with enum translation support",
   "homepage": "https://github.com/Digital-Defiance/i18n-lib",
   "repository": {
@@ -41,14 +41,15 @@
   "license": "MIT",
   "packageManager": "yarn@4.10.3",
   "dependencies": {
+    "@digitaldefiance/branded-enum": "0.0.4",
     "currency-codes": "^2.2.0",
     "lru-cache": "^5.1.1",
     "moment": "^2.30.1",
     "moment-timezone": "^0.6.0"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^8.48.0",
-    "@typescript-eslint/parser": "^8.48.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-check": "^4.3.0"

package/src/branded-string-key.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Branded String Key utilities for runtime-identifiable i18n string keys
+ *
+ * This module provides integration between @digitaldefiance/branded-enum
+ * and the i18n system, enabling:
+ * - Runtime identification of which component a string key belongs to
+ * - Collision detection when registering components
+ * - Type-safe translation functions with branded enums
+ *
+ * @module branded-string-key
+ */
+import { isFromEnum, findEnumSources, enumIntersect, getEnumValues, getEnumById, getAllEnumIds, mergeEnums } from '@digitaldefiance/branded-enum';
+import type { BrandedEnum, BrandedEnumValue, AnyBrandedEnum } from '@digitaldefiance/branded-enum';
+export type { BrandedEnum, BrandedEnumValue, AnyBrandedEnum };
+export { isFromEnum, findEnumSources, enumIntersect, getEnumValues, getEnumById, getAllEnumIds, mergeEnums, };
+/**
+ * Type alias for a branded string key enum used in i18n
+ */
+export type BrandedStringKeys<T extends Record<string, string>> = BrandedEnum<T>;
+/**
+ * Type alias for extracting the string key values from a branded enum
+ */
+export type BrandedStringKeyValue<E extends AnyBrandedEnum> = BrandedEnumValue<E>;
+/**
+ * Options for creating i18n string keys
+ */
+export interface CreateI18nStringKeysOptions {
+    /**
+     * Prefix to add to all key values (e.g., 'user.' will make 'Welcome' become 'user.welcome')
+     * If not provided, no prefix is added
+     */
+    valuePrefix?: string;
+    /**
+     * Whether to lowercase the values (default: true for consistency)
+     */
+    lowercaseValues?: boolean;
+}
+/**
+ * Creates a branded enum for i18n string keys with a namespace identifier.
+ *
+ * This is the primary factory function for creating type-safe, runtime-identifiable
+ * string key sets for i18n components.
+ *
+ * @example
+ * ```typescript
+ * // Create user-related string keys
+ * const UserStringKeys = createI18nStringKeys('user-component', {
+ *   Welcome: 'user.welcome',
+ *   Goodbye: 'user.goodbye',
+ *   Profile: 'user.profile',
+ * } as const);
+ *
+ * // Type-safe usage
+ * const key = UserStringKeys.Welcome; // 'user.welcome'
+ *
+ * // Runtime identification
+ * findEnumSources('user.welcome'); // ['user-component']
+ * isFromEnum('user.welcome', UserStringKeys); // true
+ * ```
+ *
+ * @param componentId Unique identifier for the component (used as the enum ID)
+ * @param keys Object mapping key names to their string values
+ * @returns A branded enum with runtime identification metadata
+ */
+export declare function createI18nStringKeys<T extends Record<string, string>>(componentId: string, keys: T): BrandedStringKeys<T>;
+/**
+ * Creates i18n string keys from an existing TypeScript enum.
+ *
+ * This function helps migrate from traditional enums to branded enums
+ * while maintaining the same key-value structure.
+ *
+ * @example
+ * ```typescript
+ * // Existing enum
+ * enum UserKeys {
+ *   Welcome = 'user.welcome',
+ *   Goodbye = 'user.goodbye',
+ * }
+ *
+ * // Convert to branded enum
+ * const BrandedUserKeys = createI18nStringKeysFromEnum('user-component', UserKeys);
+ *
+ * // Now has runtime identification
+ * findEnumSources('user.welcome'); // ['i18n:user-component']
+ * ```
+ *
+ * @param componentId Unique identifier for the component
+ * @param enumObj The TypeScript enum to convert
+ * @returns A branded enum with the same key-value pairs
+ */
+export declare function createI18nStringKeysFromEnum<TEnum extends Record<string, string>>(componentId: string, enumObj: TEnum): BrandedStringKeys<TEnum>;
+/**
+ * Result of a collision check between string key enums
+ */
+export interface StringKeyCollisionResult {
+    /** Whether any collisions were found */
+    hasCollisions: boolean;
+    /** Array of collision details */
+    collisions: Array<{
+        /** The colliding value */
+        value: string;
+        /** The component IDs (enum IDs) that contain this value */
+        componentIds: readonly string[];
+    }>;
+}
+/**
+ * Checks for collisions between multiple branded string key enums.
+ *
+ * Use this to detect when multiple components have overlapping string keys,
+ * which could cause routing issues in translations.
+ *
+ * @example
+ * ```typescript
+ * const UserKeys = createI18nStringKeys('user', { Welcome: 'welcome' } as const);
+ * const AdminKeys = createI18nStringKeys('admin', { Welcome: 'welcome' } as const);
+ *
+ * const result = checkStringKeyCollisions(UserKeys, AdminKeys);
+ * // result.hasCollisions === true
+ * // result.collisions === [{ value: 'welcome', componentIds: ['i18n:user', 'i18n:admin'] }]
+ * ```
+ *
+ * @param enums The branded string key enums to check
+ * @returns Collision check result
+ */
+export declare function checkStringKeyCollisions(...enums: AnyBrandedEnum[]): StringKeyCollisionResult;
+/**
+ * Finds which i18n component(s) a string key belongs to.
+ *
+ * @example
+ * ```typescript
+ * const sources = findStringKeySources('user.welcome');
+ * // ['i18n:user-component']
+ * ```
+ *
+ * @param key The string key to look up
+ * @returns Array of component IDs that contain this key
+ */
+export declare function findStringKeySources(key: string): string[];
+/**
+ * Resolves a string key to its owning component ID.
+ *
+ * Returns the component ID without the 'i18n:' prefix if exactly one
+ * component owns the key, or null if zero or multiple components own it.
+ *
+ * @example
+ * ```typescript
+ * const componentId = resolveStringKeyComponent('user.welcome');
+ * // 'user-component' (or null if ambiguous)
+ * ```
+ *
+ * @param key The string key to resolve
+ * @returns The component ID, or null if not found or ambiguous
+ */
+export declare function resolveStringKeyComponent(key: string): string | null;
+/**
+ * Gets all registered i18n component IDs.
+ *
+ * @returns Array of component IDs (without the 'i18n:' prefix)
+ */
+export declare function getRegisteredI18nComponents(): string[];
+/**
+ * Gets a branded string key enum by its component ID.
+ *
+ * @param componentId The component ID to look up
+ * @returns The branded enum, or undefined if not found
+ */
+export declare function getStringKeysByComponentId(componentId: string): BrandedEnum<Record<string, string>> | undefined;
+/**
+ * Validates that a value is a valid string key from a specific branded enum.
+ *
+ * @param value The value to validate
+ * @param stringKeys The branded enum to validate against
+ * @returns True if the value is a valid key in the enum
+ */
+export declare function isValidStringKey<E extends BrandedEnum<Record<string, string>>>(value: unknown, stringKeys: E): value is BrandedEnumValue<E>;
+/**
+ * Merges multiple branded string key enums into a combined enum.
+ *
+ * Useful for creating a unified key set from multiple components.
+ *
+ * @example
+ * ```typescript
+ * const AllKeys = mergeI18nStringKeys('all-keys',
+ *   CoreStringKeys,
+ *   UserStringKeys,
+ *   AdminStringKeys
+ * );
+ * ```
+ *
+ * @param newComponentId The ID for the merged enum
+ * @param enums The enums to merge
+ * @returns A new branded enum containing all keys from input enums
+ * @throws Error if there are duplicate keys across enums
+ */
+export declare function mergeI18nStringKeys<T extends readonly BrandedEnum<Record<string, string>>[]>(newComponentId: string, ...enums: T): BrandedEnum<Record<string, string>>;
+/**
+ * Helper to get all string key values from a branded enum as an array.
+ *
+ * @param stringKeys The branded enum
+ * @returns Array of all string key values
+ */
+export declare function getStringKeyValues<E extends BrandedEnum<Record<string, string>>>(stringKeys: E): BrandedEnumValue<E>[];
+//# sourceMappingURL=branded-string-key.d.ts.map

package/src/branded-string-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded-string-key.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/branded-string-key.ts"],"names":[],"mappings":"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"}

package/src/branded-string-key.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Branded String Key utilities for runtime-identifiable i18n string keys
+ *
+ * This module provides integration between @digitaldefiance/branded-enum
+ * and the i18n system, enabling:
+ * - Runtime identification of which component a string key belongs to
+ * - Collision detection when registering components
+ * - Type-safe translation functions with branded enums
+ *
+ * @module branded-string-key
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeEnums = exports.getAllEnumIds = exports.getEnumById = exports.getEnumValues = exports.enumIntersect = exports.findEnumSources = exports.isFromEnum = void 0;
+exports.createI18nStringKeys = createI18nStringKeys;
+exports.createI18nStringKeysFromEnum = createI18nStringKeysFromEnum;
+exports.checkStringKeyCollisions = checkStringKeyCollisions;
+exports.findStringKeySources = findStringKeySources;
+exports.resolveStringKeyComponent = resolveStringKeyComponent;
+exports.getRegisteredI18nComponents = getRegisteredI18nComponents;
+exports.getStringKeysByComponentId = getStringKeysByComponentId;
+exports.isValidStringKey = isValidStringKey;
+exports.mergeI18nStringKeys = mergeI18nStringKeys;
+exports.getStringKeyValues = getStringKeyValues;
+const branded_enum_1 = require("@digitaldefiance/branded-enum");
+Object.defineProperty(exports, "isFromEnum", { enumerable: true, get: function () { return branded_enum_1.isFromEnum; } });
+Object.defineProperty(exports, "findEnumSources", { enumerable: true, get: function () { return branded_enum_1.findEnumSources; } });
+Object.defineProperty(exports, "enumIntersect", { enumerable: true, get: function () { return branded_enum_1.enumIntersect; } });
+Object.defineProperty(exports, "getEnumValues", { enumerable: true, get: function () { return branded_enum_1.getEnumValues; } });
+Object.defineProperty(exports, "getEnumById", { enumerable: true, get: function () { return branded_enum_1.getEnumById; } });
+Object.defineProperty(exports, "getAllEnumIds", { enumerable: true, get: function () { return branded_enum_1.getAllEnumIds; } });
+Object.defineProperty(exports, "mergeEnums", { enumerable: true, get: function () { return branded_enum_1.mergeEnums; } });
+/**
+ * Creates a branded enum for i18n string keys with a namespace identifier.
+ *
+ * This is the primary factory function for creating type-safe, runtime-identifiable
+ * string key sets for i18n components.
+ *
+ * @example
+ * ```typescript
+ * // Create user-related string keys
+ * const UserStringKeys = createI18nStringKeys('user-component', {
+ *   Welcome: 'user.welcome',
+ *   Goodbye: 'user.goodbye',
+ *   Profile: 'user.profile',
+ * } as const);
+ *
+ * // Type-safe usage
+ * const key = UserStringKeys.Welcome; // 'user.welcome'
+ *
+ * // Runtime identification
+ * findEnumSources('user.welcome'); // ['user-component']
+ * isFromEnum('user.welcome', UserStringKeys); // true
+ * ```
+ *
+ * @param componentId Unique identifier for the component (used as the enum ID)
+ * @param keys Object mapping key names to their string values
+ * @returns A branded enum with runtime identification metadata
+ */
+function createI18nStringKeys(componentId, keys) {
+    return (0, branded_enum_1.createBrandedEnum)(`i18n:${componentId}`, keys);
+}
+/**
+ * Creates i18n string keys from an existing TypeScript enum.
+ *
+ * This function helps migrate from traditional enums to branded enums
+ * while maintaining the same key-value structure.
+ *
+ * @example
+ * ```typescript
+ * // Existing enum
+ * enum UserKeys {
+ *   Welcome = 'user.welcome',
+ *   Goodbye = 'user.goodbye',
+ * }
+ *
+ * // Convert to branded enum
+ * const BrandedUserKeys = createI18nStringKeysFromEnum('user-component', UserKeys);
+ *
+ * // Now has runtime identification
+ * findEnumSources('user.welcome'); // ['i18n:user-component']
+ * ```
+ *
+ * @param componentId Unique identifier for the component
+ * @param enumObj The TypeScript enum to convert
+ * @returns A branded enum with the same key-value pairs
+ */
+function createI18nStringKeysFromEnum(componentId, enumObj) {
+    // Filter out reverse mappings (numeric enums have value -> key mappings)
+    const filteredObj = Object.fromEntries(Object.entries(enumObj).filter(([_key, value]) => typeof value === 'string' &&
+        !Object.prototype.hasOwnProperty.call(enumObj, value)));
+    return createI18nStringKeys(componentId, filteredObj);
+}
+/**
+ * Checks for collisions between multiple branded string key enums.
+ *
+ * Use this to detect when multiple components have overlapping string keys,
+ * which could cause routing issues in translations.
+ *
+ * @example
+ * ```typescript
+ * const UserKeys = createI18nStringKeys('user', { Welcome: 'welcome' } as const);
+ * const AdminKeys = createI18nStringKeys('admin', { Welcome: 'welcome' } as const);
+ *
+ * const result = checkStringKeyCollisions(UserKeys, AdminKeys);
+ * // result.hasCollisions === true
+ * // result.collisions === [{ value: 'welcome', componentIds: ['i18n:user', 'i18n:admin'] }]
+ * ```
+ *
+ * @param enums The branded string key enums to check
+ * @returns Collision check result
+ */
+function checkStringKeyCollisions(...enums) {
+    const collisions = (0, branded_enum_1.enumIntersect)(...enums);
+    return {
+        hasCollisions: collisions.length > 0,
+        collisions: collisions.map((c) => ({
+            value: c.value,
+            componentIds: c.enumIds,
+        })),
+    };
+}
+/**
+ * Finds which i18n component(s) a string key belongs to.
+ *
+ * @example
+ * ```typescript
+ * const sources = findStringKeySources('user.welcome');
+ * // ['i18n:user-component']
+ * ```
+ *
+ * @param key The string key to look up
+ * @returns Array of component IDs that contain this key
+ */
+function findStringKeySources(key) {
+    return (0, branded_enum_1.findEnumSources)(key).filter((id) => id.startsWith('i18n:'));
+}
+/**
+ * Resolves a string key to its owning component ID.
+ *
+ * Returns the component ID without the 'i18n:' prefix if exactly one
+ * component owns the key, or null if zero or multiple components own it.
+ *
+ * @example
+ * ```typescript
+ * const componentId = resolveStringKeyComponent('user.welcome');
+ * // 'user-component' (or null if ambiguous)
+ * ```
+ *
+ * @param key The string key to resolve
+ * @returns The component ID, or null if not found or ambiguous
+ */
+function resolveStringKeyComponent(key) {
+    const sources = findStringKeySources(key);
+    if (sources.length === 1) {
+        return sources[0].replace(/^i18n:/, '');
+    }
+    return null;
+}
+/**
+ * Gets all registered i18n component IDs.
+ *
+ * @returns Array of component IDs (without the 'i18n:' prefix)
+ */
+function getRegisteredI18nComponents() {
+    return (0, branded_enum_1.getAllEnumIds)()
+        .filter((id) => id.startsWith('i18n:'))
+        .map((id) => id.replace(/^i18n:/, ''));
+}
+/**
+ * Gets a branded string key enum by its component ID.
+ *
+ * @param componentId The component ID to look up
+ * @returns The branded enum, or undefined if not found
+ */
+function getStringKeysByComponentId(componentId) {
+    return (0, branded_enum_1.getEnumById)(`i18n:${componentId}`);
+}
+/**
+ * Validates that a value is a valid string key from a specific branded enum.
+ *
+ * @param value The value to validate
+ * @param stringKeys The branded enum to validate against
+ * @returns True if the value is a valid key in the enum
+ */
+function isValidStringKey(value, stringKeys) {
+    return (0, branded_enum_1.isFromEnum)(value, stringKeys);
+}
+/**
+ * Merges multiple branded string key enums into a combined enum.
+ *
+ * Useful for creating a unified key set from multiple components.
+ *
+ * @example
+ * ```typescript
+ * const AllKeys = mergeI18nStringKeys('all-keys',
+ *   CoreStringKeys,
+ *   UserStringKeys,
+ *   AdminStringKeys
+ * );
+ * ```
+ *
+ * @param newComponentId The ID for the merged enum
+ * @param enums The enums to merge
+ * @returns A new branded enum containing all keys from input enums
+ * @throws Error if there are duplicate keys across enums
+ */
+function mergeI18nStringKeys(newComponentId, ...enums) {
+    return (0, branded_enum_1.mergeEnums)(`i18n:${newComponentId}`, ...enums);
+}
+/**
+ * Helper to get all string key values from a branded enum as an array.
+ *
+ * @param stringKeys The branded enum
+ * @returns Array of all string key values
+ */
+function getStringKeyValues(stringKeys) {
+    return ((0, branded_enum_1.getEnumValues)(stringKeys) ?? []);
+}
+//# sourceMappingURL=branded-string-key.js.map

package/src/branded-string-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded-string-key.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/branded-string-key.ts"],"names":[],"mappings":"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"}

package/src/component-definition.d.ts

@@ -1,12 +1,54 @@
 /**
- * Component definition with its string keys
+ * Component definition with branded string keys
+ *
+ * @module component-definition
  */
-export interface ComponentDefinition<TStringKeys extends string> {
+import type { AnyBrandedEnum, BrandedEnumValue } from '@digitaldefiance/branded-enum';
+/**
+ * Component definition using branded enums for runtime-identifiable string keys
+ *
+ * This interface provides:
+ * - Runtime identification of string key sources
+ * - Automatic collision detection during registration
+ * - Type-safe string key validation
+ * - Automatic translation routing
+ *
+ * @template TBrandedEnum - The branded enum type containing string keys
+ *
+ * @example
+ * ```typescript
+ * const MyKeys = createI18nStringKeys('my-component', {
+ *   Key1: 'key1',
+ *   Key2: 'key2',
+ * } as const);
+ *
+ * const myComponent: ComponentDefinition<typeof MyKeys> = {
+ *   id: 'my-component',
+ *   name: 'My Component',
+ *   stringKeys: MyKeys,
+ * };
+ * ```
+ */
+export interface ComponentDefinition<TBrandedEnum extends AnyBrandedEnum> {
     /** Unique identifier for the component */
     readonly id: string;
     /** Human-readable name for the component */
     readonly name: string;
-    /** Array of all string keys this component requires */
-    readonly stringKeys: readonly TStringKeys[];
+    /**
+     * Branded enum containing all string keys for this component
+     * Provides runtime identification and collision detection
+     */
+    readonly stringKeys: TBrandedEnum;
 }
+/**
+ * Helper to extract string key values from a component definition
+ *
+ * @param definition - The component definition
+ * @returns Array of all string key values
+ */
+export declare function getComponentStringKeys<TBrandedEnum extends AnyBrandedEnum>(definition: ComponentDefinition<TBrandedEnum>): BrandedEnumValue<TBrandedEnum>[];
+/**
+ * Type to extract string key type from a component definition
+ */
+export type ComponentStringKeys<T extends ComponentDefinition<AnyBrandedEnum>> = T extends ComponentDefinition<infer E> ? BrandedEnumValue<E> : never;
 //# sourceMappingURL=component-definition.d.ts.map

package/src/component-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-definition.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-definition.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,WAAW,SAAS,MAAM;IAC7D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C"}
+{"version":3,"file":"component-definition.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,mBAAmB,CAAC,YAAY,SAAS,cAAc;IACtE,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,SAAS,cAAc,EACxE,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,GAC5C,gBAAgB,CAAC,YAAY,CAAC,EAAE,CAGlC;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,mBAAmB,CAAC,cAAc,CAAC,IAC3E,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC"}

package/src/component-definition.js

@@ -1,3 +1,20 @@
 "use strict";
+/**
+ * Component definition with branded string keys
+ *
+ * @module component-definition
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComponentStringKeys = getComponentStringKeys;
+const branded_enum_1 = require("@digitaldefiance/branded-enum");
+/**
+ * Helper to extract string key values from a component definition
+ *
+ * @param definition - The component definition
+ * @returns Array of all string key values
+ */
+function getComponentStringKeys(definition) {
+    const values = (0, branded_enum_1.getEnumValues)(definition.stringKeys);
+    return (values ?? []);
+}
 //# sourceMappingURL=component-definition.js.map

package/src/component-definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"component-definition.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-definition.ts"],"names":[],"mappings":""}
+{"version":3,"file":"component-definition.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-definition.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAmDH,wDAKC;AAlDD,gEAA8D;AAuC9D;;;;;GAKG;AACH,SAAgB,sBAAsB,CACpC,UAA6C;IAE7C,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACpD,OAAO,CAAC,MAAM,IAAI,EAAE,CAAqC,CAAC;AAC5D,CAAC"}

package/src/component-registration.d.ts

@@ -1,22 +1,37 @@
+import type { AnyBrandedEnum, BrandedEnumValue } from '@digitaldefiance/branded-enum';
 import { ComponentDefinition } from './component-definition';
 import { PartialComponentLanguageStrings } from './types';
 /**
  * Registration payload for a component with its strings
+ *
+ * @example
+ * ```typescript
+ * const MyKeys = createI18nStringKeys('my-component', {
+ *   Welcome: 'my.welcome',
+ *   Goodbye: 'my.goodbye',
+ * } as const);
+ *
+ * const registration: ComponentRegistration<typeof MyKeys, 'en' | 'es'> = {
+ *   component: {
+ *     id: 'my-component',
+ *     name: 'My Component',
+ *     stringKeys: MyKeys,
+ *   },
+ *   strings: {
+ *     en: { 'my.welcome': 'Welcome!', 'my.goodbye': 'Goodbye!' },
+ *     es: { 'my.welcome': '¡Bienvenido!', 'my.goodbye': '¡Adiós!' },
+ *   },
+ * };
+ * ```
  */
-export interface ComponentRegistration<TStringKeys extends string, TLanguages extends string> {
-    readonly component: ComponentDefinition<TStringKeys>;
-    readonly strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>;
-    readonly enumName?: string;
-    readonly enumObject?: Record<string, TStringKeys>;
+export interface ComponentRegistration<TBrandedEnum extends AnyBrandedEnum, TLanguages extends string> {
+    readonly component: ComponentDefinition<TBrandedEnum>;
+    readonly strings: PartialComponentLanguageStrings<BrandedEnumValue<TBrandedEnum>, TLanguages>;
+    /** Optional aliases for resolving component references */
     readonly aliases?: readonly string[];
 }
 /**
- * Type utility to extract string keys from a component definition
+ * Type utility to extract string keys type from a component registration
  */
-type ExtractStringKeys<T> = T extends ComponentDefinition<infer K> ? K : never;
-/**
- * Type utility to create a strongly typed component registration
- */
-export type CreateComponentRegistration<TComponent extends ComponentDefinition<string>, TLanguages extends string> = ComponentRegistration<ExtractStringKeys<TComponent>, TLanguages>;
-export {};
+export type RegistrationStringKeys<T extends ComponentRegistration<AnyBrandedEnum, string>> = T extends ComponentRegistration<infer E, string> ? BrandedEnumValue<E> : never;
 //# sourceMappingURL=component-registration.d.ts.map

package/src/component-registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-registration.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,qBAAqB,CACpC,WAAW,SAAS,MAAM,EAC1B,UAAU,SAAS,MAAM;IAEzB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,2BAA2B,CACrC,UAAU,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAC9C,UAAU,SAAS,MAAM,IACvB,qBAAqB,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC"}
+{"version":3,"file":"component-registration.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-i18n-lib/src/component-registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,qBAAqB,CACpC,YAAY,SAAS,cAAc,EACnC,UAAU,SAAS,MAAM;IAEzB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAC/C,gBAAgB,CAAC,YAAY,CAAC,EAC9B,UAAU,CACX,CAAC;IACF,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAChC,CAAC,SAAS,qBAAqB,CAAC,cAAc,EAAE,MAAM,CAAC,IAEvD,CAAC,SAAS,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAC5C,gBAAgB,CAAC,CAAC,CAAC,GACnB,KAAK,CAAC"}