@supersoniks/concorde 5.0.4 → 5.0.5

package/docs/llms.txt

@@ -29,43 +29,36 @@ Full text: https://concorde.supersoniks.org/llms-full.txt
 - [Submit](https://concorde.supersoniks.org/crawl/core/components/functional/submit/submit.html) (core/components/functional/submit/submit): > Live demos: <docs-lit-demo> + src/docs/example/docs-submit-demos.ts. Use Local API demos (serviceURL="/docs-mock-api").
 - [Subscriber](https://concorde.supersoniks.org/crawl/core/components/functional/subscriber/subscriber.html) (core/components/functional/subscriber/subscriber): La mixin Subscriber permet lier un composant à un publisher.
 - [Value](https://concorde.supersoniks.org/crawl/core/components/functional/value/value.html) (core/components/functional/value/value): Simply shows a value from a data provider.
-- [Concorde](https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html) (core/components/ui/alert-messages/alert-messages): Concorde documentation: Concorde
-- [Alert](https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html) (core/components/ui/alert/alert): This address is already in use. Lorem ipsum dolor sit amet.
-- [Badge](https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html) (core/components/ui/badge/badge): Messages <sonic-badge slot="suffix" type="danger" size="xs">5</sonic-badge>
+- [Alert messages](https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html) (core/components/ui/alert-messages/alert-messages): sonic-alert-messages renders a vertical stack of sonic-alert items from a messages array on a linked data provider (typical pattern: submitResultDataProvider after a form submit). Only entries with ty
+- [Alert](https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html) (core/components/ui/alert/alert): Alerts surface important feedback inline—errors, confirmations, or contextual help. Use label / text for simple copy, or the default slot for rich content (links, buttons). Set announce when the messa
+- [Badge](https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html) (core/components/ui/badge/badge): Badges are compact, non-interactive labels for status, counts, or categories. They mirror sonic-button styling (type, variant, size) without focus rings or click handling—use a button when the control
 - [Button](https://concorde.supersoniks.org/crawl/core/components/ui/button/button.html) (core/components/ui/button/button): The length of the button depends on the size of its content
-- [Captcha](https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html) (core/components/ui/captcha/captcha): Captcha: Submit with captcha
-- [Card](https://concorde.supersoniks.org/crawl/core/components/ui/card/card.html) (core/components/ui/card/card): Suffix
-- [Divider](https://concorde.supersoniks.org/crawl/core/components/ui/divider/divider.html) (core/components/ui/divider/divider): Default
-
-Align
-
-Size
-
-Custom
-
-  Lorem ipsum dolor sit amet  +25
+- [Captcha](https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html) (core/components/ui/captcha/captcha): sonic-captcha embeds an ALTCHA widget and wires captchaToken / needsCaptchaValidation on the ancestor formDataProvider (or headersDataProvider). sonic-submit waits for a token before sending when vali
+- [Card](https://concorde.supersoniks.org/crawl/core/components/ui/card/card.html) (core/components/ui/card/card): Cards group related content on a padded surface with radius, theme type colors, and elevation. Default shadow is lg. Compose sonic-card-header / sonic-card-main / sonic-card-footer, or place any marku
+- [Divider](https://concorde.supersoniks.org/crawl/core/components/ui/divider/divider.html) (core/components/ui/divider/divider): sonic-divider draws a horizontal or vertical rule with optional centered label copy. Use it to separate sections in forms, cards, and sonic-menu. Set label for simple HTML captions or use the default 
 - [Checkbox](https://concorde.supersoniks.org/crawl/core/components/ui/form/checkbox/checkbox.html) (core/components/ui/form/checkbox/checkbox): >Already checked checkbox
-- [Fieldset](https://concorde.supersoniks.org/crawl/core/components/ui/form/fieldset/fieldset.html) (core/components/ui/form/fieldset/fieldset): Default
-- [Form-actions](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-actions/form-actions.html) (core/components/ui/form/form-actions/form-actions): Left seats
-- [Form-layout](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-layout/form-layout.html) (core/components/ui/form/form-layout/form-layout): autocomplete="email"
+- [Fieldset](https://concorde.supersoniks.org/crawl/core/components/ui/form/fieldset/fieldset.html) (core/components/ui/form/fieldset/fieldset): sonic-fieldset groups related form controls with a bordered container and an accessible <fieldset> semantics layer. Put fields in the default slot; add a title with sonic-legend or the shorthand label
+- [Form actions](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-actions/form-actions.html) (core/components/ui/form/form-actions/form-actions): sonic-form-actions lays out submit / cancel and other form footer controls in a wrapping flex row with a small fixed gap. Place it inside sonic-form-layout (full-width row) or any block that should en
+- [Form layout](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-layout/form-layout.html) (core/components/ui/form/form-layout/form-layout): sonic-form-layout arranges slotted form controls in a responsive CSS grid with consistent vertical spacing. Pair sonic-input · sonic-select and sonic-input-autocomplete fields side by side when the ho
 - [Input-autocomplete](https://concorde.supersoniks.org/crawl/core/components/ui/form/input-autocomplete/input-autocomplete.html) (core/components/ui/form/input-autocomplete/input-autocomplete): Champ formulaire + suggestions via queue. Valeur via formDataProvider + name ; la recherche filtre la queue (store interne).
-- [Input](https://concorde.supersoniks.org/crawl/core/components/ui/form/input/input.html) (core/components/ui/form/input/input): Native attibutes list
+- [Input](https://concorde.supersoniks.org/crawl/core/components/ui/form/input/input.html) (core/components/ui/form/input/input): Native attributes list
 - [Radio](https://concorde.supersoniks.org/crawl/core/components/ui/form/radio/radio.html) (core/components/ui/form/radio/radio): >Already checked radio
 - [Select](https://concorde.supersoniks.org/crawl/core/components/ui/form/select/select.html) (core/components/ui/form/select/select): {"value":"dark", "wording":"dark (set by \"attribute\")", "selected" : "true"}, {"value":"auto", "wording":"auto"}
 - [Switch](https://concorde.supersoniks.org/crawl/core/components/ui/form/switch/switch.html) (core/components/ui/form/switch/switch): >Already checked switch
-- [Textarea](https://concorde.supersoniks.org/crawl/core/components/ui/form/textarea/textarea.html) (core/components/ui/form/textarea/textarea): Native attibutes list
-- [Group](https://concorde.supersoniks.org/crawl/core/components/ui/group/group.html) (core/components/ui/group/group): Group: 😎 Standard ⭐ Premium 💎 Diamond
-- [Icon](https://concorde.supersoniks.org/crawl/core/components/ui/icon/icon.html) (core/components/ui/icon/icon): customIconDefaultPrefix="regular">
-- [Image](https://concorde.supersoniks.org/crawl/core/components/ui/image/image.html) (core/components/ui/image/image): src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-- [Link](https://concorde.supersoniks.org/crawl/core/components/ui/link/link.html) (core/components/ui/link/link): Link: Basic link with href attibute
-- [Loader](https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html) (core/components/ui/loader/loader): import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
-- [Menu](https://concorde.supersoniks.org/crawl/core/components/ui/menu/menu.html) (core/components/ui/menu/menu): Row
-- [Concorde](https://concorde.supersoniks.org/crawl/core/components/ui/modal/modal.html) (core/components/ui/modal/modal): Concorde: Simple modal Lorem ipsum dolor sit amet +33 Donec sed vestibulum augue. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus. Click don't close Confir
-- [Pop](https://concorde.supersoniks.org/crawl/core/components/ui/pop/pop.html) (core/components/ui/pop/pop): Click to open pop
-- [Progress bar](https://concorde.supersoniks.org/crawl/core/components/ui/progress/progress.html) (core/components/ui/progress/progress): Displays an indicator showing the completion progress of a task.
-- [Table](https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html) (core/components/ui/table/table): Values available : primary, info, success, warning, danger
-- [Toast](https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html) (core/components/ui/toast/toast): Afficher un toast
-- [Tooltip](https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html) (core/components/ui/tooltip/tooltip): By default, tooltip is centered next to its content
+- [Textarea](https://concorde.supersoniks.org/crawl/core/components/ui/form/textarea/textarea.html) (core/components/ui/form/textarea/textarea): Native attributes list
+- [Group](https://concorde.supersoniks.org/crawl/core/components/ui/group/group.html) (core/components/ui/group/group): sonic-group lays out slotted sonic-button · sonic-input and sonic-select controls in a single horizontal row with shared corner radius (first / middle / last items). Optional label and description fol
+- [Icon](https://concorde.supersoniks.org/crawl/core/components/ui/icon/icon.html) (core/components/ui/icon/icon): sonic-icon renders inline SVG icons from the bundled core set or from CDN libraries. Set name (and library / prefix when needed); scale with size. Icons inherit currentColor and are aria-hidden by def
+- [Image](https://concorde.supersoniks.org/crawl/core/components/ui/image/image.html) (core/components/ui/image/image): sonic-image wraps a responsive <img> with aspect ratio, object-fit: cover, optional rounded corners, and load transitions. The host shows a placeholder background (--sc-placeholder-bg) until the asset
+- [Link](https://concorde.supersoniks.org/crawl/core/components/ui/link/link.html) (core/components/ui/link/link): Links navigate with inherited typography: internal routes, anchors, or external URLs. The default slot is the anchor label. For in-app routing, pair href with pushstate; use autoActive to reflect the 
+- [Loader](https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html) (core/components/ui/loader/loader): sonic-loader shows a loading animation in the page or as a viewport overlay. Default mode is fixed (centered overlay). Use inline inside lists and fetch placeholders. Pair noDelay when the spinner sho
+- [Menu](https://concorde.supersoniks.org/crawl/core/components/ui/menu/menu.html) (core/components/ui/menu/menu): sonic-menu lays out navigation or actions as a direction row or column of sonic-menu-item entries (ghost variant and block shape by default), optional sonic-divider separators, and overflow content in
+- [Modal](https://concorde.supersoniks.org/crawl/core/components/ui/modal/modal.html) (core/components/ui/modal/modal): sonic-modal presents focused content in a <dialog> overlay with backdrop, enter/exit animation, and a built-in close control. Compose sonic-modal-title / sonic-modal-subtitle / sonic-modal-content / s
+- [Pop](https://concorde.supersoniks.org/crawl/core/components/ui/pop/pop.html) (core/components/ui/pop/pop): sonic-pop anchors floating panels to a trigger: put the control in the default slot and the panel in slot="content" (menus, forms, custom markup). Click toggles open/closed unless manual is set; defau
+- [Progress](https://concorde.supersoniks.org/crawl/core/components/ui/progress/progress.html) (core/components/ui/progress/progress): Shows task completion on a value / max scale via a native <progress> bar. Omit value for an indeterminate loading animation. Put primary copy in the default slot and optional secondary text in remaini
+- [Table](https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html) (core/components/ui/table/table): sonic-table lays out tabular data with composable sonic-tr / sonic-th / sonic-td children. The root applies shared typography via size, scrolls horizontally when content overflows, and optionally caps
+- [Theme](https://concorde.supersoniks.org/crawl/core/components/ui/theme/theme.html) (core/components/ui/theme/theme): sonic-theme wraps a Concorde UI: it registers --sc-* design tokens and provides the default slot for your app. With no theme attribute (or theme="custom"), only shared primitives and your overrides ap
+- [Toast](https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html) (core/components/ui/toast/toast): Toasts surface short-lived feedback in a fixed stack (bottom-right in the main window). Queue messages with SonicToast.add() on the global SonicToast class—the host sonic-toast is created automaticall
+- [Tooltip](https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html) (core/components/ui/tooltip/tooltip): Tooltip shows a short label on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default placement is top (center-aligned). A
 - [Data flow](https://concorde.supersoniks.org/crawl/docs/_core-concept/dataFlow.html) (docs/_core-concept/dataFlow): Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store (legacy Publisher API: Legacy: Sharing data).
 - [lit + tailwind + vite](https://concorde.supersoniks.org/crawl/docs/_core-concept/overview.html) (docs/_core-concept/overview): Some notes for an overview of Concorde's functioning
 - [Legacy: Subscriber mixin](https://concorde.supersoniks.org/crawl/docs/_core-concept/subscriber.html) (docs/_core-concept/subscriber): > New app components: My first component and Data flow — extend LitElement with decorators (@subscribe, @ancestorAttribute, …). This mixin remains in core components (sonic-list, sonic-fetch, …) and l
@@ -90,7 +83,7 @@ Custom
 - [Legacy: My first subscriber component](https://concorde.supersoniks.org/crawl/docs/_getting-started/my-first-subscriber.html) (docs/_getting-started/my-first-subscriber): > New projects: use My first component (@ancestorAttribute, @subscribe + DataProviderKey, .items on lists) and Data flow. This page documents the Subscriber mixin used by older apps and core component
 - [Legacy: Sharing data](https://concorde.supersoniks.org/crawl/docs/_getting-started/pubsub.html) (docs/_getting-started/pubsub): > New apps: Data flow (get / set / DataProviderKey, decorators). This page documents the historical Publisher proxy API (PublisherManager, publisher.set, onAssign, …).
 - [Introduction](https://concorde.supersoniks.org/crawl/docs/_getting-started/start.html) (docs/_getting-started/start): Based on lit.dev, Concorde is a collection of web components for shared apps and websites.
-- [Adding styles](https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html) (docs/_getting-started/theming): No style crosses the shadow root of a component, except for inheritable properties (which have the "inherit" property possible) and CSS variables.
+- [Customization](https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html) (docs/_getting-started/theming): Concorde components ship with default styles (fallback values in each component and in <sonic-theme>).
 - [API configuration](https://concorde.supersoniks.org/crawl/docs/_misc/api-configuration.html) (docs/_misc/api-configuration): APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, 
 - [DataProviderKey](https://concorde.supersoniks.org/crawl/docs/_misc/dataProviderKey.html) (docs/_misc/dataProviderKey): The DataProviderKey<T> utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via toString() or the
 - [Local API demos (offline)](https://concorde.supersoniks.org/crawl/docs/_misc/docs-mock-api.html) (docs/_misc/docs-mock-api): The Concorde doc site does not call fragile third-party APIs during yarn dev. A Service Worker and the Vite dev middleware serve /docs-mock-api/* on the same origin.

package/docs/sitemap.xml

@@ -132,6 +132,9 @@
   <url>
     <loc>https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html</loc>
   </url>
+  <url>
+    <loc>https://concorde.supersoniks.org/crawl/core/components/ui/theme/theme.html</loc>
+  </url>
   <url>
     <loc>https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html</loc>
   </url>

package/docs/src/core/components/ui/alert/alert.md

@@ -1,5 +1,9 @@
 # Alert
 
+Alerts **surface important feedback** inline—errors, confirmations, or contextual help. Use **`label`** / **`text`** for simple copy, or the **default slot** for rich content (links, buttons). Set **`announce`** when the message appears after an action so screen readers pick it up.
+
+## Basic example
+
 <sonic-code>
   <template>
     <sonic-alert status="error" label="Email error" text="This address is already in use" background></sonic-alert>
@@ -8,15 +12,52 @@
 
 ## Status
 
+Color and icon follow `status`. With no `status`, behavior is `default`.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-alert label="Default">This address is already in use.</sonic-alert>
+      <sonic-alert status="success" label="Success">This address is already in use.</sonic-alert>
+      <sonic-alert status="error" label="Error">This address is already in use.</sonic-alert>
+      <sonic-alert status="warning" label="Warning">This address is already in use.</sonic-alert>
+      <sonic-alert status="info" label="Info">This address is already in use.</sonic-alert>
+    </div>
+  </template>
+</sonic-code>
+
+## Accessibility (`announce`)
+
+By default, an alert already in the DOM is **not** announced (no `role` / `aria-live`). Set **`announce`** when the message appears **after** user action (API response, validation, etc.): screen readers get `role="alert"` for `error`, otherwise `role="status"` and `aria-live="polite"`.
+
+`sonic-alert-messages` sets `announce` on every rendered alert.
+
+<sonic-code>
+  <template>
+    <sonic-alert announce status="success" label="Saved" text="Your changes were saved."></sonic-alert>
+  </template>
+</sonic-code>
+
+## Content and icon
+
+`label` and `text` accept plain text only. The default slot is rendered after `text`. Use the **`icon`** slot to replace the default `sonic-icon`. **`noIcon`** hides the icon.
+
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert label="Default"> This address is already in use. </sonic-alert>
-  <sonic-alert status="success" label="Success"> This address is already in use. </sonic-alert>
-  <sonic-alert status="error" label="Error"> This address is already in use. </sonic-alert>
-  <sonic-alert status="warning" label="Warning"> This address is already in use. </sonic-alert>
-  <sonic-alert status="info" label="Info"> This address is already in use. </sonic-alert>
-  </div>
+    <sonic-alert status="info" noIcon label="No icon" text="Informational message."></sonic-alert>
+  </template>
+</sonic-code>
+
+## Custom icon slot
+
+Project any markup into **`slot="icon"`** (emoji, image, custom component). Keep it decorative with `aria-hidden="true"` when the message text already conveys meaning.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="success" label="Achievement unlocked" background>
+      <span slot="icon" aria-hidden="true" class="text-lg leading-none">🎉</span>
+      You unlocked a new badge.
+    </sonic-alert>
   </template>
 </sonic-code>
 
@@ -24,98 +65,132 @@
 
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert status="error" label="Email error" size="2xs">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="xs">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="sm">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="lg">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="xl">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="2xl">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  </div>
+    <div class="grid gap-4">
+      <sonic-alert status="error" label="Email error" size="2xs">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="xs">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="sm">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="lg">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="xl">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="2xl">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+    </div>
   </template>
 </sonic-code>
 
 ## Alert with link
 
+Rich content in the slot (buttons, links).
+
 <sonic-code>
   <template>
-  <sonic-alert status="info" label="New messages !">
-    You have 2 unread messages<br />
-    <div class="flex gap-2 mt-1">
-      <sonic-button variant="outline" type="info" size="xs">See messages</sonic-button>
-      <sonic-button variant="ghost" type="info" size="xs">dismiss</sonic-button>
-    </div>
-  </sonic-alert>
+    <sonic-alert status="info" label="New messages !">
+      You have 2 unread messages<br />
+      <div class="flex gap-2 mt-1">
+        <sonic-button variant="outline" type="info" size="xs">See messages</sonic-button>
+        <sonic-button variant="ghost" type="info" size="xs">Dismiss</sonic-button>
+      </div>
+    </sonic-alert>
   </template>
 </sonic-code>
 
 ## Background
 
+Tinted background from the `status` color (`color-mix` on `currentColor`).
+
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="success" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="error" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="warning" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="info" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  </div>
+    <div class="grid gap-4">
+      <sonic-alert background label="Lorem ipsum dolor">This address is already in use.</sonic-alert>
+      <sonic-alert status="success" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="error" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="warning" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="info" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+    </div>
   </template>
 </sonic-code>
 
 ## Dismissible
 
+`dismissible` removes the alert from the DOM when the close control is clicked (i18n aria label). **`dismissible`** and **`background`** are independent: without `background`, close sits at the end of the row; with `background`, top-right.
+
 <sonic-code>
   <template>
-  <sonic-alert class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="success" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="error" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="warning" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="info" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
+    <sonic-alert status="info" class="mb-3" dismissible label="This address is already in use.">
+    </sonic-alert>
+    <sonic-alert class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="success" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="error" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="warning" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="info" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
   </template>
 </sonic-code>
 
 ## Dismiss forever
 
+With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-alert-dismissed`). A stable **`id`** on the element is **required**; without `id`, a warning is logged and nothing is persisted.
+
 <sonic-code>
   <template>
-  <sonic-alert class="mb-3" dismissible dismissForever label="Lorem ipsum dolor" id="addressUniqueId">
-    This address is already in use.
-  </sonic-alert>
+    <sonic-alert
+      class="mb-3"
+      dismissible
+      background
+      dismissForever
+      label="Lorem ipsum dolor"
+      id="addressUniqueId"
+    >
+      This address is already in use.
+    </sonic-alert>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `status` | `default` · `info` · `success` · `warning` · `error` | Color and default icon |
+| `label` | string | Title (plain text) |
+| `text` | string | Short body (plain text), rendered before the slot |
+| `size` | `2xs` … `2xl` | Corner radius and typography |
+| `background` | boolean | Tinted background (`color-mix` on status color) |
+| `dismissible` | boolean | Close control; removes the element from the DOM |
+| `dismissForever` | boolean | Persists dismissal in `localStorage`; requires **`id`** |
+| `noIcon` | boolean | Hides the icon (including custom `icon` slot content) |
+| `announce` | boolean | `role="alert"` / `aria-live` for dynamically injected content |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Message body (HTML, actions); rendered after `text` |
+| `icon` | Replaces the default `sonic-icon` |

package/docs/src/core/components/ui/alert-messages/alert-messages.md

@@ -0,0 +1,85 @@
+# Alert messages
+
+**`sonic-alert-messages`** renders a vertical stack of **`sonic-alert`** items from a **`messages`** array on a linked **data provider** (typical pattern: **`submitResultDataProvider`** after a form submit). Only entries with **`type="public"`** are shown. Each alert gets **`announce`** so screen readers pick up feedback after the request.
+
+## With submit result
+
+Bind **`dataProvider`** to the same publisher as **`submitResultDataProvider`**. API **`messages`** entries need **`type`**: **`public`**, plus **`content`** and optional **`status`** (`warning` · `success` · `error` · `info`).
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="submit-example"
+      submitResultDataProvider="submit-example-result"
+    >
+      <sonic-alert-messages dataProvider="submit-example-result" background class="mb-4"></sonic-alert-messages>
+      <div class="grid gap-4 max-w-md">
+        <sonic-input name="email" type="email" label="Email" value=""></sonic-input>
+        <sonic-input name="password" type="password" label="Password" value=""></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Submit (empty fields → error messages)</sonic-button>
+        </sonic-submit>
+      </div>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Shared alert props
+
+**`size`** · **`background`** and **`noIcon`** apply to every rendered **`sonic-alert`** in the list.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      size="sm"
+      variant="outline"
+      class="mb-3"
+      onclick="SonicPublisherManager.get('submit-example-result').set({ messages: [{ type: 'public', content: 'Compact inline feedback without icons.', status: 'info' }] })"
+    >
+      Load sample messages
+    </sonic-button>
+    <sonic-alert-messages
+      dataProvider="submit-example-result"
+      size="sm"
+      background
+      noIcon
+    ></sonic-alert-messages>
+  </template>
+</sonic-code>
+
+## Message shape
+
+Example JSON on the result publisher (or API response merged into it):
+
+<sonic-code language="typescript">
+  <template>
+{
+  "messages": [
+    {
+      "type": "public",
+      "content": "The product has been added to your cart",
+      "status": "success"
+    }
+  ]
+}
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `dataProvider` | publisher id | Source object; **`messages`** array is auto-filled via **Subscriber** |
+| `size` | `2xs` … `2xl` (default `md`) | Passed to each **`sonic-alert`** |
+| `background` | boolean | Tinted background on each alert |
+| `noIcon` | boolean | Hides icons on each alert |
+| `messages` | `Message[]` | Usually set by the publisher; each item uses **`content`** as alert **`text`** |
+
+| Message field | Values | Description |
+|---------------|---------|-------------|
+| `type` | `public` | Required for the message to render |
+| `content` | string | Alert body (**`text`** on **`sonic-alert`**) |
+| `status` | `warning` · `success` · `error` · `info` | Alert **`status`**; defaults to **`default`** when omitted |
+
+No slots — alerts are generated from **`messages`**.