From 764b9226f16b135094b3566919b02191ec78dd68 Mon Sep 17 00:00:00 2001 From: nicholasrice Date: Mon, 15 Jun 2020 18:26:27 -0700 Subject: [PATCH 01/31] document switch --- .../fast-foundation/docs/api-report.md | 12 +++--- .../fast-foundation/src/switch/switch.ts | 42 +++++++++++++++++-- 2 files changed, 44 insertions(+), 10 deletions(-) diff --git a/packages/web-components/fast-foundation/docs/api-report.md b/packages/web-components/fast-foundation/docs/api-report.md index 406ecb2ec85..3fccd7de5db 100644 --- a/packages/web-components/fast-foundation/docs/api-report.md +++ b/packages/web-components/fast-foundation/docs/api-report.md @@ -670,24 +670,22 @@ export class StartEnd { // @public (undocumented) export const startTemplate: import("@microsoft/fast-element").ViewTemplate; -// @public (undocumented) +// @public export class Switch extends FormAssociated { constructor(); checked: boolean; - // (undocumented) checkedAttribute: boolean; - // (undocumented) + // @internal (undocumented) clickHandler: (e: MouseEvent) => void; - // (undocumented) + // @internal (undocumented) connectedCallback(): void; defaultChecked: boolean; - // (undocumented) + // @internal (undocumented) defaultSlottedNodes: Node[]; - // (undocumented) + // @internal (undocumented) keypressHandler: (e: KeyboardEvent) => void; // (undocumented) protected proxy: HTMLInputElement; - // (undocumented) readOnly: boolean; value: string; } diff --git a/packages/web-components/fast-foundation/src/switch/switch.ts b/packages/web-components/fast-foundation/src/switch/switch.ts index 7f1c1b4ded2..d026a860ed4 100644 --- a/packages/web-components/fast-foundation/src/switch/switch.ts +++ b/packages/web-components/fast-foundation/src/switch/switch.ts @@ -2,7 +2,19 @@ import { attr, observable } from "@microsoft/fast-element"; import { keyCodeSpace } from "@microsoft/fast-web-utilities"; import { FormAssociated } from "../form-associated/index"; +/** + * An Switch Custom HTML Element. + * Implements the {@link https://www.w3.org/TR/wai-aria-1.1/#switch | ARIA switch }. + * + * @public + */ export class Switch extends FormAssociated { + /** + * When true, the control will be immutable by user interaction. See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute} for more information. + * @public + * @remarks + * HTML Attribute: readonly + */ @attr({ attribute: "readonly", mode: "boolean" }) public readOnly: boolean; // Map to proxy element private readOnlyChanged(): void { @@ -18,6 +30,9 @@ export class Switch extends FormAssociated { /** * The element's value to be included in form submission when checked. * Default to "on" to reach parity with input[type="checkbox"] + * + * @public + * HTML Attribute: value */ @attr public value: string = "on"; // Map to proxy element. @@ -27,18 +42,29 @@ export class Switch extends FormAssociated { } } + /** + * The checked attribute value. This sets the initial checked value. + * + * @public + * HTML Attribute: checked + */ @attr({ attribute: "checked", mode: "boolean" }) public checkedAttribute: boolean; private checkedAttributeChanged(): void { this.defaultChecked = this.checkedAttribute; } + /** + * @internal + */ @observable public defaultSlottedNodes: Node[]; /** * Initialized to the value of the checked attribute. Can be changed independently of the "checked" attribute, * but changing the "checked" attribute always additionally sets this value. + * + * @public */ @observable public defaultChecked: boolean = !!this.checkedAttribute; @@ -53,7 +79,9 @@ export class Switch extends FormAssociated { } /** - * The checked state of the control + * The checked state of the control. + * + * @public */ @observable public checked: boolean = this.defaultChecked; @@ -88,17 +116,23 @@ export class Switch extends FormAssociated { this.proxy.setAttribute("type", "checkbox"); } + /** + * @internal + */ public connectedCallback(): void { super.connectedCallback(); this.updateForm(); } - + private updateForm(): void { const value = this.checked ? this.value : null; this.setFormValue(value, value); } + /** + * @internal + */ public keypressHandler = (e: KeyboardEvent) => { super.keypressHandler(e); @@ -109,7 +143,9 @@ export class Switch extends FormAssociated { } }; - /* eslint-disable-next-line @typescript-eslint/no-unused-vars */ + /** + * @internal + */ public clickHandler = (e: MouseEvent) => { if (!this.disabled && !this.readOnly) { this.checked = !this.checked; From 86f2b667ab9821503c2b2f815a8503b2816aa7f0 Mon Sep 17 00:00:00 2001 From: nicholasrice Date: Mon, 15 Jun 2020 18:48:15 -0700 Subject: [PATCH 02/31] slider docs --- .../fast-foundation/docs/api-report.md | 58 +++++------ .../src/slider-label/slider-label.template.ts | 4 + .../src/slider-label/slider-label.ts | 52 ++++++++++ .../src/slider/slider.template.ts | 4 + .../fast-foundation/src/slider/slider.ts | 95 ++++++++++++++++++- 5 files changed, 177 insertions(+), 36 deletions(-) diff --git a/packages/web-components/fast-foundation/docs/api-report.md b/packages/web-components/fast-foundation/docs/api-report.md index 3fccd7de5db..bf3fc148c21 100644 --- a/packages/web-components/fast-foundation/docs/api-report.md +++ b/packages/web-components/fast-foundation/docs/api-report.md @@ -554,20 +554,18 @@ export const RadioGroupTemplate: import("@microsoft/fast-element").ViewTemplate< // @public (undocumented) export const RadioTemplate: import("@microsoft/fast-element").ViewTemplate; -// @public (undocumented) +// @public export class Slider extends FormAssociated implements SliderConfiguration { constructor(); - // (undocumented) + // @internal (undocumented) connectedCallback(): void; - // (undocumented) decrement: () => void; - // (undocumented) + // @internal (undocumented) direction: Direction; - // (undocumented) + // @internal (undocumented) disconnectedCallback(): void; - // (undocumented) increment: () => void; - // (undocumented) + // @internal (undocumented) isDragging: boolean; // (undocumented) protected keypressHandler: (e: KeyboardEvent) => void; @@ -575,29 +573,28 @@ export class Slider extends FormAssociated implements SliderCo min: number; mode: SliderMode; orientation: Orientation; - // (undocumented) + // @internal (undocumented) position: string; // (undocumented) protected proxy: HTMLInputElement; - // (undocumented) readOnly: boolean; step: number; - // (undocumented) + // @internal (undocumented) thumb: HTMLDivElement; - // (undocumented) + // @internal (undocumented) track: HTMLDivElement; - // (undocumented) + // @internal (undocumented) trackHeight: number; - // (undocumented) + // @internal (undocumented) trackMinHeight: number; - // (undocumented) + // @internal (undocumented) trackMinWidth: number; - // (undocumented) + // @internal (undocumented) trackWidth: number; value: string; } -// @public (undocumented) +// @public export interface SliderConfiguration { // (undocumented) direction?: Direction; @@ -611,44 +608,41 @@ export interface SliderConfiguration { orientation?: Orientation; } -// @public (undocumented) +// @public export class SliderLabel extends FASTElement { - // (undocumented) + // @internal (undocumented) connectedCallback(): void; - // (undocumented) disabled: boolean; - // (undocumented) + // @internal (undocumented) disconnectedCallback(): void; - // (undocumented) + // @internal (undocumented) handleChange(source: any, propertyName: string): void; - // (undocumented) hideMark: boolean; - // (undocumented) position: string; - // (undocumented) + // @internal (undocumented) positionStyle: string; - // (undocumented) + // @internal (undocumented) root: HTMLDivElement; - // (undocumented) + // @internal (undocumented) sliderDirection: Direction; - // (undocumented) + // @internal (undocumented) sliderMaxPosition: number; - // (undocumented) + // @internal (undocumented) sliderMinPosition: number; - // (undocumented) + // @internal (undocumented) sliderOrientation: Orientation; } -// @public (undocumented) +// @public export const SliderLabelTemplate: import("@microsoft/fast-element").ViewTemplate; -// @public (undocumented) +// @public export enum SliderMode { // (undocumented) singleValue = "single-value" } -// @public (undocumented) +// @public export const SliderTemplate: import("@microsoft/fast-element").ViewTemplate; // @public (undocumented) diff --git a/packages/web-components/fast-foundation/src/slider-label/slider-label.template.ts b/packages/web-components/fast-foundation/src/slider-label/slider-label.template.ts index 8ae2cb95f1d..364dd6525d4 100644 --- a/packages/web-components/fast-foundation/src/slider-label/slider-label.template.ts +++ b/packages/web-components/fast-foundation/src/slider-label/slider-label.template.ts @@ -2,6 +2,10 @@ import { html, ref, when } from "@microsoft/fast-element"; import { Orientation } from "@microsoft/fast-web-utilities"; import { SliderLabel } from "./slider-label"; +/** + * The template for the {@link @microsoft/fast-foundation#SliderLabel} component. + * @public + */ export const SliderLabelTemplate = html`