Hydra-AI 样式化组件封装指南基于 tambo-ai/react-ui-base 的组合式重构实践【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai导读本篇技术指南聚焦于 hydra-ai 仓库中creating-styled-wrappers这一工程实践技能当你在tambo-ai/react-ui-base之上实现有主见opinionated的设计系统或需要把重复实现逻辑的样式化组件重构为「组合 base 原语」的形态时本文提供一套可照抄的六步工作流、状态访问层级选择标准与反模式清单。读完本文你将掌握如何用数据属性data-*、渲染属性render props与 Context Hook 三种方式正确消费无头组件以及如何通过 Icon 工厂与 CSS 变体把「行为」与「表现」干净地分层。一、核心原则Compose, Dont Duplicatecreating-styled-wrappers技能与仓库内配套的 compound-components 技能 互为表里前者负责构建无样式的 base 原语headless primitives后者则规定如何正确消费并包装它们。两者的分界线只有一句话样式化包装器应当组合composebase 组件而不是重新实现re-implementbase 的逻辑。// WRONG - 重复实现 base 已经做好的事 const StyledInput ({ children, className }) { const { value, setValue, submit } useTamboThreadInput(); // 重复 const [isDragging, setIsDragging] useState(false); // 重复 const handleDrop useCallback(/* ... */); // 重复 return ( form onDrop{handleDrop} className{className} {children} /form ); }; // CORRECT - 组合 base 组件 const StyledInput ({ children, className, variant }) { return ( BaseInput.Root className{cn(inputVariants({ variant }), className)} BaseInput.Content classNamerounded-xl>import { MessageInput as MessageInputBase } from tambo-ai/react-ui-base/message-input;该包在仓库内的真实名称可在 packages/react-ui-base/package.json 中确认name: tambo-ai/react-ui-base命名空间导出定义见 packages/react-ui-base/src/message-input/index.tsxRoot、Content、Elicitation、Textarea、SubmitButton、StopButton、FileButton、Error、StagedImages、Toolbar、ValueAccess共 11 个部件且该文件只 re-export 类型、绝不导出 Hook——这与 compound-components 技能 中「Hooks Are Internal」的规则严格一致。Step 3: 用 Base Root 包裹用 base 的 Root 替换自定义的 Context/state 管理// Before const MessageInput ({ children, variant }) { return ( MessageInputInternal variant{variant}{children}/MessageInputInternal ); }; // After const MessageInput ({ children, variant, className }) { return ( MessageInputBase.Root className{cn(variants({ variant }), className)} {children} /MessageInputBase.Root ); };从源码看message-input-root.tsx 的 Root 承担了全部「重活」内部调用useTamboThreadInput()获取value/setValue/submit/error/images/addImages/removeImage调用useTambo()获取cancelRun/currentThreadId/isIdle并维护isSubmitting、isDragging状态与拖拽计数器dragCounter此外它还内置了会话级草稿持久化——通过sessionStorage按tambo.components.messageInput.draft.threadId键存取草稿见 message-input-root.tsx并在切换线程时自动重置提交状态。这些逻辑如果被样式化层复制光是草稿与线程切换的边界情况就足以产生大量 bug。Step 4: 应用基于状态的样式与行为状态访问遵循一个层级——始终选择最简单且够用的方案数据属性Data attributes——样式首选base 组件会暴露data-*属性渲染属性Render props——用于行为变化需要渲染不同组件时使用Context Hook——用于子组件样式化子组件需要深层访问 Context 时可用。// BEST ->// Submit button const SubmitButton ({ className, children }) ( BaseComponent.SubmitButton className{cn(w-10 h-10 rounded-lg, className)} {({ showCancelButton }) children ?? (showCancelButton ? Square / : ArrowUp /) } /BaseComponent.SubmitButton ); // Error const Error ({ className }) ( BaseComponent.Error className{cn(text-sm text-destructive, className)} / ); // Staged images - base 预计算 props 数组直接遍历即可 const StagedImages ({ className }) ( BaseComponent.StagedImages className{cn(flex gap-2, className)} {({ images }) images.map((imageProps) ( ImageBadge key{imageProps.image.id} {...imageProps} / )) } /BaseComponent.StagedImages );这里有两个值得注意的源码细节SubmitButton 的隐藏/禁用逻辑由 base 完成message-input-submit-button.tsx 依据isPending、isIdle、isUpdatingToken推导disabled、hidden、loading三个状态并据此把tabIndex设为-1、写入aria-hidden、切换typesubmit。样式化层只需要通过 render props 拿到showCancelButton等状态决定渲染什么图标不必重复判断线程是否在生成。集合类子组件遵循「预计算 props 数组」约定base 在useMemo中一次性算出images数组每个元素已含image/displayName/onRemove等完整 props见 real-world-example.md 的 StagedImages 前后对比样式化层拿到imageProps直接展开即可无需再写 getter 函数——这与 compound-components 技能 的「Pre-computed Props Arrays for Collections」规则一一对应。Step 6: 最终验证Final Checks: - [ ] No duplicate context creation - [ ] No duplicate SDK hooks in root wrappers - [ ] No duplicate state management or event handlers - [ ] Base namespace imported and Base.Root used as wrapper - [ ] data-* classes used for styling (with group-data-* for children) - [ ] Render props used only for rendering behavior changes - [ ] Base sub-components wrapped with styling - [ ] Icon factories passed from styled layer to base hooks - [ ] Visual sub-components and CSS variants stay in styled layer三、样式化层的职责边界哪些内容必须留在 Styled Layer3.1 Icon 工厂Icon Factories当 base Hook 需要图标时样式化层以工厂函数的形式传入而不是把图标硬编码进 base// Base hook 接受可选的 icon factory export function useCombinedResourceList( providers: ResourceProvider[] | undefined, search: string, createMcpIcon?: (serverName: string) React.ReactNode, ) { /* ... */ } // 样式化层提供工厂 const resources useCombinedResourceList(providers, search, (serverName) ( McpServerIcon name{serverName} classNamew-4 h-4 / ));这个模式在仓库中有真实实现base 侧 use-combined-lists.tsx 负责 MCP 资源列表的获取、去重与过滤数据逻辑留在 base但对 MCP 项只调用createMcpIcon(serverName)生成图标而样式化层把McpServerIcon name{serverName} classNamew-4 h-4 /作为工厂注入见 real-world-example.md 的「What Moved to Base Layer」小节。这样图标库的选择、尺寸、颜色完全由样式化层掌控base 保持零视觉依赖。3.2 CSS 变体CSS Variantsconst inputVariants cva(w-full, { variants: { variant: { default: , solid: [div]:shadow-xl [div]:ring-1, bordered: [div]:border-2, }, }, });3.3 布局逻辑、可视化子组件与自定义数据获取这三类内容同样留在样式化层。真实重构中保留在样式化层的清单包括Icon 工厂、ImageContextBadge/DictationButton等视觉组件、messageInputVariantsCSS 变体、MCP 集成组件McpPromptButton、McpResourceButton、McpConfigButton、把工具栏子元素拆分为左/右两侧的布局逻辑以及MessageInputPlainTextarea纯文本替代实现见 real-world-example.md 的「What Stayed in Styled Layer」。与之对应base 负责行为样式化层负责表现而「自定义数据获取」多数据源合并、外部 Provider 组合也被明确排除在 base 原语之外——base 可以使用tambo-ai/react的 SDK Hook组件本来就依赖 Tambo Provider但合并外部数据源必须上移到样式化层参见 compound-components 技能 的「No Custom Data Fetching in Primitives」。四、类型处理Ref 类型差异base 的 Context 中持有的是RefObjectT | null而样式化组件往往需要RefObjectT需要显式断言// Base context 可能是 RefObjectT | null // 样式化组件可能需要 RefObjectT TextEditor ref{editorRef as React.RefObjectTamboEditor} /同样的处理也出现在 MessageInput 重构中MessageInputBase.Root的inputRef以inputRef as React.RefObjectTamboEditor | null传递见 real-world-example.md 的 After 代码因为 base 的MessageInputRootProps中inputRef类型就是React.RefObjectTamboEditor | null见 message-input-root.tsx。五、反模式清单以下是本技能明确禁止的做法可作为 code review 的检查项重新实现 base 逻辑Re-implementing base logic——如果 base 已经处理了它就组合它用 render props 做样式Using render props for styling——优先使用data-*类render props 只用于行为变化在包装器中重复创建 ContextDuplicating context in wrapper——使用 base 的 Root它本身就提供 Context在 base Hook 中硬编码图标Hardcoding icons in base hooks——使用工厂函数把样式留在样式化层。这四条反模式与仓库中的编码事实互为印证base 层通过MessageInputContext.Provider统一供给 Context见 message-input-root.tsxRoot 之外的任何包装器再次createContext都意味着 Step 1 的识别失败而MessageInputContent同时暴露data-*与 render props 正是为了让你能「样式走属性、行为走渲染」两不误。延伸阅读本技能与 compound-components 技能 是一对配套工作流——前者回答「base 原语怎么建」本文回答「在 base 之上怎么包」。完整的 MessageInput 重构前后对比、子组件逐项转换与行数消减统计见 real-world-example.mdbase 组件的命名空间导出与类型定义见 packages/react-ui-base/src/message-input/index.tsx。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hydra-AI 样式化组件封装指南基于 tambo-ai/react-ui-base 的组合式重构实践【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai导读本篇技术指南聚焦于 hydra-ai 仓库中creating-styled-wrappers这一工程实践技能当你在tambo-ai/react-ui-base之上实现有主见opinionated的设计系统或需要把重复实现逻辑的样式化组件重构为「组合 base 原语」的形态时本文提供一套可照抄的六步工作流、状态访问层级选择标准与反模式清单。读完本文你将掌握如何用数据属性data-*、渲染属性render props与 Context Hook 三种方式正确消费无头组件以及如何通过 Icon 工厂与 CSS 变体把「行为」与「表现」干净地分层。一、核心原则Compose, Dont Duplicatecreating-styled-wrappers技能与仓库内配套的 compound-components 技能 互为表里前者负责构建无样式的 base 原语headless primitives后者则规定如何正确消费并包装它们。两者的分界线只有一句话样式化包装器应当组合composebase 组件而不是重新实现re-implementbase 的逻辑。// WRONG - 重复实现 base 已经做好的事 const StyledInput ({ children, className }) { const { value, setValue, submit } useTamboThreadInput(); // 重复 const [isDragging, setIsDragging] useState(false); // 重复 const handleDrop useCallback(/* ... */); // 重复 return ( form onDrop{handleDrop} className{className} {children} /form ); }; // CORRECT - 组合 base 组件 const StyledInput ({ children, className, variant }) { return ( BaseInput.Root className{cn(inputVariants({ variant }), className)} BaseInput.Content classNamerounded-xl>import { MessageInput as MessageInputBase } from tambo-ai/react-ui-base/message-input;该包在仓库内的真实名称可在 packages/react-ui-base/package.json 中确认name: tambo-ai/react-ui-base命名空间导出定义见 packages/react-ui-base/src/message-input/index.tsxRoot、Content、Elicitation、Textarea、SubmitButton、StopButton、FileButton、Error、StagedImages、Toolbar、ValueAccess共 11 个部件且该文件只 re-export 类型、绝不导出 Hook——这与 compound-components 技能 中「Hooks Are Internal」的规则严格一致。Step 3: 用 Base Root 包裹用 base 的 Root 替换自定义的 Context/state 管理// Before const MessageInput ({ children, variant }) { return ( MessageInputInternal variant{variant}{children}/MessageInputInternal ); }; // After const MessageInput ({ children, variant, className }) { return ( MessageInputBase.Root className{cn(variants({ variant }), className)} {children} /MessageInputBase.Root ); };从源码看message-input-root.tsx 的 Root 承担了全部「重活」内部调用useTamboThreadInput()获取value/setValue/submit/error/images/addImages/removeImage调用useTambo()获取cancelRun/currentThreadId/isIdle并维护isSubmitting、isDragging状态与拖拽计数器dragCounter此外它还内置了会话级草稿持久化——通过sessionStorage按tambo.components.messageInput.draft.threadId键存取草稿见 message-input-root.tsx并在切换线程时自动重置提交状态。这些逻辑如果被样式化层复制光是草稿与线程切换的边界情况就足以产生大量 bug。Step 4: 应用基于状态的样式与行为状态访问遵循一个层级——始终选择最简单且够用的方案数据属性Data attributes——样式首选base 组件会暴露data-*属性渲染属性Render props——用于行为变化需要渲染不同组件时使用Context Hook——用于子组件样式化子组件需要深层访问 Context 时可用。// BEST ->// Submit button const SubmitButton ({ className, children }) ( BaseComponent.SubmitButton className{cn(w-10 h-10 rounded-lg, className)} {({ showCancelButton }) children ?? (showCancelButton ? Square / : ArrowUp /) } /BaseComponent.SubmitButton ); // Error const Error ({ className }) ( BaseComponent.Error className{cn(text-sm text-destructive, className)} / ); // Staged images - base 预计算 props 数组直接遍历即可 const StagedImages ({ className }) ( BaseComponent.StagedImages className{cn(flex gap-2, className)} {({ images }) images.map((imageProps) ( ImageBadge key{imageProps.image.id} {...imageProps} / )) } /BaseComponent.StagedImages );这里有两个值得注意的源码细节SubmitButton 的隐藏/禁用逻辑由 base 完成message-input-submit-button.tsx 依据isPending、isIdle、isUpdatingToken推导disabled、hidden、loading三个状态并据此把tabIndex设为-1、写入aria-hidden、切换typesubmit。样式化层只需要通过 render props 拿到showCancelButton等状态决定渲染什么图标不必重复判断线程是否在生成。集合类子组件遵循「预计算 props 数组」约定base 在useMemo中一次性算出images数组每个元素已含image/displayName/onRemove等完整 props见 real-world-example.md 的 StagedImages 前后对比样式化层拿到imageProps直接展开即可无需再写 getter 函数——这与 compound-components 技能 的「Pre-computed Props Arrays for Collections」规则一一对应。Step 6: 最终验证Final Checks: - [ ] No duplicate context creation - [ ] No duplicate SDK hooks in root wrappers - [ ] No duplicate state management or event handlers - [ ] Base namespace imported and Base.Root used as wrapper - [ ] data-* classes used for styling (with group-data-* for children) - [ ] Render props used only for rendering behavior changes - [ ] Base sub-components wrapped with styling - [ ] Icon factories passed from styled layer to base hooks - [ ] Visual sub-components and CSS variants stay in styled layer三、样式化层的职责边界哪些内容必须留在 Styled Layer3.1 Icon 工厂Icon Factories当 base Hook 需要图标时样式化层以工厂函数的形式传入而不是把图标硬编码进 base// Base hook 接受可选的 icon factory export function useCombinedResourceList( providers: ResourceProvider[] | undefined, search: string, createMcpIcon?: (serverName: string) React.ReactNode, ) { /* ... */ } // 样式化层提供工厂 const resources useCombinedResourceList(providers, search, (serverName) ( McpServerIcon name{serverName} classNamew-4 h-4 / ));这个模式在仓库中有真实实现base 侧 use-combined-lists.tsx 负责 MCP 资源列表的获取、去重与过滤数据逻辑留在 base但对 MCP 项只调用createMcpIcon(serverName)生成图标而样式化层把McpServerIcon name{serverName} classNamew-4 h-4 /作为工厂注入见 real-world-example.md 的「What Moved to Base Layer」小节。这样图标库的选择、尺寸、颜色完全由样式化层掌控base 保持零视觉依赖。3.2 CSS 变体CSS Variantsconst inputVariants cva(w-full, { variants: { variant: { default: , solid: [div]:shadow-xl [div]:ring-1, bordered: [div]:border-2, }, }, });3.3 布局逻辑、可视化子组件与自定义数据获取这三类内容同样留在样式化层。真实重构中保留在样式化层的清单包括Icon 工厂、ImageContextBadge/DictationButton等视觉组件、messageInputVariantsCSS 变体、MCP 集成组件McpPromptButton、McpResourceButton、McpConfigButton、把工具栏子元素拆分为左/右两侧的布局逻辑以及MessageInputPlainTextarea纯文本替代实现见 real-world-example.md 的「What Stayed in Styled Layer」。与之对应base 负责行为样式化层负责表现而「自定义数据获取」多数据源合并、外部 Provider 组合也被明确排除在 base 原语之外——base 可以使用tambo-ai/react的 SDK Hook组件本来就依赖 Tambo Provider但合并外部数据源必须上移到样式化层参见 compound-components 技能 的「No Custom Data Fetching in Primitives」。四、类型处理Ref 类型差异base 的 Context 中持有的是RefObjectT | null而样式化组件往往需要RefObjectT需要显式断言// Base context 可能是 RefObjectT | null // 样式化组件可能需要 RefObjectT TextEditor ref{editorRef as React.RefObjectTamboEditor} /同样的处理也出现在 MessageInput 重构中MessageInputBase.Root的inputRef以inputRef as React.RefObjectTamboEditor | null传递见 real-world-example.md 的 After 代码因为 base 的MessageInputRootProps中inputRef类型就是React.RefObjectTamboEditor | null见 message-input-root.tsx。五、反模式清单以下是本技能明确禁止的做法可作为 code review 的检查项重新实现 base 逻辑Re-implementing base logic——如果 base 已经处理了它就组合它用 render props 做样式Using render props for styling——优先使用data-*类render props 只用于行为变化在包装器中重复创建 ContextDuplicating context in wrapper——使用 base 的 Root它本身就提供 Context在 base Hook 中硬编码图标Hardcoding icons in base hooks——使用工厂函数把样式留在样式化层。这四条反模式与仓库中的编码事实互为印证base 层通过MessageInputContext.Provider统一供给 Context见 message-input-root.tsxRoot 之外的任何包装器再次createContext都意味着 Step 1 的识别失败而MessageInputContent同时暴露data-*与 render props 正是为了让你能「样式走属性、行为走渲染」两不误。延伸阅读本技能与 compound-components 技能 是一对配套工作流——前者回答「base 原语怎么建」本文回答「在 base 之上怎么包」。完整的 MessageInput 重构前后对比、子组件逐项转换与行数消减统计见 real-world-example.mdbase 组件的命名空间导出与类型定义见 packages/react-ui-base/src/message-input/index.tsx。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
