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

package/src/components/AppHeader.tsx

@@ -0,0 +1,87 @@
+/**
+ * AppHeader — the ecosystem-standard top bar for every hadoku.me app.
+ *
+ * Enforces the shared contract so child apps stop drifting:
+ *   [ title (left) ] ————— <space> ————— [ status? · ThemePicker · Settings gear ] (right)
+ *
+ * Everything BELOW the header is the app's own concern. The header owns the
+ * title, and it OWNS both right-hand controls outright — it renders the theme
+ * picker and the settings gear itself. Neither is a prop.
+ *
+ * WHY THEY ARE NOT PROPS ANY MORE
+ * -------------------------------
+ * `themePicker?: React.ReactNode` was an open hole: a slot that accepts a node
+ * accepts ANY node, so "every app uses the same picker" was a convention, and
+ * conventions drift. They did — one app passed a raw `<ThemePicker>` with its
+ * own `isOpen` state and a debug logger wired into `getThemeIcon`, and eight
+ * apps each kept a hand-copied `useTheme` hook to feed it. Those copies had
+ * already diverged on real behaviour (only one wrote `localStorage`, so the
+ * rest lost the theme on browser restart and flashed a default on next paint).
+ *
+ * The control is now rendered here, from `useHadokuTheme()`. An app cannot
+ * substitute, restyle or omit it. What an app CAN do is inject its own
+ * preferences — see `children`.
+ *
+ * @example
+ * ```tsx
+ * import { AppHeader } from '@wolffm/task-ui-components'
+ * import { HadokuThemeRoot } from '@wolffm/themes'
+ *
+ * // once, at the app root:
+ * <HadokuThemeRoot>
+ *   <AppHeader title="Print Tool" status={<ApiStatus status={apiStatus} />}>
+ *     <MyAppPreferences />   // optional: appended AFTER the canonical rows
+ *   </AppHeader>
+ * </HadokuThemeRoot>
+ * ```
+ */
+import React from 'react'
+import { ConnectedSettings, type ConnectedSettingsProps } from './ConnectedSettings'
+import { HadokuThemePicker } from './HadokuThemePicker'
+
+export interface AppHeaderProps {
+  /** Left-aligned header title. A string is wrapped in an <h1>; pass a node for
+   *  custom markup (e.g. a clickable title button). */
+  title: React.ReactNode
+  /** Optional status/extra node shown left of the theme + settings controls
+   *  (e.g. an "API Online" indicator). Acceptable per the header contract. */
+  status?: React.ReactNode
+  /** Identity hints for the settings popout. Narrow on purpose: `userType` and
+   *  `name` exist because an app behind a path-prefixed shim may not be able to
+   *  reach `/session/whoami` (conjure), NOT as a styling or layout hook. */
+  settingsProps?: ConnectedSettingsProps
+  /** THE app-specific extension point. Rendered inside the settings popout as a
+   *  final section, under the four canonical rows. Put your app's own
+   *  preferences here — checkboxes, selects, whatever it needs; this slot is
+   *  deliberately unconstrained. What it cannot do is alter the rows above it. */
+  children?: React.ReactNode
+  /** Extra class on the <header> root. Layout only — it cannot reach the
+   *  controls, which own their own markup. */
+  className?: string
+}
+
+export function AppHeader({
+  title,
+  status,
+  settingsProps,
+  children,
+  className = ''
+}: AppHeaderProps) {
+  // No useHadokuTheme() call here: <HadokuThemePicker> reads the context and
+  // throws its own actionable error when the app root was never wrapped, so a
+  // second read would only duplicate that.
+  return (
+    <header className={`app-header ${className}`.trim()}>
+      {typeof title === 'string' ? (
+        <h1 className="app-header__title">{title}</h1>
+      ) : (
+        <div className="app-header__title">{title}</div>
+      )}
+      <div className="app-header__actions">
+        {status}
+        <HadokuThemePicker />
+        <ConnectedSettings {...settingsProps}>{children}</ConnectedSettings>
+      </div>
+    </header>
+  )
+}

package/src/components/BentoCard.tsx

@@ -0,0 +1,72 @@
+/**
+ * BentoCard Component
+ * Base card component for bento grid layouts
+ * Supports various sizes and disabled state for preloading
+ */
+
+import React from 'react'
+
+export type CardSize = 'default' | 'wide' | 'tall' | 'large' | 'hero'
+
+export interface BentoCardProps {
+  children: React.ReactNode
+  className?: string
+  /** Card size affects grid span */
+  size?: CardSize
+  /** Disable interactions (for preload state) */
+  disabled?: boolean
+  /** Click handler */
+  onClick?: () => void
+  /** Custom aria-label for accessibility */
+  ariaLabel?: string
+  /** Optional data attributes for animation libraries */
+  'data-layout-id'?: string
+}
+
+const sizeClasses: Record<CardSize, string> = {
+  default: 'bento-card--default',
+  wide: 'bento-card--wide',
+  tall: 'bento-card--tall',
+  large: 'bento-card--large',
+  hero: 'bento-card--hero'
+}
+
+export function BentoCard({
+  children,
+  className = '',
+  size = 'default',
+  disabled = false,
+  onClick,
+  ariaLabel,
+  'data-layout-id': layoutId,
+  ...rest
+}: BentoCardProps) {
+  const handleClick = () => {
+    if (!disabled && onClick) {
+      onClick()
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if ((e.key === 'Enter' || e.key === ' ') && !disabled && onClick) {
+      e.preventDefault()
+      onClick()
+    }
+  }
+
+  return (
+    <article
+      className={`bento-card ${sizeClasses[size]} ${disabled ? 'bento-card--disabled' : ''} ${className}`}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      role={onClick ? 'button' : undefined}
+      tabIndex={onClick && !disabled ? 0 : undefined}
+      aria-label={ariaLabel}
+      aria-disabled={disabled}
+      data-layout-id={layoutId}
+      {...rest}
+    >
+      {children}
+    </article>
+  )
+}

package/src/components/BentoGrid.tsx

@@ -0,0 +1,48 @@
+/**
+ * BentoGrid Component
+ * Responsive grid container for bento-style card layouts
+ * Automatically adjusts columns based on viewport size
+ */
+
+import React from 'react'
+
+export type BentoColumns = 1 | 2 | 3 | 4 | 6
+
+export interface BentoGridProps {
+  children: React.ReactNode
+  className?: string
+  /** Column configuration at each breakpoint */
+  columns?: {
+    sm?: BentoColumns
+    md?: BentoColumns
+    lg?: BentoColumns
+    xl?: BentoColumns
+  }
+  /** Gap between cards in rem */
+  gap?: number
+  /** Maximum width of the grid */
+  maxWidth?: string
+}
+
+export function BentoGrid({
+  children,
+  className = '',
+  columns = { sm: 2, md: 3, lg: 4, xl: 6 },
+  gap = 1,
+  maxWidth = '1400px'
+}: BentoGridProps) {
+  const gridStyle: React.CSSProperties = {
+    '--bento-gap': `${gap}rem`,
+    '--bento-max-width': maxWidth,
+    '--bento-cols-sm': columns.sm ?? 2,
+    '--bento-cols-md': columns.md ?? 3,
+    '--bento-cols-lg': columns.lg ?? 4,
+    '--bento-cols-xl': columns.xl ?? 6
+  } as React.CSSProperties
+
+  return (
+    <div className={`bento-grid ${className}`} style={gridStyle}>
+      {children}
+    </div>
+  )
+}

package/src/components/Button.tsx

@@ -0,0 +1,81 @@
+/**
+ * Button Component
+ * Themed button in five treatments x five colour families, so an app never
+ * falls back to the browser's default button chrome.
+ */
+
+import React from 'react'
+import { Icon, type IconName } from '@wolffm/themes'
+import '../button.css'
+
+export type ButtonVariant = 'solid' | 'gradient' | 'soft' | 'outline' | 'ghost'
+export type ButtonFamily = 'primary' | 'success' | 'warning' | 'danger' | 'neutral'
+export type ButtonSize = 'sm' | 'md' | 'lg'
+export type ButtonShape = 'rounded' | 'pill' | 'square'
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant
+  family?: ButtonFamily
+  size?: ButtonSize
+  shape?: ButtonShape
+  /** Registry icon before the label. */
+  icon?: IconName
+  /** Registry icon after the label (e.g. `chevron-down` on a menu button). */
+  iconEnd?: IconName
+  /** Shows a spinner, sets aria-busy and blocks clicks. */
+  loading?: boolean
+  /** Stretch to the container width. */
+  block?: boolean
+}
+
+const ICON_SIZE: Record<ButtonSize, number> = { sm: 14, md: 16, lg: 18 }
+
+export function Button({
+  variant = 'soft',
+  family = 'primary',
+  size = 'md',
+  shape = 'rounded',
+  icon,
+  iconEnd,
+  loading = false,
+  block = false,
+  disabled,
+  type = 'button',
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  // An icon with no label is a square button; it still needs an aria-label.
+  const iconOnly = !children && (icon || iconEnd)
+  const classes = [
+    'hdk-btn',
+    `hdk-btn--${variant}`,
+    `hdk-btn--${family}`,
+    `hdk-btn--${size}`,
+    `hdk-btn--${shape}`,
+    iconOnly && 'hdk-btn--icon-only',
+    block && 'hdk-btn--block',
+    loading && 'hdk-btn--loading',
+    className
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <button
+      type={type}
+      className={classes}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      {...rest}
+    >
+      {loading ? (
+        <span className="hdk-btn__spinner" aria-hidden="true" />
+      ) : (
+        icon && <Icon name={icon} size={ICON_SIZE[size]} />
+      )}
+      {children}
+      {iconEnd && <Icon name={iconEnd} size={ICON_SIZE[size]} />}
+    </button>
+  )
+}