Merge branch 'next' into datarewrite-structures

1 files changed, 54 insertions, 4 deletions

diff --git a/static/components/tab-group-element.ts b/static/ts/components/tab-group-element.ts
index e90997e9..bcd45b40 100644
--- a/static/components/tab-group-element.ts
+++ b/static/ts/components/tab-group-element.ts
@@ -1,3 +1,40 @@
+/**
+ * `<tab-group />`
+
+A group of tabs, where only one can be visible at a time.
+
+@privateRemarks TODO which form does the HTML document have? For CSS purposes
+
+Each tab consists of two parts, a label which is used for selecting
+it, and a tab-element, which contains the actual content. These two
+should refer to each other as follows:
+
+@example
+```
++---------------+     +-----------------+
+|   TabLabel    |     |       Tab       |
++---------------+     +-----------------+
+|            id |<----| aria-labelledby |
+| aria-controls |---->|              id |
++---------------+     +-----------------+
+```
+
+Further information about tabs in HTML can be found here:
+https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role
+
+#### CSS Variables
+
+##### tabcount
+Each tab element has the style property `--tabcount` set to how
+many tabs it has. This is mostly useful to make sure the tab context
+is large enough to fit all tab labels without overflowing.
+
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
+
 import { ComponentVEvent } from './vevent'
 import { makeElement, gensym } from '../lib'
 import { EditRRule } from './edit-rrule'
@@ -6,7 +43,7 @@ import { vcal_objects } from '../globals'
 
 export { TabGroupElement }
 
-/* Lacks a template, since it's trivial
+/** Lacks a template, since it's trivial
    The initial children of this element all becomes tabs, each child may have
    the datapropertys 'label' and 'title' set, where label is what is shown in
    the tab bar, and title is the hower text.
@@ -21,9 +58,12 @@ export { TabGroupElement }
 */
 class TabGroupElement extends ComponentVEvent {
 
+    /** The container holding all the tabLabels */
     readonly menu: HTMLElement;
 
+    /** Contents of each tab */
     tabs: HTMLElement[] = [];
+    /** Label element of each tab */
     tabLabels: HTMLElement[] = [];
 
     constructor(uid?: string) {
@@ -81,6 +121,12 @@ class TabGroupElement extends ComponentVEvent {
 
     } /* end connectedCallback */
 
+    /**
+       Adds a new tab to the group. The first parameter will make up the body
+       of the tab. The label is whath should be shown in the tab selector,
+       but defaults to the first letter of the text content of the body node.
+       Title is the hoover text of the label.
+    */
     addTab(child: HTMLElement, label?: string, title?: string) {
 
         /* First character of text is a good a guess as any for our label,
@@ -123,11 +169,15 @@ class TabGroupElement extends ComponentVEvent {
         this.tabLabels.push(tabLabel);
         this.menu.appendChild(tabLabel);
 
-        tabLabel.addEventListener('click', () => this.tabClickedCallback(tabLabel));
+        tabLabel.addEventListener('click', () => this.#tabClickedCallback(tabLabel));
 
         this.style.setProperty('--tabcount', '' + this.tabs.length);
     }
 
+    /**
+       HTMLElement must be one of the tab bodies in this group. This method
+       removes it, along with its TabLabel.
+    */
     removeTab(tab: HTMLElement) {
         let id = tab.getAttribute('aria-labelledby')!
         let label = document.getElementById(id)
@@ -152,7 +202,7 @@ class TabGroupElement extends ComponentVEvent {
     }
 
     /* TODO replace querySelectors here with our already saved references */
-    tabClickedCallback(tab: Element) {
+    #tabClickedCallback(tab: Element) {
 
         /* hide all tab panels */
         for (let tabcontent of this.querySelectorAll('[role="tabpanel"]')) {
@@ -171,7 +221,7 @@ class TabGroupElement extends ComponentVEvent {
     }
 
 
-    /* returns our rrule tab if we have one */
+    /** Return our rrule tab if we have one */
     has_rrule_tab(): Element | false {
         for (let child of this.children) {
             if (child.firstChild! instanceof EditRRule) {