@solidev/data 1.0.0-beta.1 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,475 @@
+# Using `@solidev/data` — rules for AI agents
+
+This file tells an AI coding agent how to use `@solidev/data` **correctly**. It is
+shipped inside the published package, so it is available at
+`node_modules/@solidev/data/AGENTS.md` in any consuming project.
+
+If you are an agent working in a project that depends on `@solidev/data`, read this
+before writing models, lists, or forms. The rules below are not style preferences —
+most of them are runtime contracts that fail **silently** when broken.
+
+> To adopt these rules in your project, see [Wiring this into your project](#wiring-this-into-your-project) at the end.
+
+---
+
+## 1. The mental model
+
+`@solidev/data` is a **Django-REST-Framework-style client for Angular**. The chain is:
+
+```
+DataModel  →  Collection<T>  →  Queryset<T>  →  ModelList<T>  →  components
+(fields)      (an endpoint)     (filter/sort)   (list state)     (dispedit, filters…)
+```
+
+The central idea: **you declare fields on a model, and the UI configures itself from
+that metadata.** A `foreignKeyField` renders as an FK dropdown, a `charField` with
+`choices` renders as a `<select>`, a `decimalField` renders as money — because the
+field manager sets its own `editorType`/`displayType`. You almost never choose a
+widget by hand.
+
+So: **put the effort into the model declaration.** Everything downstream follows.
+
+---
+
+## 2. Declaring a model
+
+### 2.1 The four-file split
+
+One directory per model, four files. This is the convention across every mature
+consumer of this library:
+
+```
+thing/
+  thing.base.ts      # ThingBase extends DataModel — server-side fields only
+  thing.ts           # Thing extends ThingBase — the *_details half of relations
+  thing.service.ts   # ThingService extends Collection<Thing>
+  thing.resolver.ts  # optional route resolver
+```
+
+The split is **not cosmetic — it is the circular-import firewall.** `*.base.ts`
+imports only `@solidev/data` plus local constants; it never imports a sibling model.
+`*.ts` is the only file allowed to import other model classes. Two models can
+reference each other because the id half of a relation only needs a *string*, never
+the target class.
+
+### 2.2 `__name` is mandatory and must be unique
+
+```ts
+export class ThingBase extends DataModel {
+  static override readonly __name: string = 'ThingBase';
+}
+export class Thing extends ThingBase {
+  static override readonly __name: string = 'Thing';   // redeclared, always
+}
+```
+
+Rules:
+
+- Declare `__name` on **every** class in the chain, base and concrete.
+- It must be **globally unique**.
+- Keep the explicit `: string` annotation — it defeats literal-type narrowing so
+  `override` typechecks.
+
+**Why it matters:** `DataModel`'s constructor walks the prototype chain and collects
+field metadata by matching keys against `` `${parent.constructor.__name}__` ``. A
+missing or duplicated `__name` **silently drops that class's fields**. There is no
+error — you just get a model with missing fields.
+
+### 2.3 Never declare `id`
+
+`id` is declared once on `DataModel` with `@primaryField()`. Every model inherits it.
+
+```ts
+// ✅ correct — say nothing, you already have `id: number`
+export class ThingBase extends DataModel { /* … */ }
+
+// ❌ WRONG — shadows the base field with `undefined`
+@primaryField() public override id!: number;
+```
+
+Under `useDefineForClassFields: true` (which this library and Angular ≥ 20 use),
+re-declaring `override id` emits `id = undefined` and destroys the inherited field.
+
+### 2.4 Field ordering and `priority`
+
+Source order is for humans. **Display order comes from `priority` — higher shows
+first.** `id` is `1000`.
+
+`priority: -1` is the established idiom for **"load this field, never offer it in the
+UI"**. Use it on the id half of every relation. A field with no `priority` sorts
+unpredictably — always set one.
+
+---
+
+## 3. Relations: the FK ⇄ details pair
+
+This is the single most important pattern in the library, and the easiest to get
+wrong. **Every relation is two fields split across two files.**
+
+```ts
+// thing.base.ts — the id half. Does NOT import Category.
+@foreignKeyField({
+  name: 'category',
+  description: 'Category',
+  related: 'Category',   // see the warning below
+  priority: -1,          // the raw id is plumbing, not UI
+})
+public category!: number;
+```
+
+```ts
+// thing.ts — the details half. Imports Category for real.
+import { Category } from '../category/category';
+
+@detailsField({
+  description: 'Category',
+  model: Category,       // ← the REAL link
+  readonly: true,
+  priority: 750,         // the displayed half of the pair
+})
+public category_details?: Category;
+```
+
+### 3.1 The `_details` name is a runtime contract
+
+`dispedit` and `m2mselect` find the sibling by **string concatenation** —
+`` (model as any)[`${field}_details`] ``. So the property must be named **exactly**
+`<fkFieldName>_details`. Nothing type-checks this. Rename the FK without renaming
+its details twin and both the display and the write-back break **silently**. There is
+no alias mechanism.
+
+### 3.2 `related:` is inert — do not rely on it
+
+**`related` is never read by the library.** It is unresolved, unvalidated, purely
+documentary metadata. In a 150-model production codebase, roughly 20% of `related`
+values point at classes that do not exist — misspellings and stale renames — and it
+has never caused a bug, because nothing resolves it.
+
+- Set it to the **concrete** class name (`'Category'`, never `'CategoryBase'`) as an
+  annotation for humans and tooling.
+- **Never assume it links anything.** `model:` on the details half does the work.
+
+### 3.3 Many-to-many is the same shape
+
+```ts
+// base — note defaultValue: []
+@manyToManyField({ name: 'tags', description: 'Tags', related: 'Tag',
+                   defaultValue: [], priority: -1 })
+public tags: number[] = [];
+
+// concrete — note many: true
+@detailsField({ description: 'Tags', model: Tag, many: true,
+                readonly: true, priority: 650 })
+public tags_details?: Tag[];
+```
+
+**`defaultValue: []` is not optional in practice.** Omit it and the field
+deserialises to `undefined`, which breaks the `m2mselect` editor.
+
+### 3.4 Self-reference needs nothing special
+
+A tree model points at itself with `related: 'Category'` in `category.base.ts` — just
+a string, so no cycle. The details half in `category.ts` uses `model: Category`, which
+is fully defined by the time the decorator runs. **No `forwardRef`, no lambda.**
+`model:` is always a bare class identifier.
+
+### 3.5 `detailsField` without `model:`
+
+A bare `@detailsField({...})` with no `model:` **passes the raw JSON through
+untouched**. That is the right tool for server-computed payloads and string arrays
+(e.g. a `flags: string[]`). For a shape that `model:`/`many:` cannot express, use the
+`deserialize: (data) => ...` escape hatch.
+
+### 3.6 Define `_display` on FK targets
+
+FK and M2M dropdowns render each option via the target model's `_display`. Define it
+on any model used as a relation target, or your dropdowns show nothing useful:
+
+```ts
+public get _display(): string { return this.name; }
+```
+
+A getter or a method both work (the library duck-types it); a **getter** is the
+convention.
+
+---
+
+## 4. The collection service
+
+One `@Injectable({providedIn: 'root'})` `Collection<T>` subclass per model. This is
+rigidly uniform in practice — do not invent variations.
+
+```ts
+@Injectable({ providedIn: 'root' })
+export class ThingService extends Collection<Thing> {
+  constructor() {
+    const backend = inject(DataBackend);
+    super(backend, '/path/to/things', Thing);
+  }
+}
+```
+
+- `inject(DataBackend)` goes **inside the constructor body** — `super()` must run
+  before `this` exists.
+- Three positional args: backend, **API-relative** path, **concrete** model class
+  (never the `*Base`).
+- Do **not** concatenate a base URL here. It comes from `DATA_API_URL`.
+- Keep the service stateless. Model-specific behaviour belongs in a separate
+  `*-action.service.ts`, not on the Collection subclass.
+
+`Collection.list()` assumes a **paginated** API response and reads `result.results`.
+
+---
+
+## 5. Lists — `ModelListService`
+
+### 5.1 Wrap it. Do not call it from every component.
+
+In a large production consumer, `ModelListService.get()` is called from **exactly one
+place**: an abstract base `@Directive` that ~150 list components extend. If you are
+adding lists to a project, look for that base class and extend it. If none exists and
+you need more than one or two lists, **write one** — the per-component boilerplate is
+otherwise copied everywhere.
+
+### 5.2 Call `get()` from `ngOnInit`, never the constructor
+
+`get()` consumes bound `@Input()`s (`name`, `keep`, `filter`). In a constructor they
+are still undefined, and you silently land in the "no name → always a fresh instance"
+branch.
+
+```ts
+private _subscriptions$ = new Subject<void>();
+
+public ngOnInit(): void {
+  this.list = this._list.get<Thing>(this.name, this.coll, {
+    fields:      this.fields,
+    filters:     this.filters,
+    sorter:      this.sorter,
+    paginator:   this.paginator,
+    keep:        this.keep,
+    reload:      this.reload,
+    filter:      this.filter,
+    unsubscribe: this._subscriptions$,
+  });
+}
+
+public ngOnDestroy(): void {
+  this._subscriptions$.next();
+  this._subscriptions$.complete();
+}
+```
+
+### 5.3 `name` + `keep` is a global cache — the #1 trap
+
+`ModelListService` holds `_instances: Map<string, ModelList>` keyed by **`name`
+alone** — not by component, not by route, not by collection.
+
+- With `keep: true`, two lists sharing a `name` **share one `ModelList`**. Field
+  selection, filters, sort and pagination bleed across routes.
+- Worse: when a cached instance is returned, **the `defaults` you passed are silently
+  ignored**. Your `fields`/`filters` do nothing on the second call.
+
+Rules: **`name` must be globally unique** (deriving it from the route is a good
+habit), and use **`keep: false`** when you want a private, non-persisted list.
+
+### 5.4 `filter` vs `filters` — they are different things
+
+| param | type | meaning |
+|---|---|---|
+| `filter` | `FilterDefaults \| Observable<FilterDefaults>` | A fixed dict **force-ANDed into every query**. Scoping/context. Not user-facing. |
+| `filters` | `FiltersParams` | Definitions of the **user-facing filter widgets**. |
+
+Mixing these up is a common and confusing mistake.
+
+### 5.5 Lifecycle
+
+- **`unsubscribe`**: a `Subject<void>` you own, passed in and fired in `ngOnDestroy`.
+  The library `takeUntil`s it. The public API is **Subject-based, not
+  `DestroyRef`-based** — reuse the same Subject for your own `takeUntil` pipes rather
+  than mixing both mechanisms.
+- **`reload`**: a `Subject<void|boolean>` you own; `.next(true)` re-runs the query.
+  Pass one if the list has row actions — if you don't, `get()` creates its own and
+  **you have no reference to it**.
+- **Known defect, design around it:** `get()` only wires `reload`/`unsubscribe`
+  `if (!ml.started)`. Revisit a `keep: true` list that is already running and your
+  `reload.next(true)` does nothing. If a list needs reliable refresh, prefer
+  `keep: false`.
+- **`fields.custom`** adds synthetic non-model columns (e.g. an actions column) so
+  they appear in both the table and the field selector.
+
+---
+
+## 6. Filters
+
+```ts
+new ModelListTextFilter({ name: 'search', field: 'q', label: 'Search', help: '…' })
+```
+
+- **`name` and `field` are different.** `field` = the query param sent to the server;
+  `name` = the filter's identity, used by `defaults`/`allowed`. Usually equal — but
+  two filters may share one `field` under different `name`s to present as distinct
+  widgets.
+- **Always set `label` and `help` explicitly.** Every filter class hardcodes a
+  **French** default when you omit them. If your app is not French, omitting them
+  leaks French into the UI.
+- Instantiate filters **inside** a `getFilters()`-style method, not as module
+  constants — most need an injected collection.
+- Several filters **throw on missing params** (as bare strings, not `Error`s, so no
+  stack trace):
+
+| filter | requires |
+|---|---|
+| `ModelListSelectFilter` / `…MultiFilter` | `choices` **or** `model` |
+| `ModelListAutocompleteFilter` / `…MultiFilter` | `collection` **or** `queryset` |
+| `ModelListTreeFilter` | `collection`/`queryset` (extends autocomplete) |
+| `ModelListFlagsFilter` | `collection` |
+| `ModelListGeodistanceFilter` | `geolocator` |
+
+Notes worth knowing:
+
+- `ModelListSelectFilter` can **reflect choices off the model** — pass `model:` (+
+  optional `mfield:`) instead of restating a `choices` list you already declared on
+  the field. `choices` also accepts an `Observable`.
+- Autocomplete/tree: narrow the lookup with
+  `filter: { fields: ['id', 'name'].join(',') }`. This is a real performance lever —
+  it stops the dropdown shipping whole objects.
+- `ModelListFlagsFilter` discovers its options at runtime via a collection action
+  (`get_flags` by default). Pass the list's own collection.
+- `ModelListFilterGroup` is a **presentation container only**. Groups go into the same
+  `filters: []` array as ungrouped filters, and `defaults` still names **leaf filter
+  names**, never group names.
+
+---
+
+## 7. Display and edit — `<data-dispedit>`
+
+```html
+<!-- a scalar, definition-list mode, auto-saves on edit -->
+<data-dispedit [model]="thing" field="name" mode="dd" [editable]="true" />
+
+<!-- an FK: [collection] is what makes the editor work -->
+<data-dispedit [model]="thing" field="category" mode="dd" [editable]="true"
+               [collection]="categories"
+               [filter]="{ fields: ['id', 'name'].join(',') }" />
+```
+
+- **`mode="dd"`** renders a `<dt>/<dd>` block that flips to an editor in place and
+  **auto-saves to the API**. This is the workhorse.
+- **`mode="inline"` / `"form"`** renders a bare form control and **does not save** —
+  it expects an external `[form]` group and your own submit. **Exception:** FK/M2M
+  selection saves in *every* mode. The selection handler calls `_save()`
+  unconditionally, so an FK picked inside an `inline`/`form` form PATCHes immediately
+  rather than waiting for your submit. Don't design around it saving on submit.
+- `field` is a **static string**, not a binding.
+- **`[collection]` is required for FK/M2M editors.** `[filter]` narrows that lookup.
+- The widget is chosen from field metadata. Overrides exist but are almost never the
+  right answer — fix the model instead.
+- If you use dispedit's auto-save, render a `<data-message-zone>` somewhere;
+  successes and errors are reported through `DataMessageService` and are otherwise
+  invisible.
+
+**Do not try to bind `[save]`.** It is declared as a plain class property, not an
+`input()`, so it is not template-bindable. Control saving via `mode`.
+
+---
+
+## 8. Bootstrap wiring
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    { provide: DATA_API_URL, useValue: environment.API_URL },
+
+    { provide: DATA_AUTH_PARAMS, useValue: {
+        tokenUrl:        environment.API_URL + '/path/to/token',
+        tokenRefreshUrl: environment.API_URL + '/path/to/token/refresh',
+        loginField: 'username', passwordField: 'password', tokenField: 'token',
+        loginRoute: ['/login'], logoutRoute: ['/'],
+        userFetchValiditySeconds: 600,
+      } as AuthParams },
+
+    { provide: DATA_AUTH_URLS, useValue: [environment.OTHER_API_URL] },
+
+    // useExisting — NOT useClass. See below.
+    { provide: DATA_AUTH_USER_SERVICE, useExisting: UserService },
+    { provide: DATA_AUTH_SERVICE,      useExisting: AuthService },
+    AuthService,   // the concrete class must also be provided
+
+    provideHttpClient(withInterceptorsFromDi()),
+    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
+  ],
+});
+```
+
+- `DATA_API_URL` is **required** and must not have a trailing slash.
+- `DATA_AUTH_SERVICE` / `DATA_AUTH_USER_SERVICE` must use **`useExisting`**, aliasing
+  app-owned singletons — so the concrete class must **also** be listed as a plain
+  provider. `useClass` there creates a **second instance** and breaks `logout$`.
+- `AuthInterceptor` is a **legacy `HTTP_INTERCEPTORS` multi-provider**, which forces
+  `withInterceptorsFromDi()`. It is not a functional interceptor.
+- **Optional, with fallbacks — provide only if you need them:**
+  - `DATA_DISPLAY_CONFIG` falls back to `BootstrapDataDisplayConfig` (Bootstrap 5
+    classes). Provide it only for a different CSS framework.
+  - `DATA_MAX_TRANSFERSTATE_TIME` defaults to `0` (TransferState disabled). Provide it
+    only for SSR.
+
+---
+
+## 9. Testing
+
+Use the shipped mocks — **do not stand up HTTP** to test a model:
+
+```ts
+const things = new CollectionMock<Thing>(Thing);
+const t = things.fromJson({ id: 1, name: '…' }) as Thing;
+
+things.mockValues = [t];              // drives .list()
+const qs = things.queryset();
+qs.mockData = [t];                    // drives .get()
+```
+
+`CollectionMock` / `QuerysetMock` are exported from the package root. A worked,
+test-covered example lives in the library repo at
+`projects/data/src/examples/catalog/`.
+
+---
+
+## 10. Checklist before you finish
+
+Run through this. Every item is a silent failure, not a compile error.
+
+- [ ] `static override readonly __name: string` on **every** class, **unique**.
+- [ ] **No** `override id` anywhere.
+- [ ] Every FK/M2M has a matching `<field>_details` — spelled **exactly** right.
+- [ ] Every `detailsField` that should hydrate a model has `model:` (not just
+      `related:`).
+- [ ] Every m2m id field has `defaultValue: []`.
+- [ ] Every model used as an FK target defines `_display`.
+- [ ] `priority` set on every field; `-1` on relation id halves.
+- [ ] `ModelListService.get()` called in `ngOnInit`, with a **globally unique**
+      `name`, and an `unsubscribe` Subject fired in `ngOnDestroy`.
+- [ ] Every filter has an explicit `label` and `help` (or you ship French).
+- [ ] Collection path is API-relative; no base URL concatenated.
+
+---
+
+## Wiring this into your project
+
+Add this to your project's own `AGENTS.md` / `CLAUDE.md` so agents pick the rules up
+automatically:
+
+```markdown
+## @solidev/data
+
+This project uses `@solidev/data` for its models, collections and list/edit UI.
+Before writing or changing any model, collection, list component, or `dispedit`
+usage, read `node_modules/@solidev/data/AGENTS.md` and follow it.
+
+Non-negotiables from that file:
+- Never declare `override id` on a model — it is inherited from `DataModel`.
+- `static override readonly __name` on every model class, globally unique.
+- Every foreign key needs a `<field>_details` twin; the name is a runtime contract.
+- `related:` is inert documentation — `model:` on the details half does the linking.
+- `ModelListService.get()` goes in `ngOnInit`, with a globally unique `name`.
+- Always set `label`/`help` on filters, or French defaults leak into the UI.
+```

package/README.md

@@ -1,7 +1,97 @@
-# @solidev/data library
+# @solidev/data
 
-- data fields / models / collections
-- data backends & query
-- model list display
-- model edit
+A **Django-REST-Framework-style data layer for Angular**. Declare a model once and get
+HTTP access, querysets, filtering, sorting, pagination, forms, validation and
+display/edit widgets — all driven by that single declaration.
 
+```ts
+export class ProductBase extends DataModel {
+  static override readonly __name: string = 'ProductBase';
+
+  @charField({ description: 'Name', maxLength: 200 })
+  public name!: string;
+
+  @charField({ description: 'Status', choices: [
+    { value: 'draft', desc: 'Draft' },
+    { value: 'published', desc: 'Published' },
+  ]})
+  public status!: string;
+
+  @foreignKeyField({ description: 'Category', related: 'Category', priority: -1 })
+  public category!: number;
+}
+```
+
+```html
+<data-dispedit [model]="product" field="name"   mode="dd" [editable]="true" />
+<data-dispedit [model]="product" field="status" mode="dd" [editable]="true" />
+<data-dispedit [model]="product" field="category" mode="dd" [editable]="true"
+               [collection]="categories" />
+```
+
+That is the whole idea: `status` renders as a `<select>` and `category` as an FK
+dropdown **because the field metadata says so**. You declare the model; the UI follows.
+
+## Install
+
+```bash
+npm install @solidev/data
+```
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    { provide: DATA_API_URL, useValue: 'https://api.example.com/v1' },
+    provideHttpClient(),
+  ],
+});
+```
+
+## What's in the box
+
+| Module | What it gives you |
+|---|---|
+| **data** | `DataModel` + field decorators, `Collection<T>`, `Queryset<T>`, `DataBackend` (with SSR `TransferState` support) |
+| **modellist** | `ModelListService` — field selection, filters, sorter, paginator, and the components to render them |
+| **dispedit** | `<data-dispedit>` and friends — metadata-driven display/edit, FK/M2M pickers, flags, safe-delete |
+| **auth** | JWT service + interceptor with automatic refresh and replay |
+| **messages, routing, updates, uploader, richedit** | supporting pieces |
+
+## Documentation
+
+- **Guides** — see the `docs/` directory in the repository, also published in the
+  generated documentation under **Guides**.
+- **API reference** — generated with [compodoc](https://compodoc.app):
+  `npm run mkdocs:serve`.
+- **Worked example** — `projects/data/src/examples/catalog/`, a small catalog domain
+  (tree categories, m2m tags, geolocated stores, flags) that is **test-covered**, so it
+  cannot drift from the library.
+
+### Using this library with an AI agent
+
+This package ships **[`AGENTS.md`](./AGENTS.md)** — a rules file covering the model
+conventions and the runtime contracts that fail silently when broken. It is available
+in consuming projects at `node_modules/@solidev/data/AGENTS.md`.
+
+Point your agent at it from your own `AGENTS.md` / `CLAUDE.md`:
+
+```markdown
+This project uses `@solidev/data`. Before writing or changing any model, collection,
+list component, or `dispedit` usage, read `node_modules/@solidev/data/AGENTS.md`
+and follow it.
+```
+
+## Start here
+
+Whatever else you skip, read the **Relations** guide and the **Traps** guide. The
+FK ⇄ details pairing is a runtime contract enforced by string concatenation, and most
+of the ways to misuse this library fail **silently**.
+
+## Requirements
+
+Angular 22+. Peer dependencies: `@angular/common`, `@angular/core`, and — depending on
+which parts you use — `@ng-bootstrap/ng-bootstrap`, `jwt-decode`, `ngx-editor`.
+
+## Licence
+
+See [LICENSE](../../LICENSE).