add remaining functions

docs-src/api-table/ApiTable.svelte

@@ -36,8 +36,8 @@ function buildType (prop) {
 	if (!prop.type) prop.type = '-';
 	const types = (Array.isArray(prop.type) ? prop.type : [prop.type]).map(t => `<i>${t}</i>`);
 	res.push(types.join(' | '));
-	if (prop.required) res.push('<em>required</em>');
-	if (prop.default) res.push(`<br>(defaults to ${prop.default})`);
+	if (typeof prop.required !== 'undefined') res.push('<em>required</em>');
+	if (typeof prop.default !== 'undefined') res.push(`<br>(defaults to ${prop.default})`);
 	return res.join(' ');
 }
 </script>

docs-src/components/utils/Utils.css

@@ -1,3 +1,7 @@
+.utilities {
+	padding-bottom: 3rem;
+}
+
 .utilities h3.util {
 	font-size: 1.1rem;
 	color: var(--ui-color-accent);

docs-src/components/utils/Utils.svelte

@@ -2,16 +2,14 @@
 	<h2>Utility properties</h2>
 
 	<FocusableSelector/><hr>
-	<PrefersDark/><hr>
+	<PrefersDark/>
 </div>
 
 <div class="sticky-block utilities">
 	<h2>Utility Functions</h2>
 
 	<Animate/><hr>
 	<Blink/><hr>
-
-<!--
 	<DeepCopy/><hr>
 	<Debounce/><hr>
 	<Throttle/><hr>
@@ -27,12 +25,9 @@
 	<FormatDate/><hr>
 	<TimeAgo/><hr>
 	<AlignItem/><hr>
-	<IsInScrollable/><hr>
--->
-
-
+	<IsInScrollable/>
 </div>
-
+docs-src/components/utils/fn-guid.svelte
 
 <p>
 	<em>*</em> <a href="https://svelte.dev/docs/svelte-components#script-4-prefix-stores-with-$-to-access-their-values">
@@ -46,4 +41,20 @@ import FocusableSelector from './prop-focusable-selector.svelte';
 import PrefersDark from './prop-prefers-dark.svelte';
 import Animate from './fn-animate.svelte';
 import Blink from './fn-blink.svelte';
+import DeepCopy from './fn-deep-copy.svelte';
+import Debounce from './fn-debounce.svelte';
+import Throttle from './fn-throttle.svelte';
+import Empty from './fn-empty.svelte';
+import Fuzzy from './fn-fuzzy.svelte';
+import Guid from './fn-guid.svelte';
+import GetMouseX from './fn-get-mouse-x.svelte';
+import GetMouseY from './fn-get-mouse-y.svelte';
+import GetMouseXY from './fn-get-mouse-xy.svelte';
+import IsMobile from './fn-is-mobile.svelte';
+import Pluck from './fn-pluck.svelte';
+import RoundAmount from './fn-round-amount.svelte';
+import FormatDate from './fn-format-date.svelte';
+import TimeAgo from './fn-time-ago.svelte';
+import AlignItem from './fn-align-item.svelte';
+import IsInScrollable from './fn-is-in-scrollable.svelte';
 </script>

docs-src/components/utils/fn-align-item.svelte

@@ -0,0 +1,48 @@
+<h3 class="util">alignItem (config)</h3>
+<p>Aligns an element to another element,
+	ensuring that the aligned element remains within the viewport.
+</p>
+<ul>
+	<li><em>config</em> - an object with the configuration (see below).
+	<li>Returns <em>position</em> - whether the aligned item is above (top) or below (bottom) the target.
+</ul>
+
+<API props="{apiProps}" title="Config object schema"/>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { API } from '../../api-table';
+import { CodeExample } from '../../code-example';
+
+
+const apiProps = [
+	{ name: 'element', type: 'HTMLElement', description: 'main element that will be aligned.' },
+	{ name: 'target', type: 'HTMLElement', description: 'target element to align to.' },
+	{ name: 'alignH', type: ['left', 'right', 'center'], default: 'left', description: 'Horizontal position' },
+	{ name: 'offsetH', type: 'number', default: 0, description: 'horizontal offset of the aligned position (in pixels).' },
+	{ name: 'alignV', type: ['top', 'bottom'], default: 'bottom', description: 'Vertical position' },
+	{ name: 'offsetV', type: 'number', default: 2, description: 'vertical offset of the aligned position (in pixels).' },
+	{ name: 'viewportPadding', type: 'number', default: 10, description: 'padding from the viewport (in pixels).' },
+	{ name: 'setMinWidthToTarget', type: 'boolean', default: false, description: 'whether to set the minWidth of the element to the width of the target.' },
+];
+
+
+const example = `
+<script>
+	const button = document.querySelector('.button1');
+	const popup = document.querySelector('.popup1');
+	const pos = alignItem({
+		element: popup,
+		target: button,
+		alignH: 'left',
+		alignV: 'bottom',
+	});
+	// it may happen that there is not enough space to align the popup as requested
+	// in this case, the popup will be aligned to the opposite side
+	console.log('position:', pos); // 'top'
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-animate.svelte

@@ -2,19 +2,26 @@
 
 <p>Animates an element from one state to another. Shortcut & wrapper for the native javascript animation.</p>
 
-<ul>
-	<li><em>element</em> - HTMLElement to animate
-	<li><em>from</em> - object of properties to animate from, e.g. <em>&lbrace; opacity: 0 &rbrace;</em>
-	<li><em>to</em> - object of properties to animate to, e.g. <em>&lbrace; opacity: 1 &rbrace;</em>
-	<li><em>options</em> - optional object of animation options: duration, easing, fill (see more at <a href="https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#options">MDN</a>).
-	<li>Returns a promise which resolves when the animation finishes.
-</ul>
+<API props="{apiProps}" title="Parameters"/>
+<p>Returns a promise which resolves when the animation finishes.</p>
+
+
 <CodeExample nohr html="{example}" />
 
 
 <script>
+import { API } from '../../api-table';
 import { CodeExample } from '../../code-example';
 
+const apiProps = [
+	{ name: 'element', type: 'HTMLElement', description: 'An element that will be animated.' },
+	{ name: 'from', type: 'object', description: 'object of properties to animate from, e.g. <em>&lbrace; opacity: 0 &rbrace;</em>' },
+	{ name: 'to', type: 'object', description: 'object of properties to animate to, e.g. <em>&lbrace; opacity: 1 &rbrace;</em>' },
+	{ name: 'options', type: 'object', description: 'optional object of animation options: duration, easing, fill (see more at <a href="https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#options">MDN</a>).' },
+];
+
+
+
 const example = `
 <script>
 	const el = document.querySelector('.some-div');

docs-src/components/utils/fn-debounce.svelte

@@ -0,0 +1,31 @@
+<h3 class="util">debounce(fn, timeout = 300)</h3>
+<p>The "debounced" function will only be called after it has not been called for <em>timeout</em> milliseconds.</p>
+<ul>
+	<li><em>fn</em> - function to debounce.
+	<li><em>timeout</em> - milliseconds to wait before calling <em>fn</em>.
+</ul>
+
+<p>
+	This is a useful e.g. when attaching an event listener to an event that is fired repeatedly & quickly (like scroll or resize).<br>
+	Attaching a heavy function to such an event can cause performance issues, so debouncing it will ensure
+	that the function is only called after it has not been called for <em>timeout</em> milliseconds.
+</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	function original() {
+		console.log('resizing has stopped for 300ms');
+	}
+	const debounced = debounce(original);
+	window.addEventListener('resize', debounced);
+&lt;/script>
+`;
+
+
+</script>

docs-src/components/utils/fn-deep-copy.svelte

@@ -0,0 +1,20 @@
+<h3 class="util">deepCopy(object)</h3>
+<p>This is just an alias for an oddly-named native function: <b>structuredClone</b>.</p>
+<ul>
+	<li><em>object</em> - any object or array to clone.
+</ul>
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	const original = {a: 1, b: 2, c: 3};
+	const clone = deepCopy(original);
+&lt;/script>
+`;
+
+
+</script>

docs-src/components/utils/fn-empty.svelte

@@ -0,0 +1,39 @@
+<h3 class="util">empty(value)</h3>
+<p>Similar to PHP's <em>empty</em> - returns true if a value is empty.</p>
+<ul>
+	<li><em>value</em> - any data type.
+</ul>
+
+<p>Empty will return true if the <em>value</em> is one of the following:</p>
+<ul>
+	<li><em>undefined</em>
+	<li><em>null</em>
+	<li><em>empty string</em>
+	<li><em>empty array</em>
+	<li><em>empty object</em>
+</ul>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	empty();        // true
+	empty(null);    // true
+	empty('');      // true
+	empty([]);      // true
+	empty({});      // true
+
+	empty(0);       // false
+	empty(false);   // false
+	empty('0');     // false
+	empty([0]);     // false
+	empty({a: 0});  // false
+&lt;/script>
+`;
+
+
+</script>

docs-src/components/utils/fn-format-date.svelte

@@ -0,0 +1,16 @@
+<h3 class="util">formatDate (date)</h3>
+<p>Converts date to a string in the format: <em>YYYY-MM-DD HH:mm</em>.</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	formatDate(new Date()); // 2020-01-01 12:00
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-fuzzy.svelte

@@ -0,0 +1,26 @@
+<h3 class="util">fuzzy (haystack = '', needle = '')</h3>
+<p>Fuzzy finds if <em>haystack</em> contains characters from the <em>needle</em> in the same order.</p>
+<ul>
+	<li><em>haystack</em> - a string to be searched in.
+	<li><em>needle</em> - a string to search for.
+</ul>
+
+<p>It's useful for filtering lists of items by a search string.</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	fuzzy('hello world', 'hell');    // true
+	fuzzy('hello world', 'helloo');  // true
+	fuzzy('hello world', 'helll');   // true
+	fuzzy('hello world', 'hellooo'); // false
+&lt;/script>
+`;
+
+
+</script>

docs-src/components/utils/fn-get-mouse-x.svelte.svelte

@@ -0,0 +1,19 @@
+<h3 class="util">getMouseX (event)</h3>
+<p>Returns the mouse X position. Event is standardised across platforms (touch & pointer)</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	document.addEventListener('mousedown', e => {
+		const x = getMouseX(e);
+		console.log(x);
+	});
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-get-mouse-xy.svelte.svelte

@@ -0,0 +1,19 @@
+<h3 class="util">getMouseY (event)</h3>
+<p>Returns the mouse XY position. Event is standardised across platforms (touch & pointer)</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	document.addEventListener('mousedown', e => {
+		const [x, y] = getMouseXY(e);
+		console.log(x, y);
+	});
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-get-mouse-y.svelte.svelte

@@ -0,0 +1,19 @@
+<h3 class="util">getMouseY (event)</h3>
+<p>Returns the mouse Y position. Event is standardised across platforms (touch & pointer)</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	document.addEventListener('mousedown', e => {
+		const y = getMouseY(e);
+		console.log(y);
+	});
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-guid.svelte

@@ -0,0 +1,17 @@
+<h3 class="util">guid ()</h3>
+<p>Generates a globally unique identifier.</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	const id = guid();
+	console.log(id);	// 9748bb50-0e54-4f4d-b6a2-c0ea0d576cd4
+&lt;/script>
+`;
+
+</script>

docs-src/components/utils/fn-is-in-scrollable.svelte

@@ -0,0 +1,21 @@
+<h3 class="util">isInScrollable (node)</h3>
+<p>Checks whether the given node is inside a scrollable element.</p>
+<p>This function is useful when determining whether a swipe event should be allowed
+	to start on a given element.<br>
+	If an element is inside a scrollable element, the swipe event will not start,
+	allowing the browser to trigger the normal scrolling.
+</p>
+
+<CodeExample nohr html="{example}" />
+
+
+<script>
+import { CodeExample } from '../../code-example';
+
+const example = `
+<script>
+	const isInScrl = isInScrollable(document.querySelector('.element'));
+&lt;/script>
+`;
+
+</script>