@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.6

package/dist/esm/core/resources/resources.frontend.schemas.d.ts

@@ -1,11 +1,13 @@
+import type { AutoEmptyValue, LabellingTypes } from '@wildo-ai/presets-components-models';
 import type React from 'react';
 import { z } from "zod";
-import type { EnumLikeType, IconLike, AutosaveFieldParams, ValidationMode, ResponsiveAware, EditChromeMode, DisplayChromeMode, DraftableConfigParams } from '@wildo-ai/zod-decorators';
+import type { EnumLikeType, IconLike, AutosaveFieldParams, ValidationMode, ResponsiveAware, EditChromeMode, DisplayChromeMode, DraftableConfigParams, ContainerSectionMode } from '@wildo-ai/zod-decorators';
 import type { ButtonVariants_Variant } from '../../components/actions/button';
 import type { QuickSwitcherScopeField } from '../../core/config/app-configuration-frontend.schemas';
-import { ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationship, ResourceTranspositionPolicy, CoreResourceOperation, ResourceOperationDisplayMode, ResourceOperationFrontendSurface, ResourceFieldIdentifier, ResourceType, ResourceConfiguration_Operation_ApiCall, ResourceConfiguration_Operation_ApiCallWithCallback, ResourceConfiguration_ResourceRelationships, ResourceConfiguration_InheritanceSchemaDefinition, TourStepPlacement, NavigationZoneName, OverlayAppearance, SplitAppearance, ZoneEmptyBehavior } from '@wildo-ai/saas-models';
+import { ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationship, ResourceTranspositionPolicy, CoreResourceOperation, ResourceOperationDisplayMode, ResourceOperationFrontendSurface, ResourceFieldIdentifier, ResourceType, ResourceConfiguration_Operation_ApiCall, ResourceConfiguration_Operation_ApiCallWithCallback, ResourceConfiguration_ResourceRelationships, ResourceConfiguration_InheritanceSchemaDefinition, TourStepPlacement, NavigationZoneName, OverlayAppearance, ZoneEmptyBehavior } from '@wildo-ai/saas-models';
 import type { ResourceConfiguration, ResourceConfiguration_InitializationFactory, ValidOperationKeys, RelationshipDisplayInParentNavigation, RelationshipDisplayInChildView } from '@wildo-ai/saas-models';
 import type { InsertedChartDeclaration } from '../../core/config/chart-view.frontend.schemas';
+import type { ExternalDataPipelineDeclaration } from '@wildo-ai/saas-models/external-data';
 import type { InsertedExecutionDeclaration, ResourceExecutionViewsConfig } from '../../core/config/execution-view.schemas';
 import type { OnboardingElementType, GuidanceRenderMode, GuidanceFlowScope, GuidanceAudience, NotificationBadgeDefinition, UserNotificationDefinition, SubtreeMap, ManyToManyScopeJunctionMap } from '@wildo-ai/saas-models';
 import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
@@ -15,7 +17,7 @@ import type { InsertedCompositeDeclaration, ResourceCompositeViewAuthoringConfig
 /**
  * @wildo_source:part:start saas.frontend.navigation.operation-override facet:layer:frontend facet:family:navigation-config
  *
- * Per-operation navigation chrome: transition, overlay/split appearance, source zone.
+ * Per-operation navigation chrome: transition, overlay appearance, source zone.
  *
  * **How to use:** attach fragments of this shape under
  * `ResourceOperationFrontendConfig.navigationOverrides` in `resourceUIBehavior()`.
@@ -29,7 +31,7 @@ export declare const NavigationOperationOverrideSchema: z.ZodObject<{
         persistent: z.ZodOptional<z.ZodBoolean>;
         ephemeral: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>]>;
-    appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>]>>;
+    appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
     fromZone: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"appLevel">]>>;
     viewport: z.ZodOptional<z.ZodEnum<typeof ViewportBreakpoint>>;
     overlayBehavior: z.ZodOptional<z.ZodObject<{
@@ -54,6 +56,7 @@ export interface AppScopeFieldDefinition extends QuickSwitcherScopeField {
     resourcePrimaryScope: ResourcePrimaryScope;
 }
 import type { FrontendResourceOperationPath, FrontendResource_ParentResourceRequirement } from './resource-path.frontend.schemas';
+import { UpdateLikeMutationFallbackMode } from '../../core/resources/rmm/update-like-mutation-fallback.frontend';
 /**
  * Resolved operation row the **frontend registry** stores: same structural operation
  * config as `@wildo-ai/saas-models` (API_CALL / callback variants) plus optional
@@ -109,6 +112,14 @@ export type FrontendResourceConfiguration<TCustomOperationEnum extends EnumLikeT
     primaryKeyIdentifiesInitiator: boolean;
     isAnonymizable: boolean;
     transpositionPolicy: ResourceTranspositionPolicy;
+    /**
+     * Mirrors `ResourceConfiguration.externalDataPipeline` (#1997): present on a resource an external-data pipeline
+     * fills from a system of record. Always populated at runtime for such a resource, because
+     * `buildFrontendResourceConfigurations` spreads the backend config onto every registry entry; declared here so the
+     * display pipeline can read it typed — to know which fields the pipeline writes (the provenance cue) — rather than
+     * through a cast. Read-only: the frontend never runs a pipeline.
+     */
+    externalDataPipeline?: ExternalDataPipelineDeclaration;
     operations: FrontendResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>[];
 };
 export type AnyFrontendResourceConfiguration = FrontendResourceConfiguration<any, any, any>;
@@ -164,6 +175,16 @@ export interface FrontendResourceOperationContext extends FrontendResourceOperat
     }>;
     /** Additional context data that can be passed */
     additionalContext?: Record<string, unknown>;
+    /**
+     * Filters the HOST fixes for a collection it embeds — values the reader can neither see nor change (#1630).
+     *
+     * A record's page that embeds another resource's LIST narrowed to that record ("the conversations linked to
+     * this matter") needs a filter that is not a route parameter and not the reader's choice. Every key must be a
+     * `filterFields` key of the operation, so the backend applies it exactly as a reader's filter; it is sent on
+     * every fetch (it wins over a reader's value for the same key) and its fields are left out of the filter panel.
+     * Absent for a collection the reader filters freely.
+     */
+    pinnedFilters?: Readonly<Record<string, string>>;
     /** Parent resource requirements - explicitly included from FrontendResourceOperationPath */
     parentResourcesRequirements: FrontendResource_ParentResourceRequirement[];
 }
@@ -192,6 +213,7 @@ export declare const FrontendResourceOperationContextSchema: z.ZodObject<{
         resourceId: z.ZodString;
     }, z.core.$strip>]>>;
     additionalContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    pinnedFilters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 /**
  * Frontend-native resource configuration types.
@@ -226,13 +248,12 @@ export declare enum ResourceFrontend_GuidanceFlowTriggerType {
 }
 /**
  * Empty state configuration for list/table views when no items exist.
- * Labels (title, description, primaryActionLabel) come from i18n.
+ * Labels (title, description) come from i18n; the primary action is the CREATE operation and takes its title.
  *
  * @example
  * ```
  * emptyState: {
  *   icon: 'inbox',
- *   primaryAction: CoreResourceOperation.CREATE,
  *   secondaryAction: { type: ResourceFrontend_EmptyStateSecondaryActionType.LINK, target: 'https://docs.example.com/projects' },
  * }
  * ```
@@ -241,11 +262,14 @@ export interface ResourceUIBehavior_EmptyState {
     /** Icon ref from the icon registry. If not provided, uses a default empty-state icon. */
     icon?: string;
     /**
-     * Operation ref for the primary CTA (e.g., `CoreResourceOperation.CREATE`).
-     * If not provided, auto-detects CREATE from available operations.
-     * Set to `false` to explicitly disable the primary action button.
+     * The empty state's primary action is always the collection's CREATE, offered whenever the caller can create,
+     * and named by that operation's title. `false` opts out, for a collection that is populated for the person
+     * rather than by them.
+     *
+     * Only `false` is accepted: this used to take an operation ref, and every value other than `false` was
+     * ignored, so `primaryAction: CoreResourceOperation.UPDATE` read like a decision and changed nothing.
      */
-    primaryAction?: string | false;
+    primaryAction?: false;
     /** Secondary action — link to docs, guidance flow, or external URL. */
     secondaryAction?: {
         type: ResourceFrontend_EmptyStateSecondaryActionType;
@@ -352,6 +376,110 @@ export declare enum CollectionDisplayMode {
     /** Dense table — one column per summary field via the table body. */
     TABLE = "table"
 }
+/**
+ * Whether a collection's toolbar OFFERS the free-form filters panel (the "Filters" trigger and the
+ * panel it opens), authored on a LIST operation's `collectionDisplayConfig.filterPanel`.
+ *
+ * ## Why this exists
+ *
+ * A collection whose useful narrowings are already one click away — a `quickFilterField` tab strip,
+ * a row of `presetFilters` pills — often has no need for the general-purpose panel beside them, and
+ * a third way to write the same filter state is clutter in the action lane. This lets the author say
+ * so, without giving up the backend's `filterFields` (the tabs and pills write into exactly those).
+ *
+ * ## What HIDDEN does NOT hide
+ *
+ * The active-filter CHIPS stay. They are the readout of what is currently narrowing the list and the
+ * only way to clear a value that arrived by another door (a deep link, a restored view). Hiding them
+ * with the trigger would let a filter be active and invisible — a list that silently shows less than
+ * it says. The quick-filter tabs and the preset pills are unaffected: they are their own surfaces.
+ */
+export declare enum CollectionFilterPanelVisibility {
+    /** The "Filters" trigger and its panel are offered whenever the operation has filter fields. The default. */
+    OFFERED = "offered",
+    /** No trigger and no panel — narrowing happens through the tabs and pills only; the chips remain. */
+    HIDDEN = "hidden"
+}
+/**
+ * A DATE WINDOW named relative to NOW, for a preset filter that must mean the same thing tomorrow.
+ *
+ * A preset is authored once and clicked forever, so "created today" cannot be an authored pair of
+ * instants — it has to be RESOLVED at the moment it is applied. The vocabulary is closed and small
+ * on purpose: each member is a window a person actually asks for, and each resolves to the
+ * `{ startDate, endDate }` pair the framework's date-range filter already carries end to end, so a
+ * preset needs no filter grammar of its own and no backend change.
+ *
+ * Resolution is in the VIEWER's timezone, which is the only one that makes "today" true for the
+ * person reading the screen. The backend compares instants, so the boundaries travel as absolute
+ * times and nothing downstream has to know a timezone was involved.
+ */
+export declare enum CollectionFilterPresetRelativeRange {
+    /** Midnight this morning until midnight tonight, local. */
+    TODAY = "today",
+    /** The same window, one day back. */
+    YESTERDAY = "yesterday",
+    /** The last seven days INCLUDING today — the rolling week, not the last seven whole days. */
+    LAST_7_DAYS = "last_7_days",
+    /** The last thirty days including today. */
+    LAST_30_DAYS = "last_30_days",
+    /** The first of this calendar month until now. */
+    THIS_MONTH = "this_month",
+    /** The first of this calendar year until now. */
+    THIS_YEAR = "this_year"
+}
+/**
+ * What a preset ASSIGNS to one filter field.
+ *
+ * Two members, and the split is between a value that is FIXED at authoring time and one that can
+ * only be known when the pill is clicked. A literal covers every enum value, id, number and flag —
+ * which is the whole of "filter to HIGH priority". A relative range covers the temporal case, whose
+ * defining property is that an authored answer would be wrong by tomorrow.
+ *
+ * A NUMERIC BOUND is the third, and it is the one that needed the rest of the stack before it could
+ * mean anything: the framework's collection filters carried a date range and scalars and no numeric
+ * range, so a preset could have declared "cost below 500" and nothing between here and the database
+ * would have honoured it. It is expressible now because `Resources_Filter_NumberRangeSchema`, the
+ * controller's fail-closed value guard and the cross-adapter normalizer all learned the `{ min, max }`
+ * vocabulary — a preset assigning one is writing the same value the filter panel's own two inputs do.
+ *
+ * Both bounds optional, for the same reason the schema has them optional: "under 500" is a range
+ * with no floor, and that is the commonest threshold anyone asks for.
+ */
+export declare const CollectionFilterPresetValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+    relativeRange: z.ZodEnum<typeof CollectionFilterPresetRelativeRange>;
+}, z.core.$strip>, z.ZodObject<{
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+export type CollectionFilterPresetValue = z.infer<typeof CollectionFilterPresetValueSchema>;
+/**
+ * ONE named, one-click narrowing of a collection, rendered as a toggleable pill above the list.
+ *
+ * ## Why this is not `quickFilterField`
+ *
+ * They answer different questions and both are worth having. A quick-filter field promotes ONE enum
+ * and spends every one of its values on a TAB STRIP: the tabs are mutually exclusive and they read
+ * as "which slice of this collection am I looking at". A preset is ADDITIVE and crosses fields —
+ * "high priority", "created today", "unassigned" — and several can be on at once. Collapsing them
+ * would cost one of the two meanings.
+ *
+ * ## No state of its own
+ *
+ * A preset is a WRITE into the collection's existing filter values, and its ON/OFF is DERIVED by
+ * reading them back: it is active exactly when every key it assigns currently holds its value. So
+ * clearing a chip, editing the panel, or applying a second preset that touches the same field all
+ * update the pills for free, and there is no second copy of the filter state to keep in step.
+ */
+export declare const CollectionFilterPresetSchema: z.ZodObject<{
+    ref: z.ZodString;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+        relativeRange: z.ZodEnum<typeof CollectionFilterPresetRelativeRange>;
+    }, z.core.$strip>, z.ZodObject<{
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export type CollectionFilterPreset = z.infer<typeof CollectionFilterPresetSchema>;
 /**
  * How CARDS-mode items are arranged. Orthogonal to {@link CollectionDisplayMode}
  * (this only shapes the CARDS body; TABLE ignores it). LIST and GRID are kept as
@@ -483,8 +611,8 @@ export declare enum ActionPlacement {
  *
  * `MODAL` and `PAGE` do not render anything themselves — they resolve to the navigation transitions
  * that already exist (`OVERLAY`, and the ordinary chain), so there is one runtime mechanism and one
- * set of zone/appearance/URL semantics. `DIRECT`, `POPOVER` and `INLINE` never enter navigation at
- * all, because none of them is a destination: nothing is pushed, no zone changes, and there is
+ * set of zone/appearance/URL semantics. `DIRECT`, `POPOVER`, `DROPDOWN` and `INLINE` never enter
+ * navigation at all, because none of them is a destination: nothing is pushed, no zone changes, and there is
  * nothing for a back button to pop. `INLINE` is hosted by the collection the element belongs to —
  * see `InPlaceOperationContext` for why that is not the navigation layer's job.
  *
@@ -496,7 +624,8 @@ export declare enum ActionPlacement {
  * ## When omitted
  *
  * It is DERIVED from the operation — see `resolveResourceOperationActionPresentation()`. An
- * operation that asks for nothing executes directly; a small field set opens a modal; input the
+ * operation that asks for nothing executes directly; one choice from an enum or a reference is a
+ * DROPDOWN; one or two simple fields open an anchored POPOVER; a small field set opens a modal; input the
  * framework cannot fit in an overlay (files, nested writes, a large field set) keeps the page it
  * has always had. An operation whose `surface` is `ADDRESSABLE` always keeps its page: the author
  * has already said it is a deep-linkable destination.
@@ -515,11 +644,35 @@ export declare enum ResourceOperationActionPresentation {
     /**
      * A small form anchored to the button that opened it, dismissed by clicking away.
      *
-     * The single-input idiom ("assign to…", "snooze until…"). Transient by construction: no URL, no
+     * The small-input idiom ("snooze until…", "reject with a reason…" — a ONE-CHOICE input such as
+     * "assign to…" is a {@link DROPDOWN}). Transient by construction: no URL, no
      * history entry, nothing to deep-link. Use it when the surrounding context is the point — the user
      * is reading the row they are acting on and must not lose sight of it.
      */
     POPOVER = "popover",
+    /**
+     * A list of the operation's admissible VALUES, anchored to the button; picking one executes the
+     * operation with it. No form, no Submit — the pick IS the submission.
+     *
+     * The "Status ▾" / "Assign ▾" idiom: an operation whose whole input is ONE choice from an
+     * enumerable domain. Two domains qualify, and each renders the list it deserves:
+     * - an ENUM field — its values, labelled exactly as the form would label them;
+     * - a REFERENCE (a foreign-key field) — a SEARCHABLE list of the referenced records, queried
+     *   server-side as you type, scoped exactly like the form's reference picker.
+     *
+     * Transient like {@link POPOVER}, and it shares the popover's host and degrades: collapsed into
+     * the overflow menu or a subgroup — where nothing can anchor — it opens as an overlay form.
+     *
+     * **It cannot be a deliberate act.** A pick that executes has no second step, so an operation
+     * whose risk level asks for a confirmation (HIGH / CRITICAL), a BULK operation (one pick would
+     * rewrite every selected row), or one whose input is not one choice field, resolves to
+     * {@link POPOVER} instead even when this is authored: a panel holding the same control plus an
+     * explicit Submit. See `resolveResourceOperationActionPresentation`.
+     *
+     * Not to be confused with `ActionLabelDisplayMode.DROPDOWN`, which is about the BAR — whether its
+     * actions collapse into an overflow menu. This is about one action's INPUT.
+     */
+    DROPDOWN = "dropdown",
     /**
      * The element being acted on transforms in place to collect the input, leaving its neighbours
      * visible — the row becomes the form rather than being covered by one.
@@ -618,9 +771,9 @@ export interface ResourceActionDisclosureConfig {
     maxPrimaryActions?: number;
     /**
      * Default handling for actions disabled by an unmet `enabledCondition` — see
-     * {@link DisabledActionHandling}. Omitted inherits the framework default,
-     * which is `HIDE` for both views (set `SHOW_DISABLED` here to keep disabled
-     * actions greyed-but-present for a view).
+     * {@link DisabledActionHandling}. Omitted inherits the framework default:
+     * `HIDE` on SUMMARY rows, `SHOW_DISABLED` on DETAIL (where each unavailable
+     * action explains why it cannot run).
      */
     disabledActionHandling?: DisabledActionHandling;
 }
@@ -631,13 +784,19 @@ export interface ResolvedActionDisclosure {
     disabledActionHandling: DisabledActionHandling;
 }
 /**
- * Framework defaults per view. Both views HIDE actions disabled by an unmet
- * `enabledCondition` — an inapplicable, greyed button is noise everywhere, so
- * the bar only ever shows actions the user can actually take right now. They
- * differ on the overflow cap: SUMMARY (dense list/table rows) shows at most 3
- * direct actions before the `…` menu; DETAIL (roomy read view) is uncapped.
- * A resource that WANTS the informative greyed-with-reason affordance opts into
- * `SHOW_DISABLED` per view via `layout.actionDisclosure`.
+ * Framework defaults per view.
+ *
+ * - SUMMARY (dense list/table rows) HIDES actions an unmet `enabledCondition`
+ *   disables and caps direct actions at 3 before the `…` menu: on a row, a greyed
+ *   button is noise repeated N times.
+ * - DETAIL (the read view and the bulk bar) SHOWS them, uncapped. Both views used
+ *   to hide, on the reasoning that "an inapplicable, greyed button is noise" — true
+ *   of a greyed button that explained nothing. An unavailable action now opens its
+ *   reason (and, for a bulk selection, offers to keep only the eligible rows), so on
+ *   the surface where someone is deciding what to do, hiding it would hide the
+ *   answer to "why can't I?".
+ *
+ * A resource overrides either view via `layout.actionDisclosure`.
  */
 export declare const DEFAULT_ACTION_DISCLOSURE: Record<ResourceOperationDisplayMode, ResolvedActionDisclosure>;
 /**
@@ -687,6 +846,7 @@ export declare const ResourceOperationFrontendConfigSchema: z.ZodObject<{
     actionVariant: z.ZodOptional<z.ZodAny>;
     actionScope: z.ZodOptional<z.ZodEnum<typeof ResourceOperationActionScope>>;
     rowTargetRequestField: z.ZodOptional<z.ZodString>;
+    updateLikeMutationFallbackMode: z.ZodOptional<z.ZodEnum<typeof UpdateLikeMutationFallbackMode>>;
     actionPresentation: z.ZodOptional<z.ZodEnum<typeof ResourceOperationActionPresentation>>;
     customView: z.ZodOptional<z.ZodAny>;
     displayPresetOverride: z.ZodOptional<z.ZodObject<{
@@ -698,7 +858,7 @@ export declare const ResourceOperationFrontendConfigSchema: z.ZodObject<{
             persistent: z.ZodOptional<z.ZodBoolean>;
             ephemeral: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>]>;
-        appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodEnum<typeof SplitAppearance>]>>]>>;
+        appearance: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof OverlayAppearance>, z.ZodRecord<z.ZodEnum<typeof ViewportBreakpoint> & z.core.$partial, z.ZodEnum<typeof OverlayAppearance>>]>>;
         fromZone: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof NavigationZoneName>, z.ZodLiteral<"appLevel">]>>;
         viewport: z.ZodOptional<z.ZodEnum<typeof ViewportBreakpoint>>;
         overlayBehavior: z.ZodOptional<z.ZodObject<{
@@ -713,6 +873,16 @@ export declare const ResourceOperationFrontendConfigSchema: z.ZodObject<{
         displayMode: z.ZodOptional<z.ZodEnum<typeof CollectionDisplayMode>>;
         userSwitchableDisplayMode: z.ZodOptional<z.ZodBoolean>;
         quickFilterField: z.ZodOptional<z.ZodString>;
+        presetFilters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            ref: z.ZodString;
+            filters: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+                relativeRange: z.ZodEnum<typeof CollectionFilterPresetRelativeRange>;
+            }, z.core.$strip>, z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>>>;
+        filterPanel: z.ZodOptional<z.ZodEnum<typeof CollectionFilterPanelVisibility>>;
         temporalGroupField: z.ZodOptional<z.ZodString>;
         enumGroupField: z.ZodOptional<z.ZodString>;
         cardLayout: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -805,6 +975,23 @@ export type ResourceUIBehaviorLabelParams<TMainSchema extends z.ZodTypeAny = z.Z
     objectContext: any;
     initiatorUserContext?: any;
     t: (toTranslate: string, params?: Record<string, any>) => string;
+    /**
+     * Formats a date the way the viewer's regional preferences (date format, timezone) render one everywhere
+     * else. A label built from a date must use it: a hand-formatted `YYYY-MM-DD` agreed with the record's own
+     * card only for a viewer whose preference happened to be ISO, and a different timezone could shift the day.
+     */
+    formatDate: (value: Date | string | number) => string;
+    /**
+     * `formatDate` with the time of day, for a record whose name is an instant rather than a day — an audit
+     * event, where many share a date and only the time tells them apart.
+     */
+    formatDateTime: (value: Date | string | number) => string;
+    /**
+     * The resource being named. One polymorphic behavior serves several resource types (an organization's and a
+     * user's billing account share one callback), and a record with no name of its own is named by ITS resource's
+     * words — which only the resource type can address in the label tree.
+     */
+    resourceType: string;
 };
 /** @wildo_source:part:start saas.frontend.resource-layout-templates facet:layer:frontend facet:family:resource-ui */
 /**
@@ -853,6 +1040,49 @@ export type LayoutTemplate = React.ComponentType;
  * companion validation. Omit `edit` / `display` / `summary` individually to keep the
  * auto-generated default for that context only.
  */
+/**
+ * How a layout decides which of its fields may be edited IN PLACE on the READ surface.
+ *
+ * ## Why this is a layout decision and not only a per-field one
+ *
+ * Inline edit was per-field only: a field became editable in place by declaring
+ * `{primitive}UI.display.inlineEditable`. That is right for an ordinary resource, where editing a
+ * row is an occasional act and a READ page is mostly for reading.
+ *
+ * It is the wrong default for a SETTINGS layout, and the Settings hub measured the cost. A settings
+ * pane is a list of DECISIONS an operator came to take, so a read-only rendering of a policy is not
+ * a conservative choice — it is a pane that cannot do its job. Measured 2026-09-19 on the running
+ * dogfood application: `organizationSsoConfig` declares 24 fields across seven sections, including
+ * `enforcement.requireSSO` and `enforcement.allowPasswordFallback`, and NOT ONE declared
+ * `inlineEditable`. Every boolean therefore rendered through `BooleanDisplayMode.CHECKMARK` — a
+ * read-only ✓ or ✕ glyph, where ✕ is also indistinguishable from a remove affordance — and the only
+ * way to change a policy was a pencil that flipped the entire pane into a form.
+ *
+ * The per-field remedy is to write `.inlineEditable()` on all 24, and on every field added to any
+ * settings schema afterwards. That is a hand-kept list of somebody else's population: correct on the
+ * day it is written and silently incomplete forever after, because nothing goes red when the
+ * twenty-fifth field is added without it.
+ *
+ * So the layout — which already knows it is a settings surface, because it sets
+ * `defaultChromeMode: { display: SETTINGS_ROW }` — declares it once, and the set is DERIVED over
+ * the layout's fields rather than enumerated.
+ */
+export declare enum ResourceLayoutInlineEditDefault {
+    /**
+     * No default. Only a field carrying `{primitive}UI.display.inlineEditable` is editable in place.
+     * This is the system default and the correct choice for an ordinary resource READ page.
+     */
+    NONE = "none",
+    /**
+     * Every WRITABLE field in this layout is editable in place, unless it declines.
+     *
+     * Eligibility is `isEligibleForLayoutDefaultInlineEdit` in `@wildo-ai/zod-decorators` — not the
+     * primary key, not `.excludeFromUpdate()`, not `.isHidden()`, and not an explicit
+     * `inlineEditable: false`. A field declaring `inlineEditable` with PARAMS still wins: the default
+     * decides WHETHER, the decorator decides HOW.
+     */
+    WRITABLE_FIELDS = "writable-fields"
+}
 export interface ResourceLayoutConfig {
     /**
      * Companion-readable manifest of all structural names used in templates.
@@ -860,6 +1090,84 @@ export interface ResourceLayoutConfig {
      * Dev-time validation cross-checks manifest names against template `name` props.
      */
     refs?: LayoutRefManifest;
+    /**
+     * Whether this layout's READ surface offers its writable fields for in-place editing without
+     * each one declaring `inlineEditable` for itself. See {@link ResourceLayoutInlineEditDefault}.
+     *
+     * Renderers read:
+     * `{primitive}UI.display.inlineEditable ?? (layout.defaultInlineEdit === WRITABLE_FIELDS && eligible)`
+     *
+     * Defaults to {@link ResourceLayoutInlineEditDefault.NONE}, so no existing resource changes
+     * behaviour by this field being added. Turning it on is the settings-surface opt-in, and it pairs
+     * with `defaultChromeMode.display: SETTINGS_ROW` — the row geometry that gives the control
+     * somewhere to sit.
+     *
+     * **This does not bypass authorization.** `canInlineEdit` on the display context still requires a
+     * usable UPDATE path (an RMM, an `onInlineEdit`, or a real UPDATE operation the caller may
+     * perform), so a layout that turns this on for a reader who cannot write still renders read-only.
+     */
+    defaultInlineEdit?: ResourceLayoutInlineEditDefault;
+    /**
+     * How an EMPTY field renders on this layout's read surface, overriding the surface policy.
+     *
+     * ## Why a layout may outrank the surface here
+     *
+     * `AutoEmptyValue` is declared per SURFACE VARIANT — BASE, RAISED, OVERLAY and INSET all default
+     * to `em-dash`. That is a sensible default for a surface, which knows nothing about the fields it
+     * happens to contain: in a dense table or a summary card a dash is exactly right, because the
+     * reader is scanning and the row's meaning comes from its neighbours.
+     *
+     * A settings pane is the opposite case. Its rows ARE the content, an operator reads one at a time
+     * to decide something, and an em dash there is an answer that refuses to say which of four things
+     * it means — a field awaiting their input, a list with no members, or a computed value nothing has
+     * produced yet (see `DisplayEmptyReason`). `placeholder` renders the reason's own words instead:
+     * "No value", "None yet", "Not available".
+     *
+     * Declared on the LAYOUT because that is the thing that knows it is a settings surface — it is
+     * already saying so with `defaultChromeMode.display: SETTINGS_ROW` and `defaultInlineEdit` — and
+     * because a per-field declaration would be a hand-kept list that goes silently incomplete the
+     * first time a field is added without it.
+     *
+     * ## What it costs, stated plainly
+     *
+     * It outranks the resolved surface policy, and this seam cannot distinguish a variant's DEFAULT
+     * from a deliberate per-surface `policyOverride` — both arrive as the same resolved value. So a
+     * layout that sets this wins over both. That is what a settings layout wants and it is why the
+     * field exists; a layout with no opinion omits it and every surface keeps its own policy exactly
+     * as before.
+     */
+    defaultEmptyValue?: AutoEmptyValue;
+    /**
+     * The container mode this layout's DISPLAY sections adopt when they declare none of their own.
+     *
+     * ## What it is for
+     *
+     * A section's `appearance` is a per-section prop, and the container modes — `VERTICAL_TABS`,
+     * `TABS`, `ACCORDION`, `GRID` — are not really per-section decisions at all. Grouping keys on
+     * `(mode, its mode-specific props)` over CONSECUTIVE siblings, so a set of sections becomes one
+     * container only when every member declares the same mode with the same props and nothing
+     * separates them. Declared per section that is an agreement N authors must keep; one that slips
+     * does not fail, it silently renders TWO rails, or one rail and a stray bare section.
+     *
+     * So the declaration belongs where the decision does: the layout knows it is a settings pane with
+     * seven groups of fields, and says it once. A section that declares its own `appearance` still
+     * wins — this is the fallback, not an override.
+     *
+     * ## Why DISPLAY only, in the name
+     *
+     * `defaultChromeMode` carries display / summary / edit keys, and a bare `defaultSectionAppearance`
+     * would read as covering the same three while covering one. An edit form's section grouping is a
+     * different question — a wizard's steps, a form's save boundaries — and nothing asks for it yet.
+     * The name says which surface it governs so the answer is not assumed.
+     *
+     * ## It also decides how much ROOM the pane is given
+     *
+     * A navigation container mode puts a second vertical rail inside the pane, and the Settings Hub
+     * reads this to widen its frame accordingly — see `settingsSectionNeedsWideFrame`. That is the
+     * reason this is a layout DECLARATION rather than seven JSX props: a prop inside a template is
+     * invisible to anything that has to size the surface around it.
+     */
+    defaultDisplaySectionAppearance?: ContainerSectionMode;
     /**
      * Default chrome mode for fields in each context.
      * Used when a field's `{primitive}UI.{context}.chromeMode` is not set.
@@ -897,7 +1205,7 @@ export interface ResourceLayoutConfig {
      * greyed (`disabledActionHandling`), keyed by {@link ResourceOperationDisplayMode}.
      * Omit a view (or a field) to inherit the framework default
      * ({@link DEFAULT_ACTION_DISCLOSURE}): SUMMARY = { max 3, hide-disabled },
-     * DETAIL = { unlimited, hide-disabled }.
+     * DETAIL = { unlimited, show-disabled — each explains why it cannot run }.
      *
      * @example
      * // A busy list keeps just one action inline; the detail view spells them all out.
@@ -911,6 +1219,15 @@ export interface ResourceLayoutConfig {
      * The component is instantiated as `<EditTemplate />` and has access to
      * `useFormTemplateContext()` for labels/schema/operation and `useWatch()` for reactivity.
      * For operation-specific branching, read `operationType` from `FormTemplateContext`.
+     *
+     * Which forms use it: the core create and edit forms, and a custom operation whose request is made of
+     * this resource's own fields (a `change_status` posting `status` is laid out by the template, with the
+     * template's control for that field). A custom operation whose request carries a field the resource
+     * does not have gets the form generated from its request instead, because no slot here could place
+     * that field; and a request field of a custom operation that this template has no slot for is appended
+     * after it. Place slots unconditionally and let the operation's schema decide: a slot whose field the
+     * operation lacks renders nothing, and a section left with nothing to show hides (see `Section`, and
+     * `FormLayout` for grouped sections).
      * Standard `<FormField name="...">` slots automatically honor upstream
      * generated replacements (for example relationship-backed fields reshaped by
      * `ResourceAutomatedForm`). When a generated override exists, that replacement
@@ -1149,6 +1466,29 @@ export type ResourceUIBehaviorConfig<TCustomOp extends EnumLikeType | undefined
      * Used by `ResourceListItemRenderer` (rows) and `ResourceLayout_Header` (titles).
      */
     getFrontendResourceLabel?: string[] | ((params: ResourceUIBehaviorLabelParams<TMainSchema>) => string);
+    /**
+     * The label SECTIONS `getFrontendResourceLabel` reads beyond this resource's own `resources.<type>` words (#1851).
+     *
+     * A record is named by its own words when its name is a catalogue key the application words elsewhere: a billing
+     * product is named `billing_products.<key>.name`, a credit pool `billing_credit_pools.<poolKey>.name`. Those
+     * sections are loaded on demand, and the callers that compute a record's name — list rows, the page header, the
+     * breadcrumb, the command menu, reference pickers — each request only the words of the resource on screen, so a
+     * name read from another section rendered its key everywhere.
+     *
+     * Declared here, the section is requested ONCE, when the registry loads (`ResourceRegistryProvider`), so no caller
+     * has to know this resource needs it. Loading at the registry rather than per caller was chosen because the name
+     * is computed in a dozen places and a caller added later would be the one that forgets; the cost is one small
+     * bundle per declared section at start-up, only for the resources that declare one.
+     *
+     * The request is not a readiness gate. A name computed before the words arrive shows the key, and the surfaces
+     * that name a record while rendering (list rows, the header, the breadcrumb, a reference field) show the word
+     * once it loads. The command menu names its search results when it fetches them, so a search run in that first
+     * moment shows keys until the next search.
+     *
+     * Name only what the label callback actually reads; an undeclared read still resolves wherever that section
+     * happens to be loaded, and renders its key (a missing label that looks missing) where it is not.
+     */
+    instanceLabelSections?: readonly LabellingTypes[];
     /** Resource-owned composite templates declared inline on the resource UI behavior. */
     compositeViews?: ResourceCompositeViewsConfig;
     /** Resource-owned execution surfaces declared inline on the resource UI behavior. */
@@ -1157,7 +1497,7 @@ export type ResourceUIBehaviorConfig<TCustomOp extends EnumLikeType | undefined
     chartViews?: InsertedChartDeclaration[];
     /**
      * Empty state configuration for list/table views when no items exist.
-     * Labels (title, description, primaryActionLabel) come from i18n.
+     * Labels (title, description) come from i18n; the primary action is the CREATE operation and takes its title.
      */
     emptyState?: ResourceUIBehavior_EmptyState;
     /**