@kubex/zinc 1.1.92 → 1.1.95

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

@@ -27,6 +27,10 @@ are bound by their `name` attribute: values prefill from the section's data and
             description="Large banner with optional search">
     <zn-input name="title" label="Title"></zn-input>
     <zn-input name="subtitle" label="Subtitle"></zn-input>
+    <zn-input name="gradient" label="Background gradient" placeholder="linear-gradient(135deg, #00aaff, #aa00ff)"
+              help-text="CSS gradient painted behind the hero. Leave empty for the theme default."></zn-input>
+    <zn-toggle name="showSearch" label="Show search"
+               description="Draws the site search box in the banner."></zn-toggle>
   </template>
   <template type="article-list" slot="config" label="Article List" icon="list" category="Content"
             description="A list of KB articles">
@@ -40,13 +44,42 @@ Types can also be registered programmatically via `sectionTypes` /
 `registerSectionTypes()`, including a `renderConfig(section, update)` callback for
 inspector bodies that need real logic.
 
+## The inspector
+
+Selecting a section opens the inspector, which heads the panel with the section type's
+icon and colour, the section's name, its type (shown only where a renamed section makes
+it useful), and a close button that clears the selection. Below that, a **Section name**
+field renames the section (the card's label), followed by the type's stamped config form.
+A type whose template has no content gets a hint in place of the form rather than an
+empty panel.
+
+Because the panel is narrow, the inspector sets its own form-label and help-text
+typography rather than inheriting your app's full-width form styling, and its `gap` is
+the single source of spacing between fields — a control's own outer margins are zeroed
+so they can't stack with it. Stamped `<zn-toggle>`s are laid out as a row, with the
+label and description left and the switch right; set `label-position` yourself on a
+toggle to opt out.
+
+Style the panel through `inspector`, `inspector-header` and `inspector-body` parts.
+
+A container section additionally gets a **Layout** group at the top of the inspector: a column
+count, a weight per column, a "Keep adding rows" toggle, and — when growing is off — a row count.
+Every edit here is lossless: changing the column count re-chunks the same ordered list of
+stacks into the new shape, changing the row count only pads or trims trailing empty rows
+(clamping at the last row that still holds content), and changing a column's weight leaves
+every cell's contents untouched. All of it is undoable like any other edit.
+
 ## JavaScript API
 
 - `state` — get/set the current `PageState`. The getter returns a deep copy; the setter
   replaces the state wholesale (like the `config` attribute, it does not emit `zn-page-change`).
 - `addSection(type, index?)` — insert a new section of a registered type (default: at the end).
-- `addSectionToSlot(type, containerId, slotIndex)` — insert into a container's empty slot,
-  honouring its `accepts` list. Returns the new section, or `null` if not allowed.
+- `addSectionToCell(type, containerId, cellIndex, insertIndex?)` — insert a new section of a
+  registered type into a container's cell. `cellIndex` is the position in the container's flat,
+  row-major `cells` list; `insertIndex` (default `0`, the top of the stack) is where in that
+  cell's stack it lands. Returns the new section, or `null` if the drop isn't allowed — because
+  the type isn't in the container's `accepts` list, or because it would exceed the two-level
+  nesting cap.
 - `undo()` / `redo()` — step through edit history (bounded at 50 entries). There is no built-in
   toolbar: wire these to your own header buttons or keyboard shortcuts.
 - `registerSectionType(type)` / `registerSectionTypes(types)` — programmatic registration,
@@ -92,8 +125,8 @@ or call `restoreAutoSave()` yourself.
 
 Every edit emits `zn-page-change` with the full page state (`event.detail.state`, also
 readable via the `state` property) — plain JSON the host persists and later feeds back in
-through the `config` attribute. Sections appear in page order; container sections carry a
-`children` array sized to their slot count, with `null` for empty slots:
+through the `config` attribute. Sections appear in page order; a container section additionally
+carries `layout` and `cells`, per the Containers section below:
 
 ```json
 {
@@ -108,10 +141,11 @@ through the `config` attribute. Sections appear in page order; container section
       "type": "article-grid",
       "label": "Popular articles",
       "data": {"title": "Popular"},
-      "children": [
-        {"id": "s-mc42h-2", "type": "article-tile", "data": {"article": "art_42"}},
-        {"id": "s-mc42p-3", "type": "article-tile", "data": {"article": "art_7"}},
-        null, null, null, null
+      "layout": {"widths": [1, 1, 1], "grow": false},
+      "cells": [
+        [{"id": "s-mc42h-2", "type": "article-tile", "data": {"article": "art_42"}}],
+        [{"id": "s-mc42p-3", "type": "article-tile", "data": {"article": "art_7"}}],
+        []
       ]
     },
     {
@@ -123,29 +157,119 @@ through the `config` attribute. Sections appear in page order; container section
 }
 ```
 
-## Container tiles
+A host loading a config saved before this model — the old flat, null-padded `children` array —
+still has it accepted and migrated on load; see "Legacy `slots`" further down for what that
+older shape looked like and how it's converted.
 
-A section type with a `slots` attribute becomes a full-row container: its card renders a
-3-column grid of that many child slots beneath it. Drag sections from the palette into empty
-cells, drag children **between cells to reorder**, or out onto the page. `accepts` restricts
-which types the slots take. Containers can't be placed inside other containers, and slot
-contents persist as `children` on the section (empty slots are `null`).
+## A required first section
+
+Pages that must always open with a particular section — a hero banner, a masthead — set
+`required-first` to that section type. The builder hoists an existing section of the type to
+the top of the page, or inserts an empty one when there is none, and pins it there: it has no
+remove action, ignores <kbd>Delete</kbd>, can't be dragged or moved into a container slot, and
+nothing can be dropped above it. Its content stays fully editable in the inspector, and the
+type stays in the palette, so further sections of it can still be added below.
+
+Which section is pinned is derived from the state — `sections[0]` when its type matches — so
+nothing about the lock is written into the persisted config.
+
+```html:preview
+<zn-page-builder heading="KB Homepage" required-first="hero" style="height: 420px"
+  config='{"sections":[{"id":"t1","type":"rich-text","data":{"content":"Welcome"}}]}'>
+  <template type="hero" slot="config" label="Hero" icon="star" category="Headers"
+            description="Banner with a heading and optional search">
+    <zn-input name="title" label="Title"></zn-input>
+    <zn-toggle name="showSearch" label="Show search"></zn-toggle>
+  </template>
+  <template type="rich-text" slot="config" label="Rich Text" icon="notes" category="Content"
+            description="A block of markdown content">
+    <zn-input name="content" label="Content"></zn-input>
+  </template>
+</zn-page-builder>
+```
+
+The config above declares only a rich-text section, so the hero is inserted above it — loading a
+page that lacks the required section normalises it rather than rejecting it. Two things follow
+from that. The inserted section's `data` is empty, so a host that wants the pinned section
+prefilled should put it into the `config` it hands over rather than rely on the insert. And the
+guard is client-side, so a host that persists the config should enforce the same rule on save.
+
+## Containers
+
+A section type with the `container` attribute becomes a full-row container: its card renders a
+grid of **cells** beneath it, and each cell holds an ordered **stack** of sections. The type
+author only declares that it's a container and what it starts as; the editor reshapes it after
+placing it, from the inspector's Layout group.
+
+| Attribute | Meaning |
+|---|---|
+| `container` | Marks the type a container. Required. |
+| `columns="4"` | Seeds a new instance with 4 equal columns. |
+| `widths="1 2 1"` | Seeds the column weights directly (comma- or whitespace-separated). Wins over `columns`. |
+| `grow` | Seeds the instance growable — it always offers a further empty row. |
+| `accepts="a,b"` | Restricts which types the cells take. Omit to allow any type, within the nesting cap below. |
+
+If `widths` is present but unparsable — non-numeric tokens are discarded rather than kept as
+columns — the container falls back to `columns`, and if that's absent too, to three equal
+columns (`[1, 1, 1]`).
+
+Drag sections from the palette into a cell, stack several sections in one cell, or drag them
+between cells or out onto the page. Containers may nest **two levels deep** — a container inside
+a cell, itself holding another container — and a drop that would nest a third level is refused.
+That cap holds even when a container's `accepts` list names another container type: `accepts`
+can't be used to bypass it.
 
 ```html:preview
 <zn-page-builder heading="KB Homepage" style="height: 560px"
-  config='{"sections":[{"id":"g1","type":"article-grid","data":{}}]}'>
-  <template type="article-grid" slot="config" label="Article Grid" icon="grid_view"
-            category="Layout" description="A 3x2 grid of article tiles"
-            slots="6" accepts="article-tile">
+  config='{"sections":[{"id":"g1","type":"row","data":{},"layout":{"widths":[1,2,1],"grow":false},"cells":[[],[],[]]}]}'>
+  <template type="row" slot="config" label="Row" icon="view_column" category="Layout"
+            description="A row of columns you can weight" container widths="1 2 1">
+    <zn-input name="title" label="Row title"></zn-input>
+  </template>
+  <template type="grid" slot="config" label="Tile Grid" icon="grid_view" category="Layout"
+            description="Keeps adding rows as you fill it" container columns="3" grow>
     <zn-input name="title" label="Grid title"></zn-input>
   </template>
-  <template type="article-tile" slot="config" label="Article" icon="article" category="Content"
+  <template type="article" slot="config" label="Article" icon="article" category="Content"
             description="A single article tile">
     <zn-input name="article" label="Article id"></zn-input>
   </template>
 </zn-page-builder>
 ```
 
+### The container config
+
+A container persists its `layout` and its `cells` — a flat, row-major list of stacks whose
+length is always a whole multiple of `layout.widths.length`. Rows are implicit
+(`cells.length / layout.widths.length`), so there's no row count to keep in sync:
+
+```json
+{
+  "id": "s-mc42a-1",
+  "type": "row",
+  "layout": { "widths": [1, 2, 1], "grow": false },
+  "cells": [
+    [ { "id": "s-1", "type": "nav", "data": {} },
+      { "id": "s-2", "type": "links", "data": {} } ],
+    [ { "id": "s-3", "type": "hero", "data": {} } ],
+    []
+  ]
+}
+```
+
+Render it by mapping each weight to a grid track and each cell to a stack. A **growable**
+container never persists a trailing all-empty row — the builder adds that row itself at render
+time, so don't expect it in the JSON. A **fixed** container's trailing empty row, by contrast, is
+part of its layout and does persist.
+
+### Legacy `slots`
+
+`slots="6"` still declares a container, and pages persisted with the old flat, null-padded
+`children` array still load: they're migrated to `layout` + `cells` on load and re-saved in the
+new shape — `children` is never written back. A `slots`-declared container that has no explicit
+`accepts` also keeps its older, stricter rule of refusing container types in its cells (rather
+than allowing anything up to the nesting cap). Prefer `container` going forward.
+
 ## List sections
 
 Sections that show a set of existing items (categories, articles, …) reference them by id:

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

@@ -0,0 +1,345 @@
+---
+meta:
+  title: Schedule Builder
+  description: Builds a weekly opening-hours schedule as a drag-to-paint calendar or a compact list of time ranges, and posts the result as JSON.
+layout: component
+---
+
+```html:preview
+<zn-schedule-builder
+  name="opening-hours"
+  value='{
+    "timezone": "Europe/London",
+    "days": {
+      "mon": ["08:00-18:00"],
+      "tue": ["08:00-18:00"],
+      "wed": ["08:00-18:00"],
+      "thu": ["08:30-18:00"],
+      "fri": ["08:00-18:00"],
+      "sat": ["09:00-13:00"],
+      "sun": []
+    },
+    "exceptions": [
+      {"label": "All-hands offsite", "date": "2026-08-28", "ranges": ["08:00-13:00"]},
+      {"label": "Systems maintenance", "date": "2026-09-14", "ranges": ["10:00-18:00"]},
+      {"label": "Christmas Eve — early close", "date": "2026-12-24", "ranges": ["08:00-13:00"]}
+    ]
+  }'>
+</zn-schedule-builder>
+```
+
+:::tip
+This component works with standard `<form>` elements. Please refer to the section
+on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+:::
+
+## The Value
+
+The schedule is serialised to JSON and exposed three ways:
+
+- as the `value` attribute/property — a JSON string, which is what gets submitted with the form;
+- as the `schedule` property — the same data as a plain object;
+- as the `zn-change` event, emitted whenever the schedule changes.
+
+```json
+{
+  "timezone": "UTC",
+  "days": {
+    "mon": [{ "start": "08:00", "end": "18:00" }],
+    "tue": [{ "start": "08:00", "end": "12:00" }, { "start": "13:30", "end": "18:00" }],
+    "wed": [], "thu": [], "fri": [], "sat": [], "sun": []
+  },
+  "exceptions": [
+    { "label": "Christmas Eve — early close", "date": "2026-12-24", "ranges": [{ "start": "08:00", "end": "13:00" }] }
+  ]
+}
+```
+
+Ranges are always sorted, and overlapping or touching ranges are merged, so `08:00–12:00` plus
+`12:00–18:00` becomes a single `08:00–18:00`. Times are 24 hour `HH:MM` regardless of the
+`time-format` used for display, and `timezone` names the timezone they are expressed in — see
+[Timezones](#timezones).
+
+When you write the value yourself you can use the `"08:00-18:00"` shorthand instead of
+`{"start": "08:00", "end": "18:00"}`, and you can pass a bare day map without the `days` wrapper.
+Both are normalised on the way in.
+
+## Examples
+
+### Views
+
+The builder has two views. `calendar` is a drag-to-paint week grid; `form` is a compact list of time
+ranges that fits inside a normal settings form. Use the `view` attribute to choose the starting
+view, and `no-toggle` to remove the switcher and lock the component to one of them.
+
+```html:preview
+<zn-schedule-builder
+  view="form"
+  value='{"mon":["08:00-18:00"],"tue":["08:00-18:00"],"wed":["08:00-12:00","13:30-18:00"],"thu":["08:00-18:00"],"fri":["08:00-16:00"],"sat":["09:00-13:00"],"sun":[]}'>
+</zn-schedule-builder>
+```
+
+In the form view, click a range to edit it, and use **Add range** to split a day into multiple
+periods. In the calendar view, drag across the grid to open hours and drag over open hours to close
+them — a drag can span several days at once.
+
+### Timezones
+
+A schedule has two timezones: the one it is **stored** in, and the one it is **shown** in.
+
+- `save-timezone` is the timezone the value is written in. It defaults to `UTC` as soon as the
+  schedule is timezone-aware, so hours land in your database in one canonical zone.
+- `display-timezone` is the timezone the grid and the list are drawn in. It defaults to
+  `save-timezone`, and accepts `auto` for the viewer's own timezone.
+- `show-timezone` adds a picker so the viewer can read the same schedule in any timezone.
+
+Switching the display timezone never changes the value — the same hours are simply labelled in
+another zone, and `zn-change` doesn't fire. Edits work the other way around: you drag or type in the
+zone you are looking at, and the component converts back to `save-timezone` before storing.
+
+```html:preview
+<zn-schedule-builder
+  id="tz-demo"
+  show-timezone
+  display-timezone="Europe/London"
+  start-hour="0"
+  end-hour="24"
+  hide-summary
+  value='{"timezone":"UTC","days":{"mon":["08:00-18:00"],"tue":["08:00-18:00"],"wed":["08:00-18:00"],"thu":["08:00-18:00"],"fri":["08:00-16:00"]}}'>
+</zn-schedule-builder>
+
+<pre id="tz-demo-output" style="margin-top: 1rem"></pre>
+
+<script>
+  const tzBuilder = document.querySelector('#tz-demo');
+  const tzOutput = document.querySelector('#tz-demo-output');
+
+  const printTz = () => (tzOutput.textContent = `stored (UTC):\n${JSON.stringify(tzBuilder.schedule.days, null, 2)}`);
+
+  tzBuilder.addEventListener('zn-change', printTz);
+  printTz();
+</script>
+```
+
+Pick a timezone far from UTC and the blocks slide, wrapping onto the next day — or onto Monday, from
+the end of Sunday — while the stored hours below stay put.
+
+#### Which Timezones the Picker Offers
+
+`timezones` takes IANA names, or one of three named sets:
+
+| Set | Zones | What it is |
+| --- | --- | --- |
+| `en` | 6 | US Eastern, Central, Mountain and Pacific, the UK, and Australia — listed under those names rather than their IANA ones. For an English-speaking audience who would rather not read `America/Los_Angeles`. |
+| `offsets` | ~42 | One zone per UTC offset. The default — enough to read a schedule from anywhere without a long list, though the city standing in for each offset is arbitrary. |
+| `common` | ~90 | Every offset in use, plus the business and population centres that share one — so Berlin, Paris, Madrid and Rome all appear rather than one standing for the rest. Includes the half and quarter-hour zones (India, Iran, Nepal, Newfoundland, central Australia, Chatham). |
+| `all` | ~420 | Everything `Intl.supportedValuesOf('timeZone')` reports. Complete, but full of aliases and zones nobody selects. |
+
+`common` is the one to reach for whenever real users pick their own timezone; `offsets` suits an
+internal tool where the offset is all that matters; `en` suits a product whose customers are all in
+the US, the UK or Australia.
+
+```html:preview
+<zn-schedule-builder
+  show-timezone
+  timezones="en"
+  display-timezone="Europe/London"
+  view="form"
+  value='{"timezone":"UTC","days":{"mon":["13:00-21:00"],"tue":["13:00-21:00"]}}'>
+</zn-schedule-builder>
+```
+
+```html:preview
+<zn-schedule-builder
+  show-timezone
+  timezones="common"
+  display-timezone="auto"
+  view="form"
+  value='{"timezone":"UTC","days":{"mon":["13:00-21:00"],"tue":["13:00-21:00"]}}'>
+</zn-schedule-builder>
+```
+
+Sets and explicit names can be mixed — `timezones="en Asia/Tokyo"` adds Tokyo to the six above, and a
+set's friendly name wins over a later plain listing of the same zone. The viewer's own timezone plus
+both configured zones are always added, so the current selection is never missing from the list.
+
+```html:preview
+<zn-schedule-builder
+  show-timezone
+  display-timezone="America/New_York"
+  timezones="UTC Europe/London America/New_York Asia/Tokyo"
+  view="form"
+  value='{"timezone":"UTC","days":{"mon":["13:00-21:00"],"tue":["13:00-21:00"]}}'>
+</zn-schedule-builder>
+```
+
+Reading the hours in code follows the same split: `schedule`, `value` and `getDay()` are in the save
+timezone, while `displayedDays` and `setDisplayDay()` are in the display timezone.
+
+:::tip
+A weekly pattern has no date of its own, so there is no way to know whether daylight saving applies
+to it. Offsets are resolved against today by default; set `reference-date` to a `YYYY-MM-DD` date to
+pin them to a specific point in the year.
+:::
+
+### Open and Closed Labels
+
+`open-label` and `closed-label` name the two states. They appear in the calendar legend, against
+days with no hours, and in the exception annotations, so use whatever wording fits the thing being
+scheduled — availability, cover, staffing, opening hours.
+
+```html:preview
+<zn-schedule-builder
+  open-label="On call"
+  closed-label="Off"
+  start-hour="8"
+  end-hour="20"
+  hide-summary
+  value='{"mon":["09:00-17:00"],"tue":["09:00-17:00"],"wed":["09:00-17:00"],"thu":["09:00-17:00"],"fri":["09:00-13:00"]}'>
+</zn-schedule-builder>
+```
+
+### Labels and Help Text
+
+```html:preview
+<zn-schedule-builder
+  label="Opening hours"
+  help-text="Customers can only book appointments during these hours."
+  view="form"
+  value='{"mon":["09:00-17:00"],"tue":["09:00-17:00"],"wed":["09:00-17:00"],"thu":["09:00-17:00"],"fri":["09:00-17:00"]}'>
+</zn-schedule-builder>
+```
+
+### Grid Range and Granularity
+
+`start-hour` and `end-hour` set the window the calendar draws, and `interval` sets both the grid
+granularity and the step of the time inputs in the form view. The interval must be one of `5`, `10`,
+`15`, `20`, `30` or `60` minutes.
+
+```html:preview
+<zn-schedule-builder
+  start-hour="7"
+  end-hour="13"
+  interval="15"
+  hide-summary
+  value='{"mon":["08:00-12:00"],"tue":["08:15-11:45"],"wed":["08:00-12:00"],"thu":["08:00-12:00"],"fri":["08:00-11:00"]}'>
+</zn-schedule-builder>
+```
+
+### Exceptions
+
+Exceptions are dated deviations from the weekly pattern. The builder never edits them — it displays
+them, and carries them through the value untouched — so the surrounding application stays in charge
+of how they are created.
+
+Hours an exception removes are drawn in a lighter shade in the calendar, and annotated against the
+day in the form view. An exception can be a single `date`, or a `from`/`to` window, and can either
+close the day outright (`closed`) or replace its hours (`ranges`).
+
+Only exceptions that change the repeating weekly pattern are drawn against it: ones that name their
+`days`, and ones whose date window covers at least a full week. A one-off date is a single
+occurrence rather than a pattern, so it is carried through the value untouched but leaves the grid
+alone.
+
+```html:preview
+<zn-schedule-builder
+  view="form"
+  value='{
+    "days": {
+      "mon": ["08:00-18:00"],
+      "tue": ["08:00-18:00"],
+      "wed": ["08:00-18:00"],
+      "thu": ["08:00-18:00"],
+      "fri": ["08:00-16:00"],
+      "sat": ["09:00-13:00"],
+      "sun": []
+    },
+    "exceptions": [
+      {"label": "Summer Fridays", "from": "2026-06-01", "to": "2026-08-29", "days": ["fri"], "ranges": ["08:00-16:00"]},
+      {"label": "Bank holiday", "date": "2026-08-31", "closed": true}
+    ]
+  }'>
+</zn-schedule-builder>
+```
+
+### Week Start and Time Format
+
+```html:preview
+<zn-schedule-builder
+  week-start="sun"
+  time-format="12"
+  view="form"
+  value='{"mon":["08:00-18:00"],"sat":["09:00-13:00"],"sun":["10:00-16:00"]}'>
+</zn-schedule-builder>
+```
+
+### Readonly and Disabled
+
+Use `readonly` to display a schedule without any editing affordances, and `disabled` to grey it out
+and take it out of form submission.
+
+```html:preview
+<zn-schedule-builder
+  readonly
+  view="form"
+  value='{"mon":["08:00-18:00"],"tue":["08:00-18:00"],"wed":["08:00-18:00"],"thu":["08:00-18:00"],"fri":["08:00-18:00"],"sat":["09:00-13:00"]}'>
+</zn-schedule-builder>
+```
+
+### Reading the Value from JavaScript
+
+```html:preview
+<zn-schedule-builder
+  id="schedule-demo"
+  view="form"
+  value='{"mon":["09:00-17:00"],"tue":["09:00-17:00"]}'>
+</zn-schedule-builder>
+
+<pre id="schedule-demo-output" style="margin-top: 1rem"></pre>
+
+<script>
+  const builder = document.querySelector('#schedule-demo');
+  const output = document.querySelector('#schedule-demo-output');
+
+  const print = () => (output.textContent = JSON.stringify(builder.schedule, null, 2));
+
+  builder.addEventListener('zn-change', print);
+  print();
+</script>
+```
+
+### In a Form
+
+The schedule posts as a single JSON field named after the control.
+
+```html:preview
+<form class="schedule-form">
+  <zn-schedule-builder
+    name="opening-hours"
+    label="Opening hours"
+    required
+    view="form"
+    value='{"mon":["09:00-17:00"],"tue":["09:00-17:00"],"wed":["09:00-17:00"],"thu":["09:00-17:00"],"fri":["09:00-17:00"]}'>
+  </zn-schedule-builder>
+
+  <br />
+  <zn-button type="submit">Submit</zn-button>
+</form>
+
+<script>
+  const form = document.querySelector('.schedule-form');
+
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    const data = new FormData(form);
+    alert(data.get('opening-hours'));
+  });
+</script>
+```
+
+## Accessibility
+
+The form view is fully keyboard operable: ranges are buttons, editing a range gives you two native
+time inputs, and <kbd>Enter</kbd> or <kbd>Escape</kbd> closes the editor. The calendar view is a
+pointer-driven surface, so offer the form view (the default toggle does) wherever keyboard-only
+users need to edit a schedule.