render task list items with a checkbox (#433)

rdar://100145156

Co-authored-by: Marcus Ortiz <marcus_ortiz@apple.com>

Author: QuietMisdreavus

src/components/ContentNode.vue

@@ -26,6 +26,7 @@ import BlockVideo from './ContentNode/BlockVideo.vue';
 import Column from './ContentNode/Column.vue';
 import Row from './ContentNode/Row.vue';
 import TabNavigator from './ContentNode/TabNavigator.vue';
+import TaskList from './ContentNode/TaskList.vue';
 
 const BlockType = {
   aside: 'aside',
@@ -279,10 +280,23 @@ function renderNode(createElement, references) {
           renderChildren(definition.content)
         )),
       ]));
-    case BlockType.unorderedList:
-      return createElement('ul', {}, (
-        renderListItems(node.items)
-      ));
+    case BlockType.unorderedList: {
+      const isTaskList = list => TaskList.props.tasks.validator(list.items);
+      return isTaskList(node) ? (
+        createElement(TaskList, {
+          props: {
+            tasks: node.items,
+          },
+          scopedSlots: {
+            task: slotProps => renderChildren(slotProps.task.content),
+          },
+        })
+      ) : (
+        createElement('ul', {}, (
+          renderListItems(node.items)
+        ))
+      );
+    }
     case BlockType.dictionaryExample: {
       const props = {
         example: node.example,

src/components/ContentNode/TaskList.vue

@@ -0,0 +1,63 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <ul class="tasklist">
+    <li v-for="(task, i) in tasks" :key="i">
+      <input v-if="showCheckbox(task)" type="checkbox" disabled :checked="task.checked" />
+      <slot name="task" :task="task" />
+    </li>
+  </ul>
+</template>
+
+<script>
+const CHECKED_PROP = 'checked';
+
+const hasCheckedProp = obj => Object.hasOwnProperty.call(obj, CHECKED_PROP);
+
+export default {
+  name: 'TaskList',
+  props: {
+    tasks: {
+      required: true,
+      type: Array,
+      // A task list is an unordered list that has at least one item with a
+      // boolean `checked` property
+      validator: list => list.some(hasCheckedProp),
+    },
+  },
+  methods: {
+    showCheckbox: hasCheckedProp,
+  },
+};
+</script>
+
+<style scoped lang="scss">
+.tasklist {
+  --checkbox-width: 1rem;
+  --indent-width: calc(var(--checkbox-width) / 2);
+  --content-margin: var(--indent-width);
+
+  list-style-type: none;
+  margin-left: var(--indent-width);
+}
+
+p {
+  margin-left: var(--content-margin);
+
+  &:only-child {
+    --content-margin: calc(var(--checkbox-width) + var(--indent-width));
+  }
+
+  input[type="checkbox"] + & {
+    display: inline-block;
+  }
+}
+</style>

tests/unit/components/ContentNode.spec.js

@@ -8,7 +8,7 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import { shallowMount } from '@vue/test-utils';
+import { shallowMount, mount } from '@vue/test-utils';
 import Aside from 'docc-render/components/ContentNode/Aside.vue';
 import CodeListing from 'docc-render/components/ContentNode/CodeListing.vue';
 import CodeVoice from 'docc-render/components/ContentNode/CodeVoice.vue';
@@ -27,6 +27,7 @@ import BlockVideo from '@/components/ContentNode/BlockVideo.vue';
 import Row from '@/components/ContentNode/Row.vue';
 import Column from '@/components/ContentNode/Column.vue';
 import TabNavigator from '@/components/ContentNode/TabNavigator.vue';
+import TaskList from 'docc-render/components/ContentNode/TaskList.vue';
 
 const { TableHeaderStyle } = ContentNode.constants;
 
@@ -325,6 +326,58 @@ describe('ContentNode', () => {
       expect(items.at(0).find('p').text()).toBe('foo');
       expect(items.at(1).find('p').text()).toBe('bar');
     });
+
+    it('renders a `TaskList` for checked items', () => {
+      const items = [
+        {
+          checked: true,
+          content: [
+            {
+              type: 'paragraph',
+              inlineContent: [
+                {
+                  type: 'text',
+                  text: 'foo',
+                },
+              ],
+            },
+          ],
+        },
+        {
+          checked: false,
+          content: [
+            {
+              type: 'paragraph',
+              inlineContent: [
+                {
+                  type: 'text',
+                  text: 'bar',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      const wrapper = mount(ContentNode, {
+        propsData: {
+          content: [
+            {
+              type: 'unorderedList',
+              items,
+            },
+          ],
+        },
+      });
+
+      const list = wrapper.find(TaskList);
+      expect(list.exists()).toBe(true);
+      expect(list.props('tasks')).toEqual(items);
+
+      const paragraphs = list.findAll('li p');
+      expect(paragraphs.length).toBe(items.length);
+      expect(paragraphs.at(0).text()).toBe('foo');
+      expect(paragraphs.at(1).text()).toBe('bar');
+    });
   });
 
   describe('with type="small"', () => {

tests/unit/components/ContentNode/TaskList.spec.js

@@ -0,0 +1,71 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2022 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import { shallowMount } from '@vue/test-utils';
+import TaskList from 'docc-render/components/ContentNode/TaskList.vue';
+
+describe('ContentNode', () => {
+  const createWrapper = options => shallowMount(TaskList, options);
+
+  it('renders a list with a disabled checkbox for each list item', () => {
+    const tasks = [
+      { checked: false },
+      { checked: true },
+    ];
+
+    const wrapper = createWrapper({
+      propsData: { tasks },
+    });
+    expect(wrapper.is('ul.tasklist')).toBe(true);
+
+    const checkboxes = wrapper.findAll('li input[disabled][type="checkbox"]');
+    expect(checkboxes.length).toBe(tasks.length);
+    expect(checkboxes.at(0).element.checked).toBe(tasks[0].checked);
+    expect(checkboxes.at(1).element.checked).toBe(tasks[1].checked);
+  });
+
+  it('renders slot content for tasks', () => {
+    const tasks = [
+      { checked: false, text: 'foo' },
+      { checked: true, text: 'bar' },
+    ];
+
+    const wrapper = createWrapper({
+      propsData: { tasks },
+      scopedSlots: {
+        task: function render(slotProps) {
+          return this.$createElement('p', slotProps.task.text);
+        },
+      },
+    });
+
+    const paragraphs = wrapper.findAll('li p');
+    expect(paragraphs.length).toBe(tasks.length);
+    expect(paragraphs.at(0).text()).toBe(tasks[0].text);
+    expect(paragraphs.at(1).text()).toBe(tasks[1].text);
+  });
+
+  it('does not render checkbox for items without `checked` prop', () => {
+    const tasks = [
+      { checked: false, content: 'foo' },
+      { content: 'bar' },
+      { checked: true, content: 'baz' },
+    ];
+
+    const wrapper = createWrapper({
+      propsData: { tasks },
+    });
+    const items = wrapper.findAll('li');
+    expect(items.length).toBe(tasks.length);
+    expect(items.at(0).find('input[type="checkbox"]').exists()).toBe(true);
+    expect(items.at(1).find('input[type="checkbox"]').exists()).toBe(false);
+    expect(items.at(2).find('input[type="checkbox"]').exists()).toBe(true);
+  });
+});