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 8 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,724 changes: 1,973 additions & 751 deletions package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

50 changes: 26 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,9 @@
"@skyux/i18n": "^3.5.0",
"@skyux/indicators": "^3.0.0"
},
"dependencies": {},
"dependencies": {
"ajv": "^6.12.0"
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
},
"devDependencies": {
"@angular/animations": "7.2.16",
"@angular/common": "7.2.16",
Expand All @@ -40,43 +42,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.3",
"@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.10.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.5",
"@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.8.2",
"tslint": "5.20.1",
"typescript": "3.2.4",
"zone.js": "0.8.29"
Expand Down
2 changes: 1 addition & 1 deletion skyuxconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,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>
195 changes: 195 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,195 @@
<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
(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>
{{ switchLable }}
</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"
headingType="danger"
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
>
<p>
Don’t use toggles when the options have significant consequences that the user needs to confirm before changes take effect. Use a workflow where users must confirm the changes instead.
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
</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>

<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>
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
<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>
When toggles are in grid columns, the text label is not required if you use a column heading. Use text labels for all other states.
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
If the scenario allows for toggles to become disabled, always include a text label on each toggle.
Copy link
Contributor

Choose a reason for hiding this comment

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

Looking at this again, the opening clause is nonsensical. If the scenario does NOT allow for toggles to become disabled, then toggles shouldn't be used. ... I think what we mean is something more like To make it clear what happens when users select toggles, you can include different text labels for the selected and unselected states. Or something like that.

Again, if we change this, we should probably bounce it off of Adam or Todd.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I went ahead and just made the change, but I can easily just put it back to what it was if they disagree.

@Blackbaud-AdamFunderburk or @Blackbaud-ToddRoberts Any strong thoughts on this change?

Copy link
Contributor

Choose a reason for hiding this comment

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

@Blackbaud-AdamFunderburk and @Blackbaud-ToddRoberts, just checking back in to see if you guys are OK with this change.

Copy link

Choose a reason for hiding this comment

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

I think the new wording is generally good. @Blackbaud-AdamFunderburk I don't remember why we decided that disabled toggles always need labels, even in grids, but I do remember that it was intentional. Should we add that back in?

Copy link
Contributor

Choose a reason for hiding this comment

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

I think it's important to maintain the point that labels should be used if the switches can be disabled.

"If toggle switches can be disabled, include individual text labels to reflect their state."

I understand how tangled that makes the guidelines around the text label, and I'm not sure quite how to optimize them.

</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>
36 changes: 36 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,36 @@
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 switchLable = 'Inactive';
public showLable = true;
public checked = false;

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

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

if (this.showLable === true) {
this.switchLable = this.switchStatus;
}
if (this.showLable === false) {
this.switchLable = ' ';
}
}
}
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>
Blackbaud-DeniseCisneros marked this conversation as resolved.
Show resolved Hide resolved
</li>
</ul>

<h2>
Expand Down
15 changes: 15 additions & 0 deletions ...blic/plugin-resources/code-examples/toggle-switch/basic/toggle-switch-demo.component.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<p>
<sky-toggle-switch formControlName="controlToggle" (toggleChange)="toggleDisabled()">
<sky-toggle-switch-label>
Enable the bottom toggle switch
</sky-toggle-switch-label>
</sky-toggle-switch>
</p>

<p>
<sky-toggle-switch [disabled]="disabled" formControlName="dynamicToggle">
<sky-toggle-switch-label>
This switch can be enabled and disabled dynamically
</sky-toggle-switch-label>
</sky-toggle-switch>
</p>
40 changes: 40 additions & 0 deletions ...public/plugin-resources/code-examples/toggle-switch/basic/toggle-switch-demo.component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
import {
Component
} from '@angular/core';

import {
FormBuilder,
FormControl,
FormGroup
} from '@angular/forms';

@Component({
selector: 'app-toggle-switch-demo',
templateUrl: './toggle-switch-demo.component.html'
})
export class ToggleSwitchDemoComponent {
public checked: boolean = false;
public disabled: boolean = true;

public formGroup: FormGroup;

constructor(
private formBuilder: FormBuilder
) {
this.formGroup = this.formBuilder.group({
dynamicToggle: new FormControl(true)
});
}

public toggleDisabled(): void {
this.disabled = !this.disabled;

const control = this.formGroup.get('dynamicToggle');

if (control.disabled) {
control.enable();
} else {
control.disable();
}
}
}
Loading