@h-ai/ui 0.1.0-alpha.31 → 0.1.0-alpha.32

package/dist/components/compounds/Combobox.svelte

@@ -36,7 +36,7 @@
   import type { DataAttributes } from '../../types.js'
   import { Combobox } from 'bits-ui'
   import { uiM } from '../../messages.js'
-  import { getDataAttributes } from '../../utils.js'
+  import { cn, getDataAttributes } from '../../utils.js'
   import BareButton from '../primitives/BareButton.svelte'
 
   /** 选项定义 */
@@ -93,8 +93,18 @@
     value = ''
   }
 
+  // ─── 统一视觉样式（与 Select 对齐：rounded-lg / 柔和边框 / focus ring） ───
+  const controlStateClass = $derived(
+    error
+      ? 'border-error/60 focus-within:ring-2 focus-within:ring-error/15'
+      : 'border-base-content/15 hover:border-base-content/25 focus-within:border-primary/50 focus-within:ring-2 focus-within:ring-primary/10',
+  )
+  const contentClass = 'z-[1200] mt-1.5 max-h-60 w-(--bits-combobox-anchor-width) overflow-y-auto rounded-xl border border-base-content/10 bg-base-100 p-1.5 shadow-xl shadow-base-content/10'
+  const itemClass = 'flex cursor-pointer items-center gap-2 rounded-lg px-3 py-2.5 text-sm transition-colors hover:bg-base-content/5 data-highlighted:bg-base-content/5 data-disabled:cursor-not-allowed data-disabled:opacity-40'
+
   let searchValue = $state('')
   let open = $state(false)
+  let inputRef = $state<HTMLInputElement | null>(null)
 
   /** 根据搜索关键词过滤选项 */
   const filteredOptions = $derived(
@@ -131,6 +141,19 @@
   /** 单选模式：提供给 Combobox.Root 的类型安全值 */
   const singleVal = $derived(typeof value === 'string' ? value : '')
 
+  function syncInputElementValue() {
+    if (!inputRef)
+      return
+    const nextValue = multiple ? multiInputValue : singleInputValue
+    if (inputRef.value !== nextValue) {
+      inputRef.value = nextValue
+    }
+  }
+
+  $effect(() => {
+    syncInputElementValue()
+  })
+
   function handleInput(e: Event & { currentTarget: HTMLInputElement }) {
     searchValue = e.currentTarget.value
     if (!open)
@@ -145,11 +168,19 @@
   function handleMultiValueChange(v: string[]) {
     value = v
     onchange?.(v)
+    setTimeout(() => {
+      searchValue = ''
+      syncInputElementValue()
+    }, 0)
   }
 
   function handleSingleValueChange(v: string) {
     value = v
     onchange?.(v)
+    setTimeout(() => {
+      searchValue = ''
+      syncInputElementValue()
+    }, 0)
   }
 
   /** 多选模式下移除某个已选项 */
@@ -182,18 +213,20 @@
     >
       <div class='relative'>
         <div
-          class="min-h-10 px-2 py-1.5 pr-8 border rounded-lg bg-base-100 flex flex-wrap gap-1.5 items-center transition-colors
-            {disabled ? 'opacity-50 cursor-not-allowed bg-base-200' : 'cursor-text'}
-            {error ? 'border-error focus-within:border-error' : 'border-base-content/20 focus-within:border-primary focus-within:ring-1 focus-within:ring-primary/20'}"
+          class={cn(
+            'min-h-10 rounded-lg border bg-base-100 flex flex-wrap gap-1.5 items-center py-1.5 pl-2.5 pr-9 transition-[border-color,box-shadow] duration-150',
+            disabled ? 'opacity-50 cursor-not-allowed bg-base-200' : 'cursor-text',
+            controlStateClass,
+          )}
         >
           {#each selectedOptions as opt (opt.value)}
-            <span class='inline-flex items-center gap-1 px-2 py-0.5 bg-primary/10 text-primary text-sm rounded-md'>
+            <span class='inline-flex items-center gap-1 rounded-md bg-primary/10 px-2 py-0.5 text-sm text-primary'>
               <span class='truncate max-w-32'>{opt.label}</span>
               {#if !disabled}
                 <BareButton
                   type='button'
-                  class='hover:bg-primary/20 rounded p-0.5 transition-colors'
-                  onclick={e => removeItem(opt.value, e)}
+                  class='rounded p-0.5 transition-colors hover:bg-primary/20'
+                  onclick={(e: MouseEvent) => removeItem(opt.value, e)}
                   ariaLabel="{uiM('combobox_remove')} {opt.label}"
                 >
                   <span class='icon-[tabler--x] size-3'></span>
@@ -203,7 +236,8 @@
           {/each}
 
           <Combobox.Input
-            class='flex-1 min-w-20 bg-transparent outline-none text-sm py-0.5'
+            bind:ref={inputRef}
+            class='flex-1 min-w-20 bg-transparent py-0.5 text-sm outline-none placeholder:text-base-content/40'
             placeholder={selectedOptions.length === 0 ? placeholder : ''}
             {disabled}
             oninput={handleInput}
@@ -215,7 +249,7 @@
         </div>
 
         <Combobox.Trigger
-          class='absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle'
+          class='absolute right-2.5 top-1/2 flex size-5 -translate-y-1/2 items-center justify-center text-base-content/40 transition-colors hover:text-base-content/70'
         >
           <span class="icon-[tabler--chevron-down] size-4 transition-transform {open ? 'rotate-180' : ''}"></span>
         </Combobox.Trigger>
@@ -223,11 +257,11 @@
 
       <Combobox.Portal>
         <Combobox.Content
-          class='z-50 mt-1 max-h-60 w-[var(--bits-combobox-anchor-width)] overflow-y-auto rounded-lg border border-base-content/10 bg-base-100 p-1 shadow-lg'
+          class={contentClass}
           sideOffset={4}
         >
           {#if filteredOptions.length === 0}
-            <div class='px-3 py-2 text-sm text-base-content/50'>
+            <div class='px-3 py-2.5 text-sm text-base-content/50'>
               {uiM('combobox_no_match')}
             </div>
           {:else}
@@ -236,10 +270,10 @@
                 value={opt.value}
                 label={opt.label}
                 disabled={opt.disabled}
-                class='flex cursor-pointer items-center gap-2 rounded-md px-3 py-2 text-sm transition-colors hover:bg-base-200 data-[highlighted]:bg-base-200 data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50'
+                class={itemClass}
               >
                 {#snippet children({ selected })}
-                  <span class="size-4 shrink-0 rounded border border-base-content/30 flex items-center justify-center {selected ? 'bg-primary border-primary' : ''}">
+                  <span class="flex size-4 shrink-0 items-center justify-center rounded border border-base-content/30 {selected ? 'border-primary bg-primary' : ''}">
                     {#if selected}
                       <span class='icon-[tabler--check] size-3 text-primary-content'></span>
                     {/if}
@@ -247,7 +281,7 @@
                   <div class='flex-1 min-w-0'>
                     <span>{opt.label}</span>
                     {#if opt.description}
-                      <div class='text-xs text-base-content/50 truncate'>{opt.description}</div>
+                      <div class='truncate text-xs text-base-content/50'>{opt.description}</div>
                     {/if}
                   </div>
                 {/snippet}
@@ -271,7 +305,12 @@
     >
       <div class='relative'>
         <Combobox.Input
-          class="input w-full pr-8 {error ? 'input-error' : ''}"
+          bind:ref={inputRef}
+          class={cn(
+            'h-10 w-full rounded-lg border bg-base-100 pl-3 pr-9 text-sm outline-none transition-[border-color,box-shadow] duration-150 placeholder:text-base-content/40',
+            controlStateClass,
+            disabled && 'opacity-50 cursor-not-allowed',
+          )}
           {placeholder}
           {disabled}
           oninput={handleInput}
@@ -281,7 +320,7 @@
           }}
         />
         <Combobox.Trigger
-          class='absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle'
+          class='absolute right-2.5 top-1/2 flex size-5 -translate-y-1/2 items-center justify-center text-base-content/40 transition-colors hover:text-base-content/70'
         >
           <span class="icon-[tabler--chevron-down] size-4 transition-transform {open ? 'rotate-180' : ''}"></span>
         </Combobox.Trigger>
@@ -289,11 +328,11 @@
 
       <Combobox.Portal>
         <Combobox.Content
-          class='z-50 mt-1 max-h-60 w-[var(--bits-combobox-anchor-width)] overflow-y-auto rounded-lg border border-base-content/10 bg-base-100 p-1 shadow-lg'
+          class={contentClass}
           sideOffset={4}
         >
           {#if filteredOptions.length === 0}
-            <div class='px-3 py-2 text-sm text-base-content/50'>
+            <div class='px-3 py-2.5 text-sm text-base-content/50'>
               {uiM('combobox_no_match')}
             </div>
           {:else}
@@ -302,7 +341,7 @@
                 value={opt.value}
                 label={opt.label}
                 disabled={opt.disabled}
-                class='flex cursor-pointer items-center gap-2 rounded-md px-3 py-2 text-sm transition-colors hover:bg-base-200 data-[highlighted]:bg-base-200 data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50'
+                class={cn(itemClass, 'data-selected:bg-primary/10 data-selected:text-primary data-selected:font-medium')}
               >
                 {#snippet children({ selected })}
                   <span class='size-4 shrink-0'>
@@ -313,7 +352,7 @@
                   <div class='flex-1 min-w-0'>
                     <span>{opt.label}</span>
                     {#if opt.description}
-                      <div class='text-xs text-base-content/50 truncate'>{opt.description}</div>
+                      <div class='truncate text-xs text-base-content/50'>{opt.description}</div>
                     {/if}
                   </div>
                 {/snippet}

package/dist/components/compounds/Pagination.svelte

@@ -41,6 +41,7 @@
   const controlSize = $derived(size === 'xs' ? 'xs' : 'sm')
   const jumperControlSize = 'xs'
   const sizeChangerClass = $derived(size === 'xs' ? 'w-17 shrink-0' : 'w-18 shrink-0')
+  const pageSizeSelectOptions = $derived(pageSizeOptions.map(opt => ({ value: String(opt), label: String(opt) })))
   const jumperWrapClass = $derived(size === 'xs' ? 'flex min-w-fit items-center gap-1.5 whitespace-nowrap' : 'flex min-w-fit items-center gap-2 whitespace-nowrap')
   const jumperInputClass = $derived(
     size === 'xs'
@@ -105,12 +106,9 @@
           <Select
             size={controlSize}
             value={String(pageSize)}
+            options={pageSizeSelectOptions}
             onchange={handlePageSizeChange}
-          >
-            {#each pageSizeOptions as opt (opt)}
-              <option value={String(opt)}>{opt}</option>
-            {/each}
-          </Select>
+          />
         </div>
       </div>
     {/if}

package/dist/components/primitives/Select.svelte

@@ -10,7 +10,7 @@
 -->
 <script lang='ts' generics="T = string">
   import type { DataAttributes, SelectProps } from '../../types.js'
-  import { cn, getDataAttributes } from '../../utils.js'
+  import { cn, getDataAttributes, portal } from '../../utils.js'
 
   let {
     value = $bindable<T>(),
@@ -31,16 +31,21 @@
   const dataAttributes = $derived(getDataAttributes(restProps))
   let inputRef: HTMLInputElement | undefined = $state()
   let dropdownRef: HTMLDivElement | undefined = $state()
+  let triggerRef: HTMLDivElement | undefined = $state()
+  let listboxRef: HTMLUListElement | undefined = $state()
   let isDropdownOpen = $state(false)
   let filterText = $state('')
   let isHovered = $state(false)
+  // 下拉层定位样式（portal 到 body，用 fixed 逃逸 overflow/stacking）
+  let dropdownStyle = $state('')
 
-  // 尺寸映射
+  // 尺寸映射（与 Input 保持一致）
   const sizeClasses: Record<string, string> = {
-    xs: 'h-7 text-xs px-2',
+    xs: 'h-8 text-xs px-2.5',
     sm: 'h-9 text-sm px-3',
     md: 'h-10 text-sm px-3',
     lg: 'h-12 text-base px-4',
+    xl: 'h-14 text-lg px-4',
   }
 
   // 选项文字尺寸
@@ -49,6 +54,8 @@
       ? 'text-xs'
       : size === 'lg'
       ? 'text-base'
+      : size === 'xl'
+      ? 'text-lg'
       : 'text-sm',
   )
 
@@ -73,7 +80,7 @@
 
   const wrapperClass = $derived(
     cn(
-      'relative flex w-full items-center rounded-lg border bg-base-100 cursor-pointer',
+      'relative flex w-full min-w-0 items-center rounded-lg border bg-base-100 cursor-pointer',
       sizeClasses[size] || sizeClasses.md,
       error
         ? 'border-error/60 focus-within:ring-2 focus-within:ring-error/15'
@@ -82,6 +89,7 @@
         : 'border-base-content/15 hover:border-base-content/25 focus-within:border-primary/50 focus-within:ring-2 focus-within:ring-primary/10',
       'transition-[border-color,box-shadow] duration-150',
       disabled && 'opacity-50 cursor-not-allowed',
+      className,
     ),
   )
 
@@ -91,14 +99,16 @@
       'focus:outline-none focus:ring-0 focus:shadow-none',
       'placeholder:text-base-content/40',
       error && 'text-error',
-      className,
     ),
   )
 
-  // 点击外部关闭下拉框
+  // 点击外部关闭下拉框（下拉层已 portal 到 body，需同时排除 listbox）
   $effect(() => {
     function handleClickOutside(e: MouseEvent) {
-      if (dropdownRef && !dropdownRef.contains(e.target as Node)) {
+      const target = e.target as Node
+      const inTrigger = dropdownRef?.contains(target) ?? false
+      const inListbox = listboxRef?.contains(target) ?? false
+      if (!inTrigger && !inListbox) {
         isDropdownOpen = false
         filterText = ''
       }
@@ -110,6 +120,35 @@
     }
   })
 
+  // 计算下拉层位置（fixed，基于触发器视口坐标；空间不足时向上翻转）
+  function updateDropdownPosition() {
+    if (!triggerRef)
+      return
+    const rect = triggerRef.getBoundingClientRect()
+    const gap = 4
+    const maxHeight = 240
+    const spaceBelow = window.innerHeight - rect.bottom
+    const openUp = spaceBelow < maxHeight + gap && rect.top > spaceBelow
+    const vertical = openUp
+      ? `bottom:${Math.round(window.innerHeight - rect.top + gap)}px`
+      : `top:${Math.round(rect.bottom + gap)}px`
+    dropdownStyle = `position:fixed;left:${Math.round(rect.left)}px;width:${Math.round(rect.width)}px;${vertical};z-index:1200;`
+  }
+
+  // 打开时定位并跟随滚动/缩放更新
+  $effect(() => {
+    if (!isDropdownOpen)
+      return
+    updateDropdownPosition()
+    const scrollOpts = { passive: true, capture: true } as const
+    window.addEventListener('scroll', updateDropdownPosition, scrollOpts)
+    window.addEventListener('resize', updateDropdownPosition)
+    return () => {
+      window.removeEventListener('scroll', updateDropdownPosition, scrollOpts)
+      window.removeEventListener('resize', updateDropdownPosition)
+    }
+  })
+
   function handleWrapperClick() {
     if (disabled)
       return
@@ -173,7 +212,7 @@
 
 <div
   {...dataAttributes}
-  class='fieldset w-full'
+  class='fieldset w-full min-w-0'
   bind:this={dropdownRef}
   role='combobox'
   aria-expanded={isDropdownOpen}
@@ -183,6 +222,7 @@
 >
   <div
     class={wrapperClass}
+    bind:this={triggerRef}
     onclick={handleWrapperClick}
     onkeydown={(e) => {
       if (e.key === 'Enter' || e.key === ' ') {
@@ -255,13 +295,15 @@
       {/if}
     </div>
 
-    <!-- 下拉选项列表 -->
+    <!-- 下拉选项列表（portal 到 body，fixed 定位，逃逸 overflow/stacking 裁剪） -->
     {#if isDropdownOpen}
       <ul
+        bind:this={listboxRef}
+        use:portal
         id='{id}-listbox'
-        class='absolute left-0 z-50 mt-2 w-full max-h-60 overflow-auto rounded-xl border border-base-content/10 bg-base-100 p-1.5 shadow-xl shadow-base-content/10'
+        class='max-h-60 overflow-auto rounded-xl border border-base-content/10 bg-base-100 p-1.5 shadow-xl shadow-base-content/10'
+        style={dropdownStyle}
         role='listbox'
-        style='top: 100%;'
       >
         {#each filteredOptions() as option (String(option.value))}
           <li

package/dist/components/scenes/app/FeedbackModal.svelte

@@ -55,9 +55,10 @@
     open?: boolean
     labels?: FeedbackLabels
     onsubmit?: (data: FeedbackData) => Promise<void>
+    class?: string
   }
 
-  let { open = $bindable(false), labels = {}, onsubmit, ...restProps }: Props & DataAttributes = $props()
+  let { open = $bindable(false), labels = {}, onsubmit, class: className = '', ...restProps }: Props & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
   // 文案优先使用传入的 labels，缺省回退到内置消息 uiM(...)
@@ -109,7 +110,7 @@
   }
 </script>
 
-<Modal {...dataAttributes} bind:open title={labels.title ?? uiM('feedback_title')}>
+<Modal {...dataAttributes} class={className} bind:open title={labels.title ?? uiM('feedback_title')}>
   <p class='text-base-content/70 mb-4'>{labels.description ?? uiM('feedback_description')}</p>
 
   {#if error}

package/dist/components/scenes/app/FeedbackModal.svelte.d.ts

@@ -29,6 +29,7 @@ interface Props {
     open?: boolean;
     labels?: FeedbackLabels;
     onsubmit?: (data: FeedbackData) => Promise<void>;
+    class?: string;
 }
 type $$ComponentProps = Props & DataAttributes;
 /**

package/dist/components/scenes/app/SettingsModal.svelte

@@ -12,7 +12,7 @@
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
   import { uiM } from '../../../messages.js'
-  import { getDataAttributes } from '../../../utils.js'
+  import { cn, getDataAttributes } from '../../../utils.js'
   import BareButton from '../../primitives/BareButton.svelte'
   import IconButton from '../../primitives/IconButton.svelte'
 
@@ -25,6 +25,7 @@
     onlanguagechange?: (lang: string) => void
     onthemechange?: (theme: string) => void
     onclose?: () => void
+    class?: string
   }
 
   let {
@@ -45,6 +46,7 @@
     onlanguagechange,
     onthemechange,
     onclose,
+    class: className = '',
     ...restProps
   }: Props & DataAttributes = $props()
 
@@ -76,7 +78,7 @@
     onclick={handleBackdropClick}
   >
     <div
-      class='relative w-full max-w-lg mx-4 transform overflow-hidden rounded-2xl bg-base-100 shadow-xl transition-all'
+      class={cn('relative w-full max-w-lg mx-4 transform overflow-hidden rounded-2xl bg-base-100 shadow-xl transition-all', className)}
       role='dialog'
       aria-modal='true'
     >

package/dist/components/scenes/app/SettingsModal.svelte.d.ts

@@ -15,6 +15,7 @@ interface Props {
     onlanguagechange?: (lang: string) => void;
     onthemechange?: (theme: string) => void;
     onclose?: () => void;
+    class?: string;
 }
 type $$ComponentProps = Props & DataAttributes;
 /**

package/dist/components/scenes/crud/CrudDeleteConfirm.svelte

@@ -18,6 +18,7 @@
     message = '',
     onconfirm,
     oncancel,
+    class: className = '',
     ...restProps
   }: {
     open?: boolean
@@ -26,12 +27,14 @@
     message?: string
     onconfirm?: () => Promise<void> | void
     oncancel?: () => void
+    class?: string
   } & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
 </script>
 
 <Confirm {...dataAttributes}
+         class={className}
          bind:open
          title={title || uiM('crud_delete_title')}
          message={message || uiM('crud_delete_message')}

package/dist/components/scenes/crud/CrudDeleteConfirm.svelte.d.ts

@@ -6,6 +6,7 @@ type $$ComponentProps = {
     message?: string;
     onconfirm?: () => Promise<void> | void;
     oncancel?: () => void;
+    class?: string;
 } & DataAttributes;
 /**
  * CrudDeleteConfirm

package/dist/components/scenes/crud/CrudDetailDrawer.svelte

@@ -41,6 +41,7 @@
     onedit,
     onclose,
     detailExtra,
+    class: className = '',
     ...restProps
   }: {
     open?: boolean
@@ -57,6 +58,7 @@
     onedit?: () => void
     onclose?: () => void
     detailExtra?: Snippet<[Record<string, unknown>]>
+    class?: string
   } & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
@@ -171,6 +173,7 @@
 {#if variant === 'modal'}
   <Modal
     bind:open
+    class={className}
     {title}
     size={modalSize}
     width={modalWidth}
@@ -184,7 +187,7 @@
     {/snippet}
   </Modal>
 {:else}
-  <Drawer bind:open {title} position='right' {size} width={drawerWidth} onclose={handleClose}>
+  <Drawer bind:open {title} class={className} position='right' {size} width={drawerWidth} onclose={handleClose}>
     {#if item}
       <div class='pb-20'>
         {@render detailBody()}

package/dist/components/scenes/crud/CrudDetailDrawer.svelte.d.ts

@@ -31,6 +31,7 @@ type $$ComponentProps = {
     onedit?: () => void;
     onclose?: () => void;
     detailExtra?: Snippet<[Record<string, unknown>]>;
+    class?: string;
 } & DataAttributes;
 /**
  * CrudDetailDrawer

package/dist/components/scenes/crud/CrudDetailPanel.svelte

@@ -42,6 +42,7 @@
     onedit,
     onclose,
     detailExtra,
+    class: className = '',
     ...restProps
   }: {
     open?: boolean
@@ -59,6 +60,7 @@
     onedit?: () => void
     onclose?: () => void
     detailExtra?: Snippet<[Record<string, unknown>]>
+    class?: string
   } & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
@@ -179,6 +181,7 @@
 {#if variant === 'modal'}
   <Modal
     bind:open
+    class={className}
     {title}
     size={modalSize}
     width={modalWidth}
@@ -192,7 +195,7 @@
     {/snippet}
   </Modal>
 {:else}
-  <Drawer bind:open {title} position='right' {size} width={drawerWidth} onclose={handleClose}>
+  <Drawer bind:open {title} class={className} position='right' {size} width={drawerWidth} onclose={handleClose}>
     {#if item}
       <div class={drawerBodyClass}>
         {@render detailBody()}

package/dist/components/scenes/crud/CrudDetailPanel.svelte.d.ts

@@ -32,6 +32,7 @@ type $$ComponentProps = {
     onedit?: () => void;
     onclose?: () => void;
     detailExtra?: Snippet<[Record<string, unknown>]>;
+    class?: string;
 } & DataAttributes;
 /**
  * CrudDetailPanel

package/dist/components/scenes/crud/CrudEditPanel.svelte

@@ -50,6 +50,7 @@
     onclose,
     editFormExtra,
     editingItem = null,
+    class: className = '',
     ...restProps
   }: {
     open?: boolean
@@ -70,6 +71,7 @@
     onclose?: () => void
     editFormExtra?: Snippet<[Record<string, unknown> | null, 'create' | 'edit']>
     editingItem?: Record<string, unknown> | null
+    class?: string
   } & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
@@ -171,13 +173,12 @@
           size={controlSize}
           value={String(fieldValue ?? '')}
           disabled={submitting || isReadonly}
+          options={[
+            { value: '', label: placeholder || uiM('crud_filter_all') },
+            ...opts.map(opt => ({ value: String(opt.value), label: opt.label })),
+          ]}
           onchange={value => updateField(field.id, value)}
-        >
-          <option value="">{placeholder || uiM('crud_filter_all')}</option>
-          {#each opts as opt (String(opt.value))}
-            <option value={String(opt.value)}>{opt.label}</option>
-          {/each}
-        </Select>
+        />
       </FormField>
 
     {:else if field.type === 'multi-select'}
@@ -255,6 +256,7 @@
 {#if variant === 'modal'}
   <Modal
     bind:open
+    class={className}
     {title}
     size={modalSize}
     width={modalWidth}
@@ -271,7 +273,7 @@
     {/snippet}
   </Modal>
 {:else}
-  <Drawer bind:open {title} position='right' {size} width={drawerWidth} onclose={handleClose} closeOnBackdrop={false}>
+  <Drawer bind:open {title} class={className} position='right' {size} width={drawerWidth} onclose={handleClose} closeOnBackdrop={false}>
     <form onsubmit={handleSubmit} class={drawerFormClass}>
       {@render formFields()}
     </form>

package/dist/components/scenes/crud/CrudEditPanel.svelte.d.ts

@@ -42,6 +42,7 @@ type $$ComponentProps = {
     onclose?: () => void;
     editFormExtra?: Snippet<[Record<string, unknown> | null, 'create' | 'edit']>;
     editingItem?: Record<string, unknown> | null;
+    class?: string;
 } & DataAttributes;
 /**
  * CrudEditPanel

package/dist/components/scenes/crud/CrudFilterBar.svelte

@@ -7,7 +7,7 @@
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
   import { uiM } from '../../../messages.js'
-  import { getDataAttributes } from '../../../utils.js'
+  import { cn, getDataAttributes } from '../../../utils.js'
   import BareButton from '../../primitives/BareButton.svelte'
   import Input from '../../primitives/Input.svelte'
   import Select from '../../primitives/Select.svelte'
@@ -34,6 +34,7 @@
     onsearch,
     onfilterchange,
     onreset,
+    class: className = '',
     ...restProps
   }: {
     searchable?: boolean
@@ -44,6 +45,7 @@
     onsearch?: (search: string) => void
     onfilterchange?: (filters: Record<string, unknown>) => void
     onreset?: () => void
+    class?: string
   } & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
@@ -120,7 +122,7 @@
   }
 </script>
 
-<div {...dataAttributes} class='flex flex-wrap items-center gap-2 [&_.fieldset]:m-0 [&_.fieldset]:min-w-0'>
+<div {...dataAttributes} class={cn('flex flex-wrap items-center gap-2 [&_.fieldset]:m-0 [&_.fieldset]:min-w-0', className)}>
   {#if searchable}
     <div class='relative w-full sm:w-64 md:w-72'>
       <span class='icon-[tabler--search] pointer-events-none absolute left-3 top-1/2 z-10 size-4 -translate-y-1/2 text-base-content/35'></span>
@@ -170,12 +172,13 @@
           size='sm'
           class='h-8 border-base-content/20 bg-base-100 shadow-none'
           value={String(filterValues[field.id] ?? '')}
+          options={[
+            { value: '', label: uiM('crud_filter_all') },
+            { value: 'true', label: uiM('crud_filter_yes') },
+            { value: 'false', label: uiM('crud_filter_no') },
+          ]}
           onchange={(value: string) => handleFilterChange(field.id, value)}
-        >
-          <option value="">{uiM('crud_filter_all')}</option>
-          <option value='true'>{uiM('crud_filter_yes')}</option>
-          <option value='false'>{uiM('crud_filter_no')}</option>
-        </Select>
+        />
       </div>
     {:else if isDateField(field)}
       <div class='w-36 shrink-0'>
@@ -207,13 +210,12 @@
           size='sm'
           class='h-8 border-base-content/20 bg-base-100 shadow-none'
           value={String(filterValues[field.id] ?? '')}
+          options={[
+            { value: '', label: uiM('crud_filter_all') },
+            ...opts.map(opt => ({ value: String(opt.value), label: opt.label })),
+          ]}
           onchange={(value: string) => handleFilterChange(field.id, value)}
-        >
-          <option value="">{uiM('crud_filter_all')}</option>
-          {#each opts as opt (String(opt.value))}
-            <option value={String(opt.value)}>{opt.label}</option>
-          {/each}
-        </Select>
+        />
       </div>
     {:else if isTextField(field)}
       <div class='w-44 shrink-0'>

package/dist/components/scenes/crud/CrudFilterBar.svelte.d.ts

@@ -26,6 +26,7 @@ type $$ComponentProps = {
     onsearch?: (search: string) => void;
     onfilterchange?: (filters: Record<string, unknown>) => void;
     onreset?: () => void;
+    class?: string;
 } & DataAttributes;
 /**
  * CrudFilterBar

package/dist/utils.d.ts

@@ -49,3 +49,16 @@ export declare function getProgressVariantClass(variant: Variant): string;
  * 生成唯一 ID
  */
 export declare function generateId(prefix?: string): string;
+/**
+ * Portal action：将节点移动到目标容器（默认 document.body）下渲染。
+ *
+ * 用于弹出层（下拉、气泡等）逃逸祖先的 `overflow: hidden` 裁剪与
+ * 堆叠上下文（stacking context）限制，避免被相邻控件遮挡。
+ *
+ * @param node - 要移动的节点
+ * @param target - 目标容器或选择器；默认 body
+ */
+export declare function portal(node: HTMLElement, target?: HTMLElement | string): {
+    update(next: HTMLElement | string): void;
+    destroy(): void;
+};

package/dist/utils.js

@@ -176,3 +176,27 @@ export function getProgressVariantClass(variant) {
 export function generateId(prefix = 'hai') {
     return `${prefix}-${Math.random().toString(36).slice(2, 9)}`;
 }
+/**
+ * Portal action：将节点移动到目标容器（默认 document.body）下渲染。
+ *
+ * 用于弹出层（下拉、气泡等）逃逸祖先的 `overflow: hidden` 裁剪与
+ * 堆叠上下文（stacking context）限制，避免被相邻控件遮挡。
+ *
+ * @param node - 要移动的节点
+ * @param target - 目标容器或选择器；默认 body
+ */
+export function portal(node, target = 'body') {
+    function mount(to) {
+        const targetEl = typeof to === 'string' ? document.querySelector(to) : to;
+        targetEl?.appendChild(node);
+    }
+    mount(target);
+    return {
+        update(next) {
+            mount(next);
+        },
+        destroy() {
+            node.parentNode?.removeChild(node);
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.31",
+  "version": "0.1.0-alpha.32",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -51,7 +51,7 @@
     "mermaid": "^11.12.0",
     "shiki": "^4.0.2",
     "tailwind-merge": "^3.5.0",
-    "@h-ai/core": "0.1.0-alpha.31"
+    "@h-ai/core": "0.1.0-alpha.32"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",