jfs-components 0.0.79 → 0.0.85

package/src/components/AreaLineChart/chartMath.ts

@@ -0,0 +1,265 @@
+/**
+ * Pure, framework-agnostic math helpers for `AreaLineChart`.
+ *
+ * Everything here is intentionally dependency-free (no d3, no react-native)
+ * so the chart can stay lightweight and be unit-reasoned in isolation. The
+ * functions cover the four primitives a line/area chart needs:
+ *   1. linear scales (data domain -> pixel range)
+ *   2. "nice" tick generation for the value axis
+ *   3. SVG path generation for lines and filled areas (straight + smooth)
+ *   4. interaction lookup (which data index is nearest a touch x)
+ */
+
+/** A resolved point in data space. `x` is the categorical/linear index. */
+export type ResolvedPoint = {
+    /** Position along the x domain (defaults to the array index). */
+    x: number
+    /** Value along the y domain. */
+    y: number
+    /**
+     * When true, the line segment that *ends* at this point is rendered
+     * dashed (used for projected / low-confidence data).
+     */
+    projected: boolean
+}
+
+/** A point already projected into pixel space. */
+export type PixelPoint = { x: number; y: number; projected: boolean }
+
+/** Linear interpolation scale: maps a value from `domain` into `range`. */
+export type LinearScale = {
+    (value: number): number
+    domain: readonly [number, number]
+    range: readonly [number, number]
+}
+
+/**
+ * Create a linear scale mapping `domain` -> `range`. Mirrors the subset of
+ * `d3-scale.scaleLinear` we rely on, without the dependency. A zero-width
+ * domain collapses to the midpoint of the range so we never divide by zero.
+ */
+export function createLinearScale(
+    domain: readonly [number, number],
+    range: readonly [number, number]
+): LinearScale {
+    const [d0, d1] = domain
+    const [r0, r1] = range
+    const domainSpan = d1 - d0
+
+    const scale = ((value: number): number => {
+        if (domainSpan === 0) {
+            return (r0 + r1) / 2
+        }
+        const t = (value - d0) / domainSpan
+        return r0 + t * (r1 - r0)
+    }) as LinearScale
+
+    scale.domain = domain
+    scale.range = range
+    return scale
+}
+
+/**
+ * Generate up to ~`count` "nice" evenly-spaced tick values spanning
+ * `[min, max]`, snapping the step to a 1/2/5 * 10^n progression so labels
+ * read cleanly (e.g. 0, 30K, 60K, 90K). Returns ascending values that
+ * always include the rounded-down min and rounded-up max bounds.
+ */
+export function niceTicks(min: number, max: number, count = 5): number[] {
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        return []
+    }
+    if (min === max) {
+        return [min]
+    }
+    const safeCount = Math.max(1, Math.floor(count))
+    const span = max - min
+    const rawStep = span / safeCount
+    const magnitude = Math.pow(10, Math.floor(Math.log10(rawStep)))
+    const normalized = rawStep / magnitude
+
+    let niceNormalized: number
+    if (normalized <= 1) niceNormalized = 1
+    else if (normalized <= 2) niceNormalized = 2
+    else if (normalized <= 5) niceNormalized = 5
+    else niceNormalized = 10
+
+    const step = niceNormalized * magnitude
+    const niceMin = Math.floor(min / step) * step
+    const niceMax = Math.ceil(max / step) * step
+
+    const ticks: number[] = []
+    // Guard against floating point drift by rounding to the step's precision.
+    const decimals = Math.max(0, -Math.floor(Math.log10(step)))
+    for (let v = niceMin; v <= niceMax + step / 2; v += step) {
+        ticks.push(Number(v.toFixed(decimals)))
+    }
+    return ticks
+}
+
+/**
+ * Compute the [min, max] extent of an array of resolved points along the
+ * requested axis. Returns `[0, 0]` for an empty list.
+ */
+export function extent(points: ResolvedPoint[], axis: 'x' | 'y'): [number, number] {
+    if (points.length === 0) {
+        return [0, 0]
+    }
+    let min = Infinity
+    let max = -Infinity
+    for (const p of points) {
+        const v = p[axis]
+        if (v < min) min = v
+        if (v > max) max = v
+    }
+    return [min, max]
+}
+
+/**
+ * Normalize the loose `number[] | ChartPoint[]` series data into a uniform
+ * `ResolvedPoint[]`. Bare numbers use their array index as the x value.
+ */
+export function resolvePoints(
+    data: ReadonlyArray<number | { x?: number | string; y: number; projected?: boolean }>
+): ResolvedPoint[] {
+    return data.map((entry, index) => {
+        if (typeof entry === 'number') {
+            return { x: index, y: entry, projected: false }
+        }
+        const x = typeof entry.x === 'number' ? entry.x : index
+        return { x, y: entry.y, projected: entry.projected === true }
+    })
+}
+
+/**
+ * Catmull-Rom -> cubic Bézier control point helper. Produces a smooth,
+ * monotone-ish curve through the points without overshooting wildly. Used
+ * for the `curve="monotone"` mode. `tension` of 0 yields a standard
+ * Catmull-Rom spline.
+ */
+function controlPoints(
+    p0: PixelPoint,
+    p1: PixelPoint,
+    p2: PixelPoint,
+    p3: PixelPoint
+): { cp1x: number; cp1y: number; cp2x: number; cp2y: number } {
+    const t = 1 / 6
+    return {
+        cp1x: p1.x + (p2.x - p0.x) * t,
+        cp1y: p1.y + (p2.y - p0.y) * t,
+        cp2x: p2.x - (p3.x - p1.x) * t,
+        cp2y: p2.y - (p3.y - p1.y) * t,
+    }
+}
+
+export type Curve = 'linear' | 'monotone'
+
+/**
+ * One drawable line segment. `dashed` mirrors the `projected` flag of the
+ * point the segment ends at, letting the renderer split the polyline into
+ * solid and dashed `Path`s.
+ */
+export type LineSegment = { d: string; dashed: boolean }
+
+/**
+ * Build the SVG path(s) for a polyline through `points`, split into runs of
+ * solid vs dashed segments. Each individual segment ("move to A, line/curve
+ * to B") is emitted as its own sub-path so that a single projected point can
+ * dash exactly one segment while leaving its neighbours solid.
+ */
+export function buildLineSegments(points: PixelPoint[], curve: Curve): LineSegment[] {
+    if (points.length < 2) {
+        return []
+    }
+
+    const segments: LineSegment[] = []
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const start = points[i]
+        const end = points[i + 1]
+        const dashed = end.projected
+
+        let d: string
+        if (curve === 'monotone') {
+            const p0 = points[i - 1] ?? start
+            const p3 = points[i + 2] ?? end
+            const { cp1x, cp1y, cp2x, cp2y } = controlPoints(p0, start, end, p3)
+            d = `M ${start.x} ${start.y} C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${end.x} ${end.y}`
+        } else {
+            d = `M ${start.x} ${start.y} L ${end.x} ${end.y}`
+        }
+        segments.push({ d, dashed })
+    }
+
+    // Merge adjacent segments that share the same dashed-ness into one path
+    // string to minimize the number of rendered <Path> nodes.
+    const merged: LineSegment[] = []
+    for (const seg of segments) {
+        const last = merged[merged.length - 1]
+        if (last && last.dashed === seg.dashed) {
+            // Drop the redundant leading "M x y" of the appended segment.
+            const continuation = seg.d.replace(/^M [^A-Za-z]+/, '')
+            last.d += ' ' + continuation
+        } else {
+            merged.push({ ...seg })
+        }
+    }
+    return merged
+}
+
+/**
+ * Build a single closed area path (the line, then down to `baselineY` and
+ * back) for a filled area fill. Curve smoothing matches `buildLineSegments`.
+ */
+export function buildAreaPath(
+    points: PixelPoint[],
+    baselineY: number,
+    curve: Curve
+): string {
+    if (points.length === 0) {
+        return ''
+    }
+    if (points.length === 1) {
+        const p = points[0]
+        return `M ${p.x} ${baselineY} L ${p.x} ${p.y} Z`
+    }
+
+    let d = `M ${points[0].x} ${baselineY} L ${points[0].x} ${points[0].y}`
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const start = points[i]
+        const end = points[i + 1]
+        if (curve === 'monotone') {
+            const p0 = points[i - 1] ?? start
+            const p3 = points[i + 2] ?? end
+            const { cp1x, cp1y, cp2x, cp2y } = controlPoints(p0, start, end, p3)
+            d += ` C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${end.x} ${end.y}`
+        } else {
+            d += ` L ${end.x} ${end.y}`
+        }
+    }
+
+    const lastX = points[points.length - 1].x
+    d += ` L ${lastX} ${baselineY} Z`
+    return d
+}
+
+/**
+ * Find the index of the point whose pixel-x is nearest to `targetX`. Used to
+ * snap the crosshair / tooltip to the closest data point during hover/drag.
+ */
+export function nearestIndex(pixelXs: number[], targetX: number): number {
+    if (pixelXs.length === 0) {
+        return -1
+    }
+    let best = 0
+    let bestDist = Infinity
+    for (let i = 0; i < pixelXs.length; i++) {
+        const dist = Math.abs(pixelXs[i] - targetX)
+        if (dist < bestDist) {
+            bestDist = dist
+            best = i
+        }
+    }
+    return best
+}

package/src/components/Attached/Attached.tsx

@@ -7,6 +7,7 @@ import {
   type ViewStyle,
 } from 'react-native'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { cloneChildrenWithModes, EMPTY_MODES } from '../../utils/react-utils'
 
 /**
@@ -37,6 +38,24 @@ export type AttachedProps = Omit<ViewProps, 'children'> & {
    * `modes` are cascaded into it as well.
    */
   badge?: React.ReactNode
+  /**
+   * Enforces a fixed square size (in px) on the `badge` slot, regardless of
+   * what node is passed. The badge is wrapped in a box of
+   * `badgeSize × badgeSize` with `overflow: 'hidden'`, and the badge content is
+   * stretched to fill it. Use this to guarantee the design-token size even when
+   * a consumer drops in an arbitrary node (e.g. an `Image`) whose intrinsic
+   * size/aspect-ratio would otherwise win.
+   *
+   * When omitted, the badge keeps its own intrinsic size (legacy behavior).
+   */
+  badgeSize?: number
+  /**
+   * Corner radius used to clip the `badge` box. Only applies when `badgeSize`
+   * is set. Anything that overflows the rounded box (e.g. a non-square image)
+   * is clipped.
+   * @default badgeSize / 2 (a full circle)
+   */
+  badgeRadius?: number
   /**
    * Anchor point for the `badge` relative to the main content.
    * @default 'bottom-right'
@@ -89,9 +108,28 @@ function resolveAnchorFractions(position: AttachedPosition): { fx: number; fy: n
  * </Attached>
  * ```
  */
+/**
+ * Stretches the immediate badge child/children to fill the enforced badge box.
+ * Merges `{ width: '100%', height: '100%' }` into each top-level element's
+ * `style` so an arbitrary node (e.g. an `Image` with its own width/aspectRatio)
+ * fills the fixed `badgeSize` box instead of laying out at its intrinsic size.
+ * The wrapping box's `overflow: 'hidden'` clips anything that still overflows.
+ */
+function forceBadgeFill(children: React.ReactNode): React.ReactNode {
+  return React.Children.map(children, (child) => {
+    if (!React.isValidElement(child)) return child
+    const childStyle = (child.props as any)?.style
+    return React.cloneElement(child as React.ReactElement<any>, {
+      style: [FILL_STYLE, childStyle],
+    })
+  })
+}
+
 function Attached({
   children,
   badge,
+  badgeSize,
+  badgeRadius,
   position = 'bottom-right',
   circular = true,
   modes: propModes = EMPTY_MODES,
@@ -108,7 +146,7 @@ function Attached({
   )
 
   const [mainSize, setMainSize] = useState<Size>(ZERO_SIZE)
-  const [badgeSize, setBadgeSize] = useState<Size>(ZERO_SIZE)
+  const [measuredBadgeSize, setMeasuredBadgeSize] = useState<Size>(ZERO_SIZE)
 
   const onMainLayout = useCallback((e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout
@@ -117,7 +155,7 @@ function Attached({
 
   const onBadgeLayout = useCallback((e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout
-    setBadgeSize((prev) => (prev.width === width && prev.height === height ? prev : { width, height }))
+    setMeasuredBadgeSize((prev) => (prev.width === width && prev.height === height ? prev : { width, height }))
   }, [])
 
   const mainChildren = useMemo(
@@ -129,9 +167,47 @@ function Attached({
     [badge, modes]
   )
 
+  // When a fixed size is requested, the badge is wrapped in a clipped box and
+  // its content is force-stretched to fill it (see `forceBadgeFill`).
+  const badgeBoxStyle = useMemo<ViewStyle | null>(() => {
+    if (badgeSize == null) return null
+    return {
+      width: badgeSize,
+      height: badgeSize,
+      borderRadius: badgeRadius ?? badgeSize / 2,
+      overflow: 'hidden',
+    }
+  }, [badgeSize, badgeRadius])
+
+  // Forced slot ring. Like the corner radius, the border color/width are driven
+  // by design tokens (`attached/slot/border`, `attached/slot/borderWidth`) and
+  // applied to the slot regardless of the node passed. Rendered as an *outside*
+  // border: the ring lives on a wrapper that is pulled out by `-borderWidth` on
+  // every side (negative margin) so it grows outward instead of eating into the
+  // content, and its layout footprint stays equal to the slot box (keeping the
+  // anchor centering intact).
+  const slotBorderStyle = useMemo<ViewStyle | null>(() => {
+    const borderColor = getVariableByName('attached/slot/border', modes)
+    const borderWidth = parseFloat(getVariableByName('attached/slot/borderWidth', modes) || '0')
+    if (!borderColor || !(borderWidth > 0)) return null
+
+    // Match the inner clip radius so the ring stays concentric. The outer edge
+    // sits `borderWidth` further out, hence `innerRadius + borderWidth`.
+    const innerRadius =
+      badgeBoxStyle != null
+        ? (badgeBoxStyle.borderRadius as number)
+        : badgeRadius ?? 9999
+    return {
+      borderWidth,
+      borderColor,
+      borderRadius: (typeof innerRadius === 'number' ? innerRadius : 9999) + borderWidth,
+      margin: -borderWidth,
+    }
+  }, [modes, badgeBoxStyle, badgeRadius])
+
   const badgePlacement = useMemo<ViewStyle>(() => {
     const { fx, fy } = resolveAnchorFractions(position)
-    const measured = mainSize.width > 0 && badgeSize.width > 0
+    const measured = mainSize.width > 0 && measuredBadgeSize.width > 0
 
     let anchorX: number
     let anchorY: number
@@ -153,19 +229,27 @@ function Attached({
 
     return {
       position: 'absolute',
-      left: anchorX - badgeSize.width / 2,
-      top: anchorY - badgeSize.height / 2,
+      left: anchorX - measuredBadgeSize.width / 2,
+      top: anchorY - measuredBadgeSize.height / 2,
       // Hide until both elements are measured to avoid a one-frame flash at (0,0).
       opacity: measured ? 1 : 0,
     }
-  }, [position, circular, mainSize, badgeSize])
+  }, [position, circular, mainSize, measuredBadgeSize])
 
   return (
     <View style={[styles.container, style]} {...rest}>
       <View onLayout={onMainLayout}>{mainChildren}</View>
       {badgeChildren != null && (
         <View style={badgePlacement} onLayout={onBadgeLayout} pointerEvents="box-none">
-          {badgeChildren}
+          {(() => {
+            const slot =
+              badgeBoxStyle != null ? (
+                <View style={badgeBoxStyle}>{forceBadgeFill(badgeChildren)}</View>
+              ) : (
+                badgeChildren
+              )
+            return slotBorderStyle != null ? <View style={slotBorderStyle}>{slot}</View> : slot
+          })()}
         </View>
       )}
     </View>
@@ -178,4 +262,7 @@ const styles = {
   container: { position: 'relative', alignSelf: 'flex-start' } as ViewStyle,
 }
 
+/** Fill style merged into badge content when `badgeSize` enforces a fixed box. */
+const FILL_STYLE = { width: '100%', height: '100%' } as ViewStyle
+
 export default React.memo(Attached)