hisd3-ui-kit 4.5.0 → 4.7.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ThemeConfig, MenuProps, TableProps, TabsProps, ButtonProps, InputProps } from 'antd';
-import React, { ReactNode } from 'react';
+import React, { ReactNode, ComponentType } from 'react';
 import * as styled_components_dist_types from 'styled-components/dist/types';
 import * as styled_components from 'styled-components';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -71,6 +71,14 @@ interface HISD3ThemeOptions {
     overrides?: ThemeConfig;
 }
 declare const resolvePrimary: (primary?: HISD3Preset | string) => string;
+/**
+ * Mix a hex color with black: amount 0 → color, 1 → black.
+ *
+ * Used for table backgrounds. A fixed column is `position: sticky`, so the rest
+ * of the row scrolls underneath it and its cells must be opaque — every Table
+ * background token has to be a solid blend, never an alpha overlay.
+ */
+declare const shade: (hex: string, amount: number) => string;
 /** Mix a hex color with white: amount 0 → color, 1 → white. */
 declare const tint: (hex: string, amount: number) => string;
 /**
@@ -1053,6 +1061,54 @@ interface HISD3SearchInputProps extends Omit<InputProps, "size"> {
 /** Grey filled search field with leading icon (the page-level search bar). */
 declare const HISD3SearchInput: React.FC<HISD3SearchInputProps>;
 
+/**
+ * Open a drawer or modal from anywhere, without the page holding its state.
+ *
+ *   const showRecord = useDialog(RecordEventDrawer);
+ *   showRecord({ fundYear, balances }, (batchId) => { if (batchId) refetch(); });
+ *
+ * The page no longer owns `const [open, setOpen] = useState(false)` for every
+ * drawer it can show, nor renders each one inline with `open={…}`; it calls a
+ * function with the props and, optionally, what to do with the result. The
+ * component gets two extra props — `open` and `hide(result)` — and hands its
+ * result back through `hide`, which is what reaches the second argument.
+ *
+ * Same shape as the `useModal`-based `UseDrawer` used in the other HISD3 apps,
+ * implemented here without `react-modal-hook`: that library predates React 18,
+ * and this is forty lines. Two differences worth knowing:
+ *
+ *  - `open` is passed so antd can animate the close. `hide` sets it false,
+ *    fires the callback at once, and unmounts after the animation.
+ *  - Props are captured when `show` is called. A drawer whose parent used to
+ *    feed it live state (`saving`) owns that state itself now.
+ *
+ * Dialogs render under `DialogProvider`. Put it inside whatever providers a
+ * dialog may need — the account and Apollo providers, and `HISD3Provider` for
+ * the theme — so a drawer may use every hook a page may.
+ */
+/** What every dialog component receives on top of its own props. */
+type DialogProps<R = void> = {
+    /** True while shown; false during the close animation. Pass to antd's `open`. */
+    open: boolean;
+    /** Close, handing a result to whoever opened the dialog. */
+    hide: (result?: R) => void;
+};
+/** The result type a component's `hide` carries. */
+type DialogResult<P> = P extends {
+    hide: (result?: infer R) => void;
+} ? R : void;
+/** A component's own props, without the two the hook supplies. */
+type DialogOwnProps<P> = Omit<P, keyof DialogProps>;
+/** Where every open dialog renders. Once, near the root of the app. */
+declare function DialogProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * A function that shows `Component` with the given props. Its second argument
+ * receives whatever the component passes to `hide`.
+ */
+declare function useDialog<P extends DialogProps<DialogResult<P>>>(Component: ComponentType<P>): (props: DialogOwnProps<P>, onClose?: (result?: DialogResult<P>) => void) => void;
+
 /** Shared layout metrics so the sidebar brand block and page top bar line up. */
 declare const HISD3_LAYOUT: {
     readonly siderWidth: 260;
@@ -1063,5 +1119,5 @@ declare const HISD3_LAYOUT: {
     readonly pageGutter: 28;
 };
 
-export { AppAnimateGroups, AppAnimates, AppMotionAnimate, AuthType, Fonts, FooterType, HISD3AvatarMenu, HISD3Button, HISD3HeaderActions, HISD3Input, HISD3LoginPage, HISD3NotificationButton, HISD3PageBody, HISD3PageHeader, HISD3Provider, HISD3SearchInput, HISD3Sidebar, HISD3Table, HISD3Tabs, HISD3Tag, HISD3_BORDER_PRESETS, HISD3_COLORS, HISD3_FONT_FAMILY, HISD3_FONT_WEIGHT_BODY, HISD3_FONT_WEIGHT_HEADING, HISD3_LAYOUT, HISD3_LOGO_SRC, HISD3_NEUTRALS, HISD3_PRESETS, HeaderIconButton, HeaderType, LayoutDirection, LayoutType, MenuStyle, MessageType, NavStyle, RoutePermittedRole, RouteTransition, ThemeMode, ThemeStyle, ThemeStyleRadius, UserMenu, borderVarsCss, createHisd3Theme, getInitials, hisd3AntdTheme, hisd3VarsCss, resolvePrimary, tint, useInsideHISD3Provider };
-export type { HISD3AvatarMenuProps, HISD3Borders, HISD3BreadcrumbItem, HISD3ButtonProps, HISD3ButtonVariant, HISD3HeaderActionsProps, HISD3InputProps, HISD3LoginPageProps, HISD3LoginValues, HISD3MenuItem, HISD3Notification, HISD3NotificationButtonProps, HISD3PageHeaderProps, HISD3Preset, HISD3ProviderProps, HISD3SearchInputProps, HISD3SidebarProps, HISD3TabItem, HISD3TablePagination, HISD3TableProps, HISD3TabsProps, HISD3TagProps, HISD3TagTone, HISD3TagVariant, HISD3ThemeOptions, IUserEmployee, StyledTheme, UserMenuProps };
+export { AppAnimateGroups, AppAnimates, AppMotionAnimate, AuthType, DialogProvider, Fonts, FooterType, HISD3AvatarMenu, HISD3Button, HISD3HeaderActions, HISD3Input, HISD3LoginPage, HISD3NotificationButton, HISD3PageBody, HISD3PageHeader, HISD3Provider, HISD3SearchInput, HISD3Sidebar, HISD3Table, HISD3Tabs, HISD3Tag, HISD3_BORDER_PRESETS, HISD3_COLORS, HISD3_FONT_FAMILY, HISD3_FONT_WEIGHT_BODY, HISD3_FONT_WEIGHT_HEADING, HISD3_LAYOUT, HISD3_LOGO_SRC, HISD3_NEUTRALS, HISD3_PRESETS, HeaderIconButton, HeaderType, LayoutDirection, LayoutType, MenuStyle, MessageType, NavStyle, RoutePermittedRole, RouteTransition, ThemeMode, ThemeStyle, ThemeStyleRadius, UserMenu, borderVarsCss, createHisd3Theme, getInitials, hisd3AntdTheme, hisd3VarsCss, resolvePrimary, shade, tint, useDialog, useInsideHISD3Provider };
+export type { DialogOwnProps, DialogProps, DialogResult, HISD3AvatarMenuProps, HISD3Borders, HISD3BreadcrumbItem, HISD3ButtonProps, HISD3ButtonVariant, HISD3HeaderActionsProps, HISD3InputProps, HISD3LoginPageProps, HISD3LoginValues, HISD3MenuItem, HISD3Notification, HISD3NotificationButtonProps, HISD3PageHeaderProps, HISD3Preset, HISD3ProviderProps, HISD3SearchInputProps, HISD3SidebarProps, HISD3TabItem, HISD3TablePagination, HISD3TableProps, HISD3TabsProps, HISD3TagProps, HISD3TagTone, HISD3TagVariant, HISD3ThemeOptions, IUserEmployee, LoginSide, LoginVariant, StyledTheme, UserMenuProps };