Skip to content

Commit

Permalink
Merge pull request #362 from MisRob/document-mixins
Browse files Browse the repository at this point in the history 
Add documentation pages for KResponsiveWindow and KResponsiveElement
  • Loading branch information
@MisRob
MisRob authored Sep 21, 2022
2 parents 7324ffa + c5442e4 commit ecfa5e9
Show file tree
Hide file tree
Showing 6 changed files with 222 additions and 83 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'

<!-- Referenced PRs -->
[#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
Expand Down
8 changes: 8 additions & 0 deletions docs/assets/main.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,11 @@ html {
*::after {
box-sizing: inherit;
}

dt {
margin-top: 16px;
}

dd {
margin-left: 20px;
}
62 changes: 62 additions & 0 deletions docs/pages/kresponsiveelement.vue
View file
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>
132 changes: 132 additions & 0 deletions docs/pages/kresponsivewindow.vue
View file
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">
&lt;div class="box" :style="boxStyle"&gt;
Box 1
&lt;/div&gt;
&lt;div class="box" :style="boxStyle"&gt;
Box 2
&lt;/div&gt;
</DocsShowCode>
<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>
84 changes: 1 addition & 83 deletions docs/pages/layout/index.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,63 +69,8 @@
<li>Level 7: <code>&gt;= 1600px</code></li>
</ul>
<p>
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 <code>KResponsiveWindowMixin</code> 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 <DocsLibraryLink component="KResponsiveWindow" /> when reactive window's size information is needed or <DocsLibraryLink component="KResponsiveElement" /> when reactive component's size information is needed.
</p>
<ul>
<li><code>windowIsSmall</code>: boolean</li>
<li><code>windowIsMedium</code>: boolean</li>
<li><code>windowIsLarge</code>: boolean</li>
<li><code>windowHeight</code>: integer height in pixels</li>
<li><code>windowWidth</code>: integer width in pixels</li>
<li><code>windowBreakpoint</code>: integer breakpoint level</li>
</ul>
<p>
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.
</p>
<p>
For example, consider a Vue file with this in its template and script:
</p>
<!-- eslint-disable -->
<!-- prevent prettier from changing indentation -->
<DocsShowCode language="html">
&lt;div class="box" :style="boxStyle"&gt;
Box 1
&lt;/div&gt;
&lt;div class="box" :style="boxStyle"&gt;
Box 2
&lt;/div&gt;
</DocsShowCode>
<DocsShowCode language="javascript">
computed: {
boxStyle() {
if (this.windowIsLarge) {
return { display: 'block' };
}
return { display: 'inline-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="Grid system" anchor="#grid-system">
Expand Down Expand Up @@ -265,30 +210,3 @@

</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>
13 changes: 13 additions & 0 deletions docs/tableOfContents.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down Expand Up @@ -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'],
}),
],
}),
];

0 comments on commit ecfa5e9

Please sign in to comment.