@neeleshyadav/react-native-html-renderer 1.1.0

package/src/types/index.ts

@@ -0,0 +1,229 @@
+import type { ReactNode } from 'react';
+import type {
+  TextStyle,
+  ViewStyle,
+  ImageStyle,
+  TextProps,
+  ViewProps,
+  ColorSchemeName,
+} from 'react-native';
+
+// ---------------------------------------------------------------------------
+// DOM Nodes
+// ---------------------------------------------------------------------------
+
+/** A parsed DOM node — either an element or a text node. */
+export type DOMNode = DOMElement | DOMText;
+
+/** An HTML element node with tag, attributes, and children. */
+export interface DOMElement {
+  type: 'element';
+  tag: string;
+  attributes: Record<string, string>;
+  children: DOMNode[];
+}
+
+/** A text node containing raw string data. */
+export interface DOMText {
+  type: 'text';
+  data: string;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+/** Union of all React Native style types. */
+export type RNStyle = ViewStyle | TextStyle | ImageStyle;
+
+/** Per-tag style overrides keyed by HTML tag name. */
+export type TagsStyles = Record<string, RNStyle>;
+
+/** Per-class style overrides keyed by HTML class name. */
+export type ClassesStyles = Record<string, RNStyle>;
+
+/** Per-id style overrides keyed by HTML element id. */
+export type IdsStyles = Record<string, RNStyle>;
+
+// ---------------------------------------------------------------------------
+// Custom Renderers
+// ---------------------------------------------------------------------------
+
+/** Props passed to a custom renderer function. */
+export interface CustomRendererProps {
+  /** The DOM element node being rendered. */
+  node: DOMElement;
+  /** Pre-rendered children as React nodes. */
+  children: ReactNode[];
+  /** Merged style for this element. */
+  style: RNStyle;
+  /** Attributes from the HTML element. */
+  attributes: Record<string, string>;
+  /** Extra props passed via renderersProps[tag]. */
+  passProps: Record<string, unknown>;
+  /** Render helper — call with child DOMNodes to render them. */
+  renderChildren: (nodes: DOMNode[]) => ReactNode[];
+  /** Current content width from context. */
+  contentWidth: number;
+}
+
+/** A custom renderer receives props and returns a ReactNode. */
+export type CustomRenderer = (props: CustomRendererProps) => ReactNode;
+
+// ---------------------------------------------------------------------------
+// List prefix renderers
+// ---------------------------------------------------------------------------
+
+export interface ListPrefixRendererProps {
+  index: number;
+  nestLevel: number;
+}
+
+export interface ListsPrefixesRenderers {
+  ul?: (props: ListPrefixRendererProps) => ReactNode;
+  ol?: (props: ListPrefixRendererProps) => ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// HtmlRenderer Props
+// ---------------------------------------------------------------------------
+
+/** Props for the main `<HtmlRenderer />` component. */
+export interface HtmlRendererProps {
+  /** Raw HTML string to render. */
+  html: string;
+
+  /** Available width for content layout and image scaling. */
+  contentWidth: number;
+
+  /** Base style applied to the root container. */
+  baseStyle?: ViewStyle;
+
+  /** Per-tag style overrides. */
+  tagsStyles?: TagsStyles;
+
+  /** Styles applied by HTML class name. */
+  classesStyles?: ClassesStyles;
+
+  /** Styles applied by HTML element id. */
+  idsStyles?: IdsStyles;
+
+  /** Override rendering for specific tags. */
+  customRenderers?: Record<string, CustomRenderer>;
+
+  /** Called when a link (`<a>`) is pressed. */
+  onLinkPress?: (href: string, attributes: Record<string, string>) => void;
+
+  /** Called when an image is pressed. */
+  onImagePress?: (src: string, attributes: Record<string, string>) => void;
+
+  /** Called when an error occurs during parsing or rendering. */
+  onError?: (error: Error) => void;
+
+  /** Custom fallback UI to show when an error occurs. If omitted, a default error message is shown. Set to `null` to render nothing on error. */
+  fallback?: ReactNode;
+
+  /** Tags to completely ignore (including their children). */
+  ignoredTags?: string[];
+
+  /** CSS property names to ignore during style conversion. */
+  ignoredStyles?: string[];
+
+  /** Whitelist of CSS property names to allow (if set, only these are kept). */
+  allowedStyles?: string[];
+
+  /** Default props passed to every `<Text>` component. */
+  defaultTextProps?: TextProps;
+
+  /** Default props passed to every `<View>` component. */
+  defaultViewProps?: ViewProps;
+
+  /** Extra props forwarded to specific tag renderers. */
+  renderersProps?: Record<string, Record<string, unknown>>;
+
+  /** Maximum width for images. */
+  maxImagesWidth?: number;
+
+  /** Placeholder dimensions before image loads. */
+  imagesInitialDimensions?: { width: number; height: number };
+
+  /** Custom bullet/number renderers for lists. */
+  listsPrefixesRenderers?: ListsPrefixesRenderers;
+
+  /** Base em unit in pixels (default 14). */
+  emSize?: number;
+
+  /** List of available system fonts. */
+  systemFonts?: string[];
+
+  /** Map unsupported font families to fallback fonts. */
+  fallbackFonts?: Record<string, string>;
+
+  /** Log parsed DOM and computed styles to the console. */
+  debug?: boolean;
+
+  // --- Security ---
+
+  /**
+   * When false (default), dangerous tags (`<script>`, `<iframe>`, `<object>`,
+   * `<embed>`, `<form>`) and `javascript:` hrefs are stripped automatically.
+   * Set to true to allow all HTML through (use with caution).
+   */
+  allowDangerousHtml?: boolean;
+
+  // --- Dark Mode ---
+
+  /** Per-tag style overrides applied when the system is in dark mode. */
+  darkModeStyles?: TagsStyles;
+
+  /**
+   * Override color scheme detection. When omitted the system scheme is used
+   * via `useColorScheme()`.
+   */
+  colorScheme?: ColorSchemeName;
+
+  // --- Font Scaling ---
+
+  /** Allow system font-size accessibility scaling (default true). */
+  allowFontScaling?: boolean;
+
+  /** Cap the font-size multiplier for accessibility scaling. */
+  maxFontSizeMultiplier?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal Context
+// ---------------------------------------------------------------------------
+
+/** Shape of the context shared through the renderer tree. */
+export interface HtmlRendererContextValue {
+  contentWidth: number;
+  tagsStyles: TagsStyles;
+  classesStyles: ClassesStyles;
+  idsStyles: IdsStyles;
+  customRenderers: Record<string, CustomRenderer>;
+  onLinkPress?: (href: string, attributes: Record<string, string>) => void;
+  onImagePress?: (src: string, attributes: Record<string, string>) => void;
+  renderersProps: Record<string, Record<string, unknown>>;
+  emSize: number;
+  debug: boolean;
+  ignoredTags: Set<string>;
+  ignoredStyles: Set<string>;
+  allowedStyles: Set<string> | null;
+  defaultTextProps?: TextProps;
+  defaultViewProps?: ViewProps;
+  maxImagesWidth?: number;
+  imagesInitialDimensions: { width: number; height: number };
+  listsPrefixesRenderers?: ListsPrefixesRenderers;
+  systemFonts?: string[];
+  fallbackFonts?: Record<string, string>;
+  nestLevel: number;
+  /** Resolved color scheme — 'dark' | 'light' | null | undefined. */
+  colorScheme: ColorSchemeName | null | undefined;
+  /** Dark mode tag style overrides (merged into tagsStyles when dark). */
+  darkModeStyles: TagsStyles;
+  /** Allow system font scaling on Text components. */
+  allowFontScaling: boolean;
+  /** Cap the font size multiplier. */
+  maxFontSizeMultiplier?: number;
+}

package/src/utils/accessibility.ts

@@ -0,0 +1,132 @@
+import type { AccessibilityRole } from 'react-native';
+import type { DOMElement } from '../types';
+import { extractTextContent } from './index';
+
+/** Map HTML tags to React Native accessibility roles. */
+const TAG_TO_ROLE: Record<string, AccessibilityRole> = {
+  a: 'link',
+  button: 'button',
+  img: 'image',
+  h1: 'header',
+  h2: 'header',
+  h3: 'header',
+  h4: 'header',
+  h5: 'header',
+  h6: 'header',
+  input: 'none',
+  textarea: 'none',
+  nav: 'menu',
+  form: 'none',
+  summary: 'button',
+};
+
+/** Accessibility props derived from a DOM element's attributes. */
+export interface A11yProps {
+  accessibilityRole?: AccessibilityRole;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  accessibilityState?: {
+    disabled?: boolean;
+    selected?: boolean;
+    checked?: boolean | 'mixed';
+    busy?: boolean;
+    expanded?: boolean;
+  };
+  accessible?: boolean;
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+}
+
+/**
+ * Extract accessibility props from a DOMElement's HTML attributes.
+ * Supports: aria-label, aria-hidden, aria-role, role, alt, title,
+ * aria-disabled, aria-selected, aria-checked, aria-busy, aria-expanded.
+ */
+export function getAccessibilityProps(node: DOMElement): A11yProps {
+  const attrs = node.attributes;
+  const props: A11yProps = {};
+
+  // Role: aria-role > role attribute > tag-based default
+  const ariaRole = attrs['aria-role'] ?? attrs.role;
+  if (ariaRole) {
+    props.accessibilityRole = ariaRole as AccessibilityRole;
+  } else if (TAG_TO_ROLE[node.tag]) {
+    props.accessibilityRole = TAG_TO_ROLE[node.tag];
+  }
+
+  // Label: aria-label > alt > title > text content for certain tags
+  const ariaLabel = attrs['aria-label'];
+  if (ariaLabel) {
+    props.accessibilityLabel = ariaLabel;
+  } else if (attrs.alt) {
+    props.accessibilityLabel = attrs.alt;
+  } else if (attrs.title) {
+    props.accessibilityLabel = attrs.title;
+  }
+
+  // Hint: for links, use href as hint
+  if (node.tag === 'a' && attrs.href) {
+    props.accessibilityHint = `Opens ${attrs.href}`;
+  }
+
+  // Hidden: aria-hidden
+  if (attrs['aria-hidden'] === 'true') {
+    props.importantForAccessibility = 'no-hide-descendants';
+    props.accessible = false;
+  }
+
+  // Accessibility state
+  const state: A11yProps['accessibilityState'] = {};
+  let hasState = false;
+
+  if (attrs['aria-disabled'] === 'true' || attrs.disabled != null) {
+    state.disabled = true;
+    hasState = true;
+  }
+  if (attrs['aria-selected'] === 'true') {
+    state.selected = true;
+    hasState = true;
+  }
+  if (attrs['aria-checked'] != null) {
+    state.checked =
+      attrs['aria-checked'] === 'mixed'
+        ? 'mixed'
+        : attrs['aria-checked'] === 'true';
+    hasState = true;
+  }
+  if (attrs['aria-busy'] === 'true') {
+    state.busy = true;
+    hasState = true;
+  }
+  if (attrs['aria-expanded'] != null) {
+    state.expanded = attrs['aria-expanded'] === 'true';
+    hasState = true;
+  }
+
+  if (hasState) {
+    props.accessibilityState = state;
+  }
+
+  return props;
+}
+
+/**
+ * Build an accessibility label for an image from its attributes.
+ */
+export function getImageA11yLabel(node: DOMElement): string | undefined {
+  return (
+    node.attributes['aria-label'] ??
+    node.attributes.alt ??
+    node.attributes.title ??
+    undefined
+  );
+}
+
+/**
+ * Build an accessibility label for a link from its children text.
+ */
+export function getLinkA11yLabel(node: DOMElement): string | undefined {
+  const ariaLabel = node.attributes['aria-label'];
+  if (ariaLabel) return ariaLabel;
+  const textContent = extractTextContent(node.children);
+  return textContent || undefined;
+}

package/src/utils/cache.ts

@@ -0,0 +1,83 @@
+import type { DOMNode } from '../types';
+
+// ---------------------------------------------------------------------------
+// Image Dimension Cache (LRU, bounded)
+// ---------------------------------------------------------------------------
+
+interface ImageDimensions {
+  width: number;
+  height: number;
+}
+
+const imageDimensionCache = new Map<string, ImageDimensions>();
+const IMAGE_CACHE_MAX_SIZE = 200;
+
+/** Get cached image dimensions for a URL. */
+export function getCachedImageDimensions(
+  uri: string
+): ImageDimensions | undefined {
+  return imageDimensionCache.get(uri);
+}
+
+/** Cache image dimensions for a URL. */
+export function setCachedImageDimensions(
+  uri: string,
+  dimensions: ImageDimensions
+): void {
+  if (imageDimensionCache.size >= IMAGE_CACHE_MAX_SIZE) {
+    const firstKey = imageDimensionCache.keys().next().value;
+    if (firstKey !== undefined) {
+      imageDimensionCache.delete(firstKey);
+    }
+  }
+  imageDimensionCache.set(uri, dimensions);
+}
+
+/** Clear the image dimension cache (useful for testing). */
+export function clearImageDimensionCache(): void {
+  imageDimensionCache.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Parsed DOM Cache (LRU, bounded)
+// Cache key includes html + allowDangerousHtml + ignoredTags to prevent
+// cache poisoning when these parameters change.
+// ---------------------------------------------------------------------------
+
+const domCache = new Map<string, DOMNode[]>();
+const DOM_CACHE_MAX_SIZE = 50;
+
+/**
+ * Build a composite cache key that incorporates all parameters affecting
+ * the parse/sanitize result, preventing cache poisoning.
+ */
+export function buildDOMCacheKey(
+  html: string,
+  allowDangerousHtml: boolean,
+  ignoredTags: Set<string>
+): string {
+  const tagsSuffix =
+    ignoredTags.size > 0 ? [...ignoredTags].sort().join(',') : '';
+  return `${allowDangerousHtml ? '1' : '0'}|${tagsSuffix}|${html}`;
+}
+
+/** Get cached parsed DOM for a cache key. */
+export function getCachedDOM(cacheKey: string): DOMNode[] | undefined {
+  return domCache.get(cacheKey);
+}
+
+/** Cache parsed DOM for a cache key. */
+export function setCachedDOM(cacheKey: string, nodes: DOMNode[]): void {
+  if (domCache.size >= DOM_CACHE_MAX_SIZE) {
+    const firstKey = domCache.keys().next().value;
+    if (firstKey !== undefined) {
+      domCache.delete(firstKey);
+    }
+  }
+  domCache.set(cacheKey, nodes);
+}
+
+/** Clear the DOM cache (useful for testing). */
+export function clearDOMCache(): void {
+  domCache.clear();
+}

package/src/utils/index.ts

@@ -0,0 +1,151 @@
+import type { DOMNode, DOMElement } from '../types';
+
+// Re-export sub-modules
+export { sanitizeDOM } from './sanitize';
+export {
+  getAccessibilityProps,
+  getImageA11yLabel,
+  getLinkA11yLabel,
+  type A11yProps,
+} from './accessibility';
+export {
+  getCachedImageDimensions,
+  setCachedImageDimensions,
+  clearImageDimensionCache,
+  getCachedDOM,
+  setCachedDOM,
+  clearDOMCache,
+  buildDOMCacheKey,
+} from './cache';
+
+// ---------------------------------------------------------------------------
+// CSS unit conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a CSS value string to a numeric pixel value.
+ * Supports: px, em, rem, bare numbers. Percentage returns NaN (handled upstream).
+ */
+export function cssValueToNumeric(
+  value: string,
+  emSize: number
+): number | undefined {
+  const trimmed = value.trim();
+  if (trimmed.endsWith('px')) {
+    return parseFloat(trimmed);
+  }
+  if (trimmed.endsWith('em') || trimmed.endsWith('rem')) {
+    return parseFloat(trimmed) * emSize;
+  }
+  if (trimmed.endsWith('%')) {
+    // Percentage — return undefined, caller must handle contextually
+    return undefined;
+  }
+  const num = parseFloat(trimmed);
+  return isNaN(num) ? undefined : num;
+}
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+/** Tags that are inherently inline (text-level). */
+export const INLINE_TAGS = new Set([
+  'span',
+  'strong',
+  'b',
+  'em',
+  'i',
+  'u',
+  's',
+  'strike',
+  'del',
+  'ins',
+  'mark',
+  'small',
+  'sub',
+  'sup',
+  'a',
+  'code',
+  'br',
+]);
+
+/** Tags that are text containers (rendered as `<Text>` at block level). */
+export const TEXT_BLOCK_TAGS = new Set([
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'li',
+  'th',
+  'td',
+  'pre',
+  'label',
+  'dt',
+  'dd',
+]);
+
+/** Tags that should be silently skipped (no output). */
+export const ALWAYS_IGNORED_TAGS = new Set([
+  'script',
+  'style',
+  'head',
+  'meta',
+  'link',
+  'title',
+  'noscript',
+]);
+
+/**
+ * Returns true if every child of the given list is either a text node
+ * or an inline-level element whose descendants are also all inline.
+ */
+export function isInlineContent(nodes: DOMNode[]): boolean {
+  return nodes.every((node) => {
+    if (node.type === 'text') return true;
+    if (node.type === 'element') {
+      return INLINE_TAGS.has(node.tag) && isInlineContent(node.children);
+    }
+    return false;
+  });
+}
+
+/**
+ * Resolve a potentially relative URL against a base URL.
+ */
+export function resolveUrl(url: string, baseUrl?: string): string {
+  if (!baseUrl || /^https?:\/\//i.test(url) || url.startsWith('data:')) {
+    return url;
+  }
+  const base = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
+  return url.startsWith('/') ? base + url.slice(1) : base + url;
+}
+
+/**
+ * Type-guard: checks if a DOMNode is a DOMElement.
+ */
+export function isDOMElement(node: DOMNode): node is DOMElement {
+  return node.type === 'element';
+}
+
+/**
+ * Extract all text content from a node tree (for accessibility labels, etc.).
+ */
+export function extractTextContent(nodes: DOMNode[]): string {
+  let text = '';
+  for (const node of nodes) {
+    if (node.type === 'text') {
+      text += node.data;
+    } else if (node.type === 'element') {
+      if (node.tag === 'br') {
+        text += '\n';
+      } else {
+        text += extractTextContent(node.children);
+      }
+    }
+  }
+  return text;
+}