{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "cron-builder", "type": "registry:component", "title": "Cron Builder", "description": "Edit a cron expression field by field or with friendly controls, read it back as a plain sentence, see the next five runs in your timezone update as you type, and get told exactly why a schedule is invalid or can never run.", "categories": [ "component", "Dev Tools" ], "dependencies": [ "lucide-react", "motion" ], "registryDependencies": [ "utils", "https://coss.com/ui/r/tabs.json" ], "files": [ { "path": "registry/devl/cron-builder.tsx", "type": "registry:component", "content": "\"use client\";\n\nimport { AlertCircleIcon, CheckIcon, CopyIcon, MinusIcon, PlusIcon } from \"lucide-react\";\nimport { motion, useReducedMotion } from \"motion/react\";\nimport { type ClipboardEvent, type KeyboardEvent, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport { Tabs, TabsList, TabsTab } from \"@/components/ui/tabs\";\nimport { cn } from \"@/lib/utils\";\n\nexport interface CronBuilderProps {\n defaultValue?: string;\n onChange?: (expression: string, valid: boolean) => void;\n presets?: { label: string; value: string }[];\n className?: string;\n}\n\ntype FieldId = \"minute\" | \"hour\" | \"dom\" | \"month\" | \"dow\";\n\ninterface FieldSpec {\n id: FieldId;\n label: string;\n noun: string;\n plural: string;\n min: number;\n max: number;\n names?: string[];\n}\n\nconst MONTHS = [\"January\", \"February\", \"March\", \"April\", \"May\", \"June\", \"July\", \"August\", \"September\", \"October\", \"November\", \"December\"];\nconst DAYS = [\"Sunday\", \"Monday\", \"Tuesday\", \"Wednesday\", \"Thursday\", \"Friday\", \"Saturday\"];\n\nconst FIELDS: FieldSpec[] = [\n { id: \"minute\", label: \"Minute\", noun: \"minute\", plural: \"minutes\", min: 0, max: 59 },\n { id: \"hour\", label: \"Hour\", noun: \"hour\", plural: \"hours\", min: 0, max: 23 },\n { id: \"dom\", label: \"Day\", noun: \"day of the month\", plural: \"days\", min: 1, max: 31 },\n { id: \"month\", label: \"Month\", noun: \"month\", plural: \"months\", min: 1, max: 12, names: MONTHS.map((m) => m.slice(0, 3).toUpperCase()) },\n { id: \"dow\", label: \"Weekday\", noun: \"weekday\", plural: \"weekdays\", min: 0, max: 6, names: DAYS.map((d) => d.slice(0, 3).toUpperCase()) },\n];\n\nconst DEFAULT_PRESETS = [\n { label: \"Every 15 min\", value: \"*/15 * * * *\" },\n { label: \"Hourly\", value: \"0 * * * *\" },\n { label: \"Daily 09:00\", value: \"0 9 * * *\" },\n { label: \"Weekdays 09:30\", value: \"30 9 * * 1-5\" },\n { label: \"Mondays 08:00\", value: \"0 8 * * 1\" },\n { label: \"1st of month\", value: \"0 0 1 * *\" },\n];\n\nconst MACROS: Record = {\n \"@yearly\": \"0 0 1 1 *\",\n \"@annually\": \"0 0 1 1 *\",\n \"@monthly\": \"0 0 1 * *\",\n \"@weekly\": \"0 0 * * 0\",\n \"@daily\": \"0 0 * * *\",\n \"@midnight\": \"0 0 * * *\",\n \"@hourly\": \"0 * * * *\",\n};\n\ntype Parsed = { values: Set; error?: undefined } | { values?: undefined; error: string };\n\nfunction parseField(raw: string, spec: FieldSpec): Parsed {\n const text = raw.trim();\n const What = spec.label;\n if (!text) return { error: `${What} is empty. Use * for every ${spec.noun}.` };\n const values = new Set();\n const max = spec.id === \"dow\" ? 7 : spec.max;\n const num = (s: string): number | string => {\n const named = spec.names?.indexOf(s.toUpperCase()) ?? -1;\n if (named >= 0) return named + spec.min;\n if (!/^\\d+$/.test(s)) return `“${s}” isn’t a valid ${spec.noun}.`;\n const n = Number(s);\n if (n < spec.min || n > max) return `${What} must be ${spec.min}–${max}; ${n} is out of range.`;\n return n;\n };\n for (const part of text.split(\",\")) {\n if (!part) return { error: `There’s an empty item in “${text}”.` };\n const [range, stepText, extra] = part.split(\"/\");\n if (extra !== undefined) return { error: `“${part}” has more than one step.` };\n let step = 1;\n if (stepText !== undefined) {\n if (!/^\\d+$/.test(stepText)) return { error: `Step “${stepText}” must be a whole number.` };\n step = Number(stepText);\n if (step === 0) return { error: \"A step of 0 never moves forward. Use 1 or more.\" };\n }\n let lo: number;\n let hi: number;\n if (range === \"*\") {\n lo = spec.min;\n hi = spec.max;\n } else if (range.includes(\"-\")) {\n const [a, b] = range.split(\"-\");\n const na = num(a);\n const nb = num(b ?? \"\");\n if (typeof na === \"string\") return { error: na };\n if (typeof nb === \"string\") return { error: nb };\n if (na > nb) return { error: `The range ${a}-${b} runs backwards.` };\n lo = na;\n hi = nb;\n } else {\n const n = num(range);\n if (typeof n === \"string\") return { error: n };\n lo = n;\n hi = stepText !== undefined ? spec.max : n;\n }\n for (let v = lo; v <= hi; v += step) values.add(spec.id === \"dow\" && v === 7 ? 0 : v);\n }\n return { values };\n}\n\nfunction serialize(values: Set, spec: FieldSpec) {\n const sorted = [...values].sort((a, b) => a - b);\n const full = spec.max - spec.min + 1;\n if (sorted.length === full) return \"*\";\n if (sorted.length > 2 && sorted[0] === spec.min) {\n const step = sorted[1] - sorted[0];\n const fits = sorted.every((v, i) => v === spec.min + i * step) && sorted[sorted.length - 1] + step > spec.max && step > 1;\n if (fits) return `*/${step}`;\n }\n const parts: string[] = [];\n let i = 0;\n while (i < sorted.length) {\n let j = i;\n while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++;\n if (j - i >= 2) parts.push(`${sorted[i]}-${sorted[j]}`);\n else for (let k = i; k <= j; k++) parts.push(String(sorted[k]));\n i = j + 1;\n }\n return parts.join(\",\");\n}\n\nconst pad = (n: number) => String(n).padStart(2, \"0\");\n\nfunction list(items: string[]) {\n if (items.length <= 1) return items.join(\"\");\n return `${items.slice(0, -1).join(\", \")} and ${items[items.length - 1]}`;\n}\n\nfunction runs(values: number[], name: (n: number) => string) {\n const out: string[] = [];\n let i = 0;\n while (i < values.length) {\n let j = i;\n while (j + 1 < values.length && values[j + 1] === values[j] + 1) j++;\n if (j - i >= 2) out.push(`${name(values[i])} through ${name(values[j])}`);\n else for (let k = i; k <= j; k++) out.push(name(values[k]));\n i = j + 1;\n }\n return list(out);\n}\n\nfunction stepOf(values: number[], min: number, max: number) {\n if (values.length < 2 || values[0] !== min) return 0;\n const s = values[1] - values[0];\n return values.every((v, i) => v === min + i * s) && values[values.length - 1] + s > max ? s : 0;\n}\n\nfunction describe(sets: Record>, raw: Record) {\n const m = [...sets.minute].sort((a, b) => a - b);\n const h = [...sets.hour].sort((a, b) => a - b);\n const allM = m.length === 60;\n const allH = h.length === 24;\n const mStep = stepOf(m, 0, 59);\n const hStep = stepOf(h, 0, 23);\n let time: string;\n if (allM && allH) time = \"Every minute\";\n else if (mStep && allH) time = `Every ${mStep} minutes`;\n else if (m.length === 1 && allH) time = m[0] === 0 ? \"Every hour, on the hour\" : `At ${m[0]} minutes past every hour`;\n else if (m.length === 1 && hStep) time = `At minute ${m[0]}, every ${hStep} hours`;\n else if (m.length * h.length <= 4 && !allH) time = `At ${list(h.flatMap((hh) => m.map((mm) => `${pad(hh)}:${pad(mm)}`)))}`;\n else if (allH) time = `At minutes ${list(m.map(String))} past every hour`;\n else if (allM) time = `Every minute during ${runs(h, (x) => `${pad(x)}:00`)} hours`;\n else time = `At minutes ${runs(m, String)} past ${runs(h, (x) => `${pad(x)}:00`)}`;\n\n const either = !raw.dom.trim().startsWith(\"*\") && !raw.dow.trim().startsWith(\"*\");\n const domR = sets.dom.size < 31;\n const dowR = sets.dow.size < 7;\n const dom = [...sets.dom].sort((a, b) => a - b);\n const dow = [...sets.dow].sort((a, b) => ((a + 6) % 7) - ((b + 6) % 7));\n const dowSorted = dow.map((d) => (d + 6) % 7);\n const dowWords = () => {\n if (dow.length === 2 && sets.dow.has(0) && sets.dow.has(6)) return \"on weekends\";\n return `on ${runs(dowSorted, (x) => DAYS[(x + 1) % 7])}`;\n };\n const domWords = () => {\n const step = stepOf(dom, 1, 31);\n if (step) return `every ${step} days`;\n return `on day ${runs(dom, String)} of the month`;\n };\n let days = \"\";\n if (domR && dowR) days = `${domWords()} ${either ? \"or\" : \"and\"} ${dowWords()}`;\n else if (domR) days = domWords();\n else if (dowR) days = dowWords();\n\n const mo = [...sets.month].sort((a, b) => a - b);\n let months = \"\";\n if (mo.length < 12) {\n const step = stepOf(mo, 1, 12);\n months = step ? `every ${step} months` : `in ${runs(mo, (x) => MONTHS[x - 1])}`;\n }\n return [time, days, months].filter(Boolean).join(\", \");\n}\n\nfunction nextRuns(sets: Record>, raw: Record, from: Date, count = 5) {\n const out: Date[] = [];\n const hours = [...sets.hour].sort((a, b) => a - b);\n const minutes = [...sets.minute].sort((a, b) => a - b);\n const either = !raw.dom.trim().startsWith(\"*\") && !raw.dow.trim().startsWith(\"*\");\n const start = new Date(from);\n start.setSeconds(0, 0);\n start.setMinutes(start.getMinutes() + 1);\n const day = new Date(start.getFullYear(), start.getMonth(), start.getDate());\n for (let i = 0; i < 366 * 5 && out.length < count; i++) {\n const d = new Date(day.getFullYear(), day.getMonth(), day.getDate() + i);\n if (!sets.month.has(d.getMonth() + 1)) continue;\n const domOk = sets.dom.has(d.getDate());\n const dowOk = sets.dow.has(d.getDay());\n const match = either ? domOk || dowOk : domOk && dowOk;\n if (!match) continue;\n for (const hh of hours) {\n for (const mm of minutes) {\n const t = new Date(d.getFullYear(), d.getMonth(), d.getDate(), hh, mm);\n if (t >= start) out.push(t);\n if (out.length >= count) return out;\n }\n }\n }\n return out;\n}\n\nfunction neverReason(sets: Record>) {\n const minDom = Math.min(...sets.dom);\n const mo = [...sets.month];\n if (mo.every((m) => m === 2) && minDom > 29) return `February never has a ${minDom}${minDom === 31 ? \"st\" : \"th\"}.`;\n if (minDom === 31 && mo.every((m) => [2, 4, 6, 9, 11].includes(m))) return `${list(mo.map((m) => MONTHS[m - 1]))} ${mo.length > 1 ? \"don’t\" : \"doesn’t\"} have a 31st.`;\n return \"No date matches every field at once.\";\n}\n\nconst SHORT_DAYS = [\"Sun\", \"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\"];\nconst SHORT_MONTHS = MONTHS.map((m) => m.slice(0, 3));\nconst when = (d: Date) => `${SHORT_DAYS[d.getDay()]}, ${SHORT_MONTHS[d.getMonth()]} ${d.getDate()}`;\nfunction relative(d: Date, now: number) {\n const mins = Math.round((d.getTime() - now) / 60000);\n if (mins < 60) return `in ${Math.max(1, mins)} min`;\n const hrs = Math.floor(mins / 60);\n const today = new Date(now);\n const days = Math.round(\n (new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime() - new Date(today.getFullYear(), today.getMonth(), today.getDate()).getTime()) / 86400000,\n );\n if (hrs < 12 || days === 0) return `in ${hrs}h ${pad(mins % 60)}m`;\n return days === 1 ? \"tomorrow\" : `in ${days} days`;\n}\n\ntype Mode = \"every\" | \"step\" | \"specific\";\nconst modeOf = (raw: string): Mode => (raw.trim() === \"*\" ? \"every\" : /^\\*\\/\\d+$/.test(raw.trim()) ? \"step\" : \"specific\");\n\nfunction gridFor(spec: FieldSpec, current: Set) {\n if (spec.id === \"minute\") {\n const base = Array.from({ length: 12 }, (_, i) => i * 5);\n return [...new Set([...base, ...current])].sort((a, b) => a - b);\n }\n if (spec.id === \"dow\") return [1, 2, 3, 4, 5, 6, 0];\n return Array.from({ length: spec.max - spec.min + 1 }, (_, i) => spec.min + i);\n}\n\nconst cellLabel = (spec: FieldSpec, v: number) =>\n spec.id === \"month\" ? SHORT_MONTHS[v - 1] : spec.id === \"dow\" ? SHORT_DAYS[v] : spec.id === \"hour\" ? pad(v) : spec.id === \"minute\" ? `:${pad(v)}` : String(v);\n\nexport function CronBuilder({ defaultValue = \"30 9 * * 1-5\", onChange, presets = DEFAULT_PRESETS, className }: CronBuilderProps) {\n const errorId = useId();\n const reduce = useReducedMotion();\n const panelRef = useRef(null);\n const [panelHeight, setPanelHeight] = useState(null);\n const [raw, setRaw] = useState>(() => {\n const parts = (MACROS[defaultValue] ?? defaultValue).trim().split(/\\s+/);\n return { minute: parts[0] ?? \"*\", hour: parts[1] ?? \"*\", dom: parts[2] ?? \"*\", month: parts[3] ?? \"*\", dow: parts[4] ?? \"*\" };\n });\n const [active, setActive] = useState(\"minute\");\n const [now, setNow] = useState(null);\n const [tz, setTz] = useState(\"\");\n const [copied, setCopied] = useState(false);\n const inputs = useRef>({});\n const mounted = useRef(false);\n const changeRef = useRef(onChange);\n changeRef.current = onChange;\n\n useEffect(() => {\n mounted.current = true;\n setNow(Date.now());\n setTz(Intl.DateTimeFormat().resolvedOptions().timeZone.replace(/_/g, \" \"));\n const t = setInterval(() => setNow(Date.now()), 30000);\n return () => clearInterval(t);\n }, []);\n\n useLayoutEffect(() => {\n const el = panelRef.current;\n if (!el) return;\n const ro = new ResizeObserver(() => setPanelHeight(el.offsetHeight));\n ro.observe(el);\n return () => ro.disconnect();\n }, []);\n\n useEffect(() => {\n if (!copied) return;\n const t = setTimeout(() => setCopied(false), 1400);\n return () => clearTimeout(t);\n }, [copied]);\n\n const parsed = useMemo(() => Object.fromEntries(FIELDS.map((f) => [f.id, parseField(raw[f.id], f)])) as Record, [raw]);\n const firstError = FIELDS.find((f) => parsed[f.id].error);\n const sets = firstError ? null : (Object.fromEntries(FIELDS.map((f) => [f.id, parsed[f.id].values])) as Record>);\n const expression = FIELDS.map((f) => raw[f.id].trim() || \"?\").join(\" \");\n const sentence = sets ? describe(sets, raw) : null;\n const runsList = useMemo(() => (sets && now ? nextRuns(sets, raw, new Date(now)) : []), [sets, raw, now]);\n const never = sets && now !== null && runsList.length === 0;\n\n useEffect(() => {\n changeRef.current?.(expression, !firstError);\n }, [expression, firstError]);\n\n const spec = FIELDS.find((f) => f.id === active) ?? FIELDS[0];\n const mode = modeOf(raw[active]);\n const current = parsed[active].values ?? new Set();\n const stepValue = mode === \"step\" ? Number(raw[active].trim().slice(2)) : 0;\n\n const setField = (id: FieldId, value: string) => setRaw((r) => ({ ...r, [id]: value }));\n\n const applyExpression = (text: string) => {\n const parts = (MACROS[text.trim().toLowerCase()] ?? text).trim().split(/\\s+/);\n if (parts.length !== 5) return false;\n setRaw({ minute: parts[0], hour: parts[1], dom: parts[2], month: parts[3], dow: parts[4] });\n return true;\n };\n\n const onPaste = (e: ClipboardEvent) => {\n const text = e.clipboardData.getData(\"text\");\n if (/\\s/.test(text.trim()) || text.trim().startsWith(\"@\")) {\n if (applyExpression(text)) e.preventDefault();\n }\n };\n\n const onFieldKey = (e: KeyboardEvent, i: number) => {\n const el = e.currentTarget;\n const go = (j: number) => {\n const f = FIELDS[j];\n if (!f) return;\n e.preventDefault();\n inputs.current[f.id]?.focus();\n requestAnimationFrame(() => inputs.current[f.id]?.select());\n };\n if (e.key === \" \") go(i + 1);\n else if (e.key === \"ArrowRight\" && el.selectionStart === el.value.length) go(i + 1);\n else if (e.key === \"ArrowLeft\" && el.selectionStart === 0) go(i - 1);\n else if (e.key === \"Backspace\" && el.value === \"\") go(i - 1);\n };\n\n const setMode = (m: Mode) => {\n if (m === \"every\") setField(active, \"*\");\n else if (m === \"step\") setField(active, `*/${active === \"minute\" ? 15 : 2}`);\n else {\n const fallback = active === \"dow\" ? \"1-5\" : active === \"month\" || active === \"dom\" ? \"1\" : \"0\";\n setField(active, current.size && mode === \"specific\" ? raw[active] : fallback);\n }\n };\n\n const toggleValue = (v: number) => {\n const next = new Set(mode === \"specific\" ? current : []);\n if (next.has(v)) next.delete(v);\n else next.add(v);\n setField(active, next.size ? serialize(next, spec) : \"*\");\n };\n\n const grid = gridFor(spec, current);\n const cols = spec.id === \"hour\" ? \"grid-cols-8\" : spec.id === \"dom\" ? \"grid-cols-8\" : spec.id === \"dow\" ? \"grid-cols-7\" : \"grid-cols-6\";\n const canStep = active !== \"dow\";\n const maxStep = Math.floor((spec.max - spec.min + 1) / 2);\n\n return (\n
\n
\n
\n

Schedule

\n

\n {tz ? `Times in ${tz}` : \"Times in your timezone\"}\n · paste any cron line\n

\n
\n {\n try {\n await navigator.clipboard.writeText(expression);\n } catch {}\n setCopied(true);\n }}\n type=\"button\"\n >\n {copied ? : }\n {expression}\n \n
\n\n
\n {FIELDS.map((f, i) => {\n const err = parsed[f.id].error;\n const isActive = f.id === active;\n return (\n \n );\n })}\n
\n\n
\n {firstError ? (\n

\n \n {parsed[firstError.id].error}\n

\n ) : (\n <>\n

{sentence}

\n {never && sets && (\n

\n Never runs: {neverReason(sets)}\n

\n )}\n \n )}\n
\n\n
\n {presets.map((p) => {\n const on = p.value === expression;\n return (\n applyExpression(p.value)}\n type=\"button\"\n >\n {p.label}\n \n );\n })}\n
\n\n
\n
\n {spec.label}\n setMode(v as Mode)} value={mode}>\n \n \n Every\n \n {canStep && (\n \n Every N\n \n )}\n \n Specific\n \n \n \n
\n\n \n
\n \n {mode === \"every\" && (\n

\n Runs every {spec.noun}\n {spec.id === \"dom\" || spec.id === \"dow\" ? \" (unless the other day field narrows it)\" : \"\"}.\n

\n )}\n {mode === \"step\" && (\n
\n Every\n
\n setField(active, `*/${stepValue - 1}`)}\n type=\"button\"\n >\n \n \n {stepValue}\n = maxStep}\n onClick={() => setField(active, `*/${stepValue + 1}`)}\n type=\"button\"\n >\n \n \n
\n {spec.plural}\n
\n )}\n {mode === \"specific\" && (\n
\n {grid.map((v) => {\n const on = current.has(v);\n return (\n toggleValue(v)}\n type=\"button\"\n >\n {cellLabel(spec, v)}\n \n );\n })}\n
\n )}\n \n
\n \n
\n\n
\n

Next runs

\n {firstError || never ? (\n
\n {firstError ? \"Fix the expression to see upcoming runs.\" : \"Nothing scheduled: this expression never matches a real date.\"}\n
\n ) : (\n
    \n {(now === null ? Array.from({ length: 5 }, () => null) : runsList).map((d, i) => (\n
  1. \n {i + 1}\n {d && now !== null ? (\n <>\n \n {when(d)} · {pad(d.getHours())}:{pad(d.getMinutes())}\n \n {relative(d, now)}\n \n ) : (\n \n )}\n
    2. \n ))}\n
\n )}\n
\n
\n );\n}\n" } ] }