@vectoriox/iox-ui 4.31.1 → 4.32.0

package/forms-core/index.d.ts

@@ -242,5 +242,70 @@ declare function applyServerErrors(state: FormRuntimeState, errors: Record<strin
 /** A clean slate after a successful submit, for a form configured to clear itself. */
 declare function resetFormState(): FormRuntimeState;
 
-export { ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PatternPreset, RULE_MESSAGE_KEYS, RuleName, STORE_ACTION, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, shouldShowError, uniqueFieldName, validateField, validateForm };
-export type { FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, SubmitAction, ValidationRule };
+/**
+ * Which rules exist, and which controls they make sense on.
+ *
+ * The panel must not offer "must be ticked" on a text field, or a character limit on a date. That
+ * knowledge belongs with the validator, not duplicated into the editor — otherwise the two drift and
+ * an author configures a rule that silently never runs.
+ *
+ * Pure data, in forms-core, so the builder panel, the engine and the backend all read one catalog.
+ */
+
+/** How a rule's parameter is edited. The panel maps these to its own controls. */
+declare enum RuleParamKind {
+    /** No parameter — the rule is its own statement (`required`, `accepted`). */
+    None = "none",
+    /** A single number (`{ n }`) — lengths and bounds. */
+    Number = "number",
+    /** A preset regex, or a custom one (`{ preset }` / `{ regex }`). */
+    Pattern = "pattern",
+    /** Another field in the same form (`{ field }`). */
+    Field = "field"
+}
+interface RuleDescriptor {
+    name: RuleName;
+    /** i18n key for the rule's name in the Add-rule menu. */
+    labelKey: string;
+    param: RuleParamKind;
+    /** Controls this rule can apply to. Empty means every control. */
+    controls: readonly ControlType[];
+    /** Suggested starting value for the parameter, so a freshly added rule is already valid. */
+    defaultParams?: Record<string, any>;
+}
+declare const RULE_DESCRIPTORS: readonly RuleDescriptor[];
+/** The rules that can be added to a field of this control type. */
+declare function rulesFor(control: ControlType | string): RuleDescriptor[];
+/**
+ * The rules an author may still ADD — the catalog minus what is already on the field.
+ *
+ * Each rule appears once: two `maxLength` rules on one field is not a configuration anyone means,
+ * and the validator would apply whichever came first. `pattern` is the exception a caller might
+ * expect to repeat, and it deliberately does not: a second pattern can only contradict the first.
+ */
+declare function addableRules(control: ControlType | string, existing?: readonly {
+    name: RuleName;
+}[]): RuleDescriptor[];
+/** The preset options a Pattern rule offers, in the order the panel should list them. */
+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[];
+
+export { ACTION_DESCRIPTORS, ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableActions, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, rulesFor, shouldShowError, uniqueFieldName, validateField, validateForm };
+export type { ActionDescriptor, FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, RuleDescriptor, SubmitAction, ValidationRule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.31.1",
+  "version": "4.32.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

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

@@ -15,3 +15,4 @@ export * from './messages';
 export * from './validate';
 export * from './collect';
 export * from './runtime';
+export * from './rule-catalog';

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

@@ -0,0 +1,135 @@
+/**
+ * Which rules exist, and which controls they make sense on.
+ *
+ * The panel must not offer "must be ticked" on a text field, or a character limit on a date. That
+ * knowledge belongs with the validator, not duplicated into the editor — otherwise the two drift and
+ * an author configures a rule that silently never runs.
+ *
+ * Pure data, in forms-core, so the builder panel, the engine and the backend all read one catalog.
+ */
+
+import { ControlType, PatternPreset, RuleName } from './form.model';
+
+/** How a rule's parameter is edited. The panel maps these to its own controls. */
+export enum RuleParamKind {
+    /** No parameter — the rule is its own statement (`required`, `accepted`). */
+    None = 'none',
+    /** A single number (`{ n }`) — lengths and bounds. */
+    Number = 'number',
+    /** A preset regex, or a custom one (`{ preset }` / `{ regex }`). */
+    Pattern = 'pattern',
+    /** Another field in the same form (`{ field }`). */
+    Field = 'field',
+}
+
+export interface RuleDescriptor {
+    name: RuleName;
+    /** i18n key for the rule's name in the Add-rule menu. */
+    labelKey: string;
+    param: RuleParamKind;
+    /** Controls this rule can apply to. Empty means every control. */
+    controls: readonly ControlType[];
+    /** Suggested starting value for the parameter, so a freshly added rule is already valid. */
+    defaultParams?: Record<string, any>;
+}
+
+/** Text-ish controls: the ones whose value is a string a person typed. */
+const TEXTUAL: readonly ControlType[] = [
+    ControlType.Text, ControlType.Email, ControlType.Tel, ControlType.Url,
+    ControlType.Password, ControlType.Textarea,
+];
+
+/** Controls with a comparable magnitude. */
+const NUMERIC: readonly ControlType[] = [ControlType.Number, ControlType.Date, ControlType.Time];
+
+export const RULE_DESCRIPTORS: readonly RuleDescriptor[] = Object.freeze([
+    {
+        name: RuleName.MinLength, labelKey: 'forms.rules.minLength',
+        param: RuleParamKind.Number, controls: TEXTUAL, defaultParams: { n: 2 },
+    },
+    {
+        name: RuleName.MaxLength, labelKey: 'forms.rules.maxLength',
+        param: RuleParamKind.Number, controls: TEXTUAL, defaultParams: { n: 200 },
+    },
+    {
+        name: RuleName.Min, labelKey: 'forms.rules.min',
+        param: RuleParamKind.Number, controls: NUMERIC, defaultParams: { n: 0 },
+    },
+    {
+        name: RuleName.Max, labelKey: 'forms.rules.max',
+        param: RuleParamKind.Number, controls: NUMERIC, defaultParams: { n: 100 },
+    },
+    {
+        name: RuleName.Pattern, labelKey: 'forms.rules.pattern',
+        param: RuleParamKind.Pattern, controls: TEXTUAL,
+        defaultParams: { preset: PatternPreset.Email },
+    },
+    {
+        // Cross-field: confirm-email, confirm-password.
+        name: RuleName.Matches, labelKey: 'forms.rules.matches',
+        param: RuleParamKind.Field, controls: [],
+    },
+    {
+        // A checkbox's `required` already becomes `accepted`, so offering it again would be a
+        // duplicate — it is here for a checkbox the author wants ticked WITHOUT marking it required.
+        name: RuleName.Accepted, labelKey: 'forms.rules.accepted',
+        param: RuleParamKind.None, controls: [ControlType.Checkbox],
+    },
+]);
+
+/** The rules that can be added to a field of this control type. */
+export function rulesFor(control: ControlType | string): RuleDescriptor[] {
+    return RULE_DESCRIPTORS.filter(rule =>
+        rule.controls.length === 0 || rule.controls.includes(control as ControlType));
+}
+
+/**
+ * The rules an author may still ADD — the catalog minus what is already on the field.
+ *
+ * Each rule appears once: two `maxLength` rules on one field is not a configuration anyone means,
+ * and the validator would apply whichever came first. `pattern` is the exception a caller might
+ * expect to repeat, and it deliberately does not: a second pattern can only contradict the first.
+ */
+export function addableRules(
+    control: ControlType | string,
+    existing: readonly { name: RuleName }[] = [],
+): RuleDescriptor[] {
+    const used = new Set(existing.map(rule => rule.name));
+    return rulesFor(control).filter(rule => !used.has(rule.name));
+}
+
+/** The preset options a Pattern rule offers, in the order the panel should list them. */
+export const PATTERN_PRESET_OPTIONS: readonly { value: PatternPreset; labelKey: string }[] = Object.freeze([
+    { value: PatternPreset.Email, labelKey: 'forms.rules.preset.email' },
+    { value: PatternPreset.Phone, labelKey: 'forms.rules.preset.phone' },
+    { value: PatternPreset.Url, labelKey: 'forms.rules.preset.url' },
+    { value: PatternPreset.Digits, labelKey: 'forms.rules.preset.digits' },
+    { value: PatternPreset.Letters, labelKey: 'forms.rules.preset.letters' },
+    { 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));
+}