Implement FMGroup tag

package.json

@@ -55,7 +55,7 @@
     "url": "https://github.com/flexmonster/react"
   },
   "peerDependencies": {
-    "@flexmonster/js": "3.0.0-preview.3.1",
+    "@flexmonster/js": "3.0.0-preview.5.1",
     "next": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"

src/FMFilter.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { Filter, type IFMFilter, type IFilterOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMFilterRef extends IFMFilter {
 }
@@ -12,7 +13,10 @@ export interface FMFilterProps {
     options?: IFilterOptionsInputParams;
 }
 
-const FMFilter = forwardRef<FMFilterRef, FMFilterProps>(({ state, options, fieldName }, ref) => {
+const FMFilter = forwardRef<FMFilterRef, FMFilterProps>(({ state: ownState, options, fieldName }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-filter-${useId()}`;
     const filterRef = useRef<IFMFilter | null>(null);
 

src/FMFlatFieldList.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { FlatFieldList, type IFMFlatFieldList, type IFMFlatFieldListOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMFlatFieldListRef extends IFMFlatFieldList {
 }
@@ -11,7 +12,10 @@ export interface FMFlatFieldListProps {
   options?: IFMFlatFieldListOptionsInputParams;
 }
 
-const FMFlatFieldList = forwardRef<FMFlatFieldListRef, FMFlatFieldListProps>(({ state, options }, ref) => {
+const FMFlatFieldList = forwardRef<FMFlatFieldListRef, FMFlatFieldListProps>(({ state: ownState, options }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-flat-field-list-${useId()}`;
     const flatFieldListRef = useRef<IFMFlatFieldList | null>(null);
 

src/FMFlatTable.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { FlatTable, type IFMFlatTable, type IFMFlatTableOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMFlatTableRef extends IFMFlatTable {
 }
@@ -12,7 +13,10 @@ export interface FMFlatTableProps {
   name?: string;
 }
 
-const FMFlatTable = forwardRef<FMFlatTableRef, FMFlatTableProps>(({ state, options, name }, ref) => {
+const FMFlatTable = forwardRef<FMFlatTableRef, FMFlatTableProps>(({ state: ownState, options, name }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-flat-table-${useId()}`;
     const flatTableRef = useRef<IFMFlatTable | null>(null);
 

src/FMFlexmonster.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { Flexmonster, IFMFlexmonsterInputParams, type IFMFlexmonster, type IFMFlexmonsterOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMFlexmonsterRef extends IFMFlexmonster {
 }
@@ -11,7 +12,10 @@ export interface FMFlexmonsterProps extends IFMFlexmonsterInputParams {
   options?: IFMFlexmonsterOptionsInputParams;
 }
 
-const FMFlexmonster = forwardRef<FMFlexmonsterRef, FMFlexmonsterProps>(({ state, options }, ref) => {
+const FMFlexmonster = forwardRef<FMFlexmonsterRef, FMFlexmonsterProps>(({ state: ownState, options }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-flexmonster-${useId()}`;
     const flexmonsterRef = useRef<IFMFlexmonster | null>(null);
 

src/FMGroup.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import React from 'react';
+import type { StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
+
+export interface FMGroupProps {
+    state?: StateInputParams;
+    children?: React.ReactNode;
+}
+
+const FMGroup: React.FC<FMGroupProps> = ({ state, children }) => (
+    <FMStateContext.Provider value={state}>{children}</FMStateContext.Provider>
+);
+
+FMGroup.displayName = 'FMGroup';
+
+export default FMGroup;

src/FMPivotFieldList.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { PivotFieldList, type IFMPivotFieldList, type IFMPivotFieldListOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMPivotFieldListRef extends IFMPivotFieldList {
 }
@@ -11,7 +12,10 @@ export interface FMPivotFieldListProps {
   options?: IFMPivotFieldListOptionsInputParams;
 }
 
-const FMPivotFieldList = forwardRef<FMPivotFieldListRef, FMPivotFieldListProps>(({ state, options }, ref) => {
+const FMPivotFieldList = forwardRef<FMPivotFieldListRef, FMPivotFieldListProps>(({ state: ownState, options }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-pivot-field-list-${useId()}`;
     const pivotFieldListRef = useRef<IFMPivotFieldList | null>(null);
 

src/FMPivotTable.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { PivotTable, type IFMPivotTable, type IFMPivotTableOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMPivotTableRef extends IFMPivotTable {
 }
@@ -12,7 +13,10 @@ export interface FMPivotTableProps {
   name?: string;
 }
 
-const FMPivotTable = forwardRef<FMPivotTableRef, FMPivotTableProps>(({ state, options, name }, ref) => {
+const FMPivotTable = forwardRef<FMPivotTableRef, FMPivotTableProps>(({ state: ownState, options, name }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-pivot-table-${useId()}`;
     const pivotTableRef = useRef<IFMPivotTable | null>(null);
 

src/FMStateContext.ts

@@ -0,0 +1,10 @@
+"use client";
+
+import React from 'react';
+import type { StateInputParams } from '@flexmonster/js';
+
+/**
+ * Carries the state shared by an <FMGroup> to every Flexmonster component
+ * rendered inside it, no matter how deeply it is nested.
+ */
+export const FMStateContext = React.createContext<StateInputParams | undefined>(undefined);

src/FMToolbar.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
+import React, { useContext, useEffect, useId, useRef, forwardRef, useImperativeHandle } from 'react';
 import { Toolbar, type IFMToolbar, type IFMToolbarOptionsInputParams, type StateInputParams } from '@flexmonster/js';
+import { FMStateContext } from './FMStateContext';
 
 export interface FMToolbarRef extends IFMToolbar {
 }
@@ -12,7 +13,10 @@ export interface FMToolbarProps {
   for?: string;
 }
 
-const FMToolbar = forwardRef<FMToolbarRef, FMToolbarProps>(({ state, options, for: forControl }, ref) => {
+const FMToolbar = forwardRef<FMToolbarRef, FMToolbarProps>(({ state: ownState, options, for: forControl }, ref) => {
+    const groupState = useContext(FMStateContext);
+    const state = ownState ?? groupState;
+
     const containerId = `fm-toolbar-${useId()}`;
     const toolbarRef = useRef<IFMToolbar | null>(null);
 

src/index.ts

@@ -5,3 +5,4 @@ export { default as FMPivotFieldList, type FMPivotFieldListRef, type FMPivotFiel
 export { default as FMFlatFieldList, type FMFlatFieldListRef, type FMFlatFieldListProps } from './FMFlatFieldList';
 export { default as FMToolbar, type FMToolbarRef, type FMToolbarProps } from './FMToolbar';
 export { default as FMFilter, type FMFilterRef, type FMFilterProps } from './FMFilter';
+export { default as FMGroup, type FMGroupProps } from './FMGroup';

src/next/FMGroup.ts

@@ -0,0 +1,12 @@
+"use client";
+
+import type React from "react";
+import dynamic from "next/dynamic";
+import type { FMGroupProps } from "@flexmonster/react";
+
+const FMGroup = dynamic(
+  () => import("@flexmonster/react").then((mod) => mod.FMGroup),
+  { ssr: false }
+) as React.FC<FMGroupProps>;
+
+export default FMGroup;

src/next/index.ts

@@ -5,3 +5,4 @@ export { default as FMPivotFieldList } from './FMPivotFieldList';
 export { default as FMFlatFieldList } from './FMFlatFieldList';
 export { default as FMToolbar } from './FMToolbar';
 export { default as FMFilter } from './FMFilter';
+export { default as FMGroup } from './FMGroup';