@vc-shell/framework 1.2.4-beta.1 → 1.2.4-beta.3

package/ui/components/molecules/vc-input-group/context.ts

@@ -0,0 +1,10 @@
+import type { InjectionKey, Ref } from "vue";
+
+export interface InputGroupContext {
+  name: Ref<string | undefined>;
+  disabled: Ref<boolean>;
+  invalid: Ref<boolean>;
+  describedBy: Ref<string | undefined>;
+}
+
+export const InputGroupContextKey: InjectionKey<InputGroupContext> = Symbol("vc-input-group-context");

package/ui/components/molecules/vc-input-group/index.ts

@@ -0,0 +1,2 @@
+export { default as VcInputGroup } from "@ui/components/molecules/vc-input-group/vc-input-group.vue";
+export type { InputGroupContext } from "@ui/components/molecules/vc-input-group/context";

package/ui/components/molecules/vc-input-group/vc-input-group.stories.ts

@@ -0,0 +1,355 @@
+import { ref } from "vue";
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import { VcCheckbox } from "@ui/components/molecules/vc-checkbox";
+import { VcInput } from "@ui/components/molecules/vc-input";
+import { VcRadioButton } from "@ui/components/molecules/vc-radio-button";
+import { VcSelect } from "@ui/components/molecules/vc-select";
+import { VcInputGroup } from "@ui/components/molecules/vc-input-group";
+
+/**
+ * `VcInputGroup` is a semantic wrapper for related form controls.
+ * It is designed for text inputs, selects, checkboxes, radios, and mixed field compositions.
+ */
+const meta = {
+  title: "Molecules/VcInputGroup",
+  component: VcInputGroup,
+  tags: ["autodocs"],
+  argTypes: {
+    label: {
+      description: "Group label (renders as legend)",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+    tooltip: {
+      description: "Tooltip text shown on the group label",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+    hint: {
+      description: "Hint text shown below grouped controls",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+    error: {
+      description: "Error state for the entire group",
+      control: "boolean",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    errorMessage: {
+      description: "Error message shown below the group",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+    required: {
+      description: "Shows required mark on the group label",
+      control: "boolean",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    disabled: {
+      description: "Disables all controls in the fieldset",
+      control: "boolean",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    orientation: {
+      description: "Layout orientation for grouped controls",
+      control: "select",
+      options: ["vertical", "horizontal"],
+      table: {
+        type: { summary: "'vertical' | 'horizontal'" },
+        defaultValue: { summary: "'vertical'" },
+      },
+    },
+    role: {
+      description: "ARIA role for the group container",
+      control: "select",
+      options: ["group", "radiogroup"],
+      table: {
+        type: { summary: "'group' | 'radiogroup'" },
+        defaultValue: { summary: "'group'" },
+      },
+    },
+    name: {
+      description: "Shared name propagated to child controls",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+  },
+  args: {
+    label: "Customer profile",
+    hint: "Group related form fields in one semantic section",
+    orientation: "vertical",
+    role: "group",
+    name: "customer-profile",
+  },
+} satisfies Meta<typeof VcInputGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const countryOptions = [
+  { id: "us", title: "United States" },
+  { id: "de", title: "Germany" },
+  { id: "jp", title: "Japan" },
+];
+
+/**
+ * Main use case: grouping text inputs and selects.
+ */
+export const FormFields: Story = {
+  render: (args) => ({
+    components: { VcInputGroup, VcInput, VcSelect },
+    setup: () => {
+      const firstName = ref("");
+      const country = ref<string | undefined>(undefined);
+      return { args, firstName, country, countryOptions };
+    },
+    template: `
+      <div class="tw-max-w-xl tw-space-y-3">
+        <VcInputGroup v-bind="args">
+          <VcInput
+            v-model="firstName"
+            label="First name"
+            placeholder="John"
+          />
+
+          <VcSelect
+            v-model="country"
+            label="Country"
+            placeholder="Select country"
+            :options="countryOptions"
+            option-value="id"
+            option-label="title"
+          />
+        </VcInputGroup>
+
+        <div class="tw-text-sm tw-text-gray-600">
+          Value: {{ { firstName, country } }}
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Horizontal form section layout.
+ */
+export const HorizontalFields: Story = {
+  args: {
+    orientation: "horizontal",
+    label: "Shipping details",
+    hint: "Fields can be aligned in a row",
+  },
+  render: (args) => ({
+    components: { VcInputGroup, VcInput, VcSelect },
+    setup: () => {
+      const city = ref("");
+      const country = ref<string | undefined>(undefined);
+      return { args, city, country, countryOptions };
+    },
+    template: `
+      <div class="tw-max-w-3xl">
+        <VcInputGroup v-bind="args">
+          <div class="tw-w-[280px]">
+            <VcInput v-model="city" label="City" placeholder="Berlin" />
+          </div>
+          <div class="tw-w-[280px]">
+            <VcSelect
+              v-model="country"
+              label="Country"
+              placeholder="Select country"
+              :options="countryOptions"
+              option-value="id"
+              option-label="title"
+            />
+          </div>
+        </VcInputGroup>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Checkbox controls grouped with semantic fieldset/legend.
+ */
+export const Checkboxes: Story = {
+  args: {
+    label: "Delivery options",
+    hint: "Choose at least one option",
+    name: "delivery-options",
+  },
+  render: (args) => ({
+    components: { VcInputGroup, VcCheckbox },
+    setup: () => {
+      const selected = ref<string[]>(["courier"]);
+      return { args, selected };
+    },
+    template: `
+      <div class="tw-max-w-lg tw-space-y-3">
+        <VcInputGroup v-bind="args">
+          <VcCheckbox v-model="selected" value="courier">Courier delivery</VcCheckbox>
+          <VcCheckbox v-model="selected" value="pickup">Store pickup</VcCheckbox>
+          <VcCheckbox v-model="selected" value="postal">Postal service</VcCheckbox>
+        </VcInputGroup>
+        <div class="tw-text-sm tw-text-gray-600">Selected: {{ selected }}</div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Horizontal radio controls with radiogroup role.
+ */
+export const RadiosHorizontal: Story = {
+  args: {
+    role: "radiogroup",
+    orientation: "horizontal",
+    label: "Payment method",
+    hint: "You can change it later in checkout",
+    name: "payment-method",
+  },
+  render: (args) => ({
+    components: { VcInputGroup, VcRadioButton },
+    setup: () => {
+      const value = ref("card");
+      return { args, value };
+    },
+    template: `
+      <div class="tw-max-w-lg tw-space-y-3">
+        <VcInputGroup v-bind="args">
+          <VcRadioButton v-model="value" value="card" label="Card" />
+          <VcRadioButton v-model="value" value="invoice" label="Invoice" />
+          <VcRadioButton v-model="value" value="cash" label="Cash" />
+        </VcInputGroup>
+        <div class="tw-text-sm tw-text-gray-600">Selected: {{ value }}</div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Group-level disabled state for input/select fields.
+ */
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    label: "Read-only section",
+    hint: "All controls are disabled by fieldset",
+    name: "readonly-profile",
+  },
+  render: (args) => ({
+    components: { VcInputGroup, VcInput, VcSelect },
+    setup: () => {
+      const email = ref("john@example.com");
+      const country = ref<string | undefined>("us");
+      return { args, email, country, countryOptions };
+    },
+    template: `
+      <VcInputGroup v-bind="args">
+        <VcInput v-model="email" label="Email" />
+        <VcSelect
+          v-model="country"
+          label="Country"
+          :options="countryOptions"
+          option-value="id"
+          option-label="title"
+        />
+      </VcInputGroup>
+    `,
+  }),
+};
+
+/**
+ * Group-level error message for mixed form controls.
+ */
+export const ErrorState: Story = {
+  args: {
+    label: "Billing details",
+    required: true,
+    error: true,
+    errorMessage: "Please fill required fields in this section",
+    hint: "At least one value is required",
+    name: "billing-details",
+  },
+  render: (args) => ({
+    components: { VcInputGroup, VcInput, VcSelect },
+    setup: () => {
+      const company = ref("");
+      const country = ref<string | undefined>(undefined);
+      return { args, company, country, countryOptions };
+    },
+    template: `
+      <VcInputGroup v-bind="args">
+        <VcInput v-model="company" label="Company" placeholder="ACME Inc." />
+        <VcSelect
+          v-model="country"
+          label="Country"
+          placeholder="Select country"
+          :options="countryOptions"
+          option-value="id"
+          option-label="title"
+        />
+      </VcInputGroup>
+    `,
+  }),
+};
+
+/**
+ * Accessibility demo: inspect fieldset/legend and ARIA links.
+ */
+export const Accessibility: Story = {
+  render: () => ({
+    components: { VcInputGroup, VcInput, VcSelect },
+    setup: () => {
+      const firstName = ref("Jane");
+      const country = ref<string | undefined>("de");
+      return { firstName, country, countryOptions };
+    },
+    template: `
+      <div class="tw-max-w-xl tw-space-y-4">
+        <VcInputGroup
+          label="Profile section"
+          name="profile-section"
+          hint="Inspect aria-describedby and aria-labelledby on fieldset"
+        >
+          <VcInput v-model="firstName" label="First name" />
+          <VcSelect
+            v-model="country"
+            label="Country"
+            :options="countryOptions"
+            option-value="id"
+            option-label="title"
+          />
+        </VcInputGroup>
+
+        <div class="tw-p-3 tw-bg-blue-50 tw-rounded tw-text-blue-700 tw-text-sm">
+          <strong>Inspect in DOM:</strong>
+          <ul class="tw-list-disc tw-pl-5 tw-mt-1">
+            <li><code>fieldset</code> groups related controls semantically</li>
+            <li><code>legend</code> provides section label</li>
+            <li><code>aria-describedby</code> points to hint/error id</li>
+            <li>works for standard form controls, not only checkbox/radio groups</li>
+          </ul>
+        </div>
+      </div>
+    `,
+  }),
+};

package/ui/components/molecules/vc-input-group/vc-input-group.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { mount } from "@vue/test-utils";
+import VcInputGroup from "@ui/components/molecules/vc-input-group/vc-input-group.vue";
+
+describe("VcInputGroup", () => {
+  it("renders semantic fieldset with legend", () => {
+    const wrapper = mount(VcInputGroup as any, {
+      props: {
+        label: "Delivery",
+      },
+      slots: {
+        default: '<input type="checkbox" value="courier" />',
+      },
+    });
+
+    expect(wrapper.find("fieldset").exists()).toBe(true);
+    expect(wrapper.find("legend").text()).toContain("Delivery");
+  });
+
+  it("links error message through aria-describedby", () => {
+    const wrapper = mount(VcInputGroup as any, {
+      props: {
+        label: "Channels",
+        error: true,
+        errorMessage: "Select at least one",
+      },
+      slots: {
+        default: '<input type="checkbox" value="email" />',
+      },
+    });
+
+    const fieldset = wrapper.find("fieldset");
+    const describedBy = fieldset.attributes("aria-describedby");
+
+    expect(fieldset.attributes("aria-invalid")).toBe("true");
+    expect(describedBy).toBeTruthy();
+    expect(wrapper.find(`#${describedBy}`).exists()).toBe(true);
+  });
+});

package/ui/components/molecules/vc-input-group/vc-input-group.vue

@@ -0,0 +1,184 @@
+<template>
+  <fieldset
+    class="vc-input-group"
+    :class="[
+      {
+        'vc-input-group--horizontal': orientation === 'horizontal',
+        'vc-input-group--vertical': orientation === 'vertical',
+        'vc-input-group--error': invalid,
+        'vc-input-group--disabled': disabled,
+      },
+    ]"
+    :disabled="disabled"
+    :role="role"
+    :aria-invalid="invalid || undefined"
+    :aria-describedby="describedBy"
+    :aria-labelledby="ariaLabelledBy"
+    :aria-label="ariaLabel"
+  >
+    <legend
+      v-if="label"
+      :id="labelId"
+      class="vc-input-group__legend"
+    >
+      <VcLabel
+        :required="required"
+        :error="invalid"
+      >
+        <span>{{ label }}</span>
+        <template
+          v-if="tooltip"
+          #tooltip
+          >{{ tooltip }}</template
+        >
+      </VcLabel>
+    </legend>
+
+    <div class="vc-input-group__controls">
+      <slot />
+    </div>
+
+    <Transition
+      name="slide-up"
+      mode="out-in"
+    >
+      <div v-if="invalid && errorMessage">
+        <slot name="error">
+          <VcHint
+            :id="errorId"
+            class="vc-input-group__error"
+            :error="true"
+          >
+            {{ errorMessage }}
+          </VcHint>
+        </slot>
+      </div>
+      <div v-else-if="hint">
+        <slot name="hint">
+          <VcHint
+            :id="hintId"
+            class="vc-input-group__hint"
+          >
+            {{ hint }}
+          </VcHint>
+        </slot>
+      </div>
+    </Transition>
+  </fieldset>
+</template>
+
+<script lang="ts" setup>
+import { computed, provide, toRef, useId } from "vue";
+import { VcHint, VcLabel } from "@ui/components";
+import { InputGroupContextKey } from "@ui/components/molecules/vc-input-group/context";
+
+export interface Props {
+  label?: string;
+  tooltip?: string;
+  hint?: string;
+  error?: boolean;
+  errorMessage?: string;
+  required?: boolean;
+  disabled?: boolean;
+  orientation?: "vertical" | "horizontal";
+  role?: "group" | "radiogroup";
+  name?: string;
+  ariaLabel?: string;
+  ariaLabelledby?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  orientation: "vertical",
+  role: "group",
+});
+
+const uid = useId();
+const labelId = computed(() => `vc-input-group-${uid}-label`);
+const hintId = computed(() => `vc-input-group-${uid}-hint`);
+const errorId = computed(() => `vc-input-group-${uid}-error`);
+
+const invalid = computed(() => !!props.error || !!props.errorMessage);
+
+const describedBy = computed(() => {
+  if (invalid.value && props.errorMessage) {
+    return errorId.value;
+  }
+
+  if (props.hint) {
+    return hintId.value;
+  }
+
+  return undefined;
+});
+
+const ariaLabelledBy = computed(() => {
+  if (props.label) {
+    return labelId.value;
+  }
+
+  return props.ariaLabelledby;
+});
+
+provide(InputGroupContextKey, {
+  name: toRef(props, "name"),
+  disabled: computed(() => !!props.disabled),
+  invalid,
+  describedBy,
+});
+</script>
+
+<style lang="scss">
+:root {
+  --input-group-gap: 0.5rem;
+  --input-group-horizontal-gap: 1rem;
+  --input-group-legend-spacing: 0.375rem;
+}
+
+.vc-input-group {
+  @apply tw-flex tw-flex-col tw-gap-[var(--input-group-gap)] tw-min-w-0;
+
+  border: 0;
+  margin: 0;
+  padding: 0;
+
+  &__legend {
+    @apply tw-p-0 tw-m-0 tw-mb-[var(--input-group-legend-spacing)];
+  }
+
+  &__controls {
+    @apply tw-flex tw-flex-col tw-gap-[var(--input-group-gap)];
+  }
+
+  &__hint,
+  &__error {
+    @apply tw-mt-1;
+  }
+
+  &__error {
+    @apply [--hint-error-color:var(--danger-500)];
+  }
+
+  &--horizontal {
+    .vc-input-group__controls {
+      @apply tw-flex-row tw-flex-wrap tw-items-start tw-gap-[var(--input-group-horizontal-gap)];
+    }
+  }
+
+  &--disabled {
+    @apply tw-opacity-50;
+  }
+
+  .slide-up-enter-active,
+  .slide-up-leave-active {
+    @apply tw-transition-all tw-duration-[250ms] tw-ease-out;
+  }
+
+  .slide-up-enter-from {
+    @apply tw-opacity-0 tw-translate-y-[5px];
+  }
+
+  .slide-up-leave-to {
+    @apply tw-opacity-0 tw--translate-y-[5px];
+  }
+}
+</style>