@nest-my-admin/core 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,9 @@
 A Django-admin-class admin panel for **NestJS + TypeORM**: declarative resources, forms from your DTOs,
 admin writes that go through your own services, and a prebuilt shadcn UI served by Nest itself.
 
-> Status: pre-alpha, version 0.2 (lists and forms, sign-in, permissions, files and rich text, actions, settings pages, audit log). APIs will change.
+> Status: pre-alpha, version 0.2.1 (lists and forms, sign-in, permissions, files and rich text, actions, settings pages, audit log). APIs will change.
+>
+> **Upgrading from 0.2.0:** nothing breaks; see [Upgrading to 0.2.1](#upgrading-to-021) for what is new and what you may notice.
 >
 > **Upgrading from 0.1:** boot can now fail for an app that booted before, and a few behaviours changed. See [Upgrading to 0.2](#upgrading-to-02).
 
@@ -11,6 +13,14 @@ Requires NestJS 11 or 12, TypeORM 0.3.20+ or 1.x, Node 20.19+ (or Bun), and Post
 The package is ESM; CommonJS apps load it through Node's `require(esm)`. A CommonJS app compiled with
 `"module": "nodenext"` (the `nest new` default since Nest 11) needs TypeScript 5.8+; with `"module": "commonjs"` any 5.x works.
 
+```bash
+npm install @nest-my-admin/core          # the admin (brings the prebuilt UI with it)
+npm install @nest-my-admin/auth          # optional: the built-in sign-in
+npm install -D @nest-my-admin/testing    # optional: test helpers
+```
+
+`nest-my-admin` (no scope) is the same package as `@nest-my-admin/core` under a shorter name: it re-exports it, at the same version.
+
 ```ts
 @AdminResource(Product, { icon: 'package' })
 export class ProductAdmin extends AdminResourceBase<Product> {
@@ -42,6 +52,23 @@ in the default create/update/delete, and `AdminModule.forRoot({ autoRegister: tr
 without a resource. `ne` and `nin` exclude NULLs (SQL semantics), and datetime filter values must be ISO-8601
 with a time zone.
 
+### Sidebar groups and order
+
+```ts
+@AdminGroup({ key: 'settings', label: { en: 'Settings', fa: 'تنظیمات' }, icon: 'settings', order: 900 })
+@Module({ providers: [BrandingPage, SeoPage] })
+export class SettingsModule {}
+
+@AdminSettingsPage('branding', { group: 'settings', order: 10, form: BrandingDto })   // first
+@AdminSettingsPage('seo', { group: 'settings', order: 20, form: SeoDto })             // second
+@AdminResource(Product, { order: 10 })                                                // first among its group's resources
+```
+
+- **A group is a Nest module.** Resources and settings pages go to the group of the module that provides them; `@AdminGroup` on the module sets its `key` (default: the module's name in kebab-case, without `Module`), `label`, `icon` and `order` (lower first, default 100; then by label).
+- **`group: '<key>'`** on a resource or a page puts it into another group. That group is configured by the module whose `@AdminGroup` has that key: any module of the app, whether the group's members are its own or not, resources, pages or both, in any import order. Such a module may provide nothing at all. A key that no `@AdminGroup` names gets its key as label (`odds-and-ends` → "Odds and ends"), no icon and order 100.
+- **One module per key.** When two modules configure the same key with a different label, icon or order, the first one Nest discovers (import order) wins and a warning is logged at boot. The same options twice are fine.
+- **`order` inside a group.** `@AdminResource(Entity, { order })` and `@AdminSettingsPage(name, { order })`: lower comes first, then the label in the reader's language; the default is 100, as for groups. A group lists its resources first and its settings pages after them, so `order` sorts resources among resources and pages among pages. The sidebar, the group's page, the home page and the command palette all show this order. `order` must be a finite number, or boot fails.
+
 ### Customising lists
 
 Put row restrictions in `query(qb, ctx)`. It applies to every read path: the list, GET, PATCH, DELETE, restore and
@@ -175,7 +202,9 @@ AdminModule.forRoot({
 
 - **Languages.**
   - The language switch appears when there is more than one locale, and the choice is remembered in the browser.
-  - The UI sends it as `Accept-Language`. Labels given per language answer in it, falling back to the default
+  - The page itself (`GET <path>/` and every deep link) is served in the default `locale`: `<html lang dir>` (`dir` is `rtl` for `fa`, `ar`, `he` and `ur`), your `title` in that language as `<title>`, and `Content-Language`. It is the same page for every request; the browser's `Accept-Language` is not consulted, because the UI starts in the default locale too.
+  - A reader who switched to another language gets the default-locale page for the moment before the script runs, which then sets `lang`, `dir` and the title for their choice (the choice lives in their browser, where the server cannot see it).
+  - The UI sends the language in use as `Accept-Language` with every API request. Labels given per language answer in it, falling back to the default
     locale.
   - Resources and hooks see it as `ctx.locale`.
   - Field labels, help, placeholders and enum value labels take the same `{ en, fa }` form (see Fields and forms).
@@ -297,6 +326,15 @@ export class ProductAdmin extends AdminResourceBase<Product> {
   - `s3Storage({ endpoint, region, bucket, accessKeyId, secretAccessKey, publicBaseUrl?, forcePathStyle? })` works with S3 and compatible stores (MinIO, R2), with no SDK.
   - Anything else: implement `AdminStorage` (`put`, `get`, `delete`, `publicUrl`).
   - Files are tracked in the `nma_file` table (`ADMIN_FILE_ENTITIES`; `files.dataSource` names another DataSource).
+- **Storage keys.** The admin makes up a key at upload and never changes it:
+
+  | The file of | Upload query | `nma_file.resource` / `recordId` | Storage key |
+  | --- | --- | --- | --- |
+  | a resource's record | `resource=<resource>&field=<field>` | `<resource>` / the record's id | `<resource>/<field>/<yyyy>/<mm>/<uuid><ext>` |
+  | a settings page | `resource=page:<name>&field=<field>` | `page:<name>` / `page` | `page/<name>/<field>/<yyyy>/<mm>/<uuid><ext>` |
+
+  - `<yyyy>/<mm>` is the month of the upload in UTC, `<uuid>` a random UUID, and `<ext>` the extension of the type found in the bytes (`.png`, `.pdf`; nothing when the type has none).
+  - A page is written `page:<name>` wherever it is named as the owner, and `page/<name>/` in the key: a colon is not a file name everywhere. Example: `page/branding/logo/2026/10/ca56b927-6a9a-40c9-8967-28a6433f7b59.png`.
 - **Fields.**
   - The column holds the storage key (`product/image/2026/10/<uuid>.png`), or the list of keys for `many`. Records carry `_files[field]` with each file's `name`, `size`, `contentType` and `url`.
   - `file.accept` lists types (`image/*`, `application/pdf`); the image widget defaults to `image/*`. `file.maxBytes` overrides `files.maxBytes` (default 10 MiB); both stop at 2147483647 bytes (2 GiB - 1).
@@ -317,7 +355,7 @@ export class ProductAdmin extends AdminResourceBase<Product> {
   - The stored HTML holds the full URL of each image. Changing the admin `path` or the storage's `publicBaseUrl` later breaks the images of existing records (and the admin no longer recognises them as the record's files), so rewrite the stored HTML when you move either.
   - **Duplicate** copies the text without its images, for the same reason it copies no files.
   - The editor is a separate chunk of the UI, loaded only by forms with a rich-text field.
-- **API.** `POST /api/uploads?resource=&field=` takes the file itself as the request body (not multipart) with `Content-Type: application/octet-stream`, `Content-Length` and an optional percent-encoded `X-File-Name`, and answers `{ token, name, contentType, size, url? }`. Do not send the file's own type: a body parser of your app (Nest's JSON parser, for one) would read an `application/json` body before the admin does, and the upload is then refused with a 400 that says so. A write then sends `{ token }` for a new file, `{ key }` to keep a stored one, or `null`; a `many` field sends the whole list. Sending the same `{ token }` again for the same record and field (a retry after a lost answer) keeps the file.
+- **API.** `POST /api/uploads?resource=&field=` (`resource=page:<name>` for a settings page) takes the file itself as the request body (not multipart) with `Content-Type: application/octet-stream`, `Content-Length` and an optional percent-encoded `X-File-Name`, and answers `{ token, name, contentType, size, url? }`. Do not send the file's own type: a body parser of your app (Nest's JSON parser, for one) would read an `application/json` body before the admin does, and the upload is then refused with a 400 that says so. A write then sends `{ token }` for a new file, `{ key }` to keep a stored one, or `null`; a `many` field sends the whole list. Sending the same `{ token }` again for the same record and field (a retry after a lost answer) keeps the file.
 
 **Security notes**
 
@@ -330,6 +368,74 @@ export class ProductAdmin extends AdminResourceBase<Product> {
 - Rich text is sanitized on the server at every write, whatever the browser sent. Links keep http(s), mailto and relative addresses and get `rel="noopener noreferrer nofollow"`; an `<img>` is kept only when it points at a file of this admin that belongs to the record (or that the same user just uploaded for this field). A custom `files.sanitizeHtml` is trusted to do the same.
 - An unsaved upload can be fetched only by the user who made it.
 
+**Serving public files yourself**
+
+A storefront needs the public files (product images, the shop's logo) without an admin session. With a `publicBaseUrl` the storage serves them. Without one, serve them from a route of your own and ask `AdminFiles` which keys are public; do not read `nma_file` yourself.
+
+```ts
+import { AdminFiles } from '@nest-my-admin/core';
+import { Controller, Get, NotFoundException, Param, Req, Res, StreamableFile } from '@nestjs/common';
+import type { Request, Response } from 'express';
+
+/** Images a browser may show in place; everything else is downloaded. */
+const RASTER = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/avif']);
+
+@Controller('media')
+export class MediaController {
+  constructor(private readonly files: AdminFiles) {}   // AdminModule is global: nothing to import
+
+  @Get('*key')                                          // Nest 11 (Express 5): the segments of the key
+  async serve(@Param('key') key: string | string[], @Req() req: Request, @Res({ passthrough: true }) res: Response): Promise<StreamableFile | undefined> {
+    const path = Array.isArray(key) ? key.join('/') : key;
+    // Express answers HEAD with the GET route: the row is enough for that, the object is not opened.
+    const file = req.method === 'HEAD' ? await this.files.publicFile(path) : await this.files.openPublic(path);
+    if (!file) throw new NotFoundException();
+    res.setHeader('Content-Type', file.contentType.startsWith('text/') ? 'text/plain; charset=utf-8' : file.contentType);
+    res.setHeader('Content-Length', String(file.size));
+    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');   // a replaced file gets a new key
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+    if (!RASTER.has(file.contentType)) {
+      const name = encodeURIComponent(file.name).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${name}`);
+    }
+    if (!('body' in file)) return undefined;
+    const { body } = file;
+    res.on('close', () => body.destroy());   // a reader who leaves early must not keep the file or the connection open
+    return new StreamableFile(body);
+  }
+}
+```
+
+- **Keep the headers.** Uploaded bytes are someone else's content served from your origin. `nosniff` and the type found at upload stop a browser from guessing another type; the `Content-Security-Policy` stops anything served here from running or loading anything if it is opened as a page; everything but a raster image is a download (`Content-Disposition: attachment`), and text is only ever `text/plain`. This is what the admin's own download route does.
+- `publicFile(key)` answers `{ key, name, contentType, size }` or `null`, from the `nma_file` table alone (the storage is not touched): enough for a `HEAD`, or to decide before streaming.
+- `openPublic(key)` makes the same check and then reads the storage: `{ body, contentType, size, name }`, or `null` when the key is not a public file or the object is gone from the storage. `size` is the stored object's size, or the size recorded at upload when the storage does not report one. **Consume `body` or destroy it**: an unread body holds a file descriptor or a connection to the storage.
+- **Public** means a row with `visibility: 'public'` (the field's `file: { visibility: 'public' }`) and `status: 'attached'` (a saved record or settings page holds it). A private file, an upload nobody saved yet, a file its record let go of and a key the admin never issued are all `null`, and so is anything that is not a key (an empty string, `..` segments, a backslash, more than 500 characters): neither method throws for what a key is, so the key can come straight from the URL. No permission is checked.
+- **Public is what was recorded at upload.** `AdminFiles` goes by the row's visibility, set from the field's `file.visibility` when the file was uploaded: a field you later make private keeps its earlier files public (new uploads are private). A record in the trash still holds its files, so its public files are still served; they stop when the record is purged or the file is removed from it.
+- `contentType` is the type the admin found in the file's bytes at upload, never what the uploader claimed. The long `Cache-Control` is safe for the key (a replaced file gets a new one), but a file that is removed or made private stays in browser and CDN caches until it expires there; choose the lifetime with that in mind.
+- `AdminFiles` is always injectable and follows `files.dataSource`. In an admin without `files`, both methods reject with an error that says `files` is missing (`files.enabled` tells beforehand); before the application has started they reject too.
+- The admin's own `url` for a public file without a `publicBaseUrl` is `<path>/api/files/<key>`, which needs an admin session: build your storefront's link from the key (`/media/${key}`) instead.
+
+#### Registering files yourself
+
+A host that stores a file itself (an image fetched from another system, an attachment its own API took) registers it, so the admin's downloads, `_files`, `publicFile` and the delete/purge cleanup treat it like an upload:
+
+```ts
+await dataSource.transaction(async (manager) => {
+  const file = await this.adminFiles.register(
+    { resource: 'product', field: 'image', recordId: product.id, body: imageStream, name: 'front.jpg' },
+    manager,
+  );
+  await manager.update(Product, product.id, { image: file.key });   // the record holds the key: you store it
+});
+```
+
+- The bytes are checked like an upload's: the type is read from the content and must fit the field's `accept`, and the size its `maxBytes`. A refusal is an `AdminValidationError` (422) on the field, and nothing is stored. The field must be a `file` or `image` field (not rich text); an unknown resource or field is an error.
+- The object is stored under a new key in the usual format, and the row is `attached` to `recordId` (`RecordId`: a value, or `{ key: value }` for composite keys; for a settings page, `resource: 'page:<name>'` and any `recordId`). `visibility` defaults to the field's.
+- **With `manager`** the row is written in that transaction when `nma_file` is on its DataSource (else at once), and if the transaction rolls back neither the row nor the object is left. Without one, the row is written at once.
+- **It does not write the record.** Store `file.key` in the column yourself, in the same transaction.
+- `release({ resource, field, recordId, key }, manager?)` is for a key the record no longer holds: its row goes, and its object after the transaction commits (at once without one). A key that is not that record's file in that field is left alone: `release` never deletes another record's file.
+
 ### Actions
 
 ```ts
@@ -405,7 +511,7 @@ export class ShopSettingsPage implements AdminSettingsSource<ShopSettingsDto> {
 }
 ```
 
-- **What it is.** One form that is not a table: a provider with `load` and `save`, shown in the sidebar under its module's group (or `group: '<key>'`) at `/p/<name>`. A group may hold only pages. List the class in a module's `providers`.
+- **What it is.** One form that is not a table: a provider with `load` and `save`, shown in the sidebar under its module's group (or `group: '<key>'`) at `/p/<name>`. A group may hold only pages; its label, icon and order come from the module whose `@AdminGroup` has its key, and `order` places a page among the pages of its group (see [Sidebar groups and order](#sidebar-groups-and-order)). List the class in a module's `providers`.
 - **The form** comes from the DTO alone: one field per property with a class-validator decorator. `fields` and `@AdminField` set labels, help, widgets and `showIf`; `layout` works as on resources. `readonly`, `readonlyIf` and `restricted` do not exist on pages.
 - **`load(ctx)`** returns the stored values. Keys that are not form fields are dropped.
 - **`save(changes, ctx)`** gets only the keys that were sent: a save is partial and validated like a PATCH. The UI sends what changed; a group of fields (a nested DTO) is sent whole once one of its fields changed, so `save` can store it under its key.
@@ -416,13 +522,53 @@ export class ShopSettingsPage implements AdminSettingsSource<ShopSettingsDto> {
   - A save replaces it with any non-empty text, clears it with `null` (even when the DTO requires the property), and leaves it alone when the key is absent. An empty string is refused with 422: empty never means "clear".
   - `load` returns the secret like any other value (the admin needs to know whether one is set), and `save` gets the new text or `null`. Encrypt it in `save` if the table is not a safe place for it.
   - Never put a secret into an error message. As a last line of defence the admin replaces the exact values of secrets of 6 or more characters with `***` in errors leaving a save (messages, field errors, the log). That is best effort: shorter and transformed values are not found, and errors thrown by `load` outside a save are logged as thrown.
-- **Files.** File, image and rich-text fields work as on records, with `resource=page:<name>` for uploads. `save` gets an `AdminFile` (store its `key`) or `null`, and `load` returns the key, and `null` once the file was cleared: leaving the key out means "unknown", and the removed file is then kept. List fields (`many`) are not supported on pages.
+- **Files.** File, image and rich-text fields work as on records, with `resource=page:<name>&field=<field>` for uploads; the stored key is `page/<name>/<field>/<yyyy>/<mm>/<uuid><ext>` (see Storage keys under [Files](#files-images-and-rich-text)). `save` gets an `AdminFile` (store its `key`) or `null`, and `load` returns the key, and `null` once the file was cleared: leaving the key out means "unknown", and the removed file is then kept. List fields (`many`) are not supported on pages.
 - **Permissions.** `page.<name>` views the page and `page.<name>.update` saves it; whoever may save may view.
   - `*` and `page.*` grant both codes of every page, and `page.*.update` saves every page. Resource wildcards (`*.view`, `*.update`, `product.*`) never reach a page.
   - Without view, the page is a 404 and absent from the sidebar. With view only, the form is read-only. Viewing as someone is always read-only.
 - **Names.** Letters, digits, `-` and `_`; not the name of a resource, an operation (`view`, `update`, …) or a resource's custom permission. Because page codes start with `page.`, **a resource cannot be named `page` in an admin with settings pages**: boot fails and suggests `@AdminResource(Page, { name: 'content-page' })`.
 - **API.** `GET /api/pages/:name` answers `{ schema, values, secrets, files }`, and `PATCH /api/pages/:name` takes the changed keys and answers the same.
 
+### Inlines
+
+A parent's form can edit its child records (a product's variants, specifications and pictures; an order's lines), and one Save writes the parent and every change to its children in **one transaction**. The child is an ordinary resource, with its own permissions, scopes, fields, DTOs, hooks and service overrides; the parent's layout places it:
+
+```ts
+@AdminResource(OrderLine, { name: 'order-line' })
+export class OrderLineAdmin extends AdminResourceBase<OrderLine> {
+  form: FormConfig = { create: CreateOrderLineDto, update: UpdateOrderLineDto };
+}
+
+@AdminResource(Order)
+export class OrderAdmin extends AdminResourceBase<Order> {
+  form: FormConfig = {
+    create: CreateOrderDto,
+    update: UpdateOrderDto,
+    layout: [
+      { section: { en: 'Order', fa: 'سفارش' }, fields: ['number', 'customer'], columns: 2 },
+      { section: { en: 'Lines', fa: 'ردیف‌ها' }, inline: OrderLineAdmin, display: 'table', fields: ['productId', 'description', 'quantity', 'unitPrice'], order: 'position', min: 1, max: 50 },
+    ],
+  };
+}
+```
+
+- **`inline`**: the child resource class. Its entity needs exactly one many-to-one (or owning one-to-one) relation to the parent's entity: that relation's field is the **link** (`orderId`). With several candidates, name it with `link: 'orderId'`. The server sets the link; a client that sends it is refused (422), and an update cannot change it.
+- **`display`**: `cards` (default; each child is a card with the child's own form layout) or `table` (one row per child, one cell per field: for short rows like order lines; on phones the table scrolls sideways).
+- **`fields`**: which of the child's form fields the inline shows, in order (default: the child's update form fields without the link). Fields it does not show keep their stored values, and their DTO defaults on create.
+- **`order`**: a number field of the child. Rows are read sorted by it (then by key), and dragging or the up/down buttons write 0, 1, 2… into it on save. Without it rows go by key and cannot be reordered.
+- **`min`**, **`max`** (default 100, at most 500): how many rows a save may leave, checked on the server after the changes (422 on the inline). `max` is also how many rows are read: a record with more shows them read-only, with a link to the child's list filtered by the parent.
+- One level only: an inline cannot contain inlines (boot error). A child may be inlined into more than one parent (with different links).
+
+**Permissions.** An inline never widens access: a user reads, adds, changes, removes or reorders a child through an inline only as they could through the child's own resource (`order-line.view`, `.create`, `.update`, `.delete`, its field levels and scopes, each row's `@AdminCan`), and only the children of this parent. A user without `<child>.view` does not see the inline at all; without `<child>.delete` there is no remove button, and a crafted delete is a 403 that saves nothing. Since children are saved with the parent, the save also needs `<parent>.create` (a new parent) or `<parent>.update`. View-as shows inlines read-only, like everything else.
+
+**Saving.** The form sends, next to the parent's fields, `_inlines: { <child>: { create, update, delete, order } }` (`InlineChanges` in the contract): new rows with a `_key`, changed fields of changed rows with their `_id` (and `_version` for a child with a version column), the ids to delete, and the new order. Inside the parent's write the parent is saved first (a save with only inline changes does not update the parent), then each inline in layout order: deletes, updates, creates, each through the child resource's own `delete`/`update`/`create` and its write participants (files, audit). Any error rolls back everything; errors name the row (`_inlines.order-line.create.2.quantity`, `_inlines.order-line.update.17.unitPrice`) and the form shows them on that row. At most 500 entries per inline per request.
+
+**Options that depend on the parent.** A child's `relationOptions(field, qb, ctx, values)` receives `values._parent`: the parent form's values as the user sees them (unsaved, in the picker; body over stored, on save), with `_parent._resource` naming the parent. Use it to narrow a picker to what the parent allows, such as the attributes of the product's category.
+
+**History.** Each child change is the child's own audit entry (`order-line.created`, …) in the child's history, with `meta.parent` naming the parent (for readers who may view the parent's resource). The parent's History tab shows the parent's own entries only.
+
+**Duplicate** copies the parent only, not its children (the copied form says so).
+
 ## Transactions, context and errors
 
 Every create, update and delete runs in one database transaction. Pass `ctx.manager` to your services so their writes
@@ -671,6 +817,41 @@ export class EmployeeAdmin extends AdminResourceBase<Employee> {
   - **Read replicas.** Reads outside a transaction (that check after commit; with `transactions: false` the before and after images too) go through `dataSource.manager`, which TypeORM replication may send to a replica. A lagging replica then still shows a deleted row (no stamp), or shows an update as unchanged (a smaller diff, or no entry).
   - **Scopes that depend on a field.** A record's history is open to whoever may open the record now. A reader whose scope depends on a field (`ownerId`, a status) reads the values the record had before it entered their scope, in the fields they may view.
 
+## Upgrading to 0.3.0
+
+Nothing in 0.3.0 breaks an app that runs on 0.2.1: no option or export was removed or changed, no table or stored key changed, and a resource without inlines answers exactly as before (responses only gain fields). All five packages are 0.3.0; upgrade them together, as before.
+
+**New**
+
+- **Inlines**: child resources edited in the parent's form and saved with it in one transaction. See [Inlines](#inlines).
+- **`AdminFiles.register()` and `release()`**: files a host stored itself become files of a record's field. See "Registering files yourself" under [Files](#files-images-and-rich-text).
+- **A key column named `id` without a label is "شناسه" in Persian** (still "Id" in English).
+
+**What a 0.2.1 app may notice**
+
+- `relationOptions(field, qb, ctx, values)`: a key named `_parent` in `values` now has a meaning when the picker belongs to an inline (`?parent=` on the options route); without `?parent=` it is passed through as before.
+- The UI's lists, sidebar and header: the sidebar and the header stay in place while the page scrolls, and in right-to-left languages table headers start on the right like their cells.
+
+## Upgrading to 0.2.1
+
+Nothing in 0.2.1 breaks an app that runs on 0.2.0: no option or export was removed or changed, no table or stored key changed, and permissions decide as before. All five packages (`@nest-my-admin/core`, `ui`, `auth`, `testing` and `nest-my-admin`) are 0.2.1. Upgrade them together: `@nest-my-admin/auth` and `@nest-my-admin/testing` peer on the exact core version (0.2.1 of either does not install next to core 0.2.0), and core brings the UI of its own version.
+
+**New**
+
+- **`@AdminGroup` by key, for any members.** A module's `@AdminGroup` now configures the group of its key whoever the members are, also when they are only settings pages that say `group: '<key>'`, and also when the module provides nothing. See [Sidebar groups and order](#sidebar-groups-and-order).
+- **`order`** on `@AdminResource` and `@AdminSettingsPage`: the place inside the group (lower first, default 100, then by label).
+- **`AdminFiles`** (`publicFile(key)`, `openPublic(key)`): which keys are public files, for a host that serves them itself. See "Serving public files yourself" under [Files](#files-images-and-rich-text).
+- **The page is in the admin's language**: `GET <path>/` answers `<html lang dir>`, `<title>` and `Content-Language` for the default `locale` and your `title`.
+- **Documented:** the storage key of a settings page's file, `page/<name>/<field>/<yyyy>/<mm>/<uuid><ext>` (unchanged; it was only in the source).
+
+**What a 0.2.0 app may notice**
+
+- **A sidebar group can change its label, icon and place.** In 0.2.0 an `@AdminGroup` was read only when its module provided a resource, or a page without `group`. A group reached only through `group: '<key>'` therefore showed the key as its label ("Settings"), with no icon and order 100, even though a module carried `@AdminGroup({ key: '<key>', … })` (or was named like the key and carried `@AdminGroup` without a `key`). In 0.2.1 that module's label, icon and order apply. Group keys, URLs (`/g/<key>`) and permissions are unchanged. If you worked around it by leaving `group` off some pages, both spellings now give the same group.
+  - A module that carries `@AdminGroup` now also wins over a module without the decorator whose name gives the same key, whichever is imported first (in 0.2.0, the one whose resource was registered first).
+  - Two modules that configure one key differently: the first in import order wins (in 0.2.0, the first that had a resource or a page registered, which is nearly always the same), and 0.2.1 logs a warning at boot that names both.
+- **The served HTML.** `GET <path>/` used to answer `<html lang="en" dir="ltr">` and `<title>Admin</title>` whatever the admin's language. It now answers with the default `locale` (`lang`, `dir`, `Content-Language`) and your `title` in it. The page is still one page for every request (it does not vary by `Accept-Language`, and there is no `Vary` header), and `Cache-Control` is still `no-cache`. An admin with `locale: 'en'` and no `title` gets byte-for-byte what it got before, plus `Content-Language: en`. The UI behaves as before once it runs. If you serve your own UI build (`uiDistPath`), the `lang` and `dir` of its `<html>` and the `<title>` of its `<head>` are replaced the same way.
+- **Boot fails for `order` that is not a finite number** on a resource or a settings page. TypeScript did not accept the option in 0.2.0, so only untyped code that already passed one can be hit.
+
 ## Upgrading to 0.2
 
 **Boot can now fail.** Each of these stops the app at start, with a message that names the class:

package/dist/admin.module.js

@@ -13,6 +13,7 @@ import { AuditReader } from './audit/audit-reader.js';
 import { AdminAudit } from './audit/audit.service.js';
 import { AdminAuthService } from './auth/auth.service.js';
 import { AdminPolicy } from './policy/admin-policy.service.js';
+import { AdminFiles } from './files/admin-files.service.js';
 import { FilesService } from './files/files.service.js';
 import { AdminRbac } from './rbac/rbac.service.js';
 import { AdminHttpServer } from './http/admin-http.server.js';
@@ -33,12 +34,13 @@ let AdminModule = AdminModule_1 = class AdminModule {
                 AdminAudit,
                 AdminRbac,
                 FilesService,
+                AdminFiles,
                 AdminPolicy,
                 AdminApiService,
                 AuditReader,
                 AdminHttpServer,
             ],
-            exports: [ResourceRegistry],
+            exports: [ResourceRegistry, AdminFiles],
         };
     }
 };

package/dist/admin.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"admin.module.js","sourceRoot":"","sources":["../src/admin.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAE,MAAM,EAAsB,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAA2B,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAG5D,IAAM,WAAW,mBAAjB,MAAM,WAAW;IACf,AAAP,MAAM,CAAC,OAAO,CAAC,OAAO,GAAuB,EAAE;QAC7C,OAAO;YACL,MAAM,eAAa;YACnB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,eAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE;gBAClE,gBAAgB;gBAChB,YAAY;gBACZ,gBAAgB;gBAChB,UAAU;gBACV,SAAS;gBACT,YAAY;gBACZ,WAAW;gBACX,eAAe;gBACf,WAAW;gBACX,eAAe;aAChB;YACD,OAAO,EAAE,CAAC,gBAAgB,CAAC;SAC5B,CAAC;IACJ,CAAC;CACF,CAAA;AAtBY,WAAW;IADvB,MAAM,CAAC,EAAE,CAAC;GACE,WAAW,CAsBvB"}
+{"version":3,"file":"admin.module.js","sourceRoot":"","sources":["../src/admin.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAE,MAAM,EAAsB,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAA2B,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAG5D,IAAM,WAAW,mBAAjB,MAAM,WAAW;IACf,AAAP,MAAM,CAAC,OAAO,CAAC,OAAO,GAAuB,EAAE;QAC7C,OAAO;YACL,MAAM,eAAa;YACnB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,eAAe,CAAC;YAC1B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE;gBAClE,gBAAgB;gBAChB,YAAY;gBACZ,gBAAgB;gBAChB,UAAU;gBACV,SAAS;gBACT,YAAY;gBACZ,UAAU;gBACV,WAAW;gBACX,eAAe;gBACf,WAAW;gBACX,eAAe;aAChB;YACD,OAAO,EAAE,CAAC,gBAAgB,EAAE,UAAU,CAAC;SACxC,CAAC;IACJ,CAAC;CACF,CAAA;AAvBY,WAAW;IADvB,MAAM,CAAC,EAAE,CAAC;GACE,WAAW,CAuBvB"}

package/dist/api/admin-api.service.d.ts

@@ -15,6 +15,10 @@ export declare class AdminApiService {
     /** The write transaction and what takes part in every change made inside it: files, then the audit log. */
     private readonly writes;
     constructor(registry: ResourceRegistry, options: ResolvedAdminOptions, policy: AdminPolicy, files: FilesService, pages: PageRegistry, audit: AdminAudit);
+    /** `_inlines` of a POST or PATCH: the children's changes, saved inside the parent's write. */
+    private readonly inlineWriter;
+    /** `_inlines` of a record: its children through each child resource's read path. */
+    private readonly inlines;
     /** Runs `@AdminAction`s; it writes and serializes through this service. */
     private readonly actions;
     /** Settings pages; they save through this service's write transaction. */
@@ -37,12 +41,21 @@ export declare class AdminApiService {
     private records;
     /** One record with every relation field loaded (detail and write responses). */
     private record;
+    /** Records as the detail endpoint answers them, every relation field loaded (in one lookup per field, not per record). */
+    private fullRecords;
     /** One transaction on the target's DataSource with `ctx.manager` set (see `WriteRunner.run`). */
     private write;
     /** One change inside a write, with every participant around the host `method` (see `WriteRunner.change`). */
     private change;
     create(name: string, body: unknown, ctx: AdminContext): Promise<AdminRecord>;
     update(name: string, rawId: string, body: unknown, ctx: AdminContext, version?: number): Promise<AdminRecord>;
+    /**
+     * The parent's own validation and the preparation of its `_inlines` (`InlineWriter.prepare`), with the 422s of both
+     * in one answer. A resource without inlines validates as before. On update, only a body with `_inlines` gets a plan.
+     */
+    private withInlines;
+    /** The answer of a write: the record, and for a parent with inlines its `_inlines` as they are after the save. */
+    private withInlineRows;
     remove(name: string, rawId: string, ctx: AdminContext, version?: number): Promise<void>;
     /**
      * Optimistic concurrency (`If-Match`): inside the write transaction, reads the row, locked on drivers that lock rows
@@ -65,6 +78,13 @@ export declare class AdminApiService {
      * `list.search` fields, else its title column) or `?ids=` (up to 100, to show titles of known ids).
      */
     fieldOptions(name: string, fieldName: string, query: URLSearchParams, ctx: AdminContext): Promise<OptionsResponse>;
+    /**
+     * A child's picker inside a parent's form: `?parent=<parent resource>` and `values._parent` (the parent form's values)
+     * come together. `parent` must inline this resource and be one the user may view; `_parent` reaches relationOptions()
+     * with `_resource` set to it (and keys starting with `_` dropped), as on save. Like the rest of `values`, it can only
+     * narrow the options: the target's query() and scopes are applied before.
+     */
+    private parentValues;
     /**
      * Deletes each record on its own (its own transaction, hooks, `query()` and trash), so one failure never undoes the
      * others. Answers `{ ok, failed }` in request order; failures carry the code and message the single DELETE would.