react-morphcard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Łukasz Piera
+
+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,100 @@
+# react-morphcard
+
+A React hook for a card that grows into a full detail screen and shrinks back. The card's title, name and badge fly into the header, the content settles in, and Back plays a shorter version that ends on the card.
+
+<p align="center">
+  <img src="docs-site/public/videos/demo.gif" width="320" alt="A delivery card growing into its detail screen and shrinking back, at half speed">
+</p>
+
+**Docs and live demo: [morphcard.lucaspiera.com](https://morphcard.lucaspiera.com)**
+
+- One hook, `useMorph`. No components, no context provider, no dependencies besides React 18 or 19.
+- Works in any modern browser, in installed PWAs and in WebViews. It does not work in React Native, because it animates DOM elements with the Web Animations API.
+- The detail screen opens by `clip-path` from the card's rectangle, so nothing stretches and `position: fixed` children stay put.
+- Text that wraps differently on the card and in the header crossfades while it flies instead of scaling.
+- Closing (300 ms) is quicker than opening (400 ms) and ends on the card.
+- Closing during an open reverses the running animations from where they are.
+- No flight when the card is off screen or the destination is missing. The sheet fades instead.
+- Reduced motion is opacity only. Focus moves into the sheet and back to the card.
+- Safe to import during server rendering. The built file starts with `"use client"` for the Next.js App Router.
+
+## Install
+
+```bash
+pnpm add react-morphcard
+# or
+npm install react-morphcard
+```
+
+## Use
+
+```tsx
+import { useMorph } from "react-morphcard";
+
+export function Deliveries({ items }: { items: Delivery[] }) {
+  const morph = useMorph<Delivery>();
+  const d = morph.item;
+
+  return (
+    <>
+      <main ref={morph.backgroundRef}>
+        {items.map((item) => (
+          <article key={item.id} ref={morph.cardRef(item.id)} className="card">
+            <button
+              aria-label={`Open delivery ${item.id}`}
+              onClick={() => morph.open({ key: item.id, item })}
+            />
+            <h3 data-morph="title">{item.title}</h3>
+            <span data-morph="badge">{item.status}</span>
+          </article>
+        ))}
+      </main>
+      <div ref={morph.scrimRef} className="scrim" data-morph-close hidden />
+      <section ref={morph.sheetRef} className="sheet" role="dialog" aria-label="Delivery" hidden>
+        <button data-morph-close data-morph-focus>Back</button>
+        {d && (
+          <>
+            <h1 data-morph="title">{d.title}</h1>
+            <span data-morph="badge">{d.status}</span>
+            <div data-morph-stagger>{d.cargo}</div>
+          </>
+        )}
+      </section>
+    </>
+  );
+}
+```
+
+```css
+.sheet, .scrim { position: fixed; inset: 0; }
+[hidden] { display: none !important; }
+```
+
+Elements with the same `data-morph` key on the card and in the sheet fly between each other. `morph.item` is set before anything is measured and cleared only after the sheet has closed, so the sheet keeps its content for the whole flight back. If you keep the selected item in your own state, pass an update instead: `morph.open(event.currentTarget, () => setItem(item))`.
+
+See [Getting started](https://morphcard.lucaspiera.com/docs/getting-started) and the [API reference](https://morphcard.lucaspiera.com/docs/api).
+
+## Develop
+
+```bash
+pnpm install
+pnpm build          # dist/ with tsdown
+pnpm typecheck
+pnpm test           # builds dist, then unit tests (vitest), including an import of dist in plain Node
+pnpm test:e2e       # browser tests (Playwright, Chromium, desktop and phone)
+pnpm serve          # examples at http://127.0.0.1:3301/examples/index.html
+```
+
+The hook drives an internal engine in `src/morph.ts` that has no React in it. The package does not export it. `tsdown.fixtures.config.ts` builds it to `examples/dist/engine.js` for the plain JavaScript demo in `examples/` and for the engine tests.
+
+The browser tests run at 1280×800 and 390×844. The engine tests cover open and close end states, reversing mid-transition, rapid clicks, reduced motion, missing and off-screen targets, scroll restore, focus return and leftover DOM. The React tests use `tests/fixtures/react` in StrictMode. They check where the card lands, how long `item` lives, unmounting mid-animation, live option changes and keyed cards. `scripts/record.mjs` records a transition frame by frame and `scripts/make-videos.sh` builds the videos used by the docs.
+
+The docs site lives in `docs-site/` (Fumadocs, static export).
+
+## Publishing
+
+`package.json` is ready for npm (`exports`, types, `files`; `prepublishOnly` runs the typecheck, the build and the unit tests). Publishing is one command: `pnpm publish`.
+
+## License
+
+MIT © Łukasz Piera

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+
+//#region src/dom.d.ts
+type Scroller = HTMLElement | Window;
+//#endregion
+//#region src/types.d.ts
+type MorphState = "closed" | "opening" | "open" | "closing";
+/** Why a shared element (or the whole card) did not fly. */
+type SkipReason = "reduced-motion" | "no-card" | "card-offscreen" | "sheet-hidden" | "not-shared" | "missing-card-element" | "missing-sheet-element" | "sheet-element-offscreen";
+interface PairReport {
+  key: string;
+  /** scale: one copy flies and scales. crossfade: both copies fly and swap. skip: no flight. */
+  mode: "scale" | "crossfade" | "skip";
+  reason?: SkipReason;
+}
+/** What the last transition decided. Handy when a flight did not happen. */
+interface MorphPlan {
+  direction: "open" | "close";
+  /** morph: the surface grows from the card. fade: opacity only, no flight. */
+  choreography: "morph" | "fade";
+  reason?: SkipReason;
+  reduced: boolean;
+  backgroundScaled: boolean;
+  pairs: PairReport[];
+}
+interface MorphTiming {
+  /** Milliseconds. Closing is shorter: the user already knows where they are going back to. */
+  duration: {
+    open: number;
+    close: number;
+  };
+  /** surface: clip-path, shared flights and background. content: stagger and dock. */
+  easing: {
+    surface: string;
+    content: string;
+  };
+  /** Delay between staggered content blocks, in milliseconds. */
+  stagger: number;
+  /** Scale of the background while the sheet is open. false keeps it still. */
+  backgroundScale: number | false;
+  /** "system" follows prefers-reduced-motion; true or false forces it. */
+  reducedMotion: "system" | boolean;
+  /** Multiplies every duration and delay. 4 plays everything four times slower. */
+  timeScale: number;
+  closeOnEscape: boolean;
+  /** Put the list's scroll position back before measuring the card on close. */
+  restoreScroll: boolean;
+}
+interface MorphOptions extends Partial<Omit<MorphTiming, "duration" | "easing">> {
+  /** The detail surface. Positioned (fixed or absolute) and hidden while closed. */
+  sheet: HTMLElement;
+  /** What recedes behind the sheet. Must not contain the sheet. */
+  background?: HTMLElement | null;
+  /** Dims the background. Shown while the sheet is visible. */
+  scrim?: HTMLElement | null;
+  duration?: Partial<MorphTiming["duration"]>;
+  easing?: Partial<MorphTiming["easing"]>;
+  /** Keys allowed to fly. Default: every data-morph key. Others fade in place. */
+  shared?: string[];
+  /** Corner radius of the card in px. Default: the card's computed border radius. */
+  radius?: number;
+  /** Scroll container of the list. Default: nearest scrolling ancestor of the card, or the window. */
+  scroller?: Scroller;
+  /** Fill the sheet for this card. Runs before anything is measured; may return a promise. */
+  prepare?: (card: HTMLElement | null) => void | Promise<void>;
+  onStateChange?: (state: MorphState, card: HTMLElement | null) => void;
+  /**
+   * Where a close without `to` lands. Receives the card the sheet opened
+   * from. Lets a caller follow a card that was re-rendered while the sheet
+   * was open. Default: that same card.
+   */
+  resolveCard?: (card: HTMLElement | null) => HTMLElement | null;
+}
+interface CloseOptions {
+  /**
+   * The element to return to. Pass a new element when the list re-rendered,
+   * or null when there is nothing to return to (the sheet then fades out).
+   */
+  to?: HTMLElement | null;
+}
+interface Morph {
+  /** Opens the sheet from `card`. null opens without a flight (deep link). Resolves true once open. */
+  open(card?: HTMLElement | null): Promise<boolean>;
+  /** Closes back to the card. Resolves true once closed. */
+  close(options?: CloseOptions): Promise<boolean>;
+  readonly state: MorphState;
+  /** The card the sheet belongs to, or null. */
+  readonly card: HTMLElement | null;
+  /** The decision taken by the latest transition. */
+  readonly plan: MorphPlan | null;
+  /** Changes timing and callbacks for the next transition. */
+  setOptions(options: Partial<Omit<MorphOptions, "sheet" | "background" | "scrim">>): void;
+  /** Stops any transition, restores the page and removes listeners. */
+  destroy(): void;
+}
+//#endregion
+//#region src/use-morph.d.ts
+type UseMorphOptions = Omit<MorphOptions, "sheet" | "background" | "scrim" | "prepare" | "resolveCard">;
+/** Identifies a card registered with `cardRef(key)`. */
+type MorphKey = string | number;
+/** The object form of `open`'s first argument. */
+interface MorphTarget<T> {
+  /** A card registered with `cardRef(key)`. */
+  key?: MorphKey;
+  /** A card element. Used instead of the registered one when both are given. */
+  card?: HTMLElement | null;
+  /** Becomes `item` inside flushSync, before anything is measured. */
+  item?: T;
+}
+interface UseMorphCloseOptions {
+  /**
+   * The card to return to: an element, a key registered with `cardRef`, or
+   * null to fade out. Default: the card it opened from, or the element now
+   * registered under the same key if the list re-rendered.
+   */
+  to?: HTMLElement | MorphKey | null;
+}
+/** Read-only view of the engine, for debugging a transition. */
+type MorphInstance = Pick<Morph, "state" | "card" | "plan">;
+interface UseMorph<T = unknown> {
+  sheetRef: (el: HTMLElement | null) => void;
+  backgroundRef: (el: HTMLElement | null) => void;
+  scrimRef: (el: HTMLElement | null) => void;
+  /** A stable callback ref for each key. `open(key)` finds the card through it. */
+  cardRef: (key: MorphKey) => (el: HTMLElement | null) => void;
+  state: MorphState;
+  /**
+   * The item passed to the latest `open`. Set before measuring and cleared
+   * once the sheet has finished closing, so the sheet never empties mid-flight.
+   */
+  item: T | null;
+  /**
+   * Opens the sheet from a card element, a key registered with `cardRef`, or
+   * `{ key, card, item }`. null opens without a flight (deep link). `update`
+   * runs inside flushSync before anything is measured.
+   */
+  open(target: HTMLElement | MorphKey | MorphTarget<T> | null, update?: () => void): Promise<boolean>;
+  close(options?: UseMorphCloseOptions): Promise<boolean>;
+  /** The engine once the sheet is mounted, for reading `plan` and `card`. */
+  readonly instance: MorphInstance | null;
+}
+export declare function useMorph<T = unknown>(options?: UseMorphOptions): UseMorph<T>;
+//#endregion
+//#region src/timing.d.ts
+export declare const defaults: MorphTiming;
+/**
+ * Fractions of the open or close duration. With the defaults (400 / 300 ms):
+ * content enters at 130 ms, the card copy of a crossfading text is gone by
+ * 160 ms, and on close the big heading hands over to the card text by 90 ms.
+ */
+export declare const choreography: {
+  readonly open: {
+    readonly contentDelay: 0.325;
+    readonly content: 0.65;
+    readonly copyOut: 0.4;
+    readonly targetIn: 0.5;
+    readonly restOut: 0.35;
+    readonly borderOut: 0.2;
+    readonly lateIn: 0.4;
+    readonly dockDelay: 0.4;
+    readonly dock: 0.75;
+  };
+  readonly close: {
+    readonly copyIn: 0.37;
+    readonly targetOut: 0.3;
+    readonly restDelay: 0.5;
+    readonly rest: 0.5;
+    readonly contentOut: 0.37;
+    readonly dock: 0.6;
+  };
+  /** Opacity only, in ms: the empty surface covers the page before any text appears. */
+  readonly fade: {
+    readonly surface: 120;
+    readonly contentDelay: 100;
+    readonly content: 140;
+    readonly closeContent: 100;
+    readonly closeSurfaceDelay: 100;
+    readonly closeSurface: 120;
+  };
+};
+//#endregion
+export type { MorphInstance, MorphKey, MorphPlan, MorphState, MorphTarget, MorphTiming, PairReport, SkipReason, UseMorph, UseMorphCloseOptions, UseMorphOptions };
+//# sourceMappingURL=index.d.ts.map