From c9b484e4c81ff5bb80aa22ae3834f5cef55eef4f Mon Sep 17 00:00:00 2001
From: zenn <zenn.message@gmail.com>
Date: Fri, 15 May 2026 18:44:56 +0900
Subject: [PATCH] =?UTF-8?q?v1.2.4:=20=EC=9D=B4=EB=AF=B8=EC=A7=80=20?=
 =?UTF-8?q?=EC=BA=A1=EC=85=98=20=ED=91=9C=EC=8B=9C=20=EC=88=98=EC=A0=95=20?=
 =?UTF-8?q?=EB=B0=8F=20=EB=AF=B8=EB=A6=AC=EB=B3=B4=EA=B8=B0=20=EA=B0=A4?=
 =?UTF-8?q?=EB=9F=AC=EB=A6=AC=20=EB=93=9C=EB=9E=98=EA=B7=B8=20=EC=A0=95?=
 =?UTF-8?q?=EB=A0=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

파일명 alt와 캡션을 분리해 공개·미리보기에 캡션이 보이도록 하고, 관리자 미리보기에서 갤러리 순서를 드래그로 바꿀 수 있게 했다.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 components/admin/AdminMarkdownEditor.vue      |  45 +++++-
 .../content/ContentMarkdownRenderer.vue       | 134 ++++++++++++++++--
 components/content/ProseImage.vue             |  12 +-
 docs/update.md                                |   6 +
 lib/markdown-image.js                         |  29 +++-
 package-lock.json                             |  36 ++---
 package.json                                  |   2 +-
 7 files changed, 224 insertions(+), 40 deletions(-)

diff --git a/components/admin/AdminMarkdownEditor.vue b/components/admin/AdminMarkdownEditor.vue
index 854ca40..844c5fc 100644
--- a/components/admin/AdminMarkdownEditor.vue
+++ b/components/admin/AdminMarkdownEditor.vue
@@ -1,7 +1,7 @@
 <script setup>
 import { normalizeMarkdownContent } from '../../lib/markdown-content-normalizer.js'
 import { resolveActiveBlockContext } from '../../lib/markdown-block-context.js'
-import { serializeImageMarkdown } from '../../lib/markdown-image.js'
+import { getImageDefaultAltLabel, serializeImageMarkdown } from '../../lib/markdown-image.js'
 
 const props = defineProps({
   modelValue: {
@@ -629,7 +629,41 @@ const updateActiveMediaImage = (imageIndex, patch) => {
  * @returns {void}
  */
 const setActiveMediaUseAlt = (imageIndex, enabled) => {
-  updateActiveMediaImage(imageIndex, { useAlt: enabled })
+  const image = activeMediaBlock.value?.images[imageIndex]
+
+  if (!image) {
+    return
+  }
+
+  const patch = { useAlt: enabled }
+
+  if (enabled && !String(image.caption || '').trim()) {
+    const legacy = String(image.legacyBracketLabel || '').trim()
+    const filename = getImageDefaultAltLabel(image.url)
+
+    if (legacy && legacy !== filename) {
+      patch.caption = legacy
+    }
+  }
+
+  updateActiveMediaImage(imageIndex, patch)
+}
+
+/**
+ * 미리보기에서 갤러리 순서 변경
+ * @param {{ startLine: number, endLine: number, images: Array<Object> }} payload - 갤러리 줄 범위·이미지 목록
+ * @returns {void}
+ */
+const onPreviewGalleryReorder = ({ startLine, endLine, images }) => {
+  if (typeof startLine !== 'number' || typeof endLine !== 'number' || !Array.isArray(images)) {
+    return
+  }
+
+  replaceLineRange(startLine, endLine, [
+    ':::gallery',
+    ...images.map(createImageMarkdown),
+    ':::'
+  ], false)
 }
 
 /**
@@ -1318,7 +1352,12 @@ const handleKeydown = (event) => {
       style="--site-text: #15171a; --site-muted: #6b7280; --site-panel: #f6f7f8; --site-line: #e3e6e8; --site-accent: #2eb6ea;"
       tabindex="0"
     >
-      <ContentMarkdownRenderer v-if="markdownValue.trim()" :content="markdownValue" />
+      <ContentMarkdownRenderer
+        v-if="markdownValue.trim()"
+        :content="markdownValue"
+        interactive
+        @gallery-reorder="onPreviewGalleryReorder"
+      />
       <p v-else class="admin-markdown-editor__preview-empty text-sm text-[#8e9cac]">
         미리보기할 본문이 없습니다.
       </p>
diff --git a/components/content/ContentMarkdownRenderer.vue b/components/content/ContentMarkdownRenderer.vue
index adeaf68..c531f0d 100644
--- a/components/content/ContentMarkdownRenderer.vue
+++ b/components/content/ContentMarkdownRenderer.vue
@@ -1,7 +1,7 @@
 <script setup>
 import {
   getImageAltAttribute,
-  getImageCaption,
+  getImageDisplayCaption,
   parseImageMarkdownLine
 } from '../../lib/markdown-image.js'
 
@@ -9,13 +9,22 @@ const props = defineProps({
   content: {
     type: String,
     default: ''
+  },
+  /** 관리자 미리보기: 갤러리 드래그 정렬 등 */
+  interactive: {
+    type: Boolean,
+    default: false
   }
 })
 
+const emit = defineEmits(['gallery-reorder'])
+
 const BLANK_PARAGRAPH_MARKER = '<!--sori:blank-paragraph-->'
 
 const activeLightboxImages = ref([])
 const activeLightboxIndex = ref(0)
+/** @type {import('vue').Ref<{ blockId: string, imageIndex: number }|null>} */
+const galleryDragState = ref(null)
 
 /**
  * 마크다운 블록을 생성
@@ -323,7 +332,13 @@ const parseMarkdownBlocks = (markdown) => {
         }
       })
 
-      blocks.push(createBlock('gallery', '', null, `block-${blocks.length}`, { images }))
+      blocks.push(createBlock('gallery', '', null, `block-${blocks.length}`, {
+        images,
+        meta: {
+          startLine: index,
+          endLine: nextIndex
+        }
+      }))
       index = nextIndex
       continue
     }
@@ -552,6 +567,65 @@ const showNextImage = () => {
   activeLightboxIndex.value = (activeLightboxIndex.value + 1) % activeLightboxImages.value.length
 }
 
+/**
+ * 갤러리 드래그 시작
+ * @param {DragEvent} event - 드래그 이벤트
+ * @param {string} blockId - 블록 ID
+ * @param {number} imageIndex - 이미지 인덱스
+ * @returns {void}
+ */
+const onGalleryDragStart = (event, blockId, imageIndex) => {
+  if (!props.interactive) {
+    return
+  }
+
+  galleryDragState.value = { blockId, imageIndex }
+  event.dataTransfer.effectAllowed = 'move'
+  event.dataTransfer.setData('text/plain', String(imageIndex))
+}
+
+/**
+ * 갤러리 드래그 종료
+ * @returns {void}
+ */
+const onGalleryDragEnd = () => {
+  galleryDragState.value = null
+}
+
+/**
+ * 갤러리 드롭으로 순서 변경
+ * @param {DragEvent} event - 드롭 이벤트
+ * @param {Object} block - 갤러리 블록
+ * @param {number} targetIndex - 대상 인덱스
+ * @returns {void}
+ */
+const onGalleryDrop = (event, block, targetIndex) => {
+  if (!props.interactive || !galleryDragState.value) {
+    return
+  }
+
+  event.preventDefault()
+
+  const { blockId, imageIndex: fromIndex } = galleryDragState.value
+
+  if (blockId !== block.id || fromIndex === targetIndex) {
+    galleryDragState.value = null
+    return
+  }
+
+  const images = [...block.images]
+  const [moved] = images.splice(fromIndex, 1)
+  images.splice(targetIndex, 0, moved)
+
+  emit('gallery-reorder', {
+    startLine: block.meta?.startLine,
+    endLine: block.meta?.endLine,
+    images
+  })
+
+  galleryDragState.value = null
+}
+
 /**
  * 라이트박스 키보드 조작(Esc 닫기, 좌우 이전·다음)
  * @param {KeyboardEvent} event - 키보드 이벤트
@@ -640,12 +714,9 @@ onBeforeUnmount(() => {
         v-else-if="block.type === 'image'"
         :src="block.url"
         :alt="getImageAltAttribute(block)"
+        :caption="getImageDisplayCaption(block)"
         :variant="block.width"
-      >
-        <template v-if="getImageCaption(block)">
-          {{ getImageCaption(block) }}
-        </template>
-      </ProseImage>
+      />
       <ProseCallout
         v-else-if="block.type === 'callout'"
         :emoji-enabled="block.calloutEmojiEnabled"
@@ -684,16 +755,39 @@ onBeforeUnmount(() => {
         :placeholder="block.meta.placeholder"
       />
       <ProseEmbed v-else-if="block.type === 'embed'" :url="block.url" />
-      <div v-else-if="block.type === 'gallery'" class="content-markdown-renderer__gallery my-8 grid grid-cols-2 gap-2 md:grid-cols-3">
-        <button
+      <div
+        v-else-if="block.type === 'gallery'"
+        class="content-markdown-renderer__gallery my-8 grid grid-cols-2 gap-2 md:grid-cols-3"
+      >
+        <figure
           v-for="(image, imageIndex) in block.images"
-          :key="`${block.id}-${image.url}`"
-          class="content-markdown-renderer__gallery-button overflow-hidden rounded-[10px] border border-[var(--site-line)] bg-[var(--site-panel)]"
-          type="button"
-          @click="openLightbox(block.images, imageIndex)"
+          :key="`${block.id}-${imageIndex}-${image.url}`"
+          class="content-markdown-renderer__gallery-item min-w-0"
+          :class="interactive ? 'content-markdown-renderer__gallery-item--interactive' : ''"
+          :draggable="interactive"
+          @dragstart="onGalleryDragStart($event, block.id, imageIndex)"
+          @dragend="onGalleryDragEnd"
+          @dragover.prevent
+          @drop="onGalleryDrop($event, block, imageIndex)"
         >
-          <img class="content-markdown-renderer__gallery-image aspect-[4/3] w-full object-cover transition-transform hover:scale-[1.02]" :src="image.url" :alt="getImageAltAttribute(image)">
-        </button>
+          <button
+            class="content-markdown-renderer__gallery-button w-full overflow-hidden rounded-[10px] border border-[var(--site-line)] bg-[var(--site-panel)]"
+            type="button"
+            @click="openLightbox(block.images, imageIndex)"
+          >
+            <img
+              class="content-markdown-renderer__gallery-image aspect-[4/3] w-full object-cover transition-transform hover:scale-[1.02]"
+              :src="image.url"
+              :alt="getImageAltAttribute(image)"
+            >
+          </button>
+          <figcaption
+            v-if="getImageDisplayCaption(image)"
+            class="content-markdown-renderer__gallery-caption mt-1.5 text-center text-xs text-[var(--site-muted)]"
+          >
+            {{ getImageDisplayCaption(image) }}
+          </figcaption>
+        </figure>
       </div>
       <pre
         v-else-if="block.type === 'code'"
@@ -750,3 +844,13 @@ onBeforeUnmount(() => {
     </div>
   </div>
 </template>
+
+<style scoped>
+.content-markdown-renderer__gallery-item--interactive {
+  cursor: grab;
+}
+
+.content-markdown-renderer__gallery-item--interactive:active {
+  cursor: grabbing;
+}
+</style>
diff --git a/components/content/ProseImage.vue b/components/content/ProseImage.vue
index 3318de1..5f6ced7 100644
--- a/components/content/ProseImage.vue
+++ b/components/content/ProseImage.vue
@@ -8,6 +8,11 @@ defineProps({
     type: String,
     default: ''
   },
+  /** 이미지 아래 표시용 캡션 */
+  caption: {
+    type: String,
+    default: ''
+  },
   variant: {
     type: String,
     default: 'regular'
@@ -26,8 +31,11 @@ defineProps({
     <div class="overflow-hidden rounded-[10px] border border-[var(--site-line)] bg-[var(--site-panel)]">
       <img class="prose-image__media w-full object-cover" :src="src" :alt="alt">
     </div>
-    <figcaption v-if="$slots.default" class="prose-image__caption mt-1.5 text-center text-sm text-[var(--site-muted)]">
-      <slot />
+    <figcaption
+      v-if="caption"
+      class="prose-image__caption mt-1.5 text-center text-sm text-[var(--site-muted)]"
+    >
+      {{ caption }}
     </figcaption>
   </figure>
 </template>
diff --git a/docs/update.md b/docs/update.md
index 0fd2e36..1e01189 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v1.2.4
+
+- 이미지 캡션: `ProseImage` caption prop, 갤러리 figcaption, 파일명 alt와 별도 표시. useAlt 파일명 비교 URI 디코딩 정규화.
+- 관리자 미리보기: 갤러리 드래그 순서 변경(`interactive` + `gallery-reorder`).
+- 패키지 버전 `1.2.4`로 갱신.
+
 ## v1.2.3
 
 - 관리자 마크다운 에디터: textarea 내부 스크롤·`resize-y` 제거, 본문 높이 자동 확장·`admin-post-form__editor-scroll` 외부 스크롤만 사용, 줄 번호 거터 flex 정렬.
diff --git a/lib/markdown-image.js b/lib/markdown-image.js
index b4878b5..7162482 100644
--- a/lib/markdown-image.js
+++ b/lib/markdown-image.js
@@ -20,6 +20,25 @@ const escapeImageCaption = (value) => String(value || '').replace(/"/g, '\\"')
  * @param {string} url - 이미지 URL
  * @returns {string} 파일명 기반 라벨
  */
+/**
+ * 파일명·대괄호 라벨 비교용 정규화
+ * @param {string} value - 원본 문자열
+ * @returns {string} 정규화된 문자열
+ */
+const normalizeFilenameLabel = (value) => {
+  const raw = String(value || '').trim()
+
+  if (!raw) {
+    return ''
+  }
+
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
 export const getImageDefaultAltLabel = (url) => {
   const raw = String(url || '').trim()
 
@@ -53,7 +72,8 @@ export const parseImageMarkdownLine = (line) => {
   const quotedCaption = unescapeImageCaption(match[3])
   const filenameAlt = getImageDefaultAltLabel(url)
   /** 대괄호 안 문자열이 URL 파일명과 같을 때만 파일명 대체 텍스트 모드 */
-  const useAlt = altBracket !== '' && altBracket === filenameAlt
+  const useAlt = altBracket !== ''
+    && normalizeFilenameLabel(altBracket) === normalizeFilenameLabel(filenameAlt)
 
   return {
     url,
@@ -117,3 +137,10 @@ export const getImageCaption = (image) => {
 
   return String(image?.legacyBracketLabel || '').trim()
 }
+
+/**
+ * 표시용 캡션(단일·갤러리 공통)
+ * @param {Object} image - 이미지 블록 데이터
+ * @returns {string} figcaption 텍스트
+ */
+export const getImageDisplayCaption = (image) => getImageCaption(image)
diff --git a/package-lock.json b/package-lock.json
index e62086a..ba5537b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sori.studio",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sori.studio",
-      "version": "1.2.3",
+      "version": "1.2.4",
       "hasInstallScript": true,
       "dependencies": {
         "@nuxtjs/tailwindcss": "^6.14.0",
@@ -615,7 +615,7 @@
       }
     },
     "node_modules/@emnapi/wasi-threads": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
       "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
       "license": "MIT",
@@ -3503,7 +3503,7 @@
       }
     },
     "node_modules/@poppinss/exception": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz",
       "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==",
       "license": "MIT"
@@ -5445,7 +5445,7 @@
       "license": "MIT"
     },
     "node_modules/cookie-es": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/cookie-es/-/cookie-es-1.2.3.tgz",
       "integrity": "sha512-lXVyvUvrNXblMqzIRrxHb57UUVmqsSWlxqt3XIjCkUP0wDAf6uicO6KMbEgYrMNtEvWgWHwe42CKxPu9MYAnWw==",
       "license": "MIT"
@@ -5470,7 +5470,7 @@
       "license": "MIT"
     },
     "node_modules/crc-32": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz",
       "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==",
       "license": "Apache-2.0",
@@ -5905,7 +5905,7 @@
       "license": "MIT"
     },
     "node_modules/didyoumean": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/didyoumean/-/didyoumean-1.2.2.tgz",
       "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==",
       "license": "Apache-2.0"
@@ -6340,7 +6340,7 @@
       }
     },
     "node_modules/fast-string-truncated-width": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-1.2.1.tgz",
       "integrity": "sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==",
       "license": "MIT"
@@ -6847,7 +6847,7 @@
       }
     },
     "node_modules/http-shutdown": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/http-shutdown/-/http-shutdown-1.2.2.tgz",
       "integrity": "sha512-S9wWkJ/VSY9/k4qcjG318bqJNruzE4HySUhFYknwmu6LBP97KLLfwNf+n4V1BHurvFNkSKLFnK/RsuUnRTf9Vw==",
       "license": "MIT",
@@ -6885,7 +6885,7 @@
       }
     },
     "node_modules/ieee754": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
       "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
       "funding": [
@@ -6983,7 +6983,7 @@
       }
     },
     "node_modules/iron-webcrypto": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-1.2.1.tgz",
       "integrity": "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==",
       "license": "MIT",
@@ -7156,7 +7156,7 @@
       }
     },
     "node_modules/is-reference": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-1.2.1.tgz",
       "integrity": "sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ==",
       "license": "MIT",
@@ -7165,7 +7165,7 @@
       }
     },
     "node_modules/is-regex": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.2.1.tgz",
       "integrity": "sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==",
       "license": "MIT",
@@ -9859,7 +9859,7 @@
       "license": "MIT"
     },
     "node_modules/queue-microtask": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
       "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==",
       "funding": [
@@ -9885,7 +9885,7 @@
       "license": "MIT"
     },
     "node_modules/range-parser": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
       "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==",
       "license": "MIT",
@@ -10459,7 +10459,7 @@
       }
     },
     "node_modules/send": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
       "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
       "license": "MIT",
@@ -10693,7 +10693,7 @@
       }
     },
     "node_modules/source-map-js": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
       "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
       "license": "BSD-3-Clause",
@@ -11895,7 +11895,7 @@
       }
     },
     "node_modules/update-browserslist-db": {
-      "version": "1.2.3",
+      "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
       "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
       "funding": [
diff --git a/package.json b/package.json
index b9bc35f..e4904ef 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sori.studio",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "private": true,
   "type": "module",
   "imports": {