feat: add temporal context and contextual help

webui/src/components/Button.tsx

@@ -7,7 +7,20 @@ export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & PlatformInte
   disabledReason?: ReactNode;
 };
 
-export default function Button({ variant = "secondary", className = "", disabledReason, disabled, interfaceId, helpTopicId, ...props }: ButtonProps) {
-  const button = <button data-interface-id={interfaceId} data-help-topic-id={helpTopicId} className={`btn btn-${variant} ${className}`} disabled={disabled || Boolean(disabledReason)} {...props} />;
+export default function Button({ variant = "secondary", className = "", disabledReason, disabled, interfaceId, helpContextId, helpTopicId, children, ...props }: ButtonProps) {
+  const button = (
+    <button
+      data-help-scope="action"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={typeof children === "string" ? children : undefined}
+      className={`btn btn-${variant} ${className}`}
+      disabled={disabled || Boolean(disabledReason)}
+      {...props}
+    >
+      {children}
+    </button>
+  );
   return <DisabledActionTooltip reason={disabledReason}>{button}</DisabledActionTooltip>;
 }

webui/src/components/Card.tsx

@@ -1,8 +1,9 @@
 import { useEffect, useState, type ReactNode } from "react";
 import { ChevronDown } from "lucide-react";
 import { usePlatformLanguage } from "../i18n/LanguageContext";
+import type { PlatformInterfaceIdentityProps } from "../types";
 
-type CardProps = {
+type CardProps = PlatformInterfaceIdentityProps & {
   title?: ReactNode;
   children: ReactNode;
   actions?: ReactNode;
@@ -38,7 +39,7 @@ function writeCollapseState(storageKey: string | null, collapsed: boolean): void
     // localStorage may be unavailable in private or restricted contexts.
   }}
 
-export default function Card({ title, children, actions, collapsible = false, collapseKey, persistCollapse = true }: CardProps) {
+export default function Card({ title, children, actions, collapsible = false, collapseKey, persistCollapse = true, interfaceId, helpContextId, helpTopicId }: CardProps) {
   const { translateText } = usePlatformLanguage();
   const storageKey = resolveCollapseStorageKey(collapsible, persistCollapse, collapseKey, title);
   const [collapseState, setCollapseState] = useState(() => ({ storageKey, collapsed: readCollapseState(storageKey) }));
@@ -59,7 +60,14 @@ export default function Card({ title, children, actions, collapsible = false, co
   }
 
   return (
-    <section className={`card${collapsible ? " card-collapsible" : ""}${collapsed ? " is-collapsed" : ""}`}>
+    <section
+      className={`card${collapsible ? " card-collapsible" : ""}${collapsed ? " is-collapsed" : ""}`}
+      data-help-scope="interface"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={typeof title === "string" ? title : undefined}
+    >
       {hasHeader &&
       <header className="card-header">
           {title && (typeof title === "string" ? <h2>{translateText(title)}</h2> : <div className="card-title-node">{title}</div>)}
@@ -85,4 +93,4 @@ export default function Card({ title, children, actions, collapsible = false, co
       {shouldRenderBody && (collapsible ? <div className="card-collapse-region">{body}</div> : body)}
     </section>);
 
-}
+}

webui/src/components/DateTimeField.tsx

@@ -50,7 +50,7 @@ function combineDateTime(date: string, time: string): string {
   return `${date || dateString(new Date())}T${time || "00:00"}`;
 }
 
-export function DateField({ value, onChange, min, max, disabled, className = "", placeholder = "i18n:govoplan-core.yyyy_mm_dd.d3f8f7b8", interfaceId, helpTopicId, ...props }: BaseProps) {
+export function DateField({ value, onChange, min, max, disabled, className = "", placeholder = "i18n:govoplan-core.yyyy_mm_dd.d3f8f7b8", interfaceId, helpContextId, helpTopicId, ...props }: BaseProps) {
   const selectedDate = parseDate(value);
   const [open, setOpen] = useState(false);
   const [visibleMonth, setVisibleMonth] = useState<Date>(() => selectedDate ?? new Date());
@@ -94,7 +94,15 @@ export function DateField({ value, onChange, min, max, disabled, className = "",
   }
 
   return (
-    <div ref={rootRef} className={`date-field ${className}`.trim()} data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <div
+      ref={rootRef}
+      className={`date-field ${className}`.trim()}
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={props["aria-label"] ?? placeholder}
+    >
       <input
         {...props}
         ref={inputRef}
@@ -146,7 +154,7 @@ export function DateField({ value, onChange, min, max, disabled, className = "",
 
 }
 
-export function TimeField({ value, onChange, min, max, className = "", placeholder = "i18n:govoplan-core.hh_mm.a4c7ee9b", interfaceId, helpTopicId, ...props }: BaseProps) {
+export function TimeField({ value, onChange, min, max, className = "", placeholder = "i18n:govoplan-core.hh_mm.a4c7ee9b", interfaceId, helpContextId, helpTopicId, ...props }: BaseProps) {
   const inputRef = useRef<HTMLInputElement | null>(null);
   useEffect(() => {
     const input = inputRef.current;
@@ -159,7 +167,14 @@ export function TimeField({ value, onChange, min, max, className = "", placehold
   }, [value, min, max]);
 
   return (
-    <div className={`time-field ${className}`.trim()} data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <div
+      className={`time-field ${className}`.trim()}
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={props["aria-label"] ?? placeholder}
+    >
       <input
         {...props}
         ref={inputRef}
@@ -175,7 +190,7 @@ export function TimeField({ value, onChange, min, max, className = "", placehold
 
 }
 
-export function DateTimeField({ value, onChange, min, max, disabled, className = "", interfaceId, helpTopicId, ...props }: BaseProps) {
+export function DateTimeField({ value, onChange, min, max, disabled, className = "", interfaceId, helpContextId, helpTopicId, ...props }: BaseProps) {
   const parts = datePartsFromDateTime(value);
   const minParts = datePartsFromDateTime(min || "");
   const maxParts = datePartsFromDateTime(max || "");
@@ -189,7 +204,14 @@ export function DateTimeField({ value, onChange, min, max, disabled, className =
   }
 
   return (
-    <div className={`date-time-field ${className}`.trim()} data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <div
+      className={`date-time-field ${className}`.trim()}
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={props["aria-label"]}
+    >
       <DateField
         {...props}
         value={parts.date}

webui/src/components/Dialog.tsx

@@ -8,8 +8,9 @@ import {
   registerDialog,
   type DialogStackId
 } from "./dialogStack";
+import type { PlatformInterfaceIdentityProps } from "../types";
 
-export type DialogProps = {
+export type DialogProps = PlatformInterfaceIdentityProps & {
   open: boolean;
   title: ReactNode;
   children: ReactNode;
@@ -56,7 +57,10 @@ export default function Dialog({
   footerClassName = "",
   portal = false,
   panelStyle,
-  backdropStyle
+  backdropStyle,
+  interfaceId,
+  helpContextId,
+  helpTopicId
 }: DialogProps) {
   const titleId = useId();
   const canClose = Boolean(onClose) && !closeDisabled;
@@ -134,6 +138,11 @@ export default function Dialog({
         role={role}
         aria-modal="true"
         data-dialog-stack-state="topmost"
+        data-help-scope="dialog"
+        data-interface-id={interfaceId}
+        data-help-context-id={helpContextId}
+        data-help-topic-id={helpTopicId}
+        data-help-key={typeof title === "string" ? title : undefined}
         aria-labelledby={titleId}
         aria-describedby={ariaDescribedBy}
       >

webui/src/components/FormField.tsx

@@ -12,11 +12,19 @@ type FormFieldProps = PlatformInterfaceIdentityProps & {
   children: ReactNode;
 };
 
-export default function FormField({ label, help, documentation, children, interfaceId, helpTopicId }: FormFieldProps) {
+export default function FormField({ label, help, documentation, children, interfaceId, helpContextId, helpTopicId }: FormFieldProps) {
   const { translateText } = usePlatformLanguage();
   const renderedLabel = typeof label === "string" ? translateText(label) : label;
   return (
-    <label className="form-field" data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <label
+      className="form-field"
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId ?? documentation?.contextId}
+      data-help-topic-id={helpTopicId ?? documentation?.topicId}
+      data-help-documentation-type={documentation?.documentationType}
+      data-help-key={typeof label === "string" ? label : undefined}
+    >
       <FieldLabel className="form-label" help={help ?? helpForFieldLabel(label)} documentation={documentation}>{renderedLabel}</FieldLabel>
       {children}
     </label>

webui/src/components/SearchableSelect.tsx

@@ -98,6 +98,7 @@ export default function SearchableSelect({
   debounceMs = 200,
   className = "",
   interfaceId,
+  helpContextId,
   helpTopicId
 }: SearchableSelectProps) {
   const { translateText } = usePlatformLanguage();
@@ -297,8 +298,11 @@ export default function SearchableSelect({
     <div
       ref={rootRef}
       className={rootClassName}
+      data-help-scope="field"
       data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
       data-help-topic-id={helpTopicId}
+      data-help-key={ariaLabel}
       onBlur={closeOnFocusLeave}
     >
       <div className="searchable-select-control">

webui/src/components/ToggleSwitch.tsx

@@ -14,7 +14,7 @@ type ToggleSwitchProps = PlatformInterfaceIdentityProps & {
   help?: ReactNode;
 };
 
-export default function ToggleSwitch({ label, activeLabel, inactiveLabel, checked, onChange, disabled = false, help, interfaceId, helpTopicId }: ToggleSwitchProps) {
+export default function ToggleSwitch({ label, activeLabel, inactiveLabel, checked, onChange, disabled = false, help, interfaceId, helpContextId, helpTopicId }: ToggleSwitchProps) {
   const { translateText } = usePlatformLanguage();
   const hasStateLabels = activeLabel !== undefined || inactiveLabel !== undefined;
   const renderedLabel = typeof label === "string" ? translateText(label) : label;
@@ -22,7 +22,14 @@ export default function ToggleSwitch({ label, activeLabel, inactiveLabel, checke
   const renderedActiveLabel = typeof activeLabel === "string" ? translateText(activeLabel) : activeLabel;
   const inputLabel = typeof renderedLabel === "string" ? renderedLabel : undefined;
   return (
-    <label className={`toggle-switch-row ${disabled ? "disabled" : ""}`} data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <label
+      className={`toggle-switch-row ${disabled ? "disabled" : ""}`}
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={typeof label === "string" ? label : undefined}
+    >
       <input
         className="toggle-switch-input"
         type="checkbox"

webui/src/components/admin/AdminPageLayout.tsx

@@ -3,8 +3,9 @@ import DismissibleAlert from "../DismissibleAlert";
 import LoadingFrame from "../LoadingFrame";
 import PageTitle from "../PageTitle";
 import { usePlatformLanguage } from "../../i18n/LanguageContext";
+import type { PlatformInterfaceIdentityProps } from "../../types";
 
-type Props = {
+type Props = PlatformInterfaceIdentityProps & {
   title: string;
   description: string;
   loading?: boolean;
@@ -25,11 +26,22 @@ export default function AdminPageLayout({
   success = "",
   actions,
   children,
-  className = ""
+  className = "",
+  interfaceId,
+  helpContextId,
+  helpTopicId
 }: Props) {
   const { translateText } = usePlatformLanguage();
   return (
-    <div className={`admin-section-page ${className}`.trim()}>
+    <div
+      className={`admin-section-page ${className}`.trim()}
+      data-help-scope="page"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-documentation-type="admin"
+      data-help-key={title}
+    >
       <div className="page-heading split workspace-heading admin-page-heading">
         <div>
           <PageTitle loading={loading}>{title}</PageTitle>
@@ -44,4 +56,4 @@ export default function AdminPageLayout({
       </LoadingFrame>
     </div>);
 
-}
+}

webui/src/components/email/EmailAddressInput.tsx

@@ -46,6 +46,7 @@ export default function EmailAddressInput({
   compact = false,
   showAddButton,
   interfaceId,
+  helpContextId,
   helpTopicId
 }: EmailAddressInputProps) {
   const { translateText } = usePlatformLanguage();
@@ -202,7 +203,14 @@ export default function EmailAddressInput({
   ) : null;
 
   return (
-    <div className={`email-address-input ${compact ? "compact" : ""} ${disabled ? "disabled" : ""} ${canUseAddButton ? "has-add-button" : ""}`} data-interface-id={interfaceId} data-help-topic-id={helpTopicId}>
+    <div
+      className={`email-address-input ${compact ? "compact" : ""} ${disabled ? "disabled" : ""} ${canUseAddButton ? "has-add-button" : ""}`}
+      data-help-scope="field"
+      data-interface-id={interfaceId}
+      data-help-context-id={helpContextId}
+      data-help-topic-id={helpTopicId}
+      data-help-key={emailPlaceholder}
+    >
       <div className={`email-address-editor ${error ? "has-error" : ""}`}>
         <div className="email-chip-list" aria-live="polite">
           {normalizedValue.length === 0 && !entryText && <span className="email-chip-empty">{translateText(emptyText)}</span>}

webui/src/components/help/documentationHelp.ts

@@ -3,6 +3,8 @@ export const HOSTED_DOCUMENTATION_URL = "https://govoplan.add-ideas.de/";
 export type DocumentationHelpReference = {
   topicId?: string;
   contextId?: string;
+  fallbackContextId?: string;
+  moduleId?: string;
   documentationType?: "user" | "admin";
   anchorId?: string;
 };
@@ -20,6 +22,10 @@ export function documentationHelpHref(
   });
   if (topicId) params.set("topic", topicId);
   else if (contextId) params.set("context", contextId);
+  const fallbackContextId = reference.fallbackContextId?.trim();
+  if (fallbackContextId && fallbackContextId !== contextId) params.set("fallback_context", fallbackContextId);
+  const moduleId = reference.moduleId?.trim();
+  if (moduleId) params.set("module", moduleId);
   const anchorId = reference.anchorId?.trim();
   return `${baseUrl}?${params.toString()}${anchorId ? `#${encodeURIComponent(anchorId)}` : ""}`;
 }