hisd3-ui-kit 5.0.0 → 5.2.0

package/README.md

@@ -25,7 +25,7 @@ copy and one theme chain.
 ```tsx
 import { HISD3Provider } from "hisd3-ui-kit";
 
-<HISD3Provider primary="red">     {/* "red" | "orange" | "teal" | "blue" | "green" | "purple" | "#hex" */}
+<HISD3Provider primary="red" mode="light">  {/* primary: "red" | "orange" | "teal" | "blue" | "green" | "purple" | "brand" | "brandBlue" | "#hex"; mode: "light" | "dark" */}
   <App />
 </HISD3Provider>
 ```
@@ -33,7 +33,7 @@ import { HISD3Provider } from "hisd3-ui-kit";
 `HISD3Provider` sets up antd's `ConfigProvider` (CSS variables on, so every kit
 component and every plain antd component follows the chosen primary), antd
 `App` (themed `modal.confirm` / `message`), and the styled-components
-`ThemeProvider`. Options: `primary`, `borders` (`"hairline"` default, or
+`ThemeProvider`. Options: `primary`, `mode` (`"light"` default, or `"dark"`), `borders` (`"hairline"` default, or
 `"bold"` for the original 2px near-black rules), `radius` (default 0),
 `lineWidth` (overrides the `borders` preset), `overrides` (extra antd
 `ThemeConfig`), or `theme` to bypass the generator entirely.
@@ -44,7 +44,36 @@ states. Every kit component follows `--hisd3-rule-width`, so switching
 `borders="bold"` retunes the sidebar, header, table, tabs, pagination, inputs
 and buttons together.
 
-Need just the antd theme object (e.g. for Storybook)? `createHisd3Theme({ primary: "teal" })`.
+Need just the antd theme object (e.g. for Storybook)? `createHisd3Theme({ primary: "teal", mode: "dark" })`.
+
+### One primary, readable in light and dark
+
+An app sets one thing, its `primary`; neutrals, type, spacing and status
+colours are the same for every app. The kit makes any primary readable:
+
+- **Light:** a primary is darkened until it reads at 4.5:1 on the page, on
+  its own tint and under white text. Teal, Blue, Green and Purple are used as
+  given; Red, Orange, Brand and Brand blue come out a little darker.
+- **Dark:** it is lightened until it reads at 4.5:1 on the dark page and on
+  its tint, and carries dark text (`--hisd3-on-primary`).
+- `resolvePrimaryPalette(primary, mode)` returns what the kit applies
+  (`primary`, `onPrimary`, `primaryBg`, …; `source` is the colour as asked
+  for, for logos only). `contrastRatio(a, b)` is the WCAG ratio it checks with.
+
+Status colours (`HISD3_STATUS`) replace antd's defaults, which failed
+contrast: success `#2E7D32`, error `#B42318`, warning `#B54708` in light;
+`#6FBF73`, `#FF8A7A`, `#F0A35E` in dark, each on its own tint. Every form
+field (text, number, select, date, cascader, tree, mentions, checkbox,
+radio, search) shares one 3:1 edge (`controlBorder`, `--hisd3-input-border`),
+the field fill and a 2px primary edge on focus.
+
+`mode` is the app's to own: keep the person's choice (light, dark, or the
+computer's `prefers-color-scheme`) and pass the result in. Dark mode is the
+same system on a warm near-black (`HISD3_NEUTRALS_DARK`); every kit
+component reads CSS variables, so nothing is inverted by hand. For a region
+that must stay light in a dark app (a printout), scope the light variables to
+it: `hisd3VarsCss({ primary, mode: "light", selector: ".my-paper" })` plus an
+antd `ConfigProvider` with `createHisd3Theme({ primary, mode: "light" })`.
 
 ## 2. Build a page
 
@@ -112,11 +141,12 @@ const menuItems = [
 | `HISD3Provider` | Root theme provider (see above). |
 | `HISD3Sidebar` | App shell (see *Scrolling* below): brand block, grouped menu with accent bar on the active route, account dropdown (Settings / Logout with confirm), collapsible, optional top-nav mode (`layoutTop`). `menuItems` accept `{ key, path, name, icon, children, group, hideInMenu, disabled }`. `renderMenuLink` lets you plug in react-router's `<Link>`. Props `bareContent` + `hideHeaderBar` hand the header over to `HISD3PageHeader`. `collapseTrigger` places the collapse control: `"edge"` (default) floats a round chevron on the sidebar's right edge, level with the top bar — it works even when the top bar is hidden, and `collapseTriggerOffset` moves it down — `"header"` puts a square button in the shell's own top bar, `"none"` renders neither. |
 | `HISD3PageHeader` / `HISD3PageBody` | Top bar (breadcrumb left, actions right) that stays pinned while the page scrolls, plus a large title + subtitle that scrolls away; `HISD3PageBody` is the matching padded content area. |
-| `HISD3Table<T>` | antd `Table` restyled compactly — 45px rows, 14px cell text, uppercase 11px headers, hairline row rules. antd's own `size="small"` tightens it further with the HISD3 pagination bar: "Total N items", square page buttons, page-size toggle. Pass `pagination={{ current, pageSize, total, onChange, pageSizeOptions?, hidePageSize? }}` or `false`. Optional `footer` strip. Cell helper classes: `hisd3-cell-primary`, `hisd3-cell-link`, `hisd3-cell-muted`. |
+| `HISD3Table<T>` | antd `Table` restyled compactly — 45px rows, 14px cell text, uppercase 12px headers in the secondary text colour, hairline row rules. antd's own `size="small"` tightens it further with the HISD3 pagination bar: "Total N items", square page buttons, page-size toggle. Pass `pagination={{ current, pageSize, total, onChange, pageSizeOptions?, hidePageSize? }}` or `false`. Optional `footer` strip. Cell helper classes: `hisd3-cell-primary`, `hisd3-cell-link`, `hisd3-cell-muted`. |
 | `HISD3Tabs` | Underlined filter tabs; each item may carry a `count`. |
-| `HISD3Tag` | Uppercase status pill. `variant`: `neutral` (grey, e.g. ACTIVE / IN PATIENT), `soft` (primary tint, e.g. ER PATIENT), `outline` (2px primary border, e.g. OUT PATIENT), `solid`. `tone`: `primary` \| `success` \| `warning` \| `danger` \| `default`. |
+| `HISD3Tag` | Uppercase status pill, 12px on a 24px pill. `variant`: `neutral` (grey, e.g. ACTIVE / IN PATIENT), `soft` (primary tint, e.g. ER PATIENT), `outline` (2px primary border, e.g. OUT PATIENT), `solid`. `tone`: `primary` \| `success` \| `warning` \| `danger` \| `default`. |
 | `HISD3Button` | `variant`: `primary` (filled), `secondary` (default, dark 2px outline), `ghost`, `danger`. Accepts all antd `Button` props (`icon`, `size`, `loading`, …). |
-| `HISD3Input` / `HISD3SearchInput` | 2px-bordered input; the search variant is the grey filled hero field with a leading icon (`compact` for a 48px version). |
+| `HISD3Input` / `HISD3SearchInput` | 2px-bordered input; the search variant is a light field with a leading icon and a visible border, lighter than the page so it never reads as disabled. `size`: `"small"` 32px, `"middle"` 40px (default), `"large"` 56px. Colours: `--hisd3-input-bg`, `--hisd3-input-bg-hover`, `--hisd3-input-border-hover`. |
+| `HISD3Select` | antd `Select` that wraps long text instead of cutting it with "…", and shows an option's `description` on a second line. See [Select](#select). |
 | `HISD3Form*` fields | Every antd data-entry control pre-wrapped in `Form.Item`, with `loading` skeletons. See *Form fields* below. |
 | `HISD3HeaderActions` | Spacing wrapper for the top-right controls; `divided` inserts a rule before the last child. |
 | `HISD3NotificationButton` | Soft-grey circular button with a solid bell glyph and a count pill on its top-right edge; tints to the primary color while its panel is open. Pass `icon` to swap the glyph. Props: `items` (`{ id, title, description, time, unread, avatarSrc, icon, onClick }`), `count` (defaults to the unread tally), `loading`, `size` (default 40), `icon`, `onMarkAllRead`, `onSeeAll`, `emptyText`. |
@@ -125,7 +155,9 @@ const menuItems = [
 | `UserMenu` | The sidebar-footer account card, on its own. |
 
 Theme utilities: `createHisd3Theme`, `hisd3AntdTheme` (red default),
-`HISD3_PRESETS`, `HISD3_NEUTRALS`, `HISD3_BORDER_PRESETS`, `borderVarsCss`,
+`HISD3_PRESETS`, `HISD3_NEUTRALS`, `HISD3_NEUTRALS_DARK`, `HISD3_STATUS`,
+`HISD3_BORDER_PRESETS`, `HISD3_BORDER_PRESETS_DARK`, `hisd3VarsCss`,
+`resolvePrimaryPalette`, `contrastRatio`, `mix`, `shade`, `borderVarsCss`,
 `HISD3_FONT_FAMILY`,
 `HISD3_FONT_WEIGHT_HEADING` (800) / `HISD3_FONT_WEIGHT_BODY` (400), `HISD3_LAYOUT`,
 `resolvePrimary`, `tint`. Plain antd components (Form, Select, DatePicker,
@@ -161,7 +193,10 @@ Inside styled-components or CSS you can rely on antd's variables:
 `var(--ant-color-border)`, `var(--ant-color-border-secondary)`,
 `var(--ant-color-text)`, `var(--ant-color-text-tertiary)`,
 `var(--ant-color-bg-layout)`. The header controls additionally read
-`--hisd3-control-bg` / `--hisd3-control-bg-hover` (the grey circle fill) and
+`--hisd3-control-bg` / `--hisd3-control-bg-hover` (the grey circle fill),
+`--hisd3-input-border` / `--hisd3-input-border-hover` (every field's edge),
+`--hisd3-on-primary` (text on a primary fill), `--hisd3-hover` (a row's hover
+wash) and
 `--hisd3-popup-radius`, `--hisd3-bell-stretch` (how wide the bell glyph is drawn, default `1.12`), `--hisd3-edge-trigger-bg` / `--hisd3-edge-trigger-color` (the sidebar collapse chevron, primary-filled by default), so you can retune them per app without forking the
 components.
 
@@ -202,6 +237,42 @@ 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.
 
+## Select
+
+`HISD3Select` is antd's `Select` with two additions, and takes every `Select`
+prop. `HISD3FormSelect` uses it, so both work the same way.
+
+- **Long text wraps** — in the chosen value and in every option — instead of
+  being cut off with "…". On by default; `wrap={false}` turns it off.
+- **`description` on an option** is shown under its label, smaller and muted,
+  in the dropdown and in the box. With `showSearch`, typing matches the label
+  and the description.
+
+`monoLabel` puts the label line in a monospace font, for codes:
+
+```tsx
+<HISD3Select
+  showSearch
+  monoLabel
+  placeholder="Search an account…"
+  options={accounts.map((a) => ({ value: a.code, label: a.code, description: a.title }))}
+/>
+
+<HISD3FormSelect
+  name="accountCode"
+  label="Account"
+  fieldProps={{ showSearch: true, monoLabel: true, options: accountOptions }}
+/>
+```
+
+Your own `optionRender`, `labelRender`, `filterOption` or `optionFilterProp`
+replaces the default. `HISD3SelectLabel` renders the same two-line layout for a
+custom `optionRender` / `labelRender`.
+
+Wrapped rows are not all one height, so `virtual` is off while `wrap` is on.
+For a list of thousands of options, pass `virtual` (or search on the server and
+show a capped list). Tags in `mode="multiple"` stay on one line.
+
 ## Form fields
 
 Each `HISD3Form*` field is an antd control inside a `Form.Item`. It takes every
@@ -225,7 +296,7 @@ Each `HISD3Form*` field is an antd control inside a `Form.Item`. It takes every
 | `HISD3FormInputNumber` | `InputNumber` | number |
 | `HISD3FormAutoComplete` | `AutoComplete` | string |
 | `HISD3FormMentions` | `Mentions` | string |
-| `HISD3FormSelect` | `Select` | value / value[] |
+| `HISD3FormSelect` | `HISD3Select` | value / value[] |
 | `HISD3FormTreeSelect` | `TreeSelect` | value / value[] |
 | `HISD3FormCascader` | `Cascader` | path array |
 | `HISD3FormRadioGroup` | `Radio.Group` | value |
@@ -327,6 +398,20 @@ again — and the instance unmounts once the animation finishes.
 
 ## Migrating
 
+### from 5.1
+
+Nothing to change in code; the look moves:
+
+- Status colours, field edges, placeholders, column headings (12px), tags
+  (12px on 24px), sidebar group titles (12px) and the Segmented control now
+  meet WCAG AA. An app that set these itself in `overrides` can drop them.
+- A light primary is darkened a little in light mode (see "One primary,
+  readable in light and dark").
+- Card titles: 18px, and 16px on `size="small"` cards.
+- `HISD3Sidebar` shows the HISD3 mark when `logoUrl` fails to load, not a
+  broken image.
+- New: `mode: "dark"`.
+
 ### from 3.x
 
 - Wrap the app in `HISD3Provider` (the sidebar still works standalone with the red default, but the provider is what lets you pick a primary).