From 421dafacc13570f15457191c58819109289ffd9a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=BCdiger=20Rolf?= <rrolf@uni-osnabrueck.de>
Date: Fri, 2 Oct 2026 16:27:14 +0200
Subject: [PATCH] fix(ui): TranslatableField hint contrast + aria-describedby
 (#11)

Hint, outdated notice and required error get AA contrast and are linked
to the input via aria-describedby; renderInput passes describedBy, which
RichTextEditor applies (and updates at runtime). Bump ui to 0.7.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          | 15 +++++++++++++++
 packages/ui/README.md                 |  8 ++++++--
 packages/ui/package-lock.json         |  4 ++--
 packages/ui/package.json              |  2 +-
 packages/ui/src/RichTextEditor.tsx    | 23 +++++++++++++++++++++++
 packages/ui/src/TranslatableField.tsx | 26 ++++++++++++++++++++++----
 6 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7741157..72e5257 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,21 @@ Changelog ist die Upgrade-Anleitung für die Tools.
 
 ## [Unreleased]
 
+### @basicbar/ui (→ wird `ui/v0.7.1`)
+
+**A11y-Fix `TranslatableField`** (#11): Der `hint` hatte mit
+`text-slate-400` nur ~2,6:1 Kontrast und war nicht mit dem Feld verknüpft.
+Jetzt `text-slate-600 dark:text-slate-300` (AA), und Hinweis,
+Veraltet-Hinweis und Pflichtfeld-Fehler hängen per `aria-describedby` an der
+Eingabe (Screenreader lesen sie mit dem Feld vor); Veraltet- und
+Fehlertext ebenfalls auf AA-Kontrast (`amber-700`, `rose-600`).
+`renderInput` bekommt dafür `describedBy`, `RichTextEditor` eine gleichnamige
+Prop (auch zur Laufzeit aktualisiert).
+
+Migration: Tarball auf `ui/v0.7.1`. Wer `renderInput` mit `RichTextEditor`
+nutzt, reicht zusätzlich `describedBy={describedBy}` durch (sonst bleibt der
+Editor ohne Beschreibung — nichts bricht).
+
 ### basicbar-integrations (→ wird `integrations/v0.3.0`)
 
 **`CapabilitiesView` entfernt** (Framework-Review: kein Tool hat
diff --git a/packages/ui/README.md b/packages/ui/README.md
index c8c8b0d..7336b69 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -189,7 +189,10 @@ die Maschinenübersetzung erhält die Tags). `renderInput` bekommt neben `id`
 auch `labelId` — die Id von `TranslatableField`s eigenem sichtbaren `<label>`
 (nur gesetzt, wenn die `label`-Prop übergeben wurde); durchgereicht als
 `labelledBy` bindet der Editor sich per `aria-labelledby` an dieses Label,
-statt ein zweites, redundantes `ariaLabel` zu brauchen. Auch `onBlur` wird
+statt ein zweites, redundantes `ariaLabel` zu brauchen. Ebenso `describedBy`
+(die Ids der gerade sichtbaren Hilfe-/Statustexte: `hint`, Veraltet-Hinweis,
+Pflichtfeld-Fehler) — als `describedBy` durchgereicht setzt der Editor
+`aria-describedby`, Screenreader lesen den Hinweis mit dem Feld vor. Auch `onBlur` wird
 durchgereicht (die `onBlur`-Prop des Feldes), falls der eigene Editor ein
 Blur-Speichern verdrahten will:
 
@@ -199,13 +202,14 @@ Blur-Speichern verdrahten will:
   values={{ de: form.description_de, en: form.description_en }}
   onChange={(lang, html) => setField(`description_${lang}`, html)}
   format="html"
-  renderInput={({ value, onChange, id, labelId }) => (
+  renderInput={({ value, onChange, id, labelId, describedBy }) => (
     <RichTextEditor
       value={value}
       onChange={onChange}
       onUploadImage={uploadRichImage}
       id={id}
       labelledBy={labelId}
+      describedBy={describedBy}
     />
   )}
 />
diff --git a/packages/ui/package-lock.json b/packages/ui/package-lock.json
index 627386c..a565996 100644
--- a/packages/ui/package-lock.json
+++ b/packages/ui/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@basicbar/ui",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@basicbar/ui",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@tiptap/extension-bold": "^3.27.2",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index bafacdb..c9142ae 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@basicbar/ui",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Design-System-Basis der virtUOS -bar-Tools: Tailwind-Preset, Basis-Styles, Theme (Dark Mode), i18n-Bootstrap, contentLang, TranslatableField, Preferences, RichText; RichTextEditor (TipTap) als eigener Entry",
   "license": "Apache-2.0",
   "author": "Universität Osnabrück (virtUOS)",
diff --git a/packages/ui/src/RichTextEditor.tsx b/packages/ui/src/RichTextEditor.tsx
index 1cfeca1..d9b73cf 100644
--- a/packages/ui/src/RichTextEditor.tsx
+++ b/packages/ui/src/RichTextEditor.tsx
@@ -58,6 +58,9 @@ export interface RichTextEditorProps {
    *  on the editable element); an alternative to `ariaLabel` when a visible
    *  label already exists (e.g. `TranslatableField`'s `labelId`). */
   labelledBy?: string;
+  /** Ids of helper texts describing this editor (sets `aria-describedby`),
+   *  e.g. `TranslatableField`'s `describedBy`. */
+  describedBy?: string;
   id?: string;
   /** `false` renders the content read-only in the editor's own frame — no
    *  toolbar, no caret, pasted/dropped files ignored — e.g. while a form is
@@ -109,6 +112,7 @@ export function RichTextEditor({
   onUploadImage,
   ariaLabel,
   labelledBy,
+  describedBy,
   id,
   editable = true,
 }: RichTextEditorProps) {
@@ -266,6 +270,25 @@ export function RichTextEditor({
     if (editor && editor.isEditable !== editable) editor.setEditable(editable);
   }, [editor, editable]);
 
+  // Not in `editorProps.attributes`: those are read once and re-applied by
+  // ProseMirror on every update, but the described-by set changes at runtime
+  // (e.g. a required-field error appearing), so it is synced directly.
+  useEffect(() => {
+    if (!editor) return;
+    const apply = () => {
+      // Before mount `editor.view` is a stub that throws on `dom`.
+      if (!editor.isInitialized || editor.isDestroyed) return;
+      const dom = editor.view.dom;
+      if (describedBy) dom.setAttribute("aria-describedby", describedBy);
+      else dom.removeAttribute("aria-describedby");
+    };
+    apply();
+    editor.on("create", apply);
+    return () => {
+      editor.off("create", apply);
+    };
+  }, [editor, describedBy]);
+
   if (!editor) return null;
 
   function setLink() {
diff --git a/packages/ui/src/TranslatableField.tsx b/packages/ui/src/TranslatableField.tsx
index a57e4a6..a97db98 100644
--- a/packages/ui/src/TranslatableField.tsx
+++ b/packages/ui/src/TranslatableField.tsx
@@ -54,6 +54,10 @@ export interface RenderInputArgs {
    *  custom editor that has no native `<label htmlFor>` association of its
    *  own (`RichTextEditor`'s `labelledBy`). */
   labelId?: string;
+  /** Space-separated ids of the field's helper/status texts (hint, outdated
+   *  notice, required error), when any is shown — pass through as
+   *  `aria-describedby` (`RichTextEditor`'s `describedBy`). */
+  describedBy?: string;
 }
 
 const DEFAULT_INPUT_CLASS =
@@ -239,6 +243,14 @@ export function TranslatableField({
   const showTabs = !singleLanguage;
   const tabsLabel = ariaLabel ?? label;
   const labelId = label ? `${inputId}-label` : undefined;
+  // Helper/status texts are announced with the input (aria-describedby).
+  const hintId = `${baseId}-hint`;
+  const staleId = `${baseId}-stale`;
+  const requiredId = `${baseId}-required`;
+  const describedBy =
+    [hint && hintId, activeStale && staleId, canonicalEmpty && requiredId]
+      .filter(Boolean)
+      .join(" ") || undefined;
 
   return (
     <div className={`block text-xs text-slate-500 dark:text-slate-400 ${className}`}>
@@ -315,7 +327,7 @@ export function TranslatableField({
       )}
       <div className="mt-1">
         {renderInput ? (
-          renderInput({ lang: active, value, onChange: set, onBlur, id: inputId, labelId })
+          renderInput({ lang: active, value, onChange: set, onBlur, id: inputId, labelId, describedBy })
         ) : multiline ? (
           <textarea
             id={inputId}
@@ -324,6 +336,7 @@ export function TranslatableField({
             placeholder={placeholder}
             onChange={(e) => set(e.target.value)}
             onBlur={onBlur}
+            aria-describedby={describedBy}
             className={inputClass}
           />
         ) : (
@@ -333,12 +346,13 @@ export function TranslatableField({
             placeholder={placeholder}
             onChange={(e) => set(e.target.value)}
             onBlur={onBlur}
+            aria-describedby={describedBy}
             className={inputClass}
           />
         )}
       </div>
       {activeStale && (
-        <p className="mt-1 text-amber-600 dark:text-amber-400">
+        <p id={staleId} className="mt-1 text-amber-700 dark:text-amber-400">
           {t("The other language was changed since this translation.")}
         </p>
       )}
@@ -369,9 +383,13 @@ export function TranslatableField({
         </div>
       )}
       {translateError && <p className="mt-1 text-rose-500">{translateError}</p>}
-      {hint && <p className="mt-1 text-slate-400 dark:text-slate-500">{hint}</p>}
+      {hint && (
+        <p id={hintId} className="mt-1 text-slate-600 dark:text-slate-300">
+          {hint}
+        </p>
+      )}
       {canonicalEmpty && (
-        <p className="mt-1 text-rose-500">
+        <p id={requiredId} className="mt-1 text-rose-600 dark:text-rose-400">
           {t("A value in {{language}} is required.", {
             language: defaultContentLangLabel(),
           })}