@mihcm/ui 0.14.1

package/src/RichTextEditor.tsx

@@ -0,0 +1,513 @@
+'use client';
+
+/**
+ * RichTextEditor (web only — React DOM).
+ *
+ * A Lexical-powered rich text editor styled to match the MiHCM design system.
+ * Four variants control which toolbar features are shown:
+ *
+ *   minimal  — Bold, Italic only
+ *   default  — Bold, Italic, Underline, Strikethrough + Bullet/Numbered lists
+ *   semi     — default + Headings (H1–H3) + Undo/Redo + Code + Link + Indent/Outdent + Markdown shortcuts + Tab indentation
+ *   full     — semi + Text alignment (L/C/R/Justify) + Superscript/Subscript + Check list + Table + Horizontal rule + Block quote + Clear formatting
+ *
+ * Web only — native apps should use a platform-specific editor.
+ *
+ * Wiki: docs/components/RichTextEditor.md
+ */
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { cn } from './internal/cn.js';
+
+import { LexicalComposer } from '@lexical/react/LexicalComposer.js';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin.js';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable.js';
+import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin.js';
+import { ListPlugin } from '@lexical/react/LexicalListPlugin.js';
+import { CheckListPlugin } from '@lexical/react/LexicalCheckListPlugin.js';
+import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin.js';
+import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin.js';
+import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin.js';
+import { TabIndentationPlugin } from '@lexical/react/LexicalTabIndentationPlugin.js';
+import { TablePlugin } from '@lexical/react/LexicalTablePlugin.js';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext.js';
+import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary.js';
+import {
+  $isRangeSelection,
+  $getSelection,
+  $createParagraphNode,
+  FORMAT_TEXT_COMMAND,
+  FORMAT_ELEMENT_COMMAND,
+  INDENT_CONTENT_COMMAND,
+  OUTDENT_CONTENT_COMMAND,
+  UNDO_COMMAND,
+  REDO_COMMAND,
+  type EditorState,
+  type LexicalEditor,
+  type Klass,
+  type LexicalNode,
+} from 'lexical';
+import { HeadingNode, $createHeadingNode, QuoteNode, $createQuoteNode, type HeadingTagType } from '@lexical/rich-text';
+import { ListItemNode, ListNode, INSERT_ORDERED_LIST_COMMAND, INSERT_UNORDERED_LIST_COMMAND } from '@lexical/list';
+import { INSERT_CHECK_LIST_COMMAND } from '@lexical/list';
+import { LinkNode, $isLinkNode, TOGGLE_LINK_COMMAND } from '@lexical/link';
+import { CodeNode } from '@lexical/code';
+import { $setBlocksType } from '@lexical/selection';
+import { HorizontalRuleNode, INSERT_HORIZONTAL_RULE_COMMAND } from '@lexical/react/LexicalHorizontalRuleNode.js';
+import { HorizontalRulePlugin } from '@lexical/react/LexicalHorizontalRulePlugin.js';
+import { TableNode, TableCellNode, TableRowNode, $createTableNodeWithDimensions } from '@lexical/table';
+import { TRANSFORMERS, ELEMENT_TRANSFORMERS, TEXT_FORMAT_TRANSFORMERS, TEXT_MATCH_TRANSFORMERS } from '@lexical/markdown';
+
+/* ── Variant config ───────────────────────────────────────────────── */
+
+export type RichTextEditorVariant = 'minimal' | 'default' | 'semi' | 'full';
+
+/* ── Theme (maps Lexical class names to Tailwind) ─────────────────── */
+
+const editorTheme = {
+  paragraph: 'mb-2 last:mb-0',
+  heading: {
+    h1: 'text-2xl font-bold mb-3 text-foreground',
+    h2: 'text-xl font-semibold mb-2 text-foreground',
+    h3: 'text-lg font-medium mb-2 text-foreground',
+  },
+  text: {
+    bold: 'font-bold',
+    italic: 'italic',
+    underline: 'underline',
+    strikethrough: 'line-through',
+    underlineStrikethrough: 'underline line-through',
+    code: 'font-mono text-sm bg-muted px-1.5 py-0.5 rounded',
+    subscript: 'align-sub',
+    superscript: 'align-super',
+  },
+  list: {
+    ul: 'list-disc ml-6 mb-2',
+    ol: 'list-decimal ml-6 mb-2',
+    listitem: 'mb-0.5',
+    listitemChecked: 'line-through opacity-60 relative ml-2 list-none outline-none',
+    listitemUnchecked: 'relative ml-2 list-none outline-none',
+    nested: { listitem: 'list-none' },
+    checklist: 'list-none ml-0',
+  },
+  link: 'text-primary underline cursor-pointer hover:text-primary/80',
+  quote: 'border-l-4 border-primary-200 dark:border-primary-800 pl-4 italic text-muted-foreground mb-2',
+  code: 'font-mono text-sm bg-muted p-3 rounded-md mb-2 block overflow-x-auto',
+  horizontalRule: 'my-4 border-t border-border',
+  table: 'border-collapse border border-border w-full mb-2',
+  tableCell: 'border border-border px-2 py-1.5 text-sm min-w-[75px]',
+  tableCellHeader: 'border border-border px-2 py-1.5 text-sm font-semibold bg-muted/50',
+};
+
+/* ── Toolbar primitives ───────────────────────────────────────────── */
+
+function TbIcon({ d, className }: { d: string; className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('size-3.5', className)}>
+      <path d={d} />
+    </svg>
+  );
+}
+
+function TbMultiIcon({ paths, className }: { paths: string[]; className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('size-3.5', className)}>
+      {paths.map((d, i) => <path key={i} d={d} />)}
+    </svg>
+  );
+}
+
+function TbBtn({ active, onClick, title, children }: { active?: boolean; onClick: () => void; title: string; children: ReactNode }) {
+  return (
+    <button type="button" onClick={onClick} title={title} aria-label={title} aria-pressed={active} className={cn(
+      'flex items-center justify-center size-7 rounded transition-colors duration-150 cursor-pointer',
+      'hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+      active && 'border border-primary bg-primary text-primary-foreground shadow-mi-card',
+    )}>
+      {children}
+    </button>
+  );
+}
+
+function TbSep() {
+  return <span className="w-px h-4 bg-border mx-0.5" aria-hidden />;
+}
+
+/* ── Toolbar plugin ───────────────────────────────────────────────── */
+
+function ToolbarPlugin({ variant }: { variant: RichTextEditorVariant }) {
+  const [editor] = useLexicalComposerContext();
+  const [isBold, setIsBold] = useState(false);
+  const [isItalic, setIsItalic] = useState(false);
+  const [isUnderline, setIsUnderline] = useState(false);
+  const [isStrikethrough, setIsStrikethrough] = useState(false);
+  const [isCode, setIsCode] = useState(false);
+  const [isSuperscript, setIsSuperscript] = useState(false);
+  const [isSubscript, setIsSubscript] = useState(false);
+  const [isLink, setIsLink] = useState(false);
+
+  const updateToolbar = useCallback(() => {
+    const selection = $getSelection();
+    if ($isRangeSelection(selection)) {
+      setIsBold(selection.hasFormat('bold'));
+      setIsItalic(selection.hasFormat('italic'));
+      setIsUnderline(selection.hasFormat('underline'));
+      setIsStrikethrough(selection.hasFormat('strikethrough'));
+      setIsCode(selection.hasFormat('code'));
+      setIsSuperscript(selection.hasFormat('superscript'));
+      setIsSubscript(selection.hasFormat('subscript'));
+      const node = selection.anchor.getNode();
+      const parent = node.getParent();
+      setIsLink($isLinkNode(parent) || $isLinkNode(node));
+    }
+  }, []);
+
+  useEffect(() => {
+    return editor.registerUpdateListener(({ editorState }) => {
+      editorState.read(() => updateToolbar());
+    });
+  }, [editor, updateToolbar]);
+
+  const formatHeading = (tag: HeadingTagType) => {
+    editor.update(() => {
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) $setBlocksType(selection, () => $createHeadingNode(tag));
+    });
+  };
+
+  const formatParagraph = () => {
+    editor.update(() => {
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) $setBlocksType(selection, () => $createParagraphNode());
+    });
+  };
+
+  const formatBlockQuote = () => {
+    editor.update(() => {
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) $setBlocksType(selection, () => $createQuoteNode());
+    });
+  };
+
+  const insertLink = () => {
+    if (isLink) {
+      editor.dispatchCommand(TOGGLE_LINK_COMMAND, null);
+    } else {
+      const url = prompt('Enter URL:');
+      if (url) editor.dispatchCommand(TOGGLE_LINK_COMMAND, url);
+    }
+  };
+
+  const insertTable = () => {
+    editor.update(() => {
+      const table = $createTableNodeWithDimensions(3, 3, false);
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) {
+        const anchor = selection.anchor.getNode();
+        const parent = anchor.getTopLevelElementOrThrow();
+        parent.insertAfter(table);
+      }
+    });
+  };
+
+  const clearFormatting = () => {
+    editor.update(() => {
+      const selection = $getSelection();
+      if ($isRangeSelection(selection)) {
+        for (const format of ['bold', 'italic', 'underline', 'strikethrough', 'code', 'superscript', 'subscript'] as const) {
+          if (selection.hasFormat(format)) {
+            editor.dispatchCommand(FORMAT_TEXT_COMMAND, format);
+          }
+        }
+      }
+    });
+  };
+
+  const showHistory = variant === 'semi' || variant === 'full';
+  const showHeadings = variant === 'semi' || variant === 'full';
+  const showUnderlineStrike = variant !== 'minimal';
+  const showLists = variant !== 'minimal';
+  const showCode = variant === 'semi' || variant === 'full';
+  const showLink = variant === 'semi' || variant === 'full';
+  const showIndent = variant === 'semi' || variant === 'full';
+  const showAlignment = variant === 'full';
+  const showSuperSub = variant === 'full';
+  const showCheckList = variant === 'full';
+  const showTable = variant === 'full';
+  const showExtras = variant === 'full';
+
+  return (
+    <div className="flex items-center gap-0.5 px-2 py-1.5 border-b border-border bg-muted/50 rounded-t-lg flex-wrap">
+      {/* Undo / Redo */}
+      {showHistory && (
+        <>
+          <TbBtn title="Undo (Ctrl+Z)" onClick={() => editor.dispatchCommand(UNDO_COMMAND, undefined)}>
+            <TbIcon d="M3 7v6h6M3 13a9 9 0 1 0 3-7.7" />
+          </TbBtn>
+          <TbBtn title="Redo (Ctrl+Shift+Z)" onClick={() => editor.dispatchCommand(REDO_COMMAND, undefined)}>
+            <TbIcon d="M21 7v6h-6M21 13a9 9 0 1 1-3-7.7" />
+          </TbBtn>
+          <TbSep />
+        </>
+      )}
+
+      {/* Headings */}
+      {showHeadings && (
+        <>
+          <TbBtn title="Heading 1" onClick={() => formatHeading('h1')}>
+            <span className="text-xs font-bold leading-none">H1</span>
+          </TbBtn>
+          <TbBtn title="Heading 2" onClick={() => formatHeading('h2')}>
+            <span className="text-xs font-bold leading-none">H2</span>
+          </TbBtn>
+          <TbBtn title="Heading 3" onClick={() => formatHeading('h3')}>
+            <span className="text-xs font-bold leading-none">H3</span>
+          </TbBtn>
+          <TbBtn title="Paragraph" onClick={formatParagraph}>
+            <span className="text-xs font-medium leading-none">¶</span>
+          </TbBtn>
+          <TbSep />
+        </>
+      )}
+
+      {/* Text formatting */}
+      <TbBtn title="Bold (Ctrl+B)" active={isBold} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold')}>
+        <span className="text-xs font-bold">B</span>
+      </TbBtn>
+      <TbBtn title="Italic (Ctrl+I)" active={isItalic} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic')}>
+        <span className="text-xs italic">I</span>
+      </TbBtn>
+      {showUnderlineStrike && (
+        <>
+          <TbBtn title="Underline (Ctrl+U)" active={isUnderline} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'underline')}>
+            <span className="text-xs underline">U</span>
+          </TbBtn>
+          <TbBtn title="Strikethrough" active={isStrikethrough} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'strikethrough')}>
+            <span className="text-xs line-through">S</span>
+          </TbBtn>
+        </>
+      )}
+
+      {/* Code */}
+      {showCode && (
+        <TbBtn title="Inline code" active={isCode} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'code')}>
+          <TbMultiIcon paths={['M16 18l6-6-6-6', 'M8 6l-6 6 6 6']} />
+        </TbBtn>
+      )}
+
+      {/* Super/sub */}
+      {showSuperSub && (
+        <>
+          <TbBtn title="Superscript" active={isSuperscript} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'superscript')}>
+            <span className="text-xs leading-none">X<sup>2</sup></span>
+          </TbBtn>
+          <TbBtn title="Subscript" active={isSubscript} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'subscript')}>
+            <span className="text-xs leading-none">X<sub>2</sub></span>
+          </TbBtn>
+        </>
+      )}
+
+      {(showLists || showLink) && <TbSep />}
+
+      {/* Lists */}
+      {showLists && (
+        <>
+          <TbBtn title="Bullet list" onClick={() => editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND, undefined)}>
+            <TbIcon d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" />
+          </TbBtn>
+          <TbBtn title="Numbered list" onClick={() => editor.dispatchCommand(INSERT_ORDERED_LIST_COMMAND, undefined)}>
+            <TbIcon d="M10 6h11M10 12h11M10 18h11M3 5l2 1V4M3 11h2l-1 2h2M3 17l2 1-2 1" />
+          </TbBtn>
+        </>
+      )}
+
+      {/* Check list */}
+      {showCheckList && (
+        <TbBtn title="Check list" onClick={() => editor.dispatchCommand(INSERT_CHECK_LIST_COMMAND, undefined)}>
+          <TbMultiIcon paths={['M9 11l3 3L22 4', 'M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11']} />
+        </TbBtn>
+      )}
+
+      {/* Link */}
+      {showLink && (
+        <TbBtn title="Insert link" active={isLink} onClick={insertLink}>
+          <TbMultiIcon paths={['M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71', 'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71']} />
+        </TbBtn>
+      )}
+
+      {/* Indent / Outdent */}
+      {showIndent && (
+        <>
+          <TbSep />
+          <TbBtn title="Indent" onClick={() => editor.dispatchCommand(INDENT_CONTENT_COMMAND, undefined)}>
+            <TbMultiIcon paths={['M3 8l4 4-4 4', 'M11 6h10', 'M11 12h10', 'M11 18h10']} />
+          </TbBtn>
+          <TbBtn title="Outdent" onClick={() => editor.dispatchCommand(OUTDENT_CONTENT_COMMAND, undefined)}>
+            <TbMultiIcon paths={['M7 8l-4 4 4 4', 'M11 6h10', 'M11 12h10', 'M11 18h10']} />
+          </TbBtn>
+        </>
+      )}
+
+      {/* Alignment */}
+      {showAlignment && (
+        <>
+          <TbSep />
+          <TbBtn title="Align left" onClick={() => editor.dispatchCommand(FORMAT_ELEMENT_COMMAND, 'left')}>
+            <TbIcon d="M17 10H3M21 6H3M21 14H3M17 18H3" />
+          </TbBtn>
+          <TbBtn title="Align center" onClick={() => editor.dispatchCommand(FORMAT_ELEMENT_COMMAND, 'center')}>
+            <TbIcon d="M18 10H6M21 6H3M21 14H3M18 18H6" />
+          </TbBtn>
+          <TbBtn title="Align right" onClick={() => editor.dispatchCommand(FORMAT_ELEMENT_COMMAND, 'right')}>
+            <TbIcon d="M21 10H7M21 6H3M21 14H3M21 18H7" />
+          </TbBtn>
+          <TbBtn title="Justify" onClick={() => editor.dispatchCommand(FORMAT_ELEMENT_COMMAND, 'justify')}>
+            <TbIcon d="M3 6h18M3 12h18M3 18h18" />
+          </TbBtn>
+        </>
+      )}
+
+      {/* Table + Extras (full only) */}
+      {showExtras && (
+        <>
+          <TbSep />
+          <TbBtn title="Insert table (3×3)" onClick={insertTable}>
+            <TbMultiIcon paths={['M3 3h18v18H3V3z', 'M3 9h18', 'M3 15h18', 'M9 3v18', 'M15 3v18']} />
+          </TbBtn>
+          <TbBtn title="Block quote" onClick={formatBlockQuote}>
+            <TbMultiIcon paths={['M3 21c3 0 7-1 7-8V5c0-1.25-.756-2.017-2-2H4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2 1 0 1 0 1 1v1c0 1-1 2-2 2s-1 .008-1 1.031V20c0 1 0 1 1 1', 'M15 21c3 0 7-1 7-8V5c0-1.25-.757-2.017-2-2h-4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2h.75c0 2.25.25 4-2.75 4v3c0 1 0 1 1 1']} />
+          </TbBtn>
+          <TbBtn title="Horizontal rule" onClick={() => editor.dispatchCommand(INSERT_HORIZONTAL_RULE_COMMAND, undefined)}>
+            <TbIcon d="M3 12h18" />
+          </TbBtn>
+          <TbBtn title="Clear formatting" onClick={clearFormatting}>
+            <TbMultiIcon paths={['M4 7h7l-2 9h7', 'M16 4l4 4-4 4', 'M7 20l5-5']} />
+          </TbBtn>
+        </>
+      )}
+    </div>
+  );
+}
+
+/* ── Placeholder ──────────────────────────────────────────────────── */
+
+function Placeholder({ text }: { text: string }) {
+  return (
+    <div className="absolute top-0 left-0 pointer-events-none text-muted-foreground text-sm px-4 pt-3">
+      {text}
+    </div>
+  );
+}
+
+/* ── RichTextEditor ───────────────────────────────────────────────── */
+
+export interface RichTextEditorProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /**
+   * Controls which toolbar features are shown.
+   * - `minimal` — Bold, Italic
+   * - `default` — Bold, Italic, Underline, Strikethrough, Lists
+   * - `semi` — default + Headings, Undo/Redo, Code, Link, Indent/Outdent, Markdown shortcuts, Tab indentation
+   * - `full` — semi + Alignment (L/C/R/Justify), Super/Subscript, Check list, Table, Block quote, HR, Clear formatting
+   */
+  variant?: RichTextEditorVariant;
+  /** Placeholder text for the editor. */
+  placeholder?: string;
+  /** Called with the serialised editor state on every change. */
+  onChange?: (editorState: EditorState, editor: LexicalEditor) => void;
+  /** Make the editor read-only. */
+  readOnly?: boolean;
+  /** Minimum height for the editor area. Default `'150px'`. */
+  minHeight?: string;
+}
+
+export const RichTextEditor = forwardRef<HTMLDivElement, RichTextEditorProps>(
+  function RichTextEditor(
+    {
+      className,
+      variant = 'default',
+      placeholder = 'Start typing...',
+      onChange,
+      readOnly = false,
+      minHeight = '150px',
+      ...props
+    },
+    ref,
+  ) {
+    const nodes: Klass<LexicalNode>[] = [ListNode, ListItemNode];
+    if (variant === 'semi' || variant === 'full') {
+      nodes.push(HeadingNode, LinkNode, CodeNode);
+    }
+    if (variant === 'full') {
+      nodes.push(QuoteNode, HorizontalRuleNode, TableNode, TableCellNode, TableRowNode);
+    }
+
+    const initialConfig = {
+      namespace: 'MiHCMRichTextEditor',
+      theme: editorTheme,
+      nodes,
+      editable: !readOnly,
+      onError: (error: Error) => {
+        console.error('[RichTextEditor]', error);
+      },
+    };
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'rounded-lg border border-border bg-card text-foreground',
+          'focus-within:ring-2 focus-within:ring-ring focus-within:border-transparent',
+          'transition-shadow',
+          readOnly && 'opacity-70',
+          className,
+        )}
+        {...props}
+      >
+        <LexicalComposer initialConfig={initialConfig}>
+          {!readOnly && <ToolbarPlugin variant={variant} />}
+          <div className="relative" style={{ minHeight }}>
+            <RichTextPlugin
+              contentEditable={
+                <ContentEditable
+                  className="outline-none px-4 py-3 text-sm leading-relaxed min-h-full"
+                  style={{ minHeight }}
+                />
+              }
+              placeholder={<Placeholder text={placeholder} />}
+              ErrorBoundary={LexicalErrorBoundary}
+            />
+          </div>
+          <HistoryPlugin />
+          <ListPlugin />
+          {variant === 'full' && <CheckListPlugin />}
+          {(variant === 'semi' || variant === 'full') && <LinkPlugin />}
+          {variant === 'full' && <MarkdownShortcutPlugin transformers={TRANSFORMERS} />}
+          {variant === 'semi' && (
+            <MarkdownShortcutPlugin
+              transformers={[
+                ...ELEMENT_TRANSFORMERS.filter((t) => t.dependencies.every(
+                  (dep) => [HeadingNode, ListNode, ListItemNode, LinkNode, CodeNode].includes(dep as never),
+                )),
+                ...TEXT_FORMAT_TRANSFORMERS,
+                ...TEXT_MATCH_TRANSFORMERS,
+              ]}
+            />
+          )}
+          {(variant === 'semi' || variant === 'full') && <TabIndentationPlugin />}
+          {variant === 'full' && <HorizontalRulePlugin />}
+          {variant === 'full' && <TablePlugin />}
+          {onChange && (
+            <OnChangePlugin onChange={(editorState, editor) => onChange(editorState, editor)} />
+          )}
+        </LexicalComposer>
+      </div>
+    );
+  },
+);

package/src/ScrollArea.native.tsx

@@ -0,0 +1,36 @@
+/**
+ * ScrollArea (React Native variant).
+ *
+ * Thin wrapper around ScrollView for API parity with the web ScrollArea.
+ * On native the OS handles scrollbar styling, so this is essentially
+ * a typed re-export.
+ *
+ * Wiki: docs/components/ScrollArea.md
+ */
+import { ScrollView, type ScrollViewProps } from 'react-native';
+import { cn } from './internal/cn.js';
+
+export interface ScrollAreaProps extends ScrollViewProps {
+  className?: string;
+}
+
+export function ScrollArea({ className, children, ...props }: ScrollAreaProps) {
+  return (
+    <ScrollView
+      showsVerticalScrollIndicator
+      showsHorizontalScrollIndicator={false}
+      className={cn(className)}
+      {...props}
+    >
+      {children}
+    </ScrollView>
+  );
+}
+
+export interface ScrollBarProps {
+  className?: string;
+}
+
+export function ScrollBar(_props: ScrollBarProps) {
+  return null;
+}

package/src/ScrollArea.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+/**
+ * ScrollArea (web variant — React DOM).
+ *
+ * Custom-styled scrollable container powered by Radix ScrollArea.
+ * Thin translucent scrollbars that appear on hover/scroll and fade out.
+ *
+ *   <ScrollArea className="h-72">
+ *     <p>Long content…</p>
+ *   </ScrollArea>
+ *
+ * Wiki: docs/components/ScrollArea.md
+ */
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from 'react';
+import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
+import { cn } from './internal/cn.js';
+
+/* ── Root ───────────────────────────────────────────────────────────── */
+
+export const ScrollArea = forwardRef<
+  ElementRef<typeof ScrollAreaPrimitive.Root>,
+  ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(function ScrollArea({ className, children, ...props }, ref) {
+  return (
+    <ScrollAreaPrimitive.Root
+      ref={ref}
+      className={cn('relative overflow-hidden', className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]">
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollBar orientation="horizontal" />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+});
+
+/* ── ScrollBar ──────────────────────────────────────────────────────── */
+
+export const ScrollBar = forwardRef<
+  ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+  ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(function ScrollBar({ className, orientation = 'vertical', ...props }, ref) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      ref={ref}
+      orientation={orientation}
+      className={cn(
+        'flex touch-none select-none transition-colors duration-150',
+        orientation === 'vertical' && 'h-full w-2.5 border-l border-l-transparent p-px',
+        orientation === 'horizontal' && 'h-2.5 flex-col border-t border-t-transparent p-px',
+        className,
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-border" />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  );
+});