@kubex/zinc 1.0.25 → 1.0.99

package/docs/pages/components/data-table-search.md

@@ -0,0 +1,451 @@
+---
+meta:
+  title: Data Table Search
+  description: A search component for data tables with debounced input and support for additional form controls.
+layout: component
+---
+
+## Examples
+
+### Basic Search
+
+Use the `zn-data-table-search` component to provide search functionality for data tables. The component includes a search input with a search icon prefix and is clearable by default.
+
+```html:preview
+<zn-data-table-search></zn-data-table-search>
+```
+
+:::tip
+This component works with standard `<form>` elements and integrates seamlessly with data tables. The search input is debounced to prevent excessive event firing while the user types.
+:::
+
+### Custom Placeholder
+
+Use the `placeholder` attribute to customize the input placeholder text.
+
+```html:preview
+<zn-data-table-search placeholder="Search products..."></zn-data-table-search>
+```
+
+### Help Text
+
+Add descriptive help text to guide users with the `help-text` attribute.
+
+```html:preview
+<zn-data-table-search
+  placeholder="Search users..."
+  help-text="Search by name, email, or user ID">
+</zn-data-table-search>
+```
+
+### Default Value
+
+Set a default search value using the `value` attribute.
+
+```html:preview
+<zn-data-table-search value="example search" placeholder="Search..."></zn-data-table-search>
+```
+
+### Custom Field Name
+
+Use the `name` attribute to set a custom field name for form submission. The default name is "search".
+
+```html:preview
+<zn-data-table-search name="query" placeholder="Search..."></zn-data-table-search>
+```
+
+### Debounce Delay
+
+Control the debounce delay using the `debounce-delay` attribute. The default is 350 milliseconds.
+
+```html:preview
+<zn-data-table-search
+  debounce-delay="1000"
+  placeholder="Search..."
+  help-text="1 second debounce delay">
+</zn-data-table-search>
+<br />
+<zn-data-table-search
+  debounce-delay="100"
+  placeholder="Search..."
+  help-text="100ms debounce delay (very responsive)">
+</zn-data-table-search>
+```
+
+### Search URI
+
+Use the `search-uri` attribute to specify a URI for search operations. This will be included in the `zn-search-change` event detail.
+
+```html:preview
+<zn-data-table-search
+  search-uri="/api/products/search"
+  placeholder="Search products...">
+</zn-data-table-search>
+
+<script type="module">
+  const search = document.querySelector('zn-data-table-search');
+
+  await customElements.whenDefined('zn-data-table-search');
+
+  search.addEventListener('zn-search-change', (event) => {
+    console.log('Search URI:', event.detail.searchUri);
+    console.log('Search value:', event.detail.value);
+  });
+</script>
+```
+
+### Listening to Search Events
+
+The component emits a `zn-search-change` event when the search value changes (after the debounce delay). The event detail includes the search value, any additional form data from slotted inputs, and the search URI if provided.
+
+```html:preview
+<zn-data-table-search class="search-demo" placeholder="Type to search..."></zn-data-table-search>
+
+<div class="search-results" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: var(--zn-border-radius-medium);">
+  <strong>Search Results:</strong>
+  <div class="results-content">No search performed yet</div>
+</div>
+
+<script type="module">
+  const search = document.querySelector('.search-demo');
+  const resultsDiv = document.querySelector('.results-content');
+
+  await customElements.whenDefined('zn-data-table-search');
+
+  search.addEventListener('zn-search-change', (event) => {
+    const { value, formData, searchUri } = event.detail;
+    if (value) {
+      resultsDiv.textContent = `Searching for: "${value}"`;
+    } else {
+      resultsDiv.textContent = 'Search cleared';
+    }
+  });
+</script>
+```
+
+### Additional Form Controls
+
+The component supports slotting additional form controls that will be included in the search event data. This is useful for adding filters or other search parameters.
+
+```html:preview
+<zn-data-table-search placeholder="Search...">
+  <zn-select name="category" value="all">
+    <zn-option value="all">All Categories</zn-option>
+    <zn-option value="electronics">Electronics</zn-option>
+    <zn-option value="books">Books</zn-option>
+    <zn-option value="clothing">Clothing</zn-option>
+  </zn-select>
+
+  <zn-select name="status" value="active">
+    <zn-option value="all">All Status</zn-option>
+    <zn-option value="active">Active</zn-option>
+    <zn-option value="inactive">Inactive</zn-option>
+  </zn-select>
+</zn-data-table-search>
+
+<div class="filter-results" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: var(--zn-border-radius-medium);">
+  <strong>Search Parameters:</strong>
+  <pre class="filter-content" style="margin-top: 0.5rem; font-size: 0.875rem;">No search performed yet</pre>
+</div>
+
+<script type="module">
+  const filterSearch = document.querySelectorAll('zn-data-table-search')[document.querySelectorAll('zn-data-table-search').length - 1];
+  const filterResults = document.querySelector('.filter-content');
+
+  await customElements.whenDefined('zn-data-table-search');
+
+  filterSearch.addEventListener('zn-search-change', (event) => {
+    const { value, formData } = event.detail;
+    filterResults.textContent = JSON.stringify({
+      search: value,
+      ...formData
+    }, null, 2);
+  });
+</script>
+```
+
+:::tip
+Slotted form controls are hidden from view but their values are collected and included in the `formData` property of the `zn-search-change` event. This allows you to manage additional search parameters without cluttering the UI.
+:::
+
+### Supported Slotted Input Types
+
+The following input types are supported in the default slot and will have their values included in the form data:
+
+- `zn-input`
+- `zn-select`
+- `zn-query-builder`
+- `zn-multiselect`
+- `zn-params-select`
+- `zn-datepicker`
+- Native HTML `input`, `select`, and `textarea` elements
+
+```html:preview
+<zn-data-table-search placeholder="Search users...">
+  <zn-select name="role">
+    <zn-option value="">All Roles</zn-option>
+    <zn-option value="admin">Admin</zn-option>
+    <zn-option value="user">User</zn-option>
+  </zn-select>
+
+  <zn-datepicker name="dateFrom"></zn-datepicker>
+  <zn-datepicker name="dateTo"></zn-datepicker>
+
+  <input type="hidden" name="includeArchived" value="false" />
+</zn-data-table-search>
+
+<div class="advanced-results" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: var(--zn-border-radius-medium);">
+  <strong>All Search Parameters:</strong>
+  <pre class="advanced-content" style="margin-top: 0.5rem; font-size: 0.875rem;">No search performed yet</pre>
+</div>
+
+<script type="module">
+  const advancedSearch = document.querySelectorAll('zn-data-table-search')[document.querySelectorAll('zn-data-table-search').length - 1];
+  const advancedResults = document.querySelector('.advanced-content');
+
+  await customElements.whenDefined('zn-data-table-search');
+  await customElements.whenDefined('zn-datepicker');
+
+  advancedSearch.addEventListener('zn-search-change', (event) => {
+    const { value, formData } = event.detail;
+    advancedResults.textContent = JSON.stringify({
+      search: value,
+      ...formData
+    }, null, 2);
+  });
+</script>
+```
+
+### Programmatic Control
+
+You can programmatically control the search component by setting its `value` property or by calling the clear functionality through the internal input component.
+
+```html:preview
+<zn-data-table-search class="programmatic-search" placeholder="Search..."></zn-data-table-search>
+
+<div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
+  <zn-button class="set-value-btn" variant="primary" outline>Set Value</zn-button>
+  <zn-button class="clear-value-btn" variant="default" outline>Clear Value</zn-button>
+</div>
+
+<script type="module">
+  const progSearch = document.querySelector('.programmatic-search');
+  const setBtn = document.querySelector('.set-value-btn');
+  const clearBtn = document.querySelector('.clear-value-btn');
+
+  await Promise.all([
+    customElements.whenDefined('zn-data-table-search'),
+    customElements.whenDefined('zn-button')
+  ]);
+
+  setBtn.addEventListener('click', () => {
+    progSearch.value = 'programmatic value';
+  });
+
+  clearBtn.addEventListener('click', () => {
+    progSearch.value = '';
+  });
+</script>
+```
+
+### Integration with Data Tables
+
+The `zn-data-table-search` component is designed to work seamlessly with the `zn-data-table` component. Here's a complete example showing how to integrate search functionality with a data table:
+
+```html:preview
+<zn-data-table-search
+  class="table-search"
+  search-uri="/api/users"
+  placeholder="Search users by name or email...">
+</zn-data-table-search>
+
+<div class="search-status" style="margin: 1rem 0; padding: 0.75rem; background: var(--zn-color-primary-50); border-radius: var(--zn-border-radius-medium); font-size: 0.875rem;">
+  Ready to search
+</div>
+
+<script type="module">
+  const tableSearch = document.querySelector('.table-search');
+  const statusDiv = document.querySelector('.search-status');
+
+  await customElements.whenDefined('zn-data-table-search');
+
+  tableSearch.addEventListener('zn-search-change', async (event) => {
+    const { value, searchUri } = event.detail;
+
+    if (!value) {
+      statusDiv.textContent = 'Search cleared - showing all results';
+      statusDiv.style.background = 'var(--zn-color-neutral-50)';
+      return;
+    }
+
+    statusDiv.textContent = `Searching for "${value}" at ${searchUri}...`;
+    statusDiv.style.background = 'var(--zn-color-warning-50)';
+
+    // Simulate API call
+    setTimeout(() => {
+      statusDiv.textContent = `Found results for "${value}"`;
+      statusDiv.style.background = 'var(--zn-color-success-50)';
+    }, 500);
+  });
+</script>
+```
+
+:::tip
+**Usage Pattern:** Use `zn-data-table-search` as the primary search interface for data tables. The component handles debouncing automatically, so you can safely make API calls in response to the `zn-search-change` event without worrying about excessive requests.
+:::
+
+### Form Integration
+
+The component implements the `ZincFormControl` interface and can be used within forms. The search value will be submitted with the form.
+
+```html:preview
+<form class="search-form">
+  <zn-data-table-search
+    name="userSearch"
+    placeholder="Search users...">
+  </zn-data-table-search>
+
+  <zn-button type="submit" variant="primary" style="margin-top: 1rem;">
+    Submit Form
+  </zn-button>
+</form>
+
+<div class="form-output" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: var(--zn-border-radius-medium);">
+  <strong>Form Data:</strong>
+  <pre class="form-content" style="margin-top: 0.5rem; font-size: 0.875rem;">No form submission yet</pre>
+</div>
+
+<script type="module">
+  const searchForm = document.querySelector('.search-form');
+  const formOutput = document.querySelector('.form-content');
+
+  await Promise.all([
+    customElements.whenDefined('zn-data-table-search'),
+    customElements.whenDefined('zn-button')
+  ]);
+
+  searchForm.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const formData = new FormData(searchForm);
+    const data = Object.fromEntries(formData);
+    formOutput.textContent = JSON.stringify(data, null, 2);
+  });
+</script>
+```
+
+### Getting Form Data
+
+Use the `getFormData()` method to retrieve all form data from the search component and any slotted input elements.
+
+```html:preview
+<zn-data-table-search
+  class="form-data-search"
+  name="search"
+  value="test search"
+  placeholder="Search...">
+  <zn-select name="filter" value="active">
+    <zn-option value="all">All</zn-option>
+    <zn-option value="active">Active</zn-option>
+    <zn-option value="inactive">Inactive</zn-option>
+  </zn-select>
+  <input type="hidden" name="page" value="1" />
+</zn-data-table-search>
+
+<zn-button class="get-data-btn" variant="primary" outline style="margin-top: 1rem;">
+  Get Form Data
+</zn-button>
+
+<div class="data-output" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: var(--zn-border-radius-medium);">
+  <strong>Form Data Object:</strong>
+  <pre class="data-content" style="margin-top: 0.5rem; font-size: 0.875rem;">Click the button to retrieve form data</pre>
+</div>
+
+<script type="module">
+  const formDataSearch = document.querySelector('.form-data-search');
+  const getDataBtn = document.querySelector('.get-data-btn');
+  const dataOutput = document.querySelector('.data-content');
+
+  await Promise.all([
+    customElements.whenDefined('zn-data-table-search'),
+    customElements.whenDefined('zn-button'),
+    customElements.whenDefined('zn-select')
+  ]);
+
+  getDataBtn.addEventListener('click', () => {
+    const formData = formDataSearch.getFormData();
+    dataOutput.textContent = JSON.stringify(formData, null, 2);
+  });
+</script>
+```
+
+## Usage Guidelines
+
+### When to Use
+
+- **Data Table Filtering:** Use as the primary search interface for data tables and lists
+- **Real-time Search:** When you need debounced search input to reduce API calls
+- **Complex Filtering:** When you need to combine search with additional filter parameters
+- **Form Integration:** When search needs to be part of a larger form submission
+
+### Best Practices
+
+1. **Placeholder Text:** Use clear, descriptive placeholder text that indicates what users can search for
+2. **Help Text:** Provide help text when the search behavior isn't obvious or when there are special search features
+3. **Debounce Delay:** The default 350ms delay works well for most cases. Increase it for expensive operations, decrease it for very fast searches
+4. **Search URI:** Always provide a `search-uri` when the search data will be sent to a specific endpoint
+5. **Event Handling:** Handle the `zn-search-change` event to trigger searches. The event includes both the search value and any additional form data
+6. **Loading States:** Show loading indicators during search operations to provide feedback to users
+
+### Accessibility
+
+The component is built with accessibility in mind:
+
+- Uses semantic HTML with proper input type (`search`)
+- Includes a visible search icon prefix for visual recognition
+- Supports keyboard navigation and clearing via the clearable input
+- Integrates with form validation and submission
+- Provides proper labeling through the help-text attribute
+
+## Properties
+
+| Property        | Attribute        | Type     | Default      | Description |
+|----------------|------------------|----------|--------------|-------------|
+| `name`         | `name`           | `string` | `'search'`   | The name of the search input field for form submission |
+| `value`        | `value`          | `string` | `''`         | The current search value |
+| `placeholder`  | `placeholder`    | `string` | `'Search...'`| The placeholder text for the search input |
+| `helpText`     | `help-text`      | `string` | `''`         | Help text displayed below the search input |
+| `searchUri`    | `search-uri`     | `string` | `undefined`  | Optional URI to use for search operations |
+| `debounceDelay`| `debounce-delay` | `number` | `350`        | The delay in milliseconds before triggering a search after the user stops typing |
+
+## Events
+
+| Event              | Description | Event Detail |
+|--------------------|-------------|--------------|
+| `zn-search-change` | Emitted when the search value changes after the debounce delay. Also emitted immediately when the search is cleared. | `{ value: string, formData: Record<string, any>, searchUri?: string }` |
+
+## Methods
+
+| Method         | Description |
+|----------------|-------------|
+| `getFormData()` | Returns an object containing all form data from the search input and any slotted form controls |
+| `checkValidity()` | Checks the validity of the form control (always returns `true` for this component) |
+| `reportValidity()` | Reports the validity of the form control (always returns `true` for this component) |
+| `setCustomValidity()` | Sets custom validity (no-op for this component, but required by the form control interface) |
+| `getForm()` | Returns the parent form element if one exists |
+
+## Slots
+
+| Name      | Description |
+|-----------|-------------|
+| (default) | Additional form inputs to be included in the search form data. Slotted elements are hidden but their values are collected. |
+
+## CSS Parts
+
+| Part   | Description |
+|--------|-------------|
+| `base` | The component's base wrapper |
+
+## Dependencies
+
+- `zn-input` - Used for the search input field
+- `zn-icon` - Used for the search icon prefix

package/docs/pages/components/data-table-sort.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Data Table Sort
-  description:
+  description: A sorting control component that displays a dropdown with field selection and sort direction (ascending/descending) options, with clear and update actions.
 layout: component
 ---
 
@@ -11,10 +11,71 @@ layout: component
 
 ## Examples
 
-### First Example
+### Basic Usage
 
-TODO
+The data table sort component provides a dropdown interface for sorting data.
 
-### Second Example
+```html:preview
+<zn-data-table-sort></zn-data-table-sort>
+```
+
+### In Table Header
 
-TODO
+Typically used in data table headers for sorting functionality.
+
+```html:preview
+<div style="display: flex; gap: 10px; align-items: center;">
+  <span>Product List</span>
+  <zn-data-table-sort></zn-data-table-sort>
+</div>
+```
+
+### With Action Bar
+
+Combine with other table controls in an action bar.
+
+```html:preview
+<zn-action-bar>
+  <zn-button slot="menu" color="transparent">All Items</zn-button>
+  <zn-button slot="menu" color="transparent">Active</zn-button>
+  <zn-button slot="menu" color="transparent">Archived</zn-button>
+
+  <zn-data-table-sort slot="actions"></zn-data-table-sort>
+  <zn-button slot="actions" icon="filter_alt" color="transparent"></zn-button>
+  <zn-button slot="actions" icon="refresh" color="transparent"></zn-button>
+</zn-action-bar>
+```
+
+### Multiple Sort Controls
+
+Use multiple sort controls for different sections or views.
+
+```html:preview
+<div class="form-spacing">
+  <div>
+    <h4>Customer List</h4>
+    <zn-data-table-sort></zn-data-table-sort>
+  </div>
+
+  <div>
+    <h4>Order History</h4>
+    <zn-data-table-sort></zn-data-table-sort>
+  </div>
+
+  <div>
+    <h4>Product Inventory</h4>
+    <zn-data-table-sort></zn-data-table-sort>
+  </div>
+</div>
+```
+
+### Compact Layout
+
+The component automatically uses a compact size suitable for table headers.
+
+```html:preview
+<div style="display: flex; align-items: center; padding: 10px; background: var(--zn-color-neutral-50); border-radius: 4px;">
+  <span style="font-weight: bold; margin-right: auto;">Results (123)</span>
+  <zn-data-table-sort></zn-data-table-sort>
+</div>
+```