@cdevhub/ngx-tw 0.4.0 → 0.6.0

package/fesm2022/cdevhub-ngx-tw-timeline.mjs

@@ -1,18 +1,23 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, makeEnvironmentProviders, Directive, input, contentChildren, inject, DestroyRef, viewChild, signal, computed, afterNextRender, ChangeDetectionStrategy, Component, contentChild } from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, Directive, input, contentChildren, inject, DestroyRef, viewChild, computed, signal, afterRenderEffect, untracked, ChangeDetectionStrategy, Component, contentChild } from '@angular/core';
 import { NgTemplateOutlet } from '@angular/common';
 import { Directionality } from '@angular/cdk/bidi';
 import { tv } from 'tailwind-variants';
 
-/** Default English labels used when `TW_TIMELINE_SCROLL_LABELS` is not provided. */
+/**
+ * Default English labels used when `TW_TIMELINE_SCROLL_LABELS` is not provided.
+ * Typed `Required<TwTimelineScrollLabels>` so readers keep a non-optional
+ * `string` for every key even though the interface itself is all-optional.
+ */
 const DEFAULT_TW_TIMELINE_SCROLL_LABELS = {
     scrollPrevious: 'Scroll to previous events',
     scrollNext: 'Scroll to next events',
+    scrollRegion: 'Timeline events',
 };
 /**
  * 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.
+ * horizontal-overflow affordances — the prev/next chevron buttons and the
+ * scrollable viewport between them. 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
@@ -101,6 +106,17 @@ const timelineVariants = tv({
             // column and stretches through this padding to touch the next item's
             // marker — items butt against each other with no container `gap-*` so
             // the line stays continuous.
+            //
+            // `item: gap-*` is NOT that vertical separation — it is the gutter
+            // between the marker column and the body (a column gap in vertical
+            // orientation, the subgrid row gap in horizontal). It runs past
+            // CLAUDE.md's `gap-3` ceiling because that scale governs spacing
+            // *inside* an element (icon↔label, button groups) against a fixed
+            // ~16–20px glyph, whereas this gutter is measured against a marker
+            // column that itself scales `w-6`→`w-12`. Held at `gap-3`, an `xl`
+            // 48px bubble sits 12px from its text — the body reads as welded to
+            // the marker and every step above `md` becomes visually identical.
+            // The gutter therefore tracks the column: 12/16/20/24/32px.
             xs: { item: 'gap-3', body: 'text-xs gap-1 pb-3', timestamp: 'text-2xs', number: 'text-2xs' },
             sm: { item: 'gap-4', body: 'text-sm gap-1 pb-4', timestamp: 'text-xs', number: 'text-xs' },
             md: { item: 'gap-5', body: 'text-sm gap-1.5 pb-6', timestamp: 'text-xs', number: 'text-xs' },
@@ -164,6 +180,17 @@ const timelineVariants = tv({
         { marker: 'circle', size: 'xs', class: { marker: 'size-6' } },
         { marker: 'circle', size: 'sm', class: { marker: 'size-7' } },
         { marker: 'circle', size: 'md', class: { marker: 'size-8' } },
+        // `size-10` / `size-12` sit above the glyph scale's `size-10` ceiling and
+        // outside the square-interactive scale (which stops at `size-9`), and
+        // neither scale governs here: the circle marker is a *container* — it
+        // wraps a projected `[twTimelineMarker]` icon/avatar or the auto-number —
+        // and the item host is never focusable, so it is not a hit target either.
+        // A container has to out-measure its contents: `<tw-icon size="lg">` is
+        // `size-6` (24px) and `size="xl"` is `size-8` (32px), so capping the bubble
+        // at the `size-9` (36px) hit-target ceiling would leave a 6px rim at `lg`
+        // and a 2px rim at `xl` — the glyph reads as cropped and the ring/border
+        // states have nowhere to render. `size-10` / `size-12` hold a constant 8px
+        // inset at both steps instead.
         { marker: 'circle', size: 'lg', class: { marker: 'size-10' } },
         { marker: 'circle', size: 'xl', class: { marker: 'size-12' } },
         // Vertical-only: `mt-*` nudges the small dot down so its vertical center
@@ -354,9 +381,13 @@ function resolveConnectorClasses(state, color, lineStyle) {
 // to clientWidth, the overflow check fails permanently, and the chevrons
 // never enable. The per-density min-w-* on each item still establishes the
 // floor.
+// The viewport carries `tabindex="0"` so keyboard-only users can reach and
+// arrow-scroll it (axe: scrollable-region-focusable), which makes it a
+// focusable element and therefore obliges it to carry the canonical focus ring.
 const HORIZONTAL_VIEWPORT_CLASSES = 'tw-scrollbar-none grid grid-flow-col auto-cols-max ' +
     '[grid-template-rows:minmax(0,1fr)_auto] ' +
-    'overflow-x-auto scroll-smooth motion-reduce:scroll-auto w-full';
+    'overflow-x-auto scroll-smooth motion-reduce:scroll-auto w-full ' +
+    'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500';
 // ── Chevron button class string ──
 // Shared by both overflow chevron buttons. Positioned absolutely against the
 // timeline host (which carries `relative` in horizontal orientation via the
@@ -480,26 +511,36 @@ class TimelineComponent {
     _scrollLabelsOverride = inject(TW_TIMELINE_SCROLL_LABELS, {
         optional: true,
     });
-    /** @internal Live `dir` from CDK `Directionality`. */
-    _cdkDir = signal(this._directionality?.value ?? 'ltr', /* @ts-ignore */
+    /**
+     * @internal Live `dir` from CDK `Directionality`. Read straight from
+     * `valueSignal` (CDK 22+) so `_isRtl` re-evaluates on a runtime `dir` flip
+     * with no manual subscription mirror.
+     */
+    _cdkDir = computed(() => this._directionality?.valueSignal() ?? 'ltr', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_cdkDir" }] : /* istanbul ignore next */ []));
     /** @internal True when the host renders inside a `dir="rtl"` ancestor. */
     _isRtl = computed(() => this._cdkDir() === 'rtl', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_isRtl" }] : /* istanbul ignore next */ []));
     /**
-     * @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.
+     * @internal Defaults to `false` until the first measurement runs in the
+     * `afterRenderEffect` in the constructor. This avoids a one-frame
+     * "enabled-then-disabled" flash where the buttons appear live before the
+     * scroll state has been read.
      */
     _canScrollPrev = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_canScrollPrev" }] : /* istanbul ignore next */ []));
     _canScrollNext = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_canScrollNext" }] : /* istanbul ignore next */ []));
     /** @internal Resolved label record. Falls back to English defaults for any missing key. */
-    scrollLabels = computed(() => ({
-        ...DEFAULT_TW_TIMELINE_SCROLL_LABELS,
-        ...(this._scrollLabelsOverride ?? {}),
-    }), /* @ts-ignore */
+    scrollLabels = computed(() => {
+        // Drop explicitly-undefined keys before merging. A plain spread would let
+        // `{ scrollRegion: undefined }` overwrite the default with undefined,
+        // which reaches the template as a null `aria-label` and silently strips
+        // the scroll region's accessible name. `Required<>` then guarantees the
+        // template a string for every label.
+        const override = Object.fromEntries(Object.entries(this._scrollLabelsOverride ?? {}).filter(([, v]) => v !== undefined));
+        return { ...DEFAULT_TW_TIMELINE_SCROLL_LABELS, ...override };
+    }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "scrollLabels" }] : /* istanbul ignore next */ []));
     /** @internal True when the prev button should be aria-hidden + visually suppressed. */
     _prevButtonHidden = computed(() => {
@@ -557,21 +598,45 @@ class TimelineComponent {
     }
     _resizeObserver = null;
     constructor() {
-        // The viewport materialises on the first frame after horizontal
-        // orientation is committed; afterNextRender hooks into that point.
-        afterNextRender(() => this._setupScrollDetection());
+        // The horizontal viewport is gated behind `@if (orientation() ===
+        // 'horizontal')`, so scroll detection has to re-run whenever orientation
+        // is (re)committed — not just once at mount. The previous
+        // `afterNextRender(() => this._setupScrollDetection())` fired a single
+        // time, and `_setupScrollDetection()` early-returns when the orientation
+        // is vertical: a timeline mounted vertical and later flipped to horizontal
+        // (`[orientation]="isWide() ? 'horizontal' : 'vertical'"`) never got a
+        // ResizeObserver and never measured, so `_canScrollPrev`/`_canScrollNext`
+        // stayed `false` and both chevrons were permanently invisible AND
+        // disabled. Same bug class `carousel.ts` records having already fixed.
+        //
+        // `afterRenderEffect` is the right primitive rather than `effect()`: the
+        // work is a DOM *measurement* that must observe the embedded view holding
+        // the viewport, and a plain `effect()` runs before this cycle's embedded
+        // views are refreshed. Tracking `_viewportRef()` as well as `orientation()`
+        // makes it self-healing — if the view query has not resolved on the pass
+        // that commits `'horizontal'`, the effect re-runs when it does.
+        //
+        // The body is wrapped in `untracked()` so the tracked region is exactly
+        // `{ orientation, _viewportRef }`: `_setupScrollDetection()` writes
+        // `_canScrollPrev`/`_canScrollNext`, and reading them here would be a
+        // read-write cycle of the shape CLAUDE.md bans.
+        afterRenderEffect(() => {
+            this.orientation();
+            this._viewportRef();
+            untracked(() => this._setupScrollDetection());
+        });
         this._destroyRef.onDestroy(() => {
             this._resizeObserver?.disconnect();
             this._resizeObserver = null;
         });
-        if (this._directionality) {
-            const sub = this._directionality.change.subscribe((value) => {
-                this._cdkDir.set(value);
-            });
-            this._destroyRef.onDestroy(() => sub.unsubscribe());
-        }
     }
     _setupScrollDetection() {
+        // Re-entrant: this runs on every orientation/viewport change, so drop any
+        // observer bound to the previous (now detached) viewport element first.
+        // Done before the early return so flipping back to vertical also releases
+        // it. `_destroyRef.onDestroy` still owns the final teardown.
+        this._resizeObserver?.disconnect();
+        this._resizeObserver = null;
         // Vertical orientation never renders the viewport — nothing to do.
         if (this.orientation() !== 'horizontal')
             return;
@@ -668,7 +733,7 @@ class TimelineComponent {
         state,
     }).number();
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: TimelineComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.7", type: TimelineComponent, isStandalone: true, selector: "tw-timeline", inputs: { orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, align: { classPropertyName: "align", publicName: "align", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, lineStyle: { classPropertyName: "lineStyle", publicName: "lineStyle", isSignal: true, isRequired: false, transformFunction: null }, scrollControls: { classPropertyName: "scrollControls", publicName: "scrollControls", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "list" }, properties: { "class": "rootClasses()", "attr.aria-orientation": "orientation() === \"horizontal\" ? \"horizontal\" : null" } }, queries: [{ propertyName: "items", predicate: TimelineItemComponent, isSignal: true }], viewQueries: [{ propertyName: "_viewportRef", first: true, predicate: ["scrollViewport"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.7", type: TimelineComponent, isStandalone: true, selector: "tw-timeline", inputs: { orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, align: { classPropertyName: "align", publicName: "align", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, lineStyle: { classPropertyName: "lineStyle", publicName: "lineStyle", isSignal: true, isRequired: false, transformFunction: null }, scrollControls: { classPropertyName: "scrollControls", publicName: "scrollControls", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.role": "orientation() === \"horizontal\" ? null : \"list\"", "class": "rootClasses()" } }, queries: [{ propertyName: "items", predicate: TimelineItemComponent, isSignal: true }], viewQueries: [{ propertyName: "_viewportRef", first: true, predicate: ["scrollViewport"], descendants: true, isSignal: true }], ngImport: i0, template: `
     <ng-template #itemsTpl>
       <ng-content />
     </ng-template>
@@ -696,6 +761,9 @@ class TimelineComponent {
       </button>
       <div
         #scrollViewport
+        role="list"
+        tabindex="0"
+        [attr.aria-label]="scrollLabels().scrollRegion"
         [class]="horizontalViewportClasses"
         (scroll)="_onScroll()"
       >
@@ -733,9 +801,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     imports: [NgTemplateOutlet],
                     host: {
-                        role: 'list',
+                        // The `list` role lives on the host only in vertical orientation, where the
+                        // projected `tw-timeline-item` elements (role="listitem") are its direct
+                        // children. In horizontal orientation the host also owns the two scroll
+                        // chevrons, which are not `listitem`s — a `list` here would own children its
+                        // role forbids (axe: aria-required-children). The role moves to the scroll
+                        // viewport instead, which does contain exactly the items.
+                        //
+                        // `aria-orientation` is deliberately absent: `list` does not support it
+                        // (axe: aria-allowed-attr), and the axis is a purely visual decision that
+                        // carries no meaning for assistive tech.
+                        '[attr.role]': 'orientation() === "horizontal" ? null : "list"',
                         '[class]': 'rootClasses()',
-                        '[attr.aria-orientation]': 'orientation() === "horizontal" ? "horizontal" : null',
                     },
                     // The projected items live inside a single `<ng-template #itemsTpl>` and are
                     // outletted into either the horizontal viewport or the vertical pass-through.
@@ -772,6 +849,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
       </button>
       <div
         #scrollViewport
+        role="list"
+        tabindex="0"
+        [attr.aria-label]="scrollLabels().scrollRegion"
         [class]="horizontalViewportClasses"
         (scroll)="_onScroll()"
       >
@@ -981,7 +1061,10 @@ class TimelineItemComponent {
         if (this.timeline.orientation() === 'horizontal')
             return '';
         // Pin the column to the marker's own width so siblings stay aligned even
-        // when items render slightly different bubble content.
+        // when items render slightly different bubble content. These mirror the
+        // circle-marker diameters one-for-one (`size-6`…`size-12` above) — the
+        // `w-10`/`w-12` steps are off-scale for the same reason the bubbles are,
+        // and diverging here would knock every marker off the connector's axis.
         switch (this.timeline.size()) {
             case 'xs':
                 return 'w-6';