Référence de l’API

Cette référence couvre l’API utilisée dans l’ensemble de ces guides, telle qu’implémentée dans la version 0.1.0. Tout, sauf la section API Lite, appartient à SuperScheduler Pro (super-scheduler). Les valeurs par défaut sont celles que le contrôle utilise quand vous omettez une option ; « aucune » signifie que l’option n’a pas de valeur tant que vous n’en définissez pas. Les guides expliquent comment combiner ces éléments ; les exemples les montrent dans des applications qui fonctionnent.

Quelques conventions valent partout :

• DateInput est SuperScheduler.Date | string. Les chaînes sont des valeurs ISO 8601 civiles avec secondes ('2026-10-01T14:00:00') ou des dates ('2026-10-01'). Les fins d’événements sont exclusives.
• Les id de ressources, d’événements et de liens sont de type string | number et sont comparés strictement : 1 et '1' sont différents.
• Les options sont à la fois des props de SuperSchedulerComponent, des clés de control.update(options) et des propriétés vivantes du contrôle.
• Les handlers s’exécutent avec this lié au contrôle. Leurs valeurs de retour sont ignorées, et un handler async n’est pas attendu : utilisez le protocole async et loaded() là où il existe.

#Points d’entrée

Chaque point d’entrée est livré en ESM et en CommonJS, avec ses déclarations de types. React 18.2 ou ultérieur, ou 19, est une dépendance peer (React DOM aussi pour Pro) ; il n’y a aucune dépendance à l’exécution. Tous les modules peuvent être importés sur un serveur sans DOM.

#Composants

#SuperSchedulerComponent

SuperSchedulerComponent héberge un contrôle. Ses props (SchedulerProps) sont toutes les options et tous les handlers ci-dessous, plus controlRef. Il rend un <div> sans style, n’a pas de props className, style ni id, et ne transmet à control.update() que les props dont l’identité a changé depuis le dernier rendu ; une prop qui disparaît revient à sa valeur par défaut.

Le composant de super-scheduler/react-render accepte les mêmes props, plus renderEvent, renderCell, renderRowHeader, renderTimeHeader, renderArea, renderCorner, eventHover, les handlers onBefore*DomAdd et onBefore*DomRemove, et renderOptions (voir 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()
}

#Types

#Formes des données

#Événements

SuperScheduler.EventData<T> n’a pas de signature d’index : déclarez les champs supplémentaires via le paramètre de type, par exemple EventData<{ guest: string }>.

#Ressources

SuperScheduler.ResourceData<T> accepte des champs supplémentaires.

#Liens, en-têtes, niveaux de zoom et séparateurs

#Options

#Axe du temps

#Lignes

#Événements et édition

#Sélection

#Zoom et niveau de détail

#Taille et disposition

#Apparence

#Liens

#Clavier

#Menus et bulles

#Données, chargement et extensions

#Contenu React

Uniquement avec le SuperSchedulerComponent de super-scheduler/react-render :

#Callbacks

#Conventions

• Avant et après. onEventMove s’exécute avant une modification et peut l’annuler ; onEventMoved s’exécute après. La plupart des paires suivent ce modèle.
• Annulation. Les handlers dont les arguments ont preventDefault() peuvent annuler : la famille des clics, onEventSelect, onEventDelete, onEventMove, onEventResize, onTimeRangeSelect, onTimeRangeClick et ses variantes double-clic et clic droit, onRectangleSelect, onRowClick et ses variantes, onRowSelect, onResourceExpand, onResourceCollapse, onTimeHeaderClick, onTimeHeaderRightClick, onGridMouseDown, onKeyDown, onKeyboardFocusChange et onLinkClick. Annuler un clic empêche aussi son handler en « -ed » et l’action qui suit.
• Confirmation asynchrone. onEventMove et onEventResize prennent en charge args.async = true puis un appel ultérieur à args.loaded() ; preventDefault() avant loaded() annule, et newStart, newEnd et newResource définis avant loaded() sont appliqués.
• Pilotage. onEventMoving, onEventResizing, onTimeRangeSelecting et onRectangleSelecting s’exécutent à chaque changement de l’ombre ; affectez args.allowed, args.start, args.end, args.cssClass ou args.html.

#Événements

e est un SuperScheduler.Event : e.data est l’objet de données, et e.id(), e.start(), e.end(), e.text(), e.resource() et e.duration() le lisent.

#Glisser et redimensionner

#Plages de temps et rectangles

#Lignes et en-têtes

#Hooks de rendu

#Autres handlers

#API du contrôle

Le contrôle est ref.current.control, la valeur de controlRef, args.control dans la plupart des handlers, ou new SuperScheduler.Scheduler(element, options) suivi de init().

#Cycle de vie et affichage

#Défilement et zone visible

#Événements

#Lignes

#Sélection

#Zoom, liens, cellules et clavier

#Membres statiques

#L’espace de noms SuperScheduler

#Modules par sous-chemin

#history

createHistory(options?) renvoie un historique à passer via history={history} ou dans extensions. Options : limit (50), record (['move', 'resize']), keys ('root', 'document' ou false ; 'root' par défaut), equals, fields, apply ('control' ou une fonction pour les événements contrôlés) et labels. Méthodes : undo(), redo(), clear(), push({ label, undo, redo }), record({ ops, control }), batch(label, run), revert(eventId), subscribe(listener) ; propriétés canUndo, canRedo, undoLabel, redoLabel. Les chargements et les modifications refusées ne sont pas enregistrés.

#minimap

createMinimap(control, container, options?) et le composant React <SchedulerMinimap control={control} />. Options : series (par défaut eventDensity(control)), height (28), peak ('relative', ou 'absolute' avec max), tone, marks (today, months, past, tous à true), range et labels. Le widget dispose de update(), refresh() et dispose().

#panes

<SchedulerPanes> accepte les props du planificateur plus panes ({ id, resources or rowFilter, size, minSize (48), hidden, props }), une height numérique obligatoire, timeHeader ('first'), scrollbar ('last'), splitter (true), crossPaneMove (true), component, onPaneResize et panesRef. linkPanes(controls, { zoom, rowHeaderWidth }) relie des contrôles existants et renvoie { dispose() }.

#zoom-ui

createZoomHud(control, { format, apiMs (700) }), createZoomSlider(control, container, { min, max, detents, scale ('log'), label }) et createLodBadge(control, container, labels?). Chacun renvoie { element, dispose() }.

#views

getViewState(control, include?) renvoie un état sérialisable en JSON (zoom, scroll, density, collapsed, columns) ; applyViewState(control, state, { animate, when, timeout }) (when vaut 'now' ou 'rows') renvoie une promesse de boolean.

#ranges

createRangeLoader({ load, chunkDays (7), prefetch (1), cacheChunks (26), skeleton (true), onError }) renvoie un chargeur doté de reload(range?), clear() et loading. load({ start, end, signal }) renvoie les événements qui chevauchent [start, end).

#hooks

useScheduler({ track }) renvoie { controlRef, control, state } pour les sujets 'events', 'selection', 'zoom', 'viewport' et 'history'. useSchedulerState(control, topic), subscribeScheduler(control, topic, listener) (qui renvoie une fonction de désabonnement) et getSchedulerSnapshot(control, topic) donnent le même état hors du hook. L’état de la zone visible est publié une fois le défilement stabilisé.

#react-render

SuperSchedulerComponent avec les props de contenu React. Le repli HTML ou texte est peint en premier ; le contenu React le remplace après la fin de l’interaction. renderOptions.retain vaut par défaut le plus petit de 2 000 ou du double des éléments montés ; sliceMs vaut 8.

#tailwind

Un preset Tailwind CSS v3 : presets: [require('super-scheduler/tailwind')]. Il ajoute des couleurs, rayons, ombres et transitions super-scheduler associés aux tokens CSS.

#datasets

generateDataset(options) et generateScenario(id, overrides?) créent des données déterministes de type hôtelier (rows et days obligatoires, seed, start en ticks, density, events, times). toSuperSchedulerData(dataset) renvoie { resources, events }. Scénarios : S1 (120 lignes, 730 jours), S2 (1 000 lignes, 730 jours), S3 (5 000 lignes, 1 500 jours) et leurs variantes denses. Par défaut, les données commencent le 2026-01-01.

#core

Utilitaires sans DOM partagés par le moteur : SchedulerDate, Duration, registerLocale, resolveLocale, formatTicks, parseTicks, ticksFromParts(year, month, day, ...), partsOf, formatIso, parseIso, todayTicks, nowTicks, les constantes MS_PER_*, ainsi que des utilitaires de frise, d’index et de mise en page. Utilisez-le pour des graphiques et des outils placés à côté du planificateur.

#API Lite

super-scheduler-lite est une frise journalière en lecture seule. Les options qu’il n’implémente pas lèvent SuperScheduler Lite: unsupported option "...", dans tous les builds.

Le contrôle (ref.current.control) dispose de init(), update(options), dispose(), disposed(), scrollTo(date), scrollToResource(id), visibleStart() et visibleEnd(). L’espace de noms contient SuperScheduler.Date et SuperScheduler.Scheduler. Les champs de ressource children, frozen, split et columns sont rejetés. Tokens de thème sur .super-scheduler-lite : --super-scheduler-background, -text, -border, -header, -event et -focus. Voir Passer de Lite à Pro.

#API réservées

Ces membres sont typés pour que le code existant compile, mais ils ne sont pas implémentés dans la 0.1.0. Ils ne font rien, renvoient des valeurs vides et affichent super-scheduler: <feature> is not supported yet une seule fois dans les builds de développement.

Partiellement implémentés :

• treeAnimation est accepté, mais l’animation de dépliage n’est jamais jouée.
• eventClusters et onClusterClick sont acceptés et n’ont encore aucun effet visible.
• Les handlers onBefore*DomAdd et onBefore*DomRemove, les props render* et eventHover ne fonctionnent qu’avec le composant de super-scheduler/react-render ; le composant racine émet un avertissement et les ignore.

Indications de réglage acceptées mais ignorées, car la virtualisation est toujours active et se règle d’elle-même : beforeCellRenderCaching, cellSweeping, cellSweepingCacheSize, drawBlankCells, dynamicEventRendering et ses options de marge et de cache, eventUpdateInplaceOptimization, progressiveRowRendering, progressiveRowRenderingPreload et les options scrollDelay* autres que scrollDelayDynamic.