@nauticana/sail 1.1.6 → 1.1.8

package/README.md

@@ -18,6 +18,7 @@ A shared Angular component library for building CRUD-based admin frontends. Prov
 | **Account** | `MyAccountComponent` (self-service hub), `ProfileEditorComponent` (name/locale immediate; email/phone verify-before-apply) |
 | **Auth** | `ConsentGateComponent`, `OtpInputComponent`, `SocialLoginComponent` |
 | **Billing** | `PlanSelectorComponent`, `PriceSelectorComponent`, `CheckoutButtonComponent`, `PaymentMethodsComponent`, `PortalButtonComponent`, `UsageMeterComponent`, `StatusChipComponent`, `TrialBannerComponent`, `SeatSelectorComponent`, `DunningBannerComponent` |
+| **Dashboard** | `DashboardShellComponent`, `DataCardComponent`, `LockedOverlayComponent`, `ActionCenterComponent`, `EntitySelectorComponent`, `VerificationFlowComponent` |
 | **Payout** | `PayoutProviderOnboardingComponent`, `PayoutBankInfoFormComponent` |
 | **Payments / SCA** | `UserPaymentMethodsComponent`, `ScaConfirmComponent`, `ScaConfirmer` (port), `SCA_CONFIRMER` (token) |
 | **Services** | `BaseAuthService` (OTP / social / push / deleteAccount / logoutEverywhere / profile: `getProfile`, `updateProfile`, `request`+`confirmEmailChange`, `request`+`confirmPhoneChange`), `BillingService`, `BackendService`, `PayoutService`, `UserPaymentMethodService`, `loadScript()`, `authInterceptor`, `apiResponseInterceptor` |
@@ -143,7 +144,9 @@ bootstrapApplication(App, {
 });
 ```
 
-> **Auth-loop breaker.** `authInterceptor` carries a built-in circuit breaker: after 5 `401`/`403`s on token-bearing keel API calls within 10s it opens for 30s and refuses those requests **locally** (never sent), so a stale/rejected session can't drive the app to hammer the API and the edge/CDN. A later success closes it; login (no bearer) is never blocked, so recovery works. No wiring needed beyond registering `authInterceptor`.
+> **Auth-loop breaker.** `authInterceptor` carries a built-in circuit breaker: after 5 `401`s on token-bearing keel API calls within 10s it opens for 30s and refuses those requests **locally** (never sent), so a stale/rejected session can't drive the app to hammer the API and the edge/CDN. Only `401` counts — a `403` is a legitimate permission denial, not a session failure. A later success **or accepting a new token** (login) closes it, so a freshly authenticated session is never blocked. No wiring needed beyond registering `authInterceptor`.
+
+> **Phone-number change (opt-in).** `ProfileEditorComponent` and `MyAccountComponent` gate phone change behind a `phoneChangeEnabled` input (default `false`, since it needs an SMS provider — keel returns 503 without `Notify`). Enable it once your backend has SMS wired: `<sail-my-account [phoneChangeEnabled]="true" />` or `<sail-profile-editor [phoneChangeEnabled]="true" />`.
 
 ### 5. Create the root component
 
@@ -505,7 +508,7 @@ readonly meters = toSignal(this.billing.listUsage(), { initialValue: [] });
 
 ### Redirect-action (v1.0.0)
 
-A `TableAction` with `kind: 'redirect'` makes `BaseTable.executeAction` POST and then follow the returned `{ url }` instead of refreshing — so checkout / portal / any provider-hosted handoff can be declared as a basis `table_action` row with **no bespoke component**. The backend action handler returns `{ "url": "https://…" }`.
+A `TableAction` with `kind: 'R'` (redirect — the `constant_value` code) makes `BaseTable.executeAction` POST and then follow the returned `{ url }` instead of refreshing — so checkout / portal / any provider-hosted handoff can be declared as a basis `table_action` row with **no bespoke component**. The backend action handler returns `{ "url": "https://…" }`.
 
 > **Response-shape contract.** The generic redirect-action path reads a bare `url` because it's polymorphic — one dispatch for checkout / portal / export / etc., where the action's identity lives in the metadata, not the payload. keel's `WrapTableAction` enforces no shape; your inner handler must return `{ url }`. The *typed* billing endpoints keep specific names instead (`createCheckout()` → `checkoutUrl`, `createPortalSession()` → `portalUrl`). So the same portal concept has two response shapes depending on the path: wire it as `<sail-portal-button>` (typed → `portalUrl`) **or** as a `table_action` redirect (generic → `url`), not both.
 
@@ -750,6 +753,25 @@ Under the hood, the component calls `BaseAuthService.loginSocial(provider, idTok
 
 For backward compatibility, the older OAuth-code flow `BaseAuthService.loginWithGoogle(code)` (hits `/public/login/google`) is still supported; prefer `loginSocial` for new code.
 
+## Dashboard components
+
+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`.
+- **`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`.
+- **`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.
+
+```html
+<sail-data-card heading="Trends" [state]="state()" description="Weekly visibility trend" (upgrade)="goUpgrade()">
+  <ng-template><canvas baseChart [data]="chartData()" [type]="'line'"></canvas></ng-template>
+</sail-data-card>
+```
+
+Models: `DataCardState`, `ActionItem`, `EntityOption`, `VerificationStep`.
+
 ## Adding a new domain table
 
 When your project owns a table that isn't part of basis (e.g. `favorite_location`, `support_ticket`, `vehicle`), follow the pattern below so the row plays nicely with keel's generic CRUD endpoints and the sail `<table-edit>` / `<table-list>` components.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "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/account/my_account.html

@@ -2,7 +2,7 @@
   <div class="auth-card">
     <h2 class="auth-title">My Account</h2>
 
-    <sail-profile-editor></sail-profile-editor>
+    <sail-profile-editor [phoneChangeEnabled]="phoneChangeEnabled()"></sail-profile-editor>
 
     <section class="account-section">
       <h3>Security</h3>

package/src/component/account/my_account.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { RouterLink } from '@angular/router';
 import { MatButtonModule } from '@angular/material/button';
 import { ProfileEditorComponent } from './profile_editor';
@@ -12,4 +12,8 @@ import { ProfileEditorComponent } from './profile_editor';
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [RouterLink, MatButtonModule, ProfileEditorComponent],
 })
-export class MyAccountComponent {}
+export class MyAccountComponent {
+  /** Opt-in: set true once the host's backend has an SMS provider, to expose
+   *  phone-number change in the embedded profile editor. */
+  readonly phoneChangeEnabled = input(false);
+}

package/src/component/account/profile_editor.html

@@ -45,6 +45,26 @@
 
 <section class="account-section">
   <h3>Phone</h3>
-  <p>{{ phone() || 'Not set' }}</p>
-  @if (!phoneChangeEnabled) { <p class="auth-instructions">Phone change is coming soon.</p> }
+  @if (!phoneChangeEnabled()) {
+    <p>{{ phone() || 'Not set' }}</p>
+  } @else if (phonePhase() === 'idle') {
+    <p>{{ phone() || 'Not set' }}</p>
+    <button matButton (click)="startPhoneChange()">Change phone</button>
+  } @else if (phonePhase() === 'enter') {
+    <mat-form-field appearance="outline">
+      <mat-label>New phone</mat-label>
+      <input matInput type="tel" [formControl]="newPhone" required>
+    </mat-form-field>
+    <button matButton="elevated" class="primary" (click)="sendPhoneCode()" [disabled]="newPhone.invalid || loading()">Send code</button>
+    <button matButton (click)="cancelPhoneChange()">Cancel</button>
+  } @else {
+    @if (phoneMsg()) { <p>{{ phoneMsg() }}</p> }
+    <mat-form-field appearance="outline">
+      <mat-label>Confirmation code</mat-label>
+      <input matInput [formControl]="phoneCode" inputmode="numeric" required>
+    </mat-form-field>
+    <button matButton="elevated" class="primary" (click)="confirmPhoneChange()" [disabled]="phoneCode.invalid || loading()">Confirm</button>
+    <button matButton (click)="cancelPhoneChange()">Cancel</button>
+  }
+  @if (phoneErr()) { <div class="auth-error" role="alert">{{ phoneErr() }}</div> }
 </section>

package/src/component/account/profile_editor.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectionStrategy, Component, OnInit, inject, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component, OnInit, inject, input, signal } from '@angular/core';
 import { FormBuilder, FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from '@angular/material/form-field';
@@ -6,9 +6,9 @@ import { MatInputModule } from '@angular/material/input';
 import { BaseAuthService } from '../../service/auth.service';
 import { UserProfile } from '../../model/auth';
 
-// Self-service profile editor: name/locale save immediately; email change is
-// verify-before-apply (code to the new address). Phone change is gated until
-// the backend has an SMS provider.
+// Self-service profile editor: name/locale save immediately; email and phone
+// change are verify-before-apply (code to the new value). Phone change is shown
+// only when the host enables phoneChangeEnabled (its backend has an SMS provider).
 @Component({
   selector: 'sail-profile-editor',
   templateUrl: './profile_editor.html',
@@ -19,8 +19,8 @@ export class ProfileEditorComponent implements OnInit {
   private readonly auth = inject(BaseAuthService);
   private readonly fb = inject(FormBuilder);
 
-  // Flip true once the backend wires an SMS provider for phone codes.
-  readonly phoneChangeEnabled = false;
+  // Set by the host once its backend wires an SMS provider for phone codes.
+  readonly phoneChangeEnabled = input(false);
 
   readonly loading = signal(false);
   readonly profileMsg = signal('');
@@ -40,6 +40,12 @@ export class ProfileEditorComponent implements OnInit {
   readonly newEmail = new FormControl('', [Validators.required, Validators.email]);
   readonly emailCode = new FormControl('', [Validators.required]);
 
+  readonly phonePhase = signal<'idle' | 'enter' | 'code'>('idle');
+  readonly phoneMsg = signal('');
+  readonly phoneErr = signal('');
+  readonly newPhone = new FormControl('', [Validators.required]);
+  readonly phoneCode = new FormControl('', [Validators.required]);
+
   ngOnInit(): void {
     this.auth.getProfile().subscribe({
       next: (p: UserProfile) => {
@@ -95,6 +101,38 @@ export class ProfileEditorComponent implements OnInit {
     });
   }
 
+  startPhoneChange(): void {
+    this.phonePhase.set('enter');
+    this.phoneMsg.set('');
+    this.phoneErr.set('');
+  }
+
+  cancelPhoneChange(): void {
+    this.phonePhase.set('idle');
+    this.newPhone.reset();
+    this.phoneCode.reset();
+  }
+
+  sendPhoneCode(): void {
+    if (this.newPhone.invalid) return;
+    this.loading.set(true);
+    this.phoneErr.set('');
+    this.auth.requestPhoneChange(this.newPhone.value!).subscribe({
+      next: () => { this.loading.set(false); this.phonePhase.set('code'); this.phoneMsg.set('We sent a code to your new number.'); },
+      error: (e) => { this.loading.set(false); this.phoneErr.set(this.msg(e, 'Could not send a code.')); },
+    });
+  }
+
+  confirmPhoneChange(): void {
+    if (this.phoneCode.invalid) return;
+    this.loading.set(true);
+    this.phoneErr.set('');
+    this.auth.confirmPhoneChange(this.newPhone.value!, Number(this.phoneCode.value)).subscribe({
+      next: () => { this.loading.set(false); this.phone.set(this.newPhone.value!); this.cancelPhoneChange(); this.profileMsg.set('Phone updated.'); },
+      error: (e) => { this.loading.set(false); this.phoneErr.set(this.msg(e, 'Invalid or expired code.')); },
+    });
+  }
+
   private msg(e: { error?: { detail?: string; message?: string } }, fallback: string): string {
     return e?.error?.detail || e?.error?.message || fallback;
   }

package/src/component/dashboard/action_center.html

@@ -0,0 +1,24 @@
+<section class="action-center">
+  @if (heading()) { <h2 class="action-center-title">{{ heading() }}</h2> }
+  @if (sorted().length === 0) {
+    <p class="action-center-empty">{{ emptyMessage() }}</p>
+  } @else {
+    <ul class="action-center-list">
+      @for (a of sorted(); track a.id) {
+        <li class="action-item" [class.action-done]="a.done" [attr.data-priority]="a.priority ?? 0">
+          <div class="action-body">
+            <span class="action-title">{{ a.title }}</span>
+            <span class="action-reason">{{ a.reason }}</span>
+          </div>
+          @if (a.done) {
+            <span class="action-complete">
+              <mat-icon aria-hidden="true">check_circle</mat-icon><span class="sr-only">Done</span>
+            </span>
+          } @else {
+            <button matButton="elevated" type="button" class="primary" (click)="act.emit(a)">{{ a.ctaLabel }}</button>
+          }
+        </li>
+      }
+    </ul>
+  }
+</section>

package/src/component/dashboard/action_center.ts

@@ -0,0 +1,27 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input, output } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+import { ActionItem } from '../../model/dashboard';
+
+/**
+ * Prioritized next-best-action list (guided completion, FR-008). Renders each
+ * action with its reason and a single CTA, sorted by descending priority;
+ * completed items show a done state instead of a button. Pure presentational —
+ * the host performs the action on `act`.
+ */
+@Component({
+  selector: 'sail-action-center',
+  templateUrl: './action_center.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatIconModule],
+})
+export class ActionCenterComponent {
+  readonly actions = input<ActionItem[]>([]);
+  readonly heading = input<string>('Recommended actions');
+  readonly emptyMessage = input<string>("You're all caught up.");
+  readonly act = output<ActionItem>();
+
+  readonly sorted = computed<ActionItem[]>(() =>
+    [...this.actions()].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0)));
+}

package/src/component/dashboard/dashboard_shell.html

@@ -0,0 +1,13 @@
+<section class="dashboard-shell">
+  @if (heading()) {
+    <header class="dashboard-header">
+      <h1 class="dashboard-title">{{ heading() }}</h1>
+      <div class="dashboard-actions">
+        <ng-content select="[dashboardActions]"></ng-content>
+      </div>
+    </header>
+  }
+  <div class="dashboard-grid">
+    <ng-content></ng-content>
+  </div>
+</section>

package/src/component/dashboard/dashboard_shell.ts

@@ -0,0 +1,17 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, input } from '@angular/core';
+
+/**
+ * Responsive card-grid dashboard shell. Pure layout: an optional heading row with
+ * a projected actions slot ([dashboardActions]), then a grid of projected cards.
+ * Ships no CSS — the app styles `.dashboard-shell` / `.dashboard-header` /
+ * `.dashboard-grid`.
+ */
+@Component({
+  selector: 'sail-dashboard-shell',
+  templateUrl: './dashboard_shell.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class DashboardShellComponent {
+  readonly heading = input<string>('');
+}

package/src/component/dashboard/data_card.html

@@ -0,0 +1,37 @@
+<section class="data-card" [attr.data-state]="state()" [attr.aria-busy]="state() === 'loading'">
+  @if (heading()) { <h2 class="data-card-title">{{ heading() }}</h2> }
+
+  @switch (state()) {
+    @case ('loading') {
+      <div class="data-card-loading"><mat-spinner diameter="28"></mat-spinner></div>
+    }
+    @case ('ready') {
+      <p class="sr-only">{{ description() }}</p>
+      @if (chart(); as tpl) { <ng-container [ngTemplateOutlet]="tpl"></ng-container> }
+      @if (tableRows().length) {
+        <table class="sr-only data-card-table">
+          <caption>{{ description() }}</caption>
+          @if (tableHeaders().length) {
+            <thead><tr>@for (h of tableHeaders(); track $index) { <th>{{ h }}</th> }</tr></thead>
+          }
+          <tbody>
+            @for (row of tableRows(); track $index) {
+              <tr>@for (cell of row; track $index) { <td>{{ cell }}</td> }</tr>
+            }
+          </tbody>
+        </table>
+      }
+    }
+    @case ('empty') { <p class="data-card-empty">{{ emptyMessage() }}</p> }
+    @case ('error') {
+      <p class="data-card-error" role="alert">{{ errorMessage() }}</p>
+      <button matButton type="button" (click)="retry.emit()">Retry</button>
+    }
+    @case ('locked') {
+      <div class="data-card-locked" role="group" [attr.aria-label]="(heading() || 'Insight') + ' — locked'">
+        <p class="locked-message">{{ lockedMessage() }}</p>
+        <button matButton="elevated" type="button" class="primary" (click)="upgrade.emit()">{{ ctaLabel() }}</button>
+      </div>
+    }
+  }
+</section>

package/src/component/dashboard/data_card.ts

@@ -0,0 +1,41 @@
+import { ChangeDetectionStrategy, Component, TemplateRef, ViewEncapsulation, contentChild, input, output } from '@angular/core';
+import { NgTemplateOutlet } from '@angular/common';
+import { MatButtonModule } from '@angular/material/button';
+import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
+import { DataCardState } from '../../model/dashboard';
+
+/**
+ * Card chrome for a single data visualization. The app supplies the chart itself
+ * as an <ng-template> (bring your own chart library — keel apps use ng2-charts);
+ * the card instantiates it ONLY in the 'ready' state, so during
+ * loading/empty/error/locked the chart never exists (no hidden canvas, no data
+ * leak when locked).
+ *
+ * Accessibility: `description` is a required text alternative announced in place
+ * of the visual chart; `tableHeaders`/`tableRows`, when supplied, render a
+ * visually-hidden data table (`.sr-only`, app-styled) as the non-visual equivalent.
+ */
+@Component({
+  selector: 'sail-data-card',
+  templateUrl: './data_card.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule, MatProgressSpinnerModule],
+})
+export class DataCardComponent {
+  readonly heading = input<string>('');
+  readonly state = input<DataCardState>('loading');
+  /** Required text alternative for screen readers — the non-visual equivalent. */
+  readonly description = input.required<string>();
+  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 ctaLabel = input<string>('Upgrade');
+  readonly tableHeaders = input<string[]>([]);
+  readonly tableRows = input<(string | number)[][]>([]);
+  readonly upgrade = output<void>();
+  readonly retry = output<void>();
+
+  /** The chart, provided as a single <ng-template>; instantiated only when ready. */
+  readonly chart = contentChild(TemplateRef);
+}

package/src/component/dashboard/entity_selector.html

@@ -0,0 +1,8 @@
+<mat-form-field appearance="outline" class="entity-selector">
+  <mat-label>{{ label() }}</mat-label>
+  <mat-select [value]="value()" (selectionChange)="onChange($event.value)">
+    @for (e of entities(); track e.id) {
+      <mat-option [value]="e.id" [disabled]="e.active === false">{{ e.label }}</mat-option>
+    }
+  </mat-select>
+</mat-form-field>

package/src/component/dashboard/entity_selector.ts

@@ -0,0 +1,50 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, effect, input, output, signal } from '@angular/core';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatSelectModule } from '@angular/material/select';
+import { EntityOption } from '../../model/dashboard';
+
+/**
+ * Scope selector for the active entity (e.g. business). Resolves the selection
+ * from `selected` when valid, else the first active option, and emits it — so the
+ * host's dependent data loads for a sensible default without extra wiring.
+ */
+@Component({
+  selector: 'sail-entity-selector',
+  templateUrl: './entity_selector.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatFormFieldModule, MatSelectModule],
+})
+export class EntitySelectorComponent {
+  readonly entities = input<EntityOption[]>([]);
+  readonly selected = input<string | undefined>(undefined);
+  readonly label = input<string>('Business');
+  readonly selectionChange = output<string | undefined>();
+
+  readonly value = signal<string | undefined>(undefined);
+
+  constructor() {
+    // Explicit selection wins; else keep the current pick if still valid; else the
+    // first active entity. "Valid" means present AND active, so a scope that goes
+    // inactive (or vanishes) is dropped. Emit on every change, including a clear
+    // (undefined) when no active option remains, so the host stops showing stale data.
+    effect(() => {
+      const opts = this.entities();
+      const isActive = (id?: string) => !!id && opts.some((e) => e.id === id && e.active !== false);
+      const cur = this.value();
+      const resolved =
+        isActive(this.selected()) ? this.selected()
+          : isActive(cur) ? cur
+            : opts.find((e) => e.active !== false)?.id;
+      if (resolved !== cur) {
+        this.value.set(resolved);
+        this.selectionChange.emit(resolved);
+      }
+    });
+  }
+
+  onChange(id: string): void {
+    this.value.set(id);
+    this.selectionChange.emit(id);
+  }
+}

package/src/component/dashboard/locked_overlay.html

@@ -0,0 +1,8 @@
+@if (locked()) {
+  <div class="locked-overlay" role="group" [attr.aria-label]="(feature() || 'Feature') + ' — locked'">
+    <p class="locked-message">{{ message() }}</p>
+    <button matButton="elevated" type="button" class="primary" (click)="upgrade.emit()">{{ ctaLabel() }}</button>
+  </div>
+} @else if (content(); as tpl) {
+  <ng-container [ngTemplateOutlet]="tpl"></ng-container>
+}

package/src/component/dashboard/locked_overlay.ts

@@ -0,0 +1,32 @@
+import { ChangeDetectionStrategy, Component, TemplateRef, ViewEncapsulation, contentChild, input, output } from '@angular/core';
+import { NgTemplateOutlet } from '@angular/common';
+import { MatButtonModule } from '@angular/material/button';
+
+/**
+ * Entitlement gate that renders an upgrade prompt over a feature. The protected
+ * content is supplied as an <ng-template> and is instantiated ONLY when unlocked —
+ * so when locked there is nothing behind it: no DOM nodes, no chart canvas, no
+ * data binding, no triggered network call. This is the strict free-tier rule
+ * (DASHBOARD.md): a locked card provably exposes no data.
+ *
+ *   <sail-locked-overlay [locked]="!entitled()" feature="Trends" (upgrade)="goUpgrade()">
+ *     <ng-template><canvas baseChart ...></canvas></ng-template>
+ *   </sail-locked-overlay>
+ */
+@Component({
+  selector: 'sail-locked-overlay',
+  templateUrl: './locked_overlay.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule],
+})
+export class LockedOverlayComponent {
+  readonly locked = input.required<boolean>();
+  readonly feature = input<string>('');
+  readonly message = input<string>('Upgrade to unlock this feature.');
+  readonly ctaLabel = input<string>('Upgrade');
+  readonly upgrade = output<void>();
+
+  /** The protected content, provided as a single <ng-template> by the consumer. */
+  readonly content = contentChild(TemplateRef);
+}

package/src/component/dashboard/verification_flow.html

@@ -0,0 +1,32 @@
+<div class="verification-flow" [attr.data-step]="step()">
+  @switch (step()) {
+    @case ('verified') {
+      <p class="verification-success" role="status">Verified.</p>
+    }
+    @case ('idle') {
+      <p class="verification-intro">
+        Verify ownership@if (target()) { of {{ target() }} } to unlock trusted features.
+      </p>
+      <button matButton="elevated" type="button" class="primary" (click)="requestVerification.emit()">
+        Start verification
+      </button>
+    }
+    @default {
+      <p class="verification-intro">Enter the code we sent@if (target()) { to {{ target() }} }.</p>
+      <mat-form-field appearance="outline">
+        <mat-label>Verification code</mat-label>
+        <input matInput #codeInput name="code" autocomplete="one-time-code"
+               [value]="code()" (input)="code.set(codeInput.value)"
+               [disabled]="step() === 'verifying'">
+      </mat-form-field>
+      @if (errorMessage()) { <p class="verification-error" role="alert">{{ errorMessage() }}</p> }
+      <div class="verification-actions">
+        <button matButton="elevated" type="button" class="primary"
+                [disabled]="step() === 'verifying' || !code().trim()" (click)="submit()">
+          @if (step() === 'verifying') { Verifying… } @else { Confirm }
+        </button>
+        <button matButton type="button" (click)="requestVerification.emit()">Resend code</button>
+      </div>
+    }
+  }
+</div>

package/src/component/dashboard/verification_flow.ts

@@ -0,0 +1,36 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, input, output, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { VerificationStep } from '../../model/dashboard';
+
+/**
+ * Self-service verification flow — a sibling to the 2FA verify component, but
+ * backend-agnostic: it owns the request → enter-code → confirmed UI and emits
+ * `requestVerification` / `confirmCode`, while the host wires the actual endpoints
+ * and feeds `step` + `errorMessage` back (daxoom wires business verify/confirm).
+ */
+@Component({
+  selector: 'sail-verification-flow',
+  templateUrl: './verification_flow.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatFormFieldModule, MatInputModule],
+})
+export class VerificationFlowComponent {
+  readonly step = input<VerificationStep>('idle');
+  readonly errorMessage = input<string>('');
+  /** The email/phone/identifier being verified, shown in the copy. */
+  readonly target = input<string>('');
+  readonly requestVerification = output<void>();
+  readonly confirmCode = output<string>();
+
+  readonly code = signal('');
+
+  submit(): void {
+    const c = this.code().trim();
+    if (c) {
+      this.confirmCode.emit(c);
+    }
+  }
+}

package/src/component/login/login_component.html

@@ -9,6 +9,9 @@
     @if (loggedOut) {
       <p class="auth-message" role="status" aria-live="polite">You have been logged out successfully.</p>
     }
+    @if (sessionHandoffError()) {
+      <p class="auth-error" role="alert">{{ sessionHandoffError() }}</p>
+    }
     <form [formGroup]="loginForm" (ngSubmit)="login()" class="auth-form">
       <mat-form-field appearance="outline">
         <mat-label>Username</mat-label>

package/src/component/login/login_component.ts

@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component, computed, inject, ViewEncapsulation } from '@angular/core';
 import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
 import { BaseAuthService } from '../../service/auth.service';
-import { ActivatedRoute, Router, RouterLink } from '@angular/router';
+import { ActivatedRoute, RouterLink } from '@angular/router';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from "@angular/material/form-field";
 import { MatInputModule } from '@angular/material/input';
@@ -25,10 +25,11 @@ import { SocialLoginComponent } from './social_login';
 })
 export class LoginComponent {
   private auth = inject(BaseAuthService);
-  private router = inject(Router);
   protected fb = inject(FormBuilder);
   protected readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
   protected readonly loggedOut = inject(ActivatedRoute).snapshot.queryParamMap.get('loggedOut') === 'true';
+  /** OAuth session-cookie handoff failure from BaseAuthService, shown below. */
+  protected readonly sessionHandoffError = this.auth.sessionHandoffError;
 
   /**
    * Auto-show the embedded SocialLoginComponent whenever at least one
@@ -58,14 +59,12 @@ export class LoginComponent {
   }
 
   /**
-   * SocialLoginComponent emits the response after BaseAuthService.loginSocial
-   * persists the JWT internally. Mirror the same post-login navigation that
-   * password-login uses (root route by default; consumers override via
-   * BaseAuthService.navigateToRoleHome when role-aware routing lands).
+   * loginSocial already ran completeLogin, which owns post-login navigation
+   * (route init, or the OAuth cookie handoff). Handlers must NOT navigate here —
+   * doing so abandons a pending handoff before its cookie is set. Downstream
+   * social-login handlers should follow the same rule.
    */
-  protected onSocialSuccess(_: LoginResponseSocial): void {
-    this.router.navigateByUrl('/');
-  }
+  protected onSocialSuccess(_: LoginResponseSocial): void {}
 
   protected onSocialError(err: Error): void {
     console.error('social login failed:', err);

package/src/index.ts

@@ -2,8 +2,15 @@ export * from './config';
 export * from './model/appdata';
 export * from './model/auth';
 export * from './model/common';
+export * from './model/dashboard';
 export * from './model/decorator';
 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/action_center';
+export * from './component/dashboard/entity_selector';
+export * from './component/dashboard/verification_flow';
 export * from './component/abstract/base_form';
 export * from './component/abstract/base_view';
 export * from './component/abstract/base_async';

package/src/model/appdata.ts

@@ -83,7 +83,7 @@ export interface TableAction {
   confirmMessage?:  string;
   authorityObject:  string;   // uppercased table_name — for canExecute()
   authorityCheck:   string;   // uppercased action_name — for canExecute()
-  kind?:            'P' | 'R' | 'V'; // P post (default) / R redirect (follow {url}) / V reveal (show returned secret once)
+  kind?:            'P' | 'R' | 'V'; // constant_value codes: P post (default) / R redirect (follow {url}) / V reveal (show returned secret once)
 }
 
 export interface ForeignKey {

package/src/model/dashboard.ts

@@ -0,0 +1,24 @@
+/** Lifecycle state of a data/chart card (sail-data-card). */
+export type DataCardState = 'loading' | 'ready' | 'empty' | 'error' | 'locked';
+
+/** A prioritized, completable next-best-action (sail-action-center, FR-008). */
+export interface ActionItem {
+  id: string;
+  title: string;
+  reason: string;
+  ctaLabel: string;
+  /** Higher sorts first; defaults to 0. */
+  priority?: number;
+  done?: boolean;
+}
+
+/** One selectable scope entity (e.g. a business) for sail-entity-selector. */
+export interface EntityOption {
+  id: string;
+  label: string;
+  /** Defaults to true; the selector defaults to the first active entity. */
+  active?: boolean;
+}
+
+/** Step of the self-service verification flow (sail-verification-flow). */
+export type VerificationStep = 'idle' | 'requested' | 'verifying' | 'verified' | 'error';

package/src/service/auth.interceptor.ts

@@ -2,12 +2,11 @@ import { HttpErrorResponse, HttpEventType, HttpInterceptorFn } from '@angular/co
 import { catchError, tap, throwError } from 'rxjs';
 import { isKeelApiUrl } from './rest_url';
 
-// Auth-loop breaker: repeated 401/403s on token-bearing API calls (a stale or
-// rejected session) can drive the app to hammer the API — and the edge/CDN in
-// front of it — indefinitely. After AUTH_FAIL_THRESHOLD failures within
-// AUTH_FAIL_WINDOW_MS the circuit opens for AUTH_CIRCUIT_COOLDOWN_MS: authed API
-// requests are refused locally (never sent) so the storm stops at the browser. A
-// later success closes it; login (no bearer) is never blocked, so recovery works.
+// Auth-loop breaker: repeated 401s on token-bearing API calls (a stale session) can
+// drive the app to hammer the API/CDN. After AUTH_FAIL_THRESHOLD within
+// AUTH_FAIL_WINDOW_MS the circuit opens for AUTH_CIRCUIT_COOLDOWN_MS — authed
+// requests are refused locally. Only 401 counts (403 is a permission denial); a
+// success or accepting a new token closes it.
 const AUTH_FAIL_WINDOW_MS = 10_000;
 const AUTH_FAIL_THRESHOLD = 5;
 const AUTH_CIRCUIT_COOLDOWN_MS = 30_000;
@@ -36,7 +35,7 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => {
       }
     }),
     catchError((err: HttpErrorResponse) => {
-      if (authedApi && (err.status === 401 || err.status === 403)) {
+      if (authedApi && err.status === 401) {
         recordAuthFailure();
       }
       return throwError(() => err);
@@ -70,3 +69,9 @@ function clearAuthFailures(): void {
   sessionStorage.removeItem(FAIL_KEY);
   sessionStorage.removeItem(OPEN_KEY);
 }
+
+/** Close the circuit on accepting a new token, so a freshly logged-in session
+ *  isn't blocked by failures from a prior stale session. */
+export function resetAuthCircuit(): void {
+  clearAuthFailures();
+}

package/src/service/auth.service.ts

@@ -16,6 +16,7 @@ import { ApplicationMenu, ConstantValue } from '../model/common';
 import { CanActivateFn, CanDeactivateFn, Router, Routes } from '@angular/router';
 import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from '../config';
 import { BaseRestService } from './base_rest.service';
+import { resetAuthCircuit } from './auth.interceptor';
 
 /** Sort dropdown options by their visible label so long lookup lists are scannable. */
 const byCaption = (a: ConstantValue, b: ConstantValue) =>
@@ -61,6 +62,10 @@ export abstract class BaseAuthService extends BaseRestService {
   token: string | null = null;
   readonly isLoggedIn = signal(false);
 
+  /** Set when the OAuth session-cookie handoff fails; the UI shows it and lets the
+   *  user retry instead of being redirected into a cookieless login loop. */
+  readonly sessionHandoffError = signal<string | null>(null);
+
   /**
    * Multi-role app support. Consumers that distinguish rider/driver/admin
    * (or any equivalent split) call setRole() after login, then
@@ -117,15 +122,22 @@ export abstract class BaseAuthService extends BaseRestService {
     this.token = token;
     this.isLoggedIn.set(true);
     localStorage.setItem('jwt', token);
+    resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
     const ret = this.validatedReturnUrl();
     if (ret && this.guiConfig.sessionCookieUrl) {
       // OAuth flow: mirror the bearer into a cookie, then hand off to the
-      // (cross-origin) authorization server via a full navigation.
+      // (cross-origin) authorization server via a full navigation. Only hand off
+      // once the cookie is actually set — redirecting after a failed cookie request
+      // sends the user on without a session and loops them back to login.
+      this.sessionHandoffError.set(null);
       this.http.post(this.url(this.guiConfig.sessionCookieUrl), {}, { withCredentials: true })
           .pipe(take(1))
           .subscribe({
             next: () => window.location.assign(ret),
-            error: () => window.location.assign(ret),
+            error: (err) => {
+              console.error('Session cookie handoff failed:', err);
+              this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
+            },
           });
       return;
     }