mac-human-design 0.1.5 → 0.1.6

package/README.md

@@ -3,6 +3,7 @@
 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:
@@ -19,11 +20,12 @@ A reusable shared library for Tauri macOS apps. It includes:
 From the consumer app:
 
 ```bash
-npm i mac-human-design @base-ui/react react react-dom
+npm i mac-human-design @base-ui/react motion react react-dom
 ```
 
-`@base-ui/react`, `react`, and `react-dom` are peer dependencies. Install
-`@tauri-apps/api` too when using the SF Symbols helpers or Tauri integration.
+`@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.
 
 Consumer apps should also include the macOS Base UI stylesheet once near their
 app root:
@@ -54,7 +56,7 @@ fn main() {
 
 ```ts
 import { useState } from "react";
-import { MacButton, MacSegmentedControl, MacSelect } from "mac-human-design";
+import { MacButton, MacMotionProvider, MacSegmentedControl, MacSelect } from "mac-human-design";
 import { SystemSymbolImage } from "mac-human-design/symbols";
 import "mac-human-design/styles/macos-base-ui.css";
 
@@ -62,7 +64,7 @@ export function Demo() {
   const [tab, setTab] = useState<"files" | "settings">("files");
 
   return (
-    <div>
+    <MacMotionProvider>
       <SystemSymbolImage symbolName="folder" sizePx={18} fallback="▢" />
       <MacSegmentedControl
         options={[
@@ -78,7 +80,7 @@ export function Demo() {
           <MacSelect.Value placeholder="Choose" />
         </MacSelect.Trigger>
       </MacSelect.Root>
-    </div>
+    </MacMotionProvider>
   );
 }
 ```
@@ -109,7 +111,7 @@ The following components are now in the shared library and can be imported by an
   `MacHelpButton`, `MacCheckbox`, `MacCheckboxGroup`, `MacCollapsible`,
   `MacCombobox`, `MacContextMenu`, `MacDialog`, `MacDrawer`, `MacField`,
   `MacFieldset`, `MacForm`, `MacInput`, `MacTextField`, `MacSearchField`,
-  `MacMenu`, `MacMenubar`, `MacMeter`, `MacNavigationMenu`,
+  `MacMenu`, `MacMenubar`, `MacMeter`, `MacMotionProvider`, `MacNavigationMenu`,
   `MacNumberField`, `MacOTPField`, `MacPopover`,
   `MacPreviewCard`, `MacProgress`, `MacRadio`, `MacRadioGroup`,
   `MacScrollArea`, `MacSelect`, `MacSeparator`, `MacSlider`, `MacSwitch`,

package/changelog.md

@@ -2,6 +2,28 @@
 
 This file tracks changes between published npm versions of `mac-human-design`.
 
+## 0.1.6
+
+### Added
+
+- Added Motion for React as the default animation layer for the macOS Base UI
+  wrappers.
+- Added `MacMotionProvider`, which applies the shared Motion transition config
+  and respects the user's reduced-motion preference by default.
+- Added default macOS motion presets for controls, fields, selection controls,
+  panels, popups, dialogs, drawers, indicators, feedback meters, and utility
+  surfaces.
+- Added verifier coverage for Motion peer/dev dependencies, provider export,
+  reduced-motion config, default transitions, and safe module-scope
+  `motion.create()` usage.
+
+### Changed
+
+- Bumped the package to `0.1.6`.
+- Added `motion` as a required peer dependency and development dependency.
+- Updated the gallery to render inside `MacMotionProvider` so animation defaults
+  are exercised by the shipped example app.
+
 ## 0.1.5
 
 ### Changed

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

@@ -7,8 +7,10 @@
 import "mac-human-design/styles/macos-base-ui.css";
 ```
 
-Consumer apps install `@base-ui/react`, `react`, and `react-dom` as peer
-dependencies alongside this package.
+Consumer apps install `@base-ui/react`, `motion`, `react`, and `react-dom` as
+peer dependencies alongside this package. Motion animations are enabled by
+default through the macOS wrappers and respect the user's reduced-motion
+preference through `MacMotionProvider`.
 
 ## Component Families
 
@@ -70,6 +72,7 @@ render UI.
 | 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` |
@@ -104,6 +107,8 @@ The gate typechecks the library and verifies:
 - macOS design features are present: system font stack, dark mode, reduced motion,
   keyboard focus rings, accent tokens, styled `hd-mac` classes, and typography
   constraints,
+- Motion integration is present: dependency declarations, `MacMotionProvider`,
+  reduced-motion config, default transitions, and module-scope `motion.create()`,
 - the visual gallery can be bundled for production from the shipped source,
 - old UI-foundation references have not returned.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mac-human-design",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Reusable macOS-oriented UI primitives and SF Symbols bridge for Tauri apps.",
   "type": "module",
   "main": "src/index.ts",
@@ -49,6 +49,7 @@
   "peerDependencies": {
     "@base-ui/react": "^1.5.0",
     "@tauri-apps/api": "^2",
+    "motion": "^12.40.0",
     "react": ">=18",
     "react-dom": ">=18"
   },
@@ -63,6 +64,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
+    "motion": "^12.40.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^6.0.3",

package/scripts/verify-base-ui-coverage.mjs

@@ -47,7 +47,10 @@ function getBaseUiFamilies() {
 
 function getMacExports(source) {
   return new Set(
-    Array.from(source.matchAll(/^export const (Mac[A-Za-z0-9]+)\b/gm), (match) => match[1]),
+    Array.from(
+      source.matchAll(/^export (?:const|function) (Mac[A-Za-z0-9]+)\b/gm),
+      (match) => match[1],
+    ),
   );
 }
 
@@ -157,6 +160,7 @@ if (missingDocsRows.length > 0) {
 }
 
 const requiredVariants = [
+  "MacMotionProvider",
   "MacPrimaryButton",
   "MacSecondaryButton",
   "MacDestructiveButton",
@@ -269,5 +273,5 @@ if (process.exitCode) {
 }
 
 console.log(
-  `Verified ${families.length} @base-ui/react component families, namespace parts, ${requiredVariants.length} native variants, ${requiredNestedVariants.length} nested variants, ${wrapperClasses.size} wrapper classes, gallery coverage, and no Base Web references.`,
+  `Verified ${families.length} @base-ui/react component families, namespace parts, ${requiredVariants.length} provider/variant exports, ${requiredNestedVariants.length} nested variants, ${wrapperClasses.size} wrapper classes, gallery coverage, and no Base Web references.`,
 );

package/scripts/verify-macos-design.mjs

@@ -4,6 +4,8 @@ import { fileURLToPath } from "node:url";
 
 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 wrapperPath = path.join(repoRoot, "src", "components", "MacBaseUI.tsx");
 
 function readText(filePath) {
   return fs.readFileSync(filePath, "utf8");
@@ -39,6 +41,8 @@ const sources = new Map(
   sourceFiles.map((relativeFile) => [relativeFile, readText(path.join(repoRoot, relativeFile))]),
 );
 const stylesSource = readText(stylesPath);
+const packageJson = JSON.parse(readText(packageJsonPath));
+const wrapperSource = readText(wrapperPath);
 
 const requiredStyleFeatures = [
   ["system font stack", /-apple-system,\s*BlinkMacSystemFont/],
@@ -56,6 +60,44 @@ if (missingFeatures.length > 0) {
   fail("Missing required macOS styling features.", missingFeatures);
 }
 
+const missingMotionDependencies = [];
+if (!packageJson.peerDependencies?.motion) {
+  missingMotionDependencies.push("peerDependencies.motion");
+}
+if (!packageJson.devDependencies?.motion) {
+  missingMotionDependencies.push("devDependencies.motion");
+}
+
+if (missingMotionDependencies.length > 0) {
+  fail("Missing required Motion dependency declarations.", missingMotionDependencies);
+}
+
+const requiredMotionFeatures = [
+  ["MotionConfig import", /import\s+\{[\s\S]*MotionConfig[\s\S]*\}\s+from\s+["']motion\/react["']/],
+  ["motion import", /import\s+\{[\s\S]*\bmotion\b[\s\S]*\}\s+from\s+["']motion\/react["']/],
+  ["MacMotionProvider export", /export function MacMotionProvider\b/],
+  ["MotionProps wrapper typing", /React\.ComponentPropsWithoutRef<C> & MotionProps/],
+  ["reduced motion user config", /reducedMotion\s*=\s*["']user["']/],
+  ["motion.create wrapper", /motion\.create\(BaseWrapped as AnyComponent\)/],
+  ["default Motion transition", /const macDefaultTransition:\s*Transition/],
+];
+
+const missingMotionFeatures = requiredMotionFeatures
+  .filter(([, pattern]) => !pattern.test(wrapperSource))
+  .map(([label]) => label);
+
+if (missingMotionFeatures.length > 0) {
+  fail("Missing required Motion integration features.", missingMotionFeatures);
+}
+
+const motionCreateMatches = Array.from(wrapperSource.matchAll(/motion\.create\(/g));
+const allowedMotionCreatePattern = /^\s*const MotionPart = motion\.create\(BaseWrapped as AnyComponent\);$/m;
+if (motionCreateMatches.length !== 1 || !allowedMotionCreatePattern.test(wrapperSource)) {
+  fail("motion.create() must be called exactly once in the module-level macPart wrapper setup.", [
+    "src/components/MacBaseUI.tsx",
+  ]);
+}
+
 const negativeLetterSpacing = [];
 const viewportScaledFonts = [];
 

package/src/components/MacBaseUI.tsx

@@ -1,4 +1,12 @@
 import * as React from "react";
+import {
+  MotionConfig,
+  motion,
+  type MotionConfigProps,
+  type MotionProps,
+  type TargetAndTransition,
+  type Transition,
+} from "motion/react";
 import { Accordion as BaseAccordion } from "@base-ui/react/accordion";
 import { AlertDialog as BaseAlertDialog } from "@base-ui/react/alert-dialog";
 import { Autocomplete as BaseAutocomplete } from "@base-ui/react/autocomplete";
@@ -42,6 +50,47 @@ import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
 
 type AnyComponent = React.ComponentType<any>;
 type ClassNameProp = string | ((state: any) => string | undefined) | undefined;
+type MacAnimatedComponent<C extends AnyComponent> = React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<React.ComponentPropsWithoutRef<C> & MotionProps> & React.RefAttributes<unknown>
+>;
+type MotionDefaults = Pick<
+  MotionProps,
+  "initial" | "animate" | "exit" | "layout" | "whileFocus" | "whileHover" | "whileTap"
+> & {
+  transition?: Transition;
+};
+
+const macDefaultTransition: Transition = {
+  default: { type: "spring", stiffness: 520, damping: 38, mass: 0.8 },
+  opacity: { duration: 0.12, ease: "easeOut" },
+};
+
+const macFastTransition: Transition = {
+  default: { type: "spring", stiffness: 680, damping: 44, mass: 0.7 },
+  opacity: { duration: 0.09, ease: "easeOut" },
+};
+
+const macSoftTransition: Transition = {
+  default: { type: "spring", stiffness: 420, damping: 34, mass: 0.9 },
+  opacity: { duration: 0.14, ease: "easeOut" },
+};
+
+export type MacMotionProviderProps = React.PropsWithChildren<{
+  reducedMotion?: MotionConfigProps["reducedMotion"];
+  transition?: MotionConfigProps["transition"];
+}>;
+
+export function MacMotionProvider({
+  children,
+  reducedMotion = "user",
+  transition = macDefaultTransition,
+}: MacMotionProviderProps) {
+  return (
+    <MotionConfig reducedMotion={reducedMotion} transition={transition}>
+      {children}
+    </MotionConfig>
+  );
+}
 
 function joinClasses(...classes: Array<string | undefined | false>) {
   return classes.filter(Boolean).join(" ");
@@ -54,8 +103,153 @@ function mergeClassName(macClassName: string, className: ClassNameProp): ClassNa
   return joinClasses(macClassName, className);
 }
 
+function includesAny(value: string, tokens: string[]) {
+  return tokens.some((token) => value.includes(token));
+}
+
+function isDisabled(props: Record<string, unknown>) {
+  return Boolean(props.disabled || props["data-disabled"] || props["aria-disabled"]);
+}
+
+function interactiveControlDefaults(macClassName: string, props: Record<string, unknown>): MotionDefaults {
+  if (isDisabled(props)) {
+    return {};
+  }
+
+  return {
+    whileHover: { y: -0.5, scale: 1.012 },
+    whileTap: { y: 1, scale: 0.985 },
+    transition: macFastTransition,
+  };
+}
+
+function fadeScaleDefaults(
+  initial: TargetAndTransition,
+  animate: TargetAndTransition = { opacity: 1, scale: 1, y: 0, x: 0 },
+  transition: Transition = macSoftTransition,
+): MotionDefaults {
+  return {
+    initial,
+    animate,
+    exit: initial,
+    transition,
+  };
+}
+
+function getMotionDefaults(macClassName: string, props: Record<string, unknown>): MotionDefaults {
+  if (
+    includesAny(macClassName, [
+      "hd-mac-button",
+      "hd-mac-select-trigger",
+      "hd-mac-toggle",
+      "hd-mac-toolbar-button",
+      "hd-mac-stepper-button",
+      "hd-mac-disclosure-trigger",
+    ])
+  ) {
+    return interactiveControlDefaults(macClassName, props);
+  }
+
+  if (macClassName.includes("hd-mac-input")) {
+    return {
+      whileFocus: { scale: 1.004 },
+      transition: macFastTransition,
+    };
+  }
+
+  if (includesAny(macClassName, ["hd-mac-checkbox-indicator", "hd-mac-radio-indicator"])) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.72 }, { opacity: 1, scale: 1 });
+  }
+
+  if (macClassName.includes("hd-mac-switch-thumb") || macClassName.includes("hd-mac-slider-thumb")) {
+    return {
+      layout: true,
+      whileTap: { scale: 0.92 },
+      transition: macDefaultTransition,
+    };
+  }
+
+  if (includesAny(macClassName, ["hd-mac-progress-indicator", "hd-mac-meter-indicator", "hd-mac-slider-indicator"])) {
+    return {
+      layout: true,
+      transition: macSoftTransition,
+    };
+  }
+
+  if (includesAny(macClassName, ["hd-mac-popup", "hd-mac-popover", "hd-mac-preview-card"])) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.97, y: 4 });
+  }
+
+  if (macClassName.includes("hd-mac-tooltip")) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.96 }, { opacity: 1, scale: 1 }, macFastTransition);
+  }
+
+  if (macClassName.includes("hd-mac-backdrop")) {
+    return fadeScaleDefaults({ opacity: 0 }, { opacity: 1 }, { duration: 0.16, ease: "easeOut" });
+  }
+
+  if (macClassName.includes("hd-mac-sheet-dialog")) {
+    return fadeScaleDefaults({ opacity: 0, y: -18, scale: 0.985 });
+  }
+
+  if (macClassName.includes("hd-mac-alert-dialog")) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.94, y: 8 }, { opacity: 1, scale: 1, y: 0 });
+  }
+
+  if (macClassName.includes("hd-mac-dialog")) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.965, y: 10 });
+  }
+
+  if (macClassName.includes("hd-mac-sidebar-drawer")) {
+    return fadeScaleDefaults({ opacity: 0, x: -22 }, { opacity: 1, x: 0 });
+  }
+
+  if (macClassName.includes("hd-mac-drawer")) {
+    return fadeScaleDefaults({ opacity: 0, y: 18 }, { opacity: 1, y: 0 });
+  }
+
+  if (includesAny(macClassName, ["hd-mac-accordion-panel", "hd-mac-collapsible-panel", "hd-mac-tab-panel"])) {
+    return {
+      initial: { opacity: 0, y: 4 },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: 4 },
+      layout: true,
+      transition: macSoftTransition,
+    };
+  }
+
+  if (includesAny(macClassName, ["hd-mac-menu-item", "hd-mac-menu-row"])) {
+    return fadeScaleDefaults({ opacity: 0, x: -3 }, { opacity: 1, x: 0 }, macFastTransition);
+  }
+
+  if (includesAny(macClassName, ["hd-mac-menu-item-indicator", "hd-mac-control-icon"])) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.76 }, { opacity: 1, scale: 1 }, macFastTransition);
+  }
+
+  if (includesAny(macClassName, ["hd-mac-avatar", "hd-mac-avatar-image", "hd-mac-avatar-fallback"])) {
+    return fadeScaleDefaults({ opacity: 0, scale: 0.92 });
+  }
+
+  if (includesAny(macClassName, ["hd-mac-error-text", "hd-mac-help-text", "hd-mac-status-text", "hd-mac-validity"])) {
+    return fadeScaleDefaults({ opacity: 0, y: -3 }, { opacity: 1, y: 0 }, macFastTransition);
+  }
+
+  if (includesAny(macClassName, ["hd-mac-separator", "hd-mac-fieldset", "hd-mac-form"])) {
+    return {
+      initial: { opacity: 0 },
+      animate: { opacity: 1 },
+      transition: { duration: 0.12, ease: "easeOut" },
+    };
+  }
+
+  return {
+    layout: includesAny(macClassName, ["hd-mac-toggle-group", "hd-mac-tabs", "hd-mac-navigation-menu"]),
+    transition: macDefaultTransition,
+  };
+}
+
 function macPart<C extends AnyComponent>(Component: C, macClassName: string) {
-  const Wrapped = React.forwardRef<unknown, React.ComponentPropsWithoutRef<C>>((props, ref) => {
+  const BaseWrapped = React.forwardRef<unknown, React.ComponentPropsWithoutRef<C>>((props, ref) => {
     const TypedComponent = Component as AnyComponent;
     const { className, ...rest } = props as Record<string, unknown>;
     return React.createElement(TypedComponent, {
@@ -65,8 +259,21 @@ function macPart<C extends AnyComponent>(Component: C, macClassName: string) {
     });
   });
 
+  BaseWrapped.displayName = `MacBase${Component.displayName ?? Component.name ?? "BaseUIPart"}`;
+
+  const MotionPart = motion.create(BaseWrapped as AnyComponent);
+  const Wrapped = React.forwardRef<unknown, React.ComponentPropsWithoutRef<C>>((props, ref) => {
+    const rest = props as Record<string, unknown>;
+    const motionDefaults = getMotionDefaults(macClassName, rest);
+    return React.createElement(MotionPart as AnyComponent, {
+      ...motionDefaults,
+      ...rest,
+      ref,
+    });
+  });
+
   Wrapped.displayName = `Mac${Component.displayName ?? Component.name ?? "BaseUIPart"}`;
-  return Wrapped as unknown as C;
+  return Wrapped as unknown as MacAnimatedComponent<C>;
 }
 
 function macProvider<C extends AnyComponent>(Component: C) {

package/src/components/MacBaseUIGallery.tsx

@@ -24,6 +24,7 @@ import {
   MacMenu,
   MacMenubar,
   MacMeter,
+  MacMotionProvider,
   MacNavigationMenu,
   MacNumberField,
   MacOTPField,
@@ -76,7 +77,8 @@ export function MacBaseUIGallery() {
   return (
     <MacCSPProvider>
       <MacDirectionProvider direction="ltr">
-        <div className="hd-mac hd-mac-gallery">
+        <MacMotionProvider>
+          <div className="hd-mac hd-mac-gallery">
       <GallerySection title="Buttons">
         <MacButton>Default</MacButton>
         <MacPrimaryButton>Continue</MacPrimaryButton>
@@ -421,7 +423,8 @@ export function MacBaseUIGallery() {
           <MacToast.Viewport />
         </MacToast.Provider>
       </GallerySection>
-        </div>
+          </div>
+        </MacMotionProvider>
       </MacDirectionProvider>
     </MacCSPProvider>
   );