@kubex/zinc 1.1.185 → 2.0.0

package/docs/pages/components/page.md

@@ -6,159 +6,327 @@ layout: component
 ---
 
 ```html:preview
-<zn-page caption="Page Title" summary="Page Summary">
-  <zn-button slot="actions" type="primary" href="/ui">UI Examples</zn-button>
+<zn-page caption="Margot Foster" summary="Customer since March 2021 · London, UK">
+  <zn-badge slot="caption-badges" type="success" dot>Active</zn-badge>
+  <zn-button slot="actions" color="secondary" icon="mail@lu">Email</zn-button>
+  <zn-button slot="actions" color="primary" icon="plus@lu">New Subscription</zn-button>
 
   <zn-tab caption="Overview">
-    Overview Content
+    <zn-sp>
+      <zn-panel caption="Contact">
+        <zn-sp divide no-gap>
+          <zn-item caption="Email">margot.foster@example.com</zn-item>
+          <zn-item caption="Phone">+44 20 7946 0958</zn-item>
+          <zn-item caption="Plan">Business, billed annually</zn-item>
+        </zn-sp>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 
-  <zn-tab caption="Tab One">
-    Tab One Content
+  <zn-tab caption="Subscriptions">
+    <zn-sp>
+      <zn-empty-state caption="No subscriptions" description="Subscriptions for this customer appear here." icon="repeat@lu"></zn-empty-state>
+    </zn-sp>
   </zn-tab>
 
-  <zn-tab caption="Tab Two" id="tab-2">
-    Tab Two Content
+  <zn-tab caption="Notes">
+    <zn-sp>
+      <zn-empty-state caption="No notes" description="Notes left by your team appear here." icon="sticky-note@lu"></zn-empty-state>
+    </zn-sp>
   </zn-tab>
-
-  <zn-tab caption="Dynamic Tab" uri="/tab-three"></zn-tab>
 </zn-page>
 ```
 
 ## Examples
 
-### Header Actions
+### Header
 
-Use `slot="actions"` to place controls in the page header action area.
+Set `caption` and `summary` for the page title and its description, or use the `caption` and `description` slots for rich content. Put status badges in the `caption-badges` slot and controls in the `actions` slot.
 
 ```html:preview
-<zn-page caption="Customers" summary="Manage active customers">
-  <zn-button slot="actions" color="secondary">Export</zn-button>
-  <zn-button slot="actions" color="primary">New Customer</zn-button>
-
-  <zn-tab caption="Overview">
-    Customer overview content
+<zn-page caption="INV-2024-0042" summary="Issued 4 March 2024 · Due in 14 days">
+  <zn-badge slot="caption-badges" type="warning">Past due</zn-badge>
+  <zn-button slot="actions" color="secondary" icon="download@lu">Download</zn-button>
+  <zn-button slot="actions" color="primary">Record Payment</zn-button>
+
+  <zn-tab caption="Details">
+    <zn-sp>
+      <zn-cols>
+        <zn-panel>
+          <zn-stat caption="Amount due" amount="1250" currency="£"></zn-stat>
+        </zn-panel>
+        <zn-panel>
+          <zn-stat caption="Paid" amount="0" currency="£"></zn-stat>
+        </zn-panel>
+      </zn-cols>
+    </zn-sp>
   </zn-tab>
+</zn-page>
+```
 
-  <zn-tab caption="Active">
-    Active customer content
-  </zn-tab>
+### Breadcrumbs
 
-  <zn-tab caption="Archived">
-    Archived customer content
+Links in the `breadcrumb` slot show above the caption, separated by an icon. Breadcrumbs are hidden in `nested` and `modal` pages.
+
+```html:preview
+<zn-page caption="Security" summary="Sign-in and access settings for Acme Inc">
+  <a href="#" slot="breadcrumb">Settings</a>
+  <a href="#" slot="breadcrumb">Acme Inc</a>
+
+  <zn-tab caption="Overview">
+    <zn-sp>
+      <zn-panel caption="Sign-in">
+        <zn-sp divide no-gap>
+          <zn-item caption="Two-factor authentication">Required for all members</zn-item>
+          <zn-item caption="Session timeout">12 hours</zn-item>
+        </zn-sp>
+      </zn-panel>
+    </zn-sp>
   </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`.
+`previous-path` adds a back button, and `previous-target` sets where it opens. `entity-id` and `full-location` add copy buttons, shown while Alt is held. Hold Alt over this example to see them.
 
 ```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">
+  caption="Margot Foster"
+  summary="Customer"
+  previous-path="/customers"
+  entity-id="cus_8F2kD91xQ"
+  full-location="/customers/cus_8F2kD91xQ">
   <zn-tab caption="Overview">
-    Overview content
+    <zn-sp>
+      <zn-panel caption="Contact">
+        <zn-item caption="Email">margot.foster@example.com</zn-item>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 </zn-page>
 ```
 
-### Breadcrumbs
+### Tabs
 
-Breadcrumb links can be passed with `slot="breadcrumb"` and will be forwarded to the underlying header.
+Each `zn-tab` becomes a tab. A tab gets its `id` from its caption, and a tab captioned Overview gets the empty id, which always shows first. Other tabs keep their source order unless `priority` is set: higher numbers come first. Add `selected` to open a tab other than the first.
+
+Tabs stay in the page's light DOM, so styles scoped to where they are written still apply.
 
 ```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-page caption="Acme Inc" summary="Workspace">
+  <zn-tab caption="Billing" priority="10">
+    <zn-sp>
+      <zn-panel caption="Billing">
+        <zn-item caption="Payment method">Visa ending 4242</zn-item>
+      </zn-panel>
+    </zn-sp>
+  </zn-tab>
 
-  <zn-tab caption="Profile">
-    Profile content
+  <zn-tab caption="Members" priority="20" selected>
+    <zn-sp>
+      <zn-panel caption="Members">
+        <zn-sp divide no-gap>
+          <zn-item caption="Margot Foster">Owner</zn-item>
+          <zn-item caption="Sam Patel">Admin</zn-item>
+        </zn-sp>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 
-  <zn-tab caption="Security">
-    Security content
+  <zn-tab caption="Overview">
+    <zn-sp>
+      <zn-panel caption="Workspace">
+        <zn-item caption="Region">Europe (London)</zn-item>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 </zn-page>
 ```
 
-### Overview Content
+### Tab Icons
 
-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.
+Set `icon` on a `zn-tab` to show an icon before its caption.
 
 ```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-page caption="Margot Foster" summary="Customer">
+  <zn-tab caption="Overview" icon="layout-grid@lu">
+    <zn-sp>
+      <zn-panel caption="Contact">
+        <zn-item caption="Email">margot.foster@example.com</zn-item>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 
-  <zn-tab caption="Activity">
-    Activity content
+  <zn-tab caption="History" icon="history@lu">
+    <zn-sp>
+      <zn-empty-state caption="No history yet" icon="history@lu"></zn-empty-state>
+    </zn-sp>
   </zn-tab>
+</zn-page>
+```
+
+### Dynamic Tabs
 
-  <zn-tab caption="Files">
-    Files content
+Set `uri` on a `zn-tab` to load its content from that address when the tab is first opened.
+
+```html:preview
+<zn-page caption="Reports" summary="Revenue and usage across your workspace">
+  <zn-tab caption="Overview">
+    <zn-sp>
+      <zn-cols>
+        <zn-panel>
+          <zn-stat caption="Revenue" description="This month" amount="48250" previous="42100" currency="£" show-delta></zn-stat>
+        </zn-panel>
+        <zn-panel>
+          <zn-stat caption="Active customers" amount="1284" previous="1210" show-delta></zn-stat>
+        </zn-panel>
+      </zn-cols>
+    </zn-sp>
   </zn-tab>
+
+  <zn-tab caption="Revenue" uri="/reports/revenue"></zn-tab>
+  <zn-tab caption="Usage" uri="/reports/usage"></zn-tab>
 </zn-page>
 ```
 
-### Tab Priority
+### Nested Tabs
 
-Use `priority` to control tab order. Lower numbers appear first after the empty-id overview tab.
+Put `zn-tab` elements inside a `zn-tab` to give that tab its own set of tabs. They show as a grey pill track below the main tab bar, so they read as secondary.
 
 ```html:preview
-<zn-page caption="Ordered Page" summary="Priority controls the navigation order">
-  <zn-tab caption="Later">
-    Later content
+<zn-page caption="Margot Foster" summary="Customer">
+  <zn-tab caption="Billing">
+    <zn-tab caption="Invoices">
+      <zn-sp>
+        <zn-panel caption="Invoices">
+          <zn-sp divide no-gap>
+            <zn-item caption="INV-2024-0042">£1,250.00 · Past due</zn-item>
+            <zn-item caption="INV-2024-0031">£1,250.00 · Paid</zn-item>
+          </zn-sp>
+        </zn-panel>
+      </zn-sp>
+    </zn-tab>
+
+    <zn-tab caption="Payment Methods">
+      <zn-sp>
+        <zn-panel caption="Payment methods">
+          <zn-item caption="Visa ending 4242">Default · Expires 08/27</zn-item>
+        </zn-panel>
+      </zn-sp>
+    </zn-tab>
   </zn-tab>
 
-  <zn-tab caption="Second" priority="20">
-    Second content
+  <zn-tab caption="Notes">
+    <zn-sp>
+      <zn-empty-state caption="No notes" icon="sticky-note@lu"></zn-empty-state>
+    </zn-sp>
   </zn-tab>
+</zn-page>
+```
 
-  <zn-tab caption="Overview">
-    Overview content
+A `zn-page` placed in a tab is a page of its own, with its own header and a normal tab bar.
+
+### Navigation Style
+
+`navigation-style` sets the tab design:
+
+- `tabs` – a tab bar below the header. This is the default.
+- `pills` – a pill track with no page header, for a page that only holds a second set of tabs. Nested tabs use it.
+- `sidebar` – for tabs shown outside the page, such as in an app sidebar. The page hides its tab bar unless the `bottom` slot has content, and still loads tabs and keeps their history as the outside navigation selects them.
+
+```html:preview
+<zn-page caption="Margot Foster" summary="Customer">
+  <zn-tab caption="Billing">
+    <zn-page nested navigation-style="pills">
+      <zn-tab caption="Invoices">
+        <zn-sp>
+          <zn-panel caption="Invoices">
+            <zn-item caption="INV-2024-0042">£1,250.00 · Past due</zn-item>
+          </zn-panel>
+        </zn-sp>
+      </zn-tab>
+      <zn-tab caption="Credit Notes">
+        <zn-sp>
+          <zn-empty-state caption="No credit notes" icon="receipt@lu"></zn-empty-state>
+        </zn-sp>
+      </zn-tab>
+    </zn-page>
   </zn-tab>
 
-  <zn-tab caption="First" priority="10">
-    First content
+  <zn-tab caption="Notes">
+    <zn-sp>
+      <zn-empty-state caption="No notes" icon="sticky-note@lu"></zn-empty-state>
+    </zn-sp>
   </zn-tab>
 </zn-page>
 ```
 
 ### Linking to a Tab
 
-Give any element in the page content a `tab` attribute holding a tab's `id` to open that tab when it is clicked. Links inside a nested `zn-page` or `zn-tabs` open tabs in that nested container.
+Give any element in the page a `tab` attribute holding a tab's `id` to open that tab when it is clicked. Links inside a nested `zn-page` or `zn-tabs` open tabs in that nested container.
 
 ```html:preview
-<zn-page caption="Scorecard">
-  <zn-tab caption="Details" id="details">
-    <zn-button tab="section-general" icon="edit">Edit General section</zn-button>
+<zn-page caption="Margot Foster" summary="Customer">
+  <zn-tab caption="Overview">
+    <zn-sp>
+      <zn-panel caption="Billing">
+        <zn-item caption="Outstanding balance">£1,250.00</zn-item>
+        <zn-button slot="actions" tab="invoices" color="secondary" size="small">View invoices</zn-button>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
-  <zn-tab caption="General" id="section-general">
-    General section settings
+
+  <zn-tab caption="Invoices">
+    <zn-sp>
+      <zn-panel caption="Invoices">
+        <zn-item caption="INV-2024-0042">£1,250.00 · Past due</zn-item>
+      </zn-panel>
+    </zn-sp>
   </zn-tab>
 </zn-page>
 ```
 
-### Dynamic Tabs
+### Footer
 
-Set `uri` on `zn-tab` to create a dynamic tab. The generated navigation item receives `tab-uri`.
+Put actions in the `footer` slot to pin them below the content while it scrolls. Give `zn-form-actions` a `form` attribute so it can submit a form it sits outside of. In a modal page the footer takes the dialog footer's styling.
 
 ```html:preview
-<zn-page caption="Reports" summary="Load reports on demand">
-  <zn-tab caption="Overview">
-    Report overview content
+<zn-page caption="New Customer" summary="Add a customer to Acme Inc" modal style="height: 420px;">
+  <zn-tab caption="Details">
+    <form id="page-footer-form">
+      <zn-sp>
+        <zn-input label="Full name" name="name" required></zn-input>
+        <zn-input label="Email" name="email" type="email" required></zn-input>
+      </zn-sp>
+    </form>
   </zn-tab>
 
-  <zn-tab caption="Revenue" uri="/reports/revenue"></zn-tab>
-  <zn-tab caption="Usage" uri="/reports/usage"></zn-tab>
+  <zn-form-actions slot="footer" form="page-footer-form" with-cancel submit-text="Add customer"
+                   submit-icon="plus@lu"></zn-form-actions>
+</zn-page>
+```
+
+### Full Width
+
+The header, tabs and content are capped at the container width (`--zn-container`) and centred. Add `full-width` to let them span the whole page, such as for wide tables. A `flush` page always spans it.
+
+```html:preview
+<zn-page caption="Transactions" summary="All payments across your workspace" full-width>
+  <zn-tab caption="Overview">
+    <zn-sp>
+      <zn-cols>
+        <zn-panel>
+          <zn-stat caption="Volume" description="Last 30 days" amount="182400" currency="£"></zn-stat>
+        </zn-panel>
+        <zn-panel>
+          <zn-stat caption="Payments" description="Last 30 days" amount="3192"></zn-stat>
+        </zn-panel>
+        <zn-panel>
+          <zn-stat caption="Declined" description="Last 30 days" amount="41"></zn-stat>
+        </zn-panel>
+      </zn-cols>
+    </zn-sp>
+  </zn-tab>
 </zn-page>
 ```

package/docs/pages/components/priority-list.md

@@ -165,6 +165,42 @@ Use the `action-{value}` slot to add interactive elements (buttons, links, etc.)
 </zn-priority-list>
 ```
 
+### Tile Items
+
+Use `zn-tile` items for titled rows: the tile supplies the caption, description, icon square and its own actions, and
+the list adds the handle, priority and ordering. A `locked` item stays where it is and nothing can move past it.
+`move-buttons` adds up and down buttons to each movable item, ahead of any controls in the item's `action-{value}` slot.
+A tile with an `href` stays clickable, underlining its caption on hover.
+
+```html:preview
+<zn-panel flush>
+  <zn-priority-list label="Steps" flush move-buttons>
+    <zn-tile value="offer" caption="Second chance" description="Offer · Default template · Student 20% (20%)" icon="tag@lu" icon-color="success">
+      <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip>
+      <small slot="properties">100% reach it</small>
+    </zn-tile>
+    <zn-button slot="action-offer" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button>
+    <zn-button slot="action-offer" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button>
+    <zn-tile value="message" caption="Before you go" href="#" description="Message · Retention copy" icon="message-square@lu" icon-color="ai">
+      <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip>
+      <small slot="properties">81% reach it</small>
+    </zn-tile>
+    <zn-button slot="action-message" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button>
+    <zn-button slot="action-message" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button>
+    <zn-tile value="survey" caption="Exit survey" description="Survey · Why are you leaving?" icon="circle-check@lu" icon-color="warning">
+      <zn-chip slot="properties" icon="globe@lu" icon-size="12">1/12</zn-chip>
+      <small slot="properties">64% reach it</small>
+    </zn-tile>
+    <zn-button slot="action-survey" icon="pencil@lu" icon-size="16" icon-button="small" plain tooltip="Edit"></zn-button>
+    <zn-button slot="action-survey" icon="trash-2@lu" icon-size="16" icon-button="small" plain tooltip="Delete"></zn-button>
+    <zn-tile value="confirm" caption="Confirmation" description="Separate confirmation step · always the final step"
+             locked>
+      <small slot="properties">58% reach it</small>
+    </zn-tile>
+  </zn-priority-list>
+</zn-panel>
+```
+
 ### Form Submission
 
 When a `name` is set, the component generates hidden inputs for each item as `name[itemValue]=priority`. This example
@@ -225,9 +261,11 @@ priority assignments.
 
 ### Keyboard Navigation
 
-Focus any item and use the keyboard to reorder:
+The list is a single tab stop. Arrow Up, Arrow Down, Home and End move focus between items; hold Alt to reorder:
+
+- **Alt + Arrow Up** — Move the focused item up one position
+- **Alt + Arrow Down** — Move the focused item down one position
+- **Alt + Home** — Move the focused item to the top
+- **Alt + End** — Move the focused item to the bottom
 
-- **Arrow Up** — Move the focused item up one position
-- **Arrow Down** — Move the focused item down one position
-- **Home** — Move the focused item to the top
-- **End** — Move the focused item to the bottom
+Locked items can't be moved, and other items can't move past them.

package/docs/pages/components/query-builder.md

@@ -112,6 +112,26 @@ This example will show the produced query string from the selected parameters.
 <div style="word-wrap: break-word;"><b>Query String:</b> </span><span class="query-string"></span></div>
 ```
 
+### Starting Rules
+
+Use `rules` to start with rules already added, in the same `key`, `comparator`, `value` shape the builder submits.
+Add `repeatable` to let a filter be used more than once, for example to filter a date between two days.
+
+```html:preview
+<zn-query-builder
+  repeatable
+  filters="[
+      {&quot;id&quot;:&quot;email&quot;,&quot;name&quot;:&quot;Email&quot;,&quot;operators&quot;:[&quot;eq&quot;,&quot;starts&quot;]},
+      {&quot;id&quot;:&quot;rating&quot;,&quot;name&quot;:&quot;Rating&quot;,&quot;type&quot;:&quot;number&quot;,&quot;operators&quot;:[&quot;gte&quot;,&quot;lte&quot;]}
+    ]"
+  rules="[
+      {&quot;key&quot;:&quot;email&quot;,&quot;comparator&quot;:&quot;starts&quot;,&quot;value&quot;:&quot;sales@&quot;},
+      {&quot;key&quot;:&quot;rating&quot;,&quot;comparator&quot;:&quot;gte&quot;,&quot;value&quot;:&quot;3&quot;},
+      {&quot;key&quot;:&quot;rating&quot;,&quot;comparator&quot;:&quot;lte&quot;,&quot;value&quot;:&quot;5&quot;}
+    ]">
+</zn-query-builder>
+```
+
 ## Types
 
 | Name      |
@@ -140,6 +160,9 @@ This example will show the produced query string from the selected parameters.
 | `NStarts`         | Does Not Start With          |
 | `Wild`            | Wildcard Match               |
 | `NWild`           | Does Not Match Wildcard      |
+| `DnContain`       | Does Not Contain             |
+| `LikeIn`          | Like Any Of                  |
+| `NLikeIn`         | Not Like Any Of              |
 | `Fuzzy`           | Fuzzy Match With             |
 | `NFuzzy`          | Does Not Match Fuzzy With    |
 | `Gte`             | Greater Than or Equals       |

package/docs/pages/components/radio-group.md

@@ -166,7 +166,8 @@ Contained radios can also render as richer [selection cards](/components/radio#s
 description, and positioned indicator. The radio group continues to manage their single selection, validation,
 keyboard navigation, and submitted form value.
 
-Contained radios are rounded by default; add `square` to the group to square off every radio in it. With
+Contained radios are rounded by default; add `square` to the group to square off every radio in it. Add `centered`
+to centre each radio's text, which suits short answers laid out as a row. With
 `horizontal`, cards in a row are given equal height, and `--zn-radio-group-column-width` (default `152px`) sets the
 minimum column width used by the grid.
 
@@ -175,6 +176,37 @@ Add `wrap` to lay the radios out as a wrapping row instead of an equal-width gri
 its own content.
 :::
 
+### Scale
+
+Add `scale` to lay the radios out as one row of segments, filling every segment up to the checked one. Use it for
+ordered answers such as a 1 to 10 rating. Unlike a range input, the group has no value until one is picked, so
+`required` still catches an unanswered scale. Arrow keys move along the scale.
+
+```html:preview
+<zn-radio-group name="tone" label="How well did the agent manage the customer's tone?" value="7" scale>
+  <zn-radio value="1">1</zn-radio>
+  <zn-radio value="2">2</zn-radio>
+  <zn-radio value="3">3</zn-radio>
+  <zn-radio value="4">4</zn-radio>
+  <zn-radio value="5">5</zn-radio>
+  <zn-radio value="6">6</zn-radio>
+  <zn-radio value="7">7</zn-radio>
+  <zn-radio value="8">8</zn-radio>
+  <zn-radio value="9">9</zn-radio>
+  <zn-radio value="10">10</zn-radio>
+</zn-radio-group>
+<br/>
+<zn-radio-group name="empathy" label="Empathy" help-text="Unanswered until a segment is picked" scale required>
+  <zn-radio value="1">1</zn-radio>
+  <zn-radio value="2">2</zn-radio>
+  <zn-radio value="3">3</zn-radio>
+  <zn-radio value="4">4</zn-radio>
+  <zn-radio value="5">5</zn-radio>
+</zn-radio-group>
+```
+
+Set `--zn-radio-scale-segment-height` and `--zn-radio-scale-segment-radius` on the radios to resize the segments.
+
 ### Disabling Options
 
 Radios can be disabled by adding the `disabled` attribute to the respective options inside the radio group.

package/docs/pages/components/radio.md

@@ -101,7 +101,7 @@ Use the `label` attribute to add a form control label above the radio group. Use
 
 ### Contained Style
 
-Add the `contained` attribute to draw a card-like container around a radio. This style is useful for giving more emphasis to radio options.
+Add the `contained` attribute to draw a card-like container around a radio. This style is useful for giving more emphasis to radio options. The container shows the selected state, so the radio indicator is hidden; set `control-position` to place one in the card.
 
 ```html:preview
 <zn-radio name="payment" value="credit" description="Pay with Visa, Mastercard, or Amex" contained checked>Credit Card</zn-radio>