@nauticana/sail 1.1.18 → 1.1.19

package/README.md

@@ -876,8 +876,9 @@ For backward compatibility, the older OAuth-code flow `BaseAuthService.loginWith
 Horizontal building blocks for an entitlement-aware dashboard. All are presentational (signals in, events out) and ship no CSS — the app styles the documented class hooks and supplies the metric data, chart, and action logic.
 
 - **`DashboardShellComponent`** (`sail-dashboard-shell`) — responsive card-grid layout. `[heading]` + a `[dashboardActions]` projection slot for the header; project cards into the default slot. Styles: `.dashboard-shell` / `.dashboard-header` / `.dashboard-grid`.
-- **`DataCardComponent`** (`sail-data-card`) — card chrome for one visualization with `[state]` ∈ `loading | ready | empty | error | locked`. The chart is supplied as an `<ng-template>` and instantiated **only** in `ready`, so during loading/error/locked it never exists (no hidden canvas). `description` (required) is the screen-reader text alternative; `[tableHeaders]`/`[tableRows]` render a visually-hidden (`.sr-only`) data table. Emits `upgrade` / `retry`.
+- **`DataCardComponent`** (`sail-data-card`) — card chrome for one visualization with `[state]` ∈ `loading | ready | empty | error | locked | no-source`. The chart is supplied as an `<ng-template>` and instantiated **only** in `ready`, so during loading/error/locked/no-source it never exists (no hidden canvas). `description` (required) is the screen-reader text alternative; `[tableHeaders]`/`[tableRows]` render a visually-hidden (`.sr-only`) data table. Emits `upgrade`, `connect`, and `retry`.
 - **`LockedOverlayComponent`** (`sail-locked-overlay`) — entitlement gate. Wraps protected content given as an `<ng-template>`; when `[locked]` the template is never instantiated, so **no data exists behind the gate** (DOM, canvas, or network) — the strict free-tier rule. Emits `upgrade`.
+- **`NoSourceOverlayComponent`** (`sail-no-source-overlay`) — source-readiness gate. Takes `[sourceName]` and emits `connect`; while `[unavailable]`, its protected `<ng-template>` is never instantiated. Use this for included features whose provider is not connected or whose collector is unavailable—never show an upgrade prompt for this state.
 - **`ActionCenterComponent`** (`sail-action-center`) — prioritized next-best-action list from `[actions]: ActionItem[]` (sorted by `priority`, done items show a check). Emits `act`.
 - **`EntitySelectorComponent`** (`sail-entity-selector`) — scope dropdown over `[entities]: EntityOption[]`; resolves `[selected]` or the first active entity and emits `selectionChange`.
 - **`VerificationFlowComponent`** (`sail-verification-flow`) — self-service request → enter-code → verified UI (a 2FA sibling), backend-agnostic: emits `requestVerification` / `confirmCode`, driven by `[step]` + `[errorMessage]` the host feeds back.
@@ -890,6 +891,36 @@ Horizontal building blocks for an entitlement-aware dashboard. All are presentat
 
 Models: `DataCardState`, `ActionItem`, `EntityOption`, `VerificationStep`.
 
+Analytics clients that need this distinction can call the protected
+`analyticWithStatus<T>()` on `BaseRestService`. It returns
+`{ rows, source: { status, id } }`, populated from `X-Data-Source-Status` and
+`X-Data-Source`; the existing `analytic<T>()` remains `Observable<T[]>`.
+
+When the app and its API are on different origins the browser hides both headers
+unless the backend sends
+`Access-Control-Expose-Headers: X-Data-Source-Status, X-Data-Source`; without it
+`source.status` is `null` and a missing source is indistinguishable from an
+empty result.
+
+## Grouped review actions and diffs (v1.1.19)
+
+`GroupedBulkActionComponent` (`sail-grouped-bulk-action`) groups eligible rows
+with the consumer's `[groupBy]` function and renders an app-chosen bounded
+`[sampleSize]` through a projected `<ng-template>`. The app supplies all domain
+copy and an `[execute]` function returning `{ attempted, succeeded }`. When
+`succeeded < attempted`, the component visibly renders the app's
+`[partialSuccessMessage]`; it never reports a partial operation as complete.
+The outcome message renders above the groups (`role="alert"`,
+`.grouped-bulk-action__message--partial` / `--error`) and stays until the next
+action, so it survives the row refresh that removes its group. Group headings
+are `role="heading"` at `[headingLevel]` (default 3).
+
+`BeforeAfterDiffComponent` (`sail-before-after-diff`) renders a
+whitespace-preserving word-level LCS diff. `[maxTokens]` defaults to 2000; above
+the cap it skips the quadratic comparison and shows the whole new value as an
+addition. Additions and deletions are `<ins class="diff-add">` /
+`<del class="diff-del">`, unchanged text `<span class="diff-same">`. The pure `wordDiff()` helper is also exported for custom layouts.
+
 ## Provider connections (v1.1.9)
 
 `ConnectionPanel` is the drop-in UI for keel's `oauth/connect` layer — connect a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "scripts": {

package/src/component/dashboard/data_card.html

@@ -33,5 +33,12 @@
         <button matButton="elevated" type="button" class="primary" (click)="upgrade.emit()">{{ ctaLabel() }}</button>
       </div>
     }
+    @case ('no-source') {
+      <div class="data-card-no-source" role="group" [attr.aria-label]="(heading() || 'Insight') + ' — source unavailable'">
+        <p class="no-source-name">{{ sourceName() }}</p>
+        <p class="no-source-message">{{ noSourceMessage() }}</p>
+        <button matButton="elevated" type="button" class="primary" (click)="connect.emit()">{{ connectLabel() }}</button>
+      </div>
+    }
   }
 </section>

package/src/component/dashboard/data_card.ts

@@ -30,10 +30,14 @@ export class DataCardComponent {
   readonly errorMessage = input<string>('Could not load this data.');
   readonly emptyMessage = input<string>('No data yet.');
   readonly lockedMessage = input<string>('Upgrade to unlock this insight.');
+  readonly sourceName = input<string>('data source');
+  readonly noSourceMessage = input<string>('Connect the required data source to see this insight.');
   readonly ctaLabel = input<string>('Upgrade');
+  readonly connectLabel = input<string>('Connect');
   readonly tableHeaders = input<string[]>([]);
   readonly tableRows = input<(string | number)[][]>([]);
   readonly upgrade = output<void>();
+  readonly connect = output<void>();
   readonly retry = output<void>();
 
   /** The chart, provided as a single <ng-template>; instantiated only when ready. */

package/src/component/dashboard/no_source_overlay.html

@@ -0,0 +1,9 @@
+@if (unavailable()) {
+  <div class="no-source-overlay" role="group" [attr.aria-label]="sourceName() + ' — source unavailable'">
+    <p class="no-source-name">{{ sourceName() }}</p>
+    <p class="no-source-message">{{ message() }}</p>
+    <button matButton="elevated" type="button" class="primary" (click)="connect.emit()">{{ ctaLabel() }}</button>
+  </div>
+} @else if (content(); as tpl) {
+  <ng-container [ngTemplateOutlet]="tpl"></ng-container>
+}

package/src/component/dashboard/no_source_overlay.ts

@@ -0,0 +1,21 @@
+import { NgTemplateOutlet } from '@angular/common';
+import { ChangeDetectionStrategy, Component, TemplateRef, ViewEncapsulation, contentChild, input, output } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+
+/** Source-readiness sibling of LockedOverlayComponent: the template is never instantiated while unavailable. */
+@Component({
+  selector: 'sail-no-source-overlay',
+  templateUrl: './no_source_overlay.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule],
+})
+export class NoSourceOverlayComponent {
+  readonly unavailable = input.required<boolean>();
+  readonly sourceName = input.required<string>();
+  readonly message = input<string>('Connect this data source to continue.');
+  readonly ctaLabel = input<string>('Connect');
+  readonly connect = output<void>();
+
+  readonly content = contentChild(TemplateRef);
+}

package/src/component/table/before_after_diff.html

@@ -0,0 +1 @@
+<pre class="before-after-diff">@for (token of tokens(); track $index) {@switch (token.kind) {@case ('add') {<ins class="diff-add">{{ token.text }}</ins>}@case ('del') {<del class="diff-del">{{ token.text }}</del>}@default {<span class="diff-same">{{ token.text }}</span>}}}</pre>

package/src/component/table/before_after_diff.ts

@@ -0,0 +1,54 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+
+export type DiffTokenKind = 'same' | 'add' | 'del';
+
+export interface DiffToken {
+  text: string;
+  kind: DiffTokenKind;
+}
+
+/** Whitespace-preserving word-level LCS diff with a bounded work limit. */
+export function wordDiff(before: string, after: string, maxTokens = 2000): DiffToken[] {
+  const left = before.split(/(\s+)/).filter((token) => token.length > 0);
+  const right = after.split(/(\s+)/).filter((token) => token.length > 0);
+  if (left.length > maxTokens || right.length > maxTokens) return [{ text: after, kind: 'add' }];
+
+  const matrix = Array.from({ length: left.length + 1 }, () => new Uint32Array(right.length + 1));
+  for (let i = left.length - 1; i >= 0; i--) {
+    for (let j = right.length - 1; j >= 0; j--) {
+      matrix[i][j] = left[i] === right[j]
+        ? matrix[i + 1][j + 1] + 1
+        : Math.max(matrix[i + 1][j], matrix[i][j + 1]);
+    }
+  }
+
+  const tokens: DiffToken[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < left.length && j < right.length) {
+    if (left[i] === right[j]) {
+      tokens.push({ text: left[i++], kind: 'same' });
+      j++;
+    } else if (matrix[i + 1][j] >= matrix[i][j + 1]) {
+      tokens.push({ text: left[i++], kind: 'del' });
+    } else {
+      tokens.push({ text: right[j++], kind: 'add' });
+    }
+  }
+  while (i < left.length) tokens.push({ text: left[i++], kind: 'del' });
+  while (j < right.length) tokens.push({ text: right[j++], kind: 'add' });
+  return tokens;
+}
+
+@Component({
+  selector: 'sail-before-after-diff',
+  templateUrl: './before_after_diff.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class BeforeAfterDiffComponent {
+  readonly before = input.required<string>();
+  readonly after = input.required<string>();
+  readonly maxTokens = input<number>(2000);
+  readonly tokens = computed(() => wordDiff(this.before(), this.after(), this.maxTokens()));
+}

package/src/component/table/grouped_bulk_action.html

@@ -0,0 +1,36 @@
+@if (message(); as outcome) {
+  <p class="grouped-bulk-action__message"
+     [class.grouped-bulk-action__message--partial]="outcome.kind === 'partial'"
+     [class.grouped-bulk-action__message--error]="outcome.kind === 'error'"
+     role="alert">{{ outcome.text }}</p>
+}
+
+@for (group of groups(); track group.key) {
+  <section class="grouped-bulk-action" [attr.data-group-key]="group.key">
+    <header class="grouped-bulk-action__header">
+      <div class="grouped-bulk-action__heading" role="heading" [attr.aria-level]="headingLevel()">{{ heading()(group) }}</div>
+      <button matButton="filled" type="button"
+              [disabled]="busyKey() !== null"
+              (click)="run(group)">
+        {{ actionLabel()(group, busyKey() === group.key) }}
+      </button>
+    </header>
+
+    @if (description()(group); as text) {
+      <p class="grouped-bulk-action__description">{{ text }}</p>
+    }
+
+    @if (sampleTemplate(); as template) {
+      <div class="grouped-bulk-action__sample">
+        @for (row of group.sample; track $index) {
+          <ng-container [ngTemplateOutlet]="template"
+                        [ngTemplateOutletContext]="{ $implicit: row, group: group }"></ng-container>
+        }
+      </div>
+    }
+
+    @if (group.count > group.sample.length) {
+      <p class="grouped-bulk-action__remainder">{{ remainderLabel()(group.count - group.sample.length, group) }}</p>
+    }
+  </section>
+}

package/src/component/table/grouped_bulk_action.ts

@@ -0,0 +1,120 @@
+import { NgTemplateOutlet } from '@angular/common';
+import { ChangeDetectionStrategy, Component, DestroyRef, TemplateRef, ViewEncapsulation, computed, contentChild, inject, input, output, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { MatButtonModule } from '@angular/material/button';
+import { finalize, Observable } from 'rxjs';
+
+export type BulkGroupKey = string | number;
+
+export interface BulkActionGroup<T> {
+  key: BulkGroupKey;
+  rows: readonly T[];
+  sample: readonly T[];
+  count: number;
+}
+
+/** Generic outcome used to detect and report partial completion. */
+export interface BulkActionResult {
+  attempted: number;
+  succeeded: number;
+}
+
+export interface BulkActionCompletion<T> {
+  group: BulkActionGroup<T>;
+  result: BulkActionResult;
+}
+
+interface OutcomeMessage {
+  text: string;
+  kind: 'partial' | 'error';
+}
+
+/** The projected template receives each sample row as `$implicit` and its group as `group`. */
+@Component({
+  selector: 'sail-grouped-bulk-action',
+  templateUrl: './grouped_bulk_action.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule],
+})
+export class GroupedBulkActionComponent<T> {
+  readonly rows = input.required<readonly T[]>();
+  readonly groupBy = input.required<(row: T) => BulkGroupKey | null | undefined>();
+  readonly eligible = input<(row: T) => boolean>(() => true);
+  readonly sampleSize = input.required<number>();
+  readonly minimumGroupSize = input<number>(2);
+  readonly execute = input.required<(group: BulkActionGroup<T>) => Observable<BulkActionResult>>();
+
+  readonly heading = input.required<(group: BulkActionGroup<T>) => string>();
+  readonly headingLevel = input<number>(3);
+  readonly description = input<(group: BulkActionGroup<T>) => string>(() => '');
+  readonly actionLabel = input.required<(group: BulkActionGroup<T>, busy: boolean) => string>();
+  readonly remainderLabel = input.required<(remaining: number, group: BulkActionGroup<T>) => string>();
+  readonly partialSuccessMessage = input.required<(result: BulkActionResult, group: BulkActionGroup<T>) => string>();
+  readonly failureMessage = input.required<(error: unknown, group: BulkActionGroup<T>) => string>();
+  readonly sortGroups = input<(left: BulkActionGroup<T>, right: BulkActionGroup<T>) => number>(() => 0);
+
+  readonly finished = output<BulkActionCompletion<T>>();
+  readonly failed = output<{ group: BulkActionGroup<T>; error: unknown }>();
+
+  readonly busyKey = signal<BulkGroupKey | null>(null);
+  /** Held outside the groups: a refresh after the action usually removes the group it concerns. */
+  readonly message = signal<OutcomeMessage | null>(null);
+  readonly sampleTemplate = contentChild<TemplateRef<unknown>>(TemplateRef);
+  readonly groups = computed(() => this.buildGroups());
+
+  private readonly destroyRef = inject(DestroyRef);
+
+  run(group: BulkActionGroup<T>): void {
+    if (this.busyKey() !== null) return;
+    this.busyKey.set(group.key);
+    this.message.set(null);
+    let request: Observable<BulkActionResult>;
+    try {
+      request = this.execute()(group);
+    } catch (error) {
+      this.handleFailure(group, error);
+      return;
+    }
+    request.pipe(
+      takeUntilDestroyed(this.destroyRef),
+      finalize(() => this.busyKey.set(null)),
+    ).subscribe({
+      next: (result) => {
+        if (result.succeeded < result.attempted) {
+          this.message.set({ text: this.partialSuccessMessage()(result, group), kind: 'partial' });
+        }
+        this.finished.emit({ group, result });
+      },
+      error: (error: unknown) => this.handleFailure(group, error),
+    });
+  }
+
+  private buildGroups(): BulkActionGroup<T>[] {
+    const grouped = new Map<BulkGroupKey, T[]>();
+    for (const row of this.rows()) {
+      if (!this.eligible()(row)) continue;
+      const key = this.groupBy()(row);
+      if (key === null || key === undefined || key === '') continue;
+      const groupRows = grouped.get(key) ?? [];
+      groupRows.push(row);
+      grouped.set(key, groupRows);
+    }
+    const sampleSize = Math.max(0, this.sampleSize());
+    return [...grouped.entries()]
+      .filter(([, groupRows]) => groupRows.length >= this.minimumGroupSize())
+      .map(([key, groupRows]) => ({
+        key,
+        rows: groupRows,
+        sample: groupRows.slice(0, sampleSize),
+        count: groupRows.length,
+      }))
+      .sort(this.sortGroups());
+  }
+
+  private handleFailure(group: BulkActionGroup<T>, error: unknown): void {
+    this.busyKey.set(null);
+    this.message.set({ text: this.failureMessage()(error, group), kind: 'error' });
+    this.failed.emit({ group, error });
+  }
+}

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './component/abstract/base_table';
 export * from './component/dashboard/dashboard_shell';
 export * from './component/dashboard/data_card';
 export * from './component/dashboard/locked_overlay';
+export * from './component/dashboard/no_source_overlay';
 export * from './component/dashboard/action_center';
 export * from './component/dashboard/entity_selector';
 export * from './component/dashboard/verification_flow';
@@ -26,6 +27,8 @@ export * from './component/table/table_edit';
 export * from './component/table/table_detail';
 export * from './component/table/table_lookup';
 export * from './component/table/table_report';
+export * from './component/table/grouped_bulk_action';
+export * from './component/table/before_after_diff';
 export * from './component/navigation/navigation';
 export * from './component/login/login_component';
 export * from './component/login/register_component';

package/src/model/dashboard.ts

@@ -1,5 +1,5 @@
 /** Lifecycle state of a data/chart card (sail-data-card). */
-export type DataCardState = 'loading' | 'ready' | 'empty' | 'error' | 'locked';
+export type DataCardState = 'loading' | 'ready' | 'empty' | 'error' | 'locked' | 'no-source';
 
 /** A prioritized, completable next-best-action (sail-action-center, FR-008). */
 export interface ActionItem {

package/src/service/base_rest.service.ts

@@ -1,6 +1,6 @@
 import { HttpClient, HttpParams } from '@angular/common/http';
 import { inject } from '@angular/core';
-import { Observable } from 'rxjs';
+import { map, Observable } from 'rxjs';
 import { RestURL } from './rest_url';
 
 /**
@@ -22,10 +22,45 @@ export abstract class BaseRestService {
   /** GET an analytic endpoint (`{host}{api_prefix}analytic/<endpoint>`), returning
    * its rows. Optional flat string params become the query string. */
   protected analytic<T>(endpoint: string, params?: Record<string, string>): Observable<T[]> {
-    let p = new HttpParams();
-    for (const k in params) {
-      if (Object.prototype.hasOwnProperty.call(params, k)) p = p.set(k, params[k]);
+    return this.http.get<T[]>(this.analyticUrl(endpoint), { params: this.analyticParams(params) });
+  }
+
+  /** `analytic()` plus the `X-Data-Source-Status` / `X-Data-Source` response headers, so an
+   * empty result can be told apart from a missing source. `analytic()` stays array-valued. */
+  protected analyticWithStatus<T>(endpoint: string, params?: Record<string, string>): Observable<AnalyticResult<T>> {
+    return this.http.get<T[]>(this.analyticUrl(endpoint), {
+      params: this.analyticParams(params),
+      observe: 'response',
+    }).pipe(
+      map((response) => ({
+        rows: response.body ?? [],
+        source: {
+          status: response.headers.get('X-Data-Source-Status'),
+          id: response.headers.get('X-Data-Source'),
+        },
+      })),
+    );
+  }
+
+  private analyticUrl(endpoint: string): string {
+    return this.url(RestURL.api_prefix + 'analytic/' + endpoint);
+  }
+
+  private analyticParams(params?: Record<string, string>): HttpParams {
+    let result = new HttpParams();
+    for (const key in params) {
+      if (Object.prototype.hasOwnProperty.call(params, key)) result = result.set(key, params[key]);
     }
-    return this.http.get<T[]>(this.url(RestURL.api_prefix + 'analytic/' + endpoint), { params: p });
+    return result;
   }
 }
+
+export interface AnalyticResult<T> {
+  rows: T[];
+  source: AnalyticSourceStatus;
+}
+
+export interface AnalyticSourceStatus {
+  status: string | null;
+  id: string | null;
+}