@axzydev/axzy_ui_system 1.4.2 → 1.4.4

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,123 @@ 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; 72px / 248px when flat).
+  const reservedWidth = desktopCollapsed
+    ? flat ? "w-[72px]" : "w-[88px]"
+    : flat ? "w-[248px]" : "w-[280px]";
+  // The sidebar collapses by button instead of hover: the top bar's menu
+  // button toggles the rail on desktop and still opens the drawer on mobile.
+  const toggleByButton = sidebar.expandOnHover === false;
+  const handleMenuButton = () => {
+    if (toggleByButton && window.matchMedia("(min-width: 1024px)").matches) handleToggleCollapse();
+    else setMobileSidebarOpen(v => !v);
+  };
+  // 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
+      showDesktopMenuButton={toggleByButton || topBar.showDesktopMenuButton}
+      onToggleMobileMenu={handleMenuButton}
+    />
+  );
 
+  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, ITSidebarNotification, 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,7 +176,7 @@ export {
     ITPageProps, ITPageHeaderProps,
     ITNavigationItem, ITNavigationSubItem,
     ITNavigationSubItemEntry, ITNavigationSubItemGroup,
-    ITSidebarNotification,
+    ITSidebarNotification, ITSidebarBrand,
     ITPaginationProps, ITPopoverProps, ITProgressProps,
     ITRadioGroupProps, ITRadioOption, ITSelectProps, ITSearchSelectProps,
     ITSearchTableProps,
@@ -184,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/theme/theme-context.ts

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-import type { ITThemePalette } from "./theme.types";
+import type { ITThemeAppearance, ITThemePalette } from "./theme.types";
 
 /**
  * Contexto de theming compartido por ITThemeProvider y componentes que lo
@@ -16,6 +16,8 @@ export interface ITThemeContextType {
   resolvedTheme: "light" | "dark";
   darkModeMode: "light" | "dark" | "system";
   setDarkModeMode: (mode: "light" | "dark" | "system") => void;
+  /** Visual language chosen on the provider (`"soft"` unless `appearance` says otherwise). */
+  appearance: ITThemeAppearance;
 }
 
 export const ITThemeContext = createContext<ITThemeContextType | undefined>(undefined);
@@ -34,4 +36,12 @@ export const useITTheme = () => {
  */
 export const useITThemeSafe = (): ITThemeContextType | undefined => {
   return useContext(ITThemeContext);
+};
+
+/**
+ * `true` cuando el provider pide el lenguaje visual plano (`appearance="flat"`).
+ * Fuera de un ITThemeProvider devuelve `false` (aspecto por defecto).
+ */
+export const useITFlatAppearance = (): boolean => {
+  return useContext(ITThemeContext)?.appearance === "flat";
 };

package/src/theme/theme.types.ts

@@ -12,6 +12,13 @@ export type ColorScale = {
   950?: string;
 };
 
+/**
+ * Visual language of the whole system.
+ * - `"soft"`: soft depth — floating cards, tinted shadows, glass sidebar and top bar (default).
+ * - `"flat"`: flat surfaces — hairline borders instead of shadows, plain sidebar and top bar, compact page headers.
+ */
+export type ITThemeAppearance = "soft" | "flat";
+
 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;