UI-274 Reimplement the UI state

CHANGELOG.md

@@ -23,10 +23,9 @@ Thousand thanks to the Svelte's team, for the [long months of hard work](https:/
   and second argument (`data`) is specific to the event & component, e.g.
     - for Inputs `onchange` event, `data` argument will contain the new value (`{ value: any }`)
 - Event listeners added to components' events will receive the relevant data as the second argument of the callback. There is no `event.detail` anymore.
-- Utils functions & constants have been updated to use the new reactive `$state`:
+- Utils functions & constants have been updated to use a new reactive state object `UI`, which is now exported from `src/utils`:
   - `$ANIMATION_SPEED`   -> `UI.ANIMATION_SPEED` - (number) reactive constant
   - `$PREFERS_DARK`      -> `UI.PREFERS_DARK` - (boolean) reactive constant
-  - `FOCUSABLE_SELECTOR` -> `UI.FOCUSABLE_SELECTOR` - (string) constant
   - `isMobile()`         -> `UI.isMobile` - (boolean) constant
 - As per Svelte's best practices, attributes bound to variables will not use quotes anymore, so: `value="{value}"` -> `value={value}` or even better: `{value}`.
 - Attributes are typed now, and are a bit more restrictive, so e.g. a `boolean` or a `number` attribute will not accept a string value.

docs-src/components/utils/Utils.css

@@ -1,10 +1,11 @@
 .section-utils {
 	--nav-sidebar-width: 240px;
 }
-.section-utils .dark-mode-switch { right: calc(var(--nav-sidebar-width) + 20px); }
 
 .section-utils .sticky-block { padding-bottom: 3rem; margin-right: var(--nav-sidebar-width); }
 
+.section-utils .docs-theme-switcher { right: calc(var(--nav-sidebar-width) + 0.6rem); }
+
 
 .section-utils .sticky-block .utility h3 {
 	scroll-margin-top: 4.2rem;
@@ -39,7 +40,7 @@
 
 
 @media (1px <= width <= 900px) {
-	.section-utils .dark-mode-switch { right: 0.6rem; }
+	.section-utils .docs-theme-switcher { right: 0.6rem; }
 	.section-utils .btn-scroll-top { right: 1rem; }
 	.section-utils .sticky-block { margin-right: 0; }
 	.section-utils .utilities-nav {
@@ -50,5 +51,4 @@
 		margin-top: 2rem;
 		background-color: unset;
 	}
-
 }

docs-src/components/utils/properties/focusable-selector.svelte

@@ -1,4 +1,4 @@
-<Util id="FocusableSelector" name="UI.FOCUSABLE_SELECTOR" {example}>
+<Util id="FocusableSelector" name="FOCUSABLE_SELECTOR" {example}>
 	<ul>
 		<li>Type: string</li>
 		<li>Returns a list of selectors that can be focused.</li>
@@ -10,9 +10,9 @@ import Util from '../Util.svelte';
 
 const example = `
 <script&gt;
-    import { UI } from '@perfectthings/ui';
+    import { FOCUSABLE_SELECTOR } from '@perfectthings/ui';
 
-    const focusableElements = document.querySelectorAll(UI.FOCUSABLE_SELECTOR);
+    const focusableElements = document.querySelectorAll(FOCUSABLE_SELECTOR);
     console.log(focusableElements);
 </script&gt;
 `;

docs-src/components/utils/properties/index.js

@@ -1,3 +1,2 @@
-export { default as AnimationSpeed } from './animation-speed.svelte';
 export { default as FocusableSelector } from './focusable-selector.svelte';
-export { default as PrefersDark } from './prefers-dark.svelte';
+export { default as UI } from './ui.svelte';

docs-src/components/utils/properties/ui.svelte

@@ -0,0 +1,56 @@
+<Util id="UI" name="UI" {example}>
+	<p>A framework helper module. Provides a bunch of useful functions and properties, like:</p>
+	<ul>
+		<li><em>UI.ANIMATION_SPEED</em> - default animation duration in ms. If the user prefers reduced-motion - this will be <em>0</em>.</li>
+		<li><em>UI.IS_MOBILE</em> - returns true if the user is on a mobile device.</li>
+		<li><em>UI.PREFERS_DARK</em> - returns true if the user prefers dark mode.</li>
+		<li><em>UI.VERSION</em> - the current version of the framework.</li>
+		<li><em>UI.init()</em> - initializes the UI module and sets up some event listeners.</li>
+		<li><em>UI.destroy()</em> - cleans up the UI module and removes the event listeners.</li>
+		<li><em>UI.on(eventName: string, callback: Function)</em> - adds an event listener for the specified event.</li>
+		<li><em>UI.off(eventName: string, callback: Function)</em> - removes the event listener for the specified event.</li>
+	</ul>
+	<h3>Events:</h3>
+	<ul>
+		<li><em>change</em> - fired when a property value changes (for <em>ANIMATION_SPEED</em> and <em>PREFERS_DARK</em>, as others don't change at runtime).</li>
+	</ul>
+	<h3>UI.init()</h3>
+	<p>Initializes the UI module:</p>
+	<ul>
+		<li>It sets the <em>ANIMATION_SPEED</em> and <em>PREFERS_DARK</em> properties based on the user's preferences.</li>
+		<li>It adds either <em>mobile</em> or <em>desktop</em> class to the html element based on the user's device.</li>
+		<li>It adds event listeners for keyboard and mouse, and toggles the <em>ui-keyboard</em> class on the html element based on the user's interactions.
+			This is useful for providing better accessibility and user experience, e.g. show additional controls or visual focus for keyboard users.</li>
+	</ul>
+</Util>
+
+<script>
+import Util from '../Util.svelte';
+const example = `
+<script&gt;
+    import { UI } from '@perfectthings/ui';
+
+    UI.init();
+    UI.on('change', (property, value) => {
+        console.log(\`UI.$\{property} changed to $\{value}\`);
+    });
+    console.log(UI.ANIMATION_SPEED + 'ms');
+    console.log(UI.IS_MOBILE ? 'mobile' : 'desktop');
+    console.log(UI.PREFERS_DARK ? 'dark mode' : 'light mode');
+    console.log('Framework version', UI.VERSION);
+</script&gt;
+`;
+
+
+
+import { UI } from '../../../../src/utils';
+
+UI.init();
+UI.on('change', (property, value) => {
+	console.log(`UI.${property} changed to ${value}`);
+});
+console.log(UI.ANIMATION_SPEED + 'ms');
+console.log(UI.IS_MOBILE ? 'mobile' : 'desktop');
+console.log(UI.PREFERS_DARK ? 'dark mode' : 'light mode');
+console.log('Framework version', UI.VERSION);
+</script>

docs-src/pages/changelog.html

@@ -20,10 +20,9 @@ <h3>Breaking changes</h3>
 </ul>
 </li>
 <li>Event listeners added to components&#39; events will receive the relevant data as the second argument of the callback. There is no <code>event.detail</code> anymore.</li>
-<li>Utils functions &amp; constants have been updated to use the new reactive <code>$state</code>:<ul>
+<li>Utils functions &amp; constants have been updated to use a new reactive state object <code>UI</code>, which is now exported from <code>src/utils</code>:<ul>
 <li><code>$ANIMATION_SPEED</code>   -&gt; <code>UI.ANIMATION_SPEED</code> - (number) reactive constant</li>
 <li><code>$PREFERS_DARK</code>      -&gt; <code>UI.PREFERS_DARK</code> - (boolean) reactive constant</li>
-<li><code>FOCUSABLE_SELECTOR</code> -&gt; <code>UI.FOCUSABLE_SELECTOR</code> - (string) constant</li>
 <li><code>isMobile()</code>         -&gt; <code>UI.isMobile</code> - (boolean) constant</li>
 </ul>
 </li>

src/dialog/Dialog.svelte

@@ -39,7 +39,7 @@ A modal dialog component with accessibility features and focus management.
 import './Dialog.css';
 import type { DialogProps } from './types';
 import { onMount } from 'svelte';
-import { UI } from '../utils';
+import { FOCUSABLE_SELECTOR, UI } from '../utils';
 
 
 let {
@@ -100,8 +100,8 @@ function focusLast () {
 
 function getFocusableElements () {
 	if (!dialogEl || !contentEl || !footerEl) return [];
-	const contentElements = Array.from(contentEl.querySelectorAll(UI.FOCUSABLE_SELECTOR));
-	const footerElements = Array.from(footerEl.querySelectorAll(UI.FOCUSABLE_SELECTOR));
+	const contentElements = Array.from(contentEl.querySelectorAll(FOCUSABLE_SELECTOR));
+	const footerElements = Array.from(footerEl.querySelectorAll(FOCUSABLE_SELECTOR));
 	return [...contentElements, ...footerElements];
 }
 

src/drawer/Drawer.svelte

@@ -41,7 +41,7 @@ A sliding panel component that appears from the side of the screen.
 import './Drawer.css';
 import type { DrawerProps } from './types';
 import { fly } from 'svelte/transition';
-import { UI } from '../utils';
+import { FOCUSABLE_SELECTOR, UI } from '../utils';
 import { Button } from '../button';
 
 
@@ -120,7 +120,7 @@ function focusLast () {
 
 
 function getFocusableElements () {
-	return Array.from(element.querySelectorAll(UI.FOCUSABLE_SELECTOR));
+	return Array.from(element.querySelectorAll(FOCUSABLE_SELECTOR));
 }
 
 

src/index.ts

@@ -1,10 +1,3 @@
-import { initUI } from './utils';
-import './root.css';
-import './theme-dark.css';
-import './theme-light.css';
-
-initUI();
-
 export * from './button';
 export * from './button-group';
 export * from './dialog';
@@ -28,3 +21,10 @@ export * from './tooltip';
 export * from './tree';
 export * from './utils';
 export * from './types';
+
+import { UI } from './utils';
+import './root.css';
+import './theme-dark.css';
+import './theme-light.css';
+
+UI.init();

src/input/combobox/Combobox.svelte

@@ -307,7 +307,7 @@ function clear () {
 
 
 function selectInputText () {
-	if (inputElement && !UI.isMobile) {
+	if (inputElement && !UI.IS_MOBILE) {
 		requestAnimationFrame(() => inputElement.select());
 	}
 }
@@ -336,7 +336,7 @@ function oninput () {
 
 
 function onItemClick (e: Event, item) {
-	if (UI.isMobile) {
+	if (UI.IS_MOBILE) {
 		if (e?.type !== 'touchend') return;
 	}
 	else {

src/popover/Popover.svelte

@@ -41,7 +41,7 @@ import './Popover.css';
 import type { AlignmentDirection } from '../types';
 import type { PopoverProps } from './types';
 import { addArias, removeArias } from './utils';
-import { alignItem, UI } from '../utils';
+import { alignItem, FOCUSABLE_SELECTOR } from '../utils';
 import { throttle } from 'es-toolkit';
 
 let {
@@ -165,7 +165,7 @@ function focusLast () {
 
 function getFocusableElements () {
 	if (!contentEl) return [];
-	return Array.from(contentEl.querySelectorAll(UI.FOCUSABLE_SELECTOR));
+	return Array.from(contentEl.querySelectorAll(FOCUSABLE_SELECTOR));
 }
 
 

src/utils/animations.ts

@@ -1,4 +1,4 @@
-import { UI } from './ui.svelte';
+import { UI } from './ui';
 
 
 /**

src/utils/dom.ts

@@ -33,20 +33,3 @@ export function getMouseY (e: any): number {
 export function getMouseXY (e: any): [number, number] {
 	return [getMouseX(e), getMouseY(e)];
 }
-
-
-
-export function initKeyboardTracking (cls: string) {
-	const keys = ['Escape', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', ' ', 'Enter'];
-
-	const setKeyboardMode = () => document.documentElement.classList.add(cls);
-	const unsetKeyboardMode = () => document.documentElement.classList.remove(cls);
-	const isKey = (key) => keys.includes(key);
-
-	const onkeydown = (e) => { if (isKey(e.key)) setKeyboardMode(); };
-
-	window.addEventListener('keydown', onkeydown, { passive: true, capture: true });
-	window.addEventListener('mousedown', unsetKeyboardMode, { passive: true, capture: true });
-	window.addEventListener('pointerdown', unsetKeyboardMode, { passive: true, capture: true });
-	window.addEventListener('touchstart', unsetKeyboardMode, { passive: true, capture: true });
-}

src/utils/index.ts

@@ -3,5 +3,5 @@ export * from './animations';
 export * from './constants';
 export * from './date';
 export * from './dom';
-export * from './ui.svelte';
+export * from './ui';
 export * from './utilities';