Merge pull request #525 from owncloud/feature/a11y-documentation/star

Refactor and document OcStar(Toggle)

src/elements/OCStar.vue

@@ -1,8 +1,5 @@
 <template>
-  <div class="oc-star">
-    <oc-icon v-show="shining" class="oc-star-shining" name="star" />
-    <oc-icon v-show="!shining" class="oc-star-dimm" name="star_border" />
-  </div>
+  <oc-icon :class="shining ? 'oc-star-shining' : 'oc-star-dimm'" name="star" />
 </template>
 <script>
 /**

src/elements/OcButton.vue

@@ -123,7 +123,7 @@ export default {
       type: String,
       default: "default",
       validator: value => {
-        return value.match(/(default|primary|secondary|danger)/)
+        return value.match(/(default|primary|secondary|danger|raw)/)
       },
     },
     /**

src/elements/OcStarToggle.vue

@@ -0,0 +1,65 @@
+<template>
+  <oc-button
+    variation="raw"
+    role="switch"
+    :aria-checked="checked.toString()"
+    :aria-label="label"
+    @click="$_ocStarToggle_togglePressed"
+  >
+    <oc-star :shining="checked" />
+  </oc-button>
+</template>
+
+<script>
+import OcButton from "./OcButton"
+
+/**
+ *
+ * ## Accessibility
+ *
+ * ### Communicating the buttons toggle role to screen readers
+ * With `role="switch"` screen readers are informed that the button is a toggle, which will have two states: on and off. Toggle buttons like this should be used instead of checkboxes (which make only really sense in form contexts – [reasoning and more background](https://inclusive-components.design/toggle-button/#thisdoesntquitefeelright)).
+ *
+ * ### Communicating the toggle's state to screen readers
+ *
+ * Buttons with `switch` role can convey their state with the `aria-checked` attribute. When using this component, authors can set the initial state of OcStarToggle with the `checked` prop.
+ *
+ * */
+
+export default {
+  name: "oc-star-toggle",
+  components: { OcButton },
+  status: "review",
+  release: "1.0.0",
+  methods: {
+    $_ocStarToggle_togglePressed: function() {
+      this.checked = !this.checked
+    },
+  },
+  props: {
+    /**
+     * Initial state of toggle button
+     **/
+    checked: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Accessible name of toggle button
+     **/
+    label: {
+      type: String,
+      required: true,
+    },
+  },
+}
+</script>
+<docs>
+  ```jsx
+  <h3>OcStarToggle initially not checked</h3>
+  <oc-star-toggle label="Favorite this item"></oc-star-toggle>
+  <h3>OcStarToggle initially checked</h3>
+  <oc-star-toggle checked="true" label="Favorite this item"></oc-star-toggle>
+  ```
+</docs>

src/styles/theme/helper.scss

@@ -2,6 +2,14 @@
   cursor: pointer;
 }
 
+.oc-button-reset {
+  @extend .uk-padding-remove;
+  -webkit-appearance: none;
+  background: transparent;
+  font: inherit;
+  border: none;
+}
+
 .oc-align-self-center {
   align-self: center;
 }

src/styles/theme/oc-button.scss

@@ -46,3 +46,7 @@
     }
   }
 }
+
+.oc-button.uk-button-raw {
+  @extend .oc-button-reset;
+}