@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/motion/LayoutChangeSnapshot.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file LayoutChangeSnapshot.tsx
+ * @input A value and a callback
+ * @output Exports LayoutChangeSnapshot: calls the callback in the commit that
+ *   changes the value, before React changes the DOM
+ * @position Motion foundation, internal to core; how a component that takes
+ *   an `animatedLayout` handle measures each change before it lands
+ *   (`spec:AST-105` FR1), whatever caused it: a click, an owner-set prop, or
+ *   a group's value
+ *
+ * `getSnapshotBeforeUpdate` runs in the commit, after render and before any
+ * DOM mutation of that commit, so the layout it reads is the old one. Unlike
+ * a read during render, it runs only for a render that commits, once (a
+ * StrictMode replay or a render React throws away never reaches it), and it
+ * keeps render pure (`architecture:react-component-runtime` INV1, INV3).
+ * Only a class component has it.
+ *
+ * SYNC: When modified, update Collapsible.tsx and TreeList.tsx.
+ */
+import { Component } from 'react';
+interface LayoutChangeSnapshotProps<T> {
+    /** The state whose change moves the layout. */
+    value: T;
+    /** Runs before the DOM changes, with the value being left. */
+    onBeforeChange: (previous: T) => void;
+}
+export declare class LayoutChangeSnapshot<T> extends Component<LayoutChangeSnapshotProps<T>> {
+    getSnapshotBeforeUpdate(previous: Readonly<LayoutChangeSnapshotProps<T>>): null;
+    componentDidUpdate(): void;
+    render(): null;
+}
+export {};
+//# sourceMappingURL=LayoutChangeSnapshot.d.ts.map

package/dist/motion/LayoutChangeSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutChangeSnapshot.d.ts","sourceRoot":"","sources":["../../src/motion/LayoutChangeSnapshot.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAEhC,UAAU,yBAAyB,CAAC,CAAC;IACnC,+CAA+C;IAC/C,KAAK,EAAE,CAAC,CAAC;IACT,8DAA8D;IAC9D,cAAc,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;CACvC;AAED,qBAAa,oBAAoB,CAAC,CAAC,CAAE,SAAQ,SAAS,CACpD,yBAAyB,CAAC,CAAC,CAAC,CAC7B;IACU,uBAAuB,CAC9B,QAAQ,EAAE,QAAQ,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI;IAQE,kBAAkB,IAAI,IAAI;IAE1B,MAAM,IAAI,IAAI;CAGxB"}

package/dist/motion/LayoutChangeSnapshot.js

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file LayoutChangeSnapshot.tsx
+ * @input A value and a callback
+ * @output Exports LayoutChangeSnapshot: calls the callback in the commit that
+ *   changes the value, before React changes the DOM
+ * @position Motion foundation, internal to core; how a component that takes
+ *   an `animatedLayout` handle measures each change before it lands
+ *   (`spec:AST-105` FR1), whatever caused it: a click, an owner-set prop, or
+ *   a group's value
+ *
+ * `getSnapshotBeforeUpdate` runs in the commit, after render and before any
+ * DOM mutation of that commit, so the layout it reads is the old one. Unlike
+ * a read during render, it runs only for a render that commits, once (a
+ * StrictMode replay or a render React throws away never reaches it), and it
+ * keeps render pure (`architecture:react-component-runtime` INV1, INV3).
+ * Only a class component has it.
+ *
+ * SYNC: When modified, update Collapsible.tsx and TreeList.tsx.
+ */
+
+import { Component } from 'react';
+export class LayoutChangeSnapshot extends Component {
+  getSnapshotBeforeUpdate(previous) {
+    if (!Object.is(previous.value, this.props.value)) {
+      this.props.onBeforeChange(previous.value);
+    }
+    return null;
+  }
+
+  // React asks for this beside getSnapshotBeforeUpdate.
+  componentDidUpdate() {}
+  render() {
+    return null;
+  }
+}

package/dist/motion/animatedLayout.d.ts

@@ -0,0 +1,190 @@
+/** How a change plays under the reader's settings. */
+type LayoutMotion = {
+    readonly kind: 'spring';
+    readonly progress: SpringProgress;
+} | {
+    readonly kind: 'fade';
+    readonly durationMs: number;
+    readonly easing: string;
+} | {
+    readonly kind: 'instant';
+};
+/** The settle spring as remaining distance (1 → 0) over its duration. */
+interface SpringProgress {
+    readonly durationMs: number;
+    /** Remaining fraction of the move at `t` ms. */
+    remaining(t: number): number;
+}
+/**
+ * The glide `element` is playing now, if any. For an adopter that draws
+ * something with each moving element (a table row's divider): it finds what
+ * moves without reading the DOM.
+ */
+export declare function glideOf(element: Element): Animation | null;
+declare const AREA: unique symbol;
+/**
+ * The opaque handle `useAnimatedLayout` returns (`spec:AST-105` FR1): no
+ * public members. A component that receives it reports its size changes to
+ * the handle's container, the area the glide stays inside.
+ */
+export interface AnimatedLayout {
+    readonly [AREA]: () => Element | null;
+}
+/** A handle over `area` (the container element, read when a change runs). */
+export declare function createAnimatedLayout(area: () => Element | null): AnimatedLayout;
+type Target = {
+    readonly current: Element | null;
+} | (() => Element | null);
+export interface LayoutChange {
+    /** Before the change commits (in the event handler that causes it). */
+    measureBefore(): void;
+    /**
+     * After it commits (a layout effect). Returns whether the change was
+     * measured: an unmeasured change (an owner set the state directly) moves
+     * nothing, and the component plays no entrance for it either.
+     *
+     * `beforeMove`, when given, runs once the new places are read and before
+     * any glide starts, with the elements the glide may move: whatever the
+     * component reads from the layout for the glide, it reads there, so the page
+     * is not laid out again (`playLayoutChange` included).
+     */
+    animate(beforeMove?: (candidates: ReadonlyArray<Element>) => void): boolean;
+}
+/**
+ * Report a size change of `target` to the handle's area. Call
+ * `measureBefore()` before the change commits and `animate()` after it; the
+ * content after `target`, up to the area, glides from its old place.
+ * Changes in one area in one frame move together. Without a handle, or
+ * outside its container, nothing moves.
+ */
+export declare function reportLayoutChange(handle: AnimatedLayout | null | undefined, target: Target): LayoutChange;
+/**
+ * The changed element's own animation, on the same motion as the content
+ * after it: content that appears reveals downward from its top edge. Plays
+ * only with a handle, inside its area and in the area's visible part.
+ * Returns the entrance it started, or null when it played none.
+ */
+export declare function playLayoutChange(handle: AnimatedLayout | null | undefined, element: Element): Animation | null;
+/**
+ * The changed element's exit (`spec:AST-105` FR4): content that disappears
+ * keeps its place on screen but gives up its space (a negative end margin
+ * measured against the layout without it, so the content after it glides up
+ * at once to exactly where it ends, and it still scrolls and clips with its
+ * container), is inert (no focus, no pointer, nothing read), conceals upward
+ * from its bottom edge on the same motion, and then `done` runs, when the
+ * component hides or unmounts it. Under Reduce Motion with a coarse primary pointer it
+ * fades instead. Call it in the layout effect of the commit that closes the
+ * element, after the change's `animate()` reported it measured, in the same
+ * task: the glide reads the layout once the element has given up its space.
+ *
+ * Returns false, holding nothing, when the exit lands at once: no handle, a
+ * close no change in the area measured, outside the area or its visible part,
+ * Reduce Motion with a fine pointer, or a layout no end margin can free (a
+ * grid track and its gap, a flex-row item that sets its row's height); in
+ * that last case the content after it takes its final place at once too.
+ * The component then hides the element itself.
+ */
+export declare function holdLayoutExit(handle: AnimatedLayout | null | undefined, element: HTMLElement, done: () => void): boolean;
+/**
+ * Puts an element `holdLayoutExit` held back: stops its exit and puts back
+ * what the exit replaced (its `inert` and inline values as they were). Called
+ * once the component has hidden the element, or when the element opens again
+ * mid-exit.
+ */
+export declare function releaseLayoutExit(element: HTMLElement): void;
+/**
+ * Old content held as one transient copy while new content enters in its
+ * place (`spec:AST-105` FR8): inert, hidden from assistive technology, and
+ * removed when the swap ends (`architecture:component-style-authoring` INV7).
+ */
+export interface LayoutSwap {
+    readonly area: Element;
+    readonly copy: HTMLElement;
+    /** Where the old content showed, in viewport coordinates. */
+    readonly rect: DOMRect;
+}
+/** How far a ridden element has moved since the swap began. */
+export interface LayoutRide {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * How a swap plays, as frames over its progress (0 → 1) and, with
+ * `rideWith`, the ridden element's travel so far.
+ */
+export interface LayoutSwapMotion {
+    /** The box the copy is laid out in, over the old content's place. */
+    readonly host: Element;
+    /** The copy's frames while it travels. */
+    readonly copy: (p: number, ride: LayoutRide) => Keyframe;
+    /** Its text's opacity, on its own curve, when that differs from the copy's. */
+    readonly copyText?: (p: number) => number;
+    /** The copy paints above its neighbours, in the background it shows. */
+    readonly isOpaque?: boolean;
+    /**
+     * An element the glide moves, such as the column the old content sat in.
+     * Every part plays over its glide, frame by frame, and is told how far it
+     * has moved; the copy rides it unless `isCopyMoved` is false. Without a
+     * glide (it lands silently) the ride is the whole `travel` at once (its
+     * old place less its new).
+     */
+    readonly rideWith?: {
+        readonly element: Element;
+        readonly travel: LayoutRide;
+        readonly isCopyMoved?: boolean;
+    };
+    /** Called once when the swap ends, however it ends. */
+    readonly onEnd?: () => void;
+    /** Elements the page already renders, entering with the swap. */
+    readonly incoming: ReadonlyArray<{
+        readonly element: Element;
+        readonly frames: (p: number, ride: LayoutRide) => Keyframe;
+    }>;
+}
+/**
+ * Before a change commits: hold `element`'s old content as one transient copy
+ * (`spec:AST-105` FR8). With `isVisiblePart`, the copy is the element's
+ * visible part, its content scrolled as it was (a scroll container). Returns
+ * null without a handle, outside its area, under an immediate change, or for
+ * content too large to copy.
+ */
+export declare function holdLayoutSwap(handle: AnimatedLayout | null | undefined, element: HTMLElement, { isVisiblePart }?: {
+    isVisiblePart?: boolean;
+}): LayoutSwap | null;
+/**
+ * After the change commits, before paint: the copy leaves while the incoming
+ * elements enter, on FR4's one motion, every part started on the same
+ * timeline time. Under Reduce Motion with a coarse pointer, only opacity
+ * changes (`design:reduced-motion` DR2). Returns what ends the swap at once;
+ * it also ends when its motion does, and the copy is removed.
+ */
+export declare function playLayoutSwap(swap: LayoutSwap, how: LayoutSwapMotion): () => void;
+/**
+ * After a change commits, before paint: elements the page already renders
+ * play frames over the change's progress on FR4's one motion, with no copy,
+ * such as a surface reaching over a gap a glide opens. Under Reduce Motion
+ * with a coarse pointer, only opacity changes; under an immediate change,
+ * nothing plays. Returns what ends them at once.
+ */
+export declare function playLayoutFrames(handle: AnimatedLayout | null | undefined, parts: LayoutSwapMotion['incoming']): () => void;
+/**
+ * A disclosure's indicator (its chevron) turns on the same motion as the
+ * glide: its CSS transition takes the spring as a `linear()` easing, and an
+ * immediate change under Reduce Motion. Without a handle the inline values are
+ * cleared, so the component's own transition applies. An engine without
+ * `linear()` drops that value and keeps the component's easing.
+ */
+export declare function applyLayoutChangeTransition(handle: AnimatedLayout | null | undefined, element: HTMLElement | SVGElement | null): void;
+/**
+ * Lands `element`'s running glide at once: it takes its layout place, and a
+ * later change starts from there (a change its caller lands rather than
+ * animates, such as a rail that snaps).
+ */
+export declare function landLayoutGlide(element: Element): void;
+/**
+ * @internal The motion a change in `area` plays, for tests and for SideNav's
+ * rail motion, which plays on the same clock (`component:SideNav` FR6).
+ */
+export declare function layoutMotionFor(area: Element): LayoutMotion;
+export {};
+//# sourceMappingURL=animatedLayout.d.ts.map

package/dist/motion/animatedLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animatedLayout.d.ts","sourceRoot":"","sources":["../../src/motion/animatedLayout.ts"],"names":[],"mappings":"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"}