@aleph-alpha/ui-library 1.8.0 → 1.10.0

package/src/primitives/UiField/UiField.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+  import { Field as ShadcnField } from '@/primitives/shadcn/field';
+  import type { UiFieldProps } from './types';
+
+  defineOptions({
+    name: 'UiField',
+  });
+
+  const props = withDefaults(defineProps<UiFieldProps>(), {
+    orientation: 'vertical',
+  });
+</script>
+
+<template>
+  <ShadcnField :orientation="props.orientation">
+    <slot />
+  </ShadcnField>
+</template>

package/src/primitives/UiField/UiFieldContent.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldContent as ShadcnFieldContent } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldContent',
+  });
+</script>
+
+<template>
+  <ShadcnFieldContent>
+    <slot />
+  </ShadcnFieldContent>
+</template>

package/src/primitives/UiField/UiFieldDescription.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldDescription as ShadcnFieldDescription } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldDescription',
+  });
+</script>
+
+<template>
+  <ShadcnFieldDescription>
+    <slot />
+  </ShadcnFieldDescription>
+</template>

package/src/primitives/UiField/UiFieldError.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+  import { FieldError as ShadcnFieldError } from '@/primitives/shadcn/field';
+  import { computed, useSlots } from 'vue';
+  import type { UiFieldErrorProps } from './types';
+
+  defineOptions({
+    name: 'UiFieldError',
+  });
+
+  const props = defineProps<UiFieldErrorProps>();
+
+  const slots = useSlots();
+  const hasDefaultSlotContent = computed(() => (slots.default?.().length ?? 0) > 0);
+</script>
+
+<template>
+  <ShadcnFieldError :errors="props.errors">
+    <slot v-if="hasDefaultSlotContent" />
+  </ShadcnFieldError>
+</template>

package/src/primitives/UiField/UiFieldGroup.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldGroup as ShadcnFieldGroup } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldGroup',
+  });
+</script>
+
+<template>
+  <ShadcnFieldGroup>
+    <slot />
+  </ShadcnFieldGroup>
+</template>

package/src/primitives/UiField/UiFieldLabel.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+  import { FieldLabel as ShadcnFieldLabel } from '@/primitives/shadcn/field';
+  import type { UiFieldLabelProps } from './types';
+
+  defineOptions({
+    name: 'UiFieldLabel',
+  });
+
+  const props = defineProps<UiFieldLabelProps>();
+</script>
+
+<template>
+  <ShadcnFieldLabel :for="props.for">
+    <slot />
+  </ShadcnFieldLabel>
+</template>

package/src/primitives/UiField/UiFieldLegend.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldLegend as ShadcnFieldLegend } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldLegend',
+  });
+</script>
+
+<template>
+  <ShadcnFieldLegend>
+    <slot />
+  </ShadcnFieldLegend>
+</template>

package/src/primitives/UiField/UiFieldSeparator.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldSeparator as ShadcnFieldSeparator } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldSeparator',
+  });
+</script>
+
+<template>
+  <ShadcnFieldSeparator>
+    <slot />
+  </ShadcnFieldSeparator>
+</template>

package/src/primitives/UiField/UiFieldSet.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldSet as ShadcnFieldSet } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldSet',
+  });
+</script>
+
+<template>
+  <ShadcnFieldSet>
+    <slot />
+  </ShadcnFieldSet>
+</template>

package/src/primitives/UiField/UiFieldTitle.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { FieldTitle as ShadcnFieldTitle } from '@/primitives/shadcn/field';
+
+  defineOptions({
+    name: 'UiFieldTitle',
+  });
+</script>
+
+<template>
+  <ShadcnFieldTitle>
+    <slot />
+  </ShadcnFieldTitle>
+</template>

package/src/primitives/UiField/__tests__/UiFieldError.test.ts

@@ -0,0 +1,35 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import { UiFieldError } from '../index';
+
+describe('UiFieldError', () => {
+  test('renders single error as text', () => {
+    const { getByRole } = render(UiFieldError, {
+      props: { errors: ['Required'] },
+    });
+
+    expect(getByRole('alert')).toHaveTextContent('Required');
+  });
+
+  test('renders an alert when errors are provided', () => {
+    const { getByRole } = render(UiFieldError, {
+      props: {
+        errors: ['Too short', { message: 'Too short' }, { message: 'Invalid format' }],
+      },
+    });
+
+    expect(getByRole('alert')).toBeInTheDocument();
+  });
+
+  test('prefers slot content over errors rendering', () => {
+    const { getByRole } = render(UiFieldError, {
+      props: { errors: ['Required'] },
+      slots: {
+        default: 'Custom error slot',
+      },
+    });
+
+    expect(getByRole('alert')).toHaveTextContent('Custom error slot');
+    expect(getByRole('alert')).not.toHaveTextContent('Required');
+  });
+});

package/src/primitives/UiField/index.ts

@@ -0,0 +1,10 @@
+export { default as UiField } from './UiField.vue';
+export { default as UiFieldContent } from './UiFieldContent.vue';
+export { default as UiFieldDescription } from './UiFieldDescription.vue';
+export { default as UiFieldError } from './UiFieldError.vue';
+export { default as UiFieldGroup } from './UiFieldGroup.vue';
+export { default as UiFieldLabel } from './UiFieldLabel.vue';
+export { default as UiFieldLegend } from './UiFieldLegend.vue';
+export { default as UiFieldSeparator } from './UiFieldSeparator.vue';
+export { default as UiFieldSet } from './UiFieldSet.vue';
+export { default as UiFieldTitle } from './UiFieldTitle.vue';

package/src/primitives/UiField/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Layout orientation supported by `UiField`.
+ */
+export type UiFieldOrientation = 'vertical' | 'horizontal' | 'responsive';
+
+/**
+ * Error shape supported by `UiFieldError`.
+ */
+export type UiFieldErrorLike = string | { message: string | undefined } | undefined;
+
+/**
+ * A form field wrapper that groups label, input, description, and error messages.
+ * Provides consistent layout and accessibility for form controls.
+ *
+ * @category Form Inputs
+ * @useCases form layout, input wrapper, field grouping, validation display
+ * @keywords field, form, label, input, error, validation, wrapper
+ * @related UiInput, UiLabel
+ */
+export interface UiFieldProps {
+  /**
+   * Layout orientation of the field.
+   * @default 'vertical'
+   */
+  orientation?: UiFieldOrientation;
+}
+
+/**
+ * Props for `UiFieldError` component.
+ */
+export interface UiFieldErrorProps {
+  /**
+   * List of errors to render. Supports strings or objects with a `message` field.
+   */
+  errors?: UiFieldErrorLike[];
+}
+
+/**
+ * Props for `UiFieldLabel` component.
+ */
+export interface UiFieldLabelProps {
+  /**
+   * The id of the element the label is associated with.
+   * Use together with `id` on an input.
+   */
+  for?: string;
+}

package/src/primitives/UiIcon/UiIcon.stories.ts

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { UiIcon } from '.';
+import { UiIconButton } from '../UiIconButton';
+
+/**
+ * UiIcon renders a single icon using the design system’s icon set (Material Symbols via UnoCSS preset-icons).
+ * Use it for consistent sizing, styling, and accessibility semantics across the UI library.
+ */
+const meta: Meta<typeof UiIcon> = {
+  title: 'Primitives/UiIcon',
+  component: UiIcon,
+  tags: ['autodocs'],
+  argTypes: {
+    icon: {
+      control: 'text',
+      description: 'Icon class, e.g. `i-material-symbols-help`.',
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label. If omitted, icon is treated as decorative.',
+    },
+  },
+  args: {
+    icon: 'i-material-symbols-help',
+    ariaLabel: 'Help',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof UiIcon>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex items-center gap-4">
+    <UiIcon icon="i-material-symbols-help" aria-label="Help" class="text-xl text-foreground" />
+    <UiIcon icon="i-material-symbols-keyboard-arrow-down" aria-label="Down" class="text-xl text-foreground" />
+    <UiIcon icon="i-material-symbols-check" aria-label="Check" class="text-xl text-foreground" />
+  </div>
+</template>`;
+
+/**
+ * Basic icon rendering with Material Symbols.
+ * Use this as a starting point for choosing an icon and verifying size/color alignment in your layout.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiIcon },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="flex items-center gap-4">
+        <UiIcon v-bind="args" class="text-xl text-foreground" />
+        <UiIcon icon="i-material-symbols-keyboard-arrow-down" aria-label="Down" class="text-xl text-foreground" />
+        <UiIcon icon="i-material-symbols-check" aria-label="Check" class="text-xl text-foreground" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: defaultTemplateSource } },
+  },
+};
+
+const iconButtonTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton aria-label="Close">
+    <UiIcon icon="i-material-symbols-close" class="text-xl" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Using UiIcon inside UiIconButton.
+ * Use this pattern when you need an icon-only control: the button gets the accessible name via `aria-label`,
+ * and the icon can stay purely visual.
+ */
+export const InIconButton: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `
+      <UiIconButton aria-label="Close">
+        <UiIcon icon="i-material-symbols-close" class="text-xl" />
+      </UiIconButton>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: iconButtonTemplateSource } },
+  },
+};

package/src/primitives/UiIcon/UiIcon.vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+  import { Icon as ShadcnIcon } from '@/primitives/shadcn/icon';
+  import type { UiIconProps } from './types';
+
+  defineOptions({
+    name: 'UiIcon',
+  });
+
+  const props = defineProps<UiIconProps>();
+</script>
+
+<template>
+  <ShadcnIcon :icon="props.icon" :aria-label="props.ariaLabel" />
+</template>

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

@@ -0,0 +1,24 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import { UiIcon } from '../index';
+
+describe('UiIcon', () => {
+  test('renders a material-symbols icon class by default', () => {
+    const { container } = render(UiIcon, {
+      props: { icon: 'i-material-symbols-help' },
+    });
+
+    const el = container.querySelector('[data-slot="icon"]');
+    expect(el).toBeInTheDocument();
+    expect(el).toHaveClass('i-material-symbols-help');
+    expect(el).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('exposes role="img" when ariaLabel is provided', () => {
+    const { getByRole } = render(UiIcon, {
+      props: { icon: 'i-material-symbols-help', ariaLabel: 'Help' },
+    });
+
+    expect(getByRole('img', { name: 'Help' })).toBeInTheDocument();
+  });
+});

package/src/primitives/UiIcon/index.ts

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

package/src/primitives/UiIcon/types.ts

@@ -0,0 +1,23 @@
+/**
+ * An icon component using UnoCSS/Iconify icons. Use for visual indicators,
+ * button decorations, or standalone meaningful graphics.
+ *
+ * @category Data Display
+ * @useCases visual indicator, button icon, status icon, decorative graphic
+ * @keywords icon, symbol, graphic, material, iconify, svg
+ * @related UiIconButton, UiButton
+ */
+export interface UiIconProps {
+  /**
+   * Icon class generated by UnoCSS preset-icons / ds-icons.
+   *
+   * Example: `i-material-symbols-help`
+   */
+  icon: string;
+
+  /**
+   * Accessible label for the icon. When provided, the icon is exposed as `role="img"`.
+   * If omitted, the icon is treated as decorative (`aria-hidden="true"`).
+   */
+  ariaLabel?: string;
+}