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

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,66 @@ 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.
+
+Each operation declares `target.resolver`, `preconditions`, `validators`,
+`affectedPaths`, `effects` and typed `submissionImpact`. Expression, frequency,
+timezone and preset changes affect the submitted schedule value; validation and
+preview generation are diagnostics-only operations with no submission mutation.
+
 ## Build Notes
 
 The builder resolves validation, humanized descriptions and occurrence preview inside the library runtime.