hisd3-ui-kit 2.0.8 → 4.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 HISD3
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 HISD3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,147 @@
-# HISD3 UI KIT
+# HISD3 UI Kit
+
+Shared React UI components for HISD3 applications, built on **Ant Design v6**.
+One install gives every app the same "Backoffice" look — square corners, 2px
+borders, Archivo type, grouped sidebar — with a primary color you choose per app.
+
+```bash
+pnpm add hisd3-ui-kit antd @ant-design/icons styled-components
+# npm i / yarn add work the same
+```
+
+`antd`, `@ant-design/icons`, `styled-components`, `react` and `react-dom` are
+**peer dependencies** — each app installs them once so there is a single antd
+copy and one theme chain.
+
+| Peer                  | Version  |
+| --------------------- | -------- |
+| `antd`                | `^6.0.0` |
+| `@ant-design/icons`   | `^6.0.0` |
+| `styled-components`   | `^6.1.0` |
+| `react` / `react-dom` | `>=18`   |
+
+## 1. Wrap the app once
+
+```tsx
+import { HISD3Provider } from "hisd3-ui-kit";
+
+<HISD3Provider primary="red">     {/* "red" | "orange" | "teal" | "blue" | "green" | "purple" | "#hex" */}
+  <App />
+</HISD3Provider>
+```
+
+`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.
+
+Need just the antd theme object (e.g. for Storybook)? `createHisd3Theme({ primary: "teal" })`.
+
+## 2. Build a page
+
+```tsx
+import {
+  HISD3Sidebar, HISD3PageHeader, HISD3PageBody, HISD3SearchInput, HISD3Tabs,
+  HISD3Table, HISD3Tag, HISD3Button,
+} from "hisd3-ui-kit";
+
+const menuItems = [
+  { path: "/dashboard", name: "Dashboard", icon: <AppstoreOutlined /> },
+  { key: "rc", name: "Receivables and Collections", group: true, children: [
+    { path: "/billing", name: "Billing", icon: <FileTextOutlined />, children: [
+      { path: "/billing/folios", name: "Billing Folios" },
+      { path: "/billing/otc", name: "OTC Transaction" },
+    ]},
+    { path: "/cashiering", name: "Cashiering", icon: <BankOutlined /> },
+  ]},
+];
+
+<HISD3Sidebar
+  appName="Backoffice"
+  menuItems={menuItems}
+  pathname={location.pathname}
+  account={currentUser}
+  onLogout={logout}
+  bareContent      // let HISD3PageHeader own the gutters
+  hideHeaderBar    // HISD3PageHeader renders the top bar
+>
+  <HISD3PageHeader
+    title="Billing Folios"
+    subtitle="Manage your billing records"
+    breadcrumb={[{ title: "Receivables and Collections", href: "/rc" }, { title: "Billing" }]}
+    extra={<>
+      <HISD3Button icon={<ReloadOutlined />}>Refresh</HISD3Button>
+      <HISD3Button variant="primary" icon={<PlusOutlined />}>New folio</HISD3Button>
+    </>}
+  />
+  <HISD3PageBody>
+    <HISD3SearchInput placeholder="Search patients, bill no. or case" />
+    <HISD3Tabs items={[{ key: "all", label: "All Patients", count: 10 }, { key: "opd", label: "Outpatient", count: 2 }]} />
+    <HISD3Table
+      columns={columns}
+      dataSource={rows}
+      footer="Outstanding on this page"
+      pagination={{ current, pageSize, total: 7223, onChange: (p, s) => ... }}
+    />
+  </HISD3PageBody>
+</HISD3Sidebar>
+```
+
+## Components
+
+| 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. |
+| `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. |
+
+Theme utilities: `createHisd3Theme`, `hisd3AntdTheme` (red default),
+`HISD3_PRESETS`, `HISD3_NEUTRALS`, `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.
+
+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
+`h1`–`h6` (and antd `Typography.Title`) pick up the heading weight automatically.
+
+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)`.
+
+## Migrating
+
+### 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).
+- The default look changed from teal/rounded to the red/square Backoffice style. To keep teal: `<HISD3Provider primary="teal">`.
+- `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)
+
+1. Upgrade the app to antd 6 and React 18+: `pnpm add antd@^6 @ant-design/icons@^6`; remove `@ant-design/v5-patch-for-react-19`. Follow the [antd v5 → v6 guide](https://ant.design/docs/react/migration-v6) for your own components.
+2. Remove `@ant-design/pro-layout` / `@ant-design/pro-provider` unless you use them directly (their stable releases do not support antd 6).
+3. `HISD3Sidebar` keeps the same required props and `menuItems` shape.
+4. The `hisd3-ui-kit/Sidebar` sub-path was removed — import from the package root.
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # rollup → dist/index.js (ESM), dist/index.cjs.js (CJS), dist/index.d.ts
+pnpm typecheck
+```
+
+Publishing runs `build` automatically (`prepublishOnly`). Only `dist/`, `README.md` and `LICENSE` are published.