@bethinkpl/design-system 42.0.0 → 43.0.0

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

@@ -0,0 +1,342 @@
+<template>
+	<form-field v-bind="formFieldProps">
+		<template #field="{ fieldId, messageId }">
+			<select-root
+				v-model="value"
+				:autocomplete="autocomplete"
+				:disabled="isDisabled"
+				:required="formFieldProps.hasRequiredIndicator"
+				@update:open="onOpenChange"
+			>
+				<select-trigger
+					:id="fieldId"
+					:aria-describedby="hasMessage ? messageId : undefined"
+					:aria-label="formFieldProps.label ? undefined : ariaLabel"
+					:class="[
+						'ds-selectField__trigger',
+						{
+							'-ds-error': formFieldProps.state === FORM_FIELD_STATES.ERROR,
+							'-ds-disabled': isDisabled,
+						},
+					]"
+				>
+					<ds-icon
+						v-if="leftIcon"
+						class="ds-selectField__leftIcon"
+						:icon="leftIcon"
+						:size="ICON_SIZES.X_SMALL"
+					/>
+					<select-value class="ds-selectField__value" :placeholder="placeholder" />
+					<select-icon as-child>
+						<ds-icon
+							class="ds-selectField__icon"
+							:icon="ICONS.FA_CHEVRON_DOWN"
+							:size="ICON_SIZES.X_SMALL"
+						/>
+					</select-icon>
+				</select-trigger>
+
+				<select-portal>
+					<select-content
+						class="ds-selectField__content"
+						position="popper"
+						align="start"
+						:side-offset="4"
+						:style="contentStyle"
+					>
+						<select-viewport as-child>
+							<ds-select-list>
+								<template
+									v-for="(group, groupIndex) in normalizedOptions"
+									:key="groupIndex"
+								>
+									<select-separator v-if="groupIndex > 0" as-child>
+										<ds-select-list-item-divider />
+									</select-separator>
+
+									<!-- A labelled group gets real `role="group"` semantics. -->
+									<select-group v-if="group.label">
+										<select-label as-child>
+											<ds-select-list-section-title
+												:label="group.label"
+												:is-uppercase="isGroupLabelUppercase"
+											/>
+										</select-label>
+										<select-field-option
+											v-for="option in group.options"
+											:key="option.value"
+											:option="option"
+											:is-selected="option.value === value"
+										/>
+									</select-group>
+
+									<!--
+										Ungrouped options render as direct children of the listbox:
+										an unlabelled SelectGroup would emit `role="group"` with a
+										dangling `aria-labelledby`.
+									-->
+									<template v-else>
+										<select-field-option
+											v-for="option in group.options"
+											:key="option.value"
+											:option="option"
+											:is-selected="option.value === value"
+										/>
+									</template>
+								</template>
+							</ds-select-list>
+						</select-viewport>
+					</select-content>
+				</select-portal>
+			</select-root>
+		</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';
+@import '../../../../styles/settings/animations';
+
+.ds-selectField {
+	$root: &;
+
+	// The element rules come before `&__trigger` so that the trigger's state overrides, which
+	// target the same elements at a higher specificity, stay in ascending order.
+	&__leftIcon {
+		color: $color-neutral-icon-weak;
+	}
+
+	&__value {
+		@include formText-s-default-regular;
+
+		color: $color-neutral-text-heavy;
+		flex: 1;
+		// override the default min-width so long values can ellipsize
+		min-width: 0;
+		overflow: hidden;
+		text-align: left;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+
+		&[data-placeholder] {
+			color: $color-neutral-text-weak;
+		}
+	}
+
+	&__icon {
+		color: $color-neutral-icon;
+		transition: $default-cubic-bezier-transition;
+	}
+
+	&__trigger {
+		align-items: center;
+		// FormField__field is `align-items: flex-start`, so the trigger must opt into full width.
+		align-self: stretch;
+		background: $color-default-background;
+		border: $border-xs solid $color-neutral-border-strong;
+		border-radius: $radius-s;
+		box-shadow: $shadow-inset-m;
+		cursor: pointer;
+		display: flex;
+		font-family: inherit;
+		gap: $space-4;
+		min-height: 32px;
+		// Focus is conveyed by the border color below, so the UA ring is suppressed
+		outline: none;
+		padding: 0 $space-4;
+		text-align: left;
+
+		// The trigger is a button, so `[data-state='open']` replaces InputField's `:focus-within`.
+		&[data-state='open'] {
+			border-color: $color-primary-border;
+
+			#{$root}__icon {
+				transform: rotate(180deg);
+			}
+		}
+
+		&:focus-visible {
+			border-color: $color-primary-border;
+		}
+
+		&.-ds-disabled {
+			border-color: $color-neutral-border-strong-disabled;
+			box-shadow: none;
+			cursor: default;
+
+			#{$root}__leftIcon {
+				color: $color-neutral-icon-weak-disabled;
+			}
+
+			#{$root}__value {
+				color: $color-neutral-text-heavy-disabled;
+
+				&[data-placeholder] {
+					color: $color-neutral-text-weak-disabled;
+				}
+			}
+
+			#{$root}__icon {
+				color: $color-neutral-icon-disabled;
+			}
+		}
+
+		// `:focus-visible` is excluded so that focusing an errored trigger shows the primary
+		// border, the same way InputField's error rule yields to `:focus-within`.
+		&.-ds-error:not([data-state='open']):not(:focus-visible) {
+			border-color: $color-danger-border;
+		}
+
+		&:hover:not(.-ds-disabled):not([data-state='open']) {
+			border-color: $color-neutral-border-strong-hovered;
+
+			#{$root}__icon {
+				color: $color-neutral-icon-hovered;
+			}
+		}
+	}
+}
+</style>
+
+<!--
+	`ds-selectField__content` is styled unscoped on purpose. SelectContent renders through
+	Presence's slot rather than as its root, so Vue never forwards this component's scope id to
+	that element — a scoped rule would not match it. It is also portalled to `<body>`, so
+	`:deep()` has no ancestor to hang off either. Same approach as DatePicker.vue.
+-->
+<style lang="scss">
+@import '../../../../styles/settings/z-indexes';
+@import '../../../../styles/mixins/dropdown-surface';
+
+.ds-selectField__content {
+	@include dropdownSurface;
+	@include dropdownSurfaceRadiusBottom;
+
+	// SelectViewport owns the scrolling; this is the flex column that caps the height.
+	display: flex;
+	flex-direction: column;
+	max-height: min(
+		var(--select-field-max-height, 320px),
+		var(--reka-select-content-available-height)
+	);
+	// Widens to fit the longest option but never narrower than the trigger, and never wider
+	// than the space available in the viewport.
+	max-width: var(--reka-select-content-available-width);
+	min-width: var(--reka-select-trigger-width);
+	// Portalled to <body>, so it needs to clear modal content. It sits on the modal layer
+	// rather than above it: the listbox is appended after the (also teleported) modal, so an
+	// equal z-index still paints it on top, and tooltips at 16777271 stay above both.
+	z-index: $z-index-modal;
+}
+</style>
+
+<script lang="ts" setup>
+import { computed, CSSProperties } from 'vue';
+import {
+	SelectContent,
+	SelectGroup,
+	SelectIcon,
+	SelectLabel,
+	SelectPortal,
+	SelectRoot,
+	SelectSeparator,
+	SelectTrigger,
+	SelectValue,
+	SelectViewport,
+} from 'reka-ui';
+import FormField, { FORM_FIELD_STATES, FormFieldProps } from '../FormField';
+import { extractFormFieldProps } from '../FormField/FormField.utils';
+import DsIcon, { ICON_SIZES, ICONS } from '../../Icons/Icon';
+import DsSelectList from '../../SelectList/SelectList.vue';
+import DsSelectListItemDivider from '../../SelectList/SelectListItemDivider/SelectListItemDivider.vue';
+import DsSelectListSectionTitle from '../../SelectList/SelectListSectionTitle/SelectListSectionTitle.vue';
+import SelectFieldOption from './SelectFieldOption.vue';
+import { SelectFieldProps, SelectFieldSlots, SelectFieldValue } from './SelectField.types';
+import { assertOptionValues, normalizeOptions, toCssLength } from './SelectField.utils';
+import { useSelectFieldWithinForm } from './useSelectFieldWithinForm';
+
+const {
+	options,
+	placeholder,
+	leftIcon,
+	ariaLabel,
+	maxHeight,
+	name,
+	autocomplete,
+	isGroupLabelUppercase = true,
+	...rest
+} = defineProps<SelectFieldProps>();
+
+const slots = defineSlots<SelectFieldSlots>();
+
+const emit = defineEmits<{
+	'open-change': [isOpen: boolean];
+}>();
+
+const modelValue = defineModel<SelectFieldValue>();
+
+const { value, errors, onClose } = useSelectFieldWithinForm(() => name, modelValue);
+
+const { formFieldProps, isDisabled, hasMessage } = useFormFieldState();
+const { normalizedOptions } = useOptions();
+
+const contentStyle = computed<CSSProperties | undefined>(() => {
+	const resolvedMaxHeight = toCssLength(maxHeight);
+
+	return resolvedMaxHeight
+		? ({ '--select-field-max-height': resolvedMaxHeight } as CSSProperties)
+		: undefined;
+});
+
+function onOpenChange(isOpen: boolean) {
+	// Closing the listbox is a select's equivalent of blur.
+	if (!isOpen) {
+		onClose(new Event('blur'));
+	}
+
+	emit('open-change', isOpen);
+}
+
+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 useOptions() {
+	const normalizedOptions = computed(() => normalizeOptions(options));
+
+	// Dev-time guard, called synchronously so invalid options fail at mount instead of
+	// surfacing as an unhandled rejection while the offscreen content fragment renders.
+	assertOptionValues(normalizedOptions.value);
+
+	return { normalizedOptions };
+}
+</script>

package/lib/js/components/Form/SelectField/SelectFieldOption.vue

@@ -0,0 +1,51 @@
+<template>
+	<select-item
+		as-child
+		:value="option.value"
+		:disabled="option.isDisabled"
+		:text-value="option.label"
+		:aria-label="option.eyebrowText ? getOptionAccessibleName(option) : undefined"
+		class="ds-selectFieldOption"
+	>
+		<ds-select-list-item
+			:label="option.label"
+			:icon-left="option.iconLeft"
+			:eyebrow-text="option.eyebrowText"
+			:is-selected="isSelected"
+			:state="
+				option.isDisabled
+					? SELECT_LIST_ITEM_STATES.DISABLED
+					: SELECT_LIST_ITEM_STATES.DEFAULT
+			"
+		>
+			<!--
+				reka-ui names each option via `aria-labelledby` pointing at the id rendered by
+				SelectItemText, so the visible label must live inside it.
+			-->
+			<template #text>
+				<select-item-text>{{ option.label }}</select-item-text>
+			</template>
+		</ds-select-list-item>
+	</select-item>
+</template>
+
+<style lang="scss">
+.ds-selectFieldOption {
+	// The highlighted state is conveyed by SelectListItem's own styling, so the UA focus ring
+	// is suppressed
+	outline: none;
+}
+</style>
+
+<script lang="ts" setup>
+import { SelectItem, SelectItemText } from 'reka-ui';
+import DsSelectListItem from '../../SelectList/SelectListItem/SelectListItem.vue';
+import { SELECT_LIST_ITEM_STATES } from '../../SelectList/SelectListItem/SelectListItem.consts';
+import { SelectFieldOption as SelectFieldOptionType } from './SelectField.types';
+import { getOptionAccessibleName } from './SelectField.utils';
+
+const { option, isSelected = false } = defineProps<{
+	option: SelectFieldOptionType;
+	isSelected?: boolean;
+}>();
+</script>

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

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

package/lib/js/components/Form/SelectField/useSelectFieldWithinForm.ts

@@ -0,0 +1,27 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { useFormFieldWithinForm } from '../../../composables/useFormFieldWithinForm';
+import { SelectFieldValue } from './SelectField.types';
+
+/**
+ * Select counterpart of `useInputFieldWithinForm`. A select has no `input` event, so closing
+ * the listbox stands in for blur — that is when the field is marked touched.
+ *
+ * Revalidation on selection needs no handler here: vee-validate's `useField` defaults to
+ * `validateOnValueUpdate: true`, so changing the value already re-runs validation.
+ */
+export function useSelectFieldWithinForm(
+	name: MaybeRefOrGetter<string | undefined>,
+	modelValue: Ref<SelectFieldValue | undefined>,
+) {
+	const { value, errors, field } = useFormFieldWithinForm(name, modelValue);
+
+	const onClose = (event: Event) => {
+		field?.handleBlur(event, true);
+	};
+
+	return {
+		value,
+		errors,
+		onClose,
+	};
+}

package/lib/js/components/SelectList/SelectListItem/SelectListItem.spec.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { h } from 'vue';
+import { ComponentProps } from 'vue-component-type-helpers';
+import SelectListItem from './SelectListItem.vue';
+import { SELECT_LIST_ITEM_SIZES, SELECT_LIST_ITEM_STATES } from './SelectListItem.consts';
+import Icon, { ICONS } from '../../Icons/Icon';
+
+const setup = (props: ComponentProps<typeof SelectListItem>, slots = {}) =>
+	mount(SelectListItem, { props, slots });
+
+describe('SelectListItem', () => {
+	it('should render the label', () => {
+		const wrapper = setup({ label: 'Basic listItem' });
+
+		expect(wrapper.find('.ds-selectListItem').exists()).toBe(true);
+		expect(wrapper.find('.ds-selectListItem__text').text()).toBe('Basic listItem');
+		expect(wrapper.find('.ds-selectListItem').attributes('title')).toBe('Basic listItem');
+	});
+
+	it('should render the eyebrow text when provided', () => {
+		const wrapper = setup({ label: 'Label', eyebrowText: 'Eyebrow' });
+
+		expect(wrapper.find('.ds-selectListItem__eyebrowText').text()).toBe('Eyebrow');
+	});
+
+	it.each(Object.values(SELECT_LIST_ITEM_SIZES))('should render in size: %s', (size) => {
+		const wrapper = setup({ label: 'Label', size });
+
+		expect(wrapper.find('.ds-selectListItem').classes()).toContain(`-ds-${size}`);
+	});
+
+	it.each([
+		{ state: SELECT_LIST_ITEM_STATES.DISABLED, expectedClass: '-ds-disabled' },
+		{ state: SELECT_LIST_ITEM_STATES.LOADING, expectedClass: '-ds-loading' },
+	])('should apply $expectedClass for state $state', ({ state, expectedClass }) => {
+		const wrapper = setup({ label: 'Label', state });
+
+		expect(wrapper.find('.ds-selectListItem').classes()).toContain(expectedClass);
+	});
+
+	it('should render the check icon when selected', () => {
+		const wrapper = setup({ label: 'Label', isSelected: true });
+
+		expect(
+			wrapper.findComponent<typeof Icon>('.ds-selectListItem__iconRight').props().icon,
+		).toEqual(ICONS.FA_CHECK_SOLID);
+	});
+
+	it('should not render the check icon when not selected', () => {
+		const wrapper = setup({ label: 'Label' });
+
+		expect(wrapper.find('.ds-selectListItem__iconRight').exists()).toBe(false);
+	});
+
+	describe('text slot', () => {
+		it('should fall back to the label when the slot is not provided', () => {
+			const wrapper = setup({ label: 'Fallback label' });
+
+			expect(wrapper.find('.ds-selectListItem__text').text()).toBe('Fallback label');
+		});
+
+		it('should override the rendered label when the slot is provided', () => {
+			const wrapper = setup(
+				{ label: 'Prop label' },
+				{ text: () => h('span', { id: 'custom-text' }, 'Slot label') },
+			);
+
+			const text = wrapper.find('.ds-selectListItem__text');
+
+			expect(text.find('#custom-text').exists()).toBe(true);
+			expect(text.text()).toBe('Slot label');
+			// `label` is still used for the title attribute and typeahead fallback.
+			expect(wrapper.find('.ds-selectListItem').attributes('title')).toBe('Prop label');
+		});
+	});
+});

package/lib/js/components/SelectList/SelectListItem/SelectListItem.vue

@@ -27,7 +27,9 @@
 				:class="{ '-ds-uppercase': isEyebrowTextUppercase }"
 				>{{ eyebrowText }}</span
 			>
-			<span class="ds-selectListItem__text">{{ label }}</span>
+			<span class="ds-selectListItem__text"
+				><slot name="text">{{ label }}</slot></span
+			>
 		</span>
 
 		<slot name="metadata" />
@@ -197,6 +199,7 @@ const {
 const slots = defineSlots<{
 	accessory?: () => any;
 	metadata?: () => any;
+	text?: () => any;
 }>();
 
 const isLoading = computed(() => state === SELECT_LIST_ITEM_STATES.LOADING);

package/lib/js/composables/useFormFieldWithinForm.ts

@@ -1,9 +1,9 @@
 import { inject, MaybeRefOrGetter, ref, Ref, toValue } from 'vue';
 import { FormContextKey, useField } from 'vee-validate';
 
-export function useFormFieldWithinForm<T = string>(
+export function useFormFieldWithinForm<T>(
 	name: MaybeRefOrGetter<string | undefined>,
-	modelValue: Ref<T | undefined>,
+	modelValue: Ref<T>,
 ) {
 	const nameValue = toValue(name);
 	const form = inject(FormContextKey, null);
@@ -14,9 +14,9 @@ export function useFormFieldWithinForm<T = string>(
 		);
 	}
 
-	const field = nameValue ? useField<Array<string>>(nameValue, undefined) : null;
+	const field = nameValue ? useField<T>(nameValue, undefined) : null;
 
-	const value = field ? field.value : modelValue;
+	const value: Ref<T> = field ? field.value : modelValue;
 
 	return {
 		field,

package/lib/js/index.ts

@@ -53,6 +53,8 @@ export { default as NumberInCircle } from './components/NumberInCircle';
 export { default as DsNumberInCircle } from './components/NumberInCircle';
 export * from './components/NumberInCircle/NumberInCircle.consts';
 export { default as DsPasswordField } from './components/Form/PasswordField';
+export { default as DsSelectField } from './components/Form/SelectField';
+export * from './components/Form/SelectField';
 export { default as TabItem } from './components/TabItem';
 export { default as DsTabItem } from './components/TabItem';
 export * from './components/TabItem/TabItem.consts';

package/lib/js/styles/Shadows/Shadows.stories.scss

@@ -23,6 +23,22 @@
 		box-shadow: $shadow-xl;
 	}
 
+	&.-ds-shadowTopS {
+		box-shadow: $shadow-top-s;
+	}
+
+	&.-ds-shadowTopM {
+		box-shadow: $shadow-top-m;
+	}
+
+	&.-ds-shadowTopL {
+		box-shadow: $shadow-top-l;
+	}
+
+	&.-ds-shadowTopXl {
+		box-shadow: $shadow-top-xl;
+	}
+
 	&.-ds-shadowInsetS {
 		box-shadow: $shadow-inset-s;
 	}

package/lib/js/styles/Shadows/Shadows.stories.ts

@@ -12,6 +12,10 @@ const shadows = [
 	{ name: 'shadow-m', modifier: '-ds-shadowM' },
 	{ name: 'shadow-l', modifier: '-ds-shadowL' },
 	{ name: 'shadow-xl', modifier: '-ds-shadowXl' },
+	{ name: 'shadow-top-s', modifier: '-ds-shadowTopS' },
+	{ name: 'shadow-top-m', modifier: '-ds-shadowTopM' },
+	{ name: 'shadow-top-l', modifier: '-ds-shadowTopL' },
+	{ name: 'shadow-top-xl', modifier: '-ds-shadowTopXl' },
 	{ name: 'shadow-inset-s', modifier: '-ds-shadowInsetS' },
 	{ name: 'shadow-inset-m', modifier: '-ds-shadowInsetM' },
 ];

package/lib/styles/mixins/_dropdown-surface.scss

@@ -0,0 +1,24 @@
+@import '../settings/colors/tokens';
+@import '../settings/radiuses';
+@import '../settings/shadows';
+
+// The visual surface shared by floating panels — DsDropdown and SelectField's listbox.
+// Deliberately covers appearance only: sizing, scrolling and positioning stay with the
+// consumer, because those legitimately differ between popper engines and use cases.
+@mixin dropdownSurface {
+	background-color: $color-default-background;
+	box-shadow: $shadow-m;
+	overflow: hidden;
+}
+
+// Applied separately from `dropdownSurface`, since a panel anchored below its trigger keeps
+// its top corners square (and vice versa).
+@mixin dropdownSurfaceRadiusTop {
+	border-top-left-radius: $radius-s;
+	border-top-right-radius: $radius-s;
+}
+
+@mixin dropdownSurfaceRadiusBottom {
+	border-bottom-left-radius: $radius-s;
+	border-bottom-right-radius: $radius-s;
+}

package/lib/styles/settings/_shadows.scss

@@ -23,6 +23,24 @@ $shadow-xl:
 	0 16px 32px $color-default-shadow-strong,
 	0 0 4px $color-default-shadow;
 
+$shadow-top-s:
+	0 -1px 2px $color-default-shadow-weak,
+	0 -8px 16px $color-default-shadow-weak,
+	0 -2px 4px $color-default-shadow-strong,
+	0 0 4px $color-default-shadow;
+$shadow-top-m:
+	0 -2px 4px $color-default-shadow-weak,
+	0 -6px 12px $color-default-shadow-strong,
+	0 0 4px $color-default-shadow;
+$shadow-top-l:
+	0 -4px 8px $color-default-shadow-weak,
+	0 -10px 20px $color-default-shadow-strong,
+	0 0 4px $color-default-shadow;
+$shadow-top-xl:
+	0 -8px 16px $color-default-shadow-weak,
+	0 -16px 32px $color-default-shadow-strong,
+	0 0 4px $color-default-shadow;
+
 $shadow-inset-m: inset 0 1px 4px $color-default-shadow-heavy;
 $shadow-inset-s: inset 0 1px 3px $color-default-shadow-heavy;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bethinkpl/design-system",
-  "version": "42.0.0",
+  "version": "43.0.0",
   "description": "Bethink universe design-system",
   "repository": {
     "type": "git",