Migrating from older versions

Notices for releases you may be upgrading past. If you are starting fresh, none of this applies — go to the Quick Start instead.

Current releases are described in CHANGELOG.md.

tosijs ^1.10.9 — 1.16.21

tosijs-ui now needs tosijs ^1.10.9; upgrade it alongside. <tosi-table> relies on that release to keep a row in place when its detail opens or closes. On an older tosijs the row jumps, with nothing in the console to say why. dist/iife.js already includes 1.10.9.

iconSvg() throws for a name it cannot draw as one SVG — 1.16.19

A stack (tosi$hat), a composition rule (unLock, spin90Loader), a style suffix other than rotation or flip (check50o), a redirect to a missing icon, or a redirect cycle used to return undefined. Each now throws, naming the problem. A name nothing would draw still returns undefined. Code that relied on undefined for those names should catch, or draw them with icons.<name>() where there is a DOM.

tjs examples compile with tjs-lang 0.14 — 1.16.17

Sites that load tjs-lang from the CDN (no copy of their own installed) now get 0.14.0-rc.5. It refuses some code 0.13 accepted, among others || in a type (a union is |), unsafe var and unsafe eval; tjs-lang's changelog lists them. Fix the example, or install tjs-lang@0.13.13 in your project: the build ships the installed copy with your pages and they prefer it to the CDN.

<tosi-md> sanitizes by default — 1.16.0

A <tosi-md> with no sanitize attribute now strips executable content from the rendered markdown, and unwraps custom elements (their content stays, the element goes). 1.15.3 logged a console warning announcing this.

• Markdown you control (your own docs, posts you wrote) that embeds HTML such as a <form>, <iframe>, <style> or <script>: set sanitize="off" on that element to keep the old behaviour.
• Markdown that embeds your own display components (<tosi-icon>, a tag chip): keep sanitizing and allow them by name, allowed-elements="tosi-icon tosi-tag".
• Markdown from anyone else (comments, issue bodies, API data): leave it sanitized. That is the point of the change: unsanitized, such text can run script in your page.

tosi-md, tosi-example and tosi-doc-system can't be allowed; they render raw HTML or run code.

tosijs 1.10: components are typed from their attributes — 1.16.0

tosijs-ui now needs tosijs ^1.10.3; upgrade it alongside. Nothing changes at runtime. What changes is what TypeScript knows about a component instance:

const rating = tosiRating()
rating.max        // number — was unknown to TypeScript on tosijs 1.9
rating.maxx       // now a type error (a typo)
rating.readonly = 'yes' // now a type error (wrong type)

So TypeScript code that read or wrote a property a component does not have, or with the wrong type, stops compiling. That is the point: those were bugs the old typing hid. (Our own migration found one: filter-builder read a selectedIndex that <tosi-select> never had, and returned an empty string every time.)

Your own components built on tosijs Component get the same benefit by moving static initAttributes into the class header, as tosijs's migration notes describe:

// before
class MyWidget extends Component<MyParts> {
  static initAttributes = { size: 3, label: '' }
}
// after
class MyWidget extends withAttributes({ size: 3, label: '' })<MyParts> {}

Element-creator arguments are not typed by this: tosiRating({ maxx: 1 }) still compiles.

The doc-system cluster moved off the root barrel — 1.14.0

If you import <tosi-code>, the doc browser, <tosi-doc-system> or <live-example> from the package root, change the import. Everything else is unaffected.

// before
import { tosiCode, createDocBrowser } from 'tosijs-ui'

// after — the same things, by subpath
import { tosiCode } from 'tosijs-ui/code-editor'
import { createDocBrowser } from 'tosijs-ui/doc-browser'

This one can fail at RUNTIME rather than at build time. A bare import 'tosijs-ui' used to register <tosi-code>, <tosi-doc-system> and <live-example> as a side effect; it no longer does, so a page using those tags renders nothing and the console says only that an unknown element was not upgraded. If a custom element stopped appearing after this upgrade, this is why.

Why: those four modules pull CodeMirror and tjs-lang, and because the package has no sideEffects field (correctly — elementCreator() registers elements at import time, so a blanket sideEffects: false would tree-shake a bare import down to zero registrations) a bundler had to treat them as reachable from any import of the barrel. Measured on a real 15 MB app bundle: 1.35 MB / 8.9% saved. The doc site and CDN <script> users are unaffected — the IIFE imports all four explicitly.

Validation is supplied, not imported — 1.11.0

If you use <tosi-schema-form>, <tosi-crud> or an editable <tosi-table> from ESM, add one line. Nothing else changes, and nothing breaks silently — a form with no validator warns in the console and reports validationAvailable === false.

import { setSchemaValidator } from 'tosijs-ui'
import { validate, inferSchema, unenforcedKeywords } from 'tosijs-schema' // ^1.8.0

setSchemaValidator({ validate, inferSchema, unenforcedKeywords })

Pass all three. unenforcedKeywords is what lets a field ask the validator "do you actually check this keyword?" — omit it and the form falls back to a list frozen at tosijs-schema 1.7.0 and labels every oneOf and exclusiveMinimum field "not validated" while it is being validated.

Nothing to do if you load the CDN <script> build or use tosijs-ui/site — both register it themselves.

Why it changed. A bare import('tosijs-schema') in shipped code is either resolved by your bundler — which fails the build for anyone who did not install it, including people using only <tosi-table> — or left external, which cannot resolve in a browser and kills validation for everyone. Both were measured; there is no third option. Asking for two functions instead of a package also means anything can supply them: an Ajv wrapper, a house validator, a stub.

tjs-lang peer moves to ^0.13.1 — 1.11.0

Only affects you if you have tjs-lang installed (it is an optional peer, for live examples and .tjs sources). ^0.12.0 could not reach 0.13.x — caret pins the minor on 0.x — so an adopter on current tjs-lang hit a hard ERESOLVE.

0.12.0 is deprecated on npm, and the deprecation names this exact combination: *"tosijs-schema

=1.5.0 breaks the battery atoms' output validation in these versions. Upgrade to 0.13.1."* Since 1.11.0 also floors tosijs-schema at ^1.8.0, staying on 0.12.0 is the pairing the upstream author deprecated it over.

Edit links are shorter and shorter-lived — 1.11.0

Only affects tosijs-ui/site users running the tosijs-tunnel bin. The token is now 7 Crockford base32 characters instead of 22, and linkTtlMinutes defaults to 5 rather than 15. A link minted by an older dev server is not redeemable by a newer one; both live in memory, so this only matters across a restart mid-session.

The token is case-insensitive and forgives the lookalikes — I/L read as 1, O as 0, hyphens ignored — because it is meant to be read off one screen and typed on another.

Changed again in 1.14.0: the token is now eight letters with no digits. See the token is eight letters.

Cannot find module under Node — fixed in 1.9.1

If an import of tosijs-ui (any entry point) fails under Node with something like:

Cannot find module '.../dist/doc-system/site/site-config'
imported from '.../dist/doc-system/site/index.js'

you are on 1.9.0 or earlier. Upgrade to 1.9.1; there is no workaround on the older versions and no code change needed on yours.

Shipped dist/ used extensionless relative imports (from './site-config'). Bun resolves those; Node ESM does not — it requires the extension. So the package worked perfectly under bun and failed on the very first import under Node, on every entry point, going back well before 1.8.0.

Not deprecated, deliberately. The failure is loud and immediate — it stops your build on the first import, so nobody is quietly running broken code. A deprecation warning would only nag the bun users for whom every version worked. If you are pinned to an older line and need this backported, open an issue; it is a mechanical change.

Worth knowing while you are here, because the error messages name symptoms rather than causes:

Those three are unchanged in 1.9.1 and are not bugs; only the module resolution was.

⚠️ Breaking change in 1.7.0 — <tosi-code> (ACE → CodeMirror 6)

1.7.0 is a breaking release shipping under a minor version, deliberately. <tosi-code> moved from ACE to CodeMirror 6. value, mode, the change event, disabled, and undo/redo are unchanged; the ACE-era theme and options props are removed: setting one warns once and does nothing. Dark mode is now automatic (body.darkmode) and styling comes from --code-bg / --text-color. The 2.0 name is reserved for the tjs-native tosijs port, so this ships as 1.7.0 — pin tosijs-ui@1.6 to defer. Full detail and rationale in CHANGELOG.md.

Migrating to v1.3.0

v1.3.0 completes the rename from xinjs-ui to tosijs-ui. All custom element tags now use the tosi- prefix and all exports use Tosi*/tosi* names.

Breaking changes

• Custom element tags have changed from <xin-*> to <tosi-*>. For example: <xin-select> is now <tosi-select>, <xin-icon> is now <tosi-icon>, <xin-example> is now <tosi-example>, etc.
• CSS selectors targeting old tag names (e.g. xin-select { ... }) must be updated.
• CSS custom properties in component styleSpec objects retain --xin-* fallbacks for backward compatibility, but new code should use --tosi-*.

Deprecated exports still work

The old xin* JavaScript exports (xinSelect, xinTabs, xinTable, etc.) remain available and will continue to work. Most log a runtime deprecation warning; a few are silent aliases marked with JSDoc @deprecated. They will be removed in a future major version.

Migration checklist

1. Search your HTML for <xin- and replace with <tosi-
2. Search your CSS for xin- selectors and update to tosi-
3. Search your JS/TS for xinSelect, xinTabs, etc. and switch to tosiSelect, tosiTabs, etc.
4. Search for --xin- CSS variable overrides and switch to --tosi-