@synapxlab/ladder-timeline 0.0.1 → 0.1.0

package/dist/adapters/FullCalendarAdapter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * FullCalendarAdapter
+ *
+ * Bridges LadderTimeline with a FullCalendar instance without creating
+ * a direct import dependency on FullCalendar inside the component.
+ *
+ * The component only depends on the `CalendarAdapter` interface:
+ *   interface CalendarAdapter { gotoDate(date: Date): void; }
+ *
+ * Usage example (see also main.ts):
+ *
+ *   import { Calendar } from '@fullcalendar/core';
+ *   import { createFullCalendarAdapter, bindTimelineToCalendar } from './adapters/FullCalendarAdapter';
+ *
+ *   const calendar = new Calendar(calendarEl, { ... });
+ *   calendar.render();
+ *
+ *   const timeline = new LadderTimeline({ container: timelineEl });
+ *   timeline.connectAdapter(createFullCalendarAdapter(calendar));
+ *
+ *   // Or use the convenience helper:
+ *   const unbind = bindTimelineToCalendar(timeline, calendar);
+ */
+import type { CalendarAdapter } from '../components/ladder-timeline/LadderTimeline.types';
+export interface FullCalendarInstance {
+    gotoDate(date: Date | string): void;
+    getDate(): Date;
+    setOption?(option: string, value: unknown): void;
+}
+/**
+ * Wrap a FullCalendar instance in the CalendarAdapter interface.
+ * The adapter forwards `gotoDate` calls to FullCalendar.
+ */
+export declare function createFullCalendarAdapter(calendar: FullCalendarInstance): CalendarAdapter;
+export interface BindableTimeline {
+    connectAdapter(adapter: CalendarAdapter): void;
+    getEventTarget(): EventTarget;
+}
+/**
+ * Bind a LadderTimeline (class variant) to a FullCalendar instance bidirectionally.
+ *
+ * - When the user picks a week in the timeline → calendar.gotoDate() is called.
+ * - Returns an `unbind` function to clean up listeners.
+ */
+export declare function bindTimelineToCalendar(timeline: BindableTimeline, calendar: FullCalendarInstance): () => void;
+/**
+ * Bind a LadderTimelineEventTarget instance to a FullCalendar instance.
+ * Use this variant when using the EventTarget-based LadderTimeline.
+ */
+export declare function bindEventTargetTimelineToCalendar(timeline: EventTarget & {
+    connectAdapter(a: CalendarAdapter): void;
+}, calendar: FullCalendarInstance): () => void;
+/**
+ * Bind a <ladder-timeline> Web Component to a FullCalendar instance.
+ *
+ * Example:
+ *   const el = document.querySelector('ladder-timeline')!;
+ *   bindWebComponentToCalendar(el, calendar);
+ */
+export declare function bindWebComponentToCalendar(el: HTMLElement & {
+    connectAdapter?(a: CalendarAdapter): void;
+}, calendar: FullCalendarInstance): () => void;
+//# sourceMappingURL=FullCalendarAdapter.d.ts.map

package/dist/adapters/FullCalendarAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FullCalendarAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/FullCalendarAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oDAAoD,CAAC;AAM1F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,IAAI,IAAI,CAAC;IAChB,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAClD;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,eAAe,CAMzF;AAID,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/C,cAAc,IAAI,WAAW,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,oBAAoB,GAC7B,MAAM,IAAI,CAUZ;AAOD;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,WAAW,GAAG;IAAE,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,EACpE,QAAQ,EAAE,oBAAoB,GAC7B,MAAM,IAAI,CAUZ;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,WAAW,GAAG;IAAE,cAAc,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,EAC/D,QAAQ,EAAE,oBAAoB,GAC7B,MAAM,IAAI,CAUZ"}

package/dist/components/ladder-timeline/LadderTimeline.d.ts

@@ -0,0 +1,148 @@
+/**
+ * LadderTimeline — Carousel multi-échelles
+ *
+ * Cursor interne unifié = decimal year (float64). L'échelle active fournit
+ * via Scale.build() les items à afficher. Le drag/momentum/scroll/visuals
+ * ne dépendent pas de l'échelle.
+ */
+import type { LadderTimelineOptions, CalendarAdapter, TimelineMarker } from './LadderTimeline.types';
+import { EVENT_WEEK_CHANGE, EVENT_SELECT, EVENT_NAVIGATE } from './LadderTimeline.events';
+import { type ScaleId } from './Scale';
+export declare class LadderTimeline {
+    private readonly container;
+    private readonly firstDayOfWeek;
+    private readonly locale;
+    private readonly compact;
+    private readonly theme;
+    private readonly storageKey;
+    private readonly onWeekChangeCb;
+    private readonly onWeekPreviewCb;
+    private readonly onItemChangeCb;
+    private readonly onItemPreviewCb;
+    private readonly onMarkerClickCb;
+    private markers;
+    private _darkMq;
+    private _darkMqHandler;
+    private selectedYear;
+    private referenceYear;
+    private scale;
+    private displayMode;
+    private readonly minYear;
+    private readonly maxYear;
+    private readonly coarsestScaleIdx;
+    private readonly finestScaleIdx;
+    private root;
+    private listWrapper;
+    private listEl;
+    private centerMark;
+    private liveRegion;
+    private isDragging;
+    private dragStartX;
+    private dragStartScroll;
+    private velX;
+    private lastMoveX;
+    private lastMoveT;
+    private rafId;
+    private wheelDebounceId;
+    private _isExtending;
+    private springRafId;
+    private _isPinching;
+    private _pinchInitialDist;
+    private cleanupFns;
+    private resizeObserver?;
+    private calendarAdapter?;
+    constructor(options: LadderTimelineOptions);
+    setDate(date: Date): void;
+    getDate(): Date;
+    goToToday(): void;
+    goToPrevious(): void;
+    goToNext(): void;
+    /** Change l'échelle courante et re-rend la barre alignée dessus */
+    setScale(id: ScaleId): void;
+    getScale(): ScaleId;
+    setDisplayMode(mode: 'expanded' | 'compact'): void;
+    getDisplayMode(): 'expanded' | 'compact';
+    /** Remplace tous les markers. */
+    setMarkers(markers: TimelineMarker[]): void;
+    /** Ajoute un marker (ne dédoublonne pas sur id — c'est à l'appelant). */
+    addMarker(marker: TimelineMarker): void;
+    /** Supprime tous les markers ayant cet id. No-op si id absent ou inconnu. */
+    removeMarker(id: string): void;
+    /** Renvoie une copie de la liste courante. */
+    getMarkers(): TimelineMarker[];
+    /** Renvoie les bornes effectives configurées sur cette instance. */
+    getBounds(): {
+        minYear: number;
+        maxYear: number;
+        minScale: ScaleId;
+        maxScale: ScaleId;
+    };
+    private _clampYear;
+    /**
+     * Snap puis clamp un year en garantissant qu'on reste sur une frontière
+     * d'échelle (sauf bornes pathologiques sans aucune frontière dans la plage).
+     * Cas géré : snap (souvent Math.floor) tombe juste sous minYear → on monte
+     * d'une unité d'échelle pour retomber dans les bornes.
+     */
+    private _snapAndClamp;
+    private _clampScaleId;
+    getEventTarget(): EventTarget;
+    connectAdapter(adapter: CalendarAdapter): void;
+    render(): void;
+    destroy(): void;
+    on(event: typeof EVENT_WEEK_CHANGE | typeof EVENT_SELECT | typeof EVENT_NAVIGATE, handler: EventListener): () => void;
+    private _buildDOM;
+    /**
+     * Rend tous les <li> dans listEl à partir de referenceYear / selectedYear
+     * et de l'échelle courante. Applique le padding carousel immédiatement.
+     */
+    private _renderItems;
+    /** Renvoie les markers dont year tombe dans [itemYear, itemYear + step). */
+    private _markersForItem;
+    private _handleMarkerClick;
+    private _updateListDOM;
+    /**
+     * Vérifie pendant le drag si le centre approche du bord (seuil × 2).
+     * Si oui, reconstruit la liste autour de l'item central visible en
+     * conservant la position de scroll — le drag continue sans saut.
+     */
+    private _checkAndExtend;
+    private _applyCarouselPadding;
+    private _syncCenterMark;
+    private _scrollToItem;
+    private _smoothScrollTo;
+    private _getCenterItem;
+    private _applyScaleEffect;
+    private _springSnap;
+    private _updateVisuals;
+    private _scheduleVisuals;
+    private _updateCenterHighlight;
+    private _bindDragEvents;
+    private _bindWheelEvents;
+    private _startMomentum;
+    private _snapToCenter;
+    private _bindKeyboardEvents;
+    private _bindPinchEvents;
+    /** Décale l'échelle de `delta` positions (+1 = plus fine, -1 = plus grossière). */
+    private _stepScale;
+    /** Construit un TimelineItemInfo pour un year donné, à l'échelle courante. */
+    private _buildItemInfo;
+    private _emitItemChange;
+    private _emitItemPreview;
+    private _commitSelection;
+    private _emitNavigate;
+    private _hapticFeedback;
+    private _setupTheme;
+    /**
+     * Format storage : `v1:{year}`. Toute autre forme (ancien format, version
+     * future inconnue) est ignorée silencieusement — permet de faire évoluer
+     * la sérialisation sans casser les sessions existantes.
+     */
+    private static readonly STORAGE_VERSION;
+    private _readStorage;
+    private _writeStorage;
+    private _initResizeObserver;
+    debugState(): Record<string, unknown>;
+    private _cleanup;
+}
+//# sourceMappingURL=LadderTimeline.d.ts.map

package/dist/components/ladder-timeline/LadderTimeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LadderTimeline.d.ts","sourceRoot":"","sources":["../../../src/components/ladder-timeline/LadderTimeline.ts"],"names":[],"mappings":"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"}

package/dist/components/ladder-timeline/LadderTimeline.events.d.ts

@@ -0,0 +1,14 @@
+import type { LadderTimelineSelectEventDetail, LadderTimelineNavigateEventDetail } from './LadderTimeline.types';
+/** Fired when the user selects a week (click, keyboard) */
+export type WeekChangeEvent = CustomEvent<LadderTimelineSelectEventDetail>;
+/** Fired when prev / next / today navigation occurs */
+export type WeekNavigateEvent = CustomEvent<LadderTimelineNavigateEventDetail>;
+export declare const EVENT_WEEK_CHANGE: "weekchange";
+export declare const EVENT_NAVIGATE: "navigate";
+export declare const EVENT_SELECT: "select";
+export declare function createWeekChangeEvent(detail: LadderTimelineSelectEventDetail): WeekChangeEvent;
+export declare function createSelectEvent(detail: LadderTimelineSelectEventDetail): CustomEvent<LadderTimelineSelectEventDetail>;
+export declare function createNavigateEvent(detail: LadderTimelineNavigateEventDetail): WeekNavigateEvent;
+export declare function onWeekChange(target: EventTarget, handler: (e: WeekChangeEvent) => void): () => void;
+export declare function onNavigate(target: EventTarget, handler: (e: WeekNavigateEvent) => void): () => void;
+//# sourceMappingURL=LadderTimeline.events.d.ts.map

package/dist/components/ladder-timeline/LadderTimeline.events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LadderTimeline.events.d.ts","sourceRoot":"","sources":["../../../src/components/ladder-timeline/LadderTimeline.events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,iCAAiC,EAClC,MAAM,wBAAwB,CAAC;AAIhC,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,+BAA+B,CAAC,CAAC;AAE3E,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,iCAAiC,CAAC,CAAC;AAI/E,eAAO,MAAM,iBAAiB,EAAG,YAAqB,CAAC;AACvD,eAAO,MAAM,cAAc,EAAG,UAAmB,CAAC;AAClD,eAAO,MAAM,YAAY,EAAG,QAAiB,CAAC;AAI9C,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,+BAA+B,GACtC,eAAe,CAMjB;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,+BAA+B,GACtC,WAAW,CAAC,+BAA+B,CAAC,CAM9C;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iCAAiC,GACxC,iBAAiB,CAMnB;AAID,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GACpC,MAAM,IAAI,CAIZ;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,GACtC,MAAM,IAAI,CAIZ"}

package/dist/components/ladder-timeline/LadderTimeline.types.d.ts

@@ -0,0 +1,116 @@
+export interface WeekRange {
+    start: Date;
+    end: Date;
+}
+export interface WeekItem {
+    weekNumber: number;
+    year: number;
+    range: WeekRange;
+    /** Short label: e.g. "31 Mar – 6 Apr" */
+    label: string;
+    /** Secondary label: e.g. "W14" */
+    sublabel: string;
+    isCurrent: boolean;
+    isSelected: boolean;
+}
+import type { ScaleId } from './Scale';
+export interface LadderTimelineOptions {
+    /** Required mount point */
+    container: HTMLElement;
+    /** Initially selected date (defaults to today) */
+    selectedDate?: Date;
+    /** Centre of the rendered window (defaults to today) */
+    referenceDate?: Date;
+    /** How many items to render at once (default: 51) */
+    weeksVisible?: number;
+    /** 0 = Sunday, 1 = Monday (default: 1) */
+    firstDayOfWeek?: 0 | 1;
+    /** BCP-47 locale for formatting (default: 'fr-FR') */
+    locale?: string;
+    /** Compact mode – less padding, smaller text (default: false) */
+    compact?: boolean;
+    /** Échelle temporelle initiale (default: 'week') */
+    scale?: ScaleId;
+    /**
+     * Mode d'affichage des items :
+     * - `'expanded'` (default) : label + sublabel sur tous les items.
+     * - `'compact'`            : seuls les items aux frontières de l'échelle
+     *   supérieure gardent l'affichage complet ; les autres sont minimisés
+     *   (juste un compactLabel).
+     */
+    displayMode?: 'expanded' | 'compact';
+    /**
+     * Échelle la plus fine autorisée (unité la plus courte). Default: `'ns'`.
+     * Ex: `minScale: 'day'` interdit hour/minute/second/ms/μs/ns.
+     */
+    minScale?: ScaleId;
+    /**
+     * Échelle la plus grossière autorisée (unité la plus longue). Default: `'Ga'`.
+     * Ex: `maxScale: 'century'` interdit millennium/10ka/100ka/Ma/100Ma/Ga.
+     */
+    maxScale?: ScaleId;
+    /** Année minimale navigable (decimal year, ex: -10000 pour 10 000 av. J.-C.). */
+    minYear?: number;
+    /** Année maximale navigable (decimal year). */
+    maxYear?: number;
+    /** Date minimale navigable. Convertie en minYear. Ignoré si minYear est fourni. */
+    minDate?: Date;
+    /** Date maximale navigable. Convertie en maxYear. Ignoré si maxYear est fourni. */
+    maxDate?: Date;
+    /** Optional callback shortcut (alternative to listening to 'weekchange') */
+    onWeekChange?: (detail: LadderTimelineSelectEventDetail) => void;
+    /** Fired live during drag as the center item changes (before snap) */
+    onWeekPreview?: (detail: LadderTimelineSelectEventDetail) => void;
+    /** Fired when the centered item is committed (after snap) — toutes échelles */
+    onItemChange?: (info: TimelineItemInfo) => void;
+    /** Fired live during drag/scroll for the centered item — toutes échelles */
+    onItemPreview?: (info: TimelineItemInfo) => void;
+    /** Liste initiale de markers (dates clés) à poser sur la timeline */
+    markers?: TimelineMarker[];
+    /** Click sur un marker */
+    onMarkerClick?: (marker: TimelineMarker) => void;
+    /**
+     * Thème visuel.
+     * - 'light' (défaut) : toujours clair
+     * - 'dark'           : toujours sombre
+     * - 'auto'           : suit prefers-color-scheme du système
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Clé localStorage pour persister la semaine sélectionnée entre les rechargements.
+     * Si définie et qu'une valeur valide est stockée, elle prend priorité sur selectedDate.
+     */
+    storageKey?: string;
+}
+export interface LadderTimelineSelectEventDetail {
+    date: Date;
+    week: WeekRange;
+}
+export interface LadderTimelineNavigateEventDetail {
+    direction: 'prev' | 'next' | 'today';
+    date: Date;
+    week: WeekRange;
+}
+export interface CalendarAdapter {
+    gotoDate(date: Date): void;
+}
+export interface TimelineItemInfo {
+    scale: ScaleId;
+    year: number;
+    label: string;
+    sublabel: string;
+    header: string;
+    /** Date équivalent si le year est dans la plage Date, sinon null */
+    date: Date | null;
+}
+export interface TimelineMarker {
+    /** Position en décimal year (ex: 1789.539 pour 14 juillet 1789) */
+    year: number;
+    /** Texte affiché en tooltip (et dans les payloads d'événement) */
+    label: string;
+    /** Couleur du marker. Défaut : couleur d'accent du thème. */
+    color?: string;
+    /** Identifiant optionnel — pour removeMarker() */
+    id?: string;
+}
+//# sourceMappingURL=LadderTimeline.types.d.ts.map

package/dist/components/ladder-timeline/LadderTimeline.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LadderTimeline.types.d.ts","sourceRoot":"","sources":["../../../src/components/ladder-timeline/LadderTimeline.types.ts"],"names":[],"mappings":"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"}

package/dist/components/ladder-timeline/LadderTimeline.utils.d.ts

@@ -0,0 +1,44 @@
+import type { WeekItem, WeekRange } from './LadderTimeline.types';
+/** Return a new Date stripped to midnight UTC-local */
+export declare function normalizeDate(d: Date): Date;
+/** Clone a Date instance */
+export declare function cloneDate(d: Date): Date;
+/** Add (or subtract) N days */
+export declare function addDays(d: Date, days: number): Date;
+/** Add (or subtract) N weeks */
+export declare function addWeeks(d: Date, weeks: number): Date;
+/**
+ * Return Monday (firstDayOfWeek=1) or Sunday (firstDayOfWeek=0)
+ * of the week containing `d`.
+ */
+export declare function getWeekStart(d: Date, firstDayOfWeek?: 0 | 1): Date;
+/** Return the last day of the week (6 days after start) */
+export declare function getWeekEnd(weekStart: Date): Date;
+/** ISO-8601 week number */
+export declare function getISOWeekNumber(d: Date): number;
+/** True if two dates fall on the same calendar day */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/** True if two dates fall in the same ISO week */
+export declare function isSameWeek(a: Date, b: Date, firstDayOfWeek?: 0 | 1): boolean;
+/** Numeric comparison: –1, 0, 1 */
+export declare function compareDate(a: Date, b: Date): -1 | 0 | 1;
+/**
+ * Format a week date range using Intl.DateTimeFormat.formatRange when available.
+ * Same month  → "18 – 24 août"  /  "Aug 18 – 24"   (month shown once)
+ * Cross-month → "28 mars – 3 avr." / "Mar 28 – Apr 3"
+ */
+export declare function formatWeekLabel(range: WeekRange, locale: string): string;
+/** "W14 · 2025" */
+export declare function formatWeekSublabel(weekNumber: number, year: number): string;
+/**
+ * Generate an array of WeekItems centred on `referenceDate`.
+ *
+ * @param referenceDate   Centre of the window
+ * @param selectedDate    Currently selected date
+ * @param weeksVisible    Total weeks to generate (should be odd for centring)
+ * @param firstDayOfWeek  0 = Sun, 1 = Mon
+ * @param locale          BCP-47 locale
+ */
+export declare function buildWeekList(referenceDate: Date, selectedDate: Date, weeksVisible: number, firstDayOfWeek: 0 | 1, locale: string): WeekItem[];
+export declare function isValidDate(d: unknown): d is Date;
+//# sourceMappingURL=LadderTimeline.utils.d.ts.map

package/dist/components/ladder-timeline/LadderTimeline.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LadderTimeline.utils.d.ts","sourceRoot":"","sources":["../../../src/components/ladder-timeline/LadderTimeline.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAIlE,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAG3C;AAED,4BAA4B;AAC5B,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAEvC;AAED,+BAA+B;AAC/B,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,gCAAgC;AAChC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAErD;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAE,CAAC,GAAG,CAAK,GAAG,IAAI,CAKrE;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAEhD;AAED,2BAA2B;AAC3B,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAMhD;AAID,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAMnD;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,GAAE,CAAC,GAAG,CAAK,GAAG,OAAO,CAI/E;AAED,mCAAmC;AACnC,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAMxD;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAaxE;AAED,mBAAmB;AACnB,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,IAAI,EACnB,YAAY,EAAE,IAAI,EAClB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,CAAC,GAAG,CAAC,EACrB,MAAM,EAAE,MAAM,GACb,QAAQ,EAAE,CA0BZ;AAID,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,IAAI,CAEjD"}

package/dist/components/ladder-timeline/Scale.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Scale system — 18 échelles temporelles, du milliard d'années à la nanoseconde.
+ *
+ * Cursor interne unifié = `decimal year` (float64). Chaque Scale fournit :
+ *  - step        : pas entre deux items (en années décimales)
+ *  - snap(year)  : arrondit à la frontière d'unité de cette échelle
+ *  - build(...)  : produit N items autour du curseur
+ *
+ * Pour les très grandes échelles (>= ka), on travaille uniquement sur le `year`
+ * numérique (Date ne supporte pas au-delà de ±271 821 ans depuis 1970).
+ * Pour les échelles fines (< seconde), la précision float64 ne suffit pas pour
+ * un timestamp absolu — les labels deviennent décoratifs.
+ */
+export type ScaleId = 'Ga' | '100Ma' | 'Ma' | '100ka' | '10ka' | 'millennium' | 'century' | 'decade' | 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'ms';
+export interface ScaleItem {
+    /** Identité canonique de l'item — décimal year de son début */
+    year: number;
+    /** Label principal affiché sur l'item */
+    label: string;
+    /** Label secondaire (S14 · 2025, 14:00…) */
+    sublabel: string;
+    /** Header optionnel affiché sur l'item sélectionné ou aux transitions */
+    header: string;
+    /** Label court pour le mode d'affichage `compact` (ex: "·10" pour 1810 à l'échelle décennie) */
+    compactLabel: string;
+    /** Marqueur "aujourd'hui" (ou présent pour macro) */
+    isCurrent: boolean;
+    /** Marqueur "sélectionné" */
+    isSelected: boolean;
+}
+export interface Scale {
+    id: ScaleId;
+    label: string;
+    /** Pas (en années décimales) entre deux items adjacents */
+    step: number;
+    /** Snap d'un year libre à la frontière d'unité de l'échelle */
+    snap(year: number): number;
+    /** Décale le year de n unités */
+    add(year: number, n: number): number;
+    /** Construit `count` items autour de `centerYear` */
+    build(centerYear: number, count: number, selectedYear: number, locale: string): ScaleItem[];
+}
+declare function inDateRange(year: number): boolean;
+declare function yearToDate(year: number): Date;
+declare function dateToYear(d: Date): number;
+declare function todayYear(): number;
+export declare const SCALES: Scale[];
+export declare function getScale(id: ScaleId): Scale;
+export declare function scaleIndex(id: ScaleId): number;
+export declare function scaleAt(index: number): Scale | undefined;
+export declare const SCALE_COUNT: number;
+export { dateToYear, yearToDate, todayYear, inDateRange };
+//# sourceMappingURL=Scale.d.ts.map

package/dist/components/ladder-timeline/Scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scale.d.ts","sourceRoot":"","sources":["../../../src/components/ladder-timeline/Scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,OAAO,GACf,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GACxC,YAAY,GAAG,SAAS,GAAG,QAAQ,GACnC,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GACjC,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAC5B,IAAI,CAAC;AAET,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,iCAAiC;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC,qDAAqD;IACrD,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;CAC7F;AAOD,iBAAS,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1C;AAED,iBAAS,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQtC;AAED,iBAAS,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAKnC;AAED,iBAAS,SAAS,IAAI,MAAM,CAE3B;AA6YD,eAAO,MAAM,MAAM,EAAE,KAAK,EAiBzB,CAAC;AAOF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,CAI3C;AASD,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAE9C;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAExD;AAED,eAAO,MAAM,WAAW,QAAgB,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC"}

package/dist/debug.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Panneau de debug LadderTimeline — dev only.
+ * Importé dynamiquement depuis main.ts uniquement quand import.meta.env.DEV === true.
+ * Jamais inclus dans le bundle de production.
+ */
+import { LadderTimeline } from './components/ladder-timeline/LadderTimeline';
+export declare function initDebugger(timeline: LadderTimeline): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAE7E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CA4H3D"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { LadderTimeline } from './components/ladder-timeline/LadderTimeline';
+export type { LadderTimelineOptions, LadderTimelineSelectEventDetail, LadderTimelineNavigateEventDetail, WeekRange, WeekItem, CalendarAdapter, } from './components/ladder-timeline/LadderTimeline.types';
+export { createFullCalendarAdapter, bindTimelineToCalendar, } from './adapters/FullCalendarAdapter';
+export type { FullCalendarInstance, BindableTimeline, } from './adapters/FullCalendarAdapter';
+import './components/ladder-timeline/LadderTimeline.scss';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAG7E,YAAY,EACV,qBAAqB,EACrB,+BAA+B,EAC/B,iCAAiC,EACjC,SAAS,EACT,QAAQ,EACR,eAAe,GAChB,MAAM,mDAAmD,CAAC;AAG3D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,kDAAkD,CAAC"}