@limetech/lime-web-components 6.6.0 → 6.8.0

package/dist/keybindings/registry.d.ts

@@ -6,31 +6,66 @@
  * to individual keys typed by a user. The key combination can be pressing a single
  * key or a sequence of keys one after the other.
  *
- * The service works together with the `CommandBus` to execute the commands and
+ * The service works together with the {@link CommandBus} to execute the commands and
  * a command needs to already be registered on the command bus in order to be
  * bound as a keyboard shortcut.
  *
- * The following example registers the command `MyCommand` to be handled by
- * `MyHandler` and creates a keybinding for it. The `bind` method takes the key
- * combination and command object as input.
+ * Keybindings are scoped to the component that creates them and should be
+ * cleaned up when the component is removed from the DOM to prevent memory leaks
+ * and unintended behavior.
  *
- * Later, if the keybinding no longer is needed it can be removed with the
- * `unbind` method.
+ * ## Key Combination Format
  *
- * @example
+ * Key combinations can be:
+ * - Single keys: `'a'`, `'enter'`, `'escape'`
+ * - Modifier combinations: `'ctrl+s'`, `'alt+shift+n'`, `'meta+k'`
+ * - Sequences: `'g i'` (press 'g' then 'i')
+ *
+ * Supported modifiers: `ctrl`, `alt`, `shift`, `meta` (Command on Mac)
+ *
+ * @example Binding a command to a key combination
+ * ```ts
+ * const saveCommand = new SaveCommand();
+ * commandBus.register(SaveCommand, { handle: (cmd) => handleSave(cmd) });
+ * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+ * registry.bind('ctrl+s', saveCommand);
+ * ```
+ *
+ * @example Checking for conflicts before binding
+ * ```ts
+ * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+ * if (!registry.isBound('j')) {
+ *     registry.bind('j', navigateNextCommand);
+ * }
+ * ```
+ *
+ * @example Vim-style key sequences
+ * ```ts
+ * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+ * registry.bind('g i', goToInboxCommand);
+ * registry.bind('g s', goToSentCommand);
+ * registry.bind('g d', goToDraftsCommand);
  * ```
- * // The command bus needs to have a handler registered for the command
- * // before it can be bound to a key sequence
- * const handler = new MyHandler();
- * commandBus.register(MyCommand, handler);
  *
- * // Bind 'ctrl+s' to trigger the command
- * const command = new MyCommand();
- * keybindingRegistry.bind('ctrl+s', command);
+ * @example Usage in a component
+ * ```ts
+ * class MyComponent {
+ *     private saveCommand = new SaveCommand();
  *
- * // Remove the binding when we no longer need it to trigger the command
- * keybindingRegistry.unbind('ctrl+s')
+ *     connectedCallback() {
+ *         this.keybindingRegistry.bind('ctrl+s', this.saveCommand);
+ *     }
+ *
+ *     disconnectedCallback() {
+ *         this.keybindingRegistry.unbind('ctrl+s', this.saveCommand);
+ *     }
+ *
+ *    private get keybindingRegistry() {
+ *        return this.platform.get(PlatformServiceName.KeybindingRegistry);
+ *    }
+ * }
  * ```
+ *
  * @note This service is work in progress
  * @beta
  * @group Keyboard shortcuts
@@ -39,46 +74,124 @@ export interface KeybindingRegistry {
     /**
      * Bind a command to a specific key combination to add it to the registry
      *
-     * @param keys - the string representation of keys
-     * @param command - the command to trigger when keys are pressed
-     * @throws Will throw an error if the command is invalid or not registered
+     * When a user presses the specified key combination, the command will be
+     * dispatched through the {@link CommandBus}. The command must already have
+     * a handler registered on the command bus before binding.
+     *
+     * If the same key combination is bound to multiple commands, all commands
+     * will be executed in the order they were registered.
+     *
+     * @param keys - the string representation of keys (e.g., 'ctrl+s', 'alt+shift+n', 'g i')
+     * @param command - the command instance to trigger when keys are pressed
+     * @throws Will throw an error if the command is invalid or not registered on the command bus
+     *
+     * @example
+     * ```ts
+     * const command = new SaveCommand();
+     * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+     * registry.bind('ctrl+s', command);
+     * ```
      */
     bind: (keys: string, command: object) => void;
     /**
      * Unbind a keybinding to remove it from the registry
      *
-     * @param keys - the string representation of the key combination
-     * @param command - the command connected to the key combination
+     * Removes the association between a key combination and a command. After
+     * unbinding, pressing the key combination will no longer trigger the command.
+     * This is essential for cleanup when components are removed from the DOM.
+     *
+     * If multiple commands are bound to the same key combination, only the
+     * specified command will be unbound.
+     *
+     * @param keys - the string representation of the key combination (e.g., 'ctrl+s')
+     * @param command - the command instance connected to the key combination
+     *
+     * @example
+     * ```ts
+     * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+     * registry.unbind('ctrl+s', saveCommand);
+     * ```
      */
     unbind: (keys: string, command: object) => void;
     /**
      * Get a list of the key bindings that are currently in the registry
      *
-     * @returns the list of command and its specific key combination
+     * Returns all active keybindings across all components. Useful for debugging,
+     * displaying keyboard shortcuts to users, or detecting conflicts.
+     *
+     * @returns the list of all active keybindings with their commands
+     *
+     * @example
+     * ```ts
+     * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+     * const bindings = registry.getKeybindings();
+     * bindings.forEach(binding => {
+     *     console.log(`${binding.keys} → ${binding.command}`);
+     * });
+     * ```
      */
     getKeybindings: () => Keybinding[];
     /**
      * Checks if a key combination or a specific keybinding is already bound
      *
-     * @param keys - the string representation of a key combination
-     * @param command - the command connected to the key combination
-     * @returns true if key combination already exists, else false
+     * Use this method to detect conflicts before binding new keybindings.
+     * When called with just a key combination, returns true if any command
+     * is bound to those keys. When called with both keys and a command,
+     * returns true only if that specific combination exists.
+     *
+     * @param keys - the string representation of a key combination (e.g., 'ctrl+s')
+     * @param command - optional command instance to check for a specific binding
+     * @returns true if the key combination is bound (to any or the specified command), false otherwise
+     *
+     * @example Check if any command is bound to keys
+     * ```ts
+     * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+     * if (registry.isBound('ctrl+s')) {
+     *     console.warn('ctrl+s is already bound');
+     * }
+     * ```
+     *
+     * @example Check if a specific command is bound to keys
+     * ```ts
+     * const registry = platform.get(PlatformServiceName.KeybindingRegistry);
+     * if (registry.isBound('ctrl+s', saveCommand)) {
+     *     console.log('Save command is bound to ctrl+s');
+     * }
+     * ```
      */
     isBound: (keys: string, command?: object) => boolean;
 }
 /**
  * A key combination and its corresponding command that will be triggered when
  * the key combination is pressed
+ *
+ * Represents an active binding in the {@link KeybindingRegistry}. Each keybinding
+ * associates a specific key combination with a command instance that will be
+ * executed via the {@link CommandBus} when the keys are pressed.
+ *
+ * @example
+ * ```ts
+ * const binding: Keybinding = {
+ *     keys: 'ctrl+s',
+ *     command: new SaveCommand(),
+ * };
+ * ```
+ *
  * @beta
  * @group Keyboard shortcuts
  */
 export interface Keybinding {
     /**
-     * The string representation of key combination
+     * The string representation of a key combination
+     *
+     * Examples: `'ctrl+s'`, `'alt+shift+n'`, `'g i'`, `'escape'`
      */
     keys: string;
     /**
-     * The command to trigger when the key combination is pressed
+     * The command instance to trigger when the key combination is pressed
+     *
+     * This command must be registered on the {@link CommandBus} before the
+     * keybinding is created.
      */
     command: object;
 }

package/dist/keybindings/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/keybindings/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;;;OAKG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,cAAc,EAAE,MAAM,UAAU,EAAE,CAAC;IAEnC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/keybindings/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,EAAE,MAAM,UAAU,EAAE,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAU;IACvB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;CACnB"}

package/dist/logger/factory.d.ts

@@ -0,0 +1,51 @@
+import { Logger } from './logger';
+/**
+ * Creates a logger instance using the platform's logger factory
+ *
+ * This function retrieves the logger factory from the global Lime platform
+ * object and creates a scoped logger. If the platform factory is not available,
+ * it falls back to the browser console.
+ *
+ * The package name is automatically determined from the module's URL on the first
+ * call and cached for all subsequent calls. This ensures consistent logger scopes
+ * across all loggers created from the same module instance.
+ *
+ * @param scope - The scope/category for the logger (e.g., 'my-component', 'http-client')
+ * @returns A logger instance integrated with the platform or console fallback
+ *
+ * @remarks
+ * The console fallback is provided for development scenarios where the full
+ * Lime platform is not available. The console object does not fully implement
+ * the Logger interface but provides compatible logging methods.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('my-component');
+ * logger.info('Component initialized');
+ * logger.debug('Processing data', { count: 42 });
+ * ```
+ *
+ * @beta
+ * @group Logger
+ */
+export declare function createLogger(scope: string): Logger;
+/**
+ * Extracts the package name from a given URL
+ *
+ * Supports multiple URL patterns:
+ * - `/packages/@scope/name/version/...` → extracts `name`
+ * - `/static/name+version/...` → extracts `name`
+ * - `/static/directory/name+version/...` → extracts `name`
+ * - `/static/name/...` → extracts `name`
+ *
+ * The extracted name is cleaned by removing common prefixes and suffixes.
+ *
+ * @param url - The URL string to extract the package name from
+ *
+ * @returns The extracted package name, or null if not found
+ *
+ * @beta
+ * @group Logger
+ */
+export declare function getPackageNameFromUrl(url: string | null): string | null;
+//# sourceMappingURL=factory.d.ts.map

package/dist/logger/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/logger/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAKlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBlD;AAqCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAcvE"}

package/dist/logger/factory.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=factory.spec.d.ts.map

package/dist/logger/factory.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.spec.d.ts","sourceRoot":"","sources":["../../src/logger/factory.spec.ts"],"names":[],"mappings":""}

package/dist/logger/index.d.ts

@@ -1,3 +1,4 @@
 export * from './logger';
 export * from './types';
+export { createLogger, getPackageNameFromUrl } from './factory';
 //# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}

package/dist/problem/index.d.ts

@@ -0,0 +1,6 @@
+export * from './problem';
+export * from './query';
+export * from './provider';
+export * from './repository';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/problem/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/problem/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}