hisd3-ui-kit 2.0.7 → 3.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,107 @@
-# HISD3 UI KIT
+# HISD3 UI Kit
+
+Shared React UI components for HISD3 applications, built on **Ant Design v6**.
+
+```bash
+# npm
+npm install hisd3-ui-kit antd @ant-design/icons styled-components
+# yarn
+yarn add hisd3-ui-kit antd @ant-design/icons styled-components
+# pnpm
+pnpm add hisd3-ui-kit antd @ant-design/icons styled-components
+```
+
+`antd`, `@ant-design/icons`, `styled-components`, `react` and `react-dom` are
+**peer dependencies** — every app installs them once, so there is a single copy
+of antd and one `ConfigProvider` theme chain.
+
+| Peer                | Version   |
+| ------------------- | --------- |
+| `antd`              | `^6.0.0`  |
+| `@ant-design/icons` | `^6.0.0`  |
+| `styled-components` | `^6.1.0`  |
+| `react` / `react-dom` | `>=18`  |
+
+## Usage
+
+```tsx
+import { HISD3Sidebar, hisd3AntdTheme, ThemeMode } from "hisd3-ui-kit";
+import { DashboardOutlined, TeamOutlined } from "@ant-design/icons";
+
+const menuItems = [
+  { path: "/dashboard", name: "Dashboard", icon: <DashboardOutlined /> },
+  {
+    path: "/patients",
+    name: "Patients",
+    icon: <TeamOutlined />,
+    children: [
+      { path: "/patients/list", name: "Patient List" },
+      { path: "/patients/admit", name: "Admission" },
+    ],
+  },
+];
+
+export default function AppShell({ children }) {
+  return (
+    <HISD3Sidebar
+      appName="Atlas HIS"
+      logoUrl="/logo.svg"
+      account={currentUser}          // { id, fullName, positionType, ... }
+      menuItems={menuItems}
+      pathname={location.pathname}   // highlights the active item
+      onLogout={logout}
+      styledTheme={{ palette: { mode: ThemeMode.LIGHT } }}
+    >
+      {children}
+    </HISD3Sidebar>
+  );
+}
+```
+
+### `HISD3Sidebar` props
+
+| Prop                  | Type                                     | Default            | Notes |
+| --------------------- | ---------------------------------------- | ------------------ | ----- |
+| `account`             | `IUserEmployee`                          | —                  | Shown in the account dropdown. |
+| `appName`, `logoUrl`  | `string`                                 | —                  | Brand block (links to `/`). |
+| `menuItems`           | `HISD3MenuItem[]`                        | —                  | `{ path, name, icon, children, hideInMenu, disabled, group }` — same shape as the previous ProLayout `MenuDataItem`. |
+| `pathname`            | `string`                                 | —                  | Current route; longest matching `path` is selected and its submenu opened. |
+| `onLogout`            | `() => void \| Promise<void>`            | —                  | Called after the user confirms the logout dialog. |
+| `styledTheme`         | `StyledTheme`                            | —                  | Passed to styled-components `ThemeProvider`. |
+| `collapsed` / `onCollapse` | `boolean` / `(c: boolean) => void`  | `false`            | Controlled or uncontrolled collapse. Auto-collapses below the `lg` breakpoint. |
+| `layoutTop`           | `boolean`                                | `false`            | Horizontal header navigation instead of a left sider. |
+| `hideSidebar`         | `boolean`                                | `false`            | Render only `children`. |
+| `loading`             | `boolean`                                | `false`            | Wraps content in a `Spin`. |
+| `avatarSrc`           | `string`                                 | initials           | Falls back to the user's initials. |
+| `settingsUrl`         | `string`                                 | `/settings`        | Target of the *Settings* menu entry. |
+| `antdTheme`           | `ThemeConfig \| null`                    | `hisd3AntdTheme`   | Applied through a nested `ConfigProvider`; pass `null` to inherit the app's theme as-is. |
+| `renderMenuLink`      | `(item, label) => ReactNode`             | `<a href>`         | Use react-router: `(item, label) => <Link to={item.path!}>{label}</Link>`. |
+| `headerExtra`         | `ReactNode`                              | —                  | Extra header content (notifications, search, …). |
+| `userMenuItems`       | `MenuProps["items"]`                     | —                  | Extra entries prepended to the account dropdown. |
+| `hideCollapseTrigger` | `boolean`                                | `false`            | |
+| `siderWidth`          | `number`                                 | `220`              | |
+| `bareContent`         | `boolean`                                | `false`            | Skip the padded `Content` wrapper. |
+
+### Other exports
+
+- `hisd3AntdTheme` / `HISD3_COLORS` — the HISD3 Ant Design theme tokens. Use `hisd3AntdTheme` in your own root `<ConfigProvider theme={hisd3AntdTheme}>` so every antd component in the app (not just the shell) is on brand.
+- `UserMenu` — the account dropdown on its own.
+- `StyledTheme`, `IUserEmployee`, `HISD3MenuItem` types and the theme enums (`ThemeMode`, `LayoutType`, `NavStyle`, …).
+
+## Migrating from 2.x (antd 5 / ProLayout)
+
+1. Upgrade the app to antd 6 and React 18+: `pnpm add antd@^6 @ant-design/icons@^6`. antd 6 drops the `@ant-design/v5-patch-for-react-19` shim — remove it if present. Follow the [antd v5 → v6 migration guide](https://ant.design/docs/react/migration-v6) for your own components.
+2. `@ant-design/pro-layout` and `@ant-design/pro-provider` are no longer used or pulled in by the kit. Remove them from your app unless you use them directly (note: the stable pro packages do not support antd 6).
+3. `HISD3Sidebar` keeps the same required props (`account`, `logoUrl`, `appName`, `menuItems`, `onLogout`, `pathname`, `styledTheme`) and the same `menuItems` shape. Menu items are rendered with plain `<a href>` by default, exactly as before; pass `renderMenuLink` for client-side routing.
+4. The `hisd3-ui-kit/Sidebar` sub-path export was removed — import `HISD3Sidebar` from the package root.
+5. The logout confirmation now uses `App.useApp().modal` so it respects the theme. No change needed in consumers.
+
+## 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.