@zvoove/unity-ui 2.22.1 → 2.23.0

package/bin/templates/component.tsx

@@ -0,0 +1,15 @@
+import { __STYLES__FUNCTION__Styles } from './__COMPONENT_NAME__.styled';
+import { __COMPONENT_NAME__Props } from './__COMPONENT_NAME__.types';
+
+const __COMPONENT_NAME__ = ({
+  children,
+  variant = 'primary',
+}: __COMPONENT_NAME__Props) => {
+  return (
+    <div className={__STYLES__FUNCTION__Styles({ variant })}>{children}</div>
+  );
+};
+
+__COMPONENT_NAME__.displayName = '__COMPONENT_NAME__';
+
+export default __COMPONENT_NAME__;

package/bin/templates/doc.mdx

@@ -0,0 +1,36 @@
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+
+import { __COMPONENT_NAME__ } from '.';
+import * as __COMPONENT_NAME__Stories from './__COMPONENT_NAME__.stories';
+
+<Meta of={__COMPONENT_NAME__Stories} />
+
+# **COMPONENT_NAME**
+
+The `__COMPONENT_NAME__` component is a auto generated component using the `npm run create <componentName>` script.
+
+<Canvas sourceState="none" of={__COMPONENT_NAME__Stories.Default} />
+
+<Controls of={__COMPONENT_NAME__Stories.Default} />
+
+## Usage
+
+```jsx
+import { __COMPONENT_NAME__ } from '@zvoove/unity-ui';
+
+<__COMPONENT_NAME__ />;
+```
+
+## Variants
+
+### Default
+
+The default `__COMPONENT_NAME__` component has the following features:
+
+<Canvas sourceState="none" of={__COMPONENT_NAME__Stories.Default} />
+
+```jsx
+import { __COMPONENT_NAME__ } from '@zvoove/unity-ui';
+
+<__COMPONENT_NAME__ />;
+```

package/bin/templates/index.ts

@@ -0,0 +1,2 @@
+export { default as __COMPONENT_NAME__ } from './__COMPONENT_NAME__';
+export type { __COMPONENT_NAME__Props } from './__COMPONENT_NAME__.types';

package/bin/templates/stories.tsx

@@ -0,0 +1,15 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+
+import __COMPONENT_NAME__ from './__COMPONENT_NAME__';
+
+const meta: Meta<typeof __COMPONENT_NAME__> = {
+  title: 'Components/__COMPONENT_NAME__',
+  component: __COMPONENT_NAME__,
+};
+
+export default meta;
+type Story = StoryObj<typeof __COMPONENT_NAME__>;
+
+export const Default: Story = {
+  args: { children: 'Auto created component' },
+};

package/bin/templates/styled.ts

@@ -0,0 +1,14 @@
+import { tv } from '@libs';
+
+export const __STYLES__FUNCTION__Styles = tv({
+  base: ['text-body-medium'],
+  variants: {
+    variant: {
+      primary: ['bg-primary', 'text-on-primary'],
+      secondary: ['bg-secondary', 'text-on-secondary'],
+    },
+  },
+  defaultVariants: {
+    variant: 'primary',
+  },
+});

package/bin/templates/test.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from '@testing-library/react';
+
+import __COMPONENT_NAME__ from './__COMPONENT_NAME__';
+import { describe, expect, it } from 'vitest';
+
+describe('__COMPONENT_NAME__', () => {
+  it('renders children correctly', () => {
+    render(
+      <__COMPONENT_NAME__>
+        <div>Test Child</div>
+      </__COMPONENT_NAME__>
+    );
+
+    expect(screen.getByText('Test Child')).toBeInTheDocument();
+  });
+
+  it('applies the correct variant class', () => {
+    render(<__COMPONENT_NAME__ variant="secondary">Test</__COMPONENT_NAME__>);
+    const __COMPONENT_NAME__Element = screen.getByText('Test');
+
+    expect(__COMPONENT_NAME__Element).toHaveClass('bg-secondary'); // Assuming the class name matches the variant
+  });
+
+  it('uses the default variant when none is provided', () => {
+    render(<__COMPONENT_NAME__>Default Variant</__COMPONENT_NAME__>);
+    const __COMPONENT_NAME__Element = screen.getByText('Default Variant');
+
+    expect(__COMPONENT_NAME__Element).toHaveClass('bg-primary'); // Assuming 'primary' is the default class
+  });
+});

package/bin/templates/types.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+
+export interface __COMPONENT_NAME__Props {
+  /**
+   * The children of the __COMPONENT_NAME__.
+   */
+  children: ReactNode;
+
+  /**
+   * The variant of the __COMPONENT_NAME__
+   */
+  variant?: 'primary' | 'secondary';
+}

package/dist/llms.txt

@@ -21,10 +21,7 @@ Import components:
 import { Button, Card, TextField, Typography } from '@zvoove/unity-ui';
 ```
 
-Font (add to HTML head):
-```html
-<link href="https://fonts.googleapis.com/css2?family=Source+Sans+3:ital,wght@0,200..900;1,200..900&display=swap" rel="stylesheet" />
-```
+Font: Source Sans 3 is bundled via `@font-face` in `theme.css` — no extra setup needed.
 
 Dark mode: add `data-theme="dark"` to a parent element.
 
@@ -196,7 +193,10 @@ Horizontal separator line.
 ```tsx
 import { Divider } from '@zvoove/unity-ui';
 
-<Divider variant="fullWidth" />  // 'fullWidth' | 'inset' | 'middle'
+<Divider
+  variant="fullWidth"     // 'fullWidth' | 'inset' | 'middle'
+  color="outline-variant" // BackgroundColors — any design token name (default: 'outline-variant')
+/>
 ```
 
 ### Expandable
@@ -548,15 +548,25 @@ import { SegmentGroup, SegmentButton } from '@zvoove/unity-ui';
 ### PopUpMenu
 Context menu / dropdown menu.
 ```tsx
-import { PopUpMenu } from '@zvoove/unity-ui';
+import { PopUpMenu, type PopUpMenuItem } from '@zvoove/unity-ui';
+
+const items: PopUpMenuItem[] = [
+  { id: '1', label: 'Edit', icon: 'edit' },
+  { id: '2', label: 'Delete', icon: 'delete' },
+  { id: 'divider', label: '', isDivider: true, dividerProps: { variant: 'middle' } },
+  // Custom non-interactive content (e.g. user header)
+  { id: 'header', label: '', customContent: <MyCustomHeader /> },
+  // Item that stays open on click (e.g. theme toggle)
+  { id: 'theme', label: 'Dark Mode', icon: 'dark-mode', keepOpen: true, onClick: toggleTheme },
+  // Sub-menu items (opens nested menu on hover)
+  { id: 'language', label: 'Sprache', icon: 'translate', subMenuItems: [
+    { id: 'de', label: 'Deutsch' },
+    { id: 'en', label: 'English' },
+  ]},
+];
 
 <PopUpMenu
-  items={[                     // PopUpMenuItem[] (required)
-    { id: '1', label: 'Edit', icon: 'Pencil' },
-    { id: '2', label: 'Delete', icon: 'Trash', variant: 'error' },
-    { id: 'divider', isDivider: true },
-    { id: '3', label: 'Settings' },
-  ]}
+  items={items}                // PopUpMenuItem[] (required)
   trigger="click"              // 'hover' | 'click' | 'right-click' (default: 'click')
   placement="bottom-left"      // PopUpMenuPlacement (default: 'bottom-left')
   selectable="none"            // 'single' | 'multiple' | 'none' (default: 'none')
@@ -564,13 +574,20 @@ import { PopUpMenu } from '@zvoove/unity-ui';
   onItemClick={handleClick}    // (item, selectedItem?) => void
   density="default"            // 'default' | '-2' | '-4'
   showSearch={false}           // boolean
-  searchPlaceholder="Search"   // string
+  searchPlaceholder="Suchen"   // string
   disabled={false}             // boolean
+  height, minHeight, maxHeight // ResponsiveType<number | string> — control popup size
 >
-  <Button>Actions</Button>
+  <Button>Aktionen</Button>
 </PopUpMenu>
 ```
 
+PopUpMenuItem special props:
+- `customContent?: ReactNode` — non-interactive custom content (no hover effect)
+- `keepOpen?: boolean` — don't close menu on click
+- `subMenuItems?: PopUpMenuItem[]` — nested sub-menu on hover
+- `dividerProps?: DividerProps` — pass props to Divider when `isDivider: true`
+
 ---
 
 ## DATA DISPLAY COMPONENTS
@@ -641,19 +658,22 @@ import { Chip } from '@zvoove/unity-ui';
 ```
 
 ### Avatar & AvatarGroup
-User avatar display.
+User avatar display. When `image` is provided and `type` is omitted, type is automatically inferred as `'image'`.
 ```tsx
 import { Avatar, AvatarGroup } from '@zvoove/unity-ui';
 
 <Avatar
   size="large"                 // ResponsiveType<'small' | 'medium' | 'large'>
-  type="initials"              // 'initials' | 'check' | 'avatar' | 'image'
-  name="John Doe"              // string
-  image="/path/to/photo.jpg"   // string (for type='image')
+  type="initials"              // 'initials' | 'check' | 'avatar' | 'image' | 'zvoove' — auto-inferred as 'image' when image prop is set
+  name="Max Mustermann"        // string
+  image="/path/to/photo.jpg"   // string — when set, type defaults to 'image'
   initialsAmount={2}           // 1 | 2
   variant="round"              // 'round' | 'square'
 />
 
+// Image avatar — type is inferred, no need to set type="image"
+<Avatar image="https://example.com/avatar.jpg" name="Max Mustermann" />
+
 <AvatarGroup maxLength={3} total={10}>
   <Avatar name="Alice" type="initials" />
   <Avatar name="Bob" type="initials" />
@@ -754,7 +774,7 @@ import { Tabs } from '@zvoove/unity-ui';
 ```
 
 ### Breadcrumbs
-Navigation breadcrumb trail.
+Navigation breadcrumb trail. First item renders as an icon (customizable via `homeIcon`).
 ```tsx
 import { Breadcrumbs } from '@zvoove/unity-ui';
 
@@ -764,28 +784,76 @@ import { Breadcrumbs } from '@zvoove/unity-ui';
     { label: 'Products', href: '/products' },
     { label: 'Details' },
   ]}
+  homeIcon="home"              // CommonIconNames (default: 'home') — icon for the first breadcrumb
   linkComponent={Link}         // React.ElementType
 />
 ```
 
 ### SideNavigation
-Collapsible sidebar navigation.
+Collapsible sidebar navigation with user area and mid-sections.
 ```tsx
-import { SideNavigation } from '@zvoove/unity-ui';
+import { SideNavigation, type MidSection } from '@zvoove/unity-ui';
 
 <SideNavigation
-  menuItems={[                 // MenuItem[] (required)
-    { id: 'home', label: 'Home', icon: 'House' },
-    { id: 'users', label: 'Users', icon: 'Users' },
+  menuItems={[                 // ListMenuItem[] (required)
+    { id: 'home', label: 'Startseite', icon: 'home', href: '/' },
+    { id: 'users', label: 'Personal', icon: 'users', href: '/users' },
+  ]}
+  utilityItems={[              // ListMenuItem[]
+    { id: 'settings', label: 'Einstellungen', icon: 'settings', href: '/settings' },
   ]}
-  utilityItems={[              // MenuItem[]
-    { id: 'settings', label: 'Settings', icon: 'Gear' },
+  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: '#' }],
+    },
+    {
+      title: 'HEUTE',
+      hideOnMenuClosed: true,         // fully hidden when menu closed
+      items: [{ id: 't1', label: 'Today item', href: '#' }],
+    },
   ]}
+  userArea={{                  // UserAreaProps — user info at the bottom
+    name: 'Max Mustermann',
+    subtitle: 'Company Name',
+    avatar: { image: '/avatar.jpg' },
+    menuItems: [/* PopUpMenuItem[] */],
+    menuMaxHeight: '80dvh',    // ResponsiveType<number | string> (default: '80dvh')
+  }}
+  logo={{                      // { icon?: ReactNode; name?: ReactNode } — compact only, defaults to zvoove brand
+    icon: <MyIcon />,          // shown when collapsed
+    name: <MyWordmark />,      // shown when expanded (fades in/out)
+  }}
+  hideUserAreaInMobile={true}  // boolean (default: true) — hides user area on mobile
   activeItem="home"            // string
+  variant="default"            // 'default' | 'compact'
   open={true}                  // boolean
   onToggleOpen={handleToggle}  // (open: boolean) => void
-  onItemClick={handleClick}    // (item: MenuItem) => void
+  onItemClick={handleClick}    // (item: ListMenuItem) => void
+  linkComponent={Link}         // React.ElementType
+/>
+```
+
+### ListMenu
+Standalone vertical menu with icon + label items. Used internally by SideNavigation, available standalone.
+```tsx
+import { ListMenu, type ListMenuItem } from '@zvoove/unity-ui';
+
+<ListMenu
+  items={[                     // ListMenuItem[] (required) — icon is optional
+    { id: 'home', label: 'Startseite', icon: 'home', href: '/' },
+    { id: 'chat', label: 'Chat title', href: '#',
+      endContent: <Icon name="pin" size="xs" />,  // extra content on the right
+      endContentVisibility: 'hover',               // 'always' (default) | 'hover'
+    },
+    { id: 'spacer', label: '', isSpacer: true },   // renders a 16px vertical spacer
+  ]}
+  activeItem="home"            // string
+  open={true}                  // boolean — shows/hides labels with animation
+  variant="default"            // 'default' | 'compact'
   linkComponent={Link}         // React.ElementType
+  onItemClick={handleClick}    // (item: ListMenuItem) => void
 />
 ```
 
@@ -1133,8 +1201,10 @@ Dark mode shadows: `dark:shadow-elevation1-dark` (replace `elevation1` with the
 
 Use `tailwind-variants` when a custom UI element has multiple visual variants.
 
-Configure `tv` with Unity UI spacing tokens so class merging works correctly:
+Configure `tv` once in a shared config file (e.g. `lib/tv.ts`) and import it everywhere — do **not** repeat `createTV` in each styled file:
+
 ```ts
+// lib/tv.ts (create once, import everywhere)
 import { createTV } from 'tailwind-variants';
 
 export const tv = createTV({
@@ -1147,7 +1217,12 @@ export const tv = createTV({
 });
 ```
 
-Usage:
+Then in styled files:
+```ts
+import { tv } from '@/lib/tv';  // import from shared config, NOT from 'tailwind-variants'
+```
+
+Basic usage (single element):
 ```ts
 const badge = tv({
   base: ['inline-flex', 'items-center', 'rounded-full', 'px-sm', 'py-xs2', 'text-label-small'],
@@ -1165,6 +1240,39 @@ const badge = tv({
 <div className={badge({ tone: 'primary' })}>Label</div>
 ```
 
+Slots (multi-element components — use when a component has distinct styled sub-parts):
+```ts
+const card = tv({
+  slots: {
+    base: ['rounded-md', 'bg-surface', 'shadow-elevation1'],
+    header: ['px-md', 'py-sm', 'border-b', 'border-outline-variant'],
+    body: ['p-md'],
+    footer: ['px-md', 'py-sm', 'flex', 'justify-end', 'gap-sm'],
+  },
+  variants: {
+    variant: {
+      outlined: { base: ['border', 'border-outline-variant', 'shadow-none'] },
+      elevated: { base: ['shadow-elevation2'] },
+    },
+    compact: {
+      true: { body: ['p-sm'], header: ['px-sm', 'py-xs'] },
+    },
+  },
+  defaultVariants: { variant: 'outlined' },
+});
+
+// Apply — destructure slots from the result:
+const { base, header, body, footer } = card({ variant: 'elevated', compact: true });
+
+<div className={base()}>
+  <div className={header()}>Title</div>
+  <div className={body()}>Content</div>
+  <div className={footer()}>
+    <Button>Save</Button>
+  </div>
+</div>
+```
+
 ### Class Merging
 
 Use `tailwind-merge` for ad-hoc merging (e.g. accepting a `className` prop):
@@ -1227,17 +1335,7 @@ Rules:
 ### `MyComponent.styled.ts`
 
 ```ts
-import { createTV } from 'tailwind-variants';
-
-// Configure tv with Unity UI spacing/radius tokens for correct class merging
-const tv = createTV({
-  twMergeConfig: {
-    theme: {
-      spacing: ['none', 'xs2', 'xs', 'sm', 'md', 'lg', 'xl', 'xl2', 'xl3', 'xl4', 'xl5', 'xl6', 'xl7'],
-      borderRadius: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'full'],
-    },
-  },
-});
+import { tv } from '@/lib/tv'; // shared tv config — do NOT use createTV here
 
 export const myComponentStyles = tv({
   base: ['text-body-medium', 'rounded-sm'],
@@ -1253,8 +1351,6 @@ export const myComponentStyles = tv({
 });
 ```
 
-Tip: define the configured `tv` once in a shared `lib/tv.ts` file in your project and import from there instead of re-configuring in every component.
-
 ### `MyComponent.tsx` — Simple
 
 ```tsx
@@ -1358,7 +1454,18 @@ Unity UI uses its own semantic icon names (not raw Phosphor icon names). Pass th
 
 ### Common Icons
 
-add, add-circle, add-file, agent, airplane, archive, arrow-back, arrow-bend, arrow-down, arrow-forward, arrow-left-right, arrow-up, article, attachment, automate, backspace, bank, bicycle, billing, binoculars, break, bus, calendar, calendar-blank, calendar-check, calendar-dot, calendar-x, camera, car, cart, cash-money, certificate, chat-bubble, chats, check, check-circle, checkbox, checkbox-empty, checkbox-indefinitely, checks, chevron-down, chevron-left, chevron-right, chevron-up, circle-notch, close, close-circle, clock-countdown, clock-person, cloud-download, cloud-upload, columns, copy, dark-mode, deactivate, delete, diagram-view, download, drag, edit, error, exclamation-mark, expand, expenses, face-id, file, filter, filters, first-page, folder, grid-view, hard-hat, help, hide, home, images, info, invoice, job, keyboard, knowledge, language, last-page, light-mode, list-view, location, location-pin, lock, menu, metadata, microphone, minus, more-horizontal, more-vertical, moped, navigation-arrow, note, notches, notifications, numpad, open-in-new-tab, order, organization, pause, phone, piggy-bank, plant, printer, privacy, qr-code, refresh, remark, save, search, send-message, settings, setup-time, shapes, show, sick, sidebar, sign-out, signature, skip-forward, smartphone, sparkle, star, start, stop, table, taxi, text-align-center, text-align-justify, text-align-left, text-align-right, text-t, time, time-sheet-download, time-sheet-upload, timer, train, translate, travel, unfold, upload, user, user-account, users, vacation, wallet, warning, wrench.
+add, add-circle, add-file, agent, airplane, archive, arrow-back, arrow-bend, arrow-down, arrow-forward, arrow-left-right, arrow-up, article, attachment, automate, backspace, bank, bicycle, billing, binoculars, break, bus, calendar, calendar-blank, calendar-check, calendar-dot, calendar-x, camera, car, cart, cash-money, certificate, chat-bubble, chat-dots, chat-slash, chats, check, check-circle, checkbox, checkbox-empty, checkbox-indefinitely, checks, chevron-down, chevron-left, chevron-right, chevron-up, circle-notch, close, close-circle, clock-countdown, clock-person, cloud-download, cloud-upload, columns, command, control, copy, currency-dollar, currency-dollar-circle, currency-gbp, dark-mode, deactivate, delete, diagram-view, download, drag, edit, error, exclamation-mark, expand, expenses, face-id, file, filter, filters, first-page, flag-de, flag-es, flag-fr, flag-gb, flag-nl, folder, folder-open, grid-view, hard-hat, head-circuit, help, hide, home, images, info, invoice, job, key-return, keyboard, knowledge, language, last-page, light-mode, list-view, location, location-pin, lock, lock-key, lock-key-open, menu, metadata, microphone, minus, more-horizontal, more-vertical, moped, navigation-arrow, note, notches, notifications, numpad, open-in-new-tab, option, order, organization, pause, phone, piggy-bank, pin, pin-simple, pin-simple-slash, pin-slash, plant, printer, privacy, qr-code, refresh, remark, robot, save, search, send-message, settings, setup-time, shapes, show, sick, sidebar, sign-out, signature, skip-forward, smartphone, sparkle, star, start, stop, table, taxi, text-align-center, text-align-justify, text-align-left, text-align-right, text-t, time, time-sheet-download, time-sheet-upload, timer, train, translate, travel, unfold, upload, user, user-account, users, vacation, wallet, warning, wrench.
+
+### Flag Icons
+
+Country flag SVGs — work in all components (ListMenu, PopUpMenu, Button, Chip, Select):
+
+flag-de (Germany), flag-es (Spain), flag-fr (France), flag-gb (United Kingdom), flag-nl (Netherlands).
+
+```tsx
+<Icon name="flag-de" size="sm" />
+<PopUpMenu items={[{ id: 'de', label: 'Deutsch', icon: 'flag-de' }]} />
+```
 
 ### File Type Icons
 

package/dist/theme.css

@@ -1,5 +1,41 @@
 @import 'tailwindcss';
 
+@font-face {
+  font-family: 'Source Sans 3';
+  font-style: normal;
+  font-weight: 300;
+  src: url('https://d1ciav5yxfbyc5.cloudfront.net/fonts/source-sans-3-variable.woff2')
+    format('woff2');
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Source Sans 3';
+  font-style: normal;
+  font-weight: 400;
+  src: url('https://d1ciav5yxfbyc5.cloudfront.net/fonts/source-sans-3-variable.woff2')
+    format('woff2');
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Source Sans 3';
+  font-style: normal;
+  font-weight: 500;
+  src: url('https://d1ciav5yxfbyc5.cloudfront.net/fonts/source-sans-3-variable.woff2')
+    format('woff2');
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Source Sans 3';
+  font-style: normal;
+  font-weight: 700;
+  src: url('https://d1ciav5yxfbyc5.cloudfront.net/fonts/source-sans-3-variable.woff2')
+    format('woff2');
+  font-display: swap;
+}
+
 @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
 @custom-variant child (& > *);
 @theme {
@@ -276,8 +312,10 @@
   --color-surface-container-highest: var(--color-neutral-variant-90);
   --color-on-surface: var(--color-neutral-variant-10);
   --color-on-surface-variant: var(--color-neutral-variant-40);
+  --color-on-surface-variant-lowest: var(--color-neutral-variant-70);
   --color-outline: var(--color-neutral-variant-70);
   --color-outline-variant: var(--color-neutral-variant-90);
+  --color-outline-low: var(--color-neutral-variant-95);
   --color-outline-variant-low: var(--color-neutral-variant-50);
   --color-error: var(--color-error-40);
   --color-error-hover: var(--color-error-50);
@@ -497,8 +535,10 @@
     --color-surface-container-highest: var(--color-neutral-35);
     --color-on-surface: var(--color-neutral-90);
     --color-on-surface-variant: var(--color-neutral-70);
+    --color-on-surface-variant-lowest: var(--color-neutral-50);
     --color-outline: var(--color-neutral-50);
     --color-outline-variant: var(--color-neutral-30);
+    --color-outline-low: var(--color-neutral-30);
     --color-outline-variant-low: var(--color-neutral-variant-60);
     --color-error: var(--color-error-80);
     --color-error-hover: var(--color-error-70);
@@ -627,6 +667,10 @@
     animation: circular-indeterminate 1.2s ease-in-out infinite;
   }
 
+  .animate-circular-indeterminate-slow {
+    animation: circular-indeterminate 1.8s ease-in-out infinite;
+  }
+
   .remove-margin-block-start {
     margin-block-start: 0 !important;
   }