jfs-components 0.1.25 → 0.1.30

package/src/components/Carousel/Carousel.tsx

@@ -21,6 +21,8 @@ import {
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import type { Modes } from '../../design-tokens'
+import AutoplayControl from '../AutoplayControl/AutoplayControl'
+import NumberPagination from '../NumberPagination/NumberPagination'
 
 // ---------------------------------------------------------------------------
 // Context
@@ -75,6 +77,13 @@ export interface CarouselProps {
   paddingHorizontal?: number
   /** Explicit vertical padding (px) for the outer container. Overrides `carousel/padding/vertical`. */
   paddingVertical?: number
+  /**
+   * Carousel visual type.
+   * - `'Default'` — standard carousel with dot pagination below.
+   * - `'Numbered'` — full-bleed carousel with floating AutoplayControl and
+   *   NumberPagination overlaid at the bottom center.
+   */
+  type?: 'Default' | 'Numbered'
 
   /** Called when the active index changes. */
   onIndexChange?: (index: number) => void
@@ -97,10 +106,12 @@ export function Carousel({
   itemWidth: itemWidthProp,
   paddingHorizontal: paddingHorizontalProp,
   paddingVertical: paddingVerticalProp,
+  type = 'Default',
 
   onIndexChange,
   style,
 }: CarouselProps) {
+  const isNumbered = type === 'Numbered'
   // ---- Token resolution ----
   const tokenGap = parseFloat(
     getVariableByName('carousel/gap', modes),
@@ -119,15 +130,32 @@ export function Carousel({
   const maxHeight = parseFloat(
     getVariableByName('carousel/maxHeight', modes),
   )
+  // Gap between AutoplayControl and NumberPagination in the Numbered overlay.
+  const controlGap = parseFloat(
+    getVariableByName('carouselControl/gap', modes),
+  )
+
   // Spacing between the cards row and the pagination dots uses `carousel/gap`.
   const paginationOffset = gap
 
   // ---- Refs & state ----
   const scrollRef = useRef<ScrollView>(null)
   const [activeIndex, setActiveIndex] = useState(0)
+  const activeIndexRef = useRef(0)
   const [containerWidth, setContainerWidth] = useState(0)
   const autoPlayTimer = useRef<ReturnType<typeof setInterval> | null>(null)
   const userInteracting = useRef(false)
+  // Guard: suppress handleScroll index updates during programmatic scrollTo
+  // animations so intermediate offsets don't flicker activeIndex back.
+  const programmaticScroll = useRef(false)
+  const programmaticTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    activeIndexRef.current = activeIndex
+  }, [activeIndex])
+
+  // Interactive play/pause state for the Numbered variant.
+  const [isPlaying, setIsPlaying] = useState(autoPlay)
 
   // Flatten children so we can count items
   const items = useMemo(
@@ -137,13 +165,15 @@ export function Carousel({
 
   const totalItems = items.length
 
-  // Effective item width: provided prop, or full container width minus peek offsets
+  // Effective item width: provided prop, or full container width minus peek offsets.
+  // For the Numbered variant the items are full-bleed (no peek padding).
   const effectiveItemWidth = useMemo(() => {
     if (itemWidthProp != null) return itemWidthProp
     if (containerWidth === 0) return 0
+    if (isNumbered) return containerWidth
     // Full-width minus peekOffset on each side
     return containerWidth - containerPaddingH * 4
-  }, [itemWidthProp, containerWidth, containerPaddingH])
+  }, [itemWidthProp, containerWidth, containerPaddingH, isNumbered])
 
   // Snap interval = item width + gap
   const snapInterval = effectiveItemWidth + gap
@@ -158,6 +188,17 @@ export function Carousel({
       } else {
         targetIndex = Math.max(0, Math.min(index, totalItems - 1))
       }
+      // Lock out handleScroll during the animated scroll so intermediate
+      // offsets don't flicker activeIndex back to the old value.
+      if (animated) {
+        programmaticScroll.current = true
+        if (programmaticTimer.current != null) {
+          clearTimeout(programmaticTimer.current)
+        }
+        programmaticTimer.current = setTimeout(() => {
+          programmaticScroll.current = false
+        }, 500)
+      }
       scrollRef.current?.scrollTo({
         x: targetIndex * snapInterval,
         animated,
@@ -185,6 +226,9 @@ export function Carousel({
   const handleScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
       if (snapInterval === 0) return
+      // Skip index recalculation during programmatic scrollTo animations
+      // to prevent the active indicator from flickering back to the old page.
+      if (programmaticScroll.current) return
       const offsetX = event.nativeEvent.contentOffset.x
       const newIndex = Math.round(offsetX / snapInterval)
       const clampedIndex = Math.max(0, Math.min(newIndex, totalItems - 1))
@@ -205,31 +249,28 @@ export function Carousel({
   }, [])
 
   const startAutoPlay = useCallback(() => {
-    if (!autoPlay || totalItems <= 1) return
+    if ((!autoPlay && !isPlaying) || totalItems <= 1) return
+    if (!isPlaying) return
     clearAutoPlay()
     autoPlayTimer.current = setInterval(() => {
       if (!userInteracting.current) {
-        setActiveIndex((prev) => {
-          const next = loop
-            ? (prev + 1) % totalItems
-            : Math.min(prev + 1, totalItems - 1)
-          scrollRef.current?.scrollTo({
-            x: next * snapInterval,
-            animated: true,
-          })
-          onIndexChange?.(next)
-          return next
-        })
+        const prev = activeIndexRef.current
+        const next = loop
+          ? (prev + 1) % totalItems
+          : Math.min(prev + 1, totalItems - 1)
+        // Route through scrollToIndex so the programmaticScroll guard
+        // suppresses intermediate handleScroll offsets during the animation.
+        scrollToIndex(next, true)
       }
     }, autoPlayInterval)
   }, [
     autoPlay,
+    isPlaying,
     totalItems,
     loop,
-    snapInterval,
     autoPlayInterval,
     clearAutoPlay,
-    onIndexChange,
+    scrollToIndex,
   ])
 
   useEffect(() => {
@@ -244,8 +285,27 @@ export function Carousel({
   const handleScrollEndDrag = useCallback(() => {
     userInteracting.current = false
     // Reset autoplay timer after interaction
-    if (autoPlay) startAutoPlay()
-  }, [autoPlay, startAutoPlay])
+    if (autoPlay || isPlaying) startAutoPlay()
+  }, [autoPlay, isPlaying, startAutoPlay])
+
+  const finishProgrammaticScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      programmaticScroll.current = false
+      if (programmaticTimer.current != null) {
+        clearTimeout(programmaticTimer.current)
+        programmaticTimer.current = null
+      }
+      if (snapInterval === 0) return
+      const offsetX = event.nativeEvent.contentOffset.x
+      const newIndex = Math.round(offsetX / snapInterval)
+      const clampedIndex = Math.max(0, Math.min(newIndex, totalItems - 1))
+      if (clampedIndex !== activeIndexRef.current) {
+        setActiveIndex(clampedIndex)
+        onIndexChange?.(clampedIndex)
+      }
+    },
+    [snapInterval, totalItems, onIndexChange],
+  )
 
   // ---- Layout ----
   const handleLayout = useCallback((e: LayoutChangeEvent) => {
@@ -265,15 +325,37 @@ export function Carousel({
     [modes, activeIndex, totalItems, goTo, goNext, goPrev],
   )
 
+  // ---- Toggle handler for Numbered variant ----
+  const handleToggleAutoplay = useCallback(() => {
+    setIsPlaying((prev) => {
+      if (prev) {
+        // Pausing
+        clearAutoPlay()
+        return false
+      }
+      // Resuming — autoplay will restart via the effect
+      return true
+    })
+  }, [clearAutoPlay])
+
+  // Restart autoplay whenever isPlaying flips to true
+  useEffect(() => {
+    if (isPlaying) startAutoPlay()
+    else clearAutoPlay()
+  }, [isPlaying, startAutoPlay, clearAutoPlay])
+
   // ---- Render ----
   // Explicit padding props win verbatim; otherwise fall back to the
   // token-derived values (horizontal keeps its legacy ×2 "peek" multiplier).
-  const effectivePaddingH = paddingHorizontalProp ?? containerPaddingH 
-  const effectivePaddingV = paddingVerticalProp ?? containerPaddingV
+  // Numbered variant is full-bleed: zero padding.
+  const effectivePaddingH = isNumbered ? 0 : (paddingHorizontalProp ?? containerPaddingH)
+  const effectivePaddingV = isNumbered ? 0 : (paddingVerticalProp ?? containerPaddingV)
 
   const outerStyle: ViewStyle = {
     paddingVertical: effectivePaddingV,
-    maxHeight,
+    maxHeight: isNumbered ? undefined : maxHeight,
+    // Numbered needs relative positioning for the floating controls overlay.
+    ...(isNumbered ? { overflow: 'hidden' as const } : {}),
   }
 
   const contentContainerStyle: ViewStyle = {
@@ -299,7 +381,7 @@ export function Carousel({
           scrollEventThrottle={16}
           onScrollBeginDrag={handleScrollBeginDrag}
           onScrollEndDrag={handleScrollEndDrag}
-
+          onMomentumScrollEnd={finishProgrammaticScroll}
         >
           {items.map((child, index) => {
             // Strict slot box: width must be honored; never grow or shrink with
@@ -343,12 +425,40 @@ export function Carousel({
           })}
         </ScrollView>
 
-        {showPagination && totalItems > 1 && (
+        {!isNumbered && showPagination && totalItems > 1 && (
           <Pagination
             modes={modes}
             style={{ marginTop: paginationOffset }}
           />
         )}
+
+        {isNumbered && showPagination && totalItems > 1 && (
+          <View
+            style={{
+              position: 'absolute',
+              bottom: 12,
+              left: 0,
+              right: 0,
+              flexDirection: 'row',
+              justifyContent: 'center',
+              alignItems: 'center',
+              gap: controlGap,
+            }}
+            pointerEvents="box-none"
+          >
+            <AutoplayControl
+              state={isPlaying ? 'pause' : 'play'}
+              onPress={handleToggleAutoplay}
+              modes={modes}
+            />
+            <NumberPagination
+              activePage={activeIndex + 1}
+              totalPages={totalItems}
+              onPageChange={(page) => goTo(page - 1)}
+              modes={modes}
+            />
+          </View>
+        )}
       </View>
     </CarouselContext.Provider>
   )

package/src/components/CompareTable/CompareTable.tsx

@@ -1,10 +1,13 @@
-import React from 'react'
+import React, { useCallback, useRef } from 'react'
 import {
     View,
     Text,
     Pressable,
     Platform,
+    ScrollView,
     type ImageSourcePropType,
+    type NativeScrollEvent,
+    type NativeSyntheticEvent,
     type StyleProp,
     type ViewStyle,
     type TextStyle,
@@ -140,6 +143,26 @@ export type CompareTableProps = {
      * lines as it needs even when horizontal space is tight.
      */
     disableTruncation?: boolean;
+    /**
+     * Fixed width (px) for every selection card and every table cell — all
+     * columns share this width. When set, the component enters **scroll mode**:
+     *
+     *  - The cards row and each section's table body become independent
+     *    horizontal `ScrollView`s whose scroll events are **chained** — moving
+     *    one moves every other in lockstep (the cards always stay aligned with
+     *    the cells beneath them).
+     *  - The cards row becomes a **sticky header** at the top: it pins in place
+     *    on the vertical axis (does not scroll away) while the sections scroll
+     *    beneath it. Requires the host to give `CompareTable` a bounded height.
+     *  - The gray table-header rows (each section's `header`) are rendered
+     *    full-width **outside** the horizontal scroll, so they stay put
+     *    horizontally (they don't slide with the cells) while still scrolling
+     *    vertically with the table.
+     *
+     * Omit to keep the original flex layout (columns share the available width,
+     * no scrolling). @default undefined
+     */
+    columnWidth?: number;
 };
 
 const DEFAULT_COLUMNS: CompareTableColumn[] = [
@@ -181,6 +204,7 @@ function CompareTable({
     modes = EMPTY_MODES,
     style,
     disableTruncation,
+    columnWidth,
 }: CompareTableProps) {
     // --- selection card tokens ------------------------------------------------
     const cardBg = (getVariableByName('selectionCard/background/color', modes) as string) ?? '#ffffff'
@@ -238,6 +262,72 @@ function CompareTable({
     const showAddCard = onAddColumn != null && columnCount < maxColumns
     /** Grid columns shared by the selection-card row and every table row. */
     const gridColumnCount = columnCount + (showAddCard ? 1 : 0)
+    const showCardsRow = columnCount > 0 || showAddCard
+
+    // --- fixed-width scroll mode -------------------------------------------
+    // `columnWidth` opts the component into scroll mode (see prop doc). In that
+    // mode the cards row and each section's table body are independent
+    // horizontal ScrollViews; their scroll events are chained so they move in
+    // lockstep, and the cards row pins to the top on the vertical axis.
+    const useFixedWidth = columnWidth != null
+    /** Total scrollable content width shared by every horizontal surface. */
+    const contentWidth = useFixedWidth ? gridColumnCount * (columnWidth as number) : 0
+
+    const cardsScrollRef = useRef<ScrollView>(null)
+    const bodyScrollRefs = useRef<Map<number, ScrollView>>(new Map())
+    // Stable per-section ref-callback instances so React doesn't detach/reattach
+    // on every render (which would churn the map and re-fire scrollTo).
+    const bodyRefCallbacks = useRef<Map<number, (r: ScrollView | null) => void>>(new Map())
+    /** Last offset we synced everyone to. Echoed onScroll events reporting this
+     *  same value are ignored — this is what prevents feedback loops. */
+    const lastSyncX = useRef(0)
+
+    const applySync = useCallback((x: number, source: 'cards' | number) => {
+        if (Math.abs(x - lastSyncX.current) < 0.5) return
+        lastSyncX.current = x
+        if (source !== 'cards' && cardsScrollRef.current) {
+            cardsScrollRef.current.scrollTo({ x, animated: false })
+        }
+        bodyScrollRefs.current.forEach((ref, idx) => {
+            if (source === 'cards' || idx !== source) {
+                ref.scrollTo({ x, animated: false })
+            }
+        })
+    }, [])
+
+    const onCardsScroll = useCallback(
+        (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+            applySync(e.nativeEvent.contentOffset.x, 'cards')
+        },
+        [applySync],
+    )
+
+    const onBodyScroll = useCallback(
+        (idx: number) => (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+            applySync(e.nativeEvent.contentOffset.x, idx)
+        },
+        [applySync],
+    )
+
+    const getBodyRefCallback = useCallback((idx: number) => {
+        let cb = bodyRefCallbacks.current.get(idx)
+        if (!cb) {
+            cb = (ref: ScrollView | null) => {
+                if (ref) {
+                    bodyScrollRefs.current.set(idx, ref)
+                    // Bring a freshly-expanded section's body into sync with
+                    // the rest of the surfaces.
+                    if (lastSyncX.current > 0) {
+                        ref.scrollTo({ x: lastSyncX.current, animated: false })
+                    }
+                } else {
+                    bodyScrollRefs.current.delete(idx)
+                }
+            }
+            bodyRefCallbacks.current.set(idx, cb)
+        }
+        return cb
+    }, [])
 
     const cardLabelStyle: TextStyle = {
         ...NO_WRAP_TEXT,
@@ -273,8 +363,7 @@ function CompareTable({
     }
 
     const cardStyle: ViewStyle = {
-        flex: 1,
-        minWidth: 0,
+        ...(useFixedWidth ? { width: columnWidth as number } : { flex: 1, minWidth: 0 }),
         minHeight: 147,
         backgroundColor: cardBg,
         borderRadius: cardRadius,
@@ -420,6 +509,7 @@ function CompareTable({
                 key={key}
                 modes={modes}
                 flex={1}
+                width={useFixedWidth ? columnWidth : undefined}
                 align="left"
                 isLastColumn={isLastCol}
                 isLastRow={isLastRow}
@@ -486,38 +576,142 @@ function CompareTable({
         </Table>
     )
 
-    return (
-        <View
-            style={[
-                {
-                    width: '100%',
-                    backgroundColor: cardBg,
-                    borderWidth: 1,
-                    borderColor: '#e8e8e8',
-                    overflow: 'hidden',
-                },
-                style,
-            ]}
+    // Render a single section in fixed-width scroll mode. Unlike `renderTable`
+    // (used in flex mode), the gray header row is rendered full-width OUTSIDE
+    // the body's horizontal ScrollView so it stays put horizontally (it does
+    // not slide with the cells) while still scrolling vertically with the table.
+    // The body rows live inside a horizontal ScrollView that is scroll-synced
+    // with the cards row and every other section's body.
+    const renderSection = (section: CompareTableSection, index: number) => (
+        <Accordion
+            key={section.key ?? section.title ?? index}
+            title={section.title}
+            defaultExpanded={section.defaultExpanded ?? index === 0}
+            modes={modes}
         >
-            {(columnCount > 0 || showAddCard) && (
-                <View style={{ flexDirection: 'row', width: '100%' }}>
-                    {columns.map(renderCard)}
-                    {showAddCard && renderAddCard()}
+            {section.header != null && (
+                <View
+                    style={{
+                        width: '100%',
+                        backgroundColor: headerBg,
+                        paddingHorizontal: headerPaddingH,
+                        paddingVertical: headerPaddingV,
+                        borderBottomWidth: cellBorderSize,
+                        borderBottomColor: cellBorderColor,
+                    }}
+                >
+                    <Text style={headerTextStyle}>{section.header}</Text>
                 </View>
             )}
+            <ScrollView
+                ref={getBodyRefCallback(index)}
+                horizontal
+                showsHorizontalScrollIndicator={false}
+                scrollEventThrottle={16}
+                onScroll={onBodyScroll(index)}
+            >
+                <View style={{ width: contentWidth }}>
+                    {section.rows.map((row, rowIndex) => {
+                        const isLastRow = rowIndex === section.rows.length - 1
+                        return (
+                            <View
+                                key={row.key ?? rowIndex}
+                                style={{ flexDirection: 'row', width: '100%' }}
+                            >
+                                {Array.from({ length: columnCount }).map((_, colIndex) =>
+                                    renderTableCell(
+                                        renderCellContent(
+                                            row.values?.[colIndex],
+                                            `${rowIndex}-${colIndex}`,
+                                        ),
+                                        colIndex,
+                                        isLastRow,
+                                        colIndex,
+                                    ),
+                                )}
+                                {showAddCard &&
+                                    renderTableCell(
+                                        null,
+                                        gridColumnCount - 1,
+                                        isLastRow,
+                                        '__add_spacer__',
+                                    )}
+                            </View>
+                        )
+                    })}
+                </View>
+            </ScrollView>
+        </Accordion>
+    )
 
-            <View style={{ width: '100%' }}>
-                {sections.map((section, index) => (
-                    <Accordion
-                        key={section.key ?? section.title ?? index}
-                        title={section.title}
-                        defaultExpanded={section.defaultExpanded ?? index === 0}
-                        modes={modes}
-                    >
-                        {renderTable(section)}
-                    </Accordion>
-                ))}
+    const outerStyle: ViewStyle = {
+        width: '100%',
+        backgroundColor: cardBg,
+        borderWidth: 1,
+        borderColor: '#e8e8e8',
+        overflow: 'hidden',
+    }
+
+    // --- flex mode (columnWidth omitted): original behaviour, unchanged -------
+    if (!useFixedWidth) {
+        return (
+            <View style={[outerStyle, style]}>
+                {showCardsRow && (
+                    <View style={{ flexDirection: 'row', width: '100%' }}>
+                        {columns.map(renderCard)}
+                        {showAddCard && renderAddCard()}
+                    </View>
+                )}
+
+                <View style={{ width: '100%' }}>
+                    {sections.map((section, index) => (
+                        <Accordion
+                            key={section.key ?? section.title ?? index}
+                            title={section.title}
+                            defaultExpanded={section.defaultExpanded ?? index === 0}
+                            modes={modes}
+                        >
+                            {renderTable(section)}
+                        </Accordion>
+                    ))}
+                </View>
             </View>
+        )
+    }
+
+    // --- fixed-width scroll mode: chained horizontal sync + sticky cards -----
+    // The cards row (index 0) is a sticky header of the vertical ScrollView so
+    // it pins to the top while the sections scroll beneath. The cards row is
+    // itself a horizontal ScrollView, synced with every section body. For the
+    // vertical scroll (and thus the sticky behaviour) to engage, the host must
+    // give CompareTable a bounded height (e.g. a sized container or flex:1).
+    return (
+        <View style={[outerStyle, style, { flexDirection: 'column', flex: 1 }]}>
+            <ScrollView
+                style={{ width: '100%', flex: 1 }}
+                stickyHeaderIndices={showCardsRow ? [0] : []}
+                showsVerticalScrollIndicator={false}
+                directionalLockEnabled
+            >
+                {showCardsRow && (
+                    <ScrollView
+                        ref={cardsScrollRef}
+                        horizontal
+                        showsHorizontalScrollIndicator={false}
+                        scrollEventThrottle={16}
+                        onScroll={onCardsScroll}
+                    >
+                        <View style={{ flexDirection: 'row', width: contentWidth }}>
+                            {columns.map(renderCard)}
+                            {showAddCard && renderAddCard()}
+                        </View>
+                    </ScrollView>
+                )}
+
+                <View style={{ width: '100%' }}>
+                    {sections.map(renderSection)}
+                </View>
+            </ScrollView>
         </View>
     )
 }