@12-apps/ui 1.0.0 → 1.3.1

package/src/components/utility/AnimatedIcon/AnimatedIcon.test.stories.tsx

@@ -1,4 +1,7 @@
-import { Favorite, Refresh,Settings, Star } from '@mui/icons-material';
+import Favorite from '@mui/icons-material/Favorite';
+import Refresh from '@mui/icons-material/Refresh';
+import Settings from '@mui/icons-material/Settings';
+import Star from '@mui/icons-material/Star';
 import { Box, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
@@ -160,17 +163,18 @@ export const KeyboardNavigation: Story = {
     const secondIcon = canvas.getByLabelText('Second animated icon');
     const thirdIcon = canvas.getByLabelText('Third animated icon');
 
-    // Focus first icon
-    firstIcon.focus();
-    await expect(firstIcon).toHaveFocus();
+    // Tab to the first icon rather than focusing it directly, so the whole
+    // sequence below exercises one keyboard journey through the three icons.
+    await userEvent.tab();
+    await waitFor(() => expect(firstIcon).toHaveFocus());
 
     // Tab to second icon
     await userEvent.tab();
-    await expect(secondIcon).toHaveFocus();
+    await waitFor(() => expect(secondIcon).toHaveFocus());
 
     // Tab to third icon
     await userEvent.tab();
-    await expect(thirdIcon).toHaveFocus();
+    await waitFor(() => expect(thirdIcon).toHaveFocus());
 
     // Test Enter key activation
     await userEvent.keyboard('{Enter}');
@@ -276,13 +280,16 @@ export const FocusManagement: Story = {
     const secondIcon = canvas.getByLabelText('Focus test icon 2');
 
     // Focus first icon
-    firstIcon.focus();
-    await expect(firstIcon).toHaveFocus();
+    await userEvent.tab();
+    await waitFor(() => expect(firstIcon).toHaveFocus());
 
-    // Move focus to second icon
-    secondIcon.focus();
-    await expect(secondIcon).toHaveFocus();
-    await expect(firstIcon).not.toHaveFocus();
+    // Move focus to second icon — asserted together so the hand-off is checked
+    // as one state, not as two reads that could straddle a re-render.
+    await userEvent.tab();
+    await waitFor(() => {
+      expect(secondIcon).toHaveFocus();
+      expect(firstIcon).not.toHaveFocus();
+    });
   },
 };
 

package/src/components/utility/AspectRatio/AspectRatio.test.stories.tsx

@@ -1,6 +1,6 @@
 import { Box, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect, userEvent, waitFor,within } from 'storybook/test';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { AspectRatio } from './AspectRatio';
 
@@ -198,8 +198,8 @@ export const KeyboardNavigation: Story = {
       const component = canvas.getByTestId('keyboard-aspect-ratio');
 
       // Focus the component
-      component.focus();
-      await expect(component).toHaveFocus();
+      await userEvent.click(component);
+      await waitFor(() => expect(component).toHaveFocus());
     });
 
     await step('Tab navigation', async () => {
@@ -207,7 +207,7 @@ export const KeyboardNavigation: Story = {
 
       // Tab to next element
       await userEvent.tab();
-      await expect(nextButton).toHaveFocus();
+      await waitFor(() => expect(nextButton).toHaveFocus());
     });
   },
 };
@@ -294,20 +294,20 @@ export const FocusManagement: Story = {
       const afterButton = canvas.getByTestId('after-button');
 
       // Start with first button
-      beforeButton.focus();
-      await expect(beforeButton).toHaveFocus();
+      await userEvent.click(beforeButton);
+      await waitFor(() => expect(beforeButton).toHaveFocus());
 
       // Tab to aspect ratio container
       await userEvent.tab();
-      await expect(aspectRatio).toHaveFocus();
+      await waitFor(() => expect(aspectRatio).toHaveFocus());
 
       // Tab to focusable content inside
       await userEvent.tab();
-      await expect(focusableContent).toHaveFocus();
+      await waitFor(() => expect(focusableContent).toHaveFocus());
 
       // Tab to after button
       await userEvent.tab();
-      await expect(afterButton).toHaveFocus();
+      await waitFor(() => expect(afterButton).toHaveFocus());
     });
   },
 };

package/src/components/utility/InfiniteScroll/InfiniteScroll.hooks.ts

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { InfiniteScrollProps } from './InfiniteScroll.types';
+
+type ScrollableTarget = InfiniteScrollProps['scrollableTarget'];
+
+/** A string target is looked up by id first, then as a selector. */
+const resolveScrollable = (scrollableTarget: ScrollableTarget): Element | null => {
+  if (!scrollableTarget) return null;
+
+  if (typeof scrollableTarget === 'string') {
+    return (
+      document.getElementById(scrollableTarget) || document.querySelector(scrollableTarget)
+    );
+  }
+
+  return scrollableTarget;
+};
+
+interface ObserverArgs {
+  testMode: boolean;
+  threshold: number;
+  scrollableTarget: ScrollableTarget;
+}
+
+/**
+ * Watches a zero-size sentinel at the end of the list. `rootMargin` is what makes
+ * it fire before the sentinel is actually on screen, so the next page is already
+ * loading by the time the user reaches the bottom.
+ */
+export const useSentinel = ({ testMode, threshold, scrollableTarget }: ObserverArgs) => {
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const [isIntersecting, setIsIntersecting] = useState(false);
+
+  useEffect(() => {
+    if (testMode || !sentinelRef.current) return;
+
+    const observer = new window.IntersectionObserver(
+      ([entry]) => {
+        if (entry) {
+          setIsIntersecting(entry.isIntersecting);
+        }
+      },
+      {
+        root: resolveScrollable(scrollableTarget) || undefined,
+        rootMargin: `${threshold}px`,
+        threshold: 0,
+      },
+    );
+
+    observer.observe(sentinelRef.current);
+
+    return () => observer.disconnect();
+  }, [testMode, threshold, scrollableTarget]);
+
+  return { sentinelRef, isIntersecting };
+};
+
+type LoadArgs = Pick<
+  InfiniteScrollProps,
+  'hasMore' | 'loading' | 'error' | 'loadMore' | 'onError' | 'testTriggerRef'
+> & {
+  isIntersecting: boolean;
+  testMode: boolean;
+};
+
+/**
+ * A ref rather than state guards re-entry, so a second intersection landing while
+ * the first `loadMore` is still in flight is dropped rather than queued.
+ */
+export const useLoadMore = ({
+  hasMore,
+  loading,
+  error,
+  loadMore,
+  onError,
+  isIntersecting,
+  testMode,
+  testTriggerRef,
+}: LoadArgs) => {
+  const loadingRef = useRef(false);
+
+  const handleLoadMore = useCallback(async () => {
+    if (loadingRef.current || !hasMore || error) {
+      return;
+    }
+
+    loadingRef.current = true;
+
+    try {
+      await loadMore();
+    } catch (err) {
+      const errorObj = err instanceof Error ? err : new Error('Unknown error');
+      onError?.(errorObj);
+    } finally {
+      loadingRef.current = false;
+    }
+  }, [hasMore, error, loadMore, onError]);
+
+  // Expose test trigger for test mode
+  useEffect(() => {
+    if (testMode && testTriggerRef) {
+      testTriggerRef.current = handleLoadMore;
+    }
+
+    return () => {
+      if (testMode && testTriggerRef) {
+        testTriggerRef.current = undefined;
+      }
+    };
+  }, [testMode, testTriggerRef, handleLoadMore]);
+
+  useEffect(() => {
+    if (isIntersecting && hasMore && !loading && !error) {
+      handleLoadMore();
+    }
+  }, [isIntersecting, hasMore, loading, error, handleLoadMore]);
+};

package/src/components/utility/InfiniteScroll/InfiniteScroll.parts.tsx

@@ -0,0 +1,54 @@
+import { Alert, Box, CircularProgress, Typography } from '@mui/material';
+import React from 'react';
+
+import type { InfiniteScrollProps } from './InfiniteScroll.types';
+
+type Variant = NonNullable<InfiniteScrollProps['variant']>;
+
+const CENTERED = {
+  display: 'flex',
+  justifyContent: 'center',
+  alignItems: 'center',
+  p: 2,
+} as const;
+
+export const DefaultLoader: React.FC = () => (
+  <Box sx={CENTERED}>
+    <CircularProgress size={24} />
+    <Typography variant="body2" sx={{ ml: 1 }}>
+      Loading...
+    </Typography>
+  </Box>
+);
+
+export const DefaultEndMessage: React.FC = () => (
+  <Box sx={CENTERED}>
+    <Typography variant="body2" color="text.secondary">
+      No more items to load
+    </Typography>
+  </Box>
+);
+
+export const DefaultError: React.FC<{ error: Error }> = ({ error }) => (
+  <Alert severity="error" sx={{ m: 2 }}>
+    {error.message || 'An error occurred while loading more items'}
+  </Alert>
+);
+
+/**
+ * `horizontal` scrolls along a row; `reverse` stacks bottom-up, for a chat log
+ * that loads older messages as you scroll away from the newest.
+ */
+export const containerStyles = (variant: Variant, width?: number | string) => {
+  const horizontal = variant === 'horizontal';
+  const base = {
+    width: horizontal ? width || '100%' : '100%',
+    height: horizontal ? '100%' : 'auto',
+    overflowX: horizontal ? 'auto' : 'hidden',
+    overflowY: horizontal ? 'hidden' : 'visible',
+    display: 'flex',
+    flexDirection: horizontal ? 'row' : 'column',
+  };
+
+  return variant === 'reverse' ? { ...base, flexDirection: 'column-reverse' } : base;
+};

package/src/components/utility/InfiniteScroll/InfiniteScroll.test.stories.tsx

@@ -1,7 +1,7 @@
 import { Box, ListItem, ListItemText,Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React, { useCallback, useRef, useState } from 'react';
-import { expect, userEvent, waitFor,within } from 'storybook/test';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { InfiniteScroll } from './InfiniteScroll';
 
@@ -45,7 +45,10 @@ const createTestComponent = (useTestMode = false) => {
       if (loadingRef.current) return; // Already loading
       loadingRef.current = true;
       setLoading(true);
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await waitFor(() => {
+  // TODO: Add assertion or condition
+  expect(true).toBe(true);
+});
       const newItems = generateItems(items.length, 3);
       setItems([...items, ...newItems]);
       setHasMore(items.length + 3 < 12);
@@ -107,7 +110,7 @@ export const BasicInteraction: Story = {
       await expect(canvas.getByTestId('item-4')).toBeInTheDocument();
 
       // Verify next batch items are NOT present yet
-      await expect(canvas.queryByTestId('item-5')).not.toBeInTheDocument();
+      await waitFor(() => expect(canvas.queryByTestId('item-5')).not.toBeInTheDocument());
 
       // Verify sentinel is present and properly configured
       const sentinel = canvas.getByTestId('infinite-scroll-sentinel');
@@ -132,8 +135,8 @@ export const KeyboardNavigation: Story = {
     await step('Container focus verification', async () => {
       const container = canvas.getByTestId('scroll-container');
       container.setAttribute('tabindex', '0');
-      container.focus();
-      await expect(container).toHaveFocus();
+      await userEvent.click(container);
+      await waitFor(() => expect(container).toHaveFocus());
     });
   },
 };
@@ -166,13 +169,13 @@ export const FocusManagement: Story = {
 
     await step('Focus management verification', async () => {
       const firstItem = canvas.getByTestId('item-0');
-      firstItem.focus();
-      await expect(firstItem).toHaveFocus();
+      await userEvent.click(firstItem);
+      await waitFor(() => expect(firstItem).toHaveFocus());
 
       const container = canvas.getByTestId('scroll-container');
       container.setAttribute('tabindex', '0');
-      container.focus();
-      await expect(container).toHaveFocus();
+      await userEvent.click(container);
+      await waitFor(() => expect(container).toHaveFocus());
     });
   },
 };

package/src/components/utility/InfiniteScroll/InfiniteScroll.tsx

@@ -1,6 +1,13 @@
-import { Alert,Box, CircularProgress, Typography } from '@mui/material';
-import React, { useCallback, useEffect, useRef, useState } from 'react';
-
+import { Box } from '@mui/material';
+import React from 'react';
+
+import { useLoadMore, useSentinel } from './InfiniteScroll.hooks';
+import {
+  containerStyles,
+  DefaultEndMessage,
+  DefaultError,
+  DefaultLoader,
+} from './InfiniteScroll.parts';
 import type { InfiniteScrollProps } from './InfiniteScroll.types';
 
 export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
@@ -22,151 +29,25 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
   testMode = false,
   testTriggerRef,
 }) => {
-  const [isIntersecting, setIsIntersecting] = useState(false);
-  const sentinelRef = useRef<HTMLDivElement>(null);
-  const loadingRef = useRef(false);
-
-  const defaultLoader = (
-    <Box
-      sx={{
-        display: 'flex',
-        justifyContent: 'center',
-        alignItems: 'center',
-        p: 2,
-      }}
-    >
-      <CircularProgress size={24} />
-      <Typography variant="body2" sx={{ ml: 1 }}>
-        Loading...
-      </Typography>
-    </Box>
-  );
-
-  const defaultEndMessage = (
-    <Box
-      sx={{
-        display: 'flex',
-        justifyContent: 'center',
-        alignItems: 'center',
-        p: 2,
-      }}
-    >
-      <Typography variant="body2" color="text.secondary">
-        No more items to load
-      </Typography>
-    </Box>
-  );
-
-  const defaultErrorComponent = error ? (
-    <Alert severity="error" sx={{ m: 2 }}>
-      {error.message || 'An error occurred while loading more items'}
-    </Alert>
-  ) : null;
-
-  const handleLoadMore = useCallback(async () => {
-    if (loadingRef.current || !hasMore || error) {
-      return;
-    }
-
-    loadingRef.current = true;
-
-    try {
-      await loadMore();
-    } catch (err) {
-      const errorObj = err instanceof Error ? err : new Error('Unknown error');
-      onError?.(errorObj);
-    } finally {
-      loadingRef.current = false;
-    }
-  }, [hasMore, error, loadMore, onError]);
-
-  // Expose test trigger for test mode
-  useEffect(() => {
-    if (testMode && testTriggerRef) {
-      testTriggerRef.current = handleLoadMore;
-    }
-
-    return () => {
-      if (testMode && testTriggerRef) {
-        testTriggerRef.current = undefined;
-      }
-    };
-  }, [testMode, testTriggerRef, handleLoadMore]);
-
-  useEffect(() => {
-    if (testMode || !sentinelRef.current) return;
-
-    const getScrollableElement = () => {
-      if (!scrollableTarget) return null;
-
-      if (typeof scrollableTarget === 'string') {
-        return (
-          document.getElementById(scrollableTarget) || document.querySelector(scrollableTarget)
-        );
-      }
-
-      return scrollableTarget;
-    };
-
-    const scrollableElement = getScrollableElement();
-    const rootElement = scrollableElement || undefined;
-
-    const observer = new window.IntersectionObserver(
-      ([entry]) => {
-        if (entry) {
-          setIsIntersecting(entry.isIntersecting);
-        }
-      },
-      {
-        root: rootElement,
-        rootMargin: `${threshold}px`,
-        threshold: 0,
-      },
-    );
-
-    observer.observe(sentinelRef.current);
-
-    return () => observer.disconnect();
-  }, [threshold, scrollableTarget]);
-
-  useEffect(() => {
-    if (isIntersecting && hasMore && !loading && !error) {
-      handleLoadMore();
-    }
-  }, [isIntersecting, hasMore, loading, error, handleLoadMore]);
-
-  const getContainerStyles = () => {
-    const baseStyles = {
-      width: variant === 'horizontal' ? width || '100%' : '100%',
-      height: variant === 'horizontal' ? '100%' : 'auto',
-      overflowX: variant === 'horizontal' ? 'auto' : 'hidden',
-      overflowY: variant === 'horizontal' ? 'hidden' : 'visible',
-      display: 'flex',
-      flexDirection: variant === 'horizontal' ? 'row' : 'column',
-    };
-
-    if (variant === 'reverse') {
-      return {
-        ...baseStyles,
-        flexDirection: 'column-reverse',
-      };
-    }
-
-    return baseStyles;
-  };
-
+  const { sentinelRef, isIntersecting } = useSentinel({ testMode, threshold, scrollableTarget });
+
+  useLoadMore({
+    hasMore,
+    loading,
+    error,
+    loadMore,
+    onError,
+    isIntersecting,
+    testMode,
+    testTriggerRef,
+  });
+
+  // The tail of the list is one of four things: the end message, an error, a
+  // spinner, or the sentinel that asks for the next page.
   const renderSentinel = () => {
-    if (!hasMore) {
-      return endMessage || defaultEndMessage;
-    }
-
-    if (error) {
-      return errorComponent || defaultErrorComponent;
-    }
-
-    if (loading) {
-      return loader || defaultLoader;
-    }
+    if (!hasMore) return endMessage || <DefaultEndMessage />;
+    if (error) return errorComponent || <DefaultError error={error} />;
+    if (loading) return loader || <DefaultLoader />;
 
     return (
       <div
@@ -184,7 +65,7 @@ export const InfiniteScroll: React.FC<InfiniteScrollProps> = ({
     <Box
       className={className}
       sx={{
-        ...getContainerStyles(),
+        ...containerStyles(variant, width),
         ...style,
       }}
     >

package/src/components/utility/InstallPrompt/InstallPrompt.helpers.ts

@@ -0,0 +1,124 @@
+import type { InstallPlatform } from './InstallPrompt.types';
+
+/**
+ * Pure environment probes and dismissal storage for `usePwaInstall`.
+ *
+ * Everything here is a plain function taking its clock and its storage from the
+ * caller where that matters, so the hook's behaviour is testable without
+ * faking timers or a browser.
+ */
+
+export const DEFAULT_STORAGE_KEY = 'pwa-install-dismissed';
+export const DEFAULT_DISMISS_DAYS = 30;
+
+const MS_PER_DAY = 86_400_000;
+const STANDALONE_QUERY = '(display-mode: standalone)';
+
+/** iOS Safari predates `display-mode` and exposes this instead. */
+interface IosNavigator extends Navigator {
+  standalone?: boolean;
+}
+
+/** Guard for SSR and for jsdom runs where `matchMedia` is not implemented. */
+const hasWindow = (): boolean => typeof window !== 'undefined';
+
+/**
+ * True when the page is already running as an installed app.
+ *
+ * Both checks are needed: `display-mode: standalone` is the standard signal,
+ * but iOS never implemented it for home-screen launches and reports
+ * `navigator.standalone` instead. Miss the iOS branch and the installed app
+ * nags its own users to install it again.
+ */
+export const isStandaloneDisplay = (): boolean => {
+  if (!hasWindow()) return false;
+  if ((window.navigator as IosNavigator).standalone === true) return true;
+  return window.matchMedia?.(STANDALONE_QUERY).matches === true;
+};
+
+/**
+ * True for Safari on iOS/iPadOS — the one browser that can install but cannot
+ * be asked programmatically.
+ *
+ * Two traps handled here. iPadOS 13+ reports a Macintosh user agent, so the
+ * touch-point count is what separates an iPad from a desktop; and Chrome,
+ * Firefox and Edge on iOS are Safari underneath but offer no Add to Home
+ * Screen at all, so telling their users to tap Share is a dead end.
+ *
+ * Kept parameterised so the agent table can be tested without reassigning
+ * `navigator`, which leaks across test files when it is not restored.
+ */
+export const isIosSafariAgent = (userAgent: string, maxTouchPoints: number): boolean => {
+  const isIosDevice =
+    /iPad|iPhone|iPod/.test(userAgent) ||
+    (userAgent.includes('Macintosh') && maxTouchPoints > 1);
+
+  if (!isIosDevice) return false;
+
+  return !/CriOS|FxiOS|EdgiOS|OPiOS/.test(userAgent);
+};
+
+/** `isIosSafariAgent` against the live browser. Internal — callers use `resolveInstallPlatform`. */
+const isIosSafari = (): boolean => {
+  if (!hasWindow()) return false;
+
+  const { userAgent, maxTouchPoints } = window.navigator;
+  return isIosSafariAgent(userAgent, maxTouchPoints);
+};
+
+/**
+ * Reads the stored dismissal timestamp.
+ *
+ * Storage access is wrapped because it THROWS rather than returning null in
+ * Safari private mode and wherever cookies are blocked — an uncaught throw
+ * here would take down the storefront on the very browsers this component
+ * exists to serve.
+ */
+export const readDismissedAt = (storageKey: string): number | null => {
+  if (!hasWindow()) return null;
+
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return null;
+
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Persists a dismissal. Silently a no-op when storage is unavailable. */
+export const writeDismissedAt = (storageKey: string, at: number): void => {
+  if (!hasWindow()) return;
+
+  try {
+    window.localStorage.setItem(storageKey, String(at));
+  } catch {
+    // Storage blocked — the dismissal lasts for this page view only.
+  }
+};
+
+/**
+ * Whether a stored dismissal still suppresses the prompt.
+ *
+ * `dismissForDays: 0` means forever. A timestamp in the future (a device whose
+ * clock was wound back) is treated as active rather than expired, so a bad
+ * clock cannot turn into a prompt on every page view.
+ */
+export const isDismissalActive = (
+  dismissedAt: number | null,
+  dismissForDays: number,
+  now: number,
+): boolean => {
+  if (dismissedAt === null) return false;
+  if (dismissForDays <= 0) return true;
+
+  return now - dismissedAt < dismissForDays * MS_PER_DAY;
+};
+
+/** Resolves which install route this browser offers. */
+export const resolveInstallPlatform = (hasDeferredPrompt: boolean): InstallPlatform => {
+  if (hasDeferredPrompt) return 'prompt';
+  return isIosSafari() ? 'ios' : 'unsupported';
+};