@stsdti/approvable-vue 0.1.0

package/src/components/approvable/ApprovableAuditTimeline.vue

@@ -0,0 +1,253 @@
+<script setup>
+import { computed, ref, watch } from 'vue'
+import { ApprovableAuditRepository, formatMessage } from '@stsdti/approvable-core'
+import { useMessages } from '../../messages.js'
+
+const props = defineProps({
+  approvableId: { type: [Number, String], required: true },
+  limit: { type: Number, default: 100 },
+  showHeader: { type: Boolean, default: true }
+})
+
+const emits = defineEmits(['loaded'])
+
+const messages = useMessages()
+const repository = new ApprovableAuditRepository()
+const audits = ref([])
+const loading = ref(false)
+const error = ref('')
+
+// Only the fields a reader actually cares about. Everything else (ids,
+// timestamps we already show, internal bookkeeping) is intentionally hidden.
+const FIELD_LABELS = {
+  approvable_status_name: 'Status',
+  comment: 'Comment',
+  responsible: 'Assigned to',
+  is_active: 'Active step'
+}
+
+// One glyph per kind of event, keyed by the `kind` we resolve below. Drawn on
+// the same 16-unit grid and at the same weight as the discs on the approval
+// trail, so a history row and a step row read as the same object.
+const ICONS = {
+  approve: { paths: ['M4 8.4l2.8 2.8 5.4-6'], width: 2.8 },
+  reject: { paths: ['M5.2 5.2l5.6 5.6M10.8 5.2l-5.6 5.6'], width: 2.4 },
+  comment: { paths: ['M8 4.6v3.6l2.6 1.6'], width: 2.2 },
+  status: { paths: ['M4 8h8M9.2 5.4L11.8 8l-2.6 2.6'], width: 2.2 },
+  undo: { paths: ['M4.4 6.6h3.4M4.4 6.6v-3M4.6 9.4a3.6 3.6 0 1 0 1-3.2'], width: 2 },
+  signal: { paths: ['M8 3.4v3.2M5.2 5.2l2.2 2.2M8 11.6a1.4 1.4 0 1 0 0-2.8 1.4 1.4 0 0 0 0 2.8'], width: 1.8 },
+  created: { paths: ['M4.4 8h7.2'], width: 2.2 },
+  update: { paths: ['M4.4 8h7.2'], width: 2.2 }
+}
+
+/** Bookkeeping, not news: these rows are dimmed the way the design dims them. */
+const QUIET_KINDS = new Set(['created', 'update'])
+
+const groups = computed(() => {
+  // The workflow-level rows are noise for a reader, so keep only step changes.
+  const stepAudits = audits.value.filter(audit => audit.approvable_step_id)
+  const grouped = new Map()
+  for (const audit of stepAudits) {
+    const key = audit.request_id || `audit-${audit.id}`
+    if (!grouped.has(key)) grouped.set(key, [])
+    grouped.get(key).push(audit)
+  }
+  return [...grouped.values()].map(entries => {
+    const audit = entries[0]
+    // Resolved here rather than in the template, where it was called twice per
+    // row on every render — once for the marker class and once for its icon.
+    const kind = auditKind(audit)
+    // A row only needs a second line when there is something to put on it.
+    const details = entries.flatMap(changeRows)
+
+    return {
+      id: audit.request_id || `audit-${audit.id}`,
+      entries,
+      audit,
+      kind,
+      // A modifier class rather than utilities: the accent for each kind of
+      // event is a theme decision, so it belongs in the stylesheets alongside
+      // every other colour, not baked into the component.
+      kindClass: `approvable-timeline-marker--${kind}`,
+      icon: ICONS[kind],
+      isQuiet: QUIET_KINDS.has(kind),
+      isSingleLine: details.length === 0
+    }
+  })
+  // Newest first: the last thing that happened is the thing a reader opened
+  // the history for.
+  .sort((a, b) => new Date(b.audit.created_at) - new Date(a.audit.created_at))
+})
+
+function auditKind (audit) {
+  const button = audit.metadata?.button
+  if (button?.is_undo) return 'undo'
+  if (button?.result === 'rejected') return 'reject'
+  if (button?.result === 'approved') return 'approve'
+  if (audit.metadata?.operation === 'comment') return 'comment'
+  if (audit.metadata?.operation === 'signal') return 'signal'
+  if (audit.event === 'created') return 'created'
+  if (statusChanged(audit)) return 'status'
+  return 'update'
+}
+
+function statusChanged (audit) {
+  const before = audit.old_values?.approvable_status_name
+  const after = audit.new_values?.approvable_status_name
+  return after !== undefined && before !== after
+}
+
+function operationTitle (audit) {
+  const button = audit.metadata?.button
+  if (button) {
+    const label = button.text || button.label || button.id || 'action'
+    if (button.is_undo) return 'Reverted the decision'
+    if (button.is_revision) return `Changed decision to ${label}`
+    return label
+  }
+  if (audit.metadata?.operation === 'comment') return 'Comment added'
+  if (audit.metadata?.operation === 'signal') return `Signal received: ${audit.metadata?.signal?.name || ''}`.trim()
+  if (audit.event === 'created') return 'Step started'
+  const after = audit.new_values?.approvable_status_name
+  if (statusChanged(audit) && after) return `Status set to ${after}`
+  return 'Step updated'
+}
+
+function actorLabel (actor = {}) {
+  if (actor.type === 'system') return 'System'
+  if (actor.name) return actor.name
+  if (actor.email) return actor.email
+  if (actor.id) return actor.type === 'fake' ? `Test user ${actor.id}` : `User ${actor.id}`
+  if (actor.type === 'fake') return 'Test identity'
+  return 'Automated'
+}
+
+// Changed fields worth surfacing, with the status change collapsed into a
+// single "before → after" row (never the raw id).
+function changeRows (entry) {
+  const oldValues = entry.old_values || {}
+  const newValues = entry.new_values || {}
+  return Object.keys(FIELD_LABELS)
+  .filter(key => key in oldValues || key in newValues)
+  .map(key => ({ key, label: FIELD_LABELS[key], oldValue: oldValues[key], newValue: newValues[key] }))
+  .filter(row => row.oldValue !== row.newValue)
+}
+
+/** A change only reads as "before → after" when there was a before. */
+function hasPreviousValue (change) {
+  return change.oldValue !== undefined && change.oldValue !== null && change.oldValue !== ''
+}
+
+function displayValue (value) {
+  if (value === null || value === undefined || value === '') return '—'
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No'
+  if (Array.isArray(value)) return value.length ? value.join(', ') : '—'
+  const text = typeof value === 'object' ? JSON.stringify(value) : String(value)
+  return text.length > 180 ? `${text.slice(0, 177)}…` : text
+}
+
+function formatDate (value) {
+  if (!value) return ''
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : new Intl.DateTimeFormat(undefined, {
+    dateStyle: 'medium',
+    timeStyle: 'short'
+  }).format(date)
+}
+
+async function refresh () {
+  if (!props.approvableId) {
+    audits.value = []
+    loading.value = false
+    error.value = 'The approval history is unavailable because the approvable has no id.'
+    return
+  }
+
+  loading.value = true
+  error.value = ''
+  try {
+    const response = await repository.fetchTimeline(props.approvableId, props.limit)
+    if (!response || response.status < 200 || response.status >= 300) {
+      throw new Error(response?.data?.message || 'The audit timeline could not be loaded.')
+    }
+    const data = Array.isArray(response.data) ? response.data : response.data?.data
+    audits.value = Array.isArray(data) ? data : []
+  } catch (exception) {
+    error.value = exception?.message || 'The audit timeline could not be loaded.'
+  } finally {
+    loading.value = false
+  }
+}
+
+const eventSummary = computed(() => formatMessage(messages.eventCount, { count: groups.value.length }))
+
+// The dialog titles itself with the count, and only this component knows it.
+watch(groups, (value) => emits('loaded', value.length))
+
+watch(() => props.approvableId, refresh, { immediate: true })
+defineExpose({ refresh })
+</script>
+
+<template>
+  <section :class="['approvable-timeline', showHeader && 'approvable-timeline--panel']">
+    <div v-if="showHeader" class="approvable-timeline-header">
+      <p class="approvable-timeline-eyebrow">{{ messages.history }}</p>
+      <h3 class="approvable-timeline-title">{{ eventSummary }}</h3>
+      <button type="button" class="approvable-timeline-refresh" :disabled="loading" @click="refresh">
+        {{ loading ? 'Loading…' : 'Refresh' }}
+      </button>
+    </div>
+
+    <div v-if="loading" class="approvable-timeline-state" role="status">
+      <span class="approvable-spinner" aria-hidden="true" />
+      Loading approval history…
+    </div>
+    <p v-else-if="error" class="approvable-timeline-error">{{ error }}</p>
+    <p v-else-if="!groups.length" class="approvable-timeline-state">No approval activity yet.</p>
+
+    <template v-else>
+      <ol class="approvable-timeline-list">
+        <li
+          v-for="group in groups"
+          :key="group.id"
+          :class="['approvable-timeline-item', {
+            'approvable-timeline-item--single-line': group.isSingleLine,
+            'approvable-timeline-item--quiet': group.isQuiet
+          }]"
+        >
+          <span :class="['approvable-timeline-marker', group.kindClass]">
+            <svg fill="none" stroke="currentColor" :stroke-width="group.icon.width" stroke-linecap="round" stroke-linejoin="round" viewBox="0 0 16 16" aria-hidden="true">
+              <path v-for="(d, i) in group.icon.paths" :key="i" :d="d" />
+            </svg>
+          </span>
+
+          <div class="approvable-timeline-content">
+            <div class="approvable-timeline-line">
+              <p class="approvable-timeline-actor">{{ actorLabel(group.audit.actor) }}</p>
+              <p class="approvable-timeline-operation">{{ operationTitle(group.audit) }}</p>
+              <time class="approvable-timeline-time">{{ formatDate(group.audit.created_at) }}</time>
+            </div>
+
+            <template v-for="entry in group.entries" :key="entry.id">
+              <template v-for="change in changeRows(entry)" :key="`${entry.id}-${change.key}`">
+                <p v-if="change.key === 'comment'" class="approvable-timeline-comment">
+                  {{ displayValue(change.newValue) }}
+                </p>
+                <p v-else class="approvable-timeline-change">
+                  <span class="approvable-timeline-change-label">{{ change.label }}</span>
+                  <template v-if="hasPreviousValue(change)">
+                    <span class="approvable-timeline-value approvable-timeline-value--old">{{ displayValue(change.oldValue) }}</span>
+                    <span class="approvable-timeline-arrow">→</span>
+                  </template>
+                  <span class="approvable-timeline-value approvable-timeline-value--new">{{ displayValue(change.newValue) }}</span>
+                </p>
+              </template>
+            </template>
+          </div>
+        </li>
+      </ol>
+
+      <p class="approvable-timeline-footer">{{ messages.allEventsShown }}</p>
+    </template>
+  </section>
+</template>

package/src/components/approvable/ApprovableButtons.vue

@@ -0,0 +1,80 @@
+<template>
+  <div v-if="hasApprovableButtons" class="approvable-actions">
+    <hr class="approvable-divider" />
+    <div class="approvable-actions-list">
+      <button
+        v-for="approvableButton in approvableButtons"
+        :key="approvableButton.code"
+        :title="approvableButton.tooltip"
+        class="approvable-btn"
+        type="button"
+        @click="onApproveStatusChange(approvableButton)"
+      >
+        <slot name="icon" :button="approvableButton">
+          <component
+            :is="icons[approvableButton.icon]"
+            v-if="isRegisteredIcon(icons, approvableButton.icon)"
+            class="approvable-btn-icon"
+          />
+          <img
+            v-else-if="isUrlIcon(approvableButton.icon)"
+            :src="approvableButton.icon"
+            alt=""
+            class="approvable-btn-icon"
+          />
+          <i v-else-if="isClassIcon(approvableButton.icon)" :class="approvableButton.icon"></i>
+        </slot>
+        {{ approvableButton.text }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+import { ApprovableStepRepository, get, isSuccessResponse, notifySuccess } from '@stsdti/approvable-core'
+import { isClassIcon, isRegisteredIcon, isUrlIcon, useIconRegistry } from '../../icons.js'
+import { useMessages } from '../../messages.js'
+
+const props = defineProps({
+  value: {
+    required: true
+  }
+})
+const emits = defineEmits(['isLoading', 'refresh'])
+
+const isLoading = ref(false)
+
+const approvableButtons = computed(() => {
+  return get(props.value, 'buttons', [])
+})
+const hasApprovableButtons = computed(() => {
+  if (!approvableButtons.value) {
+    return false
+  }
+  return approvableButtons.value.length > 0
+})
+
+const icons = useIconRegistry()
+const messages = useMessages()
+
+const onApproveStatusChange = (button) => {
+  let approvableId = get(props.value, 'id')
+
+  if (!approvableId) {
+    return
+  }
+  onUpdateStatus(approvableId, button)
+}
+const onUpdateStatus = async (id, button) => {
+  emits('isLoading', true)
+  isLoading.value = true
+  const response = await new ApprovableStepRepository().updateApproveStatus(id, button)
+
+  if (isSuccessResponse(response)) {
+    notifySuccess(messages.actionSucceeded)
+  }
+  emits('isLoading', false)
+  emits('refresh')
+}
+</script>

package/src/components/approvable/ApprovableStep.vue

@@ -0,0 +1,235 @@
+<template>
+  <li v-if="step.isVisible" :class="rowClass">
+    <span :class="discClass">
+      <svg
+        v-if="discGlyph"
+        aria-hidden="true"
+        fill="none"
+        stroke="currentColor"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        viewBox="0 0 16 16"
+      >
+        <path :d="discGlyph.d" :stroke-width="discGlyph.width" />
+      </svg>
+    </span>
+
+    <div class="approvable-step-body">
+      <div class="approvable-step-line">
+        <slot :step="value" name="approvableStepInfo">
+          <span class="approvable-step-name">{{ step.approverName }}</span>
+        </slot>
+
+        <slot :step="value" :role="step.approverRole" name="approvableStepRole">
+          <!-- The title is the whole role, so a clipped one is still readable
+               on hover; without a role the spacer keeps the row's geometry. -->
+          <span v-if="step.approverRole" :title="step.approverRole" class="approvable-step-role">
+            {{ step.approverRole }}
+          </span>
+          <span v-else class="approvable-step-spacer" />
+        </slot>
+
+        <!-- On the step being waited on the buttons carry the meaning, so the
+             status word is redundant; everywhere else it is the outcome. -->
+        <span v-if="showStatus" class="approvable-step-status">
+          <span v-if="step.statusName">{{ step.statusName }}</span>
+          <time v-if="step.performedAt" class="approvable-step-date">{{ step.performedAt }}</time>
+        </span>
+
+        <div v-if="hasActions" class="approvable-step-actions">
+          <div class="approvable-btn-group">
+            <!--      APPROVABLE BUTTONS (custom renderer per button, else basic)      -->
+            <template v-for="(button, index) in step.buttons" :key="button.id ?? index">
+              <component
+                :is="buttonRenderer(button)"
+                v-if="buttonRenderer(button)"
+                :action-ui="button.action_ui"
+                :approvable="approvable"
+                :button="button"
+                :buttons="[button]"
+                :complete="onApproveStatusChange"
+                :resource="resource"
+                :step="value"
+                @is-loading="(isLoading) => emits('isLoading', isLoading)"
+                @refresh="emits('refresh')"
+              />
+              <component
+                :is="linkComponent"
+                v-else-if="button.link"
+                v-bind="linkProps(linkComponent, button.link)"
+              >
+                <button
+                  :title="button.tooltip"
+                  :class="buttonClass(button)"
+                  type="button"
+                  @click="onApproveStatusChange(button)"
+                >
+                  <i v-if="isClassIcon(button.icon)" :class="button.icon"></i>
+                </button>
+              </component>
+              <button
+                v-else
+                :title="button.tooltip"
+                :class="buttonClass(button)"
+                type="button"
+                @click="onApproveStatusChange(button)"
+              >
+                <i v-if="isClassIcon(button.icon)" :class="button.icon"></i>
+                {{ button.text }}
+              </button>
+            </template>
+          </div>
+
+          <div v-if="value.can_comment" class="approvable-btn-group">
+            <approvable-step-comment
+              :approvable-step="value"
+              :disabled="!value.can_comment"
+              @refresh="emits('refresh')"
+              @is-loading="(isLoading) => emits('isLoading', isLoading)"
+            />
+          </div>
+        </div>
+      </div>
+
+      <p v-if="step.comment.text" class="approvable-step-comment">
+        <span :title="step.comment.title">{{ commentText }}</span>
+        <button
+          v-if="step.comment.isTrimmed"
+          type="button"
+          class="approvable-step-comment-more"
+          :aria-expanded="isCommentExpanded"
+          @click="isCommentExpanded = !isCommentExpanded"
+        >
+          {{ isCommentExpanded ? messages.showLess : messages.showMore }}
+        </button>
+      </p>
+    </div>
+  </li>
+</template>
+
+<script setup>
+import { computed, ref } from 'vue'
+import {
+  approvableStatusTone,
+  approvableStepGlyph,
+  createStepViewModel,
+  performStepAction
+} from '@stsdti/approvable-core'
+import ApprovableStepComment from './ApprovableStepComment.vue'
+import { approvableActionRenderer } from './action-renderers.js'
+import { linkProps, useLinkComponent } from '../../config.js'
+import { isClassIcon } from '../../icons.js'
+import { useMessages } from '../../messages.js'
+
+const emits = defineEmits(['isLoading', 'refresh'])
+
+const props = defineProps({
+  value: {
+    type: Object,
+    required: true
+  },
+  approvable: {
+    type: Object,
+    required: true
+  },
+  resource: {
+    type: Object,
+    required: true
+  }
+})
+
+const linkComponent = useLinkComponent()
+const messages = useMessages()
+
+const isCommentExpanded = ref(false)
+
+// Every derivation lives in core, so this component is left with rendering and
+// event plumbing only — and a React binding computes exactly the same values.
+const step = computed(() => createStepViewModel(props.value))
+
+const tone = computed(() => approvableStatusTone(step.value.status))
+
+/**
+ * A row shows controls when it has any — a finished step usually has none, and
+ * shows when it was decided instead.
+ */
+const hasActions = computed(() => step.value.buttons.length > 0 || !!props.value.can_comment)
+
+const showStatus = computed(() => (
+  (!step.value.isActive || !hasActions.value) && !!(step.value.statusName || step.value.performedAt)
+))
+
+const rowClass = computed(() => ({
+  'approvable-step': true,
+  'approvable-step--active': step.value.isActive,
+  // A step nobody has reached yet is dimmed; one with an outcome is not.
+  'approvable-step--pending': !step.value.isActive && !tone.value,
+  [`approvable-step--${tone.value}`]: !!tone.value,
+  // Nothing wraps below the name, so the row can hold to a single line.
+  'approvable-step--single-line': !hasActions.value && !step.value.comment.text
+}))
+
+/** `ring` and `pending` are drawn by the disc's border alone — no path. */
+const GLYPHS = {
+  check: { d: 'M4 8.4l2.8 2.8 5.4-6', width: 2.8 },
+  cross: { d: 'M5.2 5.2l5.6 5.6M10.8 5.2l-5.6 5.6', width: 2.4 },
+  dash: { d: 'M4.4 8h7.2', width: 2.2 }
+}
+
+/** The disc's own modifier: the glyph names the shape, the tone names the colour. */
+const DISC_MODIFIERS = {
+  check: 'success',
+  cross: 'danger',
+  dash: 'muted',
+  ring: 'ring',
+  pending: 'pending'
+}
+
+const glyph = computed(() => approvableStepGlyph(tone.value, step.value.isActive))
+
+const discGlyph = computed(() => GLYPHS[glyph.value] ?? null)
+
+const discClass = computed(() => ({
+  'approvable-step-disc': true,
+  [`approvable-step-disc--${DISC_MODIFIERS[glyph.value]}`]: true
+}))
+
+const commentText = computed(() => (
+  isCommentExpanded.value ? step.value.comment.text : step.value.comment.preview
+))
+
+const buttonClass = (button) => ({
+  'approvable-btn': true,
+  // A button carrying only an icon collapses to a circle, so the row keeps its
+  // rhythm instead of stretching around an empty label.
+  'approvable-btn--icon': !button.text,
+  'approvable-btn--primary': button.result === 'approved'
+})
+
+const buttonRenderer = (button) => {
+  if (!step.value.isActive) {
+    return null
+  }
+
+  return approvableActionRenderer(button?.action_ui)
+}
+
+const onApproveStatusChange = async (buttonOrId) => {
+  emits('isLoading', true)
+
+  const result = await performStepAction({
+    stepId: step.value.id,
+    button: buttonOrId,
+    buttons: step.value.buttons
+  })
+
+  emits('isLoading', false)
+
+  // Refresh after any attempted request, success or failure — a failed action
+  // still means the local state may be stale. Only a skipped one (no id, no
+  // button, or a presentational button) reloads nothing, since it sent nothing.
+  if (!result.skipped) {
+    emits('refresh')
+  }
+}
+</script>