@aleph-alpha/ui-library 1.12.0 → 1.14.0

package/src/components/UiPopover/types.ts

@@ -0,0 +1,98 @@
+/** The preferred side of the trigger to render the popover. */
+export type UiPopoverSide = 'top' | 'right' | 'bottom' | 'left';
+/** The preferred alignment against the trigger. */
+export type UiPopoverAlign = 'start' | 'center' | 'end';
+
+/**
+ * A floating panel that appears relative to a trigger element. Use for
+ * rich content like forms, pickers, or detailed information.
+ * @category Overlays
+ * @useCases floating panel, picker container, form popup, info panel
+ * @keywords popover, popup, floating, panel, overlay, dropdown
+ * @related UiTooltip, UiDropdownMenu
+ */
+export interface UiPopoverProps {
+  /**
+   * The controlled open state of the popover.
+   * - Omit for uncontrolled mode (component manages state internally)
+   * - Use `v-model:open` for controlled mode
+   * @example
+   * ```vue
+   * <!-- Uncontrolled (component manages state) -->
+   * <UiPopover>...</UiPopover>
+   *
+   * <!-- Controlled (parent manages state) -->
+   * <UiPopover v-model:open="isOpen">...</UiPopover>
+   * ```
+   */
+  open?: boolean;
+
+  /**
+   * The modality of the popover.
+   *
+   * When set to `true`:
+   * - Interaction with outside elements is disabled (outside clicks won't trigger underlying UI)
+   * - Focus is trapped within the popover while open
+   * - Only popover content is visible to screen readers
+   *
+   * Note: The popover is still **dismissed on outside click**. `modal` controls outside interaction,
+   * not whether the popover closes.
+   * @default false
+   */
+  modal?: boolean;
+}
+
+/**
+ * Props for the UiPopoverTrigger component.
+ * The element that opens the popover when clicked.
+ */
+export interface UiPopoverTriggerProps {
+  /**
+   * Accessible label for the trigger button.
+   * **REQUIRED** when trigger contains only icons or images (no visible text).
+   * Applied as `aria-label` attribute.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Render as child element (merges props into slotted element instead of wrapping).
+   * Set to `true` when using custom button components like `UiButton` or `UiIconButton`.
+   * @default false
+   */
+  asChild?: boolean;
+}
+
+/**
+ * Props for the UiPopoverContent component.
+ * The floating container for popover content.
+ */
+export interface UiPopoverContentProps {
+  /**
+   * The preferred side of the trigger to render against when open.
+   * @default 'bottom'
+   */
+  side?: UiPopoverSide;
+
+  /**
+   * The distance in pixels from the trigger.
+   * @default 4
+   */
+  sideOffset?: number;
+
+  /**
+   * The preferred alignment against the trigger.
+   * @default 'center'
+   */
+  align?: UiPopoverAlign;
+}
+
+/**
+ * Emits for the UiPopoverContent component.
+ */
+export interface UiPopoverContentEmits {
+  /**
+   * Event emitted when the escape key is pressed.
+   * Can be used to prevent closing or add custom behavior.
+   */
+  (e: 'escapeKeyDown', event: KeyboardEvent): void;
+}

package/src/components/UiProgress/UiProgress.stories.ts

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiProgress from './UiProgress.vue';
+
+const meta: Meta<typeof UiProgress> = {
+  title: 'Components/UiProgress',
+  component: UiProgress,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: { type: 'number', min: 0, max: 100 },
+      description: 'The current progress value.',
+    },
+    max: {
+      control: { type: 'number', min: 1 },
+      description: 'The maximum value of the progress bar.',
+    },
+  },
+  args: {
+    modelValue: 33,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiProgress>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiProgress } from '@aleph-alpha/ui-library'
+
+const progress = ref(33)
+</script>
+
+<template>
+  <UiProgress v-model="progress" />
+</template>`;
+
+/**
+ * A basic progress bar displaying current progress.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiProgress },
+    setup() {
+      return { args };
+    },
+    template: '<UiProgress :model-value="args.modelValue" :max="args.max" class="w-60" />',
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const customMaxTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiProgress } from '@aleph-alpha/ui-library'
+
+const progress = ref(75)
+const max = 200
+</script>
+
+<template>
+  <UiProgress v-model="progress" :max="max" />
+</template>`;
+
+/**
+ * Progress bar with a custom maximum value. Here, progress is 75 out of 200.
+ */
+export const CustomMax: Story = {
+  render: (args) => ({
+    components: { UiProgress },
+    setup() {
+      return { args };
+    },
+    template: '<UiProgress :model-value="args.modelValue" :max="args.max" class="w-60" />',
+  }),
+  args: {
+    modelValue: 75,
+    max: 200,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: customMaxTemplateSource,
+      },
+    },
+  },
+};

package/src/components/UiProgress/UiProgress.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+  import { computed } from 'vue';
+  import { Progress as ShadcnProgress } from '@/components/core/progress';
+  import { UiProgressProps } from './types';
+
+  defineOptions({
+    name: 'UiProgress',
+  });
+
+  const props = withDefaults(defineProps<UiProgressProps>(), {
+    max: 100,
+  });
+
+  const model = defineModel<number>({
+    default: 0,
+  });
+
+  const currentProgress = computed(() => {
+    return model.value > props.max ? props.max : model.value;
+  });
+</script>
+
+<template>
+  <ShadcnProgress :model-value="currentProgress" :max />
+</template>

package/src/components/UiProgress/types.ts

@@ -0,0 +1,15 @@
+/**
+ * A progress bar showing completion status. Use for uploads,
+ * downloads, loading states, or any task with measurable progress.
+ * @category Feedback
+ * @useCases upload progress, download status, loading bar, completion indicator
+ * @keywords progress, bar, loading, percentage, status, completion
+ * @related UiSpinner
+ */
+export type UiProgressProps = {
+  /**
+   * Max value of the Progress.
+   * @default 100
+   */
+  max?: number;
+};

package/src/components/UiRadioGroup/UiRadioGroup.stories.ts

@@ -0,0 +1,291 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { UiRadioGroup, UiRadioGroupItem } from './index';
+import { ref, watch } from 'vue';
+
+const meta: Meta<typeof UiRadioGroup> = {
+  title: 'Components/UiRadioGroup',
+  component: UiRadioGroup,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: 'select',
+      options: ['default', 'comfortable', 'compact'],
+      description: 'The selected value',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disable the entire radio group',
+    },
+    orientation: {
+      control: 'select',
+      options: ['vertical', 'horizontal'],
+      description: 'The orientation of the radio group',
+    },
+  },
+  args: {
+    name: 'radio-group',
+    modelValue: 'comfortable',
+    disabled: false,
+    orientation: 'vertical',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiRadioGroup>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiRadioGroup, UiRadioGroupItem } from '@aleph-alpha/ui-library'
+
+const selected = ref('comfortable')
+</script>
+
+<template>
+  <UiRadioGroup v-model="selected" name="spacing">
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r1" value="default" />
+      <label for="r1" class="text-sm font-medium">Default</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r2" value="comfortable" />
+      <label for="r2" class="text-sm font-medium">Comfortable</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r3" value="compact" />
+      <label for="r3" class="text-sm font-medium">Compact</label>
+    </div>
+  </UiRadioGroup>
+</template>`;
+
+/**
+ * Default radio group with three options.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiRadioGroup, UiRadioGroupItem },
+    setup() {
+      const selected = ref(args.modelValue);
+      watch(
+        () => args.modelValue,
+        (val) => {
+          selected.value = val;
+        },
+      );
+      return { args, selected };
+    },
+    template: `
+      <UiRadioGroup v-model="selected" name="spacing" :disabled="args.disabled" :orientation="args.orientation">
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r1" value="default" />
+          <label for="r1" class="text-sm font-medium">Default</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r2" value="comfortable" />
+          <label for="r2" class="text-sm font-medium">Comfortable</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r3" value="compact" />
+          <label for="r3" class="text-sm font-medium">Compact</label>
+        </div>
+      </UiRadioGroup>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiRadioGroup, UiRadioGroupItem } from '@aleph-alpha/ui-library'
+
+const selected = ref('default')
+</script>
+
+<template>
+  <UiRadioGroup v-model="selected" name="spacing">
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r1" value="default" />
+      <label for="r1" class="text-sm font-medium">Default</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r2" value="comfortable" disabled />
+      <label for="r2" class="text-sm font-medium text-muted-foreground">Comfortable</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r3" value="compact" />
+      <label for="r3" class="text-sm font-medium">Compact</label>
+    </div>
+  </UiRadioGroup>
+</template>`;
+
+/**
+ * Radio group with a disabled item.
+ */
+export const Disabled: Story = {
+  render: (args) => ({
+    components: { UiRadioGroup, UiRadioGroupItem },
+    setup() {
+      const selected = ref('default');
+      return { args, selected };
+    },
+    template: `
+      <UiRadioGroup v-model="selected" name="spacing" :orientation="args.orientation">
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r1" value="default" />
+          <label for="r1" class="text-sm font-medium">Default</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r2" value="comfortable" disabled />
+          <label for="r2" class="text-sm font-medium text-muted-foreground">Comfortable</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r3" value="compact" />
+          <label for="r3" class="text-sm font-medium">Compact</label>
+        </div>
+      </UiRadioGroup>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: disabledTemplateSource,
+      },
+    },
+  },
+};
+
+const horizontalTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiRadioGroup, UiRadioGroupItem } from '@aleph-alpha/ui-library'
+
+const selected = ref('small')
+</script>
+
+<template>
+  <UiRadioGroup v-model="selected" name="size" orientation="horizontal">
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r1" value="small" />
+      <label for="r1" class="text-sm font-medium">Small</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r2" value="medium" />
+      <label for="r2" class="text-sm font-medium">Medium</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <UiRadioGroupItem id="r3" value="large" />
+      <label for="r3" class="text-sm font-medium">Large</label>
+    </div>
+  </UiRadioGroup>
+</template>`;
+
+/**
+ * Radio group with horizontal orientation.
+ * Items are laid out horizontally and can be navigated using Left/Right arrow keys.
+ */
+export const HorizontalOrientation: Story = {
+  args: {
+    orientation: 'horizontal',
+    modelValue: 'small',
+  },
+  render: (args) => ({
+    components: { UiRadioGroup, UiRadioGroupItem },
+    setup() {
+      const selected = ref(args.modelValue);
+      watch(
+        () => args.modelValue,
+        (val) => {
+          selected.value = val;
+        },
+      );
+      return { args, selected };
+    },
+    template: `
+      <UiRadioGroup v-model="selected" name="size" :orientation="args.orientation">
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r1" value="small" />
+          <label for="r1" class="text-sm font-medium">Small</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r2" value="medium" />
+          <label for="r2" class="text-sm font-medium">Medium</label>
+        </div>
+        <div class="flex items-center space-x-2">
+          <UiRadioGroupItem id="r3" value="large" />
+          <label for="r3" class="text-sm font-medium">Large</label>
+        </div>
+      </UiRadioGroup>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: horizontalTemplateSource,
+      },
+    },
+  },
+};
+
+const asChildTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiRadioGroup, UiRadioGroupItem } from '@aleph-alpha/ui-library'
+
+const selected = ref('default')
+</script>
+
+<template>
+  <UiRadioGroup v-model="selected" name="options" as-child>
+    <fieldset class="rounded-lg border p-4">
+      <legend class="px-2 text-sm font-medium">Select an option</legend>
+      <div class="flex items-center space-x-2">
+        <UiRadioGroupItem id="r1" value="default" />
+        <label for="r1" class="text-sm font-medium">Default</label>
+      </div>
+      <div class="flex items-center space-x-2">
+        <UiRadioGroupItem id="r2" value="second" />
+        <label for="r2" class="text-sm font-medium">Second</label>
+      </div>
+    </fieldset>
+  </UiRadioGroup>
+</template>`;
+
+/**
+ * Radio group with as-child prop.
+ * The radio group merges its props into the slotted element instead of wrapping it.
+ */
+export const AsChild: Story = {
+  render: (args) => ({
+    components: { UiRadioGroup, UiRadioGroupItem },
+    setup() {
+      const selected = ref('default');
+      return { args, selected };
+    },
+    template: `
+      <UiRadioGroup v-model="selected" name="options" as-child>
+        <fieldset class="rounded-lg border p-4">
+          <legend class="px-2 text-sm font-medium">Select an option</legend>
+          <div class="flex items-center space-x-2">
+            <UiRadioGroupItem id="r1" value="default" />
+            <label for="r1" class="text-sm font-medium">Default</label>
+          </div>
+          <div class="flex items-center space-x-2">
+            <UiRadioGroupItem id="r2" value="second" />
+            <label for="r2" class="text-sm font-medium">Second</label>
+          </div>
+        </fieldset>
+      </UiRadioGroup>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: asChildTemplateSource,
+      },
+    },
+  },
+};

package/src/components/UiRadioGroup/UiRadioGroup.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+  import { computed } from 'vue';
+  import { cn } from '@/lib/utils';
+  import { RadioGroup as ShadcnRadioGroup } from '@/components/core/radio-group';
+  import { UiRadioGroupProps } from './types';
+
+  defineOptions({
+    name: 'UiRadioGroup',
+  });
+
+  const props = withDefaults(defineProps<UiRadioGroupProps>(), {
+    asChild: false,
+    disabled: false,
+    required: false,
+    orientation: 'vertical',
+    dir: 'ltr',
+    loop: true,
+  });
+
+  const model = defineModel<string>({
+    required: false,
+  });
+
+  const orientationClass = computed(() =>
+    cn(props.orientation === 'horizontal' ? 'flex flex-wrap gap-3' : 'grid gap-3'),
+  );
+</script>
+
+<template>
+  <ShadcnRadioGroup
+    v-model="model"
+    :name
+    :disabled
+    :required
+    :as-child
+    :orientation
+    :dir
+    :loop
+    :class="orientationClass"
+  >
+    <slot />
+  </ShadcnRadioGroup>
+</template>

package/src/components/UiRadioGroup/UiRadioGroupItem.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+  import { RadioGroupItem as ShadcnRadioGroupItem } from '@/components/core/radio-group';
+  import { UiRadioGroupItemProps } from './types';
+
+  defineOptions({
+    name: 'UiRadioGroupItem',
+  });
+
+  const props = withDefaults(defineProps<UiRadioGroupItemProps>(), {
+    asChild: false,
+    disabled: false,
+    required: false,
+  });
+</script>
+
+<template>
+  <ShadcnRadioGroupItem :id :disabled :required :as-child :value />
+</template>

package/src/components/UiRadioGroup/types.ts

@@ -0,0 +1,71 @@
+/** The orientation of the radio group (vertical or horizontal). */
+export type UiRadioGroupOrientation = 'vertical' | 'horizontal';
+/** The reading direction of the radio group. */
+export type UiRadioGroupDirection = 'ltr' | 'rtl';
+
+/**
+ * Shared props between `UiRadioGroup` and `UiRadioGroupItem`.
+ * Note: `name` belongs to the group only.
+ */
+export type UiRadioGroupSharedProps = {
+  /**
+   * Render as child element (merges props into slotted element instead of wrapping).
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Whether the component is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Whether the component is required.
+   * @default false
+   */
+  required?: boolean;
+};
+
+/**
+ * A group of radio buttons for single-choice selection. Use when users
+ * must pick exactly one option from a visible list.
+ * @category Form Inputs
+ * @useCases single choice, option selection, survey question, settings
+ * @keywords radio, radiogroup, option, choice, single, select, form
+ * @related UiCheckbox, UiSelect
+ */
+export type UiRadioGroupProps = UiRadioGroupSharedProps & {
+  /**
+   * The name attribute applied to the radio group.
+   */
+  name: string;
+  /**
+   * The orientation of the radio group.
+   * @default vertical
+   */
+  orientation?: UiRadioGroupOrientation;
+  /**
+   * The reading direction of the radio group.
+   * @default ltr
+   */
+  dir?: UiRadioGroupDirection;
+  /**
+   * Whether keyboard navigation loops from last to first item.
+   * @default true
+   */
+  loop?: boolean;
+};
+
+/**
+ * Props for the UiRadioGroupItem component.
+ * An individual radio button within a radio group.
+ */
+export type UiRadioGroupItemProps = UiRadioGroupSharedProps & {
+  /**
+   * The unique identifier for the radio item.
+   */
+  id: string;
+  /**
+   * The value of the radio item.
+   */
+  value: string;
+};