diff --git a/CHANGELOG.md b/CHANGELOG.md
index afb7ad001..de870ba83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ Releases are recorded as git tags in the [Github releases](https://github.com/le
## Version 1.4.x
- [#185] - Handle arrow key navigation and improve focusOutline
- [#338] - Allow for new 'nav' slot inline in the toolbar
+- [#362] - Add documentation pages for 'KResponsiveWindow' and 'KResponsiveElement'
+
+
+[#185]: https://github.com/learningequality/kolibri-design-system/pull/185
+[#338]: https://github.com/learningequality/kolibri-design-system/pull/338
+[#362]: https://github.com/learningequality/kolibri-design-system/pull/362
## Version 1.3.1
diff --git a/docs/assets/main.scss b/docs/assets/main.scss
index b5a0fa5ca..541c1a37e 100644
--- a/docs/assets/main.scss
+++ b/docs/assets/main.scss
@@ -75,3 +75,11 @@ html {
*::after {
box-sizing: inherit;
}
+
+dt {
+ margin-top: 16px;
+}
+
+dd {
+ margin-left: 20px;
+}
diff --git a/docs/pages/kresponsiveelement.vue b/docs/pages/kresponsiveelement.vue
new file mode 100644
index 000000000..615af2a81
--- /dev/null
+++ b/docs/pages/kresponsiveelement.vue
@@ -0,0 +1,62 @@
+
+
+
+
+
+
+ Once added to a component it provides the following reactive component's size information:
+
+
+
+ elementHeight- The component's element
$el height in pixels (integer)
+
+ elementWidth- The component's element
$el width in pixels (integer)
+
+
+
+
+
+ When compared to , KResponsiveElement 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.
+
+ As mixin
+ It can be imported as KResponsiveElementMixin. As with any other mixin, you need to register it in the script part of a component file:
+
+
+
+
+ import KResponsiveElementMixin from 'kolibri-design-system/lib/KResponsiveElementMixin';
+
+ export default {
+ mixins: [KResponsiveElementMixin]
+ };
+
+
+
+
+ Provided reactive properties can then be accessed on the component instance via this.
+
+
+
+
+
+ -
+ Due to performance issues (), using
KResponsiveElement in larger numbers on one page is currently discouraged
+
+
+
+
+
+
+ -
+ See if you need the window's size reactive information rather than that of a component
+
+
+
+
+
+
diff --git a/docs/pages/kresponsivewindow.vue b/docs/pages/kresponsivewindow.vue
new file mode 100644
index 000000000..a469d76b0
--- /dev/null
+++ b/docs/pages/kresponsivewindow.vue
@@ -0,0 +1,132 @@
+
+
+
+
+
+
+ Once added to a component it provides the following reactive window's size information:
+
+
+
+ windowIsSmall, windowIsMedium, and windowIsLarge- Returns
true when the window width fits the small, medium, or large breakpoint respectively as defined in (boolean)
+
+ windowHeight- Returns the window height in pixels (integer)
+
+ windowWidth- Returns the window width in pixels (integer)
+
+ windowBreakpoint- Returns one of the more granular breakpoints defined as levels in (integer, 0-7)
+
+
+
+
+ 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.
+
+ As mixin
+ It can be imported as KResponsiveWindowMixin. As with any other mixin, you need to register it in the script part of a component file:
+
+
+
+
+ import KResponsiveWindowMixin from 'kolibri-design-system/lib/KResponsiveWindowMixin';
+
+ export default {
+ mixins: [KResponsiveWindowMixin]
+ };
+
+
+
+
+ Provided reactive properties can then be accessed on the component instance via this.
+
+
+
+
+
+ Consider a Vue file with this in its template and script:
+
+
+
+
+ <div class="box" :style="boxStyle">
+ Box 1
+ </div>
+ <div class="box" :style="boxStyle">
+ Box 2
+ </div>
+
+
+ computed: {
+ boxStyle() {
+ if (this.windowIsLarge) {
+ return { display: 'inline-block' };
+ }
+ return { display: 'block' };
+ },
+ },
+
+
+
+ This results in two boxes that stack vertically on small screens and otherwise display side-by-side:
+
+
+ Breakpoint level: {{ windowBreakpoint }}
+ Window is large: {{ windowIsLarge }}
+
+
+ Box 1
+
+
+ Box 2
+
+
+ Try adjusting your browser window size to see the example in action.
+
+
+
+
+
+ -
+ has an overview of breakpoints
+
+ -
+ See if you need a component's size reactive information rather than that of the window
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/pages/layout/index.vue b/docs/pages/layout/index.vue
index a417946dc..12211f1d0 100644
--- a/docs/pages/layout/index.vue
+++ b/docs/pages/layout/index.vue
@@ -69,63 +69,8 @@
Level 7: >= 1600px
- Responsive layouts in the design system are built using reactive javascript state in Vue components rather than CSS media queries. This is done using the KResponsiveWindowMixin Vue mixin. Once added to a component it provides the following reactive window state information:
+ Responsive layouts in the design system are built using reactive JavaScript state in Vue components rather than CSS media queries. This is done using when reactive window's size information is needed or when reactive component's size information is needed.
-
- windowIsSmall: booleanwindowIsMedium: booleanwindowIsLarge: booleanwindowHeight: integer height in pixelswindowWidth: integer width in pixelswindowBreakpoint: integer breakpoint level
-
- These reactive properties are 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.
-
-
- For example, consider a Vue file with this in its template and script:
-
-
-
-
- <div class="box" :style="boxStyle">
- Box 1
- </div>
- <div class="box" :style="boxStyle">
- Box 2
- </div>
-
-
- computed: {
- boxStyle() {
- if (this.windowIsLarge) {
- return { display: 'block' };
- }
- return { display: 'inline-block' };
- },
- },
-
-
-
- This results in two boxes that stack vertically on small screens and otherwise display side-by-side:
-
-
- Breakpoint level: {{ windowBreakpoint }}
- Window is large: {{ windowIsLarge }}
-
-
- Box 1
-
-
- Box 2
-
-
- Try adjusting your browser window size to see the example in action.
-
-
-
@@ -265,30 +210,3 @@
-
-
-
-
-
diff --git a/docs/tableOfContents.js b/docs/tableOfContents.js
index b7e3b0329..2ba982972 100644
--- a/docs/tableOfContents.js
+++ b/docs/tableOfContents.js
@@ -58,6 +58,7 @@ class Page {
const buttonRelatedKeywords = ['button', 'link'];
const textRelatedKeywords = ['text', 'area', 'field', 'box'];
const layoutRelatedKeywords = ['grid', 'layout', 'container', 'page'];
+const responsiveComponentsRelatedKeywords = ['responsive', 'mixin', 'breakpoint'];
export default [
new Section({
@@ -301,6 +302,18 @@ export default [
title: 'KBreadcrumbs',
isCode: true,
}),
+ new Page({
+ path: '/kresponsivewindow',
+ title: 'KResponsiveWindow',
+ isCode: true,
+ keywords: [...responsiveComponentsRelatedKeywords, 'window'],
+ }),
+ new Page({
+ path: '/kresponsiveelement',
+ title: 'KResponsiveElement',
+ isCode: true,
+ keywords: [...responsiveComponentsRelatedKeywords, 'element'],
+ }),
],
}),
];