Merge branch 'master' into update-alpha [skip release]

.github/workflows/rebuild-docs.yml

@@ -0,0 +1,19 @@
+name: 'dhis2: rebuild developer docs'
+
+on:
+    push:
+        branches:
+            - master
+        paths:
+            - 'docs/**'
+            - 'CHANGELOG.md'
+
+concurrency:
+    group: ${{ github.workflow}}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    rebuild-docs:
+        runs-on: ubuntu-latest
+        steps:
+            - run: curl -X POST -d {} https://api.netlify.com/build_hooks/${{ secrets.NETLIFY_DEVELOPER_DOCS_TOKEN }}

README.md

@@ -21,7 +21,7 @@ A query REPL platform application is also available at `./examples/query-playgro
 
 Running `yarn build` at root will automatically update the example app's copy, and running `yarn start` will build the runtime and then start the example.
 
-A [`DHIS2 App Platform`](https://platform.dhis2.nu) example is available at [./examples/query-playground](./examples/query-playground). This is a full, deployable DHIS2 application and a live standalone version is available at [runtime.dhis2.nu/playground](https://runtime.dhis2.nu/playground)
+A [`DHIS2 App Platform`](https://platform.dhis2.nu) example is available at [./examples/query-playground](./examples/query-playground). This is a full, deployable DHIS2 application and a live standalone version is available at [every play instance](https://play.dhis2.org), such as the `dev` instance [play.dhis2.org/dev](https://play.dhis2.org/dev/api/apps/query-playground/index.html).
 
 ## Release
 

docs/advanced/offline/CustomOnlineStatusMessage.md

@@ -0,0 +1,46 @@
+# Custom Connection Status Message
+
+By default, the header bar shows either an "Online" or "Offline" message based on whether the app can connect to the DHIS2 server. If it's useful for an app to share other relevant info in that badge, for example "3 changes saved locally", then it's possible to set a custom message there:
+
+![Custom online status message](custom-online-status-message.png)
+
+## Hooks
+
+```ts
+import {
+    useSetOnlineStatusMessage,
+    useOnlineStatusMessageValue,
+    useOnlineStatusMessage,
+} from '@dhis2/app-runtime'
+```
+
+### `useSetOnlineStatusMessage`
+
+It's most likely that you'll only use `useSetOnlineStatusMessage()`, a hook that returns a `setState` function. It can set the value in the Header Bar without causing a rerender for itself.
+
+`setOnlineStatusMessage()` accepts a `ReactNode`-type object, so icons or other components can be added to the badge, but don't go crazy. A simple string is also a valid `ReactNode`:
+
+```ts
+const setOnlineStatusMessage: (message: ReactNode) => void =
+    useSetOnlineStatusMessage()
+```
+
+### `useOnlineStatusMessageValue`
+
+This hook returns just the value:
+
+```ts
+const onlineStatusMessage: ReactNode = useOnlineStatusMessageValue()
+```
+
+### `useOnlineStatusMessage`
+
+This hook returns both the value and the `set` function:
+
+```ts
+const { onlineMessage, setOnlineStatusMessage } = useOnlineStatusMessage()
+```
+
+## Example
+
+You can see an example in use in the [Aggregate Data Entry app](https://github.com/dhis2/aggregate-data-entry-app/blob/dadd61392ea010a8017a19a25eaf76f885d9eea7/src/data-workspace/use-handle-headerbar-status.js)

docs/advanced/offline/README.md

@@ -1,10 +1,12 @@
 # Offline tools
 
-!> **WARNING** These features are considered **experimental** and are **subject to breaking changes outside of the normal release cycle.**
+:::warning Experimental
+These features are considered **experimental** and are **subject to breaking changes outside of the normal release cycle.**
+:::
 
-The app platform provides some support for PWA features, including a `manifest.json` file for installability and service worker which can provide offline caching. In addition to those features, the app runtime provides support for ["cacheable sections"](advanced/offline/CacheableSections), which are sections of an app that can be individually cached on-demand. The [`useCacheableSection` hook](advanced/offline/CacheableSections#usecacheablesection-api) and the [`CacheableSection` component](advanced/offline/CacheableSections#cacheablesection-api) provide the controls for the section and the wrapper for the section, respectively. The [`useCachedSections` hook](advanced/offline/CacheableSections#usecachedsections-api) returns a list of sections that are stored in the cache and a function that can delete them.
+The app platform provides some support for PWA features, including a `manifest.json` file for installability and service worker which can provide offline caching. In addition to those features, the app runtime provides support for ["cacheable sections"](./CacheableSections.md), which are sections of an app that can be individually cached on-demand. The [`useCacheableSection` hook](./CacheableSections.md#usecacheablesection-api) and the [`CacheableSection` component](./CacheableSections.md#cacheablesection-api) provide the controls for the section and the wrapper for the section, respectively. The [`useCachedSections` hook](./CacheableSections.md#usecachedsections-api) returns a list of sections that are stored in the cache and a function that can delete them.
 
-An important tool for offline-capable apps is the [`useDhis2ConnectionStatus` hook](advanced/offline/useDhis2ConnectionStatus.md), which can be used to determine whether or not the app can connect to the DHIS2 server. There is also a [`useOnlineStatus` hook](advanced/offline/useOnlineStatus.md) which returns whether or not the client is connected to the internet, but `useDhis2ConnectionStatus` is probably the one you want to use. On instances where DHIS2 is deployed locally in an environment without internet, `useOnlineStatus` can cause problems, because it will always return `false` even though the app can communicate with the DHIS2 server and therefore function just fine. `useDhis2ConnectionStatus` was created to address this problem.
+An important tool for offline-capable apps is the [`useDhis2ConnectionStatus` hook](./useDhis2ConnectionStatus.md), which can be used to determine whether or not the app can connect to the DHIS2 server. There is also a [`useOnlineStatus` hook](./useOnlineStatus.md) which returns whether or not the client is connected to the internet, but `useDhis2ConnectionStatus` is probably the one you want to use. On instances where DHIS2 is deployed locally in an environment without internet, `useOnlineStatus` can cause problems, because it will always return `false` even though the app can communicate with the DHIS2 server and therefore function just fine. `useDhis2ConnectionStatus` was created to address this problem.
 
 ## Examples
 

docs/advanced/offline/useDhis2ConnectionStatus.md

@@ -6,6 +6,8 @@ This hook is used to detect whether or not the app can connect to the DHIS2 serv
 
 It's designed to detect server connection because checking just the internet connection can lead to problems on DHIS2 instances that are implemented offline, where features or actions might be blocked because the device is offline, even though the app can connect to the DHIS2 server just fine. In these cases, what matters is whether or not the app can connect to the DHIS2 server.
 
+This what the DHIS2 Header Bar uses to show an "Online" or "Offline" badge.
+
 ```ts
 import { useDhis2ConnectionStatus } from '@dhis2/app-runtime'
 

docs/advanced/offline/useOnlineStatus.md

@@ -1,6 +1,8 @@
 # useOnlineStatus
 
-!> This hook only detects whether or not you're connected to the internet, which could be problematic for DHIS2 instances that are hosted locally or offline, where what really matters is whether or not you can communicate with the DHIS2 server. The [`useDhis2ConnectionStatus` hook](advanced/offline/useDhis2ConnectionStatus) is usually better for that reason, and is therefore recommended.
+:::info Internet Only
+This hook only detects whether or not you're connected to the internet, which could be problematic for DHIS2 instances that are hosted locally or offline, where what really matters is whether or not you can communicate with the DHIS2 server. The [`useDhis2ConnectionStatus` hook](./useDhis2ConnectionStatus.md) is usually better for that reason, and is therefore recommended.
+:::
 
 The `useOnlineStatus` returns whether the client is online or offline. It debounces the returned values by default to prevent rapid changes of any UI elements that depend on the online status.
 

docs/advanced/services.md

@@ -1,6 +1,8 @@
 # Services
 
-!> **NOTE**<br/>Services are purely a concept **internal** to `@dhis2/app-runtime` - you don't need to care about them to use it.
+:::caution Note
+Services are purely a concept **internal** to `@dhis2/app-runtime` - you don't need to care about them to use it.
+:::
 
 Internally, `@dhis2/app-runtime` is composed of several functionally-isolated **services**. Each of these services is a private (unpublished) npm package which is bundled into the final `@dhis2/app-runtime` library at build-time. Each services exposes a relevant Context provider as well as various Hook and Component interfaces which are re-exported by the `@dhis2/app-runtime` public package. There are currently only 2 services, but more will be added soon.
 

docs/components/DataMutation.md

@@ -1,6 +1,6 @@
 # DataMutation Component
 
-A thin wrapper around the [useDataMutation](hooks/useDataMutation.md) hook
+A thin wrapper around the [useDataMutation](../hooks/useDataMutation.md) hook
 
 ## Basic Usage
 
@@ -19,13 +19,13 @@ return (
 
 ## Input Props
 
-|      Name      |              Type               |   Required   | Description                                                                                                                   |
-| :------------: | :-----------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- |
-|  **mutation**  | [_Mutation_](types/Mutation.md) | **required** | The Mutation definition describing the requested operation                                                                    |
-| **variables**  |            _Object_             |              | Variables to be passed to the dynamic portions of the mutation                                                                |
-| **onComplete** |           _Function_            |              | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. |
-|  **onError**   |           _Function_            |              | Callback function to be called on failure of the mutation. Called with the error instance as the only argument.               |
-|    **lazy**    |            _boolean_            |              | If false, run the mutation immediately after the component mounts.<br/>_**Default**: `true`_                                  |
+|      Name      |                Type                |   Required   | Description                                                                                                                   |
+| :------------: | :--------------------------------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------- |
+|  **mutation**  | [_Mutation_](../types/Mutation.md) | **required** | The Mutation definition describing the requested operation                                                                    |
+| **variables**  |              _Object_              |              | Variables to be passed to the dynamic portions of the mutation                                                                |
+| **onComplete** |             _Function_             |              | Callback function to be called on successfull completion of the mutation. Called with the response data as the only argument. |
+|  **onError**   |             _Function_             |              | Callback function to be called on failure of the mutation. Called with the error instance as the only argument.               |
+|    **lazy**    |             _boolean_              |              | If false, run the mutation immediately after the component mounts.<br/>_**Default**: `true`_                                  |
 
 ## Render Function Props
 
@@ -34,13 +34,13 @@ The render function is called whenever the state of the mutation changes. It is
 1. `mutate` - a function which can be called to trigger the mutation (for instance in an onClick callback)
 2. `state` - an object containing the following properties:
 
-|    Name     |                  Type                   | Description                                                                                                                                                                            |
-| :---------: | :-------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **called**  |                _boolean_                | **true** if the mutation has been triggered through a call to the `mutate` function or on component mount with `lazy: false`                                                           |
-| **loading** |                _boolean_                | **true** if the data is not yet available and no error has yet been encountered                                                                                                        |
-|  **error**  |     _Error_<br/>or<br/>_undefined_      | **undefined** if no error has occurred, otherwise the Error which was thrown                                                                                                           |
-|  **data**   | _MutationResult_<br/>or<br/>_undefined_ | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query |
-| **engine**  |  [_Data Engine_](advanced/DataEngine)   | A reference to the DataEngine instance                                                                                                                                                 |
+|    Name     |                    Type                    | Description                                                                                                                                                                            |
+| :---------: | :----------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **called**  |                 _boolean_                  | **true** if the mutation has been triggered through a call to the `mutate` function or on component mount with `lazy: false`                                                           |
+| **loading** |                 _boolean_                  | **true** if the data is not yet available and no error has yet been encountered                                                                                                        |
+|  **error**  |       _Error_<br/>or<br/>_undefined_       | **undefined** if no error has occurred, otherwise the Error which was thrown                                                                                                           |
+|  **data**   |  _MutationResult_<br/>or<br/>_undefined_   | **undefined** if the data is loading or an error has occurred, otherwise a map from the name of each **QueryDefinition** defined in the **Query** to the resulting data for that query |
+| **engine**  | [_Data Engine_](../advanced/DataEngine.md) | A reference to the DataEngine instance                                                                                                                                                 |
 
 ## Example