@bethinkpl/design-system 42.0.0 → 43.0.0

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

@@ -0,0 +1,287 @@
+import { Meta, StoryObj } from '@storybook/vue3';
+import { computed } from 'vue';
+import { withActions } from '@storybook/addon-actions/decorator';
+import SelectField from './SelectField.vue';
+import HelpButton from '../../Buttons/HelpButton/HelpButton.vue';
+import Modal from '../../Modals/Modal';
+import { ICONS } from '../../Icons/Icon';
+import { args, argTypes } from '../FormField/FormField.stories.shared';
+import { FORM_FIELD_STATES } from '../FormField/FormField.consts';
+import { SelectFieldOption, SelectFieldOptionGroup } from './SelectField.types';
+
+const OPTIONS: Array<SelectFieldOption> = [
+	{ value: 'pl', label: 'Polska' },
+	{ value: 'de', label: 'Niemcy' },
+	{ value: 'cz', label: 'Czechy' },
+	{ value: 'sk', label: 'Słowacja', isDisabled: true },
+	{ value: 'jp', label: 'Japonia' },
+];
+
+const GROUPED_OPTIONS: Array<SelectFieldOption | SelectFieldOptionGroup> = [
+	{ value: 'all', label: 'Wszystkie kraje' },
+	{
+		label: 'Europa',
+		options: [
+			{ value: 'pl', label: 'Polska' },
+			{ value: 'de', label: 'Niemcy' },
+			{ value: 'cz', label: 'Czechy' },
+		],
+	},
+	{
+		label: 'Azja',
+		options: [
+			{ value: 'jp', label: 'Japonia' },
+			{ value: 'kr', label: 'Korea Południowa' },
+		],
+	},
+];
+
+const RICH_OPTIONS: Array<SelectFieldOption> = [
+	{ value: 'draft', label: 'Szkic', eyebrowText: 'Status', iconLeft: ICONS.FA_PENCIL },
+	{
+		value: 'published',
+		label: 'Opublikowany',
+		eyebrowText: 'Status',
+		iconLeft: ICONS.FA_CHECK_SOLID,
+	},
+	{ value: 'archived', label: 'Zarchiwizowany', eyebrowText: 'Status', iconLeft: ICONS.FA_BOX },
+];
+
+const LONG_OPTIONS: Array<SelectFieldOption> = Array.from({ length: 30 }, (_, index) => ({
+	value: `option-${index + 1}`,
+	label: `Opcja numer ${index + 1}`,
+}));
+
+const LONG_LABEL_OPTIONS: Array<SelectFieldOption> = [
+	{ value: 'anatomia', label: 'Anatomia prawidłowa człowieka z elementami histologii' },
+	{ value: 'biochemia', label: 'Biochemia kliniczna i diagnostyka laboratoryjna' },
+	{ value: 'farmakologia', label: 'Farmakologia z toksykologią dla kierunku lekarskiego' },
+	{ value: 'short', label: 'Krótka nazwa' },
+	{
+		value: 'bardzo-dlugi',
+		label: 'Wyjątkowo długa nazwa kursu, która nie zmieści się w dostępnej szerokości okna i zostanie skrócona wielokropkiem',
+	},
+];
+
+/**
+ * The `maxHeight` control is a text input, so a unitless `320` would reach the component as the
+ * string `'320'` and produce invalid CSS. Turn such a value into a number, which the component
+ * reads as pixels; anything carrying a unit is passed through.
+ */
+function normalizeMaxHeight(maxHeight: string | number | undefined): string | number | undefined {
+	if (
+		typeof maxHeight === 'string' &&
+		maxHeight.trim() !== '' &&
+		!Number.isNaN(Number(maxHeight))
+	) {
+		return Number(maxHeight);
+	}
+
+	return maxHeight;
+}
+
+const meta: Meta<typeof SelectField> = {
+	title: 'Components/Form/SelectField',
+	component: SelectField,
+	decorators: [withActions],
+	render: (args) => ({
+		components: { SelectField, HelpButton, Modal },
+		setup() {
+			const props = computed(() => {
+				const { help, labelAside, message, fieldStatus, ...rest } = args;
+
+				return { ...rest, maxHeight: normalizeMaxHeight(rest.maxHeight) };
+			});
+
+			return {
+				args,
+				props,
+				FORM_FIELD_STATES,
+				ICONS,
+			};
+		},
+		data: () => ({
+			value: undefined,
+		}),
+		template: `<SelectField v-bind="props" :left-icon="props.leftIcon ? ICONS[props.leftIcon] : null" v-model="value">
+			<template v-if="args.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="args.labelAside">
+				<div v-html="args.labelAside" />
+			</template>
+			<template #fieldStatus v-if="args.fieldStatus">
+				<div v-html="args.fieldStatus" />
+			</template>
+			<template #message v-if="args.message">
+				<div v-html="args.message" />
+			</template>
+		</SelectField>`,
+	}),
+	argTypes: {
+		...argTypes,
+		options: {
+			control: 'object',
+		},
+		placeholder: {
+			control: 'text',
+		},
+		leftIcon: {
+			control: 'select',
+			options: [null, ...Object.keys(ICONS)],
+		},
+		ariaLabel: {
+			control: 'text',
+		},
+		maxHeight: {
+			control: 'text',
+		},
+		isGroupLabelUppercase: {
+			control: 'boolean',
+		},
+		autocomplete: {
+			control: 'text',
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof SelectField>;
+
+export const Interactive: Story = {
+	args: {
+		...args,
+		options: OPTIONS,
+		placeholder: 'Wybierz kraj',
+		leftIcon: null,
+		isGroupLabelUppercase: true,
+	},
+	parameters: {
+		design: {
+			type: 'figma',
+			url: 'https://www.figma.com/design/izQdYyiBR1GQgFkaOIfIJI/LMS---DS-Components?node-id=13216-6915',
+		},
+	},
+};
+
+export const WithGroups: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		options: GROUPED_OPTIONS,
+	},
+	parameters: {},
+};
+
+export const WithIconsAndEyebrow: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		options: RICH_OPTIONS,
+		placeholder: 'Wybierz status',
+	},
+	parameters: {},
+};
+
+/**
+ * The field is constrained to 360px while the option labels are much longer. Two behaviours to
+ * check here:
+ *
+ * - the trigger keeps the field's width and ellipsizes the selected label;
+ * - the dropdown uses the trigger width only as a *minimum*, widening to fit the longest
+ *   option, and stops at the space available in the viewport — where the last option, which is
+ *   longer still, ellipsizes inside the list.
+ *
+ * Try it near the right edge of the canvas, and switch to a mobile viewport, to see the
+ * `max-width` clamp take over.
+ */
+export const ConstrainedWidthWithLongLabels: Story = {
+	render: (args) => ({
+		components: { SelectField },
+		setup() {
+			return { args };
+		},
+		data: () => ({
+			// Preselected so the trigger's ellipsis is visible without opening the dropdown.
+			value: 'farmakologia',
+		}),
+		template: `
+			<div style="width: 360px;">
+				<SelectField v-bind="args" v-model="value" />
+			</div>
+		`,
+	}),
+	args: {
+		label: 'Kurs',
+		placeholder: 'Wybierz kurs',
+		options: LONG_LABEL_OPTIONS,
+	},
+};
+
+/** The dropdown caps at `maxHeight` (320px by default) and scrolls beyond it. */
+export const LongList: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		options: LONG_OPTIONS,
+		placeholder: 'Wybierz opcję',
+	},
+	parameters: {},
+};
+
+/**
+ * The field sits at the bottom of the viewport, so there is no room for the dropdown below the
+ * trigger — the popper flips and the list opens upwards. Uses the long list to make sure the
+ * dropdown is tall enough to force the flip on any viewport height.
+ */
+export const OpeningUpwards: Story = {
+	parameters: {
+		layout: 'fullscreen',
+	},
+	render: (args) => ({
+		components: { SelectField },
+		setup() {
+			return { args };
+		},
+		data: () => ({
+			value: undefined,
+		}),
+		template: `
+			<div
+				style="display: flex; align-items: flex-end; box-sizing: border-box; min-height: 100vh; padding: 16px;"
+			>
+				<div style="width: 360px;">
+					<SelectField v-bind="args" v-model="value" />
+				</div>
+			</div>
+		`,
+	}),
+	args: {
+		label: 'Opcja',
+		placeholder: 'Wybierz opcję',
+		options: LONG_OPTIONS,
+	},
+};
+
+export const Disabled: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		state: FORM_FIELD_STATES.DISABLED,
+	},
+	parameters: {},
+};
+
+export const Error: Story = {
+	...Interactive,
+	args: {
+		...Interactive.args,
+		state: FORM_FIELD_STATES.ERROR,
+		messageText: 'Error message text',
+	},
+	parameters: {},
+};

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

@@ -0,0 +1,65 @@
+import { FormFieldProps, FormFieldSlots } from '../FormField';
+import { IconItem } from '../../Icons/Icon';
+
+/**
+ * reka-ui reserves the empty string for clearing the selection, so `''` must never be
+ * used as an option value. `undefined` (or `''`/`null` coming from a form) renders the
+ * placeholder.
+ */
+export type SelectFieldValue = string | number;
+
+export interface SelectFieldOption {
+	value: SelectFieldValue;
+	label: string;
+	iconLeft?: IconItem | null;
+	eyebrowText?: string;
+	isDisabled?: boolean;
+}
+
+export interface SelectFieldOptionGroup {
+	/**
+	 * When set, the group is rendered as an accessible `role="group"` with this text as its
+	 * accessible name. Groups without a label render their options as direct children of the
+	 * listbox instead.
+	 */
+	label?: string;
+	options: Array<SelectFieldOption>;
+}
+
+export interface SelectFieldProps extends FormFieldProps {
+	options: Array<SelectFieldOption | SelectFieldOptionGroup>;
+	placeholder?: string;
+	leftIcon?: IconItem | null;
+	/**
+	 * Used as `aria-label` when no visible `label` is provided, so the field always has an
+	 * accessible name.
+	 */
+	ariaLabel?: string;
+	/**
+	 * Caps the dropdown height. A `number` is treated as pixels; a string is used as-is, so
+	 * any CSS length works. The dropdown never exceeds the space available in the viewport
+	 * regardless of this value.
+	 *
+	 * @default '320px'
+	 */
+	maxHeight?: string | number;
+	/**
+	 * vee-validate field name. Requires a surrounding `useForm()` context.
+	 */
+	name?: string;
+	/**
+	 * Native `autocomplete` attribute of the visually hidden `<select>` reka renders for form
+	 * autofill (e.g. `'country'`, `'off'`). That element only exists when the field is inside a
+	 * `<form>`, so outside one the prop has no effect.
+	 */
+	autocomplete?: string;
+	/**
+	 * Renders the labels of grouped options in the uppercase section-title style. Set to `false`
+	 * for a lighter, sentence-case label.
+	 *
+	 * @default true
+	 */
+	isGroupLabelUppercase?: boolean;
+}
+
+export type SelectFieldSlots = Omit<FormFieldSlots, 'field'>;

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

@@ -0,0 +1,83 @@
+import { SelectFieldOption, SelectFieldOptionGroup } from './SelectField.types';
+
+export function isSelectFieldOptionGroup(
+	option: SelectFieldOption | SelectFieldOptionGroup,
+): option is SelectFieldOptionGroup {
+	return 'options' in option;
+}
+
+/**
+ * Normalises the mixed options prop into a list of groups, preserving order.
+ * Consecutive ungrouped options collapse into a single group without a label — such a group
+ * renders its options as direct children of the listbox, because an unlabelled reka-ui
+ * `SelectGroup` emits `role="group"` with a dangling `aria-labelledby`.
+ *
+ * Never mutates the `options` prop: synthesised groups own their arrays, and groups passed in
+ * by the consumer are copied before anything is appended to them.
+ */
+export function normalizeOptions(
+	options: Array<SelectFieldOption | SelectFieldOptionGroup>,
+): Array<SelectFieldOptionGroup> {
+	const groups: Array<SelectFieldOptionGroup> = [];
+	// Only a group synthesised here may absorb following ungrouped options.
+	let openGroup: SelectFieldOptionGroup | null = null;
+
+	options.forEach((option) => {
+		if (isSelectFieldOptionGroup(option)) {
+			groups.push({ ...option, options: [...option.options] });
+			openGroup = null;
+
+			return;
+		}
+
+		if (openGroup) {
+			openGroup.options.push(option);
+
+			return;
+		}
+
+		openGroup = { options: [option] };
+		groups.push(openGroup);
+	});
+
+	return groups;
+}
+
+/**
+ * reka-ui throws an opaque error when a `SelectItem` receives an empty string value.
+ * Fail earlier with a message that names the component.
+ */
+export function assertOptionValues(groups: Array<SelectFieldOptionGroup>): void {
+	const hasEmptyValue = groups.some(({ options }) => options.some(({ value }) => value === ''));
+
+	if (hasEmptyValue) {
+		throw new Error(
+			'[SelectField]: An option value must not be an empty string, because an empty string clears the selection.',
+		);
+	}
+}
+
+/**
+ * Resolves a CSS length prop: a `number` is treated as pixels, a string is passed through.
+ * Returns `undefined` for anything that must not reach the style attribute, so `0` still
+ * produces a usable `0px`.
+ */
+export function toCssLength(value: string | number | undefined): string | undefined {
+	if (typeof value === 'number') {
+		return `${value}px`;
+	}
+
+	return value || undefined;
+}
+
+/**
+ * reka-ui names an option after its `SelectItemText`, which only wraps the label, so the
+ * eyebrow text would be dropped from the accessible name. Prepend it so assistive technology
+ * announces everything that is visible.
+ *
+ * Deliberately *not* used for reka-ui's `textValue`: typeahead matches on a prefix, and users
+ * type the label rather than the eyebrow.
+ */
+export function getOptionAccessibleName(option: SelectFieldOption): string {
+	return option.eyebrowText ? `${option.eyebrowText} ${option.label}` : option.label;
+}