@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 +12 -1
- package/FormattedMessage.d.ts +76 -0
- package/FormattedMessage.js +28 -0
- package/FormattedMessage.js.map +1 -0
- package/README.md +24 -0
- package/index.d.ts +5 -0
- package/index.js +1 -0
- package/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
# @open-pioneer/react-utils
|
|
2
2
|
|
|
3
|
-
## 4.6.0
|
|
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
|
|
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/
|
|
21
|
-
"@open-pioneer/
|
|
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",
|