@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.1

package/dist/esm/core/resources/resources.frontend.schemas.js

@@ -1,11 +1,21 @@
 import { z } from "zod";
 import { getZodObjectShape } from '@wildo-ai/zod-decorators';
-import { NavigationZoneName, OverlayAppearance, SplitAppearance, TransitionConfigSchema, viewportDiscriminatedSchema, } from '@wildo-ai/saas-models';
-import { ViewportBreakpoint } from '@wildo-ai/zod-decorators';
+import { ResourceOperationDisplayMode, ResourceOperationFrontendSurface, NavigationZoneName, OverlayAppearance, SplitAppearance, TransitionConfigSchema, viewportDiscriminatedSchema, computePolymorphicVariantSchemas, } from '@wildo-ai/saas-models';
+import { ViewportBreakpoint, DisplayDirection } from '@wildo-ai/zod-decorators';
+import { VerticalPlacement, HorizontalPlacement, } from '@wildo-ai/presets-components-models';
 // ================================================================================================
 // Types transferred from saas-models/config/frontend/navigation.shared.schemas.ts
 // NavigationOperationOverrideSchema only — the rest of navigation stays in saas-models.
 // ================================================================================================
+/**
+ * Per-operation navigation chrome: transition, overlay/split appearance, source zone.
+ *
+ * **How to use:** attach fragments of this shape under
+ * `ResourceOperationFrontendConfig.navigationOverrides` in `resourceUIBehavior()`.
+ * Each override applies when navigating **from** the configured zone/viewport into
+ * this operation. Prefer mirroring a sibling resource that already matches the
+ * product’s overlay vs split behavior.
+ */
 export const NavigationOperationOverrideSchema = z.object({
     transition: TransitionConfigSchema,
     appearance: viewportDiscriminatedSchema(z.union([
@@ -48,6 +58,12 @@ export const FrontendResourceOperationContextSchema = FrontendResourceOperationP
  * build. The `views` sub-field provides per-operation frontend config — giving
  * a single, self-contained definition of how each resource appears and behaves in
  * a given frontend application.
+ *
+ * **How to use (authoring):** in app code, build a `ResourceUIBehavior` map with
+ * `resourceUIBehavior(factory, schema, callback)` and merge presets; the framework
+ * compiles that into `FrontendResourceConfiguration` entries. The types below
+ * (`ResourceUIBehavior_EmptyState`, `ResourceLayoutConfig`, …) are the pieces you
+ * pass inside that callback’s return value.
  */
 // ── Resource frontend config sub-types ──────────────────────────────
 /** Secondary action type for empty state (link to URL vs guidance flow). */
@@ -72,35 +88,504 @@ export var ResourceFrontend_GuidanceFlowTriggerType;
  * and is invisible in Object.keys()/JSON serialization.
  */
 export const FRONTEND_SCHEMA_KEY = Symbol('frontendSchema');
+/** @wildo_source:part:end saas.frontend.operation-key-and-resource-config-like */
 // ── Operation-level frontend config ─────────────────────────────────
 /**
+ * @wildo_source:part:start saas.frontend.resource-operation-frontend-config facet:layer:frontend facet:family:resource-ui
+ *
+ * How a resource collection renders its items (cards vs table). A FRONTEND
+ * presentation vocabulary — authored on a LIST/SEARCH operation's
+ * `collectionDisplayConfig` (below) in the resource UI behavior, NEVER on the
+ * shared resources-config operation: the backend has no notion of cards-vs-table.
+ * The string values are the persisted view-mode keys, so a stored user choice
+ * reads straight across.
+ *
+ * @example
+ * // resource UI behavior `views` entry:
+ * [Op.LIST, { collectionDisplayConfig: { displayMode: CollectionDisplayMode.TABLE, userSwitchableDisplayMode: true } }]
+ */
+export var CollectionDisplayMode;
+(function (CollectionDisplayMode) {
+    /** Stacked cards — one row per item via `ResourceListItemRenderer`. */
+    CollectionDisplayMode["CARDS"] = "cards";
+    /** Dense table — one column per summary field via the table body. */
+    CollectionDisplayMode["TABLE"] = "table";
+})(CollectionDisplayMode || (CollectionDisplayMode = {}));
+/**
+ * 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
+ * DISTINCT layouts, not a `columns: 1` collapse — a list is bordered rows sharing
+ * one container (`divide-y`), a grid is separated card cells in N responsive
+ * columns.
+ */
+export var CardLayoutStyle;
+(function (CardLayoutStyle) {
+    /** Bordered rows in a single shared container (the classic stacked list). */
+    CardLayoutStyle["LIST"] = "list";
+    /** Separated card cells laid out in an N-column responsive grid. */
+    CardLayoutStyle["GRID"] = "grid";
+})(CardLayoutStyle || (CardLayoutStyle = {}));
+/** @wildo_source:part:end saas.frontend.resource-operation-frontend-config */
+/**
+ * @wildo_source:part:start saas.frontend.resource-operation-frontend-config facet:layer:frontend facet:family:resource-ui
+ *
  * Frontend configuration for a single resource operation.
  *
  * Controls how the operation is surfaced in the frontend:
- * - `isAddressable` — whether the operation has a routable URL
- * - `customView` — direct UIBehavior-owned React component override for authored custom operation views
+ * - `surface` — the operation's frontend surface: `ADDRESSABLE` (routable page),
+ *   `EMBEDDED` (non-addressable view rendered within a host: overlay, composite, or
+ *   nested), or `API_ONLY` (headless — no interface, callable as an API). See
+ *   `ResourceOperationFrontendSurface`.
+ * - `customView` — direct UIBehavior-owned React component override for authored custom operation views.
  *   Use the exported operation-family component types (`ResourceReadCustomViewComponent`,
  *   `ResourceListCustomViewComponent`, etc.) plus the matching
  *   `useReadOperationSurface()` / `useListOperationSurface()` helpers when you
  *   want a strongly truthful custom host for a specific layout family.
- * - `additionalViewLinks` — ordered refs of resource-owned chart/composite/execution
- *   views that this operation host should surface
  * - `displayPresetOverride` — layout preset override for the operation's UI
  * - `navigationOverrides` — per-operation navigation transition overrides
  * - `displayPriority` — visual ordering in ActionBar/operation lists (lower = higher priority)
  * - `iconOverride` — per-operation icon ref (overrides resource-level icon in navigation items)
+ * - `collectionDisplayConfig` — for LIST/SEARCH collection operations: the default
+ *   cards-vs-table body (`displayMode`) and whether the user may toggle it
+ *   (`userSwitchableDisplayMode`, persisted per resource type); the CARDS
+ *   arrangement (`cardLayout` — LIST vs N-column GRID); where each card's action
+ *   buttons sit (`cardActionPlacement` — 2-axis anchor + orientation); and
+ *   whether items are selectable for bulk actions (`selectable`). Pure frontend
+ *   presentation; the backend never reads it.
+ *
+ * **Resource-owned inserted views are NOT configured here.** Composite, chart,
+ * and execution views declared on the resource UI behavior surface themselves
+ * into their targeted operation host directly, via their own canonical fields:
+ * `compositeViews[*].operationLike` / `chartViews[*].operationLike` (single)
+ * and `executionViews[*].surfaceInOperations` (list). The layout consumer
+ * (`ResourceLayout_InsertedViews`) reads those declarations and filters them
+ * by the current operation at render time — there is no operation-level
+ * view-ref list to author or compile.
+ *
+ * **Historical note (search hit):** earlier versions of this schema exposed an
+ * `additionalViews: ResourceViewRef[]` (and before that `additionalViewLinks:
+ * string[]`) operation-level field that authored which resource-owned views
+ * surfaced in this operation. That field was removed in the
+ * `resource-owned-view-surfacing-contract.md` workstream because it duplicated
+ * the per-view declaration sites (`compositeViews`, `chartViews`,
+ * `executionViews`) and could silently disagree with them. If you are looking
+ * for `additionalViews` because a doc, comment, prompt, or downstream code
+ * still references it, the answer is: declare the surface on the view itself
+ * (use `operationLike` for composite/chart, `surfaceInOperations` for
+ * execution), do not re-introduce an operation-level seam.
+ */
+/**
+ * How an operation's ACTION (its action-bar button) is surfaced in this application.
+ *
+ * A per-app, **display-only** axis — backend authorization is unaffected, roles
+ * remain the only security authority, so this never makes an operation reachable
+ * that wasn't already; it only governs the button.
+ */
+export var ActionVisibility;
+(function (ActionVisibility) {
+    /** Always shown; rendered DISABLED when its `enabledCondition` is unmet. The default. */
+    ActionVisibility["ALWAYS"] = "always";
+    /**
+     * Never shown — this app declares the operation's action off for this surface.
+     *
+     * Invariant: do NOT pair with a visible (addressable) view for the same operation.
+     * The action is the entry point to the view, so a visible view whose action is
+     * hidden is contradictory — there is no way to reach it. Hiding the action removes
+     * the operation, and the path to any view it has, from this app's UI.
+     */
+    ActionVisibility["HIDDEN"] = "hidden";
+    /**
+     * Shown ONLY when its `enabledCondition` is met; HIDDEN (not disabled) otherwise.
+     *
+     * For state-conditional operations whose disabled state is just noise — e.g.
+     * organization `ACTIVATE` appears on a suspended org but vanishes on an active one,
+     * rather than sitting there greyed out.
+     */
+    ActionVisibility["WHEN_AVAILABLE"] = "when_available";
+})(ActionVisibility || (ActionVisibility = {}));
+/**
+ * Where an operation's ACTION sits in the action bar for this application.
+ *
+ * A per-app, **display-only** layout axis, orthogonal to authorization. When
+ * omitted, placement is DERIVED from the operation's `riskLevel`: HIGH/CRITICAL
+ * operations default to `DANGER_ZONE`, everything else to `PRIMARY`. Set it
+ * explicitly to override that default — e.g. tuck a non-risky-but-rare action
+ * into the danger zone, or keep a CRITICAL action inline in a dedicated admin
+ * tool. The same axis drives the bulk action bar, since both are built from the
+ * same operation pipeline.
+ */
+export var ActionPlacement;
+(function (ActionPlacement) {
+    /** Inline in the main action group. The default for low/medium-risk operations. */
+    ActionPlacement["PRIMARY"] = "primary";
+    /**
+     * Segregated into a trailing "danger zone" group, fenced off by a separator,
+     * after every PRIMARY action. The default for HIGH/CRITICAL-risk operations
+     * (destructive deletes, lifecycle suspends).
+     */
+    ActionPlacement["DANGER_ZONE"] = "danger_zone";
+})(ActionPlacement || (ActionPlacement = {}));
+/**
+ * HOW an operation's action collects its input and shows its result — the chrome the user meets
+ * when they click the button.
+ *
+ * ## Why this axis exists
+ *
+ * Until this axis, one rule decided the answer for every custom operation:
+ * *has a `requestDto` ⇒ navigate*. So an action asking for a single reason string got the same
+ * full-page treatment as a multi-step wizard, and the only way out was to author
+ * `navigationOverrides` — per operation, in terms of a zone, a transition verb and an appearance.
+ * Three concepts to answer one question.
+ *
+ * This is that one question. It is a **display-only** axis: backend authorization is untouched and
+ * `roles` remain the only security authority, exactly like its siblings {@link ActionVisibility},
+ * {@link ActionPlacement} and {@link ResourceOperationActionScope}.
+ *
+ * ## It is an ALIAS, not a parallel mechanism
+ *
+ * `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
+ * 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.
+ *
+ * Consequently an explicit `navigationOverrides` entry still WINS over a presentation authored here
+ * (it is the more specific instrument, and it is checked first in the resolution chain). Author this
+ * axis to say what KIND of chrome the action wants; author `navigationOverrides` when you need to
+ * name the zone, the appearance or the viewport yourself.
+ *
+ * ## 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
+ * 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.
  */
+export var ResourceOperationActionPresentation;
+(function (ResourceOperationActionPresentation) {
+    /**
+     * Execute on click, with no form at all — the confirmation dialog for a risky operation is the
+     * only thing between the click and the request.
+     *
+     * Only meaningful for an operation that needs no caller input. Declaring it on an operation that
+     * DOES have required request fields would send an empty body, so the resolver refuses to derive it
+     * there and an author who declares it anyway gets the operation's fields dropped — check
+     * `requestDto` before reaching for this.
+     */
+    ResourceOperationActionPresentation["DIRECT"] = "direct";
+    /**
+     * 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
+     * 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.
+     */
+    ResourceOperationActionPresentation["POPOVER"] = "popover";
+    /**
+     * 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.
+     *
+     * Use it when the surrounding rows are the point: the user is comparing, and an overlay would hide
+     * the very thing that made them act on this row.
+     *
+     * **Transient, like {@link POPOVER}, and for the same reason.** Nothing is pushed, no URL changes,
+     * and a reload returns the list to rest. An inline row-edit is a momentary state of a listing, not
+     * a place — which is also why no admin framework deep-links one, and why anything that SHOULD be
+     * linkable, reloadable or reachable by a back button wants {@link PAGE}.
+     *
+     * **It requires a collection.** The host is provided by the list the element belongs to
+     * (`InPlaceOperationProvider`); the same action rendered on a detail page, in a danger zone or in a
+     * picker has no row to transform and degrades to an overlay rather than becoming a dead button.
+     *
+     * Note it does NOT resolve to `NavigationTransition.INPLACE`. Element-level hosting uses none of
+     * what the navigation layer offers — no zone, no stack entry, no appearance — and routing it there
+     * is exactly why that transition has never done what its own docstring promises. See
+     * `InPlaceOperationContext`.
+     */
+    ResourceOperationActionPresentation["INLINE"] = "inline";
+    /**
+     * An overlay above the layout — the workhorse for "a handful of fields", and the default the
+     * derivation reaches for.
+     *
+     * Resolves to {@link NavigationTransition.OVERLAY}. The concrete appearance (dialog / sheet /
+     * drawer / panel) stays the app's decision, resolved from its navigation layout exactly as any
+     * other overlay: this axis says "an overlay", not "a dialog specifically". Author
+     * `navigationOverrides` when you need to name one.
+     */
+    ResourceOperationActionPresentation["MODAL"] = "modal";
+    /**
+     * A routable page, resolved through the ordinary navigation chain (zone transitions, viewport
+     * overrides, the framework `PUSH` fallback) — i.e. exactly the behaviour every parameterised
+     * action had before this axis existed.
+     *
+     * The right answer for complex or multi-step input, and for anything a user should be able to
+     * link to, reload, or reach with a back button.
+     */
+    ResourceOperationActionPresentation["PAGE"] = "page";
+})(ResourceOperationActionPresentation || (ResourceOperationActionPresentation = {}));
+/**
+ * Does an operation's action target a SINGLE resource instance, or the WHOLE
+ * collection in the current scope?
+ *
+ * A per-app **surfacing** axis, orthogonal to authorization. Most actions are
+ * `ITEM` (edit / delete / retry one row) and render in the per-row and detail
+ * action bars. A `COLLECTION` action operates on every row in scope at once
+ * (e.g. "retry all failed deliveries", "purge the queue"): it renders ONCE in
+ * the list's collection-action surface (the toolbar), never per row, and
+ * confirms + executes in place rather than opening a per-row form.
+ *
+ * For a `COLLECTION` action to have a callable route, its operation must borrow
+ * a COLLECTION verb via `resourceOperationLike` (`UPDATE_MANY` / `DELETE_MANY` /
+ * `CREATE_MANY`) — an entity verb (`UPDATE` / `DELETE`) generates a route with a
+ * `:id` segment the scope-level surface has no single row to fill.
+ */
+export var ResourceOperationActionScope;
+(function (ResourceOperationActionScope) {
+    /** Targets one resource instance — the per-row / detail action bars. The default when omitted. */
+    ResourceOperationActionScope["ITEM"] = "item";
+    /** Targets the whole collection in scope — rendered once in the list's collection-action surface. */
+    ResourceOperationActionScope["COLLECTION"] = "collection";
+})(ResourceOperationActionScope || (ResourceOperationActionScope = {}));
+/**
+ * What happens to an operation's action when its `enabledCondition` is currently
+ * unmet — the per-view default for actions that don't declare an explicit
+ * `actionVisibility`. An explicit per-operation `actionVisibility` always wins
+ * over this policy; feature-gated unavailability keeps its own
+ * `FeatureUnavailabilityBehavior` (upgrade/prompt) and is never hidden by this.
+ *
+ * - `HIDE` — drop the action entirely while unavailable (as if it declared
+ *   `ActionVisibility.WHEN_AVAILABLE`). The framework default for BOTH views: a
+ *   greyed, non-actionable button is noise wherever it sits, and hiding it also
+ *   collapses mutually-exclusive state pairs (e.g. "Set as recurring" / "Set as
+ *   one time") down to the one that currently applies.
+ * - `SHOW_DISABLED` — render the action greyed/disabled (the classic behavior).
+ *   Opt in per view when the disabled action + its reason tooltip is genuinely
+ *   informative and you want it always present.
+ */
+export var DisabledActionHandling;
+(function (DisabledActionHandling) {
+    DisabledActionHandling["SHOW_DISABLED"] = "show_disabled";
+    DisabledActionHandling["HIDE"] = "hide";
+})(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`.
+ */
+export const DEFAULT_ACTION_DISCLOSURE = {
+    [ResourceOperationDisplayMode.SUMMARY]: {
+        maxPrimaryActions: 3,
+        disabledActionHandling: DisabledActionHandling.HIDE,
+    },
+    [ResourceOperationDisplayMode.DETAIL]: {
+        maxPrimaryActions: undefined,
+        disabledActionHandling: DisabledActionHandling.HIDE,
+    },
+};
+/**
+ * Resolve the effective disclosure policy for a view: per-resource override
+ * (`layout.actionDisclosure[view]`) layered over the framework default. Used by
+ * both the action-building hook (disabled handling) and the operations-items
+ * host (overflow cap).
+ */
+export function resolveActionDisclosure(displayMode, disclosure) {
+    const base = DEFAULT_ACTION_DISCLOSURE[displayMode] ?? DEFAULT_ACTION_DISCLOSURE[ResourceOperationDisplayMode.DETAIL];
+    const override = disclosure?.[displayMode];
+    return {
+        maxPrimaryActions: override?.maxPrimaryActions ?? base.maxPrimaryActions,
+        disabledActionHandling: override?.disabledActionHandling ?? base.disabledActionHandling,
+    };
+}
+/**
+ * 2-axis card action-button placement. Single source of truth for the config
+ * field AND the `card-action-placement.utils` resolver (which imports the
+ * `CardActionPlacement` type inferred from this schema, so the two can never
+ * drift). `MIDDLE × MIDDLE` is rejected — dead-center overlaps the card content.
+ */
+export const CardActionPlacementSchema = z.object({
+    vertical: z.enum(VerticalPlacement),
+    horizontal: z.enum(HorizontalPlacement),
+    orientation: z.enum(DisplayDirection).optional(),
+}).refine((p) => !(p.vertical === VerticalPlacement.MIDDLE && p.horizontal === HorizontalPlacement.MIDDLE), { message: 'cardActionPlacement cannot be MIDDLE × MIDDLE (dead-center overlaps card content); choose an edge or corner.' });
 export const ResourceOperationFrontendConfigSchema = z.object({
-    isAddressable: z.boolean(),
+    /**
+     * The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
+     * `ADDRESSABLE` (routable page) and `EMBEDDED` (non-addressable view rendered within
+     * a host — overlay/composite/nested) both have a view + action button; `API_ONLY` is
+     * headless (no view, no button). The view fields below (`actionVisibility`,
+     * `customView`, `iconOverride`, layout, …) apply only to `ADDRESSABLE`/`EMBEDDED`; a
+     * build-time check rejects them on `API_ONLY`.
+     * Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
+     */
+    surface: z.enum(ResourceOperationFrontendSurface),
+    /**
+     * How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
+     * (the common case) behaves as `ALWAYS`.
+     */
+    actionVisibility: z.enum(ActionVisibility).optional(),
+    /**
+     * Where this operation's action sits in the bar — see {@link ActionPlacement}.
+     * Omitted derives from `riskLevel` (HIGH/CRITICAL → danger zone, else primary).
+     */
+    actionPlacement: z.enum(ActionPlacement).optional(),
+    /**
+     * Visual button variant (colour) for this operation's action — a
+     * `ButtonVariants_Variant` (e.g. `DESTRUCTIVE`, `GHOST`, `ACCENT`). Omitted
+     * derives from `riskLevel` (HIGH/CRITICAL → destructive/red, else ghost). Typed
+     * on the interface below; the Zod field stays `z.any()` because the enum lives
+     * in a component module a schema must not pull at runtime (same as `iconOverride`).
+     */
+    actionVariant: z.any().optional(),
+    /**
+     * Does this action target one row or the whole collection — see
+     * {@link ResourceOperationActionScope}. Omitted behaves as `ITEM`. A
+     * `COLLECTION` action renders once in the list's collection-action surface
+     * (never per row) and confirms + executes in place; pair it with a COLLECTION
+     * `resourceOperationLike` (`*_MANY`) so its generated route carries no `:id`.
+     */
+    actionScope: z.enum(ResourceOperationActionScope).optional(),
+    /**
+     * For an `ITEM` action whose backend addresses the target row by a field in
+     * the REQUEST BODY (not the URL id), the request-DTO field name to fill with
+     * the clicked row's id. When set, clicking the action executes IN PLACE —
+     * sending `{ [rowTargetRequestField]: <rowId> }` — instead of opening a form:
+     * e.g. a per-row "Retry" whose handler reads `{ entryId }` from the body. (The
+     * row id still rides the URL path too, which the handler may ignore.)
+     */
+    rowTargetRequestField: z.string().optional(),
+    /**
+     * HOW this action collects its input — see {@link ResourceOperationActionPresentation}.
+     * Omitted derives from the operation (`resolveResourceOperationActionPresentation`): no input
+     * executes directly, a small field set opens a modal, complex input keeps its page.
+     *
+     * Display-only. An explicit `navigationOverrides` entry is the more specific instrument and wins
+     * over whatever this resolves to.
+     */
+    actionPresentation: z.enum(ResourceOperationActionPresentation).optional(),
     customView: z.any().optional(),
-    additionalViewLinks: z.array(z.string().min(1)).optional(),
     displayPresetOverride: z.object({
         resourceLayoutPresetKey: z.string().optional(),
     }).optional(),
     navigationOverrides: z.array(NavigationOperationOverrideSchema).optional(),
     displayPriority: z.number().optional(),
     iconOverride: z.any().optional(),
+    collectionDisplayConfig: z.object({
+        displayMode: z.enum(CollectionDisplayMode).optional(),
+        userSwitchableDisplayMode: z.boolean().optional(),
+        /**
+         * Promote ONE enum filter field to a prominent quick-filter tab strip
+         * rendered above the collection toolbar ("All · <value> · <value> …" —
+         * the Stripe/Ignisign webhook-dashboard idiom, e.g. All/Delivered/Failed).
+         *
+         * The named field MUST be an enum member of the operation's backend
+         * `filterFields` — the tabs write into the SAME filter state as the
+         * filters panel (selecting a tab filters server-side), and the field is
+         * removed from the panel/chips so there is never a second competing
+         * control for it. Unknown / non-enum field names degrade gracefully
+         * (no tab strip, field stays in the panel). Tab labels reuse the enum
+         * value i18n (`tResourceFieldEnumValue`).
+         */
+        quickFilterField: z.string().optional(),
+        /**
+         * Group CARDS-mode rows into day buckets by this date field, rendering a
+         * date heading between groups (activity-feed idiom for log-like
+         * collections, e.g. webhook deliveries by day). Purely presentational:
+         * grouping applies to the fetched page in its server order — pair it
+         * with a default sort on the same field so buckets are contiguous.
+         * Ignored in TABLE mode (column sorting owns the ordering there). Rows
+         * whose field value is missing/unparsable render in a trailing bucket
+         * without a date heading rather than being dropped.
+         */
+        temporalGroupField: z.string().optional(),
+        /**
+         * CARDS-mode arrangement — a single-column bordered LIST (default) or an
+         * N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
+         * the TARGET maximum; the grid steps DOWN to fewer columns as the grid's own
+         * available WIDTH narrows (an intrinsic `auto-fill minmax` track spec — so a
+         * grid embedded in a narrow pane collapses even on a wide viewport, with no
+         * media breakpoint). Authors give one N; the framework handles the rest.
+         * Ignored in TABLE mode.
+         *
+         * @example
+         * cardLayout: { style: CardLayoutStyle.GRID, columns: 3 }
+         */
+        cardLayout: z.discriminatedUnion('style', [
+            z.object({ style: z.literal(CardLayoutStyle.LIST) }),
+            z.object({
+                style: z.literal(CardLayoutStyle.GRID),
+                columns: z.number().int().min(1).max(6),
+            }),
+        ]).optional(),
+        /**
+         * Where each card's per-item action buttons sit, as a 2-axis anchor:
+         * `vertical` ({@link VerticalPlacement} TOP/MIDDLE/BOTTOM) × `horizontal`
+         * ({@link HorizontalPlacement} START/MIDDLE/END, RTL-aware). `orientation`
+         * ({@link DisplayDirection}) lays the button set out as a row (HORIZONTAL,
+         * default) or a vertical stack (VERTICAL). Omitted → the classic
+         * MIDDLE × END horizontal row.
+         *
+         * `MIDDLE × MIDDLE` is rejected (dead-center overlaps the card content and
+         * has no sensible meaning).
+         *
+         * @example
+         * cardActionPlacement: { vertical: VerticalPlacement.TOP, horizontal: HorizontalPlacement.END }
+         */
+        cardActionPlacement: CardActionPlacementSchema.optional(),
+        /**
+         * Enable per-item SELECTION (checkboxes on cards / a select column in the
+         * table) and the resulting BULK ACTION bar. Explicit opt-in per view. The
+         * bar surfaces only operations declared `isBulkOperation` — a `selectable`
+         * view with no bulk operations shows checkboxes that drive an empty bar, so
+         * pair it with at least one bulk operation. Selection state is shared across
+         * the cards↔table toggle (it does not reset when switching modes).
+         */
+        selectable: z.boolean().optional(),
+    }).optional(),
+    /**
+     * Opt this operation into a generated per-operation description label
+     * (`resources.{res}.operations.{op}.description`, read via `tResourceOperation`).
+     * Default off — most operations need no description (making it mandatory for
+     * every operation is far too verbose). Surfaces that show one (e.g. the danger
+     * zone) fall back to risk-based copy when this is unset. Mirrors how fields opt
+     * into a description via the `.describe()` decorator.
+     */
+    hasDescription: z.boolean().optional(),
 });
+/** @wildo_source:part:end saas.frontend.resource-operation-frontend-config */
+/**
+ * Is this operation's frontend surface URL-addressable (a routable page)?
+ *
+ * The canonical replacement for the former `isAddressable` boolean field — read
+ * `surface` rather than storing addressability, so the three surfaces stay a
+ * single source of truth. Safe on `undefined` (an operation whose frontend
+ * config has not been resolved yet is treated as not addressable).
+ */
+export function isOperationAddressable(config) {
+    return config?.surface === ResourceOperationFrontendSurface.ADDRESSABLE;
+}
+/**
+ * Is this operation headless — callable as an API with no rendered interface
+ * (no page, no overlay, no action button)? See {@link ResourceOperationFrontendSurface.API_ONLY}.
+ */
+export function isOperationHeadless(config) {
+    return config?.surface === ResourceOperationFrontendSurface.API_ONLY;
+}
+/**
+ * Does this operation's action target the whole collection in scope, rather than
+ * a single row? See {@link ResourceOperationActionScope}. Safe on `undefined`
+ * (treated as `ITEM`). Collection-scoped actions render ONLY in the list's
+ * collection-action surface (the toolbar) and are excluded from the per-row,
+ * detail, danger-zone, and bulk bars.
+ */
+export function isCollectionScopedOperation(config) {
+    return config?.actionScope === ResourceOperationActionScope.COLLECTION;
+}
 // ── Polymorphic preset factory ──────────────────────────────────────
 /**
  * Creates frontend preset entries for all scope variants of a polymorphic resource.
@@ -134,7 +619,7 @@ export const ResourceOperationFrontendConfigSchema = z.object({
  * }, {
  *   views: [
  *     [Op.READ, addressable()],
- *     [SsoConfig_Operations.ADD_DOMAIN, notAddressable()],
+ *     [CustomOperations.RUN_DIAGNOSTIC, notAddressable()],
  *   ],
  *   variantOverrides: {
  *     [R.APPLICATION]: { views: [] },
@@ -150,7 +635,7 @@ export const ResourceOperationFrontendConfigSchema = z.object({
  * }, {
  *   views: [
  *     [Op.READ, addressable()],
- *     [SsoConfig_Operations.ADD_DOMAIN, notAddressable()],
+ *     [CustomOperations.RUN_DIAGNOSTIC, notAddressable()],
  *   ],
  *   variantOverrides: {
  *     [R.ORGANIZATIONS]: {
@@ -164,19 +649,53 @@ export const ResourceOperationFrontendConfigSchema = z.object({
  * ```
  */
 export function createPolymorphicFrontendPreset(declaration, config) {
+    const schema = config[FRONTEND_SCHEMA_KEY];
     const { variantOverrides, views: sharedViewsEntries, ...sharedRest } = config;
     const sharedViews = new Map(sharedViewsEntries);
     const sharedConfig = { ...sharedRest, views: sharedViews };
+    // Compute per-variant FK-renamed schemas. The author passes ONE base
+    // schema to `polymorphicResourceUIBehavior(decl, factory, baseSchema, ...)`,
+    // but the runtime polymorphic factory renames `polymorphicVariants`-marked
+    // FK fields per variant (e.g. `billingAccountId` →
+    // `organizationBillingAccountId` for the ORGANIZATIONS variant). If we
+    // attach the un-renamed base schema as `FRONTEND_SCHEMA_KEY` on every
+    // variant, `buildFrontendResourceConfigurations` later replaces the
+    // renamed `mainSchema` with the un-renamed base — and the FK→parent
+    // resolution check throws because the base's `billingAccountId` doesn't
+    // resolve to a unique parent. Mirror the factory's rename at this seam
+    // so per-variant `FRONTEND_SCHEMA_KEY` matches the per-variant
+    // `mainSchema` keys.
+    const variantSchemas = schema !== undefined && schema?._zod?.def?.type === 'object'
+        ? computePolymorphicVariantSchemas(schema, declaration.variants)
+        : null;
+    if (schema !== undefined) {
+        sharedConfig[FRONTEND_SCHEMA_KEY] = schema;
+    }
     const result = {};
     for (const variant of declaration.variants) {
         const override = variantOverrides?.[variant.parentResourceType];
+        // Use the per-variant renamed schema when available; fall back to the
+        // shared base schema for declarations whose fields have no
+        // `polymorphicVariants` metadata (rename map is empty → identity).
+        const variantSchema = variantSchemas?.get(variant.parentResourceType) ?? schema;
         if (override) {
             const { views: overrideViewsEntries, ...overrideRest } = override;
-            result[variant.resourceType] = {
+            const concreteConfig = {
                 ...sharedConfig,
                 ...overrideRest,
                 views: overrideViewsEntries ? new Map(overrideViewsEntries) : sharedViews,
             };
+            if (variantSchema !== undefined) {
+                concreteConfig[FRONTEND_SCHEMA_KEY] = variantSchema;
+            }
+            result[variant.resourceType] = concreteConfig;
+        }
+        else if (variantSchemas && variantSchema !== schema) {
+            // Distinct per-variant schema: clone sharedConfig so each variant
+            // keeps its own FRONTEND_SCHEMA_KEY rather than sharing the base.
+            const concreteConfig = { ...sharedConfig, views: sharedViews };
+            concreteConfig[FRONTEND_SCHEMA_KEY] = variantSchema;
+            result[variant.resourceType] = concreteConfig;
         }
         else {
             result[variant.resourceType] = sharedConfig;
@@ -188,6 +707,10 @@ export function createPolymorphicFrontendPreset(declaration, config) {
 /**
  * Creates a typed operation variant tuple `[operationKey, variantKey]`.
  * Preserves the literal operation key for `TypedOperationKey` assignability.
+ *
+ * **How to use:** in `views: [ … ]` when the operation key must stay a narrow literal
+ * (custom enum member or core op). Equivalent to `opsVariantResolver(op, key)` but
+ * useful in static arrays outside the callback.
  */
 export function variant(op, variantKey) {
     return [op, variantKey];
@@ -217,8 +740,8 @@ export function variant(op, variantKey) {
  *       }),
  *     },
  *     views: [
- *       [CoreResourceOperation.LIST, { isAddressable: true }],
- *       [opsVariantResolver(CoreResourceOperation.CREATE, 'quick-add'), { isAddressable: false }],
+ *       [CoreResourceOperation.LIST, addressable()],
+ *       [opsVariantResolver(CoreResourceOperation.CREATE, 'quick-add'), notAddressable()],
  *     ],
  *   }),
  * ),
@@ -375,9 +898,11 @@ export function polymorphicResourceUIBehavior(declaration, _factory, schemaOrCon
                 ? schema.shape
                 : getZodObjectShape(schema));
             const opsVariantResolver = (op, variantKey) => [op, variantKey];
-            return configFactory({ schema, schemaShape, opsVariantResolver: opsVariantResolver });
+            const config = configFactory({ schema, schemaShape, opsVariantResolver: opsVariantResolver });
+            config[FRONTEND_SCHEMA_KEY] = schema;
+            return config;
         })()
         : schemaOrConfig;
     return createPolymorphicFrontendPreset(declaration, config);
 }
-//# sourceMappingURL=resources.frontend.schemas.js.map
+//# sourceMappingURL=resources.frontend.schemas.js.map