@praxisui/cron-builder 8.0.0-beta.0 → 8.0.0-beta.11

package/README.md

@@ -79,6 +79,7 @@ Template-only example:
 Exports:
 - `PdxCronBuilderComponent`
 - Types: `CronBuilderMetadata`, `SimpleCronFormValue`, `AdvancedCronFormValue`, `CronPresetType`
+- Scheduler authoring foundation: `ScheduleAuthoringConfig`, `CronDialect`, `CRON_DIALECTS`, `normalizeScheduleValue`, `compileScheduleExpression`, `validateScheduleAuthoringConfig`, `createSchedulePreview`
 
 Inputs/Outputs:
 - `metadata: CronBuilderMetadata` – configure fields, timezone, locale, presets, preview.
@@ -93,6 +94,61 @@ Inputs/Outputs:
 - `previewOccurrences?: number` – number of preview dates to show.
 - `validators?: { invalidCronMessage?: string }` – customize error messages.
 
+## Scheduler Authoring Foundation
+
+`@praxisui/cron-builder` also exposes the canonical foundation for evolving CRON editing into schedule authoring.
+This keeps enterprise scheduling semantics in the library instead of pushing cron parsing, dialect checks or preview policy into host applications.
+
+The initial contract is `ScheduleAuthoringConfig`. It models:
+- schedule kind: `once`, `interval`, `daily`, `weekly`, `monthly` or `customCron`;
+- timezone and locale;
+- CRON expression plus explicit dialect;
+- recurrence intent;
+- start/end window;
+- execution policy such as enabled state, missed-run policy, concurrency and jitter;
+- preview configuration;
+- governance metadata such as name, owner and tags.
+
+The exported `CRON_DIALECTS` matrix describes the supported dialect families:
+- Unix cron
+- Quartz cron
+- AWS EventBridge cron
+- Kubernetes CronJob
+- GitHub Actions schedule
+- Google Cloud Scheduler
+
+Use `normalizeScheduleValue(value)` to convert legacy string values into `ScheduleAuthoringConfig` while preserving current `ControlValueAccessor` compatibility.
+The current component still emits the existing CRON string; the schedule authoring contract is the platform foundation for the next visual authoring iteration.
+
+Runtime helpers:
+- `compileScheduleExpression(config)` compiles supported schedule intents (`interval`, `daily`, `weekly`, `monthly`, `customCron`) into CRON when the intent has a portable representation.
+- `validateScheduleAuthoringConfig(config)` returns structured diagnostics for invalid or non-portable schedules.
+- `createSchedulePreview(value, preview)` returns the compiled expression, humanized text, structured occurrences and diagnostics.
+
+The AI adapter exposes both the legacy `value` and the structured scheduler state:
+- `schedule` is the canonical authoring config snapshot.
+- `diagnostics` contains read-only validation results.
+- `preview` contains read-only structured next occurrences.
+
+AI patches should prefer `schedule.kind` plus `schedule.recurrence` for business scheduling intent, and reserve `schedule.expression.cron` for explicit custom CRON requests.
+
+## Agentic Authoring
+
+The executable authoring contract is exported as `PRAXIS_CRON_BUILDER_AUTHORING_MANIFEST`.
+It models typed operations over the same schedule runtime used by the component:
+
+- `cron.expression.set`
+- `cron.frequency.set`
+- `cron.timezone.set`
+- `cron.preset.apply`
+- `cron.validate`
+- `cron.preview.generate`
+
+Expression, frequency, timezone and preset operations may patch canonical
+`schedule` or compatibility `value` paths only after validation succeeds.
+`cron.validate` and `cron.preview.generate` are read-only operations: invalid
+schedules return structured `diagnostics` and do not mutate the current schedule.
+
 ## Build Notes
 
 The builder resolves validation, humanized descriptions and occurrence preview inside the library runtime.

package/fesm2022/praxisui-cron-builder.mjs

@@ -429,6 +429,451 @@ function getNextCronOccurrences(expression, count, options) {
     return results;
 }
 
+const SCHEDULE_AUTHORING_CONFIG_VERSION = 'v1';
+const CRON_DIALECTS = {
+    unix: {
+        dialect: 'unix',
+        label: 'Unix cron',
+        fieldCount: { min: 5, max: 5 },
+        supportsSeconds: false,
+        supportsYear: false,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: false,
+        supportsLast: false,
+        supportsNearestWeekday: false,
+        supportsNthWeekday: false,
+        timezoneMode: 'host-local',
+        dayOfMonthDayOfWeekRule: 'unix-or',
+        examples: ['*/5 * * * *', '0 9 * * 1-5'],
+    },
+    quartz: {
+        dialect: 'quartz',
+        label: 'Quartz cron',
+        fieldCount: { min: 6, max: 7 },
+        supportsSeconds: true,
+        supportsYear: true,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: true,
+        supportsLast: true,
+        supportsNearestWeekday: true,
+        supportsNthWeekday: true,
+        timezoneMode: 'external-field',
+        dayOfMonthDayOfWeekRule: 'either-or-question-mark',
+        examples: ['0 0 9 ? * MON-FRI', '0 0 9 ? * 2#1'],
+    },
+    'aws-eventbridge': {
+        dialect: 'aws-eventbridge',
+        label: 'AWS EventBridge cron',
+        fieldCount: { min: 6, max: 6 },
+        supportsSeconds: false,
+        supportsYear: true,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: true,
+        supportsLast: true,
+        supportsNearestWeekday: false,
+        supportsNthWeekday: true,
+        timezoneMode: 'external-field',
+        dayOfMonthDayOfWeekRule: 'either-or-question-mark',
+        examples: ['0 9 ? * MON-FRI *', '0 9 ? * 2#1 *'],
+    },
+    kubernetes: {
+        dialect: 'kubernetes',
+        label: 'Kubernetes CronJob',
+        fieldCount: { min: 5, max: 5 },
+        supportsSeconds: false,
+        supportsYear: false,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: true,
+        supportsLast: false,
+        supportsNearestWeekday: false,
+        supportsNthWeekday: false,
+        timezoneMode: 'external-field',
+        dayOfMonthDayOfWeekRule: 'unix-or',
+        examples: ['*/5 * * * *', '0 9 * * 1-5'],
+    },
+    'github-actions': {
+        dialect: 'github-actions',
+        label: 'GitHub Actions schedule',
+        fieldCount: { min: 5, max: 5 },
+        supportsSeconds: false,
+        supportsYear: false,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: false,
+        supportsLast: false,
+        supportsNearestWeekday: false,
+        supportsNthWeekday: false,
+        timezoneMode: 'fixed-utc',
+        dayOfMonthDayOfWeekRule: 'unix-or',
+        examples: ['*/15 * * * *', '0 9 * * 1-5'],
+    },
+    'gcp-scheduler': {
+        dialect: 'gcp-scheduler',
+        label: 'Google Cloud Scheduler',
+        fieldCount: { min: 5, max: 5 },
+        supportsSeconds: false,
+        supportsYear: false,
+        supportsNamedMonths: true,
+        supportsNamedWeekdays: true,
+        supportsQuestionMark: false,
+        supportsLast: false,
+        supportsNearestWeekday: false,
+        supportsNthWeekday: false,
+        timezoneMode: 'external-field',
+        dayOfMonthDayOfWeekRule: 'unix-or',
+        examples: ['*/5 * * * *', '0 9 * * MON-FRI'],
+    },
+};
+function getCronDialectDefinition(dialect) {
+    return CRON_DIALECTS[dialect];
+}
+
+function normalizeScheduleValue(value, options = {}) {
+    if (value == null || value === '') {
+        return {
+            config: null,
+            diagnostics: [],
+        };
+    }
+    if (typeof value === 'string') {
+        return normalizeCronString(value, options);
+    }
+    return normalizeScheduleConfig(value, options);
+}
+function inferCronDialect(expression) {
+    const fieldCount = expression.trim().split(/\s+/).filter(Boolean).length;
+    return fieldCount === 6 ? 'quartz' : 'unix';
+}
+function normalizeCronString(cron, options) {
+    const trimmed = cron.trim();
+    const dialect = options.dialect ?? inferCronDialect(trimmed);
+    const diagnostics = createCronDiagnostics(trimmed, dialect);
+    return {
+        config: {
+            version: SCHEDULE_AUTHORING_CONFIG_VERSION,
+            kind: 'customCron',
+            timezone: options.timezone ?? 'UTC',
+            locale: options.locale,
+            expression: {
+                cron: trimmed,
+                dialect,
+                seconds: trimmed.split(/\s+/).length === 6 && dialect !== 'aws-eventbridge',
+            },
+            preview: {
+                occurrences: options.previewOccurrences ?? 5,
+            },
+        },
+        diagnostics,
+    };
+}
+function normalizeScheduleConfig(config, options) {
+    const normalized = {
+        ...config,
+        version: SCHEDULE_AUTHORING_CONFIG_VERSION,
+        timezone: config.timezone || options.timezone || 'UTC',
+        locale: config.locale ?? options.locale,
+        preview: {
+            occurrences: options.previewOccurrences ?? config.preview?.occurrences ?? 5,
+            from: config.preview?.from,
+        },
+    };
+    return {
+        config: normalized,
+        diagnostics: normalized.expression?.cron
+            ? createCronDiagnostics(normalized.expression.cron, normalized.expression.dialect)
+            : [],
+    };
+}
+function createCronDiagnostics(cron, dialect) {
+    const diagnostics = [];
+    const fieldCount = cron.trim().split(/\s+/).filter(Boolean).length;
+    if (dialect === 'aws-eventbridge' && fieldCount !== 6) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'cron.aws.fieldCount',
+            field: 'expression.cron',
+            message: 'AWS EventBridge schedules require six fields.',
+            suggestion: 'Use the AWS order: minutes hours day-of-month month day-of-week year.',
+        });
+    }
+    else if (dialect !== 'aws-eventbridge' && !isValidCronExpression(cron)) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'cron.invalid',
+            field: 'expression.cron',
+            message: 'Invalid CRON expression for the selected dialect.',
+            suggestion: 'Check field count, ranges, steps and unsupported special characters.',
+        });
+    }
+    if (dialect === 'unix' && fieldCount !== 5) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'cron.unix.fieldCount',
+            field: 'expression.cron',
+            message: 'Unix cron schedules require five fields.',
+            suggestion: 'Remove seconds or year fields, or select a dialect that supports them.',
+        });
+    }
+    if (dialect === 'quartz' && fieldCount < 6) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'cron.quartz.fieldCount',
+            field: 'expression.cron',
+            message: 'Quartz cron commonly uses seconds as the first field.',
+            suggestion: 'Add a seconds field or select the Unix dialect.',
+        });
+    }
+    return diagnostics;
+}
+
+function compileScheduleExpression(config) {
+    const diagnostics = [];
+    const dialect = config.expression?.dialect ?? 'unix';
+    if (config.kind === 'customCron') {
+        if (!config.expression?.cron) {
+            diagnostics.push(createDiagnostic('error', 'schedule.cron.required', 'expression.cron', 'A CRON expression is required for custom schedules.'));
+            return { expression: null, diagnostics };
+        }
+        const seconds = config.expression.seconds ?? config.expression.cron.trim().split(/\s+/).length === 6;
+        return {
+            expression: {
+                cron: config.expression.cron.trim(),
+                dialect,
+                seconds,
+            },
+            diagnostics,
+        };
+    }
+    if (config.kind === 'once') {
+        diagnostics.push(createDiagnostic('warning', 'schedule.once.noCron', 'kind', 'One-time schedules do not have a portable CRON representation.'));
+        return { expression: null, diagnostics };
+    }
+    if (config.kind === 'interval') {
+        return compileIntervalSchedule(config, dialect);
+    }
+    if (config.kind === 'daily') {
+        return compileDailySchedule(config, dialect);
+    }
+    if (config.kind === 'weekly') {
+        return compileWeeklySchedule(config, dialect);
+    }
+    if (config.kind === 'monthly') {
+        return compileMonthlySchedule(config, dialect);
+    }
+    diagnostics.push(createDiagnostic('error', 'schedule.kind.unsupported', 'kind', 'Unsupported schedule kind.'));
+    return { expression: null, diagnostics };
+}
+function validateScheduleAuthoringConfig(config) {
+    const compiled = compileScheduleExpression(config);
+    const diagnostics = [...compiled.diagnostics];
+    if (compiled.expression && compiled.expression.dialect !== 'aws-eventbridge' && !isValidCronExpression(compiled.expression.cron)) {
+        diagnostics.push(createDiagnostic('error', 'schedule.cron.invalid', 'expression.cron', 'The compiled CRON expression is invalid.'));
+    }
+    if (!config.timezone) {
+        diagnostics.push(createDiagnostic('warning', 'schedule.timezone.defaulted', 'timezone', 'Timezone is missing and will default to UTC.'));
+    }
+    if (config.window?.startAt && config.window?.endAt && Date.parse(config.window.startAt) > Date.parse(config.window.endAt)) {
+        diagnostics.push(createDiagnostic('error', 'schedule.window.invalid', 'window', 'The schedule start date must be before the end date.'));
+    }
+    return diagnostics;
+}
+function createSchedulePreview(value, preview = {}) {
+    const normalized = normalizeScheduleValue(value, {
+        timezone: preview.timezone,
+        locale: preview.locale,
+        dialect: preview.dialect,
+        previewOccurrences: preview.occurrences,
+    });
+    const config = normalized.config;
+    if (!config) {
+        return {
+            config: null,
+            expression: null,
+            humanized: '',
+            occurrences: [],
+            diagnostics: normalized.diagnostics,
+        };
+    }
+    const compiled = compileScheduleExpression(config);
+    const diagnostics = mergeDiagnostics([
+        ...normalized.diagnostics,
+        ...validateScheduleAuthoringConfig(config),
+    ]);
+    if (!compiled.expression || diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+        return {
+            config,
+            expression: compiled.expression,
+            humanized: '',
+            occurrences: [],
+            diagnostics,
+        };
+    }
+    const from = preview.from ?? config.preview?.from ?? config.window?.startAt;
+    const count = preview.occurrences ?? config.preview?.occurrences ?? 5;
+    const currentDate = from ? new Date(from) : new Date();
+    const timezone = config.timezone || 'UTC';
+    const occurrences = getNextCronOccurrences(compiled.expression.cron, count, {
+        currentDate,
+        timeZone: timezone,
+    }).map((date) => ({
+        instant: date.toISOString(),
+        localDateTime: formatLocalDateTime(date, timezone, config.locale ?? 'en-US'),
+        timezone,
+    }));
+    return {
+        config,
+        expression: compiled.expression,
+        humanized: humanizeCronExpression(compiled.expression.cron, config.locale ?? 'en-US'),
+        occurrences,
+        diagnostics,
+    };
+}
+function compileIntervalSchedule(config, dialect) {
+    const interval = config.recurrence?.interval;
+    const diagnostics = [];
+    if (!interval || interval.every < 1) {
+        diagnostics.push(createDiagnostic('error', 'schedule.interval.invalid', 'recurrence.interval', 'Interval schedules require a positive interval.'));
+        return { expression: null, diagnostics };
+    }
+    if (interval.unit === 'minutes') {
+        if (interval.every > 59) {
+            diagnostics.push(createDiagnostic('error', 'schedule.interval.minutes.range', 'recurrence.interval.every', 'Minute intervals must be between 1 and 59.'));
+            return { expression: null, diagnostics };
+        }
+        return makeExpression(`*/${interval.every} * * * *`, dialect, false, diagnostics);
+    }
+    if (interval.unit === 'hours') {
+        if (interval.every > 23) {
+            diagnostics.push(createDiagnostic('error', 'schedule.interval.hours.range', 'recurrence.interval.every', 'Hourly intervals must be between 1 and 23.'));
+            return { expression: null, diagnostics };
+        }
+        return makeExpression(`0 */${interval.every} * * *`, dialect, false, diagnostics);
+    }
+    diagnostics.push(createDiagnostic('warning', 'schedule.interval.notPortable', 'recurrence.interval.unit', 'Day and week intervals are not portable CRON schedules without an anchor date.'));
+    return { expression: null, diagnostics };
+}
+function compileDailySchedule(config, dialect) {
+    const daily = config.recurrence?.daily;
+    const diagnostics = validateTimes(daily?.times, 'recurrence.daily.times');
+    if (!daily || diagnostics.length > 0) {
+        return { expression: null, diagnostics };
+    }
+    const time = parseTime(daily.times[0]);
+    const dayOfWeek = daily.onlyWeekdays ? '1-5' : '*';
+    return makeExpression(`${time.minute} ${time.hour} * * ${dayOfWeek}`, dialect, false, diagnostics);
+}
+function compileWeeklySchedule(config, dialect) {
+    const weekly = config.recurrence?.weekly;
+    const diagnostics = validateTimes(weekly?.times, 'recurrence.weekly.times');
+    if (!weekly || diagnostics.length > 0) {
+        return { expression: null, diagnostics };
+    }
+    if (!weekly.daysOfWeek?.length) {
+        diagnostics.push(createDiagnostic('error', 'schedule.weekly.days.required', 'recurrence.weekly.daysOfWeek', 'Weekly schedules require at least one weekday.'));
+        return { expression: null, diagnostics };
+    }
+    const time = parseTime(weekly.times[0]);
+    const days = normalizeWeekdays(weekly.daysOfWeek).join(',');
+    return makeExpression(`${time.minute} ${time.hour} * * ${days}`, dialect, false, diagnostics);
+}
+function compileMonthlySchedule(config, dialect) {
+    const monthly = config.recurrence?.monthly;
+    const diagnostics = validateTimes(monthly?.times, 'recurrence.monthly.times');
+    if (!monthly || diagnostics.length > 0) {
+        return { expression: null, diagnostics };
+    }
+    const time = parseTime(monthly.times[0]);
+    if (monthly.mode === 'dayOfMonth') {
+        if (!monthly.dayOfMonth || monthly.dayOfMonth < 1 || monthly.dayOfMonth > 31) {
+            diagnostics.push(createDiagnostic('error', 'schedule.monthly.day.range', 'recurrence.monthly.dayOfMonth', 'Monthly day must be between 1 and 31.'));
+            return { expression: null, diagnostics };
+        }
+        return makeExpression(`${time.minute} ${time.hour} ${monthly.dayOfMonth} * *`, dialect, false, diagnostics);
+    }
+    if (monthly.mode === 'nthWeekday') {
+        if (!monthly.nth || monthly.weekday == null) {
+            diagnostics.push(createDiagnostic('error', 'schedule.monthly.nth.required', 'recurrence.monthly', 'Nth weekday schedules require nth and weekday.'));
+            return { expression: null, diagnostics };
+        }
+        return makeExpression(`${time.minute} ${time.hour} ? * ${monthly.weekday}#${monthly.nth}`, dialect, false, diagnostics);
+    }
+    diagnostics.push(createDiagnostic('warning', 'schedule.monthly.mode.notPortable', 'recurrence.monthly.mode', 'This monthly mode needs a dialect-specific compiler before it can produce CRON.'));
+    return { expression: null, diagnostics };
+}
+function makeExpression(cron, dialect, seconds, diagnostics) {
+    if (dialect === 'quartz') {
+        return {
+            expression: {
+                cron: seconds ? cron : `0 ${cron}`,
+                dialect,
+                seconds: true,
+            },
+            diagnostics,
+        };
+    }
+    return {
+        expression: {
+            cron,
+            dialect,
+            seconds,
+        },
+        diagnostics,
+    };
+}
+function validateTimes(times, field) {
+    if (!times?.length) {
+        return [createDiagnostic('error', 'schedule.time.required', field, 'At least one time is required.')];
+    }
+    if (times.length > 1) {
+        return [createDiagnostic('warning', 'schedule.time.multiple.unsupported', field, 'Only the first time is compiled in this initial scheduler runtime.')];
+    }
+    const time = parseTime(times[0]);
+    if (time.hour < 0 || time.hour > 23 || time.minute < 0 || time.minute > 59) {
+        return [createDiagnostic('error', 'schedule.time.invalid', field, 'Time must use HH:mm with a 24-hour clock.')];
+    }
+    return [];
+}
+function parseTime(value) {
+    if (!/^\d{2}:\d{2}$/.test(value)) {
+        return { hour: Number.NaN, minute: Number.NaN };
+    }
+    const [hour, minute] = value.split(':').map((part) => Number(part));
+    return { hour, minute };
+}
+function normalizeWeekdays(days) {
+    return Array.from(new Set(days)).sort((a, b) => a - b);
+}
+function formatLocalDateTime(date, timezone, locale) {
+    return new Intl.DateTimeFormat(locale, {
+        timeZone: timezone,
+        dateStyle: 'full',
+        timeStyle: 'long',
+    }).format(date);
+}
+function mergeDiagnostics(diagnostics) {
+    const seen = new Set();
+    return diagnostics.filter((diagnostic) => {
+        const key = `${diagnostic.severity}:${diagnostic.code}:${diagnostic.field ?? ''}:${diagnostic.message}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function createDiagnostic(severity, code, field, message) {
+    return {
+        severity,
+        code,
+        field,
+        message,
+    };
+}
+
 class PdxCronBuilderComponent {
     // Tipos auxiliares para Typed Forms
     fb = inject(NonNullableFormBuilder);
@@ -462,6 +907,9 @@ class PdxCronBuilderComponent {
     destroy$ = new Subject();
     humanized = '';
     preview = [];
+    structuredPreview = [];
+    scheduleConfig = null;
+    scheduleDiagnostics = [];
     error = null;
     // Opções expostas ao template para controle de fluxo moderno
     weekdayLabels = ['Dom', 'Seg', 'Ter', 'Qua', 'Qui', 'Sex', 'Sáb'];
@@ -522,7 +970,7 @@ class PdxCronBuilderComponent {
             .subscribe((tz) => {
             this.metadata.timezone = tz || 'UTC';
             if (typeof this.value === 'string') {
-                this.generatePreview(this.value);
+                this.refreshScheduleState(this.value);
             }
         });
     }
@@ -569,9 +1017,7 @@ class PdxCronBuilderComponent {
         if (emitEvent) {
             this.onChange(cron);
         }
-        this.validate(cron);
-        this.humanize(cron);
-        this.generatePreview(cron);
+        this.refreshScheduleState(cron);
     }
     copyCron() {
         if (typeof this.value === 'string') {
@@ -595,27 +1041,22 @@ class PdxCronBuilderComponent {
             this.syncSimpleForm(cron);
         }
     }
-    validate(cron) {
-        this.error = isValidCronExpression(cron)
-            ? null
-            : this.metadata.validators?.invalidCronMessage || 'Invalid CRON expression';
-    }
-    humanize(cron) {
-        if (this.error) {
-            this.humanized = '';
-            return;
-        }
-        this.humanized = humanizeCronExpression(cron, this.metadata.locale || 'en-US');
-    }
-    generatePreview(cron) {
-        if (this.error || !this.metadata.previewOccurrences) {
-            this.preview = [];
-            return;
-        }
-        this.preview = getNextCronOccurrences(cron, this.metadata.previewOccurrences ?? 5, {
-            currentDate: this.metadata.previewFrom ?? new Date(),
-            timeZone: this.metadata.timezone,
+    refreshScheduleState(cron) {
+        const preview = createSchedulePreview(cron, {
+            occurrences: this.metadata.previewOccurrences ?? 5,
+            from: this.metadata.previewFrom?.toISOString(),
+            timezone: this.metadata.timezone || this.timezoneControl.value || 'UTC',
+            locale: this.metadata.locale || 'en-US',
         });
+        this.scheduleConfig = preview.config;
+        this.scheduleDiagnostics = preview.diagnostics;
+        this.structuredPreview = preview.occurrences;
+        this.humanized = preview.humanized;
+        this.preview = preview.occurrences.map((occurrence) => new Date(occurrence.instant));
+        const error = preview.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        this.error = error
+            ? this.metadata.validators?.invalidCronMessage || error.message || 'Invalid CRON expression'
+            : null;
     }
     parseCronString(cron) {
         const parts = cron.trim().split(/\s+/);
@@ -806,6 +1247,12 @@ const PDX_CRON_BUILDER_DOC_META_LEGACY = {
  */
 const ENUMS = {
     mode: ['simple', 'advanced', 'both'],
+    scheduleKind: ['once', 'interval', 'daily', 'weekly', 'monthly', 'customCron'],
+    cronDialect: ['unix', 'quartz', 'aws-eventbridge', 'kubernetes', 'github-actions', 'gcp-scheduler'],
+    intervalUnit: ['minutes', 'hours', 'days', 'weeks'],
+    monthlyMode: ['dayOfMonth', 'nthWeekday', 'lastDay', 'lastWeekday'],
+    misfirePolicy: ['skip', 'run-late', 'run-once'],
+    concurrencyPolicy: ['allow', 'forbid', 'replace'],
     validationTrigger: ['change', 'blur'],
     errorPosition: ['tooltip', 'inline'],
 };
@@ -816,6 +1263,8 @@ const CRON_BUILDER_AI_CAPABILITIES = {
     notes: [
         'presets[] should be merged by cron or label to avoid replacing all entries.',
         'metadata.previewFrom expects an ISO date string when provided.',
+        'schedule is the canonical scheduler authoring state; value remains the current CRON string compatibility surface.',
+        'Prefer schedule.kind and schedule.recurrence for business intent; use schedule.expression.cron only for custom CRON edits.',
     ],
     capabilities: [
         { path: 'label', category: 'meta', valueKind: 'string', description: 'Field label (if exposed by host).' },
@@ -848,6 +1297,290 @@ const CRON_BUILDER_AI_CAPABILITIES = {
         { path: 'metadata.errorPosition', category: 'ui', valueKind: 'enum', allowedValues: ENUMS.errorPosition, description: 'Error display position.' },
         { path: 'metadata.showInlineErrors', category: 'ui', valueKind: 'boolean', description: 'Show inline errors.' },
         { path: 'metadata.hint', category: 'ui', valueKind: 'string', description: 'Hint text.' },
+        { path: 'schedule', category: 'schedule', valueKind: 'object', description: 'Canonical scheduler authoring config.' },
+        { path: 'schedule.kind', category: 'schedule', valueKind: 'enum', allowedValues: ENUMS.scheduleKind, description: 'Business schedule intent.' },
+        { path: 'schedule.timezone', category: 'i18n', valueKind: 'string', description: 'IANA timezone used by the schedule.' },
+        { path: 'schedule.locale', category: 'i18n', valueKind: 'string', description: 'Locale used by humanized text and preview.' },
+        { path: 'schedule.expression', category: 'dialects', valueKind: 'object', description: 'Technical CRON representation.' },
+        { path: 'schedule.expression.cron', category: 'dialects', valueKind: 'string', description: 'CRON expression for custom or compiled schedules.' },
+        { path: 'schedule.expression.dialect', category: 'dialects', valueKind: 'enum', allowedValues: ENUMS.cronDialect, description: 'CRON dialect family.' },
+        { path: 'schedule.expression.seconds', category: 'dialects', valueKind: 'boolean', description: 'Whether the CRON representation includes seconds.' },
+        { path: 'schedule.recurrence', category: 'recurrence', valueKind: 'object', description: 'Structured recurrence intent.' },
+        { path: 'schedule.recurrence.once.runAt', category: 'recurrence', valueKind: 'string', description: 'ISO date-time for one-time schedules.' },
+        { path: 'schedule.recurrence.interval.every', category: 'recurrence', valueKind: 'number', description: 'Interval amount.' },
+        { path: 'schedule.recurrence.interval.unit', category: 'recurrence', valueKind: 'enum', allowedValues: ENUMS.intervalUnit, description: 'Interval unit.' },
+        { path: 'schedule.recurrence.daily.times', category: 'recurrence', valueKind: 'array', description: 'Daily run times in HH:mm format.' },
+        { path: 'schedule.recurrence.daily.onlyWeekdays', category: 'recurrence', valueKind: 'boolean', description: 'Limit daily schedule to Monday through Friday.' },
+        { path: 'schedule.recurrence.weekly.daysOfWeek', category: 'recurrence', valueKind: 'array', description: 'Weekdays as numbers where 0 is Sunday.' },
+        { path: 'schedule.recurrence.weekly.times', category: 'recurrence', valueKind: 'array', description: 'Weekly run times in HH:mm format.' },
+        { path: 'schedule.recurrence.monthly.mode', category: 'recurrence', valueKind: 'enum', allowedValues: ENUMS.monthlyMode, description: 'Monthly recurrence strategy.' },
+        { path: 'schedule.recurrence.monthly.dayOfMonth', category: 'recurrence', valueKind: 'number', description: 'Day of month for monthly schedules.' },
+        { path: 'schedule.recurrence.monthly.nth', category: 'recurrence', valueKind: 'number', description: 'Nth weekday occurrence in the month.' },
+        { path: 'schedule.recurrence.monthly.weekday', category: 'recurrence', valueKind: 'number', description: 'Weekday for nth weekday monthly schedules.' },
+        { path: 'schedule.recurrence.monthly.times', category: 'recurrence', valueKind: 'array', description: 'Monthly run times in HH:mm format.' },
+        { path: 'schedule.window.startAt', category: 'policy', valueKind: 'string', description: 'ISO start date-time for schedule validity.' },
+        { path: 'schedule.window.endAt', category: 'policy', valueKind: 'string', description: 'ISO end date-time for schedule validity.' },
+        { path: 'schedule.executionPolicy.enabled', category: 'policy', valueKind: 'boolean', description: 'Whether the schedule is active.' },
+        { path: 'schedule.executionPolicy.misfirePolicy', category: 'policy', valueKind: 'enum', allowedValues: ENUMS.misfirePolicy, description: 'Policy for missed scheduled runs.' },
+        { path: 'schedule.executionPolicy.concurrencyPolicy', category: 'policy', valueKind: 'enum', allowedValues: ENUMS.concurrencyPolicy, description: 'Policy for overlapping runs.' },
+        { path: 'schedule.executionPolicy.flexibleWindowMinutes', category: 'policy', valueKind: 'number', description: 'Flexible delivery window in minutes.' },
+        { path: 'schedule.executionPolicy.jitterMinutes', category: 'policy', valueKind: 'number', description: 'Randomized delay window in minutes.' },
+        { path: 'schedule.preview.occurrences', category: 'preview', valueKind: 'number', description: 'Number of occurrences to preview.' },
+        { path: 'schedule.preview.from', category: 'preview', valueKind: 'string', description: 'ISO date-time used as preview start.' },
+        { path: 'schedule.governance.name', category: 'governance', valueKind: 'string', description: 'Schedule name.' },
+        { path: 'schedule.governance.description', category: 'governance', valueKind: 'string', description: 'Schedule description.' },
+        { path: 'schedule.governance.owner', category: 'governance', valueKind: 'string', description: 'Schedule owner.' },
+        { path: 'schedule.governance.tags', category: 'governance', valueKind: 'array', description: 'Governance tags.' },
+        { path: 'diagnostics', category: 'validation', valueKind: 'array', description: 'Read-only structured schedule diagnostics.' },
+        { path: 'preview', category: 'preview', valueKind: 'array', description: 'Read-only structured preview occurrences.' },
+    ],
+};
+
+const cronDialectEnum = ['unix', 'quartz', 'aws-eventbridge', 'kubernetes', 'github-actions', 'gcp-scheduler'];
+const scheduleKindEnum = ['once', 'interval', 'daily', 'weekly', 'monthly', 'customCron'];
+const PRAXIS_CRON_BUILDER_AUTHORING_MANIFEST = {
+    schemaVersion: '1.0.0',
+    componentId: 'pdx-cron-builder',
+    ownerPackage: '@praxisui/cron-builder',
+    configSchemaId: 'CronBuilderMetadata',
+    manifestVersion: '1.0.0',
+    runtimeInputs: [
+        { name: 'metadata', type: 'CronBuilderMetadata', description: 'Builder UI, timezone, locale, presets, validation and preview configuration.' },
+        { name: 'value', type: 'string | ScheduleAuthoringConfig', description: 'Current CRON string compatibility value or canonical schedule authoring config.' },
+        { name: 'disabled', type: 'boolean', description: 'ControlValueAccessor disabled state.' },
+    ],
+    editableTargets: [
+        { kind: 'expression', resolver: 'schedule-expression', description: 'Canonical CRON expression under schedule.expression or legacy value.' },
+        { kind: 'frequency', resolver: 'schedule-kind-and-recurrence', description: 'Business recurrence intent compiled into a canonical expression.' },
+        { kind: 'timezone', resolver: 'schedule-timezone', description: 'IANA timezone used for preview and schedule metadata.' },
+        { kind: 'preview', resolver: 'schedule-preview-config', description: 'Read-only preview generation request for next occurrences.' },
+        { kind: 'validation', resolver: 'schedule-validation-request', description: 'Read-only validation diagnostics request for expression or schedule config.' },
+        { kind: 'preset', resolver: 'cron-preset-by-label-or-expression', description: 'Preset entry in metadata.presets[] or top-level presets[].' },
+    ],
+    operations: [
+        {
+            operationId: 'cron.expression.set',
+            title: 'Set CRON expression',
+            scope: 'global',
+            targetKind: 'expression',
+            target: { kind: 'expression', resolver: 'schedule-expression', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                required: ['cron'],
+                properties: {
+                    cron: { type: 'string' },
+                    dialect: { enum: cronDialectEnum },
+                    seconds: { type: 'boolean' },
+                },
+            },
+            effects: [{ kind: 'merge-object', path: 'schedule.expression' }, { kind: 'set-value', path: 'schedule.kind' }],
+            validators: ['cron-expression-valid', 'cron-dialect-compatible', 'editor-runtime-round-trip'],
+            affectedPaths: ['schedule.kind', 'schedule.expression.cron', 'schedule.expression.dialect', 'schedule.expression.seconds', 'value'],
+            submissionImpact: true,
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'cron.frequency.set',
+            title: 'Set schedule frequency',
+            scope: 'global',
+            targetKind: 'frequency',
+            target: { kind: 'frequency', resolver: 'schedule-kind-and-recurrence', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                required: ['kind', 'recurrence'],
+                properties: {
+                    kind: { enum: scheduleKindEnum },
+                    recurrence: { type: 'object' },
+                    dialect: { enum: cronDialectEnum },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'cron-frequency-to-expression',
+                    handlerContract: {
+                        reads: ['schedule.kind', 'schedule.recurrence', 'schedule.timezone', 'schedule.expression.dialect'],
+                        writes: ['schedule.kind', 'schedule.recurrence', 'schedule.expression', 'value'],
+                        identityKeys: ['schedule.kind'],
+                        inputSchema: {
+                            type: 'object',
+                            required: ['kind', 'recurrence'],
+                            properties: {
+                                kind: { enum: scheduleKindEnum },
+                                recurrence: { type: 'object' },
+                                dialect: { enum: cronDialectEnum },
+                            },
+                        },
+                        failureModes: ['unsupported-kind', 'non-portable-frequency', 'invalid-recurrence', 'cron-compile-failed'],
+                        description: 'Compiles structured recurrence intent through compileScheduleExpression and updates the canonical schedule expression only when diagnostics have no errors.',
+                    },
+                }],
+            validators: ['frequency-maps-to-canonical-expression', 'cron-expression-valid', 'diagnostics-before-patch'],
+            affectedPaths: ['schedule.kind', 'schedule.recurrence', 'schedule.expression', 'value'],
+            submissionImpact: true,
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'cron.timezone.set',
+            title: 'Set schedule timezone',
+            scope: 'global',
+            targetKind: 'timezone',
+            target: { kind: 'timezone', resolver: 'schedule-timezone', ambiguityPolicy: 'fail', required: false },
+            inputSchema: { type: 'object', required: ['timezone'], properties: { timezone: { type: 'string' } } },
+            effects: [{ kind: 'set-value', path: 'schedule.timezone' }, { kind: 'set-value', path: 'metadata.timezone' }],
+            validators: ['timezone-valid', 'preview-matches-expression', 'editor-runtime-round-trip'],
+            affectedPaths: ['schedule.timezone', 'metadata.timezone', 'preview'],
+            submissionImpact: true,
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'cron.preset.apply',
+            title: 'Apply CRON preset',
+            scope: 'global',
+            targetKind: 'preset',
+            target: { kind: 'preset', resolver: 'cron-preset-by-label-or-expression', ambiguityPolicy: 'fail', required: true },
+            inputSchema: {
+                type: 'object',
+                required: ['labelOrCron'],
+                properties: {
+                    labelOrCron: { type: 'string' },
+                    timezone: { type: 'string' },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'cron-preset-apply',
+                    handlerContract: {
+                        reads: ['metadata.presets[]', 'presets[]', 'schedule.timezone', 'metadata.timezone'],
+                        writes: ['schedule.kind', 'schedule.expression', 'schedule.timezone', 'value'],
+                        identityKeys: ['metadata.presets[].label', 'metadata.presets[].cron', 'presets[].label', 'presets[].cron'],
+                        inputSchema: {
+                            type: 'object',
+                            required: ['labelOrCron'],
+                            properties: {
+                                labelOrCron: { type: 'string' },
+                                timezone: { type: 'string' },
+                            },
+                        },
+                        failureModes: ['preset-not-found', 'preset-cron-invalid', 'timezone-invalid'],
+                        description: 'Resolves a preset by label or cron, validates it through normalizeScheduleValue/createSchedulePreview, then applies the canonical expression.',
+                    },
+                }],
+            validators: ['preset-exists', 'preset-maps-to-canonical-expression', 'cron-expression-valid'],
+            affectedPaths: ['schedule.kind', 'schedule.expression', 'schedule.timezone', 'value'],
+            submissionImpact: true,
+            preconditions: ['config-initialized', 'target-preset-exists'],
+        },
+        {
+            operationId: 'cron.validate',
+            title: 'Validate schedule',
+            scope: 'global',
+            targetKind: 'validation',
+            target: { kind: 'validation', resolver: 'schedule-validation-request', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    cron: { type: 'string' },
+                    schedule: { type: 'object' },
+                    timezone: { type: 'string' },
+                    dialect: { enum: cronDialectEnum },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'cron-validation-diagnostics',
+                    handlerContract: {
+                        reads: ['value', 'schedule', 'metadata.timezone'],
+                        writes: ['diagnostics'],
+                        identityKeys: ['schedule.expression.cron', 'schedule.timezone'],
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                cron: { type: 'string' },
+                                schedule: { type: 'object' },
+                                timezone: { type: 'string' },
+                                dialect: { enum: cronDialectEnum },
+                            },
+                        },
+                        failureModes: ['invalid-expression', 'invalid-timezone', 'invalid-recurrence'],
+                        description: 'Runs normalizeScheduleValue and validateScheduleAuthoringConfig and returns diagnostics without mutating schedule/value paths.',
+                    },
+                }],
+            validators: ['invalid-schedules-return-diagnostics', 'cron-expression-valid', 'timezone-valid'],
+            affectedPaths: ['diagnostics'],
+            submissionImpact: false,
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'cron.preview.generate',
+            title: 'Generate schedule preview',
+            scope: 'global',
+            targetKind: 'preview',
+            target: { kind: 'preview', resolver: 'schedule-preview-config', ambiguityPolicy: 'fail', required: false },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    occurrences: { type: 'number' },
+                    from: { type: 'string' },
+                    timezone: { type: 'string' },
+                    locale: { type: 'string' },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'cron-preview-generate',
+                    handlerContract: {
+                        reads: ['value', 'schedule', 'metadata.previewOccurrences', 'metadata.previewFrom', 'metadata.timezone', 'metadata.locale'],
+                        writes: ['preview', 'diagnostics'],
+                        identityKeys: ['schedule.expression.cron', 'schedule.timezone', 'metadata.previewFrom'],
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                occurrences: { type: 'number' },
+                                from: { type: 'string' },
+                                timezone: { type: 'string' },
+                                locale: { type: 'string' },
+                            },
+                        },
+                        failureModes: ['invalid-expression', 'invalid-timezone', 'preview-empty', 'diagnostics-contain-errors'],
+                        description: 'Runs createSchedulePreview and returns read-only preview occurrences plus diagnostics; it does not patch the schedule when validation fails.',
+                    },
+                }],
+            validators: ['preview-matches-expression', 'timezone-valid', 'invalid-schedules-return-diagnostics'],
+            affectedPaths: ['preview', 'diagnostics'],
+            submissionImpact: false,
+            preconditions: ['config-initialized'],
+        },
+    ],
+    validators: [
+        { validatorId: 'cron-expression-valid', level: 'error', code: 'PCRON001', description: 'CRON expressions must pass the canonical cron-runtime parser for the selected dialect before schedule/value paths are patched.' },
+        { validatorId: 'cron-dialect-compatible', level: 'error', code: 'PCRON002', description: 'Field count, seconds support and dialect-specific rules must match CRON_DIALECTS.' },
+        { validatorId: 'timezone-valid', level: 'error', code: 'PCRON003', description: 'Timezone must be a valid IANA timezone accepted by Intl.DateTimeFormat and schedule preview.' },
+        { validatorId: 'frequency-maps-to-canonical-expression', level: 'error', code: 'PCRON004', description: 'Structured frequency intent must compile through compileScheduleExpression into the canonical expression when portable.' },
+        { validatorId: 'preset-exists', level: 'error', code: 'PCRON005', description: 'Preset operations must resolve an existing preset by label or cron expression.' },
+        { validatorId: 'preset-maps-to-canonical-expression', level: 'error', code: 'PCRON006', description: 'Preset cron values must normalize into ScheduleAuthoringConfig and a valid canonical expression.' },
+        { validatorId: 'preview-matches-expression', level: 'error', code: 'PCRON007', description: 'Preview occurrences must be generated from the same expression, timezone and from-date requested by authoring.' },
+        { validatorId: 'invalid-schedules-return-diagnostics', level: 'error', code: 'PCRON008', description: 'Validation and preview requests for invalid schedules must return diagnostics and must not patch schedule/value fields.' },
+        { validatorId: 'diagnostics-before-patch', level: 'error', code: 'PCRON009', description: 'Operations that compile recurrence or presets must evaluate diagnostics before mutating canonical schedule/value paths.' },
+        { validatorId: 'editor-runtime-round-trip', level: 'error', code: 'PCRON010', description: 'ControlValueAccessor, runtime preview and AI adapter snapshots must preserve expression and timezone.' },
+    ],
+    roundTripRequirements: [
+        'Expression and timezone edits must round-trip through ControlValueAccessor, normalizeScheduleValue and createSchedulePreview without losing the selected timezone.',
+        'Structured frequency authoring must use ScheduleAuthoringConfig and compileScheduleExpression as the canonical source of recurrence semantics.',
+        'Validation and preview operations are read-only: invalid schedules return diagnostics and must not mutate schedule/value paths.',
+        'Preset operations must resolve stable label/cron identities and validate the resulting expression before applying it.',
+        'Preview generation must use the same expression, timezone, locale, occurrences and from-date that are visible in the schedule config or metadata input.',
+    ],
+    examples: [
+        { id: 'weekday-0800', request: 'Run every weekday at 08:00.', operationId: 'cron.frequency.set', params: { kind: 'daily', recurrence: { daily: { times: ['08:00'], onlyWeekdays: true } }, dialect: 'unix' }, isPositive: true },
+        { id: 'every-15-minutes', request: 'Run every 15 minutes.', operationId: 'cron.frequency.set', params: { kind: 'interval', recurrence: { interval: { every: 15, unit: 'minutes' } }, dialect: 'unix' }, isPositive: true },
+        { id: 'monthly-first-day', request: 'Run monthly on the first day at 09:00.', operationId: 'cron.frequency.set', params: { kind: 'monthly', recurrence: { monthly: { mode: 'dayOfMonth', dayOfMonth: 1, times: ['09:00'] } }, dialect: 'unix' }, isPositive: true },
+        { id: 'set-explicit-expression', request: 'Use cron expression 0 8 * * 1-5.', operationId: 'cron.expression.set', params: { cron: '0 8 * * 1-5', dialect: 'unix', seconds: false }, isPositive: true },
+        { id: 'change-timezone-preview', request: 'Change timezone to America/Sao_Paulo and preview the next runs.', operationId: 'cron.timezone.set', params: { timezone: 'America/Sao_Paulo' }, isPositive: true },
+        { id: 'preview-next-five', request: 'Preview the next five runs from 2026-04-20T00:00:00Z.', operationId: 'cron.preview.generate', params: { occurrences: 5, from: '2026-04-20T00:00:00.000Z', timezone: 'UTC' }, isPositive: true },
+        { id: 'apply-business-hours-preset', request: 'Apply the business hours preset.', operationId: 'cron.preset.apply', target: 'business hours', params: { labelOrCron: 'business hours' }, isPositive: true },
+        { id: 'reject-impossible-expression', request: 'Use cron expression 99 99 * * *.', operationId: 'cron.expression.set', params: { cron: '99 99 * * *', dialect: 'unix' }, isPositive: false },
+        { id: 'diagnose-invalid-expression', request: 'Validate 99 99 * * * and explain why it is invalid.', operationId: 'cron.validate', params: { cron: '99 99 * * *', dialect: 'unix' }, isPositive: true },
+        { id: 'reject-invalid-timezone', request: 'Change timezone to Mars/Olympus.', operationId: 'cron.timezone.set', params: { timezone: 'Mars/Olympus' }, isPositive: false },
     ],
 };
 
@@ -859,4 +1592,4 @@ const CRON_BUILDER_AI_CAPABILITIES = {
  * Generated bundle index. Do not edit.
  */
 
-export { CRON_BUILDER_AI_CAPABILITIES, PDX_CRON_BUILDER_DOC_META_LEGACY, PdxCronBuilderComponent };
+export { CRON_BUILDER_AI_CAPABILITIES, CRON_DIALECTS, PDX_CRON_BUILDER_DOC_META_LEGACY, PRAXIS_CRON_BUILDER_AUTHORING_MANIFEST, PdxCronBuilderComponent, SCHEDULE_AUTHORING_CONFIG_VERSION, compileScheduleExpression, createSchedulePreview, getCronDialectDefinition, inferCronDialect, normalizeScheduleValue, validateScheduleAuthoringConfig };

package/index.d.ts

@@ -2,7 +2,150 @@ import * as i0 from '@angular/core';
 import { OnInit, OnDestroy } from '@angular/core';
 import { ControlValueAccessor, FormGroup, FormControl } from '@angular/forms';
 import { MatTabChangeEvent } from '@angular/material/tabs';
-import { AiCapabilityCategory, AiValueKind, AiCapability, AiCapabilityCatalog } from '@praxisui/core';
+import { AiCapabilityCategory, AiValueKind, AiCapability, AiCapabilityCatalog, ComponentAuthoringManifest } from '@praxisui/core';
+
+declare const SCHEDULE_AUTHORING_CONFIG_VERSION: "v1";
+type ScheduleAuthoringConfigVersion = typeof SCHEDULE_AUTHORING_CONFIG_VERSION;
+type CronDialect = 'unix' | 'quartz' | 'aws-eventbridge' | 'kubernetes' | 'github-actions' | 'gcp-scheduler';
+type ScheduleKind = 'once' | 'interval' | 'daily' | 'weekly' | 'monthly' | 'customCron';
+type ScheduleTimeUnit = 'minutes' | 'hours' | 'days' | 'weeks';
+type ScheduleWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+type ScheduleSeverity = 'error' | 'warning' | 'info';
+interface CronDialectDefinition {
+    dialect: CronDialect;
+    label: string;
+    fieldCount: {
+        min: number;
+        max: number;
+    };
+    supportsSeconds: boolean;
+    supportsYear: boolean;
+    supportsNamedMonths: boolean;
+    supportsNamedWeekdays: boolean;
+    supportsQuestionMark: boolean;
+    supportsLast: boolean;
+    supportsNearestWeekday: boolean;
+    supportsNthWeekday: boolean;
+    timezoneMode: 'external-field' | 'host-local' | 'fixed-utc' | 'expression-prefix-unsupported';
+    dayOfMonthDayOfWeekRule: 'either-or-question-mark' | 'unix-or' | 'host-specific';
+    examples: readonly string[];
+}
+interface ScheduleDiagnostic {
+    severity: ScheduleSeverity;
+    code: string;
+    field?: string;
+    message: string;
+    suggestion?: string;
+}
+interface ScheduleCronExpression {
+    cron: string;
+    dialect: CronDialect;
+    seconds?: boolean;
+}
+interface OnceSchedule {
+    runAt: string;
+}
+interface IntervalSchedule {
+    every: number;
+    unit: ScheduleTimeUnit;
+}
+interface DailySchedule {
+    times: string[];
+    onlyWeekdays?: boolean;
+}
+interface WeeklySchedule {
+    daysOfWeek: ScheduleWeekday[];
+    times: string[];
+}
+interface MonthlySchedule {
+    mode: 'dayOfMonth' | 'nthWeekday' | 'lastDay' | 'lastWeekday';
+    dayOfMonth?: number;
+    nth?: 1 | 2 | 3 | 4 | 5;
+    weekday?: ScheduleWeekday;
+    times: string[];
+}
+interface ScheduleRecurrence {
+    once?: OnceSchedule;
+    interval?: IntervalSchedule;
+    daily?: DailySchedule;
+    weekly?: WeeklySchedule;
+    monthly?: MonthlySchedule;
+}
+interface ScheduleWindow {
+    startAt?: string;
+    endAt?: string;
+}
+interface ScheduleExecutionPolicy {
+    enabled?: boolean;
+    misfirePolicy?: 'skip' | 'run-late' | 'run-once';
+    concurrencyPolicy?: 'allow' | 'forbid' | 'replace';
+    flexibleWindowMinutes?: number;
+    jitterMinutes?: number;
+}
+interface SchedulePreviewConfig {
+    occurrences?: number;
+    from?: string;
+}
+interface ScheduleGovernance {
+    name?: string;
+    description?: string;
+    owner?: string;
+    tags?: string[];
+}
+interface ScheduleAuthoringConfig {
+    version: ScheduleAuthoringConfigVersion;
+    kind: ScheduleKind;
+    timezone: string;
+    locale?: string;
+    expression?: ScheduleCronExpression;
+    recurrence?: ScheduleRecurrence;
+    window?: ScheduleWindow;
+    executionPolicy?: ScheduleExecutionPolicy;
+    preview?: SchedulePreviewConfig;
+    governance?: ScheduleGovernance;
+}
+declare const CRON_DIALECTS: Record<CronDialect, CronDialectDefinition>;
+declare function getCronDialectDefinition(dialect: CronDialect): CronDialectDefinition;
+
+interface ScheduleNormalizeOptions {
+    timezone?: string;
+    locale?: string;
+    dialect?: CronDialect;
+    previewOccurrences?: number;
+}
+interface ScheduleNormalizeResult {
+    config: ScheduleAuthoringConfig | null;
+    diagnostics: ScheduleDiagnostic[];
+}
+type ScheduleInput = string | ScheduleAuthoringConfig | null | undefined;
+declare function normalizeScheduleValue(value: ScheduleInput, options?: ScheduleNormalizeOptions): ScheduleNormalizeResult;
+declare function inferCronDialect(expression: string): CronDialect;
+
+interface CompiledScheduleExpression {
+    cron: string;
+    dialect: CronDialect;
+    seconds: boolean;
+}
+interface SchedulePreviewOccurrence {
+    instant: string;
+    localDateTime: string;
+    timezone: string;
+}
+interface SchedulePreviewResult {
+    config: ScheduleAuthoringConfig | null;
+    expression: CompiledScheduleExpression | null;
+    humanized: string;
+    occurrences: SchedulePreviewOccurrence[];
+    diagnostics: ScheduleDiagnostic[];
+}
+interface CreateSchedulePreviewOptions extends SchedulePreviewConfig, Pick<ScheduleNormalizeOptions, 'timezone' | 'locale' | 'dialect'> {
+}
+declare function compileScheduleExpression(config: ScheduleAuthoringConfig): {
+    expression: CompiledScheduleExpression | null;
+    diagnostics: ScheduleDiagnostic[];
+};
+declare function validateScheduleAuthoringConfig(config: ScheduleAuthoringConfig): ScheduleDiagnostic[];
+declare function createSchedulePreview(value: string | ScheduleAuthoringConfig | null | undefined, preview?: CreateSchedulePreviewOptions): SchedulePreviewResult;
 
 interface Recurrence {
 }
@@ -70,6 +213,9 @@ declare class PdxCronBuilderComponent implements ControlValueAccessor, OnInit, O
     private readonly destroy$;
     humanized: string;
     preview: Date[];
+    structuredPreview: SchedulePreviewOccurrence[];
+    scheduleConfig: ScheduleAuthoringConfig | null;
+    scheduleDiagnostics: ScheduleDiagnostic[];
     error: string | null;
     readonly weekdayLabels: readonly ["Dom", "Seg", "Ter", "Qua", "Qui", "Sex", "Sáb"];
     readonly weeklyDayOptions: readonly [0, 1, 2, 3, 4, 5, 6];
@@ -91,9 +237,7 @@ declare class PdxCronBuilderComponent implements ControlValueAccessor, OnInit, O
     copyCron(): void;
     copyHumanized(): void;
     importCron(): void;
-    private validate;
-    private humanize;
-    private generatePreview;
+    private refreshScheduleState;
     private parseCronString;
     private syncSimpleForm;
     private buildCronFromSimple;
@@ -116,9 +260,14 @@ declare const PDX_CRON_BUILDER_DOC_META_LEGACY: any;
 declare module '@praxisui/core' {
     interface AiCapabilityCategoryMap {
         meta: true;
+        schedule: true;
+        recurrence: true;
+        dialects: true;
         fields: true;
         presets: true;
+        policy: true;
         preview: true;
+        governance: true;
         i18n: true;
         ui: true;
     }
@@ -133,5 +282,7 @@ interface CapabilityCatalog extends AiCapabilityCatalog {
 }
 declare const CRON_BUILDER_AI_CAPABILITIES: CapabilityCatalog;
 
-export { CRON_BUILDER_AI_CAPABILITIES, PDX_CRON_BUILDER_DOC_META_LEGACY, PdxCronBuilderComponent };
-export type { AdvancedCronFormValue, Capability, CapabilityCatalog, CapabilityCategory, CronBuilderMetadata, CronPresetType, Recurrence, SimpleCronFormValue, ValueKind };
+declare const PRAXIS_CRON_BUILDER_AUTHORING_MANIFEST: ComponentAuthoringManifest;
+
+export { CRON_BUILDER_AI_CAPABILITIES, CRON_DIALECTS, PDX_CRON_BUILDER_DOC_META_LEGACY, PRAXIS_CRON_BUILDER_AUTHORING_MANIFEST, PdxCronBuilderComponent, SCHEDULE_AUTHORING_CONFIG_VERSION, compileScheduleExpression, createSchedulePreview, getCronDialectDefinition, inferCronDialect, normalizeScheduleValue, validateScheduleAuthoringConfig };
+export type { AdvancedCronFormValue, Capability, CapabilityCatalog, CapabilityCategory, CompiledScheduleExpression, CreateSchedulePreviewOptions, CronBuilderMetadata, CronDialect, CronDialectDefinition, CronPresetType, DailySchedule, IntervalSchedule, MonthlySchedule, OnceSchedule, Recurrence, ScheduleAuthoringConfig, ScheduleAuthoringConfigVersion, ScheduleCronExpression, ScheduleDiagnostic, ScheduleExecutionPolicy, ScheduleGovernance, ScheduleInput, ScheduleKind, ScheduleNormalizeOptions, ScheduleNormalizeResult, SchedulePreviewConfig, SchedulePreviewOccurrence, SchedulePreviewResult, ScheduleRecurrence, ScheduleSeverity, ScheduleTimeUnit, ScheduleWeekday, ScheduleWindow, SimpleCronFormValue, ValueKind, WeeklySchedule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/cron-builder",
-  "version": "8.0.0-beta.0",
+  "version": "8.0.0-beta.11",
   "description": "Cron expression builder utilities and components for Praxis UI.",
   "peerDependencies": {
     "@angular/common": "^20.1.0",
@@ -8,7 +8,7 @@
     "@angular/forms": "^20.1.0",
     "@angular/cdk": "^20.1.0",
     "@angular/material": "^20.1.0",
-    "@praxisui/core": "^8.0.0-beta.0"
+    "@praxisui/core": "^8.0.0-beta.11"
   },
   "dependencies": {
     "tslib": "^2.3.0",