@digihmis/esm-administration-app 1.0.0 → 1.0.1

package/src/document-branding/document-branding-workspace/document-branding.workspace.scss

@@ -0,0 +1,34 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+
+.form {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  height: 100%;
+}
+
+.formContainer {
+  margin: layout.$spacing-05;
+}
+
+.tablet {
+  padding: layout.$spacing-06 layout.$spacing-05;
+  background-color: colors.$white;
+}
+
+.desktop {
+  padding: 0;
+}
+
+.logoPreview {
+  display: block;
+  max-height: 4rem;
+  max-width: 12rem;
+  margin-bottom: layout.$spacing-03;
+  object-fit: contain;
+}
+
+.loading {
+  margin: layout.$spacing-07;
+}

package/src/document-branding/document-branding-workspace/document-branding.workspace.tsx

@@ -0,0 +1,160 @@
+import React, { useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button, ButtonSet, Form, FormGroup, FileUploader, InlineLoading, Stack, TextArea, TextInput } from '@carbon/react';
+import { Controller, useForm } from 'react-hook-form';
+import classNames from 'classnames';
+import { mutate } from 'swr';
+import { type DefaultWorkspaceProps, ResponsiveWrapper, showSnackbar, useLayoutType } from '@openmrs/esm-framework';
+import { facilityInfoUrl, type FacilityInfo, saveFacilityInfo, useFacilityInfo } from '../document-branding.resource';
+import styles from './document-branding.workspace.scss';
+
+const DocumentBrandingWorkspace: React.FC<DefaultWorkspaceProps> = ({
+  closeWorkspace,
+  closeWorkspaceWithSavedChanges,
+  promptBeforeClosing,
+}) => {
+  const { t } = useTranslation();
+  const isTablet = useLayoutType() === 'tablet';
+  const { info, settingUuid, isLoading } = useFacilityInfo();
+
+  const { control, handleSubmit, reset, setValue, watch, formState: { isDirty, isSubmitting } } = useForm<FacilityInfo>({
+    defaultValues: {},
+  });
+
+  // Prefill once the stored value has loaded.
+  useEffect(() => {
+    if (!isLoading) {
+      reset(info);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isLoading, settingUuid]);
+
+  useEffect(() => {
+    promptBeforeClosing(() => isDirty);
+  }, [isDirty, promptBeforeClosing]);
+
+  const logoData = watch('logoData');
+
+  const onLogo = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    if (!file) {
+      return;
+    }
+    const reader = new FileReader();
+    reader.onload = () => setValue('logoData', String(reader.result), { shouldDirty: true });
+    reader.readAsDataURL(file);
+  };
+
+  const onSubmit = async (data: FacilityInfo) => {
+    if (!settingUuid) {
+      showSnackbar({ kind: 'error', title: t('settingMissing', 'Print module setting not found — is it installed?') });
+      return;
+    }
+    try {
+      await saveFacilityInfo(settingUuid, data);
+      await mutate(facilityInfoUrl);
+      showSnackbar({ kind: 'success', isLowContrast: true, title: t('brandingSaved', 'Document letterhead saved') });
+      closeWorkspaceWithSavedChanges();
+    } catch (err) {
+      showSnackbar({
+        kind: 'error',
+        title: t('brandingError', 'Could not save the letterhead'),
+        subtitle: err?.responseBody?.error?.message ?? err?.message,
+      });
+    }
+  };
+
+  if (isLoading) {
+    return <InlineLoading className={styles.loading} description={t('loading', 'Loading…')} />;
+  }
+
+  return (
+    <Form className={styles.form} onSubmit={handleSubmit(onSubmit)}>
+      <div className={styles.formContainer}>
+        <Stack gap={5}>
+          <Controller
+            name="facilityName"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextInput id="facilityName" labelText={t('facilityName', 'Facility name')} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+          <Controller
+            name="facilityTagline"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextInput id="facilityTagline" labelText={t('tagline', 'Tagline')} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+          <Controller
+            name="phone"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextInput id="phone" labelText={t('phone', 'Phone')} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+          <Controller
+            name="email"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextInput id="email" labelText={t('email', 'Email')} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+          <Controller
+            name="website"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextInput id="website" labelText={t('website', 'Website')} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+          <Controller
+            name="address"
+            control={control}
+            render={({ field }) => (
+              <ResponsiveWrapper>
+                <TextArea id="address" labelText={t('address', 'Address')} rows={2} {...field} value={field.value ?? ''} />
+              </ResponsiveWrapper>
+            )}
+          />
+
+          <FormGroup legendText={t('logo', 'Logo')}>
+            {logoData && <img src={logoData} alt={t('logoPreview', 'Logo preview')} className={styles.logoPreview} />}
+            <FileUploader
+              accept={['.png', '.jpg', '.jpeg']}
+              buttonLabel={t('uploadLogo', 'Upload logo')}
+              labelDescription={t('logoHint', 'PNG or JPG; shown top-left on documents.')}
+              filenameStatus="edit"
+              onChange={onLogo}
+              onDelete={() => setValue('logoData', undefined, { shouldDirty: true })}
+            />
+          </FormGroup>
+        </Stack>
+      </div>
+
+      <ButtonSet className={classNames({ [styles.tablet]: isTablet, [styles.desktop]: !isTablet })}>
+        <Button style={{ maxWidth: '50%' }} kind="secondary" onClick={() => closeWorkspace()}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button style={{ maxWidth: '50%' }} kind="primary" type="submit" disabled={isSubmitting || !isDirty}>
+          {isSubmitting ? (
+            <InlineLoading description={t('saving', 'Saving…')} />
+          ) : (
+            t('saveAndClose', 'Save & close')
+          )}
+        </Button>
+      </ButtonSet>
+    </Form>
+  );
+};
+
+export default DocumentBrandingWorkspace;

package/src/document-branding/document-branding.component.tsx

@@ -0,0 +1,185 @@
+import React, { useMemo, useState } from 'react';
+import {
+  Button,
+  DataTable,
+  DataTableSkeleton,
+  Layer,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tile,
+} from '@carbon/react';
+import { Edit } from '@carbon/react/icons';
+import { launchWorkspace, useLayoutType, useConfig, ErrorState } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { CardHeader } from '@openmrs/esm-patient-common-lib';
+import { type ConfigObject } from '../config-schema';
+import { CustomPageHeader } from '../components/custom-page-header/custom-page-header.component';
+import styles from './document-branding.scss';
+import { useFacilityInfo } from './document-branding.resource';
+
+/**
+ * Admin page for the document letterhead — the facility identity (name, tagline, contacts, address)
+ * and logo shown on every generated PDF. It lists the stored value and launches a workspace to edit it,
+ * writing to the print module's global property so no one has to hand-edit JSON.
+ */
+const DocumentBrandingDashboard = () => {
+  const { t } = useTranslation();
+  const layout = useLayoutType();
+  const isTablet = layout === 'tablet';
+  const responsiveSize = isTablet ? 'lg' : 'sm';
+  const { documentBrandingIcon } = useConfig<ConfigObject>();
+
+  const { info, isLoading, error } = useFacilityInfo();
+
+  const headers = [
+    { key: 'field', header: t('field', 'Field') },
+    { key: 'value', header: t('value', 'Value') },
+  ];
+
+  const fields = useMemo(
+    () => [
+      { key: 'facilityName', label: t('facilityName', 'Facility name'), value: info.facilityName },
+      { key: 'facilityTagline', label: t('tagline', 'Tagline'), value: info.facilityTagline },
+      { key: 'phone', label: t('phone', 'Phone'), value: info.phone },
+      { key: 'email', label: t('email', 'Email'), value: info.email },
+      { key: 'website', label: t('website', 'Website'), value: info.website },
+      { key: 'address', label: t('address', 'Address'), value: info.address },
+    ],
+    [info, t],
+  );
+
+  const hasLogo = Boolean(info.logoData || info.logoPath);
+
+  const tableRows = useMemo(() => {
+    const rows = fields
+      .filter((field) => field.value)
+      .map((field) => ({ id: field.key, field: field.label, value: field.value as React.ReactNode }));
+    if (hasLogo) {
+      rows.push({
+        id: 'logo',
+        field: t('logo', 'Logo'),
+        value: (
+          <img
+            src={info.logoData ?? info.logoPath}
+            alt={t('logoPreview', 'Logo preview')}
+            className={styles.logoPreview}
+          />
+        ),
+      });
+    }
+    return rows;
+  }, [fields, hasLogo, info.logoData, info.logoPath, t]);
+
+  const hasBranding = tableRows.length > 0;
+
+  const [currentPage, setCurrentPage] = useState(1);
+  const [currentPageSize, setCurrentPageSize] = useState(10);
+  const pageSizes = [10, 20, 30, 40, 50];
+
+  const paginatedRows = useMemo(() => {
+    const startIndex = (currentPage - 1) * currentPageSize;
+    return tableRows.slice(startIndex, startIndex + currentPageSize);
+  }, [tableRows, currentPage, currentPageSize]);
+
+  const handleConfigure = () => {
+    launchWorkspace('document-branding-workspace', {
+      workspaceTitle: t('configureLetterhead', 'Configure letterhead'),
+    });
+  };
+
+  const renderBody = () => {
+    if (isLoading) {
+      return <DataTableSkeleton role="progressbar" compact={!isTablet} zebra />;
+    }
+    if (error) {
+      return <ErrorState error={error} headerTitle={t('facilityLetterhead', 'Facility letterhead')} />;
+    }
+    return (
+      <Layer>
+        <DataTable rows={paginatedRows} headers={headers} size={responsiveSize} useZebraStyles>
+          {({ rows, headers, getHeaderProps, getRowProps, getTableProps }) => (
+            <TableContainer>
+              <Table {...getTableProps()} aria-label={t('facilityLetterheadTable', 'Facility letterhead table')}>
+                <TableHead>
+                  <TableRow>
+                    {headers.map((header) => (
+                      <TableHeader key={header.key} {...getHeaderProps({ header })}>
+                        {header.header}
+                      </TableHeader>
+                    ))}
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  {rows.map((row) => (
+                    <TableRow key={row.id} {...getRowProps({ row })}>
+                      {row.cells.map((cell) => (
+                        <TableCell key={cell.id}>{cell.value}</TableCell>
+                      ))}
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+              {!hasBranding ? (
+                <div className={styles.tileContainer}>
+                  <Tile className={styles.tile}>
+                    <div className={styles.tileContent}>
+                      <p className={styles.content}>{t('noLetterhead', 'No Facility letterhead configured yet')}</p>
+                      <p className={styles.emptyStateHelperText}>
+                        {t(
+                          'noLetterheadHelp',
+                          'Add the facility name, contacts and logo to brand generated documents.',
+                        )}
+                      </p>
+                    </div>
+                  </Tile>
+                </div>
+              ) : null}
+              {hasBranding && (
+                <Pagination
+                  forwardText={t('nextPage', 'Next page')}
+                  backwardText={t('previousPage', 'Previous page')}
+                  page={currentPage}
+                  pageSize={currentPageSize}
+                  pageSizes={pageSizes}
+                  totalItems={tableRows.length}
+                  className={styles.pagination}
+                  onChange={({ pageSize, page }) => {
+                    if (pageSize !== currentPageSize) {
+                      setCurrentPageSize(pageSize);
+                      setCurrentPage(1);
+                    }
+                    if (page !== currentPage) {
+                      setCurrentPage(page);
+                    }
+                  }}
+                />
+              )}
+            </TableContainer>
+          )}
+        </DataTable>
+      </Layer>
+    );
+  };
+
+  return (
+    <>
+      <CustomPageHeader subTitle={t('facilityBranding', 'Facility branding')} iconSrc={documentBrandingIcon?.src} />
+      <div className={styles.section}>
+        <CardHeader title={t('facilityLetterhead', 'Facility letterhead')}>
+          <Button kind="ghost" renderIcon={(props) => <Edit size={16} {...props} />} onClick={handleConfigure}>
+            {hasBranding ? t('editLetterhead', 'Edit letterhead') : t('configureLetterhead', 'Configure letterhead')}
+          </Button>
+        </CardHeader>
+        {renderBody()}
+      </div>
+    </>
+  );
+};
+
+export default DocumentBrandingDashboard;

package/src/document-branding/document-branding.resource.ts

@@ -0,0 +1,54 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+
+/** The global property the print module reads for the document letterhead. */
+export const facilityInfoGp = 'digihmisprint.facilityInformation';
+
+/** SWR key for the stored letterhead — exported so the workspace can revalidate the dashboard after saving. */
+export const facilityInfoUrl = `${restBaseUrl}/systemsetting/${facilityInfoGp}?v=custom:(uuid,value)`;
+
+export interface FacilityInfo {
+  facilityName?: string;
+  facilityTagline?: string;
+  phone?: string;
+  email?: string;
+  website?: string;
+  address?: string;
+  /** Logo as a base64 / data-URI string (from the upload). */
+  logoData?: string;
+  /** Or a server file path, as an alternative to an uploaded logo. */
+  logoPath?: string;
+}
+
+/** The stored letterhead (parsed from the GP JSON) plus the setting uuid needed to save it. */
+export const useFacilityInfo = () => {
+  const { data, error, isLoading, mutate } = useSWR<{ data: { uuid: string; value?: string } }>(
+    facilityInfoUrl,
+    openmrsFetch,
+  );
+  let info: FacilityInfo = {};
+  const raw = data?.data?.value;
+  if (raw) {
+    try {
+      info = JSON.parse(raw);
+    } catch {
+      info = {};
+    }
+  }
+  return { info, settingUuid: data?.data?.uuid, isLoading, error, mutate };
+};
+
+/** Save the letterhead back to the global property as JSON (dropping blank fields). */
+export const saveFacilityInfo = (settingUuid: string, info: FacilityInfo) => {
+  const cleaned: Record<string, string> = {};
+  Object.entries(info).forEach(([key, value]) => {
+    if (value != null && String(value).trim() !== '') {
+      cleaned[key] = String(value).trim();
+    }
+  });
+  return openmrsFetch(`${restBaseUrl}/systemsetting/${settingUuid}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: { value: JSON.stringify(cleaned) },
+  });
+};

package/src/document-branding/document-branding.scss

@@ -0,0 +1,69 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@carbon/colors';
+
+.dashboardContainer {
+  display: flex;
+  flex-direction: column;
+}
+
+.section {
+  margin-bottom: layout.$spacing-07;
+  padding: layout.$spacing-05;
+    background-color: colors.$gray-10;
+
+
+  &:last-child {
+    margin-bottom: 0;
+  }
+}
+
+.subhead {
+  @include type.type-style('body-01');
+  color: colors.$gray-70;
+  margin-bottom: layout.$spacing-05;
+}
+
+.logoPreview {
+  display: block;
+  max-height: 4rem;
+  max-width: 12rem;
+  margin-bottom: layout.$spacing-05;
+  object-fit: contain;
+}
+
+.tileContainer {
+  border-top: 1px solid colors.$gray-20;
+  padding: 3rem 0;
+}
+
+.tile {
+  margin: auto;
+  width: fit-content;
+  background: colors.$gray-20;
+}
+
+.tileContent {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.content {
+  @include type.type-style('heading-compact-02');
+  color: colors.$gray-70;
+  margin-bottom: layout.$spacing-03;
+}
+
+.emptyStateHelperText {
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-70;
+}
+
+.pagination {
+  overflow: hidden;
+
+  &:global(.cds--pagination) {
+    border-top: none;
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import { createDashboardLink } from './left-panel/left-panel.component';
 import {
   bedManagementDashboardMeta,
   billingManagementDashboardMeta,
+  documentBrandingDashboardMeta,
   formBuilderDashboardMeta,
   locationManagementDashboardMeta,
   queueManagementDashboardMeta,
@@ -15,6 +16,7 @@ import BedManagementDashboard from './bed-management/bed-management.component';
 import FormBuilderDashboard from './form-builder/form-builder.component';
 import BillingManagementDashboard from './billing-management/billing-management.component';
 import SystemInfoDashboard from './system-info/system-info.component';
+import DocumentBrandingDashboard from './document-branding/document-branding.component';
 import DeletePaymentModeModal from './billing-management/billing-payment-modes/billing-payment-modes-modal/billing-delete-payment-modes.modal';
 import DeletePaymentPointModal from './billing-management/billing-payment-points/billing-payment-point-modal/billing-delete-payment-point.modal';
 import DeleteBillableServiceModal from './billing-management/billing-charge-items/billing-charge-items-modal/billing-charge-items.modal';
@@ -35,6 +37,10 @@ export const bedLeftPanelLink = getSyncLifecycle(createDashboardLink(bedManageme
 export const formBuilderLeftPanelLink = getSyncLifecycle(createDashboardLink(formBuilderDashboardMeta), options);
 export const billingLeftPanelLink = getSyncLifecycle(createDashboardLink(billingManagementDashboardMeta), options);
 export const systemInfoLeftPanelLink = getSyncLifecycle(createDashboardLink(systemInfoDashboardMeta), options);
+export const documentBrandingLeftPanelLink = getSyncLifecycle(
+  createDashboardLink(documentBrandingDashboardMeta),
+  options,
+);
 
 export const queueManagementDashboard = getSyncLifecycle(QueueManagementDashboard, options);
 export const locationManagementDashboard = getSyncLifecycle(LocationManagementDashboard, options);
@@ -42,6 +48,7 @@ export const bedManagementDashboard = getSyncLifecycle(BedManagementDashboard, o
 export const formBuilderDashboard = getSyncLifecycle(FormBuilderDashboard, options);
 export const billingManagementDashboard = getSyncLifecycle(BillingManagementDashboard, options);
 export const systemInfoDashboard = getSyncLifecycle(SystemInfoDashboard, options);
+export const documentBrandingDashboard = getSyncLifecycle(DocumentBrandingDashboard, options);
 
 // t('addNewQueueService', 'Add New Queue Service')
 export const addNewQueueServiceWorkspace = getAsyncLifecycle(
@@ -103,22 +110,21 @@ export const paymentPointWorkspace = getAsyncLifecycle(
   },
 );
 
-// t('addCommodityItem', 'Add Commodity Item')
-export const commodityForm = getAsyncLifecycle(
+// t('addServiceItem', 'Add Charge Service')
+export const billableServiceForm = getAsyncLifecycle(
   () =>
-    import('./billing-management/billing-charge-items/billing-charge-items-workspace/billing-charge-item.workspace'),
+    import('./billing-management/billing-charge-items/billing-charge-items-workspace/billing-charge-service.workspace'),
   {
-    featureName: 'billing-charge-item-workspace',
+    featureName: 'billing-charge-service-workspace',
     moduleName,
   },
 );
 
-// t('addServiceItem', 'Add Charge Service')
-export const billableServiceForm = getAsyncLifecycle(
-  () =>
-    import('./billing-management/billing-charge-items/billing-charge-items-workspace/billing-charge-service.workspace'),
+// t('configureLetterhead', 'Configure letterhead')
+export const documentBrandingWorkspace = getAsyncLifecycle(
+  () => import('./document-branding/document-branding-workspace/document-branding.workspace'),
   {
-    featureName: 'billing-charge-service-workspace',
+    featureName: 'document-branding-workspace',
     moduleName,
   },
 );

package/src/routes.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.openmrs.org/routes.schema.json",
   "backendDependencies": {
     "fhir2": ">=1.2",
-    "webservices.rest": "^2.24.0"
+    "webservices.rest": ">=2.24.0"
   },
   "extensions": [
     {
@@ -65,6 +65,16 @@
         "title": "Billing Management"
       }
     },
+    {
+      "name": "document-branding-dashboard-link",
+      "slot": "administration-dashboard-slot",
+      "component": "documentBrandingLeftPanelLink",
+      "meta": {
+        "name": "document-branding",
+        "slot": "document-branding-homepage-dashboard-slot",
+        "title": "Document Branding"
+      }
+    },
     {
       "name": "queue-management-dashboard-content",
       "slot": "queue-management-homepage-dashboard-slot",
@@ -94,10 +104,15 @@
       "name": "system-info-management-dashboard-content",
       "slot": "system-info-management-homepage-dashboard-slot",
       "component": "systemInfoDashboard"
+    },
+    {
+      "name": "document-branding-dashboard-content",
+      "slot": "document-branding-homepage-dashboard-slot",
+      "component": "documentBrandingDashboard"
     }
   ],
   "workspaces": [
-       {
+    {
       "name": "service-queues-service-form",
       "title": "addNewQueueService",
       "component": "addNewQueueServiceWorkspace",
@@ -108,36 +123,42 @@
       "title": "addNewQueueServiceRoom",
       "component": "addNewQueueServiceRoomWorkspace",
       "type": "service-queues"
-    },{
+    },
+    {
       "name": "add-location-workspace",
       "title": "addNewLocationWorkspace",
       "component": "addNewLocationWorkspace",
       "type": "location-management"
-    },{
+    },
+    {
       "name": "search-location-workspace",
       "title": "searchLocationWorkspace",
       "component": "searchLocationWorkspace",
       "type": "location-management"
-    },{
+    },
+    {
       "name": "payment-mode-workspace",
       "title": "paymentModeWorkspace",
       "component": "paymentModeWorkspace",
       "type": "billing-management"
-    },{
+    },
+    {
       "name": "payment-point-workspace",
       "title": "paymentPointWorkspace",
       "component": "paymentPointWorkspace",
       "type": "billing-management"
-    },{
+    },
+    {
       "name": "billing-charge-service-workspace",
       "title": "addServiceItem",
       "component": "billableServiceForm",
       "type": "billing-management"
-    },{
-      "name": "billing-charge-item-workspace",
-      "title": "addCommodityItem",
-      "component": "commodityForm",
-      "type": "billing-management"
+    },
+    {
+      "name": "document-branding-workspace",
+      "title": "configureLetterhead",
+      "component": "documentBrandingWorkspace",
+      "type": "document-branding"
     }
   ],
   "modals": [
@@ -154,4 +175,4 @@
       "component": "deleteBillableService"
     }
   ]
-}
+}