intelliwaketssveltekitv25 1.0.81 → 1.0.83

package/docs/DropDown.md

@@ -0,0 +1,269 @@
+# DropDown Component
+
+**Replaces:** `<select>` elements and custom dropdown menus
+
+**Purpose:** Rich dropdown menu with keyboard navigation, icons, search, and action handling
+
+**When to Use:**
+- Action menus (context menus, toolbar dropdowns)
+- Navigation dropdowns with links
+- Replacing `<select>` when you need icons, dividers, or complex items
+- Any menu that needs better UX than native `<select>`
+
+## Key Props
+
+- `show?: boolean` ($bindable) - Control dropdown open/closed state
+- `position?: TDropDownControlPosition` (default: null) - Menu position relative to button
+- `ddActions?: IDDAction[]` (default: []) - Array of menu items/actions (see IDDAction interface below)
+- `noCaret?: boolean` - Hide the dropdown arrow icon
+- `buttonTitle?: string | null` - Button text (if not using `button` snippet)
+- `buttonClass?: string` - CSS classes for the button
+- `controlClass?: string` - CSS classes for the dropdown wrapper
+- `toggleClass?: string` - CSS classes for the toggle container
+- `inputControl?: boolean` - Style button as input control
+- `fullBlock?: boolean` - Make button full width
+- `bodyClass?: string` - CSS classes for dropdown body/menu
+- `sameSize?: boolean` - Make dropdown menu same width as button
+- `zIndex?: number` (default: 40) - Z-index for dropdown positioning
+- `disabled?: boolean` - Disable the dropdown
+- `hidden?: boolean` - Hide the dropdown
+- `hideEmptyDDActions?: boolean` - Auto-hide if no actions provided
+- `verbose?: boolean` - Enable console logging for debugging
+- `dataColor?: TDefaultColorPalate` - Color theme for button
+- `clientWidth?: number` ($bindable) - Width of the button element
+
+## Snippets
+
+- `button?: Snippet` - Custom button content (overrides `buttonTitle`)
+- `actions?: Snippet` - Custom menu content (in addition to or instead of `ddActions`)
+
+## IDDAction Interface
+
+Menu items configuration:
+
+```typescript
+interface IDDAction {
+  title?: string                    // Display text
+  key?: string | number              // Unique key for item
+  divider?: boolean                  // Render as divider line
+  header?: boolean                   // Render as header text (bold, no click)
+  dividerGroup?: string              // Auto-add divider when group changes
+  headerGroup?: string               // Auto-add header when group changes
+  active?: boolean                   // Highlight as active/selected
+  disabled?: boolean                 // Disable interaction
+  hidden?: boolean                   // Hide from menu
+  indented?: boolean                 // Indent item (for hierarchy)
+
+  // Actions
+  action?: () => void                // Click handler
+  href?: string                      // Navigation URL
+  hrefReplace?: boolean              // Use replaceState navigation
+  hrefDownload?: string              // Download URL
+  hrefDownloadFilename?: string      // Filename for download
+
+  // Visual
+  faProps?: IFAProps                 // FontAwesome icon
+  imageHref?: string                 // Image URL for icon
+
+  // Alternate action (right side button)
+  alternateAction?: () => void       // Right-side button action
+  alternateTitle?: string            // Right-side button text
+  alternateFAProps?: IFAProps        // Right-side button icon
+  alternateNoClose?: boolean         // Keep menu open after alternate action
+
+  // Behavior
+  noCloseMenu?: boolean              // Keep menu open after action
+}
+```
+
+## Keyboard Navigation
+
+- **Arrow Down:** Open menu / Move to next item
+- **Arrow Up:** Move to previous item
+- **Enter:** Execute selected item action
+- **Tab:** Close menu
+- **Type letter:** Jump to first item starting with that letter
+
+## Usage Examples
+
+```svelte
+<script>
+  import { DropDown } from 'intelliwaketssveltekitv25';
+  import { faEdit, faTrash, faCopy } from '@fortawesome/free-solid-svg-icons';
+
+  let showMenu = $state(false);
+  let selectedOption = $state('option1');
+
+  const actions = [
+    {
+      title: 'Edit',
+      faProps: { icon: faEdit },
+      action: () => editItem()
+    },
+    {
+      title: 'Duplicate',
+      faProps: { icon: faCopy },
+      action: () => duplicateItem()
+    },
+    { divider: true },
+    {
+      title: 'Delete',
+      faProps: { icon: faTrash },
+      action: () => deleteItem()
+    }
+  ];
+</script>
+
+<!-- Simple action menu -->
+<DropDown
+  bind:show={showMenu}
+  buttonTitle="Actions"
+  ddActions={actions}
+/>
+
+<!-- As select replacement with active indicator -->
+<DropDown
+  bind:show={showOptions}
+  buttonTitle={selectedOption}
+  ddActions={[
+    {
+      title: 'Option 1',
+      active: selectedOption === 'option1',
+      action: () => selectedOption = 'option1'
+    },
+    {
+      title: 'Option 2',
+      active: selectedOption === 'option2',
+      action: () => selectedOption = 'option2'
+    },
+    {
+      title: 'Option 3',
+      active: selectedOption === 'option3',
+      action: () => selectedOption = 'option3'
+    }
+  ]}
+  inputControl
+/>
+
+<!-- With navigation links -->
+<DropDown
+  buttonTitle="Navigate"
+  ddActions={[
+    { title: 'Dashboard', href: '/dashboard' },
+    { title: 'Settings', href: '/settings' },
+    { divider: true },
+    { title: 'Logout', href: '/logout', hrefReplace: true }
+  ]}
+/>
+
+<!-- With grouped items -->
+<DropDown
+  buttonTitle="Options"
+  ddActions={[
+    { title: 'File Operations', header: true },
+    { title: 'Open', action: () => open() },
+    { title: 'Save', action: () => save() },
+    { divider: true },
+    { title: 'Edit Operations', header: true },
+    { title: 'Cut', action: () => cut() },
+    { title: 'Copy', action: () => copy() },
+    { title: 'Paste', action: () => paste() }
+  ]}
+/>
+
+<!-- With auto-grouping by headerGroup -->
+<DropDown
+  buttonTitle="Grouped"
+  ddActions={[
+    { title: 'Item 1', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item 2', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item 3', headerGroup: 'Group B', action: () => {} },
+    { title: 'Item 4', headerGroup: 'Group B', action: () => {} }
+  ]}
+/>
+<!-- Automatically adds headers "Group A" and "Group B" -->
+
+<!-- Custom button content -->
+<DropDown bind:show={showCustom} ddActions={actions}>
+  {#snippet button()}
+    <Icon icon={faEllipsisV} />
+    More Options
+  {/snippet}
+</DropDown>
+
+<!-- Full width dropdown -->
+<DropDown
+  buttonTitle="Select Option"
+  ddActions={options}
+  fullBlock
+  sameSize
+  inputControl
+/>
+
+<!-- With disabled items -->
+<DropDown
+  buttonTitle="Actions"
+  ddActions={[
+    { title: 'Available Action', action: () => {} },
+    { title: 'Coming Soon', disabled: true },
+    { title: 'Premium Only', disabled: true }
+  ]}
+/>
+
+<!-- With alternate actions (two buttons per row) -->
+<DropDown
+  buttonTitle="Files"
+  ddActions={[
+    {
+      title: 'document.pdf',
+      action: () => openFile('document.pdf'),
+      alternateAction: () => downloadFile('document.pdf'),
+      alternateFAProps: { icon: faDownload }
+    }
+  ]}
+/>
+
+<!-- Download action -->
+<DropDown
+  buttonTitle="Export"
+  ddActions={[
+    {
+      title: 'Export as CSV',
+      hrefDownload: '/api/export?format=csv',
+      hrefDownloadFilename: 'data.csv'
+    },
+    {
+      title: 'Export as PDF',
+      hrefDownload: '/api/export?format=pdf',
+      hrefDownloadFilename: 'data.pdf'
+    }
+  ]}
+/>
+```
+
+## Common Mistakes
+
+- ❌ Not providing `action`, `href`, or `hrefDownload` for menu items
+  ✅ Correct: Every menu item (except dividers/headers) needs an action
+
+- ❌ Using DropDown when MultiSelect is more appropriate
+  ✅ Correct: Use `MultiSelect` for selecting multiple options, `DropDown` for single actions/selections
+
+- ❌ Forgetting to handle menu close in custom `noCloseMenu` actions
+  ✅ Correct: Manually set `show = false` when using `noCloseMenu: true`
+
+- ❌ Not using `bind:show` for controlled dropdowns
+  ✅ Correct: `<DropDown bind:show={showMenu}>` to control open/close state
+
+- ❌ Using complex objects as `key` without providing unique string/number keys
+  ✅ Correct: Always provide `key` prop for array items
+
+## Related Components
+
+- `DropDownControl` - Lower-level dropdown control (used internally by DropDown)
+- `MultiSelect` - For selecting multiple options from a list
+- `Importer` - Specialized dropdown for file imports
+
+## Storybook
+
+See `Components/DropDown` stories