@nauticana/sail 1.1.14 → 1.1.17

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Mustafa Karli
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -240,17 +240,41 @@ keel REST list responses are paginated:
 { "items": [...], "limit": 100, "offset": 0, "total": 12345 }
 ```
 
-`BackendService.list<T>()` continues to return `Observable<T[]>` — sail unwraps `items` for you. To access the metadata, use `listPaginated<T>()`:
+`BackendService.list<T>()` continues to return `Observable<T[]>` — sail unwraps `items` for you. Both list methods accept a typed `PageRequest` after the filter map. To access the metadata, use `listPaginated<T>()`:
 
 ```typescript
-this.backend.listPaginated<MyRow>('orders', { _limit: '50', _offset: '0' })
+this.backend.listPaginated<MyRow>('orders', { Status: 'open' }, {
+    limit: 50,
+    offset: 0,
+    orderBy: 'created_at DESC',
+})
     .subscribe((page) => {
       this.rows.set(page.items);
       this.total.set(page.total);   // total rows matching the filter
     });
 ```
 
-Default page size is 100, capped at 1000 server-side. Pass `_limit` / `_offset` in the filter map to control paging.
+Default page size is 100, capped at 1000 server-side. Sail maps `limit`, `offset`, and `orderBy` to keel's `_limit`, `_offset`, and `_order` query controls. Existing callers that put those string controls in the filter map remain compatible; explicit `PageRequest` values take precedence.
+
+## Backend-driven constant captions
+
+`LabelService` loads one keel `constant_value` domain from the backend-provided `ApplicationData.ConstantCache` and caches its value-to-caption map. The domain is the backend `constant_id` (for example `ride_type`), not a locale: keel's constant catalogue does not contain a language column. It does not call generic `constant_value` CRUD, which is normally restricted to administrative roles.
+
+```typescript
+this.labels.loadLabels('ride_type').subscribe(() => {
+  this.rideTypeCaption.set(this.labels.getLabel('ride_type', ride.type));
+});
+```
+
+Concurrent loads share one application-data subscription, completed domains stay cached, and application-data failures can be retried. Missing values fall back to the raw key.
+
+## Status-filtered API errors
+
+Pass an optional status allowlist when backend detail is safe to show only for selected responses. Other HTTP statuses return the caller's generic fallback:
+
+```typescript
+errorDetail(error, 'Could not save.', [400, 409]);
+```
 
 ## Configuration reference
 
@@ -1163,10 +1187,10 @@ Wherever you stored the OTP `sessionId`, swap it for `otpToken: string`.
 
 `BackendService.list<T>()` returns `Observable<T[]>` (unchanged). It now expects keel to return paginated `{items, limit, offset, total}` and has dropped the legacy "bare array" fallback. If you have an in-house wrapper that calls keel `list` endpoints directly, expect the wrapper shape.
 
-For pagination metadata, use `listPaginated<T>()`:
+For pagination metadata, use `listPaginated<T>()` with a typed `PageRequest`:
 
 ```typescript
-backend.listPaginated<MyRow>('orders', { _limit: '50', _offset: '0' })
+backend.listPaginated<MyRow>('orders', undefined, { limit: 50, offset: 0 })
   .subscribe(page => {
     this.rows.set(page.items);
     this.total.set(page.total);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.14",
+  "version": "1.1.17",
   "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/table/table_list.ts

@@ -103,12 +103,11 @@ export class TableList extends AbstractEditableView implements OnInit {
     }
 
     private loadPage(): Observable<unknown> {
-        const filter = {
-            ...this.searchTerms(),
-            _limit: String(this.pageSize()),
-            _offset: String(this.pageIndex() * this.pageSize()),
-        };
-        return this.backendService.listPaginated<Record<string, unknown>>(this.apiName(), filter).pipe(
+        return this.backendService.listPaginated<Record<string, unknown>>(
+            this.apiName(),
+            this.searchTerms(),
+            { limit: this.pageSize(), offset: this.pageIndex() * this.pageSize() },
+        ).pipe(
             tap((page) => {
                 this.records.set(page.items ?? []);
                 this.total.set(page.total ?? page.items?.length ?? 0);

package/src/model/appdata.ts

@@ -330,6 +330,13 @@ export interface PaginatedList<T> {
 	total:  number;
 }
 
+/** Typed controls for keel REST list pagination and ordering. */
+export interface PageRequest {
+	limit?:   number;
+	offset?:  number;
+	orderBy?: string;
+}
+
 export interface Subscription {
 	planId:      string;
 	status:      string;  // 'A' active, 'P' pending-payment, 'C' cancelled, 'T' trialing, 'X' past-due — caption via SUBSCRIPTION_STATUS dict

package/src/service/label.service.ts

@@ -1,19 +1,44 @@
-import { Injectable } from "@angular/core";
+import { inject, Injectable } from "@angular/core";
+import { Observable, map, of, shareReplay, take, tap } from "rxjs";
+import { BaseAuthService } from "./auth.service";
 
-// TODO: Implement translated captions service
-// - loadLabels(langcode) should fetch labels from the backend
-// - getLabel(langcode, key) should return the translated caption for a given key
-// - BaseTable.colCaption() and related methods should use this service for i18n
 @Injectable({ providedIn: 'root' })
 export class LabelService {
+    private readonly auth = inject(BaseAuthService);
     protected labels: Map<string, Map<string, string>> = new Map();
+    private readonly pendingLoads = new Map<string, Observable<void>>();
 
-    /** Falls back to the key itself so a missing translation is visible, not a blank caption. */
-    getLabel(langcode: string, key: string): string {
-        return this.labels.get(langcode)?.get(key) ?? key;
+    /** Return a caption from a constant domain, falling back visibly to its raw value. */
+    getLabel(constantId: string, key: string): string {
+        return this.labels.get(constantId)?.get(key) ?? key;
     }
 
-    loadLabels(_langcode: string) {
-        // TODO: fetch from backend and populate this.labels
+    /**
+     * Load one backend-provided `constant_value` domain from ApplicationData.
+     * Completed and concurrent requests are cached; a failed application-data
+     * load is evicted so a later call can retry.
+     */
+    loadLabels(constantId: string): Observable<void> {
+        const domain = constantId.trim();
+        if (!domain) throw new Error('sail: a constant id is required to load labels.');
+        if (this.labels.has(domain)) return of(undefined);
+
+        const pending = this.pendingLoads.get(domain);
+        if (pending) return pending;
+
+        const request = this.auth.getAppData().pipe(
+            take(1),
+            tap({
+                next: (data) => this.labels.set(
+                    domain,
+                    new Map(Object.entries(data.ConstantCache?.[domain] ?? {})),
+                ),
+                error: () => this.pendingLoads.delete(domain),
+            }),
+            map(() => undefined),
+            shareReplay({ bufferSize: 1, refCount: false }),
+        );
+        this.pendingLoads.set(domain, request);
+        return request;
     }
 }

package/src/service/rest_service.ts

@@ -1,7 +1,7 @@
 import { HttpErrorResponse, HttpParams } from "@angular/common/http";
 import { inject, Injectable } from "@angular/core";
 import { catchError, map, Observable, switchMap, take, throwError } from "rxjs";
-import { ApplicationData, PaginatedList } from "../model/appdata";
+import { ApplicationData, PageRequest, PaginatedList } from "../model/appdata";
 import { RestURL } from "./rest_url";
 import { BaseAuthService } from "./auth.service";
 import { BaseRestService } from "./base_rest.service";
@@ -83,15 +83,19 @@ export class BackendService extends BaseRestService {
         return this.http.request<T>(method, this.apiUrl(path), { body }).pipe(catchError((err) => this.handleError(err)));
     }
 
-    /** Build query params from a flat string-string map; skips undefined/null values. */
-    private toParams(filter?: {[key: string]: string}): HttpParams {
+    /** Build query params from filters plus keel's underscore-prefixed paging aliases. */
+    private toParams(filter?: {[key: string]: string}, page?: PageRequest): HttpParams {
         let params = new HttpParams();
-        if (!filter) return params;
-        for (const key in filter) {
-            if (Object.prototype.hasOwnProperty.call(filter, key) && filter[key] != null) {
-                params = params.set(key, filter[key]);
+        if (filter) {
+            for (const key in filter) {
+                if (Object.prototype.hasOwnProperty.call(filter, key) && filter[key] != null) {
+                    params = params.set(key, filter[key]);
+                }
             }
         }
+        if (page?.limit != null) params = params.set('_limit', page.limit);
+        if (page?.offset != null) params = params.set('_offset', page.offset);
+        if (page?.orderBy) params = params.set('_order', page.orderBy);
         return params;
     }
 
@@ -100,16 +104,16 @@ export class BackendService extends BaseRestService {
         return this.auth.getAppData().pipe(take(1));
     }
 
-    /** Unwraps `{items, limit, offset, total}` to the items array. Pass `_limit` / `_offset` in `filter` to control paging (defaults: 100 / 0). */
-    list<T>(apiName: string, filter?: {[key: string]: string}) : Observable<T[]> {
-        return this.listPaginated<T>(apiName, filter).pipe(map((page) => page.items));
+    /** Unwraps `{items, limit, offset, total}` to the items array. */
+    list<T>(apiName: string, filter?: {[key: string]: string}, page?: PageRequest) : Observable<T[]> {
+        return this.listPaginated<T>(apiName, filter, page).pipe(map((result) => result.items));
     }
 
-    listPaginated<T>(apiName: string, filter?: {[key: string]: string}) : Observable<PaginatedList<T>> {
+    listPaginated<T>(apiName: string, filter?: {[key: string]: string}, page?: PageRequest) : Observable<PaginatedList<T>> {
         return this.appDataReady().pipe(
             switchMap(() => this.http.get<PaginatedList<T>>(
                 this.crudUrl(apiName, 'list'),
-                {params: this.toParams(filter)},
+                {params: this.toParams(filter, page)},
             )),
             catchError((err) => this.handleError(err)),
         );

package/src/util/errors.ts

@@ -15,11 +15,42 @@ function asString(value: unknown): string | undefined {
   return typeof value === 'string' && value ? value : undefined;
 }
 
+function statusOf(err: unknown): number | undefined {
+  if (!err || typeof err !== 'object') return undefined;
+  const s = (err as { status?: unknown }).status;
+  return typeof s === 'number' ? s : undefined;
+}
+
+/**
+ * True when the browser never received a readable response — the network was
+ * down, a CORS rule blocked it, or the request was aborted. Angular collapses
+ * all three to status 0 with a ProgressEvent body, so this is the only signal
+ * available. Use it to offer a retry rather than reporting a backend rejection.
+ */
+export function isTransportFailure(err: unknown): boolean {
+  return statusOf(err) === 0;
+}
+
 /**
  * Human-readable message from any sail error shape — SailApiError (BackendService),
  * raw HttpErrorResponse (direct HttpClient calls), or plain Error.
+ *
+ * keel answers every rejection with an RFC 7807 body, so an error carrying no
+ * `detail` did not come from the API: either nothing reached it (status 0) or
+ * something in front of it replied with a body we cannot read. Both used to
+ * collapse into the caller's fallback, which reads as a backend rejection and
+ * hides the real fault; they are now reported distinctly. When `statuses` is
+ * supplied, HTTP statuses outside that allowlist return `fallback` without
+ * exposing their response text.
  */
-export function errorDetail(err: unknown, fallback: string): string {
+export function errorDetail(err: unknown, fallback: string, statuses?: readonly number[]): string {
+  const status = statusOf(err);
+  if (statuses && status !== undefined && !statuses.includes(status)) {
+    return fallback;
+  }
+  if (isTransportFailure(err)) {
+    return 'Cannot reach the server — the network or a CORS rule blocked the response.';
+  }
   const problem = problemOf(err);
   if (problem) {
     const message = asString(problem.detail) ?? asString(problem.title) ?? asString(problem.message);
@@ -28,7 +59,7 @@ export function errorDetail(err: unknown, fallback: string): string {
   if (err instanceof Error && err.message) {
     return err.message;
   }
-  return fallback;
+  return status ? `${fallback} (HTTP ${status})` : fallback;
 }
 
 /** Stable machine-readable discriminator from a keel RFC 7807 response. */