ab-nextjs-core 0.1.4 → 0.1.6

package/ab-aside-layout/styles.module.css

@@ -27,7 +27,7 @@
 * @name: AB Aside Layout (client) - Component Stylesheet (plain CSS, Tailwind-independent)
 * @file: ab-aside-layout/styles.module.css
 * @type: CSS Module
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -50,6 +50,17 @@
   transition-duration: 300ms;
   transition-timing-function: ease-in-out;
   background-color: var(--color-background, var(--surface, #ffffff));
+
+  /* 🎞️ 0.1.6: the slideFromRight keyframe (ab-nextjs-animations) runs 240ms here (brief §4) */
+  --slide-from-right-animation-duration: 240ms;
+}
+
+/* ♿ 0.1.6: reduced motion = instant toggle, no slide (the provider also drops its timers to 0) */
+@media (prefers-reduced-motion: reduce) {
+  .abAsideLayout {
+    animation: none !important; /* 🚫 beats the global .slideFromRight class */
+    transition: none;
+  }
 }
 
 @media (min-width: 1536px) {
@@ -158,3 +169,45 @@
   from { opacity: 0; }
   to { opacity: 1; }
 }
+
+/* ================================================================== */
+/* 📏 0.1.6 layout rule (G51 + G52 + G54): a bounded box whose CONTENT */
+/*    scrolls on its own; aside-header / aside-bar collapse when empty   */
+/* ================================================================== */
+/* 🫥 D37: an empty slot is 0px (also outside panes: an empty wrapper had no size anyway) */
+.abAsideLayout__headerWrapper:empty,
+.abAsideLayout__footerWrapper:empty,
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__headerWrapper:not(:has(> *)),
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__footerWrapper:not(:has(> *)) {
+  display: none; /* 📏 0px, and no footer gradient */
+}
+/* 🧭 inside AbAppLayout variant="panes": a full-height column, only the content wrapper scrolls */
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout {
+  height: 100%; /* 📏 the pane */
+  min-height: 0; /* 🚫 */
+  max-height: none; /* 🧹 the legacy 100vh caps */
+  overflow: hidden; /* 🔒 */
+  display: flex; /* 🧱 header · content · bar */
+  flex-direction: column;
+  margin: 0; /* 🧹 legacy 2xl margins */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__headerWrapper,
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__footerWrapper {
+  flex: none; /* 📏 rows size to their content: no hard-coded heights */
+  pointer-events: auto; /* 🖱️ real chrome, not an overlay */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__footerWrapper {
+  padding-bottom: env(safe-area-inset-bottom, 0px); /* 📱 home indicator */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__footerWrapper::before {
+  content: none; /* 🧹 no gradient over the scroller */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abAsideLayout__contentWrapper {
+  flex: 1 1 0; /* ↕️ the rest */
+  height: auto; /* 📏 */
+  min-height: 0; /* 🚫 lets it scroll */
+  overflow: hidden auto; /* 📜 THE scroller of this pane */
+  overscroll-behavior: contain; /* 🚫 never chains to the page (G54) */
+  scrollbar-gutter: stable; /* 📏 no layout jump */
+  justify-content: flex-start; /* ⬆️ */
+}

package/ab-linear-progress/index.tsx

@@ -24,7 +24,7 @@
 * SOFTWARE.
 *
 * @project: ab-nextjs-core
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*

package/ab-main-layout/index.tsx

@@ -24,7 +24,7 @@
 * SOFTWARE.
 *
 * @project: ab-nextjs-core
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -38,7 +38,10 @@
 import type { ReactElement, ReactNode } from 'react';
 import clsx from 'clsx';
 import AbLinearProgress from '../ab-linear-progress';
+import { useAbPage } from '../ab-page-provider';
 import styles from './styles.module.css';
+// 🫥 G52: empty-slot helper (strings get a <span>, so the :has() collapse never hides text)
+import { toAbSlot } from '../ab-page-provider/slot';
 
 export interface AbMainLayoutProps {
   orientation: 'vertical' | 'horizontal';
@@ -46,11 +49,22 @@ export interface AbMainLayoutProps {
   hidden?: boolean;
   pageName?: string;
   screenName?: string;
+  /** 🔝 0.1.6 (G52): the main pane's header slot (data-ab-part="main-header"); 0px and not rendered when empty. */
+  mainHeader?: ReactNode;
+  /** 🔚 0.1.6 (G52): the main pane's bottom bar slot (data-ab-part="main-bar"); 0px and not rendered when empty. */
+  mainBar?: ReactNode;
+  /** @deprecated 0.1.6: use `mainHeader` (kept as an alias for one minor). */
   header?: ReactNode;
   content?: ReactNode;
+  /** @deprecated 0.1.6: use `mainBar` (kept as an alias for one minor). */
   footer?: ReactNode;
   children?: ReactNode;
   menus?: ReactNode;
+  /** 🆔 0.1.6: element id (e.g. the skip-link target), no inner wrapper needed. */
+  id?: string;
+  /** @deprecated 0.1.6: `false` drops the legacy backdrop / menus / dialogs / toasts / progress / canvas layers.
+   *  Empty header / bar slots are never rendered any more, so this only gates those layers (default `true`). */
+  chrome?: boolean;
 }
 
 /** Client markup mirror of server AbMainLayout. */
@@ -60,14 +74,24 @@ const AbMainLayout = ({
   hidden,
   pageName,
   screenName,
-  header,
+  mainHeader,
+  mainBar,
+  header, // 🕰️ deprecated alias
   content,
-  footer,
+  footer, // 🕰️ deprecated alias
   children,
   menus,
+  id, // 🆔
+  chrome = true, // 🧰
 }: AbMainLayoutProps): ReactElement => {
+  // 🔝🔚 G52: the new slot names win, the 0.1.5 names still work
+  const top = toAbSlot(mainHeader ?? header);
+  const bar = toAbSlot(mainBar ?? footer);
+  // 📜 G55: publish this pane's scroller (the content wrapper) so scroll spies / TOCs can use it as `root`
+  const { setMainScrollElement } = useAbPage();
   return (
     <main
+      id={id} // 🆔 0.1.6
       className={clsx(
         ['AbMainLayout', 'group-mainLayout', styles.abMainLayout, className],
         { 'has-screen-name': !!screenName },
@@ -78,36 +102,46 @@ const AbMainLayout = ({
       data-ab-part="main"
       data-screen-name={screenName}
     >
-      <header className={clsx(['HeaderWrapper', styles.abMainLayout__headerWrapper])}>
-        {header}
-      </header>
+      {top != null && ( // 🫥 not rendered when empty (D37)
+        <header className={clsx(['HeaderWrapper', styles.abMainLayout__headerWrapper])} data-ab-part="main-header">
+          {top}
+        </header>
+      )}
       <div
         className={clsx([
           'ContentWrapper',
           styles.abMainLayout__contentWrapper,
           orientation === 'horizontal' && 'md:!flex-row',
         ])}
+        data-ab-part="main-content" // 📜 G51/G55: THE scroller of this pane (useAbScrollSpy root)
+        ref={setMainScrollElement} // 📜 G55: useAbPage().mainScrollElement
         data-orientation={orientation ? orientation.toString() : undefined}
       >
         {content ?? children}
       </div>
-      <footer className={clsx(['FooterWrapper', styles.abMainLayout__footerWrapper])}>
-        {footer}
-      </footer>
-      <div className={clsx(['Backdrop', styles.abMainLayout__backdrop])} hidden />
-      <div className={clsx(['Menus', styles.abMainLayout__menus])} hidden>
-        {menus}
-      </div>
-      <div className={clsx(['Dialogs', styles.abMainLayout__dialogs])} hidden />
-      <div className={clsx(['Toasts', styles.abMainLayout__toasts])} hidden />
-      <AbLinearProgress
-        className="absolute top-0 left-0 right-0 z-50 !w-1/2 place-self-center !my-1 3xl:!my-2 !mx-auto !h-0.5 lg:!h-1 3xl:!h-1.5"
-        color="secondary"
-        hidden={true}
-        isIndeterminate={true}
-        progress={25}
-      />
-      <canvas className={clsx(['Canvas', styles.abMainLayout__canvas])} />
+      {bar != null && ( // 🫥 not rendered when empty (D37)
+        <footer className={clsx(['FooterWrapper', styles.abMainLayout__footerWrapper])} data-ab-part="main-bar">
+          {bar}
+        </footer>
+      )}
+      {chrome && ( // 🧰 0.1.6: legacy layers
+        <>
+        <div className={clsx(['Backdrop', styles.abMainLayout__backdrop])} hidden />
+        <div className={clsx(['Menus', styles.abMainLayout__menus])} hidden>
+          {menus}
+        </div>
+        <div className={clsx(['Dialogs', styles.abMainLayout__dialogs])} hidden />
+        <div className={clsx(['Toasts', styles.abMainLayout__toasts])} hidden />
+        <AbLinearProgress
+          className="absolute top-0 left-0 right-0 z-50 !w-1/2 place-self-center !my-1 3xl:!my-2 !mx-auto !h-0.5 lg:!h-1 3xl:!h-1.5"
+          color="secondary"
+          hidden={true}
+          isIndeterminate={true}
+          progress={25}
+        />
+        <canvas className={clsx(['Canvas', styles.abMainLayout__canvas])} />
+        </>
+      )}
     </main>
   );
 };

package/ab-main-layout/styles.module.css

@@ -27,7 +27,7 @@
 * @name: AB Main Layout - Component Stylesheet (plain CSS, Tailwind-independent)
 * @file: ab-main-layout/styles.module.css
 * @type: CSS Module
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -165,3 +165,45 @@
   from { opacity: 0; }
   to { opacity: 1; }
 }
+
+/* ================================================================== */
+/* 📏 0.1.6 layout rule (G51 + G52 + G54): a bounded box whose CONTENT */
+/*    scrolls on its own; main-header / main-bar collapse when empty   */
+/* ================================================================== */
+/* 🫥 D37: an empty slot is 0px (also outside panes: an empty wrapper had no size anyway) */
+.abMainLayout__headerWrapper:empty,
+.abMainLayout__footerWrapper:empty,
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__headerWrapper:not(:has(> *)),
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__footerWrapper:not(:has(> *)) {
+  display: none; /* 📏 0px, and no footer gradient */
+}
+/* 🧭 inside AbAppLayout variant="panes": a full-height column, only the content wrapper scrolls */
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout {
+  height: 100%; /* 📏 the pane */
+  min-height: 0; /* 🚫 */
+  max-height: none; /* 🧹 the legacy 100vh caps */
+  overflow: hidden; /* 🔒 */
+  display: flex; /* 🧱 header · content · bar */
+  flex-direction: column;
+  margin: 0; /* 🧹 legacy 2xl margins */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__headerWrapper,
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__footerWrapper {
+  flex: none; /* 📏 rows size to their content: no hard-coded heights */
+  pointer-events: auto; /* 🖱️ real chrome, not an overlay */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__footerWrapper {
+  padding-bottom: env(safe-area-inset-bottom, 0px); /* 📱 home indicator */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__footerWrapper::before {
+  content: none; /* 🧹 no gradient over the scroller */
+}
+:global(.AbAppLayout[data-variant="panes"]) .abMainLayout__contentWrapper {
+  flex: 1 1 0; /* ↕️ the rest */
+  height: auto; /* 📏 */
+  min-height: 0; /* 🚫 lets it scroll */
+  overflow: hidden auto; /* 📜 THE scroller of this pane */
+  overscroll-behavior: contain; /* 🚫 never chains to the page (G54) */
+  scrollbar-gutter: stable; /* 📏 no layout jump */
+  justify-content: flex-start; /* ⬆️ */
+}

package/ab-page-provider/index.tsx

@@ -24,7 +24,7 @@
 * SOFTWARE.
 *
 * @project: ab-nextjs-core
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -39,13 +39,22 @@ import {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useRef,
   useState,
   type ReactElement,
   type ReactNode,
 } from 'react';
 
 export interface AbPageContextValue {
+  /** 📜 0.1.6 (G55): the main pane's scroller (AbMainLayout's content wrapper), e.g. `useAbScrollSpy({ root })`. */
+  mainScrollElement: HTMLElement | null;
+  /** 📜 0.1.6 (G55): the aside pane's scroller. */
+  asideScrollElement: HTMLElement | null;
+  /** 🔗 ref callbacks used by AbMainLayout / AbAsideLayout. */
+  setMainScrollElement: (el: HTMLElement | null) => void;
+  setAsideScrollElement: (el: HTMLElement | null) => void;
   isAsideOpen: boolean;
   isAsideOpenOnMobile: boolean;
   asideDuration: number;
@@ -57,9 +66,38 @@ export interface AbPageContextValue {
   setAsideOpen: (open: boolean) => void;
   setAsideOpenOnMobile: (open: boolean) => void;
   setAsideLoading: (loading: boolean) => void;
+  /** 🆔 0.1.6: id of the aside element (for `aria-controls` on the TOC / »« buttons). */
+  asideId: string;
+  /** 🔁 0.1.6: flip the laptop+ aside (»/« toggle). */
+  toggleAside: () => void;
+  /** 📱 0.1.6: flip the mobile/tablet aside sheet (TOC button). */
+  toggleAsideOnMobile: () => void;
+}
+
+/** 🎞️ 0.1.6: aside slide duration (brief §4: slide-from-right 240ms). */
+export const AB_ASIDE_DURATION = 240;
+/** 📐 0.1.6: below this the aside is a sheet driven by `isAsideOpenOnMobile` (mobile + tablet). */
+export const AB_ASIDE_SHEET_QUERY = '(max-width: 1023px)';
+/** ♿ reduced-motion query (same string as ab-nextjs-hooks' AB_REDUCED_MOTION_QUERY). */
+export const AB_REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+// 🔍 one-shot media check (false on the server / without matchMedia)
+const matches = (query: string): boolean =>
+  typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia(query).matches;
+
+/**
+ * ⏱️ getAbAsideDuration — the duration the open/close timers should use: `0` under reduced motion
+ * (instant toggle, brief §1.4), otherwise the provider's duration.
+ */
+export function getAbAsideDuration(duration: number, reducedMotion: boolean): number {
+  return reducedMotion ? 0 : Math.max(0, duration); // ♿ instant, never negative
 }
 
 const defaultValue: AbPageContextValue = {
+  mainScrollElement: null,
+  asideScrollElement: null,
+  setMainScrollElement: () => {},
+  setAsideScrollElement: () => {},
   isAsideOpen: true,
   isAsideOpenOnMobile: false,
   asideDuration: 300,
@@ -71,6 +109,9 @@ const defaultValue: AbPageContextValue = {
   setAsideOpen: () => {},
   setAsideOpenOnMobile: () => {},
   setAsideLoading: () => {},
+  asideId: 'ab-aside',
+  toggleAside: () => {},
+  toggleAsideOnMobile: () => {},
 };
 
 const AbPageContext = createContext<AbPageContextValue>(defaultValue);
@@ -79,7 +120,10 @@ export interface AbPageProviderProps {
   children?: ReactNode;
   /** Initial aside open state (default true so shells render visibly). */
   defaultAsideOpen?: boolean;
+  /** 🎞️ slide duration in ms (default 240, 0.1.6; was 300). Reduced motion always makes it instant. */
   asideDuration?: number;
+  /** 🆔 aside element id for `aria-controls` (default `'ab-aside'`). */
+  asideId?: string;
 }
 
 /**
@@ -89,7 +133,8 @@ export interface AbPageProviderProps {
 export function AbPageProvider({
   children,
   defaultAsideOpen = true,
-  asideDuration = 300,
+  asideDuration = AB_ASIDE_DURATION,
+  asideId = 'ab-aside',
 }: AbPageProviderProps): ReactElement {
   const [isAsideOpen, setAsideOpen] = useState(defaultAsideOpen);
   const [isAsideOpenOnMobile, setAsideOpenOnMobile] = useState(false);
@@ -97,27 +142,79 @@ export function AbPageProvider({
   const [isAsideClosing, setAsideClosing] = useState(false);
   const [isAsideLoading, setAsideLoading] = useState(false);
   const [asideElement, setAsideElementState] = useState<HTMLElement | null>(null);
+  // 📜 G55: the two pane scrollers (state, so consumers re-render once they mount)
+  const [mainScrollElement, setMainScrollElement] = useState<HTMLElement | null>(null);
+  const [asideScrollElement, setAsideScrollElement] = useState<HTMLElement | null>(null);
 
   const setAsideElement = useCallback((el: HTMLElement | null) => {
     setAsideElementState(el);
   }, []);
 
+  // ⏲️ 0.1.6 (James review): ONE pending open/close timer, so quick toggles never race
+  const asideTimerRef = useRef<number | undefined>(undefined);
+  useEffect(() => () => window.clearTimeout(asideTimerRef.current), []); // 🧹 unmount
+
   const setAsideOpenSafe = useCallback((open: boolean) => {
+    // ♿ 0.1.6: instant under reduced motion (no slide, no closing delay)
+    const ms = getAbAsideDuration(asideDuration, matches(AB_REDUCED_MOTION_QUERY));
+    window.clearTimeout(asideTimerRef.current); // 🛑 cancel the previous transition's timer
     if (open) {
-      setAsideOpening(true);
+      setAsideClosing(false); // 🔁 a close in flight is cancelled
+      setAsideOpening(ms > 0); // 🎞️ only "opening" when it animates
       setAsideOpen(true);
-      window.setTimeout(() => setAsideOpening(false), asideDuration);
+      if (ms > 0) asideTimerRef.current = window.setTimeout(() => setAsideOpening(false), ms);
+    } else if (ms === 0) {
+      setAsideOpening(false); // 🔁
+      setAsideClosing(false); // 🔁
+      setAsideOpen(false); // ⚡ instant
     } else {
+      setAsideOpening(false); // 🔁 an open in flight is cancelled
       setAsideClosing(true);
-      window.setTimeout(() => {
+      asideTimerRef.current = window.setTimeout(() => {
         setAsideOpen(false);
         setAsideClosing(false);
-      }, asideDuration);
+      }, ms);
     }
   }, [asideDuration]);
 
+  // 🔁 0.1.6: toggles for the »/« button (laptop+) and the TOC button (mobile/tablet sheet)
+  const toggleAside = useCallback(() => setAsideOpenSafe(!isAsideOpen), [isAsideOpen, setAsideOpenSafe]);
+  const toggleAsideOnMobile = useCallback(() => setAsideOpenOnMobile((v) => !v), []);
+
+  // ⎋ 0.1.6: Escape closes the mobile/tablet sheet, unless an inner menu/dialog already handled it
+  useEffect(() => {
+    if (!isAsideOpenOnMobile) return; // 💤 only while the sheet is open
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape' || e.defaultPrevented) return; // 🙅 an inner menu caught it (James review)
+      setAsideOpenOnMobile(false);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [isAsideOpenOnMobile]);
+
+  // 🎯 0.1.6 (James review): move focus INTO the sheet when it opens, and back to the opener when it closes
+  const sheetOpenerRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    if (isAsideOpenOnMobile) {
+      sheetOpenerRef.current = document.activeElement as HTMLElement | null; // 💾 the TOC button
+      const el = asideElement;
+      if (el) {
+        if (!el.hasAttribute('tabindex')) el.setAttribute('tabindex', '-1'); // 🎯 focusable container
+        el.focus({ preventScroll: true });
+      }
+    } else if (sheetOpenerRef.current) {
+      sheetOpenerRef.current.focus?.({ preventScroll: true }); // ↩️ return focus
+      sheetOpenerRef.current = null;
+    }
+  }, [isAsideOpenOnMobile, asideElement]);
+
   const value = useMemo<AbPageContextValue>(
     () => ({
+      mainScrollElement,
+      asideScrollElement,
+      setMainScrollElement,
+      setAsideScrollElement,
       isAsideOpen,
       isAsideOpenOnMobile,
       asideDuration,
@@ -129,8 +226,13 @@ export function AbPageProvider({
       setAsideOpen: setAsideOpenSafe,
       setAsideOpenOnMobile,
       setAsideLoading,
+      asideId,
+      toggleAside,
+      toggleAsideOnMobile,
     }),
     [
+      mainScrollElement,
+      asideScrollElement,
       isAsideOpen,
       isAsideOpenOnMobile,
       asideDuration,
@@ -140,6 +242,9 @@ export function AbPageProvider({
       isAsideClosing,
       isAsideLoading,
       setAsideOpenSafe,
+      asideId,
+      toggleAside,
+      toggleAsideOnMobile,
     ],
   );
 
@@ -154,4 +259,37 @@ export function useAbPage(): AbPageContextValue {
   return useContext(AbPageContext);
 }
 
+/** 🎛️ What {@link useAbAsideToggle} returns: spread `props` on the button. */
+export interface AbAsideToggle {
+  /** 📐 true below 1024px (the aside is a sheet, driven by `isAsideOpenOnMobile`). */
+  isSheet: boolean;
+  /** 👀 is the aside shown for the current viewport? */
+  expanded: boolean;
+  /** 🔁 flip it for the current viewport. */
+  toggle: () => void;
+  /** ♿ `aria-expanded` + `aria-controls` + `onClick` for a toggle button. */
+  props: { 'aria-expanded': boolean; 'aria-controls': string; onClick: () => void };
+}
+
+/**
+ * 📑 useAbAsideToggle (0.1.6) — one toggle for the TOC button (mobile/tablet sheet) and the »/« button
+ * (laptop+ pane). It picks the right state for the viewport and keeps `aria-expanded` / `aria-controls` right.
+ */
+export function useAbAsideToggle(): AbAsideToggle {
+  const { isAsideOpen, isAsideOpenOnMobile, asideId, toggleAside, toggleAsideOnMobile } = useAbPage();
+  // 📐 live viewport class (SSR: laptop+, so the server markup matches the default open pane)
+  const [isSheet, setSheet] = useState(false);
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+    const mq = window.matchMedia(AB_ASIDE_SHEET_QUERY); // 📐
+    const update = () => setSheet(mq.matches);
+    update();
+    mq.addEventListener?.('change', update);
+    return () => mq.removeEventListener?.('change', update);
+  }, []);
+  const expanded = isSheet ? isAsideOpenOnMobile : isAsideOpen; // 👀
+  const toggle = isSheet ? toggleAsideOnMobile : toggleAside; // 🔁
+  return { isSheet, expanded, toggle, props: { 'aria-expanded': expanded, 'aria-controls': asideId, onClick: toggle } };
+}
+
 export default AbPageProvider;

package/ab-page-provider/scroll-registrar.tsx

@@ -0,0 +1,71 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-core
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+*
+* @project: ab-nextjs-core
+* @name: AbScrollRegistrar (G55)
+* @file: ab-page-provider/scroll-registrar.tsx
+* @type: Client component
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
+'use client';
+
+// ⚛️ React
+import { useEffect, useRef, type ReactElement } from 'react';
+// 🧠 the page context (no-op setters outside an AbPageProvider)
+import { useAbPage } from './index';
+
+/** ⚙️ props */
+export interface AbScrollRegistrarProps {
+  pane: 'main' | 'aside'; // 📜 which scroller to publish
+}
+
+/**
+ * 📌 AbScrollRegistrar — a tiny client island for the SERVER `AbMainLayout` / `AbAsideLayout` (G55, Joseph).
+ * Server components can't hold a ref, so the server layouts render this as the first child of their content
+ * wrapper: it publishes its parent (the `data-ab-part="main-content"` / `"aside-content"` scroller) on
+ * `useAbPage()` as `mainScrollElement` / `asideScrollElement`, in an effect, and clears it on unmount.
+ * It renders one hidden, empty `<span>` (no layout, no a11y tree).
+ */
+export function AbScrollRegistrar({ pane }: AbScrollRegistrarProps): ReactElement {
+  const { setMainScrollElement, setAsideScrollElement } = useAbPage(); // 🧠
+  const ref = useRef<HTMLSpanElement>(null); // 📍
+  useEffect(() => {
+    const set = pane === 'main' ? setMainScrollElement : setAsideScrollElement; // 🎯
+    set(ref.current?.parentElement ?? null); // 📜 the content wrapper = the scroller
+    return () => set(null); // 🧹
+  }, [pane, setMainScrollElement, setAsideScrollElement]);
+  return <span ref={ref} hidden data-ab-part="scroll-registrar" />; // 🫥
+}
+
+// 📦 default export
+export default AbScrollRegistrar;

package/ab-page-provider/slot.ts

@@ -0,0 +1,51 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-core
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+*
+* @project: ab-nextjs-core
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🫥 0.1.6 (G52, D37): server-safe (no 'use client'), shared by the client and server layouts
+
+import { createElement, type ReactNode } from 'react';
+
+/**
+ * 🫥 toAbSlot — normalise a slot for rendering:
+ * · `null` / `undefined` / `false` / `''` / `[]` → `null`, so the wrapper is NOT rendered (0px)
+ * · a bare string / number → wrapped in a `<span>`, so the CSS `:not(:has(> *))` collapse never hides text
+ * · anything else (elements, fragments, arrays with content) → returned as is
+ */
+export function toAbSlot(node: ReactNode): ReactNode {
+  if (node == null || node === false || node === true || node === '') return null; // 🙅 empty
+  if (Array.isArray(node) && node.every((n) => n == null || n === false || n === true || n === '')) return null; // 🙅 empty list
+  if (typeof node === 'string' || typeof node === 'number') return createElement('span', { 'data-ab-part': 'slot-text' }, node); // 🔤
+  return node; // ✅
+}

package/ab-screen-layout/index.tsx

@@ -24,7 +24,7 @@
 * SOFTWARE.
 *
 * @project: ab-nextjs-core
-* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -71,13 +71,13 @@ const AbScreenLayout = ({
       data-screen-name={screenName}
       data-orientation={orientation ?? ''}
     >
-      <header className={clsx(['HeaderWrapper', styles.abScreenLayout__headerWrapper])}>
+      <header className={clsx(['HeaderWrapper', styles.abScreenLayout__headerWrapper])} data-ab-part="header">
         {header}
       </header>
       <div className={clsx(['ContentWrapper', styles.abScreenLayout__contentWrapper])}>
         {content ?? children}
       </div>
-      <footer className={clsx(['FooterWrapper', styles.abScreenLayout__footerWrapper])}>
+      <footer className={clsx(['FooterWrapper', styles.abScreenLayout__footerWrapper])} data-ab-part="footer">
         {footer}
       </footer>
       <div id="backdrop" className={clsx(['Backdrop', styles.abScreenLayout__backdrop])} hidden />