@ihabdevteam/core 0.199.0 → 0.201.0

package/CHANGELOG.md

@@ -7,6 +7,211 @@ All notable changes to this project will be documented in this file.
 > 적은 글이라, 지금 이름으로 고쳐 놓으면 그 시절에 그 이름으로 받은 사람이
 > 제 이야기를 못 찾는다.
 
+## 0.201.0
+
+### 고침 — 펼친 태블릿 레일이 넓은 화면과 달랐다 (사장님 지시 2026-09-27)
+
+태블릿 폭(768~1023)에서 레일은 두 모양이다 — 접힌 72px 과 호버·포커스로 펼친 220px.
+펼친 220 은 **넓은 화면과 같은 폭**인데 여섯 군데가 달랐다(실측):
+
+| | 넓은 화면 | 펼친 레일(전) |
+|---|---|---|
+| 목록 좌우 여백 | 11px | 8px |
+| 항목 사이(`gap`) | 12px | 10px |
+| 항목 모서리 | 10px | 12px |
+| 이름표 `max-width` | none | 200px |
+| **하위 항목 들여쓰기** | **30px** | **16px** |
+| 스크롤 막대 자리 | 목록 폭 216 | 222 |
+
+까닭은 **꼴 자체**였다. 접힌 꼴 규칙마다 `:hover` 짝을 두어 되돌리고 있었는데, 그러면
+짝을 빠뜨린 것이 조용히 남는다. 하위 항목이 그랬다 — 되돌리는 규칙(`padding: 0 16px`,
+0,3,0)이 `.side-nav__item--child`(0,1,0)를 이겨 **들여쓰기가 통째로 사라졌고**, 그 짝은
+애초에 적힌 적이 없다.
+
+그래서 **접힌 꼴만 덮고 펼치면 아무것도 안 덮는다**(`:not(:hover):not(:focus-within)`).
+되돌릴 것이 없으니 빠뜨릴 것도 없고, 넓은 화면에 새 규칙이 생겨도 펼친 레일이 저절로
+따라간다. 되돌림 규칙 다섯이 사라졌다. 남은 차이는 단추 크기(48 → 44)뿐인데, 그것은
+좁은 화면에서 한 급 줄이는 **전역 사다리**라 이 레일만의 일이 아니다.
+
+**배지도 고친다** — 접힌 레일에서 인라인 배지는 이름표(폭 0) 뒤에 서느라 단추(52)를
+10px 넘어섰고 통이 그 자리를 잘라 동그라미가 베였다(실측: 단추 344~396, 배지 382~406).
+단추 안쪽 오른쪽 위로 얹는다. 모서리 값이 `--top-right` 기본(-6px)이 아니라 0 인 것은
+`BottomNav` 와 같은 까닭이다 — 통이 넘침을 자르므로 바깥으로 나간 6px 은 사라진다.
+
+### 고침 — 말귀매니저의 막대와 못 쓰는 항목
+
+**막대는 옅은 흰색으로**(`rgba(255,255,255,0.4)`, 얹으면 `0.75`). 브랜드 색으로 한 번 가
+봤다가 되돌렸다 — 이 지면이 `--color-main` → `--color-sub` 그라디언트라 **막대가 어딘가에서
+지면과 같아진다**(실측: main 은 맨 위 1.06, sub 은 맨 아래 1.01). 게다가 둘이 엇갈려 위쪽에서는
+얹으면 잘 보이고 아래쪽에서는 얹으면 덜 보였다. 색으로는 못 푸는 자리다. 투명도로 두면
+지면이 무슨 색이든 그만큼 밝아진다(가장 나쁜 자리에서 1.30 → 1.65). 흰빛으로는 3.0 에 못
+간다는 것도 재 뒀다 — 꽉 채운 흰색도 1.94 다.
+
+**못 쓰는 항목**은 글자만 희고 아이콘만 탁했다. `.side-nav__item.disabled .side-nav__icon`
+(0,3,0)이 매니저 규칙(0,2,0)을 이겨 흰 지면용 회색이 그라디언트 위에 떠 있었다. 둘 다
+`--color-deepWhite` 로 두고, 물러나는 일은 줄에 이미 걸린 `opacity: 0.6` 이 한다.
+
+### 더해짐 — 두 앱에 한 벌씩 남아 있던 넷 (말귀 ⑲)
+
+두 묶음(회원앱 · 어드민)에 걸쳐 남은 것을 다시 훑어 올라온 넷이다. **넷 다 한쪽만 고쳐지면
+조용한** 쪽이다.
+
+**`installSkewRecovery()`** — 복구하는 일(`recoverFromSkew`)은 이미 코어였는데 **어디에 어떻게
+매다는지**가 두 `main.tsx` 에 글자까지 같이 있었다. 그 열몇 줄에 틀리기 쉬운 조각이 있다:
+스타일시트의 `error` 는 **버블링하지 않아** 셋째 인자 `true`(캡처)로 들어야 한다. 빠뜨리면 그
+앱만 CSS 청크 실패를 못 듣고, 스크립트는 멀쩡히 도는 채 **화면만 스타일이 전부 빠져** 뜬다
+(말귀 실제 QA 건). 한 줄로 줄인다 — 떼는 함수를 돌려준다.
+
+**`isSessionForThisTab(받은것, 이탭것)`** — `auth.storage` 를 `sessionStorage` 로 두어 탭을 갈라도
+GoTrue 의 `BroadcastChannel` 은 저장소 종류와 무관하게 세션 이벤트를 모든 탭에 뿌린다. 받은
+세션을 그대로 믿으면 **다른 탭의 로그인이 이 탭 화면에 얹혀** 로그인된 것처럼 그려지는데, 이 탭
+저장소는 비어 API 호출이 전부 미인증으로 실패한다(어드민에서는 그것이 `ROLE_ADMIN` 세션이다).
+`getSession()` 으로 이 탭 저장소를 다시 읽어 맞대는 그 한 줄을 여기 둔다. **로그아웃은 늘
+받는다** — 지울 것이 없다는 말은 어느 탭에서 왔든 참이고, 막으면 이 탭이 로그인된 채 남는다.
+
+**`useDiscardGuard`** — 쓰던 것을 버리고 닫을지 묻는 가드. 두 앱에 한 벌씩 있었고 **어드민 쪽이
+윗집합**이었다: `allowClose()` 를 하나 더 들었다. 저장 뒤 `closeWithAnimation` 도 `beforeClose` 를
+거치는데 폼은 방금 달라진 채라 "저장했는데 버릴까요?" 를 묻게 된다 — 갈라져 있던 탓에 그 고침이
+회원앱으로 못 건너왔고, 회원앱 고객 추가 창이 실제로 그랬다. 문구는 `labels` 로 받는다(안 주면
+`common.discardConfirm.*`, 사전이 없으면 한국어 기본값). `@ihabdevteam/core/components` 에서 나온다 —
+`ConfirmPopup` 을 그리므로 그 곁이 제자리다(CONSUMING.md 2-1).
+
+**`isPersonalPhone` · `PERSONAL_PHONE_REGEX`** — 두 앱이
+`isValidPhone(phone) && phone.startsWith('0')` 을 한 벌씩 들고 있었다. 뜻은 "대표번호는 안 받는다"
+인데 **`'0'` 으로 시작하는가**로 적혀 있었고, 그 둘이 지금 같은 것은 비-0 갈래가 대표번호
+하나뿐이라서일 뿐이다 — 0 으로 시작하지 않는 대역이 하나 더 생기면 두 앱이 **조용히 그것을 받는다.**
+`PHONE_REGEX` 를 개인번호·대표번호 두 조각으로 갈라 적고, 좁은 자는 앞 조각만 쓴다. 새 대역은
+한 곳에만 더하면 둘이 함께 받는다(예전에 `050X`·`0303` 을 손으로 따라 고친 이력이 있다).
+
+> **지금 이 자를 부르는 데는 없다.** 청한 쪽에서 제품 판단이 반대로 나(2026-09-27, 사장님 —
+> "두 앱 다 대표번호를 받는다") 말귀 두 앱은 `0` 으로 시작하는 한 줄을 걷고 `isValidPhone` 을
+> 그대로 쓴다. 그래도 남겨 둔다 — 정규식을 두 조각으로 가른 것 자체가 값이고(새 대역이 한쪽에만
+> 들어오면 시험이 차집합에서 잡는다), "사람에게 거는 번호만" 받아야 하는 칸이 생기면 그 자가
+> 제자리에 있다. **죽은 코드가 아니라 아직 안 부르는 것이다.**
+
+**사전에 더한 것** — `common.discardConfirm.title` · `.body` · `.confirm`(ko · en).
+
+### 더해짐 — `useListControls`
+
+목록 화면 셋이 같은 다섯 줄을 손으로 엮고 있었다(어드민 문장 자료 · 어드민 낱말 자료 ·
+회원앱 낱말 관리). `usePagedList` 를 코어로 올린 까닭이 한 겹 위에서 그대로 되풀이된 자리다.
+
+```tsx
+import { useListControls, usePagedList } from '@ihabdevteam/core/hooks'
+
+const 목록 = useListControls({ resetOn: [보기] })   // 검색어·쪽크기는 훅이 스스로 넣는다
+const 걸러낸것 = useMemo(() => 거르기(줄들, 목록.query, 보기), [줄들, 목록.query, 보기])
+const { pageItems, totalPages, curPage } = usePagedList(걸러낸것, 목록.perPage, 목록.page)
+```
+
+**막는 것은 조용히 틀어지는 쪽이다.** 되돌림 열쇠에서 한 조각만 빠지면 — 이를테면 쪽크기 —
+25에서 100으로 바꿔도 `page` 가 7에 머문다. 총 쪽수가 2로 줄어 `usePagedList` 가 마지막
+쪽으로 조이니 **2쪽이 뜨는데 사람은 1쪽을 본다고 믿는다.** 오류도 빈 화면도 아니고 엉뚱한
+쪽이라 아무도 못 알아챈다. 그래서 검색어와 쪽크기는 부르는 쪽이 적는 것이 아니라 **훅이
+스스로 넣는다** — 적지 않은 것은 빠뜨릴 수도 없다. 쪽크기 기본값(`'25'`)도 여기가 쥔다
+(화면마다 `Number(pageSize) || 25` 가 한 벌씩 있었다).
+
+`resetOn` 은 **글·수·참거짓만** 받는다. 객체를 넣으면 `String()` 이 모두 `[object Object]` 로
+만들어 열쇠가 영영 안 바뀌는데 아무 데서도 안 터진다 — 타입으로 막는다.
+
+**거르고 세우는 일은 안 맡는다.** 세 화면의 잣대가 서로 다르고, 그 일을 훅 안에 넣으면
+부르는 쪽의 `useMemo` 가 사라진다 — 그중 한 화면은 23,000개를 세운다. 그래서 두 걸음이고,
+그 사이가 곧 `useMemo` 가 설 자리다.
+
+## 0.200.0
+
+### 더해짐 — `ItemActions`
+
+무언가를 **보여 주는 창**이 동시에 **그것을 손대는 자리**이기도 한 곳이 회원앱에 셋인데
+(훈련 묶음 실행 · 단어훈련 카드 실행 · 단어표 미리보기), 바닥 줄 왼쪽이 **같은 다섯 단추 ·
+같은 차례 · 같은 규칙**이었다. 벌리는 일은 이미 코어 몫이고(0.190.0 `footerStart`/`footerEnd`),
+남아 있던 **무엇을 어떤 차례로 세우고 무엇을 닫고 하는가**가 세 곳에 베껴져 있었다.
+
+```tsx
+import { ItemActions } from '@ihabdevteam/core/components'
+
+<Popup
+  title={표.name}
+  footerStart={({ closeWithAnimation }) => (
+    <ItemActions
+      onClose={closeWithAnimation}
+      edit={{ label: 이름표.수정, onClick: () => openEdit(표) }}
+      duplicate={{ label: 이름표.복제, onClick: () => duplicate(표) }}
+      publish={{ published: 표.isPublished,
+        publish:   { label: 이름표.올리기, onClick: () => publish(표) },
+        unpublish: { label: 이름표.내리기, onClick: () => unpublish(표) } }}
+      copyLink={링크길있나 ? { label: 이름표.링크, onClick: () => copyLink(표) } : undefined}
+      remove={{ label: 이름표.삭제, onClick: () => askDelete(표) }} />
+  )} />
+```
+
+코어가 쥐는 것 넷 —
+
+- **차례와 꼴**: 고치기 · 복제 · 발행 · 링크 · 지우기, 모두 `size={40} type="dot"`, 사이 8px.
+- **닫고 할 것과 안 닫고 할 것**: 고치기 · 지우기만 `onClose` 를 먼저 부른다. 둘 다 다른 창을
+  여는 일이라 안 닫으면 창 위에 창이 겹치고, 지운 것을 계속 보고 있게 된다.
+- **안 준 것은 안 세운다** — 부르는 쪽이 손으로 `&&` 하던 자리다.
+- **뒤집히는 단추는 하나** — `publish.published` 가 올리기/내리기를 고른다. 아이콘은 같다.
+
+**갈라진 자리가 실제로 있었다**: 링크 단추가 두 곳은 손잡이가 있을 때만 서는데 한 곳은 늘 섰다
+(말귀 실측 2026-09-26). 이런 어긋남은 아무도 안 넘어뜨리고 그 창의 짝 시험만 조용히 다르다.
+
+아무 단추나 끼울 구멍은 두지 않았다 — 그 구멍으로 들어온 단추는 닫고 할지를 또 부르는 쪽이
+정하게 되어, 이 조각이 걷어낸 갈라짐이 그대로 돌아온다. 새 갈래는 여기에 제 칸을 만든다.
+
+**코어가 가져가는 CSS 클래스 이름** — `item-actions`. 말귀 `.my-word-table-preview-actions`
+(`display:flex; align-items:center; gap:var(--spacing-xs); flex-wrap:wrap`)가 이 줄과 같은 값이라,
+갈아탄 뒤에는 그 규칙을 걷을 수 있다.
+
+### 고침 — 접힌 레일의 두 가지 (말귀 ⑮ · ⑯, 사장님 지시 2026-09-26)
+
+태블릿 폭(768–1023)에서 레일은 **두 모양**이다 — 접힌 72px 과, 호버·포커스로 펼친 220px.
+그 갈림을 안 보고 있던 자리 둘을 고친다.
+
+**짧은 구분선이 2px 오른쪽에 서 있었다.** `.side-nav__separator--short` 는 `margin: 4px 16px` 에
+명시 폭(24px)을 가진 플렉스 항목이라 `stretch` 가 안 먹고 **시작 모서리**로 떨어진다 —
+52px 목록 안에서 중심이 38 이고, 레일·항목·아이콘 중심은 모두 36 이었다(실측). 가로도
+`16 + 24 + 16 = 56` 이라 오른쪽 여백 4px 이 잘렸다. 접힌 레일에서만 좌우 여백을 `auto` 로
+바꿔 가운데로 민다. **펼치면 원래대로 돌아온다** — 16px 은 눈대중이 아니라 **아이콘 왼쪽
+모서리에 줄을 맞춘 값**이고(220px 레일 실측: 목록 x=482 · 아이콘 x=498 · 선 x=498),
+넓은 화면(≥1024)은 건드리지 않았다.
+
+**펼친 레일의 BI 가 심볼 그대로였다.** `BrandIdentity` 가 화면 폭만 보고 심볼이냐 로고냐를
+갈랐는데, 그 폭에서 펼친 220px 은 넓은 화면과 **같은 폭**이라 같은 레일이 같은 폭에서 다른
+얼굴을 했다. 펼침은 `:hover`·`:focus-within` 이라 **CSS 만 아는 상태**이고 JS 로는 `img` 의
+`src` 를 못 바꾼다 — 그래서 **둘을 다 그려 두고 고르는 것을 CSS 에 넘긴다.** 안 보이는 쪽은
+`display: none` 이라 낭독기도 안 읽어, `alt` 를 둘 다 둬도 한 번만 읽힌다.
+둘 다 **못 박아 접어 둔 레일**(`.header--force-collapsed`)에서는 호버해도 안 펼쳐지므로
+접힌 얼굴 그대로다.
+
+**코어가 가져가는 CSS 클래스 이름** — `brand-identity__image--symbol` · `brand-identity__image--logo`.
+`BrandIdentity` 의 마크업이 `img` 한 장에서 **두 장**으로 바뀌었다(`.brand-identity__image` 를
+선택자로 쓰는 자리가 있으면 이제 둘을 집는다 — 말귀 두 앱에는 그런 자리가 없다, 실측).
+
+> 브라우저로 이 폭을 잴 때는 `* { transition: none !important }` 를 먼저 얹는다. 레일 폭에
+> 180ms 전이가 걸려 있어, 안 얹으면 전이 중간 값이 잡혀 **멀쩡한 규칙을 어긋난 것으로 읽는다**
+> (여기서 한 번 그렇게 속았다 — `force-collapsed:hover` 가 안 먹는 줄 알았는데 먹고 있었다).
+
+### 고침 — 발치 줄의 알림 단추만 따로 놀았다 (말귀 ⑰)
+
+`.side-nav__notification-wrap` 은 **배지를 얹으려고 알림 단추에만 두른 한 겹**인데, 거기 붙어
+있던 `align-self: flex-start` 가 접힌 레일 발치 줄의 `align-items: center` 를 덮어 **혼자
+왼쪽에 붙었다**(말귀 실측: 넷은 가운데 36, 이것만 30). 단추가 동그라미라 다섯이 한 줄로 서면
+하나 틀어진 것이 바로 보인다. 어긋남은 `(줄 폭 − 단추 폭) / 2` 라 단추 크기에 따라 4~6px 이다.
+
+**`align-self` 만 걷으면 다른 데가 틀어진다** — 펼친 줄은 `align-items: stretch` 라 그 span 이
+1440px 에서 **194px** 까지 늘어난다(실측). 단추는 48 그대로라 눈에는 같지만 **줄 전체가 알림
+단추의 몸**이 되어 빈 자리에서도 호버·클릭이 걸린다. `width: fit-content` 를 함께 둔다 —
+definite width 가 stretch 를 막는다. 768·1440 둘 다 다섯이 한 줄로 선다.
+
+### 글 고침 — 놀이터가 안 적고 있던 공개 이름 일곱
+
+`audit:playground` 의 대응표가 **일곱 자리 비어 있었다**(`GameIntro` · `LineChart` ·
+`LINE_CHART_HOVER_DELAY_MS` · `SectionHeadFloat` · `prefetchChunk` · `toWordEntry` ·
+`usePageResetOnChange`). 0.186~0.199 에서 들인 것들이고, 그 문은 `npm test` 에 안 들어 있어
+조용했다. 일곱을 채우고, 글이 없던 셋(`SectionHeadFloat` · `toWordEntry` ·
+`LINE_CHART_HOVER_DELAY_MS`)에는 쓰는 법을 적었다.
+
 ## 0.199.0
 
 ### 더해짐 — `toWordEntry` · `WordRow`