Intégrer l'ATS dans votre site

Ajoutez l'horloge Δ n'importe où avec un seul <script> et un élément. Cette page est un guide d'intégration autonome pour les sites tiers — aucune connaissance de la spec requise.

Renvois : rationale du composant dans analog-clock (annexe), contrat de conformité dans manifeste §16.5, politique d'intégrité dans SECURITY.md §5.

1. One-liner

<script src="https://s-geffroy.github.io/ATS/assets/js/ats-clock.js" defer></script>
<ats-clock lang="fr"></ats-clock>

Exemple en direct (sur cette page) :

2. Attributs configurables

Attribut	Valeurs	Défaut	Notes
`format`	`short`, `canonical`, `both`	`short`	Forme UI (précision Milli) vs fraction canonique 5 chiffres. Cf. manifeste §4 / §5.
`lang`	`en`, `fr`	`en`	Affecte uniquement le préfixe « T+ » et le groupement des chiffres (les deux langues parsent à l'identique).
`updates-per-second`	1–20 (clampé)	10	Plus haut = lecture du Blink plus fluide, plus de batterie ; plus bas = compatible affichage statique. Cf. analog-clock §7.

L'élément observe les changements d'attributs et se re-rend à la volée ; updates-per-second est clampé à l'exécution.

3. Recommandation CSP (stricte)

Le composant fonctionne entièrement dans la page (aucun trafic réseau à l'exécution). Les sites embarqueurs DEVRAIENT le servir sous une Content Security Policy stricte. La politique minimale qui permet à <ats-clock> de fonctionner sans 'unsafe-inline' est :

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://s-geffroy.github.io;
  style-src 'self';
  img-src 'self' data:;
  connect-src 'self';
  object-src 'none';
  base-uri 'self';

Ce que cela vous coûte : plus de <script> inline sur la même page, plus d'attributs style="..." inline sur l'élément intégré (le composant utilise Shadow DOM, ses styles internes ne sont pas affectés). Si vous ne pouvez pas éviter l'inline, hébergez ats-clock.js sur votre propre origine (cf. §5) et durcissez script-src à 'self'.

Subresource Integrity (SRI) : le contenu du script peut changer entre versions (nous suivons SemVer). Soit vous épinglez une URL à un SHA spécifique, soit vous self-hostez (§5) et calculez le SRI au build.

<ats-clock> expose sa valeur courante via aria-live="polite" sur le readout interne, pour que les lecteurs d'écran annoncent les mises à jour sans interrompre l'utilisateur. L'élément n'est pas focusable au clavier. Les embarqueurs DEVRAIENT :

Placer l'horloge dans une région avec un titre explicite (<h2> ou aria-labelledby) pour qu'elle ait du contexte.
Éviter de l'envelopper dans un <button> ou de l'inclure dans un flux de tabulation — elle n'a aucune action utilisateur.
Utiliser updates-per-second="1" pour un affichage ambiant (moins de chatter pour les lecteurs d'écran ; ceux qui veulent la granularité Blink peuvent surcharger).

5. Self-hosting et endpoint alternatif

Pour la CSP la plus stricte et pour supprimer la dépendance tierce, copiez ats-clock.js (et éventuellement ats.js pour les routines de conversion brutes) dans votre origine :

curl -O https://raw.githubusercontent.com/s-geffroy/ATS/main/docs/assets/js/ats-clock.js
curl -O https://raw.githubusercontent.com/s-geffroy/ATS/main/docs/assets/js/ats.js

Votre script-src peut alors être réduit à 'self'. Cf. SECURITY.md §5 pour les arbitrages self-host vs CDN.

Alternative côté serveur. Si vous ne pouvez pas exécuter JavaScript côté client, récupérez le snapshot horaire à /api/now.json (régénéré par un cron GitHub Actions, le champ spec_version permet de détecter une dérive) :

curl -s https://s-geffroy.github.io/ATS/api/now.json
# {
#   "utc": "2026-06-15T11:00:00Z",
#   "ats_canonical": "T+ Δ 20.7.8.4.45833",
#   "ats_display": "Δ20.7.8.4-45.8",
#   "spec_version": "0.7",
#   "cadence_minutes": 60
# }

Ce n'est pas un endpoint live — il est rafraîchi toutes les heures. Pour une précision sous-minute, faites la conversion localement avec ats.js ou code/ats.py.

6. Trois exemples concrets

Blog thème clair

<article>
  <h2>Publié</h2>
  <ats-clock format="short" lang="fr" updates-per-second="1"></ats-clock>
</article>

Tuile dashboard thème sombre

<section style="background:#0b0f17;color:#e8eef7;padding:1rem;border-radius:8px">
  <h2 style="margin:0 0 .5rem">ATS maintenant</h2>
  <ats-clock format="both" lang="fr" updates-per-second="10"></ats-clock>
</section>

Badge dans un README Markdown

[![I run on Δ ATS](https://s-geffroy.github.io/ATS/assets/badge.svg)](https://s-geffroy.github.io/ATS/)

7. Variantes en direct

8. Dépannage

Symptôme	Cause	Correction
L'élément reste vide	Script chargé avec `defer` mais bloqué par la CSP	Vérifier que `script-src` inclut `https://s-geffroy.github.io` (ou l'origine de self-host)
Heure figée	L'onglet est en arrière-plan, throttlé par le navigateur	Comportement attendu — les timers passent à 1 Hz en arrière-plan, le prochain tick au premier plan re-synchronise
Erreur CORS dans la console	Fetch de `now.json` depuis une origine non autorisée	L'endpoint sert `Access-Control-Allow-Origin: *` ; vérifier que votre reverse-proxy ne le filtre pas
Police différente du reste du site	Le composant n'hérite pas de vos `@font-face` à travers Shadow DOM	Posez `font-family` sur l'hôte : `ats-clock { font-family: inherit; }`
Contraste de thème incorrect	Couleurs système non exposées	Le composant utilise `currentColor` pour les chiffres ; posez `color` sur l'hôte ou un ancêtre

9. npm (planifié, v1.0)

Les routines JS de référence sont structurées en package (non encore publié — cf. ROADMAP V1.0-H et versioning §7.2 (4)) :

// import { atsFromMs, toCanonical, toShort } from '@s-geffroy/ats';
// import '@s-geffroy/ats/web-component'; // enregistre <ats-clock>