@nauticana/sail 0.7.0 → 0.8.1

package/README.md

@@ -2,7 +2,7 @@
 
 A shared Angular component library for building CRUD-based admin frontends. Provides table management, form handling, navigation, authentication, two-factor authentication, and trusted device management — all driven by metadata from a [keel](https://github.com/nauticana/keel) Go backend.
 
-> **Compatibility:** sail **v0.5.x** targets keel **v0.5.x**. The two libraries are versioned in lock-step.
+> **Compatibility:** sail and keel are versioned in lock-step. Use **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
 
 ## What it provides
 
@@ -143,7 +143,7 @@ import { Navigation } from '@nauticana/sail';
   selector: 'app-root',
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [Navigation],
-  template: `<app-navigation><span toolbar-title>My App</span></app-navigation>`,
+  template: `<sail-navigation><span toolbar-title>My App</span></sail-navigation>`,
 })
 export class App {}
 ```
@@ -328,23 +328,23 @@ export class PricingPage {
 
 **Plan picker** — pure presentational, no API calls:
 ```html
-<app-plan-selector
+<sail-plan-selector
     [plans]="plans()"
     [selected]="selectedPlan()"
     [features]="{ PRO: ['Unlimited users', '24/7 support'] }"
     (selectionChange)="selectedPlan.set($event)">
-</app-plan-selector>
+</sail-plan-selector>
 ```
 
 **Checkout button** — calls `createCheckout()` and redirects to the provider-hosted URL. `PublicPlan.priceId` lets you wire the picker directly to checkout without a local mapping table:
 ```html
-<app-checkout-button
+<sail-checkout-button
     [priceId]="selectedPlan().priceId!"
     [mode]="'subscription'"
     [successUrl]="'https://app.example.com/billing/done'"
     [cancelUrl]="'https://app.example.com/billing'"
     [email]="userEmail">
-</app-checkout-button>
+</sail-checkout-button>
 ```
 
 For one-off charges use `[mode]="'payment'"`. For "save a card without charging" (Stripe SetupIntent), use `[mode]="'setup'"` and **omit** `[priceId]` — keel rejects a non-empty `priceId` in setup mode with 400.
@@ -364,7 +364,7 @@ metadata: {
 
 **Payment methods** — lists saved methods with loading and empty states:
 ```html
-<app-payment-methods></app-payment-methods>
+<sail-payment-methods></sail-payment-methods>
 ```
 
 ### Registration → checkout flow
@@ -430,12 +430,12 @@ import { ConsentGateComponent, ConsentOption, ConsentState, ConsentType } from '
 @Component({
   imports: [ConsentGateComponent],
   template: `
-    <app-consent-gate
+    <sail-consent-gate
         [policyVersion]="'v1'"
         [policyLanguage]="'en'"
         [optionalConsents]="extras"
         (consentStateChange)="onConsent($event)">
-    </app-consent-gate>
+    </sail-consent-gate>
   `,
 })
 export class SignupPage {
@@ -468,12 +468,12 @@ import { BaseAuthService, OtpInputComponent } from '@nauticana/sail';
 @Component({
   imports: [OtpInputComponent],
   template: `
-    <app-otp-input
+    <sail-otp-input
         [contact]="contact()"
         [length]="6"
         (codeComplete)="onVerify($event)"
         (resend)="onResend()">
-    </app-otp-input>
+    </sail-otp-input>
     @if (error()) { <div class="auth-error">{{ error() }}</div> }
   `,
 })
@@ -510,12 +510,12 @@ Override `verifyOtp()` in your own `AuthService extends BaseAuthService` when yo
 `SocialLoginComponent` renders Google / Apple buttons using each provider's official SDK. It loads the SDKs dynamically via `loadScript()` — nothing is bundled into your app.
 
 ```html
-<app-social-login
+<sail-social-login
     [providers]="['google', 'apple']"
     [consent]="consentState"
     (loginSuccess)="onSuccess($event)"
     (loginError)="onError($event)">
-</app-social-login>
+</sail-social-login>
 ```
 
 Config required in `SAIL_GUI_CONFIG`:
@@ -557,7 +557,7 @@ auth.deleteAccount(reauth, 'Closing my account.').subscribe();
 ### Account deletion
 
 ```html
-<app-account-deletion [confirmationText]="'DELETE'"></app-account-deletion>
+<sail-account-deletion [confirmationText]="'DELETE'"></sail-account-deletion>
 ```
 
 Typed-confirmation UX: the destructive button is disabled until the user types the exact `confirmationText` (default `DELETE`) **and** confirms their password. Optional reason textarea is forwarded to the backend. On success, local session is cleared and the router navigates to `config.accountDeletedRoute` (default `/login/local`).
@@ -567,7 +567,7 @@ Typed-confirmation UX: the destructive button is disabled until the user types t
 `TrustedDevicesComponent` ships a "Sign out of all devices" button that reveals a password field, then calls `BaseAuthService.logoutEverywhere({ password })` (`POST /api/user/logout-everywhere`). It also displays a single-device-mode banner when configured:
 
 ```html
-<app-trusted-devices [singleDeviceSession]="user.singleDeviceSession"></app-trusted-devices>
+<sail-trusted-devices [singleDeviceSession]="user.singleDeviceSession"></sail-trusted-devices>
 ```
 
 Pass `singleDeviceSession` from your login response (the field is part of `LoginResponse2FA`). When true, the banner reads: *"This account is in single-device mode — signing in on another device will sign you out here."*
@@ -739,3 +739,407 @@ Type errors after upgrade fall into two buckets:
 ### 8. Backend alignment
 
 This library only talks to keel **v0.5.x**. Older keel servers will reject the `otpToken` field on verify with HTTP 400. Upgrade keel and sail together. See [keel/README.md → Migration Guide](https://github.com/nauticana/keel/blob/main/README.md) for the matching backend changes.
+
+## Migrating to v0.7.0 — payout, user payment methods, table actions
+
+The v0.6 / v0.7 line introduced three additive feature groups against keel v0.7.x. All net-new exports; no breaking changes from v0.5.x. Pull what you need.
+
+| Version | Surface |
+|---|---|
+| **v0.6.0** | Payout onboarding (KYC) + multi-partner account reuse |
+| **v0.6.1** | End-user saved payment methods (cards / wallets) |
+| **v0.7.0** | `TableAction` — backend-defined custom buttons on table screens |
+
+### 1. New exports
+
+| From | Export | Purpose |
+|---|---|---|
+| `@nauticana/sail` | `PayoutService` | keel/payout API client — hosted-KYC launch, reuse flow, status |
+| `@nauticana/sail` | `PayoutProviderOnboardingComponent` (`<sail-payout-provider-onboarding>`) | Drop-in onboarding step with reuse picker + hosted-KYC launcher |
+| `@nauticana/sail` | `PayoutBankInfoFormComponent` (`<sail-payout-bank-info-form>`) | Tax + payout details form (country / currency / tax ID / billing address / agreement) |
+| `@nauticana/sail` | `UserPaymentMethodService` | Saved-card list / delete / set-default API client |
+| `@nauticana/sail` | `UserPaymentMethodsComponent` (`<sail-user-payment-methods>`) | List of saved cards/wallets with set-default + delete |
+| `@nauticana/sail` | `TableAction`, `ReusableAccount`, `PayoutOnboardingSession`, `BankInfoFormValue`, `CountryProfile`, `UserPaymentMethod`, `DEFAULT_COUNTRY_PROFILES` | Model types / defaults |
+
+### 2. New keel endpoints
+
+Make sure your keel deployment exposes these — they're all under `/api/v1/`:
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/api/v1/payout/onboard/start` | POST | Open hosted-KYC; returns `{ url, externalAccountId, expiresAt }` |
+| `/api/v1/payout/reusable` | POST | List provider accounts the user has on other partners |
+| `/api/v1/payout/reusable/link` | POST | Copy a `providerAccountId` onto the active partner's `user_bank_info` row |
+| `/api/v1/payout/status` | POST | `{ complete: true }` once the active partner's row has a `providerAccountId` |
+| `/api/v1/payment-methods/set-default` | POST | Atomic multi-row UPDATE — sets one row as default, clears the rest |
+| `/api/v1/{table}/{action_name}` | POST | Per-table custom actions resolved from `basis.table_action` |
+
+`list` / `delete` for the `user_payment_method` table go through keel's generic REST CRUD (`/api/v1/user_payment_method/list|delete`) — `user_payment_method` is a UserSpecific basis table, so keel auto-scopes reads to the caller and owner-locks DELETE. No custom endpoint needed for those two.
+
+### 3. Payout onboarding wiring
+
+Drop the two components into a wizard step. Routing between them stays in the consumer app — sail emits events, doesn't navigate.
+
+```html
+@switch (step()) {
+  @case ('bank') {
+    <sail-payout-bank-info-form
+        (submitted)="onBankInfo($event)"
+        (back)="step.set('plan')">
+    </sail-payout-bank-info-form>
+  }
+  @case ('provider') {
+    <sail-payout-provider-onboarding
+        (linked)="step.set('done')"
+        (started)="step.set('waiting')"
+        (skipped)="step.set('done')"
+        (back)="step.set('bank')">
+    </sail-payout-provider-onboarding>
+  }
+}
+```
+
+`BankInfoFormValue` maps 1:1 to `basis.user_bank_info` columns. The consumer decides where to POST it — typically a direct generic-CRUD insert against `/api/v1/user_bank_info`. The provider account itself is created by `<sail-payout-provider-onboarding>` via `PayoutService.startOnboarding()` → hosted KYC → webhook back to keel.
+
+For apps that operate on a single keel partner, the reuse picker stays empty and only the "Start onboarding" CTA renders. Multi-partner apps get the picker for free.
+
+### 4. Saved payment methods wiring
+
+```html
+<sail-user-payment-methods
+    [title]="'Payment Methods'"
+    (addClicked)="goToSetupIntent()"
+    (defaultChanged)="onDefaultChanged($event)"
+    (deleted)="onDeleted($event)">
+</sail-user-payment-methods>
+```
+
+`(addClicked)` is the only event you must wire — sail intentionally does **not** ship a SetupIntent UI (providers differ too much; consumer flows them through Stripe Elements / Apple Pay / Google Pay / etc.). Listen for the event and route to your own SetupIntent screen.
+
+### 5. TableAction — backend-defined per-table actions
+
+v0.7.0 surfaces a new `TableAction` channel: keel's REST engine ships per-table action buttons from `basis.table_action`. The shipped `TableList`, `TableSearch`, `TableEdit`, and `TableDetail` templates render these automatically (toolbar for table-level actions, per-row icon buttons for record-specific ones). Authorization gating mirrors `canRead`/`canCreate` etc. — `canExecuteAction(action)` is checked against `(authorityObject, authorityCheck, table_name)`.
+
+For your own components that subclass `BaseView` / `BaseForm`, expose the same buttons in your templates:
+
+```html
+@for (action of getActions(false); track action.action) {
+  @if (canExecuteAction(action)) {
+    <button matButton="outlined" type="button"
+            [title]="action.caption"
+            (click)="executeAction(action)">
+      @if (action.icon) { <mat-icon>{{ action.icon }}</mat-icon> }
+      {{ action.caption }}
+    </button>
+  }
+}
+
+@for (action of getActions(true); track action.action) {
+  @if (canExecuteAction(action)) {
+    <button matIconButton type="button"
+            [title]="action.caption"
+            (click)="executeAction(action, record)">
+      <mat-icon>{{ action.icon || 'play_arrow' }}</mat-icon>
+    </button>
+  }
+}
+```
+
+`executeAction()` is provided by sail's table components (it POSTs the row's primary-key columns to `action.method`). If you wrote your own subclass and want the same behaviour, inject `BackendService` and call `backendService.executeAction(action.method, body)`. The `body` is `{}` for table-level actions and the row PK (via `primaryKeyValues(record)`) for record-specific ones.
+
+### 6. Backend alignment
+
+v0.6 / v0.7 require keel **v0.7.x**. The earlier `keel v0.5.x` server doesn't expose `/api/v1/payout/*`, `/api/v1/payment-methods/set-default`, or the `basis.table_action` seed data. Upgrade keel and sail together.
+
+## Migrating to v0.8.0 — signal-driven modernization
+
+v0.8.0 finishes the Angular-signals migration that v0.5–v0.7 started incrementally. Every `@Input()` / `@Output()` decorator, `EventEmitter`, plain-field-on-`BaseTable` access, and legacy Material M2 button selector is gone. Downstream code that extends sail's abstract classes or copies its template patterns will need the steps below — there is no shim.
+
+The TS-side core peer requirements bump with this release:
+
+| | v0.7.x | v0.8.x |
+|---|---|---|
+| Angular | `^21.0.0` | `^21.2.0` |
+| TypeScript | `~5.9.2` | `~6.0.3` |
+
+### 1. `BaseTable.tableName` is now a `WritableSignal<string>`
+
+The single highest-impact change. Before:
+
+```typescript
+// BaseTable
+tableName = '';
+
+// Subclass
+@Input() override tableName = '';
+
+// In your code
+if (this.tableName === 'orders') { ... }
+this.tableName = 'orders';
+
+// In your template
+[tableName]="tableName"
+{{ tableName }}
+```
+
+After:
+
+```typescript
+// BaseTable
+readonly tableName: WritableSignal<string> = signal('');
+
+// In your code
+if (this.tableName() === 'orders') { ... }
+this.tableName.set('orders');
+
+// In your template
+[tableName]="tableName()"
+{{ tableName() }}
+```
+
+If your subclass exposes `tableName` as a route/parent input, declare an aliased `input()` and sync it into the inherited signal in the constructor:
+
+```typescript
+import { effect, input } from '@angular/core';
+
+export class YourTableComponent extends BaseForm {
+  readonly tableNameInput = input('', { alias: 'tableName' });
+
+  constructor() {
+    super();
+    effect(() => {
+      const v = this.tableNameInput();
+      if (v) this.tableName.set(v);
+    });
+  }
+
+  ngOnInit() {
+    // Route-data fallback now uses .set(), not assignment:
+    if (!this.tableName() && data['tableName']) this.tableName.set(data['tableName']);
+  }
+}
+```
+
+### 2. `BaseView.apiName` and `BaseView.dialogComponent` are signals too
+
+Same migration path as `tableName`. The TableList/TableLookup pattern in v0.5–v0.7 read these as plain strings and assigned in `ngOnInit`; they are now `WritableSignal<string>` / `WritableSignal<any>`. Update subclass code:
+
+```diff
+- if (!this.apiName && data['apiName']) this.apiName = data['apiName'];
+- this.backendService.list<MyRow>(this.apiName, terms).subscribe(...);
++ if (!this.apiName() && data['apiName']) this.apiName.set(data['apiName']);
++ this.backendService.list<MyRow>(this.apiName(), terms).subscribe(...);
+```
+
+If you bind `[apiName]` / `[dialogComponent]` on a sail subclass from a parent template, declare aliased inputs and sync via `effect()`, exactly like `tableNameInput` above.
+
+### 3. `@Input()` / `@Output()` → `input()` / `output()`
+
+Every decorator-based input/output across sail is now signal-based. Update your own components to match. The signal-input requires calling the field as a function inside the class and in templates.
+
+```diff
+- @Input() title = 'Payments';
+- @Output() saved = new EventEmitter<Payment>();
++ readonly title = input('Payments');
++ readonly saved = output<Payment>();
+
+  // class body
+- this.title           // string
+- this.saved.emit(p);
++ this.title()         // string (signal read)
++ this.saved.emit(p);  // unchanged
+
+  // template
+- {{ title }}
++ {{ title() }}
+```
+
+`EventEmitter` is no longer imported from `@angular/core` in sail; outputs created with `output<T>()` are returned as `OutputEmitterRef<T>` with the same `.emit(v)` API.
+
+For inputs whose **parent value can change at runtime** and you also want a local writable copy (the old "default value, then override in `ngOnInit`" pattern), use the alias + effect template above. If you only need the parent value reactively, just call `this.foo()` everywhere.
+
+### 4. Inline component templates moved to sibling `.html`
+
+`UserPaymentMethodsComponent`, `PayoutBankInfoFormComponent`, and `PayoutProviderOnboardingComponent` no longer ship inline `template:` strings — they reference `templateUrl: './*.html'` in the same folder. The compiled output is identical; downstream consumers that just import the component classes need no change. If you have a fork that edits these templates inline, port your edits into the new `.html` files.
+
+### 5. Clean install + recompile
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+ng build
+```
+
+Type errors after the upgrade fall into four buckets:
+
+- **`This expression is not callable. Type 'String' has no call signatures.`** — a template still reads `tableName` / `apiName` as a plain field. Add `()`. See step 1.
+- **`Cannot assign to 'tableName' because it is a read-only property.`** — a subclass declared `readonly tableName = input('')`, conflicting with the inherited writable signal. Use the `tableNameInput = input('', { alias: 'tableName' })` + `effect()` pattern from step 1 instead.
+- **`Property 'X' does not exist on type 'EventEmitter<T>'.`** — you still import `EventEmitter`. Replace the field with `output<T>()` per step 3.
+- **`'@Input' is deprecated`** / Angular language-service squiggles on decorators — step 3.
+
+## Migrating to v0.8.1 — selector standardisation, OOP cleanup, keel v0.8.3 alignment
+
+v0.8.1 is a polish pass on top of v0.8.0's signal migration. The biggest change is **the component selector prefix**: every sail component is now `sail-*`, where v0.8.0 still shipped a mix of `app-*` (older components) and `sail-*` (the v0.6 / v0.7 additions). The rest of the release is internal OOP cleanup that's mostly invisible to downstream code, plus a TypeScript downgrade and a keel pin.
+
+| | v0.8.0 | v0.8.1 |
+|---|---|---|
+| keel | `v0.8.0` | `v0.8.3` |
+| TypeScript | `~6.0.3` | `~5.9.3` |
+| Component selector prefix | `app-*` (older) + `sail-*` (newer) | `sail-*` (uniform) |
+
+### 1. Selector rename — `app-*` → `sail-*` (and `table-*` / `dynamic-field` / `record-form` → `sail-*`)
+
+Every sail component selector now starts with `sail-`. **This is the breaking change**: any downstream template that embeds a sail component needs the prefix updated. Search-and-replace across your templates:
+
+| Old | New |
+|---|---|
+| `<app-navigation>` | `<sail-navigation>` |
+| `<app-login>` | `<sail-login>` |
+| `<app-register>` | `<sail-register>` |
+| `<app-chpass>` | `<sail-chpass>` |
+| `<app-confirm-register>` | `<sail-confirm-register>` |
+| `<app-confirm-chpass>` | `<sail-confirm-chpass>` |
+| `<app-twofactor-setup>` | `<sail-twofactor-setup>` |
+| `<app-twofactor-verify>` | `<sail-twofactor-verify>` |
+| `<app-trusted-devices>` | `<sail-trusted-devices>` |
+| `<app-account-deletion>` | `<sail-account-deletion>` |
+| `<app-consent-gate>` | `<sail-consent-gate>` |
+| `<app-otp-input>` | `<sail-otp-input>` |
+| `<app-social-login>` | `<sail-social-login>` |
+| `<app-plan-selector>` | `<sail-plan-selector>` |
+| `<app-checkout-button>` | `<sail-checkout-button>` |
+| `<app-payment-methods>` | `<sail-payment-methods>` |
+| `<table-list>` | `<sail-table-list>` |
+| `<table-search>` | `<sail-table-search>` |
+| `<table-edit>` | `<sail-table-edit>` |
+| `<table-detail>` | `<sail-table-detail>` |
+| `<table-lookup>` | `<sail-table-lookup>` |
+| `<table-report>` | `<sail-table-report>` |
+| `<table-form>` | `<sail-table-form>` |
+| `<record-form>` | `<sail-record-form>` |
+| `<dynamic-field>` | `<sail-dynamic-field>` |
+
+The payout / user-payment-method selectors (`<sail-payout-bank-info-form>`, `<sail-payout-provider-onboarding>`, `<sail-user-payment-methods>`) were already on `sail-*` in v0.7.0 — no change there.
+
+**Why:** the Angular style guide assigns `app-*` to the consumer application (Angular CLI defaults to it for new components). A library shipping `app-*` selectors collides with the downstream's own components and reads ambiguously in mixed templates. v0.8.1 makes the prefix uniform across sail and unambiguous against your code.
+
+### 2. Internal: TableAction template-method pull-up
+
+`executeAction()` was duplicated three times across `TableList`, `TableSearch`, and `TableDetail` in v0.8.0. v0.8.1 moves the body into `BaseTable` with two `protected` hooks:
+
+```typescript
+protected beforeExecuteAction(action: TableAction, record?: Record<string, unknown>): boolean { return true; }
+protected onActionSuccess(action: TableAction, record?: Record<string, unknown>): void { /* no-op */ }
+```
+
+**For your subclasses:** if you have a custom view that extends `BaseTable` / `BaseForm` / `BaseView` and renders the action toolbar, you no longer write your own `executeAction()` — inherit it. Override `onActionSuccess()` to refresh your screen (the way `TableList` re-fetches) and `beforeExecuteAction()` to add per-screen pre-flight guards (the way `TableDetail` blocks unsaved rows).
+
+**For your templates:** unchanged. Action buttons still call `(click)="executeAction(action, record)"`.
+
+**Bonus:** `TableEdit` now renders per-record actions too (v0.8.0 was missing them) and re-fetches the record after a successful action.
+
+### 3. Internal: `BaseAsync` pulled up onto 5 more components
+
+`ChpassComponent`, `ConfirmChpassComponent`, `ConfirmRegisterComponent`, `TwoFactorSetupComponent`, and `TwoFactorVerifyComponent` were re-declaring their own `errorMessage` / `successMessage` signals and hand-rolled subscribe blocks. They now `extends BaseAsync` and use `this.run(obs, onSuccess, fallback)` — public template API is unchanged (`{{ errorMessage() }}` / `{{ successMessage() }}` still work).
+
+### 4. Internal: `BaseRestService` + `requireAuth()` + `openRecordDialog()` + `linkedSignal` alias-inputs
+
+- **`BaseRestService`** (`src/service/base_rest.service.ts`) owns the shared `inject(HttpClient)` and `url(path)` helper. `BackendService`, `BaseAuthService`, `BillingService`, `PayoutService`, and `UserPaymentMethodService` all extend it. The 27 hand-spelled `RestURL.httpHost + RestURL.xURL` getters in `BaseAuthService` are now `readonly` fields built via `this.url(...)`.
+- **`BaseTable.requireAuth(check, verb)`** replaces 8 copies of `alert('Missing authorization to … records')` across the codebase.
+- **`BaseView.openRecordDialog(record, isNew)`** collapses the duplicated `addRecord` / `editRecord` dialog-open bodies.
+- **`linkedSignal`** replaces the v0.8.0 `input() + signal + effect()` pattern across `TableList`, `TableSearch`, `TableEdit`, `TableDetail`, and `DynamicField`. One-line declarations per field; behaviour is unchanged (empty input doesn't override a `.set()` value).
+
+If your downstream component extends `BaseTable` / `BaseView` and uses the alias-input pattern from v0.8.0 (`input + effect`), you can optionally migrate to `linkedSignal` — but the old pattern still compiles.
+
+### 5. Internal: `BaseTable.caption` is no longer memoised; `Navigation.allMenuItems` via `toSignal`
+
+`getCaption()` and `colCaption()` previously cached on first read, so `tableName` updates after first render returned stale captions. They now recompute each call (cost is negligible). `Navigation` reads `allMenuItems` via `toSignal(getMenus(), { initialValue: [] })` instead of a manual `subscribe` in `ngOnInit`.
+
+### 6. TypeScript pinned to `~5.9.3`
+
+`@angular/compiler-cli@21.2` declares `typescript >=5.9 <6.1` as a peer, but downstream projects report that TS `6.0.3` requires `--legacy-peer-deps` on `npm install` because of transitive package mismatches. To keep the install path clean for all consumers, v0.8.1 pins to `~5.9.3`. Bump your downstream's `package.json` to match:
+
+```diff
+- "typescript": "~6.0.x"
++ "typescript": "~5.9.3"
+```
+
+### 7. Clean install + recompile
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+ng build
+```
+
+Expected errors after the upgrade:
+
+- **`'app-*' is not a known element`** — selector rename, see step 1.
+- **`'@Output' is deprecated`** — leftover from the v0.8.0 migration; finish it.
+- **`peerinvalid` / `--legacy-peer-deps` prompts on `npm install`** — your project still has TS 6.x. Downgrade per step 6.
+
+### 8. Backend alignment
+
+v0.8.1 targets **keel v0.8.3**. The shared keel API surface didn't grow in this release; the version pin tracks keel's matching v0.8.x line. See [keel/README.md → Migration Guide](https://github.com/nauticana/keel/blob/main/README.md) for the matching backend changes.
+
+## Modernization items
+
+When you extend sail in your own app, apply the same patterns sail itself follows. Downstream projects that copied templates or scaffolding from earlier sail versions will benefit from the same sweep. This list is a checklist — none are sail-specific.
+
+### Templates
+
+- **Native control flow.** Use `@if` / `@for` / `@switch` / `@let` blocks. `*ngIf`, `*ngFor`, `*ngSwitch` are legacy.
+- **Bindings, not directives, for class / style.** `[class.foo]="cond"`, `[style.width.px]="n"` — don't use `ngClass` / `ngStyle`.
+- **Material 21 M3 button selectors.** See step 5 above. `mat-raised-button` / `mat-stroked-button` etc. work but are not the current API.
+- **No `color="primary|accent|warn"` on Material components.** Use the `.primary` / `.accent` / `.warn` global CSS classes.
+- **Template spread inside expressions** (Angular 21). When you have a TS helper that only exists to merge objects for a binding, fold it into the template: `[config]="{ ...base, label: 'Override' }"`, `[items]="[...defaults, ...extra]"`, `[out]="fn(...args)"`. (Note: only valid inside array literals, object literals, or call expressions — there is no JSX-style host-attribute spread.)
+- **No structural directive on the same element as a component selector.** Already enforced by native control flow.
+
+### Components and directives
+
+- **Signal-based inputs/outputs.** `input()` / `output()` instead of `@Input()` / `@Output()`. Read as `this.x()` / `{{ x() }}`.
+- **`model()` for two-way bindings.** When the parent needs `[(value)]` binding semantics, declare `value = model('')` rather than rolling your own `@Output() valueChange`.
+- **`inject()` for dependencies.** No constructor parameter injection. Field-level `inject(Token)` keeps the constructor zero-arg and lets the class be subclassed without parameter forwarding.
+- **`ChangeDetectionStrategy.OnPush` on every component.** Signal-based code is fully compatible with OnPush; without it, change detection still runs needlessly.
+- **`host: { ... }` metadata, not `@HostBinding` / `@HostListener`.** Same effect, no decorators.
+- **Omit `standalone: true`.** It's the default in Angular v20+. Setting it explicitly is noise.
+- **Move HTML and styles to sibling files** when they grow past a few lines (`templateUrl: './*.html'`, `styleUrl: './*.scss'` or `styles: '...'`).
+
+### State and reactivity
+
+- **`signal()` for component state**, `computed()` for derived state, `effect()` for side effects that depend on signals. Don't roll your own `BehaviorSubject` for local UI state.
+- **`linkedSignal()`** for "use this input value by default, but allow local override" patterns.
+- **`takeUntilDestroyed()`** on long-lived observables (`valueChanges`, `route.queryParams`, `route.paramMap`, custom intervals). One-shot HTTP requests can skip it, but `valueChanges` and route streams must have it. Call it in a constructor or other injection context.
+- **`toSignal()`** for converting an `Observable<T>` into a signal at component boundaries — useful for `BillingService.listPlans()` and similar one-shots you read in templates.
+- **No `mutate()` on signals** — it was removed. Use `update(fn)` or `set(newValue)`.
+
+### Router
+
+- **Standalone `isActive(url, router, options?)` function** from `@angular/router`. Returns `Signal<boolean>`. `Router.prototype.isActive(...)` was `@deprecated` in Angular 21.1.
+- **`provideRouter([...])` for bootstrap.** No `RouterModule.forRoot`.
+- **Component input binding** for route params: enable `withComponentInputBinding()` and declare `id = input.required<string>()` on the routed component — drops the `ActivatedRoute` injection.
+
+### HTTP
+
+- **`provideHttpClient(withInterceptors([...]))`.** No `HttpClientModule`.
+- **Functional interceptors**, not class-based — sail's `authInterceptor` and `apiResponseInterceptor` are already functional; follow the same shape for your own.
+
+### Forms
+
+- **Reactive forms over template-driven.** sail uses `FormGroup` / `FormBuilder` throughout.
+- **`fb.nonNullable.group({...})`** for strict typing. Avoids `string | null` everywhere.
+
+### Bootstrap
+
+- **`bootstrapApplication()` with standalone components.** No `@NgModule`, no `AppModule`.
+- **`provideZonelessChangeDetection()`** — Angular 21's default. sail's components are signal-based and zoneless-safe.
+
+### Images
+
+- **`NgOptimizedImage`** for static `<img>` with known dimensions. **Exception:** base64 / data URIs aren't supported by `NgOptimizedImage` — use a plain `<img>` for those (the 2FA QR code in `TwoFactorSetupComponent` is the canonical case).
+
+### Tooling
+
+- **TypeScript `~6.0.3`** — within Angular 21.2's `>=5.9 <6.1` peer range. Bump from `~5.9.x`.
+- **`@angular/*` `^21.2.0`** for the matching set: core, common, compiler, forms, router, cdk, material.
+- **`npm update`** periodically to pull patch releases within the caret range.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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",
   "files": [
@@ -53,6 +53,6 @@
     "@angular/router": "^21.2.8",
     "class-validator": "^0.15.1",
     "rxjs": "~7.8.0",
-    "typescript": "~5.9.2"
+    "typescript": "~5.9.3"
   }
 }

package/src/component/abstract/base_async.ts

@@ -20,9 +20,15 @@ export abstract class BaseAsync {
     this.successMessage.set('');
   }
 
-  /** Set errorMessage from an HTTP error object; falls back to `fallback`. */
+  /**
+   * Set errorMessage from an HTTP error object; falls back to `fallback`.
+   *
+   * Reads `err.error.detail` first (keel emits RFC 7807 ProblemDetail with
+   * `detail` as the human-readable field), then `err.error.message` for
+   * legacy / non-RFC-7807 endpoints, then the supplied fallback.
+   */
   protected setError(err: any, fallback: string): void {
-    this.errorMessage.set(err?.error?.message ?? fallback);
+    this.errorMessage.set(err?.error?.detail ?? err?.error?.message ?? fallback);
     this.loading.set(false);
   }