@aleph-alpha/ui-library 1.11.0 → 1.12.0

package/src/primitives/UiKbd/types.ts

@@ -0,0 +1,32 @@
+/**
+ * A keyboard key indicator component. Use to display keyboard shortcuts,
+ * hotkeys, or key combinations in documentation and UI hints.
+ *
+ * @category Feedback
+ * @useCases keyboard shortcut, hotkey display, key combination, command hint
+ * @keywords kbd, keyboard, key, shortcut, hotkey, command, keybinding
+ * @related UiKbdGroup, UiTooltip
+ */
+export interface UiKbdProps {
+  /**
+   * The size of the keyboard key indicator.
+   * @default 'default'
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * A container for grouping multiple keyboard keys together. Use to display
+ * key combinations like "Ctrl + C" or "Cmd + Shift + P".
+ *
+ * @category Feedback
+ * @useCases key combination, shortcut group, multi-key display
+ * @keywords kbd, keyboard, group, combination, shortcut, keys
+ * @related UiKbd
+ */
+export interface UiKbdGroupProps {
+  /**
+   * Additional CSS classes to apply to the group container.
+   */
+  class?: string;
+}

package/src/primitives/UiLabel/UiLabel.stories.ts

@@ -0,0 +1,192 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiLabel from './UiLabel.vue';
+import { UiInput } from '../UiInput';
+import { UiCheckbox } from '../UiCheckbox';
+
+/**
+ * UiLabel provides accessible text labels for form elements. Use to identify
+ * inputs, improve accessibility, and enable click-to-focus behavior via the `for` attribute.
+ */
+const meta: Meta<typeof UiLabel> = {
+  title: 'Primitives/UiLabel',
+  component: UiLabel,
+  tags: ['autodocs'],
+  argTypes: {
+    for: {
+      control: 'text',
+      description: 'The id of the form element this label is associated with',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiLabel>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiLabel } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiLabel for="email">Email</UiLabel>
+</template>`;
+
+/**
+ * Default label displaying text content. Use the `for` attribute to associate
+ * the label with a form element, enabling click-to-focus accessibility.
+ */
+export const Default: Story = {
+  render: () => ({
+    components: { UiLabel },
+    template: `<UiLabel for="email">Email</UiLabel>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const withInputTemplateSource = `<script setup lang="ts">
+import { UiLabel, UiInput } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="grid w-full max-w-sm items-center gap-1.5">
+    <UiLabel for="email">Email</UiLabel>
+    <UiInput id="email" name="email" type="email" placeholder="Enter your email" />
+  </div>
+</template>`;
+
+/**
+ * Label associated with an input field using the `for` attribute.
+ * Clicking the label will focus the input.
+ */
+export const WithInput: Story = {
+  render: () => ({
+    components: { UiLabel, UiInput },
+    template: `
+      <div class="grid w-full max-w-sm items-center gap-1.5">
+        <UiLabel for="email">Email</UiLabel>
+        <UiInput id="email" name="email" type="email" placeholder="Enter your email" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withInputTemplateSource,
+      },
+    },
+  },
+};
+
+const withCheckboxTemplateSource = `<script setup lang="ts">
+import { UiLabel, UiCheckbox } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex items-center space-x-2">
+    <UiCheckbox id="terms" name="terms" />
+    <UiLabel for="terms">Accept terms and conditions</UiLabel>
+  </div>
+</template>`;
+
+/**
+ * Label paired with a checkbox for toggle options like terms acceptance.
+ * Position the label after the checkbox for standard form patterns.
+ */
+export const WithCheckbox: Story = {
+  render: () => ({
+    components: { UiLabel, UiCheckbox },
+    template: `
+      <div class="flex items-center space-x-2">
+        <UiCheckbox id="terms" name="terms" />
+        <UiLabel for="terms">Accept terms and conditions</UiLabel>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withCheckboxTemplateSource,
+      },
+    },
+  },
+};
+
+const disabledStateTemplateSource = `<script setup lang="ts">
+import { UiLabel, UiInput } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="grid w-full max-w-sm items-center gap-1.5" data-disabled="true">
+    <UiLabel for="disabled-input">Disabled Field</UiLabel>
+    <UiInput id="disabled-input" name="disabled-input" disabled placeholder="Disabled" />
+  </div>
+</template>`;
+
+/**
+ * Label with a disabled input field. The label automatically applies muted
+ * styling when the parent container has `data-disabled="true"` attribute.
+ */
+export const DisabledState: Story = {
+  render: () => ({
+    components: { UiLabel, UiInput },
+    template: `
+      <div class="grid w-full max-w-sm items-center gap-1.5" data-disabled="true">
+        <UiLabel for="disabled-input">Disabled Field</UiLabel>
+        <UiInput id="disabled-input" name="disabled-input" disabled placeholder="Disabled" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: disabledStateTemplateSource,
+      },
+    },
+  },
+};
+
+const requiredFieldTemplateSource = `<script setup lang="ts">
+import { UiLabel, UiInput } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="grid w-full max-w-sm items-center gap-1.5">
+    <UiLabel for="required-input">
+      Username
+      <span class="text-destructive">*</span>
+    </UiLabel>
+    <UiInput id="required-input" name="required-input" required placeholder="Enter username" />
+  </div>
+</template>`;
+
+/**
+ * Label for a required field with a red asterisk indicator. Use slot content
+ * to add custom elements like required markers alongside the label text.
+ */
+export const RequiredField: Story = {
+  render: () => ({
+    components: { UiLabel, UiInput },
+    template: `
+      <div class="grid w-full max-w-sm items-center gap-1.5">
+        <UiLabel for="required-input">
+          Username
+          <span class="text-destructive">*</span>
+        </UiLabel>
+        <UiInput id="required-input" name="required-input" required placeholder="Enter username" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: requiredFieldTemplateSource,
+      },
+    },
+  },
+};

package/src/primitives/UiLabel/UiLabel.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+  import { Label as ShadcnLabel } from '@/primitives/shadcn/label';
+  import { UiLabelProps } from './types';
+
+  defineOptions({
+    name: 'UiLabel',
+  });
+
+  const props = defineProps<UiLabelProps>();
+</script>
+
+<template>
+  <ShadcnLabel :for="props.for">
+    <slot />
+  </ShadcnLabel>
+</template>

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

@@ -0,0 +1,43 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import UiLabel from '../UiLabel.vue';
+
+describe('UiLabel', () => {
+  test('renders label with text content', () => {
+    const labelText = 'Email';
+    const { getByText } = render(UiLabel, {
+      slots: { default: labelText },
+    });
+    expect(getByText(labelText)).toBeInTheDocument();
+  });
+
+  test('renders label with for attribute', () => {
+    const forValue = 'email-input';
+    const { container } = render(UiLabel, {
+      props: { for: forValue },
+      slots: { default: 'Email' },
+    });
+    const label = container.querySelector('label');
+    expect(label).toHaveAttribute('for', forValue);
+  });
+
+  test('applies custom class', () => {
+    const customClass = 'custom-label-class';
+    const { container } = render(UiLabel, {
+      props: { class: customClass },
+      slots: { default: 'Email' },
+    });
+    const label = container.querySelector('label');
+    expect(label).toHaveClass(customClass);
+  });
+
+  test('renders slot content', () => {
+    const { getByText, getByTestId } = render(UiLabel, {
+      slots: {
+        default: '<span data-testid="slot-content">Custom Content</span>',
+      },
+    });
+    expect(getByTestId('slot-content')).toBeInTheDocument();
+    expect(getByText('Custom Content')).toBeInTheDocument();
+  });
+});

package/src/primitives/UiLabel/index.ts

@@ -0,0 +1,2 @@
+export { default as UiLabel } from './UiLabel.vue';
+export type * from './types';

package/src/primitives/UiLabel/types.ts

@@ -0,0 +1,16 @@
+/**
+ * A text label for form elements. Use to identify form inputs, provide
+ * context, and improve accessibility by associating labels with controls.
+ *
+ * @category Form Inputs
+ * @useCases form label, input label, field label, accessibility label
+ * @keywords label, form, input, text, field, accessibility, a11y
+ * @related UiInput, UiCheckbox, UiField, UiRadioGroup
+ */
+export interface UiLabelProps {
+  /**
+   * The id of the form element that this label is associated with.
+   * When provided, clicking the label will focus the associated element.
+   */
+  for: string;
+}