@drivenets/design-system 0.9.1 → 0.11.0

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.module.scss

@@ -14,9 +14,9 @@ $transition-duration: 0.2s;
 	width: $indicator-size;
 	height: $indicator-size;
 	padding: 0;
-	border: $border-width solid var(--color-border);
-	border-radius: var(--spacing-standard) var(--spacing-standard) var(--spacing-standard) 0;
-	background: var(--color-background);
+	border: $border-width solid var(--border);
+	border-radius: var(--standard) var(--standard) var(--standard) 0;
+	background: var(--background);
 	box-shadow: 0 5px 15px 0 rgba(0, 0, 0, 0.15);
 	cursor: pointer;
 	transition:
@@ -29,8 +29,8 @@ $transition-duration: 0.2s;
 	}
 
 	&:not(.actionRequired):hover {
-		background: var(--color-background-secondary);
-		border-color: var(--color-border-action-secondary-hover);
+		background: var(--background-secondary);
+		border-color: var(--border-action-secondary-hover);
 	}
 }
 
@@ -44,16 +44,16 @@ $transition-duration: 0.2s;
 		font-size: $plus-icon-font-size;
 		font-weight: var(--font-weight-semi-bold);
 		line-height: 0;
-		color: var(--color-font-main);
+		color: var(--font-main);
 	}
 }
 
 .actionRequired {
-	background: var(--color-background-warning-strong);
+	background: var(--background-warning-strong);
 
 	&:hover {
-		background: var(--color-background-danger-strong-hover);
-		border-color: var(--color-border-action-secondary-hover);
+		background: var(--background-error-hover);
+		border-color: var(--border-action-secondary-hover);
 	}
 }
 

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.module.scss

@@ -6,13 +6,13 @@
 	display: flex;
 	justify-content: space-between;
 	align-items: center;
-	gap: var(--spacing-sm);
+	gap: var(--sm);
 }
 
 .headerLeft {
 	display: flex;
 	align-items: center;
-	gap: var(--spacing-sm);
+	gap: var(--sm);
 }
 
 .body {
@@ -30,17 +30,17 @@
 .tabList {
 	flex-shrink: 0;
 	width: 200px;
-	border-right: 1px solid var(--color-border-secondary);
+	border-right: 1px solid var(--border-secondary);
 	display: flex;
 	flex-direction: column;
-	gap: var(--spacing-3xs);
-	padding: var(--spacing-sm);
+	gap: var(--3xs);
+	padding: var(--sm);
 }
 
 .tabContent {
 	flex: 1;
 	overflow-y: auto;
-	padding: var(--spacing-standard);
+	padding: var(--standard);
 
 	&[hidden] {
 		display: none;
@@ -54,7 +54,7 @@
 .badge {
 	display: flex;
 	align-items: center;
-	gap: var(--spacing-3xs);
+	gap: var(--3xs);
 	margin-left: auto;
 }
 
@@ -68,13 +68,13 @@
 .filterSection {
 	display: flex;
 	flex-direction: column;
-	gap: var(--spacing-sm);
+	gap: var(--sm);
 }
 
 .dateField {
 	display: flex;
 	flex-direction: column;
-	gap: var(--spacing-xs);
+	gap: var(--xs);
 }
 
 .dateLabel {
@@ -82,7 +82,7 @@
 }
 
 .emptyMessage {
-	color: var(--color-font-secondary);
+	color: var(--font-secondary);
 }
 
 .footer {

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.module.scss

@@ -6,13 +6,13 @@ $scrollbar-border-radius-pill: 9999px;
 .headerActions {
 	display: flex;
 	align-items: center;
-	gap: var(--spacing-xs);
+	gap: var(--xs);
 }
 
 .divider {
 	width: $divider-width;
 	height: $divider-height;
-	background: var(--color-border-secondary);
+	background: var(--border-secondary);
 }
 
 .searchInput {
@@ -22,8 +22,8 @@ $scrollbar-border-radius-pill: 9999px;
 .body {
 	display: flex;
 	flex-direction: column;
-	gap: var(--spacing-standard);
-	padding: var(--spacing-standard);
+	gap: var(--standard);
+	padding: var(--standard);
 	overflow-y: auto;
 
 	&::-webkit-scrollbar {
@@ -35,7 +35,7 @@ $scrollbar-border-radius-pill: 9999px;
 	}
 
 	&::-webkit-scrollbar-thumb {
-		background: var(--color-background-tertiary);
+		background: var(--background-tertiary);
 		border-radius: $scrollbar-border-radius-pill;
 	}
 }
@@ -45,16 +45,16 @@ $scrollbar-border-radius-pill: 9999px;
 	flex-direction: column;
 	align-items: center;
 	justify-content: center;
-	padding: var(--spacing-xl);
+	padding: var(--xl);
 	text-align: center;
-	color: var(--color-font-secondary);
-	font-size: var(--font-size-sm);
-	line-height: var(--line-height-sm);
-	gap: var(--spacing-sm);
+	color: var(--font-secondary);
+	font-size: var(--body-font-size-sm);
+	line-height: var(--body-line-height-small);
+	gap: var(--sm);
 }
 
 .emptyIcon {
-	color: var(--color-icon-secondary);
+	color: var(--icon-action-secondary);
 }
 
 .filterTagsToolbar {

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;
 }