@kubex/zinc 1.0.113 → 1.0.115

package/docs/eleventy.config.cjs

@@ -93,12 +93,14 @@ module.exports = function (eleventyConfig)
   //
   eleventyConfig.addFilter('markdown', content =>
   {
-    return zincFlavoredMarkdown.render(content);
+    // CEM members (events, slots, CSS props/parts, animations) may have no description, in which case
+    // `content` is undefined. markdown-it calls .replace on its input and would throw, so coerce to ''.
+    return typeof content === 'string' ? zincFlavoredMarkdown.render(content) : '';
   });
 
   eleventyConfig.addFilter('markdownInline', content =>
   {
-    return zincFlavoredMarkdown.renderInline(content);
+    return typeof content === 'string' ? zincFlavoredMarkdown.renderInline(content) : '';
   });
 
   // Trims whitespace and pipes from the start and end of a string. Useful for CEM types, which can be pipe-delimited.

package/docs/pages/components/header.md

@@ -20,8 +20,21 @@ layout: component
 </div>
 ```
 
+The breadcrumb slot renders inline with the page title — each slotted link is followed by a `>` separator and the `caption` becomes the final, unlinked item in the trail. Set `hide-breadcrumb` to suppress the trail and show only the title.
+
 ## Examples
 
+### Hide breadcrumb
+
+```html:preview
+<div style="background-color: #f5f5f5; padding: 20px;">
+  <zn-header caption="John Jones" hide-breadcrumb>
+    <a href="#" slot="breadcrumb">Dashboard</a>
+    <a href="#" slot="breadcrumb">Another</a>
+  </zn-header>
+</div>
+```
+
 ### Simple Header
 
 ```html:preview

package/docs/pages/components/inline-edit.md

@@ -151,6 +151,26 @@ Add the `search` attribute to enable filtering on select inputs. Users can type
 </div>
 ```
 
+### Free Text Select
+
+Add the `free-text` attribute to let users enter values that aren't in the options list (see [`zn-select`](/components/select#free-text-entry)). `free-text` implies a select input, so you don't need `input-type="select"`. Combine it with `multiple` for a tag-style editor.
+
+```html:preview
+<div class="form-spacing">
+  <zn-inline-edit name="status" value="active" free-text>
+    <zn-option value="active">Active</zn-option>
+    <zn-option value="inactive">Inactive</zn-option>
+    <zn-option value="pending">Pending</zn-option>
+  </zn-inline-edit>
+
+  <zn-inline-edit name="tags" free-text multiple value="urgent backend">
+    <zn-option value="urgent">Urgent</zn-option>
+    <zn-option value="backend">Backend</zn-option>
+    <zn-option value="frontend">Frontend</zn-option>
+  </zn-inline-edit>
+</div>
+```
+
 ### Data Select with Provider
 
 Use the `provider` attribute to integrate with data select providers like countries, currencies, or colors.

package/docs/pages/components/item.md

@@ -37,6 +37,18 @@ layout: component
 </zn-item>
 ```
 
+### Right Aligned Content
+
+Use `align-end` to right align the content value.
+
+```html:preview
+<zn-sp divide no-gap>
+  <zn-item caption="Subtotal" align-end>$120.00</zn-item>
+  <zn-item caption="Tax" align-end>$24.00</zn-item>
+  <zn-item caption="Total" align-end>$144.00</zn-item>
+</zn-sp>
+```
+
 ### Icons
 
 ```html:preview
@@ -93,4 +105,3 @@ Example of multiple actions in a description item.
   
 </zn-item>
 ```
-

package/docs/pages/components/page.md

@@ -0,0 +1,149 @@
+---
+meta:
+  title: Page
+  description: Pages combine a header with tabbed content.
+layout: component
+---
+
+```html:preview
+<zn-page caption="Page Title" summary="Page Summary">
+  <zn-button slot="actions" type="primary" size="small" href="/ui">UI Examples</zn-button>
+
+  <zn-tab caption="Overview">
+    Overview Content
+  </zn-tab>
+
+  <zn-tab caption="Tab One">
+    Tab One Content
+  </zn-tab>
+
+  <zn-tab caption="Tab Two" id="tab-2">
+    Tab Two Content
+  </zn-tab>
+
+  <zn-tab caption="Dynamic Tab" uri="/tab-three"></zn-tab>
+</zn-page>
+```
+
+## Examples
+
+### Header Actions
+
+Use `slot="actions"` to place controls in the page header action area.
+
+```html:preview
+<zn-page caption="Customers" summary="Manage active customers">
+  <zn-button slot="actions" color="secondary" size="small">Export</zn-button>
+  <zn-button slot="actions" color="primary" size="small">New Customer</zn-button>
+
+  <zn-tab caption="Overview">
+    Customer overview content
+  </zn-tab>
+
+  <zn-tab caption="Active">
+    Active customer content
+  </zn-tab>
+
+  <zn-tab caption="Archived">
+    Archived customer content
+  </zn-tab>
+</zn-page>
+```
+
+### Header Metadata
+
+`zn-page` supports the same header metadata attributes as `zn-header`: `full-location`, `entity-id`, `entity-id-show`, `previous-path`, and `previous-target`.
+
+```html:preview
+<zn-page
+  caption="Customer Comms"
+  summary="This is a description about the purpose of this page."
+  full-location="/customers/comms"
+  entity-id="customer-comms"
+  previous-path="/customers">
+  <zn-tab caption="Overview">
+    Overview content
+  </zn-tab>
+</zn-page>
+```
+
+### Breadcrumbs
+
+Breadcrumb links can be passed with `slot="breadcrumb"` and will be forwarded to the underlying header.
+
+```html:preview
+<zn-page caption="Account Settings" summary="Configure account preferences">
+  <a href="#" slot="breadcrumb">Accounts</a>
+  <a href="#" slot="breadcrumb">Acme Inc</a>
+
+  <zn-tab caption="Profile">
+    Profile content
+  </zn-tab>
+
+  <zn-tab caption="Security">
+    Security content
+  </zn-tab>
+</zn-page>
+```
+
+### Overview Content
+
+Use a normal `zn-tab` for overview content. An Overview tab without an explicit `id` uses the default empty tab id. `zn-page` leaves tab elements in the page light DOM and projects them into internal tab panels, so scoped styles from the original DOM context continue to apply.
+Tabs render in the order they appear in the page by default. Tabs with an empty id are shown first. Set `priority` on `zn-tab` to order the remaining tabs without changing their DOM position.
+
+```html:preview
+<zn-page caption="Project" summary="Current project status">
+  <zn-tab caption="Overview">
+    <zn-note open>
+      This summary appears in the Overview tab.
+    </zn-note>
+  </zn-tab>
+
+  <zn-tab caption="Activity">
+    Activity content
+  </zn-tab>
+
+  <zn-tab caption="Files">
+    Files content
+  </zn-tab>
+</zn-page>
+```
+
+### Tab Priority
+
+Use `priority` to control tab order. Lower numbers appear first after the empty-id overview tab.
+
+```html:preview
+<zn-page caption="Ordered Page" summary="Priority controls the navigation order">
+  <zn-tab caption="Later">
+    Later content
+  </zn-tab>
+
+  <zn-tab caption="Second" priority="20">
+    Second content
+  </zn-tab>
+
+  <zn-tab caption="Overview">
+    Overview content
+  </zn-tab>
+
+  <zn-tab caption="First" priority="10">
+    First content
+  </zn-tab>
+</zn-page>
+```
+
+### Dynamic Tabs
+
+Set `uri` on `zn-tab` to create a dynamic tab. The generated navigation item receives `tab-uri`.
+
+```html:preview
+<zn-page caption="Reports" summary="Load reports on demand">
+  <zn-tab caption="Overview">
+    Report overview content
+  </zn-tab>
+
+  <zn-tab caption="Revenue" uri="/reports/revenue"></zn-tab>
+  <zn-tab caption="Usage" uri="/reports/usage"></zn-tab>
+</zn-page>
+```

package/docs/pages/components/progress-bar.md

@@ -25,6 +25,22 @@ A basic progress bar displays the completion percentage using the `value` attrib
 <zn-progress-bar value="100"></zn-progress-bar>
 ```
 
+### Color Options
+
+Use the `color` attribute to set the progress fill color. Supported options are `current`, `info`, `danger`, `success`, and `warning`.
+
+```html:preview
+<zn-progress-bar color="current" value="40"></zn-progress-bar>
+<br />
+<zn-progress-bar color="info" value="50"></zn-progress-bar>
+<br />
+<zn-progress-bar color="danger" value="60"></zn-progress-bar>
+<br />
+<zn-progress-bar color="success" value="70"></zn-progress-bar>
+<br />
+<zn-progress-bar color="warning" value="80"></zn-progress-bar>
+```
+
 ### With Caption
 
 Use the `caption` attribute to add a label above the progress bar. This helps identify what the progress bar represents.

package/docs/pages/components/select.md

@@ -185,6 +185,31 @@ Combine `search` with `multiple` to allow users to search and select multiple op
 </zn-select>
 ```
 
+### Free Text Entry
+
+Use the `free-text` attribute to let users enter values that aren't in the options list. `free-text` implies the editable, filtering input behavior of `search`, so users can both filter existing options and add their own. When the typed text doesn't match an existing option, an **Add "…"** row appears at the top of the listbox; committing it (by pressing <kbd>Enter</kbd>, clicking the Add row, or blurring the field) adds the value as a selection. A committed value becomes both the option's value and its label.
+
+If the typed text exactly matches an existing option (by label or value, case-insensitive), the Add row is suppressed and the existing option is selected instead — so no duplicates are created.
+
+```html:preview
+<zn-select label="Add tags" free-text placeholder="Type a tag and press Enter">
+  <zn-option value="bug">Bug</zn-option>
+  <zn-option value="feature">Feature</zn-option>
+  <zn-option value="chore">Chore</zn-option>
+</zn-select>
+```
+
+### Free Text with Multiple Selection
+
+Combine `free-text` with `multiple` to build a tag-style input. Each committed value is added as a tag and the input stays open so users can keep entering values. Removing a tag whose value was entered as free text deletes it entirely.
+
+```html:preview
+<zn-select label="Recipients" free-text multiple clearable placeholder="Add email addresses...">
+  <zn-option value="support@example.com">support@example.com</zn-option>
+  <zn-option value="sales@example.com">sales@example.com</zn-option>
+</zn-select>
+```
+
 ### Remote Search
 
 When `search` and `data-uri` are used together, typing in the select sends debounced requests to the server instead of filtering locally. The search term is appended as a query parameter (default `q`). Use `search-param` to customise the parameter name, `search-debounce` to control the delay, and `max-results` to cap displayed results.

package/docs/pages/components/split-pane.md

@@ -67,15 +67,15 @@ Use the `pixels` attribute to switch from percentage-based sizing to pixel-based
 
 ### Min and Max Size
 
-Use `min-size` and `max-size` to constrain how much users can resize the primary pane. These values match the unit type (percentage or pixels).
+Use `min-size` and `max-size` to constrain how much users can resize the primary pane. Use `min-secondary-size` to keep the secondary pane above a minimum size. These values match the unit type (percentage or pixels).
 
 ```html:preview
-<zn-split-pane min-size="20" max-size="80" style="height: 300px;">
+<zn-split-pane min-size="20" max-size="80" min-secondary-size="30" style="height: 300px;">
   <div slot="primary" style="padding: 20px; background: #f5f5f5;">
-    <p>Primary pane can be resized between 20% and 80%</p>
+    <p>Primary pane can be resized between 20% and 70%</p>
   </div>
   <div slot="secondary" style="padding: 20px;">
-    <p>Secondary pane adjusts accordingly</p>
+    <p>Secondary pane stays at least 30%</p>
   </div>
 </zn-split-pane>
 ```
@@ -83,12 +83,12 @@ Use `min-size` and `max-size` to constrain how much users can resize the primary
 With pixel sizing:
 
 ```html:preview
-<zn-split-pane pixels min-size="150" max-size="400" initial-size="250" style="height: 300px;">
+<zn-split-pane pixels min-size="150" max-size="400" min-secondary-size="200" initial-size="250" style="height: 300px;">
   <div slot="primary" style="padding: 20px; background: #f5f5f5;">
     <p>Primary pane can be resized between 150px and 400px</p>
   </div>
   <div slot="secondary" style="padding: 20px;">
-    <p>Secondary pane fills remaining space</p>
+    <p>Secondary pane stays at least 200px wide</p>
   </div>
 </zn-split-pane>
 ```
@@ -458,4 +458,3 @@ The split pane exposes CSS variables for advanced customization.
   </div>
 </zn-split-pane>
 ```
-

package/docs/pages/components/tabs.md

@@ -28,7 +28,9 @@ layout: component
 
 ### Basic Tabs
 
-The tabs component works by connecting tab navigation elements (typically in a `zn-navbar` in the `top` slot) with content panels. Each panel is identified by an `id` attribute, and navigation items use a `tab` attribute to reference those IDs.
+The tabs component works by connecting tab navigation elements (typically in a `zn-navbar` in the `top` slot) with
+content panels. Each panel is identified by an `id` attribute, and navigation items use a `tab` attribute to reference
+those IDs.
 
 ```html:preview
 <zn-tabs flush>
@@ -52,6 +54,46 @@ The tabs component works by connecting tab navigation elements (typically in a `
 </zn-tabs>
 ```
 
+### Overflow
+
+When there are more tabs than can fit in the available space, the component will automatically show an overflow menu.
+This allows users to access all tabs even on smaller screens.
+
+```html:preview
+<zn-tabs flush>
+  <zn-navbar slot="top">
+    <li tab="">Tab 1</li>
+    <li tab="tab2">Lorem IPsum dolor sit amet. Lorem Ipsum Dolor sit Amet</li>
+    <li tab="tab3">Tab 3</li>
+    <li tab="tab4">Tab 4</li>
+    <li tab="tab5">This is Tab 5</li>
+    <li tab="tab6">This is Tab 6</li>
+    <li tab="tab7">This is Tab 7</li>
+  </zn-navbar>
+  <zn-sp id="">
+    <p>Content for Tab 1.</p>
+  </zn-sp>
+  <zn-sp id="tab2">
+    <p>Content for Tab 2.</p>
+  </zn-sp>
+  <zn-sp id="tab3">
+    <p>Content for Tab 3.</p>
+  </zn-sp>
+  <zn-sp id="tab4">
+    <p>Content for Tab 4.</p>
+  </zn-sp>
+  <zn-sp id="tab5">
+    <p>Content for Tab 5.</p>
+  </zn-sp>
+  <zn-sp id="tab6">
+    <p>Content for Tab 6.</p>
+  </zn-sp>
+  <zn-sp id="tab7">
+    <p>Content for Tab 7.</p>
+  </zn-sp>
+</zn-tabs>
+```
+
 ### With Caption and Description
 
 Use the `caption` and `description` attributes to add a header to your tabs component.
@@ -103,7 +145,8 @@ Remove the `caption` attribute for a cleaner layout when a header is not needed.
 
 ### Dynamic Tabs with URI Loading
 
-Use the `tab-uri` attribute to load content dynamically from a URL when a tab is clicked. The component will automatically fetch and display the content.
+Use the `tab-uri` attribute to load content dynamically from a URL when a tab is clicked. The component will
+automatically fetch and display the content.
 
 ```html:preview
 <zn-tabs flush no-prefetch>
@@ -117,7 +160,8 @@ Use the `tab-uri` attribute to load content dynamically from a URL when a tab is
 
 ### Prefetching
 
-By default, tabs with `tab-uri` will prefetch content on hover. Use the `no-prefetch` attribute to disable this behavior and only load content when clicked.
+By default, tabs with `tab-uri` will prefetch content on hover. Use the `no-prefetch` attribute to disable this behavior
+and only load content when clicked.
 
 ```html:preview
 <zn-tabs flush no-prefetch>
@@ -156,7 +200,8 @@ Use the `active` attribute to specify which tab should be active by default.
 
 ### Storage Persistence
 
-Use `store-key` to persist the active tab selection across page reloads. By default, uses session storage with a 5-minute TTL. Use `local-storage` for persistent storage beyond the session.
+Use `store-key` to persist the active tab selection across page reloads. By default, uses session storage with a
+5-minute TTL. Use `local-storage` for persistent storage beyond the session.
 
 ```html:preview
 <zn-tabs flush store-key="my-tabs">
@@ -182,7 +227,8 @@ Use `store-key` to persist the active tab selection across page reloads. By defa
 
 ### Local Storage
 
-Use `local-storage` with `store-key` to persist tabs across browser sessions. Control expiration with `store-ttl` (in seconds).
+Use `local-storage` with `store-key` to persist tabs across browser sessions. Control expiration with `store-ttl` (in
+seconds).
 
 ```html:preview
 <zn-tabs flush store-key="persistent-tabs" local-storage store-ttl="86400">
@@ -268,10 +314,12 @@ Use the `full-width` attribute to make tab content expand to fill the available
 
 ### Split Pane Layout
 
-Use the `split` attribute with a pixel value to create a split pane layout with resizable sections. Control minimum and maximum sizes with `split-min` and `split-max`.
+Use the `split` attribute with a pixel value to create a split pane layout with resizable sections. Control minimum and
+maximum primary sizes with `split-min` and `split-max`, and keep the secondary pane above a minimum width with
+`split-min-secondary`.
 
 ```html:preview
-<zn-tabs split="300" split-min="200" split-max="600">
+<zn-tabs split="300" split-min="200" split-max="600" split-min-secondary="320">
   <zn-navbar slot="left">
     <li tab="">Navigation</li>
     <li tab="menu2">Menu 2</li>
@@ -344,7 +392,8 @@ The tabs component provides multiple slots for flexible layouts.
 
 ### Actions Slot
 
-Use the `actions` slot to add action buttons that appear in the header. Elements can be conditionally shown based on the active tab using `ref-tab`.
+Use the `actions` slot to add action buttons that appear in the header. Elements can be conditionally shown based on the
+active tab using `ref-tab`.
 
 ```html:preview
 <zn-tabs caption="Document Editor">
@@ -418,7 +467,8 @@ Access tab methods programmatically to switch tabs, navigate, or refresh content
 
 ### Tab Refresh
 
-Triple-clicking an active tab or using the refresh parameter will reload dynamic content. Hold Alt while clicking to force a refresh.
+Triple-clicking an active tab or using the refresh parameter will reload dynamic content. Hold Alt while clicking to
+force a refresh.
 
 ```html:preview
 <zn-tabs flush>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.0.113",
+  "version": "1.0.115",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",
@@ -28,6 +28,7 @@
   "unpkg": "dist/zinc.min.js",
   "scripts": {
     "build": "node scripts/build.js",
+    "build:docs": "node scripts/build.js --with-docs",
     "build:vite": "vite build",
     "check-updates": "npx npm-check-updates --interactive --format group",
     "create": "plop --plopfile scripts/plop/plopfile.js",
@@ -37,19 +38,21 @@
     "test": "npx playwright install --with-deps && web-test-runner --group default",
     "test:component": "npx playwright install --with-deps && web-test-runner -- --watch --group",
     "test:watch": "npx playwright install --with-deps && web-test-runner --watch --group default",
-    "watch": "node scripts/build.js --serve"
+    "watch": "node scripts/build.js --serve",
+    "watch:docs": "node scripts/build.js --serve --with-docs"
   },
   "dependencies": {
     "@emoji-mart/data": "^1.2.1",
     "@floating-ui/dom": "^1.6.13",
     "@lit-labs/observers": "^2.0.4",
+    "@lit-labs/signals": "^0.3.0",
     "@lit/task": "^1.0.1",
     "@shoelace-style/localize": "^3.2.1",
     "air-datepicker": "^3.5.3",
     "composed-offset-position": "^0.0.6",
     "echarts": "^6.0.0",
     "emoji-mart": "^5.6.0",
-    "lit": "^2.7.6",
+    "lit": "^3.3.3",
     "marked": "^18.0.2",
     "quill": "^2.0.3"
   },
@@ -115,9 +118,9 @@
     "strip-css-comments": "^5.0.0",
     "tailwindcss": "^3.4.17",
     "tslib": "^2.8.1",
-    "typescript": "^5.3.3",
+    "typescript": "5.8.3",
     "user-agent-data-types": "^0.4.2"
   },
-  "customElements": "./dist/custom-elements.json",
+  "customElements": "dist/custom-elements.json",
   "web-types": "./dist/web-types.json"
 }

package/scripts/build.js

@@ -21,7 +21,10 @@ const postCss = postCSS([
   minify()
 ]);
 
-const {serve} = commandLineArgs([{name: 'serve', type: Boolean}]);
+const {serve, 'with-docs': withDocs} = commandLineArgs([
+  {name: 'serve', type: Boolean},
+  {name: 'with-docs', type: Boolean}
+]);
 const outDir = 'dist';
 const siteDir = '_site';
 const spinner = ora({hideCursor: false}).start();
@@ -256,13 +259,16 @@ if(serve)
 {
   let result;
 
-  // Spin up Eleventy and Wait for the search index to appear before proceeding. The search index is generated during
-  // eleventy.after, so it appears after the docs are fully published. This is kinda hacky, but here we are.
-  // Kick off the Eleventy dev server with --watch and --incremental
-  await nextTask('Building the docs', async () =>
+  if(withDocs)
   {
-    result = await buildTheDocs(true);
-  });
+    // Spin up Eleventy and Wait for the search index to appear before proceeding. The search index is generated during
+    // eleventy.after, so it appears after the docs are fully published. This is kinda hacky, but here we are.
+    // Kick off the Eleventy dev server with --watch and --incremental
+    await nextTask('Building the docs', async () =>
+    {
+      result = await buildTheDocs(true);
+    });
+  }
 
   const bs = browserSync.create();
   const port = await getPort({port: portNumbers(4000, 4999)});
@@ -275,31 +281,43 @@ if(serve)
     notify:         false,
     single:         false,
     ghostMode:      false,
-    server:         {
+    open:           withDocs,
+    ui:             withDocs ? undefined : false,
+    server:         withDocs ? {
       baseDir: siteDir,
       routes:  {
         '/dist': outDir
       }
-    }
+    } : false
   };
 
   // Launch BrowserSync
   bs.init(bsConfig, () =>
   {
-    const url = `http://localhost:${port}`;
-    console.log(chalk.cyan(`\n🚀 Server running at ${url}`));
+    if(withDocs)
+    {
+      const url = `http://localhost:${port}`;
+      console.log(chalk.cyan(`\n🚀 Server running at ${url}`));
+    }
+    else
+    {
+      console.log(chalk.cyan('\n👀 Watching source files (run with --with-docs for the docs server)'));
+    }
 
     // log deferred output
-    if(result.output.length > 0)
+    if(result && result.output.length > 0)
     {
       console.log('\n' + result.output.join('\n'));
     }
 
     // Log output that comes later on
-    result.child.stdout.on('data', data =>
+    if(result)
     {
-      console.log(data.toString());
-    });
+      result.child.stdout.on('data', data =>
+      {
+        console.log(data.toString());
+      });
+    }
   });
 
   // Rebuild and reload then source files change
@@ -351,15 +369,18 @@ if(serve)
   });
 
   // Reload without rebuilding when docs change
-  bs.watch([`${siteDir}/**/*.*`]).on('change', () =>
+  if(withDocs)
   {
-    bs.reload();
-  });
+    bs.watch([`${siteDir}/**/*.*`]).on('change', () =>
+    {
+      bs.reload();
+    });
+  }
 
 }
 
 // Build for production
-if(!serve)
+if(!serve && withDocs)
 {
   let result;
 

package/scss/_global-spacing.scss

@@ -1,5 +1,9 @@
 @use "mixins";
 
+.zn-gutter {
+  margin: 0 var(--zn-gutter);
+}
+
 .zn-gap {
   @include mixins.gap();
   @include mixins.padding();
@@ -62,9 +66,16 @@
 }
 
 .form-spacing ~ .form-spacing {
-  margin-top: var(--zn-spacing-medium);
+  margin-top: var(--zn-base-gap);
 }
 
+zn-form-group ~ zn-form-group {
+  margin-top: var(--zn-base-gap);
+  padding-top: var(--zn-base-gap);
+  border-top: 1px solid rgb(var(--zn-border-color));
+}
+
+
 .form-spacing > * {
   grid-column: span 6 / span 6;
 }