react-native-richify 1.0.0

package/src/components/RichTextInput.tsx

@@ -0,0 +1,174 @@
+import React, { useEffect, useCallback } from 'react';
+import {
+  View,
+  TextInput,
+  StyleSheet,
+  type NativeSyntheticEvent,
+  type TextInputSelectionChangeEventData,
+} from 'react-native';
+import type { RichTextInputProps } from '@/types';
+import { DEFAULT_THEME } from '@/constants/defaultStyles';
+import { segmentsToPlainText } from '@/utils/parser';
+import { useRichText } from '@/hooks/useRichText';
+import { OverlayText } from '@/components/OverlayText';
+import { Toolbar } from '@/components/Toolbar';
+
+/**
+ * RichTextInput — The main rich text editor component.
+ *
+ * Uses the Overlay Technique:
+ * - A transparent `TextInput` on top captures user input and selection
+ * - A styled `<Text>` layer behind it renders the formatted content
+ * - Both share identical font metrics for pixel-perfect alignment
+ *
+ * @example
+ * ```tsx
+ * <RichTextInput
+ *   placeholder="Start typing..."
+ *   showToolbar
+ *   onChangeSegments={(segments) => console.log(segments)}
+ * />
+ * ```
+ */
+export const RichTextInput: React.FC<RichTextInputProps> = ({
+  initialSegments,
+  onChangeSegments,
+  onChangeText,
+  placeholder = 'Start typing...',
+  editable = true,
+  maxLength,
+  showToolbar = true,
+  toolbarPosition = 'top',
+  toolbarItems,
+  theme,
+  multiline = true,
+  minHeight = 120,
+  maxHeight,
+  autoFocus = false,
+  textInputProps,
+  renderToolbar,
+  onReady,
+}) => {
+  const resolvedTheme = theme ?? DEFAULT_THEME;
+
+  const { state, actions } = useRichText({
+    initialSegments,
+    onChangeSegments,
+    onChangeText,
+  });
+
+  // Expose actions via onReady callback
+  useEffect(() => {
+    onReady?.(actions);
+  }, [onReady, actions]);
+
+  // Build plain text for the TextInput value
+  const plainText = segmentsToPlainText(state.segments);
+
+  // Handle selection change from TextInput
+  const onSelectionChange = useCallback(
+    (e: NativeSyntheticEvent<TextInputSelectionChangeEventData>) => {
+      const { start, end } = e.nativeEvent.selection;
+      actions.handleSelectionChange({ start, end });
+    },
+    [actions],
+  );
+
+  // Container style
+  const containerStyle = [
+    resolvedTheme.containerStyle ?? DEFAULT_THEME.containerStyle,
+  ];
+
+  // Input area style
+  const inputAreaStyle = [
+    styles.inputArea,
+    { minHeight },
+    maxHeight ? { maxHeight } : undefined,
+  ];
+
+  // Input style
+  const inputStyle = [
+    styles.textInput,
+    resolvedTheme.inputStyle ?? DEFAULT_THEME.inputStyle,
+  ];
+
+  // Toolbar component
+  const toolbarComponent = showToolbar ? (
+    <Toolbar
+      actions={actions}
+      state={state}
+      items={toolbarItems}
+      theme={resolvedTheme}
+      renderToolbar={renderToolbar}
+    />
+  ) : null;
+
+  // Toolbar border
+  const toolbarBorderStyle =
+    toolbarPosition === 'top'
+      ? { borderBottomWidth: 1, borderBottomColor: resolvedTheme.colors?.toolbarBorder ?? DEFAULT_THEME.colors?.toolbarBorder }
+      : { borderTopWidth: 1, borderTopColor: resolvedTheme.colors?.toolbarBorder ?? DEFAULT_THEME.colors?.toolbarBorder };
+
+  return (
+    <View style={containerStyle}>
+      {/* Toolbar — Top */}
+      {toolbarPosition === 'top' && toolbarComponent && (
+        <View style={toolbarBorderStyle}>{toolbarComponent}</View>
+      )}
+
+      {/* Editor Area */}
+      <View style={inputAreaStyle}>
+        {/* Overlay — Styled text rendering (behind TextInput) */}
+        <OverlayText
+          segments={state.segments}
+          baseTextStyle={resolvedTheme.baseTextStyle}
+          theme={resolvedTheme}
+        />
+
+        {/* TextInput — Transparent layer on top for input capture */}
+        <TextInput
+          {...textInputProps}
+          style={inputStyle}
+          value={plainText}
+          onChangeText={actions.handleTextChange}
+          onSelectionChange={onSelectionChange}
+          multiline={multiline}
+          placeholder={placeholder}
+          placeholderTextColor={
+            resolvedTheme.colors?.placeholder ??
+            DEFAULT_THEME.colors?.placeholder
+          }
+          editable={editable}
+          maxLength={maxLength}
+          autoFocus={autoFocus}
+          selectionColor={
+            resolvedTheme.colors?.cursor ?? DEFAULT_THEME.colors?.cursor
+          }
+          textAlignVertical="top"
+          scrollEnabled={true}
+        />
+      </View>
+
+      {/* Toolbar — Bottom */}
+      {toolbarPosition === 'bottom' && toolbarComponent && (
+        <View style={toolbarBorderStyle}>{toolbarComponent}</View>
+      )}
+    </View>
+  );
+};
+
+RichTextInput.displayName = 'RichTextInput';
+
+const styles = StyleSheet.create({
+  inputArea: {
+    position: 'relative',
+  },
+  textInput: {
+    // The TextInput must be transparent so the overlay text shows through.
+    // Only the caret/cursor and selection highlight are visible.
+    color: 'transparent',
+    // Ensure it matches the overlay text positioning exactly.
+    position: 'relative',
+    zIndex: 1,
+  },
+});

package/src/components/Toolbar.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { ToolbarProps } from '@/types';
+/**
+ * Formatting toolbar for the rich text editor.
+ *
+ * Supports:
+ * - Default toolbar items (bold, italic, underline, etc.)
+ * - Custom toolbar items via the `items` prop
+ * - Fully custom rendering via `renderToolbar`
+ * - Horizontal scrolling for overflow
+ */
+export declare const Toolbar: React.FC<ToolbarProps>;

package/src/components/Toolbar.tsx

@@ -0,0 +1,100 @@
+import React, { useMemo } from 'react';
+import { View, ScrollView, StyleSheet } from 'react-native';
+import type { ToolbarProps, ToolbarItem } from '@/types';
+import { DEFAULT_THEME, DEFAULT_TOOLBAR_ITEMS } from '@/constants/defaultStyles';
+import { ToolbarButton } from '@/components/ToolbarButton';
+
+/**
+ * Formatting toolbar for the rich text editor.
+ *
+ * Supports:
+ * - Default toolbar items (bold, italic, underline, etc.)
+ * - Custom toolbar items via the `items` prop
+ * - Fully custom rendering via `renderToolbar`
+ * - Horizontal scrolling for overflow
+ */
+export const Toolbar: React.FC<ToolbarProps> = React.memo(
+  ({ actions, state, items, theme, visible = true, renderToolbar }) => {
+    const resolvedTheme = theme ?? DEFAULT_THEME;
+    const toolbarItems = items ?? DEFAULT_TOOLBAR_ITEMS;
+
+    // Compute active state for each item
+    const enrichedItems: ToolbarItem[] = useMemo(() => {
+      return toolbarItems.map((item) => {
+        let isActive = false;
+
+        if (item.format) {
+          // Check if the format is currently active
+          const { activeStyles } = state;
+          isActive = !!activeStyles[item.format];
+        }
+
+        if (item.heading) {
+          isActive = state.activeStyles.heading === item.heading;
+        }
+
+        return {
+          ...item,
+          active: item.active ?? isActive,
+        };
+      });
+    }, [toolbarItems, state]);
+
+    // Custom render
+    if (renderToolbar) {
+      return renderToolbar({
+        items: enrichedItems,
+        state,
+        actions,
+      });
+    }
+
+    if (!visible) {
+      return null;
+    }
+
+    const toolbarStyle = [
+      resolvedTheme.toolbarStyle ?? DEFAULT_THEME.toolbarStyle,
+    ];
+
+    return (
+      <View style={toolbarStyle}>
+        <ScrollView
+          horizontal
+          showsHorizontalScrollIndicator={false}
+          keyboardShouldPersistTaps="always"
+          contentContainerStyle={styles.scrollContent}
+        >
+          {enrichedItems.map((item) => (
+            <ToolbarButton
+              key={item.id}
+              label={item.label}
+              active={!!item.active}
+              theme={resolvedTheme}
+              renderButton={item.renderButton}
+              onPress={() => {
+                if (item.onPress) {
+                  item.onPress();
+                } else if (item.format) {
+                  actions.toggleFormat(item.format);
+                } else if (item.heading) {
+                  actions.setHeading(item.heading);
+                }
+              }}
+            />
+          ))}
+        </ScrollView>
+      </View>
+    );
+  },
+);
+
+Toolbar.displayName = 'Toolbar';
+
+const styles = StyleSheet.create({
+  scrollContent: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 2,
+  },
+});

package/src/components/ToolbarButton.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { ToolbarButtonProps } from '@/types';
+/**
+ * A single toolbar button that toggles a formatting option.
+ * Supports custom rendering via the `renderButton` prop.
+ */
+export declare const ToolbarButton: React.FC<ToolbarButtonProps>;

package/src/components/ToolbarButton.tsx

@@ -0,0 +1,65 @@
+import React from 'react';
+import { TouchableOpacity, Text, StyleSheet } from 'react-native';
+import type { ToolbarButtonProps } from '@/types';
+import { DEFAULT_THEME } from '@/constants/defaultStyles';
+
+/**
+ * A single toolbar button that toggles a formatting option.
+ * Supports custom rendering via the `renderButton` prop.
+ */
+export const ToolbarButton: React.FC<ToolbarButtonProps> = React.memo(
+  ({ label, active, onPress, theme, renderButton }) => {
+    // Custom render
+    if (renderButton) {
+      return renderButton({ active, onPress, label });
+    }
+
+    const resolvedTheme = theme ?? DEFAULT_THEME;
+
+    const buttonStyle = [
+      resolvedTheme.toolbarButtonStyle ?? DEFAULT_THEME.toolbarButtonStyle,
+      active &&
+        (resolvedTheme.toolbarButtonActiveStyle ??
+          DEFAULT_THEME.toolbarButtonActiveStyle),
+    ];
+
+    const textStyle = [
+      resolvedTheme.toolbarButtonTextStyle ??
+        DEFAULT_THEME.toolbarButtonTextStyle,
+      active &&
+        (resolvedTheme.toolbarButtonActiveTextStyle ??
+          DEFAULT_THEME.toolbarButtonActiveTextStyle),
+      // Make italic button actually italic, bold button actually bold, etc.
+      label === 'I' && styles.italicLabel,
+      label === 'U' && styles.underlineLabel,
+      label === 'S' && styles.strikethroughLabel,
+    ];
+
+    return (
+      <TouchableOpacity
+        style={buttonStyle}
+        onPress={onPress}
+        activeOpacity={0.7}
+        accessibilityRole="button"
+        accessibilityLabel={`Format ${label}`}
+        accessibilityState={{ selected: active }}
+      >
+        <Text style={textStyle}>{label}</Text>
+      </TouchableOpacity>
+    );
+  },
+);
+
+ToolbarButton.displayName = 'ToolbarButton';
+
+const styles = StyleSheet.create({
+  italicLabel: {
+    fontStyle: 'italic',
+  },
+  underlineLabel: {
+    textDecorationLine: 'underline',
+  },
+  strikethroughLabel: {
+    textDecorationLine: 'line-through',
+  },
+});

package/src/constants/defaultStyles.d.ts

@@ -0,0 +1,45 @@
+import type { RichTextTheme, FormatStyle, ToolbarItem } from '@/types';
+/**
+ * Default color palette used throughout the editor.
+ */
+export declare const DEFAULT_COLORS: {
+    readonly primary: "#6366F1";
+    readonly background: "#FFFFFF";
+    readonly text: "#1F2937";
+    readonly placeholder: "#9CA3AF";
+    readonly toolbarBackground: "#F9FAFB";
+    readonly toolbarBorder: "#E5E7EB";
+    readonly cursor: "#6366F1";
+    readonly activeButtonBg: "#EEF2FF";
+    readonly codeBackground: "#F3F4F6";
+};
+/**
+ * Font size presets for heading levels.
+ */
+export declare const HEADING_FONT_SIZES: {
+    readonly h1: 32;
+    readonly h2: 24;
+    readonly h3: 20;
+    readonly none: 16;
+};
+/**
+ * Default base text style applied to all segments.
+ */
+export declare const DEFAULT_BASE_TEXT_STYLE: {
+    readonly fontSize: 16;
+    readonly lineHeight: 24;
+    readonly color: "#1F2937";
+    readonly fontFamily: undefined;
+};
+/**
+ * Empty format style — no formatting applied.
+ */
+export declare const EMPTY_FORMAT_STYLE: FormatStyle;
+/**
+ * Default theme configuration.
+ */
+export declare const DEFAULT_THEME: RichTextTheme;
+/**
+ * Default toolbar items for the built-in toolbar.
+ */
+export declare const DEFAULT_TOOLBAR_ITEMS: ToolbarItem[];

package/src/constants/defaultStyles.ts

@@ -0,0 +1,144 @@
+import type { RichTextTheme, FormatStyle, ToolbarItem } from '@/types';
+
+/**
+ * Default color palette used throughout the editor.
+ */
+export const DEFAULT_COLORS = {
+  primary: '#6366F1',
+  background: '#FFFFFF',
+  text: '#1F2937',
+  placeholder: '#9CA3AF',
+  toolbarBackground: '#F9FAFB',
+  toolbarBorder: '#E5E7EB',
+  cursor: '#6366F1',
+  activeButtonBg: '#EEF2FF',
+  codeBackground: '#F3F4F6',
+} as const;
+
+/**
+ * Font size presets for heading levels.
+ */
+export const HEADING_FONT_SIZES = {
+  h1: 32,
+  h2: 24,
+  h3: 20,
+  none: 16,
+} as const;
+
+/**
+ * Default base text style applied to all segments.
+ */
+export const DEFAULT_BASE_TEXT_STYLE = {
+  fontSize: 16,
+  lineHeight: 24,
+  color: DEFAULT_COLORS.text,
+  fontFamily: undefined, // Uses system default
+} as const;
+
+/**
+ * Empty format style — no formatting applied.
+ */
+export const EMPTY_FORMAT_STYLE: FormatStyle = {
+  bold: false,
+  italic: false,
+  underline: false,
+  strikethrough: false,
+  code: false,
+  color: undefined,
+  backgroundColor: undefined,
+  fontSize: undefined,
+  heading: undefined,
+};
+
+/**
+ * Default theme configuration.
+ */
+export const DEFAULT_THEME: RichTextTheme = {
+  containerStyle: {
+    borderWidth: 1,
+    borderColor: DEFAULT_COLORS.toolbarBorder,
+    borderRadius: 12,
+    backgroundColor: DEFAULT_COLORS.background,
+    overflow: 'hidden',
+  },
+  inputStyle: {
+    fontSize: DEFAULT_BASE_TEXT_STYLE.fontSize,
+    lineHeight: DEFAULT_BASE_TEXT_STYLE.lineHeight,
+    color: 'transparent',
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    textAlignVertical: 'top',
+  },
+  overlayContainerStyle: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+  },
+  baseTextStyle: {
+    fontSize: DEFAULT_BASE_TEXT_STYLE.fontSize,
+    lineHeight: DEFAULT_BASE_TEXT_STYLE.lineHeight,
+    color: DEFAULT_COLORS.text,
+  },
+  toolbarStyle: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+    backgroundColor: DEFAULT_COLORS.toolbarBackground,
+    borderColor: DEFAULT_COLORS.toolbarBorder,
+    gap: 2,
+  },
+  toolbarButtonStyle: {
+    paddingHorizontal: 10,
+    paddingVertical: 6,
+    borderRadius: 6,
+    minWidth: 36,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  toolbarButtonActiveStyle: {
+    backgroundColor: DEFAULT_COLORS.activeButtonBg,
+  },
+  toolbarButtonTextStyle: {
+    fontSize: 15,
+    fontWeight: '600',
+    color: DEFAULT_COLORS.text,
+  },
+  toolbarButtonActiveTextStyle: {
+    color: DEFAULT_COLORS.primary,
+  },
+  codeStyle: {
+    fontFamily: 'monospace',
+    backgroundColor: DEFAULT_COLORS.codeBackground,
+    paddingHorizontal: 4,
+    borderRadius: 4,
+    fontSize: 14,
+  },
+  colors: {
+    primary: DEFAULT_COLORS.primary,
+    background: DEFAULT_COLORS.background,
+    text: DEFAULT_COLORS.text,
+    placeholder: DEFAULT_COLORS.placeholder,
+    toolbarBackground: DEFAULT_COLORS.toolbarBackground,
+    toolbarBorder: DEFAULT_COLORS.toolbarBorder,
+    cursor: DEFAULT_COLORS.cursor,
+  },
+};
+
+/**
+ * Default toolbar items for the built-in toolbar.
+ */
+export const DEFAULT_TOOLBAR_ITEMS: ToolbarItem[] = [
+  { id: 'bold', label: 'B', format: 'bold' },
+  { id: 'italic', label: 'I', format: 'italic' },
+  { id: 'underline', label: 'U', format: 'underline' },
+  { id: 'strikethrough', label: 'S', format: 'strikethrough' },
+  { id: 'code', label: '<>', format: 'code' },
+  { id: 'h1', label: 'H1', heading: 'h1' },
+  { id: 'h2', label: 'H2', heading: 'h2' },
+  { id: 'h3', label: 'H3', heading: 'h3' },
+];

package/src/context/RichTextContext.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { UseRichTextReturn } from '@/types';
+import { type UseRichTextOptions } from '@/hooks/useRichText';
+export interface RichTextProviderProps extends UseRichTextOptions {
+    children: React.ReactNode;
+}
+/**
+ * RichTextProvider wraps children with rich text state via React Context.
+ *
+ * Use this when you need to access the rich text state/actions from
+ * deeply nested components (e.g., a custom toolbar in a different part
+ * of the component tree).
+ *
+ * @example
+ * ```tsx
+ * <RichTextProvider onChangeSegments={handleChange}>
+ *   <MyCustomToolbar />
+ *   <RichTextInput showToolbar={false} />
+ * </RichTextProvider>
+ * ```
+ */
+export declare const RichTextProvider: React.FC<RichTextProviderProps>;
+/**
+ * Hook to access the RichText state and actions from context.
+ *
+ * Must be used within a `<RichTextProvider>`.
+ *
+ * @throws If used outside of a RichTextProvider
+ */
+export declare function useRichTextContext(): UseRichTextReturn;

package/src/context/RichTextContext.tsx

@@ -0,0 +1,63 @@
+import React, { createContext, useContext } from 'react';
+import type { RichTextState, RichTextActions, UseRichTextReturn } from '@/types';
+import { useRichText, type UseRichTextOptions } from '@/hooks/useRichText';
+
+// ─── Context ─────────────────────────────────────────────────────────────────
+
+const RichTextContext = createContext<UseRichTextReturn | null>(null);
+
+// ─── Provider ────────────────────────────────────────────────────────────────
+
+export interface RichTextProviderProps extends UseRichTextOptions {
+  children: React.ReactNode;
+}
+
+/**
+ * RichTextProvider wraps children with rich text state via React Context.
+ *
+ * Use this when you need to access the rich text state/actions from
+ * deeply nested components (e.g., a custom toolbar in a different part
+ * of the component tree).
+ *
+ * @example
+ * ```tsx
+ * <RichTextProvider onChangeSegments={handleChange}>
+ *   <MyCustomToolbar />
+ *   <RichTextInput showToolbar={false} />
+ * </RichTextProvider>
+ * ```
+ */
+export const RichTextProvider: React.FC<RichTextProviderProps> = ({
+  children,
+  ...options
+}) => {
+  const richText = useRichText(options);
+
+  return (
+    <RichTextContext.Provider value={richText}>
+      {children}
+    </RichTextContext.Provider>
+  );
+};
+
+RichTextProvider.displayName = 'RichTextProvider';
+
+// ─── Consumer Hook ───────────────────────────────────────────────────────────
+
+/**
+ * Hook to access the RichText state and actions from context.
+ *
+ * Must be used within a `<RichTextProvider>`.
+ *
+ * @throws If used outside of a RichTextProvider
+ */
+export function useRichTextContext(): UseRichTextReturn {
+  const context = useContext(RichTextContext);
+  if (!context) {
+    throw new Error(
+      'useRichTextContext must be used within a <RichTextProvider>. ' +
+        'Wrap your component tree with <RichTextProvider> to use this hook.',
+    );
+  }
+  return context;
+}

package/src/hooks/useFormatting.d.ts

@@ -0,0 +1,25 @@
+import type { StyledSegment, FormatType, FormatStyle, HeadingLevel, SelectionRange } from '@/types';
+interface UseFormattingOptions {
+    segments: StyledSegment[];
+    selection: SelectionRange;
+    activeStyles: FormatStyle;
+    onSegmentsChange: (segments: StyledSegment[]) => void;
+    onActiveStylesChange: (styles: FormatStyle) => void;
+}
+/**
+ * Hook that provides formatting commands for the rich text editor.
+ *
+ * Handles both selection-based formatting (when text is selected)
+ * and active-style updates (when no text is selected — affects next typed text).
+ */
+export declare function useFormatting({ segments, selection, activeStyles, onSegmentsChange, onActiveStylesChange, }: UseFormattingOptions): {
+    toggleFormat: (format: FormatType) => void;
+    setStyleProperty: <K extends keyof FormatStyle>(key: K, value: FormatStyle[K]) => void;
+    setHeading: (level: HeadingLevel) => void;
+    setColor: (color: string) => void;
+    setBackgroundColor: (color: string) => void;
+    setFontSize: (size: number) => void;
+    isFormatActive: (format: FormatType) => boolean;
+    currentSelectionStyle: () => FormatStyle;
+};
+export {};