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

package/src/controls.css

@@ -0,0 +1,137 @@
+/* Themed fallbacks for the browser's own control styling, for
+ * @wolffm/task-ui-components.
+ *
+ *   import '@wolffm/task-ui-components/controls.css'
+ *   <html class="hdk-controls">
+ *
+ * hadoku_site puts `hdk-controls` on <html>, which covers every
+ * micro-frontend. Every selector is wrapped in `:where()`, so all of it has
+ * ZERO specificity: it only fills in where an app styled nothing. An app's
+ * own rule for the same property — any selector at all — wins, whatever order
+ * the sheets load in. An author rule of any specificity still beats the
+ * browser's stylesheet, which is all this needs to.
+ *
+ * What it covers, each the browser default it replaces:
+ *   - focus ring        Chrome's two-tone `outline: auto`  -> the accent
+ *   - links             -webkit-link blue / visited purple -> the text around it
+ *   - checkbox, radio, range, progress  system blue        -> accent-color
+ *   - text selection    system highlight                   -> the accent tint
+ *   - placeholder       darkgray                           -> tertiary text
+ *   - <summary> marker  text-colour triangle               -> secondary text
+ *   - file picker       OS "Choose file" button            -> a soft button
+ *   - number spinners   OS up/down arrows                  -> removed (arrow keys
+ *                       still step; <NumberInput> is the themed stepper)
+ *   - text fields and textarea, buttons, a select's closed box: the system
+ *     field/button chrome -> the theme's card surface and border
+ *
+ * The open list of a <select> is not CSS-reachable at all; installSelectMenus()
+ * replaces it. Date and time pickers stay OS-drawn: apps own those.
+ *
+ * Everything sits in `@layer hdk-fallbacks`. A rule in a cascade layer loses
+ * to every unlayered rule and to every layer declared after it — whatever
+ * either's specificity — and Tailwind ships its utilities in layers. Unlayered,
+ * even a zero-specificity rule here would beat `bg-primary`. The page must
+ * declare the layer FIRST, before any other, so it ranks lowest:
+ *
+ *   @layer hdk-fallbacks, base, theme, utilities;
+ *
+ * hadoku_site's global.css does that. A sheet that never names it just gets
+ * these rules below its own unlayered ones, which is also correct.
+ */
+
+@layer hdk-fallbacks {
+  /* accent-color inherits, so it is declared once per theme scope rather than
+   * per element: an app's accent-color on a container still reaches its
+   * children, and a nested [data-theme] still resolves its own accent. */
+  :where(.hdk-controls),
+  :where(.hdk-controls [data-theme]) {
+    accent-color: var(--color-primary);
+  }
+
+  :where(.hdk-controls) :where(:focus-visible) {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+
+  /* The browser colours a link directly rather than letting it inherit, so a
+   * link nobody styled is blue on any surface. `inherit` is what an app means
+   * when it styles the surface and not the link (Tailwind's preflight does the
+   * same); the underline keeps it reading as a link. */
+  :where(.hdk-controls) :where(a:any-link) {
+    color: inherit;
+  }
+
+  :where(.hdk-controls) ::selection {
+    background-color: var(--color-primary-bg);
+    color: var(--color-on-primary-bg);
+  }
+
+  :where(.hdk-controls) ::placeholder {
+    color: var(--color-text-tertiary);
+    opacity: 1;
+  }
+
+  :where(.hdk-controls) :where(summary)::marker {
+    color: var(--color-text-secondary);
+  }
+
+  :where(.hdk-controls) :where(input[type='file'])::file-selector-button {
+    margin-inline-end: 8px;
+    padding: 4px 10px;
+    font: inherit;
+    font-weight: var(--font-weight-semibold);
+    color: var(--color-on-neutral-bg);
+    background-color: var(--color-neutral-bg);
+    border: 1px solid transparent;
+    border-radius: var(--hdk-radius);
+    cursor: pointer;
+  }
+
+  :where(.hdk-controls) :where(input[type='file'])::file-selector-button:hover {
+    border-color: var(--color-neutral);
+  }
+
+  :where(.hdk-controls) :where(input[type='number']) {
+    appearance: textfield;
+  }
+
+  :where(.hdk-controls) :where(input[type='number'])::-webkit-inner-spin-button,
+  :where(.hdk-controls) :where(input[type='number'])::-webkit-outer-spin-button {
+    appearance: none;
+    margin: 0;
+  }
+
+  /* Field chrome: only the properties that make up the system look. No padding,
+   * radius, font or size: those decide layout and shape, and an app that
+   * styled a field's background but not its padding must not see it move. */
+  :where(.hdk-controls)
+    :where(
+      input:not(
+        [type='checkbox'],
+        [type='radio'],
+        [type='range'],
+        [type='file'],
+        [type='color'],
+        [type='button'],
+        [type='submit'],
+        [type='reset'],
+        [type='image']
+      ),
+      textarea,
+      select
+    ) {
+    color: var(--color-text);
+    background-color: var(--color-bg-card);
+    border: 1px solid var(--color-border);
+  }
+
+  :where(.hdk-controls)
+    :where(button, input[type='button'], input[type='submit'], input[type='reset']) {
+    /* inherit, not a token: an app that coloured a button's surface and not
+     * its text, or draws with currentColor inside it, keeps the colour it
+     * had from the page instead of jumping to the neutral tint's ink. */
+    color: inherit;
+    background-color: var(--color-neutral-bg);
+    border: 1px solid transparent;
+  }
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,36 @@
+/**
+ * useReducedMotion Hook
+ * Detects if the user prefers reduced motion
+ * Returns true if animations should be disabled or simplified
+ */
+
+import { useState, useEffect } from 'react'
+
+export function useReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+    // SSR and jsdom have no matchMedia: default to false.
+    if (typeof window === 'undefined' || !window.matchMedia) return false
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  })
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)')
+
+    const handleChange = (event: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches)
+    }
+
+    // Modern browsers
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener('change', handleChange)
+      return () => mediaQuery.removeEventListener('change', handleChange)
+    }
+
+    // Fallback for older browsers
+    mediaQuery.addListener(handleChange)
+    return () => mediaQuery.removeListener(handleChange)
+  }, [])
+
+  return prefersReducedMotion
+}

package/src/hooks/useToast.ts

@@ -0,0 +1,57 @@
+/**
+ * useToast hook
+ * Manages toast notification state and display
+ */
+
+import { useState, useCallback } from 'react'
+
+export interface ToastState {
+  id: number
+  message: string
+  type: 'success' | 'error' | 'info' | 'warning'
+  duration?: number
+}
+
+export interface UseToastReturn {
+  toasts: ToastState[]
+  showToast: (
+    message: string,
+    type?: 'success' | 'error' | 'info' | 'warning',
+    duration?: number
+  ) => void
+  dismissToast: (id: number) => void
+  clearAll: () => void
+}
+
+let toastIdCounter = 0
+
+export function useToast(): UseToastReturn {
+  const [toasts, setToasts] = useState<ToastState[]>([])
+
+  const showToast = useCallback(
+    (
+      message: string,
+      type: 'success' | 'error' | 'info' | 'warning' = 'info',
+      duration: number = 3000
+    ) => {
+      const id = ++toastIdCounter
+      setToasts(prev => [...prev, { id, message, type, duration }])
+    },
+    []
+  )
+
+  const dismissToast = useCallback((id: number) => {
+    setToasts(prev => prev.filter(toast => toast.id !== id))
+  }, [])
+
+  const clearAll = useCallback(() => {
+    setToasts([])
+  }, [])
+
+  return {
+    toasts,
+    showToast,
+    dismissToast,
+    clearAll
+  }
+}

package/src/icon-btn.css

@@ -0,0 +1,64 @@
+/* The round 32px icon button on the AppHeader bar — the theme picker trigger,
+ * the settings gear, and any link an app puts in the actions row.
+ *
+ * Defined ONCE. The picker and the gear each used to carry their own copy and
+ * the two had already drifted (padding 8px vs --hdk-space-sm, a ring on every
+ * mouse click vs on :focus-visible, a min-size on one only). `.theme-toggle-btn`
+ * and `.settings-toggle-btn` survive as hooks with no values of their own.
+ *
+ * Lives in its own file because ThemePicker renders outside the header too
+ * (HadokuThemePicker on a video overlay), so its trigger cannot depend on
+ * app-header.css. The chain is app-header.css -> theme-picker.css -> this.
+ *
+ * Works on an <a>: child apps ship without a preflight, so a bare anchor would
+ * render UA blue, visited purple and underlined. */
+
+.app-header__icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: 32px;
+  height: 32px;
+  min-width: 32px;
+  min-height: 32px;
+  padding: 0;
+  margin: 0;
+  border: none;
+  border-radius: 50%;
+  background: none;
+  color: var(--color-text);
+  font: inherit;
+  font-size: var(--hdk-text-lg);
+  line-height: 1;
+  text-decoration: none;
+  cursor: pointer;
+  opacity: 0.7;
+  transition:
+    background-color var(--transition-fast),
+    opacity var(--transition-fast);
+}
+
+/* Same colour visited or not, and no hover recolour from a host stylesheet's
+ * `a:hover` — the hover signal is the background below. */
+.app-header__icon-btn:link,
+.app-header__icon-btn:visited,
+.app-header__icon-btn:hover,
+.app-header__icon-btn:active {
+  color: var(--color-text);
+  text-decoration: none;
+}
+
+.app-header__icon-btn:hover {
+  background-color: var(--color-primary-hover);
+  opacity: 1;
+}
+
+/* :focus-visible, not :focus — :focus rings on every mouse click. Full
+ * opacity too, so a keyboard user never lands on the dimmed resting state. */
+.app-header__icon-btn:focus-visible {
+  outline: none;
+  opacity: 1;
+  box-shadow: 0 0 0 2px var(--color-primary);
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+/**
+ * @wolffm/task-ui-components
+ * Reusable UI components for task management applications
+ * Production-ready and fully typed
+ *
+ * 2.2.0 — AppHeader + ConnectedSettings (with a `children` extension slot).
+ */
+
+// Main components
+//
+// NOTE: `ThemePicker` and `ConnectedThemePicker` are intentionally NOT exported.
+// AppHeader renders the theme picker itself from the HadokuThemeRoot context,
+// so every app gets the same control by construction. Exporting them is what
+// let an app hand-roll its own (with its own open-state and a debug logger in
+// the icon resolver) — a compile error is the only enforcement that actually
+// holds. If you need theme state, use `useTheme()` from @wolffm/themes.
+// The picker itself, for an app with no header row to put it in (watchpart2's
+// UI is a video overlay). It takes NO props — placement is free, configuration
+// is not, which is the property that keeps it identical everywhere.
+export { HadokuThemePicker } from './components/HadokuThemePicker'
+export { AppHeader } from './components/AppHeader'
+export { ConnectedSettings } from './components/ConnectedSettings'
+// Re-exported from @wolffm/themes, which now owns the context AND the provider
+// that fills it. These are RE-EXPORTS, not re-declarations: every consumer gets
+// the one context object from themes, which is what makes a duplicated copy of
+// THIS package harmless. Kept here so existing
+// `import { useHadokuTheme } from '@wolffm/task-ui-components'` call sites
+// across the fleet keep working unchanged.
+export { HadokuThemeProvider, useHadokuTheme, useHadokuThemeOptional } from '@wolffm/themes'
+export type { HadokuThemeValue, HadokuThemeProviderProps } from '@wolffm/themes'
+export { Toast } from './components/Toast'
+export { Toaster } from './components/Toaster'
+export { Modal } from './components/Modal'
+export { ContextMenu } from './components/ContextMenu'
+export { LoadingSkeleton } from './components/LoadingSkeleton'
+export { SettingsModal } from './components/SettingsModal'
+// Themed replacements for the browser's default controls. Scrollbars are
+// CSS only: import '@wolffm/task-ui-components/scrollbar.css' and add
+// `hdk-scroll` to the app root.
+export { Button } from './components/Button'
+export { Select, NativeSelect } from './components/Select'
+export { NumberInput } from './components/NumberInput'
+export { Tooltip } from './components/Tooltip'
+// Framework-free; also its own entry, `@wolffm/task-ui-components/title-tooltips`,
+// so the site shell can install it without React.
+export { installTitleTooltips } from './lib/titleTooltips'
+export type { TitleTooltipOptions } from './lib/titleTooltips'
+// Same, `@wolffm/task-ui-components/select-menus`: the themed list for every
+// native <select>.
+export { installSelectMenus } from './lib/selectMenus'
+
+// Bento components
+export { BentoGrid } from './components/BentoGrid'
+export { BentoCard } from './components/BentoCard'
+
+// Hooks
+export { useToast } from './hooks/useToast'
+export { useReducedMotion } from './hooks/useReducedMotion'
+
+// Theme icons - export individually for flexibility
+export {
+  SettingsIcon,
+  TagIcon,
+  // Generic/Fallback icons
+  CircleIcon,
+  SquareIcon,
+  TriangleIcon,
+  DiamondIcon,
+  StarIcon,
+  HexagonIcon,
+  PentagonIcon,
+  OctagonIcon,
+  FALLBACK_ICONS,
+  getFallbackIcon
+} from './components/ThemeIcons'
+// Theme-family icons moved to @wolffm/themes with the rest of the theme model.
+// Re-exported so existing imports from this package keep resolving.
+export {
+  SunIcon,
+  MoonIcon,
+  StrawberryIcon,
+  WaveIcon,
+  ZapIcon,
+  CoffeeIcon,
+  FlowerIcon,
+  HeartIcon,
+  LeafIcon,
+  LanternIcon
+} from '@wolffm/themes'
+
+// Types
+// ThemeFamily stays — @wolffm/themes builds THEME_FAMILIES against it.
+// ThemePickerProps / ConnectedThemePickerProps are gone with the components:
+// a prop type you cannot render is only useful for reimplementing the control.
+export type { ThemeName, ThemeFamily, DropdownPlacement, ThemeMode } from './types'
+export type { AppHeaderProps } from './components/AppHeader'
+export type { ConnectedSettingsProps } from './components/ConnectedSettings'
+export type { ContentLevelState, Identity, SignIn, SignInResult, Tier } from './lib/settingsClient'
+export { loadSignIn, switchKeyHref } from './lib/settingsClient'
+export type { ToastProps } from './components/Toast'
+export type { ToasterProps, ToastState } from './components/Toaster'
+export type { UseToastReturn } from './hooks/useToast'
+export type { ModalProps } from './components/Modal'
+export type { ContextMenuProps, ContextMenuItem } from './components/ContextMenu'
+export type { LoadingSkeletonProps } from './components/LoadingSkeleton'
+export type {
+  ButtonProps,
+  ButtonVariant,
+  ButtonFamily,
+  ButtonSize,
+  ButtonShape
+} from './components/Button'
+export type {
+  SelectProps,
+  SelectOption,
+  SelectVariant,
+  SelectSize,
+  NativeSelectProps
+} from './components/Select'
+export type { TooltipProps, TooltipPlacement, TooltipVariant } from './components/Tooltip'
+export type {
+  SettingsModalProps,
+  SettingsSection,
+  SettingsField,
+  SettingsToggleField,
+  SettingsTextInputField,
+  SettingsPasswordField,
+  SettingsSelectField,
+  SettingsButtonField,
+  SettingsCustomField
+} from './components/SettingsModal'
+export type { BentoGridProps, BentoColumns } from './components/BentoGrid'
+export type { BentoCardProps, CardSize } from './components/BentoCard'
+
+// `logger` was removed in v2.0.0. Migrate to `@wolffm/logger/client`:
+//   - import { logger } from '@wolffm/task-ui-components'
+//   + import { logger } from '@wolffm/logger/client'
+// See packages/logger in hadoku_site for the consolidated cross-runtime
+// implementation. UI helpers (theme, component, preference, apiRequest,
+// apiResponse, fallback) are preserved on the new client logger.

package/src/lib/menuPlacement.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a dropdown list goes under (or over) its trigger, shared by <Select>
+ * and installSelectMenus so both lists sit and flip identically.
+ */
+
+export const MENU_GAP = 4
+export const MENU_MAX_HEIGHT = 280
+
+export interface MenuPosition {
+  left: number
+  width: number
+  top?: number
+  bottom?: number
+  maxHeight: number
+}
+
+/** `listHeight` is the list's full scrollHeight, so a short list never flips. */
+export function placeMenu(rect: DOMRect, listHeight: number): MenuPosition {
+  const below = window.innerHeight - rect.bottom - MENU_GAP
+  const above = rect.top - MENU_GAP
+  // Flip up only when the list does not fit below AND there is more room above.
+  const flip = below < Math.min(MENU_MAX_HEIGHT, listHeight) && above > below
+  return {
+    left: rect.left,
+    width: rect.width,
+    ...(flip
+      ? { bottom: window.innerHeight - rect.top + MENU_GAP }
+      : { top: rect.bottom + MENU_GAP }),
+    maxHeight: Math.max(120, Math.min(MENU_MAX_HEIGHT, flip ? above : below) - 8)
+  }
+}