@antadesign/anta 0.3.34 → 0.3.35

package/docs/install-config.md

@@ -52,7 +52,7 @@ import { Progress, Title, Tag } from '@antadesign/anta'
 ```
 
 Each element entry imports its own CSS for your bundler to include and registers
-its browser class when needed. Title and Tag load only CSS; they have no custom
+its browser class when needed. Some entries load only CSS and have no custom
 element class to register. Element entries do not import global tokens or the reset.
 
 JSX wrappers produce `<a-*>` tags and attributes. They do not register browser
@@ -223,6 +223,11 @@ imports with `import '@antadesign/anta/elements'`. Keep the shared tokens and
 optional reset. Registration is idempotent and guarded when `customElements`
 is unavailable. CSS imports need a bundler that handles stylesheets.
 
+CSS-only components such as Title, Tag, Progress, Icon, and Loader render
+without custom element registration. Their entries load styles. Icon and Loader
+retain `register_a_icon()` and `register_a_loader()` for integrations that
+explicitly require a defined tag.
+
 Static imports register classes before the app's first client render or
 hydration. Server-rendered HTML can paint before the browser loads JavaScript;
 load its CSS with the initial document, as in the Next.js setup below.
@@ -265,14 +270,17 @@ import '@antadesign/anta/elements/a-title'
 Rendering a JSX wrapper does not register its browser element. Raw `<a-*>`
 markup uses the same browser entries and can omit the JSX wrappers.
 For a custom JSX runtime, call `configure()` in the process or thread that
-renders the wrappers; see [Framework setup](#framework-setup).
+renders the wrappers; see [Framework setup](#framework-setup). Worker renderers
+receive native event subscriptions in the first projection. The browser listener
+workaround does not delay worker subscriptions or require access to UI-thread DOM.
 
 ## Framework setup
 
 ### React
 
-React needs no `configure()` call. Load the JavaScript and CSS entries for your
-chosen import strategy before rendering.
+Client-rendered React apps need no `configure()` call. Load the JavaScript and CSS
+entries for your chosen import strategy before rendering. If your app hydrates
+server-rendered HTML, enable [browser hydration](#browser-hydration).
 
 ### Next.js
 
@@ -294,11 +302,13 @@ Import the runtime and JSX wrappers in a Client Component:
 // app/page.tsx
 'use client'
 
-import { useState } from 'react'
-import { Button, Title } from '@antadesign/anta/bundle'
+import * as React from 'react'
+import { Button, Title, configure } from '@antadesign/anta/bundle'
+
+configure(React.createElement, React.Fragment, React, { hydratingEvents: true })
 
 export default function Page() {
-  const [count, setCount] = useState(0)
+  const [count, setCount] = React.useState(0)
   return <>
     <Title>Anta in Next.js</Title>
     <Button label={`Count: ${count}`} onClick={() => setCount(value => value + 1)} />
@@ -310,6 +320,7 @@ Next.js prerenders Client Components on the server for the initial page load.
 `'use client'` marks the client/server module boundary; it does not disable
 server rendering. Anta guards element registration when browser APIs are absent
 and registers the elements when the client module runs before hydration.
+The configuration enables the event-prop workaround for that hydration.
 
 For granular usage, replace the layout's bundle stylesheet with shared tokens
 and the optional reset:
@@ -326,10 +337,12 @@ Keep the same page component and replace its imports with:
 // app/page.tsx
 'use client'
 
-import { useState } from 'react'
+import * as React from 'react'
 import '@antadesign/anta/elements/a-button'
 import '@antadesign/anta/elements/a-title'
-import { Button, Title } from '@antadesign/anta'
+import { Button, Title, configure } from '@antadesign/anta'
+
+configure(React.createElement, React.Fragment, React, { hydratingEvents: true })
 ```
 
 Both setups work with Next.js's default Turbopack bundler.
@@ -337,8 +350,9 @@ Both setups work with Next.js's default Turbopack bundler.
 ### Preact with compat
 
 If your bundler aliases `react` to `preact/compat`, Anta needs no `configure()`
-call. Load the entries for your chosen import strategy. The Vite Preact preset
-provides these runtime aliases.
+call for client rendering. Load the entries for your chosen import strategy.
+The Vite Preact preset provides these runtime aliases. For server-rendered HTML,
+enable [browser hydration](#browser-hydration).
 
 ### Preact without compat
 
@@ -349,20 +363,97 @@ to `configure()` before rendering Anta components. For full bundle usage:
 import '@antadesign/anta/bundle.css'
 import { configure } from '@antadesign/anta/bundle'
 import { h, Fragment } from 'preact'
-import { useState, useId, useMemo, useRef, useLayoutEffect } from 'preact/hooks'
+import * as hooks from 'preact/hooks'
 import { useSyncExternalStore } from 'preact/compat'
 
-configure(h, Fragment, {
-  useState, useId, useMemo, useRef, useLayoutEffect, useSyncExternalStore,
-})
+configure(h, Fragment, { ...hooks, useSyncExternalStore })
 ```
 
+Pass the hooks object as a whole. It replaces the previous renderer's hooks;
+missing hooks report an error when used. React's hooks are the default when no
+object is supplied. The extra `useSyncExternalStore` export supports components
+that subscribe to external stores.
+
 Import JSX wrappers from `@antadesign/anta/bundle` with this setup. For granular
 usage, import both `configure` and the wrappers from `@antadesign/anta` and load
 the UI entries separately. The root package and the prebuilt bundle each have
 their own renderer configuration, so use `configure` from the same entry as
 your wrappers. The explicit `preact/compat` hook import does not require an alias.
 
+### Browser hydration
+
+When your browser app hydrates server-rendered HTML, set `hydratingEvents: true`
+before mounting Anta components:
+
+```ts
+import * as React from 'react'
+import { configure } from '@antadesign/anta/bundle'
+
+configure(React.createElement, React.Fragment, React, {
+  hydratingEvents: true,
+})
+```
+
+This lets Input, Banner, Expander, and expandable Text attach their native event
+handlers after the first browser commit. With `false` or no option, handlers
+pass through immediately without a listener setup effect or extra mount render.
+Client-only apps use that default without configuration.
+
+Use `configure` from the same entry as your wrappers: `@antadesign/anta` or
+`@antadesign/anta/bundle`. For Preact without compat aliases, pass its factory
+and hooks with the same fourth argument. Configure each rendering process or
+thread separately. Servers and workers without `window` forward immediately,
+even when this option is enabled.
+
+Keep the option unchanged while components are mounted. If any root using that
+package entry hydrates server HTML, enable it before mounting any root. Each
+`configure()` call resets an omitted option to `false`, so later setup calls must
+preserve `hydratingEvents: true`. Next.js Client Components still hydrate on the
+initial page load; `'use client'` does not make an app client-only.
+
+### Astro
+
+For hydrated React or Preact islands, configure Anta before Astro hydrates them.
+Use Astro's `before-hydration` script stage in an integration:
+
+```js
+// astro.config.mjs: add to integrations alongside your React or Preact integration
+{
+  name: 'anta-hydration',
+  hooks: {
+    'astro:config:setup': ({ injectScript }) => {
+      injectScript('before-hydration', `
+        import * as React from 'react';
+        import { configure } from '@antadesign/anta/bundle';
+        configure(React.createElement, React.Fragment, React, {
+          hydratingEvents: true,
+        });
+      `)
+    },
+  },
+}
+```
+
+This example uses full bundle wrappers. For granular wrappers, use
+`@antadesign/anta` instead and load browser elements separately. Import
+`bundle.css` in your layout for the full bundle. Preact requires the
+`@astrojs/preact` integration's `compat: true` setting for this example.
+Static markup and `client:only` islands do not need the hydration option.
+
+### Custom renderer events
+
+Worker renderers receive event subscriptions in their first projection by
+default, including renderers with a `window` shim:
+
+```ts
+configure(h, Fragment, hooks)
+```
+
+Pass the runtime's hooks object as a whole. You do not need to opt into browser
+hydration for worker projections. If shared setup previously enabled it, pass
+`{ hydratingEvents: false }` as the fourth argument before mounting the worker
+UI.
+
 ### TypeScript: typing raw `<a-*>` tags in JSX
 
 JSX wrappers such as `<Button>` and `<Progress>` need no extra typing. Configure
@@ -420,7 +511,9 @@ bundler that processes module scripts and CSS imports:
   import '@antadesign/anta/elements/a-progress'
 </script>
 
-<a-progress value="42" max="100" tone="info"></a-progress>
+<a-progress value="42" max="100" tone="info" role="progressbar"
+  aria-label="Upload" aria-valuenow="42" aria-valuemin="0" aria-valuemax="100">
+</a-progress>
 ```
 
 An import map resolves module names but does not process the plain CSS imports
@@ -436,7 +529,9 @@ and root color scheme, including scrollbar colors. The reset, included in
 ```html
 <html class="dark">
   <body>
-    <a-progress value="50"></a-progress>
+    <a-progress value="50" role="progressbar" aria-label="Upload"
+      aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+    </a-progress>
   </body>
 </html>
 ```
@@ -530,21 +625,83 @@ the range your font declares to avoid combining `slnt` with a synthetic oblique.
 
 ## Browser support
 
-Anta targets evergreen browsers and ships **no baseline polyfills**. Its floor is [custom-element states](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet), used throughout the components for their internal CSS state, alongside the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API):
+Anta requires [ARIA element references](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements),
+[custom-element states](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet),
+and the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API).
+It ships no baseline polyfills or copied-text fallback for ARIA references.
 
 | Browser | Minimum version |
 | --- | --- |
-| Chrome / Edge | 125 (May 2024) |
-| Safari | 17.4 (Mar 2024) |
-| Firefox | 126 (May 2024) |
+| Chrome / Edge, including Android Chrome and WebView | 135 |
+| Safari / iOS Safari | 17.4 |
+| Firefox, including Android Firefox | 136 |
 
-This is [Baseline 2024](https://web.dev/baseline). Anta also relies on relative
+ARIA element references are [Baseline 2025](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements#browser_compatibility).
+Anta also relies on relative
 OKLCH, `:has()`, `dvh`, cascade layers, and constructable shadow DOM. Older
 browsers can fail hard, including `:state()` being unrecognized or
 `showPopover()` throwing. Gate Anta on your own support matrix when you support
 older browsers.
 
-Two features progressively enhance with fallbacks: `checkVisibility()` falls
-back to `getClientRects()`, and typed CSS `attr()` supports raw
-`<a-icon size>` in Chrome 133+ and Safari 18.2+. Elsewhere use `<Icon size>`
-or `--icon-size`.
+`checkVisibility()` falls back to `getClientRects()`. Some raw attributes use
+[typed CSS `attr()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/attr#browser_compatibility),
+whose support extends beyond Anta's minimum browser requirements. JSX wrappers
+supply CSS variables for these values. Each component's Web Component reference
+describes its raw attribute requirements.
+
+## Content Security Policy
+
+Anta's tokens, component stylesheets, and optional themes work when your
+[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP)
+(CSP) allows their stylesheet URLs through `style-src-elem` or
+its `style-src` fallback. External CSS and named theme values do not require
+inline style attributes.
+
+Custom color props such as `tone="#6750a4"`, explicit lengths such as
+`round={12}` or Icon's `size={24}`, and some dynamic value props produce inline
+CSS custom properties. The `style` prop also produces inline styles.
+Server rendering serializes these values into HTML `style` attributes, which
+`style-src-attr 'none'` blocks. Named tones, preset sizes, and boolean `round`
+use external CSS without these attributes.
+
+When inline attributes are forbidden, omit the customization prop and apply
+its value through `className` and an allowed stylesheet. For example, replace
+`<Icon shape="check" size={24} />` with:
+
+```tsx
+<Icon shape="check" className="confirmation-icon" />
+```
+
+```css
+.confirmation-icon {
+  --icon-size: 24px;
+}
+```
+
+Define runtime values in an application-managed stylesheet permitted by your
+policy when they cannot be expressed with predefined classes. Check each
+component's reference for its styling surface and dynamic-value requirements.
+Client-side assignments to individual CSS properties can behave
+differently; do not rely on hydration to repair blocked server-rendered styles.
+See [CSP rules for style attributes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-attr).
+
+Server-rendered `<style>` blocks also need CSP permission. They follow
+`style-src-elem`, falling back to `style-src` and then `default-src`.
+`'self'` allows same-origin stylesheet files, but does not authorize inline
+`<style>` blocks. Use a matching nonce or hash for those blocks under a strict
+policy. A nonce on a `<style>` element does not authorize HTML `style`
+attributes. See [CSP rules for stylesheet elements](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-elem).
+
+Component defaults in `@antadesign/anta`, including Panel's maximized surface
+and backdrop, use external stylesheets. Load the UI entry or bundle CSS as
+described in [Installation](#installation). Custom props and application
+styles can still require inline-style permission as described here.
+
+When placing an Anta component inside an application-owned shadow root, load
+its external CSS in that root through a stylesheet link. Document styles do
+not cross that boundary.
+
+The separate `@antadesign/stickers` package has its own CSP requirements. Its
+static and animated elements still inject shadow `<style>` blocks, which a
+policy allowing only external styles blocks. Loading Anta's external CSS or a
+theme does not authorize those blocks.