🙂 Looking for an issue? Welcome! This issue is open for contribution. If this is the first time you’re requesting an issue, please:

• Read Contributing guidelines carefully. Pay extra attention to Using generative AI. Pull requests and comments that don’t follow the guidelines won’t be answered.
• Confirm that you’ve read the guidelines in your comment.

Sub-issue of learningequality/studio#5060.

Complexity: Medium

Summary

Add v-model support to KCheckbox.

Currently, KCheckbox doesn't support v-model and so to dynamically update selected choices, there's a need to use the combination of :checked and @changed, for example:

<KCheckbox
  v-for="group in groups"
  :label="group.name"
  :key="group.id"
  :checked="groupIsSelected(group)"
  @change="toggleGroup($event, group)"
/>

export default {
  data() {
    return {
      groups: [
        { "id": "group-1", "name": "First group", },
        { "id": "group-2", "name": "Second group" },
        { "id": "group-3", "name": "Third group" }
      ],
      selectedGroupIds: [],
    };
  },
  methods: {
    groupIsSelected({ id }) {
      return this.selectedGroupIds.includes(id);
    },
    toggleGroup(isChecked, { id }) {
      if (isChecked) {
        this.selectedGroupIds = [...this.selectedGroupIds, id];
      } else {
        this.selectedGroupIds = this.selectedGroupIds.filter(
          groupId => groupId !== id,
        );
      }
    },
  },
};

The goal of this issue is to add logic to KCheckbox that will allow simplification of the above example into

<KCheckbox
  v-for="group in groups"
  v-model="selectedGroupIds"
  :label="group.name"
  :key="group.id"
  :value="group.id"
/>

export default {
  data() {
    return {
      groups: [
        { "id": "group-1", "name": "First group", },
        { "id": "group-2", "name": "Second group" },
        { "id": "group-3", "name": "Third group" }
      ],
      selectedGroupIds: [],
    };
  },
};

where value holds a value to be added/removed to/from the array referenced in v-model when the checkbox is checked/unchecked.

Furthemore, v-model should not only support arrays, but also the following types (typically used in scenarios with a single checkbox):

Boolean

If checked, isSelected will become true, otherwise false. Note that here, value is not needed.

<KCheckbox
  v-model="isSelected"
/>

Number

If checked, selectedNumber will be set to value, otherwise null.

<KCheckbox
  v-model="selectedNumber"
  :value="1"
/>

String

If checked, selectedString will be set to value, otherwise null.

<KCheckbox
  v-model="selectedString"
  :value="'String'"
/>

Object

If checked, selectedObject will be set to value, otherwise null.

<KCheckbox
  v-model="selectedObject"
  :value="{ id: 1, name: 'Name 1' }"
/>

Value add

In support of learningequality/studio#5060. Will allow removal of the temporary Checkbox wrapper in favour of the native KCheckbox.

Guidance

• Code from Studio's Checkbox, which has v-model logic added on top of KCheckbox can be re-used.
• Note how the indeterminate state currently overrides checked state. This behavior should be preserved when KCheckbox used with v-model.
• Getting started
• How to update library
• Visual testing guide
• How to update the documentation website
• Writing guidelines
• Refer to other component documentation pages, e.g. KCard documentation (source code)

Acceptance criteria

• There are unit tests. Do not use obsolete @vue/test-utils approach. Instead, use @testing-library/vue (Vue Testing Library).
• There are visual tests
• v-model is documented on KCheckbox documentation page, including new examples. Documentation style follows the writing guidelines, is concise and consistent with the existing documentation.