@djangocfg/layouts 1.2.48 → 1.2.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "1.2.48",
+  "version": "1.2.50",
   "description": "Layout system and components for Unrealon applications",
   "author": {
     "name": "DjangoCFG",
@@ -63,9 +63,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.2.48",
-    "@djangocfg/og-image": "^1.2.48",
-    "@djangocfg/ui": "^1.2.48",
+    "@djangocfg/api": "^1.2.50",
+    "@djangocfg/og-image": "^1.2.50",
+    "@djangocfg/ui": "^1.2.50",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.468.0",
@@ -86,7 +86,7 @@
     "vidstack": "0.6.15"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.2.48",
+    "@djangocfg/typescript-config": "^1.2.50",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/layouts/AppLayout/components/PackageVersions/packageVersions.config.ts

@@ -16,36 +16,36 @@ export interface PackageInfo {
 /**
  * Package versions registry
  * Auto-synced from package.json files
- * Last updated: 2025-11-20T17:19:40.883Z
+ * Last updated: 2025-11-21T06:17:17.842Z
  */
 const PACKAGE_VERSIONS: PackageInfo[] = [
   {
     "name": "@djangocfg/ui",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/api",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/layouts",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/markdown",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/og-image",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/eslint-config",
-    "version": "1.2.48"
+    "version": "1.2.50"
   },
   {
     "name": "@djangocfg/typescript-config",
-    "version": "1.2.48"
+    "version": "1.2.50"
   }
 ];
 

package/src/layouts/UILayout/config/components/forms.config.tsx

@@ -2,7 +2,7 @@
  * Form Components Configuration
  */
 
-import React from 'react';
+import React, { useState, useEffect, useMemo } from 'react';
 import {
   Button,
   ButtonLink,
@@ -22,6 +22,8 @@ import {
   Slider,
   Combobox,
   MultiSelect,
+  MultiSelectPro,
+  MultiSelectProAsync,
   InputOTP,
   InputOTPGroup,
   InputOTPSlot,
@@ -34,6 +36,7 @@ import {
   FormLabel,
   FormMessage,
   Field,
+  useDebounce,
 } from '@djangocfg/ui';
 import { JsonSchemaForm } from '@djangocfg/ui/tools';
 import type { ComponentConfig } from './types';
@@ -391,6 +394,353 @@ export const FORM_COMPONENTS: ComponentConfig[] = [
       />
     ),
   },
+  {
+    name: 'MultiSelectPro',
+    category: 'forms',
+    description: 'Advanced multi-select with animations, custom styling, grouped options, and comprehensive accessibility. Supports variants, icons, gradients, responsive design, and imperative control via ref.',
+    importPath: "import { MultiSelectPro } from '@djangocfg/ui';",
+    example: `import { MultiSelectPro } from '@djangocfg/ui';
+import type { MultiSelectProOption } from '@djangocfg/ui';
+import { useState } from 'react';
+
+// Basic usage
+const [selected, setSelected] = useState<string[]>([]);
+
+<MultiSelectPro
+  options={[
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue.js" },
+    { value: "angular", label: "Angular" },
+  ]}
+  onValueChange={setSelected}
+  defaultValue={selected}
+  placeholder="Select frameworks..."
+/>
+
+// With custom styling and icons
+const styledOptions = [
+  {
+    value: "react",
+    label: "React",
+    style: {
+      badgeColor: "#61DAFB",
+      iconColor: "#282C34",
+    },
+  },
+  {
+    value: "vue",
+    label: "Vue.js",
+    style: {
+      gradient: "linear-gradient(135deg, #4FC08D 0%, #42B883 100%)",
+    },
+  },
+];
+
+<MultiSelectPro
+  options={styledOptions}
+  onValueChange={setSelected}
+  variant="secondary"
+  animationConfig={{
+    badgeAnimation: "bounce",
+    popoverAnimation: "scale",
+    duration: 0.3,
+  }}
+  maxCount={3}
+  closeOnSelect={false}
+/>
+
+// With grouped options
+const groupedOptions = [
+  {
+    heading: "Frontend Frameworks",
+    options: [
+      { value: "react", label: "React" },
+      { value: "vue", label: "Vue.js" },
+      { value: "angular", label: "Angular", disabled: true },
+    ],
+  },
+  {
+    heading: "Backend Technologies",
+    options: [
+      { value: "node", label: "Node.js" },
+      { value: "python", label: "Python" },
+    ],
+  },
+];
+
+<MultiSelectPro
+  options={groupedOptions}
+  onValueChange={setSelected}
+  placeholder="Select technologies..."
+  searchable={true}
+  responsive={true}
+  minWidth="200px"
+  maxWidth="500px"
+/>
+
+// With imperative control via ref
+import { useRef } from 'react';
+import type { MultiSelectProRef } from '@djangocfg/ui';
+
+const ref = useRef<MultiSelectProRef>(null);
+
+// Later in code:
+ref.current?.clear();
+ref.current?.reset();
+ref.current?.setSelectedValues(['react', 'vue']);
+const values = ref.current?.getSelectedValues();`,
+    preview: (
+      <div className="space-y-6">
+        <div className="space-y-2">
+          <p className="text-sm font-medium">Basic with animations:</p>
+          <MultiSelectPro
+            options={[
+              { value: "react", label: "React" },
+              { value: "vue", label: "Vue" },
+              { value: "angular", label: "Angular" },
+              { value: "svelte", label: "Svelte" },
+            ]}
+            defaultValue={[]}
+            onValueChange={() => {}}
+            placeholder="Select frameworks..."
+            animationConfig={{
+              badgeAnimation: "bounce",
+              popoverAnimation: "scale",
+              duration: 0.3,
+            }}
+            maxCount={2}
+            className="w-[350px]"
+          />
+        </div>
+
+        <div className="space-y-2">
+          <p className="text-sm font-medium">With variants and styles:</p>
+          <div className="grid grid-cols-2 gap-2">
+            <MultiSelectPro
+              options={[
+                { value: "1", label: "Option 1" },
+                { value: "2", label: "Option 2" },
+              ]}
+              defaultValue={["1"]}
+              onValueChange={() => {}}
+              variant="secondary"
+              placeholder="Secondary"
+              maxCount={1}
+            />
+            <MultiSelectPro
+              options={[
+                { value: "1", label: "Option 1" },
+                { value: "2", label: "Option 2" },
+              ]}
+              defaultValue={["2"]}
+              onValueChange={() => {}}
+              variant="destructive"
+              placeholder="Destructive"
+              maxCount={1}
+            />
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          <p className="text-sm font-medium">Grouped options:</p>
+          <MultiSelectPro
+            options={[
+              {
+                heading: "Frontend",
+                options: [
+                  { value: "react", label: "React" },
+                  { value: "vue", label: "Vue" },
+                ],
+              },
+              {
+                heading: "Backend",
+                options: [
+                  { value: "node", label: "Node.js" },
+                  { value: "python", label: "Python" },
+                ],
+              },
+            ]}
+            defaultValue={[]}
+            onValueChange={() => {}}
+            placeholder="Select from groups..."
+            className="w-[350px]"
+            maxCount={2}
+          />
+        </div>
+
+        <div className="p-4 border rounded-md bg-muted/50">
+          <p className="text-sm font-medium mb-2">Features:</p>
+          <ul className="grid grid-cols-2 gap-x-4 gap-y-1 text-sm text-muted-foreground">
+            <li>✨ Multiple variants (default, secondary, destructive, inverted)</li>
+            <li>🌈 Custom badge colors & gradients</li>
+            <li>📁 Grouped options with separators</li>
+            <li>🚫 Disabled options support</li>
+            <li>🎨 Badge animations (bounce, pulse, wiggle, fade, slide)</li>
+            <li>🔍 Built-in search & filter</li>
+            <li>📱 Responsive design (mobile/tablet/desktop)</li>
+            <li>📐 Width constraints (min/max)</li>
+            <li>♿ Full accessibility (ARIA, keyboard nav)</li>
+            <li>🔧 Imperative control via ref</li>
+            <li>🔄 Duplicate handling</li>
+            <li>🎛️ Auto-close, single-line, auto-size modes</li>
+          </ul>
+        </div>
+      </div>
+    ),
+  },
+  {
+    name: 'MultiSelectProAsync',
+    category: 'forms',
+    description: 'Async multi-select with external API search, debouncing, and loading states. Perfect for large datasets and server-side filtering.',
+    importPath: "import { MultiSelectProAsync, useDebounce } from '@djangocfg/ui';",
+    example: `import { MultiSelectProAsync, useDebounce } from '@djangocfg/ui';
+import { useState, useEffect } from 'react';
+
+// Mock API function (replace with your actual API)
+const searchAPI = async (query: string) => {
+  const response = await fetch(\`/api/search?q=\${query}\`);
+  return response.json();
+};
+
+function AsyncExample() {
+  const [searchValue, setSearchValue] = useState('');
+  const [options, setOptions] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [selected, setSelected] = useState<string[]>([]);
+
+  // Debounce search to reduce API calls
+  const debouncedSearch = useDebounce(searchValue, 300);
+
+  // Fetch options when debounced search changes
+  useEffect(() => {
+    if (!debouncedSearch) {
+      setOptions([]);
+      return;
+    }
+
+    const fetchOptions = async () => {
+      setIsLoading(true);
+      try {
+        const results = await searchAPI(debouncedSearch);
+        setOptions(results);
+      } catch (error) {
+        console.error('Search failed:', error);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchOptions();
+  }, [debouncedSearch]);
+
+  return (
+    <MultiSelectProAsync
+      // Search control (managed by parent)
+      searchValue={searchValue}
+      onSearchChange={setSearchValue}
+      isLoading={isLoading}
+
+      // Options from API
+      options={options}
+
+      // Selection
+      onValueChange={setSelected}
+      defaultValue={selected}
+
+      // UI
+      placeholder="Search and select..."
+      searchPlaceholder="Type to search..."
+      emptyText="No results found"
+      loadingText="Searching..."
+
+      // Features
+      variant="default"
+      maxCount={3}
+      closeOnSelect={false}
+    />
+  );
+}`,
+    preview: (() => {
+      // Demo component with mock data
+      const DemoAsync = () => {
+        const [searchValue, setSearchValue] = useState('');
+        const [selected, setSelected] = useState<string[]>([]);
+        const debouncedSearch = useDebounce(searchValue, 300);
+        const [isLoading, setIsLoading] = useState(false);
+
+        // Mock database of countries
+        const allCountries = useMemo(() => [
+          { value: 'us', label: 'United States' },
+          { value: 'uk', label: 'United Kingdom' },
+          { value: 'ca', label: 'Canada' },
+          { value: 'au', label: 'Australia' },
+          { value: 'de', label: 'Germany' },
+          { value: 'fr', label: 'France' },
+          { value: 'it', label: 'Italy' },
+          { value: 'es', label: 'Spain' },
+          { value: 'jp', label: 'Japan' },
+          { value: 'cn', label: 'China' },
+          { value: 'in', label: 'India' },
+          { value: 'br', label: 'Brazil' },
+          { value: 'mx', label: 'Mexico' },
+          { value: 'ru', label: 'Russia' },
+          { value: 'za', label: 'South Africa' },
+        ], []);
+
+        // Filtered options based on debounced search
+        const filteredOptions = useMemo(() => {
+          if (!debouncedSearch) return [];
+          return allCountries.filter(country =>
+            country.label.toLowerCase().includes(debouncedSearch.toLowerCase())
+          );
+        }, [debouncedSearch, allCountries]);
+
+        // Simulate API loading
+        useEffect(() => {
+          if (debouncedSearch) {
+            setIsLoading(true);
+            const timer = setTimeout(() => setIsLoading(false), 300);
+            return () => clearTimeout(timer);
+          }
+        }, [debouncedSearch]);
+
+        return (
+          <div className="space-y-4">
+            <MultiSelectProAsync
+              searchValue={searchValue}
+              onSearchChange={setSearchValue}
+              isLoading={isLoading}
+              options={filteredOptions}
+              onValueChange={setSelected}
+              defaultValue={selected}
+              placeholder="Search countries..."
+              searchPlaceholder="Type to search countries..."
+              emptyText="No countries found"
+              loadingText="Searching..."
+              maxCount={2}
+              className="w-[350px]"
+            />
+
+            <div className="p-4 border rounded-md bg-muted/50">
+              <p className="text-sm font-medium mb-2">Features:</p>
+              <ul className="space-y-1 text-sm text-muted-foreground">
+                <li>🔍 <strong>Async search</strong> - Controlled search value for API integration</li>
+                <li>⏱️ <strong>Debouncing</strong> - Use useDebounce hook to reduce API calls</li>
+                <li>🔄 <strong>Loading states</strong> - Shows spinner during data fetching</li>
+                <li>🧹 <strong>Auto-clear</strong> - Clears search when popover closes</li>
+                <li>✨ <strong>All MultiSelectPro features</strong> - Animations, variants, groups, etc.</li>
+              </ul>
+              <div className="mt-3 p-2 bg-muted rounded text-xs">
+                <strong>Try it:</strong> Type "united" or "india" to see async filtering
+              </div>
+            </div>
+          </div>
+        );
+      };
+
+      return <DemoAsync />;
+    })(),
+  },
   {
     name: 'InputOTP',
     category: 'forms',

package/src/layouts/UILayout/config/components/hooks.config.tsx

@@ -92,20 +92,57 @@ const countdown = useCountdown(targetDate);
   {
     name: 'useDebounce',
     category: 'hooks',
-    description: 'Debounce value changes',
+    description: 'Debounce value changes to reduce API calls and improve performance. Perfect for search inputs and form fields.',
     importPath: "import { useDebounce } from '@djangocfg/ui';",
-    example: `const [search, setSearch] = useState('');
-const debouncedSearch = useDebounce(search, 500);
+    example: `// Basic search debouncing
+const [search, setSearch] = useState('');
+const debouncedSearch = useDebounce(search, 300); // Default 300ms
 
-// debouncedSearch updates 500ms after last change`,
+useEffect(() => {
+  if (debouncedSearch) {
+    // API call only fires 300ms after user stops typing
+    fetchResults(debouncedSearch);
+  }
+}, [debouncedSearch]);
+
+// With MultiSelectPro (has built-in search)
+const [searchValue, setSearchValue] = useState('');
+const debouncedSearchValue = useDebounce(searchValue, 500);
+
+useEffect(() => {
+  // Fetch options from API with debounced search
+  if (debouncedSearchValue) {
+    fetchOptions(debouncedSearchValue);
+  }
+}, [debouncedSearchValue]);
+
+<MultiSelectPro
+  options={filteredOptions}
+  onValueChange={setSelected}
+  placeholder="Search and select..."
+  searchable={true}
+  // ... other props
+/>`,
     preview: (
       <div className="p-4 border rounded-md">
         <code className="text-sm">
-          useDebounce(value, delay)
+          const debouncedValue = useDebounce(value, delay);
         </code>
-        <p className="mt-2 text-sm text-muted-foreground">
-          Debounces value changes with specified delay
-        </p>
+        <div className="mt-3 space-y-2 text-sm text-muted-foreground">
+          <p><strong>Parameters:</strong></p>
+          <ul className="list-disc list-inside space-y-1 ml-2">
+            <li><code>value</code>: Any value to debounce</li>
+            <li><code>delay</code>: Delay in milliseconds (default: 300ms)</li>
+          </ul>
+          <p className="mt-2"><strong>Returns:</strong> Debounced value</p>
+          <p className="mt-2"><strong>Use Cases:</strong></p>
+          <ul className="list-disc list-inside space-y-1 ml-2">
+            <li>Search inputs (reduce API calls)</li>
+            <li>Form validation</li>
+            <li>Auto-save functionality</li>
+            <li>Scroll/resize event handlers</li>
+          </ul>
+        </div>
       </div>
     ),
   },