hisd3-ui-kit 4.4.1 → 4.7.0

package/README.md

@@ -201,6 +201,47 @@ logo is used. `HISD3_LOGO_SRC` is exported if you need the mark elsewhere.
 `primary` accepts the brand presets `"brand"` (the logo's gear, `#E5533B`) and
 `"brandBlue"` (its cloud, `#1B6FE0`), any other preset, or a hex value.
 
+## Drawers and modals — `useDialog`
+
+Open a drawer or modal from anywhere, without the page holding its state. Put
+`DialogProvider` once near the root, inside whatever providers a dialog may
+need (the account and Apollo providers, and `HISD3Provider` for the theme):
+
+```tsx
+<HISD3Provider primary="teal">
+  <DialogProvider>{children}</DialogProvider>
+</HISD3Provider>
+```
+
+Then a page calls a function instead of owning `open` state per drawer:
+
+```tsx
+const showRecord = useDialog(RecordEventDrawer);
+
+showRecord({ fundYear, balances }, (batchId) => {
+  if (batchId) refetch();
+});
+```
+
+The component receives two extra props on top of its own — `open` (pass it to
+antd's `open` so the close animates) and `hide(result)`, whose argument reaches
+the second argument of `showRecord`:
+
+```tsx
+function RecordEventDrawer({ open, hide, fundYear }: DialogProps<string> & Props) {
+  return (
+    <Drawer open={open} onClose={() => hide()} title={`Record — ${fundYear}`}>
+      <Button onClick={() => hide(batchId)}>Save</Button>
+    </Drawer>
+  );
+}
+```
+
+Props are captured when `show` is called, so a drawer that used to be fed live
+state by its parent (`saving`) owns that state itself now. `hide` is safe to
+call twice — Escape during the close animation will not fire the callback
+again — and the instance unmounts once the animation finishes.
+
 ## Migrating
 
 ### from 3.x