@fkui/logic 6.37.0 → 6.38.0

package/lib/types/index.d.ts

@@ -123,6 +123,15 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
       values: string | string[] | number | number[];
   }
 
+  /**
+   * Constructs a tuple type of a specific length `N`.
+   * Used internally for recursion depth tracking.
+   *
+   * @public
+   * @since v6.38.0
+   */
+  export declare type BuildDepth<N extends number, T extends unknown[] = []> = T["length"] extends N ? T : BuildDepth<N, [...T, unknown]>;
+
   /**
    * A string of 4-5 digits where last digit may be separated by hyphen, for
    * example "5678-1"
@@ -147,6 +156,16 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
       timeLimitSeconds?: number;
   }
 
+  /**
+   * Global registry interface.
+   * Consumers (the main project) will merge their specific key types into this.
+   *
+   * @public
+   * @since v6.38.0
+   */
+  export declare interface CustomTranslationRegistry {
+  }
+
   /**
    * A string in format YYYY-MM-DD, for example 2021-02-03
    *
@@ -613,6 +632,17 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
     */
    export declare function isVisibleInViewport(element: Element): boolean;
 
+   /**
+    * Joins two path segments.
+    *
+    * We use generic constraints (`extends ValidKey`) here instead of conditional
+    * checks to keep it clean. If K or P is not a string/number, TS will error.
+    *
+    * @public
+    * @since v6.38.0
+    */
+   export declare type Join<K extends ValidKey, P extends ValidKey> = `${K}.${P}`;
+
    /**
     * @public
     */
@@ -658,6 +688,20 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
        constructor(message?: string);
    }
 
+   /**
+    * Recursively generates a union of all dot-notation paths for object `T`.
+    *
+    * It uses `PathMap` to calculate paths for properties and then extracts
+    * the values using `[keyof T]`.
+    *
+    * @public
+    * @since v6.38.0
+    * @typeParam T - The object or array to inspect.
+    * @typeParam Depth - The maximum recursion depth (defaults to 6).
+    * @returns A union of string paths (e.g., `"user" | "user.name"`).
+    */
+   export declare type NestedKeys<T, Depth extends number = 6> = [Depth] extends [never] ? never : T extends object ? PathMap<T, Depth>[keyof T & ValidKey] : never;
+
    /**
     * @public
     */
@@ -734,6 +778,25 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
     */
    export declare function parsePostalCode(value: string): PostalCodeString | undefined;
 
+   /**
+    * Internal helper: "Flattens" the object one level deep.
+    *
+    * This generates a mapped type where the keys are the property names,
+    * and the values are the calculated paths (current key + nested paths).
+    *
+    * @example
+    * ```ts
+    * // Input: { user: { name: string } }
+    * // Output: { user: "user" | "user.name" }
+    * ```
+    *
+    * @public
+    * @since v6.38.0
+    */
+   export declare type PathMap<T, Depth extends number> = {
+       [K in keyof T & ValidKey]: T[K] extends object ? `${K}` | Join<K, NestedKeys<T[K], Prev<Depth>>> : `${K}`;
+   };
+
    /**
     * Describes the event that is dispatched during input if no instant validation.
     *
@@ -809,6 +872,14 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
     */
    export declare type PostalCodeString = string;
 
+   /**
+    * Computes `N - 1` at the type level.
+    *
+    * @public
+    * @since v6.38.0
+    */
+   export declare type Prev<N extends number> = BuildDepth<N> extends [...infer R, unknown] ? R["length"] : never;
+
    /**
     * Save current active element focus on the stack and set focus on element
     *
@@ -824,6 +895,18 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
     */
    export declare function removeFocusListener(elements: HTMLElement[], listener: ((event: Event) => unknown) | (() => unknown)): void;
 
+   /**
+    * Resolves the valid translation keys.
+    * If the consumer has defined `Keys` in the registry, use that.
+    * Otherwise, fallback to `string` (loose typing).
+    *
+    * @public
+    * @since v6.38.0
+    */
+   export declare type ResolveTranslationKey = CustomTranslationRegistry extends {
+       Keys: infer K;
+   } ? K : string;
+
    /**
     * Restore focus to a previous element. Use this in combination with {@link saveFocus}
     *
@@ -955,8 +1038,54 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
 
    /**
     * @public
+    * @typeParam Key - The valid translation keys. Defaults to `string` for loose typing,
+    * but can be set to a specific union of strings (e.g., via `NestedKeys<Schema>`)
+    * to enforce strict key validation and autocompletion.
     */
-   export declare type TranslateFunction = (key: string, defaultValueOrArgs?: string | Record<string, unknown>, args?: Record<string, unknown>) => string;
+   export declare interface TranslateFunction<Key = ResolveTranslationKey> {
+       /**
+        * Returns the translation for the key.
+        *
+        * @param key - The translation key.
+        */
+       (key: Key): string;
+       /**
+        * Returns the translation for the key or the default value if no
+        * translation exists.
+        *
+        * @param key - The translation key.
+        * @param defaultValue - The default value.
+        */
+       (key: Key, defaultValue: string): string;
+       /**
+        * Returns the translation for the key. The translation is interpolated
+        * with the given arguments.
+        *
+        * @param key - The translation key.
+        * @param args - The interpolation arguments.
+        */
+       (key: Key, args: Record<string, unknown>): string;
+       /**
+        * Returns the translation for the key or the default value if no
+        * translation exists. The translation is interpolated with the given
+        * arguments.
+        *
+        * @param key - The translation key.
+        * @param defaultValue - The default value.
+        * @param args - The interpolation arguments.
+        */
+       (key: Key, defaultValue: string, args: Record<string, unknown>): string;
+       /**
+        * Returns the translation for the key or the default value if no
+        * translation exists. The translation is interpolated with the given
+        * arguments.
+        *
+        * @param key - The translation key.
+        * @param defaultValue - The default value.
+        * @param args - The interpolation arguments.
+        */
+       (key: Key, defaultValue?: string | Record<string, unknown>, args?: Record<string, unknown>): string;
+   }
 
    /**
     * @public
@@ -1380,6 +1509,16 @@ export declare interface AllowListValidatorConfig extends ValidatorOptions {
     */
    export declare type ValidityNativeEvent = "input" | "change" | "blur" | "validate";
 
+   /**
+    * Helper type: aliases valid keys to strictly string.
+    * This filters out `symbol`, which cannot be used in template literals.
+    * Only allows "string-key": "value" pairs
+    *
+    * @public
+    * @since v6.38.0
+    */
+   export declare type ValidKey = string;
+
    /**
     * @public
     */

package/lib/types/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.56.3"
+      "packageVersion": "7.57.3"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fkui/logic",
-  "version": "6.37.0",
+  "version": "6.38.0",
   "description": "Logic",
   "keywords": [
     "fkui",
@@ -61,11 +61,11 @@
     "watch": "rollup --config --watch"
   },
   "peerDependencies": {
-    "@fkui/date": "^6.37.0"
+    "@fkui/date": "^6.38.0"
   },
   "engines": {
     "node": ">= 20",
     "npm": ">= 7"
   },
-  "gitHead": "15bcc047ba64657946b3e429cbf68abae064ebcc"
+  "gitHead": "ea8e50d8567159581a628106e93ac0e7c1d43a1b"
 }