@qijenchen/design-system 0.1.0-beta.95 → 0.1.0-beta.99

package/src/components/InlineEdit/inline-edit.stories.tsx

@@ -46,10 +46,10 @@ export const TaskTitle: Story = {
 /* ── 真實業務:詳情面板多個 metadata 欄位逐欄就地編輯 ── */
 function MetaRow({ label, value, placeholder }: { label: string; value: string; placeholder?: string }) {
   return (
-    <div className="grid grid-cols-[128px_1fr] items-center gap-[var(--layout-space-tight)]">
-      <span className="text-body text-fg-secondary">{label}</span>
+    <Field orientation="horizontal" labelWidth="128px">
+      <FieldLabel>{label}</FieldLabel>
       <StatefulInlineEdit value={value} label={label} placeholder={placeholder} size="sm" />
-    </div>
+    </Field>
   )
 }
 
@@ -108,11 +108,11 @@ export const States: Story = {
   ),
   play: async ({ canvasElement }) => {
     const { userEvent } = await import('@storybook/test')
-    // hover 態:滑鼠移入第二列 → 顯示 bg-neutral-hover 灰底
+    // 只標記第二列；真實 CSS :hover 由 visual-audit 的 Playwright pointer 建立。
     const hoverBtn = canvasElement
       .querySelector('[data-testid="inline-edit-hover-row"]')
       ?.querySelector('button')
-    if (hoverBtn) await userEvent.hover(hoverBtn)
+    if (hoverBtn) hoverBtn.setAttribute('data-visual-hover-target', '')
     // edit 態:點擊第三列 → 切成真正的 Input 控件
     const editBtn = canvasElement
       .querySelector('[data-testid="inline-edit-edit-row"]')
@@ -139,16 +139,21 @@ export const SelectTagField: Story = {
   render: () => {
     const [status, setStatus] = React.useState('in-progress')
     return (
-      <div className="grid w-[440px] grid-cols-[128px_1fr] items-center gap-[var(--layout-space-tight)] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
-        <span className="text-body text-fg-secondary">Status</span>
+      <Field
+        orientation="horizontal"
+        labelWidth="128px"
+        className="w-[440px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]"
+      >
+        <FieldLabel>Status</FieldLabel>
         <InlineEdit<string>
           value={status}
           onCommit={setStatus}
           label="status"
           size="sm"
           // view:Select 的 view mode 輸出 Tag(格式化 SSOT 住在 Select,InlineEdit 不自刻)。
-          // Tag **盒子左緣**對齊 label / 其他純文字值,tag 文字被 pill 內距自然縮排 —— 對齊 Meegle 實測
-          // (PIL 量測 2026-07-10:Meegle pill box=label 左緣、text 縮排 ~8px@1x)。**不做 text outdent**。
+          // Tag **盒子左緣**對齊同欄其他純文字值(horizontal Field:值落內容欄左緣 + field-px,
+          // 不用 -mx),tag 文字被 pill 內距自然縮排 —— 對齊 Meegle 實測
+          // (PIL 量測 2026-07-10:Meegle pill box=值左緣、text 縮排 ~8px@1x)。**不做 text outdent**。
           renderRead={(v) => (
             <Select mode="view" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
           )}
@@ -168,7 +173,7 @@ export const SelectTagField: Story = {
             />
           )}
         />
-      </div>
+      </Field>
     )
   },
 }
@@ -183,14 +188,16 @@ export const MultilineDescription: Story = {
     )
     return (
       <div className="w-[560px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
-        <p className="mb-1 text-caption text-fg-secondary">DESCRIPTION</p>
-        <InlineEdit
-          multiline
-          value={desc}
-          onCommit={setDesc}
-          label="description"
-          placeholder="Add a description…"
-        />
+        <Field orientation="vertical">
+          <FieldLabel>DESCRIPTION</FieldLabel>
+          <InlineEdit
+            multiline
+            value={desc}
+            onCommit={setDesc}
+            label="description"
+            placeholder="Add a description…"
+          />
+        </Field>
       </div>
     )
   },
@@ -201,6 +208,10 @@ export const MultilineDescription: Story = {
 export const VerticalFieldForm: Story = {
   name: '詳情面板:垂直欄位就地編輯',
   render: () => {
+    // Assignee 的 state 提到 story 本體(不包 wrapper 元件)—— InlineEdit 必須是 <Field> 的**直接子**,
+    // Field 才讀得到靜態 fieldPreferredSize='sm';包一層 wrapper 會遮蔽它 → 控件槽退回 md(32px),
+    // 與同表其他 sm(28px)列不齊(對照 inline-edit.anatomy.stories.tsx CascadeDemo)。
+    const [assignee, setAssignee] = React.useState('Alex Rivera')
     const [status, setStatus] = React.useState('in-progress')
     const [desc, setDesc] = React.useState('Safari 上點擊結帳時,e2e 測試會間歇性失敗。')
     return (
@@ -210,7 +221,7 @@ export const VerticalFieldForm: Story = {
       >
         <Field orientation="vertical">
           <FieldLabel>Assignee</FieldLabel>
-          <StatefulInlineEdit value="Alex Rivera" label="assignee" />
+          <InlineEdit value={assignee} onCommit={setAssignee} label="assignee" />
         </Field>
         <Field orientation="vertical">
           <FieldLabel>Status</FieldLabel>

package/src/components/InlineEdit/inline-edit.tsx

@@ -26,9 +26,11 @@ import { cn } from '@/lib/utils'
 import { Input } from '@/design-system/components/Input/input'
 import { Textarea } from '@/design-system/components/Textarea/textarea'
 import type { FieldSize } from '@/design-system/components/Field/field-context'
-import { useFieldContext, useResolvedFieldSize, FieldSurfaceProvider } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useRegisterFieldPreferredSize, FieldSurfaceProvider } from '@/design-system/components/Field/field-context'
 import { fieldDisplayTextClass, fieldViewGeometry } from '@/design-system/components/Field/field-wrapper'
 import { makeEditSettleKeyHandler } from '@/design-system/components/Field/field-edit-keys'
+import { useTruncated } from '@/design-system/hooks/use-truncated'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
@@ -71,6 +73,11 @@ export interface InlineEditProps<T = string> {
   renderRead?: (value: T) => React.ReactNode
   /** 多行欄位(Jira description 類):view 態換行 + 預設 edit 態用 `<Textarea>`,Enter=換行、Cmd/Ctrl+Enter 或 blur 提交 */
   multiline?: boolean
+  /**
+   * 多行 edit 態的高度上限(行數)。預設無上限 —— 高度隨內容,與 view 態同源(= DataTable cell 語意)。
+   * 設定後超過行數改為捲動。僅在 `multiline` 時有意義。
+   */
+  editMaxRows?: number
   /**
    * 是否可編輯(預設 true)。false → view 態無 hover 入口、無藍框、不可點進 edit(對齊世界級就地編輯
    * **無 disabled 態**,鎖定 = 純 view 無入口、**不灰化**;cite 見檔頭 MUI X / AG Grid URL)。
@@ -113,6 +120,7 @@ function InlineEditImpl<T = string>(
     renderEdit,
     renderRead,
     multiline = false,
+    editMaxRows,
     editable = true,
     label,
     placeholder,
@@ -123,9 +131,11 @@ function InlineEditImpl<T = string>(
   }: InlineEditProps<T>,
   ref: React.Ref<HTMLDivElement>,
 ) {
-  // size:接 fieldCtx.size cascade,standalone fallback sm(InlineEdit 靜態 fieldPreferredSize='sm'
-  //   讓外層 `<Field>` 自動收 sm — 見檔尾 static)。
+  // size:接 fieldCtx.size cascade,fallback sm。Field 只有在 consumer 顯式指定或已解析出偏好時
+  //   才壓過此 fallback(sizeExplicit),因此包一層 wrapper 也不會靜默退回 md。
   const size = useResolvedFieldSize(sizeProp, 'sm')
+  // 同時向外層 Field 註冊偏好,讓 Field 的控件槽高度跟上(靜態 fieldPreferredSize 被 wrapper 遮蔽時的補位)。
+  useRegisterFieldPreferredSize('sm')
   // orientation:vertical(值貼 label 左緣 → 用 -mx)/ horizontal(值落內容欄左緣+field-px = 對齊 sibling 控件 → 不用 -mx)。
   const fieldCtx = useFieldContext()
   const orientation = fieldCtx?.orientation ?? 'vertical'
@@ -238,6 +248,35 @@ function InlineEditImpl<T = string>(
     value == null || (value as unknown) === '' || (Array.isArray(value) && value.length === 0)
   const Tag = as as React.ElementType
 
+  // 單行純值 view 的截斷 tooltip:量測內層值 span,但 **trigger = 整個 view 容器**。
+  // 不能用 <TruncatedText>(trigger=值 span 本身):view 上疊著透明 Pressable(click-to-edit
+  // 入口,absolute inset-0),所有 hover 都被按鈕吞掉,值 span 永遠收不到 pointerenter →
+  // tooltip 永不開(2026-07-28 user 實測抓到)。truncated-text.spec 對「trigger 需自控」場景
+  // 的指定解 = 直接消費 public useTruncated 自組;DataTable cell 無疊層所以能用 primitive。
+  const singleLinePlainView = !renderRead && !multiline
+  const { ref: truncationRef, isTruncated } = useTruncated<HTMLSpanElement>({
+    deps: [singleLinePlainView && !isEmpty ? String(value) : ''],
+  })
+  const plainTruncationActive = singleLinePlainView && !isEmpty && isTruncated
+
+  // 委派 view(renderRead)同規則(tooltip.spec.md「截斷文字 → tooltip,截斷才顯」):委派控件
+  // 自帶的截斷 tooltip(Input <TruncatedText> / Tag)trigger 在內層,editable 時同樣被透明
+  // Pressable 吞掉 hover → 永不開,故外層容器 Tooltip 一併服務委派路徑。量測 = use-truncated
+  // options.measure 自訂策略(檔頭明載 Tag「observe root、量測內層」即同款開口):走訪 wrapper
+  // 子樹,任一 `.truncate` 後代溢出即視為截斷(委派控件截斷元素皆帶 truncate class:Tag 內層
+  // span / TruncatedText span / Select view span)。editable=false 不渲染 Pressable → 控件自身
+  // tooltip 可達,外層讓位避免雙重顯示。
+  const delegatedView = !!renderRead
+  const { ref: delegatedViewRef, isTruncated: delegatedTruncated } = useTruncated<HTMLDivElement>({
+    measure: (el) =>
+      Array.from(el.querySelectorAll<HTMLElement>('.truncate')).some(
+        (node) => node.scrollWidth > node.clientWidth,
+      ),
+    deps: [delegatedView && editable && !isEmpty ? value : null],
+  })
+  const delegatedTruncationActive = delegatedView && editable && !isEmpty && delegatedTruncated
+  const truncationTooltipActive = plainTruncationActive || delegatedTruncationActive
+
   // 對齊盒(orientation-aware,Model A;2026-07-17 移除 fieldCtx gate — root cause 修):
   //   vertical(預設,含 standalone)→ `-mx-field-px` + `w-calc` 把整塊拉到欄左緣(值貼 label 左緣;
   //     view 委派控件在 `surface='inline-edit'` 下 px 統一 field-px → 被 -mx 精準抵消 → 落 x=0 對齊 label)。
@@ -269,6 +308,9 @@ function InlineEditImpl<T = string>(
       <Textarea
         autoFocus
         mode="edit"
+        // view 態高度由內容決定,edit 態必須同源,否則 read↔edit 之間跳高(DataTable cell 早就是
+        // 內容驅動,standalone InlineEdit 原本卡在 rows=3)。consumer 要上限就傳 editMaxRows。
+        autoSize={editMaxRows === undefined ? true : { maxRows: editMaxRows }}
         value={draft as unknown as string}
         size={size}
         aria-label={label}
@@ -310,7 +352,8 @@ function InlineEditImpl<T = string>(
     // surface='inline-edit' 保留為 per-control 逃生訊號(若某控件 bare view 有內部 inset 破壞對齊,該控件可
     // 讀 surface 自抑;目前全控件 bare view=0px 不需)。
     <FieldSurfaceProvider surface="inline-edit">
-      <div className={fieldViewGeometry(size, multiline)}>{renderRead(value)}</div>
+      {/* delegatedViewRef = 委派路徑截斷量測根(walk `.truncate` 後代;見上方 useTruncated 註解) */}
+      <div ref={delegatedViewRef} className={fieldViewGeometry(size, multiline)}>{renderRead(value)}</div>
     </FieldSurfaceProvider>
   ) : (
     <Tag
@@ -327,37 +370,57 @@ function InlineEditImpl<T = string>(
         isEmpty && 'text-fg-muted',
       )}
     >
-      {isEmpty ? placeholder : String(value)}
+      {isEmpty || multiline
+        ? (isEmpty ? placeholder : String(value))
+        // 單行 view 恆一行:溢出改 ellipsis(tooltip.spec.md「截斷文字 → tooltip」);
+        // tooltip 掛在外層 view 容器(見 truncationRef 註解——隱形 Pressable 吞 hover)。
+        : <span ref={truncationRef} className="truncate min-w-0">{String(value)}</span>}
     </Tag>
   )
 
   return (
-    <div
-      ref={ref}
-      data-editing={false}
-      data-editable={editable || undefined}
-      className={cn(
-        'relative flex min-w-0 rounded-md border border-transparent transition-colors duration-150',
-        alignBleed,
-        // editable 才有 hover 底色 + 鍵盤 focus 藍框(Field focus 語言,非 Button ring);
-        //   editable=false = 純 view 鎖定,無入口、無藍框、不灰化。
-        editable && 'hover:bg-neutral-hover [&:has(button:focus-visible)]:border-primary',
-        className,
-      )}
-    >
-      {viewNode}
-      {/* 隱形 Pressable(僅 editable):提供 click + 鍵盤 Tab focus + Enter/Space 進 edit;透明疊於內容上。
-          hover 底色 + focus 藍框由外層 div 承載(Field focus 語言),故本 button 只需 outline-none 消瀏覽器預設外框。 */}
-      {editable && (
-        <button
-          ref={readButtonRef}
-          type="button"
-          aria-label={label ? `編輯 ${label}` : '編輯'}
-          onClick={enterEdit}
-          className="absolute inset-0 cursor-text rounded-md focus-visible:outline-none"
-        />
-      )}
-    </div>
+    // 截斷 tooltip:trigger = 整個 view 容器(隱形 Pressable 吞掉內層 hover,故不能掛在值 span);
+    // 純值路徑量內層值 span、委派路徑量 wrapper 子樹(見上方兩段 useTruncated 註解);
+    // 恆 wrap 保 DOM 生命週期穩定(truncated-text 檔頭 always-wrap 教訓),未截斷時 open={false} 靜默。
+    <Tooltip open={truncationTooltipActive ? undefined : false}>
+      <TooltipTrigger asChild>
+        <div
+          ref={ref}
+          data-editing={false}
+          data-editable={editable || undefined}
+          className={cn(
+            'relative flex min-w-0 rounded-md border border-transparent transition-colors duration-150',
+            alignBleed,
+            // editable 才有 hover 底色 + 鍵盤 focus 藍框(Field focus 語言,非 Button ring);
+            //   editable=false = 純 view 鎖定,無入口、無藍框、不灰化。
+            editable && 'hover:bg-neutral-hover [&:has(button:focus-visible)]:border-primary',
+            className,
+          )}
+        >
+          {viewNode}
+          {/* 隱形 Pressable(僅 editable):提供 click + 鍵盤 Tab focus + Enter/Space 進 edit;透明疊於內容上。
+              hover 底色 + focus 藍框由外層 div 承載(Field focus 語言),故本 button 只需 outline-none 消瀏覽器預設外框。 */}
+          {editable && (
+            <button
+              ref={readButtonRef}
+              type="button"
+              aria-label={label ? `編輯 ${label}` : '編輯'}
+              onClick={enterEdit}
+              className="absolute inset-0 cursor-text rounded-md focus-visible:outline-none"
+            />
+          )}
+        </div>
+      </TooltipTrigger>
+      <TooltipContent>
+        {delegatedTruncationActive
+          ? // 委派路徑內容 = wrapper 子樹當下 DOM 的 textContent(完整格式化文字;
+            // 非 string T 不可 String(value) —— 如 string[] / PersonValue)
+            delegatedViewRef.current?.textContent
+          : plainTruncationActive
+            ? String(value)
+            : null}
+      </TooltipContent>
+    </Tooltip>
   )
 }
 

package/src/components/Input/input.anatomy.stories.tsx

@@ -214,9 +214,9 @@ export const Overview = {
                 {/* view + readonly 讀 controlled value:兩者「空值」皆走 <span> 顯 '-'(input.tsx:121),
                     demo 要展示有值狀態故傳 value;edit / disabled 用 defaultValue 保持 uncontrolled */}
                 {(m === 'view' || m === 'readonly') ? (
-                  <Input mode={m} value="Wireless Bluetooth Headphones" size="md" />
+                  <Input mode={m} value="Wireless Bluetooth Headphones" size="md" aria-label={`商品名稱（${m} 模式）`} />
                 ) : (
-                  <Input mode={m} defaultValue="Wireless Bluetooth Headphones" size="md" />
+                  <Input mode={m} defaultValue="Wireless Bluetooth Headphones" size="md" aria-label={`商品名稱（${m} 模式）`} />
                 )}
               </div>
               <span className="text-caption text-fg-secondary">{MODE_DESC[m]}</span>
@@ -227,7 +227,7 @@ export const Overview = {
           <span className="text-[11px] text-fg-muted font-medium">+ error prop（僅 edit 模式生效）</span>
           <div className="flex items-center gap-4">
             <div className="w-64 shrink-0">
-              <Input error defaultValue="invalid-email@" size="md" />
+              <Input error defaultValue="invalid-email@" size="md" aria-label="Email（錯誤狀態）" />
             </div>
             <span className="text-caption text-fg-secondary">border-error — 錯誤訊息由 Form help text 提供</span>
           </div>
@@ -237,7 +237,7 @@ export const Overview = {
       {/* Props table */}
       <div className="flex flex-col gap-3">
         <H3>Props</H3>
-        <div className="overflow-x-auto">
+        <div className="overflow-x-auto" tabIndex={0} aria-label="Input props 表格">
           <table className="text-caption border-collapse">
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
@@ -332,6 +332,7 @@ const InspectorInner = () => {
               mode={mode}
               size={size}
               error={error}
+              aria-label="商品名稱（互動檢閱器）"
               startIcon={hasStartIcon ? Search : undefined}
               endAction={hasEndAction && isEdit ? { icon: X, label: '清除', onClick: () => {} } : undefined}
               // view mode 讀 value 渲染 <span>;其餘 mode 用 defaultValue 保持 uncontrolled
@@ -505,6 +506,7 @@ export const ColorMatrix = {
                         error={st === 'error'}
                         defaultValue="Wireless Bluetooth Headphones"
                         size="md"
+                        aria-label={`商品名稱（${st} 狀態）`}
                       />
                     </td>
                     <td className="p-3 border-b border-divider align-top">
@@ -529,7 +531,12 @@ export const ColorMatrix = {
                 <tr key={m}>
                   <td className="p-3 border-b border-divider font-mono text-caption font-medium align-top w-24">{m}</td>
                   <td className="p-3 border-b border-divider align-top min-w-[240px]">
-                    <Input mode={m} defaultValue="Wireless Bluetooth Headphones" size="md" />
+                    <Input
+                      mode={m}
+                      defaultValue="Wireless Bluetooth Headphones"
+                      size="md"
+                      aria-label={`商品名稱（${m} 模式）`}
+                    />
                   </td>
                   <td className="p-3 border-b border-divider align-top">
                     <TokenAnnotation colors={COLOR_MAP[m].default!} />
@@ -634,7 +641,13 @@ export const SizeMatrix = {
                   <Td mono>{sz}</Td>
                   {MODES.map((m) => (
                     <td key={m} className="p-2 border-b border-divider">
-                      <Input mode={m} size={sz} defaultValue="Headphones" className="w-48" />
+                      <Input
+                        mode={m}
+                        size={sz}
+                        defaultValue="Headphones"
+                        aria-label={`商品名稱（${sz} 尺寸、${m} 模式）`}
+                        className="w-48"
+                      />
                     </td>
                   ))}
                   <td className="p-2 border-b border-divider">
@@ -643,6 +656,7 @@ export const SizeMatrix = {
                       startIcon={Search}
                       endAction={{ icon: X, label: '清除', onClick: () => {} }}
                       defaultValue="Headphones"
+                      aria-label={`商品搜尋（${sz} 尺寸）`}
                       className="w-48"
                     />
                   </td>
@@ -678,8 +692,8 @@ export const StateBehavior = {
           <span className="text-caption font-medium text-fg-secondary">Focus — border-primary（1px），無 ring（readonly 例外:ring-2 ring-ring focus 指示,WCAG 2.4.7）</span>
           <div className="flex flex-col gap-2 max-w-sm">
             <span className="text-[11px] text-fg-muted">文字輸入永遠 focus-visible（瀏覽器規範），click 和 Tab 觸發相同效果。點擊下方 input 或用 Tab 切換觀察。</span>
-            <Input placeholder="點擊或 Tab 觀察 focus 邊框" />
-            <Input placeholder="第二個，測試 Tab 切換" />
+            <Input placeholder="點擊或 Tab 觀察 focus 邊框" aria-label="第一個焦點測試欄位" />
+            <Input placeholder="第二個，測試 Tab 切換" aria-label="第二個焦點測試欄位" />
           </div>
         </div>
 
@@ -689,12 +703,12 @@ export const StateBehavior = {
           <div className="flex flex-col gap-3 max-w-sm">
             <div>
               <span className="text-[11px] text-fg-muted block mb-1">border-error，hover 時 border-error-hover</span>
-              <Input error defaultValue="invalid-email@" />
+              <Input error defaultValue="invalid-email@" aria-label="Email（錯誤狀態）" />
               <p className="text-caption text-error mt-1">請輸入有效的 email 地址</p>
             </div>
             <div>
               <span className="text-[11px] text-fg-muted block mb-1">focus 時 border-error（不切回 primary）</span>
-              <Input error defaultValue="bad-url" startIcon={Search} />
+              <Input error defaultValue="bad-url" startIcon={Search} aria-label="網址（錯誤焦點狀態）" />
             </div>
           </div>
         </div>
@@ -708,6 +722,7 @@ export const StateBehavior = {
               startIcon={Search}
               value={query}
               onChange={(e) => setQuery(e.target.value)}
+              aria-label="搜尋商品"
               endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
             />
           </div>
@@ -722,6 +737,7 @@ export const StateBehavior = {
               <Input
                 type={showPwd ? 'text' : 'password'}
                 defaultValue="my-secret-123"
+                aria-label="密碼"
                 endAction={{
                   icon: showPwd ? EyeOff : Eye,
                   label: showPwd ? '隱藏密碼' : '顯示密碼',
@@ -737,10 +753,10 @@ export const StateBehavior = {
           <span className="text-caption font-medium text-fg-secondary">Disabled — endAction 不渲染，停用原因由外部承擔</span>
           <div className="flex flex-col gap-3 max-w-sm">
             <div className="flex items-center gap-3">
-              <Input mode="edit" startIcon={Mail} defaultValue="alice@example.com"
+              <Input mode="edit" startIcon={Mail} defaultValue="alice@example.com" aria-label="Email（可編輯）"
                 endAction={{ icon: X, label: '清除', onClick: () => {} }} className="w-56" />
               <span className="text-fg-muted text-caption">→</span>
-              <Input mode="disabled" startIcon={Mail} defaultValue="alice@example.com"
+              <Input mode="disabled" startIcon={Mail} defaultValue="alice@example.com" aria-label="Email（停用）"
                 endAction={{ icon: X, label: '清除', onClick: () => {} }} className="w-56" />
             </div>
             <span className="text-[11px] text-fg-muted">左：edit（有 endAction）→ 右：disabled（endAction 消失，icon 變 fg-disabled）</span>

package/src/components/Input/input.principles.stories.tsx

@@ -73,11 +73,11 @@ export const UsageGuidance: Story = {
           title="❌ 不用 Input 顯示需要格式化的資料 → NumberInput / DatePicker"
           note="數字、日期、金額都需要格式化(千分位、時區、幣別符號)。每種資料類型有專屬元件,擁有該類型的格式化邏輯(唯一真實來源),同時服務 Form 和 DataTable"
         >
-          <Input defaultValue="1234567" placeholder="金額" />
+          <Input defaultValue="1234567" placeholder="金額" aria-label="金額（不建議用 Input）" />
           <Label warn>↑ 金額 → 用 NumberInput + currency mode(自動 $1,234,567)</Label>
-          <Input defaultValue="2026-04-18" placeholder="日期" />
+          <Input defaultValue="2026-04-18" placeholder="日期" aria-label="日期（不建議用 Input）" />
           <Label warn>↑ 日期 → 用 DatePicker(in-locale 顯示、避免時區誤判)</Label>
-          <Input defaultValue="1234567" placeholder="數量" />
+          <Input defaultValue="1234567" placeholder="數量" aria-label="數量（不建議用 Input）" />
           <Label warn>↑ 數字 → 用 NumberInput(千分位、min/max、step)</Label>
         </Rule>
 
@@ -85,9 +85,9 @@ export const UsageGuidance: Story = {
           title="✅ Input 只用於純文字——沒有格式化需求的 value"
           note="姓名、URL、搜尋字串、email。格式化邏輯是 identity(value → value)"
         >
-          <Input placeholder="姓名" defaultValue="Ada Chen" />
-          <Input startIcon={Globe} defaultValue="https://example.com" />
-          <Input startIcon={Search} placeholder="搜尋..." />
+          <Input placeholder="姓名" defaultValue="Ada Chen" aria-label="姓名" />
+          <Input startIcon={Globe} defaultValue="https://example.com" aria-label="網址" />
+          <Input startIcon={Search} placeholder="搜尋..." aria-label="搜尋" />
         </Rule>
       </Section>
     </div>
@@ -102,14 +102,14 @@ export const ModeRule: Story = {
         title="edit — 表單中可編輯的欄位(預設)"
         note="Focus 時邊框變 primary,使用者正在輸入或修改"
       >
-        <Input defaultValue="Wireless Bluetooth Headphones" />
+        <Input defaultValue="Wireless Bluetooth Headphones" aria-label="商品名稱" />
       </Rule>
 
       <Rule
         title="readonly — 表單中顯示但當下不可編輯"
         note="同 edit 高度(neutral-2 底色、無邊框),確保與其他欄位並排對齊。常見場景:viewing mode、送出後鎖定但仍在表單脈絡"
       >
-        <Input mode="readonly" value="alice@example.com" />
+        <Input mode="readonly" value="alice@example.com" aria-label="Email（唯讀）" />
       </Rule>
 
       <Rule
@@ -119,7 +119,7 @@ export const ModeRule: Story = {
         <Tooltip>
           <TooltipTrigger asChild>
             <div>
-              <Input mode="disabled" defaultValue="僅付費方案可用" />
+              <Input mode="disabled" defaultValue="僅付費方案可用" aria-label="付費方案欄位（停用）" />
             </div>
           </TooltipTrigger>
           <TooltipContent>此欄位在免費方案中不可編輯</TooltipContent>
@@ -130,7 +130,7 @@ export const ModeRule: Story = {
         title="❌ 不用 readonly 作為 DataTable cell"
         note="readonly 有底色 chrome(bg-readonly),密集列表會顯得鬆散。Table cell 用 `<Input mode='view'>`(Model A:edit 幾何減 chrome —— 保留 px 與高度,只拔 border/bg;cell 內經 naked variant 由 host cell 供 padding)"
       >
-        <Input mode="readonly" value="alice@example.com" />
+        <Input mode="readonly" value="alice@example.com" aria-label="Email（資料表誤用示範）" />
         <Label warn>↑ 在 table cell 中有多餘底色 chrome → 用 &lt;Input mode=&quot;view&quot; /&gt;</Label>
       </Rule>
     </div>
@@ -145,18 +145,18 @@ export const StartIconRule: Story = {
         title="startIcon 描述 input 的「用途」,不是 value 的類型"
         note="icon 幫助使用者一眼辨識這個欄位要填什麼——搜尋、Email、密碼、網址等。與 Button 的 startIcon 同理(描述動作),這裡描述欄位身份"
       >
-        <Input startIcon={Search} placeholder="搜尋商品..." />
-        <Input startIcon={Mail} defaultValue="alice@example.com" />
-        <Input startIcon={Lock} type="password" defaultValue="secret-123" />
-        <Input startIcon={Globe} placeholder="https://example.com" />
+        <Input startIcon={Search} placeholder="搜尋商品..." aria-label="搜尋商品" />
+        <Input startIcon={Mail} defaultValue="alice@example.com" aria-label="Email" />
+        <Input startIcon={Lock} type="password" defaultValue="secret-123" aria-label="密碼" />
+        <Input startIcon={Globe} placeholder="https://example.com" aria-label="網址" />
       </Rule>
 
       <Rule
         title="❌ startIcon 不可隨 value 變化"
         note="icon 是「身份」不是「狀態」——value 變了但欄位用途沒變,icon 不該跟著跳動。狀態回饋用 error border 或 Form help text"
       >
-        <Input startIcon={AlertCircle} defaultValue="invalid-email" />
-        <Input startIcon={CheckCircle2} defaultValue="alice@example.com" />
+        <Input startIcon={AlertCircle} defaultValue="invalid-email" aria-label="Email（錯誤圖示誤用）" />
+        <Input startIcon={CheckCircle2} defaultValue="alice@example.com" aria-label="Email（成功圖示誤用）" />
         <Label warn>↑ 用 icon 切換暗示「有效/無效」——status 應該走邊框和 help text,不佔 startIcon 語意槽</Label>
       </Rule>
     </div>
@@ -177,6 +177,7 @@ export const EndActionRule: Story = {
           <Input
             type={showPwd ? 'text' : 'password'}
             defaultValue="my-secret-123"
+            aria-label="密碼"
             endAction={{
               icon: showPwd ? EyeOff : Eye,
               label: showPwd ? '隱藏密碼' : '顯示密碼',
@@ -187,6 +188,7 @@ export const EndActionRule: Story = {
             startIcon={Search}
             value={query}
             onChange={(e) => setQuery(e.target.value)}
+            aria-label="搜尋商品"
             endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
           />
         </Rule>
@@ -199,11 +201,13 @@ export const EndActionRule: Story = {
             startIcon={Search}
             value=""
             placeholder="輸入後會出現清除按鈕"
+            aria-label="搜尋商品（空值）"
             readOnly
           />
           <Input
             startIcon={Search}
             defaultValue="Bluetooth"
+            aria-label="搜尋商品（有值）"
             endAction={{ icon: X, label: '清除搜尋', onClick: () => {} }}
           />
         </Rule>
@@ -215,6 +219,7 @@ export const EndActionRule: Story = {
           <Input
             error
             defaultValue="invalid-email@"
+            aria-label="Email（錯誤狀態圖示誤用）"
             endAction={{ icon: AlertCircle, label: '錯誤', onClick: () => {} }}
           />
           <Label warn>↑ 錯誤已由紅邊框傳達,endAction 放 AlertCircle 會讓使用者誤以為可點擊解決</Label>
@@ -233,7 +238,7 @@ export const ErrorRule: Story = {
         note="紅色邊框已足夠傳達「這個欄位有問題」,具體訊息由 Form 層的 help text 補充。Input 尾部不放 ⚠️ 狀態 icon"
       >
         <div>
-          <Input error defaultValue="invalid-email@" />
+          <Input error defaultValue="invalid-email@" aria-label="Email（錯誤狀態）" />
           <p className="text-caption text-error mt-1">請輸入有效的 email 地址</p>
         </div>
       </Rule>
@@ -245,6 +250,7 @@ export const ErrorRule: Story = {
         <Input
           error
           defaultValue="invalid-email@"
+          aria-label="Email（錯誤狀態圖示誤用）"
           endAction={{ icon: AlertCircle, label: '錯誤', onClick: () => {} }}
         />
         <Label warn>↑ 邊框已紅,再加尾部 icon = 雙重傳達 + 佔用 action 槽</Label>
@@ -252,4 +258,3 @@ export const ErrorRule: Story = {
     </div>
   ),
 }
-

package/src/components/Input/input.stories.tsx

@@ -58,7 +58,12 @@ export const SizeAlignment: Story = {
     <div className="flex flex-col gap-4">
       {(['sm', 'md', 'lg'] as const).map(size => (
         <div key={size} className="flex items-center gap-3">
-          <Input size={size} defaultValue="Wireless Bluetooth Headphones" className="max-w-xs" />
+          <Input
+            size={size}
+            defaultValue="Wireless Bluetooth Headphones"
+            aria-label={`商品名稱（${size} 尺寸）`}
+            className="max-w-xs"
+          />
           <Button variant="primary" size={size}>送出</Button>
           <span className="text-caption text-fg-muted">size="{size}"</span>
         </div>
@@ -83,6 +88,7 @@ export const EndAction: Story = {
           <Input
             type={showPwd ? 'text' : 'password'}
             defaultValue="my-secret-123"
+            aria-label="密碼"
             endAction={{
               icon: showPwd ? EyeOff : Eye,
               label: showPwd ? '隱藏密碼' : '顯示密碼',
@@ -96,6 +102,7 @@ export const EndAction: Story = {
             startIcon={Search}
             value={query}
             onChange={(e) => setQuery(e.target.value)}
+            aria-label="搜尋商品"
             endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
           />
         </div>
@@ -106,6 +113,7 @@ export const EndAction: Story = {
             startIcon={Search}
             value={queryLg}
             onChange={(e) => setQueryLg(e.target.value)}
+            aria-label="搜尋商品（大尺寸）"
             endAction={queryLg ? { icon: X, label: '清除搜尋', onClick: () => setQueryLg('') } : undefined}
           />
         </div>

package/src/components/Input/input.tsx

@@ -8,6 +8,7 @@ import { fieldWrapperStyles, bareInputStyles } from '@/design-system/components/
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { useControllable } from '@/design-system/hooks/use-controllable'
 import { ItemInlineAction, ItemPrefix, type InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
@@ -184,11 +185,15 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
               // B1 fix(2026-05-05):view mode 單行 ellipsis 截斷(對齊 Notion / Airtable / Linear
               //   cell display canonical:single-line value 過長 → ellipsis。Textarea view 走 wrap path,
               //   不在此處;Input view 永遠 single-line。)
-              'truncate',
+              'min-w-0',
               displayValue == null && fieldEmptyColorClass(resolvedMode),
             )}
           >
-            {displayValue ?? emptyDisplay}
+            {/* 2026-07-28:截斷必附 tooltip(tooltip.spec.md)—— 原本只有 `truncate` 沒有 tooltip,
+                長值被裁掉就再也讀不到。改消費 truncated-text primitive(截斷才顯,未截斷靜默)。 */}
+            {displayValue == null
+              ? emptyDisplay
+              : <TruncatedText>{displayValue}</TruncatedText>}
           </span>
         </div>
       )