@open-pioneer/react-utils v0.2.2
@open-pioneer/react-utils
This package provides React utilities that help a developer create applications.
Titled sections
Use the <TitledSection>
and <SectionHeading>
components instead of raw hX
HTML tags (such as <h1>
or <h2>
).
This way, the appropriate heading level is determined automatically.
Example:
import { TitledSection, SectionHeading } from "@open-pioneer/react-utils";
function SomeComponent(props) {
return (
{/* Renders as h1 if this is the topmost section.
Title strings are automatically wrapped into `SectionHeading`. */}
<TitledSection title="Root Title">
... Some content ...
{/* Custom react component as title. Renders as the next level (h2). */}
<TitledSection title={<SectionHeading size="4xl">Sub Title</SectionHeading>}>
... More content ...
</TitledSection>
</TitledSection>
);
}
To override the automatic heading level, use the ConfigureTitledSection
component.
This can be used for example to override the initial heading level or to force a certain level when the React tree differs from the DOM tree.
Example:
<ConfigureTitledSection level={2}>
<TheRestOfYourApplication />
</ConfigureTitledSection>
In the preceding example the topmost heading(s) in TheRestOfYourApplication
start at level 2, and nested headings use increasing levels as usual.
For more details, see the API documentation.
Tool buttons
To create a simple icon button with a tooltip and an aria-label
, use the ToolButton
component as in the following sample:
<ToolButton label={someLabel} icon={<SomeIcon />} onClick={someEventHandler} />
This is used, for example, to add an icon button to the map.
Hooks
useCommonComponentProps()
A helper hook that automatically computes containerProps
: common properties to set on the topmost container element of a public component.
For the time being, these properties are className
(combined component class and optional additional class names) and data-testid
(for tests).
Example:
// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)
// SPDX-License-Identifier: Apache-2.0
import { CommonComponentProps, useCommonComponentProps } from "@open-pioneer/react-utils";
// ...
// Inherit from CommonComponentProps
export interface InitialExtentProps extends CommonComponentProps {
mapId: string;
}
export const InitialExtent: FC<InitialExtentProps> = forwardRef(function InitialExtent(
props: InitialExtentProps,
ref: ForwardedRef<HTMLDivElement>
) {
const { mapId } = props;
// Use the hook to compute container props (classNames, data-testid, maybe more in the future)
const { containerProps } = useCommonComponentProps("initial-extent", props);
// Pass containerProps directly to the container
return <Box {...containerProps}>{/* ... */}</Box>;
});
useEvent()
The useEvent
can be used to obtain a stable event handler function with changing implementation.
This is useful to avoid re-triggering useEffect
-hooks when only the event handler changed.
Example:
import { useEvent } from "@open-pioneer/react-utils";
function someReactComponent(props) {
// NOTE: logMessage() must not be called during rendering!
const logMessage = useEvent((message: string) => {
console.log(message, props.someProperty);
});
const someService = ...; // injected
// Changes of prop.someProperty will not cause the effect to re-fire, because the function identity
// of `logMessage` remains stable.
useEffect(() => {
const handle = someService.registerHandler(logMessage);
return () => handle.destroy();
}, [someService, logMessage]);
}
For more details, see the API docs of useEvent
or https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md.
License
Apache-2.0 (see LICENSE
file)