@mihcm/ui 0.14.1 → 0.15.0

package/src/RichTextEditor.tsx

@@ -6,23 +6,20 @@
  * 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
+ *   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.
+ * Implementation is split across `./RichTextEditor/*` per CLAUDE.md §6 —
+ * theme/variant config, toolbar icons, and toolbar plugin live separately.
  *
  * Wiki: docs/components/RichTextEditor.md
  */
-import {
-  forwardRef,
-  useCallback,
-  useEffect,
-  useState,
-  type HTMLAttributes,
-  type ReactNode,
-} from 'react';
+import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from './internal/cn.js';
 
 import { LexicalComposer } from '@lexical/react/LexicalComposer.js';
@@ -36,366 +33,21 @@ 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 type { EditorState, LexicalEditor, Klass, LexicalNode } from 'lexical';
+import { HeadingNode, QuoteNode } from '@lexical/rich-text';
+import { ListItemNode, ListNode } from '@lexical/list';
+import { LinkNode } 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 { HorizontalRuleNode } from '@lexical/react/LexicalHorizontalRuleNode.js';
 import { HorizontalRulePlugin } from '@lexical/react/LexicalHorizontalRulePlugin.js';
-import { TableNode, TableCellNode, TableRowNode, $createTableNodeWithDimensions } from '@lexical/table';
+import { TableNode, TableCellNode, TableRowNode } from '@lexical/table';
 import { TRANSFORMERS, ELEMENT_TRANSFORMERS, TEXT_FORMAT_TRANSFORMERS, TEXT_MATCH_TRANSFORMERS } from '@lexical/markdown';
 
-/* ── Variant config ───────────────────────────────────────────────── */
+import { editorTheme, type RichTextEditorVariant } from './RichTextEditor/theme.js';
+import { ToolbarPlugin } from './RichTextEditor/toolbar.js';
 
-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 ──────────────────────────────────────────────────── */
+export type { RichTextEditorVariant };
 
 function Placeholder({ text }: { text: string }) {
   return (
@@ -405,16 +57,16 @@ function Placeholder({ text }: { text: string }) {
   );
 }
 
-/* ── 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
+   * - `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. */

package/src/Select/content.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+/**
+ * SelectContent — floating listbox panel with outside-click dismissal,
+ * arrow-key navigation, and focus management.
+ */
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  type HTMLAttributes,
+  type MutableRefObject,
+} from 'react';
+import { cn } from '../internal/cn.js';
+import { useSelectContext } from './context.js';
+
+export interface SelectContentProps extends HTMLAttributes<HTMLDivElement> {}
+
+export const SelectContent = forwardRef<HTMLDivElement, SelectContentProps>(
+  function SelectContent({ className, children, ...props }, ref) {
+    const ctx = useSelectContext();
+    const contentRef = useRef<HTMLDivElement | null>(null);
+    const focusedIndexRef = useRef(-1);
+
+    useEffect(() => {
+      if (!ctx.open) return;
+      function handleClickOutside(e: MouseEvent) {
+        const target = e.target as Node;
+        if (
+          contentRef.current &&
+          !contentRef.current.contains(target) &&
+          ctx.triggerRef.current &&
+          !ctx.triggerRef.current.contains(target)
+        ) {
+          ctx.setOpen(false);
+        }
+      }
+      document.addEventListener('mousedown', handleClickOutside);
+      return () => document.removeEventListener('mousedown', handleClickOutside);
+    }, [ctx]);
+
+    useEffect(() => {
+      if (!ctx.open) return;
+      function handleKeyDown(e: KeyboardEvent) {
+        const options = contentRef.current?.querySelectorAll<HTMLElement>('[role="option"]');
+        if (!options?.length) return;
+
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          ctx.setOpen(false);
+          ctx.triggerRef.current?.focus();
+          return;
+        }
+
+        if (e.key === 'ArrowDown') {
+          e.preventDefault();
+          focusedIndexRef.current = Math.min(focusedIndexRef.current + 1, options.length - 1);
+          options[focusedIndexRef.current]?.focus();
+        } else if (e.key === 'ArrowUp') {
+          e.preventDefault();
+          focusedIndexRef.current = Math.max(focusedIndexRef.current - 1, 0);
+          options[focusedIndexRef.current]?.focus();
+        }
+      }
+      document.addEventListener('keydown', handleKeyDown);
+      return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [ctx]);
+
+    useEffect(() => {
+      if (!ctx.open || !contentRef.current) return;
+      focusedIndexRef.current = -1;
+      const selected = contentRef.current.querySelector<HTMLElement>('[aria-selected="true"]');
+      if (selected) {
+        selected.focus();
+      } else {
+        const first = contentRef.current.querySelector<HTMLElement>('[role="option"]');
+        first?.focus();
+      }
+    }, [ctx.open]);
+
+    const setRef = useCallback(
+      (el: HTMLDivElement | null) => {
+        contentRef.current = el;
+        if (typeof ref === 'function') ref(el);
+        else if (ref) (ref as MutableRefObject<HTMLDivElement | null>).current = el;
+      },
+      [ref],
+    );
+
+    if (!ctx.open) return null;
+
+    return (
+      <div
+        ref={setRef}
+        id={ctx.triggerRef.current?.id ? `${ctx.triggerRef.current.id}-listbox` : undefined}
+        role="listbox"
+        aria-labelledby={ctx.triggerRef.current?.id || undefined}
+        className={cn(
+          'absolute left-0 top-full z-50 mt-1 w-full min-w-[8rem] overflow-hidden rounded-lg',
+          'border border-border bg-card text-card-foreground shadow-mi-input',
+          'animate-dropdown-in',
+          className,
+        )}
+        {...props}
+      >
+        <div className="max-h-60 overflow-y-auto p-1">{children}</div>
+      </div>
+    );
+  },
+);

package/src/Select/context.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+/**
+ * Internal context for the composable Select.
+ */
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+
+export interface SelectContextValue {
+  value: string | undefined;
+  onValueChange: (value: string) => void;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  disabled: boolean;
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  setTriggerRef: (el: HTMLButtonElement | null) => void;
+  /** Label text of the currently selected item (set by SelectItem). */
+  selectedLabel: { value: string; label: string } | undefined;
+  setSelectedLabel: (selected: { value: string; label: string } | undefined) => void;
+  getLabelForValue: (value: string | undefined) => string | undefined;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+  const ctx = useContext(SelectContext);
+  if (!ctx) throw new Error('Select sub-components must be used within <Select>.');
+  return ctx;
+}
+
+function getTextLabel(children: ReactNode): string | undefined {
+  if (typeof children === 'string' || typeof children === 'number') {
+    return String(children);
+  }
+  return undefined;
+}
+
+export function findSelectItemLabel(children: ReactNode, value: string | undefined): string | undefined {
+  if (!value) return undefined;
+
+  let match: string | undefined;
+
+  Children.forEach(children, (child) => {
+    if (match || !isValidElement(child)) return;
+
+    const props = child.props as {
+      value?: unknown;
+      children?: ReactNode;
+    };
+
+    if (props.value === value) {
+      match = getTextLabel(props.children);
+      return;
+    }
+
+    match = findSelectItemLabel(props.children, value);
+  });
+
+  return match;
+}