@foris/avocado-suite 1.10.2 → 1.11.0

package/dist/components/donut/Donut.d.ts

@@ -1,18 +1,45 @@
-import { FC } from 'react';
-export interface IDonutItem {
-    name: string;
-    percentage: number;
-    value: number;
-}
+import { type FC, type ReactNode } from 'react';
+import { type DonutCenterMode, type DonutSegment, type DonutSize, type IDonutItem } from './donut.util';
 export interface DonutProps {
-    /** overwrite className */
+    /** Overwrite className */
     className?: string;
-    /** data */
-    data: IDonutItem[];
-    /** height */
-    height?: string;
-    /** width */
+    /** Slices of the ring; proportions come from `value`. */
+    segments?: DonutSegment[];
+    /** @deprecated Use `segments`. Proportions come from `percentage`, as in the SVG Donut. */
+    data?: IDonutItem[];
+    /** Ring diameter: `xs` 40, `sm` 56, `md` 96, `lg` 160 px, or `auto` to fill the parent. @default 'sm' */
+    size?: DonutSize;
+    /** Show the content inside the hole. @default true, false with legacy props */
+    showCenter?: boolean;
+    /** Custom center content; replaces `centerValue` and `centerLabel`. */
+    children?: ReactNode;
+    /**
+     * `fixed` shows `centerValue` (or the first segment share); `activeSegment` shows the hovered
+     * slice label and falls back to `centerValue`, so without it the center is empty until hover.
+     * @default 'activeSegment' from 160 px, 'fixed' below
+     */
+    centerMode?: DonutCenterMode;
+    /** Main center text, e.g. a total. */
+    centerValue?: string;
+    /** Secondary text below `centerValue`. */
+    centerLabel?: string;
+    /** Enable hover on the slices. @default true from 160 px, false below */
+    interactive?: boolean;
+    /** Show the hovered slice value and share outside the ring. Requires `interactive`. @default true from 160 px */
+    showCallout?: boolean;
+    /** Chart adapters only: Recharts nodes rendered inside the PieChart (e.g. Legend). */
+    chartChildren?: ReactNode;
+    /** Chart adapters only: slice highlighted before user interaction. */
+    defaultIndex?: number;
+    /** Chart adapters only: caps `size="auto"`. */
+    autoMaxDiameter?: number;
+    /** Chart adapters only: height reserved below the ring when `size="auto"`. */
+    autoLegendReserve?: number;
+    /** @deprecated Use `size`. Without `size`: px maps to a diameter, relative values to `'auto'`, none to 300 px. */
     width?: string;
+    /** @deprecated Use `size`. See `width`. */
+    height?: string;
 }
 declare const Donut: FC<DonutProps>;
 export default Donut;
+export type { DonutSegment, DonutSize, DonutCenterMode, IDonutItem, } from './donut.util';

package/dist/components/donut/Donut.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/donut/donut-labels/DonutLabels.d.ts

@@ -1,5 +1,5 @@
 import { FC } from 'react';
-import { IDonutItem } from '../Donut';
+import { type IDonutItem } from '../donut.util';
 export interface DonutLabelsProps {
     /** overwrite className */
     className?: string;

package/dist/components/donut/donut-legend/DonutLegend.d.ts

@@ -1,5 +1,5 @@
 import { FC } from 'react';
-import { IDonutItem } from '../Donut';
+import { type IDonutItem } from '../donut.util';
 export interface DonutLegendProps {
     /** overwrite className */
     className?: string;

package/dist/components/donut/donut.util.d.ts

@@ -0,0 +1,58 @@
+import type { Color } from '../../../../avocado-icons';
+export declare const DONUT_PALETTE: `${Color}`[];
+/** Colors of the SVG Donut (core `$donutColors`), kept for the deprecated `data` API. */
+export declare const LEGACY_DONUT_COLORS: `${Color}`[];
+export declare const DONUT_ANALYTIC_THRESHOLD = 160;
+export declare const ACTIVE_CENTER_MAX_FONT_SIZE = 14;
+/** Size of the legacy SVG Donut when no dimension was passed. */
+export declare const LEGACY_DONUT_DIAMETER = 300;
+export declare const DONUT_SIZE_MAP: {
+    readonly xs: 40;
+    readonly sm: 56;
+    readonly md: 96;
+    readonly lg: 160;
+};
+export type DonutSize = keyof typeof DONUT_SIZE_MAP | 'auto';
+export type DonutCenterMode = 'fixed' | 'activeSegment';
+export interface DonutSegment {
+    label: string;
+    value: number;
+    /** Design-system color name, e.g. `'success-50'`. Defaults to the palette by index. */
+    color?: `${Color}`;
+}
+/** Item consumed by `DonutLegend` and `DonutLabels`. */
+export interface IDonutItem {
+    name: string;
+    percentage: number;
+    value: number;
+    /** Design-system color name. Defaults to the legacy SVG Donut colors by index. */
+    color?: `${Color}`;
+}
+interface DonutBehavior {
+    interactive: boolean;
+    showCallout: boolean;
+    centerMode: DonutCenterMode;
+}
+interface DonutLayout {
+    containerSize: number;
+    innerRadius: number;
+    outerRadius: number;
+}
+export declare const toColorVar: (color: `${Color}`) => string;
+export declare const getSegmentColor: ({ color }: DonutSegment, index: number) => `${Color}`;
+export declare const getDonutItemColor: ({ color }: IDonutItem, index: number) => `${Color}`;
+export declare const resolveAutoDiameter: (width: number, height: number, { maxDiameter, legendReserve }?: {
+    maxDiameter?: number | undefined;
+    legendReserve?: number | undefined;
+}) => number;
+export declare const resolveLegacySize: (width?: string, height?: string) => DonutSize | number;
+export declare const fromLegacyData: (data: IDonutItem[]) => DonutSegment[];
+export declare const resolveDonutDiameter: (size: DonutSize | number, autoDiameter?: number) => number;
+export declare const getDonutLayout: (diameter: number, showCallout: boolean) => DonutLayout;
+export declare const getCenterFontSize: (diameter: number, innerDiameter: number, centerMode: DonutCenterMode) => number;
+export declare const getDatumPercent: (datum: DonutSegment, segments: DonutSegment[]) => number;
+export declare const resolveDonutBehavior: (analytic: boolean, overrides?: Partial<DonutBehavior>) => DonutBehavior;
+/** Maps `segments` to the items of `DonutLegend` and `DonutLabels`, keeping the ring colors. */
+export declare const toDonutLegendItems: (segments: DonutSegment[]) => IDonutItem[];
+export declare const getDonutAriaLabel: (segments: DonutSegment[], centerText?: string) => string;
+export {};

package/dist/components/donut/donut.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/header-navigation/HeaderNavigation.d.ts

@@ -14,6 +14,19 @@ export type HeaderNavigationVisual = {
     src: string;
     alt: string;
 };
+/** Solid preset, or a decorative photo with a fixed contrast overlay shape. */
+export type HeaderNavigationImageBackground = {
+    type: 'image';
+    src: string;
+    /**
+     * CSS color for the tinted overlay gradient (`rgb()`, `hsl()`, hex, or
+     * `var(--color-*)`). When omitted, the packaged brand gradient on
+     * `web-cyan-100` is used. Also paints the header surface when the photograph
+     * is loading or fails.
+     */
+    overlayColor?: string;
+};
+export type HeaderNavigationBackground = 'default' | 'brand' | HeaderNavigationImageBackground;
 /** Reusable page navigation, with content and actions supplied by its host. */
 export interface HeaderNavigationProps extends HTMLAttributes<HTMLElement> {
     /** Page title, rendered as the primary heading. */
@@ -28,8 +41,8 @@ export interface HeaderNavigationProps extends HTMLAttributes<HTMLElement> {
     menuLabel?: string;
     /** Disables the overflow trigger. */
     menuDisabled?: boolean;
-    /** Gray by default; brand selects the Figma blue in either theme. */
-    background?: 'default' | 'brand';
+    /** Gray by default, brand blue, or a full-bleed hero photograph. */
+    background?: HeaderNavigationBackground;
     /** Optional leading icon or image. */
     leadingVisual?: HeaderNavigationVisual;
     /** Displays the packaged pattern when true, or a caller-provided pattern URL. */

package/dist/components/header-navigation/index.d.ts

@@ -1,2 +1,2 @@
 export { default } from './HeaderNavigation';
-export type { HeaderNavigationProps, HeaderNavigationVisual, } from './HeaderNavigation';
+export type { HeaderNavigationBackground, HeaderNavigationImageBackground, HeaderNavigationProps, HeaderNavigationVisual, } from './HeaderNavigation';

package/dist/components/matrix-table/MatrixTable.d.ts

@@ -0,0 +1,76 @@
+import type { HTMLAttributes, Key, ReactElement, ReactNode, RefAttributes } from 'react';
+/** Supported pinning edge, relative to the document direction. */
+export type MatrixTablePinnedSide = 'start';
+/**
+ * Inline alignment of a column's header and body cells. Logical, so `start` and
+ * `end` follow the document direction. Narrow numeric columns want `center`.
+ */
+export type MatrixTableAlign = 'start' | 'center' | 'end';
+/** What a group column and a detail column declare in common. */
+interface MatrixTableColumnBase {
+    /** Stable identity, unique across both groupColumns and columns. */
+    key: string;
+    /** Content of the column header. */
+    header: ReactNode;
+    /** Declared width in px. Applied to the `col`, the header cell and the body cell. */
+    width: number;
+    /**
+     * Pins the column at the logical start. Only a contiguous prefix of
+     * `groupColumns` followed by `columns` can be pinned; a later marker is
+     * ignored and warned about in development.
+     */
+    pinned?: MatrixTablePinnedSide;
+    /**
+     * Alignment of this column's header and body cells. Defaults to the matrix
+     * defaults: `center` for detail columns, whose values are short and read as a
+     * grid, and `start` for group columns, which hold blocks of text.
+     */
+    align?: MatrixTableAlign;
+    /** Class added to this column's header and body cells; modifiers may take precedence. */
+    className?: string;
+}
+/** A column whose single cell spans every detail row of its group. */
+export interface MatrixTableGroupColumn<TGroup> extends MatrixTableColumnBase {
+    /** Receives its own definition too, so one factory can serve many columns. */
+    renderGroupCell: (group: TGroup, column: MatrixTableGroupColumn<TGroup>) => ReactNode;
+}
+/** A column that renders one cell per detail row. */
+export interface MatrixTableColumn<TGroup, TRow> extends MatrixTableColumnBase {
+    /**
+     * Receives the row, its group and the column itself. The third argument is
+     * what lets a shared handler build a full payload — which row, which group,
+     * which column — without a closure per column.
+     */
+    renderCell: (row: TRow, group: TGroup, column: MatrixTableColumn<TGroup, TRow>) => ReactNode;
+    /**
+     * Renders the cell as the row's header (`th scope="row"`). Opt in for the
+     * value that names the row — a component name, a code — not for data.
+     */
+    isRowHeader?: boolean;
+}
+/** Grouped matrix data and native attributes applied to the root div. */
+export interface MatrixTableProps<TGroup, TRow> extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML'> {
+    /** Consumer-owned group data. Never mutated, never copied into state. */
+    groups: readonly TGroup[];
+    /** Columns rendered once per group, spanning its detail rows. */
+    groupColumns: readonly MatrixTableGroupColumn<TGroup>[];
+    /** Columns rendered once per detail row. The scrolling matrix axis. */
+    columns: readonly MatrixTableColumn<TGroup, TRow>[];
+    /** Stable identity, unique within groups. */
+    getGroupKey: (group: TGroup) => Key;
+    /** Detail rows belonging to a group; an empty collection is supported. */
+    getRows: (group: TGroup) => readonly TRow[];
+    /** Stable detail-row identity, unique within its group. */
+    getRowKey: (row: TRow, group: TGroup) => Key;
+    /** Accessible name of the table and of its scroll region. Required. */
+    accessibleLabel: string;
+    /** Content of a spanning body cell when groups is empty. */
+    emptyContent?: ReactNode;
+    /** Exposed as `aria-busy`. The component ships no loader and no copy. */
+    isBusy?: boolean;
+    /** Class added to the root div alongside the component's own class. */
+    className?: string;
+}
+/** A grouped matrix table; ref and native div attributes target the root container. */
+declare const MatrixTable: <TGroup, TRow>(props: MatrixTableProps<TGroup, TRow> & RefAttributes<HTMLDivElement>) => ReactElement;
+export default MatrixTable;

package/dist/components/matrix-table/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './MatrixTable';
+export type { MatrixTableAlign, MatrixTableColumn, MatrixTableGroupColumn, MatrixTablePinnedSide, MatrixTableProps, } from './MatrixTable';

package/dist/index.d.ts

@@ -25,6 +25,7 @@ import DropdownButton from './components/dropdown-button/DropdownButton';
 import Heading from './components/heading/Heading';
 import Link from './components/link/Link';
 import Loading from './components/loading/Loading';
+import MatrixTable from './components/matrix-table';
 import Menu from './components/menu/Menu';
 import Modal from './components/modal/Modal';
 import Pager from './components/pager/Pager';
@@ -67,7 +68,7 @@ import { toast } from 'react-toastify';
  * Hooks
  */
 export { useFloatingPortal } from './hooks/useFloatingPortal';
-export { Banner, Beacon, Header, HeaderNavigation, ContextualNavigation, Hotspot, NavList, Drawer, AccessPanel, AccountMenu, SidebarMenu, Weekly, WeeklyGroup, Accordion, Box, Breadcrumbs, Button, Card, CardAccordion, CardNotification, Checkbox, DataCard, DataTable, DatePicker, Divider, Dropzone, FileUpload, Donut, DonutLabels, DonutLegend, DropdownButton, Heading, Link, Loading, Menu, Modal, Pager, Pill, PreviewerMarkdown, Processing, ProgressBar, RadioButton, RoundButton, Select, SelectPagination, SkeletonBase, SkeletonCircle, Stepper, Switch, Tabs, Tag, Text, TextField, Textarea, ThemeProvider, ThemeStore, LocaleStore, Timer, Toaster, Tooltip, Table, toast, };
+export { Banner, Beacon, Header, HeaderNavigation, ContextualNavigation, Hotspot, NavList, Drawer, AccessPanel, AccountMenu, SidebarMenu, Weekly, WeeklyGroup, Accordion, Box, Breadcrumbs, Button, Card, CardAccordion, CardNotification, Checkbox, DataCard, DataTable, DatePicker, Divider, Dropzone, FileUpload, Donut, DonutLabels, DonutLegend, DropdownButton, Heading, Link, Loading, MatrixTable, Menu, Modal, Pager, Pill, PreviewerMarkdown, Processing, ProgressBar, RadioButton, RoundButton, Select, SelectPagination, SkeletonBase, SkeletonCircle, Stepper, Switch, Tabs, Tag, Text, TextField, Textarea, ThemeProvider, ThemeStore, LocaleStore, Timer, Toaster, Tooltip, Table, toast, };
 /**
  * Types
  */
@@ -81,10 +82,13 @@ export type { DataCardProps, DataCardV1Props, DataCardV1Variant, DataCardV2Props
 export type { DividerProps } from './components/divider/Divider';
 export type { DropzoneDisplay, DropzoneProps, DropzoneUploadStatus, } from './components/dropzone/Dropzone';
 export type { FileUploadProps } from './components/file-upload/FileUpload';
+export type { DonutProps, DonutSegment, DonutSize, DonutCenterMode, IDonutItem, } from './components/donut/Donut';
+export { toDonutLegendItems } from './components/donut/donut.util';
 export type { HeadingProps } from './components/heading/Heading';
-export type { HeaderNavigationProps, HeaderNavigationVisual, } from './components/header-navigation';
+export type { HeaderNavigationBackground, HeaderNavigationImageBackground, HeaderNavigationProps, HeaderNavigationVisual, } from './components/header-navigation';
 export type { ContextualNavigationProps, ContextualNavigationItem, } from './components/contextual-navigation';
 export type { LinkProps } from './components/link/Link';
+export type { MatrixTableAlign, MatrixTableColumn, MatrixTableGroupColumn, MatrixTablePinnedSide, MatrixTableProps, } from './components/matrix-table';
 export type { MenuItem } from './types/menu.types';
 export type { RoundButtonProps } from './components/round-button/RoundButton';
 export type { SelectProps } from './components/select/Select';