jfs-components 0.1.12 → 0.1.17

package/src/utils/index.ts

@@ -2,3 +2,5 @@ export { cloneChildrenWithModes, flattenChildren } from './react-utils'
 export { default as MediaSource } from './MediaSource'
 export type { UnifiedSource, MediaSourceProps } from './MediaSource'
 export { formatIndianNumber } from './number-utils'
+export { boxShadow, supportsNativeBoxShadow, parseBoxShadow, parseSingleShadow } from './shadow'
+export type { BoxShadowOptions, ParsedShadow } from './shadow'

package/src/utils/react-utils.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { StyleProp, ViewStyle } from 'react-native';
+import { Platform, type StyleProp, type ViewStyle, type TextStyle } from 'react-native';
 import type { Modes } from '../design-tokens'
 
 /**
@@ -172,6 +172,77 @@ export function resolveTruncation(
     return { numberOfLines, ellipsizeMode };
 }
 
+export type TextLayoutResult = {
+    numberOfLines?: number | undefined;
+    ellipsizeMode?: EllipsizeMode | undefined;
+    /**
+     * Style fragment that MUST be merged onto the target `<Text>` (after the
+     * component's own style and any consumer `style` override) so the escape
+     * hatches can win. `undefined` when neither flag is set.
+     */
+    style?: TextStyle | undefined;
+};
+
+/**
+ * Resolves the `<Text>` props + style for the two truncation escape hatches.
+ * This supersedes {@link resolveTruncation} for components that want the
+ * "brutal" overflow behaviour rather than just dropping the line clamp.
+ *
+ * - `disableTruncation`: never truncate. Drops `numberOfLines`/`ellipsizeMode`
+ *   AND sets `flexShrink: 0`, so a tight flex parent can no longer squeeze the
+ *   text into an ellipsis — instead the text keeps its intrinsic size and
+ *   overflows, even if that means blowing past (and visually breaking) the
+ *   parent layout. The text still wraps onto multiple lines.
+ * - `singleLine`: force everything onto one line with no wrapping. Implies
+ *   `disableTruncation` (the ellipsis is never shown). On web this adds
+ *   `whiteSpace: 'nowrap'` so the single line overflows horizontally instead of
+ *   wrapping. The text is never shrunk.
+ *
+ * Note (native): React Native's `<Text>` has no `white-space: nowrap`
+ * equivalent, so on iOS/Android `singleLine` cannot force a hard non-wrapping
+ * overflow — it behaves like `disableTruncation` (no ellipsis, no shrink). The
+ * hard single-line overflow is honoured on web (Storybook / react-native-web).
+ *
+ * When neither flag is set, the supplied `numberOfLines`/`ellipsizeMode` pass
+ * through unchanged and no extra style is returned.
+ */
+export function resolveTextLayout({
+    disableTruncation,
+    singleLine,
+    numberOfLines,
+    ellipsizeMode,
+}: {
+    disableTruncation?: boolean | undefined;
+    singleLine?: boolean | undefined;
+    numberOfLines?: number | undefined;
+    ellipsizeMode?: EllipsizeMode | undefined;
+}): TextLayoutResult {
+    if (singleLine) {
+        return {
+            numberOfLines: undefined,
+            ellipsizeMode: undefined,
+            style: {
+                flexShrink: 0,
+                flexGrow: 0,
+                ...(Platform.OS === 'web'
+                    ? { whiteSpace: 'nowrap' as const, overflow: 'visible' as const }
+                    : {}),
+            },
+        }
+    }
+    if (disableTruncation) {
+        return {
+            numberOfLines: undefined,
+            ellipsizeMode: undefined,
+            style: {
+                flexShrink: 0,
+                ...(Platform.OS === 'web' ? { overflow: 'visible' as const } : {}),
+            },
+        }
+    }
+    return { numberOfLines, ellipsizeMode }
+}
+
 /**
  * Flattens React children, extracting them from Fragments.
  * Useful for Group components that need to process individual items (e.g., for layout or styling)

package/src/utils/shadow.ts

@@ -0,0 +1,219 @@
+import { Platform } from 'react-native'
+import type { ViewStyle } from 'react-native'
+
+/**
+ * Cross-platform drop-shadow helper with a backward-compatibility layer.
+ *
+ * Why this exists
+ * ----------------
+ * The spec-compliant `boxShadow` style prop only landed in React Native 0.76
+ * (and only on the New Architecture / Fabric). Older apps that consume this
+ * library are still on pre-0.76 React Native where `boxShadow` is silently
+ * ignored on native, so their shadows simply disappear.
+ *
+ * Rather than hand-rolling a `Platform.select` block in every component, route
+ * ALL drop shadows through this single helper. When `boxShadow` is natively
+ * supported it is used verbatim (web + RN 0.76+ Fabric). When it is NOT
+ * supported, the CSS-style shadow string is parsed and translated into the
+ * legacy native shadow API:
+ *   - iOS:     `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius`
+ *   - Android: `elevation`
+ *
+ * @example
+ * ```tsx
+ * const style = boxShadow('0px 2px 4px 0px rgba(0,0,0,0.18)')
+ * <View style={[base, style]} />
+ * ```
+ */
+
+export interface ParsedShadow {
+  offsetX: number
+  offsetY: number
+  blur: number
+  spread: number
+  color: string
+  inset: boolean
+}
+
+export interface BoxShadowOptions {
+  /**
+   * Explicit Android `elevation` for the legacy fallback. When omitted it is
+   * derived from the most prominent shadow's blur radius. Android elevation
+   * cannot reproduce colored/ring shadows, so provide this when the default
+   * heuristic doesn't match the design.
+   */
+  elevation?: number
+}
+
+// `boxShadow` is intentionally absent from the @types/react-native surface in
+// this repo (pinned to 0.73), so we widen ViewStyle locally for the cases
+// where we DO emit the native/web boxShadow string.
+type ShadowViewStyle = ViewStyle & { boxShadow?: string }
+
+/**
+ * Whether the spec-compliant `boxShadow` style prop is honored at runtime.
+ * - Web (react-native-web) always supports it.
+ * - Native supports it from RN 0.76+ AND only on the New Architecture (Fabric).
+ */
+export function supportsNativeBoxShadow(): boolean {
+  if (Platform.OS === 'web') {
+    return true
+  }
+
+  const version = (Platform.constants as { reactNativeVersion?: { major: number; minor: number } } | undefined)
+    ?.reactNativeVersion
+
+  const isVersionSupported = version
+    ? version.major > 0 || (version.major === 0 && version.minor >= 76)
+    : false
+
+  // Even on 0.76+, boxShadow is a New Architecture feature. Fabric exposes a
+  // global UI manager; its presence is the most reliable runtime signal.
+  const isFabric =
+    typeof globalThis !== 'undefined' &&
+    (globalThis as { nativeFabricUIManager?: unknown }).nativeFabricUIManager != null
+
+  return isVersionSupported && isFabric
+}
+
+/**
+ * Splits a (potentially multi-) box-shadow string on top-level commas, i.e.
+ * commas that are NOT inside a color function such as `rgba(12, 13, 16, 0.12)`.
+ */
+function splitShadows(value: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let current = ''
+
+  for (const ch of value) {
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+
+    if (ch === ',' && depth === 0) {
+      if (current.trim()) out.push(current.trim())
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+
+  if (current.trim()) out.push(current.trim())
+  return out
+}
+
+/**
+ * Parses a single CSS box-shadow layer into its primitive parts.
+ * Supports: `[inset] offsetX offsetY [blur] [spread] color` in any sensible
+ * ordering of the keyword/color, with `rgb()/rgba()/hsl()/hsla()`, hex, or
+ * named colors.
+ */
+export function parseSingleShadow(input: string): ParsedShadow {
+  let s = input.trim()
+
+  let inset = false
+  if (/(^|\s)inset(\s|$)/i.test(s)) {
+    inset = true
+    s = s.replace(/(^|\s)inset(\s|$)/i, ' ').trim()
+  }
+
+  let color = 'rgba(0,0,0,1)'
+  const fnColor = s.match(/(?:rgba?|hsla?)\([^)]*\)/i)
+  if (fnColor) {
+    color = fnColor[0]
+    s = s.replace(fnColor[0], ' ').trim()
+  } else {
+    const hex = s.match(/#[0-9a-fA-F]{3,8}\b/)
+    if (hex) {
+      color = hex[0]
+      s = s.replace(hex[0], ' ').trim()
+    } else {
+      // Fall back to a trailing named color token (e.g. "red", "black").
+      const tokens = s.split(/\s+/).filter(Boolean)
+      const last = tokens[tokens.length - 1]
+      if (last && Number.isNaN(parseFloat(last))) {
+        color = last
+        tokens.pop()
+        s = tokens.join(' ')
+      }
+    }
+  }
+
+  const nums = s.split(/\s+/).filter(Boolean).map((t) => parseFloat(t) || 0)
+  const [offsetX = 0, offsetY = 0, blur = 0, spread = 0] = nums
+
+  return { offsetX, offsetY, blur, spread, color, inset }
+}
+
+/**
+ * Parses a full box-shadow string (one or more comma-separated layers).
+ */
+export function parseBoxShadow(value: string): ParsedShadow[] {
+  return splitShadows(value).map(parseSingleShadow)
+}
+
+/**
+ * Picks the visually dominant shadow layer (largest blur, then largest spread).
+ * iOS' legacy shadow API can only render a single shadow per view.
+ */
+function pickPrimary(shadows: ParsedShadow[]): ParsedShadow | undefined {
+  if (shadows.length === 0) return undefined
+  return shadows.reduce((best, s) => {
+    if (s.blur > best.blur) return s
+    if (s.blur === best.blur && s.spread > best.spread) return s
+    return best
+  })
+}
+
+/**
+ * Translates the parsed shadow into the legacy native shadow style used by
+ * pre-0.76 React Native.
+ */
+function legacyShadowStyle(value: string, options?: BoxShadowOptions): ViewStyle {
+  const shadows = parseBoxShadow(value)
+  const primary = pickPrimary(shadows)
+
+  if (!primary) {
+    return {}
+  }
+
+  if (Platform.OS === 'android') {
+    const elevation = options?.elevation ?? Math.max(0, Math.round(primary.blur / 2))
+    if (elevation <= 0) {
+      return {}
+    }
+    return { elevation }
+  }
+
+  // iOS: shadowOpacity defaults to 0 (invisible), so it MUST be set. We keep
+  // the full color (its own alpha is respected) and use opacity 1 as the
+  // multiplier so rgba() alpha is honored end-to-end.
+  return {
+    shadowColor: primary.color,
+    shadowOffset: { width: primary.offsetX, height: primary.offsetY },
+    shadowOpacity: 1,
+    shadowRadius: primary.blur,
+  }
+}
+
+/**
+ * Returns a style object that renders the given CSS-style box-shadow on every
+ * platform. Uses the native `boxShadow` prop when supported, otherwise falls
+ * back to the legacy `shadow*` (iOS) / `elevation` (Android) API.
+ *
+ * @param value   A CSS box-shadow string, e.g. `'0px 2px 4px 0px rgba(0,0,0,0.2)'`.
+ *                Multiple comma-separated layers are supported; on the legacy
+ *                fallback iOS uses the most prominent layer and Android uses a
+ *                single elevation.
+ * @param options Optional overrides (e.g. explicit Android `elevation`).
+ */
+export function boxShadow(value: string, options?: BoxShadowOptions): ViewStyle {
+  if (!value) {
+    return {}
+  }
+
+  if (supportsNativeBoxShadow()) {
+    return { boxShadow: value } as ShadowViewStyle
+  }
+
+  return legacyShadowStyle(value, options)
+}