@hzblj/kara-router 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @hzblj/kara-router
 
+## 0.5.0
+
+### Minor Changes
+
+- [#8](https://github.com/hzblj/kara-ui/pull/8) [`3b0a6fb`](https://github.com/hzblj/kara-ui/commit/3b0a6fbc49559720023fece2b5c6189ad4d88bc8) Thanks [@hzblj](https://github.com/hzblj)! - `ZoomTransition`: a push that grows out of the photo it was opened from and shrinks back into it.
+
+  - iOS 18: UIKit's zoom transition, with the interactive dismissal (swipe down, edge swipe, pinch) gated on the scroll views under the finger. Below iOS 18 the push stays a slide. Android: Material's container transform, both ways.
+  - Three pieces from `@hzblj/kara-ui/router`, tied by one identifier: `ZoomTransition.Source` on the list, `ZoomTransition.Enabler` and `ZoomTransition.Target` on the pushed screen; `useZoomTransitionSourceId`, `ZOOM_TRANSITION_PARAM`, `useZoomTransitionParam` and `withZoomTransition` (an Android fade under the transform) around them.
+  - Settings both platforms honour sit at the top (`scrim`); the rest is typed apart under `ios` (`dismissGesture`, `blur`, the target's `fit`) and `android` (`duration`, `easing`, `fade`, `path`, corner radii, the target's `fit` and `flex`).
+  - `ContextMenu`: with a `ZoomTransition.Source` in the trigger, a tap on the iOS preview zooms the preview's photo straight into the pushed screen. `previewTransition` (`zoom`, `pop`, `dismiss`) picks how the preview leaves.
+  - `DurationSize`, the keys of `duration`.
+
+### Patch Changes
+
+- Updated dependencies [[`3b0a6fb`](https://github.com/hzblj/kara-ui/commit/3b0a6fbc49559720023fece2b5c6189ad4d88bc8)]:
+  - @hzblj/kara-native@0.5.0
+  - @hzblj/kara-components@0.5.0
+  - @hzblj/kara-theme@0.5.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [[`d14bdd3`](https://github.com/hzblj/kara-ui/commit/d14bdd37bede9fef80f4d3af4621ea5d60b2b16b)]:
+  - @hzblj/kara-native@0.4.1
+  - @hzblj/kara-theme@0.4.1
+  - @hzblj/kara-components@0.4.1
+
 ## 0.4.0
 
 ### Minor Changes

package/lib/module/index.js

@@ -2,4 +2,5 @@
 
 export * from "./navigation-theme.js";
 export * from "./tabs/index.js";
+export * from "./zoom-transition/index.js";
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":[],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,cAAc,uBAAoB;AAClC,cAAc,iBAAQ","ignoreList":[]}
+{"version":3,"names":[],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,cAAc,uBAAoB;AAClC,cAAc,iBAAQ;AACtB,cAAc,4BAAmB","ignoreList":[]}

package/lib/module/zoom-transition/index.js

@@ -0,0 +1,8 @@
+"use strict";
+
+export * from "./use-zoom-transition-source-id.js";
+export * from "./with-zoom-transition.js";
+export * from './zoom-transition';
+export * from "./zoom-transition.types.js";
+export * from "./zoom-transition-param.js";
+//# sourceMappingURL=index.js.map

package/lib/module/zoom-transition/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["zoom-transition/index.ts"],"mappings":";;AAAA,cAAc,oCAAiC;AAC/C,cAAc,2BAAwB;AACtC,cAAc,mBAAmB;AACjC,cAAc,4BAAyB;AACvC,cAAc,4BAAyB","ignoreList":[]}

package/lib/module/zoom-transition/use-zoom-transition-source-id.js

@@ -0,0 +1,11 @@
+"use strict";
+
+import { useId } from 'react';
+
+/**
+ * An identifier for a `ZoomTransition.Source`, unique to this component instance and to `key` — the item it shows.
+ * Keyed by the item, a recycled list cell registers under a new identifier when it shows another item, so a detail
+ * opened from its previous item zooms back out plainly instead of into the wrong cell.
+ */
+export const useZoomTransitionSourceId = key => `${useId()}${key}`;
+//# sourceMappingURL=use-zoom-transition-source-id.js.map

package/lib/module/zoom-transition/use-zoom-transition-source-id.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useId","useZoomTransitionSourceId","key"],"sourceRoot":"../../../src","sources":["zoom-transition/use-zoom-transition-source-id.ts"],"mappings":";;AAAA,SAAQA,KAAK,QAAO,OAAO;;AAE3B;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,yBAAyB,GAAIC,GAAW,IAAK,GAAGF,KAAK,CAAC,CAAC,GAAGE,GAAG,EAAE","ignoreList":[]}

package/lib/module/zoom-transition/with-zoom-transition.js

@@ -0,0 +1,25 @@
+"use strict";
+
+import { duration } from '@hzblj/kara-theme';
+import { Platform } from 'react-native';
+import { ZOOM_TRANSITION_PARAM } from "./zoom-transition-param.js";
+const hasZoomSource = params => !!params && !!params[ZOOM_TRANSITION_PARAM];
+
+/**
+ * `Stack.Screen` options for a screen the zoom pushes. On Android a push whose params carry `ZOOM_TRANSITION_PARAM`
+ * becomes a quick fade, so Material's container transform reads as the transition instead of racing the stack's own
+ * slide; any other push keeps the stack's animation. Your options win: set `animation` yourself to keep another one.
+ * iOS needs nothing — UIKit's zoom replaces the push animation.
+ */
+export const withZoomTransition = options => props => {
+  const resolved = (typeof options === 'function' ? options(props) : options) ?? {};
+  if (Platform.OS !== 'android' || !hasZoomSource(props.route.params)) {
+    return resolved;
+  }
+  return {
+    animation: 'fade',
+    animationDuration: duration.d300,
+    ...resolved
+  };
+};
+//# sourceMappingURL=with-zoom-transition.js.map

package/lib/module/zoom-transition/with-zoom-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["duration","Platform","ZOOM_TRANSITION_PARAM","hasZoomSource","params","withZoomTransition","options","props","resolved","OS","route","animation","animationDuration","d300"],"sourceRoot":"../../../src","sources":["zoom-transition/with-zoom-transition.ts"],"mappings":";;AAAA,SAAQA,QAAQ,QAAO,mBAAmB;AAC1C,SAAQC,QAAQ,QAAO,cAAc;AACrC,SAAQC,qBAAqB,QAAO,4BAAyB;AAM7D,MAAMC,aAAa,GAAIC,MAA0B,IAC/C,CAAC,CAACA,MAAM,IAAI,CAAC,CAAEA,MAAM,CAA6BF,qBAAqB,CAAC;;AAE1E;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,kBAAkB,GACHC,OAAsD,IAC/EC,KAAiB,IAAwC;EACxD,MAAMC,QAA2B,GAAG,CAAC,OAAOF,OAAO,KAAK,UAAU,GAAGA,OAAO,CAACC,KAAK,CAAC,GAAGD,OAAO,KAAK,CAAC,CAAC;EAEpG,IAAIL,QAAQ,CAACQ,EAAE,KAAK,SAAS,IAAI,CAACN,aAAa,CAACI,KAAK,CAACG,KAAK,CAACN,MAAM,CAAC,EAAE;IACnE,OAAOI,QAAQ;EACjB;EAEA,OAAO;IAACG,SAAS,EAAE,MAAM;IAAEC,iBAAiB,EAAEZ,QAAQ,CAACa,IAAI;IAAE,GAAGL;EAAQ,CAAC;AAC3E,CAAC","ignoreList":[]}

package/lib/module/zoom-transition/zoom-transition-param.js

@@ -0,0 +1,16 @@
+"use strict";
+
+import { useLocalSearchParams } from 'expo-router';
+
+/**
+ * The route param that carries a source's identifier to the screen it pushes — what `withZoomTransition` looks for.
+ * Push with `params: {[ZOOM_TRANSITION_PARAM]: sourceId}` and read it back with `useZoomTransitionParam`.
+ */
+export const ZOOM_TRANSITION_PARAM = 'zoomTransitionSourceId';
+
+/** The source identifier this screen was pushed with — for its `ZoomTransition.Enabler` and `Target`. */
+export const useZoomTransitionParam = () => {
+  const value = useLocalSearchParams()[ZOOM_TRANSITION_PARAM];
+  return (Array.isArray(value) ? value[0] : value) || undefined;
+};
+//# sourceMappingURL=zoom-transition-param.js.map

package/lib/module/zoom-transition/zoom-transition-param.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useLocalSearchParams","ZOOM_TRANSITION_PARAM","useZoomTransitionParam","value","Array","isArray","undefined"],"sourceRoot":"../../../src","sources":["zoom-transition/zoom-transition-param.ts"],"mappings":";;AAAA,SAAQA,oBAAoB,QAAO,aAAa;;AAEhD;AACA;AACA;AACA;AACA,OAAO,MAAMC,qBAAqB,GAAG,wBAAwB;;AAE7D;AACA,OAAO,MAAMC,sBAAsB,GAAGA,CAAA,KAA0B;EAC9D,MAAMC,KAAK,GAAGH,oBAAoB,CAAC,CAAC,CAACC,qBAAqB,CAAC;EAE3D,OAAO,CAACG,KAAK,CAACC,OAAO,CAACF,KAAK,CAAC,GAAGA,KAAK,CAAC,CAAC,CAAC,GAAGA,KAAK,KAAKG,SAAS;AAC/D,CAAC","ignoreList":[]}

package/lib/module/zoom-transition/zoom-transition.android.js

@@ -0,0 +1,75 @@
+"use strict";
+
+import { ZoomTransitionEnabler as NativeZoomTransitionEnabler, ZoomTransitionSource as NativeZoomTransitionSource, ZoomTransitionTarget as NativeZoomTransitionTarget, reverseZoomTransition } from '@hzblj/kara-native/jetpack-compose';
+import { duration, radii, useAppTheme } from '@hzblj/kara-theme';
+import { useNavigation } from 'expo-router';
+import { useEffect, useMemo } from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+const Source = ({
+  android,
+  children,
+  identifier
+}) => identifier ? /*#__PURE__*/_jsx(NativeZoomTransitionSource, {
+  cornerRadius: radii[android?.borderRadius ?? 'none'],
+  identifier: identifier,
+  children: children
+}) : children;
+const Target = ({
+  android,
+  children,
+  identifier
+}) => {
+  const flex = android?.flex;
+  const style = useMemo(() => flex === undefined ? undefined : {
+    flex
+  }, [flex]);
+  if (!identifier) {
+    return children;
+  }
+  return /*#__PURE__*/_jsx(NativeZoomTransitionTarget, {
+    cornerRadius: radii[android?.borderRadius ?? 'none'],
+    identifier: identifier,
+    isFittedToSourceAspectRatio: android?.fit === 'photo',
+    style: style,
+    children: children
+  });
+};
+
+/**
+ * The target starts the way in natively once it is laid out. The way back cannot wait for the target to go: the pop is
+ * native, and by the time the screen unmounts it is already sliding away. So the transform is played back from
+ * `beforeRemove`, while the target is still on screen.
+ */
+const Enabler = ({
+  android,
+  scrim,
+  sourceIdentifier
+}) => {
+  const navigation = useNavigation();
+  const theme = useAppTheme();
+  useEffect(() => {
+    if (!sourceIdentifier) {
+      return;
+    }
+    return navigation.addListener('beforeRemove', () => {
+      void reverseZoomTransition(sourceIdentifier);
+    });
+  }, [navigation, sourceIdentifier]);
+  if (!sourceIdentifier) {
+    return null;
+  }
+  return /*#__PURE__*/_jsx(NativeZoomTransitionEnabler, {
+    easing: android?.easing,
+    fadeMode: android?.fade,
+    pathMotion: android?.path,
+    scrimColor: scrim ? theme.color(scrim) : undefined,
+    sourceIdentifier: sourceIdentifier,
+    transformDuration: android?.duration ? duration[android.duration] : undefined
+  });
+};
+export const ZoomTransition = {
+  Enabler,
+  Source,
+  Target
+};
+//# sourceMappingURL=zoom-transition.android.js.map

package/lib/module/zoom-transition/zoom-transition.android.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ZoomTransitionEnabler","NativeZoomTransitionEnabler","ZoomTransitionSource","NativeZoomTransitionSource","ZoomTransitionTarget","NativeZoomTransitionTarget","reverseZoomTransition","duration","radii","useAppTheme","useNavigation","useEffect","useMemo","jsx","_jsx","Source","android","children","identifier","cornerRadius","borderRadius","Target","flex","style","undefined","isFittedToSourceAspectRatio","fit","Enabler","scrim","sourceIdentifier","navigation","theme","addListener","easing","fadeMode","fade","pathMotion","path","scrimColor","color","transformDuration","ZoomTransition"],"sourceRoot":"../../../src","sources":["zoom-transition/zoom-transition.android.tsx"],"mappings":";;AAAA,SACEA,qBAAqB,IAAIC,2BAA2B,EACpDC,oBAAoB,IAAIC,0BAA0B,EAClDC,oBAAoB,IAAIC,0BAA0B,EAClDC,qBAAqB,QAChB,oCAAoC;AAC3C,SAAQC,QAAQ,EAAEC,KAAK,EAAEC,WAAW,QAAO,mBAAmB;AAC9D,SAAQC,aAAa,QAAO,aAAa;AACzC,SAAQC,SAAS,EAAEC,OAAO,QAAO,OAAO;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAQxC,MAAMC,MAAM,GAAGA,CAAC;EAACC,OAAO;EAAEC,QAAQ;EAAEC;AAAqC,CAAC,KACxEA,UAAU,gBACRJ,IAAA,CAACX,0BAA0B;EAACgB,YAAY,EAAEX,KAAK,CAACQ,OAAO,EAAEI,YAAY,IAAI,MAAM,CAAE;EAACF,UAAU,EAAEA,UAAW;EAAAD,QAAA,EACtGA;AAAQ,CACiB,CAAC,GAE7BA,QACD;AAEH,MAAMI,MAAM,GAAGA,CAAC;EAACL,OAAO;EAAEC,QAAQ;EAAEC;AAAqC,CAAC,KAAK;EAC7E,MAAMI,IAAI,GAAGN,OAAO,EAAEM,IAAI;EAC1B,MAAMC,KAAK,GAAGX,OAAO,CAAC,MAAOU,IAAI,KAAKE,SAAS,GAAGA,SAAS,GAAG;IAACF;EAAI,CAAE,EAAE,CAACA,IAAI,CAAC,CAAC;EAE9E,IAAI,CAACJ,UAAU,EAAE;IACf,OAAOD,QAAQ;EACjB;EAEA,oBACEH,IAAA,CAACT,0BAA0B;IACzBc,YAAY,EAAEX,KAAK,CAACQ,OAAO,EAAEI,YAAY,IAAI,MAAM,CAAE;IACrDF,UAAU,EAAEA,UAAW;IACvBO,2BAA2B,EAAET,OAAO,EAAEU,GAAG,KAAK,OAAQ;IACtDH,KAAK,EAAEA,KAAM;IAAAN,QAAA,EAEZA;EAAQ,CACiB,CAAC;AAEjC,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,MAAMU,OAAO,GAAGA,CAAC;EAACX,OAAO;EAAEY,KAAK;EAAEC;AAA4C,CAAC,KAAK;EAClF,MAAMC,UAAU,GAAGpB,aAAa,CAAC,CAAC;EAClC,MAAMqB,KAAK,GAAGtB,WAAW,CAAC,CAAC;EAE3BE,SAAS,CAAC,MAAM;IACd,IAAI,CAACkB,gBAAgB,EAAE;MACrB;IACF;IAEA,OAAOC,UAAU,CAACE,WAAW,CAAC,cAAc,EAAE,MAAM;MAClD,KAAK1B,qBAAqB,CAACuB,gBAAgB,CAAC;IAC9C,CAAC,CAAC;EACJ,CAAC,EAAE,CAACC,UAAU,EAAED,gBAAgB,CAAC,CAAC;EAElC,IAAI,CAACA,gBAAgB,EAAE;IACrB,OAAO,IAAI;EACb;EAEA,oBACEf,IAAA,CAACb,2BAA2B;IAC1BgC,MAAM,EAAEjB,OAAO,EAAEiB,MAAO;IACxBC,QAAQ,EAAElB,OAAO,EAAEmB,IAAK;IACxBC,UAAU,EAAEpB,OAAO,EAAEqB,IAAK;IAC1BC,UAAU,EAAEV,KAAK,GAAGG,KAAK,CAACQ,KAAK,CAACX,KAAK,CAAC,GAAGJ,SAAU;IACnDK,gBAAgB,EAAEA,gBAAiB;IACnCW,iBAAiB,EAAExB,OAAO,EAAET,QAAQ,GAAGA,QAAQ,CAACS,OAAO,CAACT,QAAQ,CAAC,GAAGiB;EAAU,CAC/E,CAAC;AAEN,CAAC;AAED,OAAO,MAAMiB,cAAuC,GAAG;EAACd,OAAO;EAAEZ,MAAM;EAAEM;AAAM,CAAC","ignoreList":[]}

package/lib/module/zoom-transition/zoom-transition.ios.js

@@ -0,0 +1,47 @@
+"use strict";
+
+import { ZoomTransitionEnabler as NativeZoomTransitionEnabler, ZoomTransitionSource as NativeZoomTransitionSource, ZoomTransitionTarget as NativeZoomTransitionTarget } from '@hzblj/kara-native/swift-ui';
+import { useAppTheme } from '@hzblj/kara-theme';
+import { jsx as _jsx } from "react/jsx-runtime";
+const Source = ({
+  children,
+  identifier
+}) => identifier ? /*#__PURE__*/_jsx(NativeZoomTransitionSource, {
+  identifier: identifier,
+  children: children
+}) : children;
+const Target = ({
+  children,
+  identifier,
+  ios
+}) => identifier ? /*#__PURE__*/_jsx(NativeZoomTransitionTarget, {
+  identifier: identifier,
+  isAspectRatioMatched: ios?.fit !== 'target',
+  children: children
+}) : children;
+
+/** UIKit's zoom on the screen's own view controller; the source and target are looked up natively by identifier. */
+const Enabler = ({
+  ios,
+  scrim,
+  sourceIdentifier
+}) => {
+  const theme = useAppTheme();
+  if (!sourceIdentifier) {
+    return null;
+  }
+  const dismissGesture = ios?.dismissGesture ?? 'any';
+  return /*#__PURE__*/_jsx(NativeZoomTransitionEnabler, {
+    dimmingBlur: ios?.blur,
+    dimmingColor: scrim ? theme.color(scrim) : undefined,
+    isDismissalEnabled: dismissGesture !== 'none',
+    isHorizontalDismissalEnabled: dismissGesture === 'any',
+    sourceIdentifier: sourceIdentifier
+  });
+};
+export const ZoomTransition = {
+  Enabler,
+  Source,
+  Target
+};
+//# sourceMappingURL=zoom-transition.ios.js.map

package/lib/module/zoom-transition/zoom-transition.ios.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ZoomTransitionEnabler","NativeZoomTransitionEnabler","ZoomTransitionSource","NativeZoomTransitionSource","ZoomTransitionTarget","NativeZoomTransitionTarget","useAppTheme","jsx","_jsx","Source","children","identifier","Target","ios","isAspectRatioMatched","fit","Enabler","scrim","sourceIdentifier","theme","dismissGesture","dimmingBlur","blur","dimmingColor","color","undefined","isDismissalEnabled","isHorizontalDismissalEnabled","ZoomTransition"],"sourceRoot":"../../../src","sources":["zoom-transition/zoom-transition.ios.tsx"],"mappings":";;AAAA,SACEA,qBAAqB,IAAIC,2BAA2B,EACpDC,oBAAoB,IAAIC,0BAA0B,EAClDC,oBAAoB,IAAIC,0BAA0B,QAC7C,6BAA6B;AACpC,SAAQC,WAAW,QAAO,mBAAmB;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAQ7C,MAAMC,MAAM,GAAGA,CAAC;EAACC,QAAQ;EAAEC;AAAqC,CAAC,KAC/DA,UAAU,gBAAGH,IAAA,CAACL,0BAA0B;EAACQ,UAAU,EAAEA,UAAW;EAAAD,QAAA,EAAEA;AAAQ,CAA6B,CAAC,GAAGA,QAAQ;AAErH,MAAME,MAAM,GAAGA,CAAC;EAACF,QAAQ;EAAEC,UAAU;EAAEE;AAA8B,CAAC,KACpEF,UAAU,gBACRH,IAAA,CAACH,0BAA0B;EAACM,UAAU,EAAEA,UAAW;EAACG,oBAAoB,EAAED,GAAG,EAAEE,GAAG,KAAK,QAAS;EAAAL,QAAA,EAC7FA;AAAQ,CACiB,CAAC,GAE7BA,QACD;;AAEH;AACA,MAAMM,OAAO,GAAGA,CAAC;EAACH,GAAG;EAAEI,KAAK;EAAEC;AAA4C,CAAC,KAAK;EAC9E,MAAMC,KAAK,GAAGb,WAAW,CAAC,CAAC;EAE3B,IAAI,CAACY,gBAAgB,EAAE;IACrB,OAAO,IAAI;EACb;EAEA,MAAME,cAAc,GAAGP,GAAG,EAAEO,cAAc,IAAI,KAAK;EAEnD,oBACEZ,IAAA,CAACP,2BAA2B;IAC1BoB,WAAW,EAAER,GAAG,EAAES,IAAK;IACvBC,YAAY,EAAEN,KAAK,GAAGE,KAAK,CAACK,KAAK,CAACP,KAAK,CAAC,GAAGQ,SAAU;IACrDC,kBAAkB,EAAEN,cAAc,KAAK,MAAO;IAC9CO,4BAA4B,EAAEP,cAAc,KAAK,KAAM;IACvDF,gBAAgB,EAAEA;EAAiB,CACpC,CAAC;AAEN,CAAC;AAED,OAAO,MAAMU,cAAuC,GAAG;EAACZ,OAAO;EAAEP,MAAM;EAAEG;AAAM,CAAC","ignoreList":[]}

package/lib/module/zoom-transition/zoom-transition.types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=zoom-transition.types.js.map

package/lib/module/zoom-transition/zoom-transition.types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["zoom-transition/zoom-transition.types.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/index.d.ts

@@ -1,2 +1,3 @@
 export * from './navigation-theme';
 export * from './tabs';
+export * from './zoom-transition';

package/lib/typescript/zoom-transition/index.d.ts

@@ -0,0 +1,5 @@
+export * from './use-zoom-transition-source-id';
+export * from './with-zoom-transition';
+export * from './zoom-transition';
+export * from './zoom-transition.types';
+export * from './zoom-transition-param';

package/lib/typescript/zoom-transition/use-zoom-transition-source-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An identifier for a `ZoomTransition.Source`, unique to this component instance and to `key` — the item it shows.
+ * Keyed by the item, a recycled list cell registers under a new identifier when it shows another item, so a detail
+ * opened from its previous item zooms back out plainly instead of into the wrong cell.
+ */
+export declare const useZoomTransitionSourceId: (key: string) => string;

package/lib/typescript/zoom-transition/with-zoom-transition.d.ts

@@ -0,0 +1,17 @@
+type RouteProps = {
+    route: {
+        params?: object;
+    };
+};
+type ZoomAnimation = {
+    animation?: 'fade';
+    animationDuration?: number;
+};
+/**
+ * `Stack.Screen` options for a screen the zoom pushes. On Android a push whose params carry `ZOOM_TRANSITION_PARAM`
+ * becomes a quick fade, so Material's container transform reads as the transition instead of racing the stack's own
+ * slide; any other push keeps the stack's animation. Your options win: set `animation` yourself to keep another one.
+ * iOS needs nothing — UIKit's zoom replaces the push animation.
+ */
+export declare const withZoomTransition: <TOptions extends object>(options?: TOptions | ((props: RouteProps) => TOptions)) => (props: RouteProps) => Partial<TOptions> & ZoomAnimation;
+export {};

package/lib/typescript/zoom-transition/zoom-transition-param.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The route param that carries a source's identifier to the screen it pushes — what `withZoomTransition` looks for.
+ * Push with `params: {[ZOOM_TRANSITION_PARAM]: sourceId}` and read it back with `useZoomTransitionParam`.
+ */
+export declare const ZOOM_TRANSITION_PARAM = "zoomTransitionSourceId";
+/** The source identifier this screen was pushed with — for its `ZoomTransition.Enabler` and `Target`. */
+export declare const useZoomTransitionParam: () => string | undefined;

package/lib/typescript/zoom-transition/zoom-transition.d.ts

@@ -0,0 +1 @@
+export * from './zoom-transition.ios';

package/lib/typescript/zoom-transition/zoom-transition.ios.d.ts

@@ -0,0 +1,2 @@
+import type { ZoomTransitionComponent } from './zoom-transition.types';
+export declare const ZoomTransition: ZoomTransitionComponent;

package/lib/typescript/zoom-transition/zoom-transition.types.d.ts

@@ -0,0 +1,93 @@
+import type { ColorToken, DurationSize, RadiiSize } from '@hzblj/kara-theme';
+import type { ReactElement, ReactNode } from 'react';
+export type ZoomTransitionSourceAndroidOptions = {
+    /** The corners the transform starts with — the source's own rounding (iOS reads the view's own). Default `none`. */
+    borderRadius?: RadiiSize;
+};
+export type ZoomTransitionSourceProps = {
+    /** Android-only settings. */
+    android?: ZoomTransitionSourceAndroidOptions;
+    /** A single view — the photo or card the zoom grows from. */
+    children: ReactElement;
+    /** Unset renders `children` alone: no zoom from here. Use `useZoomTransitionSourceId` for one unique per item. */
+    identifier?: string;
+};
+export type ZoomTransitionTargetIosOptions = {
+    /**
+     * What the source lands on. `source` (default): a rect of the source's aspect ratio centred in the target, so
+     * nothing is stretched. `target`: the whole target.
+     */
+    fit?: 'source' | 'target';
+};
+export type ZoomTransitionTargetAndroidOptions = {
+    /** The corners the transform ends with — the target's own rounding. Default `none`. */
+    borderRadius?: RadiiSize;
+    /**
+     * What the source lands on. `target` (default): the whole target. `photo`: the photo inside it — where a `contain`
+     * photo sits in a tall page — with the photo's cropped edges fading in on the way.
+     */
+    fit?: 'photo' | 'target';
+    /** The Android target is a real layout box (iOS adds none): give it `flex` when its child fills the parent. */
+    flex?: number;
+};
+export type ZoomTransitionTargetProps = {
+    /** Android-only settings. */
+    android?: ZoomTransitionTargetAndroidOptions;
+    /** A single view — what the source lands on in the pushed screen. */
+    children: ReactElement;
+    /** The source's identifier, handed over in the route params. Unset renders `children` alone. */
+    identifier?: string;
+    /** iOS-only settings. */
+    ios?: ZoomTransitionTargetIosOptions;
+};
+/**
+ * Which of UIKit's gestures may dismiss the screen back into its source. `any`: swipe down, edge swipe and pinch — a
+ * swipe only once no scroll view under the finger can still scroll that way. `vertical`: a downward swipe only, for
+ * content that pages sideways under its own gestures (a gallery). `none`: the back button only.
+ */
+export type ZoomTransitionDismissGesture = 'any' | 'none' | 'vertical';
+export type ZoomTransitionEnablerIosOptions = {
+    /** A system material blurring the screen behind the zoomed one. Default none. */
+    blur?: 'regular' | 'thick' | 'thin' | 'ultraThin';
+    /** Default `any`. */
+    dismissGesture?: ZoomTransitionDismissGesture;
+};
+export type ZoomTransitionEnablerAndroidOptions = {
+    /** Default `d450`. iOS's zoom is UIKit's own spring. */
+    duration?: DurationSize;
+    /** Default `emphasized` (Material 3, `0.2, 0, 0, 1`); `standard` is `0.4, 0, 0.2, 1`, `decelerate` `0, 0, 0, 1`. */
+    easing?: 'decelerate' | 'emphasized' | 'linear' | 'standard';
+    /** How the two screens' contents fade into each other inside the container. Default `cross`. */
+    fade?: 'cross' | 'in' | 'out' | 'through';
+    /** The path the container travels. Default `arc`. */
+    path?: 'arc' | 'linear';
+};
+export type ZoomTransitionEnablerProps = {
+    /** Android-only settings: Material's container transform. */
+    android?: ZoomTransitionEnablerAndroidOptions;
+    /** iOS-only settings: UIKit's zoom. */
+    ios?: ZoomTransitionEnablerIosOptions;
+    /** Laid over the screen behind the zoomed one. Unset: UIKit's own dimming on iOS, none on Android. */
+    scrim?: ColorToken;
+    /** The source's identifier, handed over in the route params. Unset renders nothing: the push stays the stack's own. */
+    sourceIdentifier?: string;
+};
+/**
+ * A push that grows out of the view it was opened from — a photo into its detail — and shrinks back into it. iOS 18:
+ * UIKit's zoom transition (`preferredTransition = .zoom`), interactive dismissal included; below iOS 18 the push stays
+ * the regular slide. Android: Material's container transform from the source to the target, both ways.
+ *
+ * Three pieces, tied by one identifier: `Source` around the view on the screen you push from, `Enabler` and `Target`
+ * on the pushed screen. Works with any Expo Router stack screen.
+ */
+export type ZoomTransitionComponent = {
+    /**
+     * Turns the push of the screen it is rendered in into the zoom, and carries the animation settings. Render it
+     * unconditionally, before any loading state: on iOS it has to exist in the screen's first commit.
+     */
+    Enabler: (props: ZoomTransitionEnablerProps) => ReactNode;
+    /** Marks the view the zoom grows from. Inside a `ContextMenu`, a tap on the preview zooms the preview's photo. */
+    Source: (props: ZoomTransitionSourceProps) => ReactNode;
+    /** Marks what the source lands on in the pushed screen. It may render later than the enabler, once data arrives. */
+    Target: (props: ZoomTransitionTargetProps) => ReactNode;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-router",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Expo Router pieces of @hzblj/kara-ui: native tabs and a navigation theme mapped from the active kara theme.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -59,9 +59,9 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-components": "^0.4.0",
-    "@hzblj/kara-native": "^0.4.0",
-    "@hzblj/kara-theme": "^0.4.0"
+    "@hzblj/kara-components": "^0.5.0",
+    "@hzblj/kara-native": "^0.5.0",
+    "@hzblj/kara-theme": "^0.5.0"
   },
   "peerDependencies": {
     "expo-router": "*",

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './navigation-theme'
 export * from './tabs'
+export * from './zoom-transition'

package/src/zoom-transition/index.ts

@@ -0,0 +1,5 @@
+export * from './use-zoom-transition-source-id'
+export * from './with-zoom-transition'
+export * from './zoom-transition'
+export * from './zoom-transition.types'
+export * from './zoom-transition-param'

package/src/zoom-transition/use-zoom-transition-source-id.ts

@@ -0,0 +1,8 @@
+import {useId} from 'react'
+
+/**
+ * An identifier for a `ZoomTransition.Source`, unique to this component instance and to `key` — the item it shows.
+ * Keyed by the item, a recycled list cell registers under a new identifier when it shows another item, so a detail
+ * opened from its previous item zooms back out plainly instead of into the wrong cell.
+ */
+export const useZoomTransitionSourceId = (key: string) => `${useId()}${key}`

package/src/zoom-transition/with-zoom-transition.ts

@@ -0,0 +1,28 @@
+import {duration} from '@hzblj/kara-theme'
+import {Platform} from 'react-native'
+import {ZOOM_TRANSITION_PARAM} from './zoom-transition-param'
+
+type RouteProps = {route: {params?: object}}
+
+type ZoomAnimation = {animation?: 'fade'; animationDuration?: number}
+
+const hasZoomSource = (params: object | undefined) =>
+  !!params && !!(params as Record<string, unknown>)[ZOOM_TRANSITION_PARAM]
+
+/**
+ * `Stack.Screen` options for a screen the zoom pushes. On Android a push whose params carry `ZOOM_TRANSITION_PARAM`
+ * becomes a quick fade, so Material's container transform reads as the transition instead of racing the stack's own
+ * slide; any other push keeps the stack's animation. Your options win: set `animation` yourself to keep another one.
+ * iOS needs nothing — UIKit's zoom replaces the push animation.
+ */
+export const withZoomTransition =
+  <TOptions extends object>(options?: TOptions | ((props: RouteProps) => TOptions)) =>
+  (props: RouteProps): Partial<TOptions> & ZoomAnimation => {
+    const resolved: Partial<TOptions> = (typeof options === 'function' ? options(props) : options) ?? {}
+
+    if (Platform.OS !== 'android' || !hasZoomSource(props.route.params)) {
+      return resolved
+    }
+
+    return {animation: 'fade', animationDuration: duration.d300, ...resolved}
+  }

package/src/zoom-transition/zoom-transition-param.ts

@@ -0,0 +1,14 @@
+import {useLocalSearchParams} from 'expo-router'
+
+/**
+ * The route param that carries a source's identifier to the screen it pushes — what `withZoomTransition` looks for.
+ * Push with `params: {[ZOOM_TRANSITION_PARAM]: sourceId}` and read it back with `useZoomTransitionParam`.
+ */
+export const ZOOM_TRANSITION_PARAM = 'zoomTransitionSourceId'
+
+/** The source identifier this screen was pushed with — for its `ZoomTransition.Enabler` and `Target`. */
+export const useZoomTransitionParam = (): string | undefined => {
+  const value = useLocalSearchParams()[ZOOM_TRANSITION_PARAM]
+
+  return (Array.isArray(value) ? value[0] : value) || undefined
+}

package/src/zoom-transition/zoom-transition.android.tsx

@@ -0,0 +1,81 @@
+import {
+  ZoomTransitionEnabler as NativeZoomTransitionEnabler,
+  ZoomTransitionSource as NativeZoomTransitionSource,
+  ZoomTransitionTarget as NativeZoomTransitionTarget,
+  reverseZoomTransition,
+} from '@hzblj/kara-native/jetpack-compose'
+import {duration, radii, useAppTheme} from '@hzblj/kara-theme'
+import {useNavigation} from 'expo-router'
+import {useEffect, useMemo} from 'react'
+import type {
+  ZoomTransitionComponent,
+  ZoomTransitionEnablerProps,
+  ZoomTransitionSourceProps,
+  ZoomTransitionTargetProps,
+} from './zoom-transition.types'
+
+const Source = ({android, children, identifier}: ZoomTransitionSourceProps) =>
+  identifier ? (
+    <NativeZoomTransitionSource cornerRadius={radii[android?.borderRadius ?? 'none']} identifier={identifier}>
+      {children}
+    </NativeZoomTransitionSource>
+  ) : (
+    children
+  )
+
+const Target = ({android, children, identifier}: ZoomTransitionTargetProps) => {
+  const flex = android?.flex
+  const style = useMemo(() => (flex === undefined ? undefined : {flex}), [flex])
+
+  if (!identifier) {
+    return children
+  }
+
+  return (
+    <NativeZoomTransitionTarget
+      cornerRadius={radii[android?.borderRadius ?? 'none']}
+      identifier={identifier}
+      isFittedToSourceAspectRatio={android?.fit === 'photo'}
+      style={style}
+    >
+      {children}
+    </NativeZoomTransitionTarget>
+  )
+}
+
+/**
+ * The target starts the way in natively once it is laid out. The way back cannot wait for the target to go: the pop is
+ * native, and by the time the screen unmounts it is already sliding away. So the transform is played back from
+ * `beforeRemove`, while the target is still on screen.
+ */
+const Enabler = ({android, scrim, sourceIdentifier}: ZoomTransitionEnablerProps) => {
+  const navigation = useNavigation()
+  const theme = useAppTheme()
+
+  useEffect(() => {
+    if (!sourceIdentifier) {
+      return
+    }
+
+    return navigation.addListener('beforeRemove', () => {
+      void reverseZoomTransition(sourceIdentifier)
+    })
+  }, [navigation, sourceIdentifier])
+
+  if (!sourceIdentifier) {
+    return null
+  }
+
+  return (
+    <NativeZoomTransitionEnabler
+      easing={android?.easing}
+      fadeMode={android?.fade}
+      pathMotion={android?.path}
+      scrimColor={scrim ? theme.color(scrim) : undefined}
+      sourceIdentifier={sourceIdentifier}
+      transformDuration={android?.duration ? duration[android.duration] : undefined}
+    />
+  )
+}
+
+export const ZoomTransition: ZoomTransitionComponent = {Enabler, Source, Target}

package/src/zoom-transition/zoom-transition.ios.tsx

@@ -0,0 +1,47 @@
+import {
+  ZoomTransitionEnabler as NativeZoomTransitionEnabler,
+  ZoomTransitionSource as NativeZoomTransitionSource,
+  ZoomTransitionTarget as NativeZoomTransitionTarget,
+} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import type {
+  ZoomTransitionComponent,
+  ZoomTransitionEnablerProps,
+  ZoomTransitionSourceProps,
+  ZoomTransitionTargetProps,
+} from './zoom-transition.types'
+
+const Source = ({children, identifier}: ZoomTransitionSourceProps) =>
+  identifier ? <NativeZoomTransitionSource identifier={identifier}>{children}</NativeZoomTransitionSource> : children
+
+const Target = ({children, identifier, ios}: ZoomTransitionTargetProps) =>
+  identifier ? (
+    <NativeZoomTransitionTarget identifier={identifier} isAspectRatioMatched={ios?.fit !== 'target'}>
+      {children}
+    </NativeZoomTransitionTarget>
+  ) : (
+    children
+  )
+
+/** UIKit's zoom on the screen's own view controller; the source and target are looked up natively by identifier. */
+const Enabler = ({ios, scrim, sourceIdentifier}: ZoomTransitionEnablerProps) => {
+  const theme = useAppTheme()
+
+  if (!sourceIdentifier) {
+    return null
+  }
+
+  const dismissGesture = ios?.dismissGesture ?? 'any'
+
+  return (
+    <NativeZoomTransitionEnabler
+      dimmingBlur={ios?.blur}
+      dimmingColor={scrim ? theme.color(scrim) : undefined}
+      isDismissalEnabled={dismissGesture !== 'none'}
+      isHorizontalDismissalEnabled={dismissGesture === 'any'}
+      sourceIdentifier={sourceIdentifier}
+    />
+  )
+}
+
+export const ZoomTransition: ZoomTransitionComponent = {Enabler, Source, Target}

package/src/zoom-transition/zoom-transition.types.ts

@@ -0,0 +1,108 @@
+import type {ColorToken, DurationSize, RadiiSize} from '@hzblj/kara-theme'
+import type {ReactElement, ReactNode} from 'react'
+
+/*
+ * Every prop at the top level works on both platforms. What only one platform can do lives under `ios` or `android`,
+ * typed apart, and is ignored on the other — so a call site reads which of its settings each platform honours.
+ */
+
+export type ZoomTransitionSourceAndroidOptions = {
+  /** The corners the transform starts with — the source's own rounding (iOS reads the view's own). Default `none`. */
+  borderRadius?: RadiiSize
+}
+
+export type ZoomTransitionSourceProps = {
+  /** Android-only settings. */
+  android?: ZoomTransitionSourceAndroidOptions
+  /** A single view — the photo or card the zoom grows from. */
+  children: ReactElement
+  /** Unset renders `children` alone: no zoom from here. Use `useZoomTransitionSourceId` for one unique per item. */
+  identifier?: string
+}
+
+export type ZoomTransitionTargetIosOptions = {
+  /**
+   * What the source lands on. `source` (default): a rect of the source's aspect ratio centred in the target, so
+   * nothing is stretched. `target`: the whole target.
+   */
+  fit?: 'source' | 'target'
+}
+
+export type ZoomTransitionTargetAndroidOptions = {
+  /** The corners the transform ends with — the target's own rounding. Default `none`. */
+  borderRadius?: RadiiSize
+  /**
+   * What the source lands on. `target` (default): the whole target. `photo`: the photo inside it — where a `contain`
+   * photo sits in a tall page — with the photo's cropped edges fading in on the way.
+   */
+  fit?: 'photo' | 'target'
+  /** The Android target is a real layout box (iOS adds none): give it `flex` when its child fills the parent. */
+  flex?: number
+}
+
+export type ZoomTransitionTargetProps = {
+  /** Android-only settings. */
+  android?: ZoomTransitionTargetAndroidOptions
+  /** A single view — what the source lands on in the pushed screen. */
+  children: ReactElement
+  /** The source's identifier, handed over in the route params. Unset renders `children` alone. */
+  identifier?: string
+  /** iOS-only settings. */
+  ios?: ZoomTransitionTargetIosOptions
+}
+
+/**
+ * Which of UIKit's gestures may dismiss the screen back into its source. `any`: swipe down, edge swipe and pinch — a
+ * swipe only once no scroll view under the finger can still scroll that way. `vertical`: a downward swipe only, for
+ * content that pages sideways under its own gestures (a gallery). `none`: the back button only.
+ */
+export type ZoomTransitionDismissGesture = 'any' | 'none' | 'vertical'
+
+export type ZoomTransitionEnablerIosOptions = {
+  /** A system material blurring the screen behind the zoomed one. Default none. */
+  blur?: 'regular' | 'thick' | 'thin' | 'ultraThin'
+  /** Default `any`. */
+  dismissGesture?: ZoomTransitionDismissGesture
+}
+
+export type ZoomTransitionEnablerAndroidOptions = {
+  /** Default `d450`. iOS's zoom is UIKit's own spring. */
+  duration?: DurationSize
+  /** Default `emphasized` (Material 3, `0.2, 0, 0, 1`); `standard` is `0.4, 0, 0.2, 1`, `decelerate` `0, 0, 0, 1`. */
+  easing?: 'decelerate' | 'emphasized' | 'linear' | 'standard'
+  /** How the two screens' contents fade into each other inside the container. Default `cross`. */
+  fade?: 'cross' | 'in' | 'out' | 'through'
+  /** The path the container travels. Default `arc`. */
+  path?: 'arc' | 'linear'
+}
+
+export type ZoomTransitionEnablerProps = {
+  /** Android-only settings: Material's container transform. */
+  android?: ZoomTransitionEnablerAndroidOptions
+  /** iOS-only settings: UIKit's zoom. */
+  ios?: ZoomTransitionEnablerIosOptions
+  /** Laid over the screen behind the zoomed one. Unset: UIKit's own dimming on iOS, none on Android. */
+  scrim?: ColorToken
+  /** The source's identifier, handed over in the route params. Unset renders nothing: the push stays the stack's own. */
+  sourceIdentifier?: string
+}
+
+/**
+ * A push that grows out of the view it was opened from — a photo into its detail — and shrinks back into it. iOS 18:
+ * UIKit's zoom transition (`preferredTransition = .zoom`), interactive dismissal included; below iOS 18 the push stays
+ * the regular slide. Android: Material's container transform from the source to the target, both ways.
+ *
+ * Three pieces, tied by one identifier: `Source` around the view on the screen you push from, `Enabler` and `Target`
+ * on the pushed screen. Works with any Expo Router stack screen.
+ */
+export type ZoomTransitionComponent = {
+  /**
+   * Turns the push of the screen it is rendered in into the zoom, and carries the animation settings. Render it
+   * unconditionally, before any loading state: on iOS it has to exist in the screen's first commit.
+   */
+  Enabler: (props: ZoomTransitionEnablerProps) => ReactNode
+  /** Marks the view the zoom grows from. Inside a `ContextMenu`, a tap on the preview zooms the preview's photo. */
+  Source: (props: ZoomTransitionSourceProps) => ReactNode
+  /** Marks what the source lands on in the pushed screen. It may render later than the enabler, once data arrives. */
+  Target: (props: ZoomTransitionTargetProps) => ReactNode
+}