hazo_ui 4.8.0 → 4.10.0

package/CHANGE_LOG.md

@@ -5,6 +5,127 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v4.10.0 (2026-07-09)
+
+### New
+- **`Logo`, `AppHeader`, `AppFooter` chrome components** (framework-neutral,
+  `"use client"`) — consume hazo_theme's `BrandIdentity` contract (type-only
+  import) plus the new `footer-public-*`/`footer-app-*` chrome tokens:
+  - `Logo({ logoUrl?, logoUrlDark?, appTitle?, href?, height?, className?,
+    imgClassName? })` — renders the light/dark logo image (swapped via
+    `dark:hidden`/`dark:block`), falling back to `appTitle` as text when no
+    `logoUrl` is set. Prop names intentionally mirror `BrandIdentity`'s fields
+    so a caller can spread an identity object directly: `<Logo {...identity}
+    />`.
+  - `AppHeader({ identity?, homeHref?, navItems?, actions?, className? })` — a
+    `bg-navbar`/`text-navbar-fg` header bar wrapping `Logo` plus nav/actions
+    slots.
+  - `AppFooter({ variant: 'public' | 'app', footer?, identity?, className? })`
+    — `'app'` renders the thin `bg-footer-app` strip (copyright + one link
+    row); `'public'` renders the taller multi-column `bg-footer-public` block
+    (brand row, link columns, social links), reading from `footer` or falling
+    back to `identity.footer[variant]`.
+  - All three are new exports from the package root; `hazo_theme` stays an
+    optional peer — the components don't import runtime code from it, only
+    the `BrandIdentity`/`FooterConfig` types.
+- **`safeHref(url?: string): string | undefined`** exported from the package
+  root — scheme-allowlist for admin-configurable hrefs (`http://`, `https://`,
+  `mailto:`, or a same-origin `/path` that isn't protocol-relative `//host`;
+  anything else, including `javascript:`/`data:`, returns `undefined`). Every
+  `<a href>` sink inside the new chrome components (footer links, social
+  links) runs through it — XSS hardening for hrefs sourced from
+  admin-editable branding data.
+- **`HazoUiDialog` header bar is now token-driven** — the header bar
+  background/foreground (previously hardcoded `#1e293b` background / white
+  text) now default to hazo_theme's `--dialog-header-bar-bg` /
+  `--dialog-header-bar-fg` tokens, and respect the existing per-variant
+  tinting (`headerColor`/`kind`) the same way the rest of the dialog does.
+- **`HazoUiDialog` `kind` prop** (PRD hazo_theme §5.7) — orthogonal rendering/behavior
+  profile: `'form' | 'confirm' | 'status' | 'content'`. `kind` is a discriminated
+  union on `HazoUiDialogProps`: `title` is a required `string` for `'form'`/`'confirm'`,
+  and stays optional (defaulting to `"Action required"`) for `'status'`/`'content'`/
+  omitted — omitting `kind` entirely is byte-for-byte the pre-existing default
+  behavior (regression guard, verified via `npm run build` + `type-check`).
+  - `'form'` — comfortable body/label typography via the hazo_theme
+    `--dialog-body-size` / `--dialog-label-size` tokens.
+  - `'confirm'` — the compact centered-card layout previously hardcoded into
+    `HazoUiConfirmDialog` (see below).
+  - `'status'` — tinted header (via `--dialog-<variant>-bg/-fg`) with a single
+    acknowledge button (`showCancelButton=false`, `actionButtonText="OK"` by
+    default); `closeOnConfirm` defaults to `true` (self-closing) for this kind.
+  - `'content'` — unchanged sticky header/footer + scrollable body (this was
+    already the default structure).
+- Added optional peer dependency `hazo_theme@^0.1.0` (`peerDependenciesMeta.hazo_theme.optional = true`).
+  hazo_ui does not import from hazo_theme; the `--dialog-*` CSS custom
+  properties referenced below only resolve when the CONSUMING app imports
+  `hazo_theme/tokens.css`.
+
+### Changed
+- **`HazoUiConfirmDialog` is now a thin wrapper** over `<HazoUiDialog kind="confirm">`.
+  Its exported `HazoUiConfirmDialogProps` interface and `ConfirmDialogVariant` type
+  are UNCHANGED — zero prop-level breaking changes for existing consumers
+  (verified: `hazo_pay`'s `billing_admin_panel.tsx` and `hazo_config`'s
+  `app_config_list_editor.tsx` both still build with no changes on their end).
+  One documented behavior simplification: the old component allowed
+  independently-colored `accentColor` (border) vs. `confirmButtonColor` (button);
+  the new wrapper folds both into a single accent (`confirmButtonColor` wins if
+  both are set), since no known consumer relied on divergent values.
+- **`VARIANT_PRESETS` (dialog) / `CONFIRM_VARIANT_PRESETS` (confirm dialog,
+  now deleted) hardcoded RGB → hazo_theme `--dialog-*` tokens.** This is a
+  **visual-only change** — flag it as a **major version bump** on the next
+  publish, since dialog/confirm-dialog appearance shifts for any consumer.
+  - Consumers that already import `hazo_theme/tokens.css` get the intended,
+    theme-consistent look automatically (dark/light + brand theme-sets).
+  - Consumers that do NOT import `hazo_theme/tokens.css` degrade gracefully:
+    an undefined CSS custom property used inside `hsl(var(--undefined-var))`
+    (or referenced directly, for the pre-wrapped `--dialog-<variant>-bg/-fg`
+    tokens) produces an invalid color value, which browsers simply ignore —
+    falling back to the previous/inherited value (e.g. transparent background,
+    inherited text color) rather than crashing or rendering `red`/broken
+    styles. Net effect: variant tinting silently disappears, dialogs still
+    render and function correctly. **Action for consumers wanting the
+    intended look: import `hazo_theme/tokens.css`.**
+  - hazo_theme exposes exactly one bg + one fg token per status (no separate
+    "header" vs. "description" shade), so the old two-tone split-header effect
+    is flattened to a single shade per variant.
+  - `kind="status"`/`kind="confirm"` at `variant="default"` (no per-status
+    token pair exists for "default") fall back to a neutral tint derived from
+    `--dialog-border` / `--dialog-fg` instead of leaving the header untinted.
+
+## v4.9.0 (2026-07-06)
+
+### New
+- **Theme Kit** — packaged, SSR-safe dark/light theme using the shadcn
+  `.dark`-class convention (toggles a `dark` class on `<html>`). New exports:
+  - `HazoThemeProvider` — context provider that keeps `<html class="dark">` in
+    sync with the resolved theme. Props `defaultTheme` (`"light" | "dark" |
+    "system"`, default `"system"`) and `storageKey` (default `"theme"`).
+    `window`/`document` are only touched inside `useEffect`, so no hydration
+    mismatch.
+  - `useTheme()` — `{ theme, setTheme, resolvedTheme, toggleTheme }`; throws
+    outside the provider.
+  - `ThemeToggle` — accessible Sun/Moon button; renders a stable icon until
+    mounted to avoid a first-render hydration mismatch.
+  - `ThemeScript` — inline no-flash script for the root `<head>`; sets the
+    `dark` class before first paint. Wrapped in try/catch so it can never
+    block rendering.
+  - Types: `Theme`, `ThemeProviderProps`, `ThemeContextValue`,
+    `ThemeScriptProps`, `ThemeToggleProps`.
+
+  ```tsx
+  // app/layout.tsx
+  import { HazoThemeProvider, ThemeScript } from 'hazo_ui';
+
+  <html lang="en" suppressHydrationWarning>
+    <head><ThemeScript storageKey="theme" /></head>
+    <body>
+      <HazoThemeProvider defaultTheme="system" storageKey="theme">
+        {children}
+      </HazoThemeProvider>
+    </body>
+  </html>
+  ```
+
 ## v4.7.0 (2026-07-01)
 
 ### New

package/README.md

@@ -214,6 +214,10 @@ The following components support both global config and prop-level color overrid
 
 - **[Chart Primitives](#chart-primitives-v2170)** (v2.17.0) - Pure-SVG chart components for KPI cards and trend dashboards: `Sparkline`, `InverseSparkline`, `LineChart`, `MultiLineChart`, `StackedBars`, and `DateRangeSelector`. Zero third-party chart deps. Gap-aware paths, hover tooltips, and per-series endpoint markers built in.
 
+- **[Theme Kit](#theme-kit-v490)** (v4.9.0) - SSR-safe dark/light theme using the shadcn `.dark`-class convention: `HazoThemeProvider`, `useTheme`, `ThemeToggle`, and a no-flash `ThemeScript`. Persists the chosen mode to `localStorage` and resolves `"system"` against the OS preference.
+
+- **[Chrome Components](#chrome-components-v4100)** (v4.10.0) - `Logo`, `AppHeader`, and `AppFooter` — framework-neutral header/footer/logo pieces that consume hazo_theme's `BrandIdentity` contract and its `footer-public-*`/`footer-app-*` chrome tokens. Every admin-configurable `<a href>` inside them runs through the new `safeHref()` scheme allowlist.
+
 ### State Primitives (v2.10.0)
 
 Lightweight, opinionated components for the four ubiquitous async states: **loading**, **empty**, **error**, and **success**.
@@ -242,6 +246,87 @@ Lightweight, opinionated components for the four ubiquitous async states: **load
   import { Slider, InputAffix, HazoUiProgressBar, HazoUiEtaProgress, useEtaProgress } from 'hazo_ui';
   ```
 
+### Theme Kit (v4.9.0)
+
+SSR-safe dark/light theme using the shadcn `.dark`-class convention (toggles a `dark` class on `<html>`). No hydration mismatch: `window`/`document` are only touched inside `useEffect`, and an inline `ThemeScript` sets the class before first paint to avoid a flash.
+
+**Exports:** `HazoThemeProvider`, `useTheme`, `ThemeToggle`, `ThemeScript` and types `Theme`, `ThemeProviderProps`, `ThemeContextValue`, `ThemeScriptProps`, `ThemeToggleProps`.
+
+### Chrome Components (v4.10.0)
+
+`Logo`, `AppHeader`, and `AppFooter` — framework-neutral chrome pieces that consume hazo_theme's
+`BrandIdentity` (type-only import; `hazo_theme` stays an optional peer) plus its
+`footer-public-*`/`footer-app-*` chrome tokens (import `hazo_theme/theme.css` for the tokens to
+resolve).
+
+```tsx
+import { AppHeader, AppFooter } from 'hazo_ui';
+import type { BrandIdentity } from 'hazo_theme';
+
+const identity: BrandIdentity = {
+  logoUrl: '/brand/logo.svg',
+  appTitle: 'Acme',
+  footer: { app: { copyright: '© 2026 Acme Inc.' } },
+};
+
+function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <AppHeader identity={identity} homeHref="/" actions={<UserMenu />} />
+      {children}
+      <AppFooter variant="app" identity={identity} />
+    </>
+  );
+}
+```
+
+- `Logo({ logoUrl?, logoUrlDark?, appTitle?, href?, height?, className?, imgClassName? })` — logo
+  image (swaps light/dark variants via `dark:hidden`/`dark:block`) or text fallback.
+- `AppHeader({ identity?, homeHref?, navItems?, actions?, className? })` — `bg-navbar` header bar.
+- `AppFooter({ variant: 'public' | 'app', footer?, identity?, className? })` — `'app'` renders a
+  thin copyright/link strip (`bg-footer-app`); `'public'` renders a taller multi-column footer with
+  a brand row and social links (`bg-footer-public`).
+- **`safeHref(url?: string): string | undefined`** — also exported standalone from the package
+  root. Allows `http://`, `https://`, `mailto:`, and same-origin `/path` hrefs; returns `undefined`
+  for anything else (`javascript:`, `data:`, protocol-relative `//host`, …). Used internally by
+  every chrome-component `<a href>` sink; reach for it directly when rendering admin-configurable
+  links elsewhere.
+
+```tsx
+// app/layout.tsx
+import { HazoThemeProvider, ThemeScript } from 'hazo_ui';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ThemeScript storageKey="theme" />
+      </head>
+      <body>
+        <HazoThemeProvider defaultTheme="system" storageKey="theme">
+          {children}
+        </HazoThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// anywhere under the provider
+import { ThemeToggle, useTheme } from 'hazo_ui';
+
+function Header() {
+  const { theme, resolvedTheme, setTheme } = useTheme();
+  return <ThemeToggle />; // Sun/Moon button that flips light/dark
+}
+```
+
+- `HazoThemeProvider` — context provider; keeps `<html class="dark">` in sync with the resolved theme. Props: `defaultTheme` (`"light" | "dark" | "system"`, default `"system"`), `storageKey` (default `"theme"`).
+- `useTheme()` — `{ theme, setTheme, resolvedTheme, toggleTheme }`. Throws if used outside the provider.
+- `ThemeToggle` — accessible Sun/Moon button; guards against a first-render hydration mismatch by rendering a stable icon until mounted.
+- `ThemeScript` — inline no-flash script; render in the root `<head>` before content, with a `storageKey` matching the provider.
+
 ### shadcn/ui Primitive Re-exports
 
 All shadcn/ui base components are re-exported from hazo_ui, so sibling hazo_* packages (and consumers) can import UI primitives from a single source without installing shadcn/ui separately: