@djangocfg/layouts 2.1.604 → 2.1.606

package/src/layouts/PrivateLayout/hooks/usePresence.ts

@@ -0,0 +1,39 @@
+/**
+ * Presence: keeps an element mounted for `exitMs` after `open` turns false, so its exit
+ * animation can run. With `prefers-reduced-motion` the exit is skipped (unmount at once).
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+
+import { SIDEBAR_MOTION_MS } from '../geometry';
+
+export interface Presence {
+  /** Render the element. */
+  mounted: boolean;
+  /** Drives `data-state`: `open` while entering/shown, `closed` while exiting. */
+  state: 'open' | 'closed';
+}
+
+export function usePresence(open: boolean, exitMs: number = SIDEBAR_MOTION_MS): Presence {
+  const reduced = useMediaQuery('(prefers-reduced-motion: reduce)');
+  const [lingering, setLingering] = useState(false);
+
+  useEffect(() => {
+    if (open) {
+      setLingering(true);
+      return;
+    }
+    if (reduced || exitMs <= 0) {
+      setLingering(false);
+      return;
+    }
+    const t = setTimeout(() => setLingering(false), exitMs);
+    return () => clearTimeout(t);
+  }, [open, reduced, exitMs]);
+
+  return { mounted: open || lingering, state: open ? 'open' : 'closed' };
+}

package/src/layouts/PrivateLayout/hooks/useSidebarPeek.tsx

@@ -1,36 +1,27 @@
 /**
- * Peek: while the sidebar is collapsed, hovering its trigger zone floats the
- * full sidebar over the page. The panel keeps itself open while the pointer is
+ * Peek: while the sidebar is collapsed, resting the pointer on the left edge or the trigger
+ * zone (hover intent) floats the full sidebar over the page. The panel keeps itself open while the pointer is
  * on it, or while a menu opened from it (account, workspace switcher) is open.
  */
 
 'use client';
 
-import React, {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import React, { createContext, useContext, useEffect, useMemo } from 'react';
 
 import { useSidebar } from '@djangocfg/ui-core/components';
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
-// Opens on entry with no delay, then stays at least MIN_OPEN_MS even if the
-// pointer only grazed the zone, so a user who didn't notice it still sees it.
-const MIN_OPEN_MS = 900;
-const CLOSE_DELAY_MS = 300;
+import { useHoverIntent } from './useHoverIntent';
+import type { Presence } from './usePresence';
+import { usePresence } from './usePresence';
 
-interface PointerHandlers {
-  onPointerEnter: (e: React.PointerEvent) => void;
-  onPointerLeave: (e: React.PointerEvent) => void;
-}
+type PointerHandlers = ReturnType<typeof useHoverIntent>['zoneProps'];
 
-export interface SidebarPeek {
+export interface SidebarPeek extends Presence {
   /** True while the sidebar is collapsed on desktop: the trigger zone shows. */
   enabled: boolean;
+  /** Hover-open is live: collapsed, desktop, and a fine (mouse/pen) pointer. */
+  hoverEnabled: boolean;
   open: boolean;
   zoneProps: PointerHandlers;
   panelProps: PointerHandlers;
@@ -64,68 +55,14 @@ interface SidebarPeekProviderProps {
 export function SidebarPeekProvider({ pathname, children }: SidebarPeekProviderProps) {
   const { state, isMobile } = useSidebar();
   const enabled = !isMobile && state === 'collapsed';
+  // Hover is a mouse affordance: only where the primary pointer can hover precisely.
+  const finePointer = useMediaQuery('(hover: hover) and (pointer: fine)');
+  const hoverEnabled = enabled && finePointer;
 
-  const [open, setOpen] = useState(false);
-  const pinned = useRef(false);
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const openedAt = useRef(0);
-
-  const cancel = useCallback(() => {
-    if (timer.current) clearTimeout(timer.current);
-    timer.current = null;
-  }, []);
-
-  const scheduleClose = useCallback(() => {
-    cancel();
-    if (pinned.current) return;
-    const grace = openedAt.current + MIN_OPEN_MS - Date.now();
-    timer.current = setTimeout(() => setOpen(false), Math.max(CLOSE_DELAY_MS, grace));
-  }, [cancel]);
-
-  const show = useCallback(() => {
-    cancel();
-    setOpen((was) => {
-      if (!was) openedAt.current = Date.now();
-      return true;
-    });
-  }, [cancel]);
-
-  const close = useCallback(() => {
-    cancel();
-    setOpen(false);
-  }, [cancel]);
-
-  const pin = useCallback(
-    (value: boolean) => {
-      pinned.current = value;
-      if (!value) scheduleClose();
-    },
-    [scheduleClose],
-  );
-
-  // Hover is a mouse affordance; touch taps the trigger to dock instead.
-  const zoneProps = useMemo<PointerHandlers>(
-    () => ({
-      onPointerEnter: (e) => {
-        if (e.pointerType !== 'mouse') return;
-        show();
-      },
-      onPointerLeave: scheduleClose,
-    }),
-    [show, scheduleClose],
-  );
-
-  const panelProps = useMemo<PointerHandlers>(
-    () => ({
-      onPointerEnter: show,
-      onPointerLeave: scheduleClose,
-    }),
-    [show, scheduleClose],
-  );
-
-  useEffect(() => {
-    if (!enabled) close();
-  }, [enabled, close]);
+  const intent = useHoverIntent({ enabled: hoverEnabled });
+  const { close } = intent;
+  const open = enabled && intent.open;
+  const presence = usePresence(open);
 
   useEffect(() => {
     close();
@@ -140,11 +77,19 @@ export function SidebarPeekProvider({ pathname, children }: SidebarPeekProviderP
     return () => window.removeEventListener('keydown', onKey);
   }, [open, close]);
 
-  useEffect(() => cancel, [cancel]);
-
   const value = useMemo<SidebarPeek>(
-    () => ({ enabled, open: enabled && open, zoneProps, panelProps, close, pin }),
-    [enabled, open, zoneProps, panelProps, close, pin],
+    () => ({
+      enabled,
+      hoverEnabled,
+      open,
+      mounted: enabled && presence.mounted,
+      state: presence.state,
+      zoneProps: intent.zoneProps,
+      panelProps: intent.panelProps,
+      close,
+      pin: intent.pin,
+    }),
+    [enabled, hoverEnabled, open, presence.mounted, presence.state, intent.zoneProps, intent.panelProps, close, intent.pin],
   );
 
   return <PeekContext.Provider value={value}>{children}</PeekContext.Provider>;

package/src/styles/dashboard.css

@@ -49,3 +49,30 @@
 [data-sidebar-resizing] [data-variant][data-state] * {
   transition: none !important;
 }
+
+
+/**
+ * Private layout: peek panel slide in and out. Shipped here so consumers need no animation
+ * plugin. Duration mirrors SIDEBAR_MOTION_MS in PrivateLayout/geometry.ts.
+ */
+@keyframes private-sidebar-in {
+  from { opacity: 0; transform: translateX(-1rem); }
+  to { opacity: 1; transform: translateX(0); }
+}
+@keyframes private-sidebar-out {
+  from { opacity: 1; transform: translateX(0); }
+  to { opacity: 0; transform: translateX(-1rem); }
+}
+.private-sidebar-peek[data-state="open"] {
+  animation: private-sidebar-in 180ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+.private-sidebar-peek[data-state="closed"] {
+  animation: private-sidebar-out 180ms ease-in both;
+  pointer-events: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .private-sidebar-peek[data-state="open"],
+  .private-sidebar-peek[data-state="closed"] {
+    animation: none;
+  }
+}

package/src/testing/MockAuthFormProvider.tsx

@@ -11,7 +11,7 @@ import {
 } from '@djangocfg/api/auth';
 
 import { AuthFormContext } from '../layouts/AuthLayout/context';
-import { resolveOAuthProviders } from '../layouts/AuthLayout/components/oauth/oauthProviders';
+import { resolveOAuthProviders } from '../layouts/AuthLayout/components/oauth/providers/resolveProviders';
 import type { AuthFormContextType, AuthLayoutConfig, OAuthFailure } from '../layouts/AuthLayout/types';
 
 // Storybook-only provider. Reproduces the AuthFormContext shape with

package/src/layouts/AuthLayout/components/oauth/OAuthButtons.tsx

@@ -1,82 +0,0 @@
-'use client';
-
-import React, { memo, useCallback, useMemo } from 'react';
-
-import { type OAuthProviderId, useOAuthLogin } from '@djangocfg/api/auth';
-import { useAppT } from '@djangocfg/i18n';
-
-import { AuthButton, type AuthButtonProps } from '../shared';
-import { GithubIcon } from './GithubIcon';
-import { GoogleIcon } from './GoogleIcon';
-import { useOAuthErrorText } from './oauthErrors';
-
-interface OAuthProviderEntry {
-  Icon: React.FC;
-  variant: NonNullable<AuthButtonProps['variant']>;
-  labelKey: 'layouts.auth.identifier.oauth.github' | 'layouts.auth.identifier.oauth.google';
-}
-
-/** One entry per provider the client can run; keyed by the API package's id type, so a new provider fails typecheck until it has a button. */
-export const OAUTH_PROVIDER_UI: Record<OAuthProviderId, OAuthProviderEntry> = {
-  github: { Icon: GithubIcon, variant: 'secondary', labelKey: 'layouts.auth.identifier.oauth.github' },
-  google: { Icon: GoogleIcon, variant: 'google', labelKey: 'layouts.auth.identifier.oauth.google' },
-};
-
-export interface OAuthButtonsProps {
-  providers: readonly OAuthProviderId[];
-  sourceUrl?: string;
-  /** Disables every button, e.g. while the email form is submitting. */
-  disabled?: boolean;
-  onError?: (message: string) => void;
-}
-
-/**
- * The provider buttons: same size and weight each, progress only on the one
- * clicked, the rest disabled while its flow is in flight.
- */
-function OAuthButtonsRaw({ providers, sourceUrl, disabled, onError }: OAuthButtonsProps) {
-  const t = useAppT();
-  const errorText = useOAuthErrorText();
-
-  const { start, loadingProvider, isLoading } = useOAuthLogin({
-    sourceUrl,
-    onError: (message, code) => onError?.(errorText(code, message)),
-  });
-
-  const labels = useMemo(
-    () => Object.fromEntries(providers.map((id) => [id, t(OAUTH_PROVIDER_UI[id].labelKey)])) as Record<string, string>,
-    [providers, t],
-  );
-
-  const handleClick = useCallback(
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-      const id = event.currentTarget.dataset.provider as OAuthProviderId;
-      void start(id);
-    },
-    [start],
-  );
-
-  return (
-    <div className="auth-oauth" role="group">
-      {providers.map((id) => {
-        const { Icon, variant } = OAUTH_PROVIDER_UI[id];
-        return (
-          <AuthButton
-            key={id}
-            type="button"
-            variant={variant}
-            data-provider={id}
-            loading={loadingProvider === id}
-            disabled={disabled || (isLoading && loadingProvider !== id)}
-            onClick={handleClick}
-          >
-            <Icon />
-            {labels[id]}
-          </AuthButton>
-        );
-      })}
-    </div>
-  );
-}
-
-export const OAuthButtons = memo(OAuthButtonsRaw);

package/src/layouts/AuthLayout/components/oauth/oauthErrors.ts

@@ -1,23 +0,0 @@
-'use client';
-
-import { useCallback } from 'react';
-
-import type { OAuthFailureCode } from '@djangocfg/api/auth';
-import { useAppT } from '@djangocfg/i18n';
-
-import { OAUTH_CODE_TO_KEY, OAUTH_ERROR_KEYS } from './oauthNoticeCopy';
-
-/**
- * The visitor-facing sentence for a failure: the translated copy of its code,
- * else the text the hook carried (server prose), else the generic sentence.
- */
-export const useOAuthErrorText = () => {
-  const t = useAppT();
-  return useCallback(
-    (code?: OAuthFailureCode | null, fallback?: string | null): string => {
-      if (code) return t(OAUTH_CODE_TO_KEY[code]);
-      return fallback || t(OAUTH_ERROR_KEYS.generic);
-    },
-    [t],
-  );
-};

package/src/layouts/AuthLayout/components/oauth/oauthNoticeCopy.test.ts

@@ -1,36 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { describeOAuthFailure } from './oauthNoticeCopy';
-
-describe('describeOAuthFailure', () => {
-  it('says nothing when the visitor cancelled', () => {
-    expect(describeOAuthFailure('cancelled')).toBeNull();
-  });
-
-  it('points a staff account at the email code, with a heading', () => {
-    expect(describeOAuthFailure('link_not_allowed')).toEqual({
-      titleKey: 'layouts.auth.oauth.notice.linkNotAllowedTitle',
-      bodyKey: 'layouts.auth.oauth.error.link_not_allowed',
-      action: 'email',
-    });
-  });
-
-  it('offers a retry where trying again can help', () => {
-    for (const code of ['invalid_state', 'oauth_exchange_failed', 'provider_unavailable', 'server_error'] as const) {
-      expect(describeOAuthFailure(code)?.action).toBe('retry');
-    }
-  });
-
-  it('offers nothing the visitor cannot act on', () => {
-    expect(describeOAuthFailure('account_inactive')?.action).toBe('none');
-    expect(describeOAuthFailure('rate_limited')?.action).toBe('none');
-  });
-
-  it('treats a missing code as the generic failure', () => {
-    expect(describeOAuthFailure(undefined)).toEqual({
-      titleKey: undefined,
-      bodyKey: 'layouts.auth.oauth.error.generic',
-      action: 'retry',
-    });
-  });
-});

package/src/layouts/AuthLayout/components/oauth/oauthNoticeCopy.ts

@@ -1,86 +0,0 @@
-import type { OAuthFailureCode } from '@djangocfg/api/auth';
-
-/**
- * Copy for each failure code. Exhaustive on purpose: a code the backend adds
- * fails typecheck here until someone decides what to tell the visitor.
- */
-export const OAUTH_ERROR_KEYS = {
-  invalid_state: 'layouts.auth.oauth.error.invalid_state',
-  oauth_exchange_failed: 'layouts.auth.oauth.error.oauth_exchange_failed',
-  invalid_id_token: 'layouts.auth.oauth.error.invalid_id_token',
-  email_missing: 'layouts.auth.oauth.error.email_missing',
-  email_not_verified: 'layouts.auth.oauth.error.email_not_verified',
-  hosted_domain_not_allowed: 'layouts.auth.oauth.error.hosted_domain_not_allowed',
-  account_inactive: 'layouts.auth.oauth.error.account_inactive',
-  link_not_allowed: 'layouts.auth.oauth.error.link_not_allowed',
-  rate_limited: 'layouts.auth.oauth.error.rate_limited',
-  provider_unavailable: 'layouts.auth.oauth.error.provider_unavailable',
-  cancelled: 'layouts.auth.oauth.error.cancelled',
-  generic: 'layouts.auth.oauth.error.generic',
-} as const;
-
-export type OAuthErrorKey = (typeof OAUTH_ERROR_KEYS)[keyof typeof OAUTH_ERROR_KEYS];
-
-/** Maps every failure code to one of the keys above. Configuration faults the visitor cannot fix read as "unavailable" or generic. */
-export const OAUTH_CODE_TO_KEY: Record<OAuthFailureCode, OAuthErrorKey> = {
-  invalid_state: OAUTH_ERROR_KEYS.invalid_state,
-  oauth_exchange_failed: OAUTH_ERROR_KEYS.oauth_exchange_failed,
-  invalid_id_token: OAUTH_ERROR_KEYS.invalid_id_token,
-  email_missing: OAUTH_ERROR_KEYS.email_missing,
-  email_not_verified: OAUTH_ERROR_KEYS.email_not_verified,
-  hosted_domain_not_allowed: OAUTH_ERROR_KEYS.hosted_domain_not_allowed,
-  account_inactive: OAUTH_ERROR_KEYS.account_inactive,
-  link_not_allowed: OAUTH_ERROR_KEYS.link_not_allowed,
-  rate_limited: OAUTH_ERROR_KEYS.rate_limited,
-  provider_unavailable: OAUTH_ERROR_KEYS.provider_unavailable,
-  cancelled: OAUTH_ERROR_KEYS.cancelled,
-  oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
-  github_oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
-  origin_not_allowed: OAUTH_ERROR_KEYS.generic,
-  missing_redirect_uri: OAUTH_ERROR_KEYS.generic,
-  server_error: OAUTH_ERROR_KEYS.generic,
-  not_found: OAUTH_ERROR_KEYS.generic,
-  unknown_provider: OAUTH_ERROR_KEYS.generic,
-};
-
-/** The one next step a notice offers: reveal the email field, run the provider again, or nothing the visitor can do. */
-export type OAuthNoticeAction = 'email' | 'retry' | 'none';
-
-/** What the visitor does next, per copy key. A retry is only offered where trying again can change the outcome. */
-const ACTION_BY_KEY: Record<OAuthErrorKey, OAuthNoticeAction> = {
-  [OAUTH_ERROR_KEYS.invalid_state]: 'retry',
-  [OAUTH_ERROR_KEYS.oauth_exchange_failed]: 'retry',
-  [OAUTH_ERROR_KEYS.invalid_id_token]: 'retry',
-  [OAUTH_ERROR_KEYS.email_missing]: 'email',
-  [OAUTH_ERROR_KEYS.email_not_verified]: 'email',
-  [OAUTH_ERROR_KEYS.hosted_domain_not_allowed]: 'email',
-  [OAUTH_ERROR_KEYS.account_inactive]: 'none',
-  [OAUTH_ERROR_KEYS.link_not_allowed]: 'email',
-  [OAUTH_ERROR_KEYS.rate_limited]: 'none',
-  [OAUTH_ERROR_KEYS.provider_unavailable]: 'retry',
-  [OAUTH_ERROR_KEYS.cancelled]: 'none',
-  [OAUTH_ERROR_KEYS.generic]: 'retry',
-};
-
-export interface OAuthNoticeCopy {
-  /** Only the code that needs a heading has one; the rest are a single sentence. */
-  titleKey?: 'layouts.auth.oauth.notice.linkNotAllowedTitle';
-  bodyKey: OAuthErrorKey;
-  action: OAuthNoticeAction;
-}
-
-/**
- * What the sign-in form tells a visitor whose provider round trip failed.
- *
- * `null` means "say nothing": the visitor cancelled on the provider's page and
- * is back at the form they started from. An absent code is the unknown case.
- */
-export const describeOAuthFailure = (code?: OAuthFailureCode | null): OAuthNoticeCopy | null => {
-  const bodyKey = code ? OAUTH_CODE_TO_KEY[code] : OAUTH_ERROR_KEYS.generic;
-  if (bodyKey === OAUTH_ERROR_KEYS.cancelled) return null;
-  return {
-    titleKey: bodyKey === OAUTH_ERROR_KEYS.link_not_allowed ? 'layouts.auth.oauth.notice.linkNotAllowedTitle' : undefined,
-    bodyKey,
-    action: ACTION_BY_KEY[bodyKey],
-  };
-};