@ssa-ui-kit/core 3.24.0 → 3.25.0

package/dist/components/FloatingActionButton/types.d.ts

@@ -0,0 +1,129 @@
+import { AriaAttributes, MouseEventHandler, ReactNode } from 'react';
+import { ColorsKeys } from '../../types/emotion';
+import { IconProps } from '../Icon/types';
+/**
+ * Size scale of a {@link FloatingActionButton}. Icon-only and labelled FABs
+ * share one height per size: 32 / 36 / 40 / 44px.
+ */
+export type FloatingActionButtonSize = 'extraSmall' | 'small' | 'medium' | 'large';
+/**
+ * Corner of the viewport the {@link FloatingActionButton} is fixed to.
+ */
+export type FloatingActionButtonPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/**
+ * Background color of a {@link FloatingActionButton}.
+ * - `primary`: theme blue with a white icon (design default)
+ * - `secondary`: light grey with a dark icon
+ * - any theme color key (e.g. `'green'`) or CSS color string — the icon and
+ *   label color is picked automatically for contrast
+ */
+export type FloatingActionButtonColor = 'primary' | 'secondary' | ColorsKeys | (string & {});
+/**
+ * Icon of a FAB or of a menu action: a kit icon name, sized and colored by
+ * the FAB, or any node — which then brings its own size and color.
+ */
+export type FloatingActionButtonIcon = IconProps['name'] | ReactNode;
+/**
+ * A single item of a {@link FloatingActionButton} menu.
+ */
+export type FloatingActionButtonAction = {
+    /** Stable key for the item. */
+    id: string;
+    /** Icon of the item. */
+    icon: FloatingActionButtonIcon;
+    /**
+     * Text of the item. Always its accessible name; shown next to the icon
+     * unless `showActionLabels` is `false`.
+     */
+    label: string;
+    /** Called when the item is chosen. The menu then closes. */
+    onClick: () => void;
+    /** Disables the item. */
+    disabled?: boolean;
+};
+/**
+ * Props of the {@link FloatingActionButton} component.
+ */
+export type FloatingActionButtonProps = Pick<AriaAttributes, 'aria-label' | 'aria-describedby'> & {
+    /**
+     * Icon of the button (of the menu trigger while the menu is closed).
+     * @default 'plus'
+     */
+    icon?: FloatingActionButtonIcon;
+    /**
+     * Text shown next to the icon (the "extended" FAB). Without it the FAB is
+     * icon-only and needs an `aria-label`.
+     */
+    label?: string;
+    /**
+     * Background color. Pre-defined `primary` / `secondary`, a theme color key
+     * or any CSS color; custom colors get an auto-contrast icon and label.
+     * @default 'primary'
+     */
+    color?: FloatingActionButtonColor;
+    /**
+     * Draws the elevation shadow under the button.
+     * @default true
+     */
+    shadow?: boolean;
+    /**
+     * Corner shape: `square` keeps the 8px radius, `round` is fully rounded
+     * (a circle when icon-only, a pill when labelled).
+     * @default 'square'
+     */
+    shape?: 'square' | 'round';
+    /**
+     * Size of the button and of its menu items.
+     * @default 'medium'
+     */
+    size?: FloatingActionButtonSize;
+    /**
+     * Disables the button (and, in menu mode, opening the menu).
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Click handler. In menu mode it also runs, before the menu toggles.
+     */
+    onClick?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Items of the speed-dial menu. When given, the button toggles a stack of
+     * secondary FABs above it (below it for `top-*` positions).
+     */
+    actions?: FloatingActionButtonAction[];
+    /**
+     * Shows each action's `label` next to its icon. When `false` the items are
+     * icon-only and the label stays as their accessible name.
+     * @default true
+     */
+    showActionLabels?: boolean;
+    /** Controlled open state of the menu. */
+    open?: boolean;
+    /**
+     * Initial open state of the menu when uncontrolled.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Called when the menu opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Icon of the trigger while the menu is open.
+     * @default 'cross'
+     */
+    openIcon?: FloatingActionButtonIcon;
+    /**
+     * Viewport corner the FAB is fixed to.
+     * @default 'bottom-right'
+     */
+    position?: FloatingActionButtonPosition;
+    /**
+     * Distance from the corner in px — one value for both axes, or `{ x, y }`.
+     * @default 24
+     */
+    offset?: number | {
+        x: number;
+        y: number;
+    };
+    /** Class name of the fixed container. */
+    className?: string;
+};

package/dist/components/Header/Header.d.ts

@@ -0,0 +1,43 @@
+import { HeaderProps } from './types';
+/**
+ * Header - The application's top bar: logo, main navigation and a free slot
+ * on the right for the user profile, notifications or log out.
+ *
+ * ### Navigation
+ * `items` render as react-router links, so the Header must sit inside a
+ * router. The item matching the current location is highlighted, and so is
+ * every group above it. Groups open a dropdown — on hover with a mouse, on
+ * tap on touch screens — and a dropdown item can open a flyout one level
+ * further. Following a link closes them.
+ *
+ * ### Layout
+ * From 900px the navigation is centred between the logo and the right side,
+ * and scrolls sideways when it does not fit. Below 900px it moves into a
+ * drawer opened by a burger button, the logo is centred and `rightSide`
+ * stays as it is.
+ *
+ * ### Selected state
+ * The design sets the selected item in bold. The kit marks it by color
+ * only: a heavier face widens the item and shifts the whole bar whenever the
+ * route changes.
+ *
+ * @category Navigation
+ * @example
+ * ```tsx
+ * <Header
+ *   logo={<img src="/logo.svg" alt="Acme" height={38} />}
+ *   items={[
+ *     { id: 'home', label: 'Home', path: '/' },
+ *     {
+ *       id: 'people',
+ *       label: 'People',
+ *       children: [
+ *         { id: 'employees', label: 'Employees', path: '/people/employees' },
+ *       ],
+ *     },
+ *   ]}
+ *   rightSide={<UserProfile {...profile} />}
+ * />
+ * ```
+ */
+export declare const Header: import("react").ForwardRefExoticComponent<HeaderProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Header/HeaderMobileMenu.d.ts

@@ -0,0 +1,18 @@
+import { UseDrawerStore } from '../Drawer/useDrawer';
+import { HeaderNavItem, HeaderTheme } from './types';
+import * as S from './styles';
+interface HeaderMobileMenuProps {
+    store: UseDrawerStore;
+    items: HeaderNavItem[];
+    headerTheme: HeaderTheme;
+    palette: S.HeaderPalette;
+    pathname: string;
+    navLabel: string;
+}
+/**
+ * The navigation below 900px: a full-width drawer holding a `TreeView`, the
+ * same engine as CollapsibleNavBar's menu. The tree owns expansion and opens
+ * the group holding the current page; this module owns the routing.
+ */
+export declare const HeaderMobileMenu: ({ store, items, headerTheme, palette, pathname, navLabel, }: HeaderMobileMenuProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Header/HeaderNavMenu.d.ts

@@ -0,0 +1,17 @@
+import { HeaderNavItem } from './types';
+import * as S from './styles';
+interface NavEntryProps {
+    item: HeaderNavItem;
+    /** 0 — the bar itself, 1 — dropdown, 2 — flyout */
+    depth: number;
+    palette: S.HeaderPalette;
+    pathname: string;
+    /** Closes every menu above this one once a link is followed */
+    onNavigate?: () => void;
+}
+/**
+ * Top-level entry. Each group roots its own floating tree, so a flyout's
+ * hover and dismiss events reach the dropdown that opened it.
+ */
+export declare const HeaderNavEntry: (props: NavEntryProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Header/helpers.d.ts

@@ -0,0 +1,13 @@
+import { HeaderNavItem } from './types';
+/** Submenus nest this deep at most: top level → dropdown → flyout. */
+export declare const MAX_DEPTH = 2;
+/**
+ * Same rule as react-router's `NavLink` without `end`: the path itself or
+ * anything below it, matched on whole segments — `/people` covers
+ * `/people/42` but not `/peoples`. `/` only matches itself, as with NavLink.
+ */
+export declare const isPathActive: (pathname: string, path: string) => boolean;
+/** Leaf: its own path. Group: any descendant up to `MAX_DEPTH`. */
+export declare const isItemActive: (item: HeaderNavItem, pathname: string, depth?: number) => boolean;
+export declare const hasSubmenu: (item: HeaderNavItem, depth: number) => boolean;
+export declare const renderItemIcon: (icon: HeaderNavItem["icon"], size: number) => import("@emotion/react/jsx-runtime").JSX.Element | null;

package/dist/components/Header/index.d.ts

@@ -0,0 +1 @@
+export * from './Header';

package/dist/components/Header/styles.d.ts

@@ -0,0 +1,63 @@
+import { Theme } from '@emotion/react';
+import { HeaderSize, HeaderTheme } from './types';
+export declare const SIZES: Record<HeaderSize, {
+    height: number;
+    logo: number;
+}>;
+export declare const MENU_WIDTH = 164;
+/** Design: dropdowns sit 6px below their trigger and flyouts 6px aside. */
+export declare const MENU_OFFSET = 6;
+export declare const resolvePalette: (theme: Theme, headerTheme: HeaderTheme) => {
+    background: string;
+    text: `rgb${string}` | undefined;
+    accent: `rgb${string}` | undefined;
+    disabled: `rgb${string}` | undefined;
+    menuBackground: `rgb${string}` | undefined;
+    menuItem: `rgb${string}` | undefined;
+    menuItemHover: `rgb${string}` | undefined;
+    menuItemOpen: `rgb${string}` | undefined;
+    menuText: `rgb${string}` | undefined;
+    menuDisabled: `rgb${string}` | undefined;
+    drawerBackground: `rgb${string}` | undefined;
+} | {
+    background: `rgb${string}` | undefined;
+    text: `rgb${string}` | undefined;
+    accent: `rgb${string}` | "transparent";
+    disabled: `rgb${string}` | undefined;
+    menuBackground: `rgb${string}` | undefined;
+    menuItem: `rgb${string}` | undefined;
+    menuItemHover: `rgb${string}` | undefined;
+    menuItemOpen: `rgb${string}` | undefined;
+    menuText: `rgb${string}` | undefined;
+    menuDisabled: `rgb${string}` | undefined;
+    drawerBackground: `rgb${string}` | "transparent";
+};
+export type HeaderPalette = ReturnType<typeof resolvePalette>;
+export declare const root: (theme: Theme, palette: HeaderPalette, size: HeaderSize) => import("@emotion/react").SerializedStyles;
+export declare const burger: (theme: Theme, palette: HeaderPalette) => import("@emotion/react").SerializedStyles;
+/** Holds the burger's column when there is no menu, so the logo stays centred. */
+export declare const burgerPlaceholder: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/**
+ * Fixed height from the size; width follows the logo so wordmarks fit, but
+ * never drops below a square, so an empty box still holds its place.
+ */
+export declare const logo: (size: HeaderSize) => import("@emotion/react").SerializedStyles;
+/**
+ * The scroll container. Dropdowns are portalled, so the overflow here does
+ * not clip them.
+ */
+export declare const nav: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/** `margin: auto` centres the list while it fits and lets it scroll after. */
+export declare const navList: import("@emotion/react").SerializedStyles;
+export declare const rightSide: import("@emotion/react").SerializedStyles;
+/**
+ * Selected keeps the regular weight: the design's bold resizes the item and
+ * shifts the whole bar as the route changes, so the state is marked by color
+ * alone.
+ */
+export declare const navItem: (theme: Theme, palette: HeaderPalette, active: boolean) => import("@emotion/react").SerializedStyles;
+export declare const menu: (theme: Theme, palette: HeaderPalette) => import("@emotion/react").SerializedStyles;
+export declare const menuItem: (theme: Theme, palette: HeaderPalette, active: boolean) => import("@emotion/react").SerializedStyles;
+export declare const drawerContent: (palette: HeaderPalette) => import("@emotion/react").SerializedStyles;
+/** Chevron of a mobile group row; flips while the group is open. */
+export declare const mobileToggle: (expanded: boolean) => import("@emotion/react").SerializedStyles;

package/dist/components/Header/types.d.ts

@@ -0,0 +1,104 @@
+import { HTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { MapIconsType } from '../Icon/types';
+/**
+ * Header size. Sets the bar height — 64px, 84px or 92px — and the logo box.
+ */
+export type HeaderSize = 'small' | 'medium' | 'large';
+/**
+ * Header color scheme: white bar, or the dark graphite gradient.
+ */
+export type HeaderTheme = 'light' | 'dark';
+/**
+ * One entry of the Header navigation.
+ *
+ * A leaf item with a `path` renders as a router link. An item with `children`
+ * is a group: on desktop it opens a dropdown (hover with a mouse, tap on touch
+ * screens), in the mobile menu it expands in place. Groups nest two levels
+ * deep at most — the third level is not rendered.
+ *
+ * @example
+ * ```tsx
+ * const items: HeaderNavItem[] = [
+ *   { id: 'home', label: 'Home', path: '/' },
+ *   {
+ *     id: 'people',
+ *     label: 'People',
+ *     children: [
+ *       { id: 'employees', label: 'Employees', path: '/people/employees' },
+ *       { id: 'vacancies', label: 'Vacancies', path: '/people/vacancies' },
+ *     ],
+ *   },
+ * ];
+ * ```
+ */
+export interface HeaderNavItem {
+    /** Unique key of the item within its level */
+    id: string;
+    /** Visible label */
+    label: ReactNode;
+    /**
+     * Leading icon — a kit icon name, or an element rendered as-is. A string is
+     * always read as an icon name; wrap anything else (an emoji, text) in an
+     * element. Shown in the mobile menu and before the label on desktop.
+     */
+    icon?: keyof MapIconsType | ReactElement;
+    /**
+     * Route the item links to. Ignored on group items (those with `children`),
+     * which only open their submenu; a group is highlighted when any of its
+     * descendants matches the current location.
+     */
+    path?: string;
+    /** Renders the item greyed out and not interactive */
+    disabled?: boolean;
+    /** Submenu items; makes this item a group */
+    children?: HeaderNavItem[];
+}
+/**
+ * Props for the Header component.
+ *
+ * @example
+ * ```tsx
+ * <Header
+ *   logo={<img src="/logo.svg" alt="Acme" />}
+ *   items={items}
+ *   rightSide={<UserProfile {...profile} />}
+ * />
+ * ```
+ */
+export interface HeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    /**
+     * Project logo, placed in a box of fixed height. Leave it out and the box
+     * stays empty, so the layout does not shift between apps with and without
+     * a logo.
+     */
+    logo?: ReactNode;
+    /** Navigation items. Rendered centred; scrolls sideways when it overflows. */
+    items?: HeaderNavItem[];
+    /**
+     * Right-hand content — user profile, notifications, log out, whatever the
+     * app needs. Rendered as-is on every screen size.
+     */
+    rightSide?: ReactNode;
+    /**
+     * Color scheme of the bar and its menus. Named after the kit's other
+     * light/dark components (TreeView, CollapsibleNavBar) — not the Emotion
+     * theme.
+     * @default 'light'
+     */
+    theme?: HeaderTheme;
+    /**
+     * Bar height and logo size
+     * @default 'small'
+     */
+    size?: HeaderSize;
+    /**
+     * Accessible name of the navigation landmark
+     * @default 'Main'
+     */
+    navLabel?: string;
+    /**
+     * Accessible name of the burger button shown below 900px
+     * @default 'Open menu'
+     */
+    menuButtonLabel?: string;
+}

package/dist/components/index.d.ts

@@ -2,6 +2,8 @@ export { default as Button } from './Button';
 export type * from './Button/types';
 export * from './ButtonGroup';
 export * from './IconButton';
+export * from './FloatingActionButton';
+export type * from './FloatingActionButton/types';
 export * from './Breadcrumbs';
 export { default as Checkbox } from './Checkbox';
 export * from './Checkbox';
@@ -115,6 +117,8 @@ export type * from './ResponsiveImage/types';
 export { default as NavBar } from './NavBar';
 export * from './NavBar';
 export * from './CollapsibleNavBar';
+export * from './Header';
+export type * from './Header/types';
 export * from './TreeView';
 export { default as Tab } from './Tab';
 export { default as TabBar } from './TabBar';