ScheduleBuilder

A recurrence-definition control. Users author a schedule via friendly presets (every N minutes/hours, daily, weekly on selected days, or monthly on a day), raw five-field cron, or a fixed interval — all three authoring modes lower to the same portable emitted value: { mode: 'cron', expression } or { mode: 'interval', every, unit }. mode: 'preset' never appears in the emitted value; presets are sugar.

ScheduleBuilder ships no date, cron-parsing, or scheduling library. The always-visible "next N fires" preview is entirely consumer-supplied via computeNextFires, and the preview section is not rendered at all when that prop is omitted. Scope is recurrence only — overlap policy, jitter, and backfill belong to the consumer's surrounding form.

Usage

<script lang="ts">
  import ScheduleBuilder from '@lostgradient/cinder/schedule-builder';
  import type { ScheduleFire, ScheduleValue } from '@lostgradient/cinder/schedule-builder';

  let value = $state<ScheduleValue>({ mode: 'interval', every: 15, unit: 'minutes' });

  // Cinder ships no date math — bring your own cron/interval library here.
  // Labels are illustrative; a real implementation would compute actual fire times.
  function computeNextFires(current: ScheduleValue, count: number): ScheduleFire[] {
    if (current.mode === 'interval') {
      return Array.from({ length: count }, (_, index) => ({
        id: `fire-${index}`,
        label: `In ${(index + 1) * current.every} ${current.unit}`,
      }));
    }
    return Array.from({ length: count }, (_, index) => ({
      id: `fire-${index}`,
      label: `Next occurrence ${index + 1}`,
    }));
  }
</script>

<ScheduleBuilder
  {value}
  onchange={(next) => (value = next)}
  {computeNextFires}
  timezoneLabel="America/New_York"
  label="Job schedule"
/>

Authoring modes

Three modes live behind a tablist (Presets, Cron, Interval); presets is the default.

• Presets — a preset-kind selector (Every N / Daily / Weekly / Monthly) reveals the matching fields. Every N lowers to an interval value; Daily, Weekly, and Monthly lower to a cron value.
• Cron — five separate fields (minute, hour, day of month, month, day of week), each validated independently with an inline error and hint. The emitted value is the joined five-field expression.
• Interval — a number and a unit (minutes / hours / days / weeks).

Switching modes never emits a change by itself — it re-seeds the destination mode's fields from the last value you actually committed, losslessly where representable. A minute or hour interval converts to an equivalent cron step only when the count evenly divides its field cycle (e.g. */15 * * * *); day/week intervals and non-dividing minute/hour intervals (like every 45 minutes) are not faithfully representable as a cron step, so Cron mode seeds a neutral daily default rather than a misleading expression. A cron pattern converts back to an interval only when it is such a dividing step pattern.

Regardless of mode, three things are always visible: a plain-English summary line, the next-fires preview (when computeNextFires is supplied), and a timezone display slot (timezone snippet, else timezoneLabel text, else a "Not set" placeholder).