@open-pioneer/react-utils 4.5.0-dev.20260209115911 → 4.5.0-dev.20260211105402

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,18 +1,31 @@
1
1
  # @open-pioneer/react-utils
2
2
 
3
- ## 4.5.0-dev.20260209115911
3
+ ## 4.5.0-dev.20260211105402
4
4
 
5
5
  ### Minor Changes
6
6
 
7
7
  - 4e76893: Update Chakra UI to 3.32.0
8
+ - d523ade: Add more properties to the `CommonComponentProps` interface.
9
+ Previously, trails components only allowed customizing the `className`.
10
+
11
+ Now, these additional properties are supported:
12
+ - `role`: the ARIA role
13
+ - `aria-*`: arbitrary ARIA attributes
14
+ - `data-*`: arbitrary JavaScript values
15
+ - `css`: additional Chakra style rules
16
+
17
+ NOTE: Defining these values may overwrite existing behavior of a component if values cannot be merged.
18
+ For example, overriding an existing `data-` property may break a component.
19
+
20
+ - d523ade: Implement `mergeChakraProps` helper to merge multiple props objects.
8
21
  - 604a589: Provide an implementation of the roving tab index pattern for menus.
9
22
  This roving menu can be used to implement accessible menus with support for keyboard navigation.
10
23
 
11
24
  ### Patch Changes
12
25
 
13
26
  - Updated dependencies [4e76893]
14
- - @open-pioneer/core@4.5.0-dev.20260209115911
15
- - @open-pioneer/reactivity@4.5.0-dev.20260209115911
27
+ - @open-pioneer/core@4.5.0-dev.20260211105402
28
+ - @open-pioneer/reactivity@4.5.0-dev.20260211105402
16
29
 
17
30
  ## 4.4.0
18
31
 
package/index.d.ts CHANGED
@@ -16,8 +16,9 @@
16
16
  */
17
17
  export { useEvent } from "./useEvent";
18
18
  export { type TitledSectionProps, TitledSection, type SectionHeadingProps, SectionHeading, type ConfigureTitledSectionProps, ConfigureTitledSection, type HeadingLevel, useHeadingLevel } from "./TitledSection";
19
- export { type CommonComponentProps, useCommonComponentProps } from "./useCommonComponentProps";
19
+ export { type CommonComponentProps, type CommonComponentContainerProps, useCommonComponentProps } from "./useCommonComponentProps";
20
20
  export { RovingMenuRoot, type RovingMenuRootProps } from "./roving-menu/RovingMenuRoot";
21
21
  export { useRovingMenu, type RovingMenuProps, type RovingMenuResult } from "./roving-menu/useRovingMenu";
22
22
  export { useRovingMenuItem, type RovingMenuItemProps, type RovingMenuItemResult } from "./roving-menu/useRovingMenuItem";
23
23
  export { type RovingMenuState } from "./roving-menu/RovingMenuState";
24
+ export { mergeChakraProps } from "./mergeChakraProps";
package/index.js CHANGED
@@ -4,4 +4,5 @@ export { useCommonComponentProps } from './useCommonComponentProps.js';
4
4
  export { RovingMenuRoot } from './roving-menu/RovingMenuRoot.js';
5
5
  export { useRovingMenu } from './roving-menu/useRovingMenu.js';
6
6
  export { useRovingMenuItem } from './roving-menu/useRovingMenuItem.js';
7
+ export { mergeChakraProps } from './mergeChakraProps.js';
7
8
  //# sourceMappingURL=index.js.map
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":";;;;;;"}
@@ -0,0 +1,13 @@
1
+ import { SystemStyleObject } from "@chakra-ui/react";
2
+ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
3
+ /**
4
+ * Merges multiple `props` objects from left to right.
5
+ *
6
+ * This function works like Chakra's {@link mergeProps}, but has additional support for Chakra's `css` property.
7
+ * If multiple `css` objects are defined, their values are combined into an array.
8
+ * This way, multiple css rules may match and will not override each other.
9
+ */
10
+ export declare function mergeChakraProps<T extends {}>(...args: T[]): Omit<UnionToIntersection<T>, "css"> & {
11
+ css?: SystemStyleObject | SystemStyleObject[];
12
+ };
13
+ export {};
@@ -0,0 +1,36 @@
1
+ import { mergeProps } from '@chakra-ui/react';
2
+
3
+ function mergeChakraProps(...args) {
4
+ const mergedProps = mergeProps(...args);
5
+ let mergedCss;
6
+ for (const props of args) {
7
+ const localCss = props.css;
8
+ if (!localCss || typeof localCss !== "object") {
9
+ continue;
10
+ }
11
+ if (!mergedCss) {
12
+ if (Array.isArray(localCss)) {
13
+ mergedCss = [...localCss];
14
+ } else {
15
+ mergedCss = localCss;
16
+ }
17
+ } else if (!Array.isArray(mergedCss)) {
18
+ mergedCss = [mergedCss, ...wrap(localCss)];
19
+ } else {
20
+ mergedCss.push(...wrap(localCss));
21
+ }
22
+ }
23
+ if (mergedCss) {
24
+ mergedProps.css = mergedCss;
25
+ }
26
+ return mergedProps;
27
+ }
28
+ function wrap(v) {
29
+ if (Array.isArray(v)) {
30
+ return v;
31
+ }
32
+ return [v];
33
+ }
34
+
35
+ export { mergeChakraProps };
36
+ //# sourceMappingURL=mergeChakraProps.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mergeChakraProps.js","sources":["mergeChakraProps.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { mergeProps, SystemStyleObject } from \"@chakra-ui/react\";\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void\n ? I\n : never;\n\n/**\n * Merges multiple `props` objects from left to right.\n *\n * This function works like Chakra's {@link mergeProps}, but has additional support for Chakra's `css` property.\n * If multiple `css` objects are defined, their values are combined into an array.\n * This way, multiple css rules may match and will not override each other.\n */\nexport function mergeChakraProps<T extends {}>(\n ...args: T[]\n): Omit<UnionToIntersection<T>, \"css\"> & { css?: SystemStyleObject | SystemStyleObject[] } {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n const mergedProps = mergeProps(...args) as Record<string, any>;\n\n // mergeProps handles plain html attributes only; merge chakra css on our own.\n let mergedCss: SystemStyleObject | SystemStyleObject[] | undefined;\n for (const props of args) {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n const localCss = (props as any).css as SystemStyleObject | SystemStyleObject[] | undefined;\n if (!localCss || typeof localCss !== \"object\") {\n continue;\n }\n\n if (!mergedCss) {\n if (Array.isArray(localCss)) {\n mergedCss = [...localCss];\n } else {\n mergedCss = localCss;\n }\n } else if (!Array.isArray(mergedCss)) {\n mergedCss = [mergedCss, ...wrap(localCss)];\n } else {\n mergedCss.push(...wrap(localCss));\n }\n }\n if (mergedCss) {\n mergedProps.css = mergedCss;\n }\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n return mergedProps as any;\n}\n\nfunction wrap<T>(v: T | T[]): T[] {\n if (Array.isArray(v)) {\n return v;\n }\n return [v];\n}\n"],"names":[],"mappings":";;AAgBO,SAAS,oBACT,IAAA,EACoF;AAEvF,EAAA,MAAM,WAAA,GAAc,UAAA,CAAW,GAAG,IAAI,CAAA;AAGtC,EAAA,IAAI,SAAA;AACJ,EAAA,KAAA,MAAW,SAAS,IAAA,EAAM;AAEtB,IAAA,MAAM,WAAY,KAAA,CAAc,GAAA;AAChC,IAAA,IAAI,CAAC,QAAA,IAAY,OAAO,QAAA,KAAa,QAAA,EAAU;AAC3C,MAAA;AAAA,IACJ;AAEA,IAAA,IAAI,CAAC,SAAA,EAAW;AACZ,MAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,QAAQ,CAAA,EAAG;AACzB,QAAA,SAAA,GAAY,CAAC,GAAG,QAAQ,CAAA;AAAA,MAC5B,CAAA,MAAO;AACH,QAAA,SAAA,GAAY,QAAA;AAAA,MAChB;AAAA,IACJ,CAAA,MAAA,IAAW,CAAC,KAAA,CAAM,OAAA,CAAQ,SAAS,CAAA,EAAG;AAClC,MAAA,SAAA,GAAY,CAAC,SAAA,EAAW,GAAG,IAAA,CAAK,QAAQ,CAAC,CAAA;AAAA,IAC7C,CAAA,MAAO;AACH,MAAA,SAAA,CAAU,IAAA,CAAK,GAAG,IAAA,CAAK,QAAQ,CAAC,CAAA;AAAA,IACpC;AAAA,EACJ;AACA,EAAA,IAAI,SAAA,EAAW;AACX,IAAA,WAAA,CAAY,GAAA,GAAM,SAAA;AAAA,EACtB;AAEA,EAAA,OAAO,WAAA;AACX;AAEA,SAAS,KAAQ,CAAA,EAAiB;AAC9B,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAA,EAAG;AAClB,IAAA,OAAO,CAAA;AAAA,EACX;AACA,EAAA,OAAO,CAAC,CAAC,CAAA;AACb;;;;"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@open-pioneer/react-utils",
4
- "version": "4.5.0-dev.20260209115911",
4
+ "version": "4.5.0-dev.20260211105402",
5
5
  "description": "Contains common react utilities used by the open pioneer trails project",
6
6
  "keywords": [
7
7
  "open-pioneer-trails"
@@ -18,8 +18,8 @@
18
18
  "@conterra/reactivity-core": "^0.8.1",
19
19
  "classnames": "^2.5.1",
20
20
  "react": "^19.2.4",
21
- "@open-pioneer/core": "4.5.0-dev.20260209115911",
22
- "@open-pioneer/reactivity": "4.5.0-dev.20260209115911"
21
+ "@open-pioneer/core": "4.5.0-dev.20260211105402",
22
+ "@open-pioneer/reactivity": "4.5.0-dev.20260211105402"
23
23
  },
24
24
  "exports": {
25
25
  "./package.json": "./package.json",
@@ -1,18 +1,49 @@
1
- import { HTMLAttributes } from "react";
1
+ import { SystemStyleObject } from "@chakra-ui/react";
2
+ import { HTMLAttributes, AriaAttributes, AriaRole } from "react";
2
3
  /**
3
4
  * Common properties supported by all public react components.
4
5
  *
6
+ * This type allows for the customization of
7
+ * - the css `className`
8
+ * - a Chakra `css` property
9
+ * - "role" and `aria-*` properties
10
+ * - arbitrary `data-*` properties
11
+ *
12
+ * Prop types for react components typically inherit from this interface.
13
+ *
5
14
  * @group Common component props
6
15
  */
7
- export interface CommonComponentProps {
16
+ export interface CommonComponentProps extends AriaAttributes {
8
17
  /**
9
18
  * Additional class name(s).
10
19
  */
11
- "className"?: string;
20
+ className?: string;
21
+ /**
22
+ * Custom style rules using Chakra's style objects.
23
+ */
24
+ css?: SystemStyleObject | SystemStyleObject[];
25
+ /**
26
+ * Custom ARIA role.
27
+ */
28
+ role?: AriaRole;
12
29
  /**
13
30
  * Used for testing.
14
31
  */
15
32
  "data-testid"?: string;
33
+ /**
34
+ * Arbitrary data attributes.
35
+ *
36
+ * NOTE: The component may use data properties for its own behavior.
37
+ * Make sure not to overwrite required attributes.
38
+ */
39
+ [key: `data-${string}`]: unknown;
40
+ }
41
+ /**
42
+ * @group Common component props
43
+ */
44
+ export interface CommonComponentContainerProps extends Pick<HTMLAttributes<HTMLElement>, "className" | "role">, AriaAttributes {
45
+ css?: SystemStyleObject | SystemStyleObject[];
46
+ [key: `data-${string}`]: unknown;
16
47
  }
17
48
  /**
18
49
  * A helper hook that computes react properties for the topmost container in a public react component.
@@ -31,5 +62,5 @@ export interface CommonComponentProps {
31
62
  * @expandType CommonComponentProps
32
63
  */
33
64
  export declare function useCommonComponentProps(componentClassName: string, props: CommonComponentProps): {
34
- containerProps: HTMLAttributes<HTMLElement>;
65
+ containerProps: CommonComponentContainerProps;
35
66
  };
@@ -1,13 +1,29 @@
1
1
  import classNames from 'classnames';
2
+ import { useMemo } from 'react';
2
3
 
4
+ const COPY_PROP_RE = /^(data|aria)-/;
3
5
  function useCommonComponentProps(componentClassName, props) {
4
- const containerProps = {
5
- "className": classNames(componentClassName, props.className),
6
- "data-testid": props["data-testid"]
7
- };
8
- return {
9
- containerProps
10
- };
6
+ const result = useMemo(() => {
7
+ const containerProps = {
8
+ className: classNames(componentClassName, props.className)
9
+ };
10
+ if (props.role) {
11
+ containerProps.role = props.role;
12
+ }
13
+ if (props.css) {
14
+ containerProps.css = props.css;
15
+ }
16
+ for (const k in props) {
17
+ if (!Object.hasOwn(props, k)) {
18
+ continue;
19
+ }
20
+ if (COPY_PROP_RE.test(k)) {
21
+ containerProps[k] = props[k];
22
+ }
23
+ }
24
+ return { containerProps };
25
+ }, [componentClassName, props]);
26
+ return result;
11
27
  }
12
28
 
13
29
  export { useCommonComponentProps };
@@ -1 +1 @@
1
- {"version":3,"file":"useCommonComponentProps.js","sources":["useCommonComponentProps.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport classNames from \"classnames\";\nimport { HTMLAttributes } from \"react\";\n\n/**\n * Common properties supported by all public react components.\n *\n * @group Common component props\n */\nexport interface CommonComponentProps {\n /**\n * Additional class name(s).\n */\n \"className\"?: string;\n\n /**\n * Used for testing.\n */\n \"data-testid\"?: string;\n}\n\n/**\n * A helper hook that computes react properties for the topmost container in a public react component.\n *\n * Example:\n *\n * ```jsx\n * function MyComponent(props) {\n * const { containerProps } = useCommonComponentProps(\"my-component\", props);\n * // automatically applies css classes and testid\n * return <Box {...containerProps}>Content</Box>;\n * }\n * ```\n *\n * @group Common component props\n * @expandType CommonComponentProps\n */\nexport function useCommonComponentProps(\n componentClassName: string,\n props: CommonComponentProps\n): { containerProps: HTMLAttributes<HTMLElement> } {\n const containerProps = {\n \"className\": classNames(componentClassName, props.className),\n \"data-testid\": props[\"data-testid\"]\n };\n return {\n containerProps\n };\n}\n"],"names":[],"mappings":";;AAsCO,SAAS,uBAAA,CACZ,oBACA,KAAA,EAC+C;AAC/C,EAAA,MAAM,cAAA,GAAiB;AAAA,IACnB,WAAA,EAAa,UAAA,CAAW,kBAAA,EAAoB,KAAA,CAAM,SAAS,CAAA;AAAA,IAC3D,aAAA,EAAe,MAAM,aAAa;AAAA,GACtC;AACA,EAAA,OAAO;AAAA,IACH;AAAA,GACJ;AACJ;;;;"}
1
+ {"version":3,"file":"useCommonComponentProps.js","sources":["useCommonComponentProps.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { SystemStyleObject } from \"@chakra-ui/react\";\nimport classNames from \"classnames\";\nimport { HTMLAttributes, AriaAttributes, useMemo, AriaRole } from \"react\";\n\n/**\n * Common properties supported by all public react components.\n *\n * This type allows for the customization of\n * - the css `className`\n * - a Chakra `css` property\n * - \"role\" and `aria-*` properties\n * - arbitrary `data-*` properties\n *\n * Prop types for react components typically inherit from this interface.\n *\n * @group Common component props\n */\nexport interface CommonComponentProps extends AriaAttributes {\n /**\n * Additional class name(s).\n */\n className?: string;\n\n /**\n * Custom style rules using Chakra's style objects.\n */\n css?: SystemStyleObject | SystemStyleObject[];\n\n /**\n * Custom ARIA role.\n */\n role?: AriaRole;\n\n /**\n * Used for testing.\n */\n \"data-testid\"?: string;\n\n /**\n * Arbitrary data attributes.\n *\n * NOTE: The component may use data properties for its own behavior.\n * Make sure not to overwrite required attributes.\n */\n [key: `data-${string}`]: unknown;\n}\n\nconst COPY_PROP_RE = /^(data|aria)-/;\n\n/**\n * @group Common component props\n */\nexport interface CommonComponentContainerProps\n extends Pick<HTMLAttributes<HTMLElement>, \"className\" | \"role\">, AriaAttributes {\n css?: SystemStyleObject | SystemStyleObject[];\n [key: `data-${string}`]: unknown;\n}\n\n/**\n * A helper hook that computes react properties for the topmost container in a public react component.\n *\n * Example:\n *\n * ```jsx\n * function MyComponent(props) {\n * const { containerProps } = useCommonComponentProps(\"my-component\", props);\n * // automatically applies css classes and testid\n * return <Box {...containerProps}>Content</Box>;\n * }\n * ```\n *\n * @group Common component props\n * @expandType CommonComponentProps\n */\nexport function useCommonComponentProps(\n componentClassName: string,\n props: CommonComponentProps\n): { containerProps: CommonComponentContainerProps } {\n const result = useMemo(() => {\n const containerProps: Record<string, unknown> = {\n className: classNames(componentClassName, props.className)\n };\n if (props.role) {\n containerProps.role = props.role;\n }\n if (props.css) {\n containerProps.css = props.css;\n }\n for (const k in props) {\n if (!Object.hasOwn(props, k)) {\n continue;\n }\n if (COPY_PROP_RE.test(k)) {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n containerProps[k] = (props as any)[k];\n }\n }\n return { containerProps };\n }, [componentClassName, props]);\n return result;\n}\n"],"names":[],"mappings":";;;AAiDA,MAAM,YAAA,GAAe,eAAA;AA2Bd,SAAS,uBAAA,CACZ,oBACA,KAAA,EACiD;AACjD,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAM;AACzB,IAAA,MAAM,cAAA,GAA0C;AAAA,MAC5C,SAAA,EAAW,UAAA,CAAW,kBAAA,EAAoB,KAAA,CAAM,SAAS;AAAA,KAC7D;AACA,IAAA,IAAI,MAAM,IAAA,EAAM;AACZ,MAAA,cAAA,CAAe,OAAO,KAAA,CAAM,IAAA;AAAA,IAChC;AACA,IAAA,IAAI,MAAM,GAAA,EAAK;AACX,MAAA,cAAA,CAAe,MAAM,KAAA,CAAM,GAAA;AAAA,IAC/B;AACA,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACnB,MAAA,IAAI,CAAC,MAAA,CAAO,MAAA,CAAO,KAAA,EAAO,CAAC,CAAA,EAAG;AAC1B,QAAA;AAAA,MACJ;AACA,MAAA,IAAI,YAAA,CAAa,IAAA,CAAK,CAAC,CAAA,EAAG;AAEtB,QAAA,cAAA,CAAe,CAAC,CAAA,GAAK,KAAA,CAAc,CAAC,CAAA;AAAA,MACxC;AAAA,IACJ;AACA,IAAA,OAAO,EAAE,cAAA,EAAe;AAAA,EAC5B,CAAA,EAAG,CAAC,kBAAA,EAAoB,KAAK,CAAC,CAAA;AAC9B,EAAA,OAAO,MAAA;AACX;;;;"}