Add comments

Author: istarkov

packages/sdk-components-animation/src/scroll.tsx

@@ -25,6 +25,13 @@ const createSelector = (id: string) => `[${componentAttributeId}="${id}"] > *`;
 const cartesian = <A, B>(a: A[], b: B[]) =>
   a.flatMap((x) => b.map((y) => [x, y] as const));
 
+/**
+ * Scroll does not support https://drafts.csswg.org/scroll-animations/#named-ranges
+ * However, for simplicity and type unification with the view, we will use the names "start" and "end,"
+ * which will be transformed as follows:
+ * - "start" → `calc(0% + range)`
+ * - "end" → `calc(100% - range)`
+ */
 const getScrollRangeValue = ([name, value]: ScrollRangeValue) => {
   // See also WAAPI has bug https://issues.chromium.org/issues/40929569#comment9
   // so we are using calc even it it's not needed in some cases
@@ -79,6 +86,7 @@ const Animate = ({ id, action }: { id: string; action: AnimationAction }) => {
             const keyframe: Keyframe = {
               offset: animationKeyframe.offset,
               composite: "auto",
+              // Probably having linear() easing we don't need easing per keyframe
               // easing: animationKeyframe.easing,
             };
 
@@ -114,6 +122,16 @@ const Animate = ({ id, action }: { id: string; action: AnimationAction }) => {
   return undefined;
 };
 
+/**
+ * We use JavaScript to execute animations.
+ * For animations that run initially, such as scroll or view-based animations,
+ * we need to set the initial position during server rendering.
+ *
+ * On the client side, there's another issue: we use Scroll and View Timeline polyfills.
+ * These polyfills must be loaded dynamically because they rely on the `window` object globally,
+ * making them incompatible with standard imports.
+ * Similarly, for SSR, we need to set styles if the polyfill hasn't loaded yet.
+ */
 const StylesBeforeAnimate = ({
   id,
   action,
@@ -141,6 +159,8 @@ const StylesBeforeAnimate = ({
       ([property, value]) => `${hyphenateProperty(property)}:${toValue(value)};`
     );
 
+    // We use animation to set initial styles to ensure the exact same behavior
+    // (including specificity and keyframe composition) as the animation executed afterward.
     styleContent = `
     ${styleContent}
 
@@ -171,6 +191,7 @@ type ScrollProps = {
   action: AnimationAction;
 };
 
+// @todo: With high probablity it will be unified animation object
 export const Scroll = forwardRef<ElementRef<"div">, ScrollProps>(
   ({ debug = false, children, action }, ref) => {
     const nakedId = useId();