@flamingo-stack/openframe-frontend-core 0.0.705-snapshot.20261006160157 → 0.0.705

package/src/hooks/ui/use-nav-menus.ts

@@ -1,200 +0,0 @@
-'use client';
-
-import {
-  useCallback,
-  useEffect,
-  useId,
-  useRef,
-  useState,
-  type MouseEvent as ReactMouseEvent,
-  type RefCallback,
-} from 'react';
-
-export interface UseNavMenusOptions {
-  /** The host router's pathname: any change closes the open menu. */
-  pathname: string;
-  /** Hover intent: how long the pointer rests on a trigger before it opens. */
-  hoverOpenMs?: number;
-  /** How long after the pointer left the trigger and the panel the menu closes. */
-  hoverCloseMs?: number;
-}
-
-export interface NavMenuTriggerProps {
-  ref: RefCallback<HTMLElement>;
-  'aria-expanded': boolean;
-  'aria-controls': string;
-  onClick: (event: ReactMouseEvent) => void;
-  onMouseEnter: () => void;
-  onMouseLeave: () => void;
-}
-
-export interface NavMenuPanelProps {
-  ref: RefCallback<HTMLElement>;
-  id: string;
-  inert: boolean;
-  'data-state': 'open' | 'closed';
-  onMouseEnter: () => void;
-  onMouseLeave: () => void;
-}
-
-export interface UseNavMenusResult {
-  /** The id of the open menu, or `null`. One menu is open at a time. */
-  openId: string | null;
-  close: () => void;
-  getTriggerProps: (id: string) => NavMenuTriggerProps;
-  getPanelProps: (id: string) => NavMenuPanelProps;
-}
-
-/**
- * Open state for a row of disclosure menus (the site header's dropdowns and
- * mega menus).
- *
- * - Click toggles; the trigger is a `<button>`, so Enter and Space arrive as
- *   that same click.
- * - Hover on a trigger opens after `hoverOpenMs`; with a menu already open,
- *   hovering another trigger switches to it at once. Leaving the trigger and the
- *   panel closes after `hoverCloseMs`; entering the panel or any trigger
- *   cancels that close, so the pointer can cross the gap between them.
- * - Escape closes and returns focus to the trigger. A pointer-down outside
- *   every trigger and panel closes. A `pathname` change closes.
- * - No arrow-key roving: these are plain disclosures, Tab moves in DOM order.
- */
-export function useNavMenus({
-  pathname,
-  hoverOpenMs = 150,
-  hoverCloseMs = 300,
-}: UseNavMenusOptions): UseNavMenusResult {
-  const baseId = useId();
-  // The open menu is remembered WITH the pathname it was opened on, so a
-  // navigation closes it during render: no effect, no frame of a stale panel.
-  // The stale entry is dropped in the same render, or coming back to that
-  // pathname would reopen it.
-  const [opened, setOpened] = useState<{ id: string; pathname: string } | null>(null);
-  const stale = opened !== null && opened.pathname !== pathname;
-  if (stale) setOpened(null);
-  const openId = opened && !stale ? opened.id : null;
-
-  const triggers = useRef(new Map<string, HTMLElement>());
-  const panels = useRef(new Map<string, HTMLElement>());
-  const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  // The menu a HOVER opened, until a click claims it (see `onClick`).
-  const openedByHover = useRef<string | null>(null);
-
-  const clearTimers = useCallback(() => {
-    if (openTimer.current) clearTimeout(openTimer.current);
-    if (closeTimer.current) clearTimeout(closeTimer.current);
-    openTimer.current = null;
-    closeTimer.current = null;
-  }, []);
-
-  useEffect(() => clearTimers, [clearTimers]);
-
-  const close = useCallback(() => {
-    clearTimers();
-    setOpened(null);
-  }, [clearTimers]);
-
-  const cancelClose = useCallback(() => {
-    if (closeTimer.current) clearTimeout(closeTimer.current);
-    closeTimer.current = null;
-  }, []);
-
-  const scheduleClose = useCallback(() => {
-    if (openTimer.current) clearTimeout(openTimer.current);
-    openTimer.current = null;
-    cancelClose();
-    closeTimer.current = setTimeout(() => {
-      closeTimer.current = null;
-      setOpened(null);
-    }, hoverCloseMs);
-  }, [cancelClose, hoverCloseMs]);
-
-  useEffect(() => {
-    if (!openId) return undefined;
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== 'Escape') return;
-      const trigger = triggers.current.get(openId);
-      close();
-      trigger?.focus({ preventScroll: true });
-    };
-    const handlePointerDown = (event: PointerEvent) => {
-      const target = event.target;
-      if (!(target instanceof Node)) return;
-      for (const el of triggers.current.values()) if (el.contains(target)) return;
-      for (const el of panels.current.values()) if (el.contains(target)) return;
-      close();
-    };
-
-    document.addEventListener('keydown', handleKeyDown);
-    document.addEventListener('pointerdown', handlePointerDown);
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown);
-      document.removeEventListener('pointerdown', handlePointerDown);
-    };
-  }, [openId, close]);
-
-  const getTriggerProps = useCallback(
-    (id: string): NavMenuTriggerProps => ({
-      ref: el => {
-        if (el) triggers.current.set(id, el);
-        else triggers.current.delete(id);
-      },
-      'aria-expanded': openId === id,
-      'aria-controls': `${baseId}-panel-${id}`,
-      onClick: () => {
-        // A touch tap fires mouseenter first: drop its pending open, or it
-        // would reopen the menu this click just closed.
-        clearTimers();
-        // A click on a menu the pointer's hover already opened means "open
-        // it": it keeps the menu open instead of toggling it shut (a mouse
-        // user hovers, then clicks; a touch tap fires mouseenter, then click).
-        // The click claims the menu, so the next click on it closes it.
-        const hovered = openedByHover.current === id;
-        openedByHover.current = null;
-        if (hovered) {
-          setOpened({ id, pathname });
-          return;
-        }
-        setOpened(prev => (prev && prev.id === id && prev.pathname === pathname ? null : { id, pathname }));
-      },
-      onMouseEnter: () => {
-        clearTimers();
-        if (openId === id) return;
-        // A menu is already open: the visitor is browsing the row, so the next
-        // one opens at once. The hover-intent wait is only for the FIRST open
-        // (it filters a pointer merely crossing the bar).
-        if (openId !== null) {
-          openedByHover.current = id;
-          setOpened({ id, pathname });
-          return;
-        }
-        openTimer.current = setTimeout(() => {
-          openTimer.current = null;
-          openedByHover.current = id;
-          setOpened({ id, pathname });
-        }, hoverOpenMs);
-      },
-      onMouseLeave: scheduleClose,
-    }),
-    [baseId, openId, pathname, hoverOpenMs, clearTimers, scheduleClose],
-  );
-
-  const getPanelProps = useCallback(
-    (id: string): NavMenuPanelProps => ({
-      ref: el => {
-        if (el) panels.current.set(id, el);
-        else panels.current.delete(id);
-      },
-      id: `${baseId}-panel-${id}`,
-      inert: openId !== id,
-      'data-state': openId === id ? 'open' : 'closed',
-      onMouseEnter: cancelClose,
-      onMouseLeave: scheduleClose,
-    }),
-    [baseId, openId, cancelClose, scheduleClose],
-  );
-
-  return { openId, close, getTriggerProps, getPanelProps };
-}

package/src/hooks/ui/use-visitor-os.ts

@@ -1,33 +0,0 @@
-'use client';
-
-import { useSyncExternalStore } from 'react';
-import { detectVisitorOs, type VisitorOs } from '../../utils/visitor-os';
-
-export type VisitorOsState = { known: false; os: null } | { known: true; os: VisitorOs | null };
-
-const UNKNOWN: VisitorOsState = { known: false, os: null };
-// One state object per answer, so the snapshot is stable between reads.
-const KNOWN = new Map<VisitorOs | null, VisitorOsState>();
-
-const subscribe = () => () => {};
-const getServerSnapshot = () => UNKNOWN;
-function getSnapshot(): VisitorOsState {
-  // `userAgentData` is the Client Hints API (Chromium only, so not in every DOM typing).
-  const stated = (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform;
-  const os = detectVisitorOs(navigator.userAgent, { platform: stated, maxTouchPoints: navigator.maxTouchPoints });
-  let state = KNOWN.get(os);
-  if (!state) {
-    state = { known: true, os };
-    KNOWN.set(os, state);
-  }
-  return state;
-}
-
-/**
- * The visitor's system in the browser, through the one detection rule
- * (`utils/visitor-os`). `known` is false on the server and while React
- * hydrates: the server cannot see the browser, and a guess would mismatch.
- */
-export function useVisitorOs(): VisitorOsState {
-  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-}

package/src/hooks/use-location-hash.ts

@@ -1,34 +0,0 @@
-'use client';
-
-import { useSyncExternalStore } from 'react';
-import { normalizeHashFragment } from '../utils/same-page-hash-nav';
-
-/** `navigateSamePageHash` dispatches `hashchange` itself; `popstate` covers back and forward. */
-const HASH_EVENTS = ['hashchange', 'popstate'] as const;
-
-function subscribe(onChange: () => void): () => void {
-  for (const event of HASH_EVENTS) window.addEventListener(event, onChange);
-  return () => {
-    for (const event of HASH_EVENTS) window.removeEventListener(event, onChange);
-  };
-}
-
-function readHash(): string {
-  const raw = normalizeHashFragment(window.location.hash).replace(/^#/, '');
-  try {
-    return decodeURIComponent(raw);
-  } catch {
-    return raw;
-  }
-}
-
-/**
- * The URL's hash without its `#`, or `''`: the READ side of same-page anchor
- * navigation (`navigateSamePageHash` writes it, `useScrollToHash` scrolls to
- * it). For a component whose state follows the anchor: a tab group that opens
- * the tab a link names. Empty on the server and during hydration (the server
- * never sees a hash), then the real one.
- */
-export function useLocationHash(): string {
-  return useSyncExternalStore(subscribe, readHash, () => '');
-}

package/src/utils/visitor-os.ts

@@ -1,84 +0,0 @@
-/**
- * THE detection of the system a visitor is on. One rule, read by everything
- * that depends on it: which installer the desktop app's download offers, and
- * which shortcut key a hint shows. Never test `navigator.platform` or a
- * User-Agent anywhere else.
- *
- * Pure and server-safe: the server passes the request's User-Agent, the browser
- * goes through `useVisitorOs` (hooks), which also passes the touch-point count.
- */
-export type VisitorOs = 'mac' | 'windows' | 'linux' | 'ios' | 'android';
-
-/** The systems the desktop app installs on. */
-export const DESKTOP_OSES = ['mac', 'windows', 'linux'] as const;
-export type DesktopOs = (typeof DESKTOP_OSES)[number];
-
-export interface VisitorOsHints {
-  /**
-   * The platform the browser STATES through User-Agent Client Hints:
-   * `navigator.userAgentData.platform` in the browser, the `Sec-CH-UA-Platform`
-   * request header on the server (Chromium browsers send it on every request).
-   * It is the current standard and is read first: browsers are freezing the
-   * User-Agent string, so the hint is the value they keep accurate. Safari and
-   * Firefox send none, which is why the User-Agent stays the fallback.
-   */
-  platform?: string | null;
-  /**
-   * `navigator.maxTouchPoints`, when the caller is a browser. An iPad asks for
-   * the desktop site by default and then calls itself a Macintosh; a Macintosh
-   * with a touch screen does not exist, so touch points tell the two apart. The
-   * server has no such signal and reads that iPad as a Mac.
-   */
-  maxTouchPoints?: number;
-}
-
-/** Client Hints platform names (the header quotes them) to ours. Chrome OS runs Linux apps. */
-const HINT_PLATFORMS: Record<string, VisitorOs> = {
-  macos: 'mac',
-  windows: 'windows',
-  linux: 'linux',
-  'chrome os': 'linux',
-  'chromium os': 'linux',
-  android: 'android',
-  ios: 'ios',
-};
-
-/**
- * The visitor's system, or null when nothing names one. Order: the Client Hints
- * platform, then the User-Agent, with touch points separating an iPad from a Mac.
- */
-export function detectVisitorOs(userAgent: string | null | undefined, hints: VisitorOsHints = {}): VisitorOs | null {
-  const touchMac = (os: VisitorOs) => (os === 'mac' && (hints.maxTouchPoints ?? 0) > 1 ? 'ios' : os);
-  const hinted = HINT_PLATFORMS[(hints.platform ?? '').replace(/"/g, '').trim().toLowerCase()];
-  if (hinted) return touchMac(hinted);
-
-  const ua = userAgent ?? '';
-  if (!ua) return null;
-  // Phones and tablets first: Android's User-Agent also says "Linux".
-  if (/iPhone|iPad|iPod/i.test(ua)) return 'ios';
-  if (/Android/i.test(ua)) return 'android';
-  if (/Windows NT|Win64|Win32/i.test(ua)) return 'windows';
-  if (/Macintosh|Mac OS X/i.test(ua)) return touchMac('mac');
-  if (/Linux|X11|CrOS/i.test(ua)) return 'linux';
-  return null;
-}
-
-/** The system as a desktop one, or null for a phone, a tablet or an unknown system. */
-export function desktopOsOf(os: VisitorOs | null): DesktopOs | null {
-  return os !== null && (DESKTOP_OSES as readonly string[]).includes(os) ? (os as DesktopOs) : null;
-}
-
-/** The desktop system a User-Agent comes from: `desktopOsOf(detectVisitorOs(...))`. */
-export function detectDesktopOs(userAgent: string | null | undefined, hints?: VisitorOsHints): DesktopOs | null {
-  return desktopOsOf(detectVisitorOs(userAgent, hints));
-}
-
-/** Apple systems use the Command key for shortcuts; every other system uses Control. */
-export function usesCommandKey(os: VisitorOs | null): boolean {
-  return os === 'mac' || os === 'ios';
-}
-
-/** A shortcut as its hint reads on the visitor's system: `⌘K` or `Ctrl K`. */
-export function shortcutLabel(os: VisitorOs | null, key: string): string {
-  return usesCommandKey(os) ? `⌘${key}` : `Ctrl ${key}`;
-}