@x-plat/design-system 0.12.0 → 0.13.0

package/dist/index.js

@@ -5622,11 +5622,11 @@ var FieldMessage = (props) => {
 FieldMessage.displayName = "FieldMessage";
 var FieldMessage_default = FieldMessage;
 var Field = (props) => {
-  const { label, required = false, htmlFor, validations, children } = props;
+  const { label, required = false, htmlFor, labelId, validations, children } = props;
   const hasMessages = !!validations && validations.length > 0;
   if (!label && !hasMessages) return /* @__PURE__ */ jsx297(Fragment, { children });
   return /* @__PURE__ */ jsxs191("div", { className: "lib-xplat-field", children: [
-    label && /* @__PURE__ */ jsxs191("label", { className: "lib-xplat-field-label", htmlFor, children: [
+    label && /* @__PURE__ */ jsxs191("label", { className: "lib-xplat-field-label", id: labelId, htmlFor, children: [
       label,
       required && /* @__PURE__ */ jsx297("span", { className: "required", "aria-hidden": "true", children: "*" })
     ] }),
@@ -7406,8 +7406,12 @@ var SingleDatePicker = (props) => {
     highlightDates = [],
     locale = "ko",
     rangeStart,
-    rangeEnd
+    rangeEnd,
+    label,
+    required,
+    validations
   } = props;
+  const labelId = React12.useId();
   const initialYear = value?.getFullYear();
   const initialMonth = value?.getMonth();
   const { year, month, days, goToPrevMonth, goToNextMonth, setYear, setMonth } = useCalendar(
@@ -7470,10 +7474,12 @@ var SingleDatePicker = (props) => {
   const monthLabels = MONTH_LABELS[locale];
   const titleText = pickerMode === "days" ? locale === "ko" ? `${year}\uB144 ${monthLabels[month]}` : `${monthLabels[month]} ${year}` : pickerMode === "months" ? `${year}` : `${yearRangeStart} - ${yearRangeStart + 11}`;
   const hasRange = rangeStart != null && rangeEnd != null;
-  return /* @__PURE__ */ jsxs200(
+  const calendar = /* @__PURE__ */ jsxs200(
     "div",
     {
       className: clsx_default("lib-xplat-datepicker", "single"),
+      role: "group",
+      "aria-labelledby": label ? labelId : void 0,
       children: [
         /* @__PURE__ */ jsxs200("div", { className: "datepicker-header", children: [
           /* @__PURE__ */ jsx314("button", { className: "datepicker-nav", onClick: handlePrev, type: "button", children: /* @__PURE__ */ jsx314(ChevronLeftIcon_default, {}) }),
@@ -7494,18 +7500,18 @@ var SingleDatePicker = (props) => {
               y
             );
           }) }),
-          pickerMode === "months" && /* @__PURE__ */ jsx314("div", { className: "datepicker-picker-grid", children: monthLabels.map((label, i) => /* @__PURE__ */ jsx314(
+          pickerMode === "months" && /* @__PURE__ */ jsx314("div", { className: "datepicker-picker-grid", children: monthLabels.map((label2, i) => /* @__PURE__ */ jsx314(
             "button",
             {
               type: "button",
               className: clsx_default("datepicker-picker-cell", i === month && "active"),
               onClick: () => handleMonthSelect(i),
-              children: label
+              children: label2
             },
             i
           )) }),
           pickerMode === "days" && /* @__PURE__ */ jsxs200(Fragment4, { children: [
-            /* @__PURE__ */ jsx314("div", { className: "datepicker-weekdays", children: weekdays.map((label, i) => /* @__PURE__ */ jsx314(
+            /* @__PURE__ */ jsx314("div", { className: "datepicker-weekdays", children: weekdays.map((label2, i) => /* @__PURE__ */ jsx314(
               "div",
               {
                 className: clsx_default(
@@ -7513,9 +7519,9 @@ var SingleDatePicker = (props) => {
                   i === 0 && "sunday",
                   i === 6 && "saturday"
                 ),
-                children: label
+                children: label2
               },
-              label
+              label2
             )) }),
             /* @__PURE__ */ jsx314("div", { className: "datepicker-grid", children: days.map((day, idx) => {
               const t = day.date.getTime();
@@ -7547,6 +7553,7 @@ var SingleDatePicker = (props) => {
       ]
     }
   );
+  return /* @__PURE__ */ jsx314(Field, { label, required, labelId, validations, children: calendar });
 };
 SingleDatePicker.displayName = "SingleDatePicker";
 var SingleDatePicker_default = SingleDatePicker;
@@ -7561,7 +7568,18 @@ var formatDate = (date) => {
   return `${y}/${m}/${d}`;
 };
 var InputDatePicker = (props) => {
-  const { value, onChange, minDate, maxDate, disabled, locale = "ko", placeholder } = props;
+  const {
+    value,
+    onChange,
+    minDate,
+    maxDate,
+    disabled,
+    locale = "ko",
+    placeholder,
+    label,
+    required,
+    validations
+  } = props;
   const [isOpen, setIsOpen] = React13.useState(false);
   const [tempDate, setTempDate] = React13.useState(value ?? /* @__PURE__ */ new Date());
   const handleOpen = () => {
@@ -7587,6 +7605,9 @@ var InputDatePicker = (props) => {
         placeholder,
         suffix: /* @__PURE__ */ jsx315(CalenderIcon_default, {}),
         disabled,
+        label,
+        required,
+        validations,
         readOnly: true
       }
     ) }),
@@ -7718,8 +7739,12 @@ var RangePicker = (props) => {
     onChange,
     minDate,
     maxDate,
-    locale = "ko"
+    locale = "ko",
+    label,
+    required,
+    validations
   } = props;
+  const labelId = React16.useId();
   const [activeTab, setActiveTab] = React16.useState("start");
   const handleStartChange = (date) => {
     if (!date) return;
@@ -7733,70 +7758,79 @@ var RangePicker = (props) => {
   };
   const startMaxDate = maxDate && endDate < maxDate ? endDate : endDate;
   const endMinDate = minDate && startDate > minDate ? startDate : startDate;
-  return /* @__PURE__ */ jsxs203("div", { className: clsx_default("lib-xplat-datepicker", "range"), children: [
-    /* @__PURE__ */ jsx318("div", { className: "datepicker-range-tabs", children: /* @__PURE__ */ jsx318(
-      Tab_default,
-      {
-        activeIndex: activeTab === "start" ? 0 : 1,
-        tabs: [
-          { value: "start", title: locale === "ko" ? "\uC2DC\uC791\uC77C" : "Start" },
-          { value: "end", title: locale === "ko" ? "\uC885\uB8CC\uC77C" : "End" }
-        ],
-        onChange: (tab) => setActiveTab(tab.value),
-        type: "toggle",
-        size: "sm"
-      }
-    ) }),
-    /* @__PURE__ */ jsxs203("div", { className: "datepicker-range-panels", children: [
-      /* @__PURE__ */ jsx318(
-        SingleDatePicker_default,
-        {
-          value: startDate,
-          onChange: handleStartChange,
-          minDate,
-          maxDate: startMaxDate,
-          rangeStart: startDate,
-          rangeEnd: endDate,
-          locale
-        }
-      ),
-      /* @__PURE__ */ jsx318(
-        SingleDatePicker_default,
-        {
-          value: endDate,
-          onChange: handleEndChange,
-          minDate: endMinDate,
-          maxDate,
-          rangeStart: startDate,
-          rangeEnd: endDate,
-          locale
-        }
-      )
-    ] }),
-    /* @__PURE__ */ jsx318("div", { className: "datepicker-range-mobile", children: activeTab === "start" ? /* @__PURE__ */ jsx318(
-      SingleDatePicker_default,
-      {
-        value: startDate,
-        onChange: handleStartChange,
-        minDate,
-        maxDate: startMaxDate,
-        rangeStart: startDate,
-        rangeEnd: endDate,
-        locale
-      }
-    ) : /* @__PURE__ */ jsx318(
-      SingleDatePicker_default,
-      {
-        value: endDate,
-        onChange: handleEndChange,
-        minDate: endMinDate,
-        maxDate,
-        rangeStart: startDate,
-        rangeEnd: endDate,
-        locale
-      }
-    ) })
-  ] });
+  const calendar = /* @__PURE__ */ jsxs203(
+    "div",
+    {
+      className: clsx_default("lib-xplat-datepicker", "range"),
+      role: "group",
+      "aria-labelledby": label ? labelId : void 0,
+      children: [
+        /* @__PURE__ */ jsx318("div", { className: "datepicker-range-tabs", children: /* @__PURE__ */ jsx318(
+          Tab_default,
+          {
+            activeIndex: activeTab === "start" ? 0 : 1,
+            tabs: [
+              { value: "start", title: locale === "ko" ? "\uC2DC\uC791\uC77C" : "Start" },
+              { value: "end", title: locale === "ko" ? "\uC885\uB8CC\uC77C" : "End" }
+            ],
+            onChange: (tab) => setActiveTab(tab.value),
+            type: "toggle",
+            size: "sm"
+          }
+        ) }),
+        /* @__PURE__ */ jsxs203("div", { className: "datepicker-range-panels", children: [
+          /* @__PURE__ */ jsx318(
+            SingleDatePicker_default,
+            {
+              value: startDate,
+              onChange: handleStartChange,
+              minDate,
+              maxDate: startMaxDate,
+              rangeStart: startDate,
+              rangeEnd: endDate,
+              locale
+            }
+          ),
+          /* @__PURE__ */ jsx318(
+            SingleDatePicker_default,
+            {
+              value: endDate,
+              onChange: handleEndChange,
+              minDate: endMinDate,
+              maxDate,
+              rangeStart: startDate,
+              rangeEnd: endDate,
+              locale
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx318("div", { className: "datepicker-range-mobile", children: activeTab === "start" ? /* @__PURE__ */ jsx318(
+          SingleDatePicker_default,
+          {
+            value: startDate,
+            onChange: handleStartChange,
+            minDate,
+            maxDate: startMaxDate,
+            rangeStart: startDate,
+            rangeEnd: endDate,
+            locale
+          }
+        ) : /* @__PURE__ */ jsx318(
+          SingleDatePicker_default,
+          {
+            value: endDate,
+            onChange: handleEndChange,
+            minDate: endMinDate,
+            maxDate,
+            rangeStart: startDate,
+            rangeEnd: endDate,
+            locale
+          }
+        ) })
+      ]
+    }
+  );
+  return /* @__PURE__ */ jsx318(Field, { label, required, labelId, validations, children: calendar });
 };
 RangePicker.displayName = "RangePicker";
 var RangePicker_default = RangePicker;
@@ -9569,10 +9603,13 @@ var FileUpload = (props) => {
     multiple = false,
     maxSize,
     onChange,
-    label = "\uD30C\uC77C\uC744 \uB4DC\uB798\uADF8\uD558\uAC70\uB098 \uD074\uB9AD\uD558\uC5EC \uC5C5\uB85C\uB4DC",
+    placeholder = "\uD30C\uC77C\uC744 \uB4DC\uB798\uADF8\uD558\uAC70\uB098 \uD074\uB9AD\uD558\uC5EC \uC5C5\uB85C\uB4DC",
     description,
-    validations
+    validations,
+    label,
+    required
   } = props;
+  const fieldId = React23.useId();
   const [isDragOver, setIsDragOver] = React23.useState(false);
   const inputRef = React23.useRef(null);
   const handleFiles = (fileList) => {
@@ -9617,6 +9654,7 @@ var FileUpload = (props) => {
           "input",
           {
             ref: inputRef,
+            id: fieldId,
             type: "file",
             accept,
             multiple,
@@ -9625,12 +9663,12 @@ var FileUpload = (props) => {
           }
         ),
         /* @__PURE__ */ jsx325("div", { className: "upload-icon", children: /* @__PURE__ */ jsx325(UploadIcon_default, {}) }),
-        /* @__PURE__ */ jsx325("p", { className: "upload-label", children: label }),
+        /* @__PURE__ */ jsx325("p", { className: "upload-label", children: placeholder }),
         description && /* @__PURE__ */ jsx325("p", { className: "upload-description", children: description })
       ]
     }
   );
-  return /* @__PURE__ */ jsx325(Field, { validations, children: control });
+  return /* @__PURE__ */ jsx325(Field, { label, required, htmlFor: fieldId, validations, children: control });
 };
 FileUpload.displayName = "FileUpload";
 var FileUpload_default = FileUpload;
@@ -9773,7 +9811,8 @@ var HtmlTypeWriter_default = HtmlTypeWriter;
 import React26 from "react";
 import { jsx as jsx327, jsxs as jsxs210 } from "react/jsx-runtime";
 var ImageSelector = (props) => {
-  const { value, label, onChange, validations } = props;
+  const { value, placeholder, onChange, validations, label, required } = props;
+  const fieldId = React26.useId();
   const [previewUrl, setPreviewUrl] = React26.useState();
   React26.useEffect(() => {
     if (!value) {
@@ -9803,7 +9842,7 @@ var ImageSelector = (props) => {
       {
         type: "file",
         accept: "image/*",
-        id: "image-input",
+        id: fieldId,
         onChange: handleFileChange,
         ref: inputRef,
         "aria-invalid": hasError(validations) || void 0
@@ -9815,10 +9854,10 @@ var ImageSelector = (props) => {
     ] }),
     /* @__PURE__ */ jsx327("div", { className: "content", children: previewUrl ? /* @__PURE__ */ jsx327("img", { src: previewUrl, alt: "preview" }) : /* @__PURE__ */ jsxs210("div", { className: "skeleton", onClick: handleOpenFileDialog, children: [
       /* @__PURE__ */ jsx327("div", { className: "icon-wrapper", children: /* @__PURE__ */ jsx327(ImageIcon_default, {}) }),
-      /* @__PURE__ */ jsx327("div", { className: "label", children: label || "\uC774\uBBF8\uC9C0 \uCD94\uAC00\uD558\uAE30" })
+      /* @__PURE__ */ jsx327("div", { className: "label", children: placeholder || "\uC774\uBBF8\uC9C0 \uCD94\uAC00\uD558\uAE30" })
     ] }) })
   ] });
-  return /* @__PURE__ */ jsx327(Field, { validations, children: control });
+  return /* @__PURE__ */ jsx327(Field, { label, required, htmlFor: fieldId, validations, children: control });
 };
 ImageSelector.displayName = "ImageSelector";
 var ImageSelector_default = ImageSelector;

package/guidelines/Guidelines.md

@@ -74,3 +74,15 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
 4. **컴포지션**
    - [Grid](./composition/grid.md) - Grid 시스템, 위젯 패턴
    - [Layout](./composition/layout.md) - Layout, Header, SideBar
+
+---
+
+## 버전을 올릴 때
+
+[마이그레이션 노트](./MIGRATION.md) — 0.5.x 이후 **실제로 깨지는 것만** 버전별로
+모아 뒀다. 자기 버전부터 아래로 읽으면 된다.
+
+- 최신본: `https://unpkg.com/@x-plat/design-system/guidelines/MIGRATION.md`
+- 커밋 제목만 보고 판단하지 말 것. `refactor!` 인데 별칭이 살아 있어 안 깨지는
+  것이 있고, 평범한 `refactor` 인데 prop 이 사라진 것이 있다.
+

package/guidelines/MIGRATION.md

@@ -0,0 +1,270 @@
+# @x-plat/design-system — 마이그레이션 노트
+
+버전을 올릴 때 **실제로 깨지는 것만** 모았다. 추가된 기능은 여기 적지 않는다 —
+그건 각 컴포넌트 문서에 있다.
+
+- 최신본 URL: `https://unpkg.com/@x-plat/design-system/guidelines/MIGRATION.md`
+- 자기 버전부터 아래로 읽어 내려가면 된다.
+
+## 이 문서를 믿어도 되는 범위
+
+각 항목은 **커밋 해시**를 달아 뒀다. 커밋 제목만 보고 판단하지 말 것 —
+`refactor!` 라고 외치지만 별칭이 살아 있어 안 깨지는 것이 있고(0.7.1 `Badge`),
+평범한 `refactor` 인데 prop 이 사라진 것이 있다(0.8.0 `Button`).
+
+「실제로 걸린 것」 표는 진짜 이관에서 확인된 것이고, 나머지는 소스에서 확인한 것이다.
+
+---
+
+## 0.5.x → 0.6.0 — CSS 변수 이름 전면 교체
+
+**`92dac35` · 가장 큰 변경이다.** Figma 변수 컬렉션 구조에 맞춰 컬러 레이어를
+4단계에서 3단계로 줄이면서 semantic 이름을 전부 바꿨다.
+
+`var(--semantic-*)` 를 직접 쓰는 CSS 가 있으면 **조용히 깨진다** — 정의되지 않은
+변수는 오류를 내지 않고 색만 사라진다. 이관 후 화면을 눈으로 확인할 것.
+
+| 예전 | 지금 |
+|---|---|
+| `--semantic-*-strong` | `--semantic-*-primary` |
+| `--semantic-*-subtle` | `--semantic-*-secondary` |
+| `--semantic-*-muted` | `--semantic-*-tertiary` |
+| `--semantic-*-brand` | `--semantic-*-brand-primary` |
+| `--semantic-*-sunday` | `--semantic-*-accent-red` |
+| `--semantic-*-saturday` | `--semantic-*-accent-blue` |
+| `--semantic-*-emphasis-*` | 삭제 → `--semantic-surface-*-strong` |
+| `--brand-base-black-alpha-10/25` | `--brand-base-overlay-5/10/25/50/75/85` |
+
+`color/primitive.ts` 가 삭제되고 `brand`/`system` 이 hex 실값을 직접 갖는다.
+`var(--primitive-*)` 를 참조하던 곳은 전부 끊긴다.
+
+**값이 바뀐 것 6건** (이름은 그대로인데 색이 달라진다):
+`text-brand-primary` · `border-brand-primary` · `border-warning` ·
+`surface-info-default` · `icon-success` · `icon-info`.
+`system.link` 는 purple → deep-purple.
+
+> 컴포넌트만 쓰고 CSS 변수를 직접 참조하지 않는다면 이 절은 건너뛰어도 된다.
+
+## 0.6.0 → 0.7.0 — effects · typography 토큰 정합
+
+**`6429909`** 컴포넌트가 하드코딩하던 그림자·폰트를 토큰으로 옮겼다.
+컴포넌트를 그대로 쓰면 영향 없다. 그림자나 폰트 크기를 CSS 로 덮어쓰고 있었다면
+우선순위가 달라질 수 있다.
+
+## 0.7.0 → 0.7.1 — Badge 이름 변경
+
+**`c95ee21` · `6430c9c`**
+
+| 대상 | 깨지나 | 조치 |
+|---|---|---|
+| `import { Badge }` | **안 깨짐** | `Badge` 가 `@deprecated` 별칭으로 계속 나간다. 새로 쓰는 곳만 `NotificationBadge` |
+| CSS 클래스 `.lib-xplat-badge` | **깨짐** | `.lib-xplat-notification-badge` 로. 별칭 없음 |
+
+**`NotificationBadge` 는 알약(pill) 라벨이 아니다.** 아이콘 위에 올라타는 개수
+인디케이터다. `count` 도 `dot` 도 없으면 **뱃지가 렌더되지 않고 children 만 통과한다.**
+
+```tsx
+<Badge type="error">품절</Badge>        // ✗ 아무것도 안 그려지고 "품절" 만 나온다
+<NotificationBadge count={3}><BellIcon /></NotificationBadge>   // ○
+```
+
+알약 라벨이 필요하면 `Tag` 를 쓴다. 이 오용은 이름이 바뀌기 전부터 조용히
+실패하고 있었으므로, 올리기 전에 `<Badge>` 사용처를 훑어 볼 것.
+
+## 0.7.2 → 0.8.0 — `Button` 이 `<button>` 전용으로 복귀
+
+**`f5668dd` · `0a4ab14` · 실제로 제일 많이 깨지는 항목이다.**
+
+`Button` 은 이제 `<button>` 하나만 렌더한다. `href` prop 이 없다.
+
+```tsx
+<Button href="/about">소개</Button>        // ✗ 더 이상 없다
+<LinkButton href="/about">소개</LinkButton> // ○
+<Link href="/about">소개</Link>             // ○ 본문 안 링크
+```
+
+> ⚠ 커밋 `f5668dd` 에 나오는 **`buttonClass()` 는 쓰지 말 것.** 바로 다음 커밋
+> `0a4ab14` 에서 `LinkButton` 으로 대체됐고 지금 소스에 없다(export 0건).
+> 커밋을 순서대로 훑다 보면 유효한 경로로 오해하기 쉽다.
+
+## 0.8.0 → 0.8.1 — 오버레이가 항상 `document.body` 로 portal
+
+**`17004e7`** Modal · Select · Dropdown · PopOver · TimePicker 의 팝업이 조상
+DOM 이 아니라 항상 `body` 로 들어간다. 조상에 `transform`/`filter`/`will-change`/
+`contain` 이 있으면 `position: fixed` 의 기준이 그 조상으로 바뀌어 오버레이가
+엉뚱한 자리에 뜨던 것을 고친 것이다.
+
+**오버레이를 조상 기준으로 위치 잡는 CSS 가 있으면 깨진다.** 그런 CSS 는 지워야 한다 —
+위치는 DS 가 계산한다.
+
+## 0.8.1 → 0.8.2 — `modal-box` 에 `position: relative`
+
+**`c3611ee`** 0.8.1 에서 모달의 `transform` 을 걷어내면서 모달 **안쪽**
+`position: absolute` 요소들의 기준이 모달이 아니라 화면 전체(`.dim`)로 튀었다.
+그 회귀를 되돌린 것이다. 0.8.1 을 건너뛰고 0.8.2 이상으로 올리면 겪지 않는다.
+
+## 0.8.3 → 0.9.0 — 폼 검증 API 가 `validations` 로 통일
+
+**`6e64fbc`** 컴포넌트마다 제각각이던 에러 표시 방식을 하나로 모았다.
+**추가이므로 기존 코드를 깨지 않는다.** 다만 이제 직접 그릴 필요가 없다.
+
+```tsx
+validations?: { status: "error" | "warning" | "success" | "default"; message: string }[]
+```
+
+- 렌더는 `FieldMessage` 가 전담한다. 아이콘·색·간격이 DS 전체에서 같아진다.
+- `aria-invalid` 도 DS 가 붙인다 — 직접 붙이던 코드는 걷어낼 것.
+- `hasError(validations)` 가 배럴에서 나간다.
+- `Input/InputValidations` 는 **삭제됐다.** 직접 import 하던 곳이 있으면 끊긴다.
+
+`Select.error?: boolean` 은 하위호환으로 남아 있다. `validations` 와 OR 로
+합쳐지므로 둘 다 써도 되지만, 새로 쓰는 곳은 `validations` 를 쓴다.
+
+## 0.9.0 → 0.10.0 — `type` = 상태색 / `variant` = 모양 변형
+
+**`12f4319`** 한 컴포넌트에서 `type` 이 색을 뜻하기도 하고 모양을 뜻하기도 하던
+것을 두 축으로 갈랐다. **별칭이 살아 있어 깨지지 않는다.**
+
+| 축 | prop | 값 |
+|---|---|---|
+| 상태 색 | `type` | `primary` `success` `error` `warning` `info` |
+| 모양 변형 | `variant` | 컴포넌트마다 다름 |
+
+- 모양 변형을 `type` 으로 주던 곳(`Tooltip` `Chart` `Tab` `Tag`)은 `variant` 로
+  옮기는 게 맞지만, `variant ?? type ?? 기본값` 으로 받으므로 **지금 동작한다.**
+- `type="brand"` → `type="primary"`. `normalizeStatus()` 가 `brand` 를 계속 받는다.
+
+**별칭 제거 시점은 아직 정해지지 않았다.** 업그레이드와 무관한 diff 를 섞기
+싫으면 나중에 한 번에 정리해도 된다. 제거가 정해지면 이 문서에 적는다.
+
+## 0.10.0 → 0.11.0 — 폼 컨트롤에 `label` / `required`
+
+**`9f7700d` · 추가지만 기존 마크업과 겹칠 수 있다.**
+
+`Field` 가 **진짜 `<label htmlFor>` 를 그린다.** 바깥에서 `<label>` 로 감싸던
+코드에 DS 의 `label` prop 을 같이 주면 `<label>` 안에 `<label>` 이 들어간다 —
+유효하지 않은 HTML 이고, 클릭 시 포커스가 어디로 갈지 브라우저마다 다르다.
+
+> **「DS `label` 도입」과 「기존 `<label>` 제거」는 같은 커밋에 넣을 것.**
+> 한쪽만 하면 중첩되거나 라벨이 사라진다.
+
+같이 걷어낼 것:
+
+- `htmlFor` / `id` — DS 가 `React.useId()` 로 만들어 잇는다. 직접 넘길 필요 없다.
+- `aria-invalid` — DS 가 붙인다.
+
+`Field` 는 **붙일 게 없으면 래퍼를 만들지 않고 `children` 을 그대로 통과시킨다.**
+안 쓰는 곳의 DOM 은 늘지 않으므로 그대로 둬도 된다.
+
+## 0.11.0 → 0.12.0 — Editor 확충
+
+**`7bf563f` · `97e668c` · 추가만 있다.** 되돌리기/다시하기, 표, 체크리스트,
+정렬, 문법 강조, 형광펜, 위/아래 첨자가 들어갔다.
+
+**저장된 HTML 을 직접 다루는 쪽은 허용 태그 목록을 갱신해야 한다.**
+저장 값에 표·체크리스트·`mark`·`sub`/`sup` 이 새로 나타난다. 태그 목록을
+직접 들고 있다면(예: "이 값이 HTML 인가" 판별) 아래 **31개를 그대로** 복사할 것.
+
+```
+p br div span
+h1 h2 h3 h4 h5 h6
+ul ol li
+blockquote pre code
+strong b em i u s strike del
+a img hr
+sub sup mark
+table thead tbody tr th td
+```
+
+주의할 점 둘:
+
+- **`b` `i` `u` `strike` 는 옛날 태그가 아니라 평상시 출력이다.** DS 는
+  `styleWithCSS` 를 켜지 않으므로 브라우저 `execCommand` 가 `<strong>` 이 아니라
+  `<b>` 를 낸다. 굵게 쓴 글이 흔하므로 이게 빠지면 자주 밟힌다.
+- **`input` 은 필요 없다.** 체크리스트는 `<li data-checked>` + CSS `::before` 로
+  그린다. `<input>` 은 한 번도 나오지 않는다.
+
+허용 목록은 `Editor.tsx` 안의 상수이고 prop 으로 열려 있지 않다. 버전을 올리면
+따라온다. `readOnly` 로 그릴 때도 같은 태그가 전부 나온다 — sanitize 경로와
+스타일이 편집 모드와 같다.
+
+HTML 을 검색 색인에 넣는다면 **닫는 태그를 공백이나 줄바꿈으로 치환**할 것.
+`</td>` `</th>` `</tr>` `</li>` `</p>` `</h1>`~`</h6>` `</blockquote>` `<br>` 을
+그냥 지우면 칸 글자가 붙어 `가격수량` 같은 낱말이 생긴다.
+
+## 0.12.0 → 0.13.0 — `FileUpload` / `ImageSelector` 의 `label` 뜻이 바뀜
+
+**깨진다. 그런데 타입 오류가 나지 않는다 — 글자 위치만 바뀐다.**
+
+이 둘의 `label` 은 DS 안에서 혼자 다른 뜻이었다. 다른 폼 컨트롤에서는 컨트롤
+**위**에 붙는 필드 라벨인데, 여기서는 상자 **안**에 찍히는 안내 문구였다.
+그 문구를 `placeholder` 로 옮기고 `label` 을 필드 라벨로 되돌렸다.
+
+```tsx
+// 0.12.0 이하
+<FileUpload label="파일을 드래그하거나 클릭하여 업로드" />
+
+// 0.13.0 — 같은 화면을 얻으려면
+<FileUpload placeholder="파일을 드래그하거나 클릭하여 업로드" />
+
+// 이제 가능해진 것
+<FileUpload label="첨부파일" required placeholder="끌어다 놓으세요" />
+```
+
+`label` 을 그대로 두면 **그 글자가 상자 안이 아니라 상자 위 라벨로 올라간다.**
+`label?: string` 에서 `label?: React.ReactNode` 로 넓어졌으므로 기존 문자열도
+타입은 통과한다. `grep -rn 'FileUpload\|ImageSelector'` 로 훑어 `label=` 이 있는
+곳을 `placeholder=` 로 바꾸면 된다.
+
+같이 들어간 것:
+
+- `required` — 라벨 뒤에 `*`
+- `htmlFor` 연결 — 라벨을 클릭하면 파일 선택창이 열린다
+- **`ImageSelector` 의 하드코딩된 `id="image-input"` 제거.** 한 화면에 둘 이상
+  놓으면 DOM id 가 겹치던 버그였다. 이제 `React.useId()` 로 만든다.
+  `#image-input` 을 잡는 CSS 나 테스트 셀렉터가 있으면 끊긴다.
+
+### 같은 릴리스: DatePicker 3종에 `label` / `required` / `validations`
+
+**추가만 있다.** `SingleDatePicker` · `RangeDatePicker` · `InputDatePicker` 가
+다른 폼 컨트롤과 같은 방식으로 라벨·검증을 받는다.
+
+`PopupDatePicker` 와 `Dropdown` 은 받지 않는다 — 전자는 트리거를 `component` 로
+직접 넘기는 구조라 라벨이 가리킬 대상이 없고, 후자는 `role="menu"` 인 액션
+메뉴라 검증할 값이 없다.
+
+---
+
+## 실제 이관에서 걸린 것 / 안 걸린 것
+
+`xplat-shop-templat` (pnpm 모노레포, 워크스페이스 4개) 을 **0.6.1 → 0.12.0** 으로
+올렸을 때의 결과다. DS 를 어댑터 한 곳에서만 쓰는 구조였다.
+
+| 항목 | 결과 | 이유 |
+|---|---|---|
+| `Button` href 제거 | 안 걸림 | `<Button href>` 사용 0곳 |
+| `Badge` → `NotificationBadge` | 안 걸림 | `@deprecated` 별칭으로 통과 |
+| CSS 클래스 rename | 안 걸림 | `.lib-xplat-*` 을 덮어쓰는 CSS 0곳 |
+| 오버레이 body portal | 안 걸림 | 오버레이 기준을 잡는 CSS 없음 |
+| **`label` 중첩** | **걸림** | 어댑터가 `<label htmlFor>` 를 직접 그리고 있었다 |
+
+**목록을 훑기 전에 자기 저장소에서 먼저 세어 볼 것.** 위 표에서 보듯 대부분은
+해당 사항이 없고, 진짜 걸리는 건 한둘이다. `<Button href`, `.lib-xplat-`,
+`<label` 세 가지를 grep 하는 것으로 대부분 판별된다.
+
+결과: 어댑터 241줄 → 216줄, 쓰이지 않던 CSS 30줄 삭제. DS 가 `label`·
+`aria-invalid`·`useId`·검증 메시지를 맡으면서 어댑터가 얇아진다.
+
+---
+
+## 아직 확인되지 않은 것
+
+**Editor 는 브라우저에서 검증되지 않았다.** `contentEditable`·`execCommand`·IME 는
+자동 테스트로 흉내 낼 수 없다. 특히 아래 넷은 직접 눌러 봐야 한다.
+
+- 한글 조합 중 `⌘Z` / `Ctrl+Z`
+- 툴바 서식 버튼
+- 표 안에서 Enter · Backspace
+- 체크박스 클릭 판정
+
+이상이 보이면 재현 조건과 함께 알려 주면 좋겠다.

package/guidelines/components/datepicker.md

@@ -50,6 +50,32 @@ Input + 드롭다운 형태이다.
 />
 ```
 
+## 라벨과 검증
+
+`SingleDatePicker` · `RangeDatePicker` · `InputDatePicker` 는 다른 폼 컨트롤과
+똑같이 `label` · `required` · `validations` 를 받는다.
+
+```tsx
+<InputDatePicker
+  value={date}
+  onChange={setDate}
+  label="계약일"
+  required
+  validations={[{ status: "error", message: "계약일을 선택하세요" }]}
+/>
+```
+
+검증 메시지는 `FieldMessage` 가 그린다 — 아이콘·색·간격이 Input·Select 와 같다.
+직접 `<p>` 로 그리지 말 것.
+
+달력을 펼쳐 놓는 `SingleDatePicker` · `RangeDatePicker` 는 **포커스 대상이 날짜
+칸마다 있어 `htmlFor` 로 하나를 고를 수 없다.** 그래서 `role="group"` +
+`aria-labelledby` 로 라벨과 묶는다. 쓰는 쪽에서 신경 쓸 것은 없다.
+
+`PopupDatePicker` 는 라벨·검증을 받지 않는다 — 트리거를 `component` 로 직접
+넘기는 구조라 라벨이 가리킬 대상이 정해지지 않는다. 라벨이 필요하면 트리거로
+`InputDatePicker` 를 쓰거나 바깥에서 `Field` 로 감싼다.
+
 ---
 
 ## 의사결정