@7365admin1/layer-common 4.136.0 → 4.138.0

package/components/ScheduleGuide.vue

@@ -9,6 +9,29 @@
 <template>
   <div class="schedule-guide">
     <p v-if="text" class="schedule-guide__text">{{ text }}</p>
+    <!--
+      "How it works": the page's own short manual (owner 21 Oct - a supervisor
+      who was never trained must understand the screen from the screen). Open
+      by default until the viewer closes it; the choice is remembered on this
+      browser only.
+    -->
+    <v-expansion-panels
+      v-if="$slots.default && howTitle"
+      v-model="howPanel"
+      class="schedule-guide__how"
+      variant="accordion"
+      flat
+    >
+      <v-expansion-panel value="how">
+        <v-expansion-panel-title class="schedule-guide__how-title">
+          <v-icon size="20" class="mr-2">mdi-help-circle-outline</v-icon>
+          {{ howTitle }}
+        </v-expansion-panel-title>
+        <v-expansion-panel-text class="schedule-guide__how-body">
+          <slot />
+        </v-expansion-panel-text>
+      </v-expansion-panel>
+    </v-expansion-panels>
     <v-alert
       v-if="problems.length"
       type="warning"
@@ -44,6 +67,27 @@ const props = defineProps({
   serviceType: { type: String, default: "" },
   scheduleRoute: { type: String, default: "" },
   text: { type: String, default: "" },
+  /** Heading of the "How it works" panel; the panel shows only with this and a default slot. */
+  howTitle: { type: String, default: "" },
+  /** Remembers open/closed per panel on this browser. */
+  howKey: { type: String, default: "" },
+});
+
+const HOW_STORE = () => `schedule-guide-how:${props.howKey || props.howTitle}`;
+const howPanel = ref<string | undefined>("how");
+onMounted(() => {
+  try {
+    if (localStorage.getItem(HOW_STORE()) === "closed") howPanel.value = undefined;
+  } catch {
+    // storage blocked: stay open
+  }
+});
+watch(howPanel, (v) => {
+  try {
+    localStorage.setItem(HOW_STORE(), v ? "open" : "closed");
+  } catch {
+    // storage blocked: nothing to remember
+  }
 });
 
 const { getAreas, getAreaById } = useAreas();
@@ -125,8 +169,65 @@ watch(() => [props.site, props.serviceType], check);
   font-size: var(--fs-cell);
   color: var(--text2);
 }
+.schedule-guide__how {
+  margin-bottom: 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--r-inner);
+  overflow: hidden;
+}
+.schedule-guide__how-title {
+  font-family: var(--font-sans);
+  font-size: var(--fs-card-title);
+  font-weight: 700;
+}
+.schedule-guide__how-body {
+  font-family: var(--font-sans);
+  font-size: var(--fs-cell);
+  line-height: 1.55;
+}
 .schedule-guide__list {
   margin: 0;
   padding-left: 18px;
 }
 </style>
+
+<!-- Shared by the "How it works" content the schedule screens put in the slot. -->
+<style>
+.sg-steps {
+  margin: 0 0 12px;
+  padding-left: 22px;
+}
+.sg-steps li {
+  margin-bottom: 6px;
+}
+.sg-example {
+  margin: 0 0 12px;
+  padding: 12px 14px;
+  border-left: 3px solid rgb(var(--v-theme-primary));
+  border-radius: var(--r-inner-sm);
+  background: var(--hover);
+}
+.sg-legend {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 8px 12px;
+  align-items: center;
+  margin: 0;
+}
+.sg-legend dd {
+  margin: 0;
+}
+.sg-h {
+  margin: 4px 0 8px;
+  font-weight: 700;
+}
+@media (max-width: 599.98px) {
+  .sg-legend {
+    grid-template-columns: 1fr;
+    gap: 2px 0;
+  }
+  .sg-legend dd {
+    margin-bottom: 8px;
+  }
+}
+</style>

package/components/ScheduleTaskForm.vue

@@ -59,8 +59,10 @@
                   variant="outlined"
                   density="comfortable"
                   class="filter-field mb-4"
-                  placeholder="For example: Midday toilet round"
+                  placeholder="For example: Lunch toilet check"
                   :error-messages="fieldError('title')"
+                  hint="Staff see this name on their phone, on the extra round."
+                  persistent-hint
                   hide-details="auto"
                 />
                 <InputLabel for="description" title="Instructions" />
@@ -72,6 +74,8 @@
                   class="filter-field"
                   rows="3"
                   placeholder="Optional. Anything staff should know for this visit."
+                  hint="Optional. For example: refill soap and tissue as well."
+                  persistent-hint
                   hide-details="auto"
                 />
               </div>
@@ -81,8 +85,9 @@
             <v-stepper-window-item :value="2">
               <div class="st-step">
                 <p class="st-step__help">
-                  Pick the areas that get the extra visit. Every unit in an
-                  area is added to the checklist.
+                  Pick the areas that get the extra visit. Every unit in a
+                  picked area gets one more tick box on the Daily Checklist
+                  for this visit.
                 </p>
                 <InputLabel for="selected-areas" title="Areas" required />
                 <v-select
@@ -165,7 +170,8 @@
               <div class="st-step">
                 <p class="st-step__help">
                   Choose the time, and whether it happens once or repeats.
-                  Times are Singapore time.
+                  Times are Singapore time. The extra round appears on staff's
+                  checklist at this time.
                 </p>
                 <v-row dense>
                   <v-col cols="12" sm="6">
@@ -193,6 +199,8 @@
                       variant="outlined"
                       density="comfortable"
                       class="filter-field"
+                      :hint="REPEAT_HINTS[repeat]"
+                      persistent-hint
                       hide-details="auto"
                     />
                   </v-col>
@@ -200,7 +208,7 @@
 
                 <!-- Once: pick the day(s) -->
                 <div v-if="repeat === 'none'" class="mt-4">
-                  <InputLabel title="Day" required />
+                  <InputLabel title="Day(s)" required />
                   <div class="st-panel">
                     <v-date-picker
                       v-model="pickerDates"
@@ -213,7 +221,8 @@
                       class="ma-0"
                     />
                     <div class="st-step__help mt-2">
-                      {{ selectedDates.length }} day(s) selected.
+                      {{ selectedDates.length }} day(s) selected. Click a day
+                      again to remove it.
                     </div>
                   </div>
                   <div v-if="fieldError('dates').length" class="st-error">
@@ -304,6 +313,32 @@
                   <div class="st-summary__label">This will:</div>
                   <div class="st-summary__text">{{ summary }}</div>
                 </div>
+
+                <!-- What staff will see: the same card shape as the mobile checklist. -->
+                <div class="st-summary__label mt-4">
+                  What staff will see on their phone:
+                </div>
+                <div class="st-preview">
+                  <div class="st-preview__head">
+                    <v-icon size="18" class="mr-1">mdi-clock-outline</v-icon>
+                    {{ previewTime }} · Extra visit
+                  </div>
+                  <div class="st-preview__title">
+                    {{ subject.trim() || "(your title)" }}
+                  </div>
+                  <div v-if="description.trim()" class="st-preview__desc">
+                    {{ description.trim() }}
+                  </div>
+                  <div
+                    v-for="area in selectedAreas"
+                    :key="areaKey(area)"
+                    class="st-preview__row"
+                  >
+                    <v-icon size="18" class="mr-1">mdi-checkbox-blank-outline</v-icon>
+                    {{ area.name }} -
+                    {{ unitCountOf(area) }} unit{{ unitCountOf(area) === 1 ? "" : "s" }} to tick
+                  </div>
+                </div>
                 <div v-if="fieldError('never').length" class="st-error mt-2">
                   {{ fieldError("never")[0] }}
                 </div>
@@ -372,6 +407,7 @@ import {
   REPEAT_OPTIONS,
   WEEK_DAYS,
   buildSummary,
+  fmtTime,
   sgtToday,
   validateSchedule,
   type TRepeat,
@@ -395,6 +431,11 @@ const props = defineProps({
     type: String,
     default: "",
   },
+  /** The step the dialog opens on (3 = When, used by "Extend or repeat"). */
+  startStep: {
+    type: Number,
+    default: 1,
+  },
 });
 
 const show = defineModel("show", { type: Boolean, default: false });
@@ -476,6 +517,15 @@ const formState = computed(() => ({
 const errors = computed<TScheduleErrors>(() => validateSchedule(formState.value));
 const summary = computed(() => buildSummary(formState.value, totalUnits.value));
 
+const REPEAT_HINTS: Record<TRepeat, string> = {
+  none: "Only on the day(s) you pick below.",
+  daily: "Every day, weekends included.",
+  weekdays: "Monday to Friday.",
+  weekly: "On the weekdays you pick below.",
+  monthly: "Once a month, on the start date's day.",
+};
+const previewTime = computed(() => fmtTime(scheduleTime.value) || "--");
+
 const STEP_FIELDS: Record<number, (keyof TScheduleErrors)[]> = {
   1: ["title"],
   2: ["areas"],
@@ -694,6 +744,7 @@ const close = () => {
 watch(
   [show, () => props.mode, () => props.taskData],
   async ([isOpen, mode]) => {
+    if (isOpen) step.value = props.startStep || 1;
     if (isOpen && mode === "edit") {
       await loadTaskData();
     } else if (!isOpen) {
@@ -710,7 +761,7 @@ watch(
 }
 .st-step__help {
   margin: 0 0 12px;
-  font-size: var(--fs-chip-lg);
+  font-size: var(--fs-cell);
   font-weight: 600;
   color: var(--text2);
 }
@@ -748,6 +799,36 @@ watch(
   font-size: 15px;
   font-weight: 600;
 }
+.st-preview {
+  margin-top: 6px;
+  padding: 14px 16px;
+  border: 1px solid var(--border);
+  border-left: 4px solid rgb(var(--v-theme-primary));
+  border-radius: var(--r-inner);
+  background: var(--card);
+  font-size: var(--fs-cell);
+}
+.st-preview__head {
+  display: flex;
+  align-items: center;
+  font-size: var(--fs-chip-lg);
+  font-weight: 700;
+  color: var(--text2);
+}
+.st-preview__title {
+  margin: 4px 0;
+  font-size: var(--fs-card-title);
+  font-weight: 800;
+}
+.st-preview__desc {
+  margin-bottom: 6px;
+  color: var(--text2);
+}
+.st-preview__row {
+  display: flex;
+  align-items: center;
+  padding: 4px 0;
+}
 .st-stepper,
 .st-stepper__header {
   background: transparent;

package/components/ScheduleTaskMain.vue

@@ -5,10 +5,52 @@
         :org-id="orgId"
         :site="site"
         :service-type="serviceType"
-        text="An extra visit adds one more round to your daily schedule at the time you choose, once or on a repeat. Staff on this site get a push notification when it is added."
-      />
+        text="An extra visit adds one more round to the Daily Checklist at a time you choose - once, or on a repeat."
+        how-title="How extra visits work"
+        how-key="extra-visits"
+      >
+        <ol class="sg-steps">
+          <li>
+            Every night the app makes the <strong>Daily Checklist</strong>
+            for every area on this site. You do not need to do anything for
+            that.
+          </li>
+          <li>
+            An <strong>extra visit</strong> adds one more round to that
+            checklist, in the areas you pick, at the time you set - once, or
+            repeating (every day, weekdays, chosen days, or monthly).
+          </li>
+          <li>
+            At that time, staff see the extra round in their mobile app's
+            daily checklist (with a push notification) and tick each unit as
+            they finish it.
+          </li>
+          <li>
+            Here and in the Daily Checklist you see how it went:
+            <strong>Done</strong>, <strong>In progress</strong>,
+            <strong>Needs redo</strong> or <strong>Missed</strong>.
+          </li>
+        </ol>
+        <div class="sg-example">
+          <strong>Example:</strong> the lobby toilets get busy at lunch. Add
+          an extra visit called "Lunch toilet check", pick the area "Lobby
+          Toilets", set 2:00 pm, every weekday. From the next weekday, staff
+          get one more toilet round at 2:00 pm, on top of their normal ones.
+        </div>
+        <div class="sg-h">What the words mean</div>
+        <dl class="sg-legend">
+          <template v-for="h in STATUS_HELP" :key="h.word">
+            <dt><StatusChip :status="h.word" :label="h.word" /></dt>
+            <dd>{{ h.meaning }}</dd>
+          </template>
+          <template v-for="h in RESULT_HELP" :key="'r' + h.word">
+            <dt><StatusChip :status="h.word" :label="h.word" /></dt>
+            <dd>Last visit: {{ h.meaning }}</dd>
+          </template>
+        </dl>
+      </ScheduleGuide>
       <TableMain
-        :title="'Extra Visits (Scheduled)'"
+        :title="'Extra Visits'"
         :items="items"
         :headers="headers"
         :loading="loading"
@@ -26,9 +68,14 @@
           <div class="st-empty">
             <strong>No extra visits yet.</strong>
             <span>
-              An extra visit adds one more round to your daily
-              {{ scheduleName }} at a time you choose. Set up your Areas and
-              Units first, then add one.
+              Your Daily Checklist already covers the normal rounds. Add an
+              extra visit when an area needs one more round at a set time -
+              for example "Lunch toilet check, Lobby Toilets, 2:00 pm every
+              weekday".
+            </span>
+            <span v-if="canCreateScheduleTask">
+              Press <strong>Add Extra Visit</strong> above to start. Your
+              Areas and Units must be set up first.
             </span>
           </div>
         </template>
@@ -61,27 +108,6 @@
           </v-row>
         </template>
 
-        <template #item.areas="{ value }">
-          <div v-if="value && value.length > 0">
-            <StatusChip
-              v-for="(area, idx) in value.slice(0, 2)"
-              :key="idx"
-              class="mr-1 mb-1"
-              :dot="false"
-              tone="neutral"
-              :label="area.name"
-            />
-            <StatusChip
-              v-if="value.length > 2"
-              class="mb-1"
-              :dot="false"
-              tone="neutral"
-              :label="`+${value.length - 2} more`"
-            />
-          </div>
-          <span v-else>N/A</span>
-        </template>
-
         <template #item.when="{ item }">
           <span class="st-when">{{ item.whenText }}</span>
         </template>
@@ -91,24 +117,34 @@
         </template>
 
         <template #item.lastRun="{ item }">
-          <StatusChip
-            v-if="item.lastRun && item.lastRunStatus === 'done'"
-            status="Done"
-            :label="item.lastRunText"
-          />
-          <StatusChip
-            v-else-if="item.lastRun && item.lastRunStatus === 'missed'"
-            status="Missed"
-            :label="item.lastRunText"
-          />
-          <span v-else>{{ item.lastRunText }}</span>
+          <div class="st-cell">
+            <StatusChip
+              v-if="item.lastRun && item.lastRunWord"
+              :status="item.lastRunWord"
+              :label="item.lastRunText"
+            />
+            <span v-else>{{ item.lastRunText }}</span>
+            <a
+              v-if="item.lastRun"
+              href="#"
+              class="st-link"
+              @click.prevent.stop="openChecklist(item)"
+            >
+              See that day's checklist
+            </a>
+          </div>
         </template>
 
         <template #item.status="{ item }">
-          <StatusChip
-            :status="item.stateLabel"
-            :label="item.stateLabel"
-          />
+          <div class="st-cell">
+            <StatusChip
+              :status="item.stateLabel"
+              :label="item.stateLabel"
+            />
+            <span v-if="item.stateKey === 'ended'" class="st-note">
+              {{ item.finishedText }}
+            </span>
+          </div>
         </template>
 
         <template #item.actions="{ item }">
@@ -123,6 +159,17 @@
             >
               Edit
             </v-btn>
+            <v-btn
+              v-if="canUpdateScheduleTask && item.stateKey === 'ended'"
+              size="small"
+              variant="tonal"
+              color="primary"
+              class="text-none"
+              prepend-icon="mdi-calendar-refresh"
+              @click.stop="onExtendRow(item)"
+            >
+              Extend or repeat
+            </v-btn>
             <v-btn
               v-if="canUpdateScheduleTask && item.stateKey !== 'ended'"
               size="small"
@@ -155,6 +202,7 @@
         v-model:show="showForm"
         :mode="formMode"
         :taskData="selectedTask"
+        :start-step="formStartStep"
         :site="props.site"
         :serviceType="props.serviceType"
         @refresh="getTaskRefresh"
@@ -194,7 +242,7 @@
 
                 <v-row no-gutters class="mb-2">
                   <v-col cols="5" class="text-subtitle-2 font-weight-bold">
-                    Next run:
+                    Next visit:
                   </v-col>
                   <v-col cols="7" class="text-subtitle-2">
                     {{ selectedNext || "-" }}
@@ -203,10 +251,18 @@
 
                 <v-row no-gutters class="mb-2">
                   <v-col cols="5" class="text-subtitle-2 font-weight-bold">
-                    Last run:
+                    Last visit:
                   </v-col>
                   <v-col cols="7" class="text-subtitle-2">
                     {{ lastRunLabel(selectedTask) }}
+                    <a
+                      v-if="selectedTask.lastRun"
+                      href="#"
+                      class="st-link d-block"
+                      @click.prevent="openChecklist(selectedTask)"
+                    >
+                      See that day's checklist
+                    </a>
                   </v-col>
                 </v-row>
 
@@ -319,7 +375,7 @@
                                 </div>
                                 <span v-else class="text-caption text-disabled"
                                   >No units in this area, so it is skipped when
-                                  this visit runs.</span
+                                  this visit is added.</span
                                 >
                               </v-card-text>
                             </div>
@@ -348,6 +404,12 @@
                       :status="stateOf(selectedTask).label"
                       :label="stateOf(selectedTask).label"
                     />
+                    <div
+                      v-if="stateOf(selectedTask).key === 'ended'"
+                      class="st-note mt-1"
+                    >
+                      {{ finishedReason(selectedTask as any) }}
+                    </div>
                   </v-col>
                 </v-row>
 
@@ -383,8 +445,8 @@
           </v-card-title>
 
           <v-card-text class="screen-modal__body">
-            This stops all future runs of this extra visit. Visits that already
-            happened are kept. Delete it?
+            This stops all future extra visits from it. Visits that already
+            happened stay on their Daily Checklists. Delete it?
           </v-card-text>
 
           <div class="screen-modal__footer">
@@ -422,8 +484,12 @@ import useScheduleTask from "../composables/useScheduleTask";
 import useUtils from "../composables/useUtils";
 import useAreas from "../composables/useAreas";
 import {
+  RESULT_HELP,
+  STATUS_HELP,
   STATUS_LABELS,
+  describeRow,
   describeWhen,
+  finishedReason,
   fmtMoment,
   lastRunLabel,
   scheduleNameFor,
@@ -458,7 +524,16 @@ const canViewScheduleTaskDetails = computed(
   () => props.canViewScheduleTaskDetails
 );
 
-const scheduleName = scheduleNameFor(props.serviceType).title;
+const checklistRoute = scheduleNameFor(props.serviceType).route;
+
+/** Opens the Daily Checklist filtered to the day this extra visit was last added. */
+function openChecklist(row: Record<string, any>) {
+  const day = String(row?.lastRun || "").slice(0, 10);
+  navigateTo({
+    path: `/${props.orgId}/${props.site}/${checklistRoute}`,
+    query: /^\d{4}-\d{2}-\d{2}$/.test(day) ? { date: day } : {},
+  });
+}
 
 const page = ref(1);
 const pages = ref(0);
@@ -468,6 +543,7 @@ const searchInput = ref("");
 const showForm = ref(false);
 const selectedTask = ref<Record<string, any>>({});
 const formMode = ref<"add" | "edit">("add");
+const formStartStep = ref(1);
 const submitting = ref(false);
 const dialogShowMoreActions = ref(false);
 const dialogDeleteTask = ref(false);
@@ -517,11 +593,10 @@ watch(dialogShowMoreActions, async (isOpen) => {
 const items = ref<any[]>([]);
 
 const headers = [
-  { title: "Title", value: "title" },
-  { title: "Areas", value: "areas" },
-  { title: "When", value: "when", sortable: false },
-  { title: "Next run", value: "nextRun", sortable: false },
-  { title: "Last run", value: "lastRun", sortable: false },
+  { title: "Extra visit", value: "title" },
+  { title: "What will happen", value: "when", sortable: false },
+  { title: "Next visit", value: "nextRun", sortable: false },
+  { title: "Last visit", value: "lastRun", sortable: false },
   { title: "Status", value: "status", sortable: false },
   { title: "", value: "actions", sortable: false, align: "end" as const },
 ];
@@ -566,7 +641,9 @@ watchEffect(() => {
       const st = stateOf(row);
       return {
         ...row,
-        whenText: describeWhen(row),
+        whenText: describeRow(row),
+        finishedText: finishedReason(row),
+        lastRunWord: ({ done: "Done", missed: "Missed", pending: "In progress" } as Record<string, string>)[row.lastRunStatus] || "",
         nextRunText: fmtMoment(row.nextRun),
         lastRunText: lastRunLabel(row),
         stateKey: st.key,
@@ -590,6 +667,7 @@ watch(
 
 function openFormDialog() {
   formMode.value = "add";
+  formStartStep.value = 1;
   selectedTask.value = {};
   showForm.value = true;
 }
@@ -597,6 +675,15 @@ function openFormDialog() {
 function onEditRow(item: Record<string, any>) {
   selectedTask.value = item;
   formMode.value = "edit";
+  formStartStep.value = 1;
+  showForm.value = true;
+}
+
+// A finished extra visit: open its "When" step so a new end date or repeat is one change away.
+function onExtendRow(item: Record<string, any>) {
+  selectedTask.value = item;
+  formMode.value = "edit";
+  formStartStep.value = 3;
   showForm.value = true;
 }
 
@@ -612,8 +699,8 @@ async function togglePause(item: Record<string, any>) {
     await setScheduleTaskPaused(item._id, !resuming);
     showMessage(
       resuming
-        ? "Resumed. It will run again from its next date."
-        : "Paused. It will not run until you resume it.",
+        ? "Resumed. Extra visits are added again from its next date."
+        : "Paused. No extra visits are added until you resume it.",
       "success",
     );
     await getTaskRefresh();
@@ -649,6 +736,7 @@ async function onRowClick(data: any) {
 const onEditFromMoreAction = async () => {
   dialogShowMoreActions.value = false;
   formMode.value = "edit";
+  formStartStep.value = stateOf(selectedTask.value).key === "ended" ? 3 : 1;
   showForm.value = true;
 };
 
@@ -693,8 +781,27 @@ async function _deleteScheduleTask() {
   color: var(--text2);
 }
 .st-when {
+  display: inline-block;
+  min-width: 220px;
   white-space: normal;
 }
+.st-cell {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+}
+.st-note {
+  font-size: var(--fs-chip-lg);
+  color: var(--text2);
+  white-space: normal;
+}
+.st-link {
+  font-size: var(--fs-chip-lg);
+  font-weight: 600;
+  color: rgb(var(--v-theme-primary));
+  text-decoration: underline;
+}
 .st-actions {
   display: flex;
   justify-content: flex-end;