hisd3-ui-kit 5.0.0 → 5.2.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { ThemeConfig, MenuProps, TableProps, TabsProps, ButtonProps, InputProps, FormItemProps, GetProps, Skeleton, Input, InputNumberProps, GetRef, InputNumber, SelectProps, RadioGroupProps, CheckboxProps, Checkbox, SwitchProps, DatePickerProps, DatePicker, TimePickerProps, TimePicker, TimeRangePickerProps, AutoCompleteProps, AutoComplete, MentionsProps, MentionsRef, CascaderAutoProps, Cascader, TreeSelectProps, TreeSelect, SegmentedProps, TransferProps, Transfer, Slider, RateProps, Rate, ColorPickerProps, UploadProps, UploadFile } from 'antd';
+import { ThemeConfig, MenuProps, TableProps, TabsProps, ButtonProps, InputProps, SelectProps, FormItemProps, GetProps, Skeleton, Input, InputNumberProps, GetRef, InputNumber, RadioGroupProps, CheckboxProps, Checkbox, SwitchProps, DatePickerProps, DatePicker, TimePickerProps, TimePicker, TimeRangePickerProps, AutoCompleteProps, AutoComplete, MentionsProps, MentionsRef, CascaderAutoProps, Cascader, TreeSelectProps, TreeSelect, SegmentedProps, TransferProps, Transfer, Slider, RateProps, Rate, ColorPickerProps, UploadProps, UploadFile } from 'antd';
 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';
 import { AnyObject } from 'antd/es/_util/type';
+import { DefaultOptionType } from 'antd/es/select';
 import * as antd_es_input_TextArea from 'antd/es/input/TextArea';
 
 /** Named primary-color presets. Any hex string is also accepted. */
@@ -20,24 +21,82 @@ declare const HISD3_PRESETS: {
     readonly purple: "#6A3FD6";
 };
 type HISD3Preset = keyof typeof HISD3_PRESETS;
-/** Neutral palette shared by every preset (the "Backoffice" look). */
+/** Light or dark. Each person picks one; a module never forces it. */
+type HISD3ThemeMode = "light" | "dark";
+/** Neutral palette shared by every preset (the "Backoffice" look), light. */
 declare const HISD3_NEUTRALS: {
     readonly bgLayout: "#F3F2F0";
     readonly bgContainer: "#F3F2F0";
     readonly bgElevated: "#FFFFFF";
     readonly bgFilled: "#E6E4E1";
     readonly bgFilledHover: "#DBD8D4";
+    /** Inside a text field: lighter than the page, so it never reads as disabled. */
+    readonly bgField: "#FAF9F7";
+    /** A table row under the pointer: solid, so a fixed column can sit on it. */
+    readonly bgRowHover: "#EBEAE8";
+    /** A translucent hover wash for menu rows and list items. */
+    readonly hover: "rgba(0,0,0,0.04)";
     readonly text: "#171717";
     readonly textSecondary: "#4A4A4A";
+    /** Placeholders, captions, the breadcrumb trail. 4.6:1 on the page. */
     readonly textTertiary: "#6E6E6E";
     /** Structural rules: sidebar edge, header bottom, table header. */
     readonly border: "#D9D5CE";
     /** Quieter rules: table rows, dividers inside popups. */
     readonly borderSecondary: "#E7E4DE";
-    /** Near-black, used for hover/focus emphasis on controls. */
+    /** Near-black, used for hover emphasis on outlined buttons. */
     readonly borderStrong: "#1F1F1F";
+    /** The edge of every form field: 3.1:1 on the page, so a field is findable. */
+    readonly controlBorder: "#8C8A85";
+    readonly controlBorderHover: "#5F5D59";
+    /** Behind a drawer or modal. */
+    readonly mask: "rgba(23,23,23,0.45)";
     readonly white: "#FFFFFF";
 };
+/** The same roles on a warm near-black. */
+declare const HISD3_NEUTRALS_DARK: {
+    readonly bgLayout: "#1A1917";
+    readonly bgContainer: "#1A1917";
+    /** Popups sit lighter than the page, so they still lift. */
+    readonly bgElevated: "#262522";
+    readonly bgFilled: "#2E2D2A";
+    readonly bgFilledHover: "#393734";
+    readonly bgField: "#201F1D";
+    readonly bgRowHover: "#22211F";
+    readonly hover: "rgba(255,255,255,0.05)";
+    readonly text: "#EEEDEA";
+    readonly textSecondary: "#C2C0BB";
+    readonly textTertiary: "#9C9A94";
+    readonly border: "#3A3936";
+    readonly borderSecondary: "#2C2B29";
+    readonly borderStrong: "#EEEDEA";
+    readonly controlBorder: "#77746E";
+    readonly controlBorderHover: "#A8A59F";
+    readonly mask: "rgba(0,0,0,0.6)";
+    readonly white: "#FFFFFF";
+};
+/**
+ * Status colours. Separate from the primary and the same in every module;
+ * each text colour reads at 4.5:1 or more on its own tint and on the page.
+ */
+declare const HISD3_STATUS: {
+    readonly light: {
+        readonly success: "#2E7D32";
+        readonly successBg: "#EAF3EA";
+        readonly error: "#B42318";
+        readonly errorBg: "#FBEAE7";
+        readonly warning: "#B54708";
+        readonly warningBg: "#FBEFE3";
+    };
+    readonly dark: {
+        readonly success: "#6FBF73";
+        readonly successBg: "#283426";
+        readonly error: "#FF8A7A";
+        readonly errorBg: "#3F2B27";
+        readonly warning: "#F0A35E";
+        readonly warningBg: "#3C2F22";
+    };
+};
 /** Border weights. "hairline" is the default modern look. */
 declare const HISD3_BORDER_PRESETS: {
     readonly hairline: {
@@ -51,6 +110,19 @@ declare const HISD3_BORDER_PRESETS: {
         readonly borderSecondary: "#CFCDC9";
     };
 };
+/** The border presets in dark mode. */
+declare const HISD3_BORDER_PRESETS_DARK: {
+    readonly hairline: {
+        readonly width: 1;
+        readonly border: "#3A3936";
+        readonly borderSecondary: "#2C2B29";
+    };
+    readonly bold: {
+        readonly width: 2;
+        readonly border: "#C2C0BB";
+        readonly borderSecondary: "#3A3936";
+    };
+};
 type HISD3Borders = keyof typeof HISD3_BORDER_PRESETS;
 declare const HISD3_FONT_FAMILY = "'Archivo', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
 /** Archivo is used for both body (400) and headings (800). */
@@ -59,6 +131,8 @@ declare const HISD3_FONT_WEIGHT_BODY = 400;
 interface HISD3ThemeOptions {
     /** Preset name or any hex color. Default "red". */
     primary?: HISD3Preset | string;
+    /** Light (default) or dark. */
+    mode?: HISD3ThemeMode;
     /** Corner radius in px. The Backoffice look is square (0). */
     radius?: number;
     /**
@@ -82,14 +156,39 @@ declare const resolvePrimary: (primary?: HISD3Preset | string) => string;
 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;
+/** Mix two hex colors: amount 0 → `a`, 1 → `b`. */
+declare const mix: (a: string, b: string, amount: number) => string;
+/** WCAG 2 contrast ratio between two hex colours (1 to 21). */
+declare const contrastRatio: (a: string, b: string) => number;
+/** The primary as the kit applies it, and the colours derived from it. */
+interface HISD3PrimaryPalette {
+    /** The colour as asked for. Logos and illustrations only. */
+    source: string;
+    /** Buttons, links, the selected menu item, the active tab. */
+    primary: string;
+    /** Text and icons on a `primary` fill. */
+    onPrimary: string;
+    /** The selected menu row, a selected option, a soft primary tag. */
+    primaryBg: string;
+    primaryBgHover: string;
+    primaryBorder: string;
+}
+/**
+ * Make any primary readable. In light mode it is darkened until it reads at
+ * 4.5:1 on the page, on its own tint and under white text; in dark mode it is
+ * lightened until it reads at 4.5:1 on the page and on its own tint, and
+ * carries dark text. Teal, Blue, Green and Purple are used as given in light
+ * mode; Red, Orange and Brand come out a little darker.
+ */
+declare const resolvePrimaryPalette: (primary?: HISD3Preset | string, mode?: HISD3ThemeMode) => HISD3PrimaryPalette;
 /**
  * Build the HISD3 Ant Design v6 theme.
  *
  * ```ts
- * <ConfigProvider theme={createHisd3Theme({ primary: "teal" })}>
+ * <ConfigProvider theme={createHisd3Theme({ primary: "teal", mode: "dark" })}>
  * ```
  */
-declare const createHisd3Theme: ({ primary, radius, borders, lineWidth, overrides, }?: HISD3ThemeOptions) => ThemeConfig;
+declare const createHisd3Theme: ({ primary, mode, radius, borders, lineWidth, overrides, }?: HISD3ThemeOptions) => ThemeConfig;
 /**
  * CSS emitted by HISD3Provider on `:root`.
  *
@@ -99,7 +198,13 @@ declare const createHisd3Theme: ({ primary, radius, borders, lineWidth, override
  * `:root` so kit components and app CSS work anywhere in the tree. antd's own
  * declarations sit closer to its components, so they still win there.
  */
-declare const hisd3VarsCss: ({ primary, borders, lineWidth, radius, }?: HISD3ThemeOptions) => string;
+declare const hisd3VarsCss: ({ primary, mode, borders, lineWidth, radius, selector, }?: HISD3ThemeOptions & {
+    /**
+     * Where the variables apply. `:root` (default) for the app; a class to give
+     * one region its own mode, such as a printout that stays light in a dark app.
+     */
+    selector?: string;
+}) => string;
 /** @deprecated use `hisd3VarsCss` — it emits the colour tokens too. */
 declare const borderVarsCss: (borders?: HISD3Borders, lineWidth?: number) => string;
 /** Default HISD3 theme — the red "Backoffice" look. */
@@ -672,6 +777,9 @@ interface HISD3ProviderProps extends HISD3ThemeOptions {
  * </HISD3Provider>
  * ```
  *
+ * `mode="dark"` switches every kit and antd component to the dark palette;
+ * the app owns the person's choice (and where it is remembered).
+ *
  * It wires the antd `ConfigProvider` (with CSS variables enabled so every
  * kit component follows the chosen primary), antd `App` (for themed
  * `modal.confirm` / `message`), and the styled-components `ThemeProvider`.
@@ -1027,7 +1135,7 @@ interface HISD3TagProps extends React.HTMLAttributes<HTMLSpanElement> {
      * neutral → light grey fill, dark text   (ACTIVE, IN PATIENT)
      * soft    → primary tint fill, primary text (ER PATIENT)
      * outline → 2px primary border, primary text (OUT PATIENT)
-     * solid   → primary fill, white text
+     * solid   → tone fill, text in the colour that reads on it (white in light mode, dark in dark mode)
      */
     variant?: HISD3TagVariant;
     tone?: HISD3TagTone;
@@ -1059,9 +1167,52 @@ interface HISD3SearchInputProps extends Omit<InputProps, "size"> {
     /** @deprecated use `size` — kept so existing call sites keep working. */
     compact?: boolean;
 }
-/** Grey filled search field with leading icon (the page-level search bar). */
+/** Light search field with a leading icon (the page-level search bar). */
 declare const HISD3SearchInput: React.ForwardRefExoticComponent<Omit<HISD3SearchInputProps, "ref"> & React.RefAttributes<InputRef>>;
 
+/** An option that may carry a second, smaller line under its label. */
+interface HISD3SelectOption extends DefaultOptionType {
+    /** Shown under the label, smaller and muted — e.g. the account title under its code. */
+    description?: React.ReactNode;
+}
+interface HISD3SelectProps extends SelectProps<any, HISD3SelectOption> {
+    /**
+     * Wrap long text onto more lines — in the chosen value and in every option —
+     * instead of cutting it off with "…". On by default.
+     *
+     * Turns antd's virtual list off unless you pass `virtual` yourself: wrapped
+     * rows are not all the same height. Pass `virtual` for a very long list.
+     */
+    wrap?: boolean;
+    /** Label line in a monospace font — for codes (account codes, UACS, …). */
+    monoLabel?: boolean;
+}
+interface HISD3SelectLabelProps {
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    /** Label in a monospace font. */
+    mono?: boolean;
+}
+/**
+ * The two-line layout HISD3Select uses for an option with a `description`:
+ * the label on top, the description underneath, smaller and muted. Both wrap.
+ * Exported for a custom `optionRender` / `labelRender` that wants the same look.
+ */
+declare const HISD3SelectLabel: React.FC<HISD3SelectLabelProps>;
+/**
+ * antd Select that wraps long text instead of truncating it, and shows an
+ * option's `description` on a second line — in the dropdown and in the box.
+ *
+ * ```tsx
+ * <HISD3Select
+ *   showSearch
+ *   monoLabel
+ *   options={accounts.map((a) => ({ value: a.code, label: a.code, description: a.title }))}
+ * />
+ * ```
+ */
+declare const HISD3Select: React.ForwardRefExoticComponent<Omit<HISD3SelectProps, "ref"> & React.RefAttributes<RefSelectProps>>;
+
 type HISD3SkeletonInputProps = GetProps<typeof Skeleton.Input>;
 type ControlSize = HISD3SkeletonInputProps["size"];
 interface HISD3FormFieldBaseProps extends Omit<FormItemProps, "children"> {
@@ -1112,8 +1263,8 @@ declare const HISD3FormTextArea: React.ForwardRefExoticComponent<Omit<HISD3FormT
 type HISD3FormInputNumberProps = HISD3FormFieldProps<InputNumberProps>;
 /** Numeric input, full width of its column. */
 declare const HISD3FormInputNumber: HISD3FormFieldComponent<HISD3FormInputNumberProps, HISD3InputNumberRef>;
-type HISD3FormSelectProps = HISD3FormFieldProps<SelectProps>;
-/** Select / multi-select. */
+type HISD3FormSelectProps = HISD3FormFieldProps<HISD3SelectProps>;
+/** Select / multi-select (`HISD3Select`: long text wraps, options may carry a `description`). */
 declare const HISD3FormSelect: React.ForwardRefExoticComponent<Omit<HISD3FormSelectProps, "ref"> & React.RefAttributes<RefSelectProps>>;
 type HISD3FormRadioGroupProps = HISD3FormFieldProps<RadioGroupProps>;
 /** Radio group — pass `fieldProps.options`. */
@@ -1259,5 +1410,5 @@ declare const HISD3_LAYOUT: {
     readonly pageGutter: 28;
 };
 
-export { AppAnimateGroups, AppAnimates, AppMotionAnimate, AuthType, DialogProvider, Fonts, FooterType, HISD3AvatarMenu, HISD3Button, HISD3FormAutoComplete, HISD3FormCascader, HISD3FormCheckbox, HISD3FormCheckboxGroup, HISD3FormColorPicker, HISD3FormDatePicker, HISD3FormField, HISD3FormInput, HISD3FormInputNumber, HISD3FormMentions, HISD3FormOTP, HISD3FormPassword, HISD3FormRadioGroup, HISD3FormRangePicker, HISD3FormRate, HISD3FormSearch, HISD3FormSegmented, HISD3FormSelect, HISD3FormSlider, HISD3FormSwitch, HISD3FormTextArea, HISD3FormTimePicker, HISD3FormTimeRangePicker, HISD3FormTransfer, HISD3FormTreeSelect, HISD3FormUpload, HISD3FormUploadDragger, 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, normalizeUploadFileList, resolvePrimary, shade, tint, useDialog, useInsideHISD3Provider };
-export type { DialogOwnProps, DialogProps, DialogResult, HISD3AutoCompleteRef, HISD3AvatarMenuProps, HISD3Borders, HISD3BreadcrumbItem, HISD3ButtonProps, HISD3ButtonVariant, HISD3CascaderRef, HISD3FormAutoCompleteProps, HISD3FormCascaderProps, HISD3FormCheckboxGroupProps, HISD3FormCheckboxProps, HISD3FormColorPickerProps, HISD3FormDatePickerProps, HISD3FormFieldBaseProps, HISD3FormFieldComponent, HISD3FormFieldProps, HISD3FormFieldShellProps, HISD3FormInputNumberProps, HISD3FormInputProps, HISD3FormMentionsProps, HISD3FormOTPProps, HISD3FormPasswordProps, HISD3FormRadioGroupProps, HISD3FormRangePickerProps, HISD3FormRateProps, HISD3FormSearchProps, HISD3FormSegmentedProps, HISD3FormSelectProps, HISD3FormSliderProps, HISD3FormSwitchProps, HISD3FormTextAreaProps, HISD3FormTimePickerProps, HISD3FormTimeRangePickerProps, HISD3FormTransferProps, HISD3FormTreeSelectProps, HISD3FormUploadProps, HISD3HeaderActionsProps, HISD3InputNumberRef, HISD3InputProps, HISD3LoginPageProps, HISD3LoginValues, HISD3MenuItem, HISD3Notification, HISD3NotificationButtonProps, HISD3OTPRef, HISD3PageHeaderProps, HISD3PickerRef, HISD3Preset, HISD3ProviderProps, HISD3RangePickerRef, HISD3RateRef, HISD3SearchInputProps, HISD3SidebarProps, HISD3SkeletonInputProps, HISD3SliderRef, HISD3TabItem, HISD3TablePagination, HISD3TableProps, HISD3TabsProps, HISD3TagProps, HISD3TagTone, HISD3TagVariant, HISD3ThemeOptions, HISD3TimePickerRef, HISD3TimeRangePickerRef, HISD3TransferRef, HISD3TreeSelectRef, IUserEmployee, LoginSide, LoginVariant, StyledTheme, UserMenuProps };
+export { AppAnimateGroups, AppAnimates, AppMotionAnimate, AuthType, DialogProvider, Fonts, FooterType, HISD3AvatarMenu, HISD3Button, HISD3FormAutoComplete, HISD3FormCascader, HISD3FormCheckbox, HISD3FormCheckboxGroup, HISD3FormColorPicker, HISD3FormDatePicker, HISD3FormField, HISD3FormInput, HISD3FormInputNumber, HISD3FormMentions, HISD3FormOTP, HISD3FormPassword, HISD3FormRadioGroup, HISD3FormRangePicker, HISD3FormRate, HISD3FormSearch, HISD3FormSegmented, HISD3FormSelect, HISD3FormSlider, HISD3FormSwitch, HISD3FormTextArea, HISD3FormTimePicker, HISD3FormTimeRangePicker, HISD3FormTransfer, HISD3FormTreeSelect, HISD3FormUpload, HISD3FormUploadDragger, HISD3HeaderActions, HISD3Input, HISD3LoginPage, HISD3NotificationButton, HISD3PageBody, HISD3PageHeader, HISD3Provider, HISD3SearchInput, HISD3Select, HISD3SelectLabel, HISD3Sidebar, HISD3Table, HISD3Tabs, HISD3Tag, HISD3_BORDER_PRESETS, HISD3_BORDER_PRESETS_DARK, HISD3_COLORS, HISD3_FONT_FAMILY, HISD3_FONT_WEIGHT_BODY, HISD3_FONT_WEIGHT_HEADING, HISD3_LAYOUT, HISD3_LOGO_SRC, HISD3_NEUTRALS, HISD3_NEUTRALS_DARK, HISD3_PRESETS, HISD3_STATUS, HeaderIconButton, HeaderType, LayoutDirection, LayoutType, MenuStyle, MessageType, NavStyle, RoutePermittedRole, RouteTransition, ThemeMode, ThemeStyle, ThemeStyleRadius, UserMenu, borderVarsCss, contrastRatio, createHisd3Theme, getInitials, hisd3AntdTheme, hisd3VarsCss, mix, normalizeUploadFileList, resolvePrimary, resolvePrimaryPalette, shade, tint, useDialog, useInsideHISD3Provider };
+export type { DialogOwnProps, DialogProps, DialogResult, HISD3AutoCompleteRef, HISD3AvatarMenuProps, HISD3Borders, HISD3BreadcrumbItem, HISD3ButtonProps, HISD3ButtonVariant, HISD3CascaderRef, HISD3FormAutoCompleteProps, HISD3FormCascaderProps, HISD3FormCheckboxGroupProps, HISD3FormCheckboxProps, HISD3FormColorPickerProps, HISD3FormDatePickerProps, HISD3FormFieldBaseProps, HISD3FormFieldComponent, HISD3FormFieldProps, HISD3FormFieldShellProps, HISD3FormInputNumberProps, HISD3FormInputProps, HISD3FormMentionsProps, HISD3FormOTPProps, HISD3FormPasswordProps, HISD3FormRadioGroupProps, HISD3FormRangePickerProps, HISD3FormRateProps, HISD3FormSearchProps, HISD3FormSegmentedProps, HISD3FormSelectProps, HISD3FormSliderProps, HISD3FormSwitchProps, HISD3FormTextAreaProps, HISD3FormTimePickerProps, HISD3FormTimeRangePickerProps, HISD3FormTransferProps, HISD3FormTreeSelectProps, HISD3FormUploadProps, HISD3HeaderActionsProps, HISD3InputNumberRef, HISD3InputProps, HISD3LoginPageProps, HISD3LoginValues, HISD3MenuItem, HISD3Notification, HISD3NotificationButtonProps, HISD3OTPRef, HISD3PageHeaderProps, HISD3PickerRef, HISD3Preset, HISD3PrimaryPalette, HISD3ProviderProps, HISD3RangePickerRef, HISD3RateRef, HISD3SearchInputProps, HISD3SelectLabelProps, HISD3SelectOption, HISD3SelectProps, HISD3SidebarProps, HISD3SkeletonInputProps, HISD3SliderRef, HISD3TabItem, HISD3TablePagination, HISD3TableProps, HISD3TabsProps, HISD3TagProps, HISD3TagTone, HISD3TagVariant, HISD3ThemeMode, HISD3ThemeOptions, HISD3TimePickerRef, HISD3TimeRangePickerRef, HISD3TransferRef, HISD3TreeSelectRef, IUserEmployee, LoginSide, LoginVariant, StyledTheme, UserMenuProps };