@antelopejs/interface-dms 0.7.4 → 0.8.0

package/docs/3.base/8.data-types.md

@@ -73,6 +73,7 @@ abstract class DataType {
   filter(context, proxy, key, value, mode, row): ValueProxyOrValue<boolean>;
   filterComponents(): Record<string, ComponentInfoSerialized> & { default: ComponentInfoSerialized };
   inputComponent(): ComponentInfoSerialized;
+  describedInputComponent(): ComponentInfoSerialized;
   decorateField?(target: unknown, key: PropertyKey, descriptor?: PropertyDescriptor): void;
 }
 ```
@@ -85,6 +86,7 @@ abstract class DataType {
 | `defaultInputComponent()` | Abstract. Returns the input component the type renders. Implemented by every concrete type. |
 | `getValidation()` | Abstract. Returns the Zod schema for one value of this type, before the field-level adaptation described in [Forms](/docs/interfaces/base/forms). |
 | `inputComponent()` | The form input. Defaults to `defaultInputComponent()`. |
+| `describedInputComponent()` | The input as it is described where nothing is entered through it: a table column's type (its cells, cards and quick filters read the options) and a read-only form field. Defaults to `inputComponent()`; a type leaves out what only an editable control uses, as a relation leaves out its add form. |
 | `filterComponents()` | The filter inputs, keyed by compare-mode id with a mandatory `default`. Defaults to `{ default: defaultInputComponent() }`. |
 | `filter()` | Applies a filter for one compare mode. The base implementation looks the mode up in the compare-mode registry and delegates to it; a type overrides it when a mode needs different semantics. |
 | `decorateField()` | Optional. Called by the `@Column` decorator so the type can add further decorators to the field — this is how the relation types install their join. |
@@ -207,7 +209,7 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 | `compareModes` | `string[]` | Ids of the type's compare modes; unregistered ones are dropped. |
 | `defaultCompareMode` | `string` | Id of the default mode. |
 | `filterComponents` | `Record<string, FilterComponent>` | Filter inputs by mode id, from `filterComponents()`, with every `noInput` mode's entry replaced by the literal `"noInput"`. |
-| `inputComponent` | `ComponentInfoSerialized` | The form input, from `inputComponent()`. |
+| `inputComponent` | `ComponentInfoSerialized` | The input the column's cells and quick filters read the options of, from `describedInputComponent()`. |
 
 `FilterComponent` is `ComponentInfoSerialized | "noInput"`. The value-level counterpart, `ComponentOrNoInput`, is described in [Shared Types](/docs/interfaces/base/types).
 
@@ -232,7 +234,7 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 | `NotContains` | `not_contains` | value |
 | `ArrayContainsString` | `array_contains_string` | value |
 
-`IsEmpty` and `IsNotEmpty` are the two registered with `noInput`. The namespace also exports `escapeRegex(str: string): string`, the helper the substring modes use to make a viewer-supplied value safe inside a pattern.
+`IsEmpty` and `IsNotEmpty` are the two registered with `noInput`. `Include`, `Exclude` and `ArrayContainsString` read a `null` or missing list as an empty one, so a row saved without a value never fails the query: it is left out by `include` and `array_contains_string`, and kept by `exclude`. The namespace also exports `escapeRegex(str: string): string`, the helper the substring modes use to make a viewer-supplied value safe inside a pattern.
 
 ## The Default Types
 
@@ -264,12 +266,13 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 
 | Options interface | Fields |
 | --- | --- |
-| `StringTypeOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?`, `textarea?`, `rows?`, `fallback?` |
-| `NumberTypeOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `fallback?` |
+| `StringTypeOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?`, `textarea?`, `rows?`, `width?`, `fallback?` |
+| `NumberTypeOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `width?`, `fallback?` |
 | `DateTypeOptions` | `range?`, `multiple?`, `minDate?`, `maxDate?`, `fallback?` |
 | `BooleanTypeOptions` | `fallback?` |
 | `SelectTypeOptions` | `items: FormComponents.SelectOption[]`, `placeholder?`, `multiple?`, `deselectable?`, `display?`, `columns?` (cards per row of the `cards` display, 2 by default), `fallback?` |
-| `EmailTypeOptions`, `ColorTypeOptions`, `UrlTypeOptions`, `RichTextTypeOptions` | `placeholder?`, `fallback?` |
+| `EmailTypeOptions`, `ColorTypeOptions`, `RichTextTypeOptions` | `placeholder?`, `fallback?` |
+| `UrlTypeOptions` | `placeholder?`, `preview?` (`"avatar"` \| `"image"`: shown read-only, the URL is drawn as the image it points to; the form still edits it as text), `fallback?` |
 | `PasswordTypeOptions` | `placeholder?`, `minLength?`, `confirmPassword?`, `confirmPlaceholder?`, `fallback?` |
 | `PhoneTypeOptions` | `placeholder?`, `requiredPrefix?`, `fallback?` |
 | `StringTimeTypeOptions` | `placeholder?`, `min?`, `max?`, `fallback?` |
@@ -279,6 +282,7 @@ Notes on the ones whose behaviour is not obvious from the options:
 - `StringType` renders a textarea instead of a single-line input when `textarea` is set, and passes `rows` to it.
 - `StringType` with `showCount` shows the characters typed, out of `maxLength` when set ("4 / 60"), in its input or under its textarea.
 - `NumberType` hands `suffix` (an i18n key with `$`, or a literal) to its input, which writes it after the field; the value stays a number. `PriceType` inherits it; `PercentageType` keeps its own `%`.
+- `NumberType` (and the types extending it) and a single-line `StringType` hand `width` (`FormComponents.InputWidth`) to their input: `"compact"` sizes it for a short value from `sm` up, `"full"` fills the row, and left out the input is compact when `min` / `max` fit in 6 digits or `maxLength` is 16 or less.
 - `DateType` overrides `filter` so `is`, `is_not` and `is_between` compare whole UTC days rather than instants, and adds a range picker as the filter component for `is_between`. Its schema accepts a `Date` or an ISO-shaped string and transforms it to a `Date`; with `multiple` the value becomes an array, and with `range` it becomes `{ start, end }`, `end` on or after `start` (a pair `[start, end]` is still read and validates to the same object).
 - `BooleanType` uses a two-option select as its filter component, so a viewer picks "checked"/"unchecked" rather than typing a value.
 - `SelectType` validates against the `value`s of its `items`, as an enum or an array of that enum when `multiple` is set.
@@ -317,9 +321,12 @@ declare customerId: string;
 | `deselectable` | `boolean` | Allow clearing the selection. |
 | `filterOnly` | `boolean` | Skip the join entirely: the raw scalar id stays in the list output and the funnel filter runs equality on it. |
 | `addForm` | `{ displayName?: string; description?: string }` | Title and description of the drawer the picker's "add" entry opens ("New customer"). `$`-prefixed: i18n keys. Default to "New entry". |
+| `filterBy` | `{ field, from }` | List only the target rows whose `field` equals the form's current value of the field `from`, e.g. `{ field: "customerId", from: "customerId" }` for a site among its customer's sites. `field` must be filterable on the target (`filterable: true` or `@Filter`); `decorateField` throws otherwise. |
 | `fallback` | `string` | Text used in place of an empty value. |
 
-When the target controller exposes a `new` endpoint and has form fields, the picker also carries an inline "add" form built from the target's `new` fields, plus the permission id of the target's `add` action.
+With `filterBy`, the picker sends the table filter syntax to the `select` endpoint (`filter_<field>=is:<value>`), which honors only the filters the target controller declares. It searches again when `from` changes and clears a pick made for its previous value; the pair a record loaded with is kept, and while `from` is empty every row is offered. It narrows what is offered only: a rule that must hold on save belongs to the module's routes.
+
+When the target controller exposes a `new` endpoint and has form fields, the picker of an editable form field also carries an inline "add" form built from the target's `new` fields, plus the permission id of the target's `add` action. That form is the bulk of the component — the target's fields, its validation schema, its own relations' add forms — so a table column's type, its filter and a read-only field leave it out: they read the related rows through the `select` route, and a filter only picks among them.
 
 `CascaderRelationType<T>` is the same idea for a self-referencing table: the target's `select` endpoint returns a flat list, and the widget rebuilds the tree client-side. Its `keyMapping` is required and adds `parent` — the field pointing at the parent row, which must itself carry `@Select()` — alongside the required `label` and `value`. It adds `maxDepth` and `leafOnly` to the relation options, and supports the same `filterOnly` behaviour. In a table cell it shows the path of the picked node ("Electronics / Audio"); a `multiple` one shows a badge per picked node, named by its own label with its path on hover, and folds those past three into `+N`.
 
@@ -338,7 +345,7 @@ When the target controller exposes a `new` endpoint and has form fields, the pic
 | `addressLine2` | no | Supplementary delivery information. |
 | `countrySubdivision` | no | Region, state or province. |
 
-The type's options are `placeholder` (one string per address component), `autocomplete`, an optional `dataApiController` with a `keyMapping` of `label` / `value` for picking an existing address, and `fallback`. `AddressAutocomplete` configures the geocoder:
+The type's options are `placeholder` (one string per address component), `autocomplete`, `defaultCountry` (the ISO 3166-1 alpha-2 country shown while the address has none and whose places the street suggestions list first, written with the first part typed: an address left empty stays empty), an optional `dataApiController` with a `keyMapping` of `label` / `value` for picking an existing address, and `fallback`. `AddressAutocomplete` configures the geocoder:
 
 | Option | Type | Description |
 | --- | --- | --- |

package/docs/4.notifications/3.sending.md

@@ -33,7 +33,7 @@ A `SendableNotification` is immutable and holds no recipient, so you can build o
 | `toUser` | `(userId: string, options?: SendOptions) => Promise<void>` | Send to one user. |
 | `toUsers` | `(userIds: string[], options?: SendOptions) => Promise<void>` | Send to a list of users. |
 | `toUsersIdempotently` | `(userIds: string[], idempotencyKey: string, options?: SendOptions) => Promise<void>` | Send a durable event once per recipient, including after dismissal. |
-| `toRoles` | `(roleIds: string[], options?: SendOptions) => Promise<void>` | Send to every user holding at least one of the roles. |
+| `toRoles` | `(roleIds: string[], options?: RoleSendOptions) => Promise<void>` | Send to every user holding at least one of the roles, in `options.tenantId` when set. |
 | `broadcast` | `(options?: SendOptions) => Promise<void>` | Send to every user. |
 
 ## Building a Notification
@@ -146,10 +146,10 @@ await shipped.toUsers([ownerId, managerId], { readScope: "shared" });
 `toRoles(roleIds, options?)` resolves the users that hold any of the given roles and sends to them. An empty `roleIds` array sends nothing, and so does a set of roles nobody holds.
 
 ```typescript
-await shipped.toRoles([adminRoleId], { readScope: "shared" });
+await shipped.toRoles([adminRoleId], { readScope: "shared", tenantId });
 ```
 
-Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide; membership is resolved across tenants, so a user holding the role in any tenant is included.
+Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide, and they belong to a tenant. `tenantId` (`RoleSendOptions`) restricts the recipients to that tenant's members; without it, membership is resolved across tenants, so a user holding the role in any tenant is included.
 
 ## Broadcasting
 
@@ -168,6 +168,7 @@ Every dispatch method accepts an optional `SendOptions` object.
 | `readScope` | `ReadScope` (optional) | Read-state grouping for a multi-recipient send. Defaults to `"individual"` — see [Read Scope](/docs/interfaces/notifications/categories-and-subjects#read-scope). |
 | `idempotencyKey` | `string` (optional) | Stable event key, unique across producers: prefix it with your module ID. Reusing it for a recipient preserves the original notification and dismissal state. |
 | `dedupe` | `boolean` (optional) | `false` stores every unkeyed send, even one identical to a notification the recipient got less than 10 seconds earlier. Defaults to `true`; see below. |
+| `tenantId` | `string` (optional, `toRoles` only: `RoleSendOptions`) | Only the members of this tenant holding the roles; every tenant when unset. |
 
 Pick `"shared"` for alerts that only need one person to act on them, and `"individual"` for anything each recipient has to see for themselves.
 

package/docs/5.html-render/1.introduction.md

@@ -255,7 +255,7 @@ Types the `htmlRender` block of the DMS module configuration in `antelope.config
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `renderEndpoint` | `string` | Absolute URL `GenerateHtml` posts to. Default `http://localhost:3001/api/html/render`. |
-| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"` — set a strong value in production. |
+| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"`, which the DMS refuses in production. |
 | `serviceTokenLifetime` | `number` | Lifetime of that service token, in milliseconds. The frontend render server rejects a token valid for more than five minutes. Default `300000` (5 minutes). |
 
 The DMS merges the block you supply over those defaults, so a configuration only needs the keys it changes:
@@ -263,13 +263,12 @@ The DMS merges the block you supply over those defaults, so a configuration only
 ```typescript
 import { defineConfig } from "@antelopejs/interface-core/config";
 
-const renderSecret = process.env.DMS_HTML_RENDER_SECRET;
-if (!renderSecret) {
-  throw new Error("DMS_HTML_RENDER_SECRET is not set");
-}
-
 export default defineConfig({
   name: "acme-admin",
+  // Read at start; a production start without it is refused by the DMS.
+  envOverrides: {
+    DMS_HTML_RENDER_SECRET: "modules.dms.config.htmlRender.serviceSecret",
+  },
   modules: {
     dms: {
       source: {
@@ -280,7 +279,6 @@ export default defineConfig({
       config: {
         htmlRender: {
           renderEndpoint: "https://admin.example.com/api/html/render",
-          serviceSecret: renderSecret,
         },
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Public AntelopeJS interfaces of the DMS: pages, components, permissions, tenancy, auth, notifications and HTML rendering.",
   "keywords": [
     "antelopejs",
@@ -45,7 +45,6 @@
     "knip:all": "knip"
   },
   "dependencies": {
-    "jsonwebtoken": "^9.0.3",
     "randomstring": "^1.3.1",
     "zod": "~3.24.2",
     "zod-to-json-schema": "~3.24.6"
@@ -53,9 +52,8 @@
   "peerDependencies": {
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-auth": ">=0.0.7 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.3.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0"
@@ -63,13 +61,11 @@
   "devDependencies": {
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-auth": ">=0.0.7 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.3.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
-    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^24.0.0",
     "@types/randomstring": "^1.3.0",
     "knip": "^6.34.0",