a11y

import { createAnnounce } from "@solid-primitives/a11y";

const announce = createAnnounce();

// Status update — screen reader waits for idle before reading
announce("3 results found");

// Urgent error — interrupts the screen reader immediately
announce("Session expired. Please sign in again.", "assertive");

import { makeAnnounce } from "@solid-primitives/a11y";

const [announce, cleanup] = makeAnnounce();
announce("File downloaded");
// later, when your app unmounts:
cleanup();

function createAnnounce(): Announce;
function makeAnnounce(): [announce: Announce, cleanup: () => void];

type Announce = (message: string, politeness?: AnnouncePoliteness) => void;
type AnnouncePoliteness = "polite" | "assertive";

import { createReducedMotion } from "@solid-primitives/a11y";

const prefersReduced = createReducedMotion();

return <div class={prefersReduced() ? "" : "animate-fade-in"}>Content</div>;

// Gate inline styles
const style = () => ({
  transition: prefersReduced() ? "none" : "transform 0.3s ease",
});

function createReducedMotion(): Accessor<boolean>;

import {
  createFormControl,
  createFormControlInput,
  FormControlContext,
  useFormControl,
} from "@solid-primitives/a11y";

import { type Element, Show, onCleanup } from "solid-js";
import {
  createFormControl,
  createFormControlInput,
  FormControlContext,
  useFormControl,
} from "@solid-primitives/a11y";

// 1. Root — creates the ARIA graph and provides it via context
const TextFieldRoot = (props: {
  id?: string;
  validationState?: "valid" | "invalid";
  required?: boolean;
  disabled?: boolean;
  children: Element;
}) => {
  const ctx = createFormControl(props);
  return <FormControlContext value={ctx}>{props.children}</FormControlContext>;
};

// 2. Label — registers its ID so the input can reference it
const TextFieldLabel = (props: { children: Element }) => {
  const ctx = useFormControl();
  const id = ctx.generateId("label");
  onCleanup(ctx.registerLabel(id));
  return <label id={id}>{props.children}</label>;
};

// 3. Input — reads context and spreads computed ARIA props
const TextFieldInput = (props: { placeholder?: string }) => {
  const { fieldProps } = createFormControlInput();
  const ctx = useFormControl();
  return (
    <input
      id={fieldProps.id()}
      placeholder={props.placeholder}
      aria-labelledby={fieldProps.ariaLabelledBy()}
      aria-describedby={fieldProps.ariaDescribedBy()}
      aria-invalid={ctx.validationState() === "invalid" ? "true" : undefined}
      aria-required={ctx.isRequired() ? "true" : undefined}
      disabled={ctx.isDisabled() ?? false}
    />
  );
};

// 4. Description — registers so it's included in aria-describedby
const TextFieldDescription = (props: { children: Element }) => {
  const ctx = useFormControl();
  const id = ctx.generateId("description");
  onCleanup(ctx.registerDescription(id));
  return <span id={id}>{props.children}</span>;
};

// 5. ErrorMessage — registers only while rendered (Show handles mount/unmount)
const ErrorMessageInner = (props: {
  ctx: ReturnType<typeof createFormControl>;
  children: Element;
}) => {
  const id = props.ctx.generateId("error-message");
  onCleanup(props.ctx.registerErrorMessage(id));
  return (
    <span id={id} role="alert">
      {props.children}
    </span>
  );
};
const TextFieldErrorMessage = (props: { children: Element }) => {
  const ctx = useFormControl();
  return (
    <Show when={ctx.validationState() === "invalid"}>
      <ErrorMessageInner ctx={ctx}>{props.children}</ErrorMessageInner>
    </Show>
  );
};

// Usage
<TextFieldRoot id="email" validationState={fieldError() ? "invalid" : undefined} required>
  <TextFieldLabel>Email address</TextFieldLabel>
  <TextFieldInput placeholder="you@example.com" />
  <TextFieldDescription>We'll never share your email.</TextFieldDescription>
  <TextFieldErrorMessage>Enter a valid email address.</TextFieldErrorMessage>
</TextFieldRoot>;

[data-invalid] {
  border-color: red;
}
[data-disabled] {
  opacity: 0.5;
}
[data-required] {
  /* required styling */
}
[data-readonly] {
  background: #f5f5f5;
}

// Spread onto any element that should reflect the field's state
<div {...ctx.dataset()}>...</div>

{
  fieldProps: {
    id: () => string;
    ariaLabel: () => string | undefined;
    ariaLabelledBy: () => string | undefined;
    ariaDescribedBy: () => string | undefined;
  }
}

const TextFieldInput = (props: { placeholder?: string }) => {
  const { fieldProps } = createFormControlInput({
    "aria-label": props["aria-label"],
  });
  const ctx = useFormControl();

  return (
    <input
      id={fieldProps.id()}
      aria-labelledby={fieldProps.ariaLabelledBy()}
      aria-describedby={fieldProps.ariaDescribedBy()}
      aria-label={fieldProps.ariaLabel()}
      aria-invalid={ctx.validationState() === "invalid" ? "true" : undefined}
      aria-required={ctx.isRequired() ? "true" : undefined}
      disabled={ctx.isDisabled() ?? false}
      readonly={ctx.isReadOnly() ?? false}
    />
  );
};

// Provider
const ctx = createFormControl({ id: "my-field", required: true });

<FormControlContext value={ctx}>
  <MyLabel />
  <MyInput />
  <MyDescription />
</FormControlContext>;

// Consumer (inside any descendant component)
const ctx = useFormControl();

// No label registered, no aria-label                    → undefined
// Label registered, no aria-label                       → "field-label"
// Label registered + explicit aria-labelledby           → "external-label field-label"
// Label registered + aria-label on input                → "field-label field-field"

function AccessibleField() {
  const ctx = createFormControl({ id: "email" });

  const [value, setValue] = createSignal("");
  const error = () => (!value().includes("@") ? "Enter a valid email address" : null);

  // Register sub-elements synchronously (onCleanup handles deregistration)
  onCleanup(ctx.registerLabel("email-label"));
  onCleanup(ctx.registerDescription("email-desc"));

  const fieldId = "email-field";

  const ErrorMessage = () => {
    onCleanup(ctx.registerErrorMessage("email-error"));
    return (
      <span id="email-error" role="alert">
        {error()}
      </span>
    );
  };

  return (
    <div>
      <label id="email-label" for={fieldId}>
        Email
      </label>
      <input
        id={fieldId}
        type="email"
        value={value()}
        onInput={e => setValue(e.currentTarget.value)}
        aria-labelledby={ctx.getAriaLabelledBy(fieldId, undefined, undefined)}
        aria-describedby={ctx.getAriaDescribedBy(undefined)}
        aria-invalid={error() ? "true" : undefined}
      />
      <span id="email-desc">We'll never share your email.</span>
      <Show when={error()}>
        <ErrorMessage />
      </Show>
    </div>
  );
}

function createFormControl(props: CreateFormControlProps): FormControlContextValue;
function createFormControlInput(props?: CreateFormControlInputProps): { fieldProps: FieldProps };

const FormControlContext: Context<FormControlContextValue | undefined>;
function useFormControl(): FormControlContextValue;

type CreateFormControlProps = {
  id?: MaybeAccessor<string>;
  name?: MaybeAccessor<string>;
  validationState?: MaybeAccessor<"valid" | "invalid" | undefined>;
  required?: MaybeAccessor<boolean | undefined>;
  disabled?: MaybeAccessor<boolean | undefined>;
  readOnly?: MaybeAccessor<boolean | undefined>;
};

type CreateFormControlInputProps = {
  id?: MaybeAccessor<string>;
  "aria-label"?: MaybeAccessor<string>;
  "aria-labelledby"?: MaybeAccessor<string>;
  "aria-describedby"?: MaybeAccessor<string>;
};

type FormControlDataSet = {
  "data-valid"?: "" | undefined;
  "data-invalid"?: "" | undefined;
  "data-required"?: "" | undefined;
  "data-disabled"?: "" | undefined;
  "data-readonly"?: "" | undefined;
};

type FormControlContextValue = {
  name: Accessor<string>;
  validationState: Accessor<"valid" | "invalid" | undefined>;
  isRequired: Accessor<boolean | undefined>;
  isDisabled: Accessor<boolean | undefined>;
  isReadOnly: Accessor<boolean | undefined>;
  dataset: Accessor<FormControlDataSet>;
  labelId: Accessor<string | undefined>;
  fieldId: Accessor<string | undefined>;
  descriptionId: Accessor<string | undefined>;
  errorMessageId: Accessor<string | undefined>;
  generateId: (part: string) => string;
  registerLabel: (id: string) => () => void;
  registerField: (id: string) => () => void;
  registerDescription: (id: string) => () => void;
  registerErrorMessage: (id: string) => () => void;
  getAriaLabelledBy: (
    fieldId: string | undefined,
    ariaLabel: string | undefined,
    ariaLabelledBy: string | undefined,
  ) => string | undefined;
  getAriaDescribedBy: (ariaDescribedBy: string | undefined) => string | undefined;
};