@sweberdev/witness-react 0.0.0-stage → 0.1.1

package/src/AiNotice.tsx

@@ -0,0 +1,104 @@
+import type { DisclosureEvent, DisclosureKind } from "@sweberdev/witness";
+import { type ReactNode, useEffect, useId, useState } from "react";
+import { useWitnessMessages } from "./context.js";
+import { useAiDisclosure } from "./useAiDisclosure.js";
+
+export interface AiNoticeProps {
+  /** Default `chatbot`. Also fits `emotion-recognition` and `biometric-categorisation`. */
+  kind?: DisclosureKind;
+  /** Your id for this disclosure. Default: the kind. */
+  id?: string;
+  /** Bump when the wording changes, so people see it again. Default "1". */
+  version?: string;
+  locale?: string | readonly string[];
+  /** Link to a page that explains how you use AI. */
+  href?: string;
+  storage?: "local" | "session" | "memory";
+  /** Evidence hook: called when the notice is shown and acknowledged. */
+  onEvent?: (event: DisclosureEvent) => void;
+  /** Replaces the default body text. */
+  children?: ReactNode;
+  className?: string;
+}
+
+/**
+ * The AI notice for a chat (Art. 50(1)): expanded until acknowledged, then a compact label
+ * that stays visible and can be reopened. Style it with `@sweberdev/witness/styles.css`.
+ */
+export function AiNotice({
+  kind = "chatbot",
+  id,
+  version,
+  locale,
+  href,
+  storage,
+  onEvent,
+  children,
+  className,
+}: AiNoticeProps) {
+  const { locale: code, messages } = useWitnessMessages(locale);
+  const disclosure = useAiDisclosure({
+    kind,
+    locale: code,
+    ...(id ? { id } : {}),
+    ...(version ? { version } : {}),
+    ...(storage ? { storage } : {}),
+    ...(onEvent ? { onEvent } : {}),
+  });
+  const [reopened, setReopened] = useState(false);
+  const titleId = useId();
+  const text = messages.kinds[kind];
+  const full = reopened || disclosure.needsAcknowledgement;
+  const { markShown } = disclosure;
+
+  useEffect(() => {
+    if (full) markShown();
+  }, [full, markShown]);
+
+  if (!full) {
+    return (
+      <button
+        type="button"
+        className={cx("witness-notice--compact", className)}
+        aria-label={`${text.label}: ${messages.ui.details}`}
+        onClick={() => setReopened(true)}
+      >
+        <span className="witness-label__icon" aria-hidden="true">
+          AI
+        </span>
+        {text.label}
+      </button>
+    );
+  }
+
+  return (
+    <section className={cx("witness-notice", className)} role="note" aria-labelledby={titleId}>
+      <span className="witness-label__icon" aria-hidden="true">
+        AI
+      </span>
+      <div>
+        <h2 id={titleId} className="witness-notice__title">
+          {text.title}
+        </h2>
+        <p className="witness-notice__body">{children ?? text.body}</p>
+        <div className="witness-notice__actions">
+          <button
+            type="button"
+            className="witness-notice__ack"
+            onClick={() => {
+              setReopened(false);
+              disclosure.acknowledge();
+            }}
+          >
+            {messages.ui.acknowledge}
+          </button>
+          {href ? <a href={href}>{messages.ui.moreInfo}</a> : null}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export function cx(...names: Array<string | undefined | false>): string {
+  return names.filter(Boolean).join(" ");
+}

package/src/context.tsx

@@ -0,0 +1,40 @@
+import {
+  getMessages,
+  type LocaleMessages,
+  type LocaleOverride,
+  resolveLocale,
+} from "@sweberdev/witness";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+
+interface WitnessContextValue {
+  locale: string;
+  messages: LocaleMessages;
+}
+
+const WitnessContext = createContext<WitnessContextValue | null>(null);
+
+export interface WitnessProviderProps {
+  /** A locale tag such as "de-CH", or a list such as `navigator.languages`. Default "en". */
+  locale?: string | readonly string[];
+  /** Overrides for the wording, e.g. the informal "du" in German. */
+  messages?: LocaleOverride;
+  children: ReactNode;
+}
+
+/** Sets the language and wording for all Witness components below it. */
+export function WitnessProvider({ locale, messages, children }: WitnessProviderProps) {
+  const value = useMemo(
+    () => ({ locale: resolveLocale(locale), messages: getMessages(locale, messages) }),
+    [locale, messages],
+  );
+  return <WitnessContext.Provider value={value}>{children}</WitnessContext.Provider>;
+}
+
+/** The active locale and messages. A `locale` prop on a component wins over the provider. */
+export function useWitnessMessages(locale?: string | readonly string[]): WitnessContextValue {
+  const context = useContext(WitnessContext);
+  return useMemo(() => {
+    if (locale) return { locale: resolveLocale(locale), messages: getMessages(locale) };
+    return context ?? { locale: "en", messages: getMessages("en") };
+  }, [context, locale]);
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { AiContent, type AiContentProps } from "./AiContent.js";
+export { AiLabel, type AiLabelProps } from "./AiLabel.js";
+export { AiNotice, type AiNoticeProps } from "./AiNotice.js";
+export { useWitnessMessages, WitnessProvider, type WitnessProviderProps } from "./context.js";
+export { type UseAiDisclosureResult, useAiDisclosure } from "./useAiDisclosure.js";

package/src/useAiDisclosure.ts

@@ -0,0 +1,67 @@
+import { createDisclosure, type Disclosure, type DisclosureOptions } from "@sweberdev/witness";
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+
+export interface UseAiDisclosureResult {
+  /** True until the current version was acknowledged. Always true during server rendering. */
+  needsAcknowledgement: boolean;
+  acknowledgedAt: string | null;
+  acknowledge: () => void;
+  /** Records that the notice was rendered (emits a `shown` event once). */
+  markShown: () => void;
+  reset: () => void;
+  disclosure: Disclosure;
+}
+
+/**
+ * State for a custom AI disclosure UI. The server snapshot always needs acknowledgement, so
+ * the full notice is in the server HTML and collapses after hydration for people who already
+ * acknowledged it.
+ */
+export function useAiDisclosure(options: DisclosureOptions = {}): UseAiDisclosureResult {
+  const onEvent = useRef(options.onEvent);
+  onEvent.current = options.onEvent;
+  const { id, kind, version, locale, storage } = options;
+
+  const disclosure = useMemo(
+    () =>
+      createDisclosure({
+        ...(id ? { id } : {}),
+        ...(kind ? { kind } : {}),
+        ...(version ? { version } : {}),
+        ...(locale ? { locale } : {}),
+        ...(storage ? { storage } : {}),
+        onEvent: (event) => onEvent.current?.(event),
+      }),
+    [id, kind, version, locale, storage],
+  );
+
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      const unsubscribe = disclosure.subscribe(listener);
+      // Another tab acknowledged or reset: the browser tells us through a storage event.
+      const onStorage = (event: StorageEvent) => {
+        if (event.key === null || event.key.startsWith("witness:ack:")) listener();
+      };
+      if (typeof window !== "undefined") window.addEventListener("storage", onStorage);
+      return () => {
+        unsubscribe();
+        if (typeof window !== "undefined") window.removeEventListener("storage", onStorage);
+      };
+    },
+    [disclosure],
+  );
+  const acknowledgedAt = useSyncExternalStore(
+    subscribe,
+    () => disclosure.acknowledgedAt(),
+    () => null,
+  );
+
+  return {
+    needsAcknowledgement: acknowledgedAt === null,
+    acknowledgedAt,
+    acknowledge: disclosure.acknowledge,
+    markShown: disclosure.markShown,
+    reset: disclosure.reset,
+    disclosure,
+  };
+}