Skip to content
This repository has been archived by the owner on Dec 8, 2022. It is now read-only.

Toggle Switch - Phase 2 docs #109

Merged
merged 19 commits into from
Apr 28, 2020
Merged

Toggle Switch - Phase 2 docs #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
c5d1d2f
First pass of adding phase 2 of toggle switch docs
Blackbaud-DeniseCisneros Mar 18, 2020
0d91d9d
Added docs tools styles & related components
Blackbaud-DeniseCisneros Mar 20, 2020
8fa6c76
Add design demo
Blackbaud-SomaliaJamall Apr 15, 2020
8d54e8b
Clean up code for e2e check
Blackbaud-SomaliaJamall Apr 15, 2020
bccee86
Remove unused imports
Blackbaud-SomaliaJamall Apr 15, 2020
cce4f9e
Merge branch 'master' into toggleswitch-phase2
Blackbaud-DeniseCisneros Apr 15, 2020
df16779
Add code demo
Blackbaud-SomaliaJamall Apr 17, 2020
2ef5976
Merge branch 'master' into toggleswitch-phase2
blackbaud-johnly Apr 20, 2020
ff72157
Update the pact package
Blackbaud-SomaliaJamall Apr 20, 2020
a19036d
Fix visual
Blackbaud-SteveBrush Apr 21, 2020
a76be76
Implemented feedback
Blackbaud-DeniseCisneros Apr 21, 2020
c18222f
Fixed formatting issues
Blackbaud-DeniseCisneros Apr 22, 2020
3299e53
updated dev dependencies
Blackbaud-DeniseCisneros Apr 22, 2020
22c0f5a
Fix demo
Blackbaud-SteveBrush Apr 27, 2020
c924544
Add default value for `checked`
Blackbaud-SteveBrush Apr 27, 2020
003de9a
Added description for toggle switch label
Blackbaud-DeniseCisneros Apr 27, 2020
043c25d
Merge branch 'toggleswitch-phase2' of https://github.com/blackbaud/sk…
Blackbaud-DeniseCisneros Apr 27, 2020
cdef3fe
Added description for SkyToggleSwitchChange
Blackbaud-DeniseCisneros Apr 27, 2020
3f856d7
Updating with revised text
Blackbaud-DeniseCisneros Apr 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,793 changes: 2,144 additions & 649 deletions package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

47 changes: 23 additions & 24 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@
"@skyux/i18n": "^3.5.0",
"@skyux/indicators": "^3.0.0"
},
"dependencies": {},
"devDependencies": {
"@angular/animations": "7.2.16",
"@angular/common": "7.2.16",
Expand All @@ -40,43 +39,43 @@
"@angular/platform-browser": "7.2.16",
"@angular/platform-browser-dynamic": "7.2.16",
"@angular/router": "7.2.16",
"@blackbaud/auth-client": "2.22.0",
"@blackbaud/auth-client": "2.24.0",
"@blackbaud/skyux-lib-clipboard": "1.1.1",
"@blackbaud/skyux-lib-code-block": "1.3.1",
"@blackbaud/skyux-lib-code-block": "1.4.0",
"@blackbaud/skyux-lib-media": "1.2.0",
"@blackbaud/skyux-lib-stache": "3.2.3",
"@pact-foundation/pact": "9.6.1",
"@blackbaud/skyux-lib-stache": "3.3.0",
"@pact-foundation/pact": "9.9.12",
"@pact-foundation/pact-web": "7.4.0",
"@skyux-sdk/builder": "3.14.0",
"@skyux-sdk/builder-plugin-skyux": "1.2.2",
"@skyux-sdk/builder": "3.16.2",
"@skyux-sdk/builder-plugin-skyux": "1.3.1",
"@skyux-sdk/e2e": "3.1.2",
"@skyux-sdk/pact": "3.3.1",
"@skyux-sdk/testing": "3.1.0",
"@skyux-sdk/testing": "3.2.0",
"@skyux/animations": "3.0.0",
"@skyux/assets": "3.1.0",
"@skyux/config": "3.7.0",
"@skyux/core": "3.10.1",
"@skyux/docs-tools": "3.1.0",
"@skyux/config": "3.8.1",
"@skyux/core": "3.14.2",
"@skyux/docs-tools": "3.2.0",
"@skyux/forms": "^3.4.0",
"@skyux/http": "3.9.0",
"@skyux/i18n": "3.9.3",
"@skyux/indicators": "3.1.2",
"@skyux/i18n": "3.11.0",
"@skyux/indicators": "3.1.3",
"@skyux/inline-form": "3.1.0",
"@skyux/layout": "3.6.2",
"@skyux/lists": "3.8.0",
"@skyux/lookup": "3.2.0",
"@skyux/modals": "3.1.2",
"@skyux/layout": "3.9.0",
"@skyux/lists": "3.8.6",
"@skyux/lookup": "3.4.1",
"@skyux/modals": "3.2.0",
"@skyux/omnibar-interop": "3.1.0",
"@skyux/popovers": "3.4.0",
"@skyux/popovers": "3.5.2",
"@skyux/router": "3.1.1",
"@skyux/tabs": "3.2.4",
"@skyux/theme": "3.9.0",
"@types/core-js": "2.5.2",
"@skyux/tabs": "3.2.6",
"@skyux/theme": "3.12.0",
"@types/core-js": "2.5.3",
"codelyzer": "4.5.0",
"core-js": "2.6.11",
"rxjs": "6.5.4",
"rxjs-compat": "6.5.4",
"ts-node": "8.6.2",
"rxjs": "6.5.5",
"rxjs-compat": "6.5.5",
"ts-node": "8.9.0",
"tslint": "5.20.1",
"typescript": "3.2.4",
"zone.js": "0.8.29"
Expand Down
7 changes: 6 additions & 1 deletion skyuxconfig.e2e.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
{
"omnibar": false
"omnibar": false,
"app": {
"styles": [
"src/app/visual-styles.scss"
]
}
}
3 changes: 1 addition & 2 deletions skyuxconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,7 @@
},
"app": {
"styles": [
"@skyux/theme/css/sky.css",
"src/app/visual-styles.scss"
"@skyux/docs-tools/css/docs-tools.css"
]
}
}
2 changes: 2 additions & 0 deletions src/app/docs/toggle-switch/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<app-toggle-switch-docs>
</app-toggle-switch-docs>
202 changes: 202 additions & 0 deletions src/app/docs/toggle-switch/toggle-switch-docs.component.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
<sky-docs-demo-page
moduleName="SkyToggleSwitchModule"
moduleSourceCodePath="src/app/public/modules/toggle-switch/"
pageTitle="Toggle Switch"
>

<sky-docs-demo-page-summary>
The toggle switch component renders a SKY UX-themed switch for values that can either be "on" or "off." The change takes effect immediately.
</sky-docs-demo-page-summary>

<sky-docs-demo>
blackbaud-johnly marked this conversation as resolved.
Show resolved Hide resolved
<sky-docs-demo-control-panel
(reset)="onReset()"
(selectionChange)="onDemoSelectionChange($event)"
>
<sky-docs-demo-control-panel-section>
<sky-docs-demo-control-panel-checkbox
label="Include text label"
propertyName="toggleLabel"
[checked]="true"
>
</sky-docs-demo-control-panel-checkbox>
</sky-docs-demo-control-panel-section>
</sky-docs-demo-control-panel>

<sky-toggle-switch
[(ngModel)]="checked"
(toggleChange)="onDemoSelectionChange($event)"
>
<sky-toggle-switch-label *ngIf="showLabel">
{{ switchLabel }}
</sky-toggle-switch-label>
</sky-toggle-switch>
</sky-docs-demo>

<sky-docs-design-guidelines>

<sky-docs-demo-page-section
heading="Usage"
>
<sky-docs-design-guideline
heading="Use when"
headingStyle="success"
>
<p>
Use toggles when users can toggle between two states or options, and the changes take effect immediately.
</p>

<sky-docs-design-guideline-thumbnail
caption="Do use toggles to alternate between two states when changes take effect immediately."
captionType="success"
imageSource="~/assets/img/guidelines/toggle-switch/toggle-usage-1.png"
>
</sky-docs-design-guideline-thumbnail>

<sky-docs-design-guideline-thumbnail
caption="Do use toggles to set binary states on multiple items."
captionType="success"
imageSource="~/assets/img/guidelines/toggle-switch/toggle-usage-2.png"
>
</sky-docs-design-guideline-thumbnail>
</sky-docs-design-guideline>

<sky-docs-design-guideline
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
heading="Don't use when"
headingStyle="danger"
>
<p>
Don’t use toggles when the options have significant consequences that the users need to confirm before changes take effect. Use a workflow where users must confirm the changes instead.
</p>

<sky-docs-design-guideline-thumbnail
caption="Don't use toggles for states with significant consequences."
captionType="danger"
imageSource="~/assets/img/guidelines/toggle-switch/toggle-usage-3.png"
>
</sky-docs-design-guideline-thumbnail>
</sky-docs-design-guideline>

<sky-docs-design-guideline
>
<p>
Don't use toggles when the input is presented in a modal. Use <a href="https://developer.blackbaud.com/skyux/components/checkbox">checkboxes</a> instead.
</p>

<sky-docs-design-guideline-thumbnail
caption="Don't use toggles inside modals where they won't take effect immediately."
captionType="danger"
imageSource="~/assets/img/guidelines/toggle-switch/toggle-usage-4.png"
>
</sky-docs-design-guideline-thumbnail>
</sky-docs-design-guideline>
</sky-docs-demo-page-section>

<sky-docs-demo-page-section
heading="Anatomy"
>
<sky-docs-anatomy
imagePath="~/assets/img/guidelines/toggle-switch/toggle-anatomy.png"
>
<sky-docs-anatomy-item>Toggle body</sky-docs-anatomy-item>
<sky-docs-anatomy-item isOptional="true">Text label</sky-docs-anatomy-item>
</sky-docs-anatomy>
</sky-docs-demo-page-section>

<sky-docs-demo-page-section
heading="Options"
>
<sky-docs-design-guideline
heading="Text label"
>
<p>
Text labels describe the properties that toggles control, and you can provide labels for both the selected and unselected states. Always include text labels unless other labels clearly indicate the purpose of toggles. For example, when toggles are in grids, you can rely on column headings instead of text labels.
</p>
<p>
In scenarios where toggles may become disabled, always include labels for both the selected and unselected states to make those states clear to users.
</p>
</sky-docs-design-guideline>
</sky-docs-demo-page-section>

<sky-docs-demo-page-section
heading="Behavior & states"
>
<table class="sky-docs-table">
<tr>
<td class="sky-docs-table-cell sky-docs-table-cell-primary">
Unselected
</td>
<td class="sky-docs-table-cell">
<sky-docs-design-guideline-thumbnail
imageSource="~/assets/img/guidelines/toggle-switch/toggle-state-unselected.png"
>
</sky-docs-design-guideline-thumbnail>
</td>
</tr>
<tr>
<td class="sky-docs-table-cell">
Selected
</td>
<td class="sky-docs-table-cell">
<sky-docs-design-guideline-thumbnail
imageSource="~/assets/img/guidelines/toggle-switch/toggle-state-selected.png"
>
</sky-docs-design-guideline-thumbnail>
</td>
</tr>
<tr>
<td class="sky-docs-table-cell">
Hover
</td>
<td class="sky-docs-table-cell">
<sky-docs-design-guideline-thumbnail
imageSource="~/assets/img/guidelines/toggle-switch/toggle-state-hover.png"
>
</sky-docs-design-guideline-thumbnail>
</td>
</tr>
<tr>
<td class="sky-docs-table-cell">
Disable unselected
</td>
<td class="sky-docs-table-cell">
<sky-docs-design-guideline-thumbnail
imageSource="~/assets/img/guidelines/toggle-switch/toggle-state-disabled-unselected.png"
>
</sky-docs-design-guideline-thumbnail>
</td>
</tr>
<tr>
<td class="sky-docs-table-cell">
Disable selected
</td>
<td class="sky-docs-table-cell">
<sky-docs-design-guideline-thumbnail
imageSource="~/assets/img/guidelines/toggle-switch/toggle-state-disabled-selected.png"
>
</sky-docs-design-guideline-thumbnail>
</td>
</tr>
</table>
</sky-docs-demo-page-section>

<sky-docs-demo-page-section
heading="Related content"
>
<sky-docs-design-guideline
heading="Components"
>
<ul>
<li><a href="https://developer.blackbaud.com/skyux/components/checkbox">Checkbox</a></li>
<li><a href="https://developer.blackbaud.com/skyux/components/radio">Radio button</a></li>
</ul>
</sky-docs-design-guideline>
</sky-docs-demo-page-section>
</sky-docs-design-guidelines>

<sky-docs-code-examples>
<sky-docs-code-example heading="Toggle"
sourceCodePath="src/app/public/plugin-resources/code-examples/toggle-switch/basic"></sky-docs-code-example>
</sky-docs-code-examples>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Development tab content is missing. We need to add JSDoc comments. We just need to copy the content from the existing Development tab (minus the This property accepts... part) and paste it as JSDoc comments https://github.com/blackbaud/skyux-forms/blob/master/src/app/public/modules/toggle-switch/toggle-switch.component.ts. If you need an example, see the JSDoc comments for dropover at https://github.com/blackbaud/skyux-popovers/blob/master/src/app/public/modules/dropdown/dropdown.component.ts.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it looks like we only have one code example. In the old demo, we had an example of a reactive form and a template-driven form. Should we have both here as well? Might be worth asking Steve about that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I copied the code example from the specs that @Blackbaud-AdamFunderburk created, I know there's a few of them that are a bit different from the old code demos. I assumed the new ones had already been vetted, perhaps adam can weigh in?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template-driven form vs. reactive form difference might not matter in phase 2 docs. We can ask Adam at the docs check-in on Tuesday.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✔️

</sky-docs-demo-page>
31 changes: 31 additions & 0 deletions src/app/docs/toggle-switch/toggle-switch-docs.component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import {
Component
} from '@angular/core';

import {
SkyDocsDemoControlPanelChange
} from '@skyux/docs-tools';

@Component({
selector: 'app-toggle-switch-docs',
templateUrl: './toggle-switch-docs.component.html'
})
export class ToggleSwitchComponent {
public demoSettings: any = {};
public showLabel = true;
public checked = false;

public get switchLabel(): string {
return (this.checked === true) ? 'Active' : 'Inactive';
}

public onDemoSelectionChange(change: SkyDocsDemoControlPanelChange): void {
if (change.toggleLabel !== undefined) {
this.showLabel = change.toggleLabel;
}
}

public onReset(): void {
this.checked = false;
}
}
3 changes: 3 additions & 0 deletions src/app/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ <h2>
<li>
<a skyAppLink="/docs/radio">Radio</a>
</li>
<li>
<a skyAppLink="/docs/toggle-switch">Toggle switch</a>
</li>
</ul>

<h2>
Expand Down
3 changes: 3 additions & 0 deletions src/app/public/modules/toggle-switch/toggle-switch-label.component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ import {
Component
} from '@angular/core';

/**
* Specifies the label to display beside the toggle switch.
*/
@Component({
selector: 'sky-toggle-switch-label',
templateUrl: './toggle-switch-label.component.html',
Expand Down
16 changes: 16 additions & 0 deletions src/app/public/modules/toggle-switch/toggle-switch.component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,16 @@ let uniqueId = 0;
})
export class SkyToggleSwitchComponent implements AfterContentInit, OnDestroy, ControlValueAccessor, Validator {

/**
* Sets the `aria-label` attribute of the toggle switch. Only use this value if the `sky-toggle-switch-label` component is not used.
*/
@Input()
public ariaLabel: string;

/**
* Indicates whether the toggle switch is selected.
* @default false
*/
@Input()
public set checked(checked: boolean) {
if (checked !== this.checked) {
Expand All @@ -84,12 +91,21 @@ export class SkyToggleSwitchComponent implements AfterContentInit, OnDestroy, Co
return this._checked || false;
}

/**
* Indicates whether to disable the toggle switch.
*/
@Input()
public disabled = false;

/**
* Specifies a tab index for the toggle switch. If not defined, the index is set to the position of the toggle switch on load.
*/
@Input()
public tabIndex = 0;

/**
* Fires when the checked state of a toggle switch changes.
*/
@Output()
public toggleChange = new EventEmitter<SkyToggleSwitchChange>();

Expand Down
Loading