@open-pioneer/runtime 4.7.0-dev.20260624141040 → 4.7.0-dev.20260713101438

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/CHANGELOG.md +14 -1
  2. package/CustomElement.d.ts +27 -2
  3. package/CustomElement.js.map +1 -1
  4. package/_virtual/source-info.js +2 -2
  5. package/api.d.ts +55 -2
  6. package/app/AppInstance.d.ts +3 -27
  7. package/app/AppInstance.js +144 -119
  8. package/app/AppInstance.js.map +1 -1
  9. package/app/gatherConfig.js +1 -0
  10. package/app/gatherConfig.js.map +1 -1
  11. package/builtin-services/ApiServiceImpl.d.ts +1 -1
  12. package/builtin-services/ApiServiceImpl.js +3 -3
  13. package/builtin-services/ApiServiceImpl.js.map +1 -1
  14. package/builtin-services/ApplicationContextImpl.d.ts +11 -7
  15. package/builtin-services/ApplicationContextImpl.js +51 -10
  16. package/builtin-services/ApplicationContextImpl.js.map +1 -1
  17. package/builtin-services/LocaleServiceImpl.d.ts +18 -0
  18. package/builtin-services/LocaleServiceImpl.js +29 -0
  19. package/builtin-services/LocaleServiceImpl.js.map +1 -0
  20. package/builtin-services/NumberParserServiceImpl.d.ts +8 -3
  21. package/builtin-services/NumberParserServiceImpl.js +17 -12
  22. package/builtin-services/NumberParserServiceImpl.js.map +1 -1
  23. package/builtin-services/index.d.ts +3 -1
  24. package/builtin-services/index.js +34 -4
  25. package/builtin-services/index.js.map +1 -1
  26. package/dom/index.d.ts +1 -1
  27. package/dom/index.js +1 -4
  28. package/dom/index.js.map +1 -1
  29. package/i18n/AppIntl.d.ts +49 -11
  30. package/i18n/AppIntl.js +205 -87
  31. package/i18n/AppIntl.js.map +1 -1
  32. package/i18n/index.d.ts +3 -2
  33. package/i18n/index.js +2 -1
  34. package/i18n/index.js.map +1 -1
  35. package/i18n/intl-locale.d.ts +13 -0
  36. package/i18n/intl-locale.js +17 -0
  37. package/i18n/intl-locale.js.map +1 -0
  38. package/i18n/pick.d.ts +29 -16
  39. package/i18n/pick.js +78 -51
  40. package/i18n/pick.js.map +1 -1
  41. package/index.d.ts +1 -1
  42. package/index.js +6 -0
  43. package/index.js.map +1 -1
  44. package/package.json +6 -5
  45. package/react-integration/ChakraProvider.d.ts +1 -1
  46. package/react-integration/ChakraProvider.js +3 -2
  47. package/react-integration/ChakraProvider.js.map +1 -1
  48. package/react-integration/PackageContext.d.ts +1 -1
  49. package/react-integration/PackageContext.js.map +1 -1
  50. package/react-integration/ReactIntegration.d.ts +2 -10
  51. package/react-integration/ReactIntegration.js +28 -28
  52. package/react-integration/ReactIntegration.js.map +1 -1
  53. package/react-integration/hooks.js +5 -9
  54. package/react-integration/hooks.js.map +1 -1
  55. package/service-layer/ServiceLayer.d.ts +1 -20
  56. package/service-layer/ServiceLayer.js +39 -39
  57. package/service-layer/ServiceLayer.js.map +1 -1
  58. package/service-layer/ServiceLookup.d.ts +1 -3
  59. package/service-layer/ServiceLookup.js +10 -10
  60. package/service-layer/ServiceLookup.js.map +1 -1
  61. package/service-layer/ServiceRepr.d.ts +2 -11
  62. package/service-layer/ServiceRepr.js +68 -50
  63. package/service-layer/ServiceRepr.js.map +1 -1
  64. package/service-layer/verifyDependencies.js +33 -33
  65. package/service-layer/verifyDependencies.js.map +1 -1
  66. package/test-support/index.js +2 -1
  67. package/test-support/index.js.map +1 -1
package/CHANGELOG.md CHANGED
@@ -1,14 +1,27 @@
1
1
  # @open-pioneer/runtime
2
2
 
3
- ## 4.7.0-dev.20260624141040
3
+ ## 4.7.0-dev.20260713101438
4
4
 
5
5
  ### Minor Changes
6
6
 
7
+ - 278515d: Deprecate the following methods on the `ApplicationContext`: `getLocale`, `setLocale`, `getSupportedLocales()`.
8
+ Use the alternatives provided by the new `LocaleService` instead.
7
9
  - e433296: Update Chakra UI to 3.36.0
10
+ - 278515d: Add `runtime.LocaleService` and opt-in reactive locale switching.
11
+
12
+ You can opt-in by configuring the property `advanced.enableLiveLocaleChanges` when calling `createCustomElement`.
13
+ Once enabled, locale switches can be done without restarting the application.
14
+ Use `LocaleService.changeLocale` to update the application's locale.
15
+
16
+ Also export `parseLocale` and `tryParseLocale` algorithms.
17
+ These can be used to construct a (cleaned up) `Intl.Locale` object from a string.
8
18
 
9
19
  ### Patch Changes
10
20
 
21
+ - 8c277a2: Include service id in deprecation message of 'serviceOptions.intl'.
22
+ - 78aad9d: Refactor: use private javascript properties instead of typescript private keyword.
11
23
  - 7c7e6d1: Refactor equality comparisons using shallow equals from @open-pioneer/core.
24
+ - 8b5c324: Fix 'useIntl' not transporting reactive changes of the intl object in production (e.g. when the locale changes).
12
25
 
13
26
  ## 4.6.0
14
27
 
@@ -84,13 +84,26 @@ export interface ApplicationOverrides {
84
84
  */
85
85
  export interface ApplicationConfig {
86
86
  /**
87
- * Set this value to a locale string (e.g. "en") to for the application's locale.
87
+ * Set this value to a locale (BCP-47 string, e.g. `"en"`) to set the default message locale of the application.
88
+ *
88
89
  * The default behavior is to choose an appropriate locale for the current user based
89
90
  * on the browser's settings.
90
91
  *
91
- * The locale must be supported by the application.
92
+ * This locale should match one of the supported message locales defined by the application's package.
92
93
  */
93
94
  locale?: string | undefined;
95
+ /**
96
+ * The list of locales supported by the application.
97
+ *
98
+ * This allows a further restriction of the locales supported by the application, compared to the ones defined by the application's package.
99
+ * It is not possible to extend the supported locales defined by the package, only to restrict them.
100
+ *
101
+ * If this property is not set, then the application supports all locales defined by the application's package.
102
+ * If the values are not a valid subset of the application package supported locales, then the application will throw an error at startup.
103
+ *
104
+ * An empty array will disable loading of any message bundle.
105
+ */
106
+ supportedLocales?: string[] | undefined;
94
107
  /**
95
108
  * Configures the application's initial color mode.
96
109
  *
@@ -160,6 +173,18 @@ export interface AdvancedCustomElementOptions {
160
173
  * ensure that your components work in that setting.
161
174
  */
162
175
  enableShadowRoot?: boolean;
176
+ /**
177
+ * Opts into live locale changes within the running application, without performing a full application restart.
178
+ *
179
+ * Default: `false`.
180
+ *
181
+ * Live locale changes preserve the application's state when the user changes the language.
182
+ * It requires that react components and services in the application handle intl changes correctly (see, for example, {@link ServiceOptions.currentIntl}).
183
+ *
184
+ * Note that this option will become the new default in the next major release,
185
+ * at which point this option will be removed.
186
+ */
187
+ enableLiveLocaleChanges?: boolean;
163
188
  }
164
189
  /**
165
190
  * The class returned by a call to {@link createCustomElement}.
@@ -1 +1 @@
1
- {"version":3,"file":"CustomElement.js","sources":["CustomElement.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { SystemConfig as ChakraSystemConfig } from \"@chakra-ui/react\";\nimport { createLogger, Error } from \"@open-pioneer/core\";\nimport { sourceId } from \"open-pioneer:source-info\";\nimport { ComponentType } from \"react\";\nimport { type ApiMethods, type ColorModeValue, type ApiExtension } from \"./api\";\nimport { AppInstance } from \"./app\";\nimport { ErrorId } from \"./errors\";\nimport { ApplicationMetadata } from \"./metadata\";\n\nconst LOG = createLogger(sourceId);\n\n/**\n * Options for the {@link createCustomElement} function.\n */\nexport interface CustomElementOptions {\n /**\n * Rendered UI component.\n */\n component?: ComponentType<Record<string, string>>;\n\n /**\n * Application metadata (packages, services etc.).\n * This is usually autogenerated by importing the virtual `\"open-pioneer:app\"` module.\n */\n appMetadata?: ApplicationMetadata;\n\n /**\n * Application defined configuration.\n *\n * This option can be used to override default properties of the application's packages.\n *\n * All instances of the web component will share this static configuration.\n */\n config?: ApplicationConfig;\n\n /**\n * Chakra styled system object.\n *\n * Used to configure chakra's theme.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n\n /**\n * Advanced configuration that alters the behavior of the custom element.\n */\n advanced?: AdvancedCustomElementOptions;\n\n /**\n * Function to provide additional application defined configuration parameters.\n *\n * Compared to {@link config}, this function receives a context object\n * that allows the developer to provide dynamic properties on a per-application instance basis.\n *\n * Parameters returned by this function take precedence over the ones defined by {@link config}.\n */\n resolveConfig?(ctx: ConfigContext): Promise<ApplicationConfig | undefined>;\n}\n\n/**\n * A context object that is passed to the `resolveProperties` function.\n */\nexport interface ConfigContext {\n /**\n * The application's host element.\n */\n hostElement: HTMLElement;\n\n /**\n * Defined when the application forcefully restarts with new options.\n */\n overrides: ApplicationOverrides | undefined;\n\n /**\n * Returns an attribute from the application's root node.\n */\n getAttribute(name: string): string | undefined;\n}\n\n/**\n * Application overrides are defined when the is explicitly being restarted with new options.\n *\n * Options set through overrides cannot be overwritten by the `resolveConfig` hook.\n */\nexport interface ApplicationOverrides {\n /**\n * The new application locale.\n */\n locale?: string;\n\n /**\n * The new color mode.\n */\n colorMode?: ColorModeValue | \"system\";\n\n /**\n * The new used chakra system config.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n}\n\n/**\n * Runtime application configuration.\n */\nexport interface ApplicationConfig {\n /**\n * Set this value to a locale string (e.g. \"en\") to for the application's locale.\n * The default behavior is to choose an appropriate locale for the current user based\n * on the browser's settings.\n *\n * The locale must be supported by the application.\n */\n locale?: string | undefined;\n\n /**\n * Configures the application's initial color mode.\n *\n * Use `system` to use the user's preferred color mode, derived from the browser or operating system.\n *\n * Default: `light`.\n */\n colorMode?: ColorModeValue | \"system\";\n\n /**\n * Properties specified here will override default properties of the application's packages.\n */\n properties?: ApplicationProperties | undefined;\n\n /**\n * Chakra styled system object.\n *\n * Used to configure chakra's theme.\n *\n * NOTE: This setting has priority over {@link CustomElementOptions.chakraSystemConfig}.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n}\n\n/**\n * Allows the application to override default properties in all packages.\n *\n * Properties are typed when the package contains type definitions for them.\n */\nexport interface ApplicationProperties {\n /**\n * Key: the name of the package.\n * Value: A record of configuration properties (key/value pairs).\n *\n * Properties will override default property values in the package.\n */\n [packageName: string]: Record<string, unknown>;\n}\n\n/**\n * The interface implemented by web components produced via {@link createCustomElement}.\n */\nexport interface ApplicationElement extends HTMLElement {\n /**\n * Resolves to the element's API when the application has started.\n *\n * The API exposed by an application can be defined by implementing an {@link ApiExtension}.\n * For more details, open the documentation of the `@open-pioneer/integration` package.\n */\n when(): Promise<ApiMethods>;\n}\n\n/**\n * Advanced configuration that alters the behavior of the custom element.\n *\n * See {@link createCustomElement}.\n */\nexport interface AdvancedCustomElementOptions {\n /**\n * Enables or disables the [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) inside the application's web component.\n *\n * Default: `true`.\n *\n * By default, trails applications use a shadow root to avoid conflicts (e.g. styles) with other parts of the site where the application may be embedded.\n *\n * Applications that use the entire browser viewport may not need this feature, since there may be no \"other\" parts that may conflict with the app.\n * In this case, you can disable the shadow root by setting this property to `false`.\n * In general, UI components used by the app (e.g. from Chakra UI) should work just as well when disabling the shadow root.\n * If you notice any problems, please file an issue.\n *\n * If you are developing UI components that are meant to be used in other applications, you should always use a shadow root to\n * ensure that your components work in that setting.\n */\n enableShadowRoot?: boolean;\n}\n\n/**\n * The class returned by a call to {@link createCustomElement}.\n */\nexport interface ApplicationElementConstructor {\n new (): ApplicationElement;\n}\n\n/**\n * Creates a new custom element class (web component) that can be registered within a DOM.\n *\n * @example\n * ```ts\n * import * as appMetadata from \"open-pioneer:app\";\n *\n * const CustomElementClazz = createCustomElement({\n * component: <div>Hello World!</div>,\n * appMetadata\n * });\n * customElements.define(\"sample-element\", CustomElementClazz);\n * ```\n */\nexport function createCustomElement(options: CustomElementOptions): ApplicationElementConstructor {\n class PioneerApplication extends HTMLElement implements ApplicationElement {\n #shadowRoot: ShadowRoot | undefined;\n #instance: AppInstance | undefined;\n\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n #deferredRestart: any; // A Timer\n\n static get observedAttributes(): string[] {\n return [];\n }\n\n constructor() {\n super();\n\n const enableShadowRoot = options.advanced?.enableShadowRoot ?? true;\n if (enableShadowRoot) {\n this.#shadowRoot = this.attachShadow({\n mode: \"open\"\n });\n } else {\n LOG.debug(\"Creating component instance without shadow root\");\n }\n\n if (import.meta.env.DEV) {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n (this as any).$inspectElementState = () => this.#instance;\n }\n }\n\n connectedCallback() {\n LOG.debug(\"Launching application\");\n\n if (this.#instance) {\n this.#instance.destroy();\n }\n\n this.#instance = this.#createApplicationInstance();\n this.#instance.start();\n }\n\n disconnectedCallback() {\n LOG.debug(\"Shutting down application\");\n\n if (this.#deferredRestart) {\n clearTimeout(this.#deferredRestart);\n }\n this.#instance?.destroy();\n this.#instance = undefined;\n\n LOG.debug(\"Application destroyed\");\n }\n\n when() {\n if (!this.#instance) {\n return Promise.reject(\n new Error(\n ErrorId.NOT_MOUNTED,\n \"Cannot use the application's API because the HTML element has not yet been mounted into the DOM.\"\n )\n );\n }\n\n return this.#instance.whenAPI();\n }\n\n #triggerReload(overrides?: ApplicationOverrides) {\n // Defer the restart operation a tiny bit so calling code does not get surprised by the application's destruction.\n if (this.#deferredRestart) {\n clearTimeout(this.#deferredRestart);\n }\n this.#deferredRestart = setTimeout(() => {\n if (!this.#instance) {\n // disconnectedCallback was called in the meantime\n return;\n }\n\n LOG.debug(\"Restarting application with new options\", overrides);\n this.#instance.destroy();\n this.#instance = this.#createApplicationInstance(overrides);\n this.#instance.start();\n }, 1);\n }\n\n #createApplicationInstance(overrides?: ApplicationOverrides) {\n return new AppInstance({\n rootNode: this.#shadowRoot ?? document,\n hostElement: this,\n elementOptions: options,\n overrides: overrides,\n restart: this.#triggerReload.bind(this)\n });\n }\n }\n return PioneerApplication;\n}\n"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"CustomElement.js","sources":["CustomElement.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { SystemConfig as ChakraSystemConfig } from \"@chakra-ui/react\";\nimport { createLogger, Error } from \"@open-pioneer/core\";\nimport type { ServiceOptions } from \"./Service\";\nimport { sourceId } from \"open-pioneer:source-info\";\nimport { ComponentType } from \"react\";\nimport { type ApiMethods, type ColorModeValue, type ApiExtension } from \"./api\";\nimport { AppInstance } from \"./app\";\nimport { ErrorId } from \"./errors\";\nimport { ApplicationMetadata } from \"./metadata\";\n\nconst LOG = createLogger(sourceId);\n\n/**\n * Options for the {@link createCustomElement} function.\n */\nexport interface CustomElementOptions {\n /**\n * Rendered UI component.\n */\n component?: ComponentType<Record<string, string>>;\n\n /**\n * Application metadata (packages, services etc.).\n * This is usually autogenerated by importing the virtual `\"open-pioneer:app\"` module.\n */\n appMetadata?: ApplicationMetadata;\n\n /**\n * Application defined configuration.\n *\n * This option can be used to override default properties of the application's packages.\n *\n * All instances of the web component will share this static configuration.\n */\n config?: ApplicationConfig;\n\n /**\n * Chakra styled system object.\n *\n * Used to configure chakra's theme.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n\n /**\n * Advanced configuration that alters the behavior of the custom element.\n */\n advanced?: AdvancedCustomElementOptions;\n\n /**\n * Function to provide additional application defined configuration parameters.\n *\n * Compared to {@link config}, this function receives a context object\n * that allows the developer to provide dynamic properties on a per-application instance basis.\n *\n * Parameters returned by this function take precedence over the ones defined by {@link config}.\n */\n resolveConfig?(ctx: ConfigContext): Promise<ApplicationConfig | undefined>;\n}\n\n/**\n * A context object that is passed to the `resolveProperties` function.\n */\nexport interface ConfigContext {\n /**\n * The application's host element.\n */\n hostElement: HTMLElement;\n\n /**\n * Defined when the application forcefully restarts with new options.\n */\n overrides: ApplicationOverrides | undefined;\n\n /**\n * Returns an attribute from the application's root node.\n */\n getAttribute(name: string): string | undefined;\n}\n\n/**\n * Application overrides are defined when the is explicitly being restarted with new options.\n *\n * Options set through overrides cannot be overwritten by the `resolveConfig` hook.\n */\nexport interface ApplicationOverrides {\n /**\n * The new application locale.\n */\n locale?: string;\n\n /**\n * The new color mode.\n */\n colorMode?: ColorModeValue | \"system\";\n\n /**\n * The new used chakra system config.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n}\n\n/**\n * Runtime application configuration.\n */\nexport interface ApplicationConfig {\n /**\n * Set this value to a locale (BCP-47 string, e.g. `\"en\"`) to set the default message locale of the application.\n *\n * The default behavior is to choose an appropriate locale for the current user based\n * on the browser's settings.\n *\n * This locale should match one of the supported message locales defined by the application's package.\n */\n locale?: string | undefined;\n\n /**\n * The list of locales supported by the application.\n *\n * This allows a further restriction of the locales supported by the application, compared to the ones defined by the application's package.\n * It is not possible to extend the supported locales defined by the package, only to restrict them.\n *\n * If this property is not set, then the application supports all locales defined by the application's package.\n * If the values are not a valid subset of the application package supported locales, then the application will throw an error at startup.\n *\n * An empty array will disable loading of any message bundle.\n */\n supportedLocales?: string[] | undefined;\n\n /**\n * Configures the application's initial color mode.\n *\n * Use `system` to use the user's preferred color mode, derived from the browser or operating system.\n *\n * Default: `light`.\n */\n colorMode?: ColorModeValue | \"system\";\n\n /**\n * Properties specified here will override default properties of the application's packages.\n */\n properties?: ApplicationProperties | undefined;\n\n /**\n * Chakra styled system object.\n *\n * Used to configure chakra's theme.\n *\n * NOTE: This setting has priority over {@link CustomElementOptions.chakraSystemConfig}.\n */\n chakraSystemConfig?: ChakraSystemConfig;\n}\n\n/**\n * Allows the application to override default properties in all packages.\n *\n * Properties are typed when the package contains type definitions for them.\n */\nexport interface ApplicationProperties {\n /**\n * Key: the name of the package.\n * Value: A record of configuration properties (key/value pairs).\n *\n * Properties will override default property values in the package.\n */\n [packageName: string]: Record<string, unknown>;\n}\n\n/**\n * The interface implemented by web components produced via {@link createCustomElement}.\n */\nexport interface ApplicationElement extends HTMLElement {\n /**\n * Resolves to the element's API when the application has started.\n *\n * The API exposed by an application can be defined by implementing an {@link ApiExtension}.\n * For more details, open the documentation of the `@open-pioneer/integration` package.\n */\n when(): Promise<ApiMethods>;\n}\n\n/**\n * Advanced configuration that alters the behavior of the custom element.\n *\n * See {@link createCustomElement}.\n */\nexport interface AdvancedCustomElementOptions {\n /**\n * Enables or disables the [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) inside the application's web component.\n *\n * Default: `true`.\n *\n * By default, trails applications use a shadow root to avoid conflicts (e.g. styles) with other parts of the site where the application may be embedded.\n *\n * Applications that use the entire browser viewport may not need this feature, since there may be no \"other\" parts that may conflict with the app.\n * In this case, you can disable the shadow root by setting this property to `false`.\n * In general, UI components used by the app (e.g. from Chakra UI) should work just as well when disabling the shadow root.\n * If you notice any problems, please file an issue.\n *\n * If you are developing UI components that are meant to be used in other applications, you should always use a shadow root to\n * ensure that your components work in that setting.\n */\n enableShadowRoot?: boolean;\n\n /**\n * Opts into live locale changes within the running application, without performing a full application restart.\n *\n * Default: `false`.\n *\n * Live locale changes preserve the application's state when the user changes the language.\n * It requires that react components and services in the application handle intl changes correctly (see, for example, {@link ServiceOptions.currentIntl}).\n *\n * Note that this option will become the new default in the next major release,\n * at which point this option will be removed.\n */\n enableLiveLocaleChanges?: boolean;\n}\n\n/**\n * The class returned by a call to {@link createCustomElement}.\n */\nexport interface ApplicationElementConstructor {\n new (): ApplicationElement;\n}\n\n/**\n * Creates a new custom element class (web component) that can be registered within a DOM.\n *\n * @example\n * ```ts\n * import * as appMetadata from \"open-pioneer:app\";\n *\n * const CustomElementClazz = createCustomElement({\n * component: <div>Hello World!</div>,\n * appMetadata\n * });\n * customElements.define(\"sample-element\", CustomElementClazz);\n * ```\n */\nexport function createCustomElement(options: CustomElementOptions): ApplicationElementConstructor {\n class PioneerApplication extends HTMLElement implements ApplicationElement {\n #shadowRoot: ShadowRoot | undefined;\n #instance: AppInstance | undefined;\n\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n #deferredRestart: any; // A Timer\n\n static get observedAttributes(): string[] {\n return [];\n }\n\n constructor() {\n super();\n\n const enableShadowRoot = options.advanced?.enableShadowRoot ?? true;\n if (enableShadowRoot) {\n this.#shadowRoot = this.attachShadow({\n mode: \"open\"\n });\n } else {\n LOG.debug(\"Creating component instance without shadow root\");\n }\n\n if (import.meta.env.DEV) {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n (this as any).$inspectElementState = () => this.#instance;\n }\n }\n\n connectedCallback() {\n LOG.debug(\"Launching application\");\n\n if (this.#instance) {\n this.#instance.destroy();\n }\n\n this.#instance = this.#createApplicationInstance();\n this.#instance.start();\n }\n\n disconnectedCallback() {\n LOG.debug(\"Shutting down application\");\n\n if (this.#deferredRestart) {\n clearTimeout(this.#deferredRestart);\n }\n this.#instance?.destroy();\n this.#instance = undefined;\n\n LOG.debug(\"Application destroyed\");\n }\n\n when() {\n if (!this.#instance) {\n return Promise.reject(\n new Error(\n ErrorId.NOT_MOUNTED,\n \"Cannot use the application's API because the HTML element has not yet been mounted into the DOM.\"\n )\n );\n }\n\n return this.#instance.whenAPI();\n }\n\n #triggerReload(overrides?: ApplicationOverrides) {\n // Defer the restart operation a tiny bit so calling code does not get surprised by the application's destruction.\n if (this.#deferredRestart) {\n clearTimeout(this.#deferredRestart);\n }\n this.#deferredRestart = setTimeout(() => {\n if (!this.#instance) {\n // disconnectedCallback was called in the meantime\n return;\n }\n\n LOG.debug(\"Restarting application with new options\", overrides);\n this.#instance.destroy();\n this.#instance = this.#createApplicationInstance(overrides);\n this.#instance.start();\n }, 1);\n }\n\n #createApplicationInstance(overrides?: ApplicationOverrides) {\n return new AppInstance({\n rootNode: this.#shadowRoot ?? document,\n hostElement: this,\n elementOptions: options,\n overrides: overrides,\n restart: this.#triggerReload.bind(this)\n });\n }\n }\n return PioneerApplication;\n}\n"],"names":[],"mappings":"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"}
@@ -4,7 +4,7 @@ const sourceId$5 = "@open-pioneer/runtime/app/AppInstance";
4
4
 
5
5
  const sourceId$4 = "@open-pioneer/runtime/i18n/AppIntl";
6
6
 
7
- const sourceId$3 = "@open-pioneer/runtime/i18n/pick";
7
+ const sourceId$3 = "@open-pioneer/runtime/builtin-services/ApplicationContextImpl";
8
8
 
9
9
  const sourceId$2 = "@open-pioneer/runtime/builtin-services/ApplicationLifecycleEventService";
10
10
 
@@ -12,5 +12,5 @@ const sourceId$1 = "@open-pioneer/runtime/builtin-services/NumberParserServiceIm
12
12
 
13
13
  const sourceId = "@open-pioneer/runtime/service-layer/ServiceLayer";
14
14
 
15
- export { sourceId$3 as sourceId, sourceId$4 as sourceId$1, sourceId$2, sourceId$1 as sourceId$3, sourceId as sourceId$4, sourceId$5, sourceId$6 };
15
+ export { sourceId$4 as sourceId, sourceId$3 as sourceId$1, sourceId$2, sourceId$1 as sourceId$3, sourceId as sourceId$4, sourceId$5, sourceId$6 };
16
16
  //# sourceMappingURL=source-info.js.map
package/api.d.ts CHANGED
@@ -72,6 +72,8 @@ export interface ApplicationContext extends DeclaredService<"runtime.Application
72
72
  * Returns the current locale of the application.
73
73
  *
74
74
  * E.g. `"de-DE"`
75
+ *
76
+ * @deprecated Use {@link LocaleService.locale} instead.
75
77
  */
76
78
  getLocale(): string;
77
79
  /**
@@ -79,8 +81,7 @@ export interface ApplicationContext extends DeclaredService<"runtime.Application
79
81
  * `locale` must be one of the supported locales, see {@link getSupportedLocales()} or `undefined` (for automatic locale).
80
82
  * Note that `locale` does not need to be a precise match, e.g. `"de-DE"` is also valid if `"de"` is supported.
81
83
  *
82
- * > NOTE: This method will currently trigger a full restart of the application.
83
- * > Altering the locale on the fly is possible in theory but has not been implemented yet.
84
+ * @deprecated Use {@link LocaleService.changeLocale} instead.
84
85
  */
85
86
  setLocale(locale: string | undefined): void;
86
87
  /**
@@ -88,9 +89,61 @@ export interface ApplicationContext extends DeclaredService<"runtime.Application
88
89
  * the locales that have associated i18n messages.
89
90
  *
90
91
  * For example: `["de", "en"]`
92
+ * @deprecated Use {@link LocaleService.supportedMessageLocales} instead.
91
93
  */
92
94
  getSupportedLocales(): readonly string[];
93
95
  }
96
+ /**
97
+ * A service to inspect and control the application's active locale.
98
+ *
99
+ * ### `locale` vs `messageLocale`
100
+ *
101
+ * - {@link locale} is the locale used for `Intl`-based formatting (numbers, dates, ...).
102
+ * It may upgrade {@link messageLocale} with the user's script/region when compatible.
103
+ * - {@link messageLocale} is the locale of the currently loaded message bundle.
104
+ * Always one of {@link supportedMessageLocales}.
105
+ *
106
+ * ### Live locale changes
107
+ *
108
+ * If {@link supportsLiveChanges} is false, {@link changeLocale} triggers a full application restart.
109
+ * Otherwise the locale is updated in place.
110
+ *
111
+ * NOTE: live changes will become the new default with the next major release.
112
+ * Full application restarts due to locale changes will no longer happen then.
113
+ */
114
+ export interface LocaleService extends DeclaredService<"runtime.LocaleService"> {
115
+ /**
116
+ * Reactive: locale used for Intl formatting.
117
+ * Shares language with {@link messageLocale}; may add script/region when compatible.
118
+ */
119
+ readonly locale: Intl.Locale;
120
+ /**
121
+ * Reactive: the active locale used for i18n messages.
122
+ * If supportedMessageLocales is empty, this falls back to `en`.
123
+ */
124
+ readonly messageLocale: Intl.Locale;
125
+ /**
126
+ * Locales for which the application has translated messages.
127
+ * This list may be empty, if the application has no message bundles.
128
+ */
129
+ readonly supportedMessageLocales: readonly Intl.Locale[];
130
+ /**
131
+ * Flag indicating whether the application supports live changes for the current locale.
132
+ *
133
+ * If `true`, {@link changeLocale} applies the new locale in place.
134
+ * If `false`, {@link changeLocale} triggers a full application restart.
135
+ */
136
+ readonly supportsLiveChanges: boolean;
137
+ /**
138
+ * Switches to `locale`. Best-fit match against {@link supportedMessageLocales};
139
+ * throws `UNSUPPORTED_LOCALE` on no match. `undefined` enables automatic picking.
140
+ */
141
+ changeLocale(locale: Intl.Locale | undefined): Promise<void>;
142
+ /**
143
+ * True iff `locale` best-fits a supported message locale (regional variants accepted).
144
+ */
145
+ supportsLocale(locale: Intl.Locale): boolean;
146
+ }
94
147
  /**
95
148
  * Implementing this interface allows a service to be notified on certain
96
149
  * application-wide lifecycle events.
@@ -18,35 +18,11 @@ export interface AppOptions {
18
18
  }
19
19
  export type AppState = "not-started" | "starting" | "started" | "destroyed" | "error";
20
20
  export declare class AppInstance {
21
- private options;
22
- private apiPromise;
23
- private api;
24
- private state;
25
- private rootNode;
26
- private container;
27
- private appRoot;
28
- private config;
29
- private i18n;
30
- private serviceLayer;
31
- private lifecycleEvents;
32
- private themeService;
33
- private reactIntegration;
34
- private stylesWatch;
21
+ #private;
35
22
  constructor(options: AppOptions);
23
+ /** Current lifecycle state. Exposed (read-only) for tests/debugging via `$inspectElementState`. */
24
+ get state(): AppState;
36
25
  start(): void;
37
26
  destroy(): void;
38
- private reset;
39
27
  whenAPI(): Promise<ApiMethods>;
40
- private startImpl;
41
- /**
42
- * Returns a signal that contains the application's styles.
43
- * During development, the signal is updated when the user edits .css files.
44
- * In production, the signal is static.
45
- */
46
- private initStylesSignal;
47
- private initServiceLayer;
48
- private initAPI;
49
- private triggerApplicationLifecycleEvent;
50
- private checkAbort;
51
- private showErrorScreen;
52
28
  }