Merge pull request #1559 from silx-kit/docs

Misc docs improvements following feedback
silx-kit · Jan 31, 2024 · ad84ba3 · ad84ba3
2 parents 1d89e1b + 693074f
commit ad84ba3
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 10 deletions.
diff --git a/apps/demo/src/H5GroveApp.tsx b/apps/demo/src/H5GroveApp.tsx
@@ -1,4 +1,5 @@
 import { App, assertEnvVar, H5GroveProvider } from '@h5web/app';
+import { useMemo } from 'react';
 import { useSearch } from 'wouter';
 
 import { getFeedbackURL } from './utils';
@@ -17,7 +18,7 @@ function H5GroveApp() {
     <H5GroveProvider
       url={URL}
       filepath={filepath}
-      axiosConfig={{ params: { file: filepath } }}
+      axiosConfig={useMemo(() => ({ params: { file: filepath } }), [filepath])}
     >
       <App sidebarOpen={!query.has('wide')} getFeedbackURL={getFeedbackURL} />
     </H5GroveProvider>

diff --git a/apps/demo/src/Home.module.css b/apps/demo/src/Home.module.css
@@ -93,14 +93,35 @@
   font-style: italic;
 }
 
-.demoContext > a {
-  color: inherit;
-}
-
 .demoFiles {
   font-size: 0.875em;
 }
 
+.tip {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  color: var(--secondary-darker);
+  background-color: var(--secondary-light-bg);
+  margin-top: 2.5rem;
+  padding: 1rem 1.5rem;
+  border-radius: 1rem;
+}
+
+.tipIcon {
+  font-size: 3.5em;
+  color: var(--secondary-dark);
+}
+
+.tip > p {
+  margin: 0;
+}
+
+.demoContext a,
+.tip a {
+  color: inherit;
+}
+
 @media (min-width: 40em) {
   .max {
     max-width: 45em;

diff --git a/apps/demo/src/Home.tsx b/apps/demo/src/Home.tsx
@@ -1,5 +1,5 @@
 import { Fragment } from 'react';
-import { FiChevronsRight } from 'react-icons/fi';
+import { FiAlertCircle, FiChevronsRight } from 'react-icons/fi';
 import { Link } from 'wouter';
 
 import styles from './Home.module.css';
@@ -65,7 +65,7 @@ function Home() {
                   <strong>water_224.h5</strong>
                 </Link>{' '}
                 (default) - a typical NeXus file with various real-world
-                datasets to demonstrate H5Web's core visualizations.
+                datasets to demonstrate H5Web’s core visualizations.
               </li>
               <li>
                 <Link to="/h5grove?file=compressed.h5">compressed.h5</Link> - a
@@ -169,6 +169,18 @@ function Home() {
                 </Fragment>
               ))}
             </p>
+            <div className={styles.tip}>
+              <FiAlertCircle className={styles.tipIcon} />
+              <p>
+                This demo may break at any time. For a more stable and
+                featureful solution, please take a look at{' '}
+                <a href="https://myhdf5.hdfgroup.org/">myHDF5</a> or H5Web’s{' '}
+                <a href="https://marketplace.visualstudio.com/items?itemName=h5web.vscode-h5web">
+                  VS Code extension
+                </a>
+                .
+              </p>
+            </div>
           </section>
           <section>
             <h2>
@@ -190,7 +202,10 @@ function Home() {
             <p>
               This demo communicates with an HSDS test server, which serves the
               same files as the H5Grove demo above:{' '}
-              <Link to="/hsds">water_224.h5</Link> (<strong>default</strong>),{' '}
+              <Link to="/hsds">
+                <strong>water_224.h5</strong>
+              </Link>{' '}
+              (default),{' '}
               <Link to="/hsds?file=compressed.h5">compressed.h5</Link> (note
               that bitshuffle is not yet supported by HSDS),{' '}
               <Link to="/hsds?file=epics.h5">epics.h5</Link>,{' '}
@@ -207,7 +222,7 @@ function Home() {
             </h2>
             <p>
               This demo is used for development and automated testing purposes.
-              It provides a good overview of H5Web's functionalities, including
+              It provides a good overview of H5Web’s functionalities, including
               the core visualizations and their toolbars, slicing and mapping of
               nD datasets, NeXus visualizations and default plot detection, RGB
               images, error handling, loading state, etc.

diff --git a/packages/app/README.md b/packages/app/README.md
@@ -187,7 +187,7 @@ Data provider for [H5Grove](https://github.com/silx-kit/h5grove).
 <H5GroveProvider
   url="https://h5grove.server.url"
   filepath="some-file.h5"
-  axiosConfig={{ params: { file: 'some-file.h5' } }}
+  axiosConfig={useMemo(() => ({ params: { file: 'some-file.h5' } }), [])}
 >
   <App />
 </H5GroveProvider>
@@ -211,6 +211,9 @@ this prop to pass the `file` query parameter as shown above.
 If your API server requires authentication or is on a different domain, you'll
 need to pass the necessary request headers and configuration as well.
 
+> Remember to memoise or extract your `axiosConfig` object so the fetching cache
+> does not get cleared if/when your app re-renders.
+
 #### `getExportURL?: (...args) => URL | (() => Promise<URL | Blob>) | undefined` (optional)
 
 The `DataProvider#getExportURL` method is used by the toolbars to generate URLs
@@ -283,6 +286,41 @@ specific export scenarios. In this case, or if you don't provide a function at
 all, `H5GroveProvider` falls back to generating URLs based on the `/data`
 endpoint and `format` query param.
 
+#### `key?: Key` (optional)
+
+If the content of the current file changes and you want to ensure that the
+viewer refetches the latest metadata and dataset values, you can take advantage
+of
+[React's `key` attribute](https://react.dev/reference/react/useState#resetting-state-with-a-key).
+Changing the value of the `key` will force a remount of `H5GroveProvider` and
+clear its internal fetching cache.
+
+It is up to you to decide what sort of `key` to use and when to update it. For
+instance:
+
+- Your server could send over a hash of the file via WebSocket.
+- You could show a toast notification with a _Refresh_ button when the file
+  changes and simply increment a number when the button is clicked (cf.
+  contrived example below).
+
+```tsx
+function MyApp() {
+  const [key, setKey] = useState(0);
+  const incrementKey = useCallback(() => setKey((val) => val + 1), []);
+
+  return (
+    <>
+      <button type="button" onClick={incrementKey}>
+        Refresh
+      </button>
+      <H5GroveProvider key={key} /* ... */>
+        <App />
+      </H5GroveProvider>
+    </>
+  );
+}
+```
+
 ### `HsdsProvider`
 
 Data provider for [HSDS](https://github.com/HDFGroup/hsds).
@@ -321,6 +359,11 @@ See
 this time, so if you don't provide your own, the export menu will remain
 disabled in the toolbar.
 
+#### `key?: Key` (optional)
+
+See
+[`H5GroveProvider#key`](https://github.com/silx-kit/h5web/blob/main/packages/app/README.md#key-key-optional).
+
 ### `MockProvider`
 
 Data provider for demonstration and testing purposes.