@aleph-alpha/ui-library 1.9.0 → 1.11.0

package/src/primitives/UiSelect/__tests__/UiSelectTrigger.test.ts

@@ -0,0 +1,54 @@
+import '@testing-library/jest-dom/vitest';
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue } from '../index';
+
+describe('UiSelectTrigger', () => {
+  test('applies custom class', () => {
+    const { getByRole } = render({
+      components: { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue },
+      template: `
+        <UiSelect>
+          <UiSelectTrigger class="w-[200px]">
+            <UiSelectValue placeholder="Select" />
+          </UiSelectTrigger>
+          <UiSelectContent />
+        </UiSelect>
+      `,
+    });
+
+    expect(getByRole('combobox')).toHaveClass('w-[200px]');
+  });
+
+  test('is disabled when disabled prop is true', () => {
+    const { getByRole } = render({
+      components: { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue },
+      template: `
+        <UiSelect :disabled="true">
+          <UiSelectTrigger>
+            <UiSelectValue placeholder="Select" />
+          </UiSelectTrigger>
+          <UiSelectContent />
+        </UiSelect>
+      `,
+    });
+
+    expect(getByRole('combobox')).toBeDisabled();
+  });
+
+  test('applies aria-label when provided', () => {
+    const { getByRole } = render({
+      components: { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue },
+      template: `
+        <UiSelect>
+          <UiSelectTrigger ariaLabel="Select your preference">
+            <UiSelectValue placeholder="Choose" />
+          </UiSelectTrigger>
+          <UiSelectContent />
+        </UiSelect>
+      `,
+    });
+
+    expect(getByRole('combobox')).toHaveAttribute('aria-label', 'Select your preference');
+  });
+});

package/src/primitives/UiSelect/__tests__/UiSelectValue.test.ts

@@ -0,0 +1,39 @@
+import '@testing-library/jest-dom/vitest';
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue } from '../index';
+
+describe('UiSelectValue', () => {
+  test('displays placeholder when no value is selected', () => {
+    const { getByRole } = render({
+      components: { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue },
+      template: `
+        <UiSelect>
+          <UiSelectTrigger>
+            <UiSelectValue placeholder="Select an option" />
+          </UiSelectTrigger>
+          <UiSelectContent />
+        </UiSelect>
+      `,
+    });
+
+    expect(getByRole('combobox')).toHaveTextContent('Select an option');
+  });
+
+  test('applies custom class', () => {
+    const { container } = render({
+      components: { UiSelect, UiSelectTrigger, UiSelectContent, UiSelectValue },
+      template: `
+        <UiSelect>
+          <UiSelectTrigger>
+            <UiSelectValue placeholder="Select" class="text-muted" />
+          </UiSelectTrigger>
+          <UiSelectContent />
+        </UiSelect>
+      `,
+    });
+
+    const valueElement = container.querySelector('[data-slot="select-value"]');
+    expect(valueElement).toHaveClass('text-muted');
+  });
+});

package/src/primitives/UiSelect/index.ts

@@ -0,0 +1,10 @@
+export { default as UiSelect } from './UiSelect.vue';
+export { default as UiSelectTrigger } from './UiSelectTrigger.vue';
+export { default as UiSelectContent } from './UiSelectContent.vue';
+export { default as UiSelectItem } from './UiSelectItem.vue';
+export { default as UiSelectValue } from './UiSelectValue.vue';
+export { default as UiSelectLabel } from './UiSelectLabel.vue';
+export { default as UiSelectGroup } from './UiSelectGroup.vue';
+export { default as UiSelectSeparator } from './UiSelectSeparator.vue';
+
+export * from './types';

package/src/primitives/UiSelect/types.ts

@@ -0,0 +1,93 @@
+/**
+ * A dropdown select for choosing from a list of options. Use for
+ * form fields where users must pick one value from many.
+ *
+ * @category Form Inputs
+ * @useCases dropdown selection, form picker, option list, country selector
+ * @keywords select, dropdown, picker, option, choice, combobox, form
+ * @related UiDropdownMenu, UiRadioGroup
+ */
+export type UiSelectProps = {
+  /** The controlled value of the select. */
+  modelValue?: string;
+  /** The value when initially rendered (uncontrolled). */
+  defaultValue?: string;
+  /** Whether the select is open by default. */
+  defaultOpen?: boolean;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Whether the select is disabled. */
+  disabled?: boolean;
+  /** Whether the select is required in a form. */
+  required?: boolean;
+  /** The name for form submission. */
+  name?: string;
+  /** Reading direction. */
+  dir?: 'ltr' | 'rtl';
+};
+
+/**
+ * Emits for the UiSelect root component.
+ */
+export type UiSelectEmits = {
+  /** Emitted when the selected value changes. */
+  'update:modelValue': [value: string];
+  /** Emitted when the open state changes. */
+  'update:open': [value: boolean];
+};
+
+/**
+ * Props for the UiSelectTrigger component.
+ */
+export type UiSelectTriggerProps = {
+  /** Accessible label for icon-only triggers. */
+  ariaLabel?: string;
+  /** Whether the trigger is disabled. */
+  disabled?: boolean;
+  /** Size of the trigger. */
+  size?: 'default' | 'sm';
+};
+
+/**
+ * Props for the UiSelectContent component.
+ */
+export type UiSelectContentProps = {
+  /** Preferred side of the trigger. */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  /** Distance from the trigger in pixels. */
+  sideOffset?: number;
+  /** Alignment against the trigger. */
+  align?: 'start' | 'center' | 'end';
+  /** Positioning mode. */
+  position?: 'item-aligned' | 'popper';
+};
+
+/**
+ * Emits for the UiSelectContent component.
+ */
+export type UiSelectContentEmits = {
+  /** Emitted when the Escape key is pressed. */
+  (e: 'escapeKeyDown', event: KeyboardEvent): void;
+  /** Emitted when a pointer down event occurs outside the content. */
+  (e: 'pointerDownOutside', event: Event): void;
+};
+
+/**
+ * Props for the UiSelectItem component.
+ */
+export type UiSelectItemProps = {
+  /** Unique value of the item (required). */
+  value: string;
+  /** Whether the item is disabled. */
+  disabled?: boolean;
+  /** Text for typeahead purposes. */
+  textValue?: string;
+};
+
+/**
+ * Props for the UiSelectValue component.
+ */
+export type UiSelectValueProps = {
+  /** Placeholder when no value is selected. */
+  placeholder?: string;
+};

package/src/primitives/UiSlider/UiSlider.stories.ts

@@ -0,0 +1,226 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref, watch } from 'vue';
+import { UiSlider } from '.';
+
+/**
+ * UiSlider lets users pick a numeric value (single thumb) or a range (multiple thumbs) by dragging.
+ * Use it for filters and settings where immediate, continuous feedback is helpful.
+ */
+const meta: Meta<typeof UiSlider> = {
+  title: 'Primitives/UiSlider',
+  component: UiSlider,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: 'object',
+      description:
+        'Controlled slider value (array of numbers). Use `[value]` for a single thumb and `[min, max]` for a range.',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the slider is disabled.',
+    },
+    min: {
+      control: { type: 'number' },
+      description: 'Minimum value.',
+    },
+    max: {
+      control: { type: 'number' },
+      description: 'Maximum value.',
+    },
+    step: {
+      control: { type: 'number' },
+      description: 'Step size.',
+    },
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Slider orientation.',
+    },
+    inverted: {
+      control: 'boolean',
+      description: 'Whether the slider direction is visually inverted (low/high swapped).',
+    },
+  },
+  args: {
+    modelValue: [50],
+    disabled: false,
+    min: 0,
+    max: 100,
+    step: 1,
+    orientation: 'horizontal',
+    inverted: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof UiSlider>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiSlider } from '@aleph-alpha/ui-library'
+
+const value = ref([50])
+</script>
+
+<template>
+  <div class="w-72 space-y-3">
+    <UiSlider v-model="value" :min="0" :max="100" :step="1" />
+    <div class="text-sm text-muted-foreground">Value: {{ value[0] }}</div>
+  </div>
+</template>`;
+
+/**
+ * Single-thumb slider for selecting a single numeric value.
+ * Use this for settings like volume/zoom/opacity.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiSlider },
+    setup() {
+      const value = ref<number[]>(Array.isArray(args.modelValue) ? args.modelValue : [50]);
+      watch(
+        () => args.modelValue,
+        (val) => {
+          value.value = Array.isArray(val) ? val : [50];
+        },
+      );
+      return { args, value };
+    },
+    template: `
+      <div class="w-72 space-y-3">
+        <UiSlider
+          v-model="value"
+          :disabled="args.disabled"
+          :min="args.min"
+          :max="args.max"
+          :step="args.step"
+          :orientation="args.orientation"
+          :inverted="args.inverted"
+        />
+        <div class="text-sm text-muted-foreground">Value: {{ value }}</div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: defaultTemplateSource } },
+  },
+};
+
+const rangeTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiSlider } from '@aleph-alpha/ui-library'
+
+const range = ref([25, 75])
+</script>
+
+<template>
+  <div class="w-72 space-y-3">
+    <UiSlider v-model="range" :min="0" :max="100" :step="1" :min-steps-between-thumbs="5" />
+    <div class="text-sm text-muted-foreground">Range: {{ range[0] }} – {{ range[1] }}</div>
+  </div>
+</template>`;
+
+/**
+ * Multi-thumb slider for selecting a min/max range.
+ * Use this for filters like price ranges or rating ranges.
+ */
+export const Range: Story = {
+  render: () => ({
+    components: { UiSlider },
+    setup() {
+      const range = ref([25, 75]);
+      return { range };
+    },
+    template: `
+      <div class="w-72 space-y-3">
+        <UiSlider v-model="range" :min="0" :max="100" :step="1" :min-steps-between-thumbs="5" />
+        <div class="text-sm text-muted-foreground">Range: {{ range[0] }} – {{ range[1] }}</div>
+      </div>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: rangeTemplateSource } },
+  },
+};
+
+const verticalTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiSlider } from '@aleph-alpha/ui-library'
+
+const value = ref([50])
+</script>
+
+<template>
+  <div class="flex items-center gap-6">
+    <div class="h-44">
+      <UiSlider v-model="value" orientation="vertical" />
+    </div>
+    <div class="text-sm text-muted-foreground">Value: {{ value[0] }}</div>
+  </div>
+</template>`;
+
+/**
+ * Vertical slider orientation.
+ * Use this when horizontal space is limited or when matching an existing vertical control pattern.
+ */
+export const Vertical: Story = {
+  render: () => ({
+    components: { UiSlider },
+    setup() {
+      const value = ref([50]);
+      return { value };
+    },
+    template: `
+      <div class="flex items-center gap-6">
+        <div class="h-44">
+          <UiSlider v-model="value" orientation="vertical" />
+        </div>
+        <div class="text-sm text-muted-foreground">Value: {{ value[0] }}</div>
+      </div>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: verticalTemplateSource } },
+  },
+};
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiSlider } from '@aleph-alpha/ui-library'
+
+const value = ref([50])
+</script>
+
+<template>
+  <div class="w-72 space-y-3">
+    <UiSlider v-model="value" disabled />
+    <div class="text-sm text-muted-foreground">Value: {{ value[0] }}</div>
+  </div>
+</template>`;
+
+/**
+ * Disabled state.
+ * Use this when the slider is not currently applicable (e.g., gated behind another toggle).
+ */
+export const Disabled: Story = {
+  render: () => ({
+    components: { UiSlider },
+    setup() {
+      const value = ref([50]);
+      return { value };
+    },
+    template: `
+      <div class="w-72 space-y-3">
+        <UiSlider v-model="value" disabled />
+        <div class="text-sm text-muted-foreground">Value: {{ value[0] }}</div>
+      </div>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: disabledTemplateSource } },
+  },
+};

package/src/primitives/UiSlider/UiSlider.vue

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+  import type { SliderRootEmits } from 'reka-ui';
+  import { Slider as ShadcnSlider } from '@/primitives/shadcn/slider';
+  import type { UiSliderProps, UiSliderEmits } from './types';
+
+  defineOptions({
+    name: 'UiSlider',
+  });
+
+  const props = defineProps<UiSliderProps>();
+  const emit = defineEmits<UiSliderEmits>();
+
+  function handleModelValueUpdate(
+    value: SliderRootEmits['update:modelValue'] extends [infer P] ? P : unknown,
+  ) {
+    if (Array.isArray(value) && value.every((v) => typeof v === 'number')) {
+      emit('update:modelValue', value);
+      return;
+    }
+
+    // reka-ui can emit undefined in some cases; keep our public API stable.
+    emit('update:modelValue', []);
+  }
+</script>
+
+<template>
+  <ShadcnSlider
+    :model-value="props.modelValue"
+    :default-value="props.defaultValue"
+    :disabled="props.disabled"
+    :orientation="props.orientation"
+    :dir="props.dir"
+    :inverted="props.inverted"
+    :min="props.min"
+    :max="props.max"
+    :step="props.step"
+    :min-steps-between-thumbs="props.minStepsBetweenThumbs"
+    :thumb-alignment="props.thumbAlignment"
+    :name="props.name"
+    :required="props.required"
+    @update:model-value="handleModelValueUpdate"
+    @value-commit="emit('valueCommit', $event)"
+  />
+</template>

package/src/primitives/UiSlider/__tests__/UiSlider.test.ts

@@ -0,0 +1,76 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test, vi } from 'vitest';
+import { defineComponent, h, ref } from 'vue';
+import { UiSlider } from '../index';
+
+let emitUndefinedPayload = false;
+
+vi.mock('@/primitives/shadcn/slider', () => {
+  return {
+    Slider: defineComponent({
+      name: 'ShadcnSliderMock',
+      emits: ['update:modelValue', 'valueCommit'],
+      setup(_props, { emit }) {
+        return () =>
+          h('button', {
+            type: 'button',
+            onClick: () => {
+              const payload = emitUndefinedPayload ? undefined : [51];
+              emit('update:modelValue', payload);
+              if (!emitUndefinedPayload) {
+                emit('valueCommit', [51]);
+              }
+            },
+          });
+      },
+    }),
+  };
+});
+
+describe('UiSlider', () => {
+  test('re-emits update:modelValue and valueCommit from the vendor slider', async () => {
+    const { container, emitted } = render(UiSlider, {
+      props: { modelValue: [50] },
+    });
+
+    const button = container.querySelector('button');
+    expect(button).toBeInTheDocument();
+    await (button as HTMLButtonElement).click();
+
+    expect(emitted('update:modelValue')?.[0]).toEqual([[51]]);
+    expect(emitted('valueCommit')?.[0]).toEqual([[51]]);
+  });
+
+  test('normalizes invalid update:modelValue payloads to an empty array', async () => {
+    emitUndefinedPayload = true;
+    const { container, emitted } = render(UiSlider);
+    const button = container.querySelector('button');
+    expect(button).toBeInTheDocument();
+    await (button as HTMLButtonElement).click();
+
+    expect(emitted('update:modelValue')?.[0]).toEqual([[]]);
+    emitUndefinedPayload = false;
+  });
+
+  test('supports controlled mode via v-model:modelValue', async () => {
+    const { container, getByText } = render({
+      components: { UiSlider },
+      setup() {
+        const value = ref([50]);
+        return { value };
+      },
+      template: `
+        <div>
+          <div>Value: {{ value[0] }}</div>
+          <UiSlider v-model:modelValue="value" />
+        </div>
+      `,
+    });
+
+    const button = container.querySelector('button');
+    expect(button).toBeInTheDocument();
+    await (button as HTMLButtonElement).click();
+
+    expect(getByText('Value: 51')).toBeInTheDocument();
+  });
+});

package/src/primitives/UiSlider/index.ts

@@ -0,0 +1 @@
+export { default as UiSlider } from './UiSlider.vue';

package/src/primitives/UiSlider/types.ts

@@ -0,0 +1,101 @@
+/**
+ * A range input for selecting numeric values by dragging a thumb along a track.
+ * Supports single-thumb sliders via `[value]` and multi-thumb sliders via `[min, max]`.
+ *
+ * @category Form Inputs
+ * @useCases volume control, price range, numeric input, filter range
+ * @keywords slider, range, input, thumb, track, numeric
+ * @related UiInput
+ */
+export interface UiSliderProps {
+  /**
+   * The controlled value of the slider.
+   * Use `v-model` / `v-model:modelValue` for controlled mode.
+   */
+  modelValue?: number[];
+
+  /**
+   * The value of the slider when initially rendered (uncontrolled).
+   * @default [0]
+   */
+  defaultValue?: number[];
+
+  /**
+   * When `true`, prevents the user from interacting with the slider.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * The orientation of the slider.
+   * @default 'horizontal'
+   */
+  orientation?: 'horizontal' | 'vertical';
+
+  /**
+   * The reading direction.
+   * @default 'ltr'
+   */
+  dir?: 'ltr' | 'rtl';
+
+  /**
+   * Whether the slider is visually inverted.
+   * @default false
+   */
+  inverted?: boolean;
+
+  /**
+   * The minimum value for the range.
+   * @default 0
+   */
+  min?: number;
+
+  /**
+   * The maximum value for the range.
+   * @default 100
+   */
+  max?: number;
+
+  /**
+   * The stepping interval.
+   * @default 1
+   */
+  step?: number;
+
+  /**
+   * The minimum permitted steps between multiple thumbs.
+   * @default 0
+   */
+  minStepsBetweenThumbs?: number;
+
+  /**
+   * Slider thumb alignment.
+   * - `contain`: thumbs are contained within the track bounds.
+   * - `overflow`: thumbs can overflow the track bounds.
+   * @default 'contain'
+   */
+  thumbAlignment?: 'contain' | 'overflow';
+
+  /**
+   * Optional form field name (only relevant when used inside a form).
+   */
+  name?: string;
+
+  /**
+   * Whether the form field is required.
+   * @default false
+   */
+  required?: boolean;
+}
+
+export interface UiSliderEmits {
+  /**
+   * Emitted when the slider value changes.
+   */
+  (e: 'update:modelValue', value: number[]): void;
+
+  /**
+   * Emitted when the value changes at the end of an interaction (commit).
+   */
+  (e: 'valueCommit', value: number[]): void;
+}