@stenajs-webui/elements 23.21.11 → 23.21.13

package/dist/components/ui/banners/hooks/UseHasBeenVisible.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Latches to true the first time the banner is visible, and stays true.
+ *
+ * The validation banners use this to tell "not visible yet" apart from "not
+ * visible any more". Only the second one is a validation that went from
+ * failing to passing, and only then is there something to announce.
+ *
+ * The state is updated during render rather than in an effect, so that the
+ * value is settled in the same commit that hides the banner. That is the
+ * commit where the resolved text has to be added to the live region.
+ *
+ * The value is only read while the banner is hidden, and by then it has been
+ * set by an earlier render, so it is never stale where it matters.
+ */
+export declare const useHasBeenVisible: (visible: boolean) => boolean;

package/dist/components/ui/banners/validation-banner/ValidationBanner.d.ts

@@ -10,6 +10,31 @@ export interface ValidationBannerProps extends Omit<BannerProps, "aria-live"> {
      * result.
      */
     visible: boolean;
+    /**
+     * What to announce once the validation result goes away, such as
+     * "All passenger details are valid.", or null to stay silent.
+     *
+     * Screen readers announce content that is added to a live region, but say
+     * nothing when content is removed, so hiding the banner is silent on its
+     * own. This text takes the place of the banner, which turns the resolved
+     * validation into an addition, and lets it say the true thing rather than
+     * repeating the error at the moment the error is gone.
+     *
+     * It is only read by screen readers, and never shown, so a form that becomes
+     * valid looks exactly as it did before. Nothing is announced until the banner
+     * has been visible at least once, so a form that is valid from the start
+     * stays quiet.
+     *
+     * The text is announced whenever the banner goes away, whatever the reason.
+     * A banner that the user can dismiss without having fixed anything needs a
+     * text that is true in that case too, or null.
+     *
+     * Required, so that every validation result has to take a stand on what is
+     * announced once it passes. Pass null when there is nothing to announce,
+     * such as when the banner is always visible, when it is dismissed rather
+     * than resolved, or when one summary banner speaks for a whole form.
+     */
+    resolvedText: string | null;
     /**
      * How eagerly assistive technology should announce the validation result.
      *
@@ -26,10 +51,15 @@ export interface ValidationBannerProps extends Omit<BannerProps, "aria-live"> {
  *
  * The live region is rendered at all times, also while the validation passes,
  * since screen readers only announce updates to live regions that already
- * exist. Only the banner is added and removed, and the region adds no gap of
+ * exist. Only the contents are added and removed, and the region adds no gap of
  * its own, so keeping it mounted next to a form field does not affect the
  * layout.
  *
+ * The region holds the banner while the validation fails, and `resolvedText`
+ * once it passes. Since the region alternates between two different texts, and
+ * both of them arrive as additions, every change is announced: the failure, the
+ * recovery, and a second failure with the same text as the first.
+ *
  * All Banner props are forwarded, so the banner is styled and structured
  * exactly like a Banner.
  *
@@ -45,6 +75,7 @@ export interface ValidationBannerProps extends Omit<BannerProps, "aria-live"> {
  *     variant={"error"}
  *     headerText={t("validation.email.header")}
  *     text={t("validation.email.text")}
+ *     resolvedText={t("validation.email.resolved")}
  *   />
  * </Column>
  */

package/dist/components/ui/banners/validation-result-list-banner/ValidationResultListBanner.d.ts

@@ -11,6 +11,31 @@ export interface ValidationResultListBannerProps extends Omit<ResultListBannerPr
      * banner should be hidden.
      */
     bannerState: ResultListBannerState | undefined;
+    /**
+     * What to announce once the validation result goes away, such as
+     * "All bookings were saved.", or null to stay silent.
+     *
+     * Screen readers announce content that is added to a live region, but say
+     * nothing when content is removed, so clearing the result is silent on its
+     * own. This text takes the place of the banner, which turns the resolved
+     * validation into an addition, and lets it say the true thing rather than
+     * repeating the errors at the moment the errors are gone.
+     *
+     * It is only read by screen readers, and never shown, so a form that becomes
+     * valid looks exactly as it did before. Nothing is announced until the banner
+     * has been visible at least once, so a form that is valid from the start
+     * stays quiet.
+     *
+     * The text is announced whenever the banner goes away, whatever the reason.
+     * A banner that the user can dismiss without having fixed anything needs a
+     * text that is true in that case too, or null.
+     *
+     * Required, so that every validation result has to take a stand on what is
+     * announced once it passes. Pass null when there is nothing to announce,
+     * such as when the banner is always visible, when it is dismissed rather
+     * than resolved, or when one summary banner speaks for a whole form.
+     */
+    resolvedText: string | null;
     /**
      * How eagerly assistive technology should announce the validation result.
      *
@@ -28,9 +53,14 @@ export interface ValidationResultListBannerProps extends Omit<ResultListBannerPr
  *
  * The live region is rendered at all times, also while there is no result,
  * since screen readers only announce updates to live regions that already
- * exist. Only the banner is added and removed, and the region adds no gap of
+ * exist. Only the contents are added and removed, and the region adds no gap of
  * its own, so keeping it mounted next to a form does not affect the layout.
  *
+ * The region holds the banner while there is a result, and `resolvedText` once
+ * the result is cleared. Since the region alternates between two different
+ * texts, and both of them arrive as additions, every change is announced: the
+ * failure, the recovery, and a second failure with the same texts as the first.
+ *
  * All ResultListBanner props are forwarded, so the banner is styled and
  * structured exactly like a ResultListBanner.
  *
@@ -43,6 +73,7 @@ export interface ValidationResultListBannerProps extends Omit<ResultListBannerPr
  *     <ValidationResultListBanner
  *       bannerState={bannerState}
  *       variant={"error"}
+ *       resolvedText={t("validation.bookings.resolved")}
  *     />
  *     <PrimaryButton label={t("save")} onClick={onSave} />
  *   </Column>