From 6827b8fc6ac32217cc27e5095422e9496739643f Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sat, 13 Jun 2026 19:15:50 +0800
Subject: [PATCH] Fix app grid usage tips interactions
---
src/Scripts/usage_tips_qa.sh | 227 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 files changed, 218 insertions(+), 9 deletions(-)
diff --git a/src/Scripts/usage_tips_qa.sh b/src/Scripts/usage_tips_qa.sh
index 7b5b0e8..ac03213 100755
--- a/src/Scripts/usage_tips_qa.sh
+++ b/src/Scripts/usage_tips_qa.sh
@@ -4,6 +4,7 @@
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONTENT_VIEW_SWIFT="$ROOT_DIR/Apptag/ContentView.swift"
APP_GRID_SWIFT="$ROOT_DIR/Apptag/AppGridCollectionView.swift"
+APPTAG_APP_SWIFT="$ROOT_DIR/Apptag/ApptagApp.swift"
PREFERENCES_VIEW_SWIFT="$ROOT_DIR/Apptag/PreferencesView.swift"
APP_DEFAULTS_SWIFT="$ROOT_DIR/Apptag/AppDefaults.swift"
LOCALIZATION_DIR="$ROOT_DIR/Apptag/Localization"
@@ -15,11 +16,12 @@
[[ -f "$CONTENT_VIEW_SWIFT" ]] || fail "missing ContentView.swift"
[[ -f "$APP_GRID_SWIFT" ]] || fail "missing AppGridCollectionView.swift"
+[[ -f "$APPTAG_APP_SWIFT" ]] || fail "missing ApptagApp.swift"
[[ -f "$PREFERENCES_VIEW_SWIFT" ]] || fail "missing PreferencesView.swift"
[[ -f "$APP_DEFAULTS_SWIFT" ]] || fail "missing AppDefaults.swift"
[[ -d "$LOCALIZATION_DIR" ]] || fail "missing Localization directory"
-python3 - "$CONTENT_VIEW_SWIFT" "$APP_GRID_SWIFT" "$PREFERENCES_VIEW_SWIFT" "$APP_DEFAULTS_SWIFT" "$LOCALIZATION_DIR" <<'PY'
+python3 - "$CONTENT_VIEW_SWIFT" "$APP_GRID_SWIFT" "$APPTAG_APP_SWIFT" "$PREFERENCES_VIEW_SWIFT" "$APP_DEFAULTS_SWIFT" "$LOCALIZATION_DIR" <<'PY'
import json
import pathlib
import re
@@ -27,9 +29,10 @@
content_view = pathlib.Path(sys.argv[1]).read_text(encoding="utf-8")
app_grid = pathlib.Path(sys.argv[2]).read_text(encoding="utf-8")
-preferences = pathlib.Path(sys.argv[3]).read_text(encoding="utf-8")
-defaults = pathlib.Path(sys.argv[4]).read_text(encoding="utf-8")
-localization_dir = pathlib.Path(sys.argv[5])
+apptag_app = pathlib.Path(sys.argv[3]).read_text(encoding="utf-8")
+preferences = pathlib.Path(sys.argv[4]).read_text(encoding="utf-8")
+defaults = pathlib.Path(sys.argv[5]).read_text(encoding="utf-8")
+localization_dir = pathlib.Path(sys.argv[6])
required_keys = [
"settings.hideUsageTips",
@@ -83,17 +86,61 @@
"Usage tips must be implemented as a native AppKit NSView",
)
require(
- r"enum\s+AppGridUsageTipsMetrics\s*\{(?P<body>.*?)static\s+let\s+reservedHeight\s*:\s*CGFloat\s*=\s*104",
+ r"enum\s+AppGridUsageTipsMetrics\s*\{(?P<body>.*?)static\s+let\s+reservedHeight\s*:\s*CGFloat\s*=\s*128",
app_grid,
- "Usage tips overlay must reserve stable bottom space for the larger native bar",
+ "Usage tips overlay must reserve stable bottom space for the native HUD bar",
+)
+require(
+ r"NSVisualEffectView\s*\(",
+ app_grid,
+ "Usage tips must use a native macOS visual effect surface instead of split black/white blocks",
+)
+require(
+ r'systemSymbolName\s*:\s*"lightbulb\.fill"',
+ app_grid,
+ "Usage tips HUD must include a compact native guidance icon",
+)
+require(
+ r"preferredWidth\s*\(\s*maxAvailableWidth\s*:\s*CGFloat\s*\)",
+ app_grid,
+ "Usage tips HUD must be content-adaptive instead of stretched across the full AppGrid",
+)
+if re.search(r"static\s+let\s+maxWidth\s*:\s*CGFloat", app_grid):
+ fail("Usage tips HUD must not use a hard maximum width that truncates localized titles")
+require(
+ r"fullTitleWidth\s*=\s*ceil\s*\(\s*titleLabel\.attributedStringValue\.size\(\)\.width\s*\)",
+ app_grid,
+ "Usage tips layout must measure the localized title width instead of using a fixed title column",
+)
+require(
+ r"configureLabel\s*\(\s*titleLabel\s*,\s*font\s*:\s*titleFont\s*,\s*lineBreakMode\s*:\s*\.byClipping\s*\)",
+ app_grid,
+ "Usage tip titles must not use tail truncation ellipses",
+)
+if re.search(r"configureLabel\s*\(\s*titleLabel\s*,\s*font\s*:\s*titleFont\s*,\s*lineBreakMode\s*:\s*\.byTruncatingTail\s*\)", app_grid):
+ fail("Usage tip titles must not be configured with byTruncatingTail")
+require(
+ r"relayoutUsageTipsAfterContentChange\s*\(\s*\)",
+ app_grid,
+ "Usage tips must ask the host to recompute width after localized text changes",
+)
+require(
+ r"availableTextWidth\s*=\s*max\s*\(\s*1\s*,\s*visualFrame\.maxX\s*-\s*titleX\s*-\s*titleDetailGap\s*-\s*trailingWidth\s*\)",
+ app_grid,
+ "Usage tips layout must allocate text from actual available AppGrid width",
+)
+require(
+ r"return\s+min\s*\(\s*maxAvailableWidth\s*,\s*preferredWidth\s*\)",
+ app_grid,
+ "Usage tips preferred width must expand up to available AppGrid width for long localizations",
)
require(
r"detailScrollView\.hasHorizontalScroller\s*=\s*true",
app_grid,
"Long localized tip text must be horizontally scrollable in the native AppKit bar",
)
-if len(re.findall(r"NSFont\.systemFont\s*\(\s*ofSize\s*:\s*24\s*,\s*weight\s*:\s*\.bold\s*\)", app_grid)) < 2:
- fail("Usage tip title/detail fonts must use the larger 24pt native AppKit style")
+if len(re.findall(r"NSFont\.systemFont\s*\(\s*ofSize\s*:\s*24\s*,\s*weight\s*:\s*\.(?:semibold|regular)\s*\)", app_grid)) < 2:
+ fail("Usage tip title/detail fonts must use readable 24pt native HUD typography")
require(
r"override\s+func\s+scrollWheel\s*\(\s*with\s+event\s*:\s*NSEvent\s*\)\s*\{\s*detailScrollView\.scrollWheel\s*\(\s*with\s*:\s*event\s*\)",
app_grid,
@@ -120,6 +167,103 @@
"Native usage tips bar must own hit testing so clicks do not fall through to AppGrid",
)
require(
+ r"override\s+func\s+hitTest\s*\(\s*_\s+point\s*:\s*NSPoint\s*\)\s*->\s*NSView\?\s*\{(?P<body>.*?)usageTipsView\.frame\.contains\s*\(\s*point\s*\)",
+ app_grid,
+ "AppGrid host must prioritize the native usage tips hit-test region above the collection view",
+)
+require(
+ r"usageTipsEventRegion\s*\(\s*\)\s*->\s*NSRect",
+ app_grid,
+ "AppGrid host must reserve a full bottom event region for tips so clicks cannot pass through",
+)
+require(
+ r"private\s+final\s+class\s+AppGridUsageTipsShieldView\s*:\s*NSView\b",
+ app_grid,
+ "AppGrid must use a native transparent shield view for the full bottom tips event region",
+)
+require(
+ r"usageTipsShieldView\.frame\s*=\s*usageTipsEventRegion\s*\(\s*\)",
+ app_grid,
+ "Usage tips shield must cover the full bottom event region, not just the visible HUD",
+)
+require(
+ r"usageTipsView\.frame\s*=\s*usageTipsEventRegion\s*\(\s*\)",
+ app_grid,
+ "Usage tips HUD hit-test view itself must cover the full bottom event region",
+)
+require(
+ r"configureVisualLayout\s*\(\s*width\s*:\s*CGFloat\s*,\s*height\s*:\s*CGFloat\s*,\s*bottomMargin\s*:\s*CGFloat\s*\)",
+ app_grid,
+ "Usage tips must separate full hit-test coverage from the centered visual HUD frame",
+)
+require(
+ r"currentVisualFrame\s*\(\s*\)\s*->\s*NSRect",
+ app_grid,
+ "Usage tips must compute a centered visual frame inside the full bottom hit-test region",
+)
+require(
+ r"addSubview\s*\(\s*usageTipsShieldView\s*,\s*positioned\s*:\s*\.above\s*,\s*relativeTo\s*:\s*scrollView\s*\)",
+ app_grid,
+ "Usage tips shield must sit above the AppGrid collection scroll view",
+)
+require(
+ r"addSubview\s*\(\s*usageTipsView\s*,\s*positioned\s*:\s*\.above\s*,\s*relativeTo\s*:\s*usageTipsShieldView\s*\)",
+ app_grid,
+ "Visible usage tips HUD must sit above the transparent event shield",
+)
+require(
+ r"claimUsageTipsEventRegion\s*\(\s*\)",
+ app_grid,
+ "AppGrid host must claim bottom tips events and suppress lower bubbles",
+)
+require(
+ r"handleUsageTipsMouseDown\s*\(\s*_\s+event\s*:\s*NSEvent\s*\)\s*->\s*Bool",
+ app_grid,
+ "AppGrid host must expose a native AppKit event router for usage tips clicks",
+)
+require(
+ r"addLocalMonitorForEvents\s*\(\s*matching\s*:\s*\[(?P<body>.*?)\.leftMouseDown(?P<body2>.*?)\.leftMouseUp(?P<body3>.*?)\.rightMouseDown(?P<body4>.*?)\.otherMouseUp",
+ app_grid,
+ "AppGrid host must intercept usage tips mouseDown/mouseUp events before NSCollectionView app items receive them",
+)
+require(
+ r"\.leftMouseUp(?P<body>.*?)\.rightMouseUp(?P<body2>.*?)\.otherMouseUp",
+ app_grid,
+ "AppGrid host must also swallow mouseUp events in the usage tips region so app icons below cannot open on release",
+)
+require(
+ r"triggerButtons\s*:\s*event\.type\s*==\s*\.leftMouseDown",
+ app_grid,
+ "Usage tips monitor must only trigger paging on left mouseDown, not on mouseUp or right/other clicks",
+)
+require(
+ r"usageTipsHostPoint\s*\(\s*for\s+event\s*:\s*NSEvent\s*\)\s*->\s*NSPoint",
+ app_grid,
+ "Usage tips mouse monitor must resolve the event position through the AppGrid host",
+)
+require(
+ r"window\.convertPoint\s*\(\s*fromScreen\s*:\s*NSEvent\.mouseLocation\s*\)",
+ app_grid,
+ "Usage tips hit testing must fall back to current screen mouse location when event.window is unreliable",
+)
+require(
+ r"self\.handleUsageTipsMouseEvent\s*\(\s*event\s*,(?P<body>.*?)triggerButtons\s*:\s*event\.type\s*==\s*\.leftMouseDown(?P<body2>.*?)return\s+nil",
+ app_grid,
+ "Usage tips mouse monitor must swallow handled bottom-tip events so app icons below cannot open",
+)
+require(
+ r"removeUsageTipsMouseMonitor\s*\(\s*\)",
+ app_grid,
+ "Usage tips mouse monitor must be removed when the AppGrid host leaves its window",
+)
+require(
+ r"func\s+handleMouseEventFromHost\s*\(\s*_\s+event\s*:\s*NSEvent\s*,\s*triggerButtons\s*:\s*Bool\s*\)\s*->\s*Bool\s*\{(?P<body>.*?)if\s+triggerButtons\s*,\s*routeButtonClickIfNeeded\s*\(\s*event\s*\)(?P<body2>.*?)claimInteractionFocus\s*\(\s*\)(?P<body3>.*?)return\s+true",
+ app_grid,
+ "Usage tips host-routed clicks must only trigger page changes on arrow hit regions and otherwise only consume the event",
+)
+if re.search(r"handleMouseEventFromHost\s*\(\s*_\s+event\s*:\s*NSEvent\s*,\s*triggerButtons\s*:\s*Bool\s*\)\s*->\s*Bool\s*\{(?P<body>.*?)target\.mouseDown", app_grid, re.S):
+ fail("Usage tips host-routed clicks must not redispatch arbitrary mouseDown events that can pierce to app icons")
+require(
r"override\s+func\s+mouseDown\s*\(\s*with\s+event\s*:\s*NSEvent\s*\)",
app_grid,
"Native usage tips bar must swallow mouseDown events instead of letting clicks close the grid",
@@ -128,6 +272,36 @@
r"private\s+final\s+class\s+AppGridUsageTipIconButton\s*:\s*NSView\b",
app_grid,
"Usage tip navigation controls must be native AppKit hit-testable views",
+)
+require(
+ r"private\s+final\s+class\s+AppGridDecorativeImageView\s*:\s*NSImageView\b(?P<body>.*?)override\s+func\s+hitTest\s*\(\s*_\s+point\s*:\s*NSPoint\s*\)\s*->\s*NSView\?\s*\{\s*nil\s*\}",
+ app_grid,
+ "Usage tip icon images must not steal hit testing from their parent AppKit controls",
+)
+require(
+ r"private\s+final\s+class\s+AppGridUsageTipIconButton\s*:\s*NSView\b(?P<body>.*?)acceptsFirstMouse\s*\(\s*for\s+event\s*:\s*NSEvent\?\s*\)\s*->\s*Bool\s*\{\s*true\s*\}",
+ app_grid,
+ "Usage tip navigation controls must accept first mouse clicks in the floating overlay",
+)
+require(
+ r"override\s+func\s+isAccessibilityElement\s*\(\s*\)\s*->\s*Bool\s*\{\s*true\s*\}",
+ app_grid,
+ "Usage tip navigation controls must be exposed as accessibility elements",
+)
+require(
+ r"override\s+func\s+accessibilityRole\s*\(\s*\)\s*->\s*NSAccessibility\.Role\?\s*\{\s*\.button\s*\}",
+ app_grid,
+ "Usage tip navigation controls must expose the AX button role",
+)
+require(
+ r"override\s+func\s+accessibilityPerformPress\s*\(\s*\)\s*->\s*Bool\s*\{(?P<body>.*?)action\?\(\)(?P<body2>.*?)return\s+true",
+ app_grid,
+ "Usage tip navigation controls must support AX press actions",
+)
+require(
+ r"override\s+var\s+mouseDownCanMoveWindow\s*:\s*Bool\s*\{\s*false\s*\}",
+ app_grid,
+ "Usage tips hit-test views must not let mouseDown move or dismiss the overlay window",
)
require(
r"func\s+selectUsageTip\s*\(\s*offset\s*:\s*Int\s*\)",
@@ -145,7 +319,7 @@
"Next usage tip control must call the native selection handler",
)
require(
- r"override\s+func\s+mouseDown\s*\(\s*with\s+event\s*:\s*NSEvent\s*\)\s*\{\s*action\?\(\)\s*\}",
+ r"override\s+func\s+mouseDown\s*\(\s*with\s+event\s*:\s*NSEvent\s*\)\s*\{(?P<body>.*?)action\?\(\)",
app_grid,
"Native usage tip icon buttons must invoke their action directly on mouseDown",
)
@@ -153,6 +327,16 @@
r"onUsageTipIndexChange\s*\(\s*nextIndex\s*\)",
app_grid,
"Native usage tip selection must publish the new index back to SwiftUI state",
+)
+require(
+ r"override\s+func\s+keyDown\s*\(\s*with\s+event\s*:\s*NSEvent\s*\)\s*\{(?P<body>.*?)kVK_LeftArrow(?P<body2>.*?)kVK_RightArrow",
+ app_grid,
+ "Focused native usage tips HUD must support left/right arrow key switching",
+)
+require(
+ r"formattedTipDetail\s*\(_\s+text\s*:\s*String\s*\)",
+ app_grid,
+ "Usage tips detail text must normalize > separators to -> for display",
)
require(
r"setUsageTipsBubbleDisabled\s*\(\s*inside\s*\)",
@@ -165,6 +349,31 @@
"Hovering usage tips must notify ContentView to clear already visible SwiftUI bubbles",
)
require(
+ r"shouldSwallowUsageTipsBackdropClick\s*\(\s*at\s+location\s*:\s*NSPoint\s*\)\s*->\s*Bool",
+ apptag_app,
+ "DismissibleHostingView must not treat bottom usage tips clicks as backdrop taps",
+)
+require(
+ r"routeUsageTipsMouseDownIfNeeded\s*\(\s*event\s*\)",
+ apptag_app,
+ "DismissibleHostingView must forward bottom usage tips clicks to native AppKit controls before swallowing",
+)
+require(
+ r"findAppGridCollectionHost\s*\(\s*in\s+view\s*:\s*NSView\s*\)\s*->\s*AppGridCollectionHostView\?",
+ apptag_app,
+ "DismissibleHostingView must locate the native AppGrid host for usage tips event forwarding",
+)
+require(
+ r"AppGridUsageTipsMetrics\.reservedHeight",
+ apptag_app,
+ "Backdrop usage tips guard must match the native AppGrid reserved height",
+)
+require(
+ r'UserDefaults\.standard\.bool\s*\(\s*forKey\s*:\s*"hideUsageTips"\s*\)',
+ apptag_app,
+ "Backdrop usage tips guard must respect the hide usage tips setting",
+)
+require(
r"private\s+func\s+handleUsageTipsHoverChange\s*\(\s*_\s+hovering\s*:\s*Bool\s*\)",
content_view,
"ContentView must clear existing app bubbles while the native usage tips bar is hovered",
--
Gitblit v1.9.3