Referencia de la API

Esta referencia cubre la API que se usa en estas guías, tal como está implementada en la versión 0.1.0. Todo, salvo la sección API de Lite, pertenece a SuperScheduler Pro (super-scheduler). Los valores por defecto son los que usa el control cuando omites una opción; «ninguno» significa que la opción no tiene valor hasta que le das uno. Las guías explican cómo combinar estas piezas; los ejemplos las muestran en aplicaciones que funcionan.

Algunas convenciones se cumplen en todas partes:

• DateInput es SuperScheduler.Date | string. Las cadenas son valores civiles ISO 8601 con segundos ('2026-10-01T14:00:00') o fechas ('2026-10-01'). El final de los eventos es exclusivo.
• Los ids de recursos, eventos y vínculos son string | number y se comparan de forma estricta: 1 y '1' son distintos.
• Las opciones son props de SuperSchedulerComponent, claves de control.update(options) y propiedades vivas del control.
• Los handlers se ejecutan con this apuntando al control. Sus valores de retorno se ignoran, y un handler async no se espera: usa el protocolo async y loaded() donde exista.

#Puntos de entrada

Todos los puntos de entrada incluyen ESM, CommonJS y declaraciones de tipos. React 18.2 o posterior, o 19, es una dependencia peer (también React DOM en Pro); no hay dependencias en tiempo de ejecución. Todos los módulos se pueden importar en un servidor sin DOM.

#Componentes

#SuperSchedulerComponent

SuperSchedulerComponent aloja un control. Sus props (SchedulerProps) son todas las opciones y handlers de abajo, más controlRef. Renderiza un <div> sin estilos, no tiene props className, style ni id, y solo reenvía a control.update() las props cuya identidad ha cambiado desde el último render; una prop que desaparece vuelve a su valor por defecto.

El componente de super-scheduler/react-render acepta las mismas props, más renderEvent, renderCell, renderRowHeader, renderTimeHeader, renderArea, renderCorner, eventHover, los handlers onBefore*DomAdd y onBefore*DomRemove, y renderOptions (consulta react-render).

import { useEffect, useRef } from 'react'
import { SuperScheduler, SuperSchedulerComponent, useSchedulerControl } from 'super-scheduler'
import { useScheduler } from 'super-scheduler/hooks'

const CONFIG = {
  startDate: '2026-10-01',
  days: 31,
  scale: 'Day',
} satisfies SuperScheduler.SchedulerConfig

// 1. A class ref: `ref.current.control` exists after mount.
export function WithRef() {
  const ref = useRef<SuperSchedulerComponent>(null)
  useEffect(() => ref.current?.control.scrollTo('2026-10-15', true, 'middle'), [])
  return <SuperSchedulerComponent ref={ref} {...CONFIG} />
}

// 2. The control as React state: null until mount, then the live control.
export function WithHook() {
  const { controlRef, control } = useSchedulerControl()
  useEffect(() => control?.scrollTo(SuperScheduler.Date.today()), [control])
  return <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
}

// 3. Control plus tracked state topics, published after changes settle.
export function WithState() {
  const { controlRef, state } = useScheduler({ track: ['zoom', 'viewport'] })
  return (
    <>
      <p>
        {state.viewport === undefined
          ? ''
          : `${state.viewport.start.toString('d MMM')} to ${state.viewport.end.toString('d MMM')}`}
      </p>
      <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
    </>
  )
}

// 4. Imperative, without React: init() before use, dispose() on teardown.
export function mount(host: HTMLElement): () => void {
  const control = new SuperScheduler.Scheduler(host, CONFIG)
  control.init()
  return () => control.dispose()
}

#Tipos

#Formas de los datos

#Eventos

SuperScheduler.EventData<T> no tiene firma de índice: declara los campos adicionales mediante el parámetro de tipo, por ejemplo EventData<{ guest: string }>.

#Recursos

SuperScheduler.ResourceData<T> acepta campos adicionales.

#Vínculos, cabeceras, niveles de zoom y separadores

#Opciones

#Eje de tiempo

#Filas

#Eventos y edición

#Selección

#Zoom y nivel de detalle

#Tamaño y disposición

#Apariencia

#Vínculos

#Teclado

#Menús y burbujas

#Datos, carga y extensiones

#Contenido React

Solo con el SuperSchedulerComponent de super-scheduler/react-render:

#Callbacks

#Convenciones

• Antes y después. onEventMove se ejecuta antes de un cambio y puede cancelarlo; onEventMoved se ejecuta después. La mayoría de las parejas siguen este patrón.
• Cancelación. Los handlers cuyos argumentos tienen preventDefault() pueden cancelar: la familia de los clics, onEventSelect, onEventDelete, onEventMove, onEventResize, onTimeRangeSelect, onTimeRangeClick y sus variantes de doble clic y clic derecho, onRectangleSelect, onRowClick y sus variantes, onRowSelect, onResourceExpand, onResourceCollapse, onTimeHeaderClick, onTimeHeaderRightClick, onGridMouseDown, onKeyDown, onKeyboardFocusChange y onLinkClick. Cancelar un clic también omite su handler terminado en «-ed» y la acción posterior.
• Confirmación asíncrona. onEventMove y onEventResize admiten args.async = true y una llamada posterior a args.loaded(); preventDefault() antes de loaded() cancela, y los newStart, newEnd y newResource asignados antes de loaded() se aplican.
• Guiado. onEventMoving, onEventResizing, onTimeRangeSelecting y onRectangleSelecting se ejecutan en cada cambio de la sombra; asigna args.allowed, args.start, args.end, args.cssClass o args.html.

#Eventos

e es un SuperScheduler.Event: e.data es el objeto de datos, y e.id(), e.start(), e.end(), e.text(), e.resource() y e.duration() lo leen.

#Arrastrar y redimensionar

#Rangos de tiempo y rectángulos

#Filas y cabeceras

#Hooks de render

#Otros handlers

#API del control

El control es ref.current.control, el valor de controlRef, args.control en la mayoría de los handlers, o new SuperScheduler.Scheduler(element, options) seguido de init().

#Ciclo de vida y visualización

#Scroll y área visible

#Eventos

#Filas

#Selección

#Zoom, vínculos, celdas y teclado

#Miembros estáticos

#El namespace SuperScheduler

#Módulos por subpath

#history

createHistory(options?) devuelve un historial que se pasa como history={history} o en extensions. Opciones: limit (50), record (['move', 'resize']), keys ('root', 'document' o false; por defecto 'root'), equals, fields, apply ('control' o una función para eventos controlados) y labels. Métodos: undo(), redo(), clear(), push({ label, undo, redo }), record({ ops, control }), batch(label, run), revert(eventId), subscribe(listener); propiedades canUndo, canRedo, undoLabel, redoLabel. Las cargas y los cambios rechazados no se registran.

#minimap

createMinimap(control, container, options?) y el componente React <SchedulerMinimap control={control} />. Opciones: series (por defecto eventDensity(control)), height (28), peak ('relative' o 'absolute' con max), tone, marks (today, months, past, todos true), range y labels. El widget tiene update(), refresh() y dispose().

#panes

<SchedulerPanes> recibe las props del scheduler, más panes ({ id, resources or rowFilter, size, minSize (48), hidden, props }), un height numérico obligatorio, timeHeader ('first'), scrollbar ('last'), splitter (true), crossPaneMove (true), component, onPaneResize y panesRef. linkPanes(controls, { zoom, rowHeaderWidth }) vincula controles existentes y devuelve { dispose() }.

#zoom-ui

createZoomHud(control, { format, apiMs (700) }), createZoomSlider(control, container, { min, max, detents, scale ('log'), label }) y createLodBadge(control, container, labels?). Cada uno devuelve { element, dispose() }.

#views

getViewState(control, include?) devuelve un estado apto para JSON (zoom, scroll, density, collapsed, columns); applyViewState(control, state, { animate, when, timeout }) (when es 'now' o 'rows') devuelve una promesa de boolean.

#ranges

createRangeLoader({ load, chunkDays (7), prefetch (1), cacheChunks (26), skeleton (true), onError }) devuelve un cargador con reload(range?), clear() y loading. load({ start, end, signal }) devuelve los eventos que se solapan con [start, end).

#hooks

useScheduler({ track }) devuelve { controlRef, control, state } para los temas 'events', 'selection', 'zoom', 'viewport' e 'history'. useSchedulerState(control, topic), subscribeScheduler(control, topic, listener) (devuelve una función para cancelar la suscripción) y getSchedulerSnapshot(control, topic) dan el mismo estado fuera del hook. El estado del área visible se publica cuando el scroll se detiene.

#react-render

SuperSchedulerComponent con las props de contenido React. Primero se pinta el HTML o el texto de respaldo; el contenido React lo sustituye cuando termina la interacción. renderOptions.retain vale por defecto el menor entre 2.000 y el doble de los elementos montados; sliceMs, 8.

#tailwind

Un preset de Tailwind CSS v3: presets: [require('super-scheduler/tailwind')]. Añade colores, radios, sombras y transiciones super-scheduler asociados a los tokens CSS.

#datasets

generateDataset(options) y generateScenario(id, overrides?) crean datos deterministas de tipo hotel (rows y days obligatorios, seed, start en ticks, density, events, times). toSuperSchedulerData(dataset) devuelve { resources, events }. Escenarios: S1 (120 filas, 730 días), S2 (1.000 filas, 730 días), S3 (5.000 filas, 1.500 días) y sus variantes densas. Por defecto, los datos empiezan el 1 de enero de 2026.

#core

Utilidades sin DOM que comparte el motor: SchedulerDate, Duration, registerLocale, resolveLocale, formatTicks, parseTicks, ticksFromParts(year, month, day, ...), partsOf, formatIso, parseIso, todayTicks, nowTicks, las constantes MS_PER_* y utilidades de líneas de tiempo, índices y layout. Úsalo para gráficos y herramientas que acompañan al scheduler.

#API de Lite

super-scheduler-lite es una línea de tiempo diaria de solo lectura. Las opciones que no implementa lanzan SuperScheduler Lite: unsupported option "..." en todos los builds.

El control (ref.current.control) tiene init(), update(options), dispose(), disposed(), scrollTo(date), scrollToResource(id), visibleStart() y visibleEnd(). El namespace tiene SuperScheduler.Date y SuperScheduler.Scheduler. Los children, frozen, split y columns de los recursos se rechazan. Tokens de tema en .super-scheduler-lite: --super-scheduler-background, -text, -border, -header, -event y -focus. Consulta Migrar de Lite a Pro.

#APIs reservadas

Estos miembros tienen tipos para que el código existente compile, pero no están implementados en 0.1.0. No hacen nada, devuelven valores vacíos y muestran super-scheduler: <feature> is not supported yet una vez en los builds de desarrollo.

Implementado en parte:

• treeAnimation se acepta, pero la animación de despliegue nunca se reproduce.
• eventClusters y onClusterClick se aceptan y todavía no tienen ningún efecto visible.
• Los handlers onBefore*DomAdd y onBefore*DomRemove, las props render* y eventHover solo funcionan con el componente de super-scheduler/react-render; el componente raíz avisa y los ignora.

Indicaciones de ajuste que se aceptan pero se ignoran, porque la virtualización siempre está activada y se ajusta sola: beforeCellRenderCaching, cellSweeping, cellSweepingCacheSize, drawBlankCells, dynamicEventRendering y sus opciones de margen y caché, eventUpdateInplaceOptimization, progressiveRowRendering, progressiveRowRenderingPreload y las opciones scrollDelay* distintas de scrollDelayDynamic.