@sovereignfs/ui 0.45.0 → 0.83.1

package/src/hooks/__tests__/useOfflineTileState.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { useOfflineTileState } from '../useOfflineTileState';
+
+function Harness({
+  offline,
+  deviceOnlyAvailable,
+}: {
+  offline: 'offline-first' | 'device-only' | undefined;
+  deviceOnlyAvailable: boolean;
+}) {
+  const state = useOfflineTileState(offline, deviceOnlyAvailable);
+  return <span data-testid="out">{String(state)}</span>;
+}
+
+describe('useOfflineTileState', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: true });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('is null for a no-tier app while online', () => {
+    const { getByTestId } = render(<Harness offline={undefined} deviceOnlyAvailable={false} />);
+    expect(getByTestId('out').textContent).toBe('null');
+  });
+
+  it('connectivity-dims a no-tier app while offline', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const { getByTestId } = render(<Harness offline={undefined} deviceOnlyAvailable={false} />);
+    expect(getByTestId('out').textContent).toBe('connectivity-dimmed');
+  });
+
+  it('never dims an offline-first app, online or offline', () => {
+    const online = render(<Harness offline="offline-first" deviceOnlyAvailable={false} />);
+    expect(online.getByTestId('out').textContent).toBe('null');
+    cleanup();
+
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const offline = render(<Harness offline="offline-first" deviceOnlyAvailable={false} />);
+    expect(offline.getByTestId('out').textContent).toBe('null');
+  });
+
+  it('capability-restricts a device-only app when unavailable, regardless of connectivity', () => {
+    const online = render(<Harness offline="device-only" deviceOnlyAvailable={false} />);
+    expect(online.getByTestId('out').textContent).toBe('capability-restricted');
+    cleanup();
+
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const offline = render(<Harness offline="device-only" deviceOnlyAvailable={false} />);
+    expect(offline.getByTestId('out').textContent).toBe('capability-restricted');
+  });
+
+  it('is not restricted for a device-only app when available, and not dimmed offline either', () => {
+    const online = render(<Harness offline="device-only" deviceOnlyAvailable={true} />);
+    expect(online.getByTestId('out').textContent).toBe('null');
+    cleanup();
+
+    // Availability is a capability signal, not a connectivity one — a
+    // device-only app that IS available behaves like offline-first once the
+    // capability question is settled.
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const offline = render(<Harness offline="device-only" deviceOnlyAvailable={true} />);
+    expect(offline.getByTestId('out').textContent).toBe('null');
+  });
+});

package/src/hooks/__tests__/usePublishShellChromeHeight.test.tsx

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useRef } from 'react';
+import { usePublishShellChromeHeight } from '../usePublishShellChromeHeight';
+
+function Harness() {
+  const ref = useRef<HTMLDivElement>(null);
+  usePublishShellChromeHeight(ref, '--sv-shell-footer-height');
+  return <div ref={ref} />;
+}
+
+function HeaderHarness() {
+  const ref = useRef<HTMLDivElement>(null);
+  usePublishShellChromeHeight(ref, '--sv-shell-header-height');
+  return <div ref={ref} />;
+}
+
+function stubHeight(height: number) {
+  return vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue({
+    height,
+    width: 0,
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    x: 0,
+    y: 0,
+    toJSON() {},
+  } as DOMRect);
+}
+
+describe('usePublishShellChromeHeight', () => {
+  afterEach(() => {
+    cleanup();
+    document.getElementById('sv-app-shell')?.remove();
+    vi.restoreAllMocks();
+  });
+
+  it('re-measures on window resize', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    const rectSpy = stubHeight(50);
+
+    render(<Harness />);
+    expect(shell.style.getPropertyValue('--sv-shell-footer-height')).toBe('50px');
+
+    rectSpy.mockReturnValue({
+      height: 80,
+      width: 0,
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: 0,
+      x: 0,
+      y: 0,
+      toJSON() {},
+    } as DOMRect);
+    act(() => window.dispatchEvent(new Event('resize')));
+
+    expect(shell.style.getPropertyValue('--sv-shell-footer-height')).toBe('80px');
+  });
+
+  it('removes its resize listener on unmount', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    stubHeight(50);
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+
+    const { unmount } = render(<Harness />);
+    unmount();
+
+    expect(removeSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+  });
+
+  it('is a no-op when #sv-app-shell does not exist', () => {
+    stubHeight(50);
+    expect(() => render(<Harness />)).not.toThrow();
+  });
+
+  it('also mirrors --sv-shell-header-height onto --sv-dialog-inset-top on :root', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    stubHeight(69);
+
+    render(<HeaderHarness />);
+
+    expect(shell.style.getPropertyValue('--sv-shell-header-height')).toBe('69px');
+    expect(document.documentElement.style.getPropertyValue('--sv-dialog-inset-top')).toBe('69px');
+  });
+
+  it('removes --sv-dialog-inset-top from :root on unmount', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    stubHeight(69);
+
+    const { unmount } = render(<HeaderHarness />);
+    expect(document.documentElement.style.getPropertyValue('--sv-dialog-inset-top')).toBe('69px');
+
+    unmount();
+    expect(document.documentElement.style.getPropertyValue('--sv-dialog-inset-top')).toBe('');
+  });
+
+  it('never touches --sv-dialog-inset-top for the footer variable', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    stubHeight(50);
+
+    render(<Harness />);
+
+    expect(document.documentElement.style.getPropertyValue('--sv-dialog-inset-top')).toBe('');
+  });
+});

package/src/hooks/__tests__/useReorderSensors.test.ts

@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { shouldHandleDndEvent } from '../useReorderSensors';
+
+describe('shouldHandleDndEvent', () => {
+  it('refuses an element nested inside a data-no-dnd ancestor', () => {
+    const wrapper = document.createElement('div');
+    wrapper.setAttribute('data-no-dnd', '');
+    const child = document.createElement('button');
+    wrapper.appendChild(child);
+    document.body.appendChild(wrapper);
+
+    expect(shouldHandleDndEvent(child)).toBe(false);
+  });
+
+  it('allows an element with no data-no-dnd ancestor', () => {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+
+    expect(shouldHandleDndEvent(el)).toBe(true);
+  });
+
+  it('allows a non-Element target', () => {
+    expect(shouldHandleDndEvent(null)).toBe(true);
+  });
+});

package/src/hooks/__tests__/useResponsiveLayout.test.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useResponsiveLayout } from '../useResponsiveLayout';
+
+// Same matchMedia mocking approach as useIsMobile.test.tsx, since this hook
+// is a thin wrapper over it and must not diverge in SSR/breakpoint behavior.
+let changeHandler: ((e: MediaQueryListEvent) => void) | null = null;
+let matches = false;
+let lastQuery = '';
+
+function installMatchMedia() {
+  changeHandler = null;
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => {
+      lastQuery = query;
+      return {
+        matches,
+        media: query,
+        addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+          changeHandler = cb;
+        },
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      };
+    }),
+  );
+}
+
+function Harness({ breakpointPx }: { breakpointPx?: number }) {
+  const { isMobile, value } = useResponsiveLayout({
+    web: 'web-tree',
+    mobile: 'mobile-tree',
+    breakpointPx,
+  });
+  return (
+    <span data-testid="out" data-is-mobile={String(isMobile)}>
+      {value}
+    </span>
+  );
+}
+
+describe('useResponsiveLayout', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('defaults to the web value before/without a mobile match (SSR-safe default)', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('web-tree');
+    expect(getByTestId('out').dataset.isMobile).toBe('false');
+  });
+
+  it('picks the mobile value once matchMedia reports a match', () => {
+    matches = true;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('mobile-tree');
+    expect(getByTestId('out').dataset.isMobile).toBe('true');
+  });
+
+  it('swaps live when the viewport crosses the breakpoint', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('web-tree');
+    act(() => changeHandler?.({ matches: true } as MediaQueryListEvent));
+    expect(getByTestId('out').textContent).toBe('mobile-tree');
+  });
+
+  it('passes a custom breakpointPx straight through to useIsMobile', () => {
+    matches = false;
+    installMatchMedia();
+    render(<Harness breakpointPx={640} />);
+    expect(lastQuery).toBe('(max-width: 640px)');
+  });
+});

package/src/hooks/__tests__/useSnapCarousel.test.tsx

@@ -0,0 +1,175 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { useSnapCarousel, type UseSnapCarouselOptions } from '../useSnapCarousel';
+
+// jsdom doesn't implement scrollTo on elements.
+beforeEach(() => {
+  vi.useFakeTimers();
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  vi.runOnlyPendingTimers();
+  vi.useRealTimers();
+  cleanup();
+});
+
+function setLayout(el: HTMLElement, clientWidth: number, scrollLeft: number) {
+  Object.defineProperty(el, 'clientWidth', { value: clientWidth, configurable: true });
+  Object.defineProperty(el, 'scrollLeft', { value: scrollLeft, configurable: true });
+}
+
+function Harness(
+  props: UseSnapCarouselOptions & { onScrollTo?: (fn: (i: number) => void) => void },
+) {
+  const { onScrollTo, ...options } = props;
+  const { scrollRef, scrollToIndex } = useSnapCarousel(options);
+  onScrollTo?.(scrollToIndex);
+  return <div data-testid="scroller" ref={scrollRef} />;
+}
+
+describe('useSnapCarousel', () => {
+  it('calls onSettle with the new index after the debounce window', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 300); // scrollLeft 300 / width 300 -> index 1
+    fireEvent.scroll(el);
+    expect(onSettle).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('debounces repeated scroll events into a single settle call', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 0);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(60));
+    setLayout(el, 300, 300);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledOnce();
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('does not call onSettle again for the same index', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={3} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 300);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    fireEvent.touchStart(el);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledOnce();
+  });
+
+  it('clamps the settled index within [0, itemCount - 1]', () => {
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={2} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 900); // rounds to index 3, clamps to itemCount - 1 = 1
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('ignores a scroll event with no active gesture (drift, not a settle)', () => {
+    // Regression test: reproduced live via a user screen recording — a
+    // slide's content changing size while still loading can nudge
+    // scrollLeft enough to round to a different index. Previously any such
+    // stray `scroll` event was enough to fire a second, contradicting
+    // onSettle, silently "auto-swiping" the carousel back to the wrong
+    // slide with no further touch input.
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={10} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 1800); // settles cleanly on index 6
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledExactlyOnceWith(6);
+
+    // Well outside the grace window and no further touch/wheel/pointer
+    // activity — this scroll event is drift, not a resettle.
+    act(() => void vi.advanceTimersByTime(1000));
+    setLayout(el, 300, 1620); // would round to index 5
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledExactlyOnceWith(6);
+  });
+
+  it('still settles on long-running momentum/snap-correction scroll with no further touch input', () => {
+    // Regression test for a bug in the FIRST version of the drift fix above:
+    // gating on "was there a touch/wheel/pointer event within a fixed
+    // debounceMs * 2 slack of settle-check time" dropped real settles once
+    // native momentum/snap-correction ran longer than that slack — which it
+    // routinely does for a fast flick. That left activeIndex stuck on the
+    // old slide while the container had already scrolled to the new one,
+    // and since the mount window is keyed off activeIndex, the slide the
+    // user was actually looking at could get unmounted — a blank carousel,
+    // worse than the bug being fixed. The chain stays trusted for as long as
+    // scroll events keep arriving without a debounceMs-or-longer gap,
+    // regardless of how long that run lasts or how few touch events back it.
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={10} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 1700);
+    fireEvent.scroll(el); // starts the run — trusted (touchstart just happened)
+    fireEvent.touchEnd(el);
+    // Momentum keeps producing scroll events, each within debounceMs of the
+    // last (so the run never goes quiet), for far longer than any fixed
+    // slack window would tolerate — no further touch input at all.
+    for (const scrollLeft of [1720, 1740, 1760, 1780, 1800]) {
+      act(() => void vi.advanceTimersByTime(80));
+      setLayout(el, 300, scrollLeft);
+      fireEvent.scroll(el);
+    }
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledExactlyOnceWith(6);
+  });
+
+  it('settles correctly on two independent real swipes fired back-to-back', () => {
+    // Regression test: two genuine swipes with essentially no gap between
+    // them (an impatient fast double-swipe) must not corrupt or drop either
+    // settle — each is its own trusted run.
+    const onSettle = vi.fn();
+    const { getByTestId } = render(<Harness itemCount={10} onSettle={onSettle} debounceMs={120} />);
+    const el = getByTestId('scroller');
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 300);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledExactlyOnceWith(1);
+
+    fireEvent.touchStart(el);
+    setLayout(el, 300, 600);
+    fireEvent.scroll(el);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledTimes(2);
+    expect(onSettle).toHaveBeenLastCalledWith(2);
+  });
+
+  it('scrollToIndex scrolls the container to the target slide', () => {
+    let scrollToIndex: ((index: number) => void) | undefined;
+    const { getByTestId } = render(
+      <Harness itemCount={3} onScrollTo={(fn) => (scrollToIndex = fn)} />,
+    );
+    const el = getByTestId('scroller');
+    setLayout(el, 400, 0);
+    const spy = vi.spyOn(el, 'scrollTo');
+    scrollToIndex?.(2);
+    expect(spy).toHaveBeenCalledWith({ left: 800, behavior: 'smooth' });
+  });
+});

package/src/hooks/__tests__/useSwipeReveal.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { useSwipeReveal, type UseSwipeRevealOptions } from '../useSwipeReveal';
+
+// jsdom doesn't implement pointer capture — stub it as a no-op so
+// `e.currentTarget.setPointerCapture(...)` doesn't throw.
+beforeEach(() => {
+  if (!HTMLElement.prototype.setPointerCapture) {
+    HTMLElement.prototype.setPointerCapture = vi.fn();
+  }
+});
+
+afterEach(cleanup);
+
+function Harness(props: UseSwipeRevealOptions) {
+  const { rowRef, handlers } = useSwipeReveal(props);
+  return (
+    <div data-testid="row" ref={rowRef} {...handlers}>
+      row
+    </div>
+  );
+}
+
+function pointer(x: number, y: number) {
+  return { clientX: x, clientY: y, pointerId: 1 };
+}
+
+describe('useSwipeReveal', () => {
+  it('calls onOpen when a horizontal drag crosses the halfway point', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-60, 0));
+    fireEvent.pointerUp(el, pointer(-60, 0));
+    expect(onOpen).toHaveBeenCalledOnce();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('calls onClose when the drag does not cross the halfway point', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-20, 0));
+    fireEvent.pointerUp(el, pointer(-20, 0));
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+
+  it('locks to vertical and ignores a mostly-vertical drag', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(2, 60));
+    fireEvent.pointerUp(el, pointer(2, 60));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when disabled', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} disabled />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(-60, 0));
+    fireEvent.pointerUp(el, pointer(-60, 0));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('closes from an already-open state when dragged back past halfway', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open onOpen={onOpen} onClose={onClose} />,
+    );
+    const el = getByTestId('row');
+    fireEvent.pointerDown(el, pointer(0, 0));
+    fireEvent.pointerMove(el, pointer(60, 0));
+    fireEvent.pointerUp(el, pointer(60, 0));
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+
+  it('ignores pointerup without a preceding pointerdown', () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+    const { getByTestId } = render(
+      <Harness revealWidth={100} open={false} onOpen={onOpen} onClose={onClose} />,
+    );
+    fireEvent.pointerUp(getByTestId('row'), pointer(-60, 0));
+    expect(onOpen).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});