@patternmode/aperto 0.1.4 → 0.2.1

package/README.md

@@ -35,6 +35,40 @@ export function MediaGroupExample() {
 }
 ```
 
+## Optimized images
+
+Aperto's built-in image renderer uses a plain `img` so the package stays
+framework agnostic. If your app uses Next.js, pass `renderImage` and return
+your own `next/image` `Image` component:
+
+```tsx
+import Image from "next/image";
+
+const leadSrc = media[0]?.src;
+
+<Aperto.Group
+  media={media}
+  renderImage={({ alt, item, src, variant }) => {
+    const isLeadImage = variant === "expanded" || item.src === leadSrc;
+
+    return (
+      <Image
+        alt={alt ?? ""}
+        fetchPriority={isLeadImage ? "high" : "auto"}
+        fill
+        loading={isLeadImage || variant === "thumbnail" ? "eager" : "lazy"}
+        sizes={variant === "thumbnail" ? "(max-width: 640px) 50vw, 320px" : "90vw"}
+        src={String(src)}
+      />
+    );
+  }}
+>
+  {media.map((item, index) => (
+    <Aperto.Thumbnail key={item.id ?? item.src} index={index} />
+  ))}
+</Aperto.Group>;
+```
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 import * as react from 'react';
-import { ImgHTMLAttributes, ReactNode, VideoHTMLAttributes, ComponentPropsWithoutRef } from 'react';
+import { ImgHTMLAttributes, ReactNode, VideoHTMLAttributes, ComponentPropsWithRef, Ref, CSSProperties, ComponentPropsWithoutRef } from 'react';
 import * as Dialog from '@radix-ui/react-dialog';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Transition } from 'motion/react';
 
 /**
- * @patternmode/aperto
+ * Package: @patternmode/aperto
  *
  * Shared element transitions with physics-based drag dismissal.
  * Built on Radix Dialog + Motion.
@@ -23,22 +22,42 @@ interface BaseMediaItem {
     title?: string;
     width?: number;
 }
+/** Image media item rendered as a thumbnail and expanded image. */
 interface ApertoImageItem extends BaseMediaItem {
+    /** Required alt text for the image renderer. */
     alt: string;
     type: "image";
 }
+/** Video media item rendered with a thumbnail and expanded player. */
 interface ApertoVideoItem extends BaseMediaItem {
     alt?: string;
+    /** Optional captions track URL for the expanded video. */
     captionsSrc?: string;
     poster?: string;
+    /** Required thumbnail image shown before expansion. */
     thumbnailSrc: string;
     type: "video";
 }
+/** Media item supported by Aperto's grouped media API. */
 type ApertoMediaItem = ApertoImageItem | ApertoVideoItem;
+/**
+ * Custom image renderer for image media.
+ *
+ * Aperto's default renderer is a plain `img` so the package stays framework
+ * agnostic. Next.js consumers should return their own `next/image` `Image`
+ * component here, using `variant` to choose thumbnail vs expanded sizing,
+ * loading, or fetch priority behavior.
+ */
 type RenderImage = (props: ImgHTMLAttributes<HTMLImageElement> & {
     item: ApertoImageItem;
     variant: "expanded" | "thumbnail";
 }) => ReactNode;
+/**
+ * Custom video renderer for video media.
+ *
+ * Use this to replace the default `video` element while preserving the supplied
+ * accessibility, poster, and control props.
+ */
 type RenderVideo = (props: VideoHTMLAttributes<HTMLVideoElement> & {
     item: ApertoVideoItem;
     variant: "expanded" | "thumbnail";
@@ -77,50 +96,98 @@ interface MotionPreset {
 }
 /** Dismissal behaviour config */
 interface DismissibleConfig {
-    /** Distance in px to trigger dismissal (default: 100) */
+    /**
+     * Distance in px to trigger dismissal.
+     *
+     * Default `100`.
+     */
     threshold?: number;
-    /** Velocity in px/s to trigger dismissal (default: 500) */
+    /**
+     * Velocity in px/s to trigger dismissal.
+     *
+     * Default `500`.
+     */
     velocity?: number;
 }
 
 interface ApertoProps {
     classNames?: ApertoClassNames;
-    /** Whether dragging can dismiss the expanded media (default: true). */
+    /**
+     * Whether dragging can dismiss the expanded media.
+     *
+     * Default `true`.
+     */
     dismissible?: boolean | DismissibleConfig;
+    /** Single media item rendered by the standalone Aperto component. */
     media: ApertoMediaItem;
+    /**
+     * Overrides Aperto's plain `img` renderer for image media.
+     *
+     * Use this to render framework-specific image components such as Next.js
+     * `Image` while keeping Aperto itself framework agnostic.
+     */
     renderImage?: RenderImage;
     renderVideo?: RenderVideo;
 }
 interface ApertoGroupProps {
     children: ReactNode;
     classNames?: ApertoClassNames;
-    /** Whether dragging can dismiss the expanded media (default: true). */
+    /**
+     * Whether dragging can dismiss the expanded media.
+     *
+     * Default `true`.
+     */
     dismissible?: boolean | DismissibleConfig;
+    /** Controlled active media index. Pair with `onIndexChange`. */
     index?: number;
+    /**
+     * Initial active media index for uncontrolled groups.
+     *
+     * Default `0`.
+     */
     initialIndex?: number;
     media: ApertoMediaItem[];
-    /** Motion preset for open/close transitions */
+    /**
+     * Motion preset for open/close transitions, or per-part motion overrides.
+     *
+     * Default `"smooth"`.
+     */
     motion?: MotionPresetName | MotionVariants;
+    /**
+     * Motion preset for next/previous navigation inside expanded media.
+     *
+     * Default `"glide"`.
+     */
     navigationMotion?: NavigationMotionPresetName;
+    /** Called whenever grouped media navigation changes the active index. */
     onIndexChange?: (index: number) => void;
+    /**
+     * Overrides Aperto's plain `img` renderer for image media.
+     *
+     * Use this to render framework-specific image components such as Next.js
+     * `Image` while keeping Aperto itself framework agnostic.
+     */
     renderImage?: RenderImage;
     renderVideo?: RenderVideo;
 }
 interface ApertoThumbnailProps {
+    /** Optional custom thumbnail content; defaults to media thumbnail rendering. */
     children?: ReactNode;
     className?: string;
+    /** Index into the parent group's `media` array. */
     index: number;
 }
 
-declare function ApertoGroup({ children, classNames, dismissible, index: controlledIndex, initialIndex, media, motion: motionProp, navigationMotion, onIndexChange, renderImage, renderVideo, }: ApertoGroupProps): react_jsx_runtime.JSX.Element;
-
-declare function ApertoSingle({ classNames, dismissible, media, renderImage, renderVideo, }: ApertoProps): react_jsx_runtime.JSX.Element;
+declare const ApertoGroup: ({ children, classNames, dismissible, index, initialIndex, media, motion: motionProp, navigationMotion, onIndexChange, renderImage, renderVideo, }: ApertoGroupProps) => react.JSX.Element;
 
-declare function ApertoThumbnail({ children, className, index, }: ApertoThumbnailProps): react_jsx_runtime.JSX.Element | null;
+declare const ApertoThumbnail: ({ children, className, index }: ApertoThumbnailProps) => react.JSX.Element | null;
 
-declare const ApertoClose: react.ForwardRefExoticComponent<Omit<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+declare const ApertoClose: {
+    ({ children, ref, ...props }: ComponentPropsWithRef<typeof Dialog.Close>): react.JSX.Element;
+    displayName: string;
+};
 
-interface ApertoContentProps extends Omit<ComponentPropsWithoutRef<typeof Dialog.Content>, "asChild" | "forceMount"> {
+interface ApertoContentProps extends Omit<ComponentPropsWithRef<typeof Dialog.Content>, "asChild" | "forceMount"> {
     /** Motion preset override for this content panel, independent of the root preset. */
     motion?: MotionPresetName;
     /** Built-in positioning strategy. Use "none" for custom primitive compositions. */
@@ -128,24 +195,34 @@ interface ApertoContentProps extends Omit<ComponentPropsWithoutRef<typeof Dialog
     /** Internal shared layout ID override for grouped media. */
     sharedLayoutId?: string | false;
 }
-declare const ApertoContent: react.ForwardRefExoticComponent<ApertoContentProps & react.RefAttributes<HTMLDivElement>>;
+declare const ApertoContent: {
+    ({ children, className, motion: motionOverride, placement, ref, sharedLayoutId, style, ...props }: ApertoContentProps): react.JSX.Element;
+    displayName: string;
+};
 
-declare const ApertoDescription: react.ForwardRefExoticComponent<Omit<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
+declare const ApertoDescription: {
+    ({ ref, ...props }: ComponentPropsWithRef<typeof Dialog.Description>): react.JSX.Element;
+    displayName: string;
+};
 
 interface ApertoOverlayProps {
     className?: string;
     /** Internal flag used to fade the overlay during measured close transitions. */
     fadeOut?: boolean;
-    style?: React.CSSProperties;
+    ref?: Ref<HTMLDivElement>;
+    style?: CSSProperties;
 }
-declare const ApertoOverlay: react.ForwardRefExoticComponent<ApertoOverlayProps & react.RefAttributes<HTMLDivElement>>;
+declare const ApertoOverlay: {
+    ({ className, fadeOut, ref, style }: ApertoOverlayProps): react.JSX.Element;
+    displayName: string;
+};
 
 interface ApertoPortalProps {
     children: ReactNode;
     /** Container element for the portal (default: document.body) */
     container?: HTMLElement;
 }
-declare function ApertoPortal({ children, container }: ApertoPortalProps): react_jsx_runtime.JSX.Element;
+declare const ApertoPortal: ({ children, container }: ApertoPortalProps) => react.JSX.Element;
 
 interface ApertoRootProps extends Omit<ComponentPropsWithoutRef<typeof Dialog.Root>, "open" | "onOpenChange"> {
     children: ReactNode;
@@ -162,11 +239,14 @@ interface ApertoRootProps extends Omit<ComponentPropsWithoutRef<typeof Dialog.Ro
     /** Force reduced motion regardless of system preference */
     reduceMotion?: boolean;
 }
-declare function ApertoRoot({ children, dismissible, layoutId: layoutIdProp, motion: motionProp, open: controlledOpen, onOpenChange: controlledOnOpenChange, reduceMotion: reduceMotionProp, ...dialogProps }: ApertoRootProps): react_jsx_runtime.JSX.Element;
+declare const ApertoRoot: ({ children, dismissible, layoutId: layoutIdProp, motion: motionProp, open: controlledOpen, onOpenChange: controlledOnOpenChange, reduceMotion: reduceMotionProp, ...dialogProps }: ApertoRootProps) => react.JSX.Element;
 
-declare const ApertoTitle: react.ForwardRefExoticComponent<Omit<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
+declare const ApertoTitle: {
+    ({ ref, ...props }: ComponentPropsWithRef<typeof Dialog.Title>): react.JSX.Element;
+    displayName: string;
+};
 
-interface ApertoTriggerProps extends ComponentPropsWithoutRef<typeof Dialog.Trigger> {
+interface ApertoTriggerProps extends ComponentPropsWithRef<typeof Dialog.Trigger> {
     /** Internal flag used by grouped thumbnails to raise only the active trigger. */
     active?: boolean;
     /** Override motion preset for this trigger */
@@ -174,14 +254,17 @@ interface ApertoTriggerProps extends ComponentPropsWithoutRef<typeof Dialog.Trig
     /** Internal shared layout ID override for grouped thumbnails. */
     sharedLayoutId?: string | false;
 }
-declare const ApertoTrigger: react.ForwardRefExoticComponent<ApertoTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const ApertoTrigger: {
+    ({ active, children, motion: motionOverride, ref, sharedLayoutId, ...props }: ApertoTriggerProps): react.JSX.Element;
+    displayName: string;
+};
 
 /**
  * Motion presets — each bundles transition timing AND drag physics
  * so "snappy" feels snappy everywhere: open, close, and drag.
  *
- * Curves and springs are local copies of the Howells motion tokens so the
- * published package has no private workspace runtime dependencies.
+ * Curves and springs come from the shared @howells/motion tokens so motion
+ * feel stays consistent across the catalog.
  */
 declare const PRESETS: Record<MotionPresetName, MotionPreset>;
 type ComponentType = "trigger" | "content" | "backdrop";
@@ -193,33 +276,69 @@ type ComponentType = "trigger" | "content" | "backdrop";
  *
  * If `prefers-reduced-motion` is active, always returns "reduced".
  */
-declare function resolvePreset(componentType: ComponentType, componentMotion: MotionPresetName | undefined, globalPreset: MotionPresetName, variants: MotionVariants | undefined, reduceMotion: boolean): MotionPreset;
+declare const resolvePreset: (componentType: ComponentType, componentMotion: MotionPresetName | undefined, globalPreset: MotionPresetName, variants: MotionVariants | undefined, reduceMotion: boolean) => MotionPreset;
 
 /** Lower-level compound component namespace for advanced composition. */
 declare const ApertoPrimitive: {
-    Close: react.ForwardRefExoticComponent<Omit<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
-    Content: react.ForwardRefExoticComponent<ApertoContentProps & react.RefAttributes<HTMLDivElement>>;
-    Description: react.ForwardRefExoticComponent<Omit<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
-    Overlay: react.ForwardRefExoticComponent<ApertoOverlayProps & react.RefAttributes<HTMLDivElement>>;
-    Portal: typeof ApertoPortal;
-    Root: typeof ApertoRoot;
-    Title: react.ForwardRefExoticComponent<Omit<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
-    Trigger: react.ForwardRefExoticComponent<ApertoTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+    Close: {
+        ({ children, ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>>): react.JSX.Element;
+        displayName: string;
+    };
+    Content: {
+        ({ children, className, motion: motionOverride, placement, ref, sharedLayoutId, style, ...props }: ApertoContentProps): react.JSX.Element;
+        displayName: string;
+    };
+    Description: {
+        ({ ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>>): react.JSX.Element;
+        displayName: string;
+    };
+    Overlay: {
+        ({ className, fadeOut, ref, style }: ApertoOverlayProps): react.JSX.Element;
+        displayName: string;
+    };
+    Portal: ({ children, container }: ApertoPortalProps) => react.JSX.Element;
+    Root: ({ children, dismissible, layoutId: layoutIdProp, motion: motionProp, open: controlledOpen, onOpenChange: controlledOnOpenChange, reduceMotion: reduceMotionProp, ...dialogProps }: ApertoRootProps) => react.JSX.Element;
+    Title: {
+        ({ ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>>>): react.JSX.Element;
+        displayName: string;
+    };
+    Trigger: {
+        ({ active, children, motion: motionOverride, ref, sharedLayoutId, ...props }: ApertoTriggerProps): react.JSX.Element;
+        displayName: string;
+    };
 };
 /** Primary media-first component namespace. */
-declare const Aperto: typeof ApertoSingle & {
-    Group: typeof ApertoGroup;
+declare const Aperto: (({ classNames, dismissible, media, renderImage, renderVideo, }: ApertoProps) => react.JSX.Element) & {
+    Group: ({ children, classNames, dismissible, index, initialIndex, media, motion: motionProp, navigationMotion, onIndexChange, renderImage, renderVideo, }: ApertoGroupProps) => react.JSX.Element;
     Primitive: {
-        Close: react.ForwardRefExoticComponent<Omit<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
-        Content: react.ForwardRefExoticComponent<ApertoContentProps & react.RefAttributes<HTMLDivElement>>;
-        Description: react.ForwardRefExoticComponent<Omit<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
-        Overlay: react.ForwardRefExoticComponent<ApertoOverlayProps & react.RefAttributes<HTMLDivElement>>;
-        Portal: typeof ApertoPortal;
-        Root: typeof ApertoRoot;
-        Title: react.ForwardRefExoticComponent<Omit<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
-        Trigger: react.ForwardRefExoticComponent<ApertoTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+        Close: {
+            ({ children, ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>>): react.JSX.Element;
+            displayName: string;
+        };
+        Content: {
+            ({ children, className, motion: motionOverride, placement, ref, sharedLayoutId, style, ...props }: ApertoContentProps): react.JSX.Element;
+            displayName: string;
+        };
+        Description: {
+            ({ ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>>): react.JSX.Element;
+            displayName: string;
+        };
+        Overlay: {
+            ({ className, fadeOut, ref, style }: ApertoOverlayProps): react.JSX.Element;
+            displayName: string;
+        };
+        Portal: ({ children, container }: ApertoPortalProps) => react.JSX.Element;
+        Root: ({ children, dismissible, layoutId: layoutIdProp, motion: motionProp, open: controlledOpen, onOpenChange: controlledOnOpenChange, reduceMotion: reduceMotionProp, ...dialogProps }: ApertoRootProps) => react.JSX.Element;
+        Title: {
+            ({ ref, ...props }: react.ComponentPropsWithRef<react.ForwardRefExoticComponent<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>>>): react.JSX.Element;
+            displayName: string;
+        };
+        Trigger: {
+            ({ active, children, motion: motionOverride, ref, sharedLayoutId, ...props }: ApertoTriggerProps): react.JSX.Element;
+            displayName: string;
+        };
     };
-    Thumbnail: typeof ApertoThumbnail;
+    Thumbnail: ({ children, className, index }: ApertoThumbnailProps) => react.JSX.Element | null;
 };
 
 export { Aperto, type ApertoClassNames, ApertoClose, ApertoContent, type ApertoContentProps, ApertoDescription, ApertoGroup, type ApertoGroupProps, type ApertoImageItem, type ApertoMediaItem, ApertoOverlay, type ApertoOverlayProps, ApertoPortal, type ApertoPortalProps, ApertoPrimitive, type ApertoProps, ApertoRoot, type ApertoRootProps, ApertoThumbnail, type ApertoThumbnailProps, ApertoTitle, ApertoTrigger, type ApertoTriggerProps, type ApertoVideoItem, type DismissibleConfig, type DragSpringConfig, type MotionPreset, type MotionPresetName, type MotionProp, type MotionVariants, type NavigationMotionPresetName, PRESETS, type RenderImage, type RenderVideo, resolvePreset };