@nice2dev/ui 1.0.12 → 1.0.15

package/dist/index.d.ts

@@ -2734,6 +2734,9 @@ export { createCustomDataSource }
  */
 export declare function createDocIndex(docs: ComponentDoc[], packageName: string): DocIndex;
 
+/** Build an empty recipe scaffold (used by NiceRecipeEditor "new" mode). */
+export declare function createEmptyRecipe(partial?: Partial<NiceRecipeModel>): NiceRecipeModel;
+
 export { createGraphQLDataSource }
 
 export { createGraphQLSubscriptionSource }
@@ -6700,6 +6703,9 @@ export declare type NetworkNodeCategory = 'router' | 'switch' | 'access-point' |
 
 export declare type NetworkNodeStatus = 'online' | 'offline' | 'warning';
 
+/** Tiny non-cryptographic id generator suitable for UI-only records. */
+export declare function newRecipeId(prefix?: string): string;
+
 export { NICE_BREAKPOINTS }
 
 export { NICE_BUILTIN_ICONS }
@@ -6723,6 +6729,23 @@ export { NICE_THEME_PACK_LIST_EXTENDED }
 
 export { NICE_THEME_PACKS }
 
+/**
+ * Pre-built picker options for every preset in {@link NICE_THEME_PRESETS}.
+ * Use as the default `themes` prop on `<NiceThemePicker>`.
+ *
+ * @example
+ * ```tsx
+ * import { NiceThemePicker, NICE_THEME_PICKER_PRESETS } from '@nice2dev/ui';
+ *
+ * <NiceThemePicker
+ *   themes={NICE_THEME_PICKER_PRESETS}
+ *   value={themeId}
+ *   onChange={(opt) => setThemeId(opt?.id ?? null)}
+ * />
+ * ```
+ */
+export declare const NICE_THEME_PICKER_PRESETS: NiceThemeDescriptor[];
+
 export { NICE_THEME_PRESETS }
 
 export { NiceA11yConfig }
@@ -7267,6 +7290,42 @@ export declare interface NiceAuditLogProps {
     'data-testid'?: string;
 }
 
+export declare const NiceAuthButtons: default_2.ForwardRefExoticComponent<NiceAuthButtonsProps & default_2.RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceAuthButtonsProps {
+    /**
+     * Authenticated user — when set, renders the user-menu instead of
+     * login/register buttons.
+     */
+    user?: NiceAuthUser;
+    /** Items shown in the user-menu dropdown (only when `user` is set). */
+    userMenuItems?: UserMenuItem[];
+    /** Convenience handler appended as a "Profile" item if no items are given. */
+    onProfile?: () => void;
+    /** Convenience handler appended as a "Logout" item if no items are given. */
+    onLogout?: () => void;
+    /** Show the "Sign in" button when no `user`. Default: `true`. */
+    showLogin?: boolean;
+    /** Login button label. */
+    loginLabel?: string;
+    /** Login click handler. */
+    onLoginClick?: () => void;
+    /** Show the "Register" button when no `user`. Default: auto-true if `onRegisterClick` provided. */
+    showRegister?: boolean;
+    /** Register button label. */
+    registerLabel?: string;
+    /** Register click handler. */
+    onRegisterClick?: () => void;
+    /** Button size. */
+    size?: NiceSize;
+    /** Compact mode — hides login button text on narrow viewports (CSS-driven). */
+    compact?: boolean;
+    className?: string;
+    style?: default_2.CSSProperties;
+    id?: string;
+    'data-testid'?: string;
+}
+
 /**
  * {@link NiceAuthGuard} — Protected route/section wrapper.
  * Checks authentication and permission/role requirements before rendering children.
@@ -7297,6 +7356,21 @@ export declare interface NiceAuthGuardProps {
     children: default_2.ReactNode;
 }
 
+export declare interface NiceAuthUser {
+    /** Display name. */
+    name: string;
+    /** Avatar image URL. */
+    avatarUrl?: string;
+    /** Initials fallback (auto-derived from `name` when omitted). */
+    initials?: string;
+    /** Optional email address shown in the user-menu header. */
+    email?: string;
+    /** Optional role/title shown in the user-menu header. */
+    role?: string;
+    /** Online status indicator. */
+    status?: 'online' | 'away' | 'busy' | 'offline';
+}
+
 export declare const NiceAutocomplete: default_2.FC<NiceAutocompleteProps>;
 
 /** Props for the {@link NiceAutocomplete} component — a text input with filtered suggestion dropdown and optional multi-select. */
@@ -11221,6 +11295,8 @@ export declare interface NiceFileManagerProps extends NiceBaseProps {
     viewMode?: 'list' | 'detail' | 'thumbnails';
     selectable?: boolean;
     showBreadcrumb?: boolean;
+    /** Show top toolbar with single/dual-pane switch + view mode toggles + search */
+    showTopToolbar?: boolean;
     /** Show function-key toolbar at bottom (dual-pane style) */
     showFnToolbar?: boolean;
     /** Show status bar with selection summary */
@@ -11257,6 +11333,10 @@ export declare interface NiceFileManagerProps extends NiceBaseProps {
     onRefresh?: (panel?: NiceFilePanel) => void;
     /** Sort change */
     onSortChange?: (sort: NiceFileSort, panel?: NiceFilePanel) => void;
+    /** Top toolbar — toggle dual-pane mode (called when user clicks Single/Dual buttons) */
+    onDualPaneChange?: (dual: boolean) => void;
+    /** Top toolbar — change view mode */
+    onViewModeChange?: (mode: 'list' | 'detail' | 'thumbnails') => void;
 }
 
 /** Active panel identifier for dual-pane {@link NiceFileManager}. */
@@ -12498,6 +12578,31 @@ export { NiceInfiniteScrollConfig }
 
 export { NiceInfiniteScrollState }
 
+/**
+ * Shared meal/recipe/ingredient models.
+ *
+ * Used by:
+ *  - NiceRecipe (planning) — display
+ *  - NiceRecipeEditor (tools) — editing
+ *  - NiceScheduler (planning) — when an event has `eventType: 'recipe'`
+ */
+/** A single measurable component of a recipe (e.g. "200 g flour"). */
+export declare interface NiceIngredient {
+    id: string;
+    /** Display name, e.g. "All-purpose flour". */
+    name: string;
+    /** Numeric amount (parsed). Use `unit` for the measurement. */
+    quantity?: number;
+    /** Free-form unit string: "g", "ml", "tbsp", "cup", "pcs". */
+    unit?: string;
+    /** Free-form notes shown next to the ingredient ("sifted", "room temp"). */
+    notes?: string;
+    /** Optional grouping ("Dough", "Filling", "Topping"). */
+    group?: string;
+    /** Marks the ingredient as completed in interactive shopping/cook mode. */
+    checked?: boolean;
+}
+
 export { NiceInlineHelp }
 
 export { NiceInlineHelpProps }
@@ -12694,6 +12799,8 @@ export declare interface NiceKanbanBoardProps extends NiceBaseProps, TracelessSt
     size?: NiceSize;
     /** Allow columns to be collapsed */
     collapsible?: boolean;
+    /** Layout mode — `scroll` (default, horizontal scroll when overflowing) or `responsive` (columns wrap to fit container width). */
+    layoutMode?: NiceKanbanLayoutMode;
     /** View mode (default, compact, detailed) */
     viewMode?: NiceKanbanViewMode;
     /** Callback when view mode changes */
@@ -12748,6 +12855,11 @@ export declare interface NiceKanbanColumn {
     limit?: number;
 }
 
+/** Layout mode for the kanban board container.
+ * - `scroll`: Columns keep their min/max width and the board scrolls horizontally when they don't fit (default).
+ * - `responsive`: Columns wrap onto multiple rows and flex-grow to fill the available width — no horizontal overflow. */
+declare type NiceKanbanLayoutMode = 'scroll' | 'responsive';
+
 /** Persisted state for NiceKanbanBoard */
 export declare interface NiceKanbanPersistedState {
     /** Collapsed column keys */
@@ -12816,8 +12928,19 @@ export declare interface NiceLanguagePickerProps extends NiceFormFieldProps, Dua
     placeholder?: string;
     /** Enable search */
     showSearch?: boolean;
-    /** Search placeholder */
+    /**
+     * Threshold below which the internal search/filter input is hidden even
+     * when `showSearch` is `true`. Prevents a noisy filter UI for short lists
+     * (e.g. 5 languages). Default: `8`. Set `0` to always show, `Infinity` to
+     * always hide.
+     */
+    searchThreshold?: number;
+    /** Search placeholder. Default: translated `'Filter languages…'`. */
     searchPlaceholder?: string;
+    /** Controlled open state (for coordinating with sibling controls). */
+    isOpen?: boolean;
+    /** Notified whenever the dropdown open state changes. */
+    onOpenChange?: (open: boolean) => void;
     /** Show BCP-47 code in trigger. Default: false (compact) */
     showCodeInValue?: boolean;
     /** Show BCP-47 code in dropdown options. Default: true */
@@ -13351,6 +13474,57 @@ export declare interface NiceLoginFormProps extends NiceBaseProps {
     passwordPlaceholder?: string;
 }
 
+export declare const NiceLogo: default_2.ForwardRefExoticComponent<NiceLogoProps & default_2.RefAttributes<HTMLElement>>;
+
+export declare interface NiceLogoProps {
+    /** Image URL to render as `<img>`. Has priority over `icon` and `variant`. */
+    src?: string;
+    /** Custom icon node (SVG / NiceIcon / emoji). Has priority over `variant`. */
+    icon?: default_2.ReactNode;
+    /**
+     * Pre-built brand mark variant from the OmniVerk family.
+     * Used when neither `src` nor `icon` is provided.
+     * Default: `'mark'`.
+     */
+    variant?: NiceLogoVariant;
+    /** Brand name rendered next to the icon. Hidden if `iconOnly` is true. */
+    text?: string;
+    /** Render only the icon (no text). */
+    iconOnly?: boolean;
+    /** Render only the text (no icon). */
+    textOnly?: boolean;
+    /**
+     * Logo height in pixels — width is derived to preserve aspect ratio.
+     * Accepts presets (`xs`/`sm`/`md`/`lg`/`xl`) or a raw number.
+     * Default: `'md'` (32 px).
+     */
+    size?: NiceLogoSize;
+    /**
+     * Render as `<a href>` link.
+     * If neither `href` nor `onClick` is set, the logo is a static `<span>`.
+     */
+    href?: string;
+    /** Click handler — renders as `<button>`. */
+    onClick?: () => void;
+    /** Accessible label (default: `text` or "Brand"). */
+    ariaLabel?: string;
+    className?: string;
+    style?: default_2.CSSProperties;
+    id?: string;
+    'data-testid'?: string;
+}
+
+export declare type NiceLogoSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
+
+/**
+ * Brand mark variant.
+ * - `mark` (default): symbol only — diamond + triangle (NtdOmniVerk).
+ * - `badge`: rounded-square enclosed mark (NtdOmniVerkBadge), good for favicons / chips.
+ * - `spinner`: animated rotating mark (NtdOmniVerkSpinner) — use for loading states.
+ * - `logo`: full mark + wordmark side-by-side (NtdOmniVerkLogo).
+ */
+export declare type NiceLogoVariant = 'mark' | 'badge' | 'spinner' | 'logo';
+
 export declare const NiceLookup: default_2.FC<NiceLookupProps>;
 
 /** Column definition for the mini-grid lookup mode. */
@@ -13657,50 +13831,50 @@ export declare interface NiceMdiWorkspaceProps extends NiceBaseProps {
     unsavedWarningMessage?: string;
 }
 
-export declare const NiceMegaMenu: default_2.ForwardRefExoticComponent<NiceMegaMenuProps & default_2.RefAttributes<HTMLDivElement>>;
-
-/** A column within a {@link NiceMegaMenuPanel}. */
-export declare interface NiceMegaMenuColumn {
-    /** Optional column header text. */
-    header?: string;
-    /** Menu items in this column. */
-    items: NiceMegaMenuItem[];
-}
-
-/** A clickable item inside a {@link NiceMegaMenuColumn}. */
-export declare interface NiceMegaMenuItem {
-    /** Unique key. */
-    key: string;
-    /** Display label. */
-    label: string;
-    /** Optional icon. */
-    icon?: default_2.ReactNode;
-    /** If set, renders the item as a link. */
-    href?: string;
-    /** Click handler. */
-    onClick?: () => void;
-    /** Disable the item. */
-    disabled?: boolean;
+/** A planned meal — references one or more recipes. */
+export declare interface NiceMeal {
+    id: string;
+    /** Display name, e.g. "Sunday Brunch". */
+    name: string;
+    /** Date/time the meal is served. */
+    servedAt?: Date;
+    kind?: NiceMealKind;
+    /** Recipes that compose this meal. */
+    recipeIds: string[];
+    /** Optional override of total servings for this meal. */
+    servings?: number;
+    notes?: string;
 }
 
-/** A top-level panel (mega dropdown) in the {@link NiceMegaMenu}. */
-export declare interface NiceMegaMenuPanel {
-    /** Unique key. */
-    key: string;
-    /** Panel trigger label. */
-    label: string;
-    /** Multi-column layout. */
-    columns: NiceMegaMenuColumn[];
-    /** Fully custom panel renderer (overrides columns). */
-    renderPanel?: () => default_2.ReactNode;
-}
+/** Meal kind used by meal planners. */
+export declare type NiceMealKind = 'breakfast' | 'lunch' | 'dinner' | 'snack' | 'other';
 
-/** Props for the {@link NiceMegaMenu} component — a desktop mega-dropdown navigation bar. */
-export declare interface NiceMegaMenuProps extends NiceBaseProps {
-    /** Panel definitions. */
-    items: NiceMegaMenuPanel[];
-    /** Size preset. */
-    size?: NiceSize;
+/**
+ * Weekly meal planner — rows are meal kinds (breakfast/lunch/dinner by
+ * default), columns are the seven days starting at {@link weekStart}.
+ * Each cell shows the meals served at that day+kind; users can add a
+ * recipe from the pool via the cell's `+` picker, or remove individual
+ * meal cards. Pure-client state (raises {@link onChange} with the new
+ * meals array).
+ *
+ * Pairs naturally with `NiceScheduler` — meal `servedAt` dates can be
+ * surfaced as scheduler events upstream.
+ */
+export declare const NiceMealPlan: default_2.FC<NiceMealPlanProps>;
+
+export declare interface NiceMealPlanProps extends NiceBaseProps {
+    /** Pool of recipes the user can pick from. */
+    recipes: NiceRecipeModel[];
+    /** Planned meals. */
+    meals: NiceMeal[];
+    /** Called whenever the meal list changes. */
+    onChange?: (meals: NiceMeal[]) => void;
+    /** First day of the week to render (defaults to today's Monday). */
+    weekStart?: Date;
+    /** Which meal-kind rows to show (default: breakfast/lunch/dinner). */
+    rows?: NiceMealKind[];
+    /** Read-only mode (no add/remove/move). */
+    readOnly?: boolean;
 }
 
 export declare const NiceMention: default_2.ForwardRefExoticComponent<NiceMentionProps & default_2.RefAttributes<HTMLTextAreaElement>>;
@@ -13731,34 +13905,146 @@ export declare interface NiceMentionSuggestion {
 
 export declare const NiceMenu: default_2.FC<NiceMenuProps>;
 
-/** A single item (or sub-menu) in the {@link NiceMenu}. */
+export declare type NiceMenuAlign = 'start' | 'center' | 'end';
+
+export declare type NiceMenuDensity = 'compact' | 'normal' | 'comfortable';
+
+/**
+ * A single entry in {@link NiceMenu}. Both legacy (`key` + `text` + `items`)
+ * and new (`id` + `label` + `children`) shapes are accepted; new fields
+ * take precedence when both are supplied.
+ */
 export declare interface NiceMenuItem {
-    /** Unique key. */
-    key: string;
-    /** Display text. */
-    text: string;
-    /** Icon element. */
+    /** New canonical identifier. */
+    id?: string;
+    /** Legacy alias for `id`. */
+    key?: string;
+    /** New canonical label (string or arbitrary node). */
+    label?: default_2.ReactNode;
+    /** Legacy alias for `label`. */
+    text?: string;
+    /** Optional small description shown under the label inside dropdown panels. */
+    description?: default_2.ReactNode;
+    /** Leading icon. */
     icon?: default_2.ReactNode;
-    /** Disable this item. */
+    /** Optional badge (string / number) shown to the right of the label. */
+    badge?: default_2.ReactNode;
+    /** When set, renders the entry as an `<a>`. */
+    href?: string;
+    /** Anchor target. */
+    target?: string;
+    /** Anchor rel. */
+    rel?: string;
+    /** Click handler. */
+    onClick?: (event: default_2.MouseEvent) => void;
+    /** Disable the entry. */
     disabled?: boolean;
-    /** Nested sub-menu items. */
+    /** Render the entry as a danger / destructive action. */
+    danger?: boolean;
+    /** When `true`, render a horizontal divider instead of an entry (panel-only). */
+    divider?: boolean;
+    /** New canonical children list (only the first level of nesting opens a flyout). */
+    children?: NiceMenuItem[];
+    /** Legacy alias for `children`. */
     items?: NiceMenuItem[];
-    /** Click handler. */
-    onClick?: () => void;
+    /** Tooltip / `aria-label` override. */
+    ariaLabel?: string;
 }
 
-/** Props for the {@link NiceMenu} component — a horizontal or vertical navigation menu with nested sub-menus. */
+export declare type NiceMenuOrientation = 'horizontal' | 'vertical';
+
 export declare interface NiceMenuProps extends NiceBaseProps {
-    /** Size variant. */
-    size?: NiceSize;
     /** Menu items. */
     items: NiceMenuItem[];
     /** Layout direction. */
-    orientation?: 'horizontal' | 'vertical';
-    /** Called when any item is clicked. */
-    onItemClick?: (item: NiceMenuItem) => void;
+    orientation?: NiceMenuOrientation;
+    /** Visual style. */
+    variant?: NiceMenuVariant;
+    /** Density preset (paddings + font size). */
+    density?: NiceMenuDensity;
+    /** Size preset. */
+    size?: NiceSize;
+    /** Stretch top-level items to fill the container. */
+    fullWidth?: boolean;
+    /** Show vertical separators between top items. */
+    showDividers?: boolean;
+    /** Top-item alignment for dropdown panels. */
+    panelAlign?: NiceMenuAlign;
+    /** Min width for dropdown / sub-panel (px). */
+    panelMinWidth?: number;
+    /** Max width for dropdown / sub-panel (px). */
+    panelMaxWidth?: number;
+    /**
+     * Gap (in px or any CSS length) between top-level items. Use `0` for
+     * a fully flush bar (e.g. tab-bar look). Default: density-driven (`4px`).
+     */
+    itemGap?: number | string;
+    /**
+     * Horizontal padding inside each top-level button. Overrides density.
+     * Accepts a number (treated as `px`) or any CSS length.
+     */
+    paddingX?: number | string;
+    /**
+     * Vertical padding inside each top-level button. Overrides density.
+     * Accepts a number (treated as `px`) or any CSS length.
+     */
+    paddingY?: number | string;
+    /**
+     * Render dropdown / sub-panels in a `document.body` portal so the menu
+     * never gets clipped by `overflow: hidden` ancestors. Default: `true`.
+     * Set `false` to fall back to the legacy absolute-positioned panel.
+     */
+    portal?: boolean;
+    /**
+     * z-index applied to the portalled dropdown panel. Default: `1100`.
+     */
+    panelZIndex?: number;
+    /** Custom arrow node for items with children. Default: `▾`. */
+    arrowIcon?: default_2.ReactNode;
+    /** Custom flyout arrow shown next to nested items. Default: `▸`. */
+    flyoutArrowIcon?: default_2.ReactNode;
+    /** Close the panel after selecting any leaf entry. Default: `true`. */
+    closeOnSelect?: boolean;
+    /**
+     * How to open dropdown panels:
+     * - `click` (default) — toggle on trigger click only.
+     * - `hover`           — open on pointer-enter, close on pointer-leave (after `closeDelay`).
+     * - `both`            — opens on hover *and* click (best-of-both for mega-menus).
+     */
+    openTrigger?: 'click' | 'hover' | 'both';
+    /** Delay (ms) before opening on hover. Default: `120`. */
+    openDelay?: number;
+    /** Delay (ms) before closing after pointer leaves the menu+panel. Default: `180`. */
+    closeDelay?: number;
+    /** Notified whenever the open trigger id changes (null = closed). */
+    onOpenChange?: (id: string | null) => void;
+    /** Highlight the matching id (or any of its ancestors). */
+    activeId?: string;
+    /** Legacy alias for `activeId`. */
+    activeKey?: string;
+    /** Called when any leaf is clicked. */
+    onItemClick?: (item: NiceMenuItem, event: default_2.MouseEvent) => void;
+    /** Accessible name for the wrapper `<nav>`. */
+    ariaLabel?: string;
+    /** Optional renderer for top-level trigger label (allows wrapping with i18n components). */
+    renderTriggerLabel?: (item: NiceMenuItem) => default_2.ReactNode;
+    /** Optional renderer for panel-entry label. */
+    renderEntryLabel?: (item: NiceMenuItem) => default_2.ReactNode;
 }
 
+/**
+ * Visual style for top-level triggers.
+ * - `separated` — soft buttons with gap (default-ish)
+ * - `group`     — flush button-group with shared border
+ * - `pills`     — rounded pills, primary fill on active
+ * - `ghost`     — chrome-less, hover only (used by NiceTopNav)
+ * - `solid`     — opaque buttons on `--bg-elevated`
+ * - `underline` — flat with animated underline on hover/active
+ * - `tabs`      — tab-bar look (top-rounded, bottom border)
+ * - `glass`     — translucent blurred background
+ */
+export declare type NiceMenuVariant = 'separated' | 'group' | 'pills' | 'ghost' | 'solid' | 'underline' | 'tabs' | 'glass' | 'bordered' | 'borderless';
+
 export declare const NiceMergeRequestBuilder: default_2.FC<NiceMergeRequestBuilderProps>;
 
 export declare interface NiceMergeRequestBuilderProps extends NiceBaseProps {
@@ -14319,6 +14605,197 @@ export declare interface NiceNavbarProps extends NiceFormFieldProps {
     onBrandClick?: () => void;
 }
 
+export declare const NiceNavMenu: default_2.ForwardRefExoticComponent<NiceNavMenuProps & default_2.RefAttributes<HTMLElement>>;
+
+export declare type NiceNavMenuAlign = 'start' | 'end' | 'auto';
+
+export declare interface NiceNavMenuItem {
+    /** Stable id used for active-marking and keyboard focus. */
+    id: string;
+    /** Displayed label. */
+    label: default_2.ReactNode;
+    /** Optional icon (emoji, SVG node, NiceIcon). */
+    icon?: default_2.ReactNode;
+    /** Navigation href (rendered as `<a>` when no children). */
+    href?: string;
+    /** Anchor `target` attribute (only when `href` is set). */
+    target?: '_self' | '_blank' | '_parent' | '_top';
+    /** Anchor `rel` attribute (only when `href` is set). */
+    rel?: string;
+    /** Click handler (rendered as `<button>` when no `href`). */
+    onClick?: (e: default_2.MouseEvent) => void;
+    /** Disable the item. */
+    disabled?: boolean;
+    /** Render as a danger action (red text). */
+    danger?: boolean;
+    /** Render as a divider (label/icon ignored). */
+    divider?: boolean;
+    /** Optional badge node rendered to the right of the label. */
+    badge?: default_2.ReactNode;
+    /** Optional secondary text shown under the label inside dropdowns. */
+    description?: string;
+    /** Sub-items (only honored at level-1 to produce a level-2 flyout). */
+    children?: NiceNavMenuItem[];
+    /**
+     * **Mega menu** — when set on a top-level item, opens a FULL-WIDTH panel
+     * anchored to the bar's bottom edge instead of a floating dropdown. Use for
+     * marketing/SaaS navs where you want rich multi-column content.
+     *
+     * Either pass a ready `megaPanel` JSX node, or use the structured
+     * `megaColumns` shorthand which renders a clean column-based layout for you.
+     * Both can be set; `megaPanel` wins.
+     */
+    megaPanel?: default_2.ReactNode | (() => default_2.ReactNode);
+    /** Structured mega-menu data — rendered as columns of items. */
+    megaColumns?: NiceNavMenuMegaColumn[];
+    /** Optional footer node rendered at the bottom of the mega panel (CTA strip). */
+    megaFooter?: default_2.ReactNode;
+}
+
+/** A single column of items inside a mega-menu panel. */
+export declare interface NiceNavMenuMegaColumn {
+    /** Optional column heading. */
+    title?: default_2.ReactNode;
+    /** Items rendered in the column (no nested mega; each is a simple item). */
+    items: NiceNavMenuItem[];
+    /** Optional footer node under this column (e.g. "View all" link). */
+    footer?: default_2.ReactNode;
+}
+
+export declare interface NiceNavMenuProps {
+    /** Top-level items. */
+    items: NiceNavMenuItem[];
+    /** Currently active item id (matched against any nested item id). */
+    activeId?: string;
+    /** Size scale. Default `'md'`. */
+    size?: NiceNavMenuSize;
+    /** Dropdown panel alignment. Default `'start'`. */
+    align?: NiceNavMenuAlign;
+    /** Accessible label for the surrounding `<nav>`. */
+    ariaLabel?: string;
+    /** Render full-width (top-level items stretch to fill). Default `false`. */
+    stretch?: boolean;
+    /**
+     * How top-level dropdowns / mega-panels open. Default `'click'` for backward
+     * compatibility. Set to `'hover'` to get the classical desktop mega-menu
+     * pattern (Apple / Microsoft / Stripe) — opens on mouse-enter, closes after
+     * a short grace delay so the cursor can travel into the panel.
+     */
+    trigger?: 'click' | 'hover';
+    /** Hover-close grace delay in ms. Default 150. Only used when `trigger='hover'`. */
+    hoverCloseDelay?: number;
+    /** Pass-through className. */
+    className?: string;
+    /** Pass-through style. */
+    style?: default_2.CSSProperties;
+    /** Pass-through id. */
+    id?: string;
+    /** Test id. */
+    'data-testid'?: string;
+}
+
+export declare type NiceNavMenuSize = 'sm' | 'md' | 'lg';
+
+export declare const NiceNavShell: ForwardRefExoticComponent<NiceNavShellProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceNavShellApi {
+    activeRoute: string | undefined;
+    tabs: NiceNavShellTab[];
+    openRoute: (route: string, opts?: Partial<NiceNavShellTab>) => void;
+    closeTab: (id: string) => void;
+    closeOthers: (id: string) => void;
+    closeAll: () => void;
+    pinTab: (id: string, pinned?: boolean) => void;
+    setDirty: (id: string, dirty?: boolean) => void;
+}
+
+export declare type NiceNavShellPersistence = 'memory' | 'localStorage' | 'session';
+
+export declare interface NiceNavShellProps {
+    /** Top navigation slot — pass a ReactNode or render-prop. */
+    topNav?: Slot;
+    /**
+     * Convenience pass-through: when set (and `topNav` is not), the shell
+     * renders an internal `<NiceTopNav>` with these props. Lets consumers get
+     * a fully-featured top bar (logo / nav menu / search / pickers /
+     * notifications / user menu / collapsible right cluster) without having
+     * to import and instantiate NiceTopNav themselves.
+     */
+    topNavProps?: NiceTopNavProps;
+    /** Sidebar navigation slot. */
+    sidebar?: Slot;
+    /** Map of route → content (ReactNode or factory). */
+    routes: Record<string, ReactNode | (() => ReactNode)>;
+    /** Initial / default route (used when uncontrolled). */
+    defaultRoute?: string;
+    /** Controlled active route. */
+    activeRoute?: string;
+    /** Called whenever the active route changes. */
+    onRouteChange?: (route: string) => void;
+    /** Optional per-route labels (used for tab titles). */
+    routeLabels?: Record<string, ReactNode>;
+    /** Optional per-route icons. */
+    routeIcons?: Record<string, ReactNode>;
+    /** Fallback rendered when active route has no entry in `routes`. */
+    fallback?: ReactNode;
+    /**
+     * Rendered in the content area when no route is active (uncontrolled mode
+     * with no `defaultRoute`). Defaults to a blank panel painted with the
+     * theme background — intentionally empty so the shell never auto-jumps to
+     * the first route. Pass any node to customise (welcome screen, hero,
+     * shortcuts grid, etc.).
+     */
+    emptyState?: ReactNode;
+    /** `'enabled'` shows the tab strip; `'disabled'` (default) just routes content. */
+    tabsMode?: 'enabled' | 'disabled';
+    /** When `false` (default) navigating to an already-open route focuses it instead of duplicating. */
+    allowDuplicateTabs?: boolean;
+    /** Maximum number of tabs (oldest non-pinned auto-closes when exceeded). */
+    maxTabs?: number;
+    /** Show close X. Default `true`. */
+    closableTabs?: boolean;
+    /** Allow pin/unpin via context menu. Default `true`. */
+    pinnableTabs?: boolean;
+    /** Reorder via drag (shipped as basic HTML5 drag — opt-in). Default `false`. */
+    reorderableTabs?: boolean;
+    /** Persistence backend for tab list. Default `'memory'`. */
+    persistTabs?: NiceNavShellPersistence;
+    /** Storage key for persistence. Default `'nice-nav-shell:tabs'`. */
+    persistKey?: string;
+    /** Tab strip is wheel-scrollable + shows ◀▶ arrows on overflow. Default `true`. */
+    tabsScrollable?: boolean;
+    /** Right-click tab → menu (close / close others / close all / pin). Default `true`. */
+    tabsContextMenu?: boolean;
+    /** Content swap animation. Default `'fade'`. */
+    tabsAnimation?: NiceNavShellTabsAnimation;
+    /** Initial tab list (used only on first mount when storage is empty). */
+    initialTabs?: NiceNavShellTab[];
+    /** Routes auto-opened as pinned on first mount. */
+    pinnedRoutes?: string[];
+    className?: string;
+    contentClassName?: string;
+    'data-testid'?: string;
+}
+
+export declare interface NiceNavShellTab {
+    /** Unique stable id. Defaults to `route` if omitted at openRoute call. */
+    id: string;
+    /** Route key the tab represents. */
+    route: string;
+    /** Tab label (string or arbitrary node). */
+    label: ReactNode;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+    /** Pinned tabs render first and have no close button by default. */
+    pinned?: boolean;
+    /** When true, shows a `•` dot indicating unsaved work. */
+    dirty?: boolean;
+    /** Per-tab override of `closableTabs`. */
+    closable?: boolean;
+}
+
+export declare type NiceNavShellTabsAnimation = 'none' | 'fade' | 'slide';
+
 export declare const NiceNetworkDiscoveryPanel: default_2.FC<NiceNetworkDiscoveryPanelProps>;
 
 export declare interface NiceNetworkDiscoveryPanelProps extends NiceBaseProps {
@@ -14412,6 +14889,24 @@ export declare interface NiceNotificationChannel {
     configUrl?: string;
 }
 
+export declare interface NiceNotificationItem {
+    id: string;
+    title: string;
+    body?: string;
+    /** Visual level (controls color of marker dot). Default `'info'`. */
+    level?: NiceNotificationLevel;
+    /** Optional ISO date string or Date instance. */
+    timestamp?: string | Date;
+    /** Whether this notification has already been seen. */
+    read?: boolean;
+    /** Optional icon/avatar node. */
+    icon?: default_2.ReactNode;
+    /** Click handler — fires when the row is activated. */
+    onClick?: () => void;
+}
+
+export declare type NiceNotificationLevel = 'info' | 'success' | 'warning' | 'error';
+
 export declare const NiceNotificationPreferences: default_2.FC<NiceNotificationPreferencesProps>;
 
 export declare interface NiceNotificationPreferencesProps extends NiceBaseProps {
@@ -14444,6 +14939,49 @@ export declare interface NiceNotificationPrefs {
     };
 }
 
+export declare const NiceNotifications: default_2.ForwardRefExoticComponent<NiceNotificationsProps & default_2.RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceNotificationsProps {
+    /** List of notifications. */
+    items?: NiceNotificationItem[];
+    /**
+     * Optional explicit unread count. When omitted, it is computed from
+     * `items.filter(i => !i.read).length`.
+     */
+    unreadCount?: number;
+    /** Title rendered at the top of the dropdown panel. */
+    panelTitle?: string;
+    /** Empty-state text. */
+    emptyText?: string;
+    /** Width (px) of the dropdown panel. Default: 340. */
+    panelWidth?: number;
+    /** Maximum dropdown height (px). Default: 420. */
+    maxHeight?: number;
+    /** Show "Mark all as read" link in panel header. Default: true. */
+    showMarkAllRead?: boolean;
+    /** Show "View all" link at panel footer. Default: false. */
+    showViewAll?: boolean;
+    /** Mark-all-as-read handler. */
+    onMarkAllRead?: () => void;
+    /** View-all handler. */
+    onViewAll?: () => void;
+    /** Per-item read-toggle handler (called when user marks an item read). */
+    onItemRead?: (id: string) => void;
+    /** Custom bell icon. */
+    icon?: default_2.ReactNode;
+    /** Controlled open flag. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Cap the badge display (default 99 → shows "99+"). */
+    badgeMax?: number;
+    /** Size variant of the trigger. */
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+    style?: default_2.CSSProperties;
+    id?: string;
+    'data-testid'?: string;
+}
+
 export declare const NiceNumberInput: default_2.ForwardRefExoticComponent<NiceNumberInputProps & default_2.RefAttributes<HTMLInputElement>>;
 
 /** Props for the {@link NiceNumberInput} component — a numeric field with stepper and precision control. */
@@ -15880,6 +16418,165 @@ export declare interface NiceRealtimeChartRef {
     getData: () => RealtimeDataPoint[];
 }
 
+/**
+ * Recipe display component — shows photos, metadata (servings/time/difficulty),
+ * ingredient list and step-by-step instructions. Read-mostly; pair with
+ * {@link NiceRecipeEditor} (from `@nice2dev/ui-tools`) for editing.
+ */
+export declare const NiceRecipe: default_2.FC<NiceRecipeProps>;
+
+/** A named group of recipe ids. */
+export declare interface NiceRecipeCollection {
+    id: string;
+    name: string;
+    description?: string;
+    recipeIds: string[];
+}
+
+/**
+ * Sidebar of named collections (cookbooks, weekly menus, themes…) plus a
+ * `NiceRecipeList` filtered to the active collection's recipe ids.
+ * Includes inline create / rename / delete and an "Add recipe" picker.
+ */
+export declare const NiceRecipeCollections: default_2.FC<NiceRecipeCollectionsProps>;
+
+export declare interface NiceRecipeCollectionsProps extends NiceBaseProps {
+    /** Pool of recipes the collections reference. */
+    recipes: NiceRecipeModel[];
+    /** Collections to display. */
+    collections: NiceRecipeCollection[];
+    /** Fired when collections change (rename, add, remove, add/remove recipe). */
+    onChange?: (collections: NiceRecipeCollection[]) => void;
+    /** Hide create / rename / delete controls. */
+    readOnly?: boolean;
+    /** Fired when a recipe card inside the active collection is clicked. */
+    onSelectRecipe?: (recipe: NiceRecipeModel) => void;
+}
+
+/** Difficulty enum used by recipe + scheduler-recipe variant. */
+export declare type NiceRecipeDifficulty = 'easy' | 'medium' | 'hard';
+
+/**
+ * Recipe editor — full CRUD over a {@link NiceRecipe}: metadata,
+ * ingredients (add/remove/reorder), steps (add/remove/reorder), photos
+ * (URL-based). Pair with {@link NiceRecipe} (from `@nice2dev/ui-planning`)
+ * for read-only display.
+ */
+export declare const NiceRecipeEditor: default_2.FC<NiceRecipeEditorProps>;
+
+export declare interface NiceRecipeEditorProps extends NiceBaseProps {
+    /** Recipe to edit. Pass `undefined` for "new". */
+    recipe?: NiceRecipeModel;
+    /** Called on every change (live binding). */
+    onChange?: (recipe: NiceRecipeModel) => void;
+    /** Called when the user clicks Save (`showActions`). */
+    onSave?: (recipe: NiceRecipeModel) => void;
+    /** Called when the user clicks Cancel. */
+    onCancel?: () => void;
+    /** Render Save/Cancel buttons. */
+    showActions?: boolean;
+    /** Custom Save button label. */
+    saveLabel?: string;
+    /** Custom Cancel button label. */
+    cancelLabel?: string;
+}
+
+/**
+ * Browsable, searchable, filterable grid of {@link NiceRecipe} cards.
+ * Pure-client filtering: title/description/tags substring + difficulty + tag.
+ */
+export declare const NiceRecipeList: default_2.FC<NiceRecipeListProps>;
+
+export declare interface NiceRecipeListProps extends NiceBaseProps {
+    /** Recipes to browse. */
+    recipes: NiceRecipeModel[];
+    /** Fired when the user activates a card. */
+    onSelect?: (recipe: NiceRecipeModel) => void;
+    /** Initial search query. */
+    initialQuery?: string;
+    /** Hide the difficulty / tag filters. */
+    hideFilters?: boolean;
+    /** Empty-state hint when no recipes match. */
+    emptyMessage?: string;
+}
+
+/** A full recipe record. */
+export declare interface NiceRecipeModel {
+    id: string;
+    title: string;
+    description?: string;
+    /** Number of servings the recipe yields. */
+    servings?: number;
+    prepMinutes?: number;
+    cookMinutes?: number;
+    difficulty?: NiceRecipeDifficulty;
+    cuisine?: string;
+    tags?: string[];
+    ingredients: NiceIngredient[];
+    steps: NiceRecipeStep[];
+    photos?: NiceRecipePhoto[];
+    nutrition?: NiceRecipeNutrition;
+    /** External source (URL or attribution). */
+    sourceUrl?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+/** Optional nutrition summary per serving. */
+export declare interface NiceRecipeNutrition {
+    calories?: number;
+    protein?: number;
+    fat?: number;
+    carbs?: number;
+    fiber?: number;
+    sugar?: number;
+    sodium?: number;
+}
+
+/** A photo attached to a recipe. */
+export declare interface NiceRecipePhoto {
+    id: string;
+    /** Image URL (data:, blob:, http(s):). */
+    url: string;
+    /** Alt text / caption. */
+    caption?: string;
+    /** When true, this photo is used as the cover image. */
+    primary?: boolean;
+}
+
+/** Props for {@link NiceRecipe}. */
+export declare interface NiceRecipeProps extends NiceBaseProps {
+    /** Recipe to display. */
+    recipe: NiceRecipeModel;
+    /** Compact card layout (smaller paddings, hides description / nutrition). */
+    compact?: boolean;
+    /** Hide the photo gallery. */
+    hidePhotos?: boolean;
+    /** Hide the ingredients column. */
+    hideIngredients?: boolean;
+    /** Hide the steps list. */
+    hideSteps?: boolean;
+    /** Toggle an ingredient's `checked` state (interactive shopping mode). */
+    onIngredientToggle?: (ingredient: NiceIngredient) => void;
+    /** Toggle a step's `done` state (interactive cook mode). */
+    onStepToggle?: (step: NiceRecipeStep) => void;
+}
+
+/** A single step / instruction in a recipe. */
+export declare interface NiceRecipeStep {
+    id: string;
+    /** Render order (1-based). */
+    order: number;
+    /** Human instruction text. Markdown-friendly but rendered as plain text by default. */
+    instruction: string;
+    /** Optional duration in minutes for timers. */
+    durationMinutes?: number;
+    /** Optional URL of an image illustrating the step. */
+    image?: string;
+    /** Marks the step as completed in interactive cook mode. */
+    done?: boolean;
+}
+
 /**
  * NiceReconciliationView — Bank reconciliation split-view with drag-drop matching.
  *
@@ -16452,6 +17149,40 @@ export declare interface NiceSchedulerEvent {
     description?: string;
     /** Event visual style */
     eventStyle?: 'solid' | 'striped' | 'outlined' | 'dashed';
+    /**
+     * Discriminator selecting which form variant to use in the built-in editor.
+     * Defaults to `'task'`. Use `'recipe'` to attach a {@link NiceRecipe} via
+     * `recipe`, or `'service'` to attach service data via `service`.
+     */
+    eventType?: NiceSchedulerEventType;
+    /** Recipe payload — present when `eventType === 'recipe'`. */
+    recipe?: NiceRecipeModel;
+    /** Service payload — present when `eventType === 'service'`. */
+    service?: NiceSchedulerServiceData;
+}
+
+/**
+ * Discriminator for the kind of thing scheduled. Built-ins:
+ *   - `'task'`  — generic event (default, back-compat).
+ *   - `'recipe'` — meal-prep / cooking session backed by a {@link NiceRecipe}.
+ *   - `'service'` — a service appointment (provider, customer, location, price).
+ *
+ * Consumers can extend with custom string literals — the scheduler will treat
+ * unknown types like `'task'` unless a matching {@link NiceSchedulerEventTypeDef}
+ * is provided in `eventTypes`.
+ */
+export declare type NiceSchedulerEventType = 'task' | 'recipe' | 'service' | (string & {});
+
+/** Definition of a custom event-type option exposed in the editor's type picker. */
+export declare interface NiceSchedulerEventTypeDef {
+    /** Discriminator value matching {@link NiceSchedulerEvent.eventType}. */
+    type: NiceSchedulerEventType;
+    /** Display label in the editor select. */
+    label: string;
+    /** Optional emoji/icon glyph. */
+    icon?: string;
+    /** Optional accent color for the chip in the calendar grid. */
+    color?: string;
 }
 
 /** Props for the {@link NiceScheduler} component — a full-featured calendar / scheduler with drag, recurring events, resources, and inline editing. */
@@ -16499,6 +17230,19 @@ export declare interface NiceSchedulerProps extends NiceBaseProps {
     editable?: boolean;
     /** Custom field set for the built-in editor — when provided, replaces the auto-generated default fields. NiceForm-compatible. */
     formFields?: NiceFormItem[];
+    /**
+     * Per-event-type form field overrides. When a key matches the active
+     * `eventType` in the editor, those NiceForm items REPLACE the type-specific
+     * section (recipe/service body). Use `'task'` to override the default form.
+     */
+    formFieldsByType?: Partial<Record<NiceSchedulerEventType, NiceFormItem[]>>;
+    /**
+     * Available event-type options in the editor's type picker. When omitted,
+     * defaults to a single `'task'` entry (back-compat — no picker shown).
+     * Pass `[{type:'task'},{type:'recipe'},{type:'service'}]` to enable all three
+     * built-ins.
+     */
+    eventTypes?: NiceSchedulerEventTypeDef[];
     /** Custom full editor render — when provided, takes over the entire editor body. */
     renderEventEditor?: (ctx: {
         event?: NiceSchedulerEvent | null;
@@ -16529,6 +17273,26 @@ export declare interface NiceSchedulerResource {
     color?: string;
 }
 
+/** Service-specific data attached to a `service` event. */
+export declare interface NiceSchedulerServiceData {
+    /** Service name (e.g. "Haircut", "Oil change"). */
+    serviceName: string;
+    /** Person providing the service. */
+    providerName?: string;
+    /** Customer name. */
+    customerName?: string;
+    /** Customer phone / email. */
+    customerContact?: string;
+    /** Location / address. */
+    location?: string;
+    /** Price (numeric). */
+    price?: number;
+    /** Currency code (ISO 4217), defaults to display-only "PLN". */
+    currency?: string;
+    /** Free-form notes. */
+    notes?: string;
+}
+
 /** Available calendar views for the {@link NiceScheduler}. */
 export declare type NiceSchedulerView = 'day' | 'week' | 'workWeek' | 'month' | 'dayRange' | 'monthRange' | 'agenda' | 'timeline';
 
@@ -16550,6 +17314,77 @@ export declare interface NiceScrollViewProps extends NiceBaseProps {
     children?: default_2.ReactNode;
 }
 
+export declare const NiceSearchBar: default_2.ForwardRefExoticComponent<NiceSearchBarProps & default_2.RefAttributes<NiceSearchBarHandle>>;
+
+export declare type NiceSearchBarExpandDirection = 'left' | 'right' | 'down';
+
+export declare interface NiceSearchBarHandle {
+    focus: () => void;
+    expand: () => void;
+    collapse: () => void;
+    clear: () => void;
+}
+
+export declare interface NiceSearchBarProps {
+    /** Controlled value. */
+    value?: string;
+    /** Default value (uncontrolled). */
+    defaultValue?: string;
+    /** Change handler. */
+    onChange?: (value: string) => void;
+    /** Submit handler — fires on Enter. */
+    onSubmit?: (value: string) => void;
+    /** Clear handler — fires when ✕ is clicked or Escape pressed with non-empty value. */
+    onClear?: () => void;
+    /** Placeholder text (defaults to translated "Search…"). */
+    placeholder?: string;
+    /**
+     * If true, the bar starts already expanded and stays so unless `collapsible`
+     * is also true. Default: `false`.
+     */
+    defaultExpanded?: boolean;
+    /**
+     * Controlled expanded flag. When provided, takes priority over the
+     * internal state.
+     */
+    expanded?: boolean;
+    /** Notified whenever the expanded state changes. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Allow the bar to collapse. Default: `true` when no `expanded` is given.
+     * Set to `false` to render an always-expanded plain search input.
+     */
+    collapsible?: boolean;
+    /**
+     * Direction the input grows when expanding from the icon-button.
+     * Default: `'left'` (suitable for top-nav right cluster).
+     */
+    expandDirection?: NiceSearchBarExpandDirection;
+    /**
+     * Maximum width of the expanded input (px). Default: `260`.
+     * On narrow screens caps automatically at `100vw - 32px`.
+     */
+    expandWidth?: number;
+    /**
+     * Auto-collapse when the input loses focus AND is empty. Default: `true`.
+     */
+    autoCollapseOnBlur?: boolean;
+    /** Size variant. */
+    size?: NiceSearchBarSize;
+    /** Custom search icon. Default: 🔍 (will use NiceIcon when wired by host). */
+    icon?: default_2.ReactNode;
+    /** Disable the control. */
+    disabled?: boolean;
+    /** Accessible label. */
+    ariaLabel?: string;
+    className?: string;
+    style?: default_2.CSSProperties;
+    id?: string;
+    'data-testid'?: string;
+}
+
+export declare type NiceSearchBarSize = 'sm' | 'md' | 'lg';
+
 /**
  * `NiceSegmentedControl` — single-selection toggle group with an animated
  * sliding "thumb" highlight, iOS-style. The control owns a single value
@@ -16806,10 +17641,36 @@ export declare interface NiceSidebarNavProps {
     onPreferencesChange?: (prefs: SidebarNavUserPrefs) => void;
     /** Sidebar width in px (default: 264) */
     width?: number;
+    /** Sidebar width in px when collapsed/icon-only (default: 56). */
+    collapsedWidth?: number;
+    /**
+     * Which side of the screen the sidebar is anchored to. Default `'left'`.
+     * `'right'` flips the chevron direction and pushes the footer-toggle to the
+     * left edge — useful for RTL or right-side admin shells.
+     */
+    position?: 'left' | 'right';
+    /**
+     * **Minimal mode** — hides the mode strip, sources, favorites and footer
+     * preferences, leaving only the navigation tree. Use for stripped-down
+     * shells (auth flows, embedded views) where the full taxonomy is overkill.
+     * Default `false`.
+     */
+    minimal?: boolean;
+    /** Optional header slot rendered above the mode strip / tree (e.g. workspace switcher). */
+    header?: ReactNode;
+    /** Optional footer slot rendered below the standard footer-toggle row. */
+    footerExtra?: ReactNode;
     /** Collapsed (icon-only) mode */
     collapsed?: boolean;
     /** Called when collapsed state changes (for toggle button) */
     onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * When `true` (default), users can still expand/collapse module branches
+     * even while the sidebar itself is in icon-only collapsed mode (chevrons
+     * stay visible). When `false`, all branches are forced flat / always-open
+     * in collapsed mode (legacy behaviour).
+     */
+    expandableWhenCollapsed?: boolean;
     /** Extra CSS class on the root element */
     className?: string;
     /** Size variant */
@@ -18104,14 +18965,32 @@ export declare interface NiceThemePickerProps extends NiceFormFieldProps, DualVi
     defaultValue?: string;
     /** Callback when selection changes */
     onChange?: (theme: NiceThemeDescriptor | null) => void;
-    /** Available themes (required — picker is dumb on its own). */
-    themes: NiceThemeDescriptor[];
+    /**
+     * Available themes. Defaults to {@link NICE_THEME_PICKER_PRESETS} (all
+     * built-in presets adapted from {@link NICE_THEME_PRESETS}). Pass an
+     * explicit array to override or to add custom themes alongside the presets.
+     *
+     * Note: passing `[]` will produce an empty dropdown and emit a dev-mode
+     * warning. Omit the prop entirely to fall back to the built-in presets.
+     */
+    themes?: NiceThemeDescriptor[];
     /** Placeholder shown when nothing is selected (ignored in compact mode). */
     placeholder?: string;
     /** Enable search */
     showSearch?: boolean;
-    /** Search placeholder */
+    /**
+     * Threshold below which the internal search/filter input is hidden even
+     * when `showSearch` is `true`. Prevents a noisy filter UI for short lists
+     * (e.g. 6 themes). Default: `8`. Set `0` to always show, `Infinity` to
+     * always hide.
+     */
+    searchThreshold?: number;
+    /** Search placeholder. Default: translated `'Filter themes…'`. */
     searchPlaceholder?: string;
+    /** Controlled open state (for coordinating with sibling controls). */
+    isOpen?: boolean;
+    /** Notified whenever the dropdown open state changes. */
+    onOpenChange?: (open: boolean) => void;
     /** Show preview thumbnail in trigger. Default: true */
     showPreviewInValue?: boolean;
     /** Show preview thumbnail in dropdown options. Default: true */
@@ -18460,6 +19339,245 @@ export declare interface NiceTooltipProps {
     children: default_2.ReactElement;
 }
 
+export declare const NiceTopNav: default_2.ForwardRefExoticComponent<NiceTopNavProps & default_2.RefAttributes<HTMLElement>>;
+
+export declare type NiceTopNavDensity = 'compact' | 'normal' | 'comfortable';
+
+/**
+ * Optional extra round icon-button shown in the right cluster
+ * (e.g. settings gear). When `menuItems` is provided, clicking the
+ * button opens a small dropdown menu; otherwise `onClick` fires.
+ *
+ * Added in v1.0.10 to satisfy customizable user-button cluster
+ * feedback for {@link NiceTopNav}.
+ */
+declare interface NiceTopNavExtraAction {
+    id: string;
+    label: string;
+    icon: default_2.ReactNode;
+    onClick?: () => void;
+    menuItems?: UserMenuItem[];
+    /** Optional badge / dot. */
+    badge?: number | string;
+}
+
+/** @deprecated v2 nav-item type. Prefer {@link NiceNavMenuItem} via `navMenuItems`. */
+export declare interface NiceTopNavItem {
+    id: string;
+    label: string;
+    icon?: default_2.ReactNode;
+    href?: string;
+    onClick?: () => void;
+}
+
+/** @deprecated v2 language type. Prefer `<NiceLanguagePicker>` props. */
+export declare interface NiceTopNavLanguageOption {
+    code: string;
+    label: string;
+    flag?: default_2.ReactNode;
+}
+
+/** @deprecated v2 user-menu item. Prefer {@link UserMenuItem}. */
+export declare interface NiceTopNavMenuItem {
+    id: string;
+    label: string;
+    icon?: default_2.ReactNode;
+    onClick?: () => void;
+    divider?: boolean;
+    href?: string;
+}
+
+export declare interface NiceTopNavProps {
+    height?: number | string;
+    density?: NiceTopNavDensity;
+    maxWidth?: number | string;
+    paddingX?: number | string;
+    gap?: number | string;
+    borderBottom?: boolean;
+    elevated?: boolean;
+    sticky?: boolean;
+    variant?: NiceTopNavVariant;
+    accentBar?: boolean;
+    accentBarColor?: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Visual state — mirrors the standard control state contract used across
+     * basic Nice2Dev controls (input, button). Defaults to `'normal'`.
+     * - `loading`  — renders a subtle shimmer overlay; bar remains interactive.
+     * - `error`    — accents the bottom border with `--color-danger`.
+     * - `disabled` — dims the bar and disables pointer events.
+     */
+    state?: 'normal' | 'loading' | 'error' | 'disabled';
+    /**
+     * Compact mode — collapses brand name, hides labels on icon-only actions,
+     * tightens paddings. Combine with `size='sm'` for an ultra-dense bar.
+     */
+    compact?: boolean;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * Bar height when collapsed. Defaults to `32` so the entire bar content
+     * (brand, nav menu, search, pickers, notifications, user menu) stays
+     * visible — proportionally scaled down via {@link collapsedContentScale}.
+     * Lower values produce an almost-hidden strip; raise for more breathing
+     * room around shrunk controls.
+     */
+    collapsedHeight?: number | string;
+    /**
+     * Scale factor (0–1) applied to the logo / brand name while collapsed.
+     * Default `0.5`. Affects only the brand block; use
+     * {@link collapsedContentScale} to scale the rest of the bar.
+     */
+    collapsedLogoScale?: number;
+    /**
+     * Scale factor (0–1) applied to the whole inner row (nav menu, search,
+     * pickers, notifications, user menu, collapse button) while collapsed.
+     * The bar shows ALL of its content — just very small — so users keep
+     * full functionality on a slim strip. Default `0.55`.
+     */
+    collapsedContentScale?: number;
+    hideOnScroll?: boolean;
+    scrollThreshold?: number;
+    logo?: default_2.ReactNode;
+    brandName?: string;
+    brandHref?: string;
+    onBrandClick?: () => void;
+    logoVariant?: NiceLogoVariant;
+    logoSize?: NiceLogoSize;
+    /**
+     * Brand block alignment within the bar. Combined with {@link navAlignment}
+     * gives 9 possible layouts. Default `'left'`.
+     *
+     * - `'left'`   — brand sits at the very start of the bar (classic).
+     * - `'center'` — brand is centered (use with `navAlignment='start'` for
+     *                a Bootstrap-style centered logo).
+     * - `'right'`  — brand sits at the end (rare, useful for RTL or unusual layouts).
+     */
+    brandAlign?: 'left' | 'center' | 'right';
+    /**
+     * Pre-baked configuration profile. Sets sensible defaults for several props
+     * at once so a one-line `<NiceTopNav preset="marketing" />` ships a polished
+     * bar. Any explicit prop overrides the preset's default.
+     *
+     * - `'marketing'` — landing-page bar: brand left, nav center, login/register
+     *                   right, no search, no pickers, accent bar on, sticky.
+     * - `'saas'`      — admin/SaaS bar: brand left, nav left, full toolbar
+     *                   (search + lang + theme + notifications + user menu),
+     *                   collapsible right cluster opens by default, settings
+     *                   gear after the avatar.
+     * - `'docs'`      — documentation bar: brand left, nav left, prominent
+     *                   always-expanded search (max 500px), theme picker only.
+     * - `'minimal'`   — bare brand bar: brand only, no nav, no right cluster.
+     */
+    preset?: 'marketing' | 'saas' | 'docs' | 'minimal';
+    navItems?: NiceTopNavItem[];
+    navMenuItems?: NiceNavMenuItem[];
+    activeNavId?: string;
+    navAlignment?: 'start' | 'center' | 'end';
+    /**
+     * How mega-menu items in `navMenuItems` open. Default `'hover'` (classical
+     * desktop pattern). Switch to `'click'` for touch-first sites. Only applies
+     * when at least one nav item carries `megaPanel` or `megaColumns`.
+     */
+    megaTrigger?: 'hover' | 'click';
+    mobileBreakpoint?: number;
+    /**
+     * How navigation behaves below `mobileBreakpoint`:
+     * - `hamburger` (default) — collapse to hamburger button + drawer.
+     * - `wrap`               — let nav items wrap onto a second row.
+     * - `scroll`             — keep nav inline; horizontally scroll-snap overflowed items.
+     */
+    mobileVariant?: 'hamburger' | 'wrap' | 'scroll';
+    searchPlaceholder?: string;
+    searchValue?: string;
+    onSearchChange?: (value: string) => void;
+    onSearchSubmit?: (value: string) => void;
+    collapsibleSearch?: boolean;
+    searchCollapsible?: boolean;
+    searchExpandDirection?: NiceSearchBarExpandDirection;
+    searchExpandWidth?: number;
+    searchBarProps?: Partial<NiceSearchBarProps>;
+    centerContent?: default_2.ReactNode;
+    /** Toggle search visibility independently of search props presence. Default: derived from search props. */
+    showSearch?: boolean;
+    languages?: NiceTopNavLanguageOption[];
+    currentLanguage?: string;
+    onLanguageChange?: (code: string) => void;
+    showLanguagePicker?: boolean;
+    languagePickerProps?: Partial<NiceLanguagePickerProps>;
+    themes?: NiceTopNavThemeOption[];
+    currentTheme?: string;
+    onThemeChange?: (id: string) => void;
+    showThemePicker?: boolean;
+    themePickerProps?: Partial<NiceThemePickerProps>;
+    notificationsCount?: number;
+    onNotificationsClick?: () => void;
+    notifications?: NiceNotificationItem[];
+    onMarkAllNotificationsRead?: () => void;
+    /** Toggle notifications visibility independently of notification props presence. */
+    showNotifications?: boolean;
+    user?: NiceTopNavUser | NiceAuthUser;
+    userMenuItems?: UserMenuItem[];
+    /** @deprecated Use `userMenuItems`. */
+    userMenu?: NiceTopNavMenuItem[];
+    onProfile?: () => void;
+    onLogout?: () => void;
+    showLogin?: boolean;
+    loginLabel?: string;
+    onLoginClick?: () => void;
+    showRegister?: boolean;
+    registerLabel?: string;
+    onRegisterClick?: () => void;
+    /**
+     * Extra round icon-buttons rendered right before the auth/user-menu cluster.
+     * Each entry can either fire `onClick` directly or open a small dropdown
+     * (`menuItems`). Use this to add a customizable settings gear / quick actions
+     * without forking {@link NiceAuthButtons}.
+     */
+    extraActions?: NiceTopNavExtraAction[];
+    /** Show a built-in settings gear (uses inline Ntd-style cog SVG). */
+    showSettings?: boolean;
+    /** Settings click handler — used when `settingsMenuItems` is empty. */
+    onSettingsClick?: () => void;
+    /** Optional dropdown items shown when the settings gear is clicked. */
+    settingsMenuItems?: UserMenuItem[];
+    /** Settings button aria-label / tooltip. */
+    settingsLabel?: string;
+    /**
+     * Wrap search + language + theme pickers in a collapsible cluster with a
+     * chevron toggle. When `true` (default), the cluster starts collapsed and
+     * expands to the LEFT on click — saves horizontal space and prevents the
+     * navigation menu from overlapping the right toolbar. Set to `false` to
+     * always render the pickers inline.
+     */
+    collapsibleRightCluster?: boolean;
+    /** Initial open state of the collapsible cluster. Default `false`. */
+    rightClusterDefaultOpen?: boolean;
+    leftContent?: default_2.ReactNode;
+    rightContent?: default_2.ReactNode;
+    className?: string;
+    style?: default_2.CSSProperties;
+    id?: string;
+    'data-testid'?: string;
+}
+
+/** @deprecated v2 theme type. Prefer `<NiceThemePicker>` props. */
+export declare interface NiceTopNavThemeOption {
+    id: string;
+    label: string;
+    icon?: default_2.ReactNode;
+}
+
+/** @deprecated v2 user type. Prefer {@link NiceAuthUser}. */
+export declare interface NiceTopNavUser {
+    name: string;
+    avatarUrl?: string;
+    initials?: string;
+}
+
+export declare type NiceTopNavVariant = 'default' | 'primary' | 'accent' | 'transparent' | 'glass' | 'dark';
+
 export declare interface NiceTopologyData {
     links: Array<{
         sourceId: string;
@@ -21226,6 +22344,9 @@ export declare interface RealtimeDataPoint {
     label?: string;
 }
 
+/** Total time = prep + cook (minutes), or undefined if neither provided. */
+export declare function recipeTotalMinutes(recipe: NiceRecipeModel): number | undefined;
+
 /**
  * Reconciliation view configuration.
  */
@@ -22266,7 +23387,7 @@ export declare interface SidebarNavDataNode {
 export declare interface SidebarNavDataSource {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     color?: string;
     /** Server URL or connection string hint */
     url?: string;
@@ -22277,7 +23398,7 @@ export declare interface SidebarNavDataSource {
 export declare interface SidebarNavFavorite {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     route?: string;
     sourceId?: string;
     moduleId?: string;
@@ -22300,7 +23421,7 @@ export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites'
 export declare interface SidebarNavModule {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     views: SidebarNavView[];
     /** Source this module belongs to */
     sourceId?: string;
@@ -22310,7 +23431,7 @@ export declare interface SidebarNavModule {
 export declare interface SidebarNavRole {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     modules: SidebarNavModule[];
     /** Source this role belongs to */
     sourceId?: string;
@@ -22320,7 +23441,7 @@ export declare interface SidebarNavRole {
 export declare interface SidebarNavUnit {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     modules: SidebarNavModule[];
     /** Source this unit belongs to */
     sourceId?: string;
@@ -22357,7 +23478,7 @@ export declare interface SidebarNavUserPrefs {
 export declare interface SidebarNavView {
     id: string;
     label: string;
-    icon?: string;
+    icon?: ReactNode;
     /** Route path for navigation */
     route?: string;
     /** Badge counter (unread notifications, pending tasks, …) */
@@ -22427,6 +23548,8 @@ declare interface SliderConfig {
     format?: (value: number) => string;
 }
 
+declare type Slot = ReactNode | ((api: NiceNavShellApi) => ReactNode);
+
 export declare interface SmartDeviceDto {
     id: string;
     name: string;
@@ -23583,6 +24706,25 @@ declare interface TooltipData {
 
 export { TooltipStyleVariant }
 
+/**
+ * Adapts a full {@link NiceTheme} into the lightweight
+ * {@link NiceThemeDescriptor} shape consumed by `<NiceThemePicker>`.
+ *
+ * The `id` is the theme name (stable identifier across renders); the
+ * `preview` colours feed the mini page-thumbnail rendered in the trigger
+ * and dropdown options.
+ *
+ * @example
+ * ```tsx
+ * import { NICE_THEME_PRESETS } from '@nice2dev/ui';
+ * import { toThemeDescriptor } from '@nice2dev/ui';
+ *
+ * const themes = NICE_THEME_PRESETS.map(toThemeDescriptor);
+ * <NiceThemePicker themes={themes} value={current} onChange={...} />
+ * ```
+ */
+export declare function toThemeDescriptor(theme: NiceTheme): NiceThemeDescriptor;
+
 export { TouchPoint }
 
 export { TouchTargetProps }