docs(topbar): adding clarity to changes made

Signed-off-by: Dhruv Arora <dhruv.arora1@autodesk.com>

Author: Dhruv-0-Arora

fission/src/systems/match_mode/DefaultMatchModeConfigs.ts

@@ -12,6 +12,7 @@ class DefaultMatchModeConfigs {
     private static readonly MANIFEST_LOCATION = `${API_URL}/match_configs/manifest.json`
     private static _configs: MatchModeConfig[] = []
 
+    /** deferring loading so when you import this module, it doesn't fire a request */
     private static _loading: Promise<void> = new Promise<void>(resolve => {
         setTimeout(() => resolve(this.load()))
     })
@@ -50,10 +51,6 @@ class DefaultMatchModeConfigs {
         return this._configs
     }
 
-    public static get configs(): MatchModeConfig[] {
-        return this._configs
-    }
-
     static fallbackValues = (): MatchModeConfig => {
         return {
             id: "default",

fission/src/systems/scene/DragModeSystem.ts

@@ -95,6 +95,7 @@ class DragModeSystem extends WorldSystem {
         return this._enabled
     }
 
+    /** toggle using SetDragModeEvent. Not this */
     public set enabled(enabled: boolean) {
         if (this._enabled === enabled) return
 

fission/src/test/ui/TopBarFit.test.ts

@@ -1,13 +1,12 @@
 import { describe, expect, test } from "vitest"
-import { computeVisibleCount } from "@/ui/components/topbar/TopBarFit"
+import { computeVisibleCount, FIT_TOLERANCE_PX } from "@/ui/components/topbar/TopBarFit"
 
 const GAP = 12
 const BUTTON = 40
-const SUBPIXEL_SLACK_PX = 8
 
 const BUTTONS = Array<number>(6).fill(BUTTON)
 
-const leastBudgetFitting = (n: number) => n * (BUTTON + GAP) + SUBPIXEL_SLACK_PX
+const leastBudgetFitting = (n: number) => n * (BUTTON + GAP) + FIT_TOLERANCE_PX
 
 describe("computeVisibleCount", () => {
     test("drops exactly one item per item-width of budget, holding back slack", () => {

fission/src/ui/components/PortraitOverlay.tsx

@@ -4,7 +4,7 @@ import type React from "react"
 import { useCallback, useState } from "react"
 import { useIsMobile } from "@/ui/helpers/useIsMobile"
 
-/** Rotate your device to landscape screen */
+/** "Rotate your device to landscape" screen; dismissible */
 const PortraitOverlay: React.FC = () => {
     const isMobile = useIsMobile()
     const isPortrait = useMediaQuery("(orientation: portrait)")

fission/src/ui/components/SplitButtonDropdown.tsx

@@ -89,7 +89,8 @@ const SplitButtonDropdown: React.FC<SplitButtonDropdownProps> = ({
         [closeMenu]
     )
 
-    const hasIconSlot = items.some(item => item.icon !== undefined || item.selected !== undefined)
+    // !== undefined because row needs room for checkmark
+    const reservesIconColumn = items.some(item => item.icon !== undefined || item.selected !== undefined)
 
     return (
         <>
@@ -128,7 +129,7 @@ const SplitButtonDropdown: React.FC<SplitButtonDropdownProps> = ({
                         onClick={() => selectItem(item)}
                         sx={{ gap: 1 }}
                     >
-                        {hasIconSlot && (
+                        {reservesIconColumn && (
                             <Box sx={ICON_SLOT_SX}>
                                 {item.icon ?? (item.selected ? <SynthesisIcons.CHECK /> : null)}
                             </Box>

fission/src/ui/components/topbar/CollapsibleGroup.tsx

@@ -16,7 +16,7 @@ interface CollapsibleGroupProps {
 
 const GROUP_SX = { flexShrink: 0, "& > *": { flexShrink: 0 } } as const
 
-const KEY_SEPARATOR = "\u0000"
+const KEY_SEPARATOR = "\u0000" // joins item keys into comparable string
 
 export const CollapsibleGroup: React.FC<CollapsibleGroupProps> = ({ items, always }) => {
     const fit = useTopBarFit()
@@ -26,6 +26,7 @@ export const CollapsibleGroup: React.FC<CollapsibleGroupProps> = ({ items, alway
     const itemCount = items.length
     const itemsKey = items.map(item => item.key).join(KEY_SEPARATOR)
 
+    // adding guard to ensure 'fitted' isn't stale during renders
     const [fitted, setFitted] = useState({ itemsKey, visibleCount: itemCount })
     if (fitted.itemsKey !== itemsKey) {
         widthsRef.current = []
@@ -49,6 +50,7 @@ export const CollapsibleGroup: React.FC<CollapsibleGroupProps> = ({ items, alway
         const spacer = fit?.spacerRef.current
         if (!row || !spacer) return
 
+        // width the items occupy; free space the flex spacer is taking rn; subtracting anything overflowing out of the row already
         const widths = widthsRef.current
         const usedByItems = widths.slice(0, visibleCount).reduce((total, width) => total + width + TOP_BAR_GAP_PX, 0)
         const overflow = Math.max(0, row.scrollWidth - row.clientWidth)

fission/src/ui/components/topbar/ConfigureIcon.tsx

@@ -5,6 +5,7 @@ import { TopBarIcon, type TopBarIconName } from "@/ui/components/topbar/TopBarIc
 
 export type ConfigureIconSource = { sprite: TopBarIconName } | { glyph: IconType }
 
+// GLYPHS have a different scale than the SVGs so they match
 const GLYPH_SCALE = 0.87
 const glyphFontSize = (size: number | string) =>
     typeof size === "number" ? size * GLYPH_SCALE : `calc(${size} * ${GLYPH_SCALE})`

fission/src/ui/components/topbar/TopBarConfig.ts

@@ -12,13 +12,14 @@ export const TOP_BAR_ICON_BUTTON_SX = {
     "&:focus, &:focus-visible": { outline: "none" },
 } as const
 
-const tintedWithButtonColor = (percent: number) => `color-mix(in srgb, currentColor ${percent}%, transparent)`
+const tintedCurrentColor = (percent: number) => `color-mix(in srgb, currentColor ${percent}%, transparent)`
 
+/** The tints resolve against the `color` below - keep the two together. */
 export const TOP_BAR_ICON_BUTTON_ACTIVE_SX = {
     borderRadius: 1,
     color: "primary.main",
-    backgroundColor: tintedWithButtonColor(16),
-    "&:hover": { backgroundColor: tintedWithButtonColor(24) },
+    backgroundColor: tintedCurrentColor(16),
+    "&:hover": { backgroundColor: tintedCurrentColor(24) },
 } as const
 
 // making react-icon glyph consistent with buttons

fission/src/ui/components/topbar/TopBarFit.ts

@@ -1,10 +1,10 @@
 import type React from "react"
 import { createContext, useContext } from "react"
 
-const SUBPIXEL_SLACK_PX = 8
+export const FIT_TOLERANCE_PX = 8
 
 export function computeVisibleCount(budget: number, widths: readonly number[], gap: number): number {
-    const spendable = budget - SUBPIXEL_SLACK_PX
+    const spendable = budget - FIT_TOLERANCE_PX
 
     let used = 0
     for (let i = 0; i < widths.length; i++) {
@@ -17,6 +17,7 @@ export function computeVisibleCount(budget: number, widths: readonly number[], g
 export interface TopBarFitValue {
     rowRef: React.RefObject<HTMLElement | null>
     spacerRef: React.RefObject<HTMLElement | null>
+    // not read. increased on resize to give context value new identity & re-run
     resizeTick: number
 }
 

fission/src/ui/panels/configuring/MatchModeConfigPanel.tsx

@@ -204,6 +204,7 @@ const MatchModeConfigPanel: React.FC<PanelImplProps<void, void>> = ({ panel }) =
                     window.localStorage.getItem("match-mode-configs") || "[]"
                 )
 
+                // `prev` last so configs added while the manifest was loading survive.
                 setMatchModeConfigs(prev =>
                     Array.from(
                         new Map([...defaultConfigs, ...localConfigs, ...prev].map(item => [item.id, item])).values()