|
| 1 | +import React, { cloneElement, isValidElement, memo } from 'react' |
| 2 | +import type { ReactElement, ReactNode } from 'react' |
| 3 | + |
| 4 | +/** |
| 5 | + * Makes all text content within a React node tree non-selectable. |
| 6 | + * |
| 7 | + * This is important for interactive elements (buttons, clickable boxes) because |
| 8 | + * text inside them should not be selectable when the user clicks - it creates |
| 9 | + * a poor UX where text gets highlighted during interactions. |
| 10 | + * |
| 11 | + * Handles both `<text>` and `<span>` OpenTUI elements by adding `selectable={false}`. |
| 12 | + * |
| 13 | + * @example |
| 14 | + * ```tsx |
| 15 | + * // Use this when building custom interactive components |
| 16 | + * const processedChildren = makeTextUnselectable(children) |
| 17 | + * return <box onMouseDown={handleClick}>{processedChildren}</box> |
| 18 | + * ``` |
| 19 | + */ |
| 20 | +export function makeTextUnselectable(node: ReactNode): ReactNode { |
| 21 | + if (node === null || node === undefined || typeof node === 'boolean') return node |
| 22 | + if (typeof node === 'string' || typeof node === 'number') return node |
| 23 | + |
| 24 | + if (Array.isArray(node)) { |
| 25 | + return node.map((child, idx) => <React.Fragment key={idx}>{makeTextUnselectable(child)}</React.Fragment>) |
| 26 | + } |
| 27 | + |
| 28 | + if (!isValidElement(node)) return node |
| 29 | + |
| 30 | + const el = node as ReactElement |
| 31 | + const type = el.type |
| 32 | + |
| 33 | + // Ensure text and span nodes are not selectable |
| 34 | + if (typeof type === 'string' && (type === 'text' || type === 'span')) { |
| 35 | + const nextProps = { ...el.props, selectable: false } |
| 36 | + const nextChildren = el.props?.children ? makeTextUnselectable(el.props.children) : el.props?.children |
| 37 | + return cloneElement(el, nextProps, nextChildren) |
| 38 | + } |
| 39 | + |
| 40 | + // Recurse into other host elements and components' children |
| 41 | + const nextChildren = el.props?.children ? makeTextUnselectable(el.props.children) : el.props?.children |
| 42 | + return cloneElement(el, el.props, nextChildren) |
| 43 | +} |
| 44 | + |
| 45 | +interface ClickableProps { |
| 46 | + /** Element type to render: 'box' (default) or 'text' */ |
| 47 | + as?: 'box' | 'text' |
| 48 | + onMouseDown?: (e?: unknown) => void |
| 49 | + onMouseUp?: (e?: unknown) => void |
| 50 | + onMouseOver?: () => void |
| 51 | + onMouseOut?: () => void |
| 52 | + style?: Record<string, unknown> |
| 53 | + children?: ReactNode |
| 54 | + // pass-through for host element props |
| 55 | + [key: string]: unknown |
| 56 | +} |
| 57 | + |
| 58 | +/** |
| 59 | + * A wrapper component for any interactive/clickable area in the CLI. |
| 60 | + * |
| 61 | + * **Why use this instead of raw `<box>` or `<text>` with mouse handlers?** |
| 62 | + * |
| 63 | + * This component automatically makes all text content non-selectable, which is |
| 64 | + * essential for good UX - users shouldn't accidentally select text when clicking |
| 65 | + * interactive elements. |
| 66 | + * |
| 67 | + * **The `as` prop:** |
| 68 | + * - `as="box"` (default) - Renders a `<box>` element for layout containers |
| 69 | + * - `as="text"` - Renders a `<text>` element for inline clickable text |
| 70 | + * |
| 71 | + * **When to use `Clickable` vs `Button`:** |
| 72 | + * - Use `Button` for actual button-like interactions (has click-on-mouseup logic) |
| 73 | + * - Use `Clickable` for simpler interactive areas where you need direct mouse event control |
| 74 | + * |
| 75 | + * @example |
| 76 | + * ```tsx |
| 77 | + * // Default: renders <box> |
| 78 | + * <Clickable onMouseDown={handleClick}> |
| 79 | + * <text>Click me</text> |
| 80 | + * </Clickable> |
| 81 | + * |
| 82 | + * // For inline text: renders <text> |
| 83 | + * <Clickable as="text" onMouseDown={handleCopy}> |
| 84 | + * <span>⎘ copy</span> |
| 85 | + * </Clickable> |
| 86 | + * ``` |
| 87 | + */ |
| 88 | +export const Clickable = memo(function Clickable({ |
| 89 | + as = 'box', |
| 90 | + onMouseDown, |
| 91 | + onMouseUp, |
| 92 | + onMouseOver, |
| 93 | + onMouseOut, |
| 94 | + style, |
| 95 | + children, |
| 96 | + ...rest |
| 97 | +}: ClickableProps) { |
| 98 | + const sharedProps = { |
| 99 | + ...rest, |
| 100 | + style, |
| 101 | + onMouseDown, |
| 102 | + onMouseUp, |
| 103 | + onMouseOver, |
| 104 | + onMouseOut, |
| 105 | + } |
| 106 | + |
| 107 | + if (as === 'text') { |
| 108 | + return ( |
| 109 | + <text {...sharedProps} selectable={false}> |
| 110 | + {children} |
| 111 | + </text> |
| 112 | + ) |
| 113 | + } |
| 114 | + |
| 115 | + // Default: box with processed children |
| 116 | + const processedChildren = makeTextUnselectable(children) |
| 117 | + return <box {...sharedProps}>{processedChildren}</box> |
| 118 | +}) |
0 commit comments