@vectoriox/iox-ui 5.1.0 → 5.2.0

package/forms-core/index.d.ts

@@ -1,3 +1,5 @@
+export { FORM_SUBMIT_ACTION_DESCRIPTORS as ACTION_DESCRIPTORS, ActionDescriptor, addableActions } from '@vectoriox/iox-ui/actions-core';
+
 /** What the visitor actually types into. Chosen by a trait; it also implies a validation rule. */
 declare enum ControlType {
     Text = "text",
@@ -291,21 +293,6 @@ declare const PATTERN_PRESET_OPTIONS: readonly {
     value: PatternPreset;
     labelKey: string;
 }[];
-/** Destinations an author can add to a form, for the After-submit list. */
-interface ActionDescriptor {
-    type: string;
-    labelKey: string;
-    /** Always present and not removable. */
-    locked?: boolean;
-    /** Not offered yet — shown greyed with a "coming soon" note rather than hidden, so the roadmap
-     *  is visible rather than the feature looking absent. */
-    planned?: boolean;
-}
-declare const ACTION_DESCRIPTORS: readonly ActionDescriptor[];
-/** Destinations that can still be added — each at most once, and never a planned one. */
-declare function addableActions(existing?: readonly {
-    type: string;
-}[]): ActionDescriptor[];
 
 /**
  * The submit transport CONTRACT — what a host must provide to make a form actually send.
@@ -372,5 +359,5 @@ declare function withAntiSpamFields(values: Record<string, any>, renderedAt: num
  */
 declare function interpretSubmitResponse(body: any): SubmitResponse;
 
-export { ACTION_DESCRIPTORS, ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, HONEYPOT_FIELD, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RENDERED_AT_FIELD, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableActions, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, interpretSubmitResponse, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, rulesFor, shouldShowError, submitEndpointPath, uniqueFieldName, validateField, validateForm, withAntiSpamFields };
-export type { ActionDescriptor, FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, FormTransport, RuleDescriptor, SubmitAction, SubmitRequest, SubmitResponse, ValidationRule };
+export { ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, HONEYPOT_FIELD, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RENDERED_AT_FIELD, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, interpretSubmitResponse, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, rulesFor, shouldShowError, submitEndpointPath, uniqueFieldName, validateField, validateForm, withAntiSpamFields };
+export type { FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, FormTransport, RuleDescriptor, SubmitAction, SubmitRequest, SubmitResponse, ValidationRule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -19,6 +19,10 @@
       "types": "./index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui.mjs"
     },
+    "./actions-core": {
+      "types": "./actions-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-actions-core.mjs"
+    },
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"

package/src/actions-core/action.model.ts

@@ -0,0 +1,79 @@
+/**
+ * The ONE descriptor shape for everything an author can put in an ordered action list —
+ * a form's after-submit steps today, element behaviour actions (A1) next. Promoted out of
+ * `forms-core` because a button action importing from the forms module would be a lie; the
+ * forms catalog lives here now and `forms-core` re-exports it unchanged.
+ * See iox-ai-guidance `architecture/builder/actions-framework-plan.md` §4 (A0).
+ */
+
+/** How a step executes — decides which editor fields appear (timing only for `animated`). */
+export type ActionKind = 'animated' | 'instant' | 'server';
+
+/** Picker grouping. Flat lists die at ~10 entries; the group is data, never a second list. */
+export type ActionGroup =
+    | 'motion' | 'visibility' | 'navigate' | 'dialog' | 'form' | 'data' | 'service';
+
+/**
+ * What a step does inside the live builder canvas (the canvas RUNS interactions):
+ * `run` for real (open the dialog), `simulate` announce-only (navigate), `inert` with a
+ * "runs on the live site" note (anything server-side or costing money).
+ */
+export type BuilderBehaviour = 'run' | 'simulate' | 'inert';
+
+/** A configurable parameter, same shape ComponentMethodDef.params already uses. */
+export interface ActionParamSpec {
+    name: string;
+    type: 'number' | 'string' | 'boolean' | 'page' | 'node' | 'form';
+    label: string;
+}
+
+/** Does this action point at another node — and may it be any node or only certain types? */
+export interface ActionTargetSpec {
+    required: boolean;
+    types?: string[];
+}
+
+/**
+ * One row of an action catalog. Every field beyond `type`/`labelKey` is optional so the
+ * pre-A0 forms descriptors remain valid verbatim.
+ */
+export interface ActionDescriptor {
+    type: string;
+    labelKey: string;
+    kind?: ActionKind;
+    group?: ActionGroup;
+    builderBehaviour?: BuilderBehaviour;
+    target?: ActionTargetSpec;
+    params?: ActionParamSpec[];
+    /** The connector that must be configured & healthy before this action is offerable. */
+    connector?: string;
+    /** Plan-entitlement key (AI plan D5). Absent = never gated by plan. */
+    entitlement?: string;
+    /** Always present in the list and not removable (forms: `store`). */
+    locked?: boolean;
+    /** Not offered yet — shown greyed with a "coming soon" note, so the roadmap is visible. */
+    planned?: boolean;
+}
+
+/**
+ * The FORM after-submit catalog (moved verbatim from forms-core; `forms-core` re-exports it
+ * under its old name `ACTION_DESCRIPTORS`). A1's element catalog is a SEPARATE constant —
+ * the two lists share this shape, never one bucket.
+ */
+export const FORM_SUBMIT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.freeze([
+    { type: 'store',      labelKey: 'forms.actions.store',      locked: true,  kind: 'server',  group: 'data',     builderBehaviour: 'inert' },
+    { type: 'email',      labelKey: 'forms.actions.email',                     kind: 'server',  group: 'service',  builderBehaviour: 'inert', connector: 'mailer' },
+    { type: 'redirect',   labelKey: 'forms.actions.redirect',                  kind: 'instant', group: 'navigate', builderBehaviour: 'simulate' },
+    { type: 'createItem', labelKey: 'forms.actions.createItem', planned: true, kind: 'server',  group: 'data',     builderBehaviour: 'inert' },
+    { type: 'webhook',    labelKey: 'forms.actions.webhook',    planned: true, kind: 'server',  group: 'service',  builderBehaviour: 'inert' },
+    { type: 'autoReply',  labelKey: 'forms.actions.autoReply',  planned: true, kind: 'server',  group: 'service',  builderBehaviour: 'inert', connector: 'mailer' },
+]);
+
+/** Steps that can still be added to a list — each at most once, and never a planned one. */
+export function addableActions(
+    existing: readonly { type: string }[] = [],
+    catalog: readonly ActionDescriptor[] = FORM_SUBMIT_ACTION_DESCRIPTORS,
+): ActionDescriptor[] {
+    const used = new Set(existing.map(action => action.type));
+    return catalog.filter(action => !action.locked && !action.planned && !used.has(action.type));
+}

package/src/actions-core/availability.ts

@@ -0,0 +1,46 @@
+import { ActionDescriptor } from './action.model';
+
+/**
+ * K4 of the actions plan: four different reasons a catalog row is unavailable, four different
+ * sentences — *coming soon* · *always on* · *connect X first* · *upgrade*. One resolver feeds
+ * the picker AND the AI composer's validation, so they can never disagree.
+ */
+export type ActionAvailabilityState =
+    | 'available'
+    | 'planned'              // not built yet — greyed, "coming soon"
+    | 'locked'               // always present, not addable/removable
+    | 'connector-missing'    // the named connector is not configured/healthy
+    | 'entitlement-missing'; // the plan does not include it
+
+export interface ActionAvailability {
+    state: ActionAvailabilityState;
+    /** Set when state is connector-missing / entitlement-missing — what to name in the message. */
+    connector?: string;
+    entitlement?: string;
+}
+
+export interface ActionAvailabilityContext {
+    /** Connector health by name. An absent map, or an absent key, means "not known" → allowed. */
+    connectors?: Partial<Record<string, boolean>>;
+    /**
+     * Plan entitlements by key. `Plan.entitlements` does not exist yet anywhere (the known gap),
+     * so an ABSENT map means "no gating" and every entitlement passes — the hook is live the day
+     * the control plane starts sending them.
+     */
+    entitlements?: Partial<Record<string, boolean>>;
+}
+
+export function resolveActionAvailability(
+    descriptor: ActionDescriptor,
+    ctx: ActionAvailabilityContext = {},
+): ActionAvailability {
+    if (descriptor.planned) return { state: 'planned' };
+    if (descriptor.locked) return { state: 'locked' };
+    if (descriptor.connector && ctx.connectors && ctx.connectors[descriptor.connector] === false) {
+        return { state: 'connector-missing', connector: descriptor.connector };
+    }
+    if (descriptor.entitlement && ctx.entitlements && ctx.entitlements[descriptor.entitlement] === false) {
+        return { state: 'entitlement-missing', entitlement: descriptor.entitlement };
+    }
+    return { state: 'available' };
+}

package/src/actions-core/public-api.ts

@@ -0,0 +1,12 @@
+/**
+ * @vectoriox/iox-ui/actions-core — the shared, FRAMEWORK-FREE action vocabulary.
+ *
+ * One `ActionDescriptor` shape for every ordered action list in the product: the forms
+ * after-submit steps (whose catalog moved here; `forms-core` re-exports it unchanged) and
+ * the element behaviour actions of A1. Framework-free for the same reason as `forms-core`
+ * and `seo-core`: `iox-cms` consumes it under plain Node.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, and
+ * tsconfig paths — or `nest start` dies with ERR_REQUIRE_ESM while jest and build pass.
+ */
+export * from './action.model';
+export * from './availability';

package/src/forms-core/rule-catalog.ts

@@ -108,28 +108,9 @@ export const PATTERN_PRESET_OPTIONS: readonly { value: PatternPreset; labelKey:
     { value: PatternPreset.Slug, labelKey: 'forms.rules.preset.slug' },
 ]);
 
-/** Destinations an author can add to a form, for the After-submit list. */
-export interface ActionDescriptor {
-    type: string;
-    labelKey: string;
-    /** Always present and not removable. */
-    locked?: boolean;
-    /** Not offered yet — shown greyed with a "coming soon" note rather than hidden, so the roadmap
-     *  is visible rather than the feature looking absent. */
-    planned?: boolean;
-}
-
-export const ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.freeze([
-    { type: 'store', labelKey: 'forms.actions.store', locked: true },
-    { type: 'email', labelKey: 'forms.actions.email' },
-    { type: 'redirect', labelKey: 'forms.actions.redirect' },
-    { type: 'createItem', labelKey: 'forms.actions.createItem', planned: true },
-    { type: 'webhook', labelKey: 'forms.actions.webhook', planned: true },
-    { type: 'autoReply', labelKey: 'forms.actions.autoReply', planned: true },
-]);
-
-/** Destinations that can still be added — each at most once, and never a planned one. */
-export function addableActions(existing: readonly { type: string }[] = []): ActionDescriptor[] {
-    const used = new Set(existing.map(action => action.type));
-    return ACTION_DESCRIPTORS.filter(action => !action.locked && !action.planned && !used.has(action.type));
-}
+// ── MOVED to @vectoriox/iox-ui/actions-core (A0) ─────────────────────────────
+// The descriptor shape and the after-submit catalog are the ONE action vocabulary the whole
+// product shares; element actions (A1) consume the same shape. Re-exported here under the
+// original names so no forms consumer changes a line.
+export type { ActionDescriptor } from '@vectoriox/iox-ui/actions-core';
+export { FORM_SUBMIT_ACTION_DESCRIPTORS as ACTION_DESCRIPTORS, addableActions } from '@vectoriox/iox-ui/actions-core';