mac-human-design 0.1.22 → 0.1.24

package/changelog.md

@@ -2,6 +2,40 @@
 
 This file tracks changes between published npm versions of `mac-human-design`.
 
+## 0.1.24
+
+### Added
+
+- Added `role="toolbar"`, optional accessible labels, labelled control groups,
+  and title accessibility handling to `MacWindowToolbar`.
+- Added gallery coverage for an explicitly labelled `MacWindowToolbar`.
+- Extended the macOS design verifier to protect toolbar accessibility and
+  Tauri drag-region invariants.
+
+### Changed
+
+- `MacWindowToolbar` now gives leading, content, and trailing control groups
+  stable accessible labels while preserving no-drag regions around interactive
+  controls.
+- Bumped the package to `0.1.24`.
+
+## 0.1.23
+
+### Added
+
+- Added `grid`/`table` semantics, row and column metadata, busy state, selected
+  row state, keyboard row activation, and optional accessible labels to
+  `MacDataTable`.
+- Added focus-visible styling for interactive `MacDataTable` rows.
+- Extended the macOS design verifier to protect interactive table/grid
+  accessibility invariants.
+
+### Changed
+
+- Interactive table rows can now be selected with Space and opened/activated
+  with Enter when row handlers are provided.
+- Bumped the package to `0.1.23`.
+
 ## 0.1.22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mac-human-design",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "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

@@ -8,6 +8,8 @@ const packageJsonPath = path.join(repoRoot, "package.json");
 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");
+const dataTablePath = path.join(repoRoot, "src", "components", "MacDataTable.tsx");
+const windowToolbarPath = path.join(repoRoot, "src", "components", "MacWindowToolbar.tsx");
 const symbolServicePath = path.join(repoRoot, "src", "symbols", "systemSymbolService.ts");
 
 function readText(filePath) {
@@ -48,6 +50,8 @@ const packageJson = JSON.parse(readText(packageJsonPath));
 const wrapperSource = readText(wrapperPath);
 const symbolIconButtonSource = readText(symbolIconButtonPath);
 const gallerySource = readText(galleryPath);
+const dataTableSource = readText(dataTablePath);
+const windowToolbarSource = readText(windowToolbarPath);
 const symbolServiceSource = readText(symbolServicePath);
 
 function getCssRuleBody(selector) {
@@ -249,6 +253,51 @@ if (
   ]);
 }
 
+const missingDataTableRequirements = [
+  ["interactive grid role", /const tableRole = hasInteractiveRows \? "grid" : "table"/],
+  ["aria busy state", /aria-busy=\{loading \|\| undefined\}/],
+  ["row count metadata", /aria-rowcount=\{loading \? undefined : rows\.length \+ 1\}/],
+  ["column count metadata", /aria-colcount=\{columns\.length\}/],
+  ["header row index", /aria-rowindex=\{1\}/],
+  ["cell column index", /aria-colindex=\{columnIndex \+ 1\}/],
+  ["interactive row selected state", /aria-selected=\{hasInteractiveRows \? selected : undefined\}/],
+  ["interactive row tab stop", /tabIndex=\{hasInteractiveRows \? 0 : undefined\}/],
+  ["keyboard row handler", /handleRowKeyDown/],
+  ["enter key activation", /event\.key === "Enter"/],
+  ["space key activation", /event\.key === " "/],
+].filter(([, pattern]) => !pattern.test(dataTableSource));
+
+if (missingDataTableRequirements.length > 0) {
+  fail(
+    "Missing MacDataTable interactive grid accessibility invariants.",
+    missingDataTableRequirements.map(([label]) => label),
+  );
+}
+
+requireCssDeclarations(".hd-mac-data-table-row-interactive:focus-visible", [
+  ["focus outline reset", /outline\s*:\s*none\s*;/],
+  ["focus ring", /var\(--hd-mac-focus-ring\)/],
+]);
+
+const missingToolbarRequirements = [
+  ["toolbar role", /role=["']toolbar["']/],
+  ["optional aria label", /aria-label=\{ariaLabel\}/],
+  ["optional aria labelledby", /aria-labelledby=\{ariaLabelledBy\}/],
+  ["leading group role", /role=["']group["'][\s\S]*?aria-label=\{leadingLabel\}/],
+  ["children group role", /role=["']group["'][\s\S]*?aria-label=\{childrenLabel\}/],
+  ["trailing group role", /role=["']group["'][\s\S]*?aria-label=\{trailingLabel\}/],
+  ["drag region root", /data-tauri-drag-region/],
+  ["interactive groups no-drag", /data-tauri-no-drag-region/],
+  ["gallery toolbar accessible label", /<MacWindowToolbar[\s\S]*?ariaLabel=["']Library toolbar["']/],
+].filter(([, pattern]) => !pattern.test(windowToolbarSource) && !pattern.test(gallerySource));
+
+if (missingToolbarRequirements.length > 0) {
+  fail(
+    "Missing MacWindowToolbar accessibility and drag-region invariants.",
+    missingToolbarRequirements.map(([label]) => label),
+  );
+}
+
 const missingSymbolServiceRequirements = [
   ["transparent symbol padding trim", /trimTransparentSymbolPadding/],
   ["alpha threshold trim", /TRANSPARENT_ALPHA_THRESHOLD/],

package/src/components/MacBaseUIGallery.tsx

@@ -416,6 +416,7 @@ export function MacBaseUIGallery() {
           <MacAvatar.Fallback>HD</MacAvatar.Fallback>
         </MacAvatar.Root>
         <MacWindowToolbar
+          ariaLabel="Library toolbar"
           leading={<MacSegmentedControl options={choices} value={segment} onChange={setSegment} />}
           title="Library"
           trailing={<MacIconButton aria-label="Refresh">↻</MacIconButton>}

package/src/components/MacDataTable.tsx

@@ -17,6 +17,8 @@ export type MacDataTableProps<Row> = {
   columns: readonly MacDataTableColumn<Row>[];
   rows: readonly Row[];
   getRowKey: (row: Row, index: number) => React.Key;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
   isRowSelected?: (row: Row, index: number) => boolean;
   onRowClick?: (row: Row, index: number) => void;
   onRowDoubleClick?: (row: Row, index: number) => void;
@@ -53,6 +55,8 @@ export function MacDataTable<Row>({
   columns,
   rows,
   getRowKey,
+  ariaLabel,
+  ariaLabelledBy,
   isRowSelected,
   onRowClick,
   onRowDoubleClick,
@@ -67,6 +71,30 @@ export function MacDataTable<Row>({
 }: MacDataTableProps<Row>) {
   const gridTemplateColumns = columns.map((column) => column.width).join(" ");
   const hasInteractiveRows = Boolean(onRowClick || onRowDoubleClick);
+  const tableRole = hasInteractiveRows ? "grid" : "table";
+
+  const handleRowKeyDown = React.useCallback(
+    (event: React.KeyboardEvent, row: Row, index: number) => {
+      if (!hasInteractiveRows) {
+        return;
+      }
+
+      if (event.key === "Enter") {
+        event.preventDefault();
+        if (onRowDoubleClick) {
+          onRowDoubleClick(row, index);
+          return;
+        }
+        onRowClick?.(row, index);
+      }
+
+      if (event.key === " ") {
+        event.preventDefault();
+        onRowClick?.(row, index);
+      }
+    },
+    [hasInteractiveRows, onRowClick, onRowDoubleClick],
+  );
 
   return (
     <motion.div
@@ -74,12 +102,19 @@ export function MacDataTable<Row>({
       animate={{ opacity: 1 }}
       transition={tableTransition}
       className={joinClasses("hd-mac-data-table", bordered && "hd-mac-data-table-bordered", className)}
+      role={tableRole}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-busy={loading || undefined}
+      aria-rowcount={loading ? undefined : rows.length + 1}
+      aria-colcount={columns.length}
       style={style}
     >
       <motion.div
         layout
         className="hd-mac-data-table-header"
         role="row"
+        aria-rowindex={1}
         style={{ gridTemplateColumns }}
         transition={tableTransition}
       >
@@ -92,6 +127,7 @@ export function MacDataTable<Row>({
               column.headerClassName,
             )}
             role="columnheader"
+            aria-colindex={columns.indexOf(column) + 1}
             style={column.headerStyle}
           >
             {column.header}
@@ -139,10 +175,14 @@ export function MacDataTable<Row>({
               data-selected={selected || undefined}
               onClick={onRowClick ? () => onRowClick(row, index) : undefined}
               onDoubleClick={onRowDoubleClick ? () => onRowDoubleClick(row, index) : undefined}
+              onKeyDown={hasInteractiveRows ? (event) => handleRowKeyDown(event, row, index) : undefined}
               role="row"
+              aria-rowindex={index + 2}
+              aria-selected={hasInteractiveRows ? selected : undefined}
+              tabIndex={hasInteractiveRows ? 0 : undefined}
               style={{ gridTemplateColumns, ...rowStyle?.(row, index) }}
             >
-              {columns.map((column) => (
+              {columns.map((column, columnIndex) => (
                 <div
                   key={column.id}
                   className={joinClasses(
@@ -151,6 +191,7 @@ export function MacDataTable<Row>({
                     column.className,
                   )}
                   role="cell"
+                  aria-colindex={columnIndex + 1}
                   style={column.style}
                 >
                   {column.render(row, index)}

package/src/components/MacWindowToolbar.tsx

@@ -3,9 +3,14 @@ import { motion, type Transition } from "motion/react";
 
 export type MacWindowToolbarProps = {
   leading?: React.ReactNode;
+  leadingLabel?: string;
   title?: React.ReactNode;
   trailing?: React.ReactNode;
+  trailingLabel?: string;
   children?: React.ReactNode;
+  childrenLabel?: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
   className?: string;
   style?: React.CSSProperties;
 };
@@ -21,9 +26,14 @@ const toolbarTransition: Transition = {
 
 export function MacWindowToolbar({
   leading,
+  leadingLabel = "Primary toolbar controls",
   title,
   trailing,
+  trailingLabel = "Secondary toolbar controls",
   children,
+  childrenLabel = "Toolbar controls",
+  ariaLabel,
+  ariaLabelledBy,
   className,
   style,
 }: MacWindowToolbarProps) {
@@ -33,6 +43,9 @@ export function MacWindowToolbar({
       animate={{ opacity: 1, y: 0 }}
       transition={toolbarTransition}
       className={joinClasses("hd-mac-window-toolbar", className)}
+      role="toolbar"
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
       data-tauri-drag-region
       style={style}
     >
@@ -40,6 +53,8 @@ export function MacWindowToolbar({
         <motion.div
           layout
           className="hd-mac-window-toolbar-group"
+          role="group"
+          aria-label={leadingLabel}
           data-tauri-no-drag-region
           transition={toolbarTransition}
         >
@@ -50,6 +65,7 @@ export function MacWindowToolbar({
         <motion.div
           layout
           className="hd-mac-window-toolbar-title"
+          aria-hidden={typeof title === "string" ? undefined : true}
           data-tauri-drag-region
           transition={toolbarTransition}
         >
@@ -60,6 +76,8 @@ export function MacWindowToolbar({
         <motion.div
           layout
           className="hd-mac-window-toolbar-content"
+          role="group"
+          aria-label={childrenLabel}
           data-tauri-no-drag-region
           transition={toolbarTransition}
         >
@@ -70,6 +88,8 @@ export function MacWindowToolbar({
         <motion.div
           layout
           className="hd-mac-window-toolbar-group"
+          role="group"
+          aria-label={trailingLabel}
           data-tauri-no-drag-region
           transition={toolbarTransition}
         >

package/src/styles/macosBaseUi.css

@@ -1481,6 +1481,13 @@
   cursor: default;
 }
 
+.hd-mac-data-table-row-interactive:focus-visible {
+  outline: none;
+  box-shadow:
+    var(--hd-mac-focus-ring),
+    inset 0 0 0 1px color-mix(in srgb, var(--hd-mac-blue) 24%, transparent);
+}
+
 .hd-mac-data-table-row-interactive:hover {
   background: var(--hd-mac-fill-hover);
 }
@@ -1494,6 +1501,12 @@
   box-shadow: inset 3px 0 0 var(--hd-mac-blue);
 }
 
+.hd-mac-data-table-row[data-selected]:focus-visible {
+  box-shadow:
+    var(--hd-mac-focus-ring),
+    inset 3px 0 0 var(--hd-mac-blue);
+}
+
 .hd-mac-data-table-row[data-selected]:hover {
   background: color-mix(in srgb, var(--hd-mac-blue) 24%, transparent);
 }