jfs-components 0.0.64 → 0.0.65

package/src/utils/MediaSource.tsx

@@ -0,0 +1,220 @@
+import React from 'react'
+import {
+  Image,
+  type ImageStyle,
+  type ImageURISource,
+  type StyleProp,
+} from 'react-native'
+import { SvgUri, SvgXml } from 'react-native-svg'
+
+/**
+ * A unified, "do-the-right-thing" image source accepted by `MediaSource` and
+ * by the `source` prop on `Icon`, `IconCapsule` and `UpiHandle`.
+ *
+ * Accepts any of:
+ *  - `string`   — a URI (raster or `.svg`) **or** an inline SVG XML document
+ *                 (`'<svg …>…</svg>'`).
+ *  - `number`   — a Metro asset id from `require('./foo.png')`.
+ *  - `{ uri, … }` — the standard RN `ImageURISource` object (works for both
+ *                   raster and `.svg` URIs).
+ *  - `React.ComponentType` — an SVG React component (e.g. produced by
+ *                            `react-native-svg-transformer`, by `@svgr/*`,
+ *                            or hand-written). It is rendered with
+ *                            `{ width, height, color, fill }` so it can be
+ *                            tinted just like a built-in icon.
+ *  - `React.ReactElement`  — an already-rendered node, passed through verbatim.
+ *
+ * The helper sniffs the input shape (no extension hint required from the
+ * caller) and picks the correct renderer for the platform.
+ */
+export type UnifiedSource =
+  | string
+  | number
+  | ImageURISource
+  | React.ComponentType<{
+      width?: number
+      height?: number
+      color?: string
+      fill?: string
+    }>
+  | React.ReactElement
+
+export type MediaSourceProps = {
+  /** Smart source. See {@link UnifiedSource}. */
+  source: UnifiedSource
+  /** Convenience shorthand that sets both width and height. */
+  size?: number
+  width?: number
+  height?: number
+  /**
+   * Optional tint applied to the rendered media.
+   *  - Raster `<Image>` → mapped to `style.tintColor` (works on iOS, Android,
+   *    and react-native-web).
+   *  - SVG (XML / URI / component) → mapped to the `color` / `fill` props.
+   *    For an SVG to actually re-color, its source must use `currentColor`
+   *    (or have no hardcoded fill). SVGs with baked-in `fill="#xxx"` cannot
+   *    be re-tinted without parsing — this is a `react-native-svg`
+   *    limitation, not something we can paper over here.
+   */
+  tintColor?: string
+  /** Extra style merged into the underlying `<Image>` (raster path only). */
+  style?: StyleProp<ImageStyle>
+  resizeMode?: 'cover' | 'contain' | 'stretch' | 'center' | 'repeat'
+  accessibilityElementsHidden?: boolean
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants'
+}
+
+const SVG_XML_RE = /<svg[\s>]/i
+const SVG_URI_RE = /\.svg(\?|#|$)/i
+
+function isSvgXml(s: string): boolean {
+  return /^\s*</.test(s) && SVG_XML_RE.test(s)
+}
+
+function isSvgUri(s: string): boolean {
+  return SVG_URI_RE.test(s)
+}
+
+function isUriObject(
+  v: unknown
+): v is ImageURISource & { uri: string } {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    'uri' in v &&
+    typeof (v as { uri: unknown }).uri === 'string'
+  )
+}
+
+/**
+ * Smart renderer that picks the right primitive for the source shape. See
+ * {@link UnifiedSource}.
+ *
+ * Designed to be used internally by `Icon`, `IconCapsule`, and `UpiHandle`,
+ * but also exported for ad-hoc consumer use.
+ */
+function MediaSource(props: MediaSourceProps) {
+  const {
+    source,
+    size,
+    width,
+    height,
+    tintColor,
+    style,
+    resizeMode = 'cover',
+    accessibilityElementsHidden,
+    importantForAccessibility,
+  } = props
+
+  const w = width ?? size
+  const h = height ?? size
+
+  // Pre-rendered element — pass through.
+  if (React.isValidElement(source)) {
+    return source
+  }
+
+  // SVG / icon component.
+  if (typeof source === 'function') {
+    const Comp = source as React.ComponentType<{
+      width?: number
+      height?: number
+      color?: string
+      fill?: string
+    }>
+    return (
+      <Comp
+        {...(w !== undefined ? { width: w } : {})}
+        {...(h !== undefined ? { height: h } : {})}
+        {...(tintColor !== undefined ? { color: tintColor, fill: tintColor } : {})}
+      />
+    )
+  }
+
+  const sizeStyle: ImageStyle | null =
+    w !== undefined || h !== undefined ? { width: w, height: h } : null
+  const tintStyle: ImageStyle | null = tintColor ? { tintColor } : null
+  const composedStyle: StyleProp<ImageStyle> = [sizeStyle, tintStyle, style]
+
+  if (typeof source === 'string') {
+    if (isSvgXml(source)) {
+      return (
+        <SvgXml
+          xml={source}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    if (isSvgUri(source)) {
+      return (
+        <SvgUri
+          uri={source}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    return (
+      <Image
+        source={{ uri: source }}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  if (isUriObject(source)) {
+    if (isSvgUri(source.uri)) {
+      return (
+        <SvgUri
+          uri={source.uri}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    return (
+      <Image
+        source={source}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  if (typeof source === 'number') {
+    return (
+      <Image
+        source={source}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  return null
+}
+
+export default React.memo(MediaSource)

package/src/utils/index.ts

@@ -1 +1,3 @@
 export { cloneChildrenWithModes, flattenChildren } from './react-utils'
+export { default as MediaSource } from './MediaSource'
+export type { UnifiedSource, MediaSourceProps } from './MediaSource'