ab-nextjs-components 0.2.1 โ†’ 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -52,6 +52,7 @@ import {
52
52
  isValidElement,
53
53
  useCallback,
54
54
  useContext,
55
+ useEffect,
55
56
  useId,
56
57
  useMemo,
57
58
  useRef,
@@ -62,6 +63,7 @@ import {
62
63
  type ReactElement,
63
64
  type ReactNode,
64
65
  type Ref,
66
+ type RefObject,
65
67
  } from 'react';
66
68
  // ๐Ÿงต class-name joiner
67
69
  import clsx from 'clsx';
@@ -137,6 +139,9 @@ export interface AbCarouselProps {
137
139
  slideLabel?: (n: number, total: number) => string;
138
140
  // ๐Ÿ“ฃ live-region text factory, or false to disable announcements (default "Slide 3 of 9: Title")
139
141
  announce?: ((n: number, total: number, title?: string) => string) | false;
142
+ // ๐Ÿ“ 0.2.3 (Joseph, Welcome 0.2.21): size the track to the ACTIVE slide (animated, reduced-motion aware)
143
+ // instead of the tallest one (default false: one grid cell, height = tallest, CLS 0)
144
+ autoHeight?: boolean;
140
145
  // ๐Ÿงฑ element for the region (default 'section')
141
146
  as?: 'section' | 'div';
142
147
  // ๐Ÿ†” id of the region
@@ -187,6 +192,8 @@ export interface AbCarouselContextValue {
187
192
  trackId: string;
188
193
  // ๐Ÿ†” id of slide i
189
194
  slideId: (i: number) => string;
195
+ // ๐Ÿ“ 0.2.3: does the track follow the active slide's height?
196
+ autoHeight: boolean;
190
197
  // ๐Ÿ‘† swipe settings (read by the track)
191
198
  swipe: { enabled: boolean; threshold?: number; ignore?: string };
192
199
  }
@@ -204,7 +211,7 @@ export function useAbCarousel(): AbCarouselContextValue {
204
211
  // ๐Ÿ” nearest carousel
205
212
  const ctx = useContext(AbCarouselContext);
206
213
  // ๐Ÿ’ฅ used outside โ†’ explain how to fix it
207
- if (!ctx) throw new Error('useAbCarousel() must be used inside <AbCarousel>.');
214
+ if (!ctx) throw new Error('useAbCarousel() must be used inside <AbCarousel> or <AbCarouselProvider>.');
208
215
  // ๐Ÿ“ฆ
209
216
  return ctx;
210
217
  }
@@ -271,7 +278,31 @@ const readAbServerDir = (): AbCarouselDir => 'ltr';
271
278
  *
272
279
  * ๐ŸŽฌ Motion: slides cross-fade + shift 24px (280ms); reduced motion โ†’ 120ms fade, no transform.
273
280
  */
274
- export function AbCarousel(props: AbCarouselProps) {
281
+ // โš™๏ธ 0.2.3: the provider takes the state props only (no element of its own)
282
+ export type AbCarouselProviderProps = Omit<AbCarouselProps, 'as' | 'id' | 'className' | 'style' | 'ref'>;
283
+
284
+ // ๐Ÿงท 0.2.3: what the region element needs (spread by <AbCarousel>, or by the consumer in headless mode)
285
+ export interface AbCarouselRegionProps {
286
+ className: string; // ๐Ÿท๏ธ 'AbCarousel' + the module class (carries the slide-step tokens)
287
+ 'aria-roledescription': 'carousel'; // โ™ฟ
288
+ 'aria-label': string; // ๐Ÿท๏ธ
289
+ 'data-ab-part': 'carousel'; // ๐Ÿงฉ
290
+ 'data-dir': AbCarouselDir; // ๐ŸŒ
291
+ 'data-reduced-motion': string; // โ™ฟ CSS switch
292
+ 'data-ab-reduced-motion': string; // โ™ฟ ab-nextjs-animations switch
293
+ 'data-ab-direction'?: AbSlideStepDirection; // ๐Ÿงญ
294
+ 'data-hydrated': string; // ๐ŸŸข
295
+ onKeyDown: (event: KeyboardEvent<HTMLElement>) => void; // โŒจ๏ธ โ†/โ†’ Home/End while focus is inside
296
+ }
297
+
298
+ // ๐Ÿง  0.2.3: region props + the live message, for headless consumers (null outside a provider)
299
+ const AbCarouselRegionContext = createContext<{ regionProps: AbCarouselRegionProps; message: string } | null>(null);
300
+
301
+ /**
302
+ * ๐Ÿง  the whole carousel brain (state, ids, keyboard, announcements), shared by <AbCarousel> and
303
+ * <AbCarouselProvider>. Internal: render either of those, not this.
304
+ */
305
+ function useAbCarouselController(props: AbCarouselProviderProps): { value: AbCarouselContextValue; regionProps: AbCarouselRegionProps; message: string } {
275
306
  // ๐Ÿงฉ destructure with defaults
276
307
  const {
277
308
  label, // ๐Ÿท๏ธ
@@ -287,14 +318,10 @@ export function AbCarousel(props: AbCarouselProps) {
287
318
  swipeThreshold, // ๐Ÿ“
288
319
  swipeIgnore, // ๐Ÿ™ˆ
289
320
  reducedMotion: reducedMotionMode = 'auto', // โ™ฟ
321
+ autoHeight = false, // ๐Ÿ“ 0.2.3
290
322
  slideLabel = defaultAbCarouselSlideLabel, // ๐Ÿท๏ธ
291
323
  announce = defaultAbCarouselAnnouncement, // ๐Ÿ“ฃ
292
- as: Tag = 'section', // ๐Ÿงฑ
293
- id, // ๐Ÿ†”
294
- className, // ๐Ÿท๏ธ
295
- style, // ๐ŸŽจ
296
- ref, // ๐Ÿ”—
297
- children, // ๐Ÿงฉ
324
+ children, // ๐Ÿงฉ (only used to count the slides)
298
325
  } = props;
299
326
 
300
327
  // ๐Ÿ”ข slide count: explicit, else counted from the track
@@ -373,36 +400,157 @@ export function AbCarousel(props: AbCarouselProps) {
373
400
 
374
401
  // ๐Ÿง  context value (memoised)
375
402
  const value = useMemo<AbCarouselContextValue>(() => ({
376
- index, count, loop, dir, reducedMotion, hydrated, direction, previousIndex, goTo, next, prev, canPrev, canNext, titles, slideLabel, trackId, slideId,
403
+ index, count, loop, dir, reducedMotion, hydrated, direction, previousIndex, goTo, next, prev, canPrev, canNext, titles, slideLabel, trackId, slideId, autoHeight,
377
404
  swipe: { enabled: swipe && count > 1, threshold: swipeThreshold, ignore: swipeIgnore },
378
- }), [index, count, loop, dir, reducedMotion, hydrated, direction, previousIndex, goTo, next, prev, canPrev, canNext, titles, slideLabel, trackId, slideId, swipe, swipeThreshold, swipeIgnore]);
405
+ }), [index, count, loop, dir, reducedMotion, hydrated, direction, previousIndex, goTo, next, prev, canPrev, canNext, titles, slideLabel, trackId, slideId, autoHeight, swipe, swipeThreshold, swipeIgnore]);
406
+
407
+ // ๐Ÿงท the region's attributes (memo-free: cheap, and onKeyDown closes over the latest state)
408
+ const regionProps: AbCarouselRegionProps = {
409
+ className: clsx('AbCarousel', styles.carousel), // ๐Ÿท๏ธ + the slide-step tokens
410
+ 'aria-roledescription': 'carousel', // โ™ฟ "carousel" instead of "region"
411
+ 'aria-label': label, // ๐Ÿท๏ธ accessible name
412
+ 'data-ab-part': 'carousel', // ๐Ÿงฉ part hook
413
+ 'data-dir': dir, // ๐ŸŒ
414
+ 'data-reduced-motion': String(reducedMotion), // โ™ฟ CSS switch
415
+ 'data-ab-reduced-motion': String(reducedMotion), // โ™ฟ ab-nextjs-animations switch (prop OR OS)
416
+ 'data-ab-direction': direction ?? undefined, // ๐Ÿงญ forward / back for .ab-slide-step-*
417
+ 'data-hydrated': String(hydrated), // ๐ŸŸข
418
+ onKeyDown, // โŒจ๏ธ
419
+ };
420
+ return { value, regionProps, message }; // ๐Ÿ“ฆ
421
+ }
379
422
 
423
+ /**
424
+ * ๐ŸŽ  AbCarousel โ€” accessible slide carousel / walkthrough (Welcome v6, gap G31). See the a11y notes above
425
+ * `useAbCarouselController`. It renders the region element itself; for a layout where the carousel can't own one
426
+ * wrapper (e.g. it would have to wrap <main>), use <AbCarouselProvider> + useAbCarouselRegion() instead.
427
+ */
428
+ export function AbCarousel(props: AbCarouselProps) {
429
+ const { as: Tag = 'section', id, className, style, ref, children } = props; // ๐Ÿงฑ element props
430
+ const { value, regionProps, message } = useAbCarouselController(props); // ๐Ÿง 
380
431
  // ๐Ÿ–ผ๏ธ render
381
432
  return (
382
433
  <AbCarouselContext.Provider value={value}>
383
- <Tag
384
- ref={ref as Ref<HTMLElement & HTMLDivElement>} // ๐Ÿ”—
385
- id={id} // ๐Ÿ†”
386
- className={clsx('AbCarousel', styles.carousel, className)} // ๐Ÿท๏ธ
387
- style={style} // ๐ŸŽจ
388
- aria-roledescription="carousel" // โ™ฟ "carousel" instead of "region"
389
- aria-label={label} // ๐Ÿท๏ธ accessible name
390
- data-ab-part="carousel" // ๐Ÿงฉ part hook
391
- data-dir={dir} // ๐ŸŒ
392
- data-reduced-motion={String(reducedMotion)} // โ™ฟ CSS switch
393
- data-ab-reduced-motion={String(reducedMotion)} // โ™ฟ ab-nextjs-animations switch (prop OR OS)
394
- data-ab-direction={direction ?? undefined} // ๐Ÿงญ forward / back for .ab-slide-step-*
395
- data-hydrated={String(hydrated)} // ๐ŸŸข
396
- onKeyDown={onKeyDown} // โŒจ๏ธ
397
- >
398
- {children}
399
- {/* ๐Ÿ“ฃ polite live region (visually hidden) */}
400
- <div className={styles.srOnly} aria-live="polite" aria-atomic="true" data-ab-part="status">{message}</div>
401
- </Tag>
434
+ <AbCarouselRegionContext.Provider value={{ regionProps, message }}>
435
+ <Tag
436
+ ref={ref as Ref<HTMLElement & HTMLDivElement>} // ๐Ÿ”—
437
+ id={id} // ๐Ÿ†”
438
+ {...regionProps} // โ™ฟ roledescription / label / data-* / keyboard
439
+ className={clsx(regionProps.className, className)} // ๐Ÿท๏ธ
440
+ style={style} // ๐ŸŽจ
441
+ >
442
+ {children}
443
+ {/* ๐Ÿ“ฃ polite live region (visually hidden) */}
444
+ <div className={styles.srOnly} aria-live="polite" aria-atomic="true" data-ab-part="status">{message}</div>
445
+ </Tag>
446
+ </AbCarouselRegionContext.Provider>
402
447
  </AbCarouselContext.Provider>
403
448
  );
404
449
  }
405
450
 
451
+ // ===== 0.2.3 HEADLESS MODE: <AbCarouselProvider /> + useAbCarouselRegion() + <AbCarouselStatus /> ===== //
452
+
453
+ /**
454
+ * ๐Ÿง  AbCarouselProvider โ€” 0.2.3 (Joseph, Welcome 0.2.21): the carousel state WITHOUT an element, so it no longer
455
+ * has to wrap <main>. Put it high enough for every control (header counter, aside dots, main track), then mark
456
+ * ONE element as the region with `useAbCarouselRegion()` and drop <AbCarouselStatus /> inside it:
457
+ *
458
+ * <AbCarouselProvider label="Welcome" count={9}>
459
+ * <AbAppLayout mainHeader={<AbCarouselCounter />} main={<Slides />} />
460
+ * </AbCarouselProvider>
461
+ * function Slides() { const region = useAbCarouselRegion(); return (
462
+ * <div {...region}><AbCarouselTrack>โ€ฆ</AbCarouselTrack><AbCarouselStatus /></div>) }
463
+ *
464
+ * ๐Ÿ”ข Pass `count` when the track isn't a direct (element-tree) descendant of the provider's children.
465
+ */
466
+ export function AbCarouselProvider(props: AbCarouselProviderProps) {
467
+ const { value, regionProps, message } = useAbCarouselController(props); // ๐Ÿง 
468
+ return (
469
+ <AbCarouselContext.Provider value={value}>
470
+ <AbCarouselRegionContext.Provider value={{ regionProps, message }}>{props.children}</AbCarouselRegionContext.Provider>
471
+ </AbCarouselContext.Provider>
472
+ );
473
+ }
474
+
475
+ /** ๐Ÿงท useAbCarouselRegion โ€” 0.2.3: the attributes for YOUR region element (spread them; merge your own className). */
476
+ export function useAbCarouselRegion(): AbCarouselRegionProps {
477
+ const ctx = useContext(AbCarouselRegionContext); // ๐Ÿ”
478
+ if (!ctx) throw new Error('useAbCarouselRegion() must be used inside <AbCarouselProvider> or <AbCarousel>.'); // ๐Ÿ’ฅ
479
+ return ctx.regionProps; // ๐Ÿ“ฆ
480
+ }
481
+
482
+ /** ๐Ÿ“ฃ AbCarouselStatus โ€” 0.2.3: the polite live region ("Slide 3 of 9: Title"); render it once, inside the region. */
483
+ export function AbCarouselStatus({ className }: { className?: string }) {
484
+ const ctx = useContext(AbCarouselRegionContext); // ๐Ÿ”
485
+ if (!ctx) throw new Error('<AbCarouselStatus> must be used inside <AbCarouselProvider> or <AbCarousel>.'); // ๐Ÿ’ฅ
486
+ return <div className={clsx(styles.srOnly, className)} aria-live="polite" aria-atomic="true" data-ab-part="status">{ctx.message}</div>;
487
+ }
488
+
489
+ // ===== 0.2.3 useAbCarouselKeys: arrow keys OUTSIDE the region ===== //
490
+
491
+ // โš™๏ธ options
492
+ export interface UseAbCarouselKeysOptions {
493
+ // ๐ŸŽš๏ธ bind or not (default true), e.g. false while a sheet is up
494
+ enabled?: boolean;
495
+ // โฎ๏ธโญ๏ธ Home / End too? Default false: on `document` they would steal the page's own Home / End scroll
496
+ homeEnd?: boolean;
497
+ }
498
+
499
+ // ๐Ÿ™… focus places that own their keys, beyond the region's ignore list: an open dialog, editable text
500
+ const AB_CAROUSEL_KEYS_SKIP = '[role="dialog"], [aria-modal="true"], [contenteditable=""], [contenteditable="true"]';
501
+
502
+ /**
503
+ * โŒจ๏ธ useAbCarouselKeys โ€” 0.2.3 (Joseph, Welcome 0.2.21): the carousel's โ†/โ†’ (RTL-aware) on a SCOPE element, not
504
+ * just inside the region. The listener sits on that element only, so keys act only while focus is within it.
505
+ * Call it under <AbCarouselProvider> (or <AbCarousel>):
506
+ *
507
+ * useAbCarouselKeys('main') // โœ… RECOMMENDED: the layout's <main> (core's [data-ab-part="main"], else <main>)
508
+ * useAbCarouselKeys(slidesRef) // ๐Ÿ“Œ any element you hold a ref to
509
+ * useAbCarouselKeys('document') // โš ๏ธ OPT-IN only: every key on the page (header, asideโ€ฆ) โ€” a global
510
+ * // hijack; Joseph's e2e "no global hijack" forbids it on Welcome
511
+ *
512
+ * There is no default: the scope is always explicit.
513
+ *
514
+ * ๐Ÿงญ Why a hook (and not core passing the region props to <main>): core stays carousel-agnostic, the hook works
515
+ * with any layout, and the region's own handler is untouched. Safety rules:
516
+ * - ๐Ÿ™ˆ skips the same targets the region skips (inputs, textareas, selects, tabs, radio groups, slidersโ€ฆ), plus
517
+ * editable text and anything inside an open dialog / modal
518
+ * - ๐ŸŽ  skips events from INSIDE a carousel region (its own handler already moved, so no double step)
519
+ * - โŒจ๏ธ never with Alt / Ctrl / Meta / Shift, and never an event someone already handled (defaultPrevented)
520
+ * - โฎ๏ธโญ๏ธ Home / End only with `homeEnd: true`
521
+ */
522
+ export function useAbCarouselKeys(target: 'main' | 'document' | RefObject<HTMLElement | null>, options: UseAbCarouselKeysOptions = {}): void {
523
+ const { enabled = true, homeEnd = false } = options;
524
+ const ctx = useAbCarousel(); // ๐Ÿง 
525
+ const latest = useRef(ctx); // ๐Ÿ” the latest state for the listener (no re-binding per slide)
526
+ useEffect(() => { latest.current = ctx; });
527
+ useEffect(() => {
528
+ if (!enabled) return;
529
+ // ๐ŸŽฏ the scope: 'main' = core's main pane (AbMainLayout renders data-ab-part="main"), else the first <main>
530
+ const el: HTMLElement | Document | null = target === 'document' ? document
531
+ : target === 'main' ? document.querySelector<HTMLElement>('[data-ab-part="main"]') ?? document.querySelector('main')
532
+ : target.current;
533
+ if (!el) return;
534
+ const onKey = (event: Event) => {
535
+ const e = event as globalThis.KeyboardEvent; // โŒจ๏ธ
536
+ if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return; // ๐Ÿ™…
537
+ const from = e.target as Element | null; // ๐ŸŽฏ
538
+ if (from?.closest?.(AB_CAROUSEL_KEY_IGNORE_SELECTOR) || from?.closest?.(AB_CAROUSEL_KEYS_SKIP)) return; // ๐Ÿ™ˆ owns its keys
539
+ if (from?.closest?.('[data-ab-part="carousel"]')) return; // ๐ŸŽ  the region already handled it
540
+ const c = latest.current; // ๐Ÿง 
541
+ const action = getAbCarouselKeyAction(e.key, c.dir); // ๐Ÿ—บ๏ธ
542
+ if (!action || (!homeEnd && (action === 'first' || action === 'last'))) return; // ๐Ÿ™…
543
+ e.preventDefault(); // ๐Ÿ›‘ no sideways scroll
544
+ if (action === 'next') c.next('key'); // โญ๏ธ
545
+ else if (action === 'prev') c.prev('key'); // โฎ๏ธ
546
+ else if (action === 'first') c.goTo(0, 'key'); // โฎ๏ธโฎ๏ธ
547
+ else c.goTo(c.count - 1, 'key'); // โญ๏ธโญ๏ธ
548
+ };
549
+ el.addEventListener('keydown', onKey); // ๐ŸŽง
550
+ return () => el.removeEventListener('keydown', onKey); // ๐Ÿงน
551
+ }, [target, enabled, homeEnd]);
552
+ }
553
+
406
554
  // ===== <AbCarouselTrack /> ===== //
407
555
 
408
556
  // โš™๏ธ track props
@@ -411,6 +559,8 @@ export interface AbCarouselTrackProps {
411
559
  className?: string;
412
560
  // ๐ŸŽจ inline style
413
561
  style?: CSSProperties;
562
+ // ๐Ÿ“ 0.2.3: override the carousel's `autoHeight` for this track
563
+ autoHeight?: boolean;
414
564
  // ๐ŸŽž๏ธ <AbCarouselSlide> children (fragments / arrays are fine)
415
565
  children?: ReactNode;
416
566
  }
@@ -419,11 +569,25 @@ export interface AbCarouselTrackProps {
419
569
  * ๐ŸŽž๏ธ AbCarouselTrack โ€” stacks the slides in one grid cell (height = tallest slide โ†’ no layout shift)
420
570
  * and owns the swipe gesture (`touch-action: pan-y` keeps vertical scrolling).
421
571
  */
422
- export function AbCarouselTrack({ className, style, children }: AbCarouselTrackProps) {
572
+ export function AbCarouselTrack({ className, style, autoHeight: autoHeightProp, children }: AbCarouselTrackProps) {
423
573
  // ๐Ÿง  carousel state
424
574
  const ctx = useAbCarousel();
425
575
  // ๐ŸŽฏ element for the swipe hook
426
576
  const trackRef = useRef<HTMLDivElement>(null);
577
+ // ๐Ÿ“ 0.2.3 autoHeight: the track's height follows the active slide (measured, so it also tracks content changes)
578
+ const autoHeight = autoHeightProp ?? ctx.autoHeight;
579
+ const [height, setHeight] = useState<number | null>(null); // ๐Ÿ“ px, null = not measured yet (SSR: tallest slide)
580
+ useEffect(() => {
581
+ const track = trackRef.current;
582
+ if (!autoHeight || !track) return;
583
+ const active = track.querySelector<HTMLElement>(':scope > [data-ab-part="slide"][data-position="active"]'); // โœ… the slide in view
584
+ if (!active) return;
585
+ const measure = () => { const h = Math.ceil(active.getBoundingClientRect().height || active.offsetHeight); setHeight((p) => (p === h ? p : h)); }; // ๐Ÿงฎ no loop
586
+ measure(); // ๐Ÿ“ now
587
+ const ro = typeof ResizeObserver === 'function' ? new ResizeObserver(measure) : null; // ๐Ÿ‘€ fonts, images, viewport
588
+ ro?.observe(active);
589
+ return () => ro?.disconnect(); // ๐Ÿงน
590
+ }, [autoHeight, ctx.index, ctx.count]);
427
591
  // ๐Ÿ‘† swipe โ†’ next / prev (RTL-aware via dir)
428
592
  useAbSwipe(trackRef, {
429
593
  onNext: () => ctx.next('swipe'), // โญ๏ธ
@@ -437,7 +601,14 @@ export function AbCarouselTrack({ className, style, children }: AbCarouselTrackP
437
601
  const slides = flattenAbSlides(children);
438
602
  // ๐Ÿ–ผ๏ธ render, giving each slide its index
439
603
  return (
440
- <div ref={trackRef} id={ctx.trackId} className={clsx(styles.track, className)} style={style} data-ab-part="track">
604
+ <div
605
+ ref={trackRef}
606
+ id={ctx.trackId}
607
+ className={clsx(styles.track, autoHeight && AB_MOTION.size, className)} // ๐ŸŽฌ 0.2.3: height motion from ab-nextjs-animations
608
+ style={autoHeight && height != null ? { ...style, height: `${height}px` } : style} // ๐Ÿ“ 0.2.3: the active slide's height
609
+ data-ab-part="track"
610
+ data-auto-height={autoHeight ? 'true' : undefined} // ๐Ÿ“ CSS: top-aligned slides + the height transition
611
+ >
441
612
  {slides.map((slide, i) => (
442
613
  // ๐Ÿ”ข index provider per slide (keys come from the consumer, else the position)
443
614
  <AbCarouselSlideIndexContext.Provider key={slide.key ?? i} value={i}>{slide}</AbCarouselSlideIndexContext.Provider>
@@ -54,7 +54,17 @@
54
54
  --ab-slide-step-easing: var(--ab-carousel-ease, cubic-bezier(0.2, 0.8, 0.2, 1)); /* ๐Ÿ“ˆ */
55
55
  --ab-slide-step-distance: var(--ab-carousel-shift, 24px); /* โ†”๏ธ */
56
56
  --ab-slide-step-flip: 1; /* ๐ŸŒ LTR */
57
- --_accent: var(--ab-carousel-accent, var(--ab-primary, #a67c52)); /* ๐ŸŸค bronze */
57
+ --_accent: var(--ab-carousel-accent, var(--ab-color-accent, var(--ab-primary, #a67c52))); /* ๐ŸŸค bronze (0.2.3: theme accent first) */
58
+ }
59
+
60
+ /* ๐ŸŸค 0.2.3 (Joseph, Welcome 0.2.21): headless mode renders parts (dots, Prev / Next, counter) OUTSIDE the region,
61
+ where the region's `--_accent` doesn't exist and the bronze turned grey. Every part now resolves the accent ON ITS
62
+ OWN, with the same chain: --ab-carousel-accent, then the theme accent, then --ab-primary, then bronze. */
63
+ .nav,
64
+ .dots,
65
+ .dot,
66
+ .counter {
67
+ --_accent: var(--ab-carousel-accent, var(--ab-color-accent, var(--ab-primary, #a67c52))); /* ๐ŸŸค */
58
68
  }
59
69
 
60
70
  /* ๐ŸŒ RTL: mirror the slide offsets */
@@ -68,6 +78,17 @@
68
78
  touch-action: pan-y; /* ๐Ÿ‘† vertical scroll stays native; horizontal moves reach useAbSwipe */
69
79
  }
70
80
 
81
+ /* ๐Ÿ“ 0.2.3 (Joseph, Welcome 0.2.21) autoHeight: the track takes the ACTIVE slide's height (set inline from a
82
+ ResizeObserver); slides keep their own height (top-aligned, not stretched to the tallest) and the taller leaving
83
+ slide is clipped. ๐ŸŽฌ The height animation is ab-nextjs-animations' .ab-motion-size (added in JS), timed with the
84
+ carousel tokens; it snaps for prefers-reduced-motion AND for the region's data-ab-reduced-motion (the prop). */
85
+ .track[data-auto-height='true'] {
86
+ overflow: hidden; /* โœ‚๏ธ a taller inactive slide never spills */
87
+ align-items: start; /* โฌ†๏ธ each slide keeps its natural height (the measured one) */
88
+ --ab-motion-duration: var(--ab-carousel-duration, 280ms); /* โฑ๏ธ = the slide step */
89
+ --ab-motion-easing: var(--ab-carousel-ease, cubic-bezier(0.2, 0.8, 0.2, 1)); /* ๐Ÿ“ˆ */
90
+ }
91
+
71
92
  /* ๐Ÿ–ผ๏ธ slide (inactive by default; enter / leave motion = .ab-slide-step-in / -out from ab-nextjs-animations) */
72
93
  .slide {
73
94
  grid-area: 1 / 1; /* ๐Ÿงฑ stacked */
@@ -188,6 +188,33 @@
188
188
  /* ๐Ÿ“ฑ the mobile main header: 56px row, logo left, 44px globe + theme buttons right */
189
189
  .mh { box-sizing: border-box; display: flex; align-items: center; block-size: 100%; min-block-size: 56px; padding: 0 4px 0 16px; gap: 0; background: transparent; }
190
190
  .mh > .logoRow { flex: 1 1 auto; }
191
+ /* โž• 0.2.3 (Joseph, Welcome 0.2.21): with a `row`, the header is a column: the 56px bar, then the extra row */
192
+ .mhStack { flex-direction: column; align-items: stretch; padding: 0; block-size: auto; } /* ๐Ÿงฑ */
193
+ .mhBar { box-sizing: border-box; display: flex; align-items: center; min-block-size: 56px; padding: 0 4px 0 16px; } /* ๐Ÿ“ the same bar */
194
+ .mhBar > .logoRow { flex: 1 1 auto; } /* โ†”๏ธ */
195
+ .mhRow { box-sizing: border-box; display: flex; align-items: center; gap: 8px; min-block-size: 0; padding: 0 16px 8px; } /* โž• e.g. a counter row */
196
+ /* ๐Ÿ“ 0.2.3 compact (Welcome v6 mock `.mob .top{height:48px;padding:0 18px}`): a 48px bar, 18px start inset; the 44px
197
+ buttons keep their hit area and the end inset stays 4px so the last one lines up with the 44px grid */
198
+ /* ๐Ÿงฉ 0.2.3 no-JS language list: <details> around the globe; the list drops below it, end-aligned */
199
+ .langDetails { position: relative; flex: none; } /* ๐Ÿ“Œ anchor */
200
+ .langDetails > summary { list-style: none; } /* ๐Ÿ™ˆ no disclosure triangle */
201
+ .langDetails > summary::-webkit-details-marker { display: none; } /* ๐Ÿ™ˆ Safari */
202
+ .langList { position: absolute; inset-inline-end: 0; inset-block-start: 100%; z-index: 30; margin: 4px 0 0; padding: 6px; min-inline-size: 180px; list-style: none; background: var(--ab-color-card, #fff); border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-radius: 12px; box-shadow: 0 8px 24px rgb(25 18 12 / 0.12); } /* ๐Ÿ“‹ */
203
+ .langList a { display: flex; align-items: center; min-block-size: 44px; padding: 0 12px; border-radius: 8px; color: var(--ab-color-text, #211a16); text-decoration: none; } /* ๐Ÿ‘† 44px targets */
204
+ .langList a[aria-current='true'] { font-weight: 700; color: var(--ab-color-accent, #a67c52); } /* โœ… */
205
+ .langList a:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: -2px; } /* โ™ฟ */
206
+ /* ๐Ÿ“ฑ 0.2.3 barAt (Joseph, Welcome 0.2.21): from 768px up the app header carries logo ยท globe ยท theme, so the bar would
207
+ repeat it. 'mobile' hides the bar there; 'auto' does so only inside core's mainHeaderAt="all" layout (the only
208
+ place the main header shows at that width next to the app header). The row stays. Pure CSS: no-JS + SSR safe. */
209
+ @media (min-width: 768px) {
210
+ .mh[data-ab-bar-at='mobile'] > .mhBar,
211
+ [data-main-header-at='all'] .mh[data-ab-bar-at='auto'] > .mhBar { display: none; } /* ๐Ÿ™ˆ the row stays */
212
+ .mh[data-ab-bar-at='mobile']:not(.mhStack),
213
+ [data-main-header-at='all'] .mh[data-ab-bar-at='auto']:not(.mhStack) { display: none; } /* ๐Ÿ™ˆ no row: nothing left */
214
+ }
215
+ .mhCompact { min-block-size: 48px; padding-inline-start: 18px; } /* ๐Ÿ“ no row */
216
+ .mhCompact.mhStack { padding-inline-start: 0; } /* ๐Ÿงฑ the stack itself has no inset */
217
+ .mhCompact > .mhBar { min-block-size: 48px; padding-inline-start: 18px; } /* ๐Ÿ“ with a row */
191
218
  .ibtn { flex: none; inline-size: 44px; block-size: 44px; display: inline-flex; align-items: center; justify-content: center; border: 0; border-radius: 8px; background: transparent; color: var(--ab-color-text, #211a16); cursor: pointer; padding: 0; }
192
219
  .ibtn > svg { inline-size: 24px; block-size: 24px; }
193
220
  @media (hover: hover) { .ibtn:hover { background: var(--ab-color-hover, rgb(166 124 82 / 0.08)); } } /* ๐Ÿ–ฑ๏ธ 0.2.1 (Joseph): no sticky tap-hover on touch */
@@ -0,0 +1,65 @@
1
+ /*
2
+ * @license MIT
3
+ * ~~~~~~~~~~~~
4
+ * ab-nextjs-components
5
+ * ~~~~~~~~~~~~
6
+ * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
7
+ *
8
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ * of this software and associated documentation files (the 'Software'), to deal
10
+ * in the Software without restriction, including without limitation the rights
11
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ * copies of the Software, and to permit persons to whom the Software is
13
+ * furnished to do so, subject to the following conditions:
14
+ *
15
+ * The above copyright notice and this permission notice shall be included in all
16
+ * copies or substantial portions of the Software.
17
+ *
18
+ * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ * SOFTWARE.
25
+ *
26
+ * @project: ab-nextjs-components
27
+ * @name: AbFlowFrameScale
28
+ * @file: ab-flow-diagram/frame-scale.tsx
29
+ * @type: Client Component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+ 'use client';
40
+
41
+ // โš›๏ธ react
42
+ import { useEffect, useRef, type ReactElement } from 'react';
43
+
44
+ /**
45
+ * ๐Ÿ“ AbFlowFrameScale โ€” the tiny client island behind `frame`: watches the card width and sets
46
+ * `--ab-flow-scale` (card width / frame width) on it, so the fixed v6 pixel stage scales 1:1.
47
+ * Browsers with CSS typed arithmetic already get the same value from `100cqw / frame px` before hydration;
48
+ * this covers everyone else. Renders one hidden <span>, nothing visible.
49
+ */
50
+ export function AbFlowFrameScale({ width }: { width: number }): ReactElement {
51
+ const ref = useRef<HTMLSpanElement | null>(null); // ๐Ÿ“ our marker
52
+ useEffect(() => {
53
+ const card = ref.current?.parentElement; // ๐Ÿƒ the figure
54
+ if (!card || !(width > 0)) return; // ๐Ÿงฏ
55
+ const apply = (): void => { card.style.setProperty('--ab-flow-scale', String(card.clientWidth / width)); }; // ๐Ÿ“
56
+ apply(); // โ–ถ๏ธ now
57
+ if (typeof ResizeObserver === 'undefined') return; // ๐Ÿง“ old engines: the first value stays
58
+ const ro = new ResizeObserver(apply); // ๐Ÿ‘€
59
+ ro.observe(card);
60
+ return () => ro.disconnect(); // ๐Ÿงน
61
+ }, [width]);
62
+ return <span ref={ref} hidden data-ab-part="flow-frame-scale" />;
63
+ }
64
+
65
+ export default AbFlowFrameScale;
@@ -42,13 +42,33 @@ import type { ReactNode } from 'react';
42
42
  // ๐Ÿ”ต a node (x/y in 0โ€“100 scene units)
43
43
  export interface AbFlowNode {
44
44
  id: string; // ๐Ÿ†”
45
- label: string; // ๐Ÿท๏ธ visible text (package/component names are not translated)
46
- x: number; // โ†”๏ธ 0โ€“100
47
- y: number; // โ†•๏ธ 0โ€“100
45
+ label?: string; // ๐Ÿท๏ธ visible text (package/component names are not translated); optional when `content` is set
46
+ x: number; // โ†”๏ธ 0โ€“100, or px inside `frame` (left edge)
47
+ y: number; // โ†•๏ธ 0โ€“100, or px inside `frame` (top edge)
48
48
  icon?: ReactNode; // ๐Ÿ–ผ๏ธ e.g. <AbIcon name="widgets" />
49
49
  tone?: 'hub' | 'node' | 'accent'; // ๐ŸŽจ hub = centre logo
50
+ /** ๐Ÿงฉ 0.2.3 (Welcome v6): rich node body (any markup); replaces icon + label. */
51
+ content?: ReactNode;
52
+ /** ๐Ÿ“ 0.2.3: node width / height in frame px (v6 rects map 1:1). */
53
+ w?: number;
54
+ h?: number;
55
+ /** ๐Ÿท๏ธ 0.2.3: the small mono label ABOVE the node (v6 `.lb`, e.g. "ab.config.ts"). */
56
+ caption?: string;
57
+ /** ๐Ÿท๏ธ 0.2.3 (spec rev 2): frame mode caption spot. `'start'` (default) = top-left; `'beside-centre'` = just right of
58
+ * the node's centre, so a wire entering the top centre never crosses it (the mobile bottom node). */
59
+ captionAt?: 'start' | 'beside-centre';
50
60
  }
51
61
 
62
+ // ๐Ÿ–ผ๏ธ 0.2.3: a fixed design frame (John's v6 scene = 760ร—600 with a 56px header); scales to the card width
63
+ export interface AbFlowFrame {
64
+ w: number; // โ†”๏ธ px
65
+ h: number; // โ†•๏ธ px
66
+ header?: number; // ๐Ÿท๏ธ header band px (dots start below it)
67
+ }
68
+
69
+ // ๐Ÿ“ a point in frame px
70
+ export type AbFlowPoint = readonly [number, number];
71
+
52
72
  // ใ€ฐ๏ธ a wire
53
73
  export interface AbFlowEdge {
54
74
  from: string; // ๐Ÿ”ต node id
@@ -75,3 +95,69 @@ export function getAbFlowEdgePath(a: Pick<AbFlowNode, 'x' | 'y'>, b: Pick<AbFlow
75
95
  const cy = my + dx * k; // โคต๏ธ
76
96
  return `M ${x1} ${y1} Q ${+cx.toFixed(2)} ${+cy.toFixed(2)} ${x2} ${y2}`; // ใ€ฐ๏ธ
77
97
  }
98
+
99
+ // ๐Ÿ“ฆ a node rect in frame px (w/h default to 0 = a point)
100
+ type Rect = Pick<AbFlowNode, 'x' | 'y' | 'w' | 'h'>;
101
+ const W = (n: Rect): number => n.w ?? 0; // โ†”๏ธ
102
+ const H = (n: Rect): number => n.h ?? 0; // โ†•๏ธ
103
+
104
+ /**
105
+ * @name routeAbFlowWires
106
+ * @description ใ€ฐ๏ธ 0.2.3: John's v6 `route(nodes, hub)` (scenes.py), ported 1:1. Nodes above the hub wire down into
107
+ * its top edge, nodes below wire up into its bottom edge (anchors spread evenly along the edge, sorted by x), side
108
+ * nodes wire into the left / right edge. Orthogonal elbows (one horizontal run at mid-height / mid-width).
109
+ * Every wire starts at the node and ends at the hub, so pulses travel node โ†’ hub.
110
+ */
111
+ export function routeAbFlowWires(nodes: readonly Rect[], hub: Rect): AbFlowPoint[][] {
112
+ const [hx, hy, hw, hh] = [hub.x, hub.y, W(hub), H(hub)]; // ๐ŸŽฏ hub rect
113
+ const top: Rect[] = []; const bot: Rect[] = []; const side: Rect[] = []; // ๐Ÿ—‚๏ธ groups
114
+ for (const n of nodes) {
115
+ if (n.y + H(n) <= hy - 8) top.push(n); // โฌ†๏ธ
116
+ else if (n.y >= hy + hh + 8) bot.push(n); // โฌ‡๏ธ
117
+ else side.push(n); // โ†”๏ธ
118
+ }
119
+ const wires: AbFlowPoint[][] = []; // ใ€ฐ๏ธ
120
+ for (const [grp, isTop] of [[top, true], [bot, false]] as const) {
121
+ const sorted = [...grp].sort((a, b) => a.x + W(a) / 2 - (b.x + W(b) / 2)); // โ†”๏ธ left โ†’ right
122
+ sorted.forEach((n, j) => {
123
+ const ax = hx + (hw * (j + 1)) / (sorted.length + 1); // ๐Ÿ“ spread along the hub edge
124
+ const cx = n.x + W(n) / 2; // ๐ŸŽฏ node centre
125
+ const s: AbFlowPoint = isTop ? [cx, n.y + H(n)] : [cx, n.y]; // ๐Ÿ”ต node edge
126
+ const e: AbFlowPoint = isTop ? [ax, hy] : [ax, hy + hh]; // ๐ŸŽฏ hub edge
127
+ const ym = (s[1] + e[1]) / 2; // โ†•๏ธ elbow height
128
+ wires.push(Math.abs(s[0] - e[0]) < 2 ? [s, e] : [s, [s[0], ym], [e[0], ym], e]); // โž– or โคต๏ธ
129
+ });
130
+ }
131
+ for (const n of side) {
132
+ const cy = hy + hh / 2; const ny = n.y + H(n) / 2; // โ†•๏ธ centres
133
+ const right = n.x > hx + hw; // โžก๏ธ right of the hub?
134
+ const s: AbFlowPoint = right ? [n.x, ny] : [n.x + W(n), ny]; // ๐Ÿ”ต
135
+ const e: AbFlowPoint = right ? [hx + hw, cy] : [hx, cy]; // ๐ŸŽฏ
136
+ const xm = (s[0] + e[0]) / 2; // โ†”๏ธ elbow
137
+ wires.push(Math.abs(ny - cy) < 2 ? [s, e] : [s, [xm, s[1]], [xm, e[1]], e]); // โž– or โคต๏ธ
138
+ }
139
+ return wires;
140
+ }
141
+
142
+ // ๐Ÿ”ข one decimal, like the mock
143
+ const f1 = (v: number): string => (Math.round(v * 10) / 10).toFixed(1);
144
+
145
+ /**
146
+ * @name getAbFlowRoundedPath
147
+ * @description ใ€ฐ๏ธ 0.2.3: v6 `rounded(pts, r=12)`: a polyline with each corner rounded by a quadratic (radius capped
148
+ * at half the shorter segment).
149
+ */
150
+ export function getAbFlowRoundedPath(pts: readonly AbFlowPoint[], r = 12): string {
151
+ if (pts.length === 0) return ''; // ๐Ÿซฅ
152
+ const toward = (a: AbFlowPoint, b: AbFlowPoint, rr: number): AbFlowPoint => {
153
+ const L = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1; const k = Math.min(rr, L / 2) / L; // ๐Ÿ“
154
+ return [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k]; // ๐Ÿ“
155
+ };
156
+ let d = `M${f1(pts[0][0])} ${f1(pts[0][1])}`; // ๐Ÿ–Š๏ธ start
157
+ for (let i = 1; i < pts.length - 1; i++) {
158
+ const p1 = toward(pts[i], pts[i - 1], r); const p2 = toward(pts[i], pts[i + 1], r); // โ†ฉ๏ธ corner ends
159
+ d += ` L${f1(p1[0])} ${f1(p1[1])} Q${f1(pts[i][0])} ${f1(pts[i][1])} ${f1(p2[0])} ${f1(p2[1])}`; // ใ€ฐ๏ธ
160
+ }
161
+ const last = pts[pts.length - 1]; // ๐Ÿ
162
+ return `${d} L${f1(last[0])} ${f1(last[1])}`;
163
+ }