@patternmode/aperto 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Howells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @patternmode/aperto
+
+Opinionated, styled thumbnail-to-expanded media transitions for React.
+
+```tsx
+import { Aperto, type ApertoMediaItem } from "@patternmode/aperto";
+import "@patternmode/aperto/styles.css";
+
+const media: ApertoMediaItem[] = [
+  {
+    type: "image",
+    src: "/images/studio-large.jpg",
+    thumbnailSrc: "/images/studio-thumb.jpg",
+    alt: "Ceramic vessels on a linen-covered studio table",
+    title: "Studio table",
+  },
+  {
+    type: "video",
+    src: "/videos/room-study.mp4",
+    thumbnailSrc: "/images/room-study-thumb.jpg",
+    poster: "/images/room-study-poster.jpg",
+    alt: "A slow interior pan across a quiet room",
+    title: "Room study",
+  },
+];
+
+export function MediaGroupExample() {
+  return (
+    <Aperto.Group media={media} dismissible={{ threshold: 120, velocity: 600 }}>
+      {media.map((item, index) => (
+        <Aperto.Thumbnail key={item.id ?? item.src} index={index} />
+      ))}
+    </Aperto.Group>
+  );
+}
+```
+
+## Install
+
+```bash
+pnpm add @patternmode/aperto
+```
+
+React and React DOM are peer dependencies.
+
+## Drag dismissal
+
+Expanded media can be dismissed by dragging past a distance or velocity
+threshold. Pass `dismissible={false}` to disable drag dismissal, or pass
+`{ threshold, velocity }` to tune the gesture.
+
+## Primitive transitions
+
+Use the Aperto Primitive API for custom shared-element dialogs that are not
+Media Transitions. `Aperto.Primitive.Content` is centered by default; pass
+`placement="none"` when the panel should own its own positioning.

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import * as react from 'react';
+import { ImgHTMLAttributes, ReactNode, VideoHTMLAttributes, 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
+ *
+ * Shared element transitions with physics-based drag dismissal.
+ * Built on Radix Dialog + Motion.
+ *
+ * Inspired by Cambio (https://github.com/raphaelsalaja/cambio)
+ * by Raphael Salaja. Reimplemented for Radix UI primitives.
+ */
+
+interface BaseMediaItem {
+    description?: string;
+    height?: number;
+    id?: string;
+    src: string;
+    thumbnailSrc?: string;
+    title?: string;
+    width?: number;
+}
+interface ApertoImageItem extends BaseMediaItem {
+    alt: string;
+    type: "image";
+}
+interface ApertoVideoItem extends BaseMediaItem {
+    alt?: string;
+    poster?: string;
+    thumbnailSrc: string;
+    type: "video";
+}
+type ApertoMediaItem = ApertoImageItem | ApertoVideoItem;
+type RenderImage = (props: ImgHTMLAttributes<HTMLImageElement> & {
+    item: ApertoImageItem;
+    variant: "expanded" | "thumbnail";
+}) => ReactNode;
+type RenderVideo = (props: VideoHTMLAttributes<HTMLVideoElement> & {
+    item: ApertoVideoItem;
+    variant: "expanded" | "thumbnail";
+}) => ReactNode;
+interface ApertoClassNames {
+    closeButton?: string;
+    content?: string;
+    counter?: string;
+    nextButton?: string;
+    overlay?: string;
+    previousButton?: string;
+    thumbnail?: string;
+}
+/** Named motion preset */
+type MotionPresetName = "snappy" | "smooth" | "bouncy" | "reduced";
+/** Expanded media navigation transition preset */
+type NavigationMotionPresetName = "float" | "glide" | "snap";
+/** Per-component motion variant overrides */
+interface MotionVariants {
+    backdrop?: MotionPresetName;
+    content?: MotionPresetName;
+    trigger?: MotionPresetName;
+}
+/** Motion prop: a single preset name, per-component variants, or nothing */
+type MotionProp = MotionPresetName | MotionVariants;
+/** Spring config for drag physics */
+interface DragSpringConfig {
+    damping: number;
+    restDelta: number;
+    stiffness: number;
+}
+/** Resolved preset with transition timing and drag physics */
+interface MotionPreset {
+    drag: DragSpringConfig;
+    transition: Transition;
+}
+/** Dismissal behaviour config */
+interface DismissibleConfig {
+    /** Distance in px to trigger dismissal (default: 100) */
+    threshold?: number;
+    /** Velocity in px/s to trigger dismissal (default: 500) */
+    velocity?: number;
+}
+
+interface ApertoProps {
+    classNames?: ApertoClassNames;
+    /** Whether dragging can dismiss the expanded media (default: true). */
+    dismissible?: boolean | DismissibleConfig;
+    media: ApertoMediaItem;
+    renderImage?: RenderImage;
+    renderVideo?: RenderVideo;
+}
+interface ApertoGroupProps {
+    children: ReactNode;
+    classNames?: ApertoClassNames;
+    /** Whether dragging can dismiss the expanded media (default: true). */
+    dismissible?: boolean | DismissibleConfig;
+    index?: number;
+    initialIndex?: number;
+    media: ApertoMediaItem[];
+    /** Motion preset for open/close transitions */
+    motion?: MotionPresetName | MotionVariants;
+    navigationMotion?: NavigationMotionPresetName;
+    onIndexChange?: (index: number) => void;
+    renderImage?: RenderImage;
+    renderVideo?: RenderVideo;
+}
+interface ApertoThumbnailProps {
+    children?: ReactNode;
+    className?: string;
+    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 function ApertoThumbnail({ children, className, index, }: ApertoThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
+declare const ApertoClose: react.ForwardRefExoticComponent<Omit<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+
+interface ApertoContentProps extends Omit<ComponentPropsWithoutRef<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. */
+    placement?: "center" | "none";
+    /** Internal shared layout ID override for grouped media. */
+    sharedLayoutId?: string | false;
+}
+declare const ApertoContent: react.ForwardRefExoticComponent<ApertoContentProps & react.RefAttributes<HTMLDivElement>>;
+
+declare const ApertoDescription: react.ForwardRefExoticComponent<Omit<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
+
+interface ApertoOverlayProps {
+    className?: string;
+    /** Internal flag used to fade the overlay during measured close transitions. */
+    fadeOut?: boolean;
+    style?: React.CSSProperties;
+}
+declare const ApertoOverlay: react.ForwardRefExoticComponent<ApertoOverlayProps & react.RefAttributes<HTMLDivElement>>;
+
+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;
+
+interface ApertoRootProps extends Omit<ComponentPropsWithoutRef<typeof Dialog.Root>, "open" | "onOpenChange"> {
+    children: ReactNode;
+    /** Whether dragging can dismiss the content (default: true) */
+    dismissible?: boolean | DismissibleConfig;
+    /** Layout ID for shared element transition (auto-generated if omitted) */
+    layoutId?: string;
+    /** Motion preset or per-component variants */
+    motion?: MotionPresetName | MotionVariants;
+    /** Controlled open state */
+    open?: boolean;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** 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 ApertoTitle: react.ForwardRefExoticComponent<Omit<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
+
+interface ApertoTriggerProps extends ComponentPropsWithoutRef<typeof Dialog.Trigger> {
+    /** Internal flag used by grouped thumbnails to raise only the active trigger. */
+    active?: boolean;
+    /** Override motion preset for this trigger */
+    motion?: MotionPresetName;
+    /** Internal shared layout ID override for grouped thumbnails. */
+    sharedLayoutId?: string | false;
+}
+declare const ApertoTrigger: react.ForwardRefExoticComponent<ApertoTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * 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.
+ */
+declare const PRESETS: Record<MotionPresetName, MotionPreset>;
+type ComponentType = "trigger" | "content" | "backdrop";
+/**
+ * Three-level motion resolution:
+ * 1. Component-level override (highest)
+ * 2. Per-component variant from Root
+ * 3. Global preset from Root (lowest)
+ *
+ * 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;
+
+/** 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>>;
+};
+/** Primary media-first component namespace. */
+declare const Aperto: typeof ApertoSingle & {
+    Group: typeof ApertoGroup;
+    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>>;
+    };
+    Thumbnail: typeof ApertoThumbnail;
+};
+
+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 };