@happyvertical/smrt-sales 0.39.2

package/dist/svelte/components/AttributionConflictQueue.svelte

@@ -0,0 +1,361 @@
+<script lang="ts">
+/**
+ * AttributionConflictQueue — operator review queue for attribution
+ * exceptions (#1931).
+ *
+ * Open exceptions show the competing candidate touches and an award editor:
+ * per-referrer credit fractions that must sum to 100% (validated inline, the
+ * same rule `AttributionService.resolveException` enforces) plus a REQUIRED
+ * resolution reason — the resolve button stays disabled until both hold.
+ * Resolved exceptions render their read-only audit trail.
+ */
+import { FormGroup, Input, Textarea } from '@happyvertical/smrt-ui/forms';
+import { Badge, Button, Card } from '@happyvertical/smrt-ui/ui';
+import { formatDate, formatPercent } from '../format.js';
+import type { AttributionAward, AttributionExceptionView } from '../types.js';
+import {
+  equalSplitAwards,
+  uniqueCandidateReferrerIds,
+  validateAwards,
+} from '../types.js';
+
+export interface Props {
+  /** Exceptions to review (open and/or resolved). */
+  exceptions?: AttributionExceptionView[];
+  /** Disable actions while a resolution is in flight. */
+  busy?: boolean;
+  /** BCP 47 locale for date/percent formatting. */
+  locale?: string;
+  /** Resolve an open exception with explicit awards and a required reason. */
+  onResolve?: (
+    exceptionId: string,
+    awards: AttributionAward[],
+    resolutionReason: string,
+  ) => void;
+}
+
+let { exceptions = [], busy = false, locale, onResolve }: Props = $props();
+
+// Operator edits, keyed by exception id → referrer id → raw input string.
+let fractionDrafts = $state<Record<string, Record<string, string>>>({});
+// Resolution reasons, keyed by exception id.
+let reasonDrafts = $state<Record<string, string>>({});
+
+function referrerLabel(
+  exception: AttributionExceptionView,
+  referrerId: string,
+): string {
+  const candidate = exception.candidates.find(
+    (c) => c.referrerId === referrerId,
+  );
+  return candidate?.referrerName ?? referrerId.slice(0, 8);
+}
+
+/** Current award draft: equal-split defaults overlaid with operator edits. */
+function draftAwards(exception: AttributionExceptionView): AttributionAward[] {
+  const referrerIds = uniqueCandidateReferrerIds(exception.candidates);
+  const defaults = equalSplitAwards(referrerIds);
+  const overrides = fractionDrafts[exception.id] ?? {};
+  return defaults.map((award) => {
+    const raw = overrides[award.referrerId];
+    if (raw === undefined) return award;
+    return { referrerId: award.referrerId, creditFraction: Number(raw) };
+  });
+}
+
+function fractionInputValue(
+  exception: AttributionExceptionView,
+  referrerId: string,
+): string {
+  const raw = fractionDrafts[exception.id]?.[referrerId];
+  if (raw !== undefined) return raw;
+  const referrerIds = uniqueCandidateReferrerIds(exception.candidates);
+  const seeded = equalSplitAwards(referrerIds).find(
+    (award) => award.referrerId === referrerId,
+  );
+  return seeded ? String(seeded.creditFraction) : '';
+}
+
+function setFraction(exceptionId: string, referrerId: string, value: string) {
+  fractionDrafts = {
+    ...fractionDrafts,
+    [exceptionId]: {
+      ...(fractionDrafts[exceptionId] ?? {}),
+      [referrerId]: value,
+    },
+  };
+}
+
+function setReason(exceptionId: string, value: string) {
+  reasonDrafts = { ...reasonDrafts, [exceptionId]: value };
+}
+
+function resolve(exception: AttributionExceptionView) {
+  const awards = draftAwards(exception);
+  const reason = (reasonDrafts[exception.id] ?? '').trim();
+  if (!validateAwards(awards).valid || reason === '') return;
+  onResolve?.(exception.id, awards, reason);
+}
+</script>
+
+<section class="sales-attribution-queue">
+  {#if exceptions.length === 0}
+    <p class="empty">No attribution exceptions to review.</p>
+  {:else}
+    {#each exceptions as exception (exception.id)}
+      {@const open = exception.status === 'open'}
+      {@const awards = draftAwards(exception)}
+      {@const validation = validateAwards(awards)}
+      {@const reason = (reasonDrafts[exception.id] ?? '').trim()}
+      <Card variant="outlined">
+        <div class="head">
+          <span class="head__target">
+            <span class="head__kind">{exception.targetKind}</span>
+            {exception.targetLabel ?? exception.targetId}
+          </span>
+          <span class="head__badges">
+            {#if exception.programName}
+              <Badge variant="default" size="sm">{exception.programName}</Badge>
+            {/if}
+            <Badge variant={open ? 'warning' : 'success'} size="sm">
+              {exception.status}
+            </Badge>
+          </span>
+        </div>
+
+        <p class="conflict-reason">{exception.conflictReason}</p>
+
+        <table class="candidates">
+          <caption class="visually-hidden">Competing candidate touches</caption>
+          <thead>
+            <tr>
+              <th scope="col">Referrer</th>
+              <th scope="col">Touch kind</th>
+              <th scope="col">Occurred</th>
+            </tr>
+          </thead>
+          <tbody>
+            {#each exception.candidates as candidate (candidate.touchId + candidate.referrerId)}
+              <tr>
+                <td>{candidate.referrerName ?? candidate.referrerId.slice(0, 8)}</td>
+                <td>{candidate.kind.replace(/_/g, ' ')}</td>
+                <td>{formatDate(candidate.occurredAt, locale)}</td>
+              </tr>
+            {/each}
+          </tbody>
+        </table>
+
+        {#if open && onResolve}
+          <div class="award-editor">
+            <h4>Award credit</h4>
+            {#each awards as award (award.referrerId)}
+              <div class="award-editor__row">
+                <span class="award-editor__name">
+                  {referrerLabel(exception, award.referrerId)}
+                </span>
+                <Input
+                  type="number"
+                  min="0"
+                  max="1"
+                  step="0.0001"
+                  value={fractionInputValue(exception, award.referrerId)}
+                  disabled={busy}
+                  aria-label={`Credit fraction for ${referrerLabel(exception, award.referrerId)}`}
+                  oninput={(event) =>
+                    setFraction(
+                      exception.id,
+                      award.referrerId,
+                      (event.currentTarget as HTMLInputElement).value,
+                    )}
+                />
+              </div>
+            {/each}
+            <p
+              class="award-editor__total"
+              class:invalid={!validation.valid}
+              role="status"
+            >
+              Total: {formatPercent(validation.totalFraction, locale)}
+              {#if !validation.valid && validation.message}
+                — {validation.message}
+              {/if}
+            </p>
+
+            <FormGroup
+              label="Resolution reason"
+              required
+              hint="Overrides are audited — say why this award is correct."
+            >
+              <Textarea
+                rows={2}
+                value={reasonDrafts[exception.id] ?? ''}
+                disabled={busy}
+                oninput={(event) =>
+                  setReason(
+                    exception.id,
+                    (event.currentTarget as HTMLTextAreaElement).value,
+                  )}
+              />
+            </FormGroup>
+
+            <Button
+              variant="primary"
+              size="sm"
+              disabled={busy || !validation.valid || reason === ''}
+              onclick={() => resolve(exception)}
+            >
+              Resolve
+            </Button>
+          </div>
+        {:else if !open}
+          <dl class="audit">
+            <div class="audit__item">
+              <dt>Mode</dt>
+              <dd>{exception.resolutionMode ?? '—'}</dd>
+            </div>
+            <div class="audit__item">
+              <dt>Reason</dt>
+              <dd>{exception.resolutionReason ?? '—'}</dd>
+            </div>
+            <div class="audit__item">
+              <dt>Resolved by</dt>
+              <dd>{exception.resolvedByName ?? '—'}</dd>
+            </div>
+            <div class="audit__item">
+              <dt>Resolved at</dt>
+              <dd>{formatDate(exception.resolvedAt, locale)}</dd>
+            </div>
+          </dl>
+        {/if}
+      </Card>
+    {/each}
+  {/if}
+</section>
+
+<style>
+  .sales-attribution-queue {
+    display: flex;
+    flex-direction: column;
+    gap: var(--smrt-spacing-4, 1rem);
+  }
+
+  .empty {
+    margin: 0;
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    font-style: italic;
+  }
+
+  .head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--smrt-spacing-2, 0.5rem);
+    margin-bottom: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .head__target {
+    font-weight: var(--smrt-typography-weight-semibold, 600);
+  }
+
+  .head__kind {
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    font-size: var(--smrt-typography-label-medium-size, 0.75rem);
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    margin-right: var(--smrt-spacing-1, 0.25rem);
+  }
+
+  .head__badges {
+    display: inline-flex;
+    gap: var(--smrt-spacing-1, 0.25rem);
+  }
+
+  .conflict-reason {
+    margin: 0 0 var(--smrt-spacing-3, 0.75rem);
+  }
+
+  .candidates {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: var(--smrt-typography-body-medium-size, 0.875rem);
+    margin-bottom: var(--smrt-spacing-3, 0.75rem);
+  }
+
+  .candidates th {
+    padding: var(--smrt-spacing-1, 0.25rem) var(--smrt-spacing-2, 0.5rem);
+    text-align: left;
+    font-weight: var(--smrt-typography-weight-semibold, 600);
+    border-bottom: 1px solid var(--smrt-color-outline-variant, #d8dde6);
+    white-space: nowrap;
+  }
+
+  .candidates td {
+    padding: var(--smrt-spacing-1, 0.25rem) var(--smrt-spacing-2, 0.5rem);
+    border-bottom: 1px solid var(--smrt-color-outline-variant, #d8dde6);
+  }
+
+  .award-editor {
+    display: flex;
+    flex-direction: column;
+    gap: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .award-editor h4 {
+    margin: 0;
+    font-size: var(--smrt-typography-label-large-size, 0.875rem);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--smrt-color-on-surface-variant, #64748b);
+  }
+
+  .award-editor__row {
+    display: flex;
+    align-items: center;
+    gap: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .award-editor__name {
+    flex: 0 0 12rem;
+  }
+
+  .award-editor__total {
+    margin: 0;
+    font-size: var(--smrt-typography-body-small-size, 0.8125rem);
+    color: var(--smrt-color-on-surface-variant, #64748b);
+  }
+
+  .award-editor__total.invalid {
+    color: var(--smrt-color-error, #dc2626);
+  }
+
+  .award-editor :global(.form-group) {
+    margin-bottom: 0;
+  }
+
+  .audit {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--smrt-spacing-4, 1rem);
+    margin: 0;
+  }
+
+  .audit__item dt {
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    font-size: var(--smrt-typography-label-medium-size, 0.75rem);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .audit__item dd {
+    margin: 0;
+  }
+
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+  }
+</style>

package/dist/svelte/components/AttributionConflictQueue.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { AttributionAward, AttributionExceptionView } from '../types.js';
+export interface Props {
+    /** Exceptions to review (open and/or resolved). */
+    exceptions?: AttributionExceptionView[];
+    /** Disable actions while a resolution is in flight. */
+    busy?: boolean;
+    /** BCP 47 locale for date/percent formatting. */
+    locale?: string;
+    /** Resolve an open exception with explicit awards and a required reason. */
+    onResolve?: (exceptionId: string, awards: AttributionAward[], resolutionReason: string) => void;
+}
+declare const AttributionConflictQueue: import("svelte").Component<Props, {}, "">;
+type AttributionConflictQueue = ReturnType<typeof AttributionConflictQueue>;
+export default AttributionConflictQueue;
+//# sourceMappingURL=AttributionConflictQueue.svelte.d.ts.map

package/dist/svelte/components/AttributionConflictQueue.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionConflictQueue.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/AttributionConflictQueue.svelte.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAQ9E,MAAM,WAAW,KAAK;IACpB,mDAAmD;IACnD,UAAU,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACxC,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,gBAAgB,EAAE,EAC1B,gBAAgB,EAAE,MAAM,KACrB,IAAI,CAAC;CACX;AAwLD,QAAA,MAAM,wBAAwB,2CAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/svelte/components/CommissionBreakdown.svelte

@@ -0,0 +1,251 @@
+<script lang="ts">
+/**
+ * CommissionBreakdown — the explainable-amount surface (#1933).
+ *
+ * Table of commission rows (event, basis, base, rate, share, amount, status,
+ * clearing date). Each row expands to the snapshotted calculation trace —
+ * plan key@version, component, and the `base × rate × share = amount` formula
+ * line — plus the append-only adjustments recorded against it.
+ */
+import { Badge, Button } from '@happyvertical/smrt-ui/ui';
+import { formatCents, formatDate, formatPercent } from '../format.js';
+import type { CommissionRowView } from '../types.js';
+import {
+  commissionStatusBadgeVariant,
+  formatCommissionFormula,
+  formatPlanRef,
+} from '../types.js';
+
+export interface Props {
+  /** Commission rows for one earner (or one earning source). */
+  commissions?: CommissionRowView[];
+  /** BCP 47 locale for money/date formatting. */
+  locale?: string;
+}
+
+let { commissions = [], locale }: Props = $props();
+
+const uid = $props.id();
+
+let expanded = $state<Record<string, boolean>>({});
+
+function toggle(id: string) {
+  expanded = { ...expanded, [id]: !expanded[id] };
+}
+
+function detailsId(id: string): string {
+  return `${uid}-commission-details-${id}`;
+}
+</script>
+
+<div class="sales-commission-breakdown">
+  {#if commissions.length === 0}
+    <p class="empty">No commissions yet.</p>
+  {:else}
+    <table>
+      <thead>
+        <tr>
+          <th scope="col">Event</th>
+          <th scope="col">Basis</th>
+          <th scope="col" class="num">Base</th>
+          <th scope="col" class="num">Rate</th>
+          <th scope="col" class="num">Share</th>
+          <th scope="col" class="num">Amount</th>
+          <th scope="col">Status</th>
+          <th scope="col">Clears</th>
+          <th scope="col"><span class="visually-hidden">Explanation</span></th>
+        </tr>
+      </thead>
+      <tbody>
+        {#each commissions as row (row.id)}
+          {@const isExpanded = !!expanded[row.id]}
+          <tr>
+            <td>
+              <span class="event-kind">{row.eventKind.replace(/_/g, ' ')}</span>
+              {#if row.sourceLabel}
+                <span class="secondary">{row.sourceLabel}</span>
+              {/if}
+            </td>
+            <td>{row.basis}</td>
+            <td class="num">{formatCents(row.baseAmountCents, row.currency, locale)}</td>
+            <td class="num">
+              {row.basis === 'fixed' ? '—' : formatPercent(row.rate, locale)}
+            </td>
+            <td class="num">{formatPercent(row.shareFraction, locale)}</td>
+            <td class="num amount" class:negative={row.amountCents < 0}>
+              {formatCents(row.amountCents, row.currency, locale)}
+            </td>
+            <td>
+              <Badge variant={commissionStatusBadgeVariant(row.status)} size="sm">
+                {row.status}
+              </Badge>
+            </td>
+            <td>{formatDate(row.clearingEndsAt, locale)}</td>
+            <td class="toggle-cell">
+              <Button
+                variant="ghost"
+                size="sm"
+                aria-expanded={isExpanded}
+                aria-controls={detailsId(row.id)}
+                onclick={() => toggle(row.id)}
+              >
+                {isExpanded ? 'Hide' : 'Explain'}
+              </Button>
+            </td>
+          </tr>
+          {#if isExpanded}
+            <tr class="details-row">
+              <td colspan="9" id={detailsId(row.id)}>
+                <div class="details">
+                  {#if row.trace}
+                    <p class="details__ref">
+                      Plan <code>{formatPlanRef(row.trace.planKey, row.trace.planVersion)}</code>
+                      · component <code>{row.trace.componentKey}</code>
+                    </p>
+                  {/if}
+                  <p class="details__formula">
+                    <code>
+                      {formatCommissionFormula(
+                        {
+                          basis: row.basis,
+                          baseAmountCents: row.baseAmountCents,
+                          rate: row.rate,
+                          shareFraction: row.shareFraction,
+                          amountCents: row.amountCents,
+                          currency: row.currency,
+                        },
+                        locale,
+                      )}
+                    </code>
+                  </p>
+                  {#if row.adjustments && row.adjustments.length > 0}
+                    <table class="adjustments">
+                      <caption class="visually-hidden">
+                        Adjustments against this commission
+                      </caption>
+                      <thead>
+                        <tr>
+                          <th scope="col">Kind</th>
+                          <th scope="col" class="num">Amount</th>
+                          <th scope="col">Reason</th>
+                          <th scope="col">Recorded</th>
+                        </tr>
+                      </thead>
+                      <tbody>
+                        {#each row.adjustments as adjustment (adjustment.id)}
+                          <tr>
+                            <td>{adjustment.adjustmentKind}</td>
+                            <td class="num" class:negative={adjustment.amountCents < 0}>
+                              {formatCents(adjustment.amountCents, adjustment.currency, locale)}
+                            </td>
+                            <td>{adjustment.reason}</td>
+                            <td>{formatDate(adjustment.createdAt, locale)}</td>
+                          </tr>
+                        {/each}
+                      </tbody>
+                    </table>
+                  {:else}
+                    <p class="details__none">No adjustments.</p>
+                  {/if}
+                </div>
+              </td>
+            </tr>
+          {/if}
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</div>
+
+<style>
+  .sales-commission-breakdown {
+    width: 100%;
+    overflow-x: auto;
+  }
+
+  .empty {
+    margin: 0;
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    font-style: italic;
+  }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: var(--smrt-typography-body-medium-size, 0.875rem);
+  }
+
+  th {
+    padding: var(--smrt-spacing-2, 0.5rem) var(--smrt-spacing-3, 0.75rem);
+    text-align: left;
+    font-weight: var(--smrt-typography-weight-semibold, 600);
+    background: var(--smrt-color-surface-container, #f3f4f6);
+    border-bottom: 1px solid var(--smrt-color-outline-variant, #d8dde6);
+    white-space: nowrap;
+  }
+
+  td {
+    padding: var(--smrt-spacing-2, 0.5rem) var(--smrt-spacing-3, 0.75rem);
+    border-bottom: 1px solid var(--smrt-color-outline-variant, #d8dde6);
+    vertical-align: top;
+  }
+
+  .num {
+    text-align: right;
+    white-space: nowrap;
+  }
+
+  .amount {
+    font-weight: var(--smrt-typography-weight-semibold, 600);
+  }
+
+  .negative {
+    color: var(--smrt-color-error, #dc2626);
+  }
+
+  .event-kind {
+    display: block;
+    font-weight: var(--smrt-typography-weight-medium, 500);
+  }
+
+  .secondary {
+    display: block;
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    font-size: var(--smrt-typography-body-small-size, 0.75rem);
+  }
+
+  .toggle-cell {
+    text-align: right;
+    white-space: nowrap;
+  }
+
+  .details-row td {
+    background: var(--smrt-color-surface-container-low, #f9fafb);
+  }
+
+  .details {
+    display: flex;
+    flex-direction: column;
+    gap: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .details__ref,
+  .details__formula,
+  .details__none {
+    margin: 0;
+  }
+
+  .details__none {
+    color: var(--smrt-color-on-surface-variant, #64748b);
+    font-style: italic;
+  }
+
+  code {
+    font-family: var(--smrt-font-family-mono, ui-monospace, monospace);
+    font-size: var(--smrt-typography-body-small-size, 0.8125rem);
+  }
+
+  .adjustments th {
+    background: transparent;
+  }
+</style>

package/dist/svelte/components/CommissionBreakdown.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { CommissionRowView } from '../types.js';
+export interface Props {
+    /** Commission rows for one earner (or one earning source). */
+    commissions?: CommissionRowView[];
+    /** BCP 47 locale for money/date formatting. */
+    locale?: string;
+}
+declare const CommissionBreakdown: import("svelte").Component<Props, {}, "">;
+type CommissionBreakdown = ReturnType<typeof CommissionBreakdown>;
+export default CommissionBreakdown;
+//# sourceMappingURL=CommissionBreakdown.svelte.d.ts.map

package/dist/svelte/components/CommissionBreakdown.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommissionBreakdown.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/CommissionBreakdown.svelte.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAQrD,MAAM,WAAW,KAAK;IACpB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA6ID,QAAA,MAAM,mBAAmB,2CAAwC,CAAC;AAClE,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAClE,eAAe,mBAAmB,CAAC"}