@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/glass/lens/menuField.d.ts

@@ -0,0 +1,178 @@
+import { type GlassFieldMember } from '../fieldGeometry.js';
+import type { MenuSourceKind } from '../regions.js';
+/**
+ * Button → menu as one glass field of two members, like native's liquid drop:
+ * - the panel member travels from the trigger to the panel on the recorded menu pose
+ *   (menuMorphMotion.ts);
+ * - the trigger member stays at the trigger's home. On open it holds the pressed glass, dips and
+ *   is absorbed into the departing drop; on close it grows back out of the returning body as a
+ *   horn, so the shape pours back into the button as a teardrop.
+ * The trigger's glyph and the menu's rows are ink drawn inside that glass (the ink kernel), so
+ * the growing rim lenses them and no page element is scaled, blurred or clipped.
+ *
+ * Phone reference: iOS 27.0 iPhone 17 Pro Max Simulator, stock SwiftUI toolbar Menu
+ * (native recording menu measurements). Times are ms after the morph's time zero:
+ * native release +43 ms on open (regionScene anchors it on the trigger's release), close tap
+ * +41 ms on close. Measured (native release/tap times): the pressed 48 pt button holds, dips to
+ * 41 pt and departs lopsided (release +116...+175 ms); its white highlight fades 118 → 68 → 0
+ * over +108...+160 ms and its dots ride the bulge until about +150 ms.
+ *
+ * On close the button re-forms from +172 ms as a bump on the body's leading edge, 9 pt short
+ * of its home and 10 pt past it (above, for a menu that hangs below its trigger), carrying its
+ * dots. It rises to 13.5 pt past home by +242 ms and settles back by about +530 ms while the
+ * body pours into it: the tracked centre of the dots follows one spring on both axes
+ * (menuMorphPhoneFit.json `closeButton`, 0.14 pt RMS). That momentum is the only time the
+ * shape passes its button. Rows fade from the first close frame (246 → 96 in about 15 ms of
+ * motion, a faint blurred copy until about +140 ms).
+ *
+ * Triggers that are not a circle (same Simulator, stock SwiftUI Menu from a labelled capsule
+ * 129 x 50, a full-width button 400 x 50 and a toolbar group 152 x 44; phase-morph-shapes-notes.md):
+ * the drop does not start as the trigger. The whole trigger glass contracts in about three frames
+ * (its width to 0.71 and 0.47 of rest while its height is at 0.90 and 0.74: it shortens faster
+ * than it thins) toward the menu member's centre, while a round drop the size of the trigger's
+ * height grows there. From then on the drop's size and path are the circle's. On close the
+ * button re-forms as the whole trigger scaled up (height first, width lagging), carrying its
+ * label at that scale, and passes home by the same share of the travel.
+ * The part the drop forms from is the trigger's `seed` (menuSeed): for a circle, and any trigger
+ * at least two thirds as thick as it is long, the seed is the trigger and every value below is
+ * unchanged.
+ */
+export declare const MENU_FIELD: {
+    /** Smooth-union reach between the trigger and the panel members (points). */
+    readonly blendRadius: 22;
+    /** Depth over which the rim lenses the ink (points). */
+    readonly lensWidth: 14;
+    /** On close the button forms as a bump on the body: until the body reaches it, its centre
+     * stays within this many of its radii of the body's surface, so it always touches the body
+     * (fitted with the springs; native's horn grows out of the body's leading corner). */
+    readonly closeEmbed: 1;
+    /** A scaled long trigger keeps its round part at the scale and the rest of its length (width
+     * beyond its height) at the scale to this power. Native's full-width button, re-forming: 0.50,
+     * 0.67, 0.80 and 0.90 of its width at 0.75, 0.84, 0.91 and 0.95 of its height (2.5 gives 0.52,
+     * 0.67, 0.81, 0.89); contracting: 0.71 and 0.47 at 0.90 and 0.74 (0.79, 0.51). */
+    readonly excessPower: 2.5;
+    /** On open a long trigger's round part follows the absorption curve to this power (the
+     * inverse of `excessPower`), so its length follows the curve itself: native's full-width
+     * button is at 0.93, 0.71 and 0.47 of its width where the circle's curve is at 0.91, 0.74 and
+     * 0.39. */
+    readonly elongatedOpenPower: 0.4;
+    /** On close a long trigger's round part follows the re-forming spring to this power, so its
+     * length follows the spring squared: native's full-width button is back to 0.50, 0.74, 0.90
+     * and 0.98 of its width at +213, +254, +306 and +351 ms of the dismissing touch, its height
+     * ahead of it. */
+    readonly elongatedClosePower: 0.8;
+};
+type Keys = readonly (readonly [ms: number, value: number])[];
+/** Monotone cubic (Fritsch-Carlson) through the keys, constant outside them. Velocity is
+ * continuous across keys, so a curve never pauses at a knot (a per-segment smoothstep did). */
+export declare function keyed(keys: Keys, ms: number): number;
+export declare const MENU_FIELD_CURVES: {
+    readonly open: {
+        /** Trigger member size relative to its rest size; the first key is the pressed scale. */
+        readonly trigger: readonly [readonly [73, 0.93], readonly [100, 0.6], readonly [135, 0]];
+        /** Multiplier on the press highlight carried over from the trigger. */
+        readonly highlight: readonly [readonly [65, 1], readonly [117, 0]];
+        readonly glyph: readonly [readonly [80, 1], readonly [130, 0]];
+        readonly rowsScale: readonly [readonly [100, 1.3], readonly [300, 1]];
+        readonly rowsOpacity: readonly [readonly [90, 0], readonly [200, 1]];
+        readonly rowsBlur: readonly [readonly [110, 5], readonly [260, 0]];
+        readonly lens: readonly [readonly [380, 8], readonly [450, 0]];
+    };
+    readonly close: {
+        readonly highlight: readonly [readonly [0, 0]];
+        /** Dots show as a smudge in the re-forming button at +172 ms of the tap, bright at +188 ms
+         * and crisp at +207 ms. */
+        readonly glyph: readonly [readonly [132, 0], readonly [152, 0.8], readonly [168, 1]];
+        readonly rowsScale: readonly [readonly [0, 1], readonly [120, 1.12]];
+        /** Rows hold for the first frame of motion, then drop fast to a faint blurred copy. */
+        readonly rowsOpacity: readonly [readonly [25, 1], readonly [40, 0.3], readonly [65, 0.15], readonly [105, 0]];
+        readonly rowsBlur: readonly [readonly [25, 0], readonly [65, 4]];
+        /** Closing rows fade without rim bending (native shows none). */
+        readonly lens: readonly [readonly [0, 0]];
+        /** The body's corner radius as a share of its half-size: the panel's 0.34 rounds fully by
+         * +139 ms (fit). Replaces the iPad corner curve on the phone close. */
+        readonly roundness: readonly [readonly [0, 0.34], readonly [14, 0.44], readonly [29, 0.55], readonly [44, 0.71], readonly [79, 0.77], readonly [94, 1]];
+    };
+};
+export type Rect = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+/** How far a trigger is from round: 0 while it is at least two thirds as thick as it is long (a
+ * circle, and the 58 x 47 member of three blended glass buttons, whose whole glass leaves as the
+ * drop in native), 1 once it is under 0.45 (the measured capsule and full-width button are 0.39
+ * and 0.125). The circle's fitted behaviour applies at 0, the measured long-trigger behaviour at
+ * 1. Between them nothing was measured: the two are blended smoothly. */
+export declare function triggerElongation(shape: Pick<GlassFieldMember, 'halfWidth' | 'halfHeight'>): number;
+/** The part of a trigger its drop forms from. A round trigger's seed is the trigger itself. A
+ * long trigger's seed is its round part: a shape as wide as the trigger is thick, centred on
+ * `anchor` (the menu's own button inside a wider glass group; the trigger's centre when absent)
+ * and kept inside the trigger. */
+export declare function menuSeed(trigger: GlassFieldMember, anchor?: {
+    x: number;
+    y: number;
+}): GlassFieldMember;
+/** A trigger at `scale` of its rest size. Its round part (the seed) scales by `scale` about the
+ * seed's centre; its length beyond the seed scales by `scale` to `excessPower`, so a long
+ * button shortens faster than it thins. At or above 1 (the pressed growth) and for a circle the
+ * scale is uniform about the trigger's centre. */
+export declare function scaledMenuTrigger(home: GlassFieldMember, scale: number, seed?: GlassFieldMember): GlassFieldMember;
+/** Where the re-forming button's centre is at `ms` of a close: its home plus the settle
+ * spring's displacement, a share of the panel-to-trigger travel on each axis. */
+export declare function closeButtonCenter(home: GlassFieldMember, panelFrame: Rect, ms: number): {
+    x: number;
+    y: number;
+};
+/** One ink layer: a region of the ink atlas drawn at `frame` inside the glass (points). */
+export type MenuInkLayer = Readonly<{
+    source: Rect;
+    frame: Rect;
+    opacity: number;
+    blur: number;
+    /** Rim lensing: displacement (points) at the edge, fading to zero at `lensWidth` deep. */
+    lens: number;
+    lensWidth: number;
+}>;
+export type MenuFieldFrame = {
+    members: GlassFieldMember[];
+    blendRadius: number;
+    /** Press-highlight white amount over the whole field. */
+    highlight: number;
+    ink: MenuInkLayer[];
+};
+/** The two-member field, its highlight and its ink at `ms` after the morph's time zero.
+ * `panel` is the travelling panel member (between the trigger's seed and the panel); `home` the
+ * trigger glass at rest; `anchor` the centre of the menu's own button when the trigger glass is
+ * wider than it (a toolbar group); `panelFrame` the settled panel. `rows`/`glyph` pair an ink
+ * atlas region with its settled rectangle. All in points. */
+export declare function menuFieldFrame({ sourceKind, direction, ms, panel: travelling, home, anchor, pressedScale, pressHighlight, panelFrame, rows, glyph, settled, }: {
+    sourceKind?: MenuSourceKind;
+    direction: 'open' | 'close';
+    ms: number;
+    panel: GlassFieldMember;
+    home: GlassFieldMember;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+    pressedScale?: number;
+    pressHighlight?: number;
+    panelFrame: Rect;
+    rows?: {
+        source: Rect;
+        frame: Rect;
+    };
+    glyph?: {
+        source: Rect;
+        frame: Rect;
+    };
+    /** The open has settled (identity ink) or the menu snaps (reduced motion). */
+    settled?: boolean;
+}): MenuFieldFrame;
+export declare function plainMenuPresentation(kind: 'label' | 'glyph', direction: 'open' | 'close', ms: number, settled: boolean): {
+    opacity: number;
+    rounding: number;
+};
+export {};