@bethinkpl/design-system 42.0.0 → 44.0.0

package/lib/js/components/Form/TextAreaField/TextAreaField.spec.ts

@@ -0,0 +1,341 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import TextAreaField from './TextAreaField.vue';
+import TextAreaFieldAutosized from './TextAreaFieldAutosized.vue';
+import { ComputedRef, Ref } from 'vue';
+import { FORM_FIELD_STATES } from '../FormField';
+import { ComponentProps } from 'vue-component-type-helpers';
+import { FormMeta, useForm } from 'vee-validate';
+import { waitForExpectShort } from '../../../tests/helpers';
+
+const fieldId = 'form-field-v-0';
+const messageId = `${fieldId}-message`;
+
+function setup({ props }: { props?: ComponentProps<typeof TextAreaField> } = {}) {
+	return mount(TextAreaField, { props });
+}
+
+describe('TextAreaField', () => {
+	it('should render', () => {
+		const wrapper = setup({
+			props: {
+				label: 'Label',
+				messageText: 'Message text',
+			},
+		});
+
+		expect(wrapper.find('.ds-textAreaField').exists()).toBe(true);
+		expect(wrapper.find('textarea').exists()).toBe(true);
+		expect(wrapper.find('label').text()).toContain('Label');
+		expect(wrapper.find(`#${messageId}`).text()).toBe('Message text');
+	});
+
+	it('should handle value updates', async () => {
+		const onUpdate = vi.fn();
+		const wrapper = setup({
+			props: {
+				label: 'Label',
+				modelValue: 'initial value',
+				'onUpdate:modelValue': onUpdate,
+			},
+		});
+
+		const textarea = wrapper.find<HTMLTextAreaElement>('textarea');
+		expect(textarea.element.value).toBe('initial value');
+
+		await textarea.setValue('updated value');
+
+		expect(onUpdate).toHaveBeenCalledWith('updated value');
+		expect(textarea.element.value).toBe('updated value');
+	});
+
+	it('should render with accessible ids', () => {
+		const wrapper = setup({
+			props: {
+				label: 'Label',
+				messageText: 'Message text',
+			},
+		});
+
+		expect(wrapper.find('label').attributes('for')).toBe(fieldId);
+
+		const textarea = wrapper.find('textarea');
+
+		expect(textarea.attributes('id')).toBe(fieldId);
+		expect(textarea.attributes('aria-describedby')).toBe(messageId);
+		expect(wrapper.find(`#${messageId}`).exists()).toBe(true);
+	});
+
+	it('should set aria-describedby only when a message is rendered', () => {
+		const wrapper = setup({
+			props: {
+				label: 'Label',
+			},
+		});
+
+		expect(wrapper.find('textarea').attributes('aria-describedby')).toBeUndefined();
+	});
+
+	it('should pass inputProps to the textarea element', () => {
+		const inputProps = {
+			placeholder: 'Enter text',
+			disabled: true,
+			maxlength: 500,
+			'aria-label': 'Text area field',
+		};
+
+		const wrapper = setup({
+			props: {
+				label: 'Label',
+				inputProps,
+			},
+		});
+
+		const textarea = wrapper.find('textarea');
+		expect(textarea.attributes('placeholder')).toBe(inputProps.placeholder);
+		expect(textarea.attributes('disabled')).toBeDefined();
+		expect(textarea.attributes('maxlength')).toBe('500');
+		expect(textarea.attributes('aria-label')).toBe(inputProps['aria-label']);
+	});
+
+	it('should render 3 rows by default', () => {
+		const wrapper = setup();
+
+		expect(wrapper.find('textarea').attributes('rows')).toBe('3');
+	});
+
+	it('should let inputProps override the default rows', () => {
+		const wrapper = setup({
+			props: {
+				inputProps: {
+					rows: 6,
+				},
+			},
+		});
+
+		expect(wrapper.find('textarea').attributes('rows')).toBe('6');
+	});
+
+	it.each([
+		{
+			state: FORM_FIELD_STATES.DISABLED,
+			expectedClass: '-ds-disabled',
+		},
+		{
+			state: FORM_FIELD_STATES.ERROR,
+			expectedClass: '-ds-error',
+		},
+	])('should handle state: $state', ({ state, expectedClass }) => {
+		const wrapper = setup({
+			props: {
+				state,
+			},
+		});
+		expect(wrapper.find('.ds-textAreaField').classes()).toContain(expectedClass);
+	});
+
+	it('should make textarea disabled when state is DISABLED', () => {
+		const wrapper = setup({
+			props: {
+				state: FORM_FIELD_STATES.DISABLED,
+			},
+		});
+		const textarea = wrapper.find('textarea');
+		expect(textarea.attributes('disabled')).toBeDefined();
+	});
+
+	describe('autoresizing', () => {
+		it('should render a plain textarea by default', () => {
+			const wrapper = setup();
+
+			expect(wrapper.findComponent(TextAreaFieldAutosized).exists()).toBe(false);
+			expect(wrapper.find('.ds-textAreaField').classes()).not.toContain('-ds-autoresizing');
+			expect(wrapper.find('textarea').exists()).toBe(true);
+		});
+
+		it('should render the autosized textarea when isAutoresizing', () => {
+			const wrapper = setup({
+				props: {
+					isAutoresizing: true,
+				},
+			});
+
+			expect(wrapper.findComponent(TextAreaFieldAutosized).exists()).toBe(true);
+			expect(wrapper.find('.ds-textAreaField').classes()).toContain('-ds-autoresizing');
+		});
+
+		it('should keep the field plumbing when autoresizing', async () => {
+			const onUpdate = vi.fn();
+			const wrapper = setup({
+				props: {
+					label: 'Label',
+					messageText: 'Message text',
+					isAutoresizing: true,
+					inputProps: {
+						rows: 4,
+					},
+					'onUpdate:modelValue': onUpdate,
+				},
+			});
+
+			const textarea = wrapper.find('textarea');
+			expect(textarea.attributes('id')).toBe(fieldId);
+			expect(textarea.attributes('aria-describedby')).toBe(messageId);
+			expect(textarea.attributes('rows')).toBe('4');
+			expect(textarea.classes()).toContain('ds-textAreaField__input');
+
+			await textarea.setValue('updated value');
+
+			expect(onUpdate).toHaveBeenCalledWith('updated value');
+		});
+	});
+
+	describe('with vee-validate', () => {
+		const fieldName = 'siema';
+		const initialValue = 'siemanko!';
+		function setupWithForm(props?: ComponentProps<typeof TextAreaField>) {
+			let controlledValuesRef: Ref<{ siema: string }> | undefined;
+			let errorsRef: ComputedRef<Partial<Record<'siema', string | undefined>>> | undefined;
+			let metaRef: Ref<FormMeta<{ siema: string }>> | undefined;
+
+			const FormComponent = {
+				template: `
+				<form>
+					<TextAreaField
+						v-bind="props"
+						:name="name"
+					/>
+				</form>
+			`,
+				components: { TextAreaField },
+				setup() {
+					const { controlledValues, errors, meta } = useForm({
+						initialValues: {
+							[fieldName]: initialValue,
+						},
+						validationSchema: {
+							siema: (val: string) => (val.length < 5 ? 'Too short' : true),
+						},
+					});
+
+					controlledValuesRef = controlledValues;
+					errorsRef = errors;
+					metaRef = meta;
+
+					return {
+						name: fieldName,
+						props,
+					};
+				},
+			};
+
+			return {
+				wrapper: mount(FormComponent),
+				controlledValuesRef,
+				errorsRef,
+				metaRef,
+			};
+		}
+
+		it('should bind textarea value with vee-validate form values', async () => {
+			const { wrapper, controlledValuesRef } = setupWithForm();
+
+			const textarea = wrapper.find('textarea');
+
+			expect(textarea.element.value).toBe(initialValue);
+			expect(controlledValuesRef?.value[fieldName]).toBe(initialValue);
+
+			const newValue = 'no cześć!';
+			await textarea.setValue(newValue);
+
+			expect(textarea.element.value).toBe(newValue);
+			expect(controlledValuesRef?.value[fieldName]).toBe(newValue);
+		});
+
+		it('should call onBlur and mark form as touched on blur', async () => {
+			const onBlur = vi.fn();
+			const { wrapper, metaRef } = setupWithForm({
+				inputProps: {
+					onBlur,
+				},
+			});
+			expect(metaRef?.value.touched).toBe(false);
+
+			const textarea = wrapper.find('textarea');
+			await textarea.trigger('blur');
+
+			expect(onBlur).toHaveBeenCalled();
+			expect(metaRef?.value.touched).toBe(true);
+		});
+
+		it('should call onInput and show error message', async () => {
+			const onInput = vi.fn();
+			const { wrapper, errorsRef } = setupWithForm({
+				inputProps: {
+					onInput,
+				},
+			});
+
+			const textarea = wrapper.find('textarea');
+			await textarea.setValue('test');
+
+			expect(onInput).toHaveBeenCalled();
+
+			await textarea.trigger('blur');
+
+			await waitForExpectShort(() => {
+				expect(errorsRef?.value?.siema).toBeDefined();
+			});
+
+			expect(wrapper.find('.ds-textAreaField').classes()).toContain('-ds-error');
+			expect(wrapper.find(`#${messageId}`).text()).toBe('Too short');
+
+			await textarea.setValue('valid value');
+
+			await waitForExpectShort(() => {
+				expect(errorsRef?.value?.siema).toBeUndefined();
+			});
+		});
+
+		it('should bind the autosized textarea with vee-validate form values', async () => {
+			const { wrapper, controlledValuesRef } = setupWithForm({ isAutoresizing: true });
+
+			const textarea = wrapper.find('textarea');
+			expect(textarea.element.value).toBe(initialValue);
+
+			const newValue = 'no cześć!';
+			await textarea.setValue(newValue);
+
+			expect(controlledValuesRef?.value[fieldName]).toBe(newValue);
+		});
+
+		it('should throw an error if used outside of a form context', () => {
+			expect(() => {
+				setup({
+					props: {
+						name: 'siema',
+					},
+				});
+			}).toThrowError();
+		});
+
+		it('should keep an explicit state and message over a vee-validate error', async () => {
+			const { wrapper, errorsRef } = setupWithForm({
+				state: FORM_FIELD_STATES.SUCCESS,
+				messageText: 'Success message',
+			});
+
+			const textarea = wrapper.find('textarea');
+			await textarea.setValue('test');
+
+			await textarea.trigger('blur');
+
+			await waitForExpectShort(() => {
+				expect(errorsRef?.value?.siema).toBeDefined();
+			});
+
+			expect(wrapper.find(`#${messageId}`).classes()).toContain('-ds-success');
+			expect(wrapper.find(`#${messageId}`).text()).toBe('Success message');
+		});
+	});
+});

package/lib/js/components/Form/TextAreaField/TextAreaField.stories.ts

@@ -0,0 +1,99 @@
+import { Meta, StoryObj } from '@storybook/vue3';
+import TextAreaField from './TextAreaField.vue';
+import HelpButton from '../../Buttons/HelpButton/HelpButton.vue';
+import Modal from '../../Modals/Modal';
+import { args, argTypes } from '../FormField/FormField.stories.shared';
+import { FORM_FIELD_STATES } from '../FormField/FormField.consts';
+import { reactive, toRefs } from 'vue';
+
+const meta: Meta<typeof TextAreaField> = {
+	title: 'Components/Form/TextAreaField',
+	component: TextAreaField,
+	render: (args) => ({
+		components: { TextAreaField, HelpButton, Modal },
+		setup() {
+			const { help, labelAside, message, fieldStatus, ...restRefs } = toRefs(args);
+			const props = reactive({ ...restRefs });
+
+			return {
+				props,
+				labelAside,
+				fieldStatus,
+				message,
+				help,
+				FORM_FIELD_STATES,
+			};
+		},
+		data: () => ({
+			value: '',
+		}),
+		template: `<TextAreaField v-bind="props" v-model="value">
+			<template v-if="help" #help>
+				<HelpButton :is-disabled="props.state === FORM_FIELD_STATES.DISABLED" modal-title="Help modal title">
+					<template #modalContent>
+						Modal
+					</template>
+				</HelpButton>
+			</template>
+			<template #labelAside v-if="labelAside">
+				<div v-html="labelAside" />
+			</template>
+			<template #fieldStatus v-if="fieldStatus">
+				<div v-html="fieldStatus" />
+			</template>
+			<template #message v-if="message">
+				<div v-if="message" v-html="message" />
+			</template>
+		</TextAreaField>`,
+	}),
+	argTypes: {
+		...argTypes,
+		inputProps: {
+			control: 'object',
+		},
+		isAutoresizing: {
+			control: 'boolean',
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof TextAreaField>;
+
+export const Interactive: Story = {
+	args: {
+		...args,
+		isAutoresizing: false,
+		inputProps: {
+			rows: 3,
+			placeholder: 'TextArea placeholder',
+		},
+	},
+	parameters: {
+		design: {
+			type: 'figma',
+			url: 'https://www.figma.com/design/izQdYyiBR1GQgFkaOIfIJI/LMS---DS-Components?node-id=13216-6572',
+		},
+	},
+};
+
+/**
+ * The field grows with its content instead of showing the resize handle. `rows` stays the starting
+ * height, and the field grows up to 500px, after which it scrolls.
+ */
+export const Autoresizing: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		isAutoresizing: true,
+	},
+};
+
+export const Error: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		state: FORM_FIELD_STATES.ERROR,
+		messageText: 'Error message text',
+	},
+};

package/lib/js/components/Form/TextAreaField/TextAreaField.types.ts

@@ -0,0 +1,23 @@
+import { TextareaHTMLAttributes } from 'vue';
+import { FormFieldProps, FormFieldSlots } from '../FormField';
+
+export interface TextAreaFieldProps extends FormFieldProps {
+	/**
+	 * Forwarded to the `<textarea>`, so this is also where `rows` (default 3), `placeholder` and
+	 * `maxlength` go. Overrides the defaults the component applies.
+	 */
+	inputProps?: TextareaHTMLAttributes;
+	/**
+	 * Grows the field with its content instead of showing the resize handle. `rows` stays the
+	 * starting height, and the field grows up to 500px, after which it scrolls.
+	 *
+	 * @default false
+	 */
+	isAutoresizing?: boolean;
+	/**
+	 * vee-validate field name. Requires a surrounding form context, e.g. from `useForm()`.
+	 */
+	name?: string;
+}
+
+export type TextAreaFieldSlots = Omit<FormFieldSlots, 'field'>;

package/lib/js/components/Form/TextAreaField/TextAreaField.vue

@@ -0,0 +1,190 @@
+<template>
+	<form-field v-bind="formFieldProps">
+		<template #field="{ fieldId, messageId }">
+			<div
+				:class="[
+					'ds-textAreaField',
+					{
+						'-ds-autoresizing': isAutoresizing,
+						'-ds-error': formFieldProps.state === FORM_FIELD_STATES.ERROR,
+						'-ds-disabled': isDisabled,
+					},
+				]"
+			>
+				<text-area-field-autosized
+					v-if="isAutoresizing"
+					v-bind="finalInputProps"
+					:id="fieldId"
+					v-model="value"
+					class="ds-textAreaField__input"
+					:aria-describedby="hasMessage ? messageId : undefined"
+				/>
+				<textarea
+					v-else
+					v-bind="finalInputProps"
+					:id="fieldId"
+					v-model="value"
+					class="ds-textAreaField__input"
+					:aria-describedby="hasMessage ? messageId : undefined"
+				/>
+			</div>
+		</template>
+		<!-- begin: FormField slots -->
+		<template v-if="$slots.help" #help>
+			<slot name="help" />
+		</template>
+		<template v-if="$slots.labelAside" #labelAside>
+			<slot name="labelAside" />
+		</template>
+		<template v-if="$slots.message" #message="{ messageId }">
+			<slot name="message" :message-id="messageId" />
+		</template>
+		<template v-if="$slots.fieldStatus" #fieldStatus>
+			<slot name="fieldStatus" />
+		</template>
+		<!-- end: FormField slots -->
+	</form-field>
+</template>
+
+<style lang="scss" scoped>
+@import '../../../../styles/settings/spacings';
+@import '../../../../styles/settings/radiuses';
+@import '../../../../styles/settings/borders';
+@import '../../../../styles/settings/colors/tokens';
+@import '../../../../styles/settings/typography/tokens';
+@import '../../../../styles/settings/shadows';
+
+$input-padding: $space-4;
+$autoresizing-max-height: 500px;
+
+.ds-textAreaField {
+	$root: &;
+
+	align-self: stretch;
+	background: $color-default-background;
+	border: $border-xs solid $color-neutral-border-strong;
+	border-radius: $radius-s;
+	box-shadow: $shadow-inset-m;
+	display: flex;
+	overflow: hidden;
+
+	&__input {
+		@include formText-s-default-regular;
+
+		background: transparent;
+		border: none;
+		color: $color-neutral-text-heavy;
+		flex: 1;
+		min-height: 32px;
+		min-width: 0;
+		outline: none;
+		padding: $input-padding;
+		resize: vertical;
+
+		&::placeholder {
+			color: $color-neutral-text-weak;
+		}
+	}
+
+	&:focus-within {
+		border-color: $color-primary-border;
+	}
+
+	&.-ds-error:not(:focus-within) {
+		border-color: $color-danger-border;
+	}
+
+	&:hover:not(.-ds-disabled):not(:focus-within) {
+		border-color: $color-neutral-border-strong-hovered;
+	}
+
+	&.-ds-autoresizing {
+		#{$root}__input {
+			max-height: $autoresizing-max-height;
+			// The autosize writes an explicit `height`, which makes the browser ignore `rows`, so
+			// the starting height has to be restated here. Capped as well, since `min-height` would
+			// otherwise win over `max-height`.
+			min-height: min(
+				#{$autoresizing-max-height},
+				calc(v-bind(rows) * #{$typography-line-height-2xs} + #{$input-padding * 2})
+			);
+			overflow-y: auto;
+			resize: none;
+		}
+	}
+
+	&.-ds-disabled {
+		border-color: $color-neutral-border-strong-disabled;
+		box-shadow: none;
+
+		#{$root}__input {
+			color: $color-neutral-text-heavy-disabled;
+
+			&::placeholder {
+				color: $color-neutral-text-weak-disabled;
+			}
+		}
+	}
+}
+</style>
+
+<script lang="ts" setup>
+import { computed, TextareaHTMLAttributes } from 'vue';
+import FormField, { FORM_FIELD_STATES, FormFieldProps } from '../FormField';
+import { extractFormFieldProps } from '../FormField/FormField.utils';
+import TextAreaFieldAutosized from './TextAreaFieldAutosized.vue';
+import { TextAreaFieldProps, TextAreaFieldSlots } from './TextAreaField.types';
+import { useTextFieldWithinForm } from '../../../composables/useTextFieldWithinForm';
+
+const DEFAULT_ROWS = 3;
+
+const { inputProps, isAutoresizing = false, name, ...rest } = defineProps<TextAreaFieldProps>();
+
+const slots = defineSlots<TextAreaFieldSlots>();
+const modelValue = defineModel<string>();
+
+const {
+	value,
+	errors,
+	onInput: onFormFieldInput,
+	onBlur: onFormFieldBlur,
+} = useTextFieldWithinForm(() => name, modelValue);
+
+const { formFieldProps, isDisabled, hasMessage } = useFormFieldState();
+const { finalInputProps } = useTextArea();
+
+// Used by the `min-height` of the autoresizing field, see the style block.
+const rows = computed(() => finalInputProps.value.rows);
+
+function useFormFieldState() {
+	const formFieldProps = computed<FormFieldProps>(() =>
+		// this is needed to avoid passing modelValue to FormField as prop
+		extractFormFieldProps(rest, errors.value),
+	);
+
+	const isDisabled = computed(() => formFieldProps.value.state === FORM_FIELD_STATES.DISABLED);
+
+	// Avoids pointing `aria-describedby` at a message element that is never rendered.
+	const hasMessage = computed(() => !!(formFieldProps.value.messageText || slots.message));
+
+	return { formFieldProps, isDisabled, hasMessage };
+}
+
+function useTextArea() {
+	const finalInputProps = computed<TextareaHTMLAttributes>(() => ({
+		disabled: isDisabled.value,
+		rows: DEFAULT_ROWS,
+		...inputProps,
+		onInput: (event: Event) => {
+			onFormFieldInput();
+			inputProps?.onInput?.(event);
+		},
+		onBlur: (event: FocusEvent) => {
+			onFormFieldBlur(event);
+			inputProps?.onBlur?.(event);
+		},
+	}));
+
+	return { finalInputProps };
+}
+</script>

package/lib/js/components/Form/TextAreaField/TextAreaFieldAutosized.vue

@@ -0,0 +1,19 @@
+<template>
+	<textarea ref="textarea" v-model="model" />
+</template>
+
+<script lang="ts" setup>
+import { computed, useTemplateRef } from 'vue';
+import { useTextareaAutosize } from '@vueuse/core';
+
+const model = defineModel<string>();
+
+const textareaEl = useTemplateRef<HTMLTextAreaElement>('textarea');
+
+// Writes `height`, so the `min-height` / `max-height` from the CSS stay in charge of the bounds —
+// `min-height` would otherwise win over `max-height` and let the field grow past the cap.
+useTextareaAutosize({
+	element: textareaEl,
+	input: computed(() => model.value ?? ''),
+});
+</script>

package/lib/js/components/Form/TextAreaField/index.ts

@@ -0,0 +1,5 @@
+import TextAreaField from './TextAreaField.vue';
+
+export * from './TextAreaField.types';
+
+export default TextAreaField;