@cdevhub/ngx-tw 0.2.0

package/types/cdevhub-ngx-tw-timeline.d.ts

@@ -0,0 +1,278 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, AfterContentInit, EnvironmentProviders } from '@angular/core';
+import { TwOrientation, TwSize, TwColor } from '@cdevhub/ngx-tw/core';
+
+/** Marker geometry of a `tw-timeline-item`. */
+type TimelineMarker = 'dot' | 'circle';
+/** Semantic state of a `tw-timeline-item`. Drives marker fill, ring, and trailing-connector color. */
+type TimelineState = 'reached' | 'pending' | 'current' | 'error';
+/** Vertical layout strategy of a `tw-timeline`. Ignored for `orientation: 'horizontal'`. */
+type TimelineAlign = 'left' | 'right' | 'alternate' | 'split';
+/** Connector line style. */
+type TimelineLineStyle = 'solid' | 'dashed';
+/** Visibility policy for the horizontal-overflow chevron buttons. */
+type TimelineScrollControls = 'auto' | 'always' | 'never';
+/** Localisable labels for the horizontal-overflow chevron buttons on `tw-timeline`. */
+interface TwTimelineScrollLabels {
+    /** Accessible label for the previous-scroll chevron. Used as `aria-label`. Defaults to `'Scroll to previous events'`. */
+    scrollPrevious: string;
+    /** Accessible label for the next-scroll chevron. Used as `aria-label`. Defaults to `'Scroll to next events'`. */
+    scrollNext: string;
+}
+/** Default English labels used when `TW_TIMELINE_SCROLL_LABELS` is not provided. */
+declare const DEFAULT_TW_TIMELINE_SCROLL_LABELS: TwTimelineScrollLabels;
+/**
+ * Injection token carrying localisable `aria-label` strings for the timeline's
+ * horizontal-overflow chevron buttons. The container uses these labels exclusively
+ * on the prev/next buttons; they do not affect any other rendered text.
+ *
+ * Provide via `provideTwTimelineScrollLabels({ ... })` at the root or feature level.
+ * If both keys are present they override the English defaults; if only one is present
+ * the other falls back to the English default.
+ *
+ * First concrete token under the `TW_TIMELINE_I18N` reservation in
+ * `docs/requirements/timeline.requirements.md` § 11.2.
+ */
+declare const TW_TIMELINE_SCROLL_LABELS: InjectionToken<Partial<TwTimelineScrollLabels>>;
+/**
+ * Configures the localised labels used by `tw-timeline` overflow chevrons.
+ * Add to `bootstrapApplication`'s `providers` (or any feature/route provider array).
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [
+ *     provideTwTimelineScrollLabels({
+ *       scrollPrevious: 'Vorherige Ereignisse',
+ *       scrollNext: 'Nächste Ereignisse',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function provideTwTimelineScrollLabels(labels: Partial<TwTimelineScrollLabels>): EnvironmentProviders;
+/**
+ * Marker-slot directive. Apply on any element projected inside a `<tw-timeline-item>`
+ * to render that element inside the marker bubble (only when `marker="circle"`).
+ *
+ * @example
+ * ```html
+ * <tw-timeline-item marker="circle" color="success">
+ *   <tw-icon twTimelineMarker name="check" />
+ *   <p class="text-sm">Done</p>
+ * </tw-timeline-item>
+ * ```
+ */
+declare class TimelineMarkerDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimelineMarkerDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TimelineMarkerDirective, "[twTimelineMarker]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Timestamp-slot directive. Replaces the rendered `timestamp` / `dateTime`
+ * output. Use for relative-time components ("2 hours ago").
+ */
+declare class TimelineTimestampDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimelineTimestampDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TimelineTimestampDirective, "[twTimelineTimestamp]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Opposite-slot directive. Renders on the side opposite the body in
+ * `align="alternate"` / `align="split"` (vertical orientation only).
+ */
+declare class TimelineOppositeDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimelineOppositeDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TimelineOppositeDirective, "[twTimelineOpposite]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Presentational chronological-sequence layout primitive. Renders a list of
+ * `<tw-timeline-item>` children connected by a line that runs through their
+ * markers. The container owns orientation, alignment, density, and line-style
+ * decisions; items style their own marker, state, and connector colors.
+ *
+ * **Not interactive.** Unlike `tw-stepper`, the timeline does not install a
+ * keyboard map, does not own panels, does not trap focus, and item hosts are
+ * not focusable. Consumers needing row-level activation project an
+ * interactive primitive (`<tw-item interactive>`, `<button>`, an anchor) inside
+ * the default slot.
+ */
+declare class TimelineComponent {
+    /** Axis along which items are laid out. `'vertical'` stacks items top-to-bottom; `'horizontal'` lays them out left-to-right (RTL-aware). Defaults to `'vertical'`. */
+    readonly orientation: _angular_core.InputSignal<TwOrientation>;
+    /** Vertical layout strategy. `'left'` / `'right'` place the marker on that side; `'alternate'` centers the marker and flips the body left ↔ right per item; `'split'` centers the marker with body on the right and the opposite slot on the left. Ignored when orientation is `'horizontal'`. Defaults to `'left'`. */
+    readonly align: _angular_core.InputSignal<TimelineAlign>;
+    /** Density and typography scale. Controls marker diameter, gap between items, and body typography step. Defaults to `'md'`. */
+    readonly size: _angular_core.InputSignal<TwSize>;
+    /** Connector line style applied to every gap between items. Defaults to `'solid'`. */
+    readonly lineStyle: _angular_core.InputSignal<TimelineLineStyle>;
+    /**
+     * Visibility policy for the horizontal-overflow chevron buttons. `'auto'`
+     * shows them only when the inner scroll region can scroll in that direction;
+     * `'always'` renders both regardless of scroll state (disabled when at an
+     * edge); `'never'` hides them entirely (consumer manages overflow
+     * externally). Ignored when orientation is `'vertical'`. Defaults to
+     * `'auto'`.
+     *
+     * Counts as the 5th container input, justified by the "Overflow-control axis
+     * on layout primitives" cap exception: a layout primitive whose primary axes
+     * (orientation, alignment, size, line/style) already saturate ≤ 4 inputs MAY
+     * add a single additional input that toggles overflow-navigation
+     * affordances when overflow is a real concern for at least one axis value.
+     * The added input MUST be a single tri-state and MUST be inert on axis
+     * values where overflow cannot occur (here: `orientation === 'vertical'`).
+     */
+    readonly scrollControls: _angular_core.InputSignal<TimelineScrollControls>;
+    /** @internal Static class string for the horizontal scroll viewport — see `HORIZONTAL_VIEWPORT_CLASSES`. */
+    protected readonly horizontalViewportClasses: string;
+    /** @internal Projected `tw-timeline-item` children in DOM order. */
+    readonly items: _angular_core.Signal<readonly TimelineItemComponent[]>;
+    private readonly _destroyRef;
+    private readonly _directionality;
+    private readonly _viewportRef;
+    private readonly _scrollLabelsOverride;
+    /** @internal Live `dir` from CDK `Directionality`. */
+    private readonly _cdkDir;
+    /** @internal True when the host renders inside a `dir="rtl"` ancestor. */
+    readonly _isRtl: _angular_core.Signal<boolean>;
+    /**
+     * @internal Defaults to `false` until the first measurement runs in
+     * `afterNextRender`. This avoids a one-frame "enabled-then-disabled" flash
+     * where the buttons appear live before the scroll state has been read.
+     */
+    readonly _canScrollPrev: _angular_core.WritableSignal<boolean>;
+    readonly _canScrollNext: _angular_core.WritableSignal<boolean>;
+    /** @internal Resolved label record. Falls back to English defaults for any missing key. */
+    readonly scrollLabels: _angular_core.Signal<TwTimelineScrollLabels>;
+    /** @internal True when the prev button should be aria-hidden + visually suppressed. */
+    readonly _prevButtonHidden: _angular_core.Signal<boolean>;
+    /** @internal True when the next button should be aria-hidden + visually suppressed. */
+    readonly _nextButtonHidden: _angular_core.Signal<boolean>;
+    /** @internal Native `disabled` attribute. Always true for hidden buttons (defensive); also true for `'always'` policy when can't scroll. */
+    readonly _prevButtonDisabled: _angular_core.Signal<boolean>;
+    readonly _nextButtonDisabled: _angular_core.Signal<boolean>;
+    /**
+     * @internal Final class string for the prev chevron — combines the shared
+     * `CHEVRON_CLASSES`, the directional anchor (`left-0` in LTR, `right-0` in
+     * RTL), and the visibility variant driven by `scrollControls`.
+     */
+    readonly prevChevronClasses: _angular_core.Signal<string>;
+    readonly nextChevronClasses: _angular_core.Signal<string>;
+    private _chevronClasses;
+    private _resizeObserver;
+    constructor();
+    private _setupScrollDetection;
+    /** @internal Wired to the viewport's `(scroll)` event. */
+    _onScroll(): void;
+    private _updateScrollState;
+    /** Page-scroll amount: 75% of the visible width, leaving ~25% overlap for context. */
+    private _pageScrollAmount;
+    /** @internal Click handler for the prev chevron. */
+    _scrollPrev(): void;
+    /** @internal Click handler for the next chevron. */
+    _scrollNext(): void;
+    private readonly variantResult;
+    readonly rootClasses: _angular_core.Signal<string>;
+    /** @internal Item slot classes shared with `TimelineItemComponent`. */
+    readonly itemSlotClasses: _angular_core.Signal<string>;
+    readonly markerSideSlotClasses: _angular_core.Signal<string>;
+    readonly markerSlotClasses: _angular_core.Signal<string>;
+    readonly connectorLeadingSlotClasses: _angular_core.Signal<string>;
+    readonly connectorTrailingSlotClasses: _angular_core.Signal<string>;
+    readonly bodySlotClasses: _angular_core.Signal<string>;
+    readonly oppositeSlotClasses: _angular_core.Signal<string>;
+    readonly numberSlotClasses: _angular_core.Signal<string>;
+    readonly timestampSlotClasses: _angular_core.Signal<string>;
+    /** @internal Variant builder reused by items so per-item state can recompose without rebuilding the base tv() result. */
+    readonly itemMarkerVariant: (state: TimelineState, marker: TimelineMarker) => string;
+    /** @internal Variant builder for the auto-number slot (state drives text color). */
+    readonly itemNumberVariant: (state: TimelineState) => string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimelineComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TimelineComponent, "tw-timeline", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "lineStyle": { "alias": "lineStyle"; "required": false; "isSignal": true; }; "scrollControls": { "alias": "scrollControls"; "required": false; "isSignal": true; }; }, {}, ["items"], ["*"], true, never>;
+}
+/**
+ * A single event in a `tw-timeline`. Renders a marker (dot or circle) plus
+ * content. Connectors leading into and out of the marker are emitted by this
+ * component and conditionally elided when the item is first or last in the
+ * timeline. The item is not focusable — row activation belongs to projected
+ * interactive children.
+ */
+declare class TimelineItemComponent implements AfterContentInit {
+    /** Semantic color for the marker fill and the trailing connector when the item is in a reached state. Ignored when state is `'error'` (which forces the error palette). Defaults to `'primary'`. */
+    readonly color: _angular_core.InputSignal<TwColor>;
+    /** Marker geometry. `'dot'` is a small filled circle. `'circle'` is a larger ring that may contain a projected icon, avatar, or an auto-computed 1-based index. Defaults to `'dot'`. */
+    readonly marker: _angular_core.InputSignal<TimelineMarker>;
+    /** Semantic state of the event. Drives marker fill, ring, and trailing-connector color, and applies `aria-current="step"` when `'current'`. Defaults to `'reached'`. */
+    readonly state: _angular_core.InputSignal<TimelineState>;
+    /** Timestamp shown in the timestamp slot. A `Date` is formatted via `Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' })`; a string is rendered verbatim; `null` omits the timestamp element. Overridden by projected `[twTimelineTimestamp]` content when present. Defaults to `null`. */
+    readonly timestamp: _angular_core.InputSignal<string | Date | null>;
+    /** Machine-readable ISO 8601 datetime for the rendered `<time datetime="…">` attribute. Derived from `timestamp` when it is a `Date` and this input is `null`; required (explicit) when `timestamp` is a string and machine-readability is desired. When `null` with a string timestamp, the timestamp renders as a `<span>` instead. Defaults to `null`. */
+    readonly dateTime: _angular_core.InputSignal<string | null>;
+    /** @internal Direct parent timeline. A `tw-timeline-item` outside a `tw-timeline` is a programmer error — the DI failure throws naturally. */
+    readonly timeline: TimelineComponent;
+    /** @internal */
+    readonly markerSlot: _angular_core.Signal<TimelineMarkerDirective | undefined>;
+    /** @internal */
+    readonly timestampSlot: _angular_core.Signal<TimelineTimestampDirective | undefined>;
+    /** @internal */
+    readonly oppositeSlot: _angular_core.Signal<TimelineOppositeDirective | undefined>;
+    readonly hasMarkerSlot: _angular_core.Signal<boolean>;
+    readonly hasTimestampSlot: _angular_core.Signal<boolean>;
+    readonly hasOppositeSlot: _angular_core.Signal<boolean>;
+    /** @internal 0-based index in the parent timeline's content. -1 until contentChildren materialises. */
+    readonly index: _angular_core.Signal<number>;
+    readonly isFirst: _angular_core.Signal<boolean>;
+    readonly isLast: _angular_core.Signal<boolean>;
+    /**
+     * Leading-connector visibility. In vertical orientation the marker sits at
+     * the top of the body and only the trailing segment is rendered. In
+     * horizontal orientation the marker must stay centered in its row even at
+     * the ends of the timeline, so the leading segment is always rendered — as a
+     * coloured line for non-first items, as an invisible spacer for the first.
+     */
+    readonly renderLeadingConnector: _angular_core.Signal<boolean>;
+    /**
+     * Trailing-connector visibility. Rendered for every item in horizontal
+     * orientation (as a spacer on the last item) so all markers stay centered.
+     * In vertical orientation it is suppressed on the last item — the timeline
+     * ends with the marker, no trailing segment.
+     */
+    readonly renderTrailingConnector: _angular_core.Signal<boolean>;
+    /** @internal `error` state forces the error palette regardless of the color input. */
+    readonly resolvedColor: _angular_core.Signal<TwColor>;
+    /** @internal Previous item's state (drives the leading connector color so a line between two items reads as one color). */
+    readonly previousState: _angular_core.Signal<TimelineState>;
+    /** @internal Previous item's resolved color, for the same reason as `previousState`. */
+    readonly previousColor: _angular_core.Signal<TwColor>;
+    readonly stateLabel: _angular_core.Signal<string | null>;
+    readonly formattedTimestamp: _angular_core.Signal<string>;
+    readonly resolvedDateTime: _angular_core.Signal<string | null>;
+    /** @internal True when the layout needs a third (opposite) column. */
+    readonly hasOppositeColumn: _angular_core.Signal<boolean>;
+    /** @internal Order of the marker side wrapper. Always center column (2) in three-column layouts; in two-column vertical layouts the order varies. Horizontal layouts use CSS grid placement (`row-start-*`) instead, so flex-order utilities are noise — return ''. */
+    private readonly markerOrderClass;
+    /** @internal Order of the body wrapper. Alternate flips body left/right per item. Horizontal layouts use CSS grid placement (`row-start-*`) instead, so flex-order utilities are noise — return ''. */
+    private readonly bodyOrderClass;
+    /** @internal Order of the opposite wrapper. Always left of the marker except on odd-indexed alternate items. */
+    private readonly oppositeOrderClass;
+    /** @internal Width affordance for the marker side. Vertical needs a fixed-ish column; horizontal needs to span the row. */
+    private readonly markerSideSizeClass;
+    /** @internal Width affordance for the body in alternate/split layouts so the marker stays centered. */
+    private readonly bodyFlexClass;
+    /** @internal Width affordance for the opposite column (mirrors the body to keep the marker centered). */
+    private readonly oppositeFlexClass;
+    readonly itemClasses: _angular_core.Signal<string>;
+    readonly markerSideClasses: _angular_core.Signal<string>;
+    readonly markerClasses: _angular_core.Signal<string>;
+    readonly leadingConnectorClasses: _angular_core.Signal<string>;
+    readonly trailingConnectorClasses: _angular_core.Signal<string>;
+    readonly bodyClasses: _angular_core.Signal<string>;
+    readonly oppositeClasses: _angular_core.Signal<string>;
+    readonly numberClasses: _angular_core.Signal<string>;
+    readonly timestampClasses: _angular_core.Signal<string>;
+    readonly enterAnimationClass: _angular_core.Signal<"timeline-item-enter-horizontal" | "timeline-item-enter">;
+    ngAfterContentInit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimelineItemComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TimelineItemComponent, "tw-timeline-item", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "marker": { "alias": "marker"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "timestamp": { "alias": "timestamp"; "required": false; "isSignal": true; }; "dateTime": { "alias": "dateTime"; "required": false; "isSignal": true; }; }, {}, ["markerSlot", "timestampSlot", "oppositeSlot"], ["[twTimelineMarker]", "*", "[twTimelineTimestamp]", "[twTimelineOpposite]"], true, never>;
+}
+
+export { DEFAULT_TW_TIMELINE_SCROLL_LABELS, TW_TIMELINE_SCROLL_LABELS, TimelineComponent, TimelineItemComponent, TimelineMarkerDirective, TimelineOppositeDirective, TimelineTimestampDirective, provideTwTimelineScrollLabels };
+export type { TimelineAlign, TimelineLineStyle, TimelineMarker, TimelineScrollControls, TimelineState, TwTimelineScrollLabels };