mac-human-design 0.1.27 → 0.1.29

package/changelog.md

@@ -2,6 +2,38 @@
 
 This file tracks changes between published npm versions of `mac-human-design`.
 
+## 0.1.29
+
+### Added
+
+- Added `SymbolIconButton` optical centering support through default
+  per-symbol offsets and an `opticalOffset` override prop.
+- Added verifier coverage for symbol optical offset props, default offsets, and
+  CSS variable-based glyph translation.
+
+### Changed
+
+- Tuned common toolbar SF Symbols such as refresh, upload, download, back,
+  trash, and folder-plus so their visual weight sits closer to the center of
+  the fixed macOS icon button.
+- Bumped the package to `0.1.29`.
+
+## 0.1.28
+
+### Added
+
+- Added formal coverage documentation for `MacDataTable`, `MacWindowToolbar`,
+  `MacSegmentedControl`, and `SymbolIconButton` in
+  `docs/macos-base-ui-coverage.md`.
+- Documented the shared icon-button alignment guarantees that keep icon-only
+  buttons centered across normal, loading, hover, and pressed states.
+- Extended the macOS design verifier to require the app-level component docs
+  and icon alignment guarantees before release.
+
+### Changed
+
+- Bumped the package to `0.1.28`.
+
 ## 0.1.27
 
 ### Added

package/docs/macos-base-ui-coverage.md

@@ -84,6 +84,27 @@ render UI.
 | Window sheet | `MacDialog.SheetPopup` |
 | Sidebar drawer | `MacDrawer.SidebarPopup` |
 
+## App-Level Components
+
+These shared components cover reusable macOS/Tauri app patterns that should not
+be reimplemented in consuming apps:
+
+| App pattern | Export | Contract |
+| --- | --- | --- |
+| Finder-style grid/table primitive | `MacDataTable` | Uses `table` semantics for static rows, upgrades to `grid` semantics for interactive rows, exposes row/column metadata, busy state, keyboard activation, selected row state, and focus-visible row styling. |
+| Tauri window toolbar | `MacWindowToolbar` | Provides a labelled `toolbar` landmark, labelled leading/content/trailing control groups, a root drag region, and no-drag regions around interactive controls. |
+| Segmented control | `MacSegmentedControl` | Wraps the shared macOS segmented toggle styling with accessible labels, stable class names, full-width layout support, and class/style pass-through. |
+| Centered SF Symbols icon button | `SymbolIconButton` | Renders through `MacIconButton`, defaults to `type="button"`, preserves fixed geometry while allowing style/class pass-through, supports tooltip offsets and per-symbol optical offsets, and exposes loading state with `aria-busy`. |
+
+## Icon Button Alignment Guarantees
+
+Icon-only buttons use fixed-size grid containers with zero padding, zero
+line-height, centered grid content, middle inline alignment, and center transform
+origins. `SymbolIconButton` keeps the SF Symbol and loading spinner in the same
+grid cell, centers generated symbol masks, trims transparent symbol padding in
+the native symbol service, applies per-symbol optical offsets for asymmetric
+SF Symbols, and avoids vertical Motion offsets for icon-only controls.
+
 The gallery at `examples/macos-base-ui-gallery` renders these wrappers across
 normal, selected, disabled, mixed, popup, dialog, and narrow-width states.
 
@@ -102,6 +123,8 @@ The gate typechecks the library and verifies:
 - every component family is listed in this coverage document,
 - required native variants are exported,
 - nested native variant parts such as pop-up buttons, sheets, and sidebar drawers are exported,
+- shared app-level components and icon-button alignment guarantees are
+  documented in this coverage file,
 - every class assigned by the wrapper module has a matching CSS selector,
 - every public wrapper export is represented in the visual gallery source,
 - macOS design features are present: system font stack, dark mode, reduced motion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mac-human-design",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Reusable macOS-oriented UI primitives and SF Symbols bridge for Tauri apps.",
   "type": "module",
   "main": "src/index.ts",

package/scripts/verify-macos-design.mjs

@@ -6,6 +6,7 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."
 const stylesPath = path.join(repoRoot, "src", "styles", "macosBaseUi.css");
 const packageJsonPath = path.join(repoRoot, "package.json");
 const readmePath = path.join(repoRoot, "README.md");
+const coverageDocsPath = path.join(repoRoot, "docs", "macos-base-ui-coverage.md");
 const wrapperPath = path.join(repoRoot, "src", "components", "MacBaseUI.tsx");
 const symbolIconButtonPath = path.join(repoRoot, "src", "components", "SymbolIconButton.tsx");
 const galleryPath = path.join(repoRoot, "src", "components", "MacBaseUIGallery.tsx");
@@ -50,6 +51,7 @@ const sources = new Map(
 const stylesSource = readText(stylesPath);
 const packageJson = JSON.parse(readText(packageJsonPath));
 const readmeSource = readText(readmePath);
+const coverageDocsSource = readText(coverageDocsPath);
 const wrapperSource = readText(wrapperPath);
 const symbolIconButtonSource = readText(symbolIconButtonPath);
 const gallerySource = readText(galleryPath);
@@ -157,6 +159,10 @@ requireCssDeclarations(".hd-mac-symbol-icon", [
   ["horizontal glyph centering", /justify-content\s*:\s*center\s*;/],
   ["automatic optical centering margin", /margin\s*:\s*auto\s*;/],
   ["center transform origin", /transform-origin\s*:\s*center\s*;/],
+  [
+    "symbol optical centering translate",
+    /translate\s*:\s*var\(--hd-mac-symbol-offset-x,\s*0px\)\s*var\(--hd-mac-symbol-offset-y,\s*0px\)\s*;/,
+  ],
 ]);
 
 const sharedIconButtonRule = stylesSource.match(
@@ -197,6 +203,9 @@ const symbolIconRequirements = [
   ["SymbolIconButton render element is MacIconButton", /render=\{\s*<MacIconButton\b/],
   ["SymbolIconButton applies hd-mac-symbol-icon-button class", /joinClasses\("hd-mac-symbol-icon-button", className\)/],
   ["SymbolIconButton defaults to button type", /type=["']button["']/],
+  ["SymbolIconButton supports optical offset prop", /opticalOffset\?: SymbolIconOpticalOffset/],
+  ["SymbolIconButton includes default optical offsets", /DEFAULT_SYMBOL_OPTICAL_OFFSETS/],
+  ["SymbolIconButton sets symbol offset CSS variable", /"--hd-mac-symbol-offset-x": offsetToCssValue/],
   ["SymbolIconButton supports className pass-through", /\bclassName,\s*\n\s*style,/],
   ["SymbolIconButton supports style pass-through after fixed geometry", /\.\.\.style/],
   ["SymbolIconButton supports tooltip offset", /tooltipSideOffset = 5/],
@@ -325,6 +334,27 @@ if (missingPublicDocs.length > 0) {
   );
 }
 
+const missingCoverageDocs = [
+  ["coverage docs include app-level section", /## App-Level Components/],
+  ["coverage docs document MacDataTable", /Finder-style grid\/table primitive[\s\S]*`MacDataTable`/],
+  ["coverage docs document MacWindowToolbar", /Tauri window toolbar[\s\S]*`MacWindowToolbar`/],
+  ["coverage docs document MacSegmentedControl", /Segmented control[\s\S]*`MacSegmentedControl`/],
+  ["coverage docs document SymbolIconButton", /Centered SF Symbols icon button[\s\S]*`SymbolIconButton`/],
+  ["coverage docs include icon alignment section", /## Icon Button Alignment Guarantees/],
+  ["coverage docs mention fixed-size grid containers", /fixed-size grid containers/],
+  ["coverage docs mention zero line-height", /zero[\s-]line-height/],
+  ["coverage docs mention loading spinner grid cell", /loading spinner[\s\S]*same\s+grid\s+cell/],
+  ["coverage docs mention transparent symbol padding trim", /trims transparent symbol padding/],
+  ["coverage docs mention no vertical Motion offsets", /avoids vertical Motion offsets/],
+].filter(([, pattern]) => !pattern.test(coverageDocsSource));
+
+if (missingCoverageDocs.length > 0) {
+  fail(
+    "Missing coverage documentation for shared macOS app components and icon-button alignment.",
+    missingCoverageDocs.map(([label]) => label),
+  );
+}
+
 const missingSegmentedControlRequirements = [
   ["stable segmented control class", /"hd-mac-segmented-control"/],
   ["default accessible label", /ariaLabel = "Segmented control"/],

package/src/components/SymbolIconButton.tsx

@@ -10,6 +10,7 @@ type SymbolIconButtonProps = {
   disabled?: boolean;
   isLoading?: boolean;
   iconSizePx?: number;
+  opticalOffset?: SymbolIconOpticalOffset;
   symbolEnabled?: boolean;
   className?: string;
   style?: CSSProperties;
@@ -19,10 +20,31 @@ type SymbolIconButtonProps = {
 const ICON_BUTTON_SIZE = "30px";
 const ICON_BUTTON_RADIUS = "7px";
 
+type SymbolIconOpticalOffset = {
+  x?: number | string;
+  y?: number | string;
+};
+
+const DEFAULT_SYMBOL_OPTICAL_OFFSETS: Record<string, SymbolIconOpticalOffset> = {
+  "arrow.clockwise": { y: 0.5 },
+  "square.and.arrow.up": { y: 0.35 },
+  "square.and.arrow.down": { y: 0.35 },
+  "folder.badge.plus": { x: -0.65 },
+  "chevron.left": { x: 0.6 },
+  trash: { y: 0.25 },
+};
+
 function joinClasses(...classes: Array<string | undefined | false>) {
   return classes.filter(Boolean).join(" ");
 }
 
+function offsetToCssValue(value: number | string | undefined) {
+  if (typeof value === "number") {
+    return `${value}px`;
+  }
+  return value ?? "0px";
+}
+
 export function SymbolIconButton({
   label,
   symbolName,
@@ -31,6 +53,7 @@ export function SymbolIconButton({
   disabled,
   isLoading,
   iconSizePx = 18,
+  opticalOffset,
   symbolEnabled = true,
   className,
   style,
@@ -42,6 +65,13 @@ export function SymbolIconButton({
     enabled: symbolEnabled,
   });
   const glyphPx = `${iconSizePx}px`;
+  const resolvedOpticalOffset = opticalOffset ?? DEFAULT_SYMBOL_OPTICAL_OFFSETS[symbolName];
+  const iconStyle = {
+    width: glyphPx,
+    height: glyphPx,
+    "--hd-mac-symbol-offset-x": offsetToCssValue(resolvedOpticalOffset?.x),
+    "--hd-mac-symbol-offset-y": offsetToCssValue(resolvedOpticalOffset?.y),
+  } as CSSProperties;
 
   return (
     <MacTooltip.Root>
@@ -70,8 +100,7 @@ export function SymbolIconButton({
                 aria-hidden
                 className="hd-mac-symbol-icon hd-mac-symbol-icon-mask"
                 style={{
-                  width: glyphPx,
-                  height: glyphPx,
+                  ...iconStyle,
                   color: "currentColor",
                   backgroundColor: "currentColor",
                   WebkitMaskImage: `url("${symbolDataUrl}")`,
@@ -89,8 +118,7 @@ export function SymbolIconButton({
                 aria-hidden
                 className="hd-mac-symbol-icon hd-mac-symbol-icon-fallback"
                 style={{
-                  width: glyphPx,
-                  height: glyphPx,
+                  ...iconStyle,
                   fontSize: glyphPx,
                 }}
               >

package/src/styles/macosBaseUi.css

@@ -297,6 +297,7 @@
   flex-shrink: 0;
   margin: auto;
   transform-origin: center;
+  translate: var(--hd-mac-symbol-offset-x, 0px) var(--hd-mac-symbol-offset-y, 0px);
 }
 
 .hd-mac-symbol-icon-mask {