@djangocfg/layouts 2.1.585 → 2.1.590

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.585",
+  "version": "2.1.590",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -90,11 +90,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.585",
-    "@djangocfg/api": "^2.1.585",
-    "@djangocfg/devtools": "^2.1.585",
-    "@djangocfg/i18n": "^2.1.585",
-    "@djangocfg/ui-core": "^2.1.585",
+    "@djangocfg/analytics": "^2.1.590",
+    "@djangocfg/api": "^2.1.590",
+    "@djangocfg/devtools": "^2.1.590",
+    "@djangocfg/i18n": "^2.1.590",
+    "@djangocfg/ui-core": "^2.1.590",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -124,12 +124,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.585",
-    "@djangocfg/api": "^2.1.585",
-    "@djangocfg/devtools": "^2.1.585",
-    "@djangocfg/i18n": "^2.1.585",
-    "@djangocfg/typescript-config": "^2.1.585",
-    "@djangocfg/ui-core": "^2.1.585",
+    "@djangocfg/analytics": "^2.1.590",
+    "@djangocfg/api": "^2.1.590",
+    "@djangocfg/devtools": "^2.1.590",
+    "@djangocfg/i18n": "^2.1.590",
+    "@djangocfg/typescript-config": "^2.1.590",
+    "@djangocfg/ui-core": "^2.1.590",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/AuthLayout/AuthLayout.tsx

@@ -21,7 +21,7 @@ import { useAppT } from '@djangocfg/i18n';
 
 import { Suspense } from '../../components';
 import { TwoFactorChallengeDialog } from '../../snippets/TwoFactor';
-import { AuthBrandPanel } from './components/shared';
+import { AuthBrandPanel, AuthTopBar } from './components/shared';
 import { OAuthCallback } from './components/oauth';
 import { IdentifierStep, OTPStep } from './components/steps';
 import { AUTH } from './constants';
@@ -113,6 +113,10 @@ export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
     [hideHeader, hasBrandPanel],
   );
 
+  // The way out and the locale, pinned to the top of the form column. Owned by
+  // the layout so it does not depend on `logo` or `sidebar`, which are optional.
+  const topBar = useMemo(() => <AuthTopBar brandPanel={hasBrandPanel} />, [hasBrandPanel]);
+
   const oauthCallback = useMemo(() => {
     if (!enableGithubAuth) return null;
     return (
@@ -135,7 +139,14 @@ export const AuthLayout: React.FC<AuthLayoutProps> = (props) => {
           <AuthFunnelTracker />
           <AuthTwoFactorChallenge onVerified={onOTPSuccess} />
 
-          <AuthShell variant={variant} mediaSide={mediaSide} background={background} sidebar={resolvedSidebar} className={className}>
+          <AuthShell
+            variant={variant}
+            mediaSide={mediaSide}
+            background={background}
+            sidebar={resolvedSidebar}
+            topBar={topBar}
+            className={className}
+          >
             {/* Handle OAuth callback when GitHub auth is enabled */}
             {oauthCallback}
 

package/src/layouts/AuthLayout/README.md

@@ -51,6 +51,38 @@ The link carries `aria-label` from `layouts.navigation.home` rather than
 relying on its contents: `logo` is an opaque node, and a brand that is a bare
 SVG would otherwise announce as an unnamed link.
 
+## The top bar: the way out and the language
+
+Every variant pins one bar to the top of the form column: **`‹ Home`** on the
+left, the **locale picker** on the right. The layout owns it (`AuthTopBar`,
+passed to the shell as `topBar`), so it does not depend on `logo` or `sidebar`.
+
+> It exists because the brand link above was the only exit, and the brand is
+> optional. An app that passed its own `sidebar` and no `logo` (the Kino sign-in)
+> left a phone visitor with no route off the screen: the media half is hidden
+> below 1024px and the form header had nothing to render. The locale, meanwhile,
+> floated above the title inside the centered stack.
+
+- The link is a real `<a href="/">` (`AUTH.HOME_URL`) with a visible label, the
+  way an iOS back button names its destination. A bare arrow reads as browser
+  Back, and Back has nowhere to go after a direct link. The label is
+  `layouts.navigation.home`, translated in all 17 locales.
+- Both controls are at least 44px tall. The bar clears the notch with
+  `env(safe-area-inset-top)`.
+- When the layout's own `AuthBrandPanel` is on the photo half (`fullsplit`, `logo`
+  and no `sidebar`) the home link stands down from 1024px, since the panel links
+  home already. With a custom `sidebar` the bar's link stays: the layout cannot
+  know the sidebar links anywhere.
+- The locale picker mounts whenever `LayoutI18nProvider` does (`BaseApp` does it
+  when the host passes `i18n`). It moved out of `AuthContainer`.
+
+**Height.** Every shell is `min-height: 100dvh` with a `100vh` fallback, so the
+mobile address bar does not leave a gap. The form centers itself in the space the
+bar leaves with `margin: auto` on its own block, not `justify-content: center` on
+the column: with the keyboard open the form scrolls from its top instead of
+having its first field pushed out of reach. It sits slightly above the true
+center (`padding-bottom: clamp(0rem, 8dvh, 4rem)`), the optical center of a form.
+
 `logo` is a **`ReactNode`** — an inline-SVG brand component, an `<img>`, a
 horizontal lock-up. **The slot fits the artwork, not the reverse:** it caps the
 height (44px in the form header, 2.5rem on the brand panel) and lets the width

package/src/layouts/AuthLayout/components/shared/AuthContainer.tsx

@@ -2,8 +2,6 @@
 
 import React, { memo, useEffect, useState } from 'react';
 
-import { LocaleSwitcher } from '../../../_components/LocaleSwitcher';
-import { useLayoutI18nOptional } from '../../../AppLayout/LayoutI18nProvider';
 import { AUTH } from '../../constants';
 import type { AuthStep } from '../../types';
 
@@ -44,32 +42,12 @@ function AuthContainerRaw({
     }
   }, [isEntering]);
 
-  // Locale picker is mounted as the first child so it sits at the very
-  // top of the form column — visually paired with the form chrome (not
-  // floating in a viewport corner). Renders automatically when
-  // LayoutI18nProvider is mounted (BaseApp does this when the host app
-  // passes `i18n`); no prop gating needed.
-  const i18n = useLayoutI18nOptional();
-
   return (
     <div
       className={`auth-container ${className}`}
       data-entering={isEntering}
       data-step={step}
     >
-      {i18n ? (
-        <div className="auth-container__meta">
-          <LocaleSwitcher
-            variant="dropdown"
-            buttonVariant="ghost"
-            size="sm"
-            showFlag
-            showCode={false}
-            showTriggerLabel
-            className="auth-locale-trigger"
-          />
-        </div>
-      ) : null}
       {children}
     </div>
   );

package/src/layouts/AuthLayout/components/shared/AuthTopBar.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import React, { memo } from 'react';
+
+import { ChevronLeft } from 'lucide-react';
+
+import { useAppT } from '@djangocfg/i18n';
+import { Link } from '@djangocfg/ui-core/components';
+
+import { LocaleSwitcher } from '../../../_components/LocaleSwitcher';
+import { useLayoutI18nOptional } from '../../../AppLayout/LayoutI18nProvider';
+import { AUTH } from '../../constants';
+
+export interface AuthTopBarProps {
+  /**
+   * The brand already sits on the media half, which links home itself, so the
+   * bar stands its own link down where that half is visible (>= 1024px). CSS
+   * owns the breakpoint — see `.auth-topbar` in `auth.css`.
+   */
+  brandPanel?: boolean;
+  className?: string;
+}
+
+/**
+ * AuthTopBar — the one place a sign-in screen keeps its way out and its language.
+ *
+ * Home on the left, locale on the right, pinned to the top of the viewport and
+ * independent of what the app passes. Both used to ride inside the centered
+ * form stack: the locale floated above the title, and the way out existed only
+ * as the `logo` — an optional prop, hidden with the media half on a phone. An
+ * app that passed a custom `sidebar` and no `logo` (the Kino sign-in) left a
+ * phone visitor with no route off the screen at all.
+ *
+ * The link is a real `<a>` to `AUTH.HOME_URL` with a visible label, the way an
+ * iOS back button names its destination: an arrow alone reads as browser Back,
+ * and Back has nowhere to go when the page was opened by a direct link.
+ */
+function AuthTopBarRaw({ brandPanel = false, className = '' }: AuthTopBarProps) {
+  const t = useAppT();
+  const i18n = useLayoutI18nOptional();
+
+  return (
+    <div className={`auth-topbar ${className}`} data-brand-panel={brandPanel}>
+      <Link href={AUTH.HOME_URL} className="auth-topbar__home">
+        <ChevronLeft aria-hidden="true" className="auth-topbar__icon" />
+        <span>{t('layouts.navigation.home')}</span>
+      </Link>
+      {/* Mounted whenever LayoutI18nProvider is — BaseApp does it when the host
+          passes `i18n` — so there is no prop to gate it on. */}
+      {i18n ? (
+        <LocaleSwitcher
+          variant="dropdown"
+          buttonVariant="ghost"
+          size="sm"
+          showFlag
+          showCode={false}
+          showTriggerLabel
+          className="auth-locale-trigger"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+export const AuthTopBar = memo(AuthTopBarRaw);

package/src/layouts/AuthLayout/components/shared/index.ts

@@ -1,5 +1,6 @@
 export { AuthBrandPanel } from './AuthBrandPanel';
 export { AuthContainer } from './AuthContainer';
+export { AuthTopBar } from './AuthTopBar';
 export { AuthHeader } from './AuthHeader';
 export { AuthFooter } from './AuthFooter';
 export { AuthDivider } from './AuthDivider';
@@ -12,6 +13,7 @@ export { AuthConsent } from './AuthConsent';
 
 export type { AuthBrandPanelProps } from './AuthBrandPanel';
 export type { AuthContainerProps } from './AuthContainer';
+export type { AuthTopBarProps } from './AuthTopBar';
 export type { AuthHeaderProps } from './AuthHeader';
 export type { AuthFooterProps } from './AuthFooter';
 export type { AuthDividerProps } from './AuthDivider';

package/src/layouts/AuthLayout/shells/AuthShell.tsx

@@ -31,6 +31,7 @@ function AuthShellRaw({
   mediaSide = 'left',
   background,
   sidebar,
+  topBar,
   className,
 }: AuthShellProps) {
   const { isLoaded: bgLoaded, hasError: bgError } = useImageLoader(background?.imageUrl);
@@ -73,6 +74,7 @@ function AuthShellRaw({
 
   const commonShellProps = {
     children,
+    topBar,
     className,
     bgStyle,
     overlayStyle,

package/src/layouts/AuthLayout/shells/CenteredShell.tsx

@@ -13,6 +13,7 @@ import type { ShellRenderProps } from './types';
  */
 function CenteredShellRaw({
   children,
+  topBar,
   className,
   bgStyle,
   overlayStyle,
@@ -30,6 +31,8 @@ function CenteredShellRaw({
         </>
       )}
 
+      {topBar && <div className="auth-shell-centered__topbar">{topBar}</div>}
+
       <div className="auth-shell-centered__content">
         {children}
       </div>

package/src/layouts/AuthLayout/shells/FullSplitShell.tsx

@@ -25,6 +25,7 @@ interface FullSplitShellProps extends ShellRenderProps {
  */
 function FullSplitShellRaw({
   children,
+  topBar,
   className,
   bgStyle,
   overlayStyle,
@@ -64,6 +65,7 @@ function FullSplitShellRaw({
 
       {/* Right: solid panel with the centered form */}
       <div className="auth-shell-fullsplit__form">
+        {topBar}
         <div className="auth-shell-fullsplit__form-inner">{children}</div>
       </div>
     </div>

package/src/layouts/AuthLayout/shells/SplitShell.tsx

@@ -23,6 +23,7 @@ interface SplitShellProps extends ShellRenderProps {
  */
 function SplitShellRaw({
   children,
+  topBar,
   className,
   bgStyle,
   overlayStyle,
@@ -50,6 +51,7 @@ function SplitShellRaw({
       <div className="auth-shell-split__card">
         {/* Left: form */}
         <div className="auth-shell-split__form">
+          {topBar}
           <div className="auth-shell-split__form-inner">
             {children}
           </div>

package/src/layouts/AuthLayout/shells/types.ts

@@ -50,12 +50,20 @@ export interface AuthShellProps {
   background?: AuthBackgroundConfig;
   /** Slot for the right column in split variant (testimonial, branding, etc.). */
   sidebar?: ReactNode;
+  /**
+   * Pinned to the top of the form column, above the vertically centered form:
+   * the way out and the locale (see `AuthTopBar`). Optional so a harness that
+   * mounts a shell alone still renders.
+   */
+  topBar?: ReactNode;
   className?: string;
 }
 
 /** Internal props passed from AuthShell orchestrator to variant shells. */
 export interface ShellRenderProps {
   children: ReactNode;
+  /** See `AuthShellProps.topBar`. */
+  topBar?: ReactNode;
   className?: string;
   bgStyle?: CSSProperties;
   overlayStyle?: CSSProperties;

package/src/layouts/AuthLayout/styles/auth.css

@@ -32,22 +32,65 @@
   gap: var(--auth-gap);
 }
 
-/* Meta row at the top of the form — currently hosts the locale picker.
-   It is the first thing in the column but the last thing anyone came here to
-   do, so it is pulled out of the reading order by SIZE and alignment. Not by
-   contrast: `--muted-foreground` is the dimmest token that still clears AA,
-   and fading it toward transparent fails the contract gate — which is what
-   happened to the consent line below. */
-.auth-container__meta {
+/* Top bar: the way out (left) and the locale (right), pinned to the top of the
+   form column by the shell. The locale used to ride above the title inside the
+   centered stack; it is a utility, so it lives on the screen's edge, not in the
+   reading order. Contrast stays at `--muted-foreground`, the dimmest token that
+   clears AA: fading it further fails the contract gate. */
+.auth-topbar {
   display: flex;
-  justify-content: flex-end;
-  /* Lifted clear of the column's own gap — a utility chip, not a first row. */
-  margin-bottom: calc(var(--auth-gap) * -1);
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  width: 100%;
+  /* A touch target, not a text row: 44px is the floor for a thumb. */
+  min-height: 2.75rem;
+  /* Clear the notch / status bar when the page runs edge to edge. */
+  padding-top: env(safe-area-inset-top, 0);
+}
+
+.auth-topbar__home {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  min-height: 2.75rem;
+  /* Pull the chevron onto the column's left edge; the padding stays as hit area. */
+  margin-inline-start: -0.5rem;
+  padding-inline: 0.5rem 0.75rem;
+  border-radius: var(--auth-radius-sm);
+  font-size: 0.875rem;
+  color: var(--muted-foreground);
+  transition: color 0.15s var(--spring-snappy);
+}
+.auth-topbar__home:hover {
+  color: var(--foreground);
+}
+.auth-topbar__home:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.auth-topbar__icon {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+/* The locale stays at the right edge even when the link is hidden. */
+.auth-topbar > :last-child {
+  margin-inline-start: auto;
+}
+
+/* The brand panel on the media half already links home, and that half exists
+   from 1024px — the same breakpoint `fullsplit-shell.css` reveals it at. */
+@media (min-width: 1024px) {
+  .auth-topbar[data-brand-panel="true"] .auth-topbar__home {
+    display: none;
+  }
 }
 
 .auth-locale-trigger {
-  height: 1.75rem;
-  padding-inline: 0.5rem;
+  height: 2.75rem;
+  padding-inline: 0.75rem;
   font-size: 0.75rem;
   color: var(--muted-foreground);
   transition: color 0.15s var(--spring-snappy);

package/src/layouts/AuthLayout/styles/centered-shell.css

@@ -12,9 +12,10 @@
   display: flex;
   flex-direction: column;
   align-items: center;
-  justify-content: center;
+  /* The top bar pins to the top; the content centers itself in what is left
+     (see `__content`), so a short viewport never pushes the form out of reach. */
   /* Responsive padding: 24px mobile → 40px desktop */
-  padding: 1.5rem clamp(1.5rem, 5vw, 2.5rem);
+  padding: 0.5rem clamp(1.5rem, 5vw, 2.5rem) 1.5rem;
   padding-bottom: max(1.5rem, env(safe-area-inset-bottom, 1rem));
 }
 
@@ -39,11 +40,19 @@
   pointer-events: none;
 }
 
+.auth-shell-centered__topbar {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+}
+
 /* Content sits above background */
 .auth-shell-centered__content {
   position: relative;
   z-index: 1;
   width: 100%;
+  margin-block: auto;
+  padding-bottom: clamp(0rem, 8dvh, 4rem);
   display: flex;
   flex-direction: column;
   align-items: center;

package/src/layouts/AuthLayout/styles/fullsplit-shell.css

@@ -147,18 +147,26 @@ a.auth-brand-panel__mark:focus-visible {
 }
 
 /* ── Form half (right) ─────────────────────────────────────────────────── */
+/* A column: the top bar sits at the top of the viewport, and the form takes the
+   rest and centers itself in it. `margin: auto` on the inner block (rather than
+   `justify-content: center` on the column) is what keeps the form reachable when
+   the keyboard or a short viewport leaves it less room than it needs — centering
+   by the container would push the top of it out of reach. */
 .auth-shell-fullsplit__form {
   flex: 1;
   display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 1.5rem clamp(1.5rem, 5vw, 2.5rem);
+  flex-direction: column;
+  padding: 0.5rem clamp(1.5rem, 5vw, 2.5rem);
   padding-bottom: max(1.5rem, env(safe-area-inset-bottom, 1rem));
 }
 
 .auth-shell-fullsplit__form-inner {
   width: 100%;
   max-width: 360px;
+  margin: auto;
+  /* Sits a little above the true center — the optical center of a form — and
+     the top bar's height keeps it from looking low. */
+  padding-bottom: clamp(0rem, 8dvh, 4rem);
 }
 
 /* ── Desktop: reveal the image half, split 50/50 edge-to-edge ──────────── */
@@ -215,7 +223,7 @@ a.auth-brand-panel__mark:focus-visible {
 
   .auth-shell-fullsplit__form {
     flex: 1;
-    padding: 2.5rem;
+    padding: 1.5rem 2.5rem 2.5rem;
   }
 
   .auth-shell-fullsplit__form-inner {

package/src/layouts/AuthLayout/styles/split-shell.css

@@ -13,9 +13,11 @@
   min-height: 100vh;
   min-height: 100dvh;
   display: flex;
-  align-items: center;
+  /* Mobile: the card fills the viewport so the top bar lands at its top edge;
+     desktop re-centers the floating card below. */
+  align-items: stretch;
   justify-content: center;
-  padding: 1rem;
+  padding: 0.5rem 1rem 1rem;
 }
 
 /* Background layers — hidden on mobile (plain form), shown on desktop. */
@@ -47,14 +49,15 @@
 .auth-shell-split__form {
   flex: 1;
   display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 1rem 0.5rem;
+  flex-direction: column;
+  padding: 0 0.5rem 1rem;
 }
 
 .auth-shell-split__form-inner {
   width: 100%;
   max-width: 360px;
+  /* Centers in what the top bar leaves, and stays reachable when it is short. */
+  margin: auto;
 }
 
 /* Sidebar column — hidden on mobile, shown on desktop. */
@@ -64,6 +67,11 @@
 
 /* ── Desktop: frosted-glass two-column card ──────────────────────────────── */
 @media (min-width: 1280px) {
+  .auth-shell-split {
+    align-items: center;
+    padding: 1rem;
+  }
+
   .auth-shell-split__bg,
   .auth-shell-split__overlay {
     display: block;
@@ -91,7 +99,7 @@
   }
 
   .auth-shell-split__form {
-    padding: 2.75rem;
+    padding: 1.25rem 2.75rem 2.75rem;
   }
 
   .auth-shell-split__sidebar {

package/src/testing/index.ts

@@ -27,7 +27,7 @@ export { AuthLayoutProvider, AuthSuccessScreen } from '../layouts/AuthLayout/Aut
 // The layout's own default media-half content. Stories mount `AuthShell`
 // directly, so they must supply this themselves to preview what an app that
 // passes no `sidebar` actually gets.
-export { AuthBrandPanel } from '../layouts/AuthLayout/components/shared';
+export { AuthBrandPanel, AuthTopBar } from '../layouts/AuthLayout/components/shared';
 export {
   IdentifierStep,
   OTPStep,