@soxa-ui/webc 0.0.0-stage → 0.3.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuri Soldatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,623 @@
-# Temporary Holding Version
+# @soxa-ui/webc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The Web Components adapter: Soxa UI as Custom Elements on the headless models of the core.**
+
+Part of [Soxa UI](https://github.com/youra-h/soxa-ui) — UI components with the logic written once: a
+framework-agnostic core and thin adapters that render it in Vue, React, Angular, Svelte, Solid and
+Web Components.
+
+The adapter is wiring, not behavior: it defines a Custom Element per component and renders the
+markup — BEM classes `so-*` and `data-*` state attributes. Props, events and slots come from the
+component descriptor, so they match the other five adapters; only the spelling is the platform's:
+props are attributes or element properties, and events are DOM events named `so:` + the core name
+(`so:show`, `so:show:before`, `so:action:press`, `so:change:disabled`). Every event has the prefix:
+events bubble from your element through the DOM, and the prefix tells a component's event from the
+browser's and your own. A "before" event (`so:show:before`, `so:hide:before`) is cancelable, as a
+DOM event is: `event.preventDefault()` in a listener on the element or above it cancels the action.
+Its `detail` is the core event itself, so `event.detail.preventDefault()` cancels it too. Any other
+event's `detail` is the argument of the core event, or an array of them when there are several: an
+item's `so:change:selected` carries its new mark and comes only to the item whose mark changed; its
+owner's `so:change:selection` carries `[selected, changed]`, the selected items and the items whose
+mark changed; `so:change:activation` of tabs and radio groups carries `[active, previous]`.
+
+Each component is a native element of its tag extended by Soxa (a customized built-in):
+`<button is="so-button">` is a real `<button>`, `<div is="so-component-view">` a real `<div>`.
+Whatever the browser does for the tag it does for the component — a button submits and resets its
+form, is the event's `submitter`, works with `new FormData(form, submitter)`, Enter in a form
+field, `formaction`, `<fieldset disabled>`, `<label for>` and `popovertarget`. `class`, `style`,
+attributes and listeners on it take effect directly, and an attribute you set (`aria-label`,
+`tabindex`) wins over what the component writes. There is no `tag` prop — the root is always the
+element you wrote.
+
+Safari does not support customized built-ins, so the package imports the
+[`@ungap/custom-elements`](https://github.com/ungap/custom-elements) polyfill (3 KB gzipped); it
+does nothing where the browser supports them natively. With the polyfill an element comes to life a
+microtask after it is inserted, so right after `innerHTML` its `ctrl` is not there yet. Elements
+already in the page when the package is imported are assembled a microtask after the import in every
+browser (with the polyfill, once it has brought them all to life), so the theme, icons and plugins
+your entry point sets up right after the import (before any top-level `await`) apply to them too.
+They are assembled in document order, each owner before the items inside it, whatever order their
+names are registered in; an element your code puts inside such markup before then waits for it.
+
+Shadow DOM is not used — a theme styles global BEM classes, so light DOM is distributed by the
+`slot` attribute by hand. Content for a slot the component does not have is not rendered, and slots
+get no scope: slot content is the element's own light DOM, so component data (the `text` of
+Button's `default` slot) cannot be passed into it — slot content reads it from the element,
+`el.ctrl`.
+
+> **Status:** the Web Components adapter is in progress — Button, Icon, Label, Input, NumberInput
+> (`<div is="so-number-input">`: a number in the locale's format with − and + step buttons; the
+> form gets the number), Textarea (`<div is="so-textarea">`: multi-line, growing with its text,
+> with a character counter), CheckBox, Switch, Slider (`<span is="so-slider">`), Rating
+> (`<span is="so-rating">`), the form field `<div is="so-field">` (label, helper and error linked
+> to the control inside it), ProgressSpinner, ProgressLinear (`<span is="so-progress-linear">`),
+> Skeleton, Frame, Popover (`<span is="so-popover">`), Tooltip (`<span is="so-tooltip">`),
+> Menu (`<span is="so-menu">`: an action menu at a button or a context menu, with submenus,
+> checkbox and radio items and items with a panel), Dialog (`<div is="so-dialog">`), Drawer
+> (`<div is="so-drawer">`), Toasts (`<so-toasts>`
+> around the application, a toast from code — `toastsOf(element).show(…)`),
+> Scroller (`<div is="so-scroller">`), RadioGroup, ListBox, Tabs, Accordion, Tags
+> (`<div is="so-tags">`), Select (`<div is="so-select">`: a field with a list in a panel, tags in
+> the field for multiple selection), Pagination (`<nav is="so-pagination">`), Table, the date
+> field DateInput (`<div is="so-date-input">`: a date and time typed in parts in the locale's
+> format), Calendar (`<div is="so-calendar">`: month grids with a month and year picker),
+> DatePicker (`<div is="so-date-picker">`: a date field and a calendar in a panel, a single date
+> or a range), the `<so-virtual>` window for long lists and the
+> `<so-drag-and-drop>` wrapper that lets users reorder the items of Tabs, ListBox and Accordion by
+> dragging (`so:move`; `so:move:before` can cancel with `event.preventDefault()`) are ported, the
+> rest of the set is on its way. See [the adapter table](https://github.com/youra-h/soxa-ui#components).
+
+## Install
+
+```bash
+npm install @soxa-ui/webc @soxa-ui/setup @soxa-ui/theme-oren @soxa-ui/icons-material
+```
+
+Install `@soxa-ui/setup` as a direct dependency for the `useIcons` and `useTheme` imports below.
+Keep it on the same version as `@soxa-ui/webc`.
+
+A theme and an icon pack are separate packages — pick the ones you want.
+
+## Usage
+
+Importing the package defines every element:
+
+```ts
+import '@soxa-ui/webc'
+```
+
+A page that uses a few components can import just theirs. Every element has an entry of its own,
+named as the element without `so-`; importing it defines the element with its parts, the elements
+its markup draws (a select brings its field, panel and tags) and the locale provider, and the
+application's bundle carries only those:
+
+```ts
+import '@soxa-ui/webc/button' // <button is="so-button">
+import '@soxa-ui/webc/check-box' // <span is="so-check-box">
+import '@soxa-ui/webc/tabs' // <div is="so-tabs"> with so-tabs-item and so-tabs-content
+import { toastsOf } from '@soxa-ui/webc/toasts' // <so-toasts> and the queue of its toasts
+import { TLocaleProviderElement } from '@soxa-ui/webc/locale-provider'
+```
+
+An element you write without importing its entry is not an error: the browser says nothing about
+an unknown `is`, so `<button is="so-button">` stays a plain `<button>` — no classes, no behavior.
+That is why the package root, where there is nothing to forget, is the default, and the entries are
+a choice for size. Take the values of an element from its entry as well — `TButtonElement` from
+`@soxa-ui/webc/button`, `toastsOf` from `@soxa-ui/webc/toasts`, `roleIcon` from
+`@soxa-ui/webc/icon`: the same name from the root brings every element along.
+
+```html
+<button is="so-button" text="Save" class="toolbar-action"><i slot="leading">★</i></button>
+<button is="so-button"><i slot="leading">★</i> Save</button>
+<span is="so-progress-spinner" value="40" aria_label="Uploading"></span>
+<span is="so-progress-linear" value="40" aria_label="Uploading"></span>
+<div is="so-skeleton" width="160" height="16"><p>Loaded content</p></div>
+```
+
+An icon from the icon pack is `<span is="so-icon">` with the role in its `icon` attribute (`el.icon`
+from code). The role is the element's own attribute, not a component prop: the element draws the
+role's `<svg>` inside itself, stretched to its box. The `span` is the icon's root — size, classes
+and the accessible name are on it, as with any element. Without a name the icon is hidden from
+screen readers:
+
+```html
+<span is="so-icon" icon="close" size="lg"></span>
+<span is="so-icon" icon="close" aria_label="Close"></span>
+<button is="so-button" text="Next">
+  <span is="so-icon" icon="arrowRight" slot="trailing"></span>
+</button>
+```
+
+The icon is always a `span`: `is` extends HTML elements only, so it cannot be an `<svg>`, and one
+name extends one tag, so `<i is="so-icon">` does not come to life. A bare `<svg>` with a role's
+picture, for markup of your own, is `roleIcon(role)` from the package.
+
+Attributes, classes and inline styles you write on an element win over what the component writes
+there itself: `style="width: 40px"` on a skeleton beats the width it computes, and a property a
+script sets on the element directly survives the component's updates.
+
+A frame is a layer above the page: the element you wrote moves itself to its `target` (`body` by
+default), out from under `overflow` and stacking contexts, with your class, attributes and
+listeners on it, and a comment stays in its place. It is hidden until `visible`, and `contained`
+keeps it in place, inside the nearest positioned ancestor:
+
+```html
+<div class="card">
+  <div is="so-frame" visible target="#layers" class="menu-panel" x="40" y="120">
+    <button is="so-button" text="Rename"></button>
+  </div>
+</div>
+```
+
+Moving the panel rebuilds neither the frame nor anything inside it, and the panel keeps the place it
+was written in: the button above takes its language from the `<so-locale-provider>` around the
+card, not around `#layers`. Removing the card from the page takes the panel out of the target with
+it, and moving the card elsewhere — even with a single call, `other.appendChild(card)` — rebuilds
+the panel for the new place: under another provider the button takes that provider's language.
+
+A popover is a panel with any content at a trigger — a non-modal dialog — and a tooltip is a hint
+shown on hover and on keyboard focus. The trigger is your element in the `trigger` slot, the
+content is the default slot, and the panel is a frame of their own, moved to `body`. Slots get no
+scope, so the trigger receives its side of the link by itself: the component writes it onto the
+first element of the `trigger` slot — `aria-haspopup`, `aria-expanded`, `aria-controls` and
+`data-selected` at a popover's trigger, `aria-describedby` (`aria-labelledby` with `type="label"`)
+at a tooltip's. Clicking the trigger, pressing outside, Escape and Tab are handled for you:
+
+```html
+<span is="so-popover" aria_label="Filters">
+  <button is="so-button" slot="trigger" text="Filters"></button>
+  <p>Any content: text, fields, buttons</p>
+  <button is="so-button" text="Apply"></button>
+</span>
+
+<span is="so-tooltip">
+  <button is="so-button" slot="trigger" text="Save"></button>
+  Save a draft
+</span>
+```
+
+The trigger stays the node you wrote, and the panel's content is not rebuilt when the panel moves
+to `body` or back with `contained` (the panel stays in place, at an `edge` of the nearest
+positioned ancestor). `lazy-mount` keeps the content out of the document until the panel is opened
+for the first time. The close button in the panel's corner shows the `close-icon` slot or a close
+icon; `el.closable = false` removes it — the attribute of a flag can only turn it on.
+
+A menu is an action menu at a button — or, with `open-on="contextmenu"`, a context menu of the area
+in its `trigger` slot, opened by the right button, a long touch or Shift+F10 at the point where it
+was called. The trigger gets its side of the link by itself, as at a popover (`aria-haspopup="menu"`,
+`aria-expanded`, `aria-controls`, `data-selected`; an area of a context menu gets no link). Items
+are the menu's own elements: an action `<div is="so-menu-item">`, a checkbox
+`<div is="so-menu-checkbox-item">` (`selected`), radio items `<div is="so-menu-radio-item">` in
+`<div is="so-menu-radio-group">` (its `value`), a submenu `<div is="so-menu-submenu">` with items
+of its own, an item with a panel of any content `<div is="so-menu-popover-item">` (its row text is
+the `header` slot), groups `<div is="so-menu-group">` with a `label` and separators
+`<div is="so-menu-separator">`. A shortcut hint goes to an item's `trailing` slot. Arrows, letters,
+the pointer, focus, Escape and Tab are handled for you; choosing an action closes the whole menu
+and reports `so:choose`, a checkbox and a radio item keep it open:
+
+```html
+<span is="so-menu">
+  <button is="so-button" slot="trigger" text="Actions"></button>
+  <div is="so-menu-group" label="View">
+    <div is="so-menu-checkbox-item" value="grid" text="Grid" selected></div>
+  </div>
+  <div is="so-menu-separator"></div>
+  <div is="so-menu-item" value="edit" text="Edit"><span slot="trailing">Ctrl+E</span></div>
+  <div is="so-menu-submenu" value="share" text="Share">
+    <div is="so-menu-item" value="link" text="Copy link"></div>
+  </div>
+</span>
+```
+
+Items given as data (`el.items = [...]`, or an `engine`) are actions, and an item with an `items`
+array of its own is a submenu, at any depth; groups come from `_.group` in the data or `groupBy`,
+and `groups` sets their order and labels. The `item-*` slots are templates, as in a list box, and a
+submenu drawn from data gets them too, under the same names — one set of templates for every
+level; `item-content` gives each submenu drawn from data items in markup instead of its own. The
+panels move to `body`, each a layer above the one it was opened from; a submenu's items join the
+submenu, not the menu above it.
+
+A dialog and a drawer are modal: the element you wrote is the panel, and it moves to `body` itself,
+like a frame, with its backdrop right before it — the component draws the backdrop, keeps it next
+to the panel wherever the panel goes and hides it with the panel. Nothing opens them for you: there
+is no trigger, so `el.visible = true` (or `el.ctrl.show()`) opens one, and the close button, the
+backdrop, Escape and a swipe ask it to close — `so:close:before` with `event.preventDefault()`
+keeps it open, and `el.dismissible = false` leaves only the close button and the swipe. The title,
+the content and the footer are the `title`, default and `footer` slots. A dialog can be
+maximized (`maximizable`, the `maximize-icon` and `restore-icon` slots); a drawer slides in at an
+edge (`placement`), can be swiped away (`swipe`) and with `contained` stays in the nearest
+positioned ancestor, together with its backdrop:
+
+```html
+<button id="open-settings">Settings</button>
+<div is="so-dialog" id="settings">
+  <span slot="title">Settings</span>
+  <p>Any content: text, fields, buttons</p>
+  <button is="so-button" slot="footer" text="Done"></button>
+</div>
+
+<script type="module">
+  const dialog = document.getElementById('settings')
+
+  document.getElementById('open-settings').addEventListener('click', () => {
+    dialog.visible = true
+  })
+</script>
+```
+
+Toasts are shown from code. `<so-toasts>` wraps the application and has no box of its own, like
+the locale provider: the application inside it stays in place, and the region with the toasts is
+moved to `body`, with the attributes, class and style you wrote on `<so-toasts>`. A node under the
+manager gets the queue with `toastsOf(node)` — the nearest manager above the node, also from inside
+a dialog moved to `body` — and `show` takes a text or options; content of your own is a function
+that receives the toast and returns a node. The `item`, `item-icon`, `item-content` and
+`item-close-icon` slots are templates, as in collections: every toast gets a copy, and a copy finds
+its toast on the nearest `.so-toasts-item` (`el.ctrl`). A toast is the manager's markup, like an
+item drawn from data, so its events do not bubble: the manager reports a closed toast with
+`so:item:close`.
+
+```html
+<so-toasts placement="top-end">
+  <main>
+    <button id="save">Save</button>
+  </main>
+</so-toasts>
+
+<script type="module">
+  import { toastsOf } from '@soxa-ui/webc'
+
+  const save = document.getElementById('save')
+
+  save.addEventListener('click', () => {
+    toastsOf(save).show({
+      text: 'Draft saved',
+      type: 'success',
+      render: (toast) => {
+        const undo = document.createElement('button', { is: 'so-button' })
+
+        undo.text = 'Undo'
+        undo.addEventListener('click', () => toast.close())
+
+        return undo
+      },
+    })
+  })
+</script>
+```
+
+In a form it is simply a button:
+
+```html
+<form>
+  <input name="q" />
+  <button is="so-button" name="action" value="search" text="Search"></button>
+  <button is="so-button" type="reset" text="Clear"></button>
+</form>
+```
+
+A field — `<div is="so-input">`, `<div is="so-number-input">`, `<div is="so-textarea">`,
+`<span is="so-check-box">`, `<span is="so-switch">` — is your element with a real `<input>` (a
+`<textarea>`) inside, in the page's ordinary DOM. The form sees that field by itself: `FormData`,
+`<fieldset disabled>`, validation and `<label>` work as with any input, no form-associated element
+involved. A number field sends the number, not the text it shows: its `name` goes to a hidden
+`<input>` with `1234.5` while the field reads `1,234.5`. A checkbox
+and a switch get their visible name from `<label is="so-label">` around them: clicking the text
+toggles the control, and the text becomes its accessible name.
+
+```html
+<form>
+  <div is="so-input" name="city" placeholder="City" autocomplete="address-level2"></div>
+  <label is="so-label" text="Send me news">
+    <span is="so-check-box" name="news"></span>
+  </label>
+  <label is="so-label" text="Dark theme">
+    <span is="so-switch" name="dark"></span>
+  </label>
+</form>
+```
+
+Attributes you write on a field are split as in the other adapters: `class`, `style` and the
+component's own props (`name`, `disabled`, `placeholder`) stay on the element, and every other
+attribute in the markup — `autocomplete`, `aria-label`, `tabindex`, `data-*` — moves to the
+`<input>` when the element is built. An attribute you set from code later stays on the element.
+`id` is the input's: `id="city"` in the markup lands on the `<input>`, so `<label for="city">`
+finds it. From code it is the same: `el.id = 'city'` (or `setAttribute('id', …)`) moves the id to
+the `<input>`, and `el.id = ''` removes it; the element itself never keeps an `id`. Read the
+current one as `el.state.id`.
+
+Slot content gets no scope, so your own clear button (the `clear` slot) clears the field through
+the element: `el.ctrl.clear()`. The built-in clear button and its icon are part of the field's
+markup, so their events (`so:action:press`, `so:change:focused`) do not bubble — listeners on the
+field and delegation on the form hear the field's own events only.
+
+A slider and a rating are fields as well: `<span is="so-slider">` has a native
+`<input type="range">` in each thumb, `<span is="so-rating">` one under its row of stars, and the
+form gets their values under `name`. A number is one thumb, an array is a thumb per item
+(`value="[20,80]"`, or `el.value = [20, 80]`). The pointer works on the track, never on the inputs,
+so attributes you write on these two stay on the element; only a rating's `id` goes to its input,
+where `<label for>` finds it. With several thumbs the slider is a group named by `aria_label`, and
+each thumb takes its own name from `thumbLabels`:
+
+```html
+<label is="so-label" text="Volume" position="top">
+  <span is="so-slider" value="40" name="volume"></span>
+</label>
+<span is="so-slider" value="[20,80]" aria_label="Price" thumb-labels='["From","To"]'></span>
+<span is="so-rating" value="3.5" step="0.5" name="score" aria_label="Score"></span>
+```
+
+Marks as a list are a property, `el.marks = [{ value: 0, label: 'Min' }]`: the `marks` attribute
+is a flag that marks every point of the scale. The `mark` and `thumb` slots of a slider and the
+`icon` slot of a rating are templates, like the `item-*` slots of a list below: each mark, each
+thumb's tooltip and both layers of each star get a copy of their own. A copy finds its data by its
+place — a mark by its index among the `.so-slider__mark` nodes in `el.state.shownMarks`, a thumb by
+its index among the `.so-slider__thumb` nodes in `el.state.thumbs`, a star by its place among the
+stars (counting from one) and its layer by whether it is inside `.so-rating__star-fill`.
+
+A collection is an owner element with item elements inside: tabs with their panels, an accordion
+with its sections, a radio group with its radios, a list box with its options. An item joins the
+collection of the nearest owner above it in the document when it is connected — in document order,
+however the markup got onto the page (`innerHTML`, markup written before the package was imported).
+The owner's collection props (`items`, `engine`, `trackBy`, `mode`) and the item's (`active`,
+`selected`) are attributes and properties of the same elements:
+
+```html
+<div is="so-tabs" closable aria_label="Settings">
+  <div is="so-tabs-item" value="general" text="General" active></div>
+  <div is="so-tabs-item" value="mail" text="Mail"><i slot="leading">✉</i></div>
+  <div is="so-tabs-content" slot="content" value="general">…</div>
+  <div is="so-tabs-content" slot="content" value="mail">…</div>
+</div>
+
+<div is="so-accordion" mode="multiple">
+  <div is="so-accordion-item" value="a" text="First" selected><p>First section</p></div>
+  <div is="so-accordion-item" value="b" text="Second"><b slot="header">Second</b>…</div>
+</div>
+
+<div is="so-radio-group" name="delivery" value="courier">
+  <label is="so-radio-group-item" value="courier">Courier</label>
+  <label is="so-radio-group-item" value="pickup">Pickup</label>
+</div>
+
+<div is="so-list-box" mode="multiple" indicator="start" aria_label="Cities">
+  <div is="so-list-box-item" value="msk" text="Moscow" selected></div>
+  <div is="so-list-box-item" value="spb" text="Saint Petersburg" disabled></div>
+</div>
+```
+
+Panels go to the `content` slot: the default slot of tabs is the tab list, `[role=tablist]`. An
+inactive panel is hidden, and its content is out of the document — its fields are not submitted
+with the form. A radio is a real `<input type="radio">` inside a `<label>` root; attributes you
+write on it (`id`, `aria-label`, `data-*`) move to the input, as on a field, and on a tab, a
+section or a list box option they move to its row — the button that carries the item's state. On
+a list box and on tabs they move to the list itself, `[role=listbox]` or `[role=tablist]`: the
+element is a frame around it, next to the header and footer of a list box or the panels of tabs,
+so `aria-label` names the list and `tabindex="-1"` takes a list box out of the Tab order.
+
+A list box is a single Tab stop: the arrows move through its options, Enter and Space choose. An
+option's row is a button on a `<div>` — `<div is="so-item-row-div">`, a row element with Button's
+markup under a name of its own, since one element name extends one tag: a disabled option stays focusable and is announced
+as unavailable (`aria-disabled`), which a disabled `<button>` would not allow. Its selected mark
+(`indicator`) is the `indicator-icon` slot or a check icon, and it shows on selected options only —
+slot content has no scope to tell selected from not.
+
+Items given as data (`el.items = [...]`, or an `engine`) are drawn by the owner. Slots of those
+items have no scope either, so the owner's `item-*` slots are templates: each item drawn from data
+gets its own copy, in its own slot — `<template slot="item-leading">★</template>` puts a star before
+every tab's text. The item's data is on the item element, `el.ctrl`.
+
+An item drawn from data is part of the owner's markup, like the built-in clear button of a field:
+its events (`so:element:ready`, `so:change:selected`) do not bubble to the owner and above. Listen
+on the item element itself, or take the owner's event, which is usually what an application needs
+— `so:change:value`, `so:item:activated`, `so:item:close`. Items you write in the markup are yours,
+and their events bubble as any element's.
+
+A radio is always a `<label>` root, so a radio cannot go inside `<label is="so-label">` the way
+other adapters write it with `tag="span"`. An item element you add after its owner is built joins
+the collection, but the owner does not move it into its markup — put a tab into `.so-tabs__list`
+yourself. Moving a collection in the document rebuilds it, as any element is rebuilt when it moves:
+markup items join again with what their attributes and properties say, so a choice the user made
+(the active tab, an open section) does not survive the move. Items given as data in your own
+`engine` keep it.
+
+A menu's items live in its panel, and the panel is in `body`: it follows the menu. A removed menu
+takes the panel out of `body`, and a menu moved elsewhere — even with a single DOM call — is rebuilt
+together with its panel, so the items join the rebuilt menu and the keyboard and the pointer reach
+them as before.
+
+A tag set draws its tags — markup items `<div is="so-tags-item">` or data — in a row, and
+`overflow` (`wrap`, `scroll`) tells the theme what to do with the tags that do not fit. A tag's row
+is a button on a `<div>`, and its close button stands next to the row, not inside it. With a
+selection mode (`mode="single"` or `"multiple"`) the set is a single Tab stop and the arrows move
+through the tags; without one, the close buttons are the stops.
+
+A select is a field with a list in a panel, and the panel follows the select as a menu's does.
+Options are markup (`<div is="so-select-item">`, groups `<div is="so-select-group">`) or data.
+Focus stays on the field's `<input>`, and the arrows highlight options through
+`aria-activedescendant`; an option's row is a button on a `<span>` — `<span is="so-item-row-span">`.
+Attributes you write on the select (`aria-label`, `id`, `autocomplete`, `data-*`) go to that
+`<input>`, and so do the select's own accessible name and the links of a form field around it. With
+`mode="multiple"` the chosen options are tags in the field. The field's slots have no scope either:
+your own `field`, `tags` row and `clear` button take what they need from the element —
+`el.ctrl.field` (the input's instance: text, placeholder, `clear()`), `el.state.tags` and
+`el.state.tags_engine`.
+
+```html
+<div is="so-tags" closable mode="multiple">
+  <div is="so-tags-item" value="new" text="New" selected></div>
+  <div is="so-tags-item" value="sale" text="On sale"></div>
+</div>
+
+<div is="so-select" name="city" placeholder="Choose a city" clearable>
+  <div is="so-select-item" value="msk" text="Moscow"></div>
+  <div is="so-select-group" label="North-West">
+    <div is="so-select-item" value="spb" text="Saint Petersburg"></div>
+  </div>
+</div>
+```
+
+Dates are three elements. The date field `<div is="so-date-input">` is a group of parts — day,
+month and year in the locale's order, with `kind="datetime"` also the hour and the minute — and
+each part is a Tab stop of its own; the form gets the date as `YYYY-MM-DD` from a hidden field
+under `name`. The calendar `<div is="so-calendar">` has no content of its own: it draws the days of
+the months on screen (`months`) itself, each a `<td is="so-calendar-item">`, and the title of a
+month is a popover on a `<div>` — `<div is="so-popover-div">`, the same Popover under a name of its
+own — with the month and year picker in its panel. The date picker `<div is="so-date-picker">` is
+a date field and a calendar in a panel at the field, with `mode="range"` the fields of the start
+and the end; the fields and the calendar are its own instances (`el.ctrl.field`, `el.ctrl.start`,
+`el.ctrl.end`, `el.ctrl.calendar`). The language, the first day of the week and the names of the
+months and parts come from the locale provider.
+
+```html
+<div is="so-date-input" name="birthday" aria_label="Date of birth"></div>
+<div is="so-calendar" mode="range"></div>
+<div is="so-date-picker" name="arrival" clearable aria_label="Arrival"></div>
+```
+
+Several dates and a range are not strings, so they are properties:
+`el.value = ['2026-09-10', '2026-09-14']` — the `value` attribute is a single date. A day is the
+calendar's markup, like an item drawn from data: its events do not bubble, and the calendar reports
+the choice with `so:change:value`. The `item` slot is a template, as in a list: each day gets a
+copy, and a copy finds its day on the nearest `.so-calendar-item` (`el.ctrl.date`, `el.ctrl.text`);
+a date picker hands its `item` template on to its calendar.
+
+Pagination draws its pages itself — from `total` and `pageSize`, or from a list of `pages`
+(`el.pages = [{ text: 'Admin' }, …]`) — and has no content of its own. A page is an inner part,
+`<li is="so-pagination-item">` with a button in it; its `item` slot is a template too, and a copy
+finds its page on the nearest `.so-pagination-item` (`el.ctrl`). A page's events do not bubble,
+as with items drawn from data: the pagination reports the page chosen with `so:change:value`. A
+scroller lays its content out in its viewport, between the two buttons; a role for the row and
+what goes with it comes to the viewport as `viewportAria` (`viewport-aria` with JSON, or a
+property):
+
+```html
+<nav is="so-pagination" total="200" value="5" aria_label="Result pages"></nav>
+
+<div is="so-scroller">
+  <button is="so-button" text="First"></button>
+  <button is="so-button" text="Second"></button>
+</div>
+```
+
+A table takes its columns and rows as data only — `columns` and `items` (`el.columns = [...]`, or
+JSON in the attribute), or an `engine` — and draws the column headers and rows itself:
+`<th is="so-table-column">` and `<tr is="so-table-row">` over the core column and row. The element
+you write is the table's viewport, its outer box: your class and style and hiding go there, while
+the `table` inside is the root that the classes, `data-*` and roles go to — and so do the other
+attributes of your markup, `aria-label` and `id` among them, which name the table. Sorting
+buttons, row selection with "select all" (`mode`), column resizing and reordering, the grid mode
+(`grid`) and the sticky head (`sticky-head`) work as in the other adapters; a resized or moved
+column is reported by `so:column:resize` and `so:column:move`.
+
+```html
+<div
+  is="so-table"
+  mode="multiple"
+  aria_label="Staff"
+  columns='[{"field":"name","text":"Name","rowHeader":true,"sortable":true},{"field":"age","text":"Age","align":"end"}]'
+>
+  <template slot="cell"><my-cell></my-cell></template>
+  <p slot="empty">Nobody here yet</p>
+</div>
+```
+
+The `header` and `cell` slots are templates, like the `item-*` slots of a list: each header gets a
+copy of `header` and each cell a copy of `cell`. Without `cell` a cell shows its value as text. A
+copy finds its data on the elements around it: the column on its header (`el.ctrl` of the nearest
+`<th is="so-table-column">`), the row on its row (`el.ctrl` of the nearest `<tr is="so-table-row">`)
+and a cell's column by the cell's place among the row's column cells (`.so-table-row__cell`) in
+the table's `state.shownColumns`; the value is the row's `data[column.field]`. Copies of a row's
+cells are built anew when its record or the columns change; selecting rows leaves them alone.
+
+For thousands of rows or options given as data (`items`, `engine`), put the table, list box or
+select into the `<so-virtual>` window: it draws only the visible ones, with spacers in place of the
+rest. The window is an element of its own tag, without `is` and without a box of its own — the
+list or table inside is laid out as if it were not there; `el.enabled = false` turns it off. A
+list taken out of the window draws all of its items again.
+
+```html
+<so-virtual>
+  <div is="so-list-box" max-rows="8" aria_label="Items"></div>
+</so-virtual>
+```
+
+From JavaScript the element is the component: props are its properties, events are DOM events, and
+a core instance can be handed over as `ctrl` before the element is connected. `instanceof` with the
+element class gives the node with its props typed (TypeScript 5.3+):
+
+```ts
+import { TButton } from '@soxa-ui/core'
+import { TButtonElement } from '@soxa-ui/webc'
+
+const el = document.createElement('button', { is: 'so-button' })
+
+if (el instanceof TButtonElement) {
+  el.ctrl = new TButton({ text: 'Save' })
+  el.addEventListener('so:action:press', () => console.log('pressed'))
+  document.body.append(el)
+}
+```
+
+The language of the strings the library renders itself and the locale for `Intl` come from the
+nearest `<so-locale-provider>` above an element; without one, components are in English. The
+provider has no box of its own (its children lay out as if it were not there), and its `locale` is a
+property — a locale is an object, so there is no attribute. Changing it updates the components in
+place, and a nested provider gives its subtree a language of its own:
+
+```html
+<so-locale-provider>
+  <button is="so-button" text="Save"></button>
+</so-locale-provider>
+
+<script type="module">
+  import { ruRU } from '@soxa-ui/plugins'
+
+  document.querySelector('so-locale-provider').locale = ruRU
+</script>
+```
+
+The application plugs in a theme and an icon pack once, in its entry point:
+
+```ts
+import { useIcons, useTheme } from '@soxa-ui/setup'
+import * as material from '@soxa-ui/icons-material'
+import oren from '@soxa-ui/theme-oren/setup'
+
+import '@soxa-ui/theme-oren'
+
+useIcons(material)
+useTheme(oren)
+```
+
+`@soxa-ui/theme-oren` is the stylesheet of every component. To take only the components your
+pages use, import their stylesheets instead — `@soxa-ui/theme-oren/button.css`,
+`@soxa-ui/theme-oren/select.css`, one per component, each with the shared part of the theme: the stylesheet of a component goes along with the entry of its element (`@soxa-ui/webc/button`)
+(the theme's README, [Only the components you use](https://github.com/youra-h/soxa-ui/tree/main/packages/themes/oren#only-the-components-you-use)).
+
+## Documentation
+
+- [Soxa UI README](https://github.com/youra-h/soxa-ui#readme) — the component set and what each
+  adapter implements so far.
+- [Architecture overview](https://github.com/youra-h/soxa-ui/blob/main/docs/architecture.md) —
+  layers, descriptors, plugins, collections, adapters.
+
+## Public API
+
+The package entry exports application components, their consumer types, the locale provider,
+and the supported icon and toast helpers. Component props, slots, events, refs and core models
+passed through `ctrl` remain the supported ways to customize the UI. Models come from
+`@soxa-ui/core`; theme, icon and external-plugin registration comes from `@soxa-ui/setup`.
+
+Assembly functions, adapter profiles, bindings, generated metadata and rendering templates
+are private implementation details. They are no longer exported from the package entry, and
+there is no public `/internal` entry. Code that imported them must use the component contract
+instead. Building a new adapter component from Soxa's assembly helpers is not a supported
+public SDK.
+
+The same boundary applies to individual element entries such as `@soxa-ui/webc/button`.
+They export the element classes and consumer types, and the documented helpers associated
+with that entry. Importing an entry still registers its elements and required parts.
+
+## License
+
+[MIT](https://github.com/youra-h/soxa-ui/blob/main/LICENSE)