@open-pioneer/react-utils 4.6.0-dev.20260519125519 → 4.6.0

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.
package/CHANGELOG.md CHANGED
@@ -1,9 +1,20 @@
1
1
  # @open-pioneer/react-utils
2
2
 
3
- ## 4.6.0-dev.20260519125519
3
+ ## 4.6.0
4
4
 
5
5
  ### Minor Changes
6
6
 
7
+ - 10c8f27: Add new `FormattedMessage` and `FormattedRichMessage` components.
8
+ These components render translated messages using `intl.formatMessage` / `intl.formatRichMessage`
9
+ and support reactive changes of the `intl` property.
10
+
11
+ Example:
12
+
13
+ ```tsx
14
+ // currentIntl can be a signal
15
+ <FormattedMessage intl={currentIntl} id="message.id" />
16
+ ```
17
+
7
18
  - 27f5f1e: Add a new `classnames` function to replace the `classnames` package.
8
19
  - 4b207f4: Added a `required` option to `useHeadingLevel` hook to make it return `undefined` instead of throwing an error when used outside of a `TitledSection`.
9
20
 
@@ -0,0 +1,76 @@
1
+ import { ReactiveGetter, ReadonlyReactive } from "@conterra/reactivity-core";
2
+ import type { PackageIntl, RichTextValue } from "@open-pioneer/runtime";
3
+ import { type FormatXMLElementFn, type Options as IntlMessageFormatOptions, type PrimitiveType } from "intl-messageformat";
4
+ /**
5
+ * Shared formatting operations.
6
+ *
7
+ * @group Formatting
8
+ */
9
+ export interface FormattingBaseProps {
10
+ /**
11
+ * The `intl` object of the package rendering the message.
12
+ * Must contain a message associated with the given {@link id}.
13
+ *
14
+ * Note that this value can be a direct instance, or a signal / reactive getter implemented
15
+ * in terms of the Reactivity API.
16
+ */
17
+ intl: PackageIntl | ReadonlyReactive<PackageIntl> | ReactiveGetter<PackageIntl>;
18
+ }
19
+ /**
20
+ * Props supported by {@link FormattedMessage}.
21
+ *
22
+ * @group Formatting
23
+ */
24
+ export interface FormattedMessageProps extends FormattingBaseProps {
25
+ /** The message's id. */
26
+ id: string;
27
+ /**
28
+ * Formatting values used to parametrize the message.
29
+ * Also supports callbacks, see {@link PackageIntl.formatMessage}.
30
+ */
31
+ values?: Record<string, PrimitiveType | FormatXMLElementFn<string, string>>;
32
+ /** Additional options for the formatting operation. */
33
+ opts?: IntlMessageFormatOptions;
34
+ }
35
+ /**
36
+ * Renders the result of formatting a message using the provided intl object.
37
+ *
38
+ * Example:
39
+ *
40
+ * ```tsx
41
+ * <FormattedMessage intl={intl} id="message.id" />
42
+ * ```
43
+ *
44
+ * @expandType FormattedMessageProps
45
+ * @group Formatting
46
+ */
47
+ export declare function FormattedMessage(props: FormattedMessageProps): string;
48
+ /**
49
+ * Props supported by {@link FormattedRichMessage}.
50
+ *
51
+ * @group Formatting
52
+ */
53
+ export interface FormattedRichMessageProps extends FormattingBaseProps {
54
+ /** The message's id. */
55
+ id: string;
56
+ /**
57
+ * Formatting values used to parametrize the message.
58
+ * Also supports callbacks, see {@link PackageIntl.formatRichMessage}.
59
+ */
60
+ values?: Record<string, RichTextValue>;
61
+ /** Additional options for the formatting operation. */
62
+ opts?: IntlMessageFormatOptions;
63
+ }
64
+ /**
65
+ * Renders the result of formatting a message using the provided intl object.
66
+ *
67
+ * Example:
68
+ *
69
+ * ```tsx
70
+ * <FormattedRichMessage intl={intl} id="message.id" />
71
+ * ```
72
+ *
73
+ * @expandType FormattedRichMessageProps
74
+ * @group Formatting
75
+ */
76
+ export declare function FormattedRichMessage(props: FormattedRichMessageProps): import("react").ReactNode;
@@ -0,0 +1,28 @@
1
+ import { getValue } from '@conterra/reactivity-core';
2
+ import { useReactiveSnapshot } from '@open-pioneer/reactivity';
3
+ import { useMemo } from 'react';
4
+
5
+ function FormattedMessage(props) {
6
+ const { id, values, opts } = props;
7
+ const intl = useReactiveIntl(props);
8
+ return useMemo(
9
+ () => String(intl.formatMessage({ id }, values, opts)),
10
+ [intl, id, values, opts]
11
+ );
12
+ }
13
+ function FormattedRichMessage(props) {
14
+ const { id, values, opts } = props;
15
+ const intl = useReactiveIntl(props);
16
+ return useMemo(() => intl.formatRichMessage({ id }, values, opts), [intl, id, values, opts]);
17
+ }
18
+ function useReactiveIntl({ intl }) {
19
+ return useReactiveSnapshot(() => {
20
+ if (typeof intl === "function") {
21
+ return intl();
22
+ }
23
+ return getValue(intl);
24
+ }, [intl]);
25
+ }
26
+
27
+ export { FormattedMessage, FormattedRichMessage };
28
+ //# sourceMappingURL=FormattedMessage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"FormattedMessage.js","sources":["FormattedMessage.tsx"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { getValue, ReactiveGetter, ReadonlyReactive } from \"@conterra/reactivity-core\";\nimport { useReactiveSnapshot } from \"@open-pioneer/reactivity\";\nimport type { PackageIntl, RichTextValue } from \"@open-pioneer/runtime\";\nimport {\n type FormatXMLElementFn,\n type Options as IntlMessageFormatOptions,\n type PrimitiveType\n} from \"intl-messageformat\"; // not a dependency, this is a dependency of formatjs\nimport { useMemo } from \"react\";\n\n/**\n * Shared formatting operations.\n *\n * @group Formatting\n */\nexport interface FormattingBaseProps {\n /**\n * The `intl` object of the package rendering the message.\n * Must contain a message associated with the given {@link id}.\n *\n * Note that this value can be a direct instance, or a signal / reactive getter implemented\n * in terms of the Reactivity API.\n */\n intl: PackageIntl | ReadonlyReactive<PackageIntl> | ReactiveGetter<PackageIntl>;\n}\n\n/**\n * Props supported by {@link FormattedMessage}.\n *\n * @group Formatting\n */\nexport interface FormattedMessageProps extends FormattingBaseProps {\n /** The message's id. */\n id: string;\n\n /**\n * Formatting values used to parametrize the message.\n * Also supports callbacks, see {@link PackageIntl.formatMessage}.\n */\n values?: Record<string, PrimitiveType | FormatXMLElementFn<string, string>>;\n\n /** Additional options for the formatting operation. */\n opts?: IntlMessageFormatOptions;\n}\n\n/**\n * Renders the result of formatting a message using the provided intl object.\n *\n * Example:\n *\n * ```tsx\n * <FormattedMessage intl={intl} id=\"message.id\" />\n * ```\n *\n * @expandType FormattedMessageProps\n * @group Formatting\n */\nexport function FormattedMessage(props: FormattedMessageProps) {\n const { id, values, opts } = props;\n const intl = useReactiveIntl(props);\n return useMemo(\n () => String(intl.formatMessage({ id }, values, opts)),\n [intl, id, values, opts]\n );\n}\n\n/**\n * Props supported by {@link FormattedRichMessage}.\n *\n * @group Formatting\n */\nexport interface FormattedRichMessageProps extends FormattingBaseProps {\n /** The message's id. */\n id: string;\n\n /**\n * Formatting values used to parametrize the message.\n * Also supports callbacks, see {@link PackageIntl.formatRichMessage}.\n */\n values?: Record<string, RichTextValue>;\n\n /** Additional options for the formatting operation. */\n opts?: IntlMessageFormatOptions;\n}\n\n/**\n * Renders the result of formatting a message using the provided intl object.\n *\n * Example:\n *\n * ```tsx\n * <FormattedRichMessage intl={intl} id=\"message.id\" />\n * ```\n *\n * @expandType FormattedRichMessageProps\n * @group Formatting\n */\nexport function FormattedRichMessage(props: FormattedRichMessageProps) {\n const { id, values, opts } = props;\n const intl = useReactiveIntl(props);\n return useMemo(() => intl.formatRichMessage({ id }, values, opts), [intl, id, values, opts]);\n}\n\nfunction useReactiveIntl({ intl }: FormattingBaseProps) {\n return useReactiveSnapshot(() => {\n if (typeof intl === \"function\") {\n // reactive getter\n return intl();\n }\n return getValue(intl);\n }, [intl]);\n}\n"],"names":[],"mappings":";;;;AA2DO,SAAS,iBAAiB,KAAA,EAA8B;AAC3D,EAAA,MAAM,EAAE,EAAA,EAAI,MAAA,EAAQ,IAAA,EAAK,GAAI,KAAA;AAC7B,EAAA,MAAM,IAAA,GAAO,gBAAgB,KAAK,CAAA;AAClC,EAAA,OAAO,OAAA;AAAA,IACH,MAAM,OAAO,IAAA,CAAK,aAAA,CAAc,EAAE,EAAA,EAAG,EAAG,MAAA,EAAQ,IAAI,CAAC,CAAA;AAAA,IACrD,CAAC,IAAA,EAAM,EAAA,EAAI,MAAA,EAAQ,IAAI;AAAA,GAC3B;AACJ;AAiCO,SAAS,qBAAqB,KAAA,EAAkC;AACnE,EAAA,MAAM,EAAE,EAAA,EAAI,MAAA,EAAQ,IAAA,EAAK,GAAI,KAAA;AAC7B,EAAA,MAAM,IAAA,GAAO,gBAAgB,KAAK,CAAA;AAClC,EAAA,OAAO,OAAA,CAAQ,MAAM,IAAA,CAAK,iBAAA,CAAkB,EAAE,EAAA,EAAG,EAAG,MAAA,EAAQ,IAAI,GAAG,CAAC,IAAA,EAAM,EAAA,EAAI,MAAA,EAAQ,IAAI,CAAC,CAAA;AAC/F;AAEA,SAAS,eAAA,CAAgB,EAAE,IAAA,EAAK,EAAwB;AACpD,EAAA,OAAO,oBAAoB,MAAM;AAC7B,IAAA,IAAI,OAAO,SAAS,UAAA,EAAY;AAE5B,MAAA,OAAO,IAAA,EAAK;AAAA,IAChB;AACA,IAAA,OAAO,SAAS,IAAI,CAAA;AAAA,EACxB,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AACb;;;;"}
package/README.md CHANGED
@@ -43,6 +43,30 @@ Example:
43
43
  In the preceding example the topmost heading(s) in `TheRestOfYourApplication` start at level 2, and nested headings use increasing levels as usual.
44
44
  For more details, see the API documentation.
45
45
 
46
+ ### FormattedMessage
47
+
48
+ This package provides a few helper components to render formatted messages in a React tree:
49
+
50
+ ```tsx
51
+ import { FormattedMessage } from "@open-pioneer/react-utils";
52
+
53
+ <FormattedMessage intl={intl} id="message.id" />
54
+ <FormattedRichMessage intl={intl} id="message.id" />
55
+ ```
56
+
57
+ `intl` can be either a plain `PackageIntl` object, or a signal (`ReadonlyReactive<PackageIntl`>), or a reactive getter (e.g. `() => currentIntl.value`).
58
+
59
+ `FormattedMessage` and `FormattedRichMessage` support `values`, too:
60
+
61
+ ```tsx
62
+ // greeting: "Hello {name}"
63
+ <FormattedMessage intl={intl} id="greeting" values={{ name: "World" }} /> // -> Hello World
64
+ ```
65
+
66
+ When used from a plain react component, these components only offer minor additional utility.
67
+ Compared to direct calls of `intl.formatMessage`, they add a layer of caching (`useMemo`).
68
+ However, because they support reactive props for `intl`, they make it easy to compose reactive strings from non-react code.
69
+
46
70
  ### Roving menu
47
71
 
48
72
  The roving menu is a render-less component that can be used to implement an accessible menu with keyboard navigation.
package/index.d.ts CHANGED
@@ -5,6 +5,10 @@
5
5
  *
6
6
  * Implements automatic heading levels. Use {@link TitledSection} and {@link SectionHeading} instead of raw `h1`, `h2`, ... tags.
7
7
  *
8
+ * @groupDescription Formatting
9
+ *
10
+ * Formatting helpers.
11
+ *
8
12
  * @groupDescription Roving menu
9
13
  *
10
14
  * A (render-less) implementation of the roving tab index pattern.
@@ -16,6 +20,7 @@
16
20
  */
17
21
  export { useEvent } from "./useEvent";
18
22
  export { type TitledSectionProps, TitledSection, type SectionHeadingProps, SectionHeading, type ConfigureTitledSectionProps, ConfigureTitledSection, type HeadingLevel, useHeadingLevel } from "./TitledSection";
23
+ export { FormattedMessage, type FormattedMessageProps, FormattedRichMessage, type FormattedRichMessageProps, type FormattingBaseProps } from "./FormattedMessage";
19
24
  export { type CommonComponentProps, type CommonComponentContainerProps, useCommonComponentProps } from "./useCommonComponentProps";
20
25
  export { RovingMenuRoot, type RovingMenuRootProps } from "./roving-menu/RovingMenuRoot";
21
26
  export { useRovingMenu, type RovingMenuProps, type RovingMenuResult, useNestedRovingMenu, type NestedRovingMenuProps, type NestedRovingMenuResult } from "./roving-menu/useRovingMenu";
package/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  export { useEvent } from './useEvent.js';
2
2
  export { ConfigureTitledSection, SectionHeading, TitledSection, useHeadingLevel } from './TitledSection.js';
3
+ export { FormattedMessage, FormattedRichMessage } from './FormattedMessage.js';
3
4
  export { useCommonComponentProps } from './useCommonComponentProps.js';
4
5
  export { RovingMenuRoot } from './roving-menu/RovingMenuRoot.js';
5
6
  export { useNestedRovingMenu, useRovingMenu } from './roving-menu/useRovingMenu.js';
package/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}
1
+ {"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@open-pioneer/react-utils",
4
- "version": "4.6.0-dev.20260519125519",
4
+ "version": "4.6.0",
5
5
  "description": "Contains common react utilities used by the open pioneer trails project",
6
6
  "keywords": [
7
7
  "open-pioneer-trails"
@@ -17,8 +17,8 @@
17
17
  "@chakra-ui/react": "^3.35.0",
18
18
  "@conterra/reactivity-core": "^0.8.5",
19
19
  "react": "^19.2.6",
20
- "@open-pioneer/reactivity": "4.6.0-dev.20260519125519",
21
- "@open-pioneer/core": "4.6.0-dev.20260519125519"
20
+ "@open-pioneer/core": "4.6.0",
21
+ "@open-pioneer/reactivity": "4.6.0"
22
22
  },
23
23
  "exports": {
24
24
  "./package.json": "./package.json",