@kubex/zinc 1.1.97 → 1.1.99

package/docs/pages/components/background.md

@@ -0,0 +1,143 @@
+---
+meta:
+  title: Background
+  description: Layer a colour, decorative image, image strength, motion and contrast overlay behind content.
+layout: component
+---
+
+`zn-background` builds a presentation background without making assumptions about the content laid over it. Give the element a height (or let its content establish one), then use the default slot for foreground content.
+
+```html:preview
+<zn-background
+  image="https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1400&q=80"
+  color="#18382f"
+  image-strength="full"
+  motion="drift"
+  overlay="strong"
+  overlay-tone="dark"
+  floating-icons="school,lightbulb,auto_awesome,psychology,rocket_launch,public"
+  style="min-height: 24rem; border-radius: var(--zn-border-radius-large); color: white;">
+  <zn-sp style="max-width: 38rem;" xl>
+    <h2>Build a calm, legible canvas</h2>
+    <p>The image, movement and contrast treatment stay behind any slotted Zinc or HTML content.</p>
+  </zn-sp>
+</zn-background>
+```
+
+## Treatments
+
+Use `image-strength="soft|medium|full"` to set the image opacity, `motion="none|drift|breathe"` to choose its movement, and `overlay="none|soft|strong"` to control the contrast gradient. `overlay-tone="light"` places a white gradient over the image; use `dark` when light foreground content needs a dark gradient.
+
+Motion automatically stops for people who request reduced motion. Set `paused` when a background remains in the document but is not currently visible, such as an inactive slide.
+
+### Image strength
+
+```html:preview
+<zn-cols layout="1,1,1">
+  <zn-background color="#dcefeb" image="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&q=70" image-strength="soft" overlay="soft" style="min-height: 13rem;">
+    <zn-sp><strong>Soft image</strong></zn-sp>
+  </zn-background>
+  <zn-background color="#dcefeb" image="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&q=70" image-strength="medium" overlay="soft" style="min-height: 13rem;">
+    <zn-sp><strong>Medium image</strong></zn-sp>
+  </zn-background>
+  <zn-background color="#10231d" image="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&q=70" image-strength="full" overlay="strong" overlay-tone="dark" style="min-height: 13rem; color: white;">
+    <zn-sp><strong>Full image</strong></zn-sp>
+  </zn-background>
+</zn-cols>
+```
+
+### Motion
+
+`drift` slowly travels across the image, while `breathe` gently changes its scale. The oversized image canvas keeps the edges covered throughout both animations.
+
+```html:preview
+<zn-cols layout="1,1,1">
+  <zn-background
+    color="#18382f"
+    image="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=900&q=75"
+    motion="none"
+    overlay="strong"
+    overlay-tone="dark"
+    style="min-height: 14rem; color: white;">
+    <zn-sp><strong>No motion</strong></zn-sp>
+  </zn-background>
+  <zn-background
+    color="#18382f"
+    image="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=900&q=75"
+    motion="drift"
+    overlay="strong"
+    overlay-tone="dark"
+    style="min-height: 14rem; color: white;">
+    <zn-sp><strong>Gentle drift</strong></zn-sp>
+  </zn-background>
+  <zn-background
+    color="#18382f"
+    image="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=900&q=75"
+    motion="breathe"
+    overlay="strong"
+    overlay-tone="dark"
+    style="min-height: 14rem; color: white;">
+    <zn-sp><strong>Gentle breathe</strong></zn-sp>
+  </zn-background>
+</zn-cols>
+```
+
+### Overlay strength
+
+The overlay sits above the image and below the slotted content. Choose its strength based on how much contrast the foreground needs.
+
+```html:preview
+<zn-cols layout="1,1,1">
+  <zn-background
+    color="#dcefeb"
+    image="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=900&q=75"
+    overlay="none"
+    style="min-height: 14rem;">
+    <zn-sp><strong>No overlay</strong></zn-sp>
+  </zn-background>
+  <zn-background
+    color="#dcefeb"
+    image="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=900&q=75"
+    overlay="soft"
+    overlay-tone="light"
+    style="min-height: 14rem;">
+    <zn-sp><strong>Soft light overlay</strong></zn-sp>
+  </zn-background>
+  <zn-background
+    color="#10231d"
+    image="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=900&q=75"
+    overlay="strong"
+    overlay-tone="dark"
+    style="min-height: 14rem; color: white;">
+    <zn-sp><strong>Strong dark overlay</strong></zn-sp>
+  </zn-background>
+</zn-cols>
+```
+
+### Floating icons
+
+Pass up to eight comma-separated Zinc icon names to `floating-icons`. The icons are decorative and non-interactive. Each uses a fixed ambient anchor with its own timing and fades between 1% and no more than 50% opacity.
+
+Icon size follows the background width: 5% of the available space, capped at 150px. Floating motion stops when reduced motion is requested or when the background has `paused`.
+
+```html:preview
+<zn-background
+  color="#151b34"
+  image="https://images.unsplash.com/photo-1446776811953-b23d57bd21aa?w=1400&q=80"
+  image-strength="medium"
+  overlay="strong"
+  overlay-tone="dark"
+  floating-icons="rocket_launch,public,star,science,satellite_alt,explore,orbit,auto_awesome"
+  style="min-height: 28rem; color: white; --zn-background-floating-icon-color: #d9e2ff;">
+  <zn-sp style="max-width: 34rem;" xl>
+    <h2>Explore the next horizon</h2>
+    <p>Floating icons remain a background treatment, so the foreground content keeps normal focus and pointer behaviour.</p>
+  </zn-sp>
+</zn-background>
+```
+
+## CSS customisation
+
+Use `--zn-background-image-position` to change the image focal point, `--zn-background-overlay-angle` to turn the overlay gradient, and `--zn-background-floating-icon-color` to recolour the ambient icons. `--zn-background-color` provides a reusable fallback when the `color` attribute is omitted.
+
+The `base`, `image`, `overlay`, `floating-icons`, `floating-icon`, and `content` CSS parts are available for application-specific treatments that cannot be expressed with the attributes or custom properties.

package/docs/pages/components/button.md

@@ -117,6 +117,15 @@ Buttons can be used with just an icon and no text by omitting the button label.
 <zn-button icon="add" color="info"></zn-button>
 ```
 
+An icon-only button has no text for assistive technology to read, so give it a name
+with the `label` attribute. A `tooltip` is used as the name when no `label` is set,
+which covers most icon-only buttons without extra markup.
+
+```html:preview
+<zn-button icon="settings" label="Settings"></zn-button>
+<zn-button icon="delete" color="error" tooltip="Delete"></zn-button>
+```
+
 ### Icon Buttons
 
 Use `icon-button` to render a chromed icon button: a 40x36 white button with a border, a 6px radius, and a centred 20px icon. Pass `small` for the 36x36 variant or `round` for a 36x36 circle on the tab tint. The icon button style takes precedence over color variants like `secondary` — the `color` attribute only tints the icon.
@@ -216,7 +225,8 @@ Use `muted-notifications` for a subtle notification style.
 
 ### Tooltip
 
-Use the `tooltip` attribute to add a tooltip to the button.
+Use the `tooltip` attribute to add a tooltip to the button. On a button with no text,
+the tooltip also becomes the accessible name — see [Icon-Only Buttons](#icon-only-buttons).
 
 ```html:preview
 <zn-button icon="info" tooltip="This button provides additional information"></zn-button>

package/docs/pages/components/chart.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Data Chart
-  description: Charts visualize data using various chart types powered by Apache ECharts. Display line charts, bar charts, area charts, sankey diagrams, and more with full customization options.
+  description: Charts visualize data using line, bar, area, circular, statistical, hierarchical, and flow layouts powered by Apache ECharts.
 layout: component
 ---
 
@@ -281,6 +281,135 @@ Use `type="sankey"` to render a Sankey flow diagram. Each item in the series `da
 </zn-chart>
 ```
 
+### Pie Chart
+
+Use `type="pie"` for part-to-whole data. The first series supplies the slice values and `categories` supplies their
+names.
+
+```html:preview
+<zn-chart
+  type="pie"
+  categories="[&quot;Configuration suggestion&quot;,&quot;Insecure configuration&quot;]"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[8,1]}]"
+  height="300">
+</zn-chart>
+```
+
+### Donut Chart
+
+Use `type="donut"` for a pie chart with a hollow centre. Adjust the ring with `inner-radius` and `outer-radius`; both
+accept an ECharts pixel value or percentage. Add `show-labels` to render labels beside the slices.
+
+```html:preview
+<zn-chart
+  type="donut"
+  inner-radius="45%"
+  outer-radius="75%"
+  colors="[&quot;#ffe29a&quot;,&quot;#f78ab3&quot;]"
+  categories="[&quot;Configuration suggestion&quot;,&quot;Insecure configuration&quot;]"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[8,1]}]"
+  height="300">
+</zn-chart>
+```
+
+### Scatter Chart
+
+Use `type="scatter"` with `[x, y]` coordinate pairs. `d-size` controls point size, and `xaxis="datetime"` can be used
+for time-based scatter plots.
+
+```html:preview
+<zn-chart
+  type="scatter"
+  d-size="14"
+  data="[{&quot;name&quot;:&quot;Latency&quot;,&quot;data&quot;:[[12,110],[24,180],[38,140],[52,260],[70,220]]}]"
+  height="300">
+</zn-chart>
+```
+
+### Radar Chart
+
+Use `type="radar"` with an `indicators` array describing each axis. Each normal series becomes one radar shape.
+
+```html:preview
+<zn-chart
+  type="radar"
+  indicators="[{&quot;name&quot;:&quot;Security&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Performance&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Reliability&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Usability&quot;,&quot;max&quot;:100}]"
+  data="[{&quot;name&quot;:&quot;Current&quot;,&quot;data&quot;:[82,71,94,76]},{&quot;name&quot;:&quot;Target&quot;,&quot;data&quot;:[95,90,98,90]}]"
+  height="320">
+</zn-chart>
+```
+
+### Gauge Chart
+
+Use `type="gauge"` for a single current value. `min-value`, `max-value`, and `y-axis-append` configure its range and
+displayed unit.
+
+```html:preview
+<zn-chart
+  type="gauge"
+  min-value="0"
+  max-value="100"
+  y-axis-append="%"
+  data="[{&quot;name&quot;:&quot;Security score&quot;,&quot;data&quot;:[82]}]"
+  height="300">
+</zn-chart>
+```
+
+### Funnel Chart
+
+Use `type="funnel"` for ordered stages. Numeric values pair with `categories`, using the same compact format as pie
+charts.
+
+```html:preview
+<zn-chart
+  type="funnel"
+  categories="[&quot;Visitors&quot;,&quot;Trials&quot;,&quot;Customers&quot;]"
+  data="[{&quot;name&quot;:&quot;Conversion&quot;,&quot;data&quot;:[1000,320,85]}]"
+  height="320">
+</zn-chart>
+```
+
+### Heatmap Chart
+
+Use `type="heatmap"` with x-axis `categories`, `y-categories`, and `[xIndex, yIndex, value]` data points. The visual
+range is derived from the values unless `min-value` or `max-value` is provided.
+
+```html:preview
+<zn-chart
+  type="heatmap"
+  show-labels
+  categories="[&quot;Mon&quot;,&quot;Tue&quot;,&quot;Wed&quot;,&quot;Thu&quot;,&quot;Fri&quot;]"
+  y-categories="[&quot;API&quot;,&quot;Web&quot;,&quot;Worker&quot;]"
+  data="[{&quot;name&quot;:&quot;Requests&quot;,&quot;data&quot;:[[0,0,5],[1,0,12],[2,0,8],[3,0,16],[4,0,11],[0,1,9],[1,1,15],[2,1,12],[3,1,20],[4,1,14],[0,2,3],[1,2,7],[2,2,5],[3,2,10],[4,2,8]]}]"
+  height="320">
+</zn-chart>
+```
+
+### Treemap Chart
+
+Use `type="treemap"` with hierarchical `children` data to compare nested values by area.
+
+```html:preview
+<zn-chart
+  type="treemap"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[{&quot;name&quot;:&quot;Security&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Configuration&quot;,&quot;value&quot;:8},{&quot;name&quot;:&quot;Insecure&quot;,&quot;value&quot;:1}]},{&quot;name&quot;:&quot;Performance&quot;,&quot;value&quot;:4}]}]"
+  height="320">
+</zn-chart>
+```
+
+### Sunburst Chart
+
+Use `type="sunburst"` for radial hierarchical data. `inner-radius` and `outer-radius` adjust the occupied area.
+
+```html:preview
+<zn-chart
+  type="sunburst"
+  outer-radius="90%"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[{&quot;name&quot;:&quot;Security&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Configuration&quot;,&quot;value&quot;:8},{&quot;name&quot;:&quot;Insecure&quot;,&quot;value&quot;:1}]},{&quot;name&quot;:&quot;Performance&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Latency&quot;,&quot;value&quot;:4}]}]}]"
+  height="340">
+</zn-chart>
+```
+
 ### Cross-Chart Tooltip Sync
 
 Use `sync-group="<id>"` on two or more charts to synchronise hover tooltips, zoom, and legend selection across them.
@@ -439,6 +568,32 @@ When `type="sankey"`, each item in the series `data` array is an edge:
 
 Nodes are auto-derived from unique source/target values. To customise node appearance or ordering, include an explicit `nodes` key on the series object.
 
+### Pie and Donut Data
+
+Pie and donut charts use the first series. The standard numeric format pairs each value with the category at the same
+index. You can alternatively pass ECharts-style named slices when each slice needs its own metadata or colour:
+
+```json
+[{
+  "name": "Insights",
+  "data": [
+    {"name": "Configuration suggestion", "value": 8, "color": "#ffe29a"},
+    {"name": "Insecure configuration", "value": 1, "color": "#f78ab3"}
+  ]
+}]
+```
+
+### Specialized Data Formats
+
+- Scatter points use `[x, y]` or `{ "x": value, "y": value }`.
+- Radar charts accept an `indicators` array of `{ "name": string, "min"?: number, "max"?: number }`; each series
+  contains one value per indicator.
+- Gauge charts use the first value in the first series.
+- Funnel charts accept the same numeric/category or named-value formats as pie charts.
+- Heatmaps use `[xIndex, yIndex, value]` points with `categories` and `y-categories`.
+- Treemaps and sunbursts accept hierarchical nodes containing `name`, optional `value`, and optional recursive
+  `children`.
+
 ### HTML Encoding
 
 When using the data attribute in HTML, JSON must be properly encoded. Use `&quot;` for quotes:
@@ -483,6 +638,15 @@ chart.enableAnimations = true;
 - **Line Charts**: Best for showing trends over time or continuous data
 - **Bar Charts**: Ideal for comparing discrete categories or values
 - **Area Charts**: Good for showing cumulative totals or part-to-whole relationships over time
+- **Pie Charts**: Useful for compact part-to-whole comparisons with a small number of slices
+- **Donut Charts**: Useful when a pie chart needs a lighter visual weight or centred annotation space
+- **Scatter Charts**: Show relationships, distributions, and clusters between two numeric dimensions
+- **Radar Charts**: Compare a small number of entities across a shared set of metrics
+- **Gauge Charts**: Display one value against a meaningful bounded range
+- **Funnel Charts**: Show progressive reduction through ordered stages
+- **Heatmaps**: Reveal density and patterns across two categorical dimensions
+- **Treemaps**: Compare hierarchical values by area
+- **Sunburst Charts**: Explore hierarchical proportions across radial levels
 - **Stacked Charts**: Use when showing how categories contribute to a total
 
 ### Performance Considerations
@@ -505,5 +669,3 @@ chart.enableAnimations = true;
 - Round values appropriately for readability
 - Use `y-axis-append` to add units or symbols to values
 - Format dates consistently when using time series data
-
-

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

@@ -106,6 +106,18 @@ This option can be combined with the `horizontal` attribute.
 :::tip
 When [checkboxes](/components/checkbox) are wrapped with the Checkbox Group , adding the `contained` attribute to the
 parent Checkbox Group or to _any_ checkbox in the group will create `contained` checkboxes for the entire group.
+
+Contained checkboxes can also render as [multi-select cards](/components/checkbox#multi-select-cards) with an image,
+title, description, and positioned indicator. The checkbox group continues to manage validation and submits every
+selected value under the group's name.
+
+Contained checkboxes are rounded by default; add `square` to the group to square off every checkbox in it. With
+`horizontal`, cards in a row are given equal height, and `--zn-checkbox-group-column-width` (default `152px`) sets the
+minimum column width used by the grid.
+
+Add `wrap` to lay the checkboxes out as a wrapping row instead of an equal-width grid: each card starts from
+`--zn-checkbox-group-column-width` and grows to fill its line, and setting that property to `auto` sizes every card from
+its own content.
 :::
 
 ### Disabling Options
@@ -193,4 +205,4 @@ make the browser display the error message you provide. To clear the error, call
     });
   });
 </script>
-```
+```

package/docs/pages/components/checkbox.md

@@ -188,6 +188,64 @@ Add the `contained` attribute to draw a card-like container around a checkbox. T
 When checkboxes are wrapped with [Checkbox Group](/components/checkbox-group), adding the `contained` attribute to the parent Checkbox Group or to _any_ checkbox in the group will create `contained` checkboxes for the entire group.
 :::
 
+### Multi-select Cards
+
+Contained checkboxes support the same card content and placement options as [contained radios](/components/radio#selection-cards),
+while preserving checkbox semantics. Use them inside `zn-checkbox-group` when people may select more than one card.
+
+Set the title with `card-title` (or use the default slot), supporting text with `description`, and an image with `src`
+and `image-alt` or the `image` slot. `image-position` accepts `top`, `right`, `bottom`, and `left`. Cards are rounded
+by default; add `square` to the group to square off every card.
+
+```html:preview
+<zn-checkbox-group
+  label="Choose benefits"
+  help-text="Select all that apply"
+  name="benefits"
+  contained
+  horizontal>
+  <zn-checkbox
+    value="health"
+    card-title="Health insurance"
+    description="Medical and dental cover."
+    image-position="top"
+    control-position="top-right">
+    <zn-icon slot="image" src="health_and_safety" size="64"></zn-icon>
+  </zn-checkbox>
+  <zn-checkbox
+    value="pension"
+    card-title="Pension"
+    description="Employer contribution matching."
+    image-position="top"
+    control-position="top-right">
+    <zn-icon slot="image" src="savings" size="64"></zn-icon>
+  </zn-checkbox>
+</zn-checkbox-group>
+```
+
+Image and control placement is identical for radio and checkbox cards. See the
+[image and indicator position examples](/components/radio#image-and-indicator-positions) for a visual matrix of the
+four image directions, indicator corners, centered edge positions, and a hidden indicator.
+
+`control-position` accepts `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`,
+`bottom-left`, `bottom-center`, and `bottom-right`. The default `start` position retains the standard inline checkbox;
+use `none` to hide the indicator so the card itself shows the selected state, while keeping checkbox semantics and the
+full-card click target — see [hiding the input](/components/radio#hiding-the-radio-input) for what that looks like.
+
+```html:preview
+<zn-checkbox-group label="Choose add-ons" name="addons" contained horizontal wrap>
+  <zn-checkbox value="support" card-title="Priority support" description="One hour response time" control-position="none"></zn-checkbox>
+  <zn-checkbox value="backups" card-title="Daily backups" description="Retained for 30 days" control-position="none"></zn-checkbox>
+  <zn-checkbox value="audit" card-title="Audit log" description="Exportable as CSV" control-position="none"></zn-checkbox>
+</zn-checkbox-group>
+```
+
+Card dimensions can be adjusted with `--zn-selection-card-image-width`, `--zn-selection-card-image-height`,
+`--zn-selection-card-min-height`, `--zn-selection-card-content-min-width`, and `--zn-selection-card-title-font-size`.
+Use `--zn-selection-card-padding` for the inset around the card, `--zn-selection-card-gap` for the space between its
+regions, `--zn-selection-card-control-offset` for indicator placement, `--zn-selection-card-border-radius` for the
+corner radius, and `--zn-checkbox-group-column-width` on the group to control how many cards sit in a row.
+
 ### Borderless
 
 Use the `borderless` attribute to remove borders from the checkbox.
@@ -483,4 +541,4 @@ Checkboxes provide several methods for programmatic control:
     alert('Checkbox is ' + (isValid ? 'valid' : 'invalid'));
   });
 </script>
-```
+```

package/docs/pages/components/icon-picker.md

@@ -71,6 +71,14 @@ Use the `line` library for Lineicons.
 <zn-icon-picker name="line" label="Line Icon" icon="heart" library="line"></zn-icon-picker>
 ```
 
+### Lucide Icons
+
+Use the `lucide` library for [Lucide](https://lucide.dev/icons) icons, rendered as inline SVGs. Icon names use kebab-case.
+
+```html:preview
+<zn-icon-picker name="lucide" label="Lucide Icon" icon="rocket" library="lucide"></zn-icon-picker>
+```
+
 ### Gravatar
 
 Use the `gravatar` library to display a Gravatar from an email address.

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

@@ -161,6 +161,18 @@ This option can be combined with the `horizontal` attribute.
 :::tip
 When [radios](/components/radio) are wrapped with the Radio Group, adding the `contained` attribute to the
 parent Radio Group or to _any_ radio in the group will create `contained` radios for the entire group.
+
+Contained radios can also render as richer [selection cards](/components/radio#selection-cards) with an image, title,
+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
+`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.
+
+Add `wrap` to lay the radios out as a wrapping row instead of an equal-width grid: each card starts from
+`--zn-radio-group-column-width` and grows to fill its line, and setting that property to `auto` sizes every card from
+its own content.
 :::
 
 ### Disabling Options