Docs: Add canonical async examples

Author: jlukic

docs/src/content/examples/utils-debounce-async.mdx

@@ -0,0 +1,11 @@
+---
+title: 'debounce (async)'
+id: 'utils-debounce-async'
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'Functions'
+description: 'Debounce asynchronous functions with promise sharing'
+tags: ['utils', 'functions', 'debounce', 'async', 'promise']
+selectedFile: 'index.js'
+tip: 'Multiple calls to a debounced async function share the same promise until it settles'
+---

docs/src/content/examples/utils-throttle-async.mdx

@@ -0,0 +1,11 @@
+---
+title: 'throttle (async)'
+id: 'utils-throttle-async'
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'Functions'
+description: 'Throttle asynchronous functions with proper promise handling'
+tags: ['utils', 'functions', 'throttle', 'async', 'promise']
+selectedFile: 'index.js'
+tip: 'Throttled async functions maintain leading/trailing behavior while handling promises correctly'
+---

docs/src/examples/utils/functions/utils-debounce-async/index.js

@@ -0,0 +1,25 @@
+import { debounce } from '@semantic-ui/utils';
+
+async function saveData(data) {
+  await new Promise(resolve => setTimeout(resolve, 50));
+  console.log(`Saved: ${data}`);
+  return `result: ${data}`;
+}
+
+// async debouncing with promise sharing
+const debouncedSave = debounce(saveData, 200);
+
+// all calls share the same promise
+Promise.all([
+  debouncedSave('data1'),
+  debouncedSave('data2'),
+  debouncedSave('data3'), // only this executes
+]).then(results => {
+  console.log('All results:', results); // all get same result
+});
+
+// subsequent calls after settlement
+setTimeout(async () => {
+  const result = await debouncedSave('data4');
+  console.log('New result:', result);
+}, 400);

docs/src/examples/utils/functions/utils-debounce/index.js

@@ -1,49 +1,30 @@
 import { debounce } from '@semantic-ui/utils';
 
-// Sync function example
-function logMessage(message) {
-  console.log(`Sync: ${message} at ${Date.now()}`);
-  return `logged: ${message}`;
+function search(query) {
+  console.log(`Searching: ${query}`);
+  return query;
 }
 
-// Async function example
-async function saveData(data) {
-  await new Promise(resolve => setTimeout(resolve, 50));
-  console.log(`Async: saved ${data}`);
-  return `saved: ${data}`;
-}
-
-// Basic debouncing - only last call executes
-console.log('Basic debouncing:');
-const debouncedLog = debounce(logMessage, 100);
-debouncedLog('call 1');
-debouncedLog('call 2'); 
-debouncedLog('call 3'); // Only this executes
-
-// Async debouncing with promise sharing
-console.log('\nAsync debouncing (promise sharing):');
-const debouncedSave = debounce(saveData, 100);
-Promise.all([
-  debouncedSave('data1'),
-  debouncedSave('data2'),  
-  debouncedSave('data3') // Only this executes, all promises resolve to same result
-]).then(results => {
-  console.log('All results:', results); // All get 'saved: data3'
-});
+// basic debouncing - only last call executes
+const debouncedSearch = debounce(search, 200);
+debouncedSearch('a');
+debouncedSearch('ab');
+debouncedSearch('abc'); // only this executes
 
-// Leading execution
+// leading edge - executes on both leading and trailing edges
 setTimeout(() => {
-  console.log('\nLeading execution:');
-  const leadingDebounce = debounce(logMessage, 200, { leading: true });
-  console.log('Immediate result:', leadingDebounce('immediate')); // Executes right away
-  leadingDebounce('ignored'); // Debounced
+  const leadingDebounce = debounce(search, 200, { leading: true });
+  leadingDebounce('first'); // executes immediately (leading)
+  leadingDebounce('second'); // executes after 200ms (trailing)
 }, 300);
 
-// MaxWait option
+// maxWait - forces execution after maximum time
 setTimeout(() => {
-  console.log('\nMaxWait forces execution:');
-  const maxWaitDebounce = debounce(logMessage, 50, { maxWait: 120 });
-  maxWaitDebounce('call1');
-  setTimeout(() => maxWaitDebounce('call2'), 30);
-  setTimeout(() => maxWaitDebounce('call3'), 60); // Forces execution at 120ms
-}, 600);
+  const maxWaitDebounce = debounce(search, 300, { maxWait: 500 });
+  maxWaitDebounce('input1');
+  setTimeout(() => maxWaitDebounce('input2'), 100);
+  setTimeout(() => maxWaitDebounce('input3'), 200);
+  setTimeout(() => maxWaitDebounce('input4'), 400); // forces execution at 500ms
+  // input5 triggers a new debounce cycle after maxWait
+  setTimeout(() => maxWaitDebounce('input5'), 600); // executes 300ms later
+}, 600);

docs/src/examples/utils/functions/utils-throttle-async/index.js

@@ -0,0 +1,29 @@
+import { throttle } from '@semantic-ui/utils';
+
+async function fetchData(endpoint) {
+  await new Promise(resolve => setTimeout(resolve, 50));
+  console.log(`Fetched: ${endpoint}`);
+  return `data from ${endpoint}`;
+}
+
+// async throttling with promise handling
+const throttledFetch = throttle(fetchData, 200);
+
+// first call executes immediately
+throttledFetch('/users').then(result => {
+  console.log('First result:', result);
+});
+
+// subsequent calls queue for trailing execution
+throttledFetch('/posts');
+throttledFetch('/comments'); // this replaces /posts
+
+// rapid async calls
+setTimeout(() => {
+  const rapidThrottle = throttle(fetchData, 150);
+  for (let i = 1; i <= 4; i++) {
+    rapidThrottle(`/api/v${i}`).then(result => {
+      console.log(`API result: ${result}`);
+    });
+  }
+}, 400);

docs/src/examples/utils/functions/utils-throttle/index.js

@@ -1,55 +1,36 @@
 import { throttle } from '@semantic-ui/utils';
 
-// Sync function example  
-function logEvent(event) {
-  console.log(`Sync: ${event} at ${Date.now()}`);
-  return `logged: ${event}`;
+function trackEvent(event) {
+  console.log(`Event: ${event}`);
+  return event;
 }
 
-// Async function example
-async function apiCall(endpoint) {
-  await new Promise(resolve => setTimeout(resolve, 50));
-  console.log(`Async: called ${endpoint}`);
-  return `response from ${endpoint}`;
-}
-
-// Basic throttling - leading and trailing (default)
-console.log('Basic throttling (leading + trailing):');
-const throttledLog = throttle(logEvent, 200);
-console.log('First result:', throttledLog('event1')); // Executes immediately
-throttledLog('event2'); // Queued for trailing
-throttledLog('event3'); // Replaces event2
-
-// Async throttling
-console.log('\nAsync throttling:');
-const throttledAPI = throttle(apiCall, 150);
-throttledAPI('/users').then(result => console.log('API result:', result));
-throttledAPI('/posts'); // Queued for trailing execution
+// basic throttling - leading and trailing (default)
+const throttled = throttle(trackEvent, 200);
+throttled('click1'); // executes immediately
+throttled('click2'); // queued for trailing
+throttled('click3'); // replaces click2
 
-// Leading only - execute immediately, ignore subsequent
+// leading only
 setTimeout(() => {
-  console.log('\nLeading only:');
-  const leadingOnly = throttle(logEvent, 300, { leading: true, trailing: false });
-  console.log('Immediate result:', leadingOnly('click1')); // Executes immediately
-  leadingOnly('click2'); // Ignored
-  leadingOnly('click3'); // Ignored
+  const leadingOnly = throttle(trackEvent, 200, { leading: true, trailing: false });
+  leadingOnly('scroll1'); // executes immediately
+  leadingOnly('scroll2'); // ignored
+  leadingOnly('scroll3'); // ignored
 }, 400);
 
-// Trailing only - execute once after throttle period  
+// trailing only
 setTimeout(() => {
-  console.log('\nTrailing only:');
-  const trailingOnly = throttle(logEvent, 200, { leading: false, trailing: true });
-  trailingOnly('scroll1'); // Queued
-  trailingOnly('scroll2'); // Replaces scroll1
-  trailingOnly('scroll3'); // This executes after 200ms
-}, 800);
+  const trailingOnly = throttle(trackEvent, 200, { leading: false, trailing: true });
+  trailingOnly('move1'); // queued
+  trailingOnly('move2'); // replaces move1
+  trailingOnly('move3'); // executes after 200ms
+}, 700);
 
-// High frequency events simulation
+// high frequency events
 setTimeout(() => {
-  console.log('\nHigh frequency events:');
-  const throttledScroll = throttle(logEvent, 100);
-  for (let i = 1; i <= 8; i++) {
-    setTimeout(() => throttledScroll(`scroll${i}`), i * 20);
+  const throttledInput = throttle(trackEvent, 100);
+  for (let i = 1; i <= 5; i++) {
+    setTimeout(() => throttledInput(`input${i}`), i * 30);
   }
-  // Only first and last will execute due to throttling
-}, 1200);
+}, 1000);