Skip to content

v3.0.0

Choose a tag to compare

View all tags
@Neil-Lin Neil-Lin released this 16 Oct 15:34
· 6 commits to main since this release
v3.0.0
c6c0447

Accesserty UI Kit 3.0.0

3.0.0 is a major release. Vue, Nuxt, React and Next.js can now bind the form
components the way they bind native fields, and accordion, tabs and breadcrumbs
can render their Shadow DOM on the server. The component tags, attributes and
properties are unchanged, but custom events are renamed and a few other
details change. Read "What breaks" and "How to upgrade" below before you
replace your copy of the kit.

Plain HTML pages keep working the same way: copy a file, add a <script> tag,
use the <au-*> elements.

Highlights

  • v-model in Vue and Nuxt on au-input, au-textarea, au-checkbox,
    au-switch, au-radio-group, au-rating and au-file-upload, following
    Vue's own rules for native fields. A group of checkboxes can share one array
    or Set, true-value / false-value work, type="number" inputs give
    numbers, and <au-radio :value="2"> gives 2. Server rendering supports it too.
  • A Nuxt module. Add one line to modules in place of a client plugin, the
    isCustomElement setting and <ClientOnly> wrappers.
  • React components for React 19 and Next.js: AuInput, AuTextarea,
    AuCheckbox, AuSwitch, AuRadioGroup, AuRating and AuFileUpload. They
    take value / checked, defaultValue / defaultChecked, onChange and a
    ref to the element. e.target behaves like a native field, with value,
    checked, valueAsNumber and valueAsDate.
  • Server rendering of Shadow DOM (Declarative Shadow DOM) for accordion,
    tabs and breadcrumbs. They have their final look and layout before any
    JavaScript runs, so the page doesn't jump when the script loads or fails.
    • Nuxt: on by default.
    • Self-hosted Next.js: one wrapper, withDeclarativeShadow. It doesn't work on
      Vercel.
    • Any other Node server: injectDeclarativeShadow.
  • Native form API on every form component: setCustomValidity() and
    form, alongside validity, checkValidity() and reportValidity().
    au-input also gets valueAsNumber and valueAsDate. Pressing Enter in an
    au-input still does not submit the form, on purpose.
  • Single-component files in dist/components/. All 15 components are there,
    each as a self-contained file plus a minified copy (tabs.min.js: 13 KB
    instead of 21 KB).
  • TypeScript declarations. accesserty-ui-kit.d.ts types every element, for
    example document.querySelector('au-tabs').selectedIndex. The React file adds
    every au-* tag to JSX with typed event details. Vue types v-model in
    templates.
  • One disabled look. Every component and native button dims to opacity 0.6,
    which keeps dark text at about 5:1 on white. Each component has a
    --au-…-disabled-opacity variable to change it.

What breaks

2.0.10 3.0.0 What to do
au-tabs event tab-change au-tab-change Rename the listener
au-carousel event slide-change au-slide-change Rename the listener
au-pagination events page-change, page-size-change au-page-change, au-page-size-change Rename the listeners
au-dropdown-item event selected au-select Rename the listener
au-file-upload event remove-file au-remove-file Rename the listener
Cascade layer of au-style.css components accesserty Rename it in your @layer order, if you declared one
Copying one component src/components/<name>.js dist/components/<name>.js or <name>.min.js Copy from dist/components/; the files in src/ are ES modules now
au-accordion-item with open in the markup Sends au-toggle when the script loads Sends nothing, because nothing changed Read item.open for the initial state
Ids inside accordion and tabs Shadow DOM Random Fixed (title, region, tab-1…) Only matters if your code read them

The old event names are no longer sent; there is no transition period. These
events keep their names: au-toggle, the native change and input on form
components, and au-tree's change.

In React, ontab-change becomes onau-tab-change. In Vue, @tab-change
becomes @au-tab-change.

Compared with 2.0.10

All fixes from 2.0.8, 2.0.9 and 2.0.10 are included.

2.0.10 3.0.0
Vue / Nuxt forms :value + @input, :checked + @change v-model (the old bindings still work)
Nuxt setup Client plugin, isCustomElement, <ClientOnly> One module
React / Next forms <au-input> tags with on… props (React 19), or a ref and addEventListener (React 18) AuInput… with value / onChange (React 19); the tags still work
Server-rendered Shadow DOM — accordion, tabs, breadcrumbs
setCustomValidity(), form — All 7 form components
valueAsNumber, valueAsDate on au-input — Yes
Validity API on au-rating, au-file-upload Missing Same as the other form components
Disabled opacity 0.35–0.65; au-input had no disabled look 0.6 everywhere, one variable per component
Event names Mixed All start with au- (except tree's change)
Single-component files src/components/*.js dist/components/*.js and *.min.js
TypeScript — Elements, events, JSX tags, Vue v-model
accesserty-ui-kit.js / .min.js 260 KB / 197 KB 252 KB / 190 KB
Integration files in dist/ — Vue, React, Nuxt, SSR (ES modules, each with .d.ts)
package.json exports ., ./min Also ./vue, ./react, ./nuxt, ./ssr, each with types
Unit tests 456 485
Browser suites (Chrome, Firefox, Safari) 10 12 (adds server rendering and single files)
Framework checks Next, Nuxt Also Nuxt v-model, Vue SPA, Next React, server-rendered Shadow DOM, TypeScript

How to upgrade

The full guide is in UPGRADING.md.

  1. Replace the kit. Copy the whole new dist/ folder over your copy. The
    integration files import each other by relative path. If you copied single
    components, copy them from dist/components/ instead of src/components/.

  2. Rename event listeners using the table above. Searching your code for
    tab-change, slide-change, page-change, page-size-change, selected
    and remove-file finds them.

  3. CSS: if you use au-style.css, copy the new src/css/ folder. Rename
    any components layer that you ordered for the kit to accesserty:

    @layer base, accesserty, components, utilities;

  4. Vue: use the kit's isCustomElement instead of
    tag => tag.startsWith('au-'), and install the plugin:

    import { AccessertyVue, isCustomElement } from './vendor/accesserty/accesserty-ui-kit-vue.js'
createApp(App).use(AccessertyVue).mount('#app')
// vite.config.js: vue({ template: { compilerOptions: { isCustomElement } } })

    Your :value / @input bindings keep working. Switch to v-model when you
    like.

  5. Nuxt: remove your client plugin, the isCustomElement setting and any
    <ClientOnly> you added for the kit, then add the module:

    export default defineNuxtConfig({
  modules: ['./vendor/accesserty/accesserty-ui-kit-nuxt.js']
})

  6. React / Next.js (optional): switch form fields to the React components,
    and call defineElements() once in a client effect:

    import { AuInput, defineElements } from './vendor/accesserty/accesserty-ui-kit-react.js'
useEffect(() => { defineElements() }, [])
<AuInput label="Email" value={email} onChange={e => setEmail(e.target.value)} />

    For server-rendered accordion, tabs and breadcrumbs, run a custom server
    with withDeclarativeShadow.

  7. Check disabled fields if your design depends on their old opacity. Set
    --au-<component>-disabled-opacity (--au-btn-disabled-opacity for native
    buttons and pagination) to keep the previous value.

Support for 2.x

2.x gets bug fixes only. New features land in 3.x.

Assets 2
Loading