@kubex/zinc 1.0.25 → 1.0.98

package/docs/pages/components/pagination.md

@@ -1,22 +1,348 @@
 ---
 meta:
   title: Pagination
-  description:
+  description: Pagination components help users navigate through pages of content.
 layout: component
 ---
 
 ```html:preview
-<zn-pagination></zn-pagination>
+<zn-pagination total="100" limit="10" page="1" uri="#page#"></zn-pagination>
 ```
 
+Pagination controls allow users to navigate through large sets of data by dividing content into discrete pages. The component automatically generates page number buttons, previous/next navigation, and handles the display logic for showing a reasonable number of page buttons.
+
 ## Examples
 
-### First Example
+### Basic Pagination
+
+Use the `total`, `limit`, and `page` attributes to configure the pagination. The `uri` attribute defines the URL pattern for page links, where `#page#` will be replaced with the page number.
+
+```html:preview
+<zn-pagination total="250" limit="25" page="1" uri="/items?page=#page#"></zn-pagination>
+```
+
+### Current Page
+
+The `page` attribute sets the currently active page. The active page is highlighted and non-clickable.
+
+```html:preview
+<zn-pagination total="200" limit="20" page="5" uri="#page#"></zn-pagination>
+```
+
+### Different Page Sizes
+
+Use the `limit` attribute to control how many items are shown per page. This affects the total number of pages calculated.
+
+```html:preview
+<zn-pagination total="100" limit="10" page="1" uri="#page#"></zn-pagination>
+<br />
+<zn-pagination total="100" limit="20" page="1" uri="#page#"></zn-pagination>
+<br />
+<zn-pagination total="100" limit="50" page="1" uri="#page#"></zn-pagination>
+```
+
+### First Page
+
+When on the first page, the "Previous" button is disabled.
+
+```html:preview
+<zn-pagination total="100" limit="10" page="1" uri="#page#"></zn-pagination>
+```
+
+### Last Page
+
+When on the last page, the "Next" button is disabled.
+
+```html:preview
+<zn-pagination total="100" limit="10" page="10" uri="#page#"></zn-pagination>
+```
+
+### Middle Pages
+
+When navigating through middle pages, the component shows up to 5 page buttons centered around the current page, with Previous and Next buttons enabled.
+
+```html:preview
+<zn-pagination total="200" limit="10" page="8" uri="#page#"></zn-pagination>
+```
+
+### Few Pages
+
+When there are 5 or fewer total pages, all page numbers are displayed.
+
+```html:preview
+<zn-pagination total="50" limit="10" page="3" uri="#page#"></zn-pagination>
+<br />
+<zn-pagination total="30" limit="10" page="2" uri="#page#"></zn-pagination>
+```
+
+### Many Pages
+
+For larger datasets with many pages, the component shows a window of up to 5 page buttons. The window adjusts based on the current page position.
+
+```html:preview
+<zn-pagination total="1000" limit="10" page="1" uri="#page#"></zn-pagination>
+<br />
+<zn-pagination total="1000" limit="10" page="50" uri="#page#"></zn-pagination>
+<br />
+<zn-pagination total="1000" limit="10" page="100" uri="#page#"></zn-pagination>
+```
+
+### Custom URI Patterns
+
+The `uri` attribute supports any URL pattern. Use `#page#` as a placeholder for the page number.
+
+```html:preview
+<zn-pagination total="150" limit="15" page="3" uri="/products/category/electronics?page=#page#"></zn-pagination>
+<br />
+<zn-pagination total="150" limit="15" page="3" uri="/api/users/#page#"></zn-pagination>
+<br />
+<zn-pagination total="150" limit="15" page="3" uri="?q=search&page=#page#&sort=asc"></zn-pagination>
+```
+
+### Dynamic Pagination with JavaScript
+
+You can dynamically update pagination properties to respond to data changes.
+
+```html:preview
+<div id="pagination-demo">
+  <div style="margin-bottom: 1rem; padding: 1rem; background: #f5f5f5; border-radius: 4px;">
+    <strong>Current Settings:</strong>
+    <div id="settings-display" style="margin-top: 0.5rem; font-family: monospace; font-size: 13px;"></div>
+  </div>
+
+  <zn-pagination id="dynamic-pagination" total="100" limit="10" page="1" uri="#page#"></zn-pagination>
+
+  <div style="margin-top: 1rem; display: flex; gap: 0.5rem; flex-wrap: wrap;">
+    <zn-button id="set-page-1" size="small">Go to Page 1</zn-button>
+    <zn-button id="set-page-5" size="small">Go to Page 5</zn-button>
+    <zn-button id="set-total-50" size="small" color="info">Set Total: 50</zn-button>
+    <zn-button id="set-total-200" size="small" color="info">Set Total: 200</zn-button>
+    <zn-button id="set-limit-5" size="small" color="success">Set Limit: 5</zn-button>
+    <zn-button id="set-limit-20" size="small" color="success">Set Limit: 20</zn-button>
+  </div>
+</div>
+
+<script type="module">
+  const pagination = document.querySelector('#dynamic-pagination');
+  const display = document.querySelector('#settings-display');
+
+  function updateDisplay() {
+    const totalPages = Math.ceil(pagination.total / pagination.limit);
+    display.innerHTML = `
+      Page: ${pagination.page} / ${totalPages}<br>
+      Total Items: ${pagination.total}<br>
+      Items per Page: ${pagination.limit}<br>
+      URI Pattern: ${pagination.uri}
+    `;
+  }
+
+  // Initial display
+  updateDisplay();
+
+  // Listen for attribute changes
+  const observer = new MutationObserver(updateDisplay);
+  observer.observe(pagination, { attributes: true });
+
+  document.querySelector('#set-page-1').addEventListener('click', () => {
+    pagination.page = 1;
+  });
+
+  document.querySelector('#set-page-5').addEventListener('click', () => {
+    pagination.page = 5;
+  });
+
+  document.querySelector('#set-total-50').addEventListener('click', () => {
+    pagination.total = 50;
+    pagination.page = Math.min(pagination.page, Math.ceil(50 / pagination.limit));
+  });
+
+  document.querySelector('#set-total-200').addEventListener('click', () => {
+    pagination.total = 200;
+  });
+
+  document.querySelector('#set-limit-5').addEventListener('click', () => {
+    pagination.limit = 5;
+    pagination.page = Math.min(pagination.page, Math.ceil(pagination.total / 5));
+  });
+
+  document.querySelector('#set-limit-20').addEventListener('click', () => {
+    pagination.limit = 20;
+    pagination.page = Math.min(pagination.page, Math.ceil(pagination.total / 20));
+  });
+</script>
+```
+
+### Pagination with Data Table
+
+A common use case is pairing pagination with a data table or list of items.
+
+```html:preview
+<div id="table-pagination-demo">
+  <div style="margin-bottom: 1rem; padding: 1rem; background: #f5f5f5; border-radius: 4px;">
+    <div id="item-list" style="font-family: monospace; font-size: 13px; line-height: 1.6;"></div>
+  </div>
+
+  <zn-pagination id="table-pagination" total="50" limit="5" page="1" uri="#page#"></zn-pagination>
+</div>
+
+<script type="module">
+  const pagination = document.querySelector('#table-pagination');
+  const itemList = document.querySelector('#item-list');
+
+  // Generate sample data
+  const totalItems = 50;
+  const items = Array.from({ length: totalItems }, (_, i) => ({
+    id: i + 1,
+    name: `Item ${i + 1}`,
+    description: `Description for item ${i + 1}`
+  }));
+
+  function renderItems() {
+    const { page, limit } = pagination;
+    const startIndex = (page - 1) * limit;
+    const endIndex = Math.min(startIndex + limit, totalItems);
+    const pageItems = items.slice(startIndex, endIndex);
+
+    itemList.innerHTML = `
+      <strong>Showing items ${startIndex + 1}-${endIndex} of ${totalItems}</strong><br><br>
+      ${pageItems.map(item => `${item.id}. ${item.name} - ${item.description}`).join('<br>')}
+    `;
+  }
+
+  // Initial render
+  renderItems();
+
+  // Listen for page changes
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.attributeName === 'page') {
+        renderItems();
+      }
+    });
+  });
+  observer.observe(pagination, { attributes: true });
+
+  // Handle link clicks (in a real app, you'd use proper routing)
+  document.addEventListener('click', (e) => {
+    if (e.target.closest('#table-pagination a')) {
+      e.preventDefault();
+      const href = e.target.closest('a').getAttribute('href');
+      const pageMatch = href.match(/(\d+)/);
+      if (pageMatch) {
+        pagination.page = parseInt(pageMatch[1]);
+      }
+    }
+  });
+</script>
+```
+
+### Single Page
+
+When the total number of items fits within a single page, only page 1 is shown with disabled Previous and Next buttons.
+
+```html:preview
+<zn-pagination total="8" limit="10" page="1" uri="#page#"></zn-pagination>
+```
+
+### Empty State
+
+When there are no items (total is 0), the pagination shows page 0 with disabled buttons.
+
+```html:preview
+<zn-pagination total="0" limit="10" page="1" uri="#page#"></zn-pagination>
+```
+
+## Properties
+
+The pagination component exposes the following attributes and properties:
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `limit` | `limit` | `number` | `10` | Number of items to display per page. This determines how many pages are calculated from the total. |
+| `total` | `total` | `number` | `0` | Total number of items across all pages. Used to calculate the total number of pages. |
+| `page` | `page` | `number` | `1` | Current active page number. The page button matching this number will be highlighted. |
+| `uri` | `uri` | `string` | `""` | URI pattern for page links. Use `#page#` as a placeholder that will be replaced with the actual page number. |
+
+## Behavior
+
+### Page Button Display Logic
+
+The pagination component uses intelligent logic to display page buttons:
+
+- If there are 5 or fewer total pages, all page numbers are shown
+- If there are more than 5 pages, a window of up to 5 page buttons is displayed
+- When on page 1, buttons 1-5 are shown (or up to the last page if fewer than 5)
+- When on the last page, the last 5 pages are shown (or from page 1 if fewer than 5 pages after adjustment)
+- When on middle pages, the current page is centered with 2 pages on each side when possible
+- The active page button is highlighted and not clickable
+- Previous button is disabled on page 1
+- Next button is disabled on the last page
+
+### Link Generation
+
+The component generates links using the `uri` pattern:
+
+- The `#page#` placeholder is replaced with the actual page number
+- If `uri` is empty, no links are generated
+- The active page button does not generate a link
+- Previous and Next buttons generate links for page-1 and page+1 respectively
+
+### Accessibility
+
+- Active page is indicated with visual styling (primary color, bold weight)
+- Disabled buttons show reduced opacity and have cursor: not-allowed
+- All buttons are keyboard accessible via standard tab navigation
+- Links use semantic HTML `<a>` elements for proper navigation
+
+## Styling
+
+The pagination component supports customization through CSS variables and theme tokens:
+
+- Background color uses `--zn-panel` and `--zn-panel-opacity`
+- Text color uses `--zn-text`
+- Shadow effect uses `--zn-shadow`
+- Active state uses `--zn-primary`
+- Border radius uses `--zn-spacing-small`
+- Padding and spacing use standard Zinc spacing tokens
+
+### CSS Parts
+
+While the component does not currently expose CSS parts, you can style it using standard CSS selectors on the host element.
+
+## Best Practices
+
+### When to Use Pagination
+
+- Use pagination for large datasets that would be overwhelming to display all at once
+- Ideal for tables, search results, product listings, and content feeds
+- Consider pagination when you have more than 25-50 items to display
+
+### Choosing Page Size
+
+- Common page sizes are 10, 20, 25, 50, or 100 items
+- Smaller page sizes (10-25) work well for detailed content like product cards
+- Larger page sizes (50-100) work well for compact lists or tables
+- Consider your users' needs and the type of content being displayed
+
+### URI Patterns
+
+- Use clear, RESTful URL patterns like `/items?page=#page#`
+- Ensure page URLs are shareable and bookmarkable
+- Consider including other query parameters in your URI pattern
+- For SPAs, you might use hash-based routing like `#/page/#page#`
+
+### Accessibility Considerations
 
-TODO
+- Always provide a way to navigate to the first and last pages
+- Ensure keyboard navigation works properly
+- Consider adding ARIA labels for screen readers
+- Test with keyboard-only navigation
 
-### Second Example
+### Performance Tips
 
-TODO
+- Load only the data for the current page from your backend
+- Use URL parameters to maintain page state across refreshes
+- Consider implementing infinite scroll as an alternative for certain use cases
+- Cache page data when appropriate to improve navigation speed
 
 

package/docs/pages/components/pane.md

@@ -1,22 +1,238 @@
 ---
 meta:
   title: Pane
-  description:
+  description: A flexible container component for organizing content with optional headers and automatic overflow handling.
 layout: component
 ---
 
+Panes are versatile container components designed to manage content layout with automatic scrolling, flexible display, and seamless integration with headers. They serve as the primary building blocks for organizing page content in a structured, scrollable format.
+
 ```html:preview
-<zn-pane></zn-pane>
+<div style="height: 400px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane>
+    <zn-header caption="Example Pane" description="A basic pane with header"></zn-header>
+    <p>This is the main content area of the pane. It will automatically scroll when the content exceeds the available space.</p>
+    <p>The pane component provides a flexible container with built-in overflow handling and padding.</p>
+    <p>You can add any content here, and it will be properly contained within the pane.</p>
+  </zn-pane>
+</div>
 ```
 
 ## Examples
 
-### First Example
+### Basic Pane
+
+A simple pane with default padding displays content in a flexible, scrollable container. The pane automatically manages overflow and applies standard spacing around the content.
+
+```html:preview
+<div style="height: 300px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane>
+    <p>This is a basic pane with default padding.</p>
+    <p>Content is automatically wrapped with the standard spacing.</p>
+    <p>The pane will scroll if content exceeds the available height.</p>
+  </zn-pane>
+</div>
+```
+
+### Pane with Header
+
+When a `zn-header` is included as a child element, the pane automatically integrates it as a sticky header at the top. The header remains visible while scrolling through the content.
+
+```html:preview
+<div style="height: 400px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane>
+    <zn-header caption="Customer Details"
+               description="View and manage customer information"
+               icon="person">
+      <zn-button slot="actions" primary>Save</zn-button>
+      <zn-button slot="actions">Cancel</zn-button>
+    </zn-header>
+
+    <h3>Customer Information</h3>
+    <p>Name: John Smith</p>
+    <p>Email: john.smith@example.com</p>
+    <p>Phone: (555) 123-4567</p>
+
+    <h3>Address</h3>
+    <p>123 Main Street</p>
+    <p>Anytown, ST 12345</p>
+
+    <h3>Order History</h3>
+    <p>Total Orders: 15</p>
+    <p>Last Order: 2025-01-15</p>
+  </zn-pane>
+</div>
+```
+
+### Flush Pane
+
+Use the `flush` attribute to remove all padding from the content area. This is useful when working with components that need to extend to the edges of the pane, such as tables, tabs, or other full-width layouts.
+
+```html:preview
+<div style="height: 400px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane flush>
+    <zn-header caption="Flush Content"></zn-header>
+    <zn-tabs flush>
+      <zn-navbar slot="top">
+        <li tab>Overview</li>
+        <li tab="details">Details</li>
+        <li tab="settings">Settings</li>
+      </zn-navbar>
+
+      <zn-sp id="" divide no-gap>
+        <div style="padding: var(--zn-spacing-medium);">
+          <h3>Overview Tab</h3>
+          <p>This content extends to the edges of the pane.</p>
+        </div>
+        <div style="padding: var(--zn-spacing-medium);">
+          <p>No extra padding around the tabs component.</p>
+        </div>
+      </zn-sp>
 
-TODO
+      <zn-sp id="details" divide no-gap>
+        <div style="padding: var(--zn-spacing-medium);">
+          <h3>Details Tab</h3>
+          <p>Details content goes here.</p>
+        </div>
+      </zn-sp>
+
+      <zn-sp id="settings" divide no-gap>
+        <div style="padding: var(--zn-spacing-medium);">
+          <h3>Settings Tab</h3>
+          <p>Settings content goes here.</p>
+        </div>
+      </zn-sp>
+    </zn-tabs>
+  </zn-pane>
+</div>
+```
+
+### Scrollable Content
+
+Panes automatically handle overflow with scrollbars when content exceeds the available height. The header remains sticky while content scrolls beneath it.
+
+```html:preview
+<div style="height: 300px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane>
+    <zn-header caption="Long Content" description="Scroll to see more"></zn-header>
+    <h3>Section 1</h3>
+    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
 
-### Second Example
+    <h3>Section 2</h3>
+    <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
 
-TODO
+    <h3>Section 3</h3>
+    <p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</p>
+
+    <h3>Section 4</h3>
+    <p>Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
+
+    <h3>Section 5</h3>
+    <p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.</p>
+
+    <h3>Section 6</h3>
+    <p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum.</p>
+  </zn-pane>
+</div>
+```
+
+### Nested Panes
+
+Panes can be nested within layouts or other container components to create complex, multi-section interfaces with independent scrolling regions.
+
+```html:preview
+<div style="height: 400px; display: flex; gap: 10px;">
+  <div style="flex: 1; border: 1px solid var(--zn-color-neutral-300);">
+    <zn-pane>
+      <zn-header caption="Left Pane" icon="list"></zn-header>
+      <h4>Navigation</h4>
+      <ul>
+        <li>Dashboard</li>
+        <li>Customers</li>
+        <li>Orders</li>
+        <li>Products</li>
+        <li>Reports</li>
+        <li>Settings</li>
+      </ul>
+    </zn-pane>
+  </div>
+
+  <div style="flex: 2; border: 1px solid var(--zn-color-neutral-300);">
+    <zn-pane>
+      <zn-header caption="Main Content" icon="article">
+        <zn-button slot="actions" primary>Action</zn-button>
+      </zn-header>
+      <h3>Content Area</h3>
+      <p>This is the main content area with independent scrolling.</p>
+      <p>Each pane manages its own overflow and scrolling behavior.</p>
+      <p>You can have multiple panes side by side or stacked vertically.</p>
+    </zn-pane>
+  </div>
+</div>
+```
+
+### Flush Pane with Data Table
+
+A common pattern is using a flush pane with data tables or other components that manage their own spacing and borders.
+
+```html:preview
+<div style="height: 400px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane flush>
+    <zn-header caption="Customer List" description="All active customers">
+      <zn-button slot="actions" primary icon="add">Add Customer</zn-button>
+    </zn-header>
+    <zn-sp divide no-gap flush>
+      <div style="padding: var(--zn-spacing-medium);">
+        <strong>Customer 1</strong> - john@example.com
+      </div>
+      <div style="padding: var(--zn-spacing-medium);">
+        <strong>Customer 2</strong> - jane@example.com
+      </div>
+      <div style="padding: var(--zn-spacing-medium);">
+        <strong>Customer 3</strong> - bob@example.com
+      </div>
+      <div style="padding: var(--zn-spacing-medium);">
+        <strong>Customer 4</strong> - alice@example.com
+      </div>
+      <div style="padding: var(--zn-spacing-medium);">
+        <strong>Customer 5</strong> - charlie@example.com
+      </div>
+    </zn-sp>
+  </zn-pane>
+</div>
+```
+
+### Full Height Layout
+
+Panes are designed to work within full-height layouts, automatically expanding to fill the available space and managing overflow appropriately.
+
+```html:preview
+<div style="height: 500px; border: 1px solid var(--zn-color-neutral-300);">
+  <zn-pane>
+    <zn-header caption="Dashboard"
+               description="System overview and metrics"
+               icon="dashboard">
+      <zn-button slot="actions" icon="refresh">Refresh</zn-button>
+    </zn-header>
+
+    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: var(--zn-spacing-medium);">
+      <zn-stat caption="Total Users" value="1,234"></zn-stat>
+      <zn-stat caption="Active Sessions" value="567"></zn-stat>
+      <zn-stat caption="Revenue" value="$12,345"></zn-stat>
+    </div>
+
+    <h3>Recent Activity</h3>
+    <p>New user registration: john.doe@example.com</p>
+    <p>Order placed: #12345</p>
+    <p>Payment received: $99.99</p>
+    <p>Support ticket opened: #456</p>
+
+    <h3>System Status</h3>
+    <p>All systems operational</p>
+    <p>Last backup: 2025-01-23 02:00 AM</p>
+    <p>Uptime: 99.9%</p>
+  </zn-pane>
+</div>
+```