npm - @mandujs/mcp - Versions diffs - 0.9.19 → 0.9.21 - Mend

@mandujs/mcp 0.9.19 → 0.9.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/src/resources/skills/mandu-ui/rules/ui-accessibility-focus.md ADDED Viewed

@@ -0,0 +1,238 @@
+---
+title: Focus Management
+impact: HIGH
+impactDescription: Keyboard navigation and focus handling
+tags: ui, accessibility, focus, keyboard
+---
+## Focus Management
+**Impact: HIGH (Keyboard navigation and focus handling)**
+키보드 사용자를 위한 포커스 관리와 네비게이션을 구현하세요.
+## Focus Visible 스타일
+```css
+/* globals.css */
+@layer base {
+  /* 키보드 포커스만 표시 (마우스 클릭은 제외) */
+  *:focus {
+    outline: none;
+  }
+  *:focus-visible {
+    @apply outline-2 outline-offset-2 outline-ring;
+  }
+  /* 커스텀 focus ring */
+  .focus-ring {
+    @apply focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2;
+  }
+}
+```
+## Tailwind Focus 유틸리티
+```tsx
+<button
+  className={cn(
+    "rounded-md px-4 py-2",
+    // focus-visible만 스타일링 (키보드 포커스)
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+  )}
+>
+  Click me
+</button>
+```
+## Focus Trap
+```bash
+bun add focus-trap-react
+```
+```tsx
+// app/modal/client.tsx
+"use client";
+import FocusTrap from "focus-trap-react";
+import { useEffect, useRef } from "react";
+export function ModalIsland({ open, onClose, children }) {
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+  // ESC로 닫기
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    if (open) {
+      document.addEventListener("keydown", handleKeyDown);
+      return () => document.removeEventListener("keydown", handleKeyDown);
+    }
+  }, [open, onClose]);
+  if (!open) return null;
+  return (
+    <FocusTrap
+      focusTrapOptions={{
+        initialFocus: () => closeButtonRef.current,
+        allowOutsideClick: true,
+      }}
+    >
+      <div className="fixed inset-0 z-50">
+        <div className="fixed inset-0 bg-black/50" onClick={onClose} />
+        <div
+          role="dialog"
+          aria-modal="true"
+          className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 rounded-lg"
+        >
+          <button
+            ref={closeButtonRef}
+            onClick={onClose}
+            className="absolute top-4 right-4"
+          >
+            Close
+          </button>
+          {children}
+        </div>
+      </div>
+    </FocusTrap>
+  );
+}
+```
+## Roving Focus
+```tsx
+// app/toolbar/client.tsx
+"use client";
+import { useState, useRef, KeyboardEvent } from "react";
+export function ToolbarIsland() {
+  const [focusedIndex, setFocusedIndex] = useState(0);
+  const buttonsRef = useRef<(HTMLButtonElement | null)[]>([]);
+  const items = ["Bold", "Italic", "Underline"];
+  const handleKeyDown = (e: KeyboardEvent, index: number) => {
+    let newIndex = index;
+    switch (e.key) {
+      case "ArrowRight":
+        newIndex = (index + 1) % items.length;
+        break;
+      case "ArrowLeft":
+        newIndex = (index - 1 + items.length) % items.length;
+        break;
+      case "Home":
+        newIndex = 0;
+        break;
+      case "End":
+        newIndex = items.length - 1;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    setFocusedIndex(newIndex);
+    buttonsRef.current[newIndex]?.focus();
+  };
+  return (
+    <div role="toolbar" aria-label="Text formatting">
+      {items.map((item, index) => (
+        <button
+          key={item}
+          ref={(el) => (buttonsRef.current[index] = el)}
+          tabIndex={focusedIndex === index ? 0 : -1}
+          onKeyDown={(e) => handleKeyDown(e, index)}
+          onFocus={() => setFocusedIndex(index)}
+          className="px-3 py-1 rounded hover:bg-gray-100 focus-visible:ring-2"
+        >
+          {item}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+## Skip Link
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {/* 첫 번째 요소로 Skip Link */}
+        <a
+          href="#main-content"
+          className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white focus:rounded-md focus:shadow-lg"
+        >
+          Skip to main content
+        </a>
+        <header>{/* ... */}</header>
+        <main id="main-content" tabIndex={-1}>
+          {children}
+        </main>
+      </body>
+    </html>
+  );
+}
+```
+## 포커스 복원
+```tsx
+// hooks/useFocusReturn.ts
+import { useRef, useEffect } from "react";
+export function useFocusReturn(isOpen: boolean) {
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (isOpen) {
+      // 열릴 때 현재 포커스 저장
+      previousFocusRef.current = document.activeElement as HTMLElement;
+    } else if (previousFocusRef.current) {
+      // 닫힐 때 포커스 복원
+      previousFocusRef.current.focus();
+      previousFocusRef.current = null;
+    }
+  }, [isOpen]);
+}
+// 사용
+export function DialogIsland({ open, onClose }) {
+  useFocusReturn(open);
+  // ...
+}
+```
+## Tab Order 관리
+```tsx
+// 올바른 tabIndex 사용
+<div>
+  {/* tabIndex="0": 자연스러운 탭 순서에 포함 */}
+  <div tabIndex={0} role="button">Focusable div</div>
+  {/* tabIndex="-1": 프로그래밍으로만 포커스 가능 */}
+  <div tabIndex={-1} ref={focusTargetRef}>Focus target</div>
+  {/* 양수 tabIndex는 피하기 */}
+  {/* ❌ tabIndex={1} - 탭 순서 혼란 */}
+</div>
+```
+Reference: [WAI-ARIA Focus Management](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)

package/src/resources/skills/mandu-ui/rules/ui-composition-patterns.md ADDED Viewed

@@ -0,0 +1,259 @@
+---
+title: UI Composition Patterns
+impact: MEDIUM
+impactDescription: Reusable and flexible component composition
+tags: ui, composition, patterns, reusable
+---
+## UI Composition Patterns
+**Impact: MEDIUM (Reusable and flexible component composition)**
+재사용 가능하고 유연한 UI 컴포넌트 조합 패턴입니다.
+## Slot Pattern (asChild)
+```tsx
+// components/ui/button.tsx
+import { Slot } from "@radix-ui/react-slot";
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  asChild?: boolean;
+}
+export function Button({ asChild, ...props }: ButtonProps) {
+  const Comp = asChild ? Slot : "button";
+  return <Comp className={cn(buttonVariants())} {...props} />;
+}
+```
+```tsx
+// 사용: Link에 Button 스타일 적용
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+<Button asChild variant="outline">
+  <Link href="/about">About</Link>
+</Button>
+// 결과: <a> 태그에 Button 스타일이 적용됨
+```
+## Render Props
+```tsx
+// components/data-table.tsx
+interface DataTableProps<T> {
+  data: T[];
+  renderRow: (item: T, index: number) => React.ReactNode;
+  renderEmpty?: () => React.ReactNode;
+}
+export function DataTable<T>({ data, renderRow, renderEmpty }: DataTableProps<T>) {
+  if (data.length === 0) {
+    return renderEmpty?.() || <p>No data</p>;
+  }
+  return (
+    <table>
+      <tbody>
+        {data.map((item, index) => (
+          <tr key={index}>{renderRow(item, index)}</tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+```tsx
+// 사용
+<DataTable
+  data={users}
+  renderRow={(user) => (
+    <>
+      <td>{user.name}</td>
+      <td>{user.email}</td>
+    </>
+  )}
+  renderEmpty={() => <EmptyState icon={UserIcon} message="No users found" />}
+/>
+```
+## Polymorphic Components
+```tsx
+// components/ui/text.tsx
+type TextProps<T extends React.ElementType = "p"> = {
+  as?: T;
+  size?: "sm" | "md" | "lg";
+  weight?: "normal" | "medium" | "bold";
+} & Omit<React.ComponentPropsWithoutRef<T>, "as" | "size" | "weight">;
+export function Text<T extends React.ElementType = "p">({
+  as,
+  size = "md",
+  weight = "normal",
+  className,
+  ...props
+}: TextProps<T>) {
+  const Component = as || "p";
+  return (
+    <Component
+      className={cn(
+        // Size
+        { sm: "text-sm", md: "text-base", lg: "text-lg" }[size],
+        // Weight
+        { normal: "font-normal", medium: "font-medium", bold: "font-bold" }[weight],
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+```tsx
+// 사용
+<Text as="h1" size="lg" weight="bold">Title</Text>
+<Text as="span" size="sm">Caption</Text>
+<Text>Default paragraph</Text>
+```
+## Container/Presenter Pattern
+```tsx
+// Container: 로직 담당
+// app/user-profile/client.tsx
+"use client";
+import { useState, useEffect } from "react";
+import { UserProfileView } from "./view";
+export function UserProfileIsland({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    fetch(`/api/users/${userId}`)
+      .then(res => res.json())
+      .then(data => {
+        setUser(data);
+        setLoading(false);
+      });
+  }, [userId]);
+  if (loading) return <UserProfileView.Skeleton />;
+  if (!user) return <UserProfileView.Error />;
+  return <UserProfileView user={user} />;
+}
+```
+```tsx
+// Presenter: UI 담당
+// app/user-profile/view.tsx
+import { Avatar } from "@/components/ui/avatar";
+import { Card, CardHeader, CardContent } from "@/components/ui/card";
+import { Skeleton } from "@/components/ui/skeleton";
+interface UserProfileViewProps {
+  user: { name: string; email: string; avatar: string };
+}
+export function UserProfileView({ user }: UserProfileViewProps) {
+  return (
+    <Card>
+      <CardHeader>
+        <Avatar src={user.avatar} alt={user.name} />
+        <h2>{user.name}</h2>
+      </CardHeader>
+      <CardContent>
+        <p>{user.email}</p>
+      </CardContent>
+    </Card>
+  );
+}
+UserProfileView.Skeleton = function Skeleton() {
+  return (
+    <Card>
+      <CardHeader>
+        <Skeleton className="h-12 w-12 rounded-full" />
+        <Skeleton className="h-4 w-32" />
+      </CardHeader>
+    </Card>
+  );
+};
+UserProfileView.Error = function Error() {
+  return <Card><p>Failed to load user</p></Card>;
+};
+```
+## Layout Components
+```tsx
+// components/layout/stack.tsx
+interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
+  gap?: "sm" | "md" | "lg";
+  direction?: "row" | "column";
+  align?: "start" | "center" | "end";
+  justify?: "start" | "center" | "end" | "between";
+}
+export function Stack({
+  gap = "md",
+  direction = "column",
+  align = "start",
+  justify = "start",
+  className,
+  ...props
+}: StackProps) {
+  return (
+    <div
+      className={cn(
+        "flex",
+        direction === "column" ? "flex-col" : "flex-row",
+        { sm: "gap-2", md: "gap-4", lg: "gap-6" }[gap],
+        { start: "items-start", center: "items-center", end: "items-end" }[align],
+        { start: "justify-start", center: "justify-center", end: "justify-end", between: "justify-between" }[justify],
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+```tsx
+// 사용
+<Stack gap="lg" align="center">
+  <Avatar />
+  <Stack gap="sm">
+    <Text weight="bold">{name}</Text>
+    <Text size="sm">{email}</Text>
+  </Stack>
+</Stack>
+```
+## Higher-Order Island
+```tsx
+// hoc/withIslandState.tsx
+export function withIslandState<T>(
+  WrappedComponent: React.ComponentType<T & { state: any; setState: any }>
+) {
+  return function IslandWrapper(props: T) {
+    const [state, setState] = useState({});
+    return <WrappedComponent {...props} state={state} setState={setState} />;
+  };
+}
+// 사용
+const EnhancedForm = withIslandState(FormComponent);
+```
+Reference: [React Patterns](https://reactpatterns.com/)