feat: add createExternalStore utility and ClockProvider

package.json

@@ -10,6 +10,9 @@
     "test": "jest"
   },
   "license": "APACHE 2.0",
+  "dependencies": {
+    "use-sync-external-store": "^1.2.0"
+  },
   "devDependencies": {
     "@babel/core": "^7.17.8",
     "@babel/plugin-proposal-class-properties": "^7.16.7",
@@ -37,6 +40,8 @@
     "dropzone": "5.7.2",
     "enzyme": "^3.11.0",
     "enzyme-adapter-react-16": "^1.15.6",
+    "@testing-library/react": "^12.1.5",
+    "@testing-library/jest-dom": "^5.16.5",
     "extend": "^3.0.1",
     "file-loader": "^6.2.0",
     "final-form": "^4.20.7",

readme.md

@@ -18,5 +18,9 @@ import 'sweetalert2/dist/sweetalert2.css';
 1 - yarn build && yarn publish
 
 
+## React compatibility
+
+`createExternalStore` (and the clock context built on it) uses the `use-sync-external-store` shim for React 16/17 compatibility. When React is upgraded to 18+, replace the shim with the native import from `react` and remove the `use-sync-external-store` dependency from package.json.
+
 ## Troubleshoot
 For Python 3.13 and above, yarn install will not work until you install this lib: sudo apt install python3-setuptools

src/components/clock-context.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Pre-built clock store using createExternalStore.
+ *
+ * Wires the Clock component (server-synced, ticks every second) into a
+ * createExternalStore instance. Components choose their update strategy:
+ *
+ *   - useClock() re-renders every second (for countdowns, live displays)
+ *   - useClockSelector(compute) only re-renders when the computed result changes
+ *   - Components that use neither are never affected by clock ticks
+ *
+ * Usage:
+ *   import { ClockProvider, useClock, useClockSelector } from 'openstack-uicore-foundation/lib/components/clock-context';
+ *
+ *   <ClockProvider timezone={summit.time_zone_id}>
+ *     <App />
+ *   </ClockProvider>
+ *
+ *   const nowUtc = useClock();
+ *
+ *   const phase = useClockSelector((nowUtc) => {
+ *     if (nowUtc < event.start) return 'before';
+ *     if (nowUtc <= event.end) return 'during';
+ *     return 'after';
+ *   });
+ *
+ * For custom (non-clock) stores, see createExternalStore in utils/external-store.js.
+ **/
+
+import React from 'react';
+import { createExternalStore } from '../utils/external-store';
+import Clock from './clock';
+
+const { Provider, useValue: useClock, useSelector: useClockSelector } = createExternalStore('Clock');
+
+/**
+ * ClockProvider - Wraps your app with server-synced clock context.
+ *
+ * @param {string} timezone - Timezone for the clock (e.g., "America/New_York")
+ * @param {number} now - Optional initial timestamp (for testing or manual override)
+ * @param {React.ReactNode} children - Child components
+ */
+export const ClockProvider = ({ timezone, now, children }) => (
+    <Provider>
+        {(emit) => (
+            <>
+                <Clock onTick={emit} timezone={timezone} now={now} />
+                {children}
+            </>
+        )}
+    </Provider>
+);
+
+export { useClock, useClockSelector };

src/components/index.js

@@ -43,6 +43,8 @@ export {default as LanguageInput} from './inputs/language-input'
 export {default as FreeMultiTextInput} from "./inputs/free-multi-text-input";
 export {default as Exclusive} from "./exclusive-wrapper";
 export {default as Clock} from "./clock";
+export {ClockProvider, useClock, useClockSelector} from "./clock-context";
+export {createExternalStore} from "../utils/external-store";
 export {default as CircleButton} from "./circle-button";
 export {default as VideoStream} from "./video-stream";
 export {default as AttendanceTracker} from "./attendance-tracker";