@xihan-ui/styles 1.0.0-alpha.0

package/css/tags-input.css

@@ -0,0 +1,360 @@
+@layer xihan.components {
+  /* root 只负责纵向堆叠：标题一行、控件一行。可见的那个"框"长在 control 上，
+     因为标签、输入框、清空按钮都在它里面，边框必须把三者一起圈住 */
+  [data-scope='tags-input'][data-part='root'] {
+    /* 尺寸档只换这六个私有槽，标题、框、输入框与标签都从 root 继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_tags-input-control-h: var(--xh-control-h-md);
+    --xh-_tags-input-control-px: var(--xh-control-px-md);
+    --xh-_tags-input-control-gap: var(--xh-control-gap-sm);
+    --xh-_tags-input-input-font-size: var(--xh-text-body-size);
+    --xh-_tags-input-item-font-size: var(--xh-font-size-sm);
+    --xh-_tags-input-label-font-size: var(--xh-text-label-size);
+    /* 形态档只换这三个私有槽，缺省这一份就是描边式（描边 + 画布底） */
+    --xh-_tags-input-control-bg: var(--xh-bg-canvas);
+    --xh-_tags-input-control-border: var(--xh-border-default);
+    --xh-_tags-input-control-border-hover: var(--xh-border-strong);
+    /* 聚焦环与标签块的强调色随语气走。没写 data-tone 时 --xh-_tone 没被声明，退回原来的取值 */
+    --xh-_tags-input-ring: var(--xh-ring-focus);
+    --xh-_tags-input-accent: var(--xh-_tone, var(--xh-bg-brand));
+    --xh-_tags-input-accent-fg: var(--xh-_tone-on, var(--xh-fg-on-brand));
+
+    display: inline-flex;
+    flex-direction: column;
+    gap: var(--xh-tags-input-gap, var(--xh-space-1));
+    inline-size: 100%;
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='tags-input'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 形态 —— */
+  /* 形态只决定颜色怎么用；用哪族颜色由 data-tone 决定。
+     不做 solid：实心填充盖住了"这里能打字"这件事，输入框用不上它 */
+  [data-scope='tags-input'][data-part='root'][data-variant='outline'] {
+    --xh-_tags-input-control-bg: var(--xh-bg-canvas);
+    --xh-_tags-input-control-border: var(--xh-border-default);
+    --xh-_tags-input-control-border-hover: var(--xh-border-strong);
+  }
+
+  /* 填充式：底色圈出可输入的范围，描边让位给底色 */
+  [data-scope='tags-input'][data-part='root'][data-variant='subtle'] {
+    --xh-_tags-input-control-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
+    --xh-_tags-input-control-border: transparent;
+    --xh-_tags-input-control-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+  }
+
+  /* 无边框、透明底：静息时框完全隐入背景，可见反馈全靠悬停描边与聚焦环 */
+  [data-scope='tags-input'][data-part='root'][data-variant='ghost'] {
+    --xh-_tags-input-control-bg: transparent;
+    --xh-_tags-input-control-border: transparent;
+    --xh-_tags-input-control-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+  }
+
+  /* —— 尺寸 —— */
+  [data-scope='tags-input'][data-part='root'][data-size='sm'] {
+    --xh-_tags-input-control-h: var(--xh-control-h-sm);
+    --xh-_tags-input-control-px: var(--xh-control-px-sm);
+    --xh-_tags-input-input-font-size: var(--xh-font-size-sm);
+    --xh-_tags-input-item-font-size: var(--xh-font-size-xs);
+    --xh-_tags-input-label-font-size: var(--xh-font-size-sm);
+  }
+
+  [data-scope='tags-input'][data-part='root'][data-size='lg'] {
+    --xh-_tags-input-control-h: var(--xh-control-h-lg);
+    --xh-_tags-input-control-px: var(--xh-control-px-lg);
+    --xh-_tags-input-control-gap: var(--xh-control-gap-lg);
+    --xh-_tags-input-input-font-size: var(--xh-font-size-lg);
+    --xh-_tags-input-item-font-size: var(--xh-font-size-md);
+    --xh-_tags-input-label-font-size: var(--xh-font-size-lg);
+  }
+
+  [data-scope='tags-input'][data-part='label'] {
+    color: var(--xh-tags-input-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-tags-input-label-font-size, var(--xh-_tags-input-label-font-size));
+    font-weight: var(--xh-tags-input-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  [data-scope='tags-input'][data-part='label'][data-disabled] {
+    color: var(--xh-tags-input-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 标签换行排，输入框跟在最后一个标签后面。最小高度对齐单行输入框，
+     只有一个标签时看起来仍是一个普通输入框，而不是塌成一条缝 */
+  [data-scope='tags-input'][data-part='control'] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--xh-tags-input-control-gap, var(--xh-_tags-input-control-gap));
+    min-block-size: var(--xh-tags-input-control-h, var(--xh-_tags-input-control-h));
+    padding-block: var(--xh-tags-input-control-py, var(--xh-space-1));
+    padding-inline: var(--xh-tags-input-control-px, var(--xh-_tags-input-control-px));
+    border: var(--xh-stroke-thin) solid var(--xh-tags-input-control-border, var(--xh-_tags-input-control-border));
+    border-radius: var(--xh-tags-input-control-radius, var(--xh-shape-control));
+    background: var(--xh-tags-input-control-bg, var(--xh-_tags-input-control-bg));
+    color: var(--xh-tags-input-control-fg, var(--xh-fg-default));
+    cursor: text;
+    transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='tags-input'][data-part='control'][hidden] {
+    display: none;
+  }
+
+  /* hover 只在中性态换描边：invalid 与 at-max 正拿边框颜色说事，被 hover 盖掉那条信息就没了 */
+  [data-scope='tags-input'][data-part='control']:hover:not([data-disabled], [data-invalid], [data-at-max]) {
+    border-color: var(--xh-tags-input-control-border-hover, var(--xh-_tags-input-control-border-hover));
+  }
+
+  /* 焦点环画在这个框上：用户眼里"被聚焦的控件"就是整个框，
+     而真正持有焦点的是里面的 input（它自己那圈环因此让位，见下） */
+  [data-scope='tags-input'][data-part='control']:focus-within {
+    outline: var(--xh-ring-width) solid var(--xh-_tags-input-ring);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 顶到上限：再加进不去，边框先给个提示。放在 invalid 之前，
+     两者同时成立时按源序让 invalid 赢——真出错比"装满了"要紧 */
+  [data-scope='tags-input'][data-part='control'][data-at-max] {
+    border-color: var(--xh-tags-input-control-border-at-max, var(--xh-color-warning-600));
+  }
+
+  [data-scope='tags-input'][data-part='control'][data-invalid] {
+    border-color: var(--xh-tags-input-control-border-invalid, var(--xh-color-danger-500));
+  }
+
+  /* 只读仍可聚焦、可复制，所以不置灰，只把底色压下去表示"改不动" */
+  [data-scope='tags-input'][data-part='control'][data-readonly] {
+    background: var(--xh-tags-input-control-bg-readonly, var(--xh-bg-subtle));
+    cursor: default;
+  }
+
+  /* control 是容器不是原生控件，禁用只能靠 data-disabled 表达，写 :disabled 永远不命中 */
+  [data-scope='tags-input'][data-part='control'][data-disabled] {
+    background: var(--xh-tags-input-control-bg-disabled, var(--xh-bg-subtle));
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 输入框贴着标签排，自己不画边框与底色——那两样归 control。
+     min-inline-size 保证标签占满一行后它还能换到下一行继续输入，而不是被挤成零宽 */
+  [data-scope='tags-input'][data-part='input'] {
+    flex: 1 1 var(--xh-tags-input-input-basis, 6rem);
+    min-inline-size: var(--xh-tags-input-input-min-w, 4rem);
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    /* 表单控件不继承页面字体，只给字号会让输入框用 UA 默认字族，与周围文本对不上 */
+    font-family: inherit;
+    font-size: var(--xh-tags-input-input-font-size, var(--xh-_tags-input-input-font-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  [data-scope='tags-input'][data-part='input']::placeholder {
+    color: var(--xh-tags-input-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  /* 焦点环由 control 统一画（见上）：这里再画一圈会在框里套框，两条环互相压着 */
+  [data-scope='tags-input'][data-part='input']:focus-visible {
+    outline: none;
+  }
+
+  /* input 是单体表单控件，禁用走原生 disabled */
+  [data-scope='tags-input'][data-part='input']:disabled {
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 一个标签一颗胶囊。inline-size 交给内容决定，长标签由 item-text 截断 */
+  [data-scope='tags-input'][data-part='item'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    max-inline-size: 100%;
+    border-radius: var(--xh-tags-input-item-radius, var(--xh-shape-pill));
+    background: var(--xh-tags-input-item-bg, var(--xh-bg-subtle));
+    color: var(--xh-tags-input-item-fg, var(--xh-fg-default));
+    font-size: var(--xh-tags-input-item-font-size, var(--xh-_tags-input-item-font-size));
+    line-height: var(--xh-leading-none);
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='tags-input'][data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 光标走到这颗标签上（退格第一下、方向键）：整颗反白，与"删掉它"这件事对得上。
+     禁用态下不给高亮：那时候本来就走不进标签 */
+  [data-scope='tags-input'][data-part='item'][data-highlighted]:not([data-disabled]) {
+    background: var(--xh-tags-input-item-bg-highlight, var(--xh-_tags-input-accent));
+    color: var(--xh-tags-input-item-fg-highlight, var(--xh-_tags-input-accent-fg));
+  }
+
+  /* 标签不是原生控件，禁用同样只能靠 data-disabled */
+  [data-scope='tags-input'][data-part='item'][data-disabled] {
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 就地编辑时整颗胶囊让位给编辑框：底色撤掉，免得输入框外面套一圈灰底 */
+  [data-scope='tags-input'][data-part='item'][data-editing] {
+    background: transparent;
+  }
+
+  [data-scope='tags-input'][data-part='item-preview'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--xh-tags-input-item-gap, var(--xh-space-1));
+    max-inline-size: 100%;
+    padding-block: var(--xh-tags-input-item-py, var(--xh-space-1));
+    padding-inline: var(--xh-tags-input-item-px, var(--xh-space-2));
+    user-select: none;
+  }
+
+  /* 就地编辑时连接层给的是 hidden 属性；上面那条 display 会把 UA 规则盖掉，
+     少了这条预览会和编辑框叠在一起 */
+  [data-scope='tags-input'][data-part='item-preview'][hidden] {
+    display: none;
+  }
+
+  /* 长标签截断而不是把整行撑开：胶囊挤爆一行会把输入框顶到看不见的地方 */
+  [data-scope='tags-input'][data-part='item-text'] {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* 删除按钮画成胶囊里的小圆钮，与文字同一行、不撑高胶囊 */
+  [data-scope='tags-input'][data-part='item-delete-trigger'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-tags-input-delete-size, 1rem);
+    block-size: var(--xh-tags-input-delete-size, 1rem);
+    padding: 0;
+    border: 0;
+    border-radius: var(--xh-radius-full);
+    background: var(--xh-tags-input-delete-bg, transparent);
+    color: var(--xh-tags-input-delete-fg, var(--xh-fg-muted));
+    font-family: inherit;
+    font-size: var(--xh-tags-input-delete-font-size, var(--xh-font-size-xs));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='tags-input'][data-part='item-delete-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 整颗标签反白时按钮跟着改色，否则灰字压在品牌底色上会看不清 */
+  [data-scope='tags-input'][data-part='item-delete-trigger'][data-highlighted]:not(:disabled) {
+    color: var(--xh-tags-input-delete-fg-highlight, var(--xh-_tags-input-accent-fg));
+  }
+
+  [data-scope='tags-input'][data-part='item-delete-trigger']:hover:not(:disabled) {
+    background: var(--xh-tags-input-delete-bg-hover, var(--xh-bg-subtle-hover));
+    color: var(--xh-tags-input-delete-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='tags-input'][data-part='item-delete-trigger']:active:not(:disabled) {
+    background: var(--xh-tags-input-delete-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  /* 按钮不占 Tab 位（tabindex=-1），正常操作走不到这里；
+     留着焦点环是给程序化聚焦兜底——删完把焦点交回输入框之前，它确实短暂持有过焦点 */
+  [data-scope='tags-input'][data-part='item-delete-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tags-input-ring);
+    /* 比默认档窄一道：它长在胶囊里，按默认偏移画会压到相邻胶囊 */
+    outline-offset: var(--xh-stroke-thin);
+  }
+
+  /* 按钮是单体控件，禁用走原生 disabled */
+  [data-scope='tags-input'][data-part='item-delete-trigger']:disabled {
+    background: transparent;
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 就地编辑框：尺寸对齐胶囊，看起来像是在原地把标签改了，而不是另开一个框。
+     不声明 display —— 收起态靠 UA 的 [hidden]{display:none} 就够，
+     自己加一条 display 反而要再补一条 [hidden] 规则去抵消它 */
+  [data-scope='tags-input'][data-part='item-input'] {
+    max-inline-size: 100%;
+    padding-block: var(--xh-tags-input-item-py, var(--xh-space-1));
+    padding-inline: var(--xh-tags-input-item-px, var(--xh-space-2));
+    border: var(--xh-stroke-thin) solid var(--xh-tags-input-item-input-border, var(--xh-border-strong));
+    border-radius: var(--xh-tags-input-item-radius, var(--xh-shape-pill));
+    background: var(--xh-tags-input-item-input-bg, var(--xh-bg-canvas));
+    color: var(--xh-tags-input-item-input-fg, var(--xh-fg-default));
+    font-family: inherit;
+    font-size: var(--xh-tags-input-item-font-size, var(--xh-_tags-input-item-font-size));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* 它是真正持有焦点的那个节点，环画在自己身上；
+     外层 control 的 :focus-within 环同时亮着也合理——焦点确实在框内 */
+  [data-scope='tags-input'][data-part='item-input']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tags-input-ring);
+    /* 比默认档窄一道：它长在胶囊里，按默认偏移画会压到相邻胶囊 */
+    outline-offset: var(--xh-stroke-thin);
+  }
+
+  [data-scope='tags-input'][data-part='item-input']:disabled {
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 清空按钮贴在框的末端，与输入框同一行 */
+  [data-scope='tags-input'][data-part='clear-trigger'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-tags-input-clear-size, 1.25rem);
+    block-size: var(--xh-tags-input-clear-size, 1.25rem);
+    padding: 0;
+    border: 0;
+    border-radius: var(--xh-radius-full);
+    background: var(--xh-tags-input-clear-bg, transparent);
+    color: var(--xh-tags-input-clear-fg, var(--xh-fg-muted));
+    font-family: inherit;
+    font-size: var(--xh-tags-input-clear-font-size, var(--xh-font-size-sm));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='tags-input'][data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='tags-input'][data-part='clear-trigger']:hover:not(:disabled) {
+    background: var(--xh-tags-input-clear-bg-hover, var(--xh-bg-subtle-hover));
+    color: var(--xh-tags-input-clear-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='tags-input'][data-part='clear-trigger']:active:not(:disabled) {
+    background: var(--xh-tags-input-clear-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  [data-scope='tags-input'][data-part='clear-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tags-input-ring);
+    /* 比默认档窄一道：它长在胶囊里，按默认偏移画会压到相邻胶囊 */
+    outline-offset: var(--xh-stroke-thin);
+  }
+
+  /* 没东西可清、只读或禁用时按钮转灰但不收起：位置留着，加进第一个标签就亮 */
+  [data-scope='tags-input'][data-part='clear-trigger']:disabled {
+    background: transparent;
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+}

package/css/text-field.css

@@ -0,0 +1,195 @@
+@layer xihan.components {
+  /* root 只负责纵向堆叠：标签一行、输入行一行。
+     输入框与清空按钮中间那层包裹是作者自己写的、不在角色表里，
+     所以尺寸与间距一律长在各自的角色节点上，不去假设那层存在 */
+  [data-scope='text-field'][data-part='root'] {
+    /* 尺寸档只换这几个私有槽，标题、输入框与清空按钮都从 root 继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_text-field-h: var(--xh-control-h-md);
+    --xh-_text-field-px: var(--xh-control-px-md);
+    --xh-_text-field-font-size: var(--xh-text-body-size);
+    --xh-_text-field-label-font-size: var(--xh-text-label-size);
+    --xh-_text-field-clear-font-size: var(--xh-font-size-sm);
+
+    /* 形态档只换这三个私有槽：底、常态描边、悬停描边 */
+    --xh-_text-field-bg: var(--xh-bg-canvas);
+    --xh-_text-field-border: var(--xh-border-default);
+    --xh-_text-field-border-hover: var(--xh-border-strong);
+
+    /* 语气只落在聚焦这一处：环与聚焦态描边。正文颜色不归它管。
+       没写 data-tone 时 --xh-_tone 没被声明，退回原来的聚焦环色与常态描边 */
+    --xh-_text-field-ring: var(--xh-ring-focus);
+    --xh-_text-field-border-focus: var(--xh-text-field-input-border, var(--xh-_tone, var(--xh-border-default)));
+
+    display: inline-flex;
+    flex-direction: column;
+    gap: var(--xh-text-field-gap, var(--xh-space-1));
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='text-field'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='text-field'][data-part='root'][data-size='sm'] {
+    --xh-_text-field-h: var(--xh-control-h-sm);
+    --xh-_text-field-px: var(--xh-control-px-sm);
+    --xh-_text-field-font-size: var(--xh-font-size-sm);
+    --xh-_text-field-label-font-size: var(--xh-font-size-sm);
+    --xh-_text-field-clear-font-size: var(--xh-font-size-xs);
+  }
+
+  [data-scope='text-field'][data-part='root'][data-size='lg'] {
+    --xh-_text-field-h: var(--xh-control-h-lg);
+    --xh-_text-field-px: var(--xh-control-px-lg);
+    --xh-_text-field-font-size: var(--xh-font-size-lg);
+    --xh-_text-field-label-font-size: var(--xh-font-size-lg);
+    --xh-_text-field-clear-font-size: var(--xh-font-size-md);
+  }
+
+  /* —— 形态 —— */
+  /* 形态只决定底与描边怎么画；用哪族颜色由 data-tone 决定。
+     输入框没有实心档：填满一个要往里打字的框，字与底就没法同时读 */
+  [data-scope='text-field'][data-part='root'][data-variant='outline'] {
+    --xh-_text-field-bg: var(--xh-bg-canvas);
+    --xh-_text-field-border: var(--xh-border-default);
+    --xh-_text-field-border-hover: var(--xh-border-strong);
+    --xh-_text-field-border-focus: var(--xh-text-field-input-border, var(--xh-_tone, var(--xh-border-default)));
+  }
+
+  /* 填充式：底色顶替描边表达边界。描边只退成透明而不去掉，1px 的位置留着，
+     与 outline 档并排时基线对得上、聚焦画描边也不引起跳动 */
+  [data-scope='text-field'][data-part='root'][data-variant='subtle'] {
+    --xh-_text-field-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
+    --xh-_text-field-border: transparent;
+    --xh-_text-field-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_text-field-border-focus: var(--xh-_tone, var(--xh-border-default));
+  }
+
+  /* 无框：底与描边都透明，平时只看得见字，悬停与聚焦才浮出边界 */
+  [data-scope='text-field'][data-part='root'][data-variant='ghost'] {
+    --xh-_text-field-bg: transparent;
+    --xh-_text-field-border: transparent;
+    --xh-_text-field-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_text-field-border-focus: var(--xh-_tone, var(--xh-border-default));
+  }
+
+  [data-scope='text-field'][data-part='label'] {
+    color: var(--xh-text-field-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-text-field-label-font-size, var(--xh-_text-field-label-font-size));
+    font-weight: var(--xh-text-field-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  [data-scope='text-field'][data-part='label'][data-disabled] {
+    color: var(--xh-text-field-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  [data-scope='text-field'][data-part='input'] {
+    block-size: var(--xh-text-field-input-h, var(--xh-_text-field-h));
+    padding-inline: var(--xh-text-field-input-px, var(--xh-_text-field-px));
+    padding-block: 0;
+    border: var(--xh-stroke-thin) solid var(--xh-text-field-input-border, var(--xh-_text-field-border));
+    border-radius: var(--xh-text-field-input-radius, var(--xh-shape-control));
+    background: var(--xh-text-field-input-bg, var(--xh-_text-field-bg));
+    color: var(--xh-text-field-input-fg, var(--xh-fg-default));
+    /* 表单控件不继承页面字体，只给字号会让输入框用 UA 默认字族，与周围文本对不上 */
+    font-family: inherit;
+    font-size: var(--xh-text-field-input-font-size, var(--xh-_text-field-font-size));
+    line-height: var(--xh-leading-normal);
+    transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='text-field'][data-part='input']::placeholder {
+    color: var(--xh-text-field-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  /* hover 只在中性态换描边：invalid 与 at-limit 正拿边框颜色说事，
+     被 hover 盖掉那条信息就没了 */
+  [data-scope='text-field'][data-part='input']:hover:not(:disabled, [data-invalid], [data-at-limit]) {
+    border-color: var(--xh-text-field-input-border-hover, var(--xh-_text-field-border-hover));
+  }
+
+  /* 聚焦态描边与环共用一族语气色。这条特异度低于上面的 hover、也低于下面的
+     at-limit 与 invalid，三者仍按原来的次序赢过它 */
+  [data-scope='text-field'][data-part='input']:focus-visible {
+    border-color: var(--xh-text-field-input-border-focus, var(--xh-_text-field-border-focus));
+    outline: var(--xh-ring-width) solid var(--xh-_text-field-ring);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 顶到字数上限：再敲进不去，边框先给个提示。放在 invalid 之前，
+     两者同时成立时按源序让 invalid 赢——真出错比"写满了"要紧 */
+  [data-scope='text-field'][data-part='input'][data-at-limit] {
+    border-color: var(--xh-text-field-input-border-at-limit, var(--xh-color-warning-600));
+  }
+
+  [data-scope='text-field'][data-part='input'][data-invalid] {
+    border-color: var(--xh-text-field-input-border-invalid, var(--xh-color-danger-500));
+  }
+
+  /* 只读仍可聚焦、可复制，所以不置灰，只把底色压下去表示"改不动" */
+  [data-scope='text-field'][data-part='input'][readonly] {
+    background: var(--xh-text-field-input-bg-readonly, var(--xh-bg-subtle));
+  }
+
+  /* input 是单体表单控件，禁用走原生 disabled */
+  [data-scope='text-field'][data-part='input']:disabled {
+    background: var(--xh-text-field-input-bg-disabled, var(--xh-bg-subtle));
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 清空按钮画成输入框右侧的小方钮：它是 input 的兄弟节点而不是子节点，
+     没法叠进框内，只能与框等高、贴着排，靠同一套边角与高度看起来是一体的 */
+  [data-scope='text-field'][data-part='clear-trigger'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-text-field-clear-size, var(--xh-_text-field-h));
+    block-size: var(--xh-text-field-clear-size, var(--xh-_text-field-h));
+    padding: 0;
+    border: 0;
+    border-radius: var(--xh-text-field-clear-radius, var(--xh-shape-control));
+    background: var(--xh-text-field-clear-bg, transparent);
+    color: var(--xh-text-field-clear-fg, var(--xh-fg-muted));
+    font-family: inherit;
+    font-size: var(--xh-text-field-clear-font-size, var(--xh-_text-field-clear-font-size));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+    user-select: none;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 没开 clearable 时连接层给的是 hidden 属性；上面那条 display 会把 UA 规则盖掉，
+     少了这条按钮就一直杵在那儿 */
+  [data-scope='text-field'][data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='text-field'][data-part='clear-trigger']:hover:not(:disabled) {
+    background: var(--xh-text-field-clear-bg-hover, var(--xh-bg-subtle-hover));
+    color: var(--xh-text-field-clear-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='text-field'][data-part='clear-trigger']:active:not(:disabled) {
+    background: var(--xh-text-field-clear-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  /* 按钮不占 Tab 位（tabindex=-1）也不抢焦点，正常操作走不到这里；
+     留着是给程序化聚焦兜底，落焦时得看得见 */
+  [data-scope='text-field'][data-part='clear-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_text-field-ring);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 框里没字、只读或禁用时按钮转灰但不收起：位置留着，敲进第一个字就亮 */
+  [data-scope='text-field'][data-part='clear-trigger']:disabled {
+    background: var(--xh-text-field-clear-bg, transparent);
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+}

package/css/thread.css

@@ -0,0 +1,107 @@
+@layer xihan.components {
+  /* 自建定位上下文，作为绝对定位的回到底部按钮的参照系；
+     block-size: 100% 让高度由外部决定，使滚动发生在内部。 */
+  [data-scope='thread'][data-part='root'] {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    block-size: 100%;
+  }
+
+  /* 上面声明的 display 会盖掉 UA 的 [hidden]{display:none}，这里补回 */
+  [data-scope='thread'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 滚动容器，粘底读的是它的 scrollTop / clientHeight / scrollHeight。
+     min-block-size: 0 让弹性子项能被压缩从而触发溢出；
+     overscroll-behavior: contain 阻止滚动量传给页面；
+     scrollbar-gutter: stable 避免滚动条出现与消失时推动文字。 */
+  [data-scope='thread'][data-part='viewport'] {
+    flex: 1;
+    min-block-size: 0;
+    /* 逻辑属性 overflow-block 尚无可用实现，写物理轴 */
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    scrollbar-gutter: stable;
+  }
+
+  /* 视口带 tabindex=0，需要焦点环；偏移取负画在内侧，避免被 root 裁掉 */
+  [data-scope='thread'][data-part='viewport']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  /* 只定消息之间的竖向间距与上下留白，左右留白留给作者 */
+  [data-scope='thread'][data-part='content'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-thread-content-gap, var(--xh-stack-gap-md));
+    padding-block: var(--xh-thread-content-py, var(--xh-space-4));
+  }
+
+  [data-scope='thread'][data-part='content'][hidden] {
+    display: none;
+  }
+
+  /* 浮在视口右下角，z-index 使其不受源序影响地盖在消息之上 */
+  [data-scope='thread'][data-part='scroll-button'] {
+    position: absolute;
+    z-index: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-thread-scroll-button-gap, var(--xh-control-gap-md));
+    inset-block-end: var(--xh-thread-scroll-button-inset, var(--xh-space-4));
+    inset-inline-end: var(--xh-thread-scroll-button-inset, var(--xh-space-4));
+    min-inline-size: var(--xh-thread-scroll-button-h, var(--xh-control-h-md));
+    block-size: var(--xh-thread-scroll-button-h, var(--xh-control-h-md));
+    padding-inline: var(--xh-thread-scroll-button-px, var(--xh-control-px-md));
+    border: var(--xh-stroke-thin) solid var(--xh-thread-scroll-button-border, var(--xh-border-default));
+    border-radius: var(--xh-thread-scroll-button-radius, var(--xh-shape-pill));
+    background: var(--xh-thread-scroll-button-bg, var(--xh-bg-surface));
+    color: var(--xh-thread-scroll-button-fg, var(--xh-fg-default));
+    box-shadow: var(--xh-thread-scroll-button-shadow, var(--xh-elevation-2));
+    /* 按钮默认不继承页面字族，显式继承 */
+    font-family: inherit;
+    font-size: var(--xh-thread-scroll-button-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-thread-scroll-button-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+    white-space: nowrap;
+    cursor: pointer;
+    user-select: none;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 连接层收起按钮时写 hidden 属性，上面的 display 会盖掉 UA 规则，这里补回 */
+  [data-scope='thread'][data-part='scroll-button'][hidden] {
+    display: none;
+  }
+
+  [data-scope='thread'][data-part='scroll-button']:hover {
+    background: var(--xh-thread-scroll-button-bg-hover, var(--xh-bg-subtle-hover));
+  }
+
+  [data-scope='thread'][data-part='scroll-button']:active {
+    background: var(--xh-thread-scroll-button-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  [data-scope='thread'][data-part='scroll-button']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 视觉隐藏但仍参与播报：用 clip-path 裁到不可见，不能用 display:none 或 visibility:hidden；
+     white-space: nowrap 防止 1px 宽把文本挤成竖排。 */
+  [data-scope='thread'][data-part='live-region'] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+}