mirror of
https://github.com/tabler/tabler.git
synced 2026-10-12 05:06:55 +04:00
Add the 1.6 upgrade guide and group the upgrade guides per release (#3085)
This commit is contained in:
Paweł Kuna authored and 
GitHub committed
1 parent
a984752c84
commit
6bd3fff3a9
7 files changed
+425
-5
No files matched your search
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: upgrade-guide
|
||||
description: >-
|
||||
Write or update the upgrade guide for a Tabler release — the page under `docs/content/ui/getting-started/upgrade/<version>.mdx` that lists every breaking change with a before and after example. Use whenever the user asks for a migration or upgrade guide, release migration notes, or "what breaks in X.Y", and
|
||||
proactively before a release when `.changeset/` holds entries that remove or rename something. Covers where the facts come from, the page skeleton, the menu and ordering rules, and how to check the result.
|
||||
---
|
||||
|
||||
# Upgrade guides
|
||||
|
||||
One page per release that changes something a user has to touch in their own code. The pages live in `docs/content/ui/getting-started/upgrade/`, the index there lists them as cards, and the docs menu has an "Upgrade" group next to "Frameworks".
|
||||
|
||||
```
|
||||
docs/content/ui/getting-started/upgrade/
|
||||
index.mdx # "Upgrade" — intro + <DocsChildrenCards />, never lists versions by hand
|
||||
1-5.mdx # "Upgrade to 1.5", order: 2
|
||||
1-6.mdx # "Upgrade to 1.6", order: 1
|
||||
```
|
||||
|
||||
A release with no breaking change gets no page. Say so in the changelog instead.
|
||||
|
||||
## 1. Collect the facts first
|
||||
|
||||
The guide is only as good as the list of changes behind it. Never write it from memory or from the changelog summary alone.
|
||||
|
||||
1. Find the base commit: the `chore: update versions` commit of the previous release (`git log --oneline --grep "update versions"`), or the last release tag when tags exist.
|
||||
2. Read every changeset in `.changeset/*.md`. The `minor` ones with "Removed", "Renamed", "Replaced" or "Updated" are the candidates.
|
||||
3. Diff the things a user can depend on, from that base to `HEAD`:
|
||||
- Sass variables and functions: `git diff <base> HEAD -- core/scss | grep -E '^[-+][$@]'`, then split into removed, added and changed. A variable that is removed from `@use … with (…)` is a compile error for the user, so every removed `$var` must be on the page.
|
||||
- Custom properties: look at `core/scss/_props.scss` and `_root.scss` for removed `--*` names. Remember the runtime prefix is `--tblr-`, and the sources are written without it.
|
||||
- JavaScript exports: `git diff <base> HEAD -- core/js/tabler.ts core/js/src/*.ts | grep '^[-+]export'`. A removed export, a renamed data attribute or a changed global breaks user code.
|
||||
- Third-party libraries: `core/libs.json` and `core/package.json`. A library that left `dist/libs` breaks every `<script src="/dist/libs/…">`.
|
||||
- Class names: `git diff <base> HEAD -- core/scss | grep -E '^-\.[a-z]'` for removed selectors, and the `check-markup-classes` baseline when it changed.
|
||||
4. Read the docs diff of each PR (`git show <sha> -- docs`) — the component page usually already has the new usage, and the guide should agree with it word for word.
|
||||
5. Verify every name you're about to print against the current source. A wrong attribute in a guide is worse than no guide.
|
||||
|
||||
## 2. Page skeleton
|
||||
|
||||
Copy the structure of the newest existing guide. The order is fixed so readers can compare releases:
|
||||
|
||||
```text
|
||||
---
|
||||
title: Upgrade to 1.7
|
||||
summary: Move a project from Tabler 1.6 to 1.7. …
|
||||
description: Upgrade guide from Tabler 1.6 to 1.7 with all breaking changes, …
|
||||
added-in: '1.7.0'
|
||||
order: 1
|
||||
related: [/ui/getting-started/upgrade/1-6, /ui/getting-started/customize]
|
||||
---
|
||||
|
||||
Intro: how big the upgrade is and the two or three things most likely to bite.
|
||||
Link to the previous guide for people more than one version behind.
|
||||
|
||||
## Overview "If you… | You need to…" table, one row per change, links to sections
|
||||
## Update the package npm + CDN snippet with the exact version
|
||||
## <One per change> one section per breaking change: before/after, then what to do
|
||||
## Sass changes only for people compiling scss/ themselves: removed variables table,
|
||||
removed functions, changed defaults
|
||||
## Visual changes not breaking, but visible: bullets with a bold lead
|
||||
## What is new in 1.7 short bullet list with links to the component pages, then a changelog link
|
||||
```
|
||||
|
||||
Rules for the body:
|
||||
|
||||
- Every breaking change gets a `diff` or a "1.6 / 1.7" pair of code blocks. A sentence without an example is not enough.
|
||||
- Show the fix, not only the removal. "Removed `$x`" is half a row; "use `$y`" or "nothing, drop it" completes it.
|
||||
- Removed Sass variables and functions go in a table, even when the section above already explains them. Readers grep the table.
|
||||
- Deprecated aliases (`.form-hint` → `.form-text`) are listed under a "renamed" heading with "the old name still works", never among the breaking changes.
|
||||
- The `summary` and `description` must not contain `: ` — unquoted YAML breaks the build.
|
||||
- Simple English, contractions allowed, no marketing. The `write-docs` skill has the tone rules.
|
||||
|
||||
## 3. Ordering and the index
|
||||
|
||||
- `order` in the front matter drives the cards on the index and the menu is hand-written, so both must agree: newest release first. When adding `1-7.mdx`, give it `order: 1` and bump the older ones by one.
|
||||
- `index.mdx` renders `<DocsChildrenCards url="/ui/getting-started/upgrade" />`; do not add cards or a version list by hand.
|
||||
- Add the new page to `shared/data/docs.json` under the `"Upgrade"` group, first in `children`, `"url": "/ui/getting-started/upgrade/1-7"` with no trailing slash. The group is a level-two entry next to "Frameworks", because the docs menu only nests two levels below a section.
|
||||
- Update `related` on the previous guide's neighbours when they point at the old newest page.
|
||||
|
||||
## 4. Renaming or moving a guide
|
||||
|
||||
A guide's URL is linked from release notes on GitHub and npm, so it must never just disappear. Add the old path to `docs/lib/redirects.ts` with `status: 301`. The middleware reads the same map, so nothing else is needed.
|
||||
|
||||
## 5. Check
|
||||
|
||||
1. Restart the docs dev server: a new page 404s until it does (`astro-dev` skill, port 3010).
|
||||
2. Open `/ui/getting-started/upgrade` and the new page. Check the sidebar highlights the entry, the cards are in the right order, and every anchor in the overview table resolves.
|
||||
3. `pnpm run check:docs-links` — dead internal links fail it.
|
||||
4. `pnpm run lint:md` for the markdownlint rules on `docs/content`. `docs.json` is tab-indented and outside the prettier scope, so don't run prettier on it.
|
||||
|
||||
Do not write a changeset for the guide unless asked; the `generate-changeset` skill covers that when the PR is opened.
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
"@tabler/docs": minor
|
||||
---
|
||||
|
||||
Added the upgrade guide for Tabler 1.6 and moved the upgrade guides to `/ui/getting-started/upgrade/` with one page per release.
|
||||
@@ -2,7 +2,7 @@
|
||||
title: RTL support
|
||||
summary: Turn on right-to-left layouts for Arabic, Hebrew, and other RTL languages, and learn which styles flip automatically.
|
||||
description: How to enable RTL in Tabler, which stylesheet to load, how the RTL CSS is generated and which utilities are direction-aware.
|
||||
related: [/ui/getting-started/upgrade, /ui/components/popover]
|
||||
related: [/ui/getting-started/upgrade/1-5, /ui/components/popover]
|
||||
---
|
||||
import Example from '@components/Example.astro';
|
||||
|
||||
|
||||
+1
@@ -3,6 +3,7 @@ title: Upgrade to 1.5
|
||||
summary: Move a project from Tabler 1.4 to 1.5. Every breaking change is listed with a before and after example for markup, JavaScript and Sass.
|
||||
description: Upgrade guide from Tabler 1.4 to 1.5 with all breaking changes, renamed classes and Sass updates.
|
||||
added-in: '1.5.0'
|
||||
order: 2
|
||||
related: [/ui/getting-started/rtl]
|
||||
---
|
||||
|
||||
@@ -0,0 +1,297 @@
|
||||
---
|
||||
title: Upgrade to 1.6
|
||||
summary: Move a project from Tabler 1.5 to 1.6. The breaking changes are listed with a before and after example for CSS, JavaScript and Sass.
|
||||
description: Upgrade guide from Tabler 1.5 to 1.6 with all breaking changes, removed color variables, the new JavaScript components and Sass updates.
|
||||
added-in: '1.6.0'
|
||||
order: 1
|
||||
related: [/ui/getting-started/upgrade/1-5, /ui/getting-started/customize]
|
||||
---
|
||||
|
||||
Tabler 1.6 is a much smaller step than 1.5 was. If you only load the compiled files from `dist/`, the upgrade usually takes a few minutes. There are three things that can bite you, and they all live in your own code, not in Tabler's: any `rgba(var(--tblr-*-rgb), …)` in your CSS, any call to the old `autosize()`, `countUp` or `ClipboardJS` globals, and any use of `tabler.tabler.getColor()`.
|
||||
|
||||
Projects that compile Tabler from the Sass sources should also read [Sass changes](#sass-changes).
|
||||
|
||||
If you're coming from 1.4 or older, do the [1.5 upgrade](/ui/getting-started/upgrade/1-5) first.
|
||||
|
||||
## Overview
|
||||
|
||||
Use this table to find the changes that affect you.
|
||||
|
||||
If you…|You need to…
|
||||
---|---
|
||||
Use `--tblr-primary-rgb` or any `--tblr-*-rgb` variable|Replace it with `color-mix()`, see [Color variables](#rgb-color-variables-are-gone)
|
||||
Load `dist/libs/autosize` or `dist/libs/countup.js`|Remove the script tags, both are part of `tabler.js` now
|
||||
Call `autosize(el)` or `new countUp.CountUp(...)` yourself|Switch to `tabler.Autosize` and `tabler.CountUp`
|
||||
Load `dist/libs/clipboard` or call `new ClipboardJS(...)`|Switch to the `Clipboard` component, see [Clipboard](#clipboard-is-built-in)
|
||||
Hide `path:first-child` in `.accordion-button-toggle-plus` from your own CSS|Drop that rule, see [Visual changes](#visual-changes)
|
||||
Call `tabler.tabler.getColor()` or `tabler.tabler.hexToRgba()`|Read the variable yourself, see [Removed JavaScript helpers](#removed-javascript-helpers)
|
||||
Use `.form-hint`|Rename to `.form-text` (the old name still works)
|
||||
Override `$form-switch-bg-image` or the toggler icon variables|See [Masked icons](#masked-icons)
|
||||
Override `$theme-colors-rgb` or use `theme-color-lighter()`|See [Sass changes](#sass-changes)
|
||||
Rely on the empty gutter next to the scrollbar|See [Visual changes](#visual-changes)
|
||||
Set `data-mask` or `data-countup` from code after page load|Create the component instead, see [Plugins are components now](#plugins-are-components-now)
|
||||
|
||||
## Update the package
|
||||
|
||||
Install the new version:
|
||||
|
||||
```sh
|
||||
npm install --save @tabler/core@1.6.0
|
||||
```
|
||||
|
||||
Or update the CDN links:
|
||||
|
||||
```html
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/@tabler/core@1.6.0/dist/css/tabler.min.css"
|
||||
/>
|
||||
<script src="https://cdn.jsdelivr.net/npm/@tabler/core@1.6.0/dist/js/tabler.min.js"></script>
|
||||
```
|
||||
|
||||
## RGB color variables are gone
|
||||
|
||||
This is the change most likely to affect a custom stylesheet.
|
||||
|
||||
Tabler used to emit an RGB triplet next to every color, so you could build a transparent version with `rgba()`:
|
||||
|
||||
```css
|
||||
/* 1.5 */
|
||||
.my-highlight {
|
||||
background-color: rgba(var(--tblr-primary-rgb), 0.2);
|
||||
}
|
||||
```
|
||||
|
||||
Those `--tblr-*-rgb` variables (and `--tblr-*-lt-rgb`) aren't emitted any more. Tabler mixes its own tints, shades and translucent surfaces at runtime with `color-mix()`, and your CSS can do the same:
|
||||
|
||||
```css
|
||||
/* 1.6 */
|
||||
.my-highlight {
|
||||
background-color: color-mix(in oklab, var(--tblr-primary) 20%, transparent);
|
||||
}
|
||||
```
|
||||
|
||||
A quick way to find every place that needs a change is to grep your project for `-rgb)`.
|
||||
|
||||
There's a nice side effect. Because everything is derived from `--tblr-primary` at runtime, overriding that one variable is enough to recolor the whole theme. In 1.5 you also had to set `--tblr-primary-rgb` by hand, or hover states and focus rings would keep the old color. That step is gone:
|
||||
|
||||
```diff
|
||||
:root {
|
||||
--tblr-primary: #f11d46;
|
||||
- --tblr-primary-rgb: 241, 29, 70;
|
||||
}
|
||||
```
|
||||
|
||||
`--tblr-primary-lt`, `--tblr-primary-darken` and the other derived variables still exist, they're just computed with `color-mix()` now.
|
||||
|
||||
### The palette is defined in oklch
|
||||
|
||||
The color values themselves moved from hex to `oklch()`. `--tblr-primary` used to resolve to `#066fd1`, now it resolves to `oklch(54.6% 0.1724 254.2deg)`. The colors look the same. It only matters if you read a variable from JavaScript and expect a hex string, see [Removed JavaScript helpers](#removed-javascript-helpers) below.
|
||||
|
||||
Every browser that could run Tabler 1.5 supports `oklch()`, so the [minimum versions](/ui/getting-started/browser-support) don't change.
|
||||
|
||||
## Plugins are components now
|
||||
|
||||
In 1.5, a few plugins were small scripts that ran once on page load and reached for a global library. In 1.6 each of them is a proper component with the same API as the Bootstrap ones: `getInstance()`, `getOrCreateInstance()`, `dispose()`, and events with a `.bs.` suffix.
|
||||
|
||||
Component|Attribute|Docs
|
||||
---|---|---
|
||||
`tabler.Autosize`|`data-bs-toggle="autosize"`|[Autosize](/ui/plugins/autosize)
|
||||
`tabler.CountUp`|`data-countup`|[Countup](/ui/plugins/countup)
|
||||
`tabler.InputMask`|`data-mask`|[Input mask](/ui/plugins/input-mask)
|
||||
`tabler.Sortable`|`data-sortable`|[Table](/ui/components/table)
|
||||
`tabler.SwitchIcon`|`data-bs-toggle="switch-icon"`|[Switch icon](/ui/components/switch-icon)
|
||||
|
||||
Markup with data attributes keeps working as it did. Tabler still finds every element on page load and creates the component for it. What changes is the JavaScript side.
|
||||
|
||||
### Autosize and countUp.js are bundled
|
||||
|
||||
Tabler no longer depends on the `autosize` and `countup.js` packages. Both were rewritten inside `tabler.js`, so they don't need a separate script and don't exist in `dist/libs` any more. Remove them from your pages:
|
||||
|
||||
```diff
|
||||
- <script src="/dist/libs/autosize/dist/autosize.min.js"></script>
|
||||
- <script src="/dist/libs/countup.js/dist/countUp.umd.js"></script>
|
||||
<script src="/dist/js/tabler.min.js"></script>
|
||||
```
|
||||
|
||||
And from your dependencies, if you installed them for Tabler:
|
||||
|
||||
```sh
|
||||
npm uninstall autosize countup.js
|
||||
```
|
||||
|
||||
If you called the libraries directly for elements added later, switch to the components:
|
||||
|
||||
```diff
|
||||
- autosize(document.getElementById('message'));
|
||||
+ new tabler.Autosize(document.getElementById('message'));
|
||||
|
||||
- autosize.update(document.getElementById('message'));
|
||||
+ tabler.Autosize.getInstance(document.getElementById('message')).update();
|
||||
|
||||
- new countUp.CountUp('total', 1500, { duration: 4 }).start();
|
||||
+ new tabler.CountUp(document.getElementById('total'), { duration: 4 });
|
||||
```
|
||||
|
||||
The `CountUp` component reads the target number from the element's text, like the `data-countup` attribute always did. It respects `prefers-reduced-motion` on its own, so you can drop the workaround from the 1.5 docs that removed `data-countup` for those users.
|
||||
|
||||
Options you passed to countUp.js in `data-countup` keep their names: `startVal`, `duration`, `decimalPlaces`, `useEasing`, `useGrouping`, `separator`, `decimal`, `prefix` and `suffix`. Anything outside that list is ignored.
|
||||
|
||||
### IMask and SortableJS stay external
|
||||
|
||||
`InputMask` and `Sortable` are thin wrappers, so you still install [IMask](/ui/plugins/input-mask) and [SortableJS](/ui/components/table) yourself and load them before `tabler.js`. Nothing changes there. What's new is that the component keeps a reference to the library instance, so you can reach it from `getInstance()` instead of keeping your own.
|
||||
|
||||
### Clipboard is built in
|
||||
|
||||
The `clipboard` package is gone from the dependencies and from `dist/libs`. A page that loads `dist/libs/clipboard/dist/clipboard.min.js` gets a 404 after the upgrade. Tabler has its own [Clipboard](/ui/plugins/clipboard) component now, written on top of the browser's `navigator.clipboard` API, so there is nothing to load:
|
||||
|
||||
```diff
|
||||
- <script src="/dist/libs/clipboard/dist/clipboard.min.js"></script>
|
||||
<script src="/dist/js/tabler.min.js"></script>
|
||||
```
|
||||
|
||||
```sh
|
||||
npm uninstall clipboard
|
||||
```
|
||||
|
||||
The markup changes too. A copy button carries `data-bs-toggle="clipboard"` and points at its source with `data-bs-target` or `data-bs-text`, and the two states live in the button:
|
||||
|
||||
```diff
|
||||
- <button type="button" class="btn" data-clipboard-target="#api-key">Copy</button>
|
||||
+ <button type="button" class="btn" data-bs-toggle="clipboard" data-bs-target="#api-key">
|
||||
+ <span class="clipboard-label">Copy</span>
|
||||
+ <span class="clipboard-feedback">Copied</span>
|
||||
+ </button>
|
||||
```
|
||||
|
||||
If you created the library yourself, switch to the component and its events:
|
||||
|
||||
```diff
|
||||
- const clipboard = new ClipboardJS('.btn-copy');
|
||||
- clipboard.on('success', () => showToast('Copied'));
|
||||
+ document.querySelectorAll('.btn-copy').forEach((button) => {
|
||||
+ new tabler.Clipboard(button);
|
||||
+ button.addEventListener('copied.bs.clipboard', () => showToast('Copied'));
|
||||
+ });
|
||||
```
|
||||
|
||||
The browser API works in secure contexts only, so on plain `http` the copy fails and `error.bs.clipboard` fires. `localhost` counts as secure.
|
||||
|
||||
### New events
|
||||
|
||||
Every component fires events on its element. If you used to poll or wrap the library callbacks, these are the ones to listen for:
|
||||
|
||||
Component|Events
|
||||
---|---
|
||||
`Autosize`|`resized.bs.autosize`
|
||||
`Clipboard`|`copied.bs.clipboard`, `error.bs.clipboard`
|
||||
`CountUp`|`start.bs.countup`, `complete.bs.countup`
|
||||
`SwitchIcon`|`toggle.bs.switch-icon` before the state changes, cancelable with `event.preventDefault()`, then `change.bs.switch-icon`. Both carry the new state in `event.active`.
|
||||
|
||||
## Removed JavaScript helpers
|
||||
|
||||
`tabler.js` used to expose a small `tabler` namespace next to the components, with `prefix`, `getColor()` and `hexToRgba()`. It was never documented, but it was easy to find in the source, so some projects picked it up for chart colors:
|
||||
|
||||
```js
|
||||
/* 1.5 */
|
||||
const color = tabler.tabler.getColor('primary', 0.5);
|
||||
```
|
||||
|
||||
The namespace was removed, together with the `prefix` and `hexToRgba` exports. The helper only worked while colors were hex strings, and the palette is `oklch()` now. Read the variable yourself, and use `color-mix()` when you need transparency:
|
||||
|
||||
```js
|
||||
/* 1.6 */
|
||||
const primary = getComputedStyle(document.body).getPropertyValue('--tblr-primary').trim();
|
||||
const primaryHalf = `color-mix(in oklab, ${primary} 50%, transparent)`;
|
||||
```
|
||||
|
||||
Every place that accepts a CSS color, including canvas and most chart libraries that render to SVG, takes the `oklch()` string as it is. A library that parses colors itself and only understands hex or `rgb()` needs the value converted first. For ApexCharts you don't have to do anything, its theme reads the `--tblr-chart-*` variables since 1.5.
|
||||
|
||||
## Form hint is form text
|
||||
|
||||
Tabler had its own `.form-hint` class for the helper text under a field, while Bootstrap calls the same thing `.form-text`. 1.6 uses the Bootstrap class and keeps `.form-hint` as a deprecated alias, so nothing breaks. Rename when you touch the markup anyway:
|
||||
|
||||
```diff
|
||||
- <small class="form-hint">We'll never share your email.</small>
|
||||
+ <div class="form-text">We'll never share your email.</div>
|
||||
```
|
||||
|
||||
The three `$form-hint-*` Sass variables are gone. `.form-text` uses Bootstrap's `$form-text-margin-top`, `$form-text-font-size` and `$form-text-color`.
|
||||
|
||||
## Masked icons
|
||||
|
||||
The check mark in a checkbox, the dot in a radio, the knob of a switch, the navbar toggler and the carousel arrows used to be SVG background images with the color baked into the SVG. They are CSS masks now, painted with `background-color`. That's what lets them follow the color variables at runtime, and it's why the same checkbox looks right in every theme without a dark variant of the image.
|
||||
|
||||
For most projects this is invisible. It matters if you customized those icons in Sass:
|
||||
|
||||
- `$form-switch-bg-image`, `$form-switch-bg-image-dark`, `$form-switch-checked-bg-image`, `$form-switch-checked-bg-position` and `$form-switch-focus-bg-image` are gone. The switch knob is a plain circle drawn with CSS. Its color comes from `$form-switch-color`, its size from `--tblr-form-switch-knob-size`.
|
||||
- `$form-check-input-checked-bg-image-dark` is gone, because one image now works for both modes. The icon color is `$form-check-input-checked-color`, or `--tblr-form-check-icon-color` at runtime.
|
||||
- `$navbar-light-toggler-icon-bg` and `$navbar-dark-toggler-icon-bg` were merged into `$navbar-toggler-icon-bg`. The color comes from `--tblr-navbar-toggler-icon-color`.
|
||||
|
||||
If you replaced one of the SVGs with your own, keep the shape but drop the `fill` and `stroke` colors from it. The mask only looks at the alpha channel, so any color inside the SVG is ignored.
|
||||
|
||||
## Sass changes
|
||||
|
||||
Only relevant if you compile `scss/tabler.scss` yourself.
|
||||
|
||||
### Removed variables
|
||||
|
||||
Variable|What to do instead
|
||||
---|---
|
||||
`$theme-colors-rgb`|Nothing. Tabler doesn't emit RGB triplets, and neither should your code.
|
||||
`$form-hint-margin-top`, `$form-hint-label-offset`, `$form-hint-control-margin-top`|Use `$form-text-margin-top` and friends.
|
||||
`$form-switch-bg-image`, `$form-switch-bg-image-dark`, `$form-switch-checked-bg-image`, `$form-switch-checked-bg-position`, `$form-switch-focus-bg-image`|See [Masked icons](#masked-icons).
|
||||
`$form-check-input-checked-bg-image-dark`|See [Masked icons](#masked-icons).
|
||||
`$navbar-light-toggler-icon-bg`, `$navbar-dark-toggler-icon-bg`|Use `$navbar-toggler-icon-bg`.
|
||||
|
||||
Setting a removed variable in `@use … with (…)` is a compile error in Sass, so you'll notice right away.
|
||||
|
||||
### Removed functions
|
||||
|
||||
`theme-color-lighter()` and `theme-color-darker()` computed a tint and a shade at compile time. They were removed with the RGB variables. Two pairs of functions replace them:
|
||||
|
||||
- `mix-color($a, $b, $weight)` and `adjust-lightness($color, $amount)` work at compile time on Sass colors and return an sRGB color, so the result can still feed `color-contrast()` or `luminance()`.
|
||||
- `mix-color-css($a, $b, $weight)` and `adjust-lightness-css($color, $amount)` return a `color-mix()` or a relative `oklch()` expression, so the result follows `--tblr-*` overrides in the browser. Use these where the value is emitted as it is.
|
||||
|
||||
```diff
|
||||
- $my-hover: theme-color-darker($primary);
|
||||
+ $my-hover: adjust-lightness-css(var(--primary), -10%);
|
||||
```
|
||||
|
||||
`url-svg()`, `varify()`, `map-get-multiple()`, `map-merge-multiple()`, `breakpoint-prev()` and the `media-breakpoint-down-than` mixin were unused inside Tabler and were removed too. If you called one of them, copy it into your own project from the 1.5 sources.
|
||||
|
||||
### Variables that turned into color-mix()
|
||||
|
||||
A lot of Bootstrap variables that were plain Sass colors are now `color-mix()` expressions on top of a custom property. `$primary-bg-subtle`, for example, used to be `tint-color($primary, 80%)`, and is now `mix-color-css(var(--white), var(--primary), 80%)`. The same happened to the `*-text-emphasis`, `*-border-subtle`, `$focus-ring-color`, `$input-focus-border-color` and most `rgba($black, …)` shadows.
|
||||
|
||||
You can still override them with anything Sass accepts. Just be aware that a Sass color function such as `darken()` or `rgba()` won't work on their default values any more, because the default isn't a color, it's a string with `var()` inside.
|
||||
|
||||
## Visual changes
|
||||
|
||||
None of these break markup, but they change how a page looks or scrolls. Worth a quick look at your screens after the upgrade.
|
||||
|
||||
- **No reserved scrollbar gutter.** 1.5 set `scrollbar-gutter: stable` on `html`, which left an empty strip on the right of the navbar on pages too short to scroll. That rule is gone. Layout shifts between short and long pages are back to the browser default, which on macOS and most mobile browsers means none.
|
||||
- **Scroll chaining is contained.** Scrolling to the end of a modal body, an offcanvas body or a scrollable dropdown no longer scrolls the page behind it.
|
||||
- **Native `<dialog>` gets a backdrop.** A `<dialog>` opened with `showModal()` has the same backdrop as a modal, and `.modal-blur` on it blurs the page behind.
|
||||
- **Colors are computed in oklab.** Tints, shades and hover states are mixed in the `oklab` color space instead of `sRGB`. Mixed colors are a touch less muddy, mostly noticeable in the lighter `-lt` backgrounds. Solid colors are the same as before.
|
||||
- **`.form-selectgroup-label`** no longer applies the icon-only margin to icons nested deeper inside the label.
|
||||
- **Striped tables respect custom backgrounds.** A `<tr>` or `<td>` with `.bg-*`, `.table-*`, `.text-bg-*` or an inline `background` keeps that background inside `.table-striped` and `.table-striped-columns`. Before, the stripe painted over it.
|
||||
- **The accordion plus toggle rotates.** `.accordion-button-toggle-plus` used to hide the first `<path>` of the inline SVG when the item was open, which didn't work with sprite icons or icon fonts. It now rotates the whole icon a quarter turn into a close icon. If your own CSS targeted `path:first-child` in that toggle, remove it. Any icon source works, but the icon has to be a plus for the rotation to make sense.
|
||||
|
||||
## What is new in 1.6
|
||||
|
||||
Besides the changes above, 1.6 adds:
|
||||
|
||||
- [Legend](/ui/components/legend), a colored marker plus label for chart series, with an interactive mode that toggles series on click.
|
||||
- [Sparkline](/ui/components/sparkline), inline SVG line, bar and circle charts rendered from `data-bs-values`, with no chart library.
|
||||
- [Password strength](/ui/forms/strength), a segmented meter that scores the password as the user types and fires `change.bs.strength`.
|
||||
- [OTP input](/ui/forms/otp-input), grouped single-character slots for one-time codes, with masking and validation states.
|
||||
- [Clipboard](/ui/plugins/clipboard), a copy button with a copied state, built on the browser API, see above.
|
||||
- [Confetti](/ui/components/confetti), a shower of pieces from any button with `data-bs-toggle="confetti"`.
|
||||
- A `switch-icon-loading` state for [Switch icon](/ui/components/switch-icon). Pass a promise to `event.wait()` in `toggle.bs.switch-icon` and the button shows a spinner until it settles.
|
||||
- `Autosize`, `CountUp`, `InputMask`, `Sortable` and `SwitchIcon` as real components with instances, methods and events, see above.
|
||||
- `data-tblr-countup` as an alias of `data-countup`.
|
||||
- A billing page in the preview, with plan usage, payment method and invoices.
|
||||
- The Bootstrap component port is compiled with strict TypeScript, so the type declarations in the package are tighter. Configs are typed per component.
|
||||
|
||||
The full list is in the [changelog](https://github.com/tabler/tabler/blob/dev/core/CHANGELOG.md).
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Upgrade
|
||||
summary: One guide per Tabler release with breaking changes. Start from the version you are on and work forward.
|
||||
description: Upgrade guides for Tabler, one per release, listing the breaking changes with before and after examples.
|
||||
hide-pagination: true
|
||||
---
|
||||
|
||||
import DocsChildrenCards from '@components/DocsChildrenCards.astro'
|
||||
|
||||
Every release that changes something you have to touch in your own code gets its own guide. Each guide starts with a table of the changes that can affect you, then shows a before and after example for every one of them.
|
||||
|
||||
Upgrade one version at a time. If you're on 1.4, read the 1.5 guide first, then the 1.6 guide. Releases before 1.5 didn't need a guide, updating the package was enough.
|
||||
|
||||
<div class="row g-3">
|
||||
<DocsChildrenCards url="/ui/getting-started/upgrade" />
|
||||
</div>
|
||||
|
||||
The complete list of changes in every release, including the ones that don't need any work on your side, is in the [changelog](https://github.com/tabler/tabler/blob/dev/core/CHANGELOG.md).
|
||||
+14
-4
@@ -51,10 +51,6 @@
|
||||
{
|
||||
"title": "Browser support",
|
||||
"url": "/ui/getting-started/browser-support"
|
||||
},
|
||||
{
|
||||
"title": "Upgrade to 1.5",
|
||||
"url": "/ui/getting-started/upgrade"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -108,6 +104,20 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Upgrade",
|
||||
"url": "/ui/getting-started/upgrade",
|
||||
"children": [
|
||||
{
|
||||
"title": "Upgrade to 1.6",
|
||||
"url": "/ui/getting-started/upgrade/1-6"
|
||||
},
|
||||
{
|
||||
"title": "Upgrade to 1.5",
|
||||
"url": "/ui/getting-started/upgrade/1-5"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Base",
|
||||
"url": "/ui/base",
|
||||
|
||||
Reference in new issue
Block a user