@bethinkpl/design-system 26.15.1 → 27.0.0

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

@@ -0,0 +1,81 @@
+import { Meta, StoryObj } from '@storybook/vue3';
+import FormField from './FormField.vue';
+import HelpButton from '../../Buttons/HelpButton/HelpButton.vue';
+import { FORM_FIELD_STATES } from './FormField.consts';
+import { args, argTypes } from './FormField.stories.shared';
+import { reactive, toRefs } from 'vue';
+
+const meta: Meta<typeof FormField> = {
+	title: 'Components/Form/FormField',
+	component: FormField,
+	render: (args) => ({
+		components: { FormField, HelpButton },
+		setup() {
+			const { field, help, labelAside, message, fieldStatus, ...restRefs } = toRefs(args);
+			const props = reactive({ ...restRefs });
+
+			return {
+				props,
+				labelAside,
+				fieldStatus,
+				message,
+				help,
+				field,
+				FORM_FIELD_STATES,
+			};
+		},
+		template: `<FormField v-bind="props">
+			<template #field="{fieldId, messageId}">
+				<input v-if="!field" :id="fieldId" :aria-describedby="messageId" />
+				<div v-else v-html="field" />
+			</template>
+			<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 v-if="labelAside" #labelAside>
+				<div v-html="labelAside" />
+			</template>
+			<template v-if="fieldStatus" #fieldStatus>
+				<div v-html="fieldStatus" />
+			</template>
+			<template v-if="message" #message>
+				<div v-html="message" />
+			</template>
+		</FormField>`,
+	}),
+	argTypes: {
+		...argTypes,
+		field: {
+			control: 'text',
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof FormField>;
+
+export const Interactive: Story = {
+	args: {
+		...args,
+		field: '',
+	},
+	parameters: {
+		design: {
+			type: 'figma',
+			url: 'https://www.figma.com/design/izQdYyiBR1GQgFkaOIfIJI/LMS---DS-Components?node-id=13267-86654&t=ezos5nMsGrZyaqmC-4',
+		},
+	},
+};
+
+export const Error: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		state: FORM_FIELD_STATES.ERROR,
+		messageText: 'Error message text',
+	},
+};

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

@@ -0,0 +1,17 @@
+export interface FormFieldProps {
+	label?: string;
+	state?: 'default' | 'disabled' | 'error' | 'success';
+	hasRequiredIndicator?: boolean;
+	labelInfo?: string;
+	subLabel?: string;
+	fieldId?: string;
+	messageText?: string;
+}
+
+export interface FormFieldSlots {
+	labelAside?: () => any;
+	help?: () => any;
+	field: (props: { fieldId: string; messageId: string }) => any;
+	message?: (props: { messageId: string }) => any;
+	fieldStatus?: () => any;
+}

package/lib/js/components/Form/FormField/FormField.utils.ts

@@ -0,0 +1,24 @@
+import { FormFieldProps } from './FormField.types';
+
+/**
+ * Extracts the properties needed for a form field component only
+ */
+export function extractFormFieldProps({
+	label,
+	state,
+	hasRequiredIndicator,
+	labelInfo,
+	subLabel,
+	fieldId,
+	messageText,
+}: FormFieldProps) {
+	return {
+		label,
+		state,
+		hasRequiredIndicator,
+		labelInfo,
+		subLabel,
+		fieldId,
+		messageText,
+	};
+}

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

@@ -0,0 +1,192 @@
+<template>
+	<div
+		:class="[
+			'ds-formField',
+			{
+				'-ds-disabled': state === FORM_FIELD_STATES.DISABLED,
+			},
+		]"
+	>
+		<div v-if="label || subLabel || $slots.labelAside" class="ds-formField__labels">
+			<div class="ds-formField__labelRow">
+				<div class="ds-formField__labelWrapper">
+					<label v-if="label" class="ds-formField__label" :for="id">
+						<span class="ds-formField__labelText">{{ label }}</span>
+						<span
+							v-if="hasRequiredIndicator"
+							class="ds-formField__labelRequired"
+							aria-hidden="true"
+							>*</span
+						>
+						<span v-if="labelInfo" class="ds-formField__labelInfo">{{
+							labelInfo
+						}}</span>
+					</label>
+					<slot name="help"></slot>
+				</div>
+				<div v-if="$slots.labelAside" class="ds-formField__labelAside">
+					<slot name="labelAside"></slot>
+				</div>
+			</div>
+			<div v-if="subLabel" class="ds-formField__subLabelRow">{{ subLabel }}</div>
+		</div>
+		<div class="ds-formField__field">
+			<slot name="field" :field-id="id" :message-id="messageId"></slot>
+		</div>
+		<div v-if="hasMessage || $slots.fieldStatus" class="ds-formField__footerRow">
+			<div class="ds-formField__message">
+				<slot name="message" :message-id="messageId">
+					<form-field-message v-if="messageText" :state="state" :message-id="messageId">
+						{{ messageText }}
+					</form-field-message>
+				</slot>
+			</div>
+			<div v-if="$slots.fieldStatus" class="ds-formField__fieldStatus">
+				<slot name="fieldStatus"></slot>
+			</div>
+		</div>
+	</div>
+</template>
+
+<style scoped lang="scss">
+@import '../../../../styles/settings/spacings';
+@import '../../../../styles/settings/typography/tokens';
+@import '../../../../styles/settings/colors/tokens';
+
+.ds-formField {
+	$root: &;
+
+	display: flex;
+	flex-direction: column;
+	gap: $space-5xs;
+
+	&__labelRow {
+		align-items: flex-start;
+		display: flex;
+		gap: $space-xs;
+	}
+
+	&__subLabelRow {
+		@include formLabel-s-default-regular;
+
+		color: $color-neutral-text;
+		padding-bottom: $space-2xs;
+
+		#{$root}.-ds-disabled & {
+			color: $color-neutral-text-disabled;
+		}
+	}
+
+	&__labelWrapper {
+		align-items: flex-start;
+		display: flex;
+		flex: 1 0 0;
+		gap: $space-5xs;
+		padding: $space-4xs 0;
+	}
+
+	&__label {
+		@include formLabel-m-default-bold;
+
+		margin: $space-5xs 0;
+	}
+
+	&__labelText {
+		color: $color-neutral-text-strong;
+
+		#{$root}.-ds-disabled & {
+			color: $color-neutral-text-strong-disabled;
+		}
+	}
+
+	&__labelRequired {
+		@include formLabel-m-default-regular;
+
+		color: $color-danger-text;
+		margin-left: $space-5xs;
+
+		#{$root}.-ds-disabled & {
+			color: $color-danger-text-disabled;
+		}
+	}
+
+	&__labelInfo {
+		@include formLabel-s-default-regular-italic;
+
+		color: $color-neutral-text;
+		margin-left: $space-5xs;
+
+		#{$root}.-ds-disabled & {
+			color: $color-neutral-text-disabled;
+		}
+	}
+
+	&__labelAside {
+		align-items: center;
+		display: flex;
+		gap: $space-4xs;
+		min-height: 28px;
+	}
+
+	&__field {
+		align-items: flex-start;
+		display: flex;
+		flex-direction: column;
+		justify-content: center;
+		min-height: 28px;
+	}
+
+	&__footerRow {
+		align-items: flex-start;
+		display: flex;
+		gap: $space-2xs;
+		padding-top: $space-4xs;
+	}
+
+	&__message {
+		flex: 1 0 0;
+	}
+
+	&__fieldStatus {
+		align-items: flex-start;
+		display: flex;
+		gap: $space-4xs;
+	}
+}
+</style>
+
+<script lang="ts" setup>
+import { computed, useId } from 'vue';
+import FormFieldMessage from './FormFieldMessage/FormFieldMessage.vue';
+import { FORM_FIELD_STATES } from './FormField.consts';
+import { FormFieldProps, FormFieldSlots } from './FormField.types';
+
+const {
+	label,
+	hasRequiredIndicator = false,
+	subLabel,
+	labelInfo,
+	fieldId,
+	messageText,
+	state = FORM_FIELD_STATES.DEFAULT,
+} = defineProps<FormFieldProps>();
+
+const slots = defineSlots<FormFieldSlots>();
+
+const baseId = useId();
+const id = computed(() => fieldId || `form-field-${baseId}`);
+const { hasMessage, messageId } = useMessage();
+
+function useMessage() {
+	const hasMessage = computed(() => {
+		return !!(slots.message || messageText);
+	});
+
+	const messageId = computed(() => `${id.value}-message`);
+
+	return {
+		hasMessage,
+		messageId,
+	};
+}
+</script>

package/lib/js/components/Form/FormField/FormFieldMessage/FormFieldMessage.spec.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import FormFieldMessage from './FormFieldMessage.vue';
+import { mount } from '@vue/test-utils';
+import Icon, { ICONS } from '../../../Icons/Icon';
+import { ComponentProps } from 'vue-component-type-helpers';
+import { FORM_FIELD_STATES } from '../FormField.consts';
+
+const id = 'message-id';
+
+function setup(
+	props: ComponentProps<typeof FormFieldMessage> = {
+		messageId: id,
+	},
+) {
+	return mount(FormFieldMessage, {
+		props,
+		slots: {
+			default: () => 'Test message',
+		},
+	});
+}
+
+describe('FormFieldMessage', () => {
+	it('should render', () => {
+		const wrapper = setup();
+
+		expect(wrapper.exists()).toBe(true);
+		expect(wrapper.text()).toBe('Test message');
+		expect(wrapper.attributes('id')).toBe(id);
+		expect(wrapper.findComponent(Icon).exists()).toBe(false);
+	});
+
+	it.each([
+		{
+			state: FORM_FIELD_STATES.ERROR,
+			expectedIcon: ICONS.FA_CIRCLE_EXCLAMATION,
+		},
+		{
+			state: FORM_FIELD_STATES.SUCCESS,
+			expectedIcon: ICONS.FA_CIRCLE_CHECK,
+		},
+	])('should render icon for state: $state', ({ state, expectedIcon }) => {
+		const wrapper = setup({
+			state,
+			messageId: id,
+		});
+
+		expect(wrapper.exists()).toBe(true);
+		expect(wrapper.text()).toBe('Test message');
+		expect(wrapper.findComponent(Icon).exists()).toBe(true);
+		expect(wrapper.findComponent(Icon).props().icon).toEqual(expectedIcon);
+	});
+});

package/lib/js/components/Form/FormField/FormFieldMessage/FormFieldMessage.stories.ts

@@ -0,0 +1,74 @@
+import { Meta, StoryObj } from '@storybook/vue3';
+import FormFieldMessage from './FormFieldMessage.vue';
+import { ComponentProps, ComponentSlots } from 'vue-component-type-helpers';
+import { FORM_FIELD_STATES } from '../FormField.consts';
+import Icon, { ICONS, ICON_SIZES } from '../../../Icons/Icon';
+
+const meta: Meta<
+	ComponentProps<typeof FormFieldMessage> & ComponentSlots<typeof FormFieldMessage>
+> = {
+	title: 'Components/Form/FormFieldMessage',
+	component: FormFieldMessage,
+	render: (args) => ({
+		components: { FormFieldMessage },
+		setup() {
+			return {
+				args,
+			};
+		},
+		template: `<FormFieldMessage v-bind="args">
+			<div v-html="args.default" />
+		</FormFieldMessage>`,
+	}),
+	argTypes: {
+		state: {
+			control: 'select',
+			options: Object.values(FORM_FIELD_STATES),
+		},
+		messageId: {
+			control: 'text',
+		},
+		default: {
+			control: 'text',
+			description: 'Default slot content for the message.',
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof FormFieldMessage>;
+
+export const Interactive: Story = {
+	args: {
+		default: 'Message',
+		messageId: 'message-id',
+		state: FORM_FIELD_STATES.DEFAULT,
+	},
+};
+
+Interactive.parameters = {
+	design: {
+		type: 'figma',
+		url: 'https://www.figma.com/design/izQdYyiBR1GQgFkaOIfIJI/LMS---DS-Components?node-id=13364-13669&m=dev',
+	},
+};
+
+export const WithInlineIcons: Story = {
+	args: {
+		messageId: 'message-id',
+		state: FORM_FIELD_STATES.DEFAULT,
+	},
+	render: (args) => ({
+		components: { FormFieldMessage, Icon },
+		setup() {
+			return {
+				args,
+				ICONS,
+				ICON_SIZES,
+			};
+		},
+		template: `<FormFieldMessage v-bind="args">
+			Message with inline <Icon :icon="ICONS.FA_ADDRESS_CARD" :size="ICON_SIZES.XX_SMALL" /> icon
+		</FormFieldMessage>`,
+	}),
+};

package/lib/js/components/Form/FormField/FormFieldMessage/FormFieldMessage.vue

@@ -0,0 +1,89 @@
+<template>
+	<div
+		:id="messageId"
+		:class="[
+			'ds-formFieldMessage',
+			{
+				['-ds-error']: state === FORM_FIELD_STATES.ERROR,
+				['-ds-success']: state === FORM_FIELD_STATES.SUCCESS,
+				['-ds-disabled']: state === FORM_FIELD_STATES.DISABLED,
+			},
+		]"
+	>
+		<div v-if="stateIcon" class="ds-formFieldMessage__iconWrapper">
+			<icon :icon="stateIcon" :size="ICON_SIZES.XX_SMALL" />
+		</div>
+		<slot></slot>
+	</div>
+</template>
+
+<style lang="scss" scoped>
+@import '../../../../../styles/settings/spacings';
+@import '../../../../../styles/settings/typography/tokens';
+@import '../../../../../styles/settings/colors/tokens';
+
+.ds-formFieldMessage {
+	$root: &;
+
+	// if you ever change the line-height here, make sure to also update the height of the iconWrapper
+	@include formCaption-m-default-regular;
+
+	color: $color-neutral-text;
+	display: flex;
+	gap: $space-4xs;
+
+	&.-ds-error {
+		color: $color-danger-text;
+	}
+
+	&.-ds-success {
+		color: $color-success-text;
+	}
+
+	&.-ds-disabled {
+		color: $color-neutral-text-disabled;
+	}
+
+	&__iconWrapper {
+		align-items: center;
+		display: flex;
+		// height is equal to the line-height of the text to ensure proper alignment
+		// if we ever decide to introduce different sizes for the messages, we should adjust this accordingly
+		height: $typography-line-height-3xs;
+
+		#{$root}.-ds-error & {
+			color: $color-danger-icon;
+		}
+
+		#{$root}.-ds-success & {
+			color: $color-success-icon;
+		}
+	}
+}
+</style>
+
+<script lang="ts" setup>
+import { computed } from 'vue';
+import { FORM_FIELD_STATES, FormFieldState } from '../FormField.consts';
+import Icon, { ICON_SIZES, ICONS } from '../../../Icons/Icon';
+
+const { state = FORM_FIELD_STATES.DEFAULT, messageId } = defineProps<{
+	state?: FormFieldState;
+	messageId: string;
+}>();
+
+defineSlots<{
+	default: () => any;
+}>();
+
+const stateIcon = computed(() => {
+	switch (state) {
+		case FORM_FIELD_STATES.ERROR:
+			return ICONS.FA_CIRCLE_EXCLAMATION;
+		case FORM_FIELD_STATES.SUCCESS:
+			return ICONS.FA_CIRCLE_CHECK;
+		default:
+			return null;
+	}
+});
+</script>

package/lib/js/components/Form/FormField/FormFieldMessage/index.ts

@@ -0,0 +1,2 @@
+import FormFieldMessage from './FormFieldMessage.vue';
+export default FormFieldMessage;

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

@@ -0,0 +1,6 @@
+import FormField from './FormField.vue';
+
+export * from './FormField.consts';
+export * from './FormField.types';
+
+export default FormField;