Add documentation pages for KResponsiveWindow and KResponsiveElement #362
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -75,3 +75,11 @@ html { | |
| *::after { | ||
| box-sizing: inherit; | ||
| } | ||
|
|
||
| dt { | ||
| margin-top: 16px; | ||
| } | ||
|
|
||
| dd { | ||
| margin-left: 20px; | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| <template> | ||
|
|
||
| <DocsPageTemplate apiDocs> | ||
|
|
||
| <DocsPageSection title="Overview" anchor="#overview"> | ||
| <p> | ||
| Once added to a component it provides the following reactive component's size information: | ||
| </p> | ||
|
|
||
| <dl> | ||
| <dt><code>elementHeight</code></dt> | ||
| <dd>The component's element <code>$el</code> height in pixels (integer)</dd> | ||
|
|
||
| <dt><code>elementWidth</code></dt> | ||
| <dd>The component's element <code>$el</code> width in pixels (integer)</dd> | ||
| </dl> | ||
|
|
||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Usage" anchor="#usage"> | ||
| <p>When compared to <DocsLibraryLink component="KResponsiveWindow" />, <code>KResponsiveElement</code> can be suitable when it's the available space determined by the layout which should influence reponsive behavior of a child component rather than relying on the overall window size.</p> | ||
|
|
||
| <h3>As mixin</h3> | ||
| <p>It can be imported as <code>KResponsiveElementMixin</code>. As with any other mixin, you need to register it in the script part of a component file:</p> | ||
|
|
||
| <!-- eslint-disable --> | ||
| <!-- prevent prettier from changing indentation --> | ||
| <DocsShowCode language="javascript"> | ||
| import KResponsiveElementMixin from 'kolibri-design-system/lib/KResponsiveElementMixin'; | ||
|
|
||
| export default { | ||
| mixins: [KResponsiveElementMixin] | ||
| }; | ||
| </DocsShowCode> | ||
| <!-- eslint-enable --> | ||
|
|
||
| <p> | ||
| Provided reactive properties can then be accessed on the component instance via <code>this</code>. | ||
| </p> | ||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Guidelines" anchor="#guidelines"> | ||
| <ul> | ||
| <li> | ||
| Due to performance issues (<DocsExternalLink | ||
| text="Kolibri #8124" | ||
| href="https://github.com/learningequality/kolibri/issues/8124" | ||
| />), using <code>KResponsiveElement</code> in larger numbers on one page is currently discouraged | ||
| </li> | ||
| </ul> | ||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Related" anchor="#related"> | ||
| <ul> | ||
| <li> | ||
| See <DocsLibraryLink component="KResponsiveWindow" /> if you need the window's size reactive information rather than that of a component | ||
| </li> | ||
| </ul> | ||
| </DocsPageSection> | ||
| </DocsPageTemplate> | ||
|
|
||
| </template> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| <template> | ||
|
|
||
| <DocsPageTemplate apiDocs> | ||
|
|
||
| <DocsPageSection title="Overview" anchor="#overview"> | ||
| <p> | ||
| Once added to a component it provides the following reactive window's size information: | ||
| </p> | ||
|
|
||
| <dl> | ||
| <dt><code>windowIsSmall</code>, <code>windowIsMedium</code>, and <code>windowIsLarge</code></dt> | ||
| <dd>Returns <code>true</code> when the window width fits the small, medium, or large breakpoint respectively as defined in <DocsInternalLink text="Layout: Responsiveness" href="/layout#responsiveness" /> (boolean)</dd> | ||
|
|
||
| <dt><code>windowHeight</code></dt> | ||
| <dd>Returns the window height in pixels (integer)</dd> | ||
|
|
||
| <dt><code>windowWidth</code></dt> | ||
| <dd>Returns the window width in pixels (integer)</dd> | ||
|
|
||
| <dt><code>windowBreakpoint</code></dt> | ||
| <dd>Returns one of the more granular breakpoints defined as levels in <DocsInternalLink text="Layout: Responsiveness" href="/layout#responsiveness" /> (integer, 0-7)</dd> | ||
| </dl> | ||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Usage" anchor="#usage"> | ||
| <p>Provided reactive properties are typically used to dynamically drive the layout of components by adjusting inline styles, CSS classes, component visibility, or even swapping out one component for a completely different one.</p> | ||
|
|
||
| <h3>As mixin</h3> | ||
| <p>It can be imported as <code>KResponsiveWindowMixin</code>. As with any other mixin, you need to register it in the script part of a component file:</p> | ||
|
|
||
| <!-- eslint-disable --> | ||
| <!-- prevent prettier from changing indentation --> | ||
| <DocsShowCode language="javascript"> | ||
| import KResponsiveWindowMixin from 'kolibri-design-system/lib/KResponsiveWindowMixin'; | ||
|
|
||
| export default { | ||
| mixins: [KResponsiveWindowMixin] | ||
| }; | ||
| </DocsShowCode> | ||
| <!-- eslint-enable --> | ||
|
|
||
| <p> | ||
| Provided reactive properties can then be accessed on the component instance via <code>this</code>. | ||
| </p> | ||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Example" anchor="#example"> | ||
| <p> | ||
| Consider a Vue file with this in its template and script: | ||
| </p> | ||
| <!-- eslint-disable --> | ||
| <!-- prevent prettier from changing indentation --> | ||
| <DocsShowCode language="html"> | ||
| <div class="box" :style="boxStyle"> | ||
| Box 1 | ||
| </div> | ||
| <div class="box" :style="boxStyle"> | ||
| Box 2 | ||
| </div> | ||
| </DocsShowCode> | ||
|
Comment on lines
+53
to
+60
There was a problem hiding this comment. |
||
| <DocsShowCode language="javascript"> | ||
| computed: { | ||
| boxStyle() { | ||
| if (this.windowIsLarge) { | ||
| return { display: 'inline-block' }; | ||
| } | ||
| return { display: 'block' }; | ||
| }, | ||
| }, | ||
| </DocsShowCode> | ||
| <!-- eslint-enable --> | ||
| <p> | ||
| This results in two boxes that stack vertically on small screens and otherwise display side-by-side: | ||
| </p> | ||
| <DocsShow> | ||
| <div>Breakpoint level: {{ windowBreakpoint }}</div> | ||
| <div>Window is large: {{ windowIsLarge }}</div> | ||
| <div> | ||
| <div class="box" :style="boxStyle"> | ||
| Box 1 | ||
| </div> | ||
| <div class="box" :style="boxStyle"> | ||
| Box 2 | ||
| </div> | ||
| </div> | ||
| </DocsShow> | ||
| <p> | ||
| Try adjusting your browser window size to see the example in action. | ||
| </p> | ||
| </DocsPageSection> | ||
|
|
||
| <DocsPageSection title="Related" anchor="#related"> | ||
| <ul> | ||
| <li> | ||
| <DocsInternalLink text="Layout: Responsiveness" href="/layout#responsiveness" /> has an overview of breakpoints | ||
| </li> | ||
| <li> | ||
| See <DocsLibraryLink component="KResponsiveElement" /> if you need a component's size reactive information rather than that of the window | ||
| </li> | ||
| </ul> | ||
| </DocsPageSection> | ||
| </DocsPageTemplate> | ||
|
|
||
| </template> | ||
|
|
||
|
|
||
| <script> | ||
|
|
||
| import responsiveWindowMixin from '~~/lib/KResponsiveWindowMixin.js'; | ||
|
|
||
| export default { | ||
| mixins: [responsiveWindowMixin], | ||
| computed: { | ||
| boxStyle() { | ||
| return { display: this.windowIsLarge ? 'inline-block' : 'block' }; | ||
| }, | ||
| }, | ||
| }; | ||
|
|
||
| </script> | ||
|
|
||
|
|
||
| <style lang="scss" scoped> | ||
|
|
||
| .box { | ||
| padding: 16px; | ||
| margin-top: 8px; | ||
| margin-right: 8px; | ||
| border: 1px solid gray; | ||
| } | ||
|
|
||
| </style> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the scrollbar/layout issue below is addressed here:
https://github.com/learningequality/kolibri-design-system/pull/358/files#diff-96a81a59d37bb8e964652aaae48543b870906d7339c354f876b599fa7d1547ad