@drivenets/design-system 0.19.0 → 0.20.0

package/src/components/ds-filters-bar/ds-filters-bar.unit.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest';
+import type { DsFilterCondition, DsFilterField } from './ds-filters-bar.types';
+import {
+	appendCondition,
+	createConditionId,
+	createSearchCondition,
+	describeCondition,
+	isFiltersBarView,
+	lockedViewsFor,
+	normalizeQuery,
+	removeConditionById,
+	replaceCondition,
+} from './ds-filters-bar.utils';
+
+const EQUALS = { value: '=', label: 'equals', symbol: '=' };
+const NOT_EQUALS = { value: '!=', label: 'not equals', symbol: '≠' };
+
+const FIELDS: DsFilterField[] = [
+	{
+		type: 'enum',
+		id: 'status',
+		label: 'Status',
+		operators: [EQUALS, NOT_EQUALS],
+		options: [
+			{ value: 'active', label: 'Active' },
+			{ value: 'deprecated', label: 'Deprecated' },
+		],
+	},
+	{ type: 'number', id: 'parents', label: 'Parents', operators: [{ value: '>', label: 'greater than' }] },
+	{
+		type: 'date',
+		id: 'lastRun',
+		label: 'Last run',
+		operators: [EQUALS],
+		presets: [{ value: 'today', label: 'Today' }],
+	},
+	{
+		type: 'compound',
+		id: 'input',
+		label: 'Input',
+		subfields: [{ type: 'text', id: 'name', label: 'Name', operators: [{ value: '~', label: 'contains' }] }],
+	},
+];
+
+describe('isFiltersBarView', () => {
+	it.each(['filters', 'builder', 'advanced'])('accepts %s', (value) => {
+		expect(isFiltersBarView(value)).toBe(true);
+	});
+
+	it.each(['code', '', null])('rejects %s', (value) => {
+		expect(isFiltersBarView(value)).toBe(false);
+	});
+});
+
+describe('normalizeQuery', () => {
+	it('keeps edited text as is', () => {
+		expect(normalizeQuery(' status = "Active" ')).toBe(' status = "Active" ');
+	});
+
+	it.each(['', '   ', null])('turns %j into null', (query) => {
+		expect(normalizeQuery(query)).toBeNull();
+	});
+});
+
+describe('lockedViewsFor', () => {
+	it('locks nothing while the conditions are the source', () => {
+		expect(lockedViewsFor(null)).toEqual([]);
+	});
+
+	it('locks the filters and builder views while an edited query is the source', () => {
+		expect(lockedViewsFor('status = "Active"')).toEqual(['filters', 'builder']);
+	});
+});
+
+describe('createConditionId', () => {
+	it('returns a different id every call', () => {
+		expect(createConditionId()).not.toBe(createConditionId());
+	});
+});
+
+describe('createSearchCondition', () => {
+	it('creates a search condition with trimmed text', () => {
+		const condition = createSearchCondition('  AAA ');
+
+		expect(condition).toMatchObject({ kind: 'search', text: 'AAA' });
+		expect(condition?.id).toMatch(/^condition-/);
+	});
+
+	it('returns null for blank text', () => {
+		expect(createSearchCondition('   ')).toBeNull();
+	});
+});
+
+describe('condition list helpers', () => {
+	const first: DsFilterCondition = { kind: 'search', id: 'a', text: 'AAA' };
+	const second: DsFilterCondition = {
+		kind: 'field',
+		id: 'b',
+		field: 'status',
+		operator: '=',
+		value: 'active',
+	};
+
+	it('appends a condition', () => {
+		expect(appendCondition([first], second)).toEqual([first, second]);
+	});
+
+	it('replaces the condition with the same id', () => {
+		const edited: DsFilterCondition = { ...second, operator: '!=' };
+
+		expect(replaceCondition([first, second], edited)).toEqual([first, edited]);
+	});
+
+	it('removes a condition by id', () => {
+		expect(removeConditionById([first, second], 'a')).toEqual([second]);
+	});
+});
+
+describe('describeCondition', () => {
+	it('describes a search condition by its text only', () => {
+		expect(describeCondition({ kind: 'search', id: '1', text: 'WF456' }, FIELDS)).toEqual({
+			fieldPath: [],
+			value: 'WF456',
+		});
+	});
+
+	it('uses option labels for enum values', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'status',
+			operator: '!=',
+			value: ['active', 'deprecated'],
+		};
+
+		expect(describeCondition(condition, FIELDS)).toEqual({
+			fieldPath: ['Status'],
+			operator: 'not equals',
+			operatorSymbol: '≠',
+			value: 'Active, Deprecated',
+		});
+	});
+
+	it('falls back to the operator label when there is no symbol', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'parents',
+			operator: '>',
+			value: 2,
+		};
+
+		expect(describeCondition(condition, FIELDS)).toMatchObject({
+			operatorSymbol: 'greater than',
+			value: '2',
+		});
+	});
+
+	it('uses the preset label for a date preset', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'lastRun',
+			operator: '=',
+			value: 'today',
+		};
+
+		expect(describeCondition(condition, FIELDS)).toMatchObject({ value: 'Today' });
+	});
+
+	it('joins both ends of a range', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'parents',
+			operator: '>',
+			value: { from: 2, to: 5 },
+		};
+
+		expect(describeCondition(condition, FIELDS)).toMatchObject({ value: '2 – 5' });
+	});
+
+	it('includes the subfield of a compound field in the path', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'input',
+			subfield: 'name',
+			operator: '~',
+			value: 'WF456',
+		};
+
+		expect(describeCondition(condition, FIELDS)).toMatchObject({
+			fieldPath: ['Input', 'Name'],
+			operator: 'contains',
+			value: 'WF456',
+		});
+	});
+
+	it('falls back to raw ids for a field missing from the schema', () => {
+		const condition: DsFilterCondition = {
+			kind: 'field',
+			id: '1',
+			field: 'removed',
+			operator: '=',
+			value: 'x',
+		};
+
+		expect(describeCondition(condition, FIELDS)).toEqual({
+			fieldPath: ['removed'],
+			operator: '=',
+			operatorSymbol: '=',
+			value: 'x',
+		});
+	});
+});

package/src/components/ds-filters-bar/ds-filters-bar.utils.ts

@@ -0,0 +1,141 @@
+import {
+	filtersBarViews,
+	type DsFilterCondition,
+	type DsFilterField,
+	type DsFilterOption,
+	type DsFilterRange,
+	type DsFilterScalarField,
+	type DsFilterSearchCondition,
+	type DsFilterValue,
+	type DsFiltersBarView,
+} from './ds-filters-bar.types';
+
+const ID_RANDOM_WORDS = 2;
+const HEX_RADIX = 16;
+
+const QUERY_LOCKED_VIEWS: ReadonlyArray<DsFiltersBarView> = Object.freeze(['filters', 'builder']);
+const NO_LOCKED_VIEWS: ReadonlyArray<DsFiltersBarView> = Object.freeze([]);
+
+export const isFiltersBarView = (value: string | null): value is DsFiltersBarView =>
+	filtersBarViews.some((view) => view === value);
+
+/**
+ * Blank query text is not an edited query: it hands control back to the conditions.
+ */
+export const normalizeQuery = (query: string | null): string | null => (query?.trim() ? query : null);
+
+export const lockedViewsFor = (query: string | null): ReadonlyArray<DsFiltersBarView> =>
+	query === null ? NO_LOCKED_VIEWS : QUERY_LOCKED_VIEWS;
+
+/**
+ * Random, so ids stay unique across reloads and conditions restored from a **Saved filter**.
+ * `crypto.randomUUID` is avoided because it needs a secure context.
+ */
+export const createConditionId = (): string => {
+	const words = crypto.getRandomValues(new Uint32Array(ID_RANDOM_WORDS));
+
+	return `condition-${Array.from(words, (word) => word.toString(HEX_RADIX)).join('')}`;
+};
+
+export const createSearchCondition = (text: string): DsFilterSearchCondition | null => {
+	const trimmed = text.trim();
+
+	if (!trimmed) {
+		return null;
+	}
+
+	return { kind: 'search', id: createConditionId(), text: trimmed };
+};
+
+export const appendCondition = (
+	conditions: ReadonlyArray<DsFilterCondition>,
+	condition: DsFilterCondition,
+): ReadonlyArray<DsFilterCondition> => [...conditions, condition];
+
+export const replaceCondition = (
+	conditions: ReadonlyArray<DsFilterCondition>,
+	condition: DsFilterCondition,
+): ReadonlyArray<DsFilterCondition> =>
+	conditions.map((item) => (item.id === condition.id ? condition : item));
+
+export const removeConditionById = (
+	conditions: ReadonlyArray<DsFilterCondition>,
+	id: string,
+): ReadonlyArray<DsFilterCondition> => conditions.filter((item) => item.id !== id);
+
+/**
+ * Shared by the summary line and the chips, so every view words a condition the same way
+ */
+export interface DsFilterConditionDescription {
+	/**
+	 * Field then subfield labels, for example `['Input', 'Name']`. Empty for search conditions.
+	 */
+	fieldPath: ReadonlyArray<string>;
+	/**
+	 * Operator in words, for example `not equals`
+	 */
+	operator?: string;
+	/**
+	 * Operator in compact form for chips, for example `≠`
+	 */
+	operatorSymbol?: string;
+	value: string;
+}
+
+const RANGE_SEPARATOR = ' – ';
+
+const labelFor = (options: ReadonlyArray<DsFilterOption>, value: string) =>
+	options.find((option) => option.value === value)?.label ?? value;
+
+const isRange = (value: DsFilterValue): value is DsFilterRange<number> | DsFilterRange<string> =>
+	typeof value === 'object' && 'from' in value;
+
+const formatValue = (value: DsFilterValue, field: DsFilterScalarField | undefined): string => {
+	if (isRange(value)) {
+		return [value.from ?? '', value.to ?? ''].map(String).join(RANGE_SEPARATOR).trim();
+	}
+
+	if (typeof value === 'object') {
+		const options = field?.type === 'enum' ? field.options : [];
+
+		return value.map((item) => labelFor(options, item)).join(', ');
+	}
+
+	if (typeof value === 'string' && field?.type === 'date') {
+		return labelFor(field.presets ?? [], value);
+	}
+
+	return String(value);
+};
+
+/**
+ * Falls back to raw ids when a field, subfield, operator or option is missing from `fields`, so a
+ * **Saved filter** that references a removed field still shows instead of breaking the bar.
+ */
+export const describeCondition = (
+	condition: DsFilterCondition,
+	fields: ReadonlyArray<DsFilterField>,
+): DsFilterConditionDescription => {
+	if (condition.kind === 'search') {
+		return { fieldPath: [], value: condition.text };
+	}
+
+	const field = fields.find((item) => item.id === condition.field);
+	const subfield =
+		field?.type === 'compound' ? field.subfields.find((item) => item.id === condition.subfield) : undefined;
+	const scalarField = field?.type === 'compound' ? subfield : field;
+	const operator = scalarField?.operators.find((item) => item.value === condition.operator);
+
+	const fieldPath = [field?.label ?? condition.field];
+
+	if (condition.subfield) {
+		fieldPath.push(subfield?.label ?? condition.subfield);
+	}
+
+	return {
+		fieldPath,
+		operator: operator?.label ?? condition.operator,
+		operatorSymbol: operator?.symbol ?? operator?.label ?? condition.operator,
+		value: formatValue(condition.value, scalarField),
+	};
+};

package/src/components/ds-filters-bar/index.ts

@@ -0,0 +1 @@
+export { DsFiltersBar } from './ds-filters-bar';

package/src/components/ds-form-control/ds-form-control.module.scss

@@ -125,6 +125,24 @@ $form-control-description-max-height: calc(
 	}
 }
 
+// Stays in the tree while empty, so a message that appears later is announced. Out of the flex
+// flow while empty, so it adds no gap.
+.messageRegion:empty {
+	position: absolute;
+}
+
+.visuallyHidden {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	margin: -1px;
+	padding: 0;
+	border: 0;
+	overflow: hidden;
+	white-space: nowrap;
+	clip-path: inset(50%);
+}
+
 .message {
 	@include typography.body-xs-reg;
 	color: var(--font-secondary);

package/src/components/ds-form-control/ds-form-control.tsx

@@ -4,6 +4,7 @@ import classNames from 'classnames';
 import { DsIcon } from '../ds-icon';
 import { DsSelect } from '../ds-select';
 import { DsTextInput } from '../ds-text-input';
+import { DsCodeInput } from '../ds-code-input';
 import { DsTextarea } from '../ds-textarea';
 import { DsNumberInput } from '../ds-number-input';
 import { DsPasswordInput } from '../ds-password-input';
@@ -13,7 +14,13 @@ import { DsDateInput } from '../ds-date-input';
 import { DsDatePicker } from '../ds-date-picker';
 import { DsTimePicker } from '../ds-time-picker';
 
-const FormControlContext = createContext<{ controlId: string } | null>(null);
+const FormControlContext = createContext<{
+	controlId: string;
+	/**
+	 * Id of the message, while there is one
+	 */
+	messageId?: string;
+} | null>(null);
 
 const useFormControlContext = () => {
 	const context = useContext(FormControlContext);
@@ -45,6 +52,25 @@ const controlify = <TProps extends { id?: string }>(
 	return WrappedFormControl;
 };
 
+/**
+ * HOC, same as `controlify`. Also sets `aria-describedby` to the message, for inputs that accept that prop.
+ */
+const controlifyDescribed = <TProps extends { id?: string; 'aria-describedby'?: string }>(
+	Component: ComponentType<TProps>,
+	displayName: string,
+) => {
+	const WrappedFormControl = (props: TProps) => {
+		const { controlId, messageId } = useFormControlContext();
+		const describedBy = [messageId, props['aria-describedby']].filter(Boolean).join(' ') || undefined;
+
+		return <Component id={controlId} {...props} aria-describedby={describedBy} />;
+	};
+
+	WrappedFormControl.displayName = displayName;
+
+	return WrappedFormControl;
+};
+
 const DsFormControlDescription: React.FC<DsFormControlDescriptionProps> = ({ children, className }) => {
 	return <div className={classNames(styles.description, className)}>{children}</div>;
 };
@@ -63,10 +89,11 @@ const DsFormControlRoot = ({
 	children,
 }: DsFormControlProps) => {
 	const generatedId = useId();
+	const messageId = useId();
 	const controlId = id || generatedId;
 
 	return (
-		<FormControlContext.Provider value={{ controlId }}>
+		<FormControlContext.Provider value={{ controlId, messageId: message ? messageId : undefined }}>
 			<div
 				className={classNames(
 					styles.container,
@@ -77,7 +104,11 @@ const DsFormControlRoot = ({
 				)}
 				style={style}
 			>
-				{!hideLabel && (
+				{hideLabel ? (
+					<label htmlFor={controlId} className={styles.visuallyHidden}>
+						{label}
+					</label>
+				) : (
 					<div className={styles.labelContainer}>
 						<label
 							htmlFor={controlId}
@@ -93,12 +124,14 @@ const DsFormControlRoot = ({
 
 				{children}
 
-				{message && (
-					<div className={styles.message}>
-						<DsIcon icon={messageIcon} size="tiny" filled />
-						<span>{message}</span>
-					</div>
-				)}
+				<div className={styles.messageRegion} aria-live="polite">
+					{message && (
+						<div className={styles.message}>
+							<DsIcon icon={messageIcon} size="tiny" filled />
+							<span id={messageId}>{message}</span>
+						</div>
+					)}
+				</div>
 			</div>
 		</FormControlContext.Provider>
 	);
@@ -109,6 +142,7 @@ DsFormControlDescription.displayName = 'DsFormControl.Description';
 const DsFormControl = Object.assign(DsFormControlRoot, {
 	displayName: 'DsFormControl',
 	TextInput: controlify(DsTextInput, 'DsFormControl.TextInput'),
+	CodeInput: controlifyDescribed(DsCodeInput, 'DsFormControl.CodeInput'),
 	NumberInput: controlify(DsNumberInput, 'DsFormControl.NumberInput'),
 	PasswordInput: controlify(DsPasswordInput, 'DsFormControl.PasswordInput'),
 	/** @deprecated DsDateInput is deprecated. Use DsDatePicker or DsDateRangePicker instead. */

package/src/components/ds-form-control/ds-form-control.types.ts

@@ -18,7 +18,8 @@ export interface DsFormControlProps extends React.PropsWithChildren {
 	 */
 	label: string;
 	/**
-	 * When true, the label row is not rendered (e.g. inline table cell editors).
+	 * Hides the label row (e.g. inline table cell editors). The label stays as the control's
+	 * accessible name.
 	 */
 	hideLabel?: boolean;
 	/**

package/src/components/ds-icon/custom-icons/index.ts

@@ -49,6 +49,7 @@ import { SpecialWebhook } from './special-webhook';
 import { SpecialMapView } from './special-map-view';
 
 // Misc icons
+import { SpecialAdvFilters } from './special-adv-filters';
 import { SpecialHome } from './special-home';
 import { SpecialLeadingIcon } from './special-leading-icon';
 import { SpecialLego } from './special-lego';
@@ -120,6 +121,7 @@ export const customIcons = {
 	'special-map-view': SpecialMapView,
 
 	// Misc
+	'special-adv-filters': SpecialAdvFilters,
 	'special-home': SpecialHome,
 	'special-leading-icon': SpecialLeadingIcon,
 	'special-lego': SpecialLego,

package/src/components/ds-icon/custom-icons/special-adv-filters.tsx

@@ -0,0 +1,28 @@
+import type { FC, SVGProps } from 'react';
+
+/**
+ * Special Advanced Filters icon - magnifying glass with filter lines
+ * @figma https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=42571-31078
+ */
+export const SpecialAdvFilters: FC<SVGProps<SVGSVGElement>> = (props) => (
+	<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+		<path
+			d="M9.70117 12.1478C9.82249 12.1478 9.92473 12.1952 10.0068 12.2903C10.089 12.3856 10.1299 12.504 10.1299 12.6448C10.1299 12.7857 10.089 12.905 10.0068 13.0023C9.92473 13.0993 9.8225 13.1478 9.70117 13.1478H8.27344C8.15211 13.1478 8.04988 13.1003 7.96777 13.0052C7.88563 12.9099 7.84473 12.7915 7.84473 12.6507C7.84473 12.5099 7.88563 12.3905 7.96777 12.2933C8.04988 12.1962 8.15211 12.1478 8.27344 12.1478H9.70117Z"
+			fill="currentColor"
+		/>
+		<path
+			d="M11.416 9.64777C11.5374 9.6478 11.6396 9.6951 11.7217 9.79034C11.8038 9.88561 11.8447 10.004 11.8447 10.1448C11.8447 10.2857 11.8038 10.405 11.7217 10.5023C11.6396 10.5994 11.5374 10.6477 11.416 10.6478H6.55859C6.43723 10.6477 6.33504 10.6004 6.25293 10.5052C6.1708 10.4099 6.12989 10.2915 6.12988 10.1507C6.12988 10.0099 6.1708 9.89049 6.25293 9.79327C6.33504 9.69609 6.43723 9.6478 6.55859 9.64777H11.416Z"
+			fill="currentColor"
+		/>
+		<path
+			d="M12.5586 7.14777C12.68 7.14777 12.7821 7.19514 12.8643 7.29034C12.9464 7.38562 12.9873 7.50401 12.9873 7.64484C12.9873 7.78567 12.9464 7.90504 12.8643 8.00226C12.7821 8.09941 12.68 8.14777 12.5586 8.14777H5.41602C5.29463 8.14777 5.19248 8.10039 5.11035 8.00519C5.02821 7.90991 4.98731 7.79152 4.9873 7.6507C4.9873 7.50986 5.02821 7.3905 5.11035 7.29327C5.19248 7.19612 5.29463 7.14777 5.41602 7.14777H12.5586Z"
+			fill="currentColor"
+		/>
+		<path
+			fillRule="evenodd"
+			clipRule="evenodd"
+			d="M8.98535 2.14777C9.94489 2.14777 10.8519 2.3315 11.7061 2.69952C12.5602 3.06758 13.3036 3.56758 13.9355 4.19952C14.5675 4.83147 15.0675 5.57386 15.4355 6.42609C15.8036 7.27828 15.9873 8.18601 15.9873 9.14874C15.9873 9.98127 15.8491 10.7687 15.5723 11.511C15.2955 12.2535 14.9126 12.9311 14.4248 13.5433L17.4668 16.5853C17.6193 16.7329 17.6923 16.9052 17.6855 17.1019C17.6786 17.2988 17.5996 17.4745 17.4502 17.6273C17.3008 17.7797 17.1267 17.8557 16.9277 17.8558C16.7284 17.8558 16.5537 17.7798 16.4043 17.6273L13.3623 14.6058C12.7541 15.0933 12.0812 15.4724 11.3438 15.7425C10.6061 16.0126 9.82064 16.1478 8.9873 16.1478C8.01647 16.1478 7.10671 15.9641 6.25879 15.596C5.4111 15.228 4.66806 14.7277 4.0293 14.096C3.39041 13.4641 2.89041 12.7234 2.5293 11.8753C2.16829 11.0276 1.98736 10.1185 1.9873 9.14777C1.9873 8.18975 2.17104 7.28315 2.53906 6.42902C2.90712 5.57485 3.40627 4.83175 4.03516 4.19952C4.66407 3.56731 5.40284 3.06712 6.25195 2.69952C7.10137 2.33176 8.01274 2.14778 8.98535 2.14777ZM8.9873 3.64777C7.45523 3.64777 6.15525 4.18438 5.08789 5.25812C4.02067 6.33201 3.4873 7.62874 3.4873 9.14777C3.4873 10.6798 4.02066 11.9798 5.08691 13.0472C6.15288 14.1141 7.45106 14.6477 8.98145 14.6478C10.4989 14.6478 11.7967 14.1144 12.873 13.0482C13.9491 11.9822 14.4872 10.684 14.4873 9.15363C14.4873 7.63613 13.9507 6.33841 12.877 5.26202C11.8031 4.18565 10.5063 3.64777 8.9873 3.64777Z"
+			fill="currentColor"
+		/>
+	</svg>
+);

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