sh-ui-cli 0.115.0 → 0.117.0

package/data/registry/react/components/rich-text-editor/rich-text-editor.test.tsx

@@ -0,0 +1,283 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { Extension } from "@tiptap/core";
+import { RichTextEditor } from "./index";
+
+void React;
+
+describe('RichTextEditor format="markdown"', () => {
+  it("markdown defaultValue 를 받아 굵게 마크로 렌더한다", async () => {
+    render(<RichTextEditor format="markdown" defaultValue={"**굵게**"} />);
+    // 에디터가 굵게 마크로 렌더(strong 존재)
+    await screen.findByText("굵게");
+    expect(screen.getByText("굵게").closest("strong")).not.toBeNull();
+  });
+
+  it("편집 시 onChange 가 markdown 문자열을 돌려준다", async () => {
+    const onChange = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        defaultValue={"*기울임*"}
+        onChange={onChange}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("기울임");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    // 본문 끝에 굵은 텍스트를 추가하는 편집을 트랜잭션으로 일으켜 onUpdate 를 트리거.
+    editor!.chain().focus("end").insertContent(" **굵게**").run();
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalled());
+    const out = onChange.mock.calls.at(-1)![0] as string;
+    // markdown(HTML 아님) 으로 직렬화됐는지 검증: 굵게 마크 + 태그 부재.
+    expect(out).toContain("**굵게**");
+    expect(out).not.toContain("<strong>");
+    // _italic_ 은 CommonMark 정규화로 *italic* 형태(별표 기반)로 나온다.
+    expect(out).toContain("*기울임*");
+  });
+
+  it("html 모드(기본)에서는 markdown storage 가 없다(직렬화 미등록)", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        defaultValue={"<p><em>기울임</em></p>"}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("기울임");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    const storage = editor!.storage as { markdown?: unknown };
+    expect(storage.markdown).toBeUndefined();
+  });
+});
+
+describe("RichTextEditor submitOnEnter", () => {
+  it("Enter 는 onSubmit, Shift+Enter 는 줄바꿈 (ProseMirror handleKeyDown 경유)", async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        submitOnEnter
+        onSubmit={onSubmit}
+        onCreate={(e) => {
+          editor = e;
+        }}
+        aria-label="c"
+      />,
+    );
+    const el = await screen.findByLabelText("c");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    // user-event 로 실제 키 이벤트를 발생시켜 ProseMirror 의 handleKeyDown 플러그인
+    // 체인을 진짜로 통과시킨다(raw dispatchEvent 는 PM view 를 거치지 않을 수 있음).
+    editor!.commands.focus();
+    el.focus();
+    await user.keyboard("{Enter}");
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+
+    await user.keyboard("{Shift>}{Enter}{/Shift}");
+    expect(onSubmit).toHaveBeenCalledTimes(1); // 늘지 않음(줄바꿈)
+  });
+
+  it("IME 조합 중(isComposing) Enter 는 제출하지 않고, 일반 Enter 는 제출한다", async () => {
+    const onSubmit = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        submitOnEnter
+        onSubmit={onSubmit}
+        onCreate={(e) => {
+          editor = e;
+        }}
+        aria-label="ime"
+      />,
+    );
+    const el = await screen.findByLabelText("ime");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    editor!.commands.focus();
+    el.focus();
+
+    // 한글 조합 확정 Enter 는 isComposing: true 로 들어온다 — 제출되면 안 됨.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+        // @ts-expect-error jsdom KeyboardEvent 는 isComposing 을 옵션으로 받음
+        isComposing: true,
+      }),
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    // 레거시 브라우저가 보내는 keyCode 229(조합 중) Enter 도 제출 금지.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+        keyCode: 229,
+      }),
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    // 조합이 끝난 일반 Enter 는 제출된다.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("RichTextEditor controlled-sync (C-2 루프/커서 점프 방지)", () => {
+  it("동일 value 로 부모가 리렌더해도 setContent·셀렉션을 건드리지 않는다(커서 점프 방지)", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    let forceRerender: (() => void) | undefined;
+
+    // controlled value 가 그대로인데 부모가 리렌더하는 흔한 상황. lastSyncedRef 비교 덕에
+    // sync effect 가 우리 doc 을 다시 setContent 하지 않아 커서/셀렉션이 보존된다.
+    // (직렬화 비교만 했다면 markdown 정규화 차이로 매 렌더 setContent → 점프 위험.)
+    function Harness() {
+      const [, tick] = React.useState(0);
+      forceRerender = () => tick((n) => n + 1);
+      return (
+        <RichTextEditor
+          format="markdown"
+          value={"**hi**"}
+          onChange={() => {}}
+          onCreate={(e) => {
+            editor = e;
+          }}
+          aria-label="sync"
+        />
+      );
+    }
+
+    render(<Harness />);
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    await screen.findByText("hi");
+
+    // 커서를 문서 끝으로 두고 위치 기록.
+    editor!.commands.focus("end");
+    const before = editor!.state.selection.from;
+    expect(before).toBeGreaterThan(1);
+
+    // 같은 value 로 부모 리렌더 — sync effect 가 echo 를 다시 주입하면 안 된다.
+    const setContentSpy = vi.spyOn(editor!.commands, "setContent");
+    await React.act(async () => {
+      forceRerender!();
+      // effect flush 까지 대기(setContent 가 일어난다면 여기서 일어난다).
+      await Promise.resolve();
+    });
+
+    // setContent 미호출 + 셀렉션 그대로(점프 없음).
+    expect(setContentSpy).not.toHaveBeenCalled();
+    expect(editor!.state.selection.from).toBe(before);
+    setContentSpy.mockRestore();
+  });
+
+  it("진짜 다른 외부 value 는 에디터에 로드된다 (채널 전환)", async () => {
+    function Harness({ value }: { value: string }) {
+      return <RichTextEditor format="markdown" value={value} aria-label="ext" />;
+    }
+    const { rerender } = render(<Harness value={"**first**"} />);
+    await screen.findByText("first");
+
+    // 외부에서 완전히 다른 value 주입 → 에디터에 반영돼야 한다.
+    rerender(<Harness value={"**second**"} />);
+    await screen.findByText("second");
+    expect(screen.queryByText("first")).toBeNull();
+  });
+
+  it("html 모드에서도 controlled echo 루프가 발생하지 않는다", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    let lastEmitted = "";
+    function Harness() {
+      const [value, setValue] = React.useState("<p>hi</p>");
+      return (
+        <RichTextEditor
+          value={value}
+          onChange={(v) => {
+            lastEmitted = v;
+            setValue(v);
+          }}
+          onCreate={(e) => {
+            editor = e;
+          }}
+          aria-label="html-sync"
+        />
+      );
+    }
+    render(<Harness />);
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    await screen.findByText("hi");
+
+    editor!.chain().focus("end").insertContent(" x").run();
+    await vi.waitFor(() => expect(lastEmitted).toContain("x"));
+
+    const setContentSpy = vi.spyOn(editor!.commands, "setContent");
+    editor!.chain().focus("end").insertContent("y").run();
+    await vi.waitFor(() => expect(lastEmitted).toContain("y"));
+    expect(setContentSpy).not.toHaveBeenCalled();
+    setContentSpy.mockRestore();
+  });
+});
+
+describe("RichTextEditor extensions/onCreate", () => {
+  it("추가 확장이 등록되고 onCreate 로 editor 에 접근한다", async () => {
+    const onCreate = vi.fn();
+    const marker = Extension.create({ name: "spikeMarker" });
+    render(
+      <RichTextEditor
+        format="markdown"
+        extensions={[marker]}
+        onCreate={onCreate}
+      />,
+    );
+    await vi.waitFor(() => expect(onCreate).toHaveBeenCalled());
+    const editor = onCreate.mock.calls[0][0];
+    expect(
+      editor.extensionManager.extensions.some(
+        (e: { name: string }) => e.name === "spikeMarker",
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("RichTextEditor 하위호환 (default html)", () => {
+  it("기본 format(html)에서 편집 시 onChange 가 HTML 을 돌려준다", async () => {
+    const onChange = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        defaultValue={"<p><strong>굵게</strong></p>"}
+        onChange={onChange}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("굵게");
+    expect(screen.getByText("굵게").closest("strong")).not.toBeNull();
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    editor!.chain().focus("end").insertContent(" 추가").run();
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalled());
+    const out = onChange.mock.calls.at(-1)![0] as string;
+    // html 모드(기본)이므로 태그 문자열이 그대로 나와야 한다(markdown 별표 아님).
+    expect(out).toContain("<strong>");
+    expect(out).toContain("<p>");
+    expect(out).not.toContain("**");
+  });
+});

package/data/registry/react/components/tree/flatten.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { flattenVisible, nextFocusable, prevFocusable, findByTypeahead } from "./flatten";
+import type { TreeNode } from "./types";
+
+const tree: TreeNode[] = [
+  { id: "a", label: "Apple", children: [
+    { id: "a1", label: "Ant" },
+    { id: "a2", label: "Arc", disabled: true },
+  ] },
+  { id: "b", label: "Banana" },
+];
+
+describe("flattenVisible", () => {
+  it("닫힌 트리는 최상위만, hasChildren 표기", () => {
+    const v = flattenVisible(tree, new Set());
+    expect(v.map((n) => n.id)).toEqual(["a", "b"]);
+    expect(v[0].hasChildren).toBe(true);
+    expect(v[0].expanded).toBe(false);
+    expect(v[1].hasChildren).toBe(false);
+  });
+
+  it("부모가 펼쳐지면 자식이 가시 + level/aria 메타", () => {
+    const v = flattenVisible(tree, new Set(["a"]));
+    expect(v.map((n) => n.id)).toEqual(["a", "a1", "a2", "b"]);
+    const a1 = v[1];
+    expect(a1.level).toBe(1);
+    expect(a1.parentId).toBe("a");
+    expect(a1.posInSet).toBe(1);
+    expect(a1.setSize).toBe(2);
+  });
+
+  it("부모가 닫혀 있으면 자식은 안 보임", () => {
+    const v = flattenVisible(tree, new Set(["a2-only-irrelevant"]));
+    expect(v.map((n) => n.id)).toEqual(["a", "b"]);
+  });
+});
+
+describe("nextFocusable / prevFocusable", () => {
+  const v = flattenVisible(tree, new Set(["a"]));
+  it("다음 포커스는 disabled 를 건너뛴다", () => {
+    expect(nextFocusable(v, "a1")?.id).toBe("b");
+  });
+  it("이전 포커스도 disabled 를 건너뛴다", () => {
+    expect(prevFocusable(v, "b")?.id).toBe("a1");
+  });
+  it("끝에서 다음은 null", () => {
+    expect(nextFocusable(v, "b")).toBeNull();
+  });
+  it("처음에서 이전은 null", () => {
+    expect(prevFocusable(v, "a")).toBeNull();
+  });
+  it("fromId 가 없으면 next/prev 모두 null", () => {
+    expect(nextFocusable(v, "nonexistent")).toBeNull();
+    expect(prevFocusable(v, "nonexistent")).toBeNull();
+  });
+});
+
+describe("findByTypeahead", () => {
+  const v = flattenVisible(tree, new Set(["a"]));
+  it("접두사로 다음 가시 노드를 찾는다 (대소문자 무시)", () => {
+    expect(findByTypeahead(v, "ban", "a")?.id).toBe("b");
+  });
+  it("매치 없으면 null", () => {
+    expect(findByTypeahead(v, "zz", "a")).toBeNull();
+  });
+  it("disabled 는 typeahead 대상에서 제외", () => {
+    expect(findByTypeahead(v, "arc", "a")).toBeNull();
+  });
+  it("빈 prefix 는 null", () => {
+    expect(findByTypeahead(v, "", "a")).toBeNull();
+  });
+});

package/data/registry/react/components/tree/flatten.ts

@@ -0,0 +1,69 @@
+import type { TreeNode, VisibleNode } from "./types";
+
+/**
+ * 노드 label 을 typeahead 비교용 문자열로 변환한다.
+ * label 이 string 이면 그 값을, JSX 등 비문자열 ReactNode 면 "" 를 반환한다
+ * (비문자열 라벨 노드는 typeahead 검색 대상에서 제외됨).
+ */
+function labelText(node: TreeNode): string {
+  return typeof node.label === "string" ? node.label : "";
+}
+
+export function flattenVisible(nodes: TreeNode[], expanded: Set<string>): VisibleNode[] {
+  const out: VisibleNode[] = [];
+  const walk = (siblings: TreeNode[], level: number, parentId: string | null) => {
+    siblings.forEach((node, i) => {
+      const hasChildren = !!node.children && node.children.length > 0;
+      const isExpanded = hasChildren && expanded.has(node.id);
+      out.push({
+        id: node.id,
+        node,
+        level,
+        parentId,
+        hasChildren,
+        expanded: isExpanded,
+        disabled: !!node.disabled,
+        setSize: siblings.length,
+        posInSet: i + 1,
+      });
+      if (isExpanded) walk(node.children!, level + 1, node.id);
+    });
+  };
+  walk(nodes, 0, null);
+  return out;
+}
+
+export function nextFocusable(visible: VisibleNode[], fromId: string): VisibleNode | null {
+  const i = visible.findIndex((n) => n.id === fromId);
+  if (i === -1) return null;
+  for (let j = i + 1; j < visible.length; j++) {
+    if (!visible[j].disabled) return visible[j];
+  }
+  return null;
+}
+
+export function prevFocusable(visible: VisibleNode[], fromId: string): VisibleNode | null {
+  const i = visible.findIndex((n) => n.id === fromId);
+  if (i === -1) return null;
+  for (let j = i - 1; j >= 0; j--) {
+    if (!visible[j].disabled) return visible[j];
+  }
+  return null;
+}
+
+export function findByTypeahead(
+  visible: VisibleNode[],
+  prefix: string,
+  fromId: string,
+): VisibleNode | null {
+  const p = prefix.toLowerCase();
+  if (!p) return null;
+  const start = visible.findIndex((n) => n.id === fromId);
+  const n = visible.length;
+  for (let k = 1; k <= n; k++) {
+    const cand = visible[(start + k) % n];
+    if (cand.disabled) continue;
+    if (labelText(cand.node).toLowerCase().startsWith(p)) return cand;
+  }
+  return null;
+}

package/data/registry/react/components/tree/index.module.tsx

@@ -0,0 +1,215 @@
+import * as React from "react";
+import styles from "./styles.module.css";
+import { cn } from "@SH_UI_UTILS@";
+import type { TreeNode, TreeProps } from "./types";
+export type { TreeNode, TreeProps, TreeSize } from "./types";
+import { flattenVisible, nextFocusable, prevFocusable, findByTypeahead } from "./flatten";
+
+function useControllableSet(
+  controlled: string[] | undefined,
+  defaultValue: string[] | undefined,
+  onChange?: (ids: string[]) => void,
+) {
+  const [internal, setInternal] = React.useState<Set<string>>(
+    () => new Set(controlled ?? defaultValue ?? []),
+  );
+  const set = controlled ? new Set(controlled) : internal;
+  const update = (next: Set<string>) => {
+    if (!controlled) setInternal(next);
+    onChange?.([...next]);
+  };
+  return [set, update] as const;
+}
+
+export const Tree = React.forwardRef<HTMLDivElement, TreeProps>(function Tree(
+  {
+    nodes,
+    expandedIds,
+    defaultExpandedIds,
+    onExpandedChange,
+    selectedId,
+    defaultSelectedId,
+    onSelect,
+    renderLabel,
+    size = "md",
+    className,
+  },
+  ref,
+) {
+  const [expanded, setExpanded] = useControllableSet(
+    expandedIds,
+    defaultExpandedIds,
+    onExpandedChange,
+  );
+
+  const isSelectedControlled = selectedId !== undefined;
+  const [selInternal, setSelInternal] = React.useState<string | null>(
+    defaultSelectedId ?? null,
+  );
+  const selected = isSelectedControlled ? selectedId! : selInternal;
+  const selectNode = (id: string | null) => {
+    if (!isSelectedControlled) setSelInternal(id);
+    onSelect?.(id);
+  };
+
+  const visible = flattenVisible(nodes, expanded);
+  const visibleMap = React.useMemo(() => new Map(visible.map((v) => [v.id, v])), [visible]);
+  const [focusId, setFocusId] = React.useState<string | null>(visible[0]?.id ?? null);
+
+  React.useEffect(() => {
+    if (focusId && !visibleMap.has(focusId)) {
+      setFocusId(visible[0]?.id ?? null);
+    }
+  }, [visibleMap, focusId, visible]);
+
+  const toggle = (id: string) => {
+    const next = new Set(expanded);
+    if (next.has(id)) next.delete(id);
+    else next.add(id);
+    setExpanded(next);
+  };
+
+  const onItemClick = (n: TreeNode, hasChildren: boolean) => {
+    if (n.disabled) return;
+    setFocusId(n.id);
+    if (hasChildren) toggle(n.id);
+    selectNode(n.id);
+  };
+
+  const itemRefs = React.useRef<Map<string, HTMLDivElement>>(new Map());
+  const focusNode = (id: string) => {
+    setFocusId(id);
+    itemRefs.current.get(id)?.focus();
+  };
+
+  const onItemKeyDown = (e: React.KeyboardEvent, n: TreeNode, hasChildren: boolean) => {
+    switch (e.key) {
+      case "ArrowDown": {
+        e.preventDefault();
+        const nx = nextFocusable(visible, n.id);
+        if (nx) focusNode(nx.id);
+        break;
+      }
+      case "ArrowUp": {
+        e.preventDefault();
+        const pv = prevFocusable(visible, n.id);
+        if (pv) focusNode(pv.id);
+        break;
+      }
+      case "ArrowRight": {
+        e.preventDefault();
+        if (hasChildren && !expanded.has(n.id)) toggle(n.id);
+        else if (hasChildren) {
+          const first = n.children!.find((c) => !c.disabled);
+          if (first) focusNode(first.id);
+        }
+        break;
+      }
+      case "ArrowLeft": {
+        e.preventDefault();
+        if (hasChildren && expanded.has(n.id)) toggle(n.id);
+        else {
+          const meta = visibleMap.get(n.id);
+          if (meta?.parentId) focusNode(meta.parentId);
+        }
+        break;
+      }
+      case "Home": {
+        e.preventDefault();
+        const first = visible.find((v) => !v.disabled);
+        if (first) focusNode(first.id);
+        break;
+      }
+      case "End": {
+        e.preventDefault();
+        for (let i = visible.length - 1; i >= 0; i--)
+          if (!visible[i].disabled) {
+            focusNode(visible[i].id);
+            break;
+          }
+        break;
+      }
+      case "Enter":
+      case " ": {
+        e.preventDefault();
+        if (!n.disabled) selectNode(n.id);
+        break;
+      }
+      default: {
+        if (e.key.length === 1 && /\S/.test(e.key)) {
+          const hit = findByTypeahead(visible, e.key, n.id);
+          if (hit) focusNode(hit.id);
+        }
+      }
+    }
+  };
+
+  const renderNodes = (siblings: TreeNode[], level: number): React.ReactNode => (
+    <div role={level === 0 ? undefined : "group"} className={styles.tree__group}>
+      {siblings.map((n) => {
+        const hasChildren = !!n.children?.length;
+        const isExpanded = hasChildren && expanded.has(n.id);
+        const meta = visibleMap.get(n.id);
+        const depth = meta?.level ?? level;
+        return (
+          <div key={n.id}>
+            <div
+              role="treeitem"
+              ref={(el) => {
+                if (el) itemRefs.current.set(n.id, el);
+                else itemRefs.current.delete(n.id);
+              }}
+              aria-level={depth + 1}
+              aria-setsize={meta?.setSize}
+              aria-posinset={meta?.posInSet}
+              aria-expanded={hasChildren ? isExpanded : undefined}
+              aria-selected={selected === n.id}
+              aria-disabled={n.disabled || undefined}
+              aria-label={typeof n.label === "string" ? n.label : undefined}
+              tabIndex={focusId === n.id ? 0 : -1}
+              data-disabled={n.disabled || undefined}
+              className={cn(
+                styles.tree__item,
+                selected === n.id && styles["tree__item--selected"],
+              )}
+              onClick={() => onItemClick(n, hasChildren)}
+              onKeyDown={(e) => onItemKeyDown(e, n, hasChildren)}
+            >
+              <span
+                className={styles.tree__indent}
+                style={{ width: `calc(var(--space-4) * ${depth})` }}
+                aria-hidden
+              />
+              {hasChildren ? (
+                <span
+                  className={styles.tree__chevron}
+                  data-expanded={isExpanded || undefined}
+                  aria-hidden
+                >
+                  ▸
+                </span>
+              ) : (
+                <span className={cn(styles.tree__chevron, styles["tree__chevron--leaf"])} aria-hidden />
+              )}
+              {n.icon ? (
+                <span className={styles.tree__icon} aria-hidden>
+                  {n.icon}
+                </span>
+              ) : null}
+              <span className={styles.tree__label}>
+                {renderLabel ? renderLabel(n) : n.label}
+              </span>
+            </div>
+            {isExpanded ? renderNodes(n.children!, level + 1) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+
+  return (
+    <div ref={ref} role="tree" data-size={size} className={cn(styles.tree, className)}>
+      {renderNodes(nodes, 0)}
+    </div>
+  );
+});