@zvoove/unity-ui 2.23.1 → 2.24.0

package/dist/llms.txt

@@ -3,6 +3,8 @@
 > This file describes all available components in the Unity UI design system.
 > When building UIs, use ONLY these components. Do NOT create custom components for functionality already provided here.
 
+**Styling exports from this library:** Do **not** pass `className` or `style` to Unity UI components (for example `Stack`, `Grid`, `Button`, `Card`, `Typography`). They are already styled via their public props and design tokens. Use token-based Tailwind classes only on **native HTML elements** (for example a wrapping `div` or `section`) when you need extra positioning or chrome that has no matching component prop.
+
 ## Setup
 
 Install:
@@ -53,18 +55,23 @@ Values cascade upward — setting `mobile` applies to all larger breakpoints unt
 
 ### Stack
 **Primary layout component.** Use Stack for ALL layout needs — arranging children in rows or columns with consistent spacing. Do NOT use Card or raw divs for layout.
+
+**Default `align` is `baseline`** — always set it explicitly when you need centering, stretching, or any other alignment. Never assume items are centered without `align="center"`.
+
+**Dividers need `width="100%"` on the Stack** — without it the divider may not reach the edges.
+
 ```tsx
 import { Stack } from '@zvoove/unity-ui';
 
 <Stack
   direction="column"           // ResponsiveType<'row' | 'row-reverse' | 'column' | 'column-reverse'>
   gap="md"                     // ResponsiveType<SpacingKeys> - none|xs2|xs|sm|md|lg|xl|xl2|xl3|xl4|xl5|xl6|xl7
-  align="center"               // ResponsiveType<AlignItems> - default: 'baseline'
+  align="center"               // ResponsiveType<AlignItems> - default: 'baseline' — set explicitly every time
   justify="space-between"      // ResponsiveType<JustifyContent>
   wrap="wrap"                  // ResponsiveType<FlexWrap>
   padding="md"                 // ResponsiveType<Padding>
   margin="none"                // ResponsiveType<Margin>
-  width="100%"                 // ResponsiveType<number | string>
+  width="100%"                 // ResponsiveType<number | string> — required when Stack contains a Divider
   height="auto"                // ResponsiveType<number | string>
   minWidth, maxWidth, minHeight, maxHeight  // ResponsiveType<number | string>
 >
@@ -74,18 +81,25 @@ import { Stack } from '@zvoove/unity-ui';
 
 Common patterns:
 ```tsx
+// Row with icon + label — must set align="center" or they baseline-align
+<Stack direction="row" gap="sm" align="center">
+  <Icon name="info" />
+  <Typography variant="body" size="medium">Label</Typography>
+</Stack>
+
+// Divider spanning full width — Stack must have width="100%"
+<Stack direction="column" gap="md" width="100%">
+  <Typography variant="title" size="large">Title</Typography>
+  <Divider />
+  <Typography variant="body" size="medium">Content</Typography>
+</Stack>
+
 // Page layout — stacks vertically on mobile, horizontally on tablet+
 <Stack direction={{ mobile: 'column', tablet: 'row' }} gap="lg">
   <Sidebar />
   <MainContent />
 </Stack>
 
-// Form fields in a row
-<Stack direction="row" gap="md" align="flex-end">
-  <TextField label="First name" name="first" />
-  <TextField label="Last name" name="last" />
-</Stack>
-
 // Action bar — right-aligned buttons
 <Stack direction="row" gap="sm" justify="flex-end">
   <Button variant="outlined">Cancel</Button>
@@ -790,9 +804,9 @@ import { Breadcrumbs } from '@zvoove/unity-ui';
 ```
 
 ### SideNavigation
-Collapsible sidebar navigation with user area and mid-sections.
+Collapsible sidebar navigation with user area, optional **root** mid-sections, and optional **sub-menu panels** (`parentId` + arbitrary `content`).
 ```tsx
-import { SideNavigation, type MidSection } from '@zvoove/unity-ui';
+import { MidSectionMenus, SideNavigation, type MidSection, type SubMenuLayer } from '@zvoove/unity-ui';
 
 <SideNavigation
   menuItems={[                 // ListMenuItem[] (required)
@@ -802,16 +816,14 @@ import { SideNavigation, type MidSection } from '@zvoove/unity-ui';
   utilityItems={[              // ListMenuItem[]
     { id: 'settings', label: 'Einstellungen', icon: 'settings', href: '/settings' },
   ]}
-  midSections={[               // MidSection[] — sections between menu and utility items
-    {
-      title: 'ANGEPINNT',
-      replaceWithIconOnClose: 'pin',  // collapses to icon when closed, hover shows PopUpMenu
-      items: [{ id: 'p1', label: 'Pinned item', href: '#' }],
-    },
+  midSections={[               // MidSection[] — root column only; sub-panel lists go in `subMenus[].content`
+    { title: 'ANGEPINNT', replaceWithIconOnClose: 'pin', items: [{ id: 'p1', label: 'Pinned item', href: '#' }] },
+  ]}
+  subMenus={[                   // SubMenuLayer[] — matching menu rows get chevron-right endContent; shell renders back row (Tag = parent label) + spacer; body is your ReactNode (e.g. ListMenu from an MFE)
     {
-      title: 'HEUTE',
-      hideOnMenuClosed: true,         // fully hidden when menu closed
-      items: [{ id: 't1', label: 'Today item', href: '#' }],
+      parentId: 'users',        // must match an item id in menuItems, utilityItems, or midSections
+      backLabel: 'Hauptmenü',   // optional (default: 'Hauptmenü')
+      content: <MidSectionMenus sections={...} open={open} variant={variant} />,
     },
   ]}
   userArea={{                  // UserAreaProps — user info at the bottom
@@ -826,22 +838,42 @@ import { SideNavigation, type MidSection } from '@zvoove/unity-ui';
     name: <MyWordmark />,      // shown when expanded (fades in/out)
   }}
   hideUserAreaInMobile={true}  // boolean (default: true) — hides user area on mobile
-  activeItem="home"            // string
+  activeItem="home"            // string — root id, or `parentId` / `parentId.*` to open a sub panel (segment after dot is app-defined)
   variant="default"            // 'default' | 'compact'
   open={true}                  // boolean
   onToggleOpen={handleToggle}  // (open: boolean) => void
-  onItemClick={handleClick}    // (item: ListMenuItem) => void
+  onActiveItemChange={setId}   // (activeItem: string) => void — root/utility/parentId when opening a layer; not for `__back__` or clicks inside `content`
+  onItemClick={handleClick}    // (item: ListMenuItem) => void — root, utility, sub parent, back row (`__back__`); not clicks inside `content`
   linkComponent={Link}         // React.ElementType
 />
 ```
 
+### MidSectionMenus
+Renders the same **mid-section** blocks as `SideNavigation`’s `midSections` (titles, dividers, `ListMenu`, `replaceWithIconOnClose` hover menus when collapsed on desktop). **Inner lists are always `ListMenu` `variant="compact"`** (fixed; not configurable). Prop **`variant`** only matches the parent sidebar **rail width** (`default` vs `compact` open/closed widths), not row density. Uses **`useBreakpoint()`** internally (`isSmallerThan('tablet')` for mobile). Use in `subMenus[].content` with the same **`open`** / **`variant`** as the parent shell.
+```tsx
+import { MidSectionMenus, type MidSection } from '@zvoove/unity-ui';
+
+<MidSectionMenus
+  sections={[                   // MidSection[]
+    { title: 'ANGEPINNT', replaceWithIconOnClose: 'pin', items: [/* ListMenuItem[] */] },
+  ]}
+  open={true}                   // boolean — sidebar expanded
+  variant="default"             // 'default' | 'compact' — shell width only; lists stay compact
+  activeItem="x"                // string | undefined
+  onItemClick={handleClick}     // (item: ListMenuItem) => void
+  linkComponent={Link}          // optional, default 'a'
+/>
+```
+
 ### ListMenu
 Standalone vertical menu with icon + label items. Used internally by SideNavigation, available standalone.
+
+**`items`:** either a flat `ListMenuItem[]` **or** sectioned `ListMenuSection[]` (`{ title?, items: ListMenuItem[] }[]`). Mutually exclusive — do not mix row objects and section objects in one array. Empty `[]` is treated as flat. Optional `title` per section is **uppercase** (`label` / `small` / `on-surface-variant`); omit it or use whitespace-only to hide the header (e.g. first section untitled). Titles collapse when `open` is `false`. Use `isListMenuSections(items)` for the same runtime check the component uses.
 ```tsx
-import { ListMenu, type ListMenuItem } from '@zvoove/unity-ui';
+import { ListMenu, type ListMenuItem, type ListMenuSection, isListMenuSections } from '@zvoove/unity-ui';
 
 <ListMenu
-  items={[                     // ListMenuItem[] (required) — icon is optional
+  items={[                     // ListMenuItem[] | ListMenuSection[] (required)
     { id: 'home', label: 'Startseite', icon: 'home', href: '/' },
     { id: 'chat', label: 'Chat title', href: '#',
       endContent: <Icon name="pin" size="xs" />,  // extra content on the right
@@ -849,6 +881,11 @@ import { ListMenu, type ListMenuItem } from '@zvoove/unity-ui';
     },
     { id: 'spacer', label: '', isSpacer: true },   // renders a 16px vertical spacer
   ]}
+  // Sectioned example (separate usage — not mixed with flat rows):
+  // items={[
+  //   { title: 'Gruppe', items: [{ id: 'a', label: 'A', href: '#' }] },
+  //   { items: [{ id: 'b', label: 'B', href: '#' }] },
+  // ]}
   activeItem="home"            // string
   open={true}                  // boolean — shows/hides labels with animation
   variant="default"            // 'default' | 'compact'
@@ -1537,14 +1574,17 @@ function ContactForm() {
 ## RULES FOR AI AGENTS
 
 1. **Always import from `@zvoove/unity-ui`** - never recreate components that exist in this library
-2. **Use Stack and Grid for layout** - do not use Card, div, or CSS for layout. Stack is for rows/columns, Grid is for multi-column layouts
-3. **Card is a visual container, NOT a layout tool** - Card provides background, elevation, and border. Wrap layout content in Stack/Grid INSIDE a Card. Never use Card to arrange items
-4. **Use Typography for all text** - never use raw `<p>`, `<h1>`, `<span>` etc.
-5. **Use the spacing scale** for gap/padding/margin - never use arbitrary pixel values
-6. **Use Button variants** appropriately - primary actions: `filled`, secondary: `outlined`, destructive: `negative`, success: `positive`
-7. **Use TextField/Select/Checkbox/Radio for forms** - never create custom form inputs
-8. **Use Dialog for modals, Sheet for panels** - never create custom overlays
-9. **Use Snackbar for notifications** - never create custom toast systems
-10. **Use responsive props** when the UI should adapt to screen sizes. Values cascade up from smallest breakpoint. Common pattern: `{{ mobile: 'column', tablet: 'row' }}`
-11. **Card, Dialog, Sheet padding can be "none"** - use `padding="none"` for edge-to-edge content like images, tables, or dividers inside these components
-12. **Icons use semantic names** as strings (e.g., `"search"`, `"delete"`, `"edit"`) - never import Phosphor icon components directly
+2. **NEVER pass `className` or `style` to ANY Unity UI component** — components are not customizable via className/style; use their props API exclusively. For layout or chrome not covered by a prop, wrap in a native HTML element (`div`, `section`, etc.) and apply design-token Tailwind utilities there
+3. **Use Stack and Grid for layout** - do not use Card, div, or CSS for layout. Stack is for rows/columns, Grid is for multi-column layouts
+4. **Card is a visual container, NOT a layout tool** - Card provides background, elevation, and border. Wrap layout content in Stack/Grid INSIDE a Card. Never use Card to arrange items
+5. **Use Typography for all text** - never use raw `<p>`, `<h1>`, `<span>` etc.
+6. **Use the spacing scale** for gap/padding/margin - never use arbitrary pixel values
+7. **Use Button variants** appropriately - primary actions: `filled`, secondary: `outlined`, destructive: `negative`, success: `positive`
+8. **Use TextField/Select/Checkbox/Radio for forms** - never create custom form inputs
+9. **Use Dialog for modals, Sheet for panels** - never create custom overlays
+10. **Use Snackbar for notifications** - never create custom toast systems
+11. **Use responsive props** when the UI should adapt to screen sizes. Values cascade up from smallest breakpoint. Common pattern: `{{ mobile: 'column', tablet: 'row' }}`
+12. **Card, Dialog, Sheet padding can be "none"** - use `padding="none"` for edge-to-edge content like images, tables, or dividers inside these components
+13. **Icons use semantic names** as strings (e.g., `"search"`, `"delete"`, `"edit"`) - never import Phosphor icon components directly
+14. **Stack `align` defaults to `baseline`** — always set `align` explicitly when you need centering (`align="center"`), stretching, or any other alignment. Never assume items are centered without it
+15. **Stack containing a Divider needs `width="100%"`** — without it the divider will not span the full width of the container

package/dist/theme.css

@@ -139,6 +139,7 @@
   --color-primary-70: #9aa4ff;
   --color-primary-80: #bdc2ff;
   --color-primary-90: #dfe0ff;
+  --color-primary-92: #eeeff7;
   --color-primary-95: #eff0ff;
   --color-primary-99: #fbfbff;
   --color-primary-100: #ffffff;
@@ -285,6 +286,9 @@
   --color-on-primary-container: var(--color-primary-10);
   --color-secondary-container: var(--color-secondary-90);
   --color-on-secondary-container: var(--color-secondary-10);
+  --color-container-neutral: var(--color-neutral-variant-95);
+  --color-container-neutral-hover: var(--color-neutral-variant-92);
+  --color-on-container-neutral: var(--color-neutral-variant-10);
   --color-tertiary-container: var(--color-tertiary-90);
   --color-tertiary-container-hover: var(--color-tertiary-80);
   --color-tertiary-container-active: var(--color-tertiary-70);
@@ -508,6 +512,9 @@
     --color-on-primary-container: var(--color-primary-90);
     --color-secondary-container: var(--color-secondary-30);
     --color-on-secondary-container: var(--color-secondary-90);
+    --color-container-neutral: var(--color-neutral-variant-10);
+    --color-container-neutral-hover: var(--color-neutral-variant-15);
+    --color-on-container-neutral: var(--color-neutral-variant-95);
     --color-tertiary-container: var(--color-tertiary-30);
     --color-tertiary-container-hover: var(--color-tertiary-40);
     --color-tertiary-container-active: var(--color-tertiary-50);
@@ -612,6 +619,53 @@
       display: none; /* Chrome, Safari */
     }
   }
+
+  .scrollbar-overlay {
+    /* Firefox — thin bar, transparent until hover/scroll */
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+
+    /* Chrome / Edge / Safari */
+    &::-webkit-scrollbar {
+      width: 6px;
+      height: 6px;
+      background: transparent;
+    }
+
+    &::-webkit-scrollbar-thumb {
+      background: transparent;
+      border-radius: 9999px;
+      transition: background 0.2s ease;
+    }
+
+    /* Visible on hover */
+    &:hover {
+      scrollbar-color: color-mix(
+          in srgb,
+          var(--color-on-surface) 30%,
+          transparent
+        )
+        transparent;
+    }
+
+    &:hover::-webkit-scrollbar-thumb {
+      background: color-mix(in srgb, var(--color-on-surface) 30%, transparent);
+    }
+
+    /* Visible while actively scrolling (toggled by JS scroll listener) */
+    &[data-scrolling='true'] {
+      scrollbar-color: color-mix(
+          in srgb,
+          var(--color-on-surface) 30%,
+          transparent
+        )
+        transparent;
+    }
+
+    &[data-scrolling='true']::-webkit-scrollbar-thumb {
+      background: color-mix(in srgb, var(--color-on-surface) 30%, transparent);
+    }
+  }
   .prevent-select {
     -webkit-user-select: none; /* Safari */
     -ms-user-select: none; /* IE 10 and IE 11 */