@ntbjs/react-components 2.0.14 → 3.0.0-rc.2

package/types/components/widgets/AssetGallery/asset.types.d.ts

@@ -0,0 +1,329 @@
+import PropTypes from 'prop-types';
+import type { DragEvent, MouseEvent as ReactMouseEvent, ReactElement, ReactNode } from 'react';
+/**
+ * The asset contract — consumers build these objects rather than passing them as props.
+ *
+ * The interfaces are the source of truth; the propTypes at the bottom are legacy but still
+ * evaluated at runtime on React 16, so they cannot be deleted yet. Members marked `@recovered`
+ * were never declared by the propTypes but are read at runtime — grep `asset.<name>` before
+ * adding one, since a missing member becomes a compile error at the consumer's call site.
+ * `Asset` is meant to be extended (`interface MyAsset extends Asset { credit: string }`).
+ * The `AssetAction` interface here is unrelated to the `AssetAction` component in the widgets
+ * barrel; they never meet because this module is not re-exported there.
+ */
+/** Identity and React key; must be `string | number`. */
+export type AssetKey = string | number;
+/** Cards lowercase before checking; `renderMediaBadge` does not, causing inconsistency. */
+export type AssetFileType = 'image' | 'video' | 'pdf' | 'file' | 'audio';
+/**
+ * Declared corner for the file-type glyph.
+ *
+ * NOTHING IN THE LIBRARY READS THIS. It is part of the published propTypes and
+ * therefore part of the published API, so it is recorded rather than dropped —
+ * removing it is a deliberate API change and belongs in its own commit.
+ */
+export type AssetFileTypeIconPosition = 'top-left' | 'top-right';
+/** Usage-restriction level (1=info, 5=highly restricted); controls badge styling. */
+export type AssetInstructionSeverity = 1 | 2 | 3 | 4 | 5;
+/**
+ * Which of the two things a computed row entry is: a real asset card, or the
+ * group heading `AssetGalleryBase` synthesises above the first asset of a group.
+ */
+export type AssetLayoutType = 'groupLabel' | 'asset';
+/**
+ * How a note is styled on the compact card. `'error'` gets a red circle; every
+ * other value gets the neutral grey one, because
+ * `AssetGalleryCompactCard.styled` only ever tests `type === 'error'`.
+ *
+ * @recovered `AssetGalleryCompactCard.tsx` reads `asset?.note?.type`; the value
+ *   set comes from `AssetGallery.stories.tsx`.
+ */
+export type AssetNoteType = 'error' | 'warning' | 'info';
+/**
+ * A short note about the asset.
+ *
+ * THE propTypes AND THE RUNTIME DISAGREE ABOUT THIS SHAPE, and both halves are
+ * recorded because a consumer can reach both:
+ *
+ * - `title` and `type` are what `AssetGalleryCompactCard` actually reads (a
+ *   warning glyph, coloured by `type`) and what all three note stories pass.
+ * - `icon` and `message` are what the propTypes declared. No component in this
+ *   library reads either one.
+ *
+ * Deleting `icon`/`message` is an API removal and wiring them up is a feature;
+ * both are decisions for the per-component phase, not for a type-only commit.
+ * Until then this interface says what the field can contain.
+ */
+export interface AssetNote {
+    /** @recovered `AssetGalleryCompactCard.tsx` — presence is what gates the glyph. */
+    title?: string;
+    /** @recovered `AssetGalleryCompactCard.tsx` — `'error'` is the only value with its own styling. */
+    type?: AssetNoteType;
+    /** Declared by the propTypes, read by nothing. */
+    icon?: ReactElement<any>;
+    /** Declared by the propTypes, read by nothing. */
+    message?: string;
+}
+/**
+ * One entry in an action's dropdown, rendered as a `ContextMenuItem`.
+ *
+ * NOT THE SAME CALLBACK CONTRACT AS `AssetAction`. `AssetGalleryGridCard` wires
+ * `onClick` straight into `ContextMenuItem`'s `onClickEffect`, which becomes a
+ * DOM `onClick` — so a sub-action's handler receives the CLICK EVENT, while a
+ * top-level action's handler receives the ASSET. The asymmetry is real,
+ * pre-existing, and the reason this is a separate interface rather than
+ * `AssetAction[]`.
+ *
+ * @recovered `AssetGalleryGridCard.tsx` reads `action?.subActions`; the
+ *   propTypes never declared it.
+ */
+export interface AssetSubAction {
+    title: string;
+    icon: ReactElement<any>;
+    /** Receives the click event, NOT the asset. See above. */
+    onClick: (event: ReactMouseEvent<HTMLElement>) => void;
+}
+/**
+ * A button rendered over the asset thumbnail.
+ *
+ * `title`, `icon` and `onClick` are required — `PropTypes.*.isRequired`,
+ * verbatim — and `title` doubles as the tooltip text and as part of the React
+ * key, so two actions sharing a title collide.
+ */
+export interface AssetAction {
+    /** Tooltip text, and part of the action's React key. */
+    title: string;
+    icon: ReactElement<any>;
+    /**
+     * Called with the ASSET, not with the event: `AssetGalleryGridCard` stops the
+     * event itself and then calls `action.onClick(asset)`.
+     */
+    onClick: (asset: Asset) => void;
+    /**
+     * Forwarded to the underlying `ActionButton`'s `className`.
+     *
+     * WAS `PropTypes.shape` — the *uncalled* factory, not `PropTypes.shape({…})`.
+     * The fenced block at the end of this file records what that did.
+     */
+    className?: string;
+    /**
+     * Render the action yourself. Called with NO arguments and must return a valid
+     * element; the card then clones it with the computed props.
+     */
+    component?: () => ReactElement<any>;
+    /**
+     * `[width, height]` in px for the action button.
+     *
+     * @recovered `AssetGalleryGridCard.tsx` forwards `action.actionWidthHeight` to
+     *   `ComputedActionButton`. `AssetAction.tsx` declares it in its own
+     *   propTypes; `assetShape` never did.
+     */
+    actionWidthHeight?: [number, number];
+    /**
+     * Turns the action into a dropdown: a `ContextMenu` of `ContextMenuItem`s in a
+     * `Popover`, toggled by clicking the action.
+     *
+     * @recovered `AssetGalleryGridCard.tsx`.
+     */
+    subActions?: AssetSubAction[];
+}
+/**
+ * The hover-summary content, rendered by `AssetGalleryCompactCard` through
+ * `SummaryCard`, and used by `AssetGalleryGridCard` for its footer row.
+ *
+ * The four corner slots are `ReactNode`, so a fragment, a string or `null` all
+ * work — all three occur in `AssetGallery.stories.tsx`.
+ */
+export interface AssetSummary {
+    title?: string;
+    description?: string;
+    instructions?: string;
+    instructionSeverity?: AssetInstructionSeverity;
+    headerLeft?: ReactNode;
+    headerRight?: ReactNode;
+    /** Read by BOTH cards — the grid card renders it in `CardFooter` directly. */
+    footerLeft?: ReactNode;
+    /** Read by BOTH cards — the grid card renders it in `CardFooter` directly. */
+    footerRight?: ReactNode;
+}
+/**
+ * Where `AssetGalleryBase` decided to put this asset. Computed, never supplied:
+ * the gallery clones every asset with a `layout` before handing it to a card, so
+ * a consumer neither sets this nor sees it — except inside a `component(asset)`
+ * callback, which receives the cloned object.
+ *
+ * `width` / `height` / `translateX` / `translateY` are REQUIRED because that is
+ * what the propTypes said and what every `type: 'asset'` entry carries. The
+ * synthetic `type: 'groupLabel'` entries are built with no `width`, but they are
+ * consumed inside `AssetGalleryBase` itself and never reach a card — and a card
+ * is the only place `AssetWithLayout` is used. Do not make these optional to
+ * accommodate the group labels; give the group labels their own type when
+ * `AssetGalleryBase` is typed.
+ */
+export interface AssetLayout {
+    width: number;
+    height: number;
+    translateX: number;
+    translateY: number;
+    type: AssetLayoutType;
+    /** Whether the source asset declared both a width and a height. Compact view only. */
+    hasHeightAndWidth?: boolean;
+    /** Scroll-virtualisation flag: `false` unmounts the card. */
+    show?: boolean;
+}
+/**
+ * One asset in an `AssetGallery`.
+ *
+ * Every member except `key` and `fileType` is optional, which matches the
+ * propTypes exactly. Consumers are expected to EXTEND this rather than to match
+ * it exactly — see point 3 in the file header.
+ */
+export interface Asset {
+    /** Required. Identity, and the React key. */
+    key: AssetKey;
+    /** Required. Selects the preview branch — see {@link AssetFileType}. */
+    fileType: AssetFileType;
+    previewUrl?: string;
+    /** Card title and `<img alt>`. */
+    title?: string;
+    /** Pixel width; drives compact view row aspect ratio (falls back to 1920). */
+    width?: number;
+    /** Pixel height; drives compact view row aspect ratio (falls back to 1080). */
+    height?: number;
+    note?: AssetNote;
+    /** Consecutive assets sharing this get one heading row above the first. */
+    group?: string;
+    actions?: AssetAction[];
+    /** Top-right glyph on the thumbnail; suppresses the note glyph when set. */
+    statusIcon?: ReactElement<any>;
+    /** Rendered over everything else on the card; consumer owns positioning. */
+    overlay?: ReactElement<any>;
+    completed?: boolean;
+    hasError?: boolean;
+    /** Dims the card but does not prevent click handlers. */
+    disabled?: boolean;
+    fileTypeIconPosition?: AssetFileTypeIconPosition;
+    instructionSeverity?: AssetInstructionSeverity;
+    summary?: AssetSummary;
+    /** Called with event + asset; skipped in extended-select mode (click selects instead). */
+    onClick?: (event: ReactMouseEvent<HTMLElement>, asset: Asset) => void;
+    /** Called with event + asset after video preview starts playing. */
+    onMouseEnter?: (event: ReactMouseEvent<HTMLElement>, asset: Asset) => void;
+    /** Called with native event (not React event); card prevents default before calling. */
+    onContextMenu?: (event: MouseEvent) => void;
+    /** Duration in MILLISECONDS (not seconds). */
+    duration?: number;
+    /** Body text under title on grid card and summary card. */
+    description?: string;
+    /** Usage-restriction text; its presence gates InstructionSeverityDisplay. */
+    imageRights?: string;
+    /** Severity level → label map, e.g. `{ 1: 'Info', 5: 'Svært begrenset' }`. */
+    instructionLabels?: Record<string, string>;
+    /** Number of versions, shown in layers badge. */
+    versions?: number;
+    /** Pre-rendered verification badge (ReactNode, not string); consumer owns markup. */
+    verifications?: ReactNode;
+    /** Per-asset override of gallery's `selectable` prop; `false` here beats `true` there. */
+    selectable?: boolean;
+    /** Sets DOM `draggable` attribute on card root. */
+    draggable?: boolean;
+    /** Called with native drag event; pair with `draggable: true`. */
+    onDragstart?: (event: DragEvent) => void;
+}
+/**
+ * An asset as a CARD receives it — after `AssetGalleryBase` has computed its
+ * position. This is the type of `AssetGalleryGridCard`'s and
+ * `AssetGalleryCompactCard`'s `asset` prop; `Asset` is the type of the `assets`
+ * array a consumer hands to `AssetGallery`.
+ */
+export interface AssetWithLayout extends Asset {
+    layout: AssetLayout;
+}
+export declare const assetShape: {
+    key: PropTypes.Validator<NonNullable<NonNullable<string | number>>>;
+    previewUrl: PropTypes.Requireable<string>;
+    title: PropTypes.Requireable<string>;
+    note: PropTypes.Requireable<PropTypes.InferProps<{
+        icon: PropTypes.Requireable<PropTypes.ReactElementLike>;
+        message: PropTypes.Requireable<string>;
+    }>>;
+    width: PropTypes.Requireable<number>;
+    height: PropTypes.Requireable<number>;
+    fileType: PropTypes.Validator<string>;
+    fileTypeIconPosition: PropTypes.Requireable<string>;
+    group: PropTypes.Requireable<string>;
+    actions: PropTypes.Requireable<PropTypes.InferProps<{
+        title: PropTypes.Validator<string>;
+        icon: PropTypes.Validator<PropTypes.ReactElementLike>;
+        onClick: PropTypes.Validator<(...args: any[]) => any>;
+        className: PropTypes.Requireable<string>;
+        component: PropTypes.Requireable<(...args: any[]) => any>;
+    }>[]>;
+    statusIcon: PropTypes.Requireable<PropTypes.ReactElementLike>;
+    overlay: PropTypes.Requireable<PropTypes.ReactElementLike>;
+    completed: PropTypes.Requireable<boolean>;
+    hasError: PropTypes.Requireable<boolean>;
+    disabled: PropTypes.Requireable<boolean>;
+    onClick: PropTypes.Requireable<(...args: any[]) => any>;
+    onContextMenu: PropTypes.Requireable<(...args: any[]) => any>;
+    onMouseEnter: PropTypes.Requireable<(...args: any[]) => any>;
+    instructionSeverity: PropTypes.Requireable<number>;
+    summary: PropTypes.Requireable<PropTypes.InferProps<{
+        title: PropTypes.Requireable<string>;
+        description: PropTypes.Requireable<string>;
+        instructions: PropTypes.Requireable<string>;
+        instructionSeverity: PropTypes.Requireable<number>;
+        headerLeft: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        headerRight: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        footerLeft: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        footerRight: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    }>>;
+};
+export declare const assetShapeWithLayout: {
+    layout: PropTypes.Validator<NonNullable<PropTypes.InferProps<{
+        width: PropTypes.Validator<number>;
+        height: PropTypes.Validator<number>;
+        translateX: PropTypes.Validator<number>;
+        translateY: PropTypes.Validator<number>;
+        type: PropTypes.Validator<string>;
+        hasHeightAndWidth: PropTypes.Requireable<boolean>;
+    }>>>;
+    key: PropTypes.Validator<NonNullable<NonNullable<string | number>>>;
+    previewUrl: PropTypes.Requireable<string>;
+    title: PropTypes.Requireable<string>;
+    note: PropTypes.Requireable<PropTypes.InferProps<{
+        icon: PropTypes.Requireable<PropTypes.ReactElementLike>;
+        message: PropTypes.Requireable<string>;
+    }>>;
+    width: PropTypes.Requireable<number>;
+    height: PropTypes.Requireable<number>;
+    fileType: PropTypes.Validator<string>;
+    fileTypeIconPosition: PropTypes.Requireable<string>;
+    group: PropTypes.Requireable<string>;
+    actions: PropTypes.Requireable<PropTypes.InferProps<{
+        title: PropTypes.Validator<string>;
+        icon: PropTypes.Validator<PropTypes.ReactElementLike>;
+        onClick: PropTypes.Validator<(...args: any[]) => any>;
+        className: PropTypes.Requireable<string>;
+        component: PropTypes.Requireable<(...args: any[]) => any>;
+    }>[]>;
+    statusIcon: PropTypes.Requireable<PropTypes.ReactElementLike>;
+    overlay: PropTypes.Requireable<PropTypes.ReactElementLike>;
+    completed: PropTypes.Requireable<boolean>;
+    hasError: PropTypes.Requireable<boolean>;
+    disabled: PropTypes.Requireable<boolean>;
+    onClick: PropTypes.Requireable<(...args: any[]) => any>;
+    onContextMenu: PropTypes.Requireable<(...args: any[]) => any>;
+    onMouseEnter: PropTypes.Requireable<(...args: any[]) => any>;
+    instructionSeverity: PropTypes.Requireable<number>;
+    summary: PropTypes.Requireable<PropTypes.InferProps<{
+        title: PropTypes.Requireable<string>;
+        description: PropTypes.Requireable<string>;
+        instructions: PropTypes.Requireable<string>;
+        instructionSeverity: PropTypes.Requireable<number>;
+        headerLeft: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        headerRight: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        footerLeft: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        footerRight: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    }>>;
+};

package/types/components/widgets/AssetGallery/index.d.ts

@@ -0,0 +1 @@
+export { default } from './AssetGallery';

package/types/components/widgets/AssetPreview/AssetPreviewTopBar/AssetPreviewTopBar.d.ts

@@ -0,0 +1,60 @@
+import React from 'react';
+import * as S from './AssetPreviewTopBar.styled';
+type AssetPreviewTopBarOwnProps = {
+    /**
+     * On-click function for the back button
+     */
+    onBackButtonClick: (...args: any[]) => any;
+    /**
+     * Translatable text for the back button
+     */
+    backButtonText: string;
+    /**
+     * Disable the back button
+     */
+    disabled?: boolean;
+    /**
+     * Display the back button as an X instead of an arrow
+     */
+    backButtonAsClose?: boolean;
+    /**
+     * Text to be displayed grayed out after the "Back" text – e.g. "Asset selected" in gallery
+     */
+    leftText?: string;
+    /**
+     * Add a shadow on the bottom border of the top bar – e.g. in gallery view
+     */
+    shadow?: boolean;
+    /**
+     * Add a border on the bottom of the top bar
+     */
+    border?: boolean;
+    /**
+     * `Array` of buttons to be placed on the right side of the top bar
+     */
+    buttons?: React.ReactNode[];
+};
+/**
+ * Top bar for asset preview.
+ *
+ * ### Import
+ *
+ * ``` js
+ * import { AssetPreviewTopBar } from '@ntbjs/react-components/widgets'
+ * // or
+ * import AssetPreviewTopBar from '@ntbjs/react-components/AssetPreview/AssetPreviewTopBar'
+ * ```
+ *
+ * ### Usage example
+ *
+ * ``` js
+const button1 = <ActionButton key="btn1"icon={<IconAddCircle />} />;
+const button2 = <Button key="btn2" secondary={true}>Edit</Button>;
+const button3 = <Button key="btn3" secondary={true}>Share</Button>;
+const button4 = <Button key="btn4">Download</Button>;
+
+const topBar = <AssetPreviewTopBar backButtonText={t{"Back"}} onBackButtonClick={() => {}} buttons={[button1, button2, button3, button4]} />;
+ * ```
+ */
+declare const AssetPreviewTopBar: React.ForwardRefExoticComponent<Omit<Omit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, S.AssetPreviewTopBarStyleProps>, never>, "ref">, keyof AssetPreviewTopBarOwnProps> & AssetPreviewTopBarOwnProps & React.RefAttributes<any>>;
+export default AssetPreviewTopBar;

package/types/components/widgets/AssetPreview/AssetPreviewTopBar/AssetPreviewTopBar.styled.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `disabled` — greys out the back button. Not transient; present in baseline as bare boolean attribute.
+ */
+interface AssetPreviewTopBarDisabledStyleProps {
+    disabled?: boolean;
+}
+/**
+ * Props passed by `AssetPreviewTopBar.tsx` to `<S.AssetPreviewTopBar>`.
+ */
+export interface AssetPreviewTopBarStyleProps extends AssetPreviewTopBarDisabledStyleProps {
+    /** Swaps `border-bottom` between `1px solid` and `none`. */
+    $border?: boolean;
+    /** Shadow; evaluated as `props.$shadow && props.theme.themeProp(…)` to produce valid Interpolation. */
+    $shadow?: boolean;
+}
+export declare const AssetPreviewTopBar: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, AssetPreviewTopBarStyleProps>, never>> & string;
+export declare const BackButtonContainer: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, import("react").DetailedHTMLProps<import("react").AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>>, AssetPreviewTopBarDisabledStyleProps>, never>> & string;
+export declare const BackHoverEffect: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
+export declare const LeftText: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, never>, never>> & string;
+export declare const ButtonsContainer: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export {};

package/types/components/widgets/AssetPreview/AssetPreviewTopBar/index.d.ts

@@ -0,0 +1 @@
+export { default } from './AssetPreviewTopBar';

package/types/components/widgets/ContextMenu/ContextMenu.d.ts

@@ -0,0 +1,118 @@
+import React from 'react';
+type ContextMenuOwnProps = {
+    /**
+     * An array containing nodes of the `ContextMenuItem` component
+     */
+    children?: any;
+    /**
+     * Marks this menu as the sublevel/submenu of another context menu. This is a documented public prop that is currently a no-op; removing it is an API break.
+     */
+    sublevel?: boolean;
+};
+/**
+ * This component wraps around an array of `ContextMenuItems` to display a context menu.
+ *
+ * In most use-cases, the `ContextMenu` will be wrapped in a `Popover` to provide the functionality for opening/closing and placing the menu.
+ * In such cases, send the `ContextMenu` to the `Popover` as its `content` prop.
+ *
+ * The context menu and sublevels will automatically adjust their placement in relation to the element that opens it
+ * based on available space if the provided placement doesn't work. See the `Popover` documentation for further instructions on placement.
+ *
+ * ### Import
+ *
+ * ``` js
+ * import { ContextMenu } from '@ntbjs/react-components/widgets'
+ * // or
+ * import ContextMenu from '@ntbjs/react-components/widgets/ContextMenu'
+ * ```
+ *
+ * ### Usage examples
+ * #### Plain context menu
+ *
+ * ``` js
+
+const item1 = <ContextMenuItem title="Download" onClick={onClickEffect} key="item-1" />;
+const item2 = <ContextMenuItem title="Delete" icon={<IconDelete />} onClick={onClickEffect} key="item-2" />;
+
+<Popover content={<ContextMenu {...args}>{[item1, itemGroup1, item2]}</ContextMenu>} contextMenu={true}>
+  Click here to open
+</Popover>
+```
+ *
+ * #### Context menu with grouped items
+ * Use the `ContextMenuItemsGroup` component to group menu items together. Grouped items will not show borders
+ * between themselves, indicating that their actions are related.
+ *
+ * ``` js
+
+const item1 = <ContextMenuItem title="Download" onClick={onClickEffect} key="item-1" />;
+const item2 = <ContextMenuItem title="Delete" icon={<IconDelete />} onClick={onClickEffect} key="item-2" />;
+
+const groupItem1 = <ContextMenuItem title="Edit in Mediebank" icon={<IconDesignServices />} onClick={onClickEffect} key="group-item-1" />:
+const groupItem2 = <ContextMenuItem title="Edit in Photoshop" icon={<IconDesignServices />} onClick={onClickEffect} key="group-item-2" />;
+const groupItem3 = <ContextMenuItem title="Edit in Illustrator" icon={<IconDesignServices />} onClick={onClickEffect} key="group-item-3" />;
+
+const itemGroup1 = <ContextMenuItemsGroup key="item-group-1">{[groupItem1, groupItem2, groupItem3]}</ContextMenuItemsGroup>;
+
+<Popover content={<ContextMenu {...args}>{[item1, itemGroup1, item2]}</ContextMenu>} contextMenu={true}>
+  Click here to open
+</Popover>
+```
+ *
+ * #### Context menu with sublevels
+ * Wrap a `ContextMenuItem` in a `Popover` and pass it a `ContextMenu` as child to create a sublevel/submenu.
+ * A sublevel will by default be placed adjacent and aligned with the `ContextMenuItem` which opens it,
+ * and adjust automatically based on available space.
+ *
+ * Set the `contextMenu` and `contextMenuSublevel` props of the `Popover` containing the sublevel to `true`.
+ *
+ * Set the `opensSublevel` prop of the `ContextMenuItem` containing the sublevel to `true`.
+ *
+ * ``` js
+
+const item1 = <ContextMenuItem title="Download" onClick={onClickEffect} key="item-1" />;
+const item2 = <ContextMenuItem title="Delete" icon={<IconDelete />} onClick={onClickEffect} hoverBackgroundColors={['#fbeae6', '#fbeae6']} key="item-2" />;
+
+const subItem1 = <ContextMenuItem title="Edit in Mediebank" icon={<IconDesignServices />} onClick={onClickEffect} key="sub-item-1" />
+const subItem2 = <ContextMenuItem title="Edit in Photoshop" icon={<IconDesignServices />} onClick={onClickEffect} key="sub-item-2" />
+const subItem3 = <ContextMenuItem title="Edit in Illustrator" icon={<IconDesignServices />} onClick={onClickEffect} key="sub-item-3" />
+
+const itemWithSublevel = (
+  <Popover
+    content={
+      <ContextMenu sublevel={true}>
+        {[subItem1, subItem2, subItem3, subItem4, subItem5]}
+      </ContextMenu>
+    }
+    contextMenu={true}
+    contextMenuSublevel={true}
+    key="item-3"
+  >
+    <ContextMenuItem title="Open level 2" opensSublevel={true} />
+  </Popover>
+);
+
+<Popover content={<ContextMenu {...args}>{[item1, item2, itemWithSublevel]}</ContextMenu>} contextMenu={true}>
+  Click here to open
+</Popover>
+```
+ *
+ *
+ * #### Context menu from a dropdown button
+ * When used with a dropdown button, the `Button` component takes care of wrapping the menu items in a `Popover`.
+ * Just pass the array of `ContextMenuItems` directly into the `Button` as its children.
+ *
+ * ``` js
+
+const item1 = <ContextMenuItem title="Edit in Mediebank" icon={<IconDesignServices />} onClick={onClickEffect} key="item-1" />;
+const item2 = <ContextMenuItem title="Edit in Photoshop" icon={<IconDesignServices />} onClick={onClickEffect} key="item-2" />;
+const item3 = <ContextMenuItem title="Edit in Illustrator" icon={<IconDesignServices />} onClick={onClickEffect} key="item-3" />;
+
+<Button onClick={onClickEffect} dropdownItems={<ContextMenu {...args}>{[item1, item2, item3, item4, item5]}</ContextMenu>}>
+  Button text
+</Button>
+```
+ *
+ */
+declare const ContextMenu: React.ForwardRefExoticComponent<Omit<Omit<import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>, "ref">, keyof ContextMenuOwnProps> & ContextMenuOwnProps & React.RefAttributes<any>>;
+export default ContextMenu;

package/types/components/widgets/ContextMenu/ContextMenu.styled.d.ts

@@ -0,0 +1 @@
+export declare const ContextMenu: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;

package/types/components/widgets/ContextMenu/ContextMenuItem/ContextMenuItem.d.ts

@@ -0,0 +1,45 @@
+import React from 'react';
+import * as S from './ContextMenuItem.styled';
+type ContextMenuItemOwnProps = {
+    /**
+     * Menu item text
+     */
+    title: string;
+    /**
+     * Optional icon (left side)
+     */
+    icon?: React.ReactElement<any>;
+    /**
+     * Function to trigger when the item is clicked
+     */
+    onClickEffect?: (...args: any[]) => any;
+    /**
+     * Whether the `ContextMenuItem` opens another `ContextMenu`
+     */
+    opensSublevel?: boolean;
+    /**
+     * Array of custom hover text/icon color in the form of hex-strings (e.g. `'#FFFFFF'`).
+     * Must contain two colors, where the first is for dark-mode and the second is for light-mode.
+     */
+    hoverColors?: string[];
+    /**
+     * Array of custom hover background colors in the form of hex-strings (e.g. `'#FFFFFF'`).
+     * Must contain two colors, where the first is for dark-mode and the second is for light-mode.
+     */
+    hoverBackgroundColors?: string[];
+};
+/**
+ * Single context menu item.
+ *
+ * See the documentation for `ContextMenu` for usage examples.
+ *
+ * ### Import
+ *
+ * ``` js
+ * import { ContextMenuItem } from '@ntbjs/react-components/widgets/ContextMenu'
+ * // or
+ * import ContextMenuItem from '@ntbjs/react-components/widgets/ContextMenu/ContextMenuItem'
+ * ```
+ */
+declare const ContextMenuItem: React.ForwardRefExoticComponent<Omit<Omit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, S.ContextMenuItemStyleProps>, never>, "ref">, keyof ContextMenuItemOwnProps> & ContextMenuItemOwnProps & React.RefAttributes<any>>;
+export default ContextMenuItem;

package/types/components/widgets/ContextMenu/ContextMenuItem/ContextMenuItem.styled.d.ts

@@ -0,0 +1,18 @@
+import type { ReactElement } from 'react';
+/**
+ * Props passed by `ContextMenuItem.tsx` to `<S.ContextMenuItem>`.
+ */
+export interface ContextMenuItemStyleProps {
+    /** React element, read for presence only. */
+    $icon?: ReactElement<any>;
+    /** Selects right-hand padding (sublevel items have their own chevron). */
+    $openssublevel?: boolean;
+    /** `[darkModeColor, lightModeColor]` hex strings. */
+    $hoverColors?: string[];
+    /** Same shape as `$hoverColors`. */
+    $hoverBackgroundColors?: string[];
+}
+export declare const ContextMenuItem: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, ContextMenuItemStyleProps>, never>> & string;
+export declare const IconContainer: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, never>, never>> & string;
+export declare const SublevelIconContainer: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, never>, never>> & string;
+export declare const Label: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, never>> & string;

package/types/components/widgets/ContextMenu/ContextMenuItem/index.d.ts

@@ -0,0 +1 @@
+export { default } from './ContextMenuItem';

package/types/components/widgets/ContextMenu/ContextMenuItemsGroup/ContextMenuItemsGroup.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+type ContextMenuItemsGroupOwnProps = {
+    /**
+     * Nodes of the `ContextMenuItem` component — one, or an array.
+     */
+    children?: React.ReactNode;
+};
+/**
+ * Simple wrapper for a group of context menu items. These will be displayed without a border between each item.
+ *
+ * See the documentation for `ContextMenu` for an example.
+ *
+ * ### Import
+ *
+ * ``` js
+ * import { ContextMenuItemsGroup } from '@ntbjs/react-components/widgets/ContextMenu'
+ * // or
+ * import ContextMenuItemsGroup from '@ntbjs/react-components/widgets/ContextMenu/ContextMenuItemsGroup'
+ * ```
+ *
+ */
+declare const ContextMenuItemsGroup: React.ForwardRefExoticComponent<Omit<Omit<import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>, "ref">, "children"> & ContextMenuItemsGroupOwnProps & React.RefAttributes<any>>;
+export default ContextMenuItemsGroup;

package/types/components/widgets/ContextMenu/ContextMenuItemsGroup/ContextMenuItemsGroup.styled.d.ts

@@ -0,0 +1 @@
+export declare const ContextMenuItemsGroup: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;

package/types/components/widgets/ContextMenu/ContextMenuItemsGroup/index.d.ts

@@ -0,0 +1 @@
+export { default } from './ContextMenuItemsGroup';

package/types/components/widgets/ContextMenu/index.d.ts

@@ -0,0 +1 @@
+export { default } from './ContextMenu';