@multiplatform.one/forms 8.4.0 → 8.5.0

package/types/shared/sheetDetents.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Sheet detents — the rest positions a bottom sheet is allowed to settle at,
+ * and the one place their geometry is computed.
+ *
+ * Apple is the precedent: `UISheetPresentationController.detents` is an ARRAY
+ * (`.medium()`, `.large()`, `.custom`), and the sheet drags between whichever
+ * the presenter declared. MPO's sheets took a single `snapPoint` percent, so a
+ * caller could ask for one rest and never for a set, and the web twin resolved
+ * that percent to ONE snap point — which is a sheet with nothing to drag
+ * between, the open-or-closed complaint that opened FZ-455.
+ *
+ * It lives in `forms` because both sheets need it and `forms` is the lower
+ * layer: `@multiplatform.one/components`' SheetModal imports it, and
+ * FloatingPanel sits in this package. It was previously a private copy in each
+ * sheet, and that duplication is what let MPO-71 rewrite one copy from a stale
+ * version and silently drop the `snapPoint` push — declared, documented and
+ * passed by four callers while doing nothing on device for a month. One module.
+ *
+ * Percent, not points: a detent is a fraction of the sheet's own full height,
+ * so the same declaration means the same shape on a phone and an iPad, and the
+ * native and web twins resolve one set rather than two.
+ */
+/** Smallest height a sheet is ever laid out at, in points. */
+export declare const minSheetHeight = 180;
+/** The large detent: the tallest a content-sized sheet grows, as a fraction of the window. */
+export declare const largeDetentRatio = 0.85;
+/** Percent rest of a `fill` sheet with no detent: it has no intrinsic height to fit. */
+export declare const fillSnapPoint = 60;
+/** Released more than this far below the smallest detent, the sheet dismisses. */
+export declare const sheetDismissThreshold = 56;
+/**
+ * The HIG detents as percents of the sheet's full height. A caller writes
+ * `detents={[sheetDetent.large, sheetDetent.medium]}` rather than inventing
+ * numbers, the way a presenter writes `[.large(), .medium()]`.
+ */
+export declare const sheetDetent: {
+    /** `.medium()` — half-open, for a sheet that owns a scrollport. */
+    readonly medium: 55;
+    /** `.large()` — the sheet's full height. */
+    readonly large: 100;
+};
+/**
+ * Half-open detent as a fraction, for the native paths that work in points.
+ * The same number as `sheetDetent.medium`, in the unit those paths use.
+ */
+export declare const mediumDetent: number;
+export interface DetentSetOptions {
+    /**
+     * Rest positions the caller declares, as percents of the sheet's full
+     * height. Order does not matter; the set is resolved largest first. Wins
+     * over `snapPoint` as the SET, while `snapPoint` still picks which of them
+     * the sheet opens at.
+     */
+    detents?: number[];
+    /**
+     * Single-percent rest. On its own it means "full height and this one", so
+     * the sheet opens at this percent and can be dragged back to full.
+     */
+    snapPoint?: number;
+    /** The sheet owns a scrollport, so a half-open rest is meaningful. */
+    scrollable?: boolean;
+}
+/**
+ * The percents the sheet may rest at, largest first.
+ *
+ * A declared `detents` set is the caller's to own. With none, the set is the
+ * sheet's full height plus whatever else is implied: the half-open rest when
+ * it owns a scrollport, and the caller's `snapPoint`. Full height is always in
+ * that fallback set, because a sheet dragged down must be draggable back up —
+ * `.large()` stays reachable in Apple's model too.
+ */
+export declare function resolveDetentPercents({ detents, snapPoint, scrollable, }: DetentSetOptions): number[];
+/**
+ * Which detent in the resolved set the sheet opens at, as an index into it.
+ *
+ * `snapPoint` is the percent the sheet rests at, so it names the opening
+ * detent; Apple spells the same thing `selectedDetentIdentifier`. A sheet with
+ * no `snapPoint`, or one naming a percent outside the set, opens at the
+ * largest detent.
+ */
+export declare function openingDetentIndex(points: number[], snapPoint?: number): number;
+export interface ResolveSheetDetentsOptions extends DetentSetOptions {
+    /** Full (expanded) height of the sheet, in points. */
+    travel: number;
+}
+/**
+ * The heights the native sheet is allowed to rest at, largest first.
+ *
+ * The native sheets' `translateY` measures DOWN from fully-expanded, so a
+ * detent of `h` rests at `travel - h` and `travel` itself is the expanded
+ * sheet. Anything shorter than `minSheetHeight` is discarded, because a sheet
+ * resting below that is indistinguishable from a dismissed one; a sheet whose
+ * full height is already under the floor keeps its own height, or it would
+ * have no detents at all.
+ */
+export declare function resolveSheetDetents({ travel, detents, scrollable, snapPoint, }: ResolveSheetDetentsOptions): number[];
+export type WebSnap = {
+    snapPointsMode: "fit";
+} | {
+    snapPointsMode: "percent";
+    snapPoints: number[];
+    defaultPosition: number;
+};
+export interface ResolveWebSnapOptions extends DetentSetOptions {
+    /** The sheet's body takes the remaining height, so it has no intrinsic one. */
+    fill?: boolean;
+}
+/**
+ * The web Sheet's snap props.
+ *
+ * FZ-7977: a sheet with no detent of any kind opens at its content's height,
+ * capped at the large detent, the way the native twin sizes to content,
+ * instead of a fixed percent with a dead band under short content. A `fill`
+ * sheet has no intrinsic height, so it keeps a percent rest.
+ *
+ * FZ-455: once any percent is in play, the sheet gets the WHOLE resolved set
+ * rather than the single percent it used to get, and `defaultPosition` holds
+ * it at the percent it opened at before. One snap point left tamagui's Sheet
+ * with nothing to drag between, so the grabber moved and the sheet did not.
+ */
+export declare function resolveWebSnap({ detents, snapPoint, scrollable, fill, }: ResolveWebSnapOptions): WebSnap;
+//# sourceMappingURL=sheetDetents.d.ts.map

package/types/shared/sheetDetents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheetDetents.d.ts","sourceRoot":"","sources":["../../src/shared/sheetDetents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,wFAAwF;AACxF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB,mEAAmE;;IAEnE,4CAA4C;;CAEpC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA2B,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAWD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,SAAS,EACT,UAAU,GACX,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAQ7B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,OAAO,EACP,UAAU,EACV,SAAS,GACV,EAAE,0BAA0B,GAAG,MAAM,EAAE,CAMvC;AAED,MAAM,MAAM,OAAO,GACf;IAAE,cAAc,EAAE,KAAK,CAAA;CAAE,GACzB;IAAE,cAAc,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,SAAS,EACT,UAAU,EACV,IAAI,GACL,EAAE,qBAAqB,GAAG,OAAO,CAUjC"}