hisd3-ui-kit 4.0.1 → 4.2.0

package/README.md

@@ -33,9 +33,16 @@ 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`, `radius` (default 0), `lineWidth`
-(default 2), `overrides` (extra antd `ThemeConfig`), or `theme` to bypass the
-generator entirely.
+`ThemeProvider`. Options: `primary`, `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.
+
+Borders are hairline by default — 1px warm grey (`#D9D5CE` structural,
+`#E7E4DE` row rules), with near-black kept for type and for control hover
+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" })`.
 
@@ -44,7 +51,7 @@ Need just the antd theme object (e.g. for Storybook)? `createHisd3Theme({ primar
 ```tsx
 import {
   HISD3Sidebar, HISD3PageHeader, HISD3PageBody, HISD3SearchInput, HISD3Tabs,
-  HISD3Table, HISD3Tag, HISD3Button,
+  HISD3Table, HISD3Tag, HISD3Button, HISD3HeaderActions, HISD3NotificationButton, HISD3AvatarMenu,
 } from "hisd3-ui-kit";
 
 const menuItems = [
@@ -66,6 +73,7 @@ const menuItems = [
   onLogout={logout}
   bareContent      // let HISD3PageHeader own the gutters
   hideHeaderBar    // HISD3PageHeader renders the top bar
+  hideAccountCard  // account lives in the header instead (HISD3AvatarMenu)
 >
   <HISD3PageHeader
     title="Billing Folios"
@@ -74,6 +82,14 @@ const menuItems = [
     extra={<>
       <HISD3Button icon={<ReloadOutlined />}>Refresh</HISD3Button>
       <HISD3Button variant="primary" icon={<PlusOutlined />}>New folio</HISD3Button>
+      <HISD3HeaderActions divided>
+        <HISD3NotificationButton
+          items={notifications}
+          onMarkAllRead={markAllRead}
+          onSeeAll={() => router.push("/notifications")}
+        />
+        <HISD3AvatarMenu account={currentUser} avatarSrc={currentUser.photoUrl} onLogout={logout} />
+      </HISD3HeaderActions>
     </>}
   />
   <HISD3PageBody>
@@ -94,22 +110,40 @@ const menuItems = [
 | Component | What it is |
 | --- | --- |
 | `HISD3Provider` | Root theme provider (see above). |
-| `HISD3Sidebar` | App shell: 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`. |
-| `HISD3PageHeader` / `HISD3PageBody` | Sticky top bar (breadcrumb left, actions right) plus large title + subtitle; `HISD3PageBody` is the matching padded content area. |
+| `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`. |
+| `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 (uppercase muted headers, 2px row rules) 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`. |
 | `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). |
-| `UserMenu` | The account dropdown on its own. |
+| `HISD3HeaderActions` | Spacing wrapper for the top-right controls; `divided` inserts a rule before the last child. |
+| `HISD3NotificationButton` | Soft-grey circular bell button (Facebook-style) with an unread badge; tints to the primary color while its panel is open. Props: `items` (`{ id, title, description, time, unread, avatarSrc, icon, onClick }`), `count` (defaults to the unread tally), `loading`, `size` (default 40), `onMarkAllRead`, `onSeeAll`, `emptyText`. |
+| `HISD3AvatarMenu` | Circular avatar button with a small chevron badge (Facebook-style); clicking it opens a menu with the signed-in identity plus Settings and Logout (confirm dialog by default). Falls back to initials on a grey circle when there is no photo. Props: `account`, `avatarSrc`, `settingsUrl` / `onSettings`, `onLogout`, `confirmLogout`, `extraItems`, `shape` (`circle` \| `square`), `size` (default 40), `hideChevron`. |
+| `UserMenu` | The sidebar-footer account card, on its own. |
 
 Theme utilities: `createHisd3Theme`, `hisd3AntdTheme` (red default),
-`HISD3_PRESETS`, `HISD3_NEUTRALS`, `HISD3_FONT_FAMILY`,
+`HISD3_PRESETS`, `HISD3_NEUTRALS`, `HISD3_BORDER_PRESETS`, `borderVarsCss`,
+`HISD3_FONT_FAMILY`,
 `HISD3_FONT_WEIGHT_HEADING` (800) / `HISD3_FONT_WEIGHT_BODY` (400), `HISD3_LAYOUT`,
 `resolvePrimary`, `tint`. Plain antd components (Form, Select, DatePicker,
 Modal, …) inherit the same tokens automatically, so use them freely alongside
 the kit.
 
+### Scrolling
+
+The shell fills exactly one viewport and the content column scrolls inside it,
+so the page header stays pinned and the document never rubber-bands ("bounces")
+past the top or bottom — the behaviour you expect from a desktop app. Nothing to
+configure; pass `scrollContent={false}` to `HISD3Sidebar` if you need the window
+to be the scroller instead (infinite scroll bound to `window`, browser scroll
+restoration, and similar).
+
+Because the scroller is the content column rather than the window, code that
+listens for `window` scroll events or calls `window.scrollTo` inside a page
+needs to target that element instead — for example
+`document.querySelector(".ant-layout-has-sider > .ant-layout")`.
+
 Typography: Archivo throughout, loaded from Google Fonts by the kit — body 400,
 headings 800. The kit defines `--font-body`, `--font-heading` and
 `--font-weight-heading` on `:root`, so your own CSS can use them, and native
@@ -119,7 +153,10 @@ Inside styled-components or CSS you can rely on antd's variables:
 `var(--ant-color-primary)`, `var(--ant-color-primary-bg)`,
 `var(--ant-color-border)`, `var(--ant-color-border-secondary)`,
 `var(--ant-color-text)`, `var(--ant-color-text-tertiary)`,
-`var(--ant-color-bg-layout)`.
+`var(--ant-color-bg-layout)`. The header controls additionally read
+`--hisd3-control-bg` / `--hisd3-control-bg-hover` (the grey circle fill) and
+`--hisd3-popup-radius`, so you can retune them per app without forking the
+components.
 
 ## Migrating
 
@@ -127,6 +164,9 @@ Inside styled-components or CSS you can rely on antd's variables:
 
 - Wrap the app in `HISD3Provider` (the sidebar still works standalone with the red default, but the provider is what lets you pick a primary).
 - The default look changed from teal/rounded to the red/square Backoffice style. To keep teal: `<HISD3Provider primary="teal">`.
+- The shell now scrolls its content column instead of the window (pinned header, no rubber-banding). Pass `scrollContent={false}` to `HISD3Sidebar` to restore window scrolling.
+- Borders are now hairline by default; pass `borders="bold"` to `HISD3Provider` to keep the 2px near-black look.
+- New `hideAccountCard` prop on `HISD3Sidebar` for apps that put the account in the header via `HISD3AvatarMenu`.
 - `HISD3Sidebar`: `logoUrl` and `styledTheme` are now optional; a primary-colored square is shown when there is no logo. `HISD3_COLORS` is deprecated in favour of `HISD3_PRESETS`.
 
 ### from 2.x (antd 5 / ProLayout)