@aleph-alpha/ui-library 1.12.0 → 1.14.0

package/src/components/UiSlider/types.ts

@@ -0,0 +1,100 @@
+/**
+ * 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;
+}

package/src/components/UiSpinner/UiSpinner.stories.ts

@@ -0,0 +1,143 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiSpinner from './UiSpinner.vue';
+
+const meta: Meta<typeof UiSpinner> = {
+  title: 'Components/UiSpinner',
+  component: UiSpinner,
+  tags: ['autodocs'],
+  argTypes: {
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label for the spinner (announced by screen readers)',
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes to apply to the spinner',
+    },
+  },
+  args: {
+    ariaLabel: 'Loading',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiSpinner>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiSpinner } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiSpinner />
+</template>`;
+
+/**
+ * Default spinner with standard size.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiSpinner },
+    setup() {
+      return { args };
+    },
+    template: '<UiSpinner :aria-label="args.ariaLabel" :class="args.class" />',
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const sizesTemplateSource = `<script setup lang="ts">
+import { UiSpinner } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex items-end gap-6">
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">default</span>
+      <UiSpinner />
+    </div>
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">size-6</span>
+      <UiSpinner class="size-6" />
+    </div>
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">size-8</span>
+      <UiSpinner class="size-8" />
+    </div>
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">size-12</span>
+      <UiSpinner class="size-12" />
+    </div>
+  </div>
+</template>`;
+
+/**
+ * Spinner sizes using Tailwind classes. Default is size-4.
+ */
+export const Sizes: Story = {
+  render: () => ({
+    components: { UiSpinner },
+    template: `<div class="flex items-end gap-6">
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">default</span>
+        <UiSpinner />
+      </div>
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">size-6</span>
+        <UiSpinner class="size-6" />
+      </div>
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">size-8</span>
+        <UiSpinner class="size-8" />
+      </div>
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">size-12</span>
+        <UiSpinner class="size-12" />
+      </div>
+    </div>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: sizesTemplateSource,
+      },
+    },
+  },
+};
+
+const inlineTemplateSource = `<script setup lang="ts">
+import { UiSpinner } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex items-center gap-2">
+    <UiSpinner />
+    <span>Loading...</span>
+  </div>
+</template>`;
+
+/**
+ * Spinner used inline with text.
+ */
+export const InlineWithText: Story = {
+  render: () => ({
+    components: { UiSpinner },
+    template: `<div class="flex items-center gap-2">
+      <UiSpinner />
+      <span>Loading...</span>
+    </div>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: inlineTemplateSource,
+      },
+    },
+  },
+};

package/src/components/UiSpinner/UiSpinner.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+  import { Spinner as ShadcnSpinner } from '@/components/core/spinner';
+  import type { UiSpinnerProps } from './types';
+
+  defineOptions({
+    name: 'UiSpinner',
+  });
+
+  const props = withDefaults(defineProps<UiSpinnerProps>(), {
+    ariaLabel: 'Loading',
+  });
+</script>
+
+<template>
+  <ShadcnSpinner :aria-label="props.ariaLabel" />
+</template>

package/src/components/UiSpinner/types.ts

@@ -0,0 +1,15 @@
+/**
+ * An animated loading indicator. Use while content is loading
+ * or an action is processing.
+ * @category Feedback
+ * @useCases loading state, processing, waiting, fetching data
+ * @keywords spinner, loading, loader, wait, progress, animation
+ * @related UiProgress
+ */
+export interface UiSpinnerProps {
+  /**
+   * Accessible label for the spinner.
+   * @default 'Loading'
+   */
+  ariaLabel?: string;
+}

package/src/components/UiStepper/UiStepper.stories.ts

@@ -0,0 +1,425 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref, watch } from 'vue';
+import {
+  UiStepper,
+  UiStepperItem,
+  UiStepperTrigger,
+  UiStepperIndicator,
+  UiStepperTitle,
+  UiStepperDescription,
+  UiStepperSeparator,
+} from './index';
+import { UiIcon } from '../UiIcon';
+
+const meta: Meta<typeof UiStepper> = {
+  title: 'Primitives/UiStepper',
+  component: UiStepper,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: 'number',
+      description: 'The controlled value of the active step (use with v-model)',
+    },
+    defaultValue: {
+      control: 'number',
+    },
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+    },
+    linear: {
+      control: 'boolean',
+      description:
+        'Whether navigation must be sequential (user cannot skip ahead to incomplete steps)',
+    },
+  },
+  args: {
+    orientation: 'horizontal',
+    linear: true,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiStepper>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiStepper,
+  UiStepperItem,
+  UiStepperTrigger,
+  UiStepperIndicator,
+  UiStepperTitle,
+  UiStepperDescription,
+  UiStepperSeparator,
+  UiIcon,
+} from '@aleph-alpha/ui-library'
+
+const currentStep = ref(1)
+
+const steps = [
+  { step: 1, title: 'Address', description: 'Add your address', icon: 'book-user' },
+  { step: 2, title: 'Shipping', description: 'Set your preferred', icon: 'truck' },
+  { step: 3, title: 'Payment', description: 'Add any payment', icon: 'credit-card' },
+  { step: 4, title: 'Checkout', description: 'Confirm your order' },
+]
+</script>
+
+<template>
+  <UiStepper v-model="currentStep" class="flex w-full items-start gap-2">
+    <UiStepperItem
+      v-for="item in steps"
+      :key="item.step"
+      :step="item.step"
+      class="relative flex w-full flex-col items-center justify-center"
+    >
+      <UiStepperTrigger>
+        <UiStepperIndicator class="">
+          <UiIcon v-if="item.icon" :name="item.icon" :size="16" />
+          <span v-else>{{ item.step }}</span>
+        </UiStepperIndicator>
+      </UiStepperTrigger>
+      <UiStepperSeparator
+        v-if="item.step !== steps[steps.length - 1]?.step"
+      />
+      <div class="flex flex-col items-center">
+        <UiStepperTitle>{{ item.title }}</UiStepperTitle>
+        <UiStepperDescription>{{ item.description }}</UiStepperDescription>
+      </div>
+    </UiStepperItem>
+  </UiStepper>
+</template>`;
+
+/**
+ * Default stepper with icon indicators for each step. Steps without an icon
+ * fall back to displaying the step number. Use for multi-step workflows like
+ * checkout flows or onboarding sequences.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: {
+      UiStepper,
+      UiStepperItem,
+      UiStepperTrigger,
+      UiStepperIndicator,
+      UiStepperTitle,
+      UiStepperDescription,
+      UiStepperSeparator,
+      UiIcon,
+    },
+    setup() {
+      const currentStep = ref(args.modelValue ?? 1);
+      watch(
+        () => args.modelValue,
+        (val) => {
+          if (val != null) currentStep.value = val;
+        },
+      );
+      const steps = [
+        { step: 1, title: 'Address', description: 'Add your address', icon: 'book-user' },
+        { step: 2, title: 'Shipping', description: 'Set your preferred', icon: 'truck' },
+        { step: 3, title: 'Payment', description: 'Add any payment', icon: 'credit-card' },
+        { step: 4, title: 'Checkout', description: 'Confirm your order' },
+      ];
+      return { args, currentStep, steps };
+    },
+    template: `
+      <UiStepper
+        v-model="currentStep"
+        :orientation="args.orientation"
+        :linear="args.linear"
+        :class="args.orientation === 'vertical'
+          ? 'mx-auto flex w-full max-w-md flex-col justify-start gap-10'
+          : 'flex w-full items-start gap-2'"
+      >
+        <UiStepperItem
+          v-for="item in steps"
+          :key="item.step"
+          :step="item.step"
+          :class="args.orientation === 'vertical'
+            ? 'relative flex w-full items-start justify-start gap-6'
+            : 'relative flex w-full flex-col items-center justify-center'"
+        >
+          <UiStepperTrigger>
+            <UiStepperIndicator>
+              <UiIcon v-if="item.icon" :name="item.icon" :size="16" />
+              <span v-else>{{ item.step }}</span>
+            </UiStepperIndicator>
+          </UiStepperTrigger>
+          <UiStepperSeparator
+            v-if="item.step !== steps[steps.length - 1]?.step"
+          />
+          <div :class="args.orientation === 'vertical' ? 'flex flex-col gap-1' : 'flex flex-col items-center'">
+            <UiStepperTitle>{{ item.title }}</UiStepperTitle>
+            <UiStepperDescription>{{ item.description }}</UiStepperDescription>
+          </div>
+        </UiStepperItem>
+      </UiStepper>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const horizontalTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiStepper,
+  UiStepperItem,
+  UiStepperTrigger,
+  UiStepperIndicator,
+  UiStepperTitle,
+  UiStepperDescription,
+  UiStepperSeparator,
+  UiIcon,
+} from '@aleph-alpha/ui-library'
+
+const currentStep = ref(1)
+
+const steps = [
+  { step: 1, title: 'Your details', description: 'Provide your name and email' },
+  { step: 2, title: 'Company details', description: 'A few details about your company' },
+  { step: 3, title: 'Invite your team', description: 'Start collaborating with your team' },
+]
+</script>
+
+<template>
+  <UiStepper v-model="currentStep" :linear="true" class="flex w-full items-start gap-2">
+    <UiStepperItem
+      v-for="step in steps"
+      :key="step.step"
+      v-slot="{ state }"
+      :step="step.step"
+      class="relative flex w-full flex-col items-center justify-center"
+    >
+      <UiStepperTrigger>
+        <UiStepperIndicator
+          :class="[
+            state === 'completed' && 'bg-[oklch(var(--background-accent-default))] group-data-[state=completed]:text-content-on-accent-default',
+            state === 'inactive' && 'bg-transparent border-2 border-content-on-surface-muted/30',
+          ]"
+        >
+          <UiIcon v-if="state === 'completed'" name="check" class="size-5" />
+          <UiIcon v-if="state === 'active'" name="circle" class="size-4" />
+          <UiIcon v-if="state === 'inactive'" name="dot" class="size-4" />
+        </UiStepperIndicator>
+      </UiStepperTrigger>
+      <UiStepperSeparator
+        v-if="step.step !== steps[steps.length - 1]?.step"
+      />
+      <div class="flex flex-col items-center text-center">
+        <UiStepperTitle>{{ step.title }}</UiStepperTitle>
+        <UiStepperDescription>{{ step.description }}</UiStepperDescription>
+      </div>
+    </UiStepperItem>
+  </UiStepper>
+</template>`;
+
+/**
+ * Horizontal stepper with check/circle/dot icons. Completed and active steps
+ * show a filled blue indicator, inactive steps show an outlined circle.
+ */
+export const Horizontal: Story = {
+  render: () => ({
+    components: {
+      UiStepper,
+      UiStepperItem,
+      UiStepperTrigger,
+      UiStepperIndicator,
+      UiStepperTitle,
+      UiStepperDescription,
+      UiStepperSeparator,
+      UiIcon,
+    },
+    setup() {
+      const currentStep = ref(1);
+      const steps = [
+        { step: 1, title: 'Your details', description: 'Provide your name and email' },
+        {
+          step: 2,
+          title: 'Company details',
+          description: 'A few details about your company',
+        },
+        {
+          step: 3,
+          title: 'Invite your team',
+          description: 'Start collaborating with your team',
+        },
+      ];
+      return { currentStep, steps };
+    },
+    template: `
+      <UiStepper v-model="currentStep" :linear="true" class="flex w-full items-start gap-2">
+        <UiStepperItem
+          v-for="step in steps"
+          :key="step.step"
+          v-slot="{ state }"
+          :step="step.step"
+          class="relative flex w-full flex-col items-center justify-center"
+        >
+          <UiStepperTrigger>
+            <UiStepperIndicator
+              :class="[
+                state === 'completed' && 'bg-[oklch(var(--background-accent-default))] group-data-[state=completed]:text-content-on-accent-default',
+                state === 'inactive' && 'bg-transparent border-2 border-content-on-surface-muted/30',
+              ]"
+            >
+              <UiIcon v-if="state === 'completed'" name="check" class="size-5" />
+              <UiIcon v-if="state === 'active'" name="circle" class="size-4" />
+              <UiIcon v-if="state === 'inactive'" name="dot" class="size-4" />
+            </UiStepperIndicator>
+          </UiStepperTrigger>
+          <UiStepperSeparator
+            v-if="step.step !== steps[steps.length - 1]?.step"
+          />
+          <div class="flex flex-col items-center text-center">
+            <UiStepperTitle>{{ step.title }}</UiStepperTitle>
+            <UiStepperDescription>{{ step.description }}</UiStepperDescription>
+          </div>
+        </UiStepperItem>
+      </UiStepper>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: horizontalTemplateSource,
+      },
+    },
+  },
+};
+
+const verticalTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiStepper,
+  UiStepperItem,
+  UiStepperTrigger,
+  UiStepperIndicator,
+  UiStepperTitle,
+  UiStepperDescription,
+  UiStepperSeparator,
+  UiIcon,
+} from '@aleph-alpha/ui-library'
+
+const currentStep = ref(1)
+
+const steps = [
+  { step: 1, title: 'Your details', description: 'Provide your name and email' },
+  { step: 2, title: 'Company details', description: 'A few details about your company' },
+  { step: 3, title: 'Invite your team', description: 'Start collaborating with your team' },
+]
+</script>
+
+<template>
+  <UiStepper v-model="currentStep" orientation="vertical" :linear="true" class="mx-auto flex w-full max-w-md flex-col justify-start gap-10">
+    <UiStepperItem
+      v-for="step in steps"
+      :key="step.step"
+      v-slot="{ state }"
+      :step="step.step"
+      class="relative flex w-full items-start justify-start gap-6"
+    >
+      <UiStepperTrigger>
+        <UiStepperIndicator
+          :class="[
+            state === 'completed' && 'bg-[oklch(var(--background-accent-default))] group-data-[state=completed]:text-content-on-accent-default',
+            state === 'inactive' && 'bg-transparent border-2 border-content-on-surface-muted/30',
+          ]"
+        >
+          <UiIcon v-if="state === 'completed'" name="check" class="size-5" />
+          <UiIcon v-if="state === 'active'" name="circle" class="size-4" />
+          <UiIcon v-if="state === 'inactive'" name="dot" class="size-4" />
+        </UiStepperIndicator>
+      </UiStepperTrigger>
+      <UiStepperSeparator
+        v-if="step.step !== steps[steps.length - 1]?.step"
+      />
+      <div class="flex flex-col gap-1">
+        <UiStepperTitle>{{ step.title }}</UiStepperTitle>
+        <UiStepperDescription>{{ step.description }}</UiStepperDescription>
+      </div>
+    </UiStepperItem>
+  </UiStepper>
+</template>`;
+
+/**
+ * Vertical stepper with check/circle/dot icons. Uses the same indicator
+ * pattern as Horizontal but with vertical layout and connecting lines
+ * running top-to-bottom.
+ */
+export const Vertical: Story = {
+  render: () => ({
+    components: {
+      UiStepper,
+      UiStepperItem,
+      UiStepperTrigger,
+      UiStepperIndicator,
+      UiStepperTitle,
+      UiStepperDescription,
+      UiStepperSeparator,
+      UiIcon,
+    },
+    setup() {
+      const currentStep = ref(1);
+      const steps = [
+        { step: 1, title: 'Your details', description: 'Provide your name and email' },
+        {
+          step: 2,
+          title: 'Company details',
+          description: 'A few details about your company',
+        },
+        {
+          step: 3,
+          title: 'Invite your team',
+          description: 'Start collaborating with your team',
+        },
+      ];
+      return { currentStep, steps };
+    },
+    template: `
+      <UiStepper v-model="currentStep" orientation="vertical" :linear="true" class="mx-auto flex w-full max-w-md flex-col justify-start gap-10">
+        <UiStepperItem
+          v-for="step in steps"
+          :key="step.step"
+          v-slot="{ state }"
+          :step="step.step"
+          class="relative flex w-full items-start justify-start gap-6"
+        >
+          <UiStepperTrigger>
+            <UiStepperIndicator
+              :class="[
+                state === 'completed' && 'bg-[oklch(var(--background-accent-default))] group-data-[state=completed]:text-content-on-accent-default',
+                state === 'inactive' && 'bg-transparent border-2 border-content-on-surface-muted/30',
+              ]"
+            >
+              <UiIcon v-if="state === 'completed'" name="check" class="size-5" />
+              <UiIcon v-if="state === 'active'" name="circle" class="size-4" />
+              <UiIcon v-if="state === 'inactive'" name="dot" class="size-4" />
+            </UiStepperIndicator>
+          </UiStepperTrigger>
+          <UiStepperSeparator
+            v-if="step.step !== steps[steps.length - 1]?.step"
+          />
+          <div class="flex flex-col gap-1">
+            <UiStepperTitle>{{ step.title }}</UiStepperTitle>
+            <UiStepperDescription>{{ step.description }}</UiStepperDescription>
+          </div>
+        </UiStepperItem>
+      </UiStepper>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: verticalTemplateSource,
+      },
+    },
+  },
+};