@hadoku/task-ui-components 0.0.0-stage → 4.20.3

package/src/components/ConnectedSettings.tsx

@@ -0,0 +1,465 @@
+/**
+ * ConnectedSettings — the unified per-user settings control for the hadoku
+ * ecosystem: a gear button that opens a popout housing everything that is a
+ * property of the PERSON (not the app):
+ *   - current access tier (read-only, friendly label)
+ *   - display name (inline edit → POST /session/name)
+ *   - global content-visibility level (tiered pill → PUT /prefs/api/v1/content-level)
+ *   - switch key (an inline sign-in form, on the site's own sign-in client)
+ *
+ * "Connected" (parallel to ConnectedThemePicker): it self-wires to the
+ * hadoku.me edge-router via same-origin fetches (see lib/settingsClient), so
+ * dropping `<ConnectedSettings />` into any app under hadoku.me needs zero
+ * props. Identity is resolved via whoami() unless the host passes `userType` /
+ * `name` (avoids a redundant fetch when the app already knows).
+ *
+ * All of that is resolved AT MOUNT via `prefetchSettings()`, never on
+ * gear-click — opening the popout must cost zero requests. See the effect
+ * below, and `e2e/settings-prefetch.spec.ts` in hadoku-task, which fails if the
+ * fetch moves back behind the click.
+ *
+ * Mirrors ThemePicker's controlled-popout pattern: owns its own `open` state +
+ * a full-viewport overlay for click-outside dismiss. The content pill renders
+ * `maxLevel` segments (friend ⇒ 3, admin ⇒ 4) and is hidden for public callers.
+ * maxLevel comes from the server so the tier ceiling is never trusted from the
+ * client.
+ */
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { SettingsIcon } from './ThemeIcons'
+import {
+  prefetchSettings,
+  setContentLevel,
+  setDisplayName,
+  loadSignIn,
+  switchKeyHref,
+  type ContentLevelState,
+  type Tier
+} from '../lib/settingsClient'
+import '../app-header.css'
+
+export interface ConnectedSettingsProps {
+  /** Caller's tier. Omit to self-resolve via whoami().
+   *
+   *  This exists for apps that CANNOT reach `/session/whoami` — conjure sits
+   *  behind a path-prefixed shim that serves nothing outside `/conjure`, so
+   *  whoami 404s and the tier would fall back to guest. It is an identity
+   *  hint, not a way to present a different tier than the edge assigns: every
+   *  gate that matters is enforced server-side off the edge-stamped tier. */
+  userType?: Tier
+  /** Display name. Omit to self-resolve via whoami(). Same rationale. */
+  name?: string | null
+  /** Notify the host (e.g. a "Signed in as …" label) of a rename. */
+  onNameChange?: (name: string | null) => void
+  /** App-specific settings rendered as a final section in the same popout, so
+   *  an app with its own preferences keeps ONE unified gear instead of a second
+   *  control. Shown under an "App preferences" divider.
+   *
+   *  This slot is deliberately unconstrained — put whatever the app needs in
+   *  it. The constraint is only that it lands AFTER the four canonical rows and
+   *  cannot change them. */
+  children?: React.ReactNode
+}
+
+/** Rejection sink for fire-and-forget settings actions. The client helpers
+ *  already resolve to null on failure (state reflects it), so this only trips
+ *  on truly unexpected throws — log rather than swallow silently. */
+function reportErr(err: unknown) {
+  // task-ui-components v2 dropped its logger; keep the package dependency-free.
+  console.error('[ConnectedSettings] action failed', (err as Error)?.message ?? err)
+}
+
+const TIER_LABEL: Record<Tier, string> = {
+  admin: 'Administrator',
+  wife: 'Wife',
+  service: 'Service',
+  friend: 'Friend',
+  public: 'Guest'
+}
+
+export function ConnectedSettings({
+  userType: userTypeProp,
+  name: nameProp,
+  onNameChange,
+  children
+}: ConnectedSettingsProps) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // Identity — from props if supplied, else resolved lazily via whoami().
+  const [userType, setUserType] = useState<Tier>(userTypeProp ?? 'public')
+  const [resolvedName, setResolvedName] = useState<string | null>(nameProp ?? null)
+
+  // Name editing
+  const [nameDraft, setNameDraft] = useState(resolvedName ?? '')
+  const [editingName, setEditingName] = useState(false)
+  const [nameSaving, setNameSaving] = useState(false)
+  const [displayName, setLocalName] = useState<string | null>(resolvedName)
+
+  // Key swap. The draft lives only in this state and the input: it is never
+  // logged, stored or sent anywhere but the site's sign-in client.
+  const [keyFormOpen, setKeyFormOpen] = useState(false)
+  const [keyDraft, setKeyDraft] = useState('')
+  const [keyBusy, setKeyBusy] = useState(false)
+  const [keyError, setKeyError] = useState<string | null>(null)
+
+  // Content level
+  const [content, setContent] = useState<ContentLevelState | null>(null)
+  const [levelSaving, setLevelSaving] = useState(false)
+
+  // One flag for the whole prefetch, not one per request — the panel body
+  // reveals when everything has settled, so nothing pops in a beat late. In
+  // practice the user never sees it: the prefetch starts at mount and is long
+  // done by the time the gear is clicked. It only shows if they click within
+  // the first moments of the page.
+  const [resolving, setResolving] = useState(true)
+
+  // Everyone who is SIGNED IN, expressed as "not public" rather than as a list
+  // of tiers. The list form (`=== 'admin' || === 'friend' || === 'service'`)
+  // is an exact-match allowlist: it silently excluded `wife` the moment that
+  // tier existed, which is the failure the rank model is meant to prevent.
+  // There is no rank helper in this bundle, but "above public" needs none.
+  const showContentPill = userType !== 'public'
+
+  // Keep local identity in sync when the host controls it via props.
+  useEffect(() => {
+    if (userTypeProp !== undefined) setUserType(userTypeProp)
+  }, [userTypeProp])
+  useEffect(() => {
+    if (nameProp !== undefined) {
+      setResolvedName(nameProp)
+      setLocalName(nameProp)
+      setNameDraft(nameProp ?? '')
+    }
+  }, [nameProp])
+
+  // Resolve everything the panel shows AT MOUNT — not on open.
+  //
+  // This used to be gated on `open`, which made the gear the trigger for
+  // whoami + content-level (167ms / 186ms on prod, concurrent) — a round trip
+  // the user waited out with the panel already on screen and blank. Nothing
+  // about that data depends on the click:
+  // it's the signed-in user's own identity, settled at boot and unchanged for
+  // the life of the page. So it rides along with the app's boot traffic, and
+  // clicking the gear costs zero requests. `e2e/settings-prefetch.spec.ts` in
+  // hadoku-task pins that.
+  //
+  // The client memoises across callers, so mounting this in several places (or
+  // remounting it) does not multiply requests, and on hadoku.me the identity
+  // half is free — it awaits the whoami the shell already had in flight.
+  useEffect(() => {
+    let live = true
+    prefetchSettings({ userType: userTypeProp, name: nameProp })
+      .then(({ identity, content: state }) => {
+        if (!live) return
+        // Props stay authoritative: the host passed them because it can see an
+        // identity this component can't resolve for itself.
+        if (userTypeProp === undefined) {
+          setUserType(identity.userType)
+          setResolvedName(identity.name)
+          setLocalName(identity.name)
+          setNameDraft(identity.name ?? '')
+        }
+        if (state) setContent(state)
+      })
+      .catch(reportErr)
+      .finally(() => {
+        if (live) setResolving(false)
+      })
+    return () => {
+      live = false
+    }
+    // Hints are read once, on the first mount that gets there — the prefetch is
+    // page-scoped and a later prop change cannot un-issue it. Identity changes
+    // arrive through the sync effects above, and a key swap reloads the page.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Escape closes.
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [open])
+
+  const saveName = useCallback(async () => {
+    const trimmed = nameDraft.trim()
+    if (!trimmed || trimmed === displayName) {
+      setEditingName(false)
+      return
+    }
+    setNameSaving(true)
+    const stored = await setDisplayName(trimmed)
+    setNameSaving(false)
+    if (stored !== null) {
+      setLocalName(stored)
+      setNameDraft(stored)
+      onNameChange?.(stored)
+    }
+    setEditingName(false)
+  }, [nameDraft, displayName, onNameChange])
+
+  // Open the form AND start loading the site's sign-in client, which begins its
+  // fingerprint collection as it evaluates — so it is ready by submit. Where the
+  // client cannot load at all (not on hadoku.me), the page-level /auth flow is
+  // the only way to sign in, so go there.
+  const openKeyForm = useCallback(() => {
+    setKeyFormOpen(true)
+    setKeyError(null)
+    loadSignIn()
+      .then(signIn => {
+        if (!signIn) window.location.assign(switchKeyHref())
+      })
+      .catch(reportErr)
+  }, [])
+
+  const submitKey = useCallback(async () => {
+    setKeyBusy(true)
+    setKeyError(null)
+    const signIn = await loadSignIn()
+    if (!signIn) {
+      window.location.assign(switchKeyHref())
+      return
+    }
+    try {
+      await signIn(keyDraft)
+    } catch (err) {
+      // A refused key is an inline error, never a redirect.
+      setKeyError((err as Error)?.message || 'Invalid key')
+      setKeyBusy(false)
+      return
+    }
+    // The page now acts for a different identity: everything must re-mount.
+    // Busy stays on through the reload so the form can't be resubmitted.
+    window.location.reload()
+  }, [keyDraft])
+
+  const pickLevel = useCallback(
+    async (level: number) => {
+      if (!content || level === content.level || levelSaving) return
+      const prev = content
+      setContent({ ...content, level }) // optimistic
+      setLevelSaving(true)
+      const result = await setContentLevel(level)
+      setLevelSaving(false)
+      setContent(result ?? prev) // adopt server truth, or revert
+    },
+    [content, levelSaving]
+  )
+
+  // No caller-supplied class on the root. The four rows below are the
+  // platform's, not the app's, and a className here is enough to restyle or
+  // hide any of them — which is the drift this component exists to prevent.
+  // Apps extend via `children`, never by reaching into this markup.
+  return (
+    <div className="settings-popout" ref={rootRef}>
+      <button
+        type="button"
+        className="app-header__icon-btn settings-toggle-btn"
+        aria-label="User settings"
+        aria-expanded={open}
+        onClick={() => setOpen(v => !v)}
+      >
+        <SettingsIcon />
+      </button>
+
+      {open && <div className="settings-popout__overlay" onClick={() => setOpen(false)} />}
+
+      {open && (
+        <div className="settings-popout__panel" role="dialog" aria-label="User settings">
+          <div className="settings-popout__header">Settings</div>
+
+          {/* Access tier. While resolving, the state still says 'public' —
+              rendering "Guest" there would be a wrong answer that corrects
+              itself a moment later, which reads exactly like the lag this
+              placeholder exists to remove. */}
+          <section className="settings-popout__row">
+            <span className="settings-popout__label">Access tier</span>
+            {resolving ? (
+              <span className="settings-popout__value">…</span>
+            ) : (
+              <span className={`settings-popout__tier settings-popout__tier--${userType}`}>
+                {TIER_LABEL[userType]}
+              </span>
+            )}
+          </section>
+
+          {/* Display name */}
+          <section className="settings-popout__row">
+            <span className="settings-popout__label">Display name</span>
+            {resolving ? (
+              <span className="settings-popout__value">…</span>
+            ) : editingName ? (
+              <span className="settings-popout__inline">
+                <input
+                  className="settings-popout__input"
+                  value={nameDraft}
+                  maxLength={64}
+                  autoFocus
+                  disabled={nameSaving}
+                  onChange={e => setNameDraft(e.target.value)}
+                  onKeyDown={e => {
+                    if (e.key === 'Enter') {
+                      saveName().catch(reportErr)
+                    }
+                    if (e.key === 'Escape') {
+                      setEditingName(false)
+                      setNameDraft(displayName ?? '')
+                    }
+                  }}
+                />
+                <button
+                  type="button"
+                  className="settings-popout__btn settings-popout__btn--primary"
+                  disabled={nameSaving}
+                  onClick={() => {
+                    saveName().catch(reportErr)
+                  }}
+                >
+                  {nameSaving ? '…' : 'Save'}
+                </button>
+              </span>
+            ) : (
+              <span className="settings-popout__inline">
+                <span className="settings-popout__value">{displayName || 'Unnamed'}</span>
+                <button
+                  type="button"
+                  className="settings-popout__btn"
+                  onClick={() => {
+                    setNameDraft(displayName ?? '')
+                    setEditingName(true)
+                  }}
+                >
+                  Edit
+                </button>
+              </span>
+            )}
+          </section>
+
+          {/* Content visibility level. Held back until the first-open fetch
+              settles, so it lands in the same paint as the tier and name
+              rather than a round trip behind them. `content` is fetched
+              concurrently with whoami(), so by then it is already here. */}
+          {!resolving && showContentPill && (
+            <section className="settings-popout__row settings-popout__row--stack">
+              <span className="settings-popout__label">Content visibility</span>
+              {content ? (
+                <>
+                  <div
+                    className="settings-popout__pill"
+                    role="radiogroup"
+                    aria-label="Content visibility level"
+                  >
+                    {Array.from({ length: content.maxLevel }, (_, i) => i + 1).map(lvl => (
+                      <button
+                        key={lvl}
+                        type="button"
+                        role="radio"
+                        aria-checked={lvl === content.level}
+                        aria-label={`Level ${lvl}`}
+                        className={`settings-popout__seg${
+                          lvl <= content.level ? ' settings-popout__seg--filled' : ''
+                        }`}
+                        disabled={levelSaving}
+                        onClick={() => {
+                          pickLevel(lvl).catch(reportErr)
+                        }}
+                      >
+                        {lvl}
+                      </button>
+                    ))}
+                  </div>
+                  <span className="settings-popout__hint">
+                    Higher levels reveal more mature content across apps. Level 1 is
+                    safe-for-everyone.
+                  </span>
+                </>
+              ) : (
+                // Not "Loading…" — the fetch has already settled by the time
+                // this section renders at all, so a null here means it failed.
+                <span className="settings-popout__hint">Currently unavailable.</span>
+              )}
+            </section>
+          )}
+
+          {/* Switch key. Signs in inline through the SITE's sign-in client
+              (the /auth page's own code path), never a post of ours. A real
+              <form> with a username + current-password pair, so password
+              managers offer and save the key. */}
+          {keyFormOpen ? (
+            <section className="settings-popout__row settings-popout__row--stack">
+              <form
+                className="settings-popout__key-form"
+                onSubmit={e => {
+                  e.preventDefault()
+                  submitKey().catch(reportErr)
+                }}
+              >
+                <input
+                  type="text"
+                  name="username"
+                  autoComplete="username"
+                  value="hadoku"
+                  readOnly
+                  hidden
+                />
+                <label className="settings-popout__label" htmlFor="settings-popout-key">
+                  Access key
+                </label>
+                <span className="settings-popout__inline">
+                  <input
+                    id="settings-popout-key"
+                    className="settings-popout__input"
+                    type="password"
+                    name="password"
+                    autoComplete="current-password"
+                    autoCapitalize="none"
+                    spellCheck={false}
+                    autoFocus
+                    value={keyDraft}
+                    disabled={keyBusy}
+                    aria-invalid={keyError !== null}
+                    aria-describedby={keyError ? 'settings-popout-key-error' : undefined}
+                    onChange={e => setKeyDraft(e.target.value)}
+                  />
+                  <button
+                    type="submit"
+                    className="settings-popout__btn settings-popout__btn--primary"
+                    disabled={keyBusy}
+                  >
+                    {keyBusy ? 'Signing in…' : 'Sign in'}
+                  </button>
+                </span>
+                {keyError && (
+                  <span
+                    id="settings-popout-key-error"
+                    className="settings-popout__error"
+                    role="alert"
+                  >
+                    {keyError}
+                  </span>
+                )}
+              </form>
+            </section>
+          ) : (
+            <section className="settings-popout__row">
+              <span className="settings-popout__label">Access key</span>
+              <button type="button" className="settings-popout__btn" onClick={openKeyForm}>
+                Switch key
+              </button>
+            </section>
+          )}
+
+          {/* App-specific settings (optional) — same popout, one gear. */}
+          {children && (
+            <section className="settings-popout__row settings-popout__row--stack settings-popout__app">
+              {children}
+            </section>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ConnectedThemePicker.tsx

@@ -0,0 +1,79 @@
+/**
+ * ConnectedThemePicker - Stateful theme picker component
+ * A convenience wrapper around ThemePicker with built-in state management
+ */
+
+import React from 'react'
+import { ThemePicker } from './ThemePicker'
+import type { ThemeFamily, DropdownPlacement } from '../types'
+
+export interface ConnectedThemePickerProps {
+  /** Available theme families */
+  themeFamilies: ThemeFamily[]
+  /** Current active theme */
+  currentTheme: string
+  /** Callback when theme is changed */
+  onThemeChange: (theme: string) => void
+  /** Optional: Function to get icon for current theme (for toggle button) */
+  getThemeIcon?: (theme: string) => React.ReactNode
+  /** Optional: CSS class name for the container */
+  className?: string
+  /** Optional callback when settings icon is clicked */
+  onSettingsClick?: () => void
+  /** Optional: Direction the dropdown opens. Defaults to 'auto' (edge detection) */
+  dropdownPlacement?: DropdownPlacement
+}
+
+/**
+ * ConnectedThemePicker - A stateful theme picker with built-in open/close state management
+ *
+ * This component manages its own isOpen state, making it easier to use than the base ThemePicker.
+ *
+ * @example
+ * ```tsx
+ * import { ConnectedThemePicker } from '@wolffm/task-ui-components'
+ * import { THEME_FAMILIES, THEME_ICON_MAP } from '@wolffm/themes'
+ * import '@wolffm/task-ui-components/theme-picker.css'
+ *
+ * function App() {
+ *   const { theme, setTheme } = useTheme()
+ *
+ *   return (
+ *     <ConnectedThemePicker
+ *       themeFamilies={THEME_FAMILIES}
+ *       currentTheme={theme}
+ *       onThemeChange={setTheme}
+ *       getThemeIcon={(theme) => {
+ *         const Icon = THEME_ICON_MAP[theme]
+ *         return Icon ? <Icon /> : null
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function ConnectedThemePicker({
+  themeFamilies,
+  currentTheme,
+  onThemeChange,
+  getThemeIcon,
+  className,
+  onSettingsClick,
+  dropdownPlacement
+}: ConnectedThemePickerProps) {
+  const [isOpen, setIsOpen] = React.useState(false)
+
+  return (
+    <ThemePicker
+      currentTheme={currentTheme}
+      isOpen={isOpen}
+      themeFamilies={themeFamilies}
+      onThemeChange={onThemeChange}
+      onToggle={() => setIsOpen(!isOpen)}
+      getThemeIcon={getThemeIcon}
+      className={className}
+      onSettingsClick={onSettingsClick}
+      dropdownPlacement={dropdownPlacement}
+    />
+  )
+}

package/src/components/ContextMenu.tsx

@@ -0,0 +1,48 @@
+/**
+ * ContextMenu Component
+ * Generic context menu with position-based rendering
+ */
+
+import React from 'react'
+import '../context-menu.css'
+
+export interface ContextMenuItem {
+  /** ReactNode, not string, so callers can put an <Icon> beside the text. */
+  label: React.ReactNode
+  onClick: () => void | Promise<void>
+  isDanger?: boolean
+  disabled?: boolean
+}
+
+export interface ContextMenuProps {
+  isOpen: boolean
+  x: number
+  y: number
+  items: ContextMenuItem[]
+  className?: string
+}
+
+export function ContextMenu({ isOpen, x, y, items, className = 'context-menu' }: ContextMenuProps) {
+  if (!isOpen) return null
+
+  // Use CSS custom properties for dynamic positioning
+  const style = {
+    '--context-menu-x': `${x}px`,
+    '--context-menu-y': `${y}px`
+  } as React.CSSProperties
+
+  return (
+    <div className={className} style={style}>
+      {items.map((item, index) => (
+        <button
+          key={index}
+          className={`context-menu-item ${item.isDanger ? 'context-menu-item--danger' : ''}`}
+          onClick={item.onClick}
+          disabled={item.disabled}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/components/HadokuThemePicker.tsx

@@ -0,0 +1,39 @@
+/**
+ * HadokuThemePicker — the platform theme picker, placeable anywhere, and
+ * configurable nowhere.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Locking the picker inside AppHeader made it uniform, but it also made it
+ * unreachable for an app that has no header row. watchpart2 is that app: its
+ * UI is an overlay on a video surface, and its picker lives in the chat panel's
+ * button strip. Under a header-only API its only options were to grow a header
+ * it does not want, or keep hand-rolling — and hand-rolling is what this whole
+ * effort removes.
+ *
+ * So the enforcement is not "you may not PLACE the picker", it is "you may not
+ * CONFIGURE it". This component takes no props at all. There is no themeFamilies
+ * to pass a different list to, no getThemeIcon to slip a debug logger into, no
+ * className to restyle it with, no isOpen to manage differently — those props
+ * are exactly how the old ConnectedThemePicker drifted. Everything comes from
+ * <HadokuThemeRoot>.
+ *
+ * AppHeader renders this internally. An app with no header renders it directly.
+ * Both get the identical control, because there is no way to ask for a
+ * different one.
+ */
+import React from 'react'
+import { ConnectedThemePicker } from './ConnectedThemePicker'
+import { useHadokuTheme } from '@wolffm/themes'
+
+export function HadokuThemePicker() {
+  const t = useHadokuTheme()
+  return (
+    <ConnectedThemePicker
+      themeFamilies={t.themeFamilies}
+      currentTheme={t.theme}
+      onThemeChange={t.setTheme}
+      getThemeIcon={t.getThemeIcon}
+    />
+  )
+}