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

package/src/components/CircularProgress/circular-progress.principles.stories.tsx

@@ -62,7 +62,7 @@ export const UsageGuidance: Story = {
           note="語意鎖「正在載入、正在處理」。永遠旋轉的裝飾會讓 a11y 使用者(螢幕閱讀器)持續收到 loading 通知,也讓視覺使用者無法判斷何時結束"
         >
           <div className="flex items-center gap-2 border border-border rounded-lg p-3 w-72">
-            <CircularProgress />
+            <CircularProgress aria-label="載入中（裝飾誤用示範）" />
             <span className="text-body">歡迎使用本系統</span>
           </div>
           <Label warn>Welcome banner 裡無限轉的 CircularProgress → 使用者以為系統卡住</Label>
@@ -76,7 +76,7 @@ export const UsageGuidance: Story = {
             {Array.from({ length: 4 }).map((_, i) => (
               <div key={i} className="flex items-center gap-2 border border-border rounded-md px-3 py-2">
                 {/* size=16 = field-inline canonical;此例為反例(不該多個一起轉)。 */}
-                <CircularProgress size={16} />
+                <CircularProgress size={16} aria-label={`載入項目 ${i + 1}`} />
                 <span className="text-body text-fg-muted">載入項目 {i + 1}</span>
               </div>
             ))}
@@ -104,7 +104,7 @@ export const UsageGuidance: Story = {
         >
           <div className="flex items-center gap-6">
             <div className="flex flex-col items-center gap-2">
-              <CircularProgress value={100} size={24} />
+              <CircularProgress value={100} size={24} aria-label="進度 100%（穩態誤用）" />
               <Label warn>❌ 穩態停留 100% → 使用者困惑</Label>
             </div>
             <div className="flex flex-col items-center gap-2">
@@ -166,7 +166,7 @@ export const IndeterminateVsDeterminateRule: Story = {
           <Label>✅ 第三方金流驗證:不知道要多久 → 不傳 value</Label>
         </div>
         <div className="flex flex-col items-center gap-2">
-          <CircularProgress value={65} affix="value" />
+          <CircularProgress value={65} affix="value" aria-label="檔案上傳進度 65%" />
           <Label>✅ 檔案上傳:bytes 已知 → 傳 value={'{N}'}</Label>
         </div>
       </Rule>
@@ -176,7 +176,7 @@ export const IndeterminateVsDeterminateRule: Story = {
         note="value 永遠停在 0% 或隨機亂跳會讓使用者懷疑 app 壞掉。若操作本質不可量化,維持 indeterminate 到底,不要硬傳 value 假裝。"
       >
         <div className="flex flex-col items-center gap-2">
-          <CircularProgress value={0} />
+          <CircularProgress value={0} aria-label="報表產生進度 0%（假進度誤用）" />
           <Label warn>❌ 生成報表中卻永遠卡 0% → 改用 indeterminate(不傳 value)</Label>
         </div>
       </Rule>
@@ -209,6 +209,7 @@ export const ConsumptionScenarioRule: Story = {
           loading
           defaultValue="cq@"
           placeholder="驗證 email 唯一性..."
+          aria-label="Email"
           className="w-72"
         />
         <Label>驗證 email 唯一性(GitHub 註冊場景)</Label>
@@ -244,6 +245,7 @@ export const SizeMatchContextRule: Story = {
           loading
           defaultValue="驗證中..."
           placeholder="驗證 email..."
+          aria-label="Email"
           className="w-60"
         />
       </Rule>
@@ -253,7 +255,7 @@ export const SizeMatchContextRule: Story = {
         note="中等尺寸,放在 row / card 內容區,視覺重量足夠吸引注意但不喧賓奪主"
       >
         <div className="flex items-center justify-center gap-2 border border-border rounded-lg p-4 w-72">
-          <CircularProgress size={24} />
+          <CircularProgress size={24} aria-label="載入更多留言" />
           <span className="text-body text-fg-muted">載入更多留言...</span>
         </div>
         <Label>Slack channel 載入更多訊息的 footer</Label>

package/src/components/CircularProgress/circular-progress.stories.tsx

@@ -35,7 +35,7 @@ export const Default: Story = {
           (Button loading = iconSize / Input loading = iconSize / Empty = iconSize)。
           不 parallel 展示多 sizes 因為 DS 不「提供各種 sizes」讓 consumer 挑,而是透過原則
           在 consumer 端自動決定(見 spec.md「Size canonical」)。 */}
-      <CircularProgress />
+      <CircularProgress aria-label="載入中" />
       <CircularProgress value={60} aria-label="進度 60%" />
       <CircularProgress value={90} affix="value" aria-label="進度 90%" />
     </div>
@@ -65,6 +65,7 @@ export const InlineAction: Story = {
           loading
           defaultValue="react-"
           placeholder="搜尋 GitHub repositories..."
+          aria-label="搜尋 GitHub repositories"
         />
 
         <div className="flex flex-col gap-2">
@@ -107,7 +108,7 @@ const syncColumns: ColumnDef<SyncRow>[] = [
         // 再加 leading-none 嘗試「壓縮行高」——那會讓 svg(16px) 與 text line box 互搶
         // 基線,反而歪掉。
         <span className="inline-flex items-center gap-2 text-fg-muted">
-          <CircularProgress size={16} />
+          <CircularProgress size={16} aria-label="同步中" />
           同步中
         </span>
       ) : (
@@ -142,4 +143,3 @@ export const FullScreenOverlay: Story = {
     </div>
   ),
 }
-

package/src/components/Combobox/combobox.tsx

@@ -880,6 +880,7 @@ function CustomCombobox({
       createLabel={createLabel}
       searchable={searchable && searchIn === 'menu'}
       searchPlaceholder={searchPlaceholder}
+      searchAriaLabel={searchAriaLabel}
       size={size}
       open={open}
       onOpenChange={(o) => { setOpen(o); onOpenChange?.(o) }}

package/src/components/Command/command.spec.md

@@ -87,6 +87,7 @@ cmdk 自動處理：
 - **搜尋框**：`role="combobox"` + `aria-expanded` / `aria-controls` 指向 list
 - **鍵盤導覽**：cmdk 提供 ↑ / ↓ 移動 highlight、Enter 選取（另支援 vim-style Ctrl+n/p/j/k、Home/End）。cmdk 本身無 Esc handler — Esc 關閉僅在 `CommandDialog`(Cmd+K)模式由 Radix Dialog 的 DismissableLayer 提供;inline `<Command>` 模式按 Esc 無反應
 - **空狀態**：`<CommandEmpty>` 自動帶 `role="presentation"`,不干擾 screen reader 的 list 朗讀
+- **分隔線**：`<CommandSeparator>` 是純視覺分組線,固定 `role="presentation"`；不冒充 listbox 選項或其他可導覽項目
 
 Consumer 無需額外處理 a11y,保留 cmdk 原結構 + 使用 `<CommandInput>` / `<CommandList>` / `<CommandItem>` 即可。
 

package/src/components/Command/command.tsx

@@ -131,7 +131,10 @@ const CommandSeparator = React.forwardRef<
     ref={ref}
     className={cn("h-px bg-divider", className)}
     {...props}
-  />
+    asChild
+  >
+    <div role="presentation" />
+  </CommandPrimitive.Separator>
 ))
 CommandSeparator.displayName = CommandPrimitive.Separator.displayName
 

package/src/components/DataTable/cell-registry.tsx

@@ -148,20 +148,16 @@ function StringCell({ value, meta, mode, size, autoRowHeight, onCommit, onCancel
     // → cell 進 edit shrink)。改 CSS `field-sizing: content`(Chrome 123+ / FF 122+ /
     // Safari 17+)讓 textarea 自動 grow to content,匹配 view wrap 真實高度。
     // Fallback rows 仍保留給舊 browser(rows attr 在 field-sizing 支援時被覆蓋)。
-    const newlineRows = (v.match(/\n/g) || []).length + 1
-    const wrapRows = Math.ceil(v.length / 40)
-    const estimateRows = Math.min(10, Math.max(1, newlineRows, wrapRows))
     return (
       <Textarea
         autoFocus
         variant="naked"
         aria-label={ariaLabel}
         size={sizeForInput(size)}
-        rows={estimateRows}
+        // 2026-07-28:原本 field-sizing + rows 估算是本檔的呼叫端膠水,只有 cell 有、InlineEdit 沒有
+        // → 兩者 edit 高度漂移。已提升為 Textarea `autoSize` 能力,兩個語境共用同一份實作。
+        autoSize
         defaultValue={v}
-        // any-allow: CSS `field-sizing` 屬性 Chrome 123+/FF 122+/Safari 17+ 支援但 TypeScript lib.dom
-        // 尚未加 type;narrow 到 CSSProperties 仍需 cast,保留 single-site any 較 type aug 簡潔。
-        style={{ fieldSizing: 'content' } as React.CSSProperties}
         onChange={(e) => onDraft?.((e.target as HTMLTextAreaElement).value)}
         onBlur={(e) => onCommit?.((e.target as HTMLTextAreaElement).value)}
         // 多行:走 edit-in-place 鍵盤結算 SSOT(IME guard + Esc + Cmd/Ctrl+Enter commit;

package/src/components/DataTable/data-table-filter-group.tsx

@@ -27,6 +27,7 @@ import {
 } from './filter-operators'
 import type { Conjunction, FilterCondition, FilterGroup } from './filter-tree'
 import { FilterValuePicker } from './data-table-filter-value-picker'
+import type { DataTableFilterPanelLabels } from './data-table-filter-labels'
 
 // ── Shared internal types + operator helpers(panel orchestration 也消費)────
 
@@ -40,9 +41,12 @@ export interface FilterColumn {
   includeTime?: boolean
 }
 
-function getOperatorOptions(type?: ColumnType): SelectOption[] {
+function getOperatorOptions(
+  type: ColumnType | undefined,
+  operatorLabels: DataTableFilterPanelLabels['operatorLabels'],
+): SelectOption[] {
   const registry = type && OPERATOR_REGISTRY[type] ? OPERATOR_REGISTRY[type] : OPERATOR_REGISTRY.string
-  return registry.map((op) => ({ value: op.op, label: op.label }))
+  return registry.map((op) => ({ value: op.op, label: operatorLabels[op.op] ?? op.label }))
 }
 
 export function getDefaultOperator(type?: ColumnType): string {
@@ -56,25 +60,25 @@ export const datePrecisionOf = (col: FilterColumn | undefined): 'day' | 'ms' | u
 
 // ── ConjunctionLabel ───────────────────────────────────────────────────
 
-const CONJ_OPTIONS: SelectOption[] = [
-  { value: 'and', label: 'And' },
-  { value: 'or', label: 'Or' },
-]
-
 function ConjunctionLabel({
-  index, conjunction, onChange,
-}: { index: number; conjunction: Conjunction; onChange: (c: Conjunction) => void }) {
+  index, conjunction, onChange, labels,
+}: {
+  index: number
+  conjunction: Conjunction
+  onChange: (c: Conjunction) => void
+  labels: DataTableFilterPanelLabels
+}) {
   // index === 0:首 row 顯示靜態「Where」label
   // index === 1:**唯一可改**的 AND/OR Select(連動整 group conjunction)
   // index ≥ 2:被連動的 row,read-only 顯示當前 conjunction 文字(同 Where 視覺,A6 canonical)
   //   對齊 Airtable / Notion / Linear 共識 @benchmark-unverified(non-OSS)
   //   px-[var(--field-px)] 對齊 Field 內部 padding 12px(Q13)
   if (index === 0) {
-    return <div className="w-20 shrink-0 text-body text-fg-muted px-[var(--field-px)] self-center">Where</div>
+    return <div className="w-20 shrink-0 text-body text-fg-secondary px-[var(--field-px)] self-center">{labels.where}</div>
   }
   if (index >= 2) {
-    const label = conjunction === 'and' ? 'And' : 'Or'
-    return <div className="w-20 shrink-0 text-body text-fg-muted px-[var(--field-px)] self-center">{label}</div>
+    const label = conjunction === 'and' ? labels.and : labels.or
+    return <div className="w-20 shrink-0 text-body text-fg-secondary px-[var(--field-px)] self-center">{label}</div>
   }
   // index === 1:可切換的 AND/OR Select
   // minRows={2} — And/Or 2 選項,顯式縮 menu 高度避免 reserve 3 row 空白(Q5)
@@ -82,11 +86,14 @@ function ConjunctionLabel({
     <div className="w-20 shrink-0">
       <Select
         size="sm"
-        options={CONJ_OPTIONS}
+        options={[
+          { value: 'and', label: labels.and },
+          { value: 'or', label: labels.or },
+        ]}
         value={conjunction}
         onChange={(v) => onChange(v as Conjunction)}
         minRows={2}
-        aria-label="連接詞 — 同 group 共用"
+        aria-label={labels.conjunctionAriaLabel}
       />
     </div>
   )
@@ -96,7 +103,7 @@ function ConjunctionLabel({
 
 export function FilterRow({
   index, condition, conjunction, filterableColumns, fieldOptions,
-  onChangeConjunction, onChangeField, onChangeOp, onChangeValue, onRemove,
+  onChangeConjunction, onChangeField, onChangeOp, onChangeValue, onRemove, labels,
 }: {
   index: number
   condition: FilterCondition
@@ -108,9 +115,10 @@ export function FilterRow({
   onChangeOp: (v: string) => void
   onChangeValue: (v: unknown) => void
   onRemove: () => void
+  labels: DataTableFilterPanelLabels
 }) {
   const colInfo = filterableColumns.find((c) => c.id === condition.field)
-  const operatorOptions = getOperatorOptions(colInfo?.type)
+  const operatorOptions = getOperatorOptions(colInfo?.type, labels.operatorLabels)
   const hasField = !!condition.field
   const opSpec = colInfo ? getOperatorSpec(colInfo.type, condition.op) : null
   const valueShape: ValueShape | null = colInfo && opSpec
@@ -129,7 +137,7 @@ export function FilterRow({
   //   - **#2 fix**:FilterValuePicker 直接是 FieldControlGroup direct child(無 wrapper div),CSS variants 命中正確
   return (
     <div className="flex items-center gap-2">
-      <ConjunctionLabel index={index} conjunction={conjunction} onChange={onChangeConjunction} />
+      <ConjunctionLabel index={index} conjunction={conjunction} onChange={onChangeConjunction} labels={labels} />
       {/* **#9 fix(2026-05-04 v4)**:Field controls trigger `w-full` override 外 className,改用 Tailwind `!`
           important 強制 override(`!w-[160px]` / `!w-[120px]`),value 用 `!flex-1 !min-w-0`。
           Select 元件本身沒 destructure `style` prop 所以 inline style flex-basis 行不通,只能用 className。 */}
@@ -138,13 +146,13 @@ export function FilterRow({
             `--data-table-filter-field-width` / `--data-table-filter-op-width`(SSOT in uiSize.css)
             Behavior preserved 完好如初:flat + nested 同 width(token 是 design constant) */}
         <Select
-          className="!w-[var(--data-table-filter-field-width)] flex-shrink-0"
+          className="!w-[var(--data-table-filter-field-width)] flex-shrink-0 [&_.text-fg-muted]:!text-fg-secondary"
           size="sm"
           options={fieldOptions}
           value={condition.field}
           onChange={onChangeField}
-          placeholder="選擇欄位"
-          aria-label="篩選欄位"
+          placeholder={labels.fieldPlaceholder}
+          aria-label={labels.fieldAriaLabel}
         />
         <Select
           className={hasValueCell ? '!w-[var(--data-table-filter-op-width)] flex-shrink-0' : '!flex-1 !min-w-0'}
@@ -153,8 +161,8 @@ export function FilterRow({
           value={condition.op}
           onChange={onChangeOp}
           disabled={!hasField}
-          placeholder="運算子"
-          aria-label="篩選運算子"
+          placeholder={labels.operatorPlaceholder}
+          aria-label={labels.operatorAriaLabel}
         />
         {hasValueCell && (
           <FilterValuePicker
@@ -163,13 +171,14 @@ export function FilterRow({
             onChange={onChangeValue}
             colInfo={colInfo}
             disabled={!hasField}
-            ariaLabel={colInfo ? `${colInfo.label} 篩選值` : '篩選值'}
+            ariaLabel={labels.filterValueAriaLabel(colInfo?.label)}
+            labels={labels}
             className="!flex-1 !min-w-0"
           />
         )}
       </FieldControlGroup>
       {/* Trash 用 text Button — filter row 是 form-control row,Field 同高對齊(28 md) */}
-      <Button variant="text" size="sm" iconOnly startIcon={Trash2} aria-label="刪除" onClick={onRemove} />
+      <Button variant="text" size="sm" iconOnly startIcon={Trash2} aria-label={labels.deleteCondition} onClick={onRemove} />
     </div>
   )
 }
@@ -180,6 +189,7 @@ export function GroupBlock({
   index, group, rootConjunction, filterableColumns, fieldOptions,
   onChangeRootConjunction, onChangeGroupConjunction,
   onChangeCondition, onRemoveCondition, onAddCondition, onRemoveGroup,
+  canAddCondition, labels,
 }: {
   index: number
   group: FilterGroup
@@ -192,11 +202,13 @@ export function GroupBlock({
   onRemoveCondition: (condId: string) => void
   onAddCondition: () => void
   onRemoveGroup: () => void
+  canAddCondition: boolean
+  labels: DataTableFilterPanelLabels
 }) {
   return (
     <div className="flex items-start gap-2">
       <div className="pt-2">
-        <ConjunctionLabel index={index} conjunction={rootConjunction} onChange={onChangeRootConjunction} />
+        <ConjunctionLabel index={index} conjunction={rootConjunction} onChange={onChangeRootConjunction} labels={labels} />
       </div>
       {/* Group container 灰底 — `bg-muted`(`--muted` neutral-2,user 2026-05-09 拍板 Q3 A)。對齊 color.spec.md L651-654 「table header / tab / code block / skeleton」靜態低重要 surface semantic */}
       <div className="flex-1 min-w-0 rounded-md bg-muted p-2 flex flex-col gap-2">
@@ -216,13 +228,18 @@ export function GroupBlock({
             onChangeOp={(v) => onChangeCondition(cond.id, { op: v, value: '' })}
             onChangeValue={(v) => onChangeCondition(cond.id, { value: v })}
             onRemove={() => onRemoveCondition(cond.id)}
+            labels={labels}
           />
         ))}
         {/* Q9 — text variant 對齊 inline 派 + 視覺輕量 */}
         <div className="flex items-center justify-between">
-          <Button variant="text" size="sm" startIcon={Plus} onClick={onAddCondition}>加入巢狀篩選</Button>
+          <Button variant="text" size="sm" startIcon={Plus} onClick={onAddCondition} disabled={!canAddCondition}>
+            {labels.addNestedFilter}
+          </Button>
           {group.children.length === 0 && (
-            <Button variant="text" size="sm" startIcon={Trash2} danger onClick={onRemoveGroup}>移除空群組</Button>
+            <Button variant="text" size="sm" startIcon={Trash2} danger onClick={onRemoveGroup}>
+              {labels.removeEmptyGroup}
+            </Button>
           )}
         </div>
       </div>

package/src/components/DataTable/data-table-filter-labels.ts

@@ -0,0 +1,100 @@
+// @internal — DataTableFilterPanel chrome/operator/value-picker labels shared by
+// panel orchestration, row/group rendering, and value-picker dispatch.
+
+import type { DATE_RELATIVE_GROUPS, DATE_RELATIVE_OPTIONS } from './filter-operators'
+
+type RelativeDateGroupKey = (typeof DATE_RELATIVE_GROUPS)[number]['key']
+type RelativeDateValue = (typeof DATE_RELATIVE_OPTIONS)[number]['value']
+
+export interface DataTableFilterPanelLabels {
+  title: string
+  resetToDefault: string
+  close: string
+  where: string
+  and: string
+  or: string
+  conjunctionAriaLabel: string
+  fieldPlaceholder: string
+  fieldAriaLabel: string
+  operatorPlaceholder: string
+  operatorAriaLabel: string
+  valuePlaceholder: string
+  numberPlaceholder: string
+  relativeDatePlaceholder: string
+  singleSelectPlaceholder: string
+  multiSelectPlaceholder: string
+  multiSelectEmptyText: string
+  peoplePlaceholder: string
+  peopleSearchPlaceholder: string
+  peopleSearchAriaLabel: string
+  peopleEmptyText: string
+  filterValueAriaLabel: (columnLabel?: string) => string
+  deleteCondition: string
+  addFilter: string
+  addGroup: string
+  addNestedFilter: string
+  removeEmptyGroup: string
+  /**
+   * Operator key → visible label override. Missing keys fall back to
+   * `OPERATOR_REGISTRY` labels, preserving the registry as the default SSOT.
+   */
+  operatorLabels: Partial<Record<string, string>>
+  /** Relative-date group/value overrides; missing keys retain registry defaults. */
+  relativeDateGroupLabels: Partial<Record<RelativeDateGroupKey, string>>
+  relativeDateOptionLabels: Partial<Record<RelativeDateValue, string>>
+}
+
+// code-quality-allow: dead-export — public i18n defaults, re-exported by panel.
+export const DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS: DataTableFilterPanelLabels = {
+  title: '篩選',
+  resetToDefault: '恢復預設',
+  close: '關閉',
+  where: 'Where',
+  and: 'And',
+  or: 'Or',
+  conjunctionAriaLabel: '連接詞 — 同 group 共用',
+  fieldPlaceholder: '選擇欄位',
+  fieldAriaLabel: '篩選欄位',
+  operatorPlaceholder: '運算子',
+  operatorAriaLabel: '篩選運算子',
+  valuePlaceholder: '輸入值…',
+  numberPlaceholder: '輸入數字…',
+  relativeDatePlaceholder: '選擇相對日期',
+  singleSelectPlaceholder: '選擇值',
+  multiSelectPlaceholder: '選擇值…',
+  multiSelectEmptyText: '沒有符合的值',
+  peoplePlaceholder: '選擇人員',
+  peopleSearchPlaceholder: '搜尋人員…',
+  peopleSearchAriaLabel: '搜尋篩選人員',
+  peopleEmptyText: '沒有符合的人員',
+  filterValueAriaLabel: (columnLabel) => columnLabel ? `${columnLabel} 篩選值` : '篩選值',
+  deleteCondition: '刪除',
+  addFilter: '加篩選',
+  addGroup: '加入篩選器',
+  addNestedFilter: '加入巢狀篩選',
+  removeEmptyGroup: '移除空群組',
+  operatorLabels: {},
+  relativeDateGroupLabels: {},
+  relativeDateOptionLabels: {},
+}
+
+export function resolveDataTableFilterPanelLabels(
+  overrides?: Partial<DataTableFilterPanelLabels>,
+): DataTableFilterPanelLabels {
+  return {
+    ...DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS,
+    ...overrides,
+    operatorLabels: {
+      ...DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS.operatorLabels,
+      ...overrides?.operatorLabels,
+    },
+    relativeDateGroupLabels: {
+      ...DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS.relativeDateGroupLabels,
+      ...overrides?.relativeDateGroupLabels,
+    },
+    relativeDateOptionLabels: {
+      ...DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS.relativeDateOptionLabels,
+      ...overrides?.relativeDateOptionLabels,
+    },
+  }
+}

package/src/components/DataTable/data-table-filter-panel.tsx

@@ -31,6 +31,11 @@ import {
   type FilterTreeFlat,
   type FilterTreeNested,
 } from './filter-tree'
+import {
+  DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS,
+  resolveDataTableFilterPanelLabels,
+  type DataTableFilterPanelLabels,
+} from './data-table-filter-labels'
 
 // Re-export public API from filter-tree(consumer 既有 import path 不變)
 export {
@@ -40,6 +45,8 @@ export {
   dataTableFilterMatch,
 }
 export type { Conjunction, FilterCondition, FilterGroup, FilterTree, FilterTreeFlat, FilterTreeNested }
+export { DATA_TABLE_FILTER_PANEL_DEFAULT_LABELS }
+export type { DataTableFilterPanelLabels }
 
 /**
  * DataTableFilterPanel — ClickUp-style 進階篩選 panel
@@ -123,6 +130,17 @@ const newEmptyGroup = (): FilterGroup => ({
   children: [newEmptyCondition()],
 })
 
+const countFilterConditions = (tree: FilterTree): number =>
+  tree.mode === 'flat'
+    ? tree.children.length
+    : tree.children.reduce((total, group) => total + group.children.length, 0)
+
+const normalizeMaxConditions = (maxConditions: number | undefined): number => {
+  if (maxConditions === undefined || maxConditions === Number.POSITIVE_INFINITY) return Number.POSITIVE_INFINITY
+  if (!Number.isFinite(maxConditions)) return 0
+  return Math.max(0, Math.floor(maxConditions))
+}
+
 // ── Component Props ─────────────────────────────────────────────────────
 
 export interface DataTableFilterPanelProps<TData> {
@@ -144,6 +162,14 @@ export interface DataTableFilterPanelProps<TData> {
   /** Cell ⌄ menu「Filter by this」帶入的 column id(自動 add 一條 condition) */
   prefilledColumnId?: string
   onPrefillConsumed?: () => void
+  /**
+   * Condition leaf 上限(flat children 或 nested 所有 group.children 的總和)。
+   * 預設不限。到上限後所有 add 路徑與 prefill 都 fail closed；controlled value
+   * 已超過上限時保留原資料、不裁切，只停用後續新增。
+   */
+  maxConditions?: number
+  /** Panel chrome/operator/value-picker labels. Nested maps are deep-merged with defaults. */
+  labels?: Partial<DataTableFilterPanelLabels>
   onClose?: () => void
   className?: string
 }
@@ -158,6 +184,8 @@ function DataTableFilterPanelInner<TData>({
   defaultValue,
   prefilledColumnId,
   onPrefillConsumed,
+  maxConditions,
+  labels: labelsOverride,
   onClose,
   className,
 }: DataTableFilterPanelProps<TData>, ref: React.ForwardedRef<HTMLDivElement>): React.ReactElement {
@@ -166,6 +194,13 @@ function DataTableFilterPanelInner<TData>({
     () => filterableColumns.map((c) => ({ value: c.id, label: c.label })),
     [filterableColumns],
   )
+  const labels = React.useMemo(
+    () => resolveDataTableFilterPanelLabels(labelsOverride),
+    [labelsOverride],
+  )
+  const conditionCount = countFilterConditions(value)
+  const normalizedMaxConditions = normalizeMaxConditions(maxConditions)
+  const canAddCondition = conditionCount < normalizedMaxConditions
   // K13 後 firstCol 不再被 add* 消費(改用 newEmpty*),這裡只留 prefill effect 用(已直接讀 prefilledColumnId)。
 
   // **G fix(2026-05-04 v2)**:initial-mount 預設 1 empty row(field 未選 → op+value 自動 disabled)
@@ -179,6 +214,7 @@ function DataTableFilterPanelInner<TData>({
     initialMountDoneRef.current = true
     if (filterableColumns.length === 0) return
     if (value.children.length > 0) return
+    if (!canAddCondition) return
     if (value.mode === 'flat') {
       onChange({ ...value, children: [newEmptyCondition()] } as FilterTreeFlat)
     } else {
@@ -191,7 +227,7 @@ function DataTableFilterPanelInner<TData>({
   React.useEffect(() => {
     if (!prefilledColumnId) return
     const colInfo = filterableColumns.find((c) => c.id === prefilledColumnId)
-    if (colInfo) {
+    if (colInfo && canAddCondition) {
       const cond: FilterCondition = {
         kind: 'cond',
         id: newId(),
@@ -234,7 +270,7 @@ function DataTableFilterPanelInner<TData>({
     onChange({ ...flatTree, children: flatTree.children.filter((c) => c.id !== id) })
   }
   const addFlatCondition = () => {
-    if (!flatTree) return
+    if (!flatTree || !canAddCondition) return
     // K13 fix(2026-05-04):加篩選 → empty row(field 未選 → op+value disabled)
     //   World-class:Notion / Coda / ClickUp 不 auto-select;對齊 initial mount canonical
     onChange({ ...flatTree, children: [...flatTree.children, newEmptyCondition()] })
@@ -275,7 +311,7 @@ function DataTableFilterPanelInner<TData>({
   }
   // K13 fix(2026-05-04):同 addFlatCondition,巢狀內加條件也 empty row
   const addConditionToGroup = (groupId: string) => {
-    if (!nestedTree) return
+    if (!nestedTree || !canAddCondition) return
     onChange({
       ...nestedTree,
       children: nestedTree.children.map((g) =>
@@ -288,7 +324,7 @@ function DataTableFilterPanelInner<TData>({
     onChange({ ...nestedTree, children: nestedTree.children.filter((g) => g.id !== groupId) })
   }
   const addGroup = () => {
-    if (!nestedTree) return
+    if (!nestedTree || !canAddCondition) return
     // K13:加群組也用 empty group
     onChange({ ...nestedTree, children: [...nestedTree.children, newEmptyGroup()] })
   }
@@ -321,14 +357,14 @@ function DataTableFilterPanelInner<TData>({
     )}>
       {/* Popover 派輕量 chrome — slot 走 COMPACT_HEADER_SLOT(=21,衍生自 PopoverTitle text-body line-box),header 自然 ~45px */}
       <SurfaceHeader className={COMPACT_HEADER_SLOT}>
-        <PopoverTitle className="flex-1">篩選</PopoverTitle>
+        <PopoverTitle className="flex-1">{labels.title}</PopoverTitle>
         {/* Refresh icon — 只在 value ≠ defaultValue 時顯示(對齊 sort modified-from-default UX)
             含 ButtonDivider 對齊「欄位顯示」+「排序」chrome corner action canonical(2026-05-04) */}
         {defaultValue && !isFilterTreeEqual(value, defaultValue) && (
           <>
             <Button
               variant="text" size="sm" iconOnly startIcon={RotateCcw}
-              aria-label="恢復預設"
+              aria-label={labels.resetToDefault}
               onClick={() => onChange(defaultValue)}
             />
             {onClose && <ButtonDivider />}
@@ -336,7 +372,7 @@ function DataTableFilterPanelInner<TData>({
         )}
         {onClose && (
           <PopoverClose asChild>
-            <Button data-dismiss iconOnly dismiss size="sm" startIcon={XIcon} aria-label="關閉" onClick={onClose} />
+            <Button data-dismiss iconOnly dismiss size="sm" startIcon={XIcon} aria-label={labels.close} onClick={onClose} />
           </PopoverClose>
         )}
       </SurfaceHeader>
@@ -361,6 +397,7 @@ function DataTableFilterPanelInner<TData>({
             onChangeOp={(v) => updateFlatCondition(cond.id, { op: v, value: '' })}
             onChangeValue={(v) => updateFlatCondition(cond.id, { value: v })}
             onRemove={() => removeFlatCondition(cond.id)}
+            labels={labels}
           />
         ))}
 
@@ -378,6 +415,8 @@ function DataTableFilterPanelInner<TData>({
             onRemoveCondition={(condId) => removeGroupCondition(group.id, condId)}
             onAddCondition={() => addConditionToGroup(group.id)}
             onRemoveGroup={() => removeGroup(group.id)}
+            canAddCondition={canAddCondition}
+            labels={labels}
           />
         ))}
 
@@ -388,8 +427,9 @@ function DataTableFilterPanelInner<TData>({
           <Button
             variant="tertiary" size="sm" startIcon={Plus}
             onClick={value.mode === 'flat' ? addFlatCondition : addGroup}
+            disabled={!canAddCondition}
           >
-            {value.mode === 'nested' ? '加入篩選器' : '加篩選'}
+            {value.mode === 'nested' ? labels.addGroup : labels.addFilter}
           </Button>
         </div>
       </SurfaceBody>