@nauticana/sail 1.1.6 → 1.1.7

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` |
@@ -750,6 +751,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.7",
   "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/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,48 @@
+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>();
+
+  readonly value = signal<string | undefined>(undefined);
+
+  constructor() {
+    // Explicit selection wins; else keep the current pick if still valid; else the
+    // first active entity. Emit whenever the resolved value actually changes.
+    effect(() => {
+      const opts = this.entities();
+      const want = this.selected();
+      const cur = this.value();
+      const resolved =
+        want && opts.some((e) => e.id === want) ? want
+          : cur && opts.some((e) => e.id === cur) ? cur
+            : opts.find((e) => e.active !== false)?.id;
+      if (resolved && 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/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/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';