useListParams

import { useListParams } from "@sonamu-kit/react-components";
import { UserService } from "@/services/services.generated";
import { UserListParams } from "@/services/sonamu.generated";

export function UserListPage() {
  // URL에서 파라미터 파싱 및 초기화
  const { listParams, setListParams, register } = useListParams(
    UserListParams,
    {
      num: 24,
      page: 1,
      orderBy: "id-desc" as const,
      search: "id" as const,
      keyword: "",
    }
  );

  // API 호출 (listParams를 그대로 전달)
  const { data, isLoading } = UserService.useUsers("A", listParams);

  // ...
}

const { listParams } = useListParams(UserListParams, defaultValue);

// API 호출 시 그대로 전달
const { data } = UserService.useUsers("A", listParams);

// 또는 특정 값 확인
console.log(listParams.page);     // 1
console.log(listParams.keyword);  // "admin"
console.log(listParams.orderBy);  // "id-desc"

listParams: Partial<z.infer<UserListParams>> & DefaultValue

const { listParams, setListParams } = useListParams(UserListParams, defaultValue);

// 페이지 변경
setListParams({ ...listParams, page: 2 });

// 정렬 변경
setListParams({ ...listParams, page: 1, orderBy: "created_at-desc" });

// 검색 키워드 변경
setListParams({
  ...listParams,
  page: 1,  // 검색 시 항상 1페이지로
  keyword: "admin"
});

import { Input, Select } from "@sonamu-kit/react-components/components";

const { register } = useListParams(UserListParams, defaultValue);

return (
  <div>
    {/* 검색 키워드 입력 */}
    <Input {...register("keyword")} placeholder="검색어 입력" />

    {/* 정렬 선택 */}
    <UserOrderBySelect {...register("orderBy")} />

    {/* 페이지 선택 */}
    <Pagination {...register("page")} total={data?.total ?? 0} />
  </div>
);

{
  value: listParams[name] ?? defaultValue[name] ?? (name === "page" ? 1 : ""),
  onValueChange: (value) => {
    if (name === "page") {
      // 페이지 변경은 다른 필터 유지
      setListParams({ ...listParams, page: value });
    } else {
      // 다른 필터 변경은 페이지를 1로 리셋
      setListParams({
        ...listParams,
        page: 1,
        [name]: value === "" ? undefined : value
      });
    }
  }
}

import { useListParams } from "@sonamu-kit/react-components";
import { Input, Pagination } from "@sonamu-kit/react-components/components";
import { UserService } from "@/services/services.generated";
import { UserListParams } from "@/services/sonamu.generated";
import { UserOrderBySelect } from "@/components/user/UserOrderBySelect";
import { UserSearchFieldSelect } from "@/components/user/UserSearchFieldSelect";

export function UserListPage() {
  const { listParams, register } = useListParams(
    UserListParams,
    {
      num: 24,
      page: 1,
      orderBy: "id-desc" as const,
      search: "id" as const,
      keyword: "",
    }
  );

  const { data, isLoading } = UserService.useUsers("A", listParams);

  if (isLoading) return <div>로딩 중...</div>;

  return (
    <div>
      {/* 필터 섹션 */}
      <div className="flex gap-2 mb-4">
        <UserSearchFieldSelect {...register("search")} />
        <Input {...register("keyword")} placeholder="검색어 입력" />
        <UserOrderBySelect {...register("orderBy")} />
      </div>

      {/* 테이블 */}
      <table>
        <thead>
          <tr>
            <th>ID</th>
            <th>이름</th>
            <th>이메일</th>
          </tr>
        </thead>
        <tbody>
          {data?.rows.map((user) => (
            <tr key={user.id}>
              <td>{user.id}</td>
              <td>{user.username}</td>
              <td>{user.email}</td>
            </tr>
          ))}
        </tbody>
      </table>

      {/* 페이지네이션 */}
      <Pagination {...register("page")} total={data?.total ?? 0} />
    </div>
  );
}

// 백엔드: user.types.ts
export const UserListParams = UserBaseListParams.extend({
  role: z.enum(["admin", "normal"]).optional(),
  isVerified: z.boolean().optional(),
});

import { UserRoleSelect } from "@/components/user/UserRoleSelect";
import { Switch } from "@sonamu-kit/react-components/components";

const { register } = useListParams(UserListParams, {
  num: 24,
  page: 1,
  role: undefined,
  isVerified: undefined,
});

return (
  <div>
    <UserRoleSelect {...register("role")} clearable />

    <div className="flex items-center gap-2">
      <label>인증된 사용자만</label>
      <Switch {...register("isVerified")} />
    </div>
  </div>
);

# 사용자가 필터를 설정한 후 URL
https://example.com/users?page=2&keyword=admin&orderBy=created_at-desc&role=admin

# 이 URL을 복사해서 공유하거나 북마크하면
# 나중에 접속할 때 동일한 필터가 적용됨

const { listParams, setListParams, register } = useListParams(
  UserListParams,
  defaultValue,
  { disableSearchParams: true }
);

const { register } = useListParams(UserListParams, defaultValue);

// ✅ OK: UserListParams에 정의된 필드
register("keyword");
register("orderBy");
register("page");

// ❌ 컴파일 에러: 존재하지 않는 필드
register("invalidField");

register("
        ↓
        keyword
        orderBy
        page
        search
        num
        role          // 커스텀 필드
        isVerified    // 커스텀 필드

// useListParams 내부 구조 (단순화)
export function useListParams<U, T>(zType: U, defaultValue: T) {
  const search = useSearch({ strict: false });
  const navigate = useNavigate();

  const listParams = zType.safeParse(search).success
    ? { ...defaultValue, ...zType.parse(search) }
    : defaultValue;

  const setListParams = (newParams: T) => {
    navigate({ search: newParams });
  };

  // ...
}

// ❌ 잘못된 초기값 (num, page 누락)
const { listParams } = useListParams(UserListParams, {});

// ✅ 올바른 초기값 (필수 필드 포함)
const { listParams } = useListParams(UserListParams, {
  num: 24,
  page: 1,
  orderBy: "id-desc" as const,
  search: "id" as const,
});

// ❌ 컴파일 에러: string을 enum에 할당 불가
const defaultValue = {
  orderBy: "id-desc",
};

// ✅ OK: as const로 literal 타입 만들기
const defaultValue = {
  orderBy: "id-desc" as const,
};

// ❌ register의 onValueChange가 무시됨
<Input
  {...register("keyword")}
  onChange={(e) => console.log(e.target.value)}
/>

// ✅ OK: register의 onValueChange를 직접 호출
<Input
  {...register("keyword")}
  onValueChange={(value) => {
    console.log(value);
    register("keyword").onValueChange(value);
  }}
/>

// 또는 더 나은 방법: 별도 이벤트 핸들러
const handleKeywordChange = (value: string) => {
  console.log(value);
  setListParams({ ...listParams, page: 1, keyword: value });
};