@fiscozen/checkbox 0.1.5 → 0.2.0

package/src/components/ErrorAlert.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+/**
+ * ErrorAlert Component
+ *
+ * Internal component that wraps FzAlert with proper ARIA attributes for error messages.
+ * Provides accessible error announcements for screen readers.
+ *
+ * @component
+ * @internal
+ *
+ * Features:
+ * - ARIA live region with assertive priority
+ * - Automatic role="alert" for immediate announcement
+ * - Atomic reading for complete error messages
+ *
+ * @example
+ * <ErrorAlert id="field-error" size="md">
+ *   This field is required
+ * </ErrorAlert>
+ */
+import { FzAlert } from "@fiscozen/alert";
+
+defineProps<{
+  /**
+   * Unique ID for the error alert element.
+   * Used for aria-describedby relationships.
+   *
+   * @example "checkbox-123-error"
+   */
+  id: string;
+}>();
+</script>
+
+<template>
+  <!-- 
+    Error message display with ARIA live region
+    Announces validation errors immediately to screen readers
+    - role="alert": High-priority message
+    - aria-live="assertive": Interrupts current announcements
+    - aria-atomic="true": Reads complete message
+    
+    @TODO: When FzAlert supports automatic ARIA handling based on `type` 
+    (e.g., via an `announce` prop or similar semantic API), we can remove 
+    these manual attributes.
+    
+    Proposed future API:
+      FzAlert with type="error" and announce prop
+      would automatically get role="alert" and aria-live="assertive"
+  -->
+  <FzAlert
+    :id="id"
+    type="error"
+    alertStyle="simple"
+    role="alert"
+    aria-live="assertive"
+    aria-atomic="true"
+    size="md"
+  >
+    <slot />
+  </FzAlert>
+</template>

package/src/components/FzCheckboxGroupOption.vue

@@ -1,56 +1,77 @@
-<template>
-  <FzCheckbox
-    v-model="model"
-    :value="props.value"
-    :label="props.label"
-    :disabled="disabled"
-    :emphasis="emphasis"
-    :error="error"
-    :size="size"
-    :indeterminate="isIndeterminate"
-    @change="onCheckboxParentChange"
-  >
-    <template #children v-if="children?.length">
-      <div :class="[staticChildContainerClass, computedChildContainerClasses]">
-        <FzCheckbox
-          v-for="child in children"
-          :key="child.value ? child.value.toString() : child.label"
-          v-model="model"
-          :disabled="disabled"
-          v-bind="child"
-          :emphasis="emphasis"
-          :error="error"
-          :size="size"
-          @change="handleCheckboxParentChange"
-        />
-      </div>
-    </template>
-  </FzCheckbox>
-</template>
 <script setup lang="ts">
+/**
+ * FzCheckboxGroupOption Component
+ *
+ * Renders a single checkbox option within a checkbox group, with support for
+ * hierarchical parent-child relationships. When children are present, the parent
+ * checkbox displays an indeterminate state when partially selected.
+ *
+ * Key features:
+ * - Automatic indeterminate state management for parent checkboxes
+ * - Bi-directional sync: parent controls children, children update parent
+ * - ARIA relationships via aria-owns for accessibility
+ * - Deterministic IDs for proper ARIA associations
+ *
+ * @component
+ * @internal Used internally by FzCheckboxGroup, not intended for direct use
+ */
 import { computed } from "vue";
 import FzCheckbox from "../FzCheckbox.vue";
 import { ParentCheckbox } from "../types";
+import { generateCheckboxId } from "../utils";
 
-FzCheckbox.compatConfig = {
-  MODE: 3,
-};
+const props = defineProps<ParentCheckbox>();
 
-const props = defineProps<ParentCheckbox & { size: "sm" | "md" }>();
-const currentValue = computed(() => props.value ?? props.label);
+/** The actual value used for this checkbox (falls back to label if no value provided) */
+const currentValue = computed<string | number | boolean>(
+  () => props.value ?? props.label,
+);
+
+/**
+ * Two-way binding for selected values.
+ * Shared with parent component and all sibling checkboxes.
+ */
 const model = defineModel<(string | number | boolean)[]>({
   required: true,
   default: [],
 });
 
-const staticChildContainerClass = "flex flex-col justify-center pl-24";
+/**
+ * Unique identifier for this parent checkbox.
+ * Used as a prefix for child checkbox IDs to establish ARIA relationships.
+ */
+const parentId: string = generateCheckboxId();
+
+/**
+ * Computes space-separated list of child checkbox IDs.
+ * Used for aria-owns attribute to establish semantic parent-child relationship.
+ *
+ * @returns Space-separated string of child IDs, or undefined if no children
+ */
+const childrenIds = computed<string | undefined>(() =>
+  props.children?.map((child, index) => `${parentId}-child-${index}`).join(" "),
+);
+
+/** Base layout classes for the children container (indented and vertical) */
+const staticChildContainerClass: string =
+  "flex flex-col justify-center gap-8 pl-24";
 
-const computedChildContainerClasses = computed(() => [
-  props.size === "sm" ? "gap-6 mt-6" : "",
-  props.size === "md" ? "gap-8 mt-8" : "",
-]);
+/** Size-specific spacing for child checkboxes */
+const computedChildContainerClasses = computed<string[]>(() => []);
 
-const isIndeterminate = computed(() => {
+/**
+ * Determines if parent checkbox should be in indeterminate state.
+ * Indeterminate means some, but not all, children are checked.
+ *
+ * States:
+ * - No children: false (not indeterminate)
+ * - No children checked: false (unchecked)
+ * - All children checked: false (fully checked)
+ * - Some children checked: true (indeterminate/partial)
+ *
+ * @returns true if parent should display indeterminate state
+ */
+const isIndeterminate = computed<boolean>(() => {
   if (!props.children) return false;
 
   const numChecked = props.children.filter((child) =>
@@ -59,33 +80,57 @@ const isIndeterminate = computed(() => {
   return numChecked > 0 && numChecked < props.children.length;
 });
 
+/**
+ * Handles child checkbox changes to update parent state.
+ * Called when a child checkbox is toggled.
+ *
+ * Logic:
+ * - If ALL children are now checked → add parent to selection
+ * - If ANY child is unchecked → remove parent from selection
+ *
+ * Note: Uses concat() instead of push() to ensure Vue reactivity triggers.
+ */
 function handleCheckboxParentChange() {
   if (!props.children) return;
+
   const numChecked = props.children.filter((child) =>
     model.value.includes(child.value ?? child.label),
   ).length;
 
   if (numChecked === props.children.length) {
-    // push parent value to model (using concat to force reactivity, push seems to not work)
-    model.value = model.value.concat(currentValue.value);
+    // All children checked: add parent value to model if not already present
+    if (!model.value.includes(currentValue.value)) {
+      model.value = model.value.concat(currentValue.value);
+    }
   } else {
-    // remove parent value from model if it exists
+    // Not all children checked: remove parent value if present
     if (model.value.includes(currentValue.value))
       model.value = model.value.filter((value) => value !== currentValue.value);
   }
 }
 
+/**
+ * Handles parent checkbox changes to cascade to children.
+ * Called when the parent checkbox is clicked.
+ *
+ * Cascade behavior:
+ * - Parent checked → check all children
+ * - Parent unchecked → uncheck all children
+ *
+ * Only modifies children that need changes (doesn't re-add already selected children).
+ */
 function onCheckboxParentChange() {
   if (!props.children) return;
+
   if (model.value.includes(currentValue.value)) {
-    // push all children values to model that are not already in model
+    // Parent is checked: add all unchecked children to model
     model.value = model.value.concat(
       props.children
         ?.map((child) => child.value ?? child.label)
         .filter((value) => !model.value.includes(value)),
     );
   } else {
-    // remove all children values from model
+    // Parent is unchecked: remove all children from model
     model.value = model.value.filter(
       (value) =>
         !props.children
@@ -95,4 +140,50 @@ function onCheckboxParentChange() {
   }
 }
 </script>
-<style scoped></style>
+
+<template>
+  <!-- 
+    Parent checkbox
+    - Displays indeterminate state when children are partially selected
+    - aria-owns links to child checkboxes for screen reader navigation
+    - Change event cascades selection to all children
+  -->
+  <FzCheckbox
+    v-model="model"
+    :value="props.value"
+    :label="props.label"
+    :disabled="disabled"
+    :emphasis="emphasis"
+    :error="error"
+    :indeterminate="isIndeterminate"
+    :aria-owns="children?.length ? childrenIds : undefined"
+    @change="onCheckboxParentChange"
+  >
+    <!-- 
+      Children slot: renders nested child checkboxes
+      Only rendered if children array has items
+    -->
+    <template #children v-if="children?.length">
+      <!-- Indented container for visual hierarchy -->
+      <div :class="[staticChildContainerClass, computedChildContainerClasses]">
+        <!-- 
+          Child checkboxes
+          - Assigned deterministic IDs matching those in parent's aria-owns
+          - Change events update parent's indeterminate state
+          - Share same v-model array with parent and siblings
+        -->
+        <FzCheckbox
+          v-for="(child, index) in children"
+          :key="child.value ? child.value.toString() : child.label"
+          v-model="model"
+          :disabled="disabled"
+          v-bind="child"
+          :emphasis="emphasis"
+          :error="error"
+          :checkbox-id="`${parentId}-child-${index}`"
+          @change="handleCheckboxParentChange"
+        />
+      </div>
+    </template>
+  </FzCheckbox>
+</template>

package/src/index.ts

@@ -1,3 +1,4 @@
 export { default as FzCheckbox } from "./FzCheckbox.vue";
 export { default as FzCheckboxGroup } from "./FzCheckboxGroup.vue";
 export type { FzCheckboxProps, FzCheckboxGroupProps } from "./types";
+export { generateCheckboxId, generateGroupId } from "./utils";

package/src/types.ts

@@ -1,75 +1,218 @@
+/**
+ * Type definitions for the Fiscozen Checkbox component library.
+ *
+ * Provides TypeScript type definitions for checkbox components including
+ * single checkboxes, checkbox groups, and hierarchical checkbox structures.
+ *
+ * @module @fiscozen/checkbox/types
+ */
+import { FzTooltipProps } from "@fiscozen/tooltip";
+
+/**
+ * Props for the FzCheckbox component.
+ *
+ * Supports both single-selection (boolean v-model) and multi-selection (array v-model).
+ * Can be used standalone or as part of a checkbox group.
+ */
 export type FzCheckboxProps = {
   /**
-   * The label of the checkbox
+   * Text label displayed next to the checkbox.
+   * Used for aria-labelledby when not in standalone mode.
    */
   label: string;
+
   /**
-   * The value of the checkbox. If not provided, the value will be the label
+   * Value associated with the checkbox when used in array v-model.
+   * Falls back to label if not provided.
+   *
+   * @default label
    */
   value?: string | number | boolean;
+
   /**
-   * The size of the checkbox
-   */
-  size: "sm" | "md";
-  /**
-   * If the checkbox is checked
+   * Visual size of the checkbox.
+   *
+   * @deprecated This prop is deprecated and will be removed in a future version.
+   * Checkboxes now have a fixed size equivalent to the former "md" size.
    */
-  checked?: boolean;
+  size?: "sm" | "md";
   /**
-   * if the checkbox is indeterminate
+   * Displays indeterminate state (partial selection).
+   * Used for parent checkboxes when some (but not all) children are selected.
+   * Screen readers announce this as "mixed" via aria-checked="mixed".
+   *
+   * @default false
    */
   indeterminate?: boolean;
+
   /**
-   * If true, the checkbox will be emphasized
+   * Applies emphasis styling with blue icon when checked.
+   * Highlights important or primary selection options.
+   *
+   * @default false
    */
   emphasis?: boolean;
+
   /**
-   * If true, the checkbox will be disabled
+   * Disables the checkbox, preventing user interaction.
+   *
+   * @default false
    */
   disabled?: boolean;
+
   /**
-   * If true, the checkbox will be in an error state
+   * Shows error state with red styling.
+   * Use with error slot to display validation messages.
+   *
+   * @default false
    */
   error?: boolean;
+
   /**
-   * If the checkbox is required
+   * Marks the checkbox as required for form validation.
+   * Adds aria-required attribute for accessibility.
+   *
+   * @default false
    */
   required?: boolean;
   /**
-   * If the checkbox is standalone
+   * Renders only the checkbox icon without label text.
+   * Label is used for aria-label instead of being displayed.
+   * Useful for compact UIs or table cells.
+   *
+   * @default false
    */
   standalone?: boolean;
+
+  /**
+   * Configuration for optional tooltip icon.
+   * Displays info icon next to checkbox with hover tooltip.
+   */
+  tooltip?: FzTooltipProps;
+  /**
+   * Space-separated list of child checkbox IDs for aria-owns.
+   * Establishes semantic parent-child relationships for screen readers.
+   * Automatically managed by FzCheckboxGroupOption in hierarchical structures.
+   *
+   * @example "checkbox-child-0 checkbox-child-1 checkbox-child-2"
+   */
+  ariaOwns?: string;
+
+  /**
+   * Custom ID for the checkbox input element.
+   * Auto-generated if not provided using timestamp + random suffix.
+   * Used by FzCheckboxGroupOption for deterministic ARIA relationships.
+   *
+   * @example "my-custom-checkbox-id"
+   */
+  checkboxId?: string;
 };
 
+/**
+ * Props for the FzCheckboxGroup component.
+ *
+ * Container component for managing multiple related checkboxes with shared labeling,
+ * validation, and accessibility features. Supports both flat lists and hierarchical
+ * parent-child checkbox structures with automatic indeterminate state management.
+ */
 export type FzCheckboxGroupProps = {
   /**
-   * The label of the checkbox group
+   * Label text for the entire checkbox group.
+   * Connected to group via aria-labelledby for screen reader accessibility.
    */
   label: string;
+
   /**
-   * The size of the checkbox
+   * Visual size for all checkboxes in the group.
+   *
+   * @deprecated This prop is deprecated and will be removed in a future version.
+   * Checkboxes now have a fixed size equivalent to the former "md" size.
    */
-  size: "sm" | "md";
+  size?: "sm" | "md";
+
   /**
-   * The checkbox to render
+   * Array of checkbox options to render.
+   * Supports flat lists and hierarchical parent-child structures.
+   * Parent checkboxes automatically show indeterminate state when partially selected.
+   *
+   * @example
+   * // Flat list
+   * [
+   *   { label: "Option 1", value: "opt1" },
+   *   { label: "Option 2", value: "opt2" }
+   * ]
+   *
+   * @example
+   * // Hierarchical structure
+   * [
+   *   {
+   *     label: "Parent",
+   *     value: "parent",
+   *     children: [
+   *       { label: "Child 1", value: "child1" },
+   *       { label: "Child 2", value: "child2" }
+   *     ]
+   *   }
+   * ]
    */
   options: ParentCheckbox[];
+
   /**
-   * If true, the checkbox will be emphasized
+   * Applies emphasis styling to all checkboxes in the group.
+   * Icons turn blue when checked.
+   *
+   * @default false
    */
   emphasis?: boolean;
+
   /**
-   * If true, the checkbox will be disabled
+   * Disables all checkboxes in the group.
+   *
+   * @default false
    */
   disabled?: boolean;
+
   /**
-   * If true, the checkbox will be in an error state
+   * Shows error state for all checkboxes.
+   * Use with error slot to display validation messages.
+   *
+   * @default false
    */
   error?: boolean;
+
   /**
-   * If the checkbox group is required
+   * Marks the group as required for form validation.
+   * Adds aria-required to the group container.
+   *
+   * @default false
    */
   required?: boolean;
+
+  /**
+   * Arranges checkboxes horizontally instead of vertically.
+   * Useful for compact layouts or inline forms.
+   *
+   * @default false
+   */
+  horizontal?: boolean;
 };
-export type ParentCheckbox = ChildCheckbox & { children?: ChildCheckbox[] };
+
+/**
+ * Checkbox option that can optionally have child checkboxes.
+ * Used for hierarchical structures with parent-child relationships.
+ * Parent checkboxes automatically display indeterminate state when children are partially selected.
+ */
+export type ParentCheckbox = ChildCheckbox & {
+  /**
+   * Optional array of child checkboxes for hierarchical structures.
+   * Parent shows indeterminate state when some (but not all) children are selected.
+   * Parent checkbox controls all children when toggled.
+   */
+  children?: ChildCheckbox[];
+};
+
+/**
+ * Individual checkbox option within a group.
+ * Inherits all FzCheckboxProps except 'size' which is controlled by the parent group.
+ */
 export type ChildCheckbox = Omit<FzCheckboxProps, "size">;

package/src/utils.ts

@@ -0,0 +1,60 @@
+/**
+ * Utility functions for the Fiscozen Checkbox component library.
+ *
+ * @module @fiscozen/checkbox/utils
+ */
+
+/**
+ * Internal helper function to generate unique IDs with a given prefix.
+ *
+ * The ID is composed of:
+ * - Prefix string (e.g., "fz-checkbox", "fz-checkbox-group")
+ * - Obfuscated timestamp (Date.now() - epoch offset)
+ * - Random alphanumeric suffix (5 characters)
+ *
+ * This strategy ensures uniqueness through:
+ * - Different timestamps for components created at different times
+ * - Random suffix prevents collisions within the same millisecond
+ * - Stateless generation (no global counters to manage)
+ *
+ * @param prefix - The prefix to use for the generated ID
+ * @returns Unique ID with the specified prefix
+ *
+ * @internal
+ *
+ * @example
+ * generateId("fz-checkbox") // "fz-checkbox-97123456-a8d3k"
+ * generateId("fz-checkbox-group") // "fz-checkbox-group-97123457-k2m9p"
+ */
+function generateId(prefix: string): string {
+  // Obfuscate timestamp (Sept 13, 2020 offset) for shorter IDs
+  const timestamp = Date.now() - 1600000000000;
+  // Generate 5-char random alphanumeric suffix (base36: 0-9, a-z)
+  const random = Math.random().toString(36).slice(2, 7);
+  return `${prefix}-${timestamp}-${random}`;
+}
+
+/**
+ * Generates a unique ID for checkbox components.
+ *
+ * @returns Unique checkbox ID with "fz-checkbox" prefix
+ *
+ * @example
+ * generateCheckboxId() // "fz-checkbox-97123456-a8d3k"
+ * generateCheckboxId() // "fz-checkbox-97123457-k2m9p"
+ */
+export function generateCheckboxId(): string {
+  return generateId("fz-checkbox");
+}
+
+/**
+ * Generates a unique ID for checkbox group components.
+ *
+ * @returns Unique checkbox group ID with "fz-checkbox-group" prefix
+ *
+ * @example
+ * generateGroupId() // "fz-checkbox-group-97123456-b7f2n"
+ */
+export function generateGroupId(): string {
+  return generateId("fz-checkbox-group");
+}

package/tsconfig.json

@@ -1,4 +1,4 @@
 {
   "extends": "@fiscozen/tsconfig",
-  "exclude": ["src/__tests__", "vite.config.ts", "vitest.config.ts"]
+  "exclude": ["src/__test__", "vite.config.ts", "vitest.config.ts"]
 }