@axzydev/axzy_ui_system 1.4.1 → 1.4.3

package/src/components/organisms/topbar/topbar.tsx

@@ -3,6 +3,7 @@ import useClickOutside from "@/hooks/useClickOutside";
 import { useRef, useState } from "react";
 import { ITTopBarProps } from "./topbar.props";
 import ITText from "@/components/atoms/text/text";
+import { useITFlatAppearance } from "@/theme/theme-context";
 
 /**
  * ITTopBar — sticky top navigation bar with logo, nav items, and user avatar dropdown.
@@ -67,7 +68,16 @@ export default function ITTopBar({
   onToggleMobileMenu,
   navItems,
   onNavItemClick,
+  hideBrandOnDesktop = false,
 }: ITTopBarProps) {
+  // Flat appearance: plain bar (no shadow/blur), initials avatar, name before it.
+  const flat = useITFlatAppearance();
+  const initials = (userMenu?.userName ?? "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((word) => word.charAt(0).toUpperCase())
+    .join("");
   const [isUserMenuOpen, setIsUserMenuOpen] = useState(false);
   const userMenuRef = useRef<HTMLDivElement>(null);
 
@@ -75,14 +85,14 @@ export default function ITTopBar({
 
   return (
     <header 
-      className="sticky top-0 z-40 backdrop-blur-md transition-all duration-300"
+      className={`sticky top-0 z-40 transition-all duration-300 ${flat ? "" : "backdrop-blur-md"}`}
       style={{
         backgroundColor: "var(--it-topbar-bg, rgba(255, 255, 255, 0.9))",
         borderBottom: "1px solid var(--it-topbar-border, rgba(15, 23, 42, 0.06))",
-        boxShadow: "var(--shadow-xs)",
+        boxShadow: flat ? "none" : "var(--shadow-xs)",
       }}
     >
-      <div className="flex items-center justify-between h-[72px] px-6 lg:px-8">
+      <div className={`flex items-center justify-between px-6 lg:px-8 ${flat ? "h-[64px]" : "h-[72px]"}`}>
 
         {/* LEFT AREA: Logo & Mobile Toggle */}
         <div className="flex items-center gap-5">
@@ -103,7 +113,7 @@ export default function ITTopBar({
           )}
 
           {/* Logo */}
-          <div className="flex items-center gap-3">
+          <div className={`items-center gap-3 ${hideBrandOnDesktop ? "flex lg:hidden" : "flex"}`}>
             {logo && (
               <div className="flex-shrink-0 drop-shadow-sm">
                  {logo}
@@ -153,7 +163,7 @@ export default function ITTopBar({
             `justify-between` has nothing left to distribute: the logo/nav and
             the user menu stay flush with the row edges. */}
         {centerContent && (
-          <div className="hidden lg:flex flex-1 min-w-0 items-center justify-center px-4">
+          <div className={`hidden lg:flex flex-1 min-w-0 items-center ${hideBrandOnDesktop ? "justify-start pr-4" : "justify-center px-4"}`}>
             <div className="w-full max-w-[420px]">{centerContent}</div>
           </div>
         )}
@@ -169,7 +179,7 @@ export default function ITTopBar({
               <div className="relative">
                 <button
                   type="button"
-                  className="flex items-center gap-3 rounded-full pl-2 pr-4 py-1.5 transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)] border border-transparent hover:border-secondary-200"
+                  className={`flex items-center gap-3 rounded-full py-1.5 transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)] border border-transparent hover:border-secondary-200 ${flat ? "flex-row-reverse pl-4 pr-2" : "pl-2 pr-4"}`}
                   style={{
                     backgroundColor: isUserMenuOpen ? "var(--it-topbar-user-hover, #f1f5f9)" : "transparent",
                   }}
@@ -189,17 +199,30 @@ export default function ITTopBar({
                         src={userMenu.userImage}
                         alt="Current user"
                       />
+                    ) : flat && initials ? (
+                      <div
+                        aria-hidden="true"
+                        className="w-9 h-9 rounded-full flex items-center justify-center text-[0.8rem] font-semibold"
+                        style={{
+                          backgroundColor: "color-mix(in srgb, var(--color-primary, #3b82f6) 14%, transparent)",
+                          color: "var(--color-primary, #2563eb)",
+                        }}
+                      >
+                        {initials}
+                      </div>
                     ) : (
                       <div className="w-9 h-9 rounded-full bg-slate-100 flex items-center justify-center ring-2 ring-white shadow-sm">
                          <FaUserCircle className="w-6 h-6" style={{ color: "var(--it-topbar-icon, #94a3b8)" }} />
                       </div>
                     )}
                     {/* Active dot indicator */}
-                    <div className="absolute bottom-0 right-0 w-2.5 h-2.5 bg-green-500 border-2 border-white rounded-full"></div>
+                    {!flat && (
+                      <div className="absolute bottom-0 right-0 w-2.5 h-2.5 bg-green-500 border-2 border-white rounded-full"></div>
+                    )}
                   </div>
 
                   {/* Name Details */}
-                  <div className="hidden sm:flex flex-col text-left py-0.5">
+                  <div className={`hidden sm:flex flex-col py-0.5 ${flat ? "text-right" : "text-left"}`}>
                     <ITText as="span" 
                       className="font-semibold text-[0.85rem] leading-tight"
                       style={{ color: "var(--it-topbar-user-text, #0f172a)" }}

package/src/components/templates/layout/layout.props.ts

@@ -12,4 +12,12 @@ export interface ITLayoutProps {
   className?: string;
   /** Additional CSS classes for the content container */
   contentClassName?: string;
+  /**
+   * App-shell arrangement. `false` (default): the top bar spans the full width
+   * and the sidebar sits below it. `true`: the sidebar spans the full viewport
+   * height and shows the brand (`topBar.logo` + `topBar.logoText`) at its top,
+   * while the top bar covers only the content column and drops the logo from
+   * the `lg` breakpoint up. Mobile is unchanged. @default false
+   */
+  sidebarFullHeight?: boolean;
 } 

package/src/components/templates/layout/layout.tsx

@@ -4,6 +4,7 @@ import ITTopBar from "@/components/organisms/topbar/topbar";
 import ITSidebar from "@/components/organisms/sidebar/sidebar";
 import { ITLayoutProps } from "./layout.props";
 import { theme } from "@/theme/theme";
+import { useITFlatAppearance } from "@/theme/theme-context";
 
 /**
  * Main application shell with sidebar, topbar, and content area.
@@ -27,6 +28,16 @@ import { theme } from "@/theme/theme";
  * >
  *   <SettingsPage />
  * </ITLayout>
+ *
+ * @example
+ * // Full-height sidebar with the brand on top; the top bar covers only the content.
+ * <ITLayout
+ *   sidebarFullHeight
+ *   topBar={{ logo: <Logo />, logoText: "Acme", centerContent: <SearchBox /> }}
+ *   sidebar={{ navigationItems, isCollapsed: false }}
+ * >
+ *   <Dashboard />
+ * </ITLayout>
  */
 export default function ITLayout({
   topBar,
@@ -34,77 +45,113 @@ export default function ITLayout({
   children,
   className = "",
   contentClassName = "",
+  sidebarFullHeight = false,
 }: ITLayoutProps) {
   const [internalCollapsed, setInternalCollapsed] = useState(true);
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
+  const flat = useITFlatAppearance();
 
   const isControlled = sidebar.isCollapsed !== undefined;
   const desktopCollapsed = isControlled ? sidebar.isCollapsed : internalCollapsed;
   const handleToggleCollapse = isControlled ? (sidebar.onToggleCollapse ?? (() => {})) : () => setInternalCollapsed(v => !v);
 
   const layoutTokens = theme.layout;
+  // Must match ITSidebar's own at-rest width (88px rail / 280px, 248px when flat).
+  const reservedWidth = desktopCollapsed ? "w-[88px]" : flat ? "w-[248px]" : "w-[280px]";
+  // With a full-height sidebar the brand moves from the top bar to the sidebar.
+  const brand = sidebarFullHeight
+    ? (sidebar.brand ?? { logo: topBar.logo, text: topBar.logoText })
+    : sidebar.brand;
 
-  return (
-    <div className={`flex flex-col h-screen overflow-hidden w-full ${className}`}>
-      <ITTopBar
-        {...topBar}
-        showMobileMenuButton
-        onToggleMobileMenu={() => setMobileSidebarOpen(v => !v)}
-      />
+  const topBarNode = (
+    <ITTopBar
+      {...topBar}
+      hideBrandOnDesktop={sidebarFullHeight || topBar.hideBrandOnDesktop}
+      showMobileMenuButton
+      onToggleMobileMenu={() => setMobileSidebarOpen(v => !v)}
+    />
+  );
 
+  const desktopSidebar = (
+    // Full-height: the sidebar sits beside the top bar, so it needs to win the
+    // stacking order when the collapsed rail expands over the content on hover.
+    <div className={`hidden lg:block relative h-full ${sidebarFullHeight ? "z-50" : "z-40"}`}>
+      {/* Reserves the sidebar's at-rest width. When the sidebar is collapsed
+          (default), this is the 88px rail and hover expands over the content.
+          When controlled-expanded (`sidebar.isCollapsed === false`), it
+          reserves the full width so the sidebar never overlays content. */}
+      <div className={`${reservedWidth} h-full flex-shrink-0`} />
+      <div className="absolute top-0 left-0 h-full">
+        <ITSidebar
+          {...sidebar}
+          brand={brand}
+          isCollapsed={desktopCollapsed}
+          onToggleCollapse={handleToggleCollapse}
+          visibleOnMobile={false}
+          className={`h-full ${flat ? "" : "drop-shadow-2xl"} transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] flex-shrink-0`}
+        />
+      </div>
+    </div>
+  );
+
+  const mobileSidebar = mobileSidebarOpen && (
+    <div
+      className="lg:hidden fixed inset-0 z-[40] transition-opacity duration-300 backdrop-blur-sm bg-black/40"
+      onClick={() => setMobileSidebarOpen(false)}
+    >
       <div
-        className="flex flex-1 overflow-hidden relative"
+        className="h-full w-fit flex transform transition-transform duration-300 ease-[cubic-bezier(0.2,0,0,1)]"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <ITSidebar
+          {...sidebar}
+          brand={brand}
+          isCollapsed={false}
+          visibleOnMobile={true}
+          className="h-full shadow-2xl relative z-[60]"
+          onToggleCollapse={() => setMobileSidebarOpen(false)}
+          onItemClick={() => setMobileSidebarOpen(false)}
+          onSubItemClick={() => setMobileSidebarOpen(false)}
+        />
+      </div>
+    </div>
+  );
+
+  const main = (
+    <main className="flex-1 overflow-y-auto w-full custom-scrollbar relative z-0">
+      <div className={clsx("mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8 py-6 h-full", contentClassName)}>
+        {children}
+      </div>
+    </main>
+  );
+
+  if (sidebarFullHeight) {
+    return (
+      <div
+        className={`flex h-screen overflow-hidden w-full relative ${className}`}
         style={{ backgroundColor: layoutTokens.backgroundColor }}
       >
-        {/* DESKTOP SIDEBAR */}
-        <div className="hidden lg:block relative z-40 h-full">
-          {/* Reserves the sidebar's at-rest width. When the sidebar is collapsed
-              (default), this is the 88px rail and hover expands over the content.
-              When controlled-expanded (`sidebar.isCollapsed === false`), it
-              reserves the full 280px so the sidebar never overlays content. */}
-          <div
-            className={`${desktopCollapsed ? "w-[88px]" : "w-[280px]"} h-full flex-shrink-0`}
-          />
-          <div className="absolute top-0 left-0 h-full">
-            <ITSidebar
-              {...sidebar}
-              isCollapsed={desktopCollapsed}
-              onToggleCollapse={handleToggleCollapse}
-              visibleOnMobile={false}
-              className="h-full drop-shadow-2xl transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] flex-shrink-0"
-            />
-          </div>
+        {desktopSidebar}
+        <div className="flex flex-col flex-1 min-w-0 overflow-hidden">
+          {topBarNode}
+          {main}
         </div>
+        {mobileSidebar}
+      </div>
+    );
+  }
 
-        {/* MOBILE SIDEBAR PANE */}
-        {mobileSidebarOpen && (
-          <div
-            className="lg:hidden fixed inset-0 z-[40] transition-opacity duration-300 backdrop-blur-sm bg-black/40"
-            onClick={() => setMobileSidebarOpen(false)}
-          >
-            <div
-              className="h-full w-fit flex transform transition-transform duration-300 ease-[cubic-bezier(0.2,0,0,1)]"
-              onClick={(e) => e.stopPropagation()}
-            >
-              <ITSidebar
-                {...sidebar}
-                isCollapsed={false}
-                visibleOnMobile={true}
-                className="h-full shadow-2xl relative z-[60]"
-                onToggleCollapse={() => setMobileSidebarOpen(false)}
-                onItemClick={() => setMobileSidebarOpen(false)}
-                onSubItemClick={() => setMobileSidebarOpen(false)}
-              />
-            </div>
-          </div>
-        )}
+  return (
+    <div className={`flex flex-col h-screen overflow-hidden w-full ${className}`}>
+      {topBarNode}
 
-        {/* MAIN CONTENT AREA */}
-        <main className="flex-1 overflow-y-auto w-full custom-scrollbar relative z-0">
-          <div className={clsx("mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8 py-6 h-full", contentClassName)}>
-            {children}
-          </div>
-        </main>
+      <div
+        className="flex flex-1 overflow-hidden relative"
+        style={{ backgroundColor: layoutTokens.backgroundColor }}
+      >
+        {desktopSidebar}
+        {mobileSidebar}
+        {main}
       </div>
     </div>
   );

package/src/components/theme-provider/themeProvider.doc.mdx

@@ -17,6 +17,7 @@ Root theme context that injects CSS custom properties into the entire component
 | `density` | `number` | `1` | Global density/compactness factor: values below `1` shrink base sizes (fonts, paddings, gaps), above `1` grow them. Applies by scaling the root font-size so every `rem`-based token compacts together while the layout stays fluid. Clamped to `0.5`–`1.5`. |
 | `radius` | `number` | — | Global border radius in **px** applied to the whole rounding scale. `2` ⇒ 2px corners (near-square), `8` ⇒ 8px, `0` ⇒ square. No override when omitted (Tailwind defaults). |
 | `shadow` | `number` | `2` | Global shadow strength level: `0` ⇒ none, `1` ⇒ subtle, `2` ⇒ default current look, `3` ⇒ pronounced. No override when omitted (keeps defaults). |
+| `appearance` | `"soft" \| "flat"` | `"soft"` | Visual language. `"flat"` switches `ITCard`, `ITSidebar`, `ITTopBar` and `ITPageHeader` to flat surfaces (hairline borders, no shadows, no header icon tile) and sets `data-it-appearance` on `<html>`. Read it in your own components with `useITFlatAppearance()`. |
 
 ### ITThemePalette Shape
 

package/src/components/theme-provider/themeProvider.props.ts

@@ -1,3 +1,7 @@
+import type { ITThemeAppearance } from "@/theme/theme.types";
+
+export type { ITThemeAppearance };
+
 export interface ITThemePalette {
   /** Main brand accent color (hex). Drives primary buttons, active nav items, focus rings, links, and the `--color-primary` CSS variable. @default "#06b6d4" */
   primary: string;
@@ -54,4 +58,6 @@ export interface ITThemeProviderProps {
   radius?: number;
   /** Global shadow strength level. `0` ⇒ no shadows, `1` ⇒ subtle, `2` ⇒ default current look, `3` ⇒ pronounced. Shadows are injected as `--shadow-*`/`.shadow-*` overrides so cards, dropdowns and dialogs follow the level. @default 2 (keeps current default when omitted) */
   shadow?: number;
+  /** Visual language of the whole system. `"soft"` keeps the current look (floating cards, tinted shadows, glass sidebar/top bar). `"flat"` switches the app shell and surfaces to flat ones: hairline borders instead of shadows on `ITCard`, a plain `ITSidebar` (no glow, no accent bar, narrower), a plain `ITTopBar` (no shadow, initials avatar) and a compact `ITPageHeader` without the icon tile. It also sets `data-it-appearance` on `<html>` so app CSS can follow it. Combine it with `shadow` and `radius` to finish the look. @default "soft" */
+  appearance?: ITThemeAppearance;
 }

package/src/components/theme-provider/themeProvider.tsx

@@ -73,7 +73,7 @@ import { DEFAULT_PALETTE, PRESETS } from "./themePresets";
 // Contexto y hooks (useITTheme / useITThemeSafe) viven en @/theme/theme-context.
 // Re-exportados desde aquí para mantener compatibilidad de la API pública.
 // eslint-disable-next-line react-refresh/only-export-components
-export { useITTheme, useITThemeSafe } from "@/theme/theme-context";
+export { useITTheme, useITThemeSafe, useITFlatAppearance } from "@/theme/theme-context";
 
 const getNestedValue = (obj: any, path: string) => {
   return path.split(".").reduce((acc, part) => acc && acc[part], obj);
@@ -143,6 +143,7 @@ export default function ITThemeProvider({
   density = 1,
   radius,
   shadow,
+  appearance = "soft",
 }: ITThemeProviderProps) {
   const [palette, setPaletteState] = useState<ITThemePalette>(() => {
     const basePalette = {
@@ -276,6 +277,14 @@ export default function ITThemeProvider({
     };
   }, [density]);
 
+  // Lenguaje visual: se publica en <html> para que el CSS de la app pueda
+  // seguirlo; los componentes lo leen del contexto (useITFlatAppearance).
+  useLayoutEffect(() => {
+    const root = document.documentElement;
+    root.setAttribute("data-it-appearance", appearance);
+    return () => root.removeAttribute("data-it-appearance");
+  }, [appearance]);
+
   // Overrides globales de radius y sombras.
   // Radius: en Tailwind v4 cada `rounded-*` resuelve a var(--radius-*), así que
   // setear los vars en :root (en px) cuadra/redondea todo el sistema sin tocar
@@ -1611,6 +1620,7 @@ export default function ITThemeProvider({
         resolvedTheme,
         darkModeMode,
         setDarkModeMode,
+        appearance,
       }}
     >
       {children}

package/src/index.ts

@@ -103,7 +103,7 @@ import type { ITSearchSelectProps } from "./components/molecules/search-select/s
 import type { ITSelectProps } from "./components/molecules/select/select.props";
 import type { ITSearchTableProps } from "./components/organisms/searchTable/searchTable.props";
 import type { ITSegmentedControlProps } from "./components/atoms/segmented-control/segmented-control.props";
-import type { ITSidebarProps, ITNavigationItem, ITNavigationSubItem, ITNavigationSubItemEntry, ITNavigationSubItemGroup } from "./components/organisms/sidebar/sidebar.props";
+import type { ITSidebarProps, ITSidebarNotification, ITSidebarBrand, ITNavigationItem, ITNavigationSubItem, ITNavigationSubItemEntry, ITNavigationSubItemGroup } from "./components/organisms/sidebar/sidebar.props";
 import type { ITSkeletonProps } from "./components/atoms/skeleton/skeleton.props";
 import type { ITSlideToggleProps } from "./components/atoms/slide/slide.props";
 import type { ITSliderProps } from "./components/atoms/slider/slider.props";
@@ -127,8 +127,8 @@ import ITLoader from "./components/atoms/loader/loader";
 import type { LoaderProps as ITLoaderProps } from "./components/atoms/loader/loader.props";
 import ITStepper from "./components/molecules/stepper/stepper";
 import type { ITStepperProps } from "./components/molecules/stepper/stepper.props";
-import ITThemeProvider, { useITTheme, useITThemeSafe } from "./components/theme-provider/themeProvider";
-import type { ITThemeProviderProps, ITThemePalette } from "./components/theme-provider/themeProvider.props";
+import ITThemeProvider, { useITTheme, useITThemeSafe, useITFlatAppearance } from "./components/theme-provider/themeProvider";
+import type { ITThemeProviderProps, ITThemePalette, ITThemeAppearance } from "./components/theme-provider/themeProvider.props";
 import ITTimePicker from "./components/molecules/time-picker/timePicker";
 import type { ITTimePickerProps } from "./components/molecules/time-picker/timePicker.props";
 import type { ITThemeConfig } from "./theme/theme.types";
@@ -153,7 +153,7 @@ export {
   ITSearchTable,
   ITSegmentedControl, ITSidebar, ITSkeleton, ITSlideToggle, ITSlider, ITStack, ITStatCard, ITStepper,
   ITTable, ITTabs, ITText, ITTextarea, ITTripleFilter, ITThemeProvider,
-  useITTheme, useITThemeSafe, ITTimePicker, ITToast, ITWysiwyg,
+  useITTheme, useITThemeSafe, useITFlatAppearance, ITTimePicker, ITToast, ITWysiwyg,
   UploadStatus, FileTypeEnum,
   getContrastTextColor, isLightColor, resolveCssColor
 };
@@ -176,6 +176,7 @@ export {
     ITPageProps, ITPageHeaderProps,
     ITNavigationItem, ITNavigationSubItem,
     ITNavigationSubItemEntry, ITNavigationSubItemGroup,
+    ITSidebarNotification, ITSidebarBrand,
     ITPaginationProps, ITPopoverProps, ITProgressProps,
     ITRadioGroupProps, ITRadioOption, ITSelectProps, ITSearchSelectProps,
     ITSearchTableProps,
@@ -183,7 +184,7 @@ export {
     ITStackProps, ITStatCardProps, ITStepperProps,
     ITTableProps, ITTabsProps, ITTabItem, ITTextProps, ITTextareaProps,
     TableDensity,
-    ITTripleFilterProps, ITTripleFilterOption, ITThemeConfig, ITThemeProviderProps, ITThemePalette,
+    ITTripleFilterProps, ITTripleFilterOption, ITThemeConfig, ITThemeProviderProps, ITThemePalette, ITThemeAppearance,
     ITTimePickerProps, ITToastProps,
     ITWysiwygProps,
     UseTableStateOptions, UseTableStateResult

package/src/sandbox/LandingShowcase.tsx

@@ -72,7 +72,7 @@ const GROUP_ACCENTS = [
   "from-primary-500 to-purple-500",
 ];
 
-const GITHUB_URL = "https://github.com/axzydev/axzy_ui_system";
+const GITHUB_URL = "https://github.com/maag070208/AXZY_UI_SYSTEM";
 const INSTALL_CMD = "pnpm add @axzydev/axzy_ui_system";
 
 /**

package/src/sandbox/navigation.ts

@@ -30,6 +30,7 @@ export const SANDBOX_GROUPS: SandboxGroup[] = [
     label: "General",
     subitems: [
       { id: "getting-started", label: "Getting Started" },
+      { id: "help", label: "Ayuda · Solución de Bugs" },
       { id: "sizes", label: "Medidas · sm / md / lg" },
     ],
   },