id: 'product-facet-grid'
status: completed
Product Facet Grid
Reference
- URL: https://biodance.com/ (상품 목록 / PLP 영역)
- 위치: 상단 정렬 바 아래 facet sidebar + product grid
- 구조: 좌측 facet panel + 우측 상품 카드 그리드 + 선택된 필터 chip + sort dropdown + load more
React Component
- Path:
apps/makitt-standard-commerce/src/components/assets/product-facet-grid/
- Status: implemented
- 반응형: Desktop은 sidebar + grid, tablet/mobile은 facet이 상단 stack으로 이동
- i18n: ko, en, ja
- API:
shopApi.getProductFacets() — preset 기반 facet 섹션 조회shopApi.searchProductCardsCursor() — 카드 결과 + cursor load more
HCS JSON Asset
- Path:
apps/builder/data/hcs-asset/product-facet-grid.json
- Status: implemented
- Resource 바인딩:
product.facets — facet panel / selected state / countproduct.cardsSearch — cursor 기반 상품 카드 결과
- 필터 전략:
- URL query를 상태 저장소로 사용
- multi-select facet은 CSV string (
categories, tags, attributes) 토글
inStock, minPrice, maxPrice, sortBy도 query로 반영
- UX:
- checkbox 대신 selectable chip/button
- price는 input blur 시 query 반영
fetchNext로 load more
Resource Registry
- Package:
@makitt/api
- Keys:
product.facetsproduct.cardsSearch
- Schema:
ProductFacetsResponseSchemaProductCardCursorResponseSchema
- Fetcher:
productApi.facets()productApi.cardsSearch()
Prerequisites
makitt-server (shop-api)
고객 대면 API. shop storefront에서 호출.
| API | Method | Endpoint | Status |
|---|
| 상품 facet 조회 | GET | /shop/{shopId}/products/facets | available |
| 상품 카드 cursor 검색 | GET | /shop/{shopId}/products/cards/search | available |
| 상품 상세 | GET | /shop/{shopId}/products/{id} | available |
| 상품 slug 조회 | GET | /shop/{shopId}/products/by-slug/{slug} | available |
makitt-server (admin-api)
셀러 어드민에서 discovery preset을 관리하기 위한 API.
| API | Method | Endpoint | Status |
|---|
| discovery preset 조회 | GET | /api/v1/shops/{shopId}/product-discovery-settings | available |
| discovery preset 저장 | PUT | /api/v1/shops/{shopId}/product-discovery-settings | available |
makitt-server (도메인/모델링)
| 항목 | 내용 | Status |
|---|
| Shop metadata | product_discovery_configs preset 저장 | available |
| Product OpenSearch | facet count / price range / cursor search source | available |
| Product discovery config | section / preset / allowed option values | available |
makitt-web (셀러 어드민 UI)
| 기능 | 설명 | Status |
|---|
| 상품 > 필터 > Discovery | preset 생성/편집/기본 preset 지정 | available |
| allowed option values | category / attribute value subset 지정 | available |
@makitt/api (리소스 레지스트리)
| 항목 | 설명 | Status |
|---|
product.facets resource | facet panel response + fetcher | available |
product.cardsSearch resource | cursor card response + fetcher | available |
makitt-shop (HCS 렌더링)
| 항목 | 설명 | Status |
|---|
select renderer | sort dropdown 표현 | available |
input renderer | min/max price 입력 | available |
accordion renderer | facet section 묶음 | available |
fetchNext action | load more cursor | available |
pagination action | URL query 기반 필터 반영 | available |
checkbox renderer | 현재 미구현, 이번 asset은 button/chip으로 우회 | not required |
HCS Conversion Notes
- 이번 asset은 React reference 구현을 그대로 옮기기보다 HCS 제약에 맞게 재구성했다.
- 핵심 상태는 local state가 아니라 URL query에 저장한다. 덕분에 facet resource와 cards resource가 같은 query를 바라보며 동시에 refetch된다.
- multi-select는
toggle transform으로 CSV query string을 관리한다.
- selected filters는 facet API의
option.selected를 그대로 사용해 chip으로 노출한다.
- price input은 change마다 refetch하지 않고 blur 시점에 query를 갱신하도록 설계했다.