# H5Web App & Providers [![Demos](https://img.shields.io/website?down_message=offline&label=demo&up_message=online&url=https%3A%2F%2Fh5web.panosc.eu%2F)](https://h5web.panosc.eu/) [![Version](https://img.shields.io/npm/v/@h5web/app)](https://www.npmjs.com/package/@h5web/app) [H5Web](https://github.com/silx-kit/h5web) is a collection of React components to visualize and explore data. It consists of two main packages: - [`@h5web/lib`](https://www.npmjs.com/package/@h5web/lib): visualization components built with [react-three-fiber](https://github.com/react-spring/react-three-fiber). - **[`@h5web/app`](https://www.npmjs.com/package/@h5web/app): a stand-alone, web-based viewer to explore HDF5 files (this library)**. `@h5web/app` exposes the HDF5 viewer component `App`, as well as the following built-in data providers: - `H5GroveProvider` for use with server implementations based on [H5Grove](https://github.com/silx-kit/h5grove), like [jupyterlab-h5web](https://github.com/silx-kit/jupyterlab-h5web); - `HsdsProvider` for use with [HSDS](https://github.com/HDFGroup/hsds); - `MockProvider` for testing purposes. ## Getting started 🚀 ```bash npm install @h5web/app ``` ```tsx import '@h5web/app/dist/styles.css'; import React from 'react'; import { App, MockProvider } from '@h5web/app'; function MyApp() { return (

); } export default MyApp; ``` > If your bundler supports it (e.g. webpack 5), you may be able to shorten the > stylesheet import path as follows: > > ```ts > import '@h5web/app/styles.css'; > ``` ### Examples The following code sandboxes demonstrate how to set up and use `@h5web/app` with various front-end development stacks: - [Vite](https://codesandbox.io/s/h5webapp-vite-5c204) - [Create React App v4](https://codesandbox.io/s/h5webapp-cra-v4-0y1lj) - [Create React App v5](https://codesandbox.io/s/h5webapp-cra-v5-bzmbh1) ### Browser support H5Web works out of the box on **Firefox 78 ESR**. Support for Firefox 68 ESR is possible by polyfilling the `ResizeObserver` API. One easy way to do this is with [polyfill.io](https://polyfill.io/v3/): ```html ``` Older versions of Firefox are not supported. ## API reference ### `App` Renders the HDF5 viewer. For `App` to work, it must be wrapped in a data provider: ```tsx ``` #### `explorerOpen?: boolean` (optional) Whether the viewer should start with the explorer panel open. Defaults to `true`. Pass `false` to hide the explorer on initial render, thus giving more space to the visualization. This may be useful when H5Web is embeded inside another app. ```tsx ``` #### `initialPath?: string` (optional) The path to select within the file when the viewer is first rendered. Defaults to `'/'`. ```tsx ``` #### `getFeedbackURL?: (context: FeedbackContext) => string` (optional) If provided, a "Give feedback" button appears in the breadcrumbs bar, which invokes the function when clicked. The function should return a valid URL, for instance a `mailto:` URL with a pre-filled subject and body: `mailto:some@email.com?subject=Feedback&body=`. If the app is publicly available, we recommend returning the URL of a secure online contact form instead. ```tsx 'https://my-feedback-form.com'} /> ``` ```tsx { const { filePath, // path of current file entityPath, // path of currently selected entity } = context; return `mailto:some@email.com?subject=Feedback&body=${encodeURIComponent(...)}`; }} /> ``` #### `disableDarkMode?: boolean` (optional) By default, the viewer follows your browser's and/or operating system's dark mode setting. This prop disables this beahviour by forcing the viewer into light mode. ```tsx ``` #### `propagateErrors?: boolean` (optional) The viewer has a top-level `ErrorBoundary` that, by default, handles errors thrown outside of the visualization area. These include errors thrown by the data provider when fetching metadata for the explorer. If you prefer to implement your own error boundary, you may choose to let errors through the viewer's top-level boundary: ```tsx import { ErrorBoundary } from 'react-error-boundary'; ; ``` ### `H5GroveProvider` Data provider for [H5Grove](https://github.com/silx-kit/h5grove). ```tsx ``` #### `url: string` (required) The base URL of the H5Grove server. #### `filepath: string` (required) The path and/or name of the file to display in the UI. #### `axiosParams?: Record` (optional) By default, `H5GroveProvider` does not make any assumption as to which query parameters to send to the server. If you use one of H5Grove's default API implementations, then you'll need to use this prop to pass the `file` query parameter as shown above. ### `HsdsProvider` Data provider for [HSDS](https://github.com/HDFGroup/hsds). ```tsx ``` #### `url: string` (required) The base URL of the HSDS server. #### `username: string; password: string` (required) The credentials to use to authenticate to the HSDS server. Note that this authentication mechanism is not secure; please do not use it to grant access to private data. #### `filepath: string` (required) The path of the file to request. ### `MockProvider` Data provider for demonstration and testing purposes. ```tsx ``` ### Utilities #### `getFeedbackMailto` Generate a feedback `mailto:` URL using H5Web's built-in feedback email template. ```tsx (context: FeedbackContext, email: string, subject = 'Feedback') => string; ``` ```tsx import { getFeedbackMailto } from '@h5web/app'; ... { return getFeedbackMailto(context, 'some@email.com'); }} /> ``` ### Context The viewer component `App` communicates with its wrapping data provider through a React context called `DataContext`. This context is available via a custom hook called `useDataContext`. This means you can use the built-in data providers in your own applications: ```tsx ; function MyApp() { const { filename } = useDataContext(); return

{filename}

; } ``` `useDataContext` returns the following object: ```tsx interface DataContextValue { filepath: string; filename: string; entitiesStore: EntitiesStore; valuesStore: ValuesStore; attrValuesStore: AttrValuesStore; } ``` The three stores are created with the [react-suspense-fetch](https://github.com/dai-shi/react-suspense-fetch) library, which relies on [React Suspense](https://reactjs.org/docs/react-api.html#reactsuspense). A component that uses one of these stores (e.g. `entitiesStore.get('/path/to/entity')`) must have a `Suspense` ancestor to manage the loading state. ```tsx Loading...}> ; function MyApp() { const { entitiesStore } = useDataContext(); const group = entitiesStore.get('/resilience/slow_metadata'); return

{JSON.stringify(group, null, 2)}

; } ```