Primitives / foldkit-primitives/interaction

LiveAnnounce

namespace · packages/primitives/src/interaction/live-announce.ts:10

export * as LiveAnnounce from './live-announce.js'

Announcements for assistive technology: one Bundle, placed once, holds the text of a polite and an assertive live region. An announcement waits debounceMs so a burst reads once, then clears after clearAfterMs, both on Effect's clock with a generation so a superseded timer changes nothing. The same text twice gets a trailing no-break space toggled, which is what makes a screen reader read it again. view renders the two regions; put it once in the page and style them visually hidden.

In the guides

Members

LiveAnnounce.Args

const · packages/primitives/src/interaction/live-announce.ts:40

const Args: Schema.Struct<{
  readonly debounceMs: Schema.Number
  readonly clearAfterMs: Schema.Number
}>

LiveAnnounce.bundle

const · packages/primitives/src/interaction/live-announce.ts:62

const bundle: Bundle.Bundle<
  'LiveAnnounce',
  { readonly debounceMs: number; readonly clearAfterMs: number },
  {
    readonly polite: string
    readonly assertive: string
    readonly pending: {
      readonly message: string
      readonly politeness: 'polite' | 'assertive'
    } | null
    readonly generation: number
  },
  | { readonly _tag: 'Cleared'; readonly generation: number }
  | { readonly _tag: 'Read'; readonly generation: number }
  | {
      readonly _tag: 'Announced'
      readonly message: string
      readonly politeness: 'polite' | 'assertive'
    },
  never,
  never,
  never,
  void,
  {},
  {}
>

LiveAnnounce.Message

const · packages/primitives/src/interaction/live-announce.ts:28

const Message: MessageUnion<{
  readonly Announced: {
    readonly message: Schema.String
    readonly politeness: Schema.Literals<readonly ['polite', 'assertive']>
  }
  readonly Read: { readonly generation: Schema.Number }
  readonly Cleared: { readonly generation: Schema.Number }
}>

LiveAnnounce.Model

const · packages/primitives/src/interaction/live-announce.ts:19

const Model: Schema.Struct<{
  readonly polite: Schema.String
  readonly assertive: Schema.String
  readonly pending: Schema.NullOr<
    Schema.Struct<{
      readonly message: Schema.String
      readonly politeness: Schema.Literals<readonly ['polite', 'assertive']>
    }>
  >
  readonly generation: Schema.Number
}>

LiveAnnounce.Politeness

const · packages/primitives/src/interaction/live-announce.ts:16

const Politeness: Schema.Literals<readonly ['polite', 'assertive']>

LiveAnnounce.REGION_ATTRIBUTE

const · packages/primitives/src/interaction/live-announce.ts:109

const REGION_ATTRIBUTE: 'data-foldkit-plus-live'

LiveAnnounce.reread

function · packages/primitives/src/interaction/live-announce.ts:51

function reread(current: string, next: string): string

The text to put in the region so that next is read even when it equals current.

LiveAnnounce.say

function · packages/primitives/src/interaction/live-announce.ts:102

function say<Field extends string>(
  declared: Declared<typeof bundle, Field>,
): <ParentMessage>(text: string, politeness?: Politeness) => ParentMessage

The parent Message that announces text, to return from update or onOut.

LiveAnnounce.view

function · packages/primitives/src/interaction/live-announce.ts:116

function view<ParentMessage>(model: Model, h: HtmlBuilder<ParentMessage>): Html

The two live regions. Render once, anywhere in the page, and hide them visually with a rule on [data-foldkit-plus-live]; they must stay in the accessibility tree, so no display: none.