@drivenets/design-system 0.9.0 → 0.10.0

package/src/components/ds-comment-bubble/ds-comment-bubble.types.ts

@@ -2,27 +2,105 @@ import type { CSSProperties, ReactNode, Ref } from 'react';
 import type { CommentAuthor, CommentData } from '../ds-comment-card';
 
 export interface DsCommentBubbleProps {
+	/**
+	 * Ref forwarded to the bubble root element
+	 */
 	ref?: Ref<HTMLDivElement>;
+	/**
+	 * Existing comment thread rendered inside the bubble. Omit to render an empty
+	 * bubble for composing a new comment.
+	 */
 	comment?: CommentData;
+	/**
+	 * The user currently viewing the bubble. Used to decide whether thread messages
+	 * can be edited or deleted by the viewer.
+	 */
 	currentUser?: CommentAuthor;
+	/**
+	 * Hide the "action required" checkbox and the associated visual highlight.
+	 * @default false
+	 */
 	hideActionRequired?: boolean;
+	/**
+	 * Whether the comment is flagged as requiring action. Drives the action-required
+	 * highlight and the checkbox state.
+	 * @default false
+	 */
 	actionRequired?: boolean;
+	/**
+	 * Called when the "action required" checkbox is toggled. Receives the new checked state.
+	 */
 	onActionRequiredChange?: (checked: boolean) => void;
+	/**
+	 * Current value of the reply / new-comment textarea (controlled)
+	 */
 	value?: string;
+	/**
+	 * Called whenever the textarea value changes. Receives the new string value.
+	 */
 	onValueChange?: (value: string) => void;
+	/**
+	 * Called when the user submits the textarea content (clicks send or presses Enter).
+	 * Receives the message content and the current action-required flag.
+	 */
 	onSend?: (content: string, actionRequired: boolean) => void;
+	/**
+	 * Called when the bubble should be dismissed (e.g., clicking outside an empty bubble
+	 * or pressing the close affordance).
+	 */
 	onClose?: () => void;
+	/**
+	 * Called when the user resolves the top-level comment from the bubble header menu.
+	 */
 	onResolve?: () => void;
+	/**
+	 * Called when the user toggles the top-level comment's action-required flag from
+	 * the bubble header menu.
+	 */
 	onToggleActionRequired?: () => void;
+	/**
+	 * Called when the user forwards the top-level comment from the bubble header menu.
+	 */
 	onForward?: () => void;
+	/**
+	 * Called when the user marks the top-level comment as unread from the bubble header menu.
+	 */
 	onMarkUnread?: () => void;
+	/**
+	 * Called when the user copies a link to the top-level comment.
+	 */
 	onCopyLink?: () => void;
+	/**
+	 * Called when the user deletes the top-level comment.
+	 */
 	onDelete?: () => void;
+	/**
+	 * Called when a thread message is edited. Receives the message id and the new content.
+	 */
 	onEditMessage?: (messageId: string, newContent: string) => void;
+	/**
+	 * Called when a thread message is deleted. Receives the message id.
+	 */
 	onDeleteMessage?: (messageId: string) => void;
+	/**
+	 * Called when a thread message is marked as unread. Receives the message id.
+	 */
 	onMessageMarkUnread?: (messageId: string) => void;
+	/**
+	 * Called when a thread message is resolved. Receives the message id.
+	 */
 	onMessageResolved?: (messageId: string) => void;
+	/**
+	 * Optional reference chip shown in the bubble header. A string is rendered as a
+	 * `DsTag` with a sell icon; any other `ReactNode` is rendered verbatim.
+	 */
 	referenceTag?: ReactNode;
+	/**
+	 * Additional CSS class name applied to the bubble root
+	 */
 	className?: string;
+	/**
+	 * Inline styles applied to the bubble root
+	 */
 	style?: CSSProperties;
 }

package/src/components/ds-comment-card/ds-comment-card.module.scss

@@ -1,4 +1,4 @@
-@import '../../styles/mixin';
+@use '../../styles/mixin' as mixins;
 
 $side-color-width: 4px;
 $border-width: 1px;
@@ -30,7 +30,7 @@ $transition-duration: 0.2s;
 		}
 	}
 
-	@include disabled-overlay;
+	@include mixins.disabled-overlay;
 }
 
 .sideColor {

package/src/components/ds-comment-card/ds-comment-card.types.ts

@@ -1,45 +1,159 @@
 import type { CSSProperties, ReactNode, Ref } from 'react';
 
 export interface CommentAuthor {
+	/**
+	 * Stable identifier for the user. Used to compare authors (e.g. to determine
+	 * whether the current viewer can edit a message).
+	 */
 	id: string;
+	/**
+	 * Display name shown next to the avatar
+	 */
 	name: string;
+	/**
+	 * Optional URL to the user's avatar image. When omitted, the avatar falls back
+	 * to initials derived from `name`.
+	 */
 	avatarSrc?: string;
 }
 
 export interface CommentMessage {
+	/**
+	 * Stable identifier for the message. Passed to callbacks to identify which
+	 * message was acted on.
+	 */
 	id: string;
+	/**
+	 * Author of the message
+	 */
 	author: CommentAuthor;
+	/**
+	 * Text content of the message
+	 */
 	content: string;
+	/**
+	 * Timestamp when the message was created
+	 */
 	createdAt: Date;
+	/**
+	 * Whether this message is the first message in a thread (i.e., the top-level
+	 * comment body). Used to render it differently from replies.
+	 * @default false
+	 */
 	isInitialMessage?: boolean;
+	/**
+	 * Whether this message has been marked resolved
+	 * @default false
+	 */
 	isResolved?: boolean;
 }
 
 export interface CommentData {
+	/**
+	 * Stable identifier for the comment thread. Passed to drawer/bubble callbacks
+	 * to identify which comment was acted on.
+	 */
 	id: string;
+	/**
+	 * Short, user-facing numeric identifier (e.g., "#42") shown in the card header
+	 * for quick reference in conversations.
+	 */
 	numericId: number;
+	/**
+	 * Author of the top-level comment
+	 */
 	author: CommentAuthor;
+	/**
+	 * Timestamp when the top-level comment was created
+	 */
 	createdAt: Date;
+	/**
+	 * Whether the entire comment thread is resolved. When true, the card is rendered
+	 * in its resolved (muted) state.
+	 */
 	isResolved: boolean;
+	/**
+	 * Ordered list of messages in the thread, from oldest to newest. The first
+	 * message is typically the top-level comment body.
+	 */
 	messages: CommentMessage[];
+	/**
+	 * Optional tag labels used for filtering and grouping in the comments drawer.
+	 */
 	labels?: string[];
+	/**
+	 * Optional reference chip shown in the card header. A string renders as a tag;
+	 * any other `ReactNode` renders verbatim.
+	 */
 	referenceTag?: ReactNode;
+	/**
+	 * Whether the comment is flagged as requiring action. Drives the action-required
+	 * highlight.
+	 * @default false
+	 */
 	isActionRequired?: boolean;
 }
 
 export interface DsCommentCardProps {
+	/**
+	 * Ref forwarded to the card root button element
+	 */
 	ref?: Ref<HTMLButtonElement>;
+	/**
+	 * The comment thread rendered by the card
+	 */
 	comment: CommentData;
+	/**
+	 * Whether the card is disabled and cannot be clicked
+	 * @default false
+	 */
 	disabled?: boolean;
+	/**
+	 * How long message content is rendered:
+	 * - `hidden` (default): truncate to a preview with ellipsis
+	 * - `displayed`: show the full message content without truncation
+	 * @default hidden
+	 */
 	overflow?: 'hidden' | 'displayed';
+	/**
+	 * Called when the card body is clicked (typically opens the thread in a bubble/drawer).
+	 */
 	onClick?: () => void;
+	/**
+	 * Called when the user resolves the comment from the card's overflow menu.
+	 */
 	onResolve?: () => void;
+	/**
+	 * Called when the user toggles the comment's action-required flag from the overflow menu.
+	 */
 	onToggleActionRequired?: () => void;
+	/**
+	 * Called when the user forwards the comment from the overflow menu.
+	 */
 	onForward?: () => void;
+	/**
+	 * Called when the user marks the comment as unread from the overflow menu.
+	 */
 	onMarkUnread?: () => void;
+	/**
+	 * Called when the user copies a link to the comment from the overflow menu.
+	 */
 	onCopyLink?: () => void;
+	/**
+	 * Called when the user deletes the comment from the overflow menu.
+	 */
 	onDelete?: () => void;
+	/**
+	 * Formatter for the card's timestamp. Receives the `createdAt` Date and returns
+	 * the string to display. Lets consumers localize or swap the relative/absolute format.
+	 */
 	formatTimestamp?: (date: Date) => string;
+	/**
+	 * Additional CSS class name applied to the card root
+	 */
 	className?: string;
+	/**
+	 * Inline styles applied to the card root
+	 */
 	style?: CSSProperties;
 }

package/src/components/ds-comment-indicator/ds-comment-indicator.types.ts

@@ -3,11 +3,37 @@ import type { CSSProperties, Ref } from 'react';
 export type CommentIndicatorType = 'placeholder' | 'default' | 'action-required';
 
 export interface DsCommentIndicatorProps {
+	/**
+	 * Visual state of the indicator:
+	 * - `placeholder`: dashed outline for "click here to add a comment" affordances
+	 * - `default`: filled pin showing an existing comment
+	 * - `action-required`: emphasized pin for comments flagged as requiring action
+	 * @default default
+	 */
 	type?: CommentIndicatorType;
+	/**
+	 * Optional URL to the author's avatar image shown inside the pin
+	 */
 	avatarSrc?: string;
+	/**
+	 * Author display name used to derive fallback avatar initials when `avatarSrc`
+	 * is not provided
+	 */
 	avatarName?: string;
+	/**
+	 * Called when the indicator is clicked (e.g., to open the comment bubble)
+	 */
 	onClick?: () => void;
+	/**
+	 * Ref forwarded to the indicator root button element
+	 */
 	ref?: Ref<HTMLButtonElement>;
+	/**
+	 * Additional CSS class name applied to the indicator root
+	 */
 	className?: string;
+	/**
+	 * Inline styles applied to the indicator root
+	 */
 	style?: CSSProperties;
 }

package/src/components/ds-comments-drawer/comments-filters.types.ts

@@ -1,14 +1,47 @@
 export interface FilterTag {
+	/**
+	 * Stable identifier for the chip, used when removing it from the filter state
+	 */
 	id: string;
+	/**
+	 * Human-readable label rendered inside the chip
+	 */
 	label: string;
+	/**
+	 * Identifier of the filter category this chip belongs to (e.g., `authors`,
+	 * `labels`, `statuses`). Maps to a key on `CommentsFilterState`.
+	 */
 	filterId: string;
+	/**
+	 * Underlying filter value this chip represents (e.g., an author id or a status
+	 * value). Used to remove the value from the corresponding array in
+	 * `CommentsFilterState`.
+	 */
 	value: string;
 }
 
 export interface CommentsFilterState {
+	/**
+	 * Author ids currently included in the filter. Empty array means no author
+	 * filter is applied.
+	 */
 	authors: string[];
+	/**
+	 * Lower bound of the createdAt range as an ISO date string, inclusive.
+	 */
 	dateFrom?: string;
+	/**
+	 * Upper bound of the createdAt range as an ISO date string, inclusive.
+	 */
 	dateTo?: string;
+	/**
+	 * Label strings currently included in the filter. Empty array means no label
+	 * filter is applied.
+	 */
 	labels: string[];
+	/**
+	 * Status buckets currently included in the filter. Empty array means all
+	 * statuses are shown.
+	 */
 	statuses: ('unresolved' | 'resolved' | 'action-required')[];
 }

package/src/components/ds-comments-drawer/components/comments-filter-modal/comments-filter-modal.types.ts

@@ -1,12 +1,48 @@
 import type { CommentsFilterState } from '../../comments-filters.types';
 
 export interface CommentsFilterModalProps {
+	/**
+	 * Whether the filter modal is visible
+	 */
 	open: boolean;
+	/**
+	 * Called when the modal should open or close (e.g., backdrop click, close button,
+	 * escape key). Receives the next `open` state.
+	 */
 	onOpenChange: (open: boolean) => void;
+	/**
+	 * Current filter state rendered by the modal inputs (controlled)
+	 */
 	filters: CommentsFilterState;
+	/**
+	 * Called whenever the user edits a filter input. Receives the next filter state.
+	 */
 	onFiltersChange: (filters: CommentsFilterState) => void;
+	/**
+	 * Called when the user confirms the current filter state via the Apply button.
+	 */
 	onApply: () => void;
+	/**
+	 * Called when the user resets all filters via the "Clear all" affordance.
+	 */
 	onClearAll: () => void;
-	availableAuthors: Array<{ id: string; name: string }>;
+	/**
+	 * All authors selectable in the "Authors" filter input. Typically derived from
+	 * the visible comment list.
+	 */
+	availableAuthors: Array<{
+		/**
+		 * Stable author id, used as the filter value.
+		 */
+		id: string;
+		/**
+		 * Display name shown in the filter option.
+		 */
+		name: string;
+	}>;
+	/**
+	 * All labels selectable in the "Labels" filter input. Typically derived from
+	 * the visible comment list.
+	 */
 	availableLabels: string[];
 }

package/src/components/ds-comments-drawer/ds-comments-drawer.types.ts

@@ -2,22 +2,86 @@ import type { CSSProperties, ReactNode, Ref } from 'react';
 import type { CommentData } from '../ds-comment-card';
 
 export interface DsCommentsDrawerProps {
+	/**
+	 * Ref forwarded to the drawer root element
+	 */
 	ref?: Ref<HTMLElement>;
+	/**
+	 * Whether the drawer is visible
+	 */
 	open: boolean;
+	/**
+	 * Called when the drawer should open or close (e.g., backdrop click, close button,
+	 * escape key). Receives the next `open` state.
+	 */
 	onOpenChange: (open: boolean) => void;
+	/**
+	 * List of comment threads to render in the drawer
+	 */
 	comments: CommentData[];
+	/**
+	 * Whether resolved comments are currently included in the visible list.
+	 * @default false
+	 */
 	showResolved?: boolean;
+	/**
+	 * Called when the "show resolved" toggle changes. Receives the new boolean value.
+	 */
 	onShowResolvedChange?: (show: boolean) => void;
+	/**
+	 * Current value of the search input (controlled)
+	 */
 	searchQuery?: string;
+	/**
+	 * Called when the search query changes. Receives the new query string.
+	 */
 	onSearchChange?: (query: string) => void;
+	/**
+	 * Called when a comment card is clicked. Receives the full comment so consumers
+	 * can open the thread in a bubble or scroll to its anchor.
+	 */
 	onCommentClick?: (comment: CommentData) => void;
+	/**
+	 * Called when a comment is resolved from its card overflow menu. Receives the
+	 * comment id.
+	 */
 	onResolveComment?: (commentId: string) => void;
+	/**
+	 * Called when a comment's action-required flag is toggled from its card overflow
+	 * menu. Receives the comment id.
+	 */
 	onToggleActionRequired?: (commentId: string) => void;
+	/**
+	 * Called when a comment is forwarded from its card overflow menu. Receives the
+	 * comment id.
+	 */
 	onForward?: (commentId: string) => void;
+	/**
+	 * Called when a comment is marked as unread from its card overflow menu. Receives
+	 * the comment id.
+	 */
 	onMarkUnread?: (commentId: string) => void;
+	/**
+	 * Called when a link to the comment is copied from its card overflow menu.
+	 * Receives the comment id.
+	 */
 	onCopyLink?: (commentId: string) => void;
+	/**
+	 * Called when a comment is deleted from its card overflow menu. Receives the
+	 * comment id.
+	 */
 	onDelete?: (commentId: string) => void;
+	/**
+	 * Custom empty-state content shown when the comments list is empty after
+	 * applying filters and search. Defaults to a built-in placeholder when omitted.
+	 */
 	noCommentsMessage?: ReactNode;
+	/**
+	 * Additional CSS class name applied to the drawer root
+	 */
 	className?: string;
+	/**
+	 * Inline styles applied to the drawer root
+	 */
 	style?: CSSProperties;
 }

package/src/components/ds-date-input/ds-date-input.types.ts

@@ -63,6 +63,29 @@ type DsDateInputBaseProps = Pick<
 	DatePickerRootProps,
 	'disabled' | 'readOnly' | 'id' | 'open' | 'name' | 'style'
 > & {
+	/**
+	 * Unique identifier for the input field
+	 */
+	id?: string;
+	/**
+	 * HTML name attribute for the input field, used in form submissions
+	 */
+	name?: string;
+	/**
+	 * Whether the input is disabled and cannot be interacted with
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * Whether the input is read-only. The field is focusable but the value cannot
+	 * be changed.
+	 * @default false
+	 */
+	readOnly?: boolean;
+	/**
+	 * Whether the calendar popover is open (controlled). Pair with `onOpenChange`.
+	 */
+	open?: boolean;
 	/**
 	 * Callback when the open state changes
 	 * @param open - Whether the calendar is open

package/src/components/ds-date-picker/ds-date-picker.tsx

@@ -31,6 +31,7 @@ const DsDatePicker = ({
 	slotProps,
 	onChange,
 	onOpenChange,
+	onBlur,
 	value: _value,
 	defaultValue: _defaultValue,
 	min: _min,
@@ -97,6 +98,8 @@ const DsDatePicker = ({
 		} else {
 			resetInput();
 		}
+
+		onBlur?.();
 	};
 
 	const showClearButton = !hideClearButton && !disabled && !readOnly && !!value;

package/src/components/ds-date-picker/ds-date-picker.types.ts

@@ -3,13 +3,28 @@ import type { DsTextInputProps } from '../ds-text-input';
 import type { DsTimePickerProps } from '../ds-time-picker';
 
 export interface DsDatePickerLocale {
+	/**
+	 * aria-label for the button that opens the calendar popover
+	 */
 	openCalendarLabel?: string;
+	/**
+	 * aria-label for the button that reveals the time picker when `withTime` is set
+	 */
 	timeTriggerLabel?: string;
+	/**
+	 * aria-label for the clear button
+	 */
 	clearLabel?: string;
 }
 
 export interface DsDatePickerSlotProps {
+	/**
+	 * Props forwarded to the underlying `DsTextInput` that displays the selected date.
+	 */
 	input?: DsTextInputProps;
+	/**
+	 * Props forwarded to the nested `DsTimePicker` rendered when `withTime` is set.
+	 */
 	timePicker?: DsTimePickerProps;
 }
 
@@ -40,6 +55,11 @@ export interface DsDatePickerProps extends Pick<
 	 */
 	onOpenChange?: (open: boolean) => void;
 
+	/**
+	 * Callback when the input is blurred
+	 */
+	onBlur?: () => void;
+
 	/**
 	 * Minimum allowed datetime as Date object
 	 */

package/src/components/ds-date-range-picker/ds-date-range-picker.types.ts

@@ -7,15 +7,31 @@ export const dateRangePickerOrientations = ['horizontal', 'vertical'] as const;
 export type DateRangePickerOrientation = (typeof dateRangePickerOrientations)[number];
 
 export interface DsDateRangePickerLocale {
+	/**
+	 * Label shown on the "Clear all" button.
+	 */
 	clearAllLabel?: string;
 }
 
 export type DateRangeFormControlSlotProps = Partial<Omit<DsFormControlProps, 'children'>>;
 
 export interface DsDateRangePickerSlotProps {
+	/**
+	 * Props forwarded to the start-date `DsDatePicker`.
+	 */
 	startDatePicker?: DsDatePickerProps;
+	/**
+	 * Props forwarded to the end-date `DsDatePicker`.
+	 */
 	endDatePicker?: DsDatePickerProps;
+	/**
+	 * Props forwarded to the `DsFormControl` wrapping the start-date picker
+	 * (e.g., to set a label or helper text).
+	 */
 	startDateFormControl?: DateRangeFormControlSlotProps;
+	/**
+	 * Props forwarded to the `DsFormControl` wrapping the end-date picker.
+	 */
 	endDateFormControl?: DateRangeFormControlSlotProps;
 }
 
@@ -71,10 +87,22 @@ export interface DsDateRangePickerProps {
 	 */
 	closeOnSelect?: boolean;
 
+	/**
+	 * Whether both pickers are disabled.
+	 * @default false
+	 */
 	disabled?: boolean;
 
+	/**
+	 * Whether both pickers are read-only. Inputs are focusable but values cannot
+	 * be changed.
+	 * @default false
+	 */
 	readOnly?: boolean;
 
+	/**
+	 * Additional CSS class name applied to the range picker wrapper.
+	 */
 	className?: string;
 
 	/**

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

@@ -40,7 +40,16 @@ export interface DsDialogProps {
 	/**
 	 * Custom fixed position (e.g., { top: number, left: number })
 	 */
-	customPosition?: { top: number; left: number };
+	customPosition?: {
+		/**
+		 * Distance in pixels from the top of the viewport.
+		 */
+		top: number;
+		/**
+		 * Distance in pixels from the left of the viewport.
+		 */
+		left: number;
+	};
 	/**
 	 * If true, show modal overlay and center dialog (default: true)
 	 */

package/src/components/ds-dropdown-menu/ds-dropdown-menu.types.ts

@@ -162,6 +162,30 @@ export interface DsDropdownMenuItemProps extends Pick<
 	Menu.ItemProps,
 	'disabled' | 'asChild' | 'className' | 'style' | 'onSelect' | 'onClick' | 'value' | 'children'
 > {
+	/**
+	 * Underlying value reported to the root's `onSelect` when this item is chosen.
+	 */
+	value: Menu.ItemProps['value'];
+	/**
+	 * Whether this item is disabled and cannot be selected.
+	 * @default false
+	 */
+	disabled?: Menu.ItemProps['disabled'];
+	/**
+	 * Render the item as its direct child via Radix-style slot forwarding. Useful
+	 * for wrapping links (`<a>`) as dropdown items.
+	 * @default false
+	 */
+	asChild?: Menu.ItemProps['asChild'];
+	/**
+	 * Called when the item is selected via click or keyboard activation.
+	 */
+	onSelect?: Menu.ItemProps['onSelect'];
+	/**
+	 * Called when the item is clicked. Fires before `onSelect` and runs even when
+	 * keyboard-activated via Space/Enter.
+	 */
+	onClick?: Menu.ItemProps['onClick'];
 	/**
 	 * Whether the item is selected (applies selected styling)
 	 */