ab-nextjs-core 0.1.0 → 0.1.2

package/ab-linear-progress/index.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
+* @authors: Abraham Ukachi <abraham.ukachi@laplateforme.io>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+import type { ReactElement } from 'react';
+import clsx from 'clsx';
+
+export interface AbLinearProgressProps {
+  className?: string;
+  color?: string;
+  hidden?: boolean;
+  isIndeterminate?: boolean;
+  progress?: number;
+}
+
+/**
+ * Minimal linear-progress stub (API parity with LYD chrome).
+ */
+const AbLinearProgress = ({
+  className,
+  hidden = true,
+  progress = 25,
+}: AbLinearProgressProps): ReactElement => {
+  return (
+    <div
+      className={clsx(['AbLinearProgress', className])}
+      hidden={hidden}
+      role="progressbar"
+      aria-valuenow={progress}
+      aria-hidden={hidden ? true : undefined}
+    >
+      <div
+        className="h-full bg-current opacity-60"
+        style={{ width: `${Math.min(100, Math.max(0, progress))}%` }}
+      />
+    </div>
+  );
+};
+
+export default AbLinearProgress;

package/ab-main-layout/index.tsx

@@ -0,0 +1,114 @@
+/* 
+* @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 <abraham.ukachi@laplateforme.io>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client';
+
+import type { ReactElement, ReactNode } from 'react';
+import clsx from 'clsx';
+import AbLinearProgress from '../ab-linear-progress';
+import styles from './styles.module.css';
+
+export interface AbMainLayoutProps {
+  orientation: 'vertical' | 'horizontal';
+  className?: string;
+  hidden?: boolean;
+  pageName?: string;
+  screenName?: string;
+  header?: ReactNode;
+  content?: ReactNode;
+  footer?: ReactNode;
+  children?: ReactNode;
+  menus?: ReactNode;
+}
+
+/** Client markup mirror of server AbMainLayout. */
+const AbMainLayout = ({
+  orientation,
+  className,
+  hidden,
+  pageName,
+  screenName,
+  header,
+  content,
+  footer,
+  children,
+  menus,
+}: AbMainLayoutProps): ReactElement => {
+  return (
+    <main
+      className={clsx(
+        ['AbMainLayout', 'group-mainLayout', styles.abMainLayout, className],
+        { 'has-screen-name': !!screenName },
+      )}
+      style={{ maxHeight: screenName ? 'initial' : undefined }}
+      hidden={hidden}
+      data-page-name={pageName}
+      data-screen-name={screenName}
+    >
+      <div className={clsx(['HeaderWrapper', styles.abMainLayout__headerWrapper])}>
+        {header}
+      </div>
+      <div
+        className={clsx([
+          'ContentWrapper',
+          styles.abMainLayout__contentWrapper,
+          orientation === 'horizontal' && 'md:!flex-row',
+        ])}
+        data-orientation={orientation ? orientation.toString() : undefined}
+      >
+        {content ?? children}
+      </div>
+      <div className={clsx(['FooterWrapper', styles.abMainLayout__footerWrapper])}>
+        {footer}
+      </div>
+      <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>
+  );
+};
+
+export default AbMainLayout;

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

@@ -0,0 +1,167 @@
+/* 
+* @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: 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>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
+/* ===== AB MAIN LAYOUT STYLES ===== */
+
+.abMainLayout {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  z-index: 20;
+  background-color: var(--color-background, var(--surface, #ffffff));
+}
+
+@media (max-width: 639px) {
+  .abMainLayout { max-height: calc(100vh - 60px); }
+}
+
+@media (max-width: 767px) {
+  .abMainLayout { max-height: calc(100vh - 64px); }
+}
+
+@media (min-width: 1536px) {
+  .abMainLayout { border-radius: 1.5rem; }
+}
+
+:global(.dark) .abMainLayout,
+:global([data-theme="dark"]) .abMainLayout {
+  background-color: var(--color-dark-background, var(--surface, #0a0a0a));
+}
+
+.abMainLayout__headerWrapper {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: auto;
+  z-index: 20;
+  pointer-events: none;
+}
+
+.abMainLayout__contentWrapper {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: fit-content;
+  flex-grow: 1;
+  flex: 1 1 0%;
+  justify-content: space-between;
+  z-index: 10;
+  overflow: auto;
+  overflow-x: hidden;
+}
+
+.abMainLayout__footerWrapper {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: auto;
+  z-index: 20;
+  pointer-events: none;
+}
+
+.abMainLayout__footerWrapper::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: -1;
+  transform: translateY(-100%);
+  background-image: linear-gradient(to bottom, transparent, var(--color-background, var(--surface, #ffffff)));
+}
+
+:global(.dark) .abMainLayout__footerWrapper::before,
+:global([data-theme="dark"]) .abMainLayout__footerWrapper::before {
+  background-image: linear-gradient(to bottom, transparent, var(--color-dark-background, var(--surface, #0a0a0a)));
+}
+
+.abMainLayout__backdrop {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 40;
+  backdrop-filter: blur(12px);
+  background-color: rgb(0 0 0 / 0.1);
+}
+
+:global(.dark) .abMainLayout__backdrop,
+:global([data-theme="dark"]) .abMainLayout__backdrop {
+  background-color: rgb(0 0 0 / 0.5);
+}
+
+.abMainLayout__menus {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 50;
+  padding-bottom: 0;
+}
+
+.abMainLayout__dialogs,
+.abMainLayout__toasts {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 50;
+}
+
+.abMainLayout__toasts { animation: abCoreFadeIn 300ms ease-in-out; }
+
+.abMainLayout__canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  z-index: 50;
+}
+
+@keyframes abCoreFadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}

package/ab-page-provider/index.tsx

@@ -0,0 +1,157 @@
+/* 
+* @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 <abraham.ukachi@laplateforme.io>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+export interface AbPageContextValue {
+  isAsideOpen: boolean;
+  isAsideOpenOnMobile: boolean;
+  asideDuration: number;
+  asideElement: HTMLElement | null;
+  setAsideElement: (el: HTMLElement | null) => void;
+  isAsideOpening: boolean;
+  isAsideClosing: boolean;
+  isAsideLoading: boolean;
+  setAsideOpen: (open: boolean) => void;
+  setAsideOpenOnMobile: (open: boolean) => void;
+  setAsideLoading: (loading: boolean) => void;
+}
+
+const defaultValue: AbPageContextValue = {
+  isAsideOpen: true,
+  isAsideOpenOnMobile: false,
+  asideDuration: 300,
+  asideElement: null,
+  setAsideElement: () => {},
+  isAsideOpening: false,
+  isAsideClosing: false,
+  isAsideLoading: false,
+  setAsideOpen: () => {},
+  setAsideOpenOnMobile: () => {},
+  setAsideLoading: () => {},
+};
+
+const AbPageContext = createContext<AbPageContextValue>(defaultValue);
+
+export interface AbPageProviderProps {
+  children?: ReactNode;
+  /** Initial aside open state (default true so shells render visibly). */
+  defaultAsideOpen?: boolean;
+  asideDuration?: number;
+}
+
+/**
+ * Minimal page contract for client AbAsideLayout (LYD useLydPage aside slice).
+ * Not a port of LydPageProvider — only aside open/loading/element state.
+ */
+export function AbPageProvider({
+  children,
+  defaultAsideOpen = true,
+  asideDuration = 300,
+}: AbPageProviderProps): ReactElement {
+  const [isAsideOpen, setAsideOpen] = useState(defaultAsideOpen);
+  const [isAsideOpenOnMobile, setAsideOpenOnMobile] = useState(false);
+  const [isAsideOpening, setAsideOpening] = useState(false);
+  const [isAsideClosing, setAsideClosing] = useState(false);
+  const [isAsideLoading, setAsideLoading] = useState(false);
+  const [asideElement, setAsideElementState] = useState<HTMLElement | null>(null);
+
+  const setAsideElement = useCallback((el: HTMLElement | null) => {
+    setAsideElementState(el);
+  }, []);
+
+  const setAsideOpenSafe = useCallback((open: boolean) => {
+    if (open) {
+      setAsideOpening(true);
+      setAsideOpen(true);
+      window.setTimeout(() => setAsideOpening(false), asideDuration);
+    } else {
+      setAsideClosing(true);
+      window.setTimeout(() => {
+        setAsideOpen(false);
+        setAsideClosing(false);
+      }, asideDuration);
+    }
+  }, [asideDuration]);
+
+  const value = useMemo<AbPageContextValue>(
+    () => ({
+      isAsideOpen,
+      isAsideOpenOnMobile,
+      asideDuration,
+      asideElement,
+      setAsideElement,
+      isAsideOpening,
+      isAsideClosing,
+      isAsideLoading,
+      setAsideOpen: setAsideOpenSafe,
+      setAsideOpenOnMobile,
+      setAsideLoading,
+    }),
+    [
+      isAsideOpen,
+      isAsideOpenOnMobile,
+      asideDuration,
+      asideElement,
+      setAsideElement,
+      isAsideOpening,
+      isAsideClosing,
+      isAsideLoading,
+      setAsideOpenSafe,
+    ],
+  );
+
+  return <AbPageContext.Provider value={value}>{children}</AbPageContext.Provider>;
+}
+
+/**
+ * Hook contract used by client AbAsideLayout.
+ * Returns safe defaults when used outside AbPageProvider.
+ */
+export function useAbPage(): AbPageContextValue {
+  return useContext(AbPageContext);
+}
+
+export default AbPageProvider;

package/ab-screen-layout/index.tsx

@@ -0,0 +1,101 @@
+/* 
+* @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 <abraham.ukachi@laplateforme.io>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client';
+
+import type { ReactElement, ReactNode } from 'react';
+import clsx from 'clsx';
+import AbLinearProgress from '../ab-linear-progress';
+import styles from './styles.module.css';
+
+export interface AbScreenLayoutProps {
+  orientation: 'vertical' | 'horizontal';
+  className?: string;
+  hidden?: boolean;
+  screenName?: string;
+  header?: ReactNode;
+  content?: ReactNode;
+  footer?: ReactNode;
+  children?: ReactNode;
+  menus?: ReactNode;
+}
+
+/** Client markup mirror of server AbScreenLayout. */
+const AbScreenLayout = ({
+  orientation,
+  className,
+  hidden,
+  screenName,
+  header,
+  content,
+  footer,
+  children,
+  menus,
+}: AbScreenLayoutProps): ReactElement => {
+  return (
+    <div
+      className={clsx(['AbScreenLayout', styles.abScreenLayout, className])}
+      hidden={hidden}
+      data-screen-name={screenName}
+      data-orientation={orientation ?? ''}
+    >
+      <div className={clsx(['HeaderWrapper', styles.abScreenLayout__headerWrapper])}>
+        {header}
+      </div>
+      <div className={clsx(['ContentWrapper', styles.abScreenLayout__contentWrapper])}>
+        {content ?? children}
+      </div>
+      <div className={clsx(['FooterWrapper', styles.abScreenLayout__footerWrapper])}>
+        {footer}
+      </div>
+      <div id="backdrop" className={clsx(['Backdrop', styles.abScreenLayout__backdrop])} hidden />
+      <div id="menus" className={clsx(['Menus', styles.abScreenLayout__menus])} hidden>
+        {menus}
+      </div>
+      <div id="dialogs" className={clsx(['Dialogs', styles.abScreenLayout__dialogs])} hidden />
+      <div id="toasts" className={clsx(['Toasts', styles.abScreenLayout__toasts])} hidden />
+      <AbLinearProgress
+        className="absolute top-0 left-0 right-0 z-50 !h-0.5 lg:!h-1"
+        color="secondary"
+        hidden={true}
+        isIndeterminate={true}
+        progress={25}
+      />
+      <canvas className={clsx(['Canvas', styles.abScreenLayout__canvas])} />
+    </div>
+  );
+};
+
+export default AbScreenLayout;