pyqtshadcn 0.1.0__tar.gz

pyqtshadcn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QtShadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyqtshadcn-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: pyqtshadcn
+Version: 0.1.0
+Summary: PyQt6 pure-Python adapter for the QtShadcn QML component library (no C++ build).
+Author: QtShadcn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/QtShadcn/pyqtshadcn
+Project-URL: Repository, https://github.com/QtShadcn/pyqtshadcn
+Keywords: qt,qml,pyqt6,shadcn,ui,components
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyQt6>=6.10
+Dynamic: license-file
+
+# pyqtshadcn
+
+QtShadcn 组件库的 **PyQt6 纯 Python 适配包**——无需 C++ 编译，安装即用。
+
+对应主仓库 [`qtshadcn`](https://github.com/QtShadcn/qtshadcn) 的 QML 组件，本包用纯 Python 重写其
+C++ 能力层（`ThemeManager` / `IconRegistry` 两个 QML singleton），使 PyQt6 引擎可直接加载
+原仓库的 30+ 个 QML 组件（零修改复用）。
+
+## 为什么不用 C++ 插件
+
+主仓库的 C++ 插件针对特定 Qt 小版本编译，而 pip 的 PyQt6 自带另一版本 Qt，ABI 不匹配时
+QML 引擎会拒绝加载插件。本包的能力层用 Python 实现、与 PyQt6 自带 Qt 同 ABI，安装即跑。
+
+## 安装
+
+```bash
+pip install pyqtshadcn
+```
+
+需要 Python ≥ 3.10 与 PyQt6 ≥ 6.10（pip 会自动安装 PyQt6 依赖）。
+
+## 用法
+
+```python
+import sys
+from PyQt6.QtGui import QGuiApplication
+from PyQt6.QtQml import QQmlApplicationEngine
+from PyQt6.QtCore import QUrl
+
+from pyqtshadcn import setup   # 一行接入
+
+app = QGuiApplication(sys.argv)
+engine = QQmlApplicationEngine()
+setup(engine)                 # 注册 singleton + 添加 QML import path
+
+engine.loadData(b"""
+import QtQuick
+import QtQuick.Controls.Basic
+import QtShadcn
+Window {
+    width: 400; height: 300; visible: true
+    QtShadcnTheme { id: theme }
+    ShadcnButton { text: "Hello"; onClicked: theme.mode = "dark" }
+}
+""", QUrl("qrc:/main.qml"))
+
+sys.exit(app.exec())
+```
+
+`setup(engine)` 做两件事：
+
+1. `engine.addImportPath(<包内 QtShadcn 目录>)` —— 使 QML 中 `import QtShadcn` 可解析
+2. 注册 `ThemeManager` / `IconRegistry` 为 QML singleton
+
+## 本地开发运行
+
+```bash
+git clone https://github.com/QtShadcn/pyqtshadcn
+cd pyqtshadcn
+python -m venv .venv && source .venv/bin/activate
+pip install -e . PyQt6
+
+# 无界面验证（无需显示器）
+QT_QPA_PLATFORM=offscreen python examples/prototype_main.py
+```
+
+## 与主仓库的同步
+
+包内的 `qml/` 与 `icons/` 是主仓库 `src/qml`、`src/assets/icons` 的**副本**（发布时打包进 wheel）。
+主仓库更新组件后，运行同步脚本拉取最新副本：
+
+```bash
+python sync.py --src /path/to/qtshadcn     # 写文件
+python sync.py --src /path/to/qtshadcn --check   # 仅检查是否过期（CI 用）
+```
+
+同步会自动排除 `ShadcnTable`（见下）并校验 `qmldir` 与目录一致。
+
+## 已知限制
+
+1. **`ShadcnTable` 暂不支持**：该组件依赖主仓库 C++ 的 `ShadcnTableModel`（QAbstractTableModel 子类）。
+   纯 Python 路线下尚未用 `QAbstractTableModel` 移植，故包内未包含此组件。
+2. `IconRegistry` 仅实现**本地内置图标**（随包附带的 75 个 svg），未实现主仓库 C++ 版的
+   远程 CDN 兜底（lucide 按需下载 + 磁盘缓存）。
+3. 组件 QML 内已用 `import QtQuick.Controls.Basic` 强制 Basic 风格（token 自绘的前提），
+   不依赖 C++ 侧设置样式。
+
+## 许可
+
+与主仓库一致（MIT）。

pyqtshadcn-0.1.0/README.md

@@ -0,0 +1,90 @@
+# pyqtshadcn
+
+QtShadcn 组件库的 **PyQt6 纯 Python 适配包**——无需 C++ 编译，安装即用。
+
+对应主仓库 [`qtshadcn`](https://github.com/QtShadcn/qtshadcn) 的 QML 组件，本包用纯 Python 重写其
+C++ 能力层（`ThemeManager` / `IconRegistry` 两个 QML singleton），使 PyQt6 引擎可直接加载
+原仓库的 30+ 个 QML 组件（零修改复用）。
+
+## 为什么不用 C++ 插件
+
+主仓库的 C++ 插件针对特定 Qt 小版本编译，而 pip 的 PyQt6 自带另一版本 Qt，ABI 不匹配时
+QML 引擎会拒绝加载插件。本包的能力层用 Python 实现、与 PyQt6 自带 Qt 同 ABI，安装即跑。
+
+## 安装
+
+```bash
+pip install pyqtshadcn
+```
+
+需要 Python ≥ 3.10 与 PyQt6 ≥ 6.10（pip 会自动安装 PyQt6 依赖）。
+
+## 用法
+
+```python
+import sys
+from PyQt6.QtGui import QGuiApplication
+from PyQt6.QtQml import QQmlApplicationEngine
+from PyQt6.QtCore import QUrl
+
+from pyqtshadcn import setup   # 一行接入
+
+app = QGuiApplication(sys.argv)
+engine = QQmlApplicationEngine()
+setup(engine)                 # 注册 singleton + 添加 QML import path
+
+engine.loadData(b"""
+import QtQuick
+import QtQuick.Controls.Basic
+import QtShadcn
+Window {
+    width: 400; height: 300; visible: true
+    QtShadcnTheme { id: theme }
+    ShadcnButton { text: "Hello"; onClicked: theme.mode = "dark" }
+}
+""", QUrl("qrc:/main.qml"))
+
+sys.exit(app.exec())
+```
+
+`setup(engine)` 做两件事：
+
+1. `engine.addImportPath(<包内 QtShadcn 目录>)` —— 使 QML 中 `import QtShadcn` 可解析
+2. 注册 `ThemeManager` / `IconRegistry` 为 QML singleton
+
+## 本地开发运行
+
+```bash
+git clone https://github.com/QtShadcn/pyqtshadcn
+cd pyqtshadcn
+python -m venv .venv && source .venv/bin/activate
+pip install -e . PyQt6
+
+# 无界面验证（无需显示器）
+QT_QPA_PLATFORM=offscreen python examples/prototype_main.py
+```
+
+## 与主仓库的同步
+
+包内的 `qml/` 与 `icons/` 是主仓库 `src/qml`、`src/assets/icons` 的**副本**（发布时打包进 wheel）。
+主仓库更新组件后，运行同步脚本拉取最新副本：
+
+```bash
+python sync.py --src /path/to/qtshadcn     # 写文件
+python sync.py --src /path/to/qtshadcn --check   # 仅检查是否过期（CI 用）
+```
+
+同步会自动排除 `ShadcnTable`（见下）并校验 `qmldir` 与目录一致。
+
+## 已知限制
+
+1. **`ShadcnTable` 暂不支持**：该组件依赖主仓库 C++ 的 `ShadcnTableModel`（QAbstractTableModel 子类）。
+   纯 Python 路线下尚未用 `QAbstractTableModel` 移植，故包内未包含此组件。
+2. `IconRegistry` 仅实现**本地内置图标**（随包附带的 75 个 svg），未实现主仓库 C++ 版的
+   远程 CDN 兜底（lucide 按需下载 + 磁盘缓存）。
+3. 组件 QML 内已用 `import QtQuick.Controls.Basic` 强制 Basic 风格（token 自绘的前提），
+   不依赖 C++ 侧设置样式。
+
+## 许可
+
+与主仓库一致（MIT）。

pyqtshadcn-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyqtshadcn"
+version = "0.1.0"
+description = "PyQt6 pure-Python adapter for the QtShadcn QML component library (no C++ build)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "QtShadcn" }]
+keywords = ["qt", "qml", "pyqt6", "shadcn", "ui", "components"]
+dependencies = [
+    "PyQt6>=6.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/QtShadcn/pyqtshadcn"
+Repository = "https://github.com/QtShadcn/pyqtshadcn"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyqtshadcn = [
+    "QtShadcn/qml/**/*.qml",
+    "icons/**/*.svg",
+    "QtShadcn/qmldir",
+]

pyqtshadcn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyqtshadcn-0.1.0/src/pyqtshadcn/QtShadcn/qml/Components/ShadcnAvatar.qml

@@ -0,0 +1,100 @@
+import QtQuick
+import QtShadcn
+
+// 圆形头像组件：首字母 / 图标 / 图片 三选一；右下角可选状态小圆点
+//
+// 用法：
+//   ShadcnAvatar {
+//       size: ShadcnAvatar.Size.Medium
+//       text: "Ryan"
+//       status: ShadcnStatusDot.Status.Online
+//   }
+//
+//   ShadcnAvatar { iconName: "user" }
+//   ShadcnAvatar { source: "file:/path/to/photo.png"; size: ShadcnAvatar.Size.Large }
+Item {
+    id: root
+
+    enum Size { XSmall, Small, Medium, Large, XLarge }
+
+    property int size: ShadcnAvatar.Size.Medium
+    // 显示内容，按优先级：source > iconName > text（首字母）
+    property url source: ""
+    property string iconName: ""
+    property string text: ""
+
+    property color bgColor: theme.primary
+    property color textColor: theme.primaryForeground
+    property color iconColor: theme.primaryForeground
+
+    property int status: ShadcnStatusDot.Status.None
+
+    QtShadcnTheme { id: theme }
+
+    // Size 枚举 → 像素直径
+    readonly property int _diameter:
+        size === ShadcnAvatar.Size.XSmall ? 24 :
+        size === ShadcnAvatar.Size.Small  ? 32 :
+        size === ShadcnAvatar.Size.Large  ? 56 :
+        size === ShadcnAvatar.Size.XLarge ? 72 : 44   // Medium
+
+    implicitWidth: _diameter
+    implicitHeight: _diameter
+
+    // 是否使用某种内容模式（source / icon / text 三选一）
+    readonly property bool _useImage: root.source.toString().length > 0
+    readonly property bool _useIcon:  !_useImage && root.iconName.length > 0
+
+    // 视觉底：圆形填充（根是 Item 不 clip，方便 status 点越界）
+    Rectangle {
+        id: bg
+        anchors.fill: parent
+        radius: width / 2
+        color: root.bgColor
+        clip: _useImage   // 只有图片模式需要 clip 保证圆形裁切
+
+        // 模式一：图片
+        Image {
+            anchors.fill: parent
+            visible: root._useImage
+            source: root.source
+            fillMode: Image.PreserveAspectCrop
+            asynchronous: true
+            cache: true
+            sourceSize.width: parent.width * 2   // Retina 清晰
+            sourceSize.height: parent.height * 2
+        }
+
+        // 模式二：图标（无图片时）
+        ShadcnIcon {
+            visible: root._useIcon
+            anchors.centerIn: parent
+            name: root.iconName
+            size: Math.max(12, Math.round(root._diameter * 0.5))
+            color: root.iconColor
+        }
+
+        // 模式三：首字母（无图片也无图标时）
+        Text {
+            visible: !root._useImage && !root._useIcon && root.text.length > 0
+            anchors.centerIn: parent
+            text: root.text.charAt(0).toUpperCase()
+            color: root.textColor
+            font.pixelSize: Math.max(12, Math.round(root._diameter * 0.5))
+            font.weight: Font.Bold
+        }
+    }
+
+    // 状态覆盖层：右下角，大小约为头像直径 ÷4，带 1px 描边贴合头像底
+    ShadcnStatusDot {
+        id: statusDot
+        visible: root.status !== ShadcnStatusDot.Status.None
+        anchors.right: parent.right
+        anchors.bottom: parent.bottom
+        anchors.rightMargin: Math.max(0, -1)
+        anchors.bottomMargin: Math.max(0, -1)
+        status: root.status
+        size: Math.max(6, Math.round(root._diameter / 4))
+        border: true
+    }
+}

pyqtshadcn-0.1.0/src/pyqtshadcn/QtShadcn/qml/Components/ShadcnBadge.qml

@@ -0,0 +1,52 @@
+import QtQuick
+import QtShadcn
+
+// shadcn/ui 风格徽标
+// 6 variant（v4）：default / secondary / destructive（透明底红字）/ outline / ghost / link
+// 高度 20px（h-5）、胶囊圆角、文字 12px Medium
+//
+// 用法:
+//   ShadcnBadge { text: "New"; variant: ShadcnBadge.Variant.Default }
+Item {
+    id: root
+
+    enum Variant { Default, Secondary, Destructive, Outline, Ghost, Link }
+
+    property int variant: ShadcnBadge.Variant.Default
+    property string text: ""
+
+    QtShadcnTheme { id: theme }
+    VariantTokens { id: vt }
+
+    readonly property var _v: vt.badge[root.variant] ?? vt.badge[0]
+    // 中转 color 类型：theme.tokens[..] 返回 QVariant(QString)，直接 .r/.g/.b 取不到
+    // （undefined → Qt.rgba 变黑，曾致 Secondary badge 黑底深字看不见）
+    readonly property color _bgColor: _v.bg === "" ? "transparent" : theme.tokens[_v.bg]
+    readonly property color _bg: _v.bg === ""
+        ? "transparent"
+        : Qt.rgba(_bgColor.r, _bgColor.g, _bgColor.b,
+                  _v.bgAlpha !== undefined ? _v.bgAlpha : 1.0)
+    readonly property color _fg: theme.tokens[_v.fg]
+    readonly property color _border: theme.tokens[_v.borderToken !== undefined ? _v.borderToken : "border"]
+
+    implicitWidth: contentText.implicitWidth + 16   // px-2(8) * 2
+    implicitHeight: 20
+
+    Rectangle {
+        anchors.fill: parent
+        radius: 999   // 胶囊
+        color: root._bg
+        border.width: root._v.border ? 1 : 0
+        border.color: root._border
+    }
+
+    Text {
+        id: contentText
+
+        anchors.centerIn: parent
+        text: root.text
+        color: root._fg
+        font.pixelSize: 12
+        font.weight: Font.Medium
+    }
+}

pyqtshadcn-0.1.0/src/pyqtshadcn/QtShadcn/qml/Components/ShadcnButton.qml

@@ -0,0 +1,239 @@
+import QtQuick
+import QtQuick.Controls.Basic
+import QtQuick.Layouts
+import QtShadcn
+
+// shadcn/ui 风格按钮
+// 基于 QQC Button（Basic style）：键盘导航 / Focus / 无障碍继承，只替换视觉与 API
+// 注意：自定义 contentItem/background 的文件使用 style-specific import
+// （QtQuick.Controls.Basic），锁定 Basic 风格是 token 自绘的前提
+//
+// 用法:
+//   ShadcnButton {
+//       text: "Deploy"
+//       variant: ShadcnButton.Variant.Primary   // Primary/Secondary/Outline/Ghost/Destructive
+//       size: ShadcnButton.Size.Medium          // Small/Medium/Large/Icon
+//       loading: false
+//       onClicked: ...
+//   }
+Button {
+    id: root
+
+    // 选中时 z 提升：组内 spacing:-1 相邻按钮重叠 1px（后声明者盖前者右缘），
+    // 选中按钮盖住相邻按钮左缘，保证自身右缘描边完整（否则右缘 1px 被盖，
+    // 曾表现为"选中项右侧边框不存在"）
+    z: root._checked ? 1 : 0
+
+    enum Variant { Primary, Secondary, Outline, Ghost, Destructive, Link }
+    enum Size { ExtraSmall, Small, Medium, Large, Icon }
+
+    // ── 公开 API ──
+    property int variant: ShadcnButton.Variant.Primary
+    property int size: ShadcnButton.Size.Medium
+    property bool loading: false
+    // 图标（lucide 名，见 IconRegistry.names）：显示在文本左侧（shadcn 带图标按钮）
+    property string iconName: ""
+
+    // ShadcnButtonGroup / ShadcnToggleGroup 内部使用：'only' | 'first' | 'middle' | 'last'
+    property string _groupPosition: "only"
+
+    QtShadcnTheme { id: theme }
+    VariantTokens { id: vt }
+
+    // ── 尺寸表（对齐 shadcn/ui：xs=32 / sm=36 / default=40 / lg=44 / icon=40）──
+    readonly property int _ctrlHeight: size === ShadcnButton.Size.ExtraSmall ? 32
+        : size === ShadcnButton.Size.Small ? 36
+        : size === ShadcnButton.Size.Large ? 44 : 40   // Medium / Icon
+    readonly property int _hPad: size === ShadcnButton.Size.ExtraSmall ? 10
+        : size === ShadcnButton.Size.Small ? 12
+        : size === ShadcnButton.Size.Large ? 32 : 16   // shadcn px-8=32 / px-4=16
+    readonly property int _fontSize: size === ShadcnButton.Size.ExtraSmall ? 12
+        : size === ShadcnButton.Size.Small ? 12 : 14   // text-sm
+    readonly property bool _isIcon: size === ShadcnButton.Size.Icon
+
+    implicitWidth: _isIcon ? _ctrlHeight : contentItem.implicitWidth + _hPad * 2
+    implicitHeight: _ctrlHeight
+
+    // ── 配色：variant → token 查表（映射集中在 VariantTokens，新增 variant
+    //    只需枚举 + 映射表各加一项；token 名经 theme.tokens[] 查询保持绑定）──
+    readonly property bool _checked: checkable && checked
+    readonly property var _variantMap: vt.button[root.variant] ?? vt.button[0]
+    // 背景 token 不随 checked 切换（选中态视觉由 background 内的覆盖层负责——
+    // 教训：bg 在 accent↔transparent 间 color 动画会 RGBA 插值出中间灰，点击时闪烁）
+    readonly property string _bgToken: _variantMap.bg
+    // 前景色随选中切换（文字色，无动画，瞬间切换不闪）
+    readonly property string _fgToken: _checked ? vt.checkedOverride.fg : _variantMap.fg
+    readonly property color _baseBg: _bgToken === "" ? "transparent" : theme.tokens[_bgToken]
+    // hover 文字色：outline/ghost hover 时用 accentForeground（shadcn: hover:text-accent-foreground）
+    readonly property color _baseFg: (root.hovered && (variant === ShadcnButton.Variant.Outline
+                                      || variant === ShadcnButton.Variant.Ghost))
+        ? theme.accentForeground : theme.tokens[_fgToken]
+    readonly property bool _showBorder: _variantMap.border
+    // 边框宽（outline 等 border variant 才有；组内 spacing:-1 合并）
+    readonly property int _borderW: root._showBorder ? 1 : 0
+
+    // hover/pressed 混合底色：选中时用覆盖层色（accent），否则用 variant 底色。
+    // 教训：_bgToken 不随 checked 后，选中按钮的实际背景是 accent 覆盖层，
+    // 若用 primary 等深色 variant 底色混合会叠出深灰（"选中项 hover 变黑"）
+    readonly property color _hoverBase: _checked
+        ? theme.tokens[vt.checkedOverride.bg] : _baseBg
+
+    // hover 背景：outline/ghost → accent 色（shadcn: hover:bg-accent）；
+    // 其余 → 按钮色与页面背景按 hoverMix 混合（等效 shadcn hover:bg-*/90|80：
+    // 深色按钮变浅、浅色变暗，随主题背景色自动适配）。
+    // 教训：固定黑 8% 在 light 模式 primary(#18181b 近黑)上黑上加黑，肉眼不可见。
+    readonly property color _hoverOverlay: {
+        if (variant === ShadcnButton.Variant.Outline || variant === ShadcnButton.Variant.Ghost)
+            return theme.accent
+        return _mix(_hoverBase, theme.background, _variantMap.hoverMix)
+    }
+    // pressed：混合比例加重（按压反馈更深）；accent 上叠黑 15% 压暗
+    readonly property color _pressedOverlay: {
+        if (variant === ShadcnButton.Variant.Outline || variant === ShadcnButton.Variant.Ghost)
+            return Qt.rgba(0, 0, 0, 0.15)
+        return _mix(_hoverBase, theme.background, Math.min(0.25, _variantMap.hoverMix * 2))
+    }
+
+    // a 向 b 按 t 混合（t=0.1 等效 shadcn /90：0.9×a + 0.1×b）
+    function _mix(a, b, t) {
+        return Qt.rgba(a.r * (1 - t) + b.r * t, a.g * (1 - t) + b.g * t, a.b * (1 - t) + b.b * t, 1)
+    }
+
+    // 圆角：shadcn button 用 rounded-md = 6px（theme.radius 8 用于卡片/容器）
+    readonly property int _r: 6
+    readonly property int _tl: _groupPosition === "only" || _groupPosition === "first" ? _r : 0
+    readonly property int _tr: _groupPosition === "only" || _groupPosition === "last" ? _r : 0
+    readonly property int _bl: _groupPosition === "only" || _groupPosition === "first" ? _r : 0
+    readonly property int _br: _groupPosition === "only" || _groupPosition === "last" ? _r : 0
+
+    // ── 背景 ────────────────────────────────────────
+    background: Rectangle {
+        topLeftRadius: root._tl
+        topRightRadius: root._tr
+        bottomLeftRadius: root._bl
+        bottomRightRadius: root._br
+        color: root._baseBg
+        border.width: root._borderW
+        // 选中态描边用 accentForeground（light 下深色描边圈住选中项，弥补 accent 背景对比度弱；
+        // dark 下自动变白色描边。保持 border token 语义不变）
+        border.color: root.activeFocus ? theme.ring
+            : root._checked ? theme.accentForeground : theme.border
+
+        Behavior on color { ColorAnimation { duration: 120 } }
+
+        // 组内分隔线：middle/last 左侧 1px（仅无 border 的 variant，如 Primary）
+        // 用按钮自身前景色（primary 组 = 白色 primaryForeground，深底上可见；
+        // 教训：theme.foreground 在 light 模式是深色，叠深色按钮上不可见）
+        Rectangle {
+            visible: (root._groupPosition === "middle" || root._groupPosition === "last")
+                     && !root._showBorder
+            width: 1
+            anchors.top: parent.top
+            anchors.bottom: parent.bottom
+            anchors.left: parent.left
+            color: Qt.rgba(root._baseFg.r, root._baseFg.g, root._baseFg.b, 0.15)
+        }
+
+        // 选中态覆盖层（checkable 用）：accent 背景 + opacity 动画。
+        // 教训：background.color 在 accent↔transparent 间 ColorAnimation 会 RGBA 插值
+        // 出中间灰（半透明灰叠白底，点击切换时闪烁）；opacity 动画 RGB 恒定不闪灰。
+        // 内缩边框宽：outline 选中时保留 1px 边框
+        Rectangle {
+            anchors.fill: parent
+            anchors.margins: root._borderW
+            topLeftRadius: Math.max(0, parent.topLeftRadius - root._borderW)
+            topRightRadius: Math.max(0, parent.topRightRadius - root._borderW)
+            bottomLeftRadius: Math.max(0, parent.bottomLeftRadius - root._borderW)
+            bottomRightRadius: Math.max(0, parent.bottomRightRadius - root._borderW)
+            visible: root.checkable
+            color: theme.tokens[vt.checkedOverride.bg]
+            opacity: root._checked ? 1 : 0
+            Behavior on opacity { NumberAnimation { duration: 120 } }
+        }
+
+        // hover / pressed：背景色叠加（outline/ghost → accent；其余按亮度黑/白；link 无）
+        // anchors.margins = 边框宽：不盖住 outline 的 1px 边框（否则 hover 时边框视觉消失）
+        Rectangle {
+            anchors.fill: parent
+            anchors.margins: root._borderW
+            topLeftRadius: Math.max(0, parent.topLeftRadius - root._borderW)
+            topRightRadius: Math.max(0, parent.topRightRadius - root._borderW)
+            bottomLeftRadius: Math.max(0, parent.bottomLeftRadius - root._borderW)
+            bottomRightRadius: Math.max(0, parent.bottomRightRadius - root._borderW)
+            visible: root.hovered && root.variant !== ShadcnButton.Variant.Link
+            color: root._hoverOverlay
+        }
+        Rectangle {
+            anchors.fill: parent
+            anchors.margins: root._borderW
+            topLeftRadius: Math.max(0, parent.topLeftRadius - root._borderW)
+            topRightRadius: Math.max(0, parent.topRightRadius - root._borderW)
+            bottomLeftRadius: Math.max(0, parent.bottomLeftRadius - root._borderW)
+            bottomRightRadius: Math.max(0, parent.bottomRightRadius - root._borderW)
+            visible: root.pressed && root.variant !== ShadcnButton.Variant.Link
+            color: root._pressedOverlay
+        }
+
+        // 键盘焦点环（activeFocus，Tab 可达）
+        Rectangle {
+            anchors.fill: parent
+            anchors.margins: -3
+            radius: root._r + 3
+            visible: root.activeFocus
+            color: "transparent"
+            border.width: 2
+            border.color: theme.ring
+            opacity: 0.7
+        }
+    }
+
+    // ── 内容 ────────────────────────────────────────
+    // Item 包装：contentItem 会被 QQC 拉伸到内容区全宽，RowLayout 必须居中于
+    // Item（anchors.centerIn）才能保证文字水平+垂直都居中（按钮被拉伸时也成立）；
+    // RowLayout 内部子项默认垂直居中
+    contentItem: Item {
+        implicitWidth: row.implicitWidth
+        implicitHeight: row.implicitHeight
+
+        RowLayout {
+            id: row
+            anchors.centerIn: parent
+            spacing: theme.spacingXs
+
+            ShadcnSpinner {
+                Layout.preferredWidth: 14
+                Layout.preferredHeight: 14
+                visible: root.loading
+                color: root._baseFg
+            }
+
+            // 图标（iconName，shadcn 带图标按钮：svg size-4=16px，随文字色）
+            ShadcnIcon {
+                Layout.preferredWidth: 16
+                Layout.preferredHeight: 16
+                visible: root.iconName.length > 0
+                name: root.iconName
+                size: 16
+                color: root._baseFg
+            }
+
+            Text {
+                visible: root.text.length > 0
+                text: root.text
+                // 组属性限制：font 整体赋值后不能局部覆盖，故逐项复制
+                font.family: root.font.family
+                font.pixelSize: root._fontSize
+                font.weight: Font.Medium          // shadcn: font-medium
+                // link variant：hover/聚焦时显示下划线（shadcn: hover:underline）
+                font.underline: root.variant === ShadcnButton.Variant.Link
+                                && (root.hovered || root.activeFocus)
+                color: root._baseFg
+                opacity: root.loading ? 0.6 : 1
+            }
+        }
+    }
+
+    // loading：禁用交互；disabled/loading 半透明（shadcn: disabled:opacity-50）
+    enabled: !root.loading
+    opacity: root.loading || !root.enabled ? 0.5 : 1
+}

pyqtshadcn-0.1.0/src/pyqtshadcn/QtShadcn/qml/Components/ShadcnButtonGroup.qml

@@ -0,0 +1,28 @@
+import QtQuick
+import QtShadcn
+
+// 按钮组：相邻按钮边框合并（spacing: -1），圆角只保留两端
+// 子项直接放 ShadcnButton / ShadcnToggle 即可，圆角位置自动分配
+Row {
+    id: root
+
+    spacing: -1
+
+    onChildrenChanged: updateGroup()
+    Component.onCompleted: updateGroup()
+
+    function updateGroup() {
+        var btns = []
+        for (var i = 0; i < root.children.length; ++i) {
+            var c = root.children[i]
+            if (c.hasOwnProperty("_groupPosition"))
+                btns.push(c)
+        }
+        var n = btns.length
+        for (var j = 0; j < n; ++j) {
+            btns[j]._groupPosition = n === 1 ? "only"
+                : j === 0 ? "first"
+                : j === n - 1 ? "last" : "middle"
+        }
+    }
+}