@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/visual-editor-navigation.ts

@@ -0,0 +1,29 @@
+/**
+ * Workflows Module - Visual Editor Navigation Helpers
+ *
+ * Small pure helpers for drilling into a referenced sub-workflow ("Otwórz
+ * środek"): build the child editor href and extract the child definition's row
+ * id from the definitions list API response.
+ */
+
+/**
+ * The Studio's blank/template-picker entry point. The retired form-create route
+ * forwards here (spec section 10), and the definitions list opens the template
+ * gallery which lands on the same page.
+ */
+export const WORKFLOW_STUDIO_CREATE_HREF = '/backend/definitions/visual-editor'
+
+export function buildVisualEditorHref(definitionId: string): string {
+  return `/backend/definitions/visual-editor?id=${encodeURIComponent(definitionId)}`
+}
+
+/**
+ * Pull the first definition row id from a `GET /api/workflows/definitions`
+ * response. Returns null when the list is empty or malformed.
+ */
+export function extractFirstDefinitionId(
+  payload: { data?: Array<{ id?: string }> } | null | undefined,
+): string | null {
+  const first = payload?.data?.[0]
+  return first && typeof first.id === 'string' && first.id.length > 0 ? first.id : null
+}

package/src/modules/workflows/lib/work-inbox/empty-state.ts

@@ -0,0 +1,150 @@
+/**
+ * Why the Work Inbox is empty (PURE).
+ *
+ * §6.4 shipped default-ON, and it changed what an empty inbox MEANS. Before it,
+ * anybody holding `workflows.tasks.view` read the whole organisation's tasks;
+ * now `visible = SCOPE ∧ (RELATIONSHIP ∨ ADMINISTRATIVE) ∧ ENTITY`. So an
+ * employee who is neither an assignee nor a member of a role queue went from a
+ * full list to a blank one with nothing on screen to explain it. This module is
+ * the explanation, and it is PURE for the same reason `lib/task-visibility.ts`
+ * is: the decision has to be assertable without a page, a container or a query.
+ *
+ * It DECIDES ONLY. It reads no ACL, re-derives no part of the rule, and never
+ * widens what §6.4 discloses — it consumes signal the API already returned
+ * (`meta.degradedKinds`, `diagnostics.entityHiddenCount`) plus the caller's own
+ * filter state, and answers with a key.
+ *
+ * Precedence, strongest evidence first:
+ *
+ * 1. `degraded` — a source threw, so the merged page is missing an unknown
+ *    amount of work. Every other verdict would claim a completeness the response
+ *    does not have, and "nothing is assigned to you" would be a guess dressed as
+ *    a fact.
+ * 2. `entity-hidden` — the server REPORTED rows that matched the query and were
+ *    then refused by the entity gate. Their existence proves the filters are not
+ *    the whole story, which is why this outranks `filtered`.
+ * 3. `filtered` — the caller narrowed the query themselves. Telling somebody
+ *    their permissions are wrong when they merely picked a status is the failure
+ *    mode this whole surface exists to prevent, so a narrowing always answers
+ *    before the relationship verdict.
+ * 4. `no-relationship` — the common case, and the only one reached by pure
+ *    inference from absence.
+ *
+ * **`myWork` is deliberately NOT a narrowing signal.** It defaults to `'true'`
+ * on the page, and its server-side meaning (assigned ∨ claimed ∨ role overlap)
+ * is exactly the RELATIONSHIP clause a non-administrative caller is already
+ * restricted to — clearing it shows that caller nothing new. Counting it would
+ * make EVERY employee's empty inbox answer `filtered`, which is precisely the
+ * explanation they must not be given.
+ */
+
+/** Filter ids that genuinely narrow the query. `myWork` is excluded — see above. */
+export const WORK_INBOX_NARROWING_FILTER_IDS = [
+  'kind',
+  'module',
+  'entityType',
+  'role',
+  'priority',
+  'status',
+  'overdue',
+] as const
+
+export type WorkInboxNarrowingFilterId = (typeof WORK_INBOX_NARROWING_FILTER_IDS)[number]
+
+export type WorkInboxEmptyStateInput = {
+  /** The filter-bar state as the page holds it. */
+  filterValues: Readonly<Record<string, unknown>>
+  /**
+   * `diagnostics.entityHiddenCount` from the work-inbox response. It is present
+   * only for a caller the API already deemed diagnosable (a
+   * `workflows.tasks.view_all` holder or a superadmin); for everybody else the
+   * gate removed those rows in SQL, the field is absent, and this stays `0`.
+   */
+  entityHiddenCount: number
+  /** `meta.degradedKinds` — sources whose provider threw. */
+  degradedKinds: readonly string[]
+}
+
+/**
+ * The copy to render, as keys.
+ *
+ * A discriminated union rather than four uniform records, because the `filtered`
+ * case deliberately carries NO copy of its own: it is rendered through the
+ * shared `FilteredEmptyResults` (via `DataTable`'s `filterAwareEmptyState`),
+ * which already owns that message and the clear-filters affordance. Minting a
+ * second set of keys for it would be a second place for the two to disagree.
+ */
+export type WorkInboxEmptyState =
+  | {
+      kind: 'filtered'
+      narrowedFilterIds: readonly WorkInboxNarrowingFilterId[]
+    }
+  | {
+      kind: 'degraded' | 'entity-hidden' | 'no-relationship'
+      narrowedFilterIds: readonly WorkInboxNarrowingFilterId[]
+      titleKey: string
+      descriptionKey: string
+      /** Interpolation for `descriptionKey`. Never carries a record, id or reason code. */
+      descriptionVars: Readonly<Record<string, number>>
+    }
+
+export type WorkInboxEmptyStateKind = WorkInboxEmptyState['kind']
+
+/** A filter is applied when it holds a non-empty string, the shape `FilterBar` writes. */
+export function resolveWorkInboxNarrowingFilters(
+  filterValues: Readonly<Record<string, unknown>>,
+): WorkInboxNarrowingFilterId[] {
+  return WORK_INBOX_NARROWING_FILTER_IDS.filter((id) => {
+    const value = filterValues[id]
+    return typeof value === 'string' && value.length > 0
+  })
+}
+
+/**
+ * Answer why the inbox is empty. Consulted only when the page has zero rows.
+ *
+ * What each verdict is allowed to say is as load-bearing as which one is picked:
+ *
+ * - `entity-hidden` names a COUNT and nothing else. §6.4 keeps
+ *   `denied:entity-access` and `denied:unknown-entity-type` apart in the API so
+ *   an author's typo can be told from a policy refusal, and it keeps some
+ *   refusals indistinguishable on purpose. The empty state collapses both into
+ *   one sentence and names no record, binding, entity type or reason code.
+ * - `degraded` names no kind. A source's kind is the id of a module that may not
+ *   be one this caller is otherwise told exists.
+ */
+export function resolveWorkInboxEmptyState(input: WorkInboxEmptyStateInput): WorkInboxEmptyState {
+  const narrowedFilterIds = resolveWorkInboxNarrowingFilters(input.filterValues)
+
+  if (input.degradedKinds.length > 0) {
+    return {
+      kind: 'degraded',
+      narrowedFilterIds,
+      titleKey: 'workflows.workInbox.empty.degraded.title',
+      descriptionKey: 'workflows.workInbox.empty.degraded.description',
+      descriptionVars: {},
+    }
+  }
+
+  if (input.entityHiddenCount > 0) {
+    return {
+      kind: 'entity-hidden',
+      narrowedFilterIds,
+      titleKey: 'workflows.workInbox.empty.entityHidden.title',
+      descriptionKey: 'workflows.workInbox.empty.entityHidden.description',
+      descriptionVars: { count: input.entityHiddenCount },
+    }
+  }
+
+  if (narrowedFilterIds.length > 0) {
+    return { kind: 'filtered', narrowedFilterIds }
+  }
+
+  return {
+    kind: 'no-relationship',
+    narrowedFilterIds,
+    titleKey: 'workflows.workInbox.empty.noRelationship.title',
+    descriptionKey: 'workflows.workInbox.empty.noRelationship.description',
+    descriptionVars: {},
+  }
+}

package/src/modules/workflows/lib/work-inbox/entity-links.ts

@@ -0,0 +1,99 @@
+/**
+ * Deep links from a task's entity bindings to the record they are about (PURE).
+ *
+ * A binding's `entityType` is AUTHORED free text — the inspector offers
+ * `customers:person` as a placeholder but stores whatever the author typed —
+ * so this is a tolerant lookup over an explicitly enumerated set, never a
+ * guess. Anything not enumerated resolves to `null` and the panel renders the
+ * binding as plain text: a wrong link is worse than no link.
+ *
+ * Separator spelling is normalized because the same record type is written two
+ * ways across the platform: entity ids use `module:entity`
+ * (`entities.ids.generated.ts`) while record-detail injection contexts use
+ * `module.entity` (`resourceKind`). Both must resolve to the same target.
+ */
+
+import {
+  TASK_ENTITY_TYPE_ALIAS_GROUPS,
+  normalizeTaskEntityTypeSpelling,
+} from '../task-entity-aliases'
+
+const CUSTOMER_PERSON = 'customers:person'
+const CUSTOMER_COMPANY = 'customers:company'
+const CUSTOMER_DEAL = 'customers:deal'
+const SALES_ORDER = 'sales:order'
+
+export const WORK_INBOX_LINKED_ENTITY_TYPES = [
+  CUSTOMER_PERSON,
+  CUSTOMER_COMPANY,
+  CUSTOMER_DEAL,
+  SALES_ORDER,
+] as const
+
+export type WorkInboxLinkedEntityType = (typeof WORK_INBOX_LINKED_ENTITY_TYPES)[number]
+
+/**
+ * The generated entity id behind each linkable record type. This is the only
+ * mapping this file owns — the SPELLINGS come from `lib/task-entity-types.ts`,
+ * which is the single alias dictionary, so a spelling added for the visibility
+ * gate automatically resolves to a deep link too and the two cannot drift.
+ */
+const LINK_TARGET_BY_ENTITY_ID: Record<string, WorkInboxLinkedEntityType> = {
+  'customers:customer_person_profile': CUSTOMER_PERSON,
+  'customers:customer_company_profile': CUSTOMER_COMPANY,
+  'customers:customer_deal': CUSTOMER_DEAL,
+  'sales:sales_order': SALES_ORDER,
+}
+
+const ENTITY_TYPE_ALIASES: Record<string, WorkInboxLinkedEntityType> = Object.fromEntries(
+  TASK_ENTITY_TYPE_ALIAS_GROUPS.flatMap((group) => {
+    const target = LINK_TARGET_BY_ENTITY_ID[group.entityId]
+    return target ? group.spellings.map((spelling) => [spelling, target] as const) : []
+  }),
+)
+
+const ENTITY_DETAIL_PATHS: Record<WorkInboxLinkedEntityType, string> = {
+  [CUSTOMER_PERSON]: '/backend/customers/people-v2',
+  [CUSTOMER_COMPANY]: '/backend/customers/companies-v2',
+  [CUSTOMER_DEAL]: '/backend/customers/deals',
+  [SALES_ORDER]: '/backend/sales/orders',
+}
+
+/** `Customers.Person` / `customers.person` / `customers:person` → `customers:person`. */
+export const normalizeEntityType = normalizeTaskEntityTypeSpelling
+
+export function resolveLinkedEntityType(entityType: string): WorkInboxLinkedEntityType | null {
+  return ENTITY_TYPE_ALIASES[normalizeEntityType(entityType)] ?? null
+}
+
+/**
+ * Backend detail href for a bound record, or `null` when the record type has no
+ * enumerated detail page or the binding carries no id.
+ */
+export function buildEntityRecordHref(
+  entityType: string | null | undefined,
+  entityId: string | null | undefined,
+): string | null {
+  if (!entityType || !entityId) return null
+  const canonical = resolveLinkedEntityType(entityType)
+  if (!canonical) return null
+  return `${ENTITY_DETAIL_PATHS[canonical]}/${encodeURIComponent(entityId)}`
+}
+
+/**
+ * Every spelling of one record type, so a caller filtering the work inbox by
+ * `entityType` matches bindings however their author spelled them.
+ */
+export function entityTypeQueryValues(entityType: string): string[] {
+  const normalized = normalizeEntityType(entityType)
+  const canonical = resolveLinkedEntityType(entityType)
+  const values = new Set<string>([entityType, normalized, normalized.replace(/:/g, '.')])
+  if (canonical) {
+    for (const [alias, target] of Object.entries(ENTITY_TYPE_ALIASES)) {
+      if (target !== canonical) continue
+      values.add(alias)
+      values.add(alias.replace(/:/g, '.'))
+    }
+  }
+  return [...values].filter((value) => value.length > 0)
+}

package/src/modules/workflows/lib/work-inbox/navigation.ts

@@ -0,0 +1,28 @@
+/**
+ * Work Inbox — canonical hrefs (PURE).
+ *
+ * Mirrors `lib/visual-editor-navigation.ts`: every link to the inbox is built
+ * from here rather than from a literal path, so the retired `/backend/tasks`
+ * bridge and any future move are a one-line change.
+ */
+
+export const WORK_INBOX_HREF = '/backend/work-inbox'
+
+/**
+ * Task detail is deliberately still `/backend/tasks/<id>` — the spec keeps
+ * instance URLs, and only the LIST moved.
+ */
+export function buildWorkInboxItemHref(itemId: string): string {
+  return `/backend/tasks/${itemId}`
+}
+
+/**
+ * Widget-injection spot on the task detail surface (spec §7.6).
+ *
+ * A FROZEN contract surface (BACKWARD_COMPATIBILITY.md §6) once a third party
+ * mounts a widget on it. It exists because the detail page can only walk a
+ * task's `formSchema` GENERICALLY: an agent-disposition task rendered that way
+ * is a key/value dump of the mutation an operator is being asked to approve.
+ * The module that owns the proposal renders it properly instead.
+ */
+export const TASK_DETAIL_INJECTION_SPOT_ID = 'workflows.task.detail:context'

package/src/modules/workflows/lib/work-inbox/presentation.ts

@@ -0,0 +1,163 @@
+/**
+ * Work Inbox — status and priority presentation (PURE).
+ *
+ * Two rules the module is held to live here rather than inside the page:
+ *
+ * 1. **Design-system tokens only.** The retired task list hard-coded
+ *    `bg-yellow-100` / `bg-blue-100` / `bg-green-100` badges and `text-red-600`
+ *    overdue markers, none of which are dark-mode aware.
+ * 2. **Status is never colour-only** (workflows AGENTS.md → canvas/status rule,
+ *    spec §4.6). Every descriptor therefore pairs its token with an icon name
+ *    AND keeps its own translated label, so the badge reads without colour.
+ *
+ * Icon *names* rather than components keep this file free of React so it can be
+ * asserted as data.
+ */
+
+import type { TaskActionBlockReason } from '../../data/types'
+import type { WorkInboxPriority } from './provider'
+
+export type WorkInboxToneClasses = {
+  badge: string
+  icon: string
+  text: string
+}
+
+export type WorkInboxStatusDescriptor = WorkInboxToneClasses & {
+  iconName: WorkInboxIconName
+}
+
+export type WorkInboxIconName =
+  | 'Clock'
+  | 'Loader'
+  | 'CheckCircle2'
+  | 'XCircle'
+  | 'AlertTriangle'
+  | 'Flame'
+  | 'ArrowUp'
+  | 'Minus'
+  | 'ArrowDown'
+  | 'Circle'
+
+const NEUTRAL: WorkInboxToneClasses = {
+  badge: 'bg-status-neutral-bg text-status-neutral-text',
+  icon: 'text-status-neutral-icon',
+  text: 'text-status-neutral-text',
+}
+
+const INFO: WorkInboxToneClasses = {
+  badge: 'bg-status-info-bg text-status-info-text',
+  icon: 'text-status-info-icon',
+  text: 'text-status-info-text',
+}
+
+const WARNING: WorkInboxToneClasses = {
+  badge: 'bg-status-warning-bg text-status-warning-text',
+  icon: 'text-status-warning-icon',
+  text: 'text-status-warning-text',
+}
+
+const SUCCESS: WorkInboxToneClasses = {
+  badge: 'bg-status-success-bg text-status-success-text',
+  icon: 'text-status-success-icon',
+  text: 'text-status-success-text',
+}
+
+const ERROR: WorkInboxToneClasses = {
+  badge: 'bg-status-error-bg text-status-error-text',
+  icon: 'text-status-error-icon',
+  text: 'text-status-error-text',
+}
+
+const STATUS_DESCRIPTORS: Record<string, WorkInboxStatusDescriptor> = {
+  PENDING: { ...WARNING, iconName: 'Clock' },
+  IN_PROGRESS: { ...INFO, iconName: 'Loader' },
+  COMPLETED: { ...SUCCESS, iconName: 'CheckCircle2' },
+  CANCELLED: { ...NEUTRAL, iconName: 'XCircle' },
+  ESCALATED: { ...ERROR, iconName: 'AlertTriangle' },
+}
+
+/** An unknown status from a third-party source still renders, neutrally. */
+export function describeWorkInboxStatus(status: string): WorkInboxStatusDescriptor {
+  return STATUS_DESCRIPTORS[status] ?? { ...NEUTRAL, iconName: 'Circle' }
+}
+
+const PRIORITY_DESCRIPTORS: Record<WorkInboxPriority, WorkInboxStatusDescriptor> = {
+  extreme: { ...ERROR, iconName: 'Flame' },
+  high: { ...WARNING, iconName: 'ArrowUp' },
+  medium: { ...INFO, iconName: 'Minus' },
+  low: { ...NEUTRAL, iconName: 'ArrowDown' },
+}
+
+export function describeWorkInboxPriority(
+  priority: WorkInboxPriority | null,
+): WorkInboxStatusDescriptor | null {
+  return priority ? PRIORITY_DESCRIPTORS[priority] : null
+}
+
+export const WORK_INBOX_OVERDUE_TONE: WorkInboxStatusDescriptor = {
+  ...ERROR,
+  iconName: 'AlertTriangle',
+}
+
+export type TaskActionBlockDescriptor = WorkInboxToneClasses & {
+  iconName: WorkInboxIconName
+  /** Flat i18n key for the sentence a human can act on. */
+  messageKey: string
+  /**
+   * The remedy §6.4 names, when there is one. `reassign` is the ONLY remedy the
+   * model offers for an ownership refusal — administration widens seeing, never
+   * acting, so taking the row is the supported path.
+   */
+  remedy: 'reassign' | null
+}
+
+/**
+ * How an act refusal reads to a human (PURE).
+ *
+ * The reason itself is the SERVER's (`lib/task-visibility.ts`); this only says
+ * which sentence and which DS tone render it, so the page never decides whether
+ * an action is allowed. `unavailable` stays deliberately vague — it stands for
+ * the entity-gate refusal the act routes answer as a bare 404, and widening it
+ * into "binding X blocked you" would leak exactly what that 404 withholds.
+ */
+const TASK_ACTION_BLOCK_DESCRIPTORS: Record<TaskActionBlockReason, TaskActionBlockDescriptor> = {
+  'not-workable': {
+    ...INFO,
+    iconName: 'CheckCircle2',
+    messageKey: 'workflows.tasks.detail.cannotComplete',
+    remedy: null,
+  },
+  'owned-by-another': {
+    ...WARNING,
+    iconName: 'AlertTriangle',
+    messageKey: 'workflows.tasks.detail.blocked.ownedByAnother',
+    remedy: 'reassign',
+  },
+  'not-in-your-queue': {
+    ...WARNING,
+    iconName: 'AlertTriangle',
+    messageKey: 'workflows.tasks.detail.blocked.notInYourQueue',
+    remedy: 'reassign',
+  },
+  unowned: {
+    ...WARNING,
+    iconName: 'AlertTriangle',
+    messageKey: 'workflows.tasks.detail.blocked.unowned',
+    remedy: 'reassign',
+  },
+  unavailable: {
+    ...INFO,
+    iconName: 'AlertTriangle',
+    messageKey: 'workflows.tasks.detail.blocked.unavailable',
+    remedy: null,
+  },
+}
+
+/** An unknown reason from a newer server still renders, non-diagnostically. */
+export function describeTaskActionBlock(reason: string): TaskActionBlockDescriptor {
+  return (
+    TASK_ACTION_BLOCK_DESCRIPTORS[reason as TaskActionBlockReason] ??
+    TASK_ACTION_BLOCK_DESCRIPTORS.unavailable
+  )
+}