@crystaltech/hsms-shared-ui 0.5.30 → 0.5.31-alpha-1

package/README.md

@@ -1,946 +1,282 @@
-# hsms-shared-ui
+# HSMS Shared UI
 
-## HSMS-UI Documentation
-
-### Overview
-
-`@crystaltech/hsms-shared-ui` is a customizable UI component library built with React and Material-UI. It provides a structured layout system with a `MainLayout` component, theme customization, and configurable navigation options for web applications.
-
----
+A reusable React + MUI component library for HSMS applications, including a configurable layout, theme tools, and UI primitives.
 
 ## Installation
 
-To install the package, run:
-
-```sh
-pnpm install @crystaltech/hsms-shared-ui@latest
-```
-
-or using Yarn:
-
-```sh
-yarn add @crystaltech/hsms-shared-ui@latest
-```
-
----
-
-## Usage
-
-### Must Follow
-
-Create a `types` folder inside the `src` directory and add the following file:
-
-```
-/src/types/hsms-shared-ui.d.ts
-```
-
-**Note:** Make sure to add the following content to the `hsms-shared-ui.d.ts` file:
+- pnpm: `pnpm add @crystaltech/hsms-shared-ui`
+- yarn: `yarn add @crystaltech/hsms-shared-ui`
+- npm: `npm i @crystaltech/hsms-shared-ui`
 
-```ts
-declare module "@crystaltech/hsms-shared-ui";
-```
+Peer deps (match your app): `@mui/material`, `@mui/icons-material`, `@mui/x-date-pickers`, `@emotion/*`, `react`, `react-dom`, `dayjs`, `react-perfect-scrollbar`, `simplebar-react`.
 
-### Theme Component Setup
+### Using in other modules
 
-Wrap your root component with the Theme Customization component and pass theme object as a prop to the component. The prop name is defaultTheme, like this,
-
-```ts
-import { ThemeCustomization } from "@anwarhossain1/hsms-ui";
-import ReactDOM from "react-dom/client";
-import { BrowserRouter } from "react-router-dom";
-import App from "./App";
-import "./index.css";
-import reportWebVitals from "./reportWebVitals";
-const defaultTheme = {
-  palette: {
-    mode: "light",
-    navbar: {
-      background: "#000000",
-      foreground: "#000000",
-    },
-    sidebar: {
-      background: "#000000",
-      foreground: "#000000",
-    },
-    primary: {
-      main: "#ef5350", // You can change this color
-    },
-    secondary: {
-      main: "#f8fafc",
-    },
-    background: {
-      default: "#f8fafc",
-      paper: "#ffffff",
-    },
-    text: {
-      primary: "#1e293b",
-      secondary: "#64748b",
-    },
-    neutral: {
-      100: "#f6f9fc",
-      200: "#e9ecef",
-      300: "#dee2e6",
-      400: "#ced4da",
-      500: "#adb5bd",
-      600: "#868e96",
-      700: "#495057",
-      800: "#343a40",
-      900: "#212529",
-    },
-  },
-  typography: {
-    fontFamily: "Roboto",
-    h1: {
-      fontSize: "2.5rem",
-      fontWeight: 700,
-      lineHeight: "3rem",
-    },
-    h2: {
-      fontSize: "2rem",
-      fontWeight: 700,
-      lineHeight: "2.5rem",
-    },
-    h3: {
-      fontSize: "1.75rem",
-      fontWeight: 600,
-      lineHeight: "2.25rem",
-    },
-    h4: {
-      fontSize: "1.5rem",
-      fontWeight: 600,
-      lineHeight: "2rem",
-    },
-    h5: {
-      fontSize: "1.25rem",
-      fontWeight: 500,
-      lineHeight: "1.75rem",
-    },
-    h6: {
-      fontSize: "1rem",
-      fontWeight: 500,
-      lineHeight: "1.5rem",
-    },
-    subtitle1: {
-      fontSize: "1.125rem",
-      fontWeight: 400,
-      lineHeight: "1.5rem",
-    },
-    subtitle2: {
-      fontSize: "1rem",
-      fontWeight: 400,
-      lineHeight: "1.25rem",
-    },
-    body1: {
-      fontSize: "1rem",
-      fontWeight: 400,
-      lineHeight: "1.5rem",
-    },
-    body2: {
-      fontSize: "0.875rem",
-      fontWeight: 400,
-      lineHeight: "1.25rem",
-    },
-    button: {
-      fontSize: "0.875rem",
-      fontWeight: 500,
-      lineHeight: "1.25rem",
-      textTransform: "uppercase",
-    },
-    caption: {
-      fontSize: "0.75rem",
-      fontWeight: 400,
-      lineHeight: "1rem",
-    },
-    overline: {
-      fontSize: "0.75rem",
-      fontWeight: 400,
-      lineHeight: "1rem",
-      textTransform: "uppercase",
-    },
-  },
-};
-const root = ReactDOM.createRoot(document.getElementById("root"));
-root.render(
-  <ThemeCustomization defaultTheme={defaultTheme}>
-    <BrowserRouter>
-      <App />
-    </BrowserRouter>
-  </ThemeCustomization>
-);
-
-// If you want to start measuring performance in your app, pass a function
-// to log results (for example: reportWebVitals(console.log))
-// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
-reportWebVitals();
-```
+- Install typings (TypeScript projects):
+  - `pnpm add -D typescript @types/react @types/react-dom`
+- Configure TypeScript:
+  - `tsconfig.json`:
+    - `compilerOptions.jsx: "react-jsx"`
+    - `compilerOptions.moduleResolution: "bundler"` (or `"node"`)
+    - `compilerOptions.skipLibCheck: true` (optional)
+- Import components:
+  - `import { MainLayout, ThemeSetting, CustomButton } from '@crystaltech/hsms-shared-ui';`
+- Import types (optional):
+  - `import type { ITheme } from '@crystaltech/hsms-shared-ui/dist/theme/defaultTheme';`
+  - `import type { ILayoutConfig } from '@crystaltech/hsms-shared-ui/dist/components/layout/MainLayout';`
+- JavaScript projects:
+  - Enable type suggestions: add `// @ts-check` to files or use JSDoc typedefs.
+  - In VS Code ensure: `javascript.suggest.autoImports` and `typescript.suggest.autoImports` are enabled.
+- Monorepo linking:
+  - Use workspace linking or `pnpm link` and restart the TS server if auto-import suggestions don’t show.
 
-The whole project will contain properties of the theme object. This object will laterly come from API.
+## Quick Start (Theme)
 
-### Importing Components
+Wrap your app with `ThemeCustomization` and use `ThemeSetting` to edit and persist the theme.
 
 ```tsx
-import { MainLayout } from "@crystaltech/hsms-shared-ui";
-import { Routes, Route } from "react-router-dom";
-
-import { menuConfig, settingsConfig } from "./dummyData";
+import { ThemeCustomization, ThemeSetting } from "@crystaltech/hsms-shared-ui";
+import { defaultTheme, ITheme } from "@crystaltech/hsms-shared-ui/dist/theme/defaultTheme";
 
-const layoutConfig = {
-  navbar: {
-    showHamburgerInMobile: true,
-    themeToggler: false,
-  },
-  sideDrawer: {
-    menuConfig,
-    settingsConfig: settingsConfig,
-    isMinimized: false,
-    drawerWidth: 240,
-  },
-  footerText: settingsConfig.footerText,
-};
-
-function App() {
+export default function App() {
+  const [theme, setTheme] = useState<ITheme>(defaultTheme);
+  const handleSave = async (next: ITheme) => { setTheme(next); return next; };
   return (
-    <MainLayout layoutConfig={layoutConfig}>
-      <Routes>{/* Your routes with components */}</Routes>
-    </MainLayout>
+    <ThemeCustomization defaultTheme={theme}>
+      <ThemeSetting theme={theme} onSave={handleSave} />
+    </ThemeCustomization>
   );
 }
-
-export default App;
 ```
 
----
-
-## Components
-
-### 1. `MainLayout`
-
-A flexible layout component that includes a Navbar, Sidebar, and Footer.
-
-**Props:**
+## Theme Model
 
-| Prop           | Type   | Description                             |
-| -------------- | ------ | --------------------------------------- |
-| `layoutConfig` | Object | Configures navbar, sidebar, and footer. |
+- `ITheme` lives in `src/theme/defaultTheme.ts` and includes `palette` (navbar, sidebar, primary/secondary, background, text, neutral) and `typography`.
+- Use `defaultTheme` as a starting point; pass a new object to re-theme.
 
----
+## Layout
 
-### 2. `ThemeCustomization`
-
-A wrapper component that provides theme customization for Material-UI.
-
-**Usage:**
-Wrap your application inside `<ThemeCustomization>` to apply global styles.
+### MainLayout
+- Props: `title: string`, `layoutConfig: ILayoutConfig`, `logoutHandler?: () => Promise<void>`
+- `ILayoutConfig`:
+  - `userManage?: { user: UserInfo; redirectUrl: string }`
+  - `navbar: { showHamburgerInMobile: boolean; themeToggler: boolean }`
+  - `sideDrawer: { menuConfig: IMenuConfig[]; settingsConfig: ISettingsConfig; isMinimized: boolean; drawerWidth: number }`
+  - `footerText: string`
 
+Example:
 ```tsx
-<ThemeCustomization defaultTheme={}>
-  {" "}
-  // pass the DefaultTheme object either manually or from api
-  <MainLayout layoutConfig={layoutConfig}>{/* Your content here */}</MainLayout>
-</ThemeCustomization>
-```
-
-as we don't have api right now for ThemeCustomization component, we can use the given variable and pass it as a props
-
-```ts
-const defaultTheme = {
-  palette: {
-    mode: "light",
-    navbar: {
-      background: "#000000",
-      foreground: "#000000",
-    },
-    sidebar: {
-      background: "#000000",
-      foreground: "#000000",
-    },
-    primary: {
-      main: "#ef5350", // You can change this color
-    },
-    secondary: {
-      main: "#f8fafc",
-    },
-    background: {
-      default: "#f8fafc",
-      paper: "#ffffff",
-    },
-    text: {
-      primary: "#1e293b",
-      secondary: "#64748b",
-    },
-    neutral: {
-      100: "#f6f9fc",
-      200: "#e9ecef",
-      300: "#dee2e6",
-      400: "#ced4da",
-      500: "#adb5bd",
-      600: "#868e96",
-      700: "#495057",
-      800: "#343a40",
-      900: "#212529",
-    },
-  },
-  typography: {
-    fontFamily: "Roboto",
-    h1: {
-      fontSize: "2.5rem",
-      fontWeight: 700,
-      lineHeight: "3rem",
-    },
-    h2: {
-      fontSize: "2rem",
-      fontWeight: 700,
-      lineHeight: "2.5rem",
-    },
-    h3: {
-      fontSize: "1.75rem",
-      fontWeight: 600,
-      lineHeight: "2.25rem",
-    },
-    h4: {
-      fontSize: "1.5rem",
-      fontWeight: 600,
-      lineHeight: "2rem",
-    },
-    h5: {
-      fontSize: "1.25rem",
-      fontWeight: 500,
-      lineHeight: "1.75rem",
-    },
-    h6: {
-      fontSize: "1rem",
-      fontWeight: 500,
-      lineHeight: "1.5rem",
-    },
-    subtitle1: {
-      fontSize: "1.125rem",
-      fontWeight: 400,
-      lineHeight: "1.5rem",
-    },
-    subtitle2: {
-      fontSize: "1rem",
-      fontWeight: 400,
-      lineHeight: "1.25rem",
-    },
-    body1: {
-      fontSize: "1rem",
-      fontWeight: 400,
-      lineHeight: "1.5rem",
-    },
-    body2: {
-      fontSize: "0.875rem",
-      fontWeight: 400,
-      lineHeight: "1.25rem",
-    },
-    button: {
-      fontSize: "0.875rem",
-      fontWeight: 500,
-      lineHeight: "1.25rem",
-      textTransform: "uppercase",
-    },
-    caption: {
-      fontSize: "0.75rem",
-      fontWeight: 400,
-      lineHeight: "1rem",
-    },
-    overline: {
-      fontSize: "0.75rem",
-      fontWeight: 400,
-      lineHeight: "1rem",
-      textTransform: "uppercase",
-    },
-  },
-};
-```
-
----
-
-## Configuration Options
-
-The `layoutConfig` object provides the following options:
+import { MainLayout } from "@crystaltech/hsms-shared-ui";
+import { menuConfig, settingsConfig } from "@crystaltech/hsms-shared-ui/dist/components/layout/layoutConfig";
 
-```js
 const layoutConfig = {
-  navbar: {
-    showHamburgerInMobile: true,
-    themeToggler: false,
-  },
-  sideDrawer: {
-    menuConfig,
-    settingsConfig,
-    isMinimized: false,
-    drawerWidth: 240,
-  },
-  footerText: "Your Footer Text Here",
+  navbar: { showHamburgerInMobile: true, themeToggler: false },
+  sideDrawer: { menuConfig, settingsConfig, isMinimized: false, drawerWidth: 260 },
+  userManage: { user, redirectUrl: "/login" },
+  footerText: "© 2025 All rights reserved",
 };
-```
-
----
-
-### 3. `CustomButton`
-
-CustomButton import examples
-
-```ts
-<CustomButton variant="outlined">Hello</CustomButton>
-<CustomButton variant="text">Hello</CustomButton>
-<CustomButton variant="outlined" startIcon={<DeleteIcon />}>
-  Hello
-</CustomButton>
-<CustomButton endIcon={<SendIcon />}>Hello</CustomButton>
-<CustomButton endIcon={<SendIcon />} loading>
-  Hello
-</CustomButton>
 
+<MainLayout title="HSMS" layoutConfig={layoutConfig}>
+  {/* children */}
+</MainLayout>
 ```
 
-Button Props Inside CustomButton
+### MainlayoutWithWrapper
+- Wraps `MainLayout` with a `BrowserRouter`. Use when you don’t already have a router at the app root.
 
-```ts
-interface CustomButtonProps extends ButtonProps {
-  startIcon?: React.ReactNode;
-  endIcon?: React.ReactNode;
-  loading?: boolean;
-}
+### RoutesConfigLayout
+- Props: `pageTitle`, `user`, `authenticated`, `userRoles?`, `clients?`, `loginMethod`, `logoutHandler`, `redirectPath?`, `pages`, `publicRoutes?`, `Layout?`, `mainLayoutConfig`, `NotFoundPage?`.
+- Builds routes from `pages` and protects them via `ProtectedRoute`.
 
-const CustomButton: React.FC<CustomButtonProps> = ({
-  variant = "contained",
-  startIcon,
-  endIcon,
-  loading = false,
-  disabled = false,
-  children,
-  onClick,
-  ...props
-}) => {
-  return (
-    <Button
-      variant={variant}
-      startIcon={!loading ? startIcon : null}
-      endIcon={!loading ? endIcon : null}
-      disabled={disabled || loading}
-      onClick={onClick}
-      {...props}
-    >
-      {loading ? <CircularProgress size={24} color="inherit" /> : children}
-    </Button>
-  );
-};
+Example (static pages map):
+```tsx
+import { RoutesConfigLayout } from "@crystaltech/hsms-shared-ui";
+import Home from "./pages/index";
+import TablePage from "./pages/table";
+
+const pages = {
+  "/src/pages/index.tsx": { default: Home },
+  "/src/pages/table/index.tsx": { default: TablePage, roles: ["admin"] },
+} satisfies import("@crystaltech/hsms-shared-ui/dist/routes/RoutesConfigLayout").IPages;
+
+<RoutesConfigLayout
+  pageTitle="HSMS"
+  user={user}
+  authenticated={isAuthenticated}
+  loginMethod={login}
+  logoutHandler={logout}
+  redirectPath="/login"
+  pages={pages}
+  publicRoutes={[{ path: "/about", element: <About /> }]}
+  mainLayoutConfig={layoutConfig}
+/>
 ```
 
-### 4. `CustomIconButton`
-
-`Example`
+`UserInfo` supports `realm_access.roles` and per-client roles (`resource_access[client].roles`). Route-level `roles` override global roles if provided.
 
-```ts
-<CustomIconButton aria-label="delete">
-  <DeleteIcon />
-</CustomIconButton>
-<CustomIconButton aria-label="delete" color="primary">
-  <AlarmIcon />
-</CustomIconButton>
-<CustomIconButton aria-label="delete" color="secondary">
-  <AlarmIcon />
-</CustomIconButton>
-```
+## Data Table
 
-`Props`
+### MultiDynamicTable
+- Props: `tableData: DataStructure`, `rowsPerPage: number`, `page: number`, `handleChangePage`, `handleChangeRowsPerPage`.
+- Features: sticky headers, column visibility toggling, keyword filter (`CustomInput`), pagination.
 
+Types (inferred):
 ```ts
-import { IconButton, IconButtonProps } from "@mui/material";
-
-interface CustomIconButtonProps extends IconButtonProps {
-  children: React.ReactNode;
-}
-
-const CustomIconButton: React.FC<CustomIconButtonProps> = ({
-  children,
-  ...props
-}) => {
-  return <IconButton {...props}>{children}</IconButton>;
+export type FieldContentActionsProps = {
+  label: string;
+  icon?: React.ReactNode;
+  onClick: (item: FieldItem) => void;
+  variant?: "outlined" | "filled";
 };
-
-export default CustomIconButton;
-```
-
-### 5. `CustomTabs`
-
-`USAGE`
-
-```ts
-const tabsData = [
-  { label: "Tab One", value: "one" },
-  { label: "Tab Two", value: "two" },
-  { label: "Tab Three", value: "three" },
-];
-
-const [selectedTab, setSelectedTab] = useState(tabsData[0].value);
-
-const handleTabsChange = (event: React.SyntheticEvent, value: string) => {
-  setSelectedTab(value);
+export type DatePickerProps = { date: string; onChange?: (item: FieldItem, date: Date) => void };
+export type FieldItem = {
+  id: number; // same across rows for a column
+  fieldName: string;
+  isVisible: boolean;
+  fieldType: "text" | "date" | "link" | "label" | "actions" | "date-picker";
+  fieldContent: string | DatePickerProps | FieldContentActionsProps[];
+  to?: string; // for link
 };
-
-<CustomTabs
-  tabs={tabsData}
-  value={selectedTab}
-  onChange={handleTabsChange}
-  variant="scrollable" //tabs others props can be passed
-/>;
-```
-
-### 6. `CustomTextField`
-
-you can pass existing Mui Textfield's pass into it too
-
-```ts
-<CustomTextField
-  value={name}
-  onChange={(value) => setName(value)}
-  label="Name"
-/>
+export type FieldItemArray = FieldItem[];
+export type DataStructure = FieldItem[][]; // rows => columns
 ```
 
-### 7. `CustomAutoComplete`
+Example data:
+```tsx
+import { MultiDynamicTable } from "@crystaltech/hsms-shared-ui";
+import Visibility from "@mui/icons-material/Visibility";
 
-```ts
-const moviesData = [
-  { title: "The Shawshank Redemption", year: 1994 },
-  { title: "The Godfather", year: 1972 },
+const dynamicTableData: DataStructure = [
+  [
+    { id: 1, fieldName: "Name",    isVisible: true, fieldType: "link",  fieldContent: "Alice", to: "/users/1" },
+    { id: 2, fieldName: "Status",  isVisible: true, fieldType: "label", fieldContent: "Active" },
+    { id: 3, fieldName: "Joined",  isVisible: true, fieldType: "date",  fieldContent: "2025-01-01" },
+    { id: 4, fieldName: "Actions", isVisible: true, fieldType: "actions", fieldContent: [
+      { label: "View", icon: <Visibility />, variant: "outlined", onClick: (item) => console.log(item) },
+    ] },
+    { id: 5, fieldName: "Reminder", isVisible: true, fieldType: "date-picker", fieldContent: {
+      date: "2025-01-05", onChange: (item, date) => console.log(item, date)
+    } },
+  ],
+  [
+    { id: 1, fieldName: "Name",    isVisible: true, fieldType: "link",  fieldContent: "Bob", to: "/users/2" },
+    { id: 2, fieldName: "Status",  isVisible: true, fieldType: "label", fieldContent: "Inactive" },
+    { id: 3, fieldName: "Joined",  isVisible: true, fieldType: "date",  fieldContent: "2024-12-01" },
+    { id: 4, fieldName: "Actions", isVisible: true, fieldType: "actions", fieldContent: [] },
+    { id: 5, fieldName: "Reminder", isVisible: true, fieldType: "date-picker", fieldContent: { date: "2025-02-01" } },
+  ],
 ];
 
-<CustomAutoComplete
-  label="Select multiple movies"
-  options={moviesData}
-  getOptionLabel={(option) => option.title}
-  onChange={(value) => console.log(value)}
-  multiple
-/>;
-
-if you want to see multiple section pass multiple as a prop otherwise no need to pass multiple
-```
-
-### 8. `AsyncAutoComplete`
-
-for passing data at the time of user interaction (api fetch) use this component
-
-```ts
-<AsyncAutocomplete
-  label="Select a Movie"
-  fetchOptions={fetchMovies}
-  getOptionLabel={(option) => option.title}
-  isOptionEqualToValue={(option, value) => option.title === value.title}
-  onChange={(selectedMovie) => console.log("Selected movie:", selectedMovie)}
-  multiple
+<MultiDynamicTable
+  tableData={dynamicTableData}
+  page={0}
+  rowsPerPage={10}
+  handleChangePage={(_, p) => setPage(p)}
+  handleChangeRowsPerPage={(e) => setRowsPerPage(parseInt(e.target.value, 10))}
 />
 ```
 
-### 9. `CustomSelect (DropDown)`
+## UI Components
 
-```ts
-const ageOptions = [
-  { value: 10, label: "Ten" },
-  { value: 20, label: "Twenty" },
-  { value: 30, label: "Thirty" },
-];
+All components are re-exported from `src/index.ts`.
 
-const [age, setAge] = useState("");
+- CustomButton
+  - Extends MUI `ButtonProps`; adds `startIcon`, `endIcon`, `loading`.
+  - `loading` disables the button and shows a spinner.
 
-const handleAgeChange = (event: SelectChangeEvent) => {
-  setAge(event.target.value as string);
-};
+- CustomIconButton
+  - Thin wrapper over MUI `IconButton` that always renders `children` icon.
 
-<CustomSelect
-  label="Age"
-  value={age}
-  options={ageOptions}
-  onChange={handleAgeChange}
-/>;
-```
+- CustomInput
+  - Props: `startIcon?`, `placeholder?`, `onChange?(value)`, `count?`, `onClear?`.
+  - Shows count badge and clear button when not empty.
 
-### 10. `CustomCheckbox & CustomRadioGroup`
+- CustomCheckbox
+  - Props: `checked?`, `onChange?(checked)`, `label?`. Manages internal state.
 
-```ts
-const radioOptions = [
-  { label: "Female", value: "female" },
-  { label: "Male", value: "male" },
-  { label: "Other", value: "other" },
-];
+- CustomRadioGroup
+  - Props: `label`, `options: {label,value}[]`, `value`, `onChange(value)`.
 
-const [checked, setChecked] = useState<boolean>(false);
-const [selectedValue, setSelectedValue] = useState(radioOptions[0].value);
+- CustomSelect
+  - Props: `label`, `value`, `options: { value: string|number; label: string }[]`, `onChange(SelectChangeEvent)`.
 
-<CustomCheckbox checked={checked} label="CheckBox" onChange={setChecked} />
+- CustomSwitch
+  - Props: `checked`, `onChange(checked)`.
 
-<CustomRadioGroup
-  label="Gender"
-  options={radioOptions}
-  value={selectedValue}
-  onChange={(value) => setSelectedValue(value)}
-/>
+- CustomTabs
+  - Props: `tabs: {label,value}[]`, `value`, `onChange(event,value)`, plus `TabsProps`.
 
-```
+- CustomDatePicker
+  - Props: `label`, `value: Dayjs|null`, `onChange(Dayjs|null|undefined)`; clearable.
 
-### 11. `Selectable List`
+- ControlledDatePicker
+  - Props: `label?`, `initialValue?: string`, `onChange?(Dayjs|null)`; manages its own state.
 
-```ts
-const items = [
-  { label: "Inbox", icon: <InboxIcon /> },
-  { label: "Drafts", icon: <DraftsIcon /> },
-  { label: "Trash" }, // No icon
-  { label: "Spam" }, // No icon
-];
+- CustomColorPicker
+  - Props: `initialColor?`, `onChange(color)`; uses `react-color` `SketchPicker`.
 
-<CustomSelectableList items={items} onSelect={(index) => console.log(index)} />;
-```
+- CustomScrollbar
+  - Props: `children`, `maxWidth?`, `maxHeight?`; wraps `simplebar-react`.
 
-### 12. `MultiDynamicTable`
+- AsyncAutocomplete<T>
+  - Props: `label`, `multiple?`, `fetchOptions()`, `getOptionLabel`, `isOptionEqualToValue`, `onChange?`.
+  - Fetches options on open; shows loading indicator.
+  - Example:
+    ```tsx
+    <AsyncAutocomplete
+      label="Users"
+      fetchOptions={async () => [{ id:1, name:"Alice" }]}
+      getOptionLabel={(o) => o.name}
+      isOptionEqualToValue={(o,v) => o.id === v.id}
+      onChange={(sel) => console.log(sel)}
+    />
+    ```
 
-#### Data props data structure
+- CheckboxListWithAvatar
+  - Props: `items: { id:number; label:string; avatarSrc? }[]`, `checkedItems?`, `onChange(checkedIds)`.
 
-```ts
-const data: DataStructure = [
-  //Each Array represents as a row
-  [
-    //each object represents a coumn data
-    {
-      id: 0,
-      fieldName: "Title",
-      fieldType: "text",
-      fieldContent: "ajgobi",
-      isDefault: true,
-      isVisible: true,
-    },
-    {
-      id: 1,
-      fieldName: "B",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: true,
-      isVisible: true,
-    },
-    {
-      id: 2,
-      fieldName: "Date",
-      fieldType: "date",
-      fieldContent: "Feb 20, 2025",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 3,
-      fieldName: "D",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 4,
-      fieldName: "Actions",
-      fieldType: "actions",
-      fieldContent: [
-        {
-          label: "Edit",
-          onClick: (data) => {
-            console.log(data);
-          },
-          icon: <EditLocationAlt />,
-          variant: "contained",
-        },
-        {
-          label: "Delete",
-          onClick: (data) => {
-            console.log(data);
-          },
-          icon: <DeleteOutlineSharp />,
-          variant: "outlined",
-        },
-      ],
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 5,
-      fieldName: "Actions",
-      fieldType: "actions",
-      fieldContent: [
-        {
-          label: "Update",
-          onClick: (data) => {
-            console.log(data);
-          },
-          icon: <EditLocationAlt />,
-          variant: "contained",
-        },
-      ],
-
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 6,
-      fieldName: "G",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 7,
-      fieldName: "H",
-      fieldType: "link",
-      fieldContent:
-        "Click me fjaf afjasfjasfj aksfjdajfajsfkjakfjaksfjaksfjkasfjaskfjk sdgs sgfsdg asfjaskfjaskjfaksjfaksfjaskfjaksjfkasfjaskfjaksdfjaskfjaskfjaskfjasfjaskfjaskfjaksjfaskjfkasfjj",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 8,
-      fieldName: "Date Picker",
-      fieldType: "date-picker",
-      fieldContent: {
-        date: "12-12-2022",
-        onChange: (parentItem: FieldItem, timeValue: Date) => {
-          console.log(parentItem, timeValue);
-        },
-      },
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 9,
-      fieldName: "J",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-  ],
-  [
-    {
-      id: 0,
-      fieldName: "A",
-      fieldType: "link",
-      fieldContent: "hello",
-      isDefault: true,
-      isVisible: true,
-    },
-    {
-      id: 1,
-      fieldName: "B",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: true,
-      isVisible: true,
-    },
-    {
-      id: 2,
-      fieldName: "C",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 3,
-      fieldName: "D",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 4,
-      fieldName: "E",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 5,
-      fieldName: "F",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 6,
-      fieldName: "G",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 7,
-      fieldName: "H",
-      fieldType: "link",
-      fieldContent:
-        "Click me fjaf afjasfjasfj aksfjdajfajsfkjakfjaksfjaksfjkasfjaskfjk sdgs sgfsdg asfjaskfjaskjfaksjfaksfjaskfjaksjfkasfjaskfjaksdfjaskfjaskfjaskfjasfjaskfjaskfjaksjfaskjfkasfjj",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 8,
-      fieldName: "I",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 9,
-      fieldName: "J",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-  ],
-  [
-    {
-      id: 0,
-      fieldName: "A",
-      fieldType: "link",
-      fieldContent: "gkkk",
-      isDefault: true,
-      isVisible: true,
-      to: "/habi-jabi",
-    },
-    {
-      id: 1,
-      fieldName: "B",
-      fieldType: "label",
-      fieldContent: "jam me",
-      isDefault: true,
-      isVisible: true,
-    },
-    {
-      id: 2,
-      fieldName: "C",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 3,
-      fieldName: "D",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 4,
-      fieldName: "E",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 5,
-      fieldName: "F",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 6,
-      fieldName: "G",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 7,
-      fieldName: "H",
-      fieldType: "link",
-      fieldContent:
-        "Click me fjaf afjasfjasfj aksfjdajfajsfkjakfjaksfjaksfjkasfjaskfjk sdgs sgfsdg asfjaskfjaskjfaksjfaksfjaskfjaksjfkasfjaskfjaksdfjaskfjaskfjaskfjasfjaskfjaskfjaksjfaskjfkasfjj",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 8,
-      fieldName: "I",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-    {
-      id: 9,
-      fieldName: "J",
-      fieldType: "link",
-      fieldContent: "Click me",
-      isDefault: false,
-      isVisible: false,
-    },
-  ],
-];
-```
-usage of the MultiDynamicTable
+- CustomSelectableList
+  - Props: `items: { label:string; icon? }[]`, `onSelect?(index)`; supports selection and a divider after the second item.
 
-```ts
-import { useState } from "react";
-import MultiDynamicTable from "./MultiDynamicTable/MultiDynamicTable";
-import { dynamicTableData } from "./MultiDynamicTable/dynamicTableData";
+- Loader
+  - Props: `size?`, `text?`, `fullScreen?`.
+  - Shows animated spinner with module logo; optionally full-screen overlay.
 
-const Tables = () => {
-  const [page, setPage] = useState(0);
-  const [rowsPerPage, setRowsPerPage] = useState(10);
+## Exports
 
-  const handleChangePage = (_event: unknown, newPage: number) => {
-    setPage(newPage);
-  };
-
-  const handleChangeRowsPerPage = (
-    event: React.ChangeEvent<HTMLInputElement>
-  ) => {
-    setRowsPerPage(parseInt(event.target.value, 10));
-    setPage(0);
-  };
-
-  return (
-    <>
-      <MultiDynamicTable
-        tableData={dynamicTableData}
-        page={page}
-        rowsPerPage={rowsPerPage}
-        handleChangePage={handleChangePage}
-        handleChangeRowsPerPage={handleChangeRowsPerPage}
-      />
-    </>
-  );
-};
-
-export default Tables;
+```ts
+import {
+  ThemeSetting,
+  ThemeCustomization,
+  MainLayout,
+  MainlayoutWithWrapper,
+  RoutesConfigLayout,
+  MultiDynamicTable,
+  ProfilePages,
+  // UI primitives
+  AsyncAutocomplete,
+  CheckboxListWithAvatar,
+  ControlledDatePicker,
+  CustomButton,
+  CustomCheckbox,
+  CustomColorPicker,
+  CustomDatePicker,
+  CustomIconButton,
+  CustomInput,
+  CustomRadioGroup,
+  CustomScrollbar,
+  CustomSelect,
+  CustomSelectableList,
+  CustomSwitch,
+  CustomTabs,
+  CustomTextField,
+  Loader,
+} from "@crystaltech/hsms-shared-ui";
 ```
-### 13. `CustomTabs`
-
-### 14. `CustomTabs`
-
-### 15. `CustomTabs`
-
-### 16. `CustomTabs`
-
-### 17. `CustomTabs`
-
-### 18. `CustomTabs`
-
-## License
-
-This package is licensed under the **MIT License**.
-
----
 
-## Author
+## Notes
 
-Developed by **Anwar Hossain**.  
-For questions or contributions, reach out via **GitHub**.
+- `RoutesConfigLayout` uses `ProtectedRoute` to enforce `roles` and `clients`; route-level `roles` override global ones.
+- Column visibility toggling in `MultiDynamicTable` relies on shared `id` values across rows for a given column.
+- Ensure peer versions of MUI and React match your app.
+- Refer to `src/theme/defaultTheme.ts` for the complete `ITheme` shape.