arome · Oct 2, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -13,5 +13,27 @@
   "search.exclude": {
     "**/CHANGELOG.md": true
   },
-  "js/ts.preferences.autoImportSpecifierExcludeRegexes": ["^@mui/[^/]+$"]
+  "js/ts.preferences.autoImportSpecifierExcludeRegexes": ["^@mui/[^/]+$"],
+  "jest.virtualFolders": [
+    {
+      "name": "create-imodel",
+      "rootPath": "packages/modules/create-imodel"
+    },
+    {
+      "name": "delete-imodel",
+      "rootPath": "packages/modules/delete-imodel"
+    },
+    {
+      "name": "delete-itwin",
+      "rootPath": "packages/modules/delete-itwin"
+    },
+    {
+      "name": "imodel-browser",
+      "rootPath": "packages/modules/imodel-browser"
+    },
+    {
+      "name": "manage-versions",
+      "rootPath": "packages/modules/manage-versions"
+    }
+  ]
 }
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodel-browser-react",
+      "comment": "Controlled table sorting for iTwin/iModel grids",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodel-browser-react"
+}
@@ -7,7 +7,6 @@ import Avatar from "@mui/material/Avatar";
 import AvatarGroup from "@mui/material/AvatarGroup";
 import Box from "@mui/material/Box";
 import Chip from "@mui/material/Chip";
-import { action } from "storybook/actions";
 import type { Meta, StoryObj } from "@storybook/react-webpack5";
 import svgGeo from "@stratakit/icons/geospatial-features.svg";
 import svgPin from "@stratakit/icons/pin.svg";
@@ -16,6 +15,7 @@ import svgStatusError from "@stratakit/icons/status-error.svg";
 import svgStatusSuccess from "@stratakit/icons/status-success.svg";
 import svgStatusWarning from "@stratakit/icons/status-warning.svg";
 import React from "react";
+import { action } from "storybook/actions";
 
 import {
   BaseCard,
@@ -255,7 +255,11 @@ export const OpenSitePlus: StoryObj<typeof BaseCardStory> = {
         icon: svgGeo,
       },
       { key: "share", label: "Share", onClick: action("menu: share clicked") },
-      { key: "delete", label: "Delete", onClick: action("menu: delete clicked") },
+      {
+        key: "delete",
+        label: "Delete",
+        onClick: action("menu: delete clicked"),
+      },
     ],
     actions: [
       {

@@ -5,6 +5,7 @@
 import {
   type IModelFull,
   type IModelGridProps as IModelGridMUIProps,
+  type IModelSortOptionsMUI,
   DataStatus,
   IModelCellColumn,
   IModelGrid as ExternalComponent,
@@ -69,7 +70,6 @@ export default {
 
 const baseArgs: IModelGridMUIProps = {
   apiOverrides: { serverEnvironmentPrefix: "qa" },
-  sortOptions: { sortType: "name", descending: false },
   actions: [
     {
       key: "open",
@@ -91,6 +91,7 @@ const baseArgs: IModelGridMUIProps = {
       onClick: (iModel) => action("Details for " + iModel?.displayName)(iModel),
     },
   ],
+  onSortOptionsChange: undefined,
 };
 
 export const Primary: StoryObj<typeof IModelGridMUI> = {
@@ -153,6 +154,91 @@ export const TableViewWithOverrides: StoryObj<typeof IModelGridMUI> = {
   },
 };
 
+const TableWithControlledSortRender = (args: IModelGridMUIProps) => {
+  const [sortOptions, setSortOptions] = React.useState<
+    IModelSortOptionsMUI | undefined
+  >({ field: "name", direction: "desc" });
+  const field = sortOptions?.field;
+  const direction = sortOptions?.direction ?? "asc";
+
+  return (
+    <div>
+      <div
+        style={{
+          display: "flex",
+          gap: 8,
+          marginBottom: 8,
+          alignItems: "center",
+        }}
+      >
+        <Typography variant="body2">Sort by:</Typography>
+        <Chip
+          label="Name"
+          clickable
+          variant={field === "name" ? "filled" : "outlined"}
+          onClick={() => setSortOptions({ field: "name", direction })}
+        />
+        <Chip
+          label="Last Modified"
+          clickable
+          variant={
+            field === "lastChangesetPushDateTime" ? "filled" : "outlined"
+          }
+          onClick={() =>
+            setSortOptions({ field: "lastChangesetPushDateTime", direction })
+          }
+        />
+        <Chip
+          label="Created Date"
+          clickable
+          variant={field === "createdDateTime" ? "filled" : "outlined"}
+          onClick={() =>
+            setSortOptions({ field: "createdDateTime", direction })
+          }
+        />
+        <Chip
+          label={direction === "desc" ? "↓ Descending" : "↑ Ascending"}
+          clickable
+          variant="outlined"
+          onClick={() =>
+            setSortOptions(
+              (prev) =>
+                prev && {
+                  ...prev,
+                  direction: prev.direction === "desc" ? "asc" : "desc",
+                }
+            )
+          }
+        />
+      </div>
+      <ExternalComponent
+        {...args}
+        sortOptions={sortOptions}
+        onSortOptionsChange={(newSortOptions) => {
+          action("sort options changed")(newSortOptions);
+          setSortOptions(newSortOptions);
+        }}
+      />
+    </div>
+  );
+};
+
+export const TableWithControlledSort: StoryObj<typeof IModelGridMUI> = {
+  render: (args) => <TableWithControlledSortRender {...args} />,
+  args: {
+    ...baseArgs,
+    viewMode: "cells",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The sort state is fully controlled by the parent via `sortOptions` and `onSortOptionsChange`, so it can be saved anywhere the consumer wants.",
+      },
+    },
+  },
+};
+
 const OverrideApiDataWithLoadMoreRender = (args: IModelGridMUIProps) => {
   const [data, setData] = React.useState<IModelFull[]>(initialData);
   const [isLoading, setIsLoading] = React.useState(false);

@@ -11,12 +11,12 @@ import Avatar from "@mui/material/Avatar";
 import AvatarGroup from "@mui/material/AvatarGroup";
 import Box from "@mui/material/Box";
 import Chip from "@mui/material/Chip";
-import { action } from "storybook/actions";
 import type { Meta, StoryObj } from "@storybook/react-webpack5";
 import SvgDelete from "@stratakit/icons/delete.svg";
 import svgRoad from "@stratakit/icons/road.svg";
 import SvgShare from "@stratakit/icons/share.svg";
 import React from "react";
+import { action } from "storybook/actions";
 
 import bridgeThumbnail from "../../utils/bridge.jpg";
 import overpassThumbnail from "../../utils/overpass.jpg";

@@ -8,6 +8,7 @@ import {
   type ITwinDataState,
   type ITwinFull,
   type ITwinGridProps,
+  type ITwinSortOptionsMUI,
   DataStatus,
   ITwinCellColumn,
   ITwinGrid as ExternalComponent,
@@ -47,6 +48,7 @@ const baseArgs: ITwinGridProps = {
       onClick: (iTwin) => action("Open " + iTwin.displayName)(iTwin),
     },
   ],
+  onSortOptionsChange: undefined,
 };
 
 export const Primary: StoryObj<typeof ITwinGrid> = {
@@ -120,6 +122,84 @@ export const TableViewWithOverrides: StoryObj<typeof ITwinGrid> = {
   },
 };
 
+const TableWithControlledSortRender = (args: ITwinGridProps) => {
+  const [sortOptions, setSortOptions] = React.useState<
+    ITwinSortOptionsMUI | undefined
+  >({ field: "number", direction: "desc" });
+  const field = sortOptions?.field;
+  const direction = sortOptions?.direction ?? "asc";
+
+  return (
+    <div>
+      <div
+        style={{
+          display: "flex",
+          gap: 8,
+          marginBottom: 8,
+          alignItems: "center",
+        }}
+      >
+        <Typography variant="body2">Sort by:</Typography>
+        <Chip
+          label="iTwin Number"
+          clickable
+          variant={field === "number" ? "filled" : "outlined"}
+          onClick={() => setSortOptions({ field: "number", direction })}
+        />
+        <Chip
+          label="iTwin Name"
+          clickable
+          variant={field === "displayName" ? "filled" : "outlined"}
+          onClick={() => setSortOptions({ field: "displayName", direction })}
+        />
+        <Chip
+          label="Last Modified"
+          clickable
+          variant={field === "lastModifiedDateTime" ? "filled" : "outlined"}
+          onClick={() =>
+            setSortOptions({ field: "lastModifiedDateTime", direction })
+          }
+        />
+        <Chip
+          label={direction === "desc" ? "↓ Descending" : "↑ Ascending"}
+          clickable
+          variant="outlined"
+          onClick={() =>
+            setSortOptions(
+              (prev) =>
+                prev && {
+                  ...prev,
+                  direction: prev.direction === "desc" ? "asc" : "desc",
+                }
+            )
+          }
+        />
+      </div>
+      <ExternalComponent
+        {...args}
+        sortOptions={sortOptions}
+        onSortOptionsChange={(newSortOptions) => {
+          action("sort options changed")(newSortOptions);
+          setSortOptions(newSortOptions);
+        }}
+      />
+    </div>
+  );
+};
+
+export const TableWithControlledSort: StoryObj<typeof ITwinGrid> = {
+  render: (args) => <TableWithControlledSortRender {...args} />,
+  args: { ...baseArgs, viewMode: "cells" },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The sort state is fully controlled by the parent via `sortOptions` and `onSortOptionsChange`, so it can be saved anywhere the consumer wants.",
+      },
+    },
+  },
+};
+
 export const OverrideApiData: StoryObj<typeof ITwinGrid> = {
   args: {
     ...baseArgs,

@@ -10,10 +10,10 @@ import {
 import { SvgThumbnail } from "@itwin/imodel-browser-react/mui";
 import Box from "@mui/material/Box";
 import Chip from "@mui/material/Chip";
-import { action } from "storybook/actions";
 import type { Meta, StoryObj } from "@storybook/react-webpack5";
 import svgMagnet from "@stratakit/icons/magnet.svg";
 import React from "react";
+import { action } from "storybook/actions";
 
 import { DefaultThumbnail } from "../../../../../modules/imodel-browser/src/mui/containers/ITwinGrid/ITwinTileMUI";
 import bridgeThumbnail from "../../utils/bridge.jpg";

@@ -14,6 +14,7 @@ module.exports = {
     ],
   },
   transformIgnorePatterns: [
+    "<rootDir>/scripts/setupJest\\.js$",
     "node_modules/(?!(\\.pnpm/(@stratakit|@ariakit|@mui).*|@bentley/ui|@stratakit|@ariakit|@mui))",
     "^.+\\.module\\.(css|sass|scss)$",
   ],

@@ -96,11 +96,11 @@ export interface IModelGridProps {
     fetchStatus: DataStatus | undefined,
     searchText: string | undefined
   ) => IModelFull[];
-  /**Component to show when there is no iModel */
+  /** Component to show when there is no iModel */
   emptyStateComponent?: React.ReactNode;
-  /**  Exact name of the iModel to display */
+  /** Exact name of the iModel to display */
   searchText?: string;
-  /**iModel view mode */
+  /** iModel view mode */
   viewMode?: ViewType;
   /** The maximum number of iModels that can be fetched per request */
   pageSize?: number;
@@ -226,7 +226,12 @@ const IModelGridInternal = ({
   const [sort, setSort] = React.useState<IModelSortOptions>(sortOptions);
 
   React.useEffect(() => {
-    setSort(calculateSort(viewMode, sortOptions));
+    setSort(
+      calculateSort(viewMode, {
+        descending: sortOptions.descending,
+        sortType: sortOptions.sortType,
+      })
+    );
   }, [sortOptions.descending, sortOptions.sortType, viewMode]);
 
   const strings = generateStrings(requestType, stringsOverrides);