Composant · Formulaires

TimeRangePicker

Stable

Sélecteur de plage temporelle : un déclencheur qui affiche la plage courante et un popover à deux onglets — des presets relatifs (« 30 dernières minutes ») appliqués immédiatement, et un éditeur de plage absolue validé par un bouton. Registre familier des consoles d'observabilité. Le composant compose des primitives existantes du DS (popover, tabs, liste, calendrier, heure, champ, boutons) : il n'introduit aucun contrôle bas niveau supplémentaire.

Presets par défaut

Sans presets, le composant propose DEFAULT_TIME_RANGE_PRESETS : 30m, 1h, 3h, 6h, 12h, 24h, 3d, 7d, 30d. Un preset est un jeton de grammaire <nombre><m|h|d|w>.

Sélecteur par défaut

Période observée

Voir le code (Svelte)

<TimeRangePicker label="Période observée" locale="fr-FR" />

Presets sur mesure et tailles

presets accepte des jetons, ou des objets { token, label?, durationMs? } quand le libellé par défaut ne convient pas. size aligne la hauteur du déclencheur sur celle des autres contrôles de la barre d'outils.

Jeux de presets métier

Fenêtre d'incident

Rétrospective

Voir le code (Svelte)

<TimeRangePicker
  label="Fenêtre d'incident"
  presets={["5m","15m","1h","24h","7d"]}
  locale="fr-FR"
  size="sm"
/>
<TimeRangePicker
  label="Rétrospective"
  presets={["7d","30d","12w"]}
  calendarMonths={1}
  locale="fr-FR"
  size="lg"
/>

Horaire et état désactivé

Variantes

12 h, verrouillé

Horaire sur 12 h

Voir le code (Svelte)

<TimeRangePicker label="12 h, verrouillé" locale="fr-FR" disabled />
<TimeRangePicker
  label="Horaire sur 12 h"
  timeFormat="12"
  timeStep={30}
  locale="fr-FR"
/>

Le popover piège le focus tant qu'il est ouvert et le rend au déclencheur à la fermeture (Échap, clic extérieur, validation).

Contrôles additionnels de l'onglet Personnalisé

customExtra rend des contrôles du consommateur dans l'onglet Personnalisé, juste au-dessus des champs Début / Fin (ici, une base de date). L'onglet étant validé par Appliquer, ce que ces contrôles modifient est un brouillon : réinitialisez-le à l'ouverture (onOpenChange(true)) et validez-le dans onChange quand la valeur émise est en mode absolute — émission qui n'a lieu que sur Appliquer. Annuler, Échap ou un clic extérieur n'émettent rien.

Période des signaux

Base appliquée : document

<!-- Svelte -->
<TimeRangePicker value={range} onChange={onRangeChange} onOpenChange={onOpenChange}>
  {#snippet customExtra()}
    <RadioGroup legend="Date basis" name="basis" orientation="horizontal"
      options={basisOptions} value={draftBasis} onchange={(v) => (draftBasis = v)} />
  {/snippet}
</TimeRangePicker>

// React
<TimeRangePicker value={range} onChange={onRangeChange} onOpenChange={onOpenChange}
  customExtra={<RadioGroup ... value={draftBasis} onChange={setDraftBasis} />} />

<!-- Vue -->
<TimeRangePicker :value="range" @change="onRangeChange" @open-change="onOpenChange">
  <template #customExtra><RadioGroup ... /></template>
</TimeRangePicker>

<!-- Angular -->
<st-time-range-picker [value]="range" (change)="onRangeChange($event)" (openChange)="onOpenChange($event)">
  <div slot="customExtra"><st-radio-group ...></st-radio-group></div>
</st-time-range-picker>

// Commit pattern (all frameworks)
function onOpenChange(open) { if (open) draftBasis = appliedBasis; }
function onRangeChange(next) {
  range = next;
  appliedBasis = next.mode === "absolute" ? draftBasis : "document";
}

Contrat de valeur

La valeur émise est toujours la même forme, quel que soit l'onglet utilisé : from et to sont toujours des epoch ms, et un preset relatif est résolu en bornes concrètes tout en rapportant son jeton dans relative. Un consommateur peut donc interroger sans condition, et ré-résoudre la fenêtre glissante plus tard s'il le souhaite.

Champ	Type	Description
`mode`	`'relative' \| 'absolute'`	Onglet d'où vient la plage.
`relative`	`string \| undefined`	Jeton du preset résolu ; présent uniquement en mode relative.
`from`	`number`	Borne basse incluse, epoch ms.
`to`	`number`	Borne haute incluse, epoch ms.

Aides exportées

La grammaire et le formatage vivent hors du composant, sans dépendance à un framework : DEFAULT_TIME_RANGE_PRESETS, parsePresetMs, resolveRelative, splitAbsolute, composeAbsolute, formatPresetLabel, formatTriggerLabel. Utiles pour ré-résoudre un jeton côté serveur ou pour afficher la même étiquette ailleurs.

API du composant

Prop	Type	Défaut	Description
`value`	`TimeRange`	—	Plage contrôlée.
`defaultValue`	`TimeRange`	—	Graine non contrôlée. Sans value ni defaultValue, le composant part des 30 dernières minutes — un repli interne, pas un défaut de cette prop.
`onChange`	`(value: TimeRange) => void`	—	Émis à chaque plage retenue.
`presets`	`TimeRangePreset[]`	`DEFAULT_TIME_RANGE_PRESETS`	Presets relatifs proposés.
`min` / `max`	`number`	—	Bornes autorisées, epoch ms.
`locale`	`string`	`'fr-FR'`	Locale de formatage.
`timeFormat`	`'24' \| '12'`	`'24'`	Horaire de l'éditeur absolu.
`timeStep`	`number`	`15`	Pas des créneaux horaires, en minutes.
`calendarMonths`	`1 \| 2`	`2`	Mois affichés côte à côte.
`label`	`string`	—	Libellé de champ au-dessus du déclencheur (voir la réserve Angular sous le tableau).
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Hauteur du déclencheur.
`placement`	`'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'`	`'bottom-start'`	Côté où s'ouvre le popover.
`align`	`'start' \| 'end' \| 'center'`	—	Alignement transversal du popover ; sans valeur, aucune classe d'alignement n'est émise.
`disabled`	`boolean`	`false`	Désactive le déclencheur.
`formatRange` / `formatPresetLabel`	`function`	—	Remplacent le formatage par défaut du déclencheur et des presets.
`customExtra`	`Snippet`	—	Contrôles additionnels rendus dans l'onglet Personnalisé, au-dessus des champs Début / Fin (React : ReactNode ; Vue : slot customExtra ; Angular : [slot=customExtra]).
`onOpenChange`	`(open: boolean) => void`	—	Émis à chaque ouverture (true) ou fermeture (false) du popover (Vue : @open-change ; Angular : (openChange)).
`class`	`string`	—	Classe CSS supplémentaire sur la racine.

React et Vue exposent la même API que Svelte ; en Angular, label ne rend pas le libellé de champ au-dessus du déclencheur — il n'y sert que de aria-label sur le déclencheur et sur le popover. Prévoyez votre propre libellé visible si vous en avez besoin.

Tokens CSS

Le déclencheur est un contrôle de formulaire ordinaire : il n'a pas de famille de tokens propre et lit celles des contrôles et des champs, si bien qu'il suit n'importe quel thème sans réglage dédié.

--st-component-control-background
--st-component-control-border
--st-component-control-text
--st-component-control-smHeight / -mdHeight / -lgHeight
--st-component-control-hoverBackground
--st-component-control-hoverBorder
--st-component-control-disabledText
--st-component-control-focusRing
--st-component-field-labelText
--st-component-field-gap
--st-semantic-surface-default
--st-semantic-border-subtle