@drivenets/design-system 0.18.1 → 0.20.0

package/src/components/ds-main-menu/ds-main-menu.utils.ts

@@ -0,0 +1,40 @@
+import type { KeyboardEvent, MouseEvent } from 'react';
+import type { DsMainMenuItem, DsMainMenuProps } from './ds-main-menu.types';
+
+export const isNonActivatable = (state: DsMainMenuItem['state']) =>
+	state === 'disabled' || state === 'comingSoon';
+
+export const handleActivatableClick = (
+	event: MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
+	id: string,
+	href: string | undefined,
+	onItemSelect: DsMainMenuProps['onItemSelect'],
+	onClose: () => void,
+) => {
+	if (!href) {
+		event.preventDefault();
+	}
+
+	onItemSelect?.(id);
+	onClose();
+};
+
+export const handleActivatableKeyDown = (
+	event: KeyboardEvent<HTMLAnchorElement | HTMLButtonElement>,
+	id: string,
+	href: string | undefined,
+	onItemSelect: DsMainMenuProps['onItemSelect'],
+	onClose: () => void,
+) => {
+	if (event.key !== 'Enter' && event.key !== ' ') {
+		return;
+	}
+
+	event.preventDefault();
+	onItemSelect?.(id);
+	onClose();
+
+	if (href) {
+		(event.currentTarget as HTMLAnchorElement).click();
+	}
+};

package/src/components/ds-main-menu/index.ts

@@ -0,0 +1,9 @@
+export { default as DsMainMenu } from './ds-main-menu';
+export type {
+	DsMainMenuItem,
+	DsMainMenuItemState,
+	DsMainMenuProps,
+	DsMainMenuUtilityLink,
+	DsMainMenuVariant,
+} from './ds-main-menu.types';
+export { COMING_SOON_TOOLTIP, mainMenuItemStates, mainMenuVariants } from './ds-main-menu.types';

package/src/components/ds-modal/figma/ds-modal-footer.figma.ts

@@ -1,4 +1,4 @@
-// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=32014-16402
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=43101-8753
 // source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-modal
 // component=DsModal.Footer
 //

package/src/components/ds-pin-toggle/ds-pin-toggle.figma.ts

@@ -0,0 +1,27 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=42863-16495
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-pin-toggle
+// component=DsPinToggle
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+// `Part_PinnedIcon` is a `Part_*` node, which we normally do not mirror. It is
+// mapped here because, unlike `Part_CheckboxBtnV3`, it has a real exported
+// counterpart in code — the rule exists to stop us inventing components for
+// markup, not to hide ones that exist.
+const active = instance.getEnum('active', {
+	true: 'true',
+	false: 'false',
+});
+
+// `itemLabel` has no Figma source — the pin carries no text, and the name it
+// needs comes from the row it sits in. The snippet emits a placeholder so the
+// required prop is visible rather than silently missing.
+const attrs = ['itemLabel="Label"', active === 'true' ? 'pinned' : ''].filter(Boolean).join(' ');
+
+export default {
+	example: figma.code`<DsPinToggle ${attrs} />`,
+	imports: ["import { DsPinToggle } from '@drivenets/design-system';"],
+	id: 'ds-pin-toggle',
+	metadata: { nestable: true },
+} satisfies figma.Template;

package/src/components/ds-pin-toggle/ds-pin-toggle.module.scss

@@ -0,0 +1,41 @@
+$pin-border-radius: 2px;
+$pin-focus-ring-width: 2px;
+$transition-duration: 0.2s;
+
+.root {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	flex-shrink: 0;
+	margin: 0;
+	padding: var(--4xs);
+	border: none;
+	border-radius: $pin-border-radius;
+	background-color: transparent;
+	line-height: 0;
+	color: var(--icon-tertiary);
+	cursor: pointer;
+	transition: color $transition-duration ease-in-out;
+
+	&:not(:disabled):hover {
+		color: var(--icon-secondary);
+	}
+
+	&[aria-pressed='true'] {
+		color: var(--icon-action);
+
+		&:not(:disabled):hover {
+			color: var(--icon-action-hover);
+		}
+	}
+
+	&:focus-visible {
+		outline: $pin-focus-ring-width solid var(--border-action-primary);
+		outline-offset: 0;
+	}
+
+	&:disabled {
+		color: var(--icon-disabled);
+		cursor: not-allowed;
+	}
+}

package/src/components/ds-pin-toggle/ds-pin-toggle.tsx

@@ -0,0 +1,43 @@
+import classNames from 'classnames';
+import styles from './ds-pin-toggle.module.scss';
+import type { DsPinToggleProps } from './ds-pin-toggle.types';
+import { DsIcon } from '../ds-icon';
+
+const DEFAULT_LOCALE = Object.freeze({ pin: 'Pin' });
+
+/**
+ * Bare pushpin for "keep this at the top" affordances.
+ */
+const DsPinToggle = ({
+	ref,
+	className,
+	style,
+	itemLabel,
+	pinned = false,
+	disabled = false,
+	locale,
+	onPinnedChange,
+	onClick,
+	...rest
+}: DsPinToggleProps) => (
+	<button
+		{...rest}
+		ref={ref}
+		type="button"
+		disabled={disabled}
+		aria-pressed={pinned}
+		aria-label={`${locale?.pin ?? DEFAULT_LOCALE.pin} ${itemLabel}`}
+		className={classNames(styles.root, className)}
+		style={style}
+		onClick={(event) => {
+			onClick?.(event);
+			onPinnedChange?.(!pinned);
+		}}
+	>
+		<DsIcon icon="keep" size="tiny" variant="rounded" filled aria-hidden />
+	</button>
+);
+
+DsPinToggle.displayName = 'DsPinToggle';
+
+export default DsPinToggle;

package/src/components/ds-pin-toggle/ds-pin-toggle.types.ts

@@ -0,0 +1,29 @@
+import type { ButtonHTMLAttributes, Ref } from 'react';
+
+export interface DsPinToggleProps extends Omit<
+	ButtonHTMLAttributes<HTMLButtonElement>,
+	'aria-label' | 'aria-labelledby' | 'aria-pressed' | 'children' | 'type'
+> {
+	ref?: Ref<HTMLButtonElement>;
+
+	itemLabel: string;
+
+	/**
+	 * @default false
+	 */
+	pinned?: boolean;
+
+	/**
+	 * @default false
+	 */
+	disabled?: boolean;
+
+	locale?: {
+		/**
+		 * @default 'Pin'
+		 */
+		pin?: string;
+	};
+
+	onPinnedChange?: (pinned: boolean) => void;
+}

package/src/components/ds-pin-toggle/index.ts

@@ -0,0 +1,2 @@
+export { default as DsPinToggle } from './ds-pin-toggle';
+export * from './ds-pin-toggle.types';

package/src/components/ds-popover/components/popover-trigger/index.ts

@@ -0,0 +1 @@
+export { PopoverTrigger } from './popover-trigger';

package/src/components/ds-popover/components/popover-trigger/popover-trigger.tsx

@@ -0,0 +1,15 @@
+import { Popover } from '@ark-ui/react/popover';
+import { useHoverTriggerProps } from '../../ds-popover.hover-intent';
+import type { DsPopoverTriggerProps } from '../../ds-popover.types';
+
+export const PopoverTrigger = ({ children, className }: DsPopoverTriggerProps) => {
+	const hoverProps = useHoverTriggerProps();
+
+	return (
+		<Popover.Trigger asChild className={className} {...hoverProps}>
+			{children}
+		</Popover.Trigger>
+	);
+};
+
+PopoverTrigger.displayName = 'DsPopover.Trigger';

package/src/components/ds-popover/ds-popover.context.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+import type { HoverIntent } from './ds-popover.hover-intent';
+
+export interface DsPopoverContextValue {
+	matchAnchorWidth: boolean;
+	registerAnchor: (el: HTMLElement | null) => void;
+	registerContentId: (id: string | undefined) => void;
+	hoverIntent: HoverIntent | null;
+}
+
+export const DsPopoverContext = createContext<DsPopoverContextValue>({
+	matchAnchorWidth: false,
+	registerAnchor: () => undefined,
+	registerContentId: () => undefined,
+	hoverIntent: null,
+});
+
+export const useDsPopoverContext = () => useContext(DsPopoverContext);

package/src/components/ds-popover/ds-popover.hover-intent.ts

@@ -0,0 +1,65 @@
+import type { FocusEvent, PointerEvent } from 'react';
+import { usePopoverContext } from '@ark-ui/react/popover';
+import { useDsPopoverContext } from './ds-popover.context';
+import { isHoverPointer } from './ds-popover.utils';
+
+export const DEFAULT_OPEN_DELAY_MS = 200;
+export const DEFAULT_CLOSE_DELAY_MS = 150;
+
+export interface HoverIntent {
+	openDelay: number;
+	closeDelay: number;
+	setFocusInPanel: (inPanel: boolean) => void;
+	/** True once if the trigger is about to be re-focused by Ark's close-time restore. */
+	consumeFocusRestore: () => boolean;
+	/** Owns one shared timer */
+	schedule: (action: () => void, delay: number) => void;
+}
+
+const useHoverIntent = () => useDsPopoverContext().hoverIntent;
+
+export const useHoverIntentProps = () => {
+	const intent = useHoverIntent();
+	const { setOpen } = usePopoverContext();
+
+	if (!intent) {
+		return undefined;
+	}
+
+	const onPointerIntent = (event: PointerEvent, open: boolean, delay: number) => {
+		if (!isHoverPointer(event.pointerType)) {
+			return;
+		}
+
+		intent.schedule(() => setOpen(open), delay);
+	};
+
+	return {
+		onPointerEnter: (event: PointerEvent) => onPointerIntent(event, true, intent.openDelay),
+		onPointerLeave: (event: PointerEvent) => onPointerIntent(event, false, intent.closeDelay),
+	};
+};
+
+export const useHoverTriggerProps = () => {
+	const pointerProps = useHoverIntentProps();
+	const intent = useHoverIntent();
+	const { setOpen } = usePopoverContext();
+
+	if (!intent) {
+		return undefined;
+	}
+
+	return {
+		...pointerProps,
+		onFocus: (event: FocusEvent<HTMLElement>) => {
+			// Closing with focus inside the panel makes Ark re-focus the trigger
+			if (intent.consumeFocusRestore()) {
+				return;
+			}
+
+			if (event.target.matches(':focus-visible')) {
+				setOpen(true);
+			}
+		},
+	};
+};

package/src/components/ds-popover/ds-popover.tsx

@@ -1,11 +1,20 @@
-import { Popover } from '@ark-ui/react/popover';
+import { useEffect, useLayoutEffect, useRef, useState, type FocusEvent } from 'react';
+import { Popover, type PopoverRootProps } from '@ark-ui/react/popover';
 import { Portal } from '@ark-ui/react/portal';
 import classNames from 'classnames';
 import { DsStack } from '../ds-stack';
 import { DsTypography } from '../ds-typography';
+import { PopoverTrigger } from './components/popover-trigger';
+import { DsPopoverContext, useDsPopoverContext } from './ds-popover.context';
+import {
+	DEFAULT_CLOSE_DELAY_MS,
+	DEFAULT_OPEN_DELAY_MS,
+	useHoverIntentProps,
+} from './ds-popover.hover-intent';
+import { invokeCloseAutoFocus, toFocusEl, toPlacement } from './ds-popover.utils';
 import styles from './ds-popover.module.scss';
 import type {
-	DsPopoverAlign,
+	DsPopoverAnchorProps,
 	DsPopoverContentItemProps,
 	DsPopoverContentProps,
 	DsPopoverFooterProps,
@@ -13,14 +22,10 @@ import type {
 	DsPopoverPanelProps,
 	DsPopoverProps,
 	DsPopoverRootProps,
-	DsPopoverSide,
-	DsPopoverTriggerProps,
 } from './ds-popover.types';
 
 const DEFAULT_PANEL_WIDTH = 400;
-
-export const toPlacement = (side: DsPopoverSide, align: DsPopoverAlign) =>
-	align === 'center' ? side : (`${side}-${align}` as const);
+const MATCHED_PANEL_WIDTH = 'var(--reference-width)';
 
 const DsPopoverRoot = ({
 	open,
@@ -29,47 +34,164 @@ const DsPopoverRoot = ({
 	align = 'center',
 	gutter = 8,
 	modal = false,
+	matchAnchorWidth = false,
+	restoreFocus,
+	openOn = 'click',
+	openDelay = DEFAULT_OPEN_DELAY_MS,
+	closeDelay = DEFAULT_CLOSE_DELAY_MS,
+	getAnchorElement,
 	children,
+	onOpenAutoFocus,
+	onCloseAutoFocus,
+	onInteractOutside,
 	onOpenChange,
-}: DsPopoverRootProps) => (
-	<Popover.Root
-		open={open}
-		defaultOpen={defaultOpen}
-		modal={modal}
-		positioning={{ placement: toPlacement(side, align), gutter }}
-		onOpenChange={(details) => onOpenChange?.(details.open)}
-	>
-		{children}
-	</Popover.Root>
-);
+}: DsPopoverRootProps) => {
+	const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+	const anchorRef = useRef<HTMLElement | null>(null);
+	const restoringFocus = useRef(false);
+	const [contentId, setContentId] = useState<string>();
+	const [focusInPanel, setFocusInPanel] = useState(false);
 
-const DsPopoverTrigger = ({ children, className }: DsPopoverTriggerProps) => (
-	<Popover.Trigger asChild className={className}>
-		{children}
-	</Popover.Trigger>
-);
+	useEffect(() => () => clearTimeout(timer.current), []);
+
+	const schedule = (action: () => void, delay: number) => {
+		clearTimeout(timer.current);
+		timer.current = setTimeout(action, delay);
+	};
+
+	const isHover = openOn === 'hover';
+
+	const consumeFocusRestore = () => {
+		const restoring = restoringFocus.current;
+		restoringFocus.current = false;
+
+		return restoring;
+	};
+
+	const registerAnchor = (el: HTMLElement | null) => {
+		anchorRef.current = el;
+	};
+
+	const ownsCloseFocus = restoreFocus === false && Boolean(onCloseAutoFocus);
+	const initialFocusEl = toFocusEl(onOpenAutoFocus, 'openAutoFocus') as PopoverRootProps['initialFocusEl'];
+	const finalFocusEl = ownsCloseFocus
+		? undefined
+		: (toFocusEl(onCloseAutoFocus, 'closeAutoFocus') as PopoverRootProps['finalFocusEl']);
+	const arkRestoreFocus = ownsCloseFocus ? false : (restoreFocus ?? (!isHover || focusInPanel));
+
+	return (
+		<DsPopoverContext.Provider
+			value={{
+				matchAnchorWidth,
+				registerAnchor,
+				registerContentId: setContentId,
+				hoverIntent: isHover
+					? { openDelay, closeDelay, schedule, setFocusInPanel, consumeFocusRestore }
+					: null,
+			}}
+		>
+			<Popover.Root
+				open={open}
+				defaultOpen={defaultOpen}
+				modal={modal}
+				ids={contentId ? { content: contentId } : undefined}
+				// Trigger focus is lost when open on hover
+				// eslint-disable-next-line jsx-a11y/no-autofocus
+				autoFocus={!isHover}
+				restoreFocus={arkRestoreFocus}
+				positioning={{
+					placement: toPlacement(side, align),
+					gutter,
+					sameWidth: matchAnchorWidth,
+					...(getAnchorElement ? { getAnchorElement } : {}),
+				}}
+				initialFocusEl={initialFocusEl}
+				finalFocusEl={finalFocusEl}
+				persistentElements={[() => anchorRef.current]}
+				onInteractOutside={
+					onInteractOutside
+						? (event) => {
+								const dsEvent = new Event('interactOutside', { cancelable: true });
+								onInteractOutside(dsEvent);
+
+								if (dsEvent.defaultPrevented) {
+									event.preventDefault();
+								}
+							}
+						: undefined
+				}
+				onOpenChange={(details) => {
+					if (!details.open && focusInPanel) {
+						restoringFocus.current = true;
+					}
+
+					if (!details.open && ownsCloseFocus && onCloseAutoFocus) {
+						invokeCloseAutoFocus(onCloseAutoFocus);
+					}
+
+					onOpenChange?.(details.open);
+				}}
+			>
+				{children}
+			</Popover.Root>
+		</DsPopoverContext.Provider>
+	);
+};
+
+const DsPopoverAnchor = ({ children, className }: DsPopoverAnchorProps) => {
+	const { registerAnchor } = useDsPopoverContext();
+
+	return (
+		<Popover.Anchor asChild className={className} ref={registerAnchor}>
+			{children}
+		</Popover.Anchor>
+	);
+};
 
 const DsPopoverPanel = ({
-	width = DEFAULT_PANEL_WIDTH,
+	width,
 	className,
 	style,
 	children,
 	ref,
+	id,
 	'aria-label': ariaLabel,
-}: DsPopoverPanelProps) => (
-	<Portal>
-		<Popover.Positioner>
-			<Popover.Content
-				ref={ref}
-				aria-label={ariaLabel}
-				className={classNames(styles.panel, className)}
-				style={{ ...style, width }}
-			>
-				{children}
-			</Popover.Content>
-		</Popover.Positioner>
-	</Portal>
-);
+}: DsPopoverPanelProps) => {
+	const { matchAnchorWidth, registerContentId, hoverIntent } = useDsPopoverContext();
+	const hoverProps = useHoverIntentProps();
+	const resolvedWidth = width ?? (matchAnchorWidth ? MATCHED_PANEL_WIDTH : DEFAULT_PANEL_WIDTH);
+
+	useLayoutEffect(() => {
+		registerContentId(id);
+
+		return () => registerContentId(undefined);
+	}, [id, registerContentId]);
+
+	const onFocus = () => hoverIntent?.setFocusInPanel(true);
+	const onBlur = (event: FocusEvent<HTMLDivElement>) => {
+		if (!event.currentTarget.contains(event.relatedTarget)) {
+			hoverIntent?.setFocusInPanel(false);
+		}
+	};
+
+	return (
+		<Portal>
+			<Popover.Positioner>
+				<Popover.Content
+					{...hoverProps}
+					onFocus={onFocus}
+					onBlur={onBlur}
+					ref={ref}
+					aria-label={ariaLabel}
+					className={classNames(styles.panel, className)}
+					style={{ ...style, width: resolvedWidth }}
+				>
+					{children}
+				</Popover.Content>
+			</Popover.Positioner>
+		</Portal>
+	);
+};
 
 const DsPopoverHeader = ({ icon, className, style, children }: DsPopoverHeaderProps) => (
 	<div className={classNames(styles.header, className)} style={style}>
@@ -141,14 +263,14 @@ const DsPopoverLegacy = ({
 	align = 'center',
 }: DsPopoverProps) => (
 	<DsPopoverRoot side={side} align={align}>
-		<DsPopoverTrigger>{trigger}</DsPopoverTrigger>
+		<PopoverTrigger>{trigger}</PopoverTrigger>
 		<DsPopoverPanel className={className}>{children}</DsPopoverPanel>
 	</DsPopoverRoot>
 );
 
 DsPopoverLegacy.displayName = 'DsPopover';
 DsPopoverRoot.displayName = 'DsPopover.Root';
-DsPopoverTrigger.displayName = 'DsPopover.Trigger';
+DsPopoverAnchor.displayName = 'DsPopover.Anchor';
 DsPopoverPanel.displayName = 'DsPopover.Panel';
 DsPopoverHeader.displayName = 'DsPopover.Header';
 DsPopoverContent.displayName = 'DsPopover.Content';
@@ -157,7 +279,8 @@ DsPopoverFooter.displayName = 'DsPopover.Footer';
 
 export const DsPopover = Object.assign(DsPopoverLegacy, {
 	Root: DsPopoverRoot,
-	Trigger: DsPopoverTrigger,
+	Trigger: PopoverTrigger,
+	Anchor: DsPopoverAnchor,
 	Panel: DsPopoverPanel,
 	Header: DsPopoverHeader,
 	Content: DsPopoverContent,

package/src/components/ds-popover/ds-popover.types.ts

@@ -6,6 +6,9 @@ export type DsPopoverSide = (typeof popoverSides)[number];
 export const popoverAligns = ['start', 'center', 'end'] as const;
 export type DsPopoverAlign = (typeof popoverAligns)[number];
 
+export const popoverOpenTriggers = ['click', 'hover'] as const;
+export type DsPopoverOpenTrigger = (typeof popoverOpenTriggers)[number];
+
 export interface DsPopoverRootProps {
 	/** Controlled open state. Pair with `onOpenChange`. */
 	open?: boolean;
@@ -31,7 +34,62 @@ export interface DsPopoverRootProps {
 	 * @default false
 	 */
 	modal?: boolean;
+	/**
+	 * Size the panel to the positioning reference (Anchor, or the trigger).
+	 * An explicit `DsPopover.Panel` `width` wins over this.
+	 * @default false
+	 */
+	matchAnchorWidth?: boolean;
+	/**
+	 * Whether to restore focus to the previously focused element on close.
+	 * @default true
+	 */
+	restoreFocus?: boolean;
+	/**
+	 * Trigger open method - click / hover
+	 * @default 'click'
+	 */
+	openOn?: DsPopoverOpenTrigger;
+	/**
+	 * Milliseconds the pointer must rest on the trigger before the panel opens.
+	 * Ignored unless `openOn` is `'hover'`.
+	 * @default 200
+	 */
+	openDelay?: number;
+	/**
+	 * Milliseconds after the pointer leaves the trigger or the panel before it
+	 * closes. Ignored unless `openOn` is `'hover'`.
+	 * @default 150
+	 */
+	closeDelay?: number;
+	/**
+	 * Returns the element the panel should position against.
+	 * When provided, the panel anchors to this element instead of the trigger —
+	 * useful when the trigger lives in one place (e.g. a sidebar) and the panel
+	 * should appear relative to a different reference point. Prefer `DsPopover.Anchor`
+	 * when the reference is in the tree.
+	 */
+	getAnchorElement?: () => HTMLElement | null;
 	children: ReactNode;
+	/**
+	 * Called when focus is about to move into the panel as it opens.
+	 * Call `event.preventDefault()` to stop the default move to the first focusable
+	 * control; focus another node in the same handler if needed.
+	 */
+	onOpenAutoFocus?: (event: Event) => void;
+	/**
+	 * Called when focus is about to leave the panel as it closes.
+	 * Call `event.preventDefault()` to stop restoring focus to the trigger;
+	 * focus another node in the same handler if needed.
+	 * Still runs when `restoreFocus` is false.
+	 */
+	onCloseAutoFocus?: (event: Event) => void;
+	/**
+	 * Called when the user interacts outside the panel.
+	 * Call `event.preventDefault()` to keep the panel open. Clicks on
+	 * `DsPopover.Anchor` already do not dismiss.
+	 */
+	onInteractOutside?: (event: Event) => void;
 	/** Fires when the popover opens or closes. */
 	onOpenChange?: (open: boolean) => void;
 }
@@ -42,6 +100,12 @@ export interface DsPopoverTriggerProps {
 	className?: string;
 }
 
+export interface DsPopoverAnchorProps {
+	/** Single element the panel positions against. Wraps the trigger when they share a field. */
+	children: ReactNode;
+	className?: string;
+}
+
 export interface DsPopoverPanelProps {
 	/**
 	 * Panel width in pixels.
@@ -52,6 +116,7 @@ export interface DsPopoverPanelProps {
 	style?: CSSProperties;
 	children: ReactNode;
 	ref?: Ref<HTMLDivElement>;
+	id?: string;
 	'aria-label'?: string;
 }