mac-human-design 0.1.30-preview.3 → 0.1.30-preview.5

package/README.md

@@ -5,9 +5,11 @@ A reusable shared library for Tauri macOS apps. It includes:
 - macOS-styled wrappers for every public `@base-ui/react` component family.
 - Default-on Motion-powered animations that respect reduced-motion settings.
 - `MacSegmentedControl` and macOS design tokens/classes.
-- A reusable SF Symbols fetch layer with React hooks/components.
-- A Rust/Tauri plugin crate that exposes a native command:
-  `system_symbol_png_data_url`.
+- Native Tauri helpers for macOS context menus and AppKit dialogs.
+- Reusable SF Symbols and AppKit folder-icon fetch layers with React
+  hooks/components.
+- A Rust/Tauri plugin crate that exposes native commands for SF Symbols, folder
+  icons, and native dialogs.
 
 ## Structure
 
@@ -24,8 +26,8 @@ npm i mac-human-design @base-ui/react motion react react-dom
 ```
 
 `@base-ui/react`, `motion`, `react`, and `react-dom` are peer dependencies.
-Install `@tauri-apps/api` too when using the SF Symbols helpers or Tauri
-integration.
+Install `@tauri-apps/api` too when using the SF Symbols helpers, AppKit folder
+icons, native context menus, native dialogs, or other Tauri integration.
 
 Consumer apps should also include the macOS Base UI stylesheet once near their
 app root:
@@ -52,6 +54,15 @@ fn main() {
 }
 ```
 
+Native context menus use Tauri's built-in menu popup API. Consumer app
+capabilities need `core:menu:allow-popup`, `core:menu:default`, or
+`core:default`.
+
+The shared native plugin default permission enables SF Symbol PNGs, AppKit
+folder-icon PNGs, and native dialogs. If your app opts into individual plugin
+permissions instead of `human-design-system-symbols:default`, include
+`human-design-system-symbols:allow-folder-icon-png-data-url`.
+
 ## Usage (React)
 
 ```ts
@@ -60,12 +71,13 @@ import {
   MacButton,
   MacDataTable,
   MacMotionProvider,
+  MacNativeContextMenu,
   MacSegmentedControl,
   MacSelect,
   MacWindowToolbar,
-  SymbolIconButton,
+  MacSymbolButton,
 } from "mac-human-design";
-import { SystemSymbolImage } from "mac-human-design/symbols";
+import { FolderIconImage, SystemSymbolImage } from "mac-human-design/symbols";
 import "mac-human-design/styles/macos-base-ui.css";
 
 export function Demo() {
@@ -86,7 +98,7 @@ export function Demo() {
           />
         }
         trailing={
-          <SymbolIconButton
+          <MacSymbolButton
             label="Refresh"
             symbolName="arrow.clockwise"
             fallback="↻"
@@ -94,6 +106,7 @@ export function Demo() {
           />
         }
       />
+      <FolderIconImage sizePx={24} ariaLabel="Folder" />
       <SystemSymbolImage symbolName="folder" sizePx={18} fallback="▢" />
       <MacDataTable
         ariaLabel="Demo files"
@@ -104,7 +117,18 @@ export function Demo() {
         rows={[{ name: "Documents", kind: "Folder" }]}
         getRowKey={(row) => row.name}
       />
-      <MacButton data-variant="primary">Continue</MacButton>
+      <MacButton role="primary">Continue</MacButton>
+      <MacNativeContextMenu.Trigger
+        menu={[
+          { id: "rename", text: "Rename", action: () => {} },
+          { id: "duplicate", text: "Duplicate", nativeIcon: "Folder", action: () => {} },
+          { type: "separator" },
+          { type: "checkbox", id: "details", text: "Show Details", checked: true },
+        ]}
+        tabIndex={0}
+      >
+        Right-click for native actions
+      </MacNativeContextMenu.Trigger>
       <MacSelect.Root items={[{ label: "Files", value: "files" }]}>
         <MacSelect.Trigger>
           <MacSelect.Value placeholder="Choose" />
@@ -120,8 +144,23 @@ export function Demo() {
 ```bash
 npm run check
 npm run dev:gallery -- --port 5177
+npm run dev:gallery:tauri
+```
+
+## Native gallery app (dev-only)
+
+For native surface checks, run the gallery in a Tauri shell:
+
+```bash
+npm run dev:gallery:tauri
 ```
 
+The gallery is loaded from the existing `examples/macos-base-ui-gallery` frontend and opened in a Tauri shell using:
+
+`examples/macos-base-ui-gallery-tauri/src-tauri/tauri.conf.json`
+
+This is a dev-only workflow and does not affect the package public exports.
+
 ## Why it works cross-platform
 
 The React components stay browser-safe. The optional Tauri plugin is the only
@@ -136,27 +175,29 @@ The following components are now in the shared library and can be imported by an
 
 - `AppWindowShell`
 - `MacAccordion`, `MacAlertDialog`, `MacAutocomplete`, `MacAvatar`,
-  `MacButton`, `MacPrimaryButton`, `MacSecondaryButton`,
-  `MacDestructiveButton`, `MacPlainButton`, `MacIconButton`,
-  `MacHelpButton`, `MacCheckbox`, `MacCheckboxGroup`, `MacCollapsible`,
+  `MacButton`, `MacHelpButton`, `MacCheckbox`, `MacCheckboxGroup`, `MacCollapsible`,
   `MacCombobox`, `MacContextMenu`, `MacDialog`, `MacDrawer`, `MacField`,
   `MacFieldset`, `MacForm`, `MacInput`, `MacTextField`, `MacSearchField`,
   `MacMenu`, `MacMenubar`, `MacMeter`, `MacMotionProvider`, `MacNavigationMenu`,
   `MacNumberField`, `MacOTPField`, `MacPopover`,
   `MacPreviewCard`, `MacProgress`, `MacRadio`, `MacRadioGroup`,
   `MacScrollArea`, `MacSelect`, `MacSeparator`, `MacSlider`, `MacSwitch`,
-  `MacTabs`, `MacToast`, `MacToggle`, `MacToolbarToggle`,
-  `MacToggleGroup`, `MacSegmentedToggleGroup`,
-  `MacSeparatedSegmentedToggleGroup`, `MacToolbar`, `MacTooltip`
+  `MacTabs`, `MacToast`, `MacToggle`, `MacToolbarToggle`, `MacToggleGroup`,
+  `MacToolbar`, `MacTooltip`
 - `MacDataTable`, a Finder-style grid/table primitive with loading, empty,
   selected, keyboard, and interactive-row states
-- `MacSegmentedControl`, a compact macOS segmented control wrapper with
-  accessible labels and full-width support
+- `MacSegmentedControl`, the standard macOS segmented control wrapper with
+  single/multiple selection plus `regular`, `pill`, and `glass` variants
 - `MacWindowToolbar`, a Motion-backed Tauri window toolbar with drag-region
   and no-drag control group handling
+- `MacNativeContextMenu`, a native Tauri context-menu bridge with
+  `showMacNativeContextMenu()`, native menu icons such as `nativeIcon:
+"Folder"`, and a right-click/keyboard trigger component
+- `FolderIconImage`, `useFolderIcon()`, and `getFolderIconDataUrl()` for
+  rendering AppKit/Finder-style folder icons in React UI
 - `StatusMessage`
-- `SymbolIconButton`, a centered SF Symbols icon button with fallback glyphs,
-  loading state, tooltips, and pass-through styling hooks
+- `MacSymbolButton`, a centered SF Symbols icon button with fallback glyphs,
+  `role` and `variant` props, loading state, tooltips, and pass-through styling hooks
 - `ViewDragRegion`
 - `isDraggableAreaTarget` utility
 
@@ -164,13 +205,15 @@ Example import:
 
 ```ts
 import {
-  AppWindowShell,
-  MacDataTable,
-  MacSegmentedControl,
-  MacWindowToolbar,
-  StatusMessage,
-  SymbolIconButton,
-  ViewDragRegion,
-  isDraggableAreaTarget,
+    AppWindowShell,
+    MacDataTable,
+    MacNativeContextMenu,
+    MacSegmentedControl,
+    MacWindowToolbar,
+    FolderIconImage,
+    StatusMessage,
+    MacSymbolButton,
+    ViewDragRegion,
+    isDraggableAreaTarget,
 } from "mac-human-design"
 ```

package/changelog.md

@@ -2,6 +2,95 @@
 
 This file tracks changes between published npm versions of `mac-human-design`.
 
+## 0.1.30-preview.5
+
+### Added
+
+- Added `FolderIconImage`, `useFolderIcon()`, and `getFolderIconDataUrl()` so
+  Tauri macOS apps can render AppKit/Finder-style generic folder icons or
+  folder-path-specific icons through the shared native plugin.
+- Added `nativeIcon` support to `MacNativeContextMenu` action, checkbox, and
+  submenu items, including Tauri's native `Folder`, `FolderBurnable`, and
+  `FolderSmart` menu icons.
+
+### Changed
+
+- Extended the shared Tauri plugin default permission set with
+  `allow-folder-icon-png-data-url`.
+- Bumped the package to `0.1.30-preview.5`.
+
+## 0.1.30-preview.4
+
+### Added
+
+- Added `MacNativeContextMenu`, a Tauri-backed native context-menu bridge with
+  `showMacNativeContextMenu()` and `MacNativeContextMenu.Trigger`, supporting
+  action items, checkbox items, separators, predefined native items, and
+  submenus while remaining browser-safe outside a Tauri runtime.
+- Added `MacNativeDialog`, a Tauri-backed native macOS dialog bridge with
+  `showMacNativeDialog()` and `MacNativeDialog.Trigger`, plus a browser-safe
+  fallback for the web gallery.
+
+### Changed
+
+- Updated the gallery dialog section to use native Tauri/AppKit dialogs by
+  default and keep React-rendered dialog content only for the sidebar drawer
+  exception.
+- Added native context-menu gallery and README coverage, including the required
+  Tauri menu popup permission note for consumer apps.
+- Fixed Tauri plugin invocations to use the `plugin:human-design-system-symbols|`
+  command prefix for native dialogs and SF Symbols.
+- Narrowed the npm package file list so preview publishes include example source
+  files without packing generated Tauri build output.
+- Bumped the package to `0.1.30-preview.4` under the `preview` dist-tag.
+
+## 0.1.30-preview.3
+
+### Added
+
+- Added `MacSymbolButton` as the exported, symbol-aware toolbar icon component,
+  replacing the previous `SymbolIconButton` name while preserving SF Symbol image
+  loading, fallback glyph, tooltip, and loading-state behavior.
+- Added `MacSegmentedControl` selection and style variants for regular
+  single-choice controls, multiple-choice controls, pill controls, and
+  Tahoe-style glass controls.
+
+### Changed
+
+- Improved macOS control animation defaults so segmented-control segments no
+  longer enlarge on hover while keeping subtle press feedback.
+- Improved gallery segmented-control examples so multiple selection, pill, and
+  Tahoe-style glass variants demonstrate their controlled selection behavior.
+- Added a dedicated Tauri drag strip to the dev gallery so the native gallery
+  window can be moved without making component demos noninteractive.
+- Wired the dev gallery drag strip to Tauri's `startDragging` API and enabled
+  the required dev-shell permission.
+- Pinned the dev gallery drag strip to the top of the viewport so the native
+  window remains draggable after the gallery scrolls.
+- Consolidated push-button styling into `MacButton` with `role` and `variant`
+  props, removed the separate role-specific button exports, and added matching
+  `role`/`variant` support to `MacSymbolButton`.
+- Tuned `MacButton` role styling against native AppKit and SwiftUI references:
+  default and cancel buttons stay low-prominence, primary remains the filled
+  default action, destructive buttons use red low-prominence text by default,
+  regular text buttons use native 32 px sizing, regular symbol buttons use
+  native 28 px icon-button geometry, and every role now has gallery coverage for
+  regular and glass button variants.
+- Refined the shared button finish with a flatter, more vibrant macOS-style
+  treatment and hid the symbol glyph while `MacSymbolButton` displays its
+  loading spinner.
+- Updated public exports, gallery examples, README coverage, docs, and
+  verification scripts to use the new `MacSymbolButton` naming consistently.
+- Updated symbol icon button alignment styling for tooltip-trigger integration so
+  the symbol layer and loading overlay remain correctly centered.
+- Bumped the package to `0.1.30-preview.3` under the `preview` dist-tag.
+- Removed `MacIconButton` from the public wrapper set and replaced icon-only
+  uses with `MacButton` plus the `hd-mac-icon-button` styling (preserving the
+  existing `MacSymbolButton` API and behavior).
+- Removed the separate segmented toggle-group variants from the public wrapper
+  checklist and gallery so segmented controls are represented through
+  `MacSegmentedControl` instead of multiple overlapping component names.
+
 ## 0.1.30-preview.2
 
 ### Added

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

@@ -63,44 +63,50 @@ render UI.
 
 ## Native Variants
 
-| Native role                 | Export                             |
-| --------------------------- | ---------------------------------- |
-| Default push button         | `MacButton`                        |
-| Blue default button         | `MacPrimaryButton`                 |
-| Secondary push button       | `MacSecondaryButton`               |
-| Destructive button          | `MacDestructiveButton`             |
-| Borderless button           | `MacPlainButton`                   |
-| Icon button                 | `MacIconButton`                    |
-| Help button                 | `MacHelpButton`                    |
-| Motion defaults provider    | `MacMotionProvider`                |
-| Text field                  | `MacTextField` / `MacInput`        |
-| Search field                | `MacSearchField`                   |
-| Pop-up button               | `MacSelect.PopUpButtonTrigger`     |
-| Pull-down button            | `MacSelect.PullDownButtonTrigger`  |
-| Segmented control           | `MacSegmentedToggleGroup`          |
-| Separated segmented control | `MacSeparatedSegmentedToggleGroup` |
-| Toolbar toggle              | `MacToolbarToggle`                 |
-| Toolbar icon button         | `MacToolbar.IconButton`            |
-| Window sheet                | `MacDialog.SheetPopup`             |
-| Sidebar drawer              | `MacDrawer.SidebarPopup`           |
+| Native role              | Export                             |
+| ------------------------ | ---------------------------------- |
+| Default push button      | `MacButton role="default"`         |
+| Primary push button      | `MacButton role="primary"`         |
+| Secondary push button    | `MacButton role="secondary"`       |
+| Cancel button            | `MacButton role="cancel"`          |
+| Destructive button       | `MacButton role="destructive"`     |
+| Liquid glass button      | `MacButton variant="glass"`        |
+| Icon button              | `MacButton` + `hd-mac-icon-button` |
+| Help button              | `MacHelpButton`                    |
+| Motion defaults provider | `MacMotionProvider`                |
+| Text field               | `MacTextField` / `MacInput`        |
+| Search field             | `MacSearchField`                   |
+| Pop-up button            | `MacSelect.PopUpButtonTrigger`     |
+| Pull-down button         | `MacSelect.PullDownButtonTrigger`  |
+| Segmented control        | `MacSegmentedControl`              |
+| Toolbar toggle           | `MacToolbarToggle`                 |
+| Toolbar icon button      | `MacToolbar.IconButton`            |
+| Native AppKit dialog     | `MacNativeDialog`                  |
+| Native context menu      | `MacNativeContextMenu`             |
+| Native folder icon       | `FolderIconImage`                  |
+| Legacy React 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, arrow/Home/End row focus navigation, selected row state, and layered hover/selection styling. |
-| Tauri window toolbar              | `MacWindowToolbar`    | Provides a labelled `toolbar` landmark, labelled leading/content/trailing control groups, a root drag region, no-drag regions around interactive controls, and stable wrapped-control sizing for dense icon toolbars.                                  |
-| 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`.                   |
+| 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, arrow/Home/End row focus navigation, selected row state, and layered hover/selection styling.                                               |
+| Tauri window toolbar              | `MacWindowToolbar`     | Provides a labelled `toolbar` landmark, labelled leading/content/trailing control groups, a root drag region, no-drag regions around interactive controls, and stable wrapped-control sizing for dense icon toolbars.                                                                                |
+| Native Tauri context menu         | `MacNativeContextMenu` | Provides `showMacNativeContextMenu()` and `MacNativeContextMenu.Trigger` so macOS Tauri apps can present native OS context menus through Tauri's built-in menu popup API, including native menu icons such as `Folder`, while keeping the package browser-safe for gallery and documentation builds. |
+| Native Tauri dialog bridge        | `MacNativeDialog`      | Provides `showMacNativeDialog()` and `MacNativeDialog.Trigger` so Tauri apps can present native macOS `NSAlert` dialogs through the library's Tauri plugin while retaining a browser-safe fallback for the developer gallery.                                                                        |
+| AppKit folder icon bridge         | `FolderIconImage`      | Provides `getFolderIconDataUrl()`, `useFolderIcon()`, and `FolderIconImage` so macOS Tauri apps can render generic Finder-style folder icons or path-specific folder icons through `NSWorkspace`, with browser-safe fallback rendering outside Tauri.                                                |
+| Segmented control                 | `MacSegmentedControl`  | Provides the standard macOS segmented control API with single/multiple selection, regular joined segments, pill segments, Tahoe-style glass segments, accessible labels, full-width layout support, and class/style pass-through.                                                                    |
+| Centered SF Symbols icon button   | `MacSymbolButton`      | Renders through `MacButton` and `hd-mac-icon-button`, supports `role` and `variant`, 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
+origins. `MacSymbolButton` keeps the SF Symbol and loading spinner in the same
 grid cell, renders hover/focus/loading feedback as a centered state layer under
 the glyph, centers generated symbol masks, trims transparent symbol padding in
 the native symbol service, applies per-symbol optical offsets for asymmetric SF
@@ -140,4 +146,5 @@ Run the visual gallery with:
 
 ```bash
 npm run dev:gallery -- --port 5177
+npm run dev:gallery:tauri
 ```

package/examples/macos-base-ui-gallery/index.html

@@ -1,12 +1,12 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>human-design macOS Base UI gallery</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>human-design macOS Base UI gallery</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
 </html>

package/examples/macos-base-ui-gallery/src/main.tsx

@@ -5,9 +5,9 @@ import "../../../src/styles/macosBaseUi.css"
 import "../../../src/styles/macosTauri.css"
 
 createRoot(document.getElementById("root") as HTMLElement).render(
-  <StrictMode>
-    <AppWindowShell>
-      <MacBaseUIGallery />
-    </AppWindowShell>
-  </StrictMode>,
+    <StrictMode>
+        <AppWindowShell>
+            <MacBaseUIGallery />
+        </AppWindowShell>
+    </StrictMode>,
 )