Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,11 @@ jobs:
- 'src/InputBox/MainForm*.cs'
- 'src/InputBox/MainForm.resx'
- 'src/InputBox/Core/Controls/**'
- 'src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs'
- 'src/InputBox/Core/Extensions/ControlExtensions.cs'
- 'src/InputBox/Resources/**'
- 'tests/InputBox.Tests/MainFormUiSmokeTests.cs'
- 'tests/InputBox.Tests/ButtonFeedbackRenderingTests.cs'
- 'tests/InputBox.Tests/UiSmokeTestRequirements.cs'
- 'tests/InputBox.Tests/UiVisualSnapshot.cs'
- 'tests/InputBox.Tests/UiWindowDiscovery.cs'
Expand Down
2 changes: 2 additions & 0 deletions docs/engineering/a11y-safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
- 按壓狀態:獨立於焦點的第三層級。深色模式使用飽和暖色 (琥珀色 `255,200,120`),亮度差 **ΔL*≥13**。
- **Tritanopia 調整亮度公式**:$L_{tritan} = (R_{lin} \times 0.2126 + G_{lin} \times 0.7152) / 0.9278$。
- **預設動作引導**:當焦點在輸入框時,`AcceptButton` 必須顯示與焦點框一致的情境感知邊框色;強視覺反轉情境使用 **Cyan / MediumBlue**,中性情境使用 **LightBlue / MediumBlue**。
- 輸入框與預設動作提示須共用情境選色,並在輸入框底色/焦點變更時重繪。Latest 的強調色按鈕不得使提示對比下降;可在提示邊框緊鄰處繪製對比襯底,保留按鈕本體與原生主題外觀,不得改變尺寸、Margin 或 Padding。
- 測試須量測實際渲染的邊框與相鄰背景,不得只比對顏色名稱;同時覆蓋反轉及中性情境、三種主題與進度條主填色的對比。文件中對比數值為四捨五入顯示,不取代未取整的最低門檻。
- **眼動儀優化與視覺穩定性**:
- **視覺凍結 (Zero-Jitter)**:狀態變更嚴禁變動物理尺寸、Margin 或 Padding。
- **抗抖動鎖定 (Anti-Jitter Lock)**:初始化時預先計算 **Bold** 狀態最大寬度並鎖定為 `MinimumSize`。
Expand Down
50 changes: 44 additions & 6 deletions docs/engineering/git-commit-safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,50 @@
- **若簽章失敗**,Agent 應回報錯誤並提醒使用者自行檢查或授權其簽章環境;**不得** 自動修改設定檔案作為修復手段。
- **不得** 為了繞過本機 pinentry、gpg-agent 或終端互動問題,而使用 `--no-gpg-sign`、`git -c commit.gpgsign=false` 等方式提交;除非維護者明確授權,否則應先由使用者調整其簽章環境後再提交。

## 4. 分支策略與合併守門
- **採用 main-first 工作流**:`main` 必須隨時保持為可發布版本;每次新功能、修補或熱修開始前,`dev` 必須先同步或重設到目前 `main` 的最新提交,確保兩者起點一致。
- **合併路徑固定**:功能完成後,必須由 `dev` 提出 Pull Request 合併回 `main`;不得直接將應用程式變更推入 `main`。
- **CI 為必要守門**:Pull Request 在合併前,必須先確認 `.github/workflows/ci.yml` 全部必要檢查為成功狀態,未通過不得合併。
- **保留分支但每輪重對齊**:`dev` 分支可保留且 Pull Request 合併完成後**不得刪除**,但下一輪開發開始前必須重新對齊 `main`;不得讓 `dev` 長期累積與 `main` 不一致的未發布差異。
- **發版來源限制**:建立正式版本標籤時,只能以 `main` 分支最新提交為基準;不得從 `dev`、舊提交或其他分支直接打 tag 發布。
## 4. Trunk-based 分支策略與合併守門

### 4.1 分支角色與開始條件

- **`main` 是唯一主幹**,必須隨時保持為可發布版本;`dev` 是保留名稱、每輪重新對齊的開發分支,不是另一條長期整合主幹。
- 開始工作前先執行 `git fetch origin`,確認工作區、`origin/dev` 與 `origin/main` 的最新狀態。未提交變更或其他人的新提交不得被覆蓋。
- **`dev` 必須先 rebase 到最新 `origin/main`**:有待發布提交時使用 `git rebase --gpg-sign origin/main`,以使用者既有金鑰簽署重建的提交;沒有待發布差異時依 4.5 對齊。不得以 `git merge origin/main`、`git pull` 產生的 merge 或 GitHub 的 Update branch 合併操作代替。
- PR 開啟期間若 `main` 前進,必須再次 fetch、簽章 rebase、驗證並更新 `dev`,重新等待最新 SHA 的 CI;不能因先前 CI 已通過便略過同步。

### 4.2 線性歷史與 GPG 簽章

- **禁止多餘的 merge commit**:不得為同步 `main` 到 `dev` 或將 `dev` 整合回 `main` 新增 merge commit;不得使用 `--no-ff`、GitHub Create a merge commit 或 `--rebase-merges` 保留本輪不必要的分叉。檢查範圍是本輪 `origin/main..dev`,不要求重寫既有主幹歷史。
- **保留既有 GPG 簽章環境與簽章要求**:新提交使用 `git commit -S`;rebase 會改變提交物件,舊簽章不能原封不動移植,必須用既有金鑰重新簽署,而不是讓重建提交變成未簽章。
- rebase 後逐筆執行 `git verify-commit <SHA>`,驗證本輪所有提交;`git rev-list --merges origin/main..dev` 必須沒有輸出。任何簽章失敗都依第 3 節停止,不得修改 GPG 設定或關閉簽章。
- 發布到 `main` 時必須保留已驗證的提交 SHA 與 GPG 簽章;僅有相同檔案樹、只在 `dev` 留下原簽章,或只看到 GitHub 的 Verified 標籤,均不足以證明符合使用者既有金鑰的簽章要求。

### 4.3 推送與 PR 守門

- 功能、修補與文件變更均由 `dev` 提出 PR 回到 `main`;不得繞過 PR、必要 CI 或分支保護直接推送主幹。
- 首次正常推送不需強制;已推送的 `dev` 因 rebase 或對齊而改寫時,先記錄 fetch 後的遠端 SHA,經既有授權後使用 `git push --force-with-lease=refs/heads/dev:<已記錄的遠端 SHA> origin dev`。不得使用不帶保護的 `--force`,不得遇到 lease 失敗就改用新的預期值覆蓋遠端。
- 合併前必須確認:`origin/main` 是 `dev` 的祖先、本輪無 merge commit、每筆簽章有效,且 PR 最新 head SHA 的全部必要檢查成功;不得使用舊 SHA、取消、仍執行中或僅工作流外層成功的結果代替實際測試通過。
- `.github/workflows/ci.yml` 所要求的建置與測試均須通過。若某步驟允許 `continue-on-error`,仍須讀取實際日誌,確認測試失敗數為零;MSBuild 不得有警告或錯誤。

### 4.4 合併方法與遠端限制

- **預設整合語意是 fast-forward**:經 PR 審查與 CI 守門後,讓 `main` 前移到已驗證的 `dev` 提交,不建立額外提交、不改寫 SHA,也不丟失既有 GPG 簽章。
- **不得直接選用 GitHub Rebase and merge**:GitHub 會重建提交,不能保留原提交的簽章驗證。Squash and merge 也會建立新的提交,不能視為保留原 GPG 簽章的等價方式。一般 Create a merge commit 則違反本節的線性歷史要求。
- 執行前必須確認實際平台與 repository ruleset 是否提供同時滿足 PR 守門、fast-forward 與保留簽章的整合方式;不得假設 GitHub 標準合併按鈕提供 fast-forward-only。
- 若現有遠端規則無法同時滿足上述要求,**停止合併並向維護者具體回報衝突**,取得對整合方式或規則調整的明確授權後才可繼續。不得自行改成 merge commit、丟棄簽章、繞過保護或直接推送 `main`。
- 合併後確認 PR 已 merged、`main` 新增的提交沒有 merge commit、簽章仍有效,並核對合併內容與通過 CI 的版本一致。追蹤合併後實際觸發的所有必要檢查至完成;若建置僅由 PR 觸發,須如實說明,不能聲稱 main push 已重跑建置與測試。

### 4.5 合併後立即重新對齊 dev

- **保留 `dev`,不得刪除;每次 PR 合併完成後就立即對齊 `main`**,不得延後到下一輪開發才處理。
- 重新 fetch,確認 PR 已合併、工作區沒有未提交變更,且 `dev` 沒有其他尚未發布或他人新增的工作;如有則停止重設並回報,不能直接捨棄。
- 在已授權重設與推送的範圍內,切到 `dev`,執行 `git reset --hard origin/main`,再以 4.3 的精確 `--force-with-lease` 更新遠端 `dev`。若尚無破壞性操作或外部寫入授權,先取得授權再執行。
- 完成後驗證本機 `dev`、`origin/dev` 與最新遠端 `main` SHA 完全相同,且工作區乾淨;若主幹又前進或遠端 dev 已變動,重新檢查,不能盲目重設或重試強制推送。

### 4.6 發版來源

- 正式版本標籤只能從最新遠端 `main` 建立;不得從未整合的 `dev`、舊提交或其他分支打 tag 發布。
- 標籤依第 3 節使用既有 GPG 環境簽署並驗證,推送後追蹤實際發佈結果;不得只看到 tag 已推送便聲稱 Release 成功。

參考:[Git rebase 簽章選項](https://git-scm.com/docs/git-rebase)、[GitHub rebase and merge 的簽章限制](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)、[GitHub 合併方法](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github)。

## 5. 法律合規工作流
1. 若任務涉及「按鍵處理」、「剪貼簿自動化」或「控制器映射」。
Expand Down
125 changes: 112 additions & 13 deletions src/InputBox/Core/Extensions/ButtonEyeTrackerExtensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,13 @@ private sealed class ButtonVisualState
/// <summary>
/// 是否按壓按鈕(包含實際的鼠標按壓或鍵盤焦點狀態下的強視覺反饋)
/// </summary>
public bool IsPressed { get; set; }
public bool IsPressed => IsPointerPressed || IsKeyboardPressed;

/// <summary>滑鼠按壓狀態,與鍵盤狀態獨立清理。</summary>
public bool IsPointerPressed { get; set; }

/// <summary>Space 按壓狀態,失焦時必須清理。</summary>
public bool IsKeyboardPressed { get; set; }

/// <summary>
/// 凝視進度(Dwell Progress),表示使用者注視按鈕的時間比例
Expand Down Expand Up @@ -125,8 +131,48 @@ public static void AttachEyeTrackerFeedback(

btn.MouseUp -= HandleButtonMouseUp;
btn.MouseUp += HandleButtonMouseUp;

btn.KeyDown -= HandleButtonKeyDown;
btn.KeyDown += HandleButtonKeyDown;
btn.KeyUp -= HandleButtonKeyUp;
btn.KeyUp += HandleButtonKeyUp;

btn.SystemColorsChanged -= HandleButtonSystemColorsChanged;
btn.SystemColorsChanged += HandleButtonSystemColorsChanged;
}

/// <summary>Space 按住時套用獨立按下視覺,不攔截原生鍵盤點擊。</summary>
private static void HandleButtonKeyDown(object? sender, KeyEventArgs eventArgs)
{
if (eventArgs.KeyCode == Keys.Space && sender is Button { Enabled: true, Focused: true } button &&
_buttonStates.TryGetValue(button, out ButtonVisualState? state) && !state.IsKeyboardPressed)
{
state.IsKeyboardPressed = true;
StartAnimationFeedback(button);
}
}

/// <summary>Space 放開後還原目前焦點或懸停狀態。</summary>
private static void HandleButtonKeyUp(object? sender, KeyEventArgs eventArgs)
{
if (eventArgs.KeyCode == Keys.Space && sender is Button button &&
_buttonStates.TryGetValue(button, out ButtonVisualState? state))
{
state.IsKeyboardPressed = false;
StopFeedback(button);
}
}
/// <summary>
/// 系統色或高對比改變時重新套用目前互動狀態,避免保留上一個配色。
/// 深淺色模式仍由框架的啟動設定決定,不取代既有重啟提示。
/// </summary>
private static void HandleButtonSystemColorsChanged(object? sender, EventArgs eventArgs)
{
if (sender is Button { IsDisposed: false } button)
{
StopFeedback(button);
}
}
/// <summary>
/// 點擊後重置進度,
/// 並執行視線重新接合(Gaze Re-engagement),
Expand Down Expand Up @@ -230,7 +276,8 @@ private static void HandleButtonLostFocus(object? sender, EventArgs eventArgs)
{
if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state))
{
state.IsPressed = false;
state.IsPointerPressed = false;
state.IsKeyboardPressed = false;
state.OnFocusStateChanged?.Invoke(state.IsHovered);
}

Expand Down Expand Up @@ -279,7 +326,8 @@ private static void HandleButtonMouseLeave(object? sender, EventArgs eventArgs)
if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state))
{
state.IsHovered = false;
state.IsPressed = false;
state.IsPointerPressed = false;
state.IsKeyboardPressed = false;
state.OnFocusStateChanged?.Invoke(btn.Focused);
}

Expand All @@ -299,7 +347,7 @@ private static void HandleButtonMouseDown(object? sender, MouseEventArgs eventAr
{
if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state))
{
state.IsPressed = true;
state.IsPointerPressed = true;
}

StartAnimationFeedback(btn);
Expand All @@ -318,7 +366,7 @@ private static void HandleButtonMouseUp(object? sender, MouseEventArgs eventArgs
{
if (_buttonStates.TryGetValue(btn, out ButtonVisualState? state))
{
state.IsPressed = false;
state.IsPointerPressed = false;
}

StartAnimationFeedback(btn);
Expand Down Expand Up @@ -381,7 +429,6 @@ private static void ApplyStrongVisual(Button btn)
$"{st.BaseDescription} ({Strings.A11y_State_Pressed})" :
$"{st.BaseDescription} ({Strings.A11y_State_Focused})";

btn.Padding = new Padding(0);
btn.Invalidate();
}

Expand Down Expand Up @@ -416,7 +463,7 @@ private static void StartAnimationFeedback(Button btn)

if (SystemInformation.HighContrast)
{
btn.BackColor = SystemColors.HotTrack;
btn.BackColor = SystemColors.Highlight;
btn.ForeColor = SystemColors.HighlightText;
}
else
Expand All @@ -441,7 +488,6 @@ private static void StartAnimationFeedback(Button btn)

btn.AccessibleDescription = $"{st.BaseDescription} ({Strings.A11y_State_Hover})";

btn.Padding = new Padding(0);
btn.Invalidate();

btn.RunDwellAnimationAsync(
Expand All @@ -468,16 +514,16 @@ private static void StopFeedback(Button btn)

st.DwellProgress = 0f;

if (btn.Focused)
if (st.IsHovered || st.IsPressed)
{
ApplyStrongVisual(btn);
StartAnimationFeedback(btn);

return;
}

if (st.IsHovered)
if (btn.Focused)
{
StartAnimationFeedback(btn);
ApplyStrongVisual(btn);

return;
}
Expand All @@ -499,6 +545,36 @@ private static void StopFeedback(Button btn)
btn.Invalidate();
}

/// <summary>
/// 為現有文字按鈕繪製一致的互動配色,不受 Net11 預設動作強調色覆蓋。
/// </summary>
/// <param name="button">目前處於自訂回饋狀態的按鈕。</param>
/// <param name="graphics">按鈕繪圖內容。</param>
private static void DrawFeedbackSurface(Button button, Graphics graphics)
{
using Brush background = new SolidBrush(button.BackColor);
graphics.FillRectangle(background, button.ClientRectangle);

int inset = (int)Math.Ceiling(4 * button.DeviceDpi / AppSettings.BaseDpi);
Rectangle textBounds = Rectangle.FromLTRB(
inset + button.Padding.Left, inset + button.Padding.Top,
button.Width - inset - button.Padding.Right, button.Height - inset - button.Padding.Bottom);
TextFormatFlags flags = TextFormatFlags.HorizontalCenter |
TextFormatFlags.VerticalCenter | TextFormatFlags.WordBreak |
TextFormatFlags.PreserveGraphicsClipping;
if (!button.UseMnemonic)
{
flags |= TextFormatFlags.NoPrefix;
}

if (button.RightToLeft == RightToLeft.Yes)
{
flags |= TextFormatFlags.RightToLeft;
}

TextRenderer.DrawText(graphics, button.Text, button.Font, textBounds, button.ForeColor, flags);
}

/// <summary>
/// 負責接管原生的 Paint 事件以繪製包含基礎邊框、
/// 互動邊框、對比色、與 Dwell 進度條的所有按鈕客製化視覺
Expand Down Expand Up @@ -530,6 +606,14 @@ private static void HandleButtonPaint(object? sender, PaintEventArgs e)
return;
}

// Net11 的預設按鈕強制使用強調色背景,但仍接受自訂文字色。
// 自訂回饋期間成對繪製背景與文字,避免背景被覆寫而失去對比;
// 高對比的一般狀態也保留系統色配對;其他一般與停用狀態沿用原生渲染。
if (st != null && (SystemInformation.HighContrast || st.IsPressed || isFocused || isHoveredOrDwell))
{
DrawFeedbackSurface(btn, g);
Comment thread
perditavojo marked this conversation as resolved.
Resolved
}

Form? parentForm = btn.FindForm();

bool isDefault = parentForm != null &&
Expand All @@ -552,13 +636,28 @@ parentForm.ActiveControl is not Button &&
isDefault)
{
Color borderColor = btn.GetButtonInteractiveBorderColor(isStrongVisual, isDark);
Color? backingColor = null;
if (isDefault && !isFocused && !isHoveredOrDwell && !(st?.IsPressed ?? false))
{
Control? context = parentForm?.ActiveControl;
while (context is ContainerControl { ActiveControl: not null } container)
{
context = container.ActiveControl;
}

(Color Border, Color Backing) = ControlExtensions.GetContextualFocusColors(
context?.BackColor ?? Color.Empty, isDark);
borderColor = Border;
backingColor = Backing;
}

btn.DrawButtonInteractiveBorder(
g,
borderColor,
scale,
out int inset,
out int borderThickness);
out int borderThickness,
backingColor);

if (!SystemInformation.HighContrast &&
(st?.IsPressed ?? false))
Expand Down
Loading
Loading