@fiscozen/checkbox 0.1.6 → 0.2.0

package/src/FzCheckboxGroup.vue

@@ -1,78 +1,199 @@
-<template>
-  <div :class="[staticContainerClass, computedContainerClass]" :id="id">
-    <label :for="id" :class="[staticLabeldClass, computedLabelClass]">
-      <span>{{ label }}<span v-if="required"> *</span></span>
-      <p :class="computedHelpTextClass" v-if="$slots.help">
-        <slot name="help" />
-      </p>
-    </label>
-    <div :class="[staticSlotContainerClass, computedSlotContainerClass]">
-      <FzCheckboxGroupOption
-        v-for="option in options"
-        :key="option.value ? option.value.toString() : option.label"
-        v-model="model"
-        :disabled="disabled"
-        v-bind="option"
-        :emphasis="emphasis"
-        :error="error"
-        :size="size"
-      />
-    </div>
-    <FzCheckboxErrorText :size="size" v-if="error && $slots.error">
-      <slot name="error" />
-    </FzCheckboxErrorText>
-  </div>
-</template>
-
 <script setup lang="ts">
-import { computed } from "vue";
+/**
+ * FzCheckboxGroup Component
+ *
+ * A container component for managing multiple related checkboxes as a group.
+ * Provides group-level labeling, help text, error handling, and accessibility features.
+ * Supports both flat checkbox lists and hierarchical parent-child structures.
+ *
+ * @component
+ * @example
+ * // Basic checkbox group
+ * <FzCheckboxGroup
+ *   v-model="selectedOptions"
+ *   label="Choose options"
+ *   :options="[
+ *     { label: 'Option 1', value: 'opt1' },
+ *     { label: 'Option 2', value: 'opt2' }
+ *   ]"
+ * />
+ *
+ * @example
+ * // Hierarchical checkbox group with children
+ * <FzCheckboxGroup
+ *   v-model="selection"
+ *   label="Select features"
+ *   :options="[
+ *     {
+ *       label: 'All Features',
+ *       value: 'all',
+ *       children: [
+ *         { label: 'Feature A', value: 'a' },
+ *         { label: 'Feature B', value: 'b' }
+ *       ]
+ *     }
+ *   ]"
+ * />
+ */
+import { computed, useSlots, watch } from "vue";
 import { FzCheckboxGroupProps } from "./types";
-import FzCheckboxErrorText from "./components/FzCheckboxErrorText.vue";
-import { mapSizeToClasses } from "./common";
+import { generateGroupId } from "./utils";
 import FzCheckboxGroupOption from "./components/FzCheckboxGroupOption.vue";
-
-FzCheckboxGroupOption.compatConfig = {
-  MODE: 3,
-};
+import ErrorAlert from "./components/ErrorAlert.vue";
 
 const props = defineProps<FzCheckboxGroupProps>();
-const id = `fz-checkbox-group-${generateRandomId()}`;
+const slots = useSlots();
+
+/**
+ * Deprecation warning for size prop.
+ * Watches the size prop and warns once on mount if it's provided.
+ * Using watch with immediate:true ensures the warning only fires once per component instance.
+ */
+watch(
+  () => props.size,
+  (size) => {
+    if (size !== undefined) {
+      console.warn(
+        '[FzCheckboxGroup] The "size" prop is deprecated and will be removed in a future version. Checkboxes now have a fixed size.'
+      );
+    }
+  },
+  { immediate: true }
+);
+
+/** Unique identifier for the checkbox group, used for ARIA relationships */
+const id: string = generateGroupId();
 
-const computedHelpTextClass = computed(() => [
-  props.size === "sm" ? "text-xs" : "text-sm",
+/** Dynamic classes for help text based on disabled state */
+const computedHelpTextClass = computed<string[]>(() => [
+  "text-sm",
   props.disabled ? "text-grey-400" : "text-grey-500",
 ]);
 
-const model = defineModel<string[]>({
+/**
+ * Two-way binding for selected checkbox values.
+ * Supports string, number, and boolean values.
+ * Always an array, even when empty.
+ */
+const model = defineModel<(string | number | boolean)[]>({
   required: true,
   default: [],
 });
 
-const staticLabeldClass = "flex flex-col";
-const staticContainerClass = "flex flex-col";
-const staticSlotContainerClass = "flex flex-col";
+/** Base layout for the label element */
+const staticLabeldClass: string = "flex flex-col";
 
-const computedLabelClass = computed(() => [
-  mapSizeToClasses[props.size],
-  props.size === "sm" ? "gap-4" : "",
-  props.size === "md" ? "gap-6" : "",
-  props.disabled ? "text-grey-400" : "",
-  !props.disabled ? "text-grey-500" : "",
-]);
+/** Base layout for the root container */
+const staticContainerClass: string = "flex flex-col gap-10";
+
+/** Base layout for the checkboxes container */
+const staticSlotContainerClass: string = "flex items-start";
 
-const computedContainerClass = computed(() => [
-  mapSizeToClasses[props.size],
-  props.size === "sm" ? "gap-10" : "",
-  props.size === "md" ? "gap-12" : "",
+/** Dynamic label classes based on spacing and disabled state */
+const computedLabelClass = computed<string[]>(() => [
+  "text-base",
+  "gap-6",
+  props.disabled ? "text-grey-400" : "text-core-black",
 ]);
 
-const computedSlotContainerClass = computed(() => [
-  mapSizeToClasses[props.size],
-  props.size === "sm" ? "gap-6" : "",
-  props.size === "md" ? "gap-8" : "",
+/** Dynamic container classes */
+const computedContainerClass = computed<string[]>(() => ["text-base"]);
+
+/**
+ * Dynamic classes for the checkbox container.
+ * Handles both horizontal and vertical layouts with appropriate spacing.
+ */
+const computedSlotContainerClass = computed<string[]>(() => [
+  "text-base",
+  props.horizontal ? "gap-16" : "gap-8",
+  props.horizontal ? "flex-row" : "flex-col",
 ]);
 
-function generateRandomId() {
-  return Math.random().toString(36).slice(2, 9);
-}
+/**
+ * Computes the aria-describedby attribute value for the checkbox group.
+ * Combines help text and error message IDs when present.
+ *
+ * @returns Space-separated string of IDs, or undefined if no descriptions
+ *
+ * @example
+ * // Only help text
+ * "fz-checkbox-group-123-help"
+ *
+ * @example
+ * // Only error
+ * "fz-checkbox-group-123-error"
+ *
+ * @example
+ * // Both help and error
+ * "fz-checkbox-group-123-help fz-checkbox-group-123-error"
+ */
+const computedAriaDescribedby = computed<string | undefined>(() => {
+  const descriptions: string[] = [];
+
+  if (slots.help) {
+    descriptions.push(`${id}-help`);
+  }
+
+  if (props.error && slots.error) {
+    descriptions.push(`${id}-error`);
+  }
+
+  return descriptions.length > 0 ? descriptions.join(" ") : undefined;
+});
 </script>
+
+<template>
+  <!-- Root container for the entire checkbox group -->
+  <div :class="[staticContainerClass, computedContainerClass]">
+    <!-- 
+      Group label with optional required indicator and help text
+      Connected to checkbox group via aria-labelledby
+    -->
+    <label :id="id + '-label'" :class="[staticLabeldClass, computedLabelClass]">
+      <!-- Main label text with required asterisk if applicable -->
+      <span>{{ label }}<span v-if="required"> *</span></span>
+
+      <!-- Optional help text slot for additional context -->
+      <p :id="id + '-help'" :class="computedHelpTextClass" v-if="$slots.help">
+        <slot name="help" />
+      </p>
+    </label>
+
+    <!-- 
+      Checkbox group container with ARIA group role
+      - role="group": Identifies this as a group of related form controls
+      - aria-labelledby: Links to the label element
+      - aria-describedby: Links to help text and/or error message for screen readers
+      - aria-required: Indicates if selection is mandatory
+      - aria-invalid: Indicates validation state
+    -->
+    <div
+      :class="[staticSlotContainerClass, computedSlotContainerClass]"
+      :id="id"
+      role="group"
+      :aria-labelledby="id + '-label'"
+      :aria-describedby="computedAriaDescribedby"
+      :aria-required="required ? 'true' : 'false'"
+      :aria-invalid="error ? 'true' : 'false'"
+    >
+      <!-- 
+        Render each checkbox option
+        Supports both simple checkboxes and parent-child hierarchies
+        Key uses value if available, falls back to label for uniqueness
+      -->
+      <FzCheckboxGroupOption
+        v-for="option in options"
+        :key="option.value ? option.value.toString() : option.label"
+        v-model="model"
+        :disabled="disabled"
+        v-bind="option"
+        :emphasis="emphasis"
+        :error="error"
+      />
+    </div>
+    <!-- Error message display with accessible ARIA live region -->
+    <ErrorAlert v-if="error && $slots.error" :id="id + '-error'">
+      <slot name="error" />
+    </ErrorAlert>
+  </div>
+</template>

package/src/__test__/FzCheckbox.test.ts

@@ -1,4 +1,4 @@
-// FzCheckbox.spec.ts
+// FzCheckbox.test.ts
 import { mount } from "@vue/test-utils";
 import { describe, it, expect } from "vitest";
 import FzCheckbox from "../FzCheckbox.vue";
@@ -11,7 +11,6 @@ describe("FzCheckbox", () => {
       props: {
         label: "Test Checkbox",
         value: "test",
-        size: "md",
         modelValue: false,
       },
     });
@@ -20,18 +19,6 @@ describe("FzCheckbox", () => {
     expect(wrapper.html()).toContain("Test Checkbox");
   });
 
-  it("emits an update event when clicked", async () => {
-    const wrapper = mount(FzCheckbox, {
-      props: {
-        label: "Test Checkbox",
-        value: "test",
-        modelValue: false,
-      },
-    });
-    await wrapper.find("input").trigger("click");
-    expect(wrapper.emitted()).toHaveProperty("update:modelValue");
-  });
-
   it("is checked when v-model is true", async () => {
     const wrapper = mount(FzCheckbox, {
       props: {
@@ -62,7 +49,6 @@ describe("FzCheckbox", () => {
       props: {
         label: "Test Checkbox",
         value: "test",
-        size: "md",
         modelValue: false,
         emphasis: true,
       },
@@ -78,7 +64,6 @@ describe("FzCheckbox", () => {
       props: {
         label: "Test Checkbox",
         value: "test",
-        size: "md",
         modelValue: false,
         disabled: true,
       },
@@ -93,7 +78,6 @@ describe("FzCheckbox", () => {
         props: {
           label: "Test Checkbox",
           value: "test",
-          size: "md",
           modelValue: false,
           disabled: true,
         },
@@ -111,7 +95,6 @@ describe("FzCheckbox", () => {
       props: {
         label: "Test Checkbox",
         value: "test",
-        size: "md",
         modelValue: undefined,
       },
     });
@@ -124,11 +107,100 @@ describe("FzCheckbox", () => {
       props: {
         label: "Test Checkbox",
         value: "test",
-        size: "md",
         modelValue: null,
       },
     });
     await wrapper.vm.$nextTick();
     expect(wrapper.find("input").element.checked).toBe(false);
   });
+
+  it("has correct ARIA attributes (not standalone, no error)", async () => {
+    const wrapper = mount(FzCheckbox, {
+      props: {
+        label: "Test Checkbox",
+        value: "test",
+        modelValue: false,
+        required: true,
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const input = wrapper.find("input[type='checkbox']");
+    const id = input.attributes("id");
+    expect(input.attributes("aria-checked")).toBe("false");
+    expect(input.attributes("aria-label")).toBeUndefined();
+    expect(input.attributes("aria-required")).toBe("true");
+    expect(input.attributes("aria-invalid")).toBe("false");
+    expect(input.attributes("aria-describedby")).toBeUndefined();
+    expect(input.attributes("aria-labelledby")).toBe(`${id}-label`);
+    expect(wrapper.find(`#${id}-label`).exists()).toBe(true);
+  });
+
+  it("has correct ARIA attributes (standalone)", async () => {
+    const wrapper = mount(FzCheckbox, {
+      props: {
+        label: "Test Checkbox",
+        value: "test",
+        modelValue: false,
+        standalone: true,
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const input = wrapper.find("input[type='checkbox']");
+    expect(input.attributes("aria-labelledby")).toBeUndefined();
+    expect(input.attributes("aria-label")).toBe("Test Checkbox");
+  });
+
+  it("has correct ARIA attributes when error is present", async () => {
+    const wrapper = mount(FzCheckbox, {
+      props: {
+        label: "Test Checkbox",
+        value: "test",
+        modelValue: false,
+        error: true,
+      },
+      slots: {
+        error: "Test error message",
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const input = wrapper.find("input[type='checkbox']");
+    const id = input.attributes("id");
+    expect(input.attributes("aria-invalid")).toBe("true");
+    expect(input.attributes("aria-describedby")).toBe(`${id}-error`);
+    expect(wrapper.find(`#${id}-error`).exists()).toBe(true);
+  });
+
+  it("has correct ARIA attributes when error is present but no error message slot", async () => {
+    const wrapper = mount(FzCheckbox, {
+      props: {
+        label: "Test Checkbox",
+        value: "test",
+        modelValue: false,
+        error: true,
+      },
+      // No error slot provided
+    });
+    await wrapper.vm.$nextTick();
+    const input = wrapper.find("input[type='checkbox']");
+    // Error state must still be indicated via aria-invalid
+    expect(input.attributes("aria-invalid")).toBe("true");
+    // But aria-describedby should not reference an error element when no error slot is present
+    expect(input.attributes("aria-describedby")).toBeUndefined();
+    // ErrorAlert should not be rendered when no error slot is provided
+    expect(wrapper.find("[role='alert']").exists()).toBe(false);
+  });
+
+  it("has aria-checked='mixed' when indeterminate", async () => {
+    const wrapper = mount(FzCheckbox, {
+      props: {
+        label: "Test Checkbox",
+        value: "test",
+        modelValue: false,
+        indeterminate: true,
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const input = wrapper.find("input[type='checkbox']");
+    expect(input.attributes("aria-checked")).toBe("mixed");
+  });
 });

package/src/__test__/FzCheckboxGroup.test.ts

@@ -8,7 +8,6 @@ describe("FzCheckboxGroup", () => {
     const wrapper = mount(FzCheckboxGroup, {
       props: {
         label: "Test Checkbox Group",
-        size: "md",
         modelValue: [],
         options: [
           { label: "Option 1", value: "option1" },
@@ -26,7 +25,6 @@ describe("FzCheckboxGroup", () => {
     const wrapper = mount(FzCheckboxGroup, {
       props: {
         label: "Test Checkbox Group",
-        size: "md",
         modelValue: [],
         options: [
           { label: "Option 1", value: "option1" },
@@ -42,6 +40,9 @@ describe("FzCheckboxGroup", () => {
     await wrapper.vm.$nextTick();
     expect(wrapper.html()).toContain("Test error message");
     expect(wrapper.findAllComponents(FzCheckbox).length).toBe(2);
+    expect(wrapper.props("error")).toBe(true);
+
+    // Verify error prop is propagated to individual checkboxes
     expect(wrapper.findAllComponents(FzCheckbox).at(0)!.props("error")).toBe(
       true,
     );
@@ -54,7 +55,6 @@ describe("FzCheckboxGroup", () => {
     const wrapper = mount(FzCheckboxGroup, {
       props: {
         label: "Test Checkbox Group",
-        size: "md",
         modelValue: [],
         options: [
           { label: "Option 1", value: "option1" },
@@ -78,7 +78,6 @@ describe("FzCheckboxGroup", () => {
     const wrapper = mount(FzCheckboxGroup, {
       props: {
         label: "Test Checkbox Group",
-        size: "md",
         modelValue: [],
         options: [
           { label: "Option 1", value: "option1" },
@@ -97,4 +96,168 @@ describe("FzCheckboxGroup", () => {
       true,
     );
   });
+
+  it("has correct ARIA attributes for accessibility", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          { label: "Option 1", value: "option1" },
+          { label: "Option 2", value: "option2" },
+        ],
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const groupId = wrapper.find("[role='group']").attributes("id");
+    const labelId = groupId + "-label";
+    expect(wrapper.find("[role='group']").exists()).toBe(true);
+    expect(wrapper.find("[role='group']").attributes("aria-labelledby")).toBe(
+      labelId,
+    );
+    expect(wrapper.find(`#${labelId}`).exists()).toBe(true);
+    expect(
+      wrapper.find("[role='group']").attributes("aria-describedby"),
+    ).toBeUndefined();
+  });
+
+  it("has aria-describedby when error is present", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          { label: "Option 1", value: "option1" },
+          { label: "Option 2", value: "option2" },
+        ],
+        error: true,
+      },
+      slots: {
+        error: "Test error message",
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const groupId = wrapper.find("[role='group']").attributes("id");
+    const errorId = groupId + "-error";
+    expect(wrapper.find("[role='group']").attributes("aria-describedby")).toBe(
+      errorId,
+    );
+    expect(wrapper.find(`#${errorId}`).exists()).toBe(true);
+  });
+
+  it("has aria-invalid but no aria-describedby when error is present but no error message slot", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          { label: "Option 1", value: "option1" },
+          { label: "Option 2", value: "option2" },
+        ],
+        error: true,
+      },
+      // No error slot provided
+    });
+    await wrapper.vm.$nextTick();
+    const group = wrapper.find("[role='group']");
+    // Error state should still be indicated via aria-invalid
+    expect(group.attributes("aria-invalid")).toBe("true");
+    // But aria-describedby should not reference an error element when no error slot is present
+    expect(group.attributes("aria-describedby")).toBeUndefined();
+    // ErrorAlert should not be rendered when no error slot is provided
+    expect(wrapper.find("[role='alert']").exists()).toBe(false);
+    // Verify error prop is still propagated to individual checkboxes
+    const checkboxes = wrapper.findAllComponents(FzCheckbox);
+    checkboxes.forEach((checkbox) => {
+      expect(checkbox.props("error")).toBe(true);
+    });
+  });
+
+  it("has aria-describedby when help text is present", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          { label: "Option 1", value: "option1" },
+          { label: "Option 2", value: "option2" },
+        ],
+      },
+      slots: {
+        help: "This is help text",
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const groupId = wrapper.find("[role='group']").attributes("id");
+    const helpId = groupId + "-help";
+    expect(wrapper.find("[role='group']").attributes("aria-describedby")).toBe(
+      helpId,
+    );
+    expect(wrapper.find(`#${helpId}`).exists()).toBe(true);
+    expect(wrapper.find(`#${helpId}`).text()).toBe("This is help text");
+  });
+
+  it("has aria-describedby with both help and error", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          { label: "Option 1", value: "option1" },
+          { label: "Option 2", value: "option2" },
+        ],
+        error: true,
+      },
+      slots: {
+        help: "This is help text",
+        error: "This is an error",
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const groupId = wrapper.find("[role='group']").attributes("id");
+    const helpId = groupId + "-help";
+    const errorId = groupId + "-error";
+    const describedby = wrapper
+      .find("[role='group']")
+      .attributes("aria-describedby");
+
+    // Should contain both IDs separated by space
+    expect(describedby).toContain(helpId);
+    expect(describedby).toContain(errorId);
+    expect(describedby).toBe(`${helpId} ${errorId}`);
+  });
+
+  it("propagates error prop to child checkboxes in hierarchical structure", async () => {
+    const wrapper = mount(FzCheckboxGroup, {
+      props: {
+        label: "Test Checkbox Group",
+        modelValue: [],
+        options: [
+          {
+            label: "Parent Option",
+            value: "parent",
+            children: [
+              { label: "Child 1", value: "child1" },
+              { label: "Child 2", value: "child2" },
+            ],
+          },
+        ],
+        error: true,
+      },
+      slots: {
+        error: "Test error message",
+      },
+    });
+
+    await wrapper.vm.$nextTick();
+    const allCheckboxes = wrapper.findAllComponents(FzCheckbox);
+
+    // Should have parent + 2 children = 3 checkboxes
+    expect(allCheckboxes.length).toBe(3);
+
+    // All checkboxes should have error prop set to true
+    allCheckboxes.forEach((checkbox) => {
+      expect(checkbox.props("error")).toBe(true);
+    });
+  });
 });

package/src/common.ts

@@ -1,4 +1,24 @@
+/**
+ * Shared utilities for the Fiscozen Checkbox component library.
+ *
+ * @module @fiscozen/checkbox/common
+ */
+
+/**
+ * Maps checkbox size variants to corresponding Tailwind CSS text size classes.
+ *
+ * Used to maintain consistent typography across checkbox labels and helper text.
+ * Applied to both FzCheckbox and FzCheckboxGroup components.
+ *
+ * @constant
+ * @type {Record<"sm" | "md", string>}
+ *
+ * @example
+ * const labelClass = mapSizeToClasses[props.size]; // "text-sm" or "text-base"
+ */
 export const mapSizeToClasses = {
+  /** Small size: 14px font size (0.875rem) */
   sm: "text-sm",
+  /** Medium size: 16px font size (1rem) - default */
   md: "text-base",
 };