@stenajs-webui/elements 23.21.10 → 23.21.12

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

@@ -0,0 +1,82 @@
+import { LivelyPoliteness } from "@stenajs-webui/core";
+import * as React from "react";
+import { ResultListBannerProps, ResultListBannerState } from "../result-list-banner/ResultListBanner";
+export interface ValidationResultListBannerProps extends Omit<ResultListBannerProps, "bannerState" | "aria-live"> {
+    /**
+     * The result to show, or undefined when there is no result to show.
+     *
+     * Unlike ValidationBanner, there is no separate visible prop, since the
+     * whole content of the banner is this one prop. It is the same value that
+     * useResultListBannerState holds, and it is undefined exactly when the
+     * 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.
+     *
+     * - `polite` waits until the user is idle.
+     * - `assertive` interrupts the user, and should be used sparingly.
+     * - `off` stops announcing results, without removing the region.
+     *
+     * @default "polite"
+     */
+    politeness?: LivelyPoliteness;
+}
+/**
+ * A ResultListBanner inside an ARIA live region, for validation results that
+ * come and go.
+ *
+ * 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 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.
+ *
+ * @example
+ * const { bannerState, setBannerResultWithErrors, clearBannerResult } =
+ *   useResultListBannerState();
+ *
+ * return (
+ *   <Column gap={2}>
+ *     <ValidationResultListBanner
+ *       bannerState={bannerState}
+ *       variant={"error"}
+ *       resolvedText={t("validation.bookings.resolved")}
+ *     />
+ *     <PrimaryButton label={t("save")} onClick={onSave} />
+ *   </Column>
+ * );
+ */
+export declare const ValidationResultListBanner: React.FC<ValidationResultListBannerProps>;

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

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./components/ui/banners/banner/Banner";
 export * from "./components/ui/banners/result-list-banner/ResultListBanner";
 export * from "./components/ui/banners/result-list-banner/hooks/UseResultListBannerState";
 export * from "./components/ui/banners/validation-banner/ValidationBanner";
+export * from "./components/ui/banners/validation-result-list-banner/ValidationResultListBanner";
 export * from "./components/ui/result-list/ResultList";
 export * from "./components/ui/result-list/ResultListRow";
 export * from "./components/ui/spinner/Spinner";