weg-shared-layout 0.0.14 → 0.0.15

package/docs/nextjs.md

@@ -2,25 +2,32 @@
 
 Guide for **Next.js 13+ App Router** (`app/` directory). For Vite/CRA-style client-only React, see **[React SPA](./react.md)**.
 
+## Components
+
+| Tag | Purpose |
+| --- | --- |
+| `<weg-header>` | Site header — logo (bundled), nav, Sign in / Sign out |
+| `<weg-footer>` | Site footer — social, columns, legal text |
+
+Both accept **`layout`** (JSON string recommended in Next). `<weg-header>` also accepts **`signed-in`** and emits **`wegAuthClick`**.
+
 ## Why Next.js is different
 
 | Topic | SPA (React 19) | Next.js App Router |
 | --- | --- | --- |
-| **Where `<weg-footer>` runs** | Client only | Must be in a **Client Component** (`"use client"`) |
-| **Server Components** | N/A | Default in `app/` — cannot call `defineCustomElements()` or touch `window` |
-| **SSR output** | N/A | Server HTML is often an **empty** `<weg-footer></weg-footer>` until the client bundle hydrates |
-| **`layout={object}`** | Works on React 19+ | **Does not work reliably** — RSC/SSR serializes props; object props on custom elements become useless attributes |
-| **Recommended `layout` value** | Object (React 19+) or string | **`JSON.stringify(layout)`** always |
-
-Stencil custom elements need browser APIs. Registration and rendering belong in a small client wrapper; the root **Server** layout only imports that wrapper.
+| **Where components run** | Client only | Must be in **Client Components** (`"use client"`) |
+| **Server Components** | N/A | Default in `app/` — cannot call `defineCustomElements()` |
+| **SSR output** | N/A | Often empty custom-element tags until client hydrates |
+| **`layout={object}` on CE** | Works on React 19+ | **Unreliable** — use **`JSON.stringify(layout)`** |
+| **Auth state** | `signed-in` prop | Set in client wrapper from session hook / context |
 
 ## Requirements
 
 | Requirement | Notes |
 | --- | --- |
 | **Next.js 13+** | App Router (`app/layout.tsx`) |
-| **React 19** | Matches current Next defaults; string `layout` still required for custom elements |
-| **`transpilePackages`** | Next must compile `weg-shared-layout` (see below) |
+| **`transpilePackages`** | Next must compile `weg-shared-layout` |
+| **`suppressHydrationWarning`** | Recommended on both tags (SSR placeholder vs client shadow DOM) |
 
 ## Install
 
@@ -32,9 +39,8 @@ pnpm add weg-shared-layout
 
 ## 1. Transpile the package
 
-In `next.config.ts` / `next.config.js`:
-
 ```ts
+// next.config.ts
 import type { NextConfig } from 'next';
 
 const nextConfig: NextConfig = {
@@ -44,66 +50,137 @@ const nextConfig: NextConfig = {
 export default nextConfig;
 ```
 
-Without this, you may see build errors or stale/uncompiled Stencil output in the Next bundle.
+## 2. Client layout components
+
+```tsx
+// src/components/layout/Header.tsx
+'use client';
+
+import { useCallback } from 'react';
+import { defineCustomElements } from 'weg-shared-layout/loader';
+import 'weg-shared-layout/weg-header';
 
-## 2. Client `Footer` component
+defineCustomElements();
 
-Create a dedicated Client Component (pattern verified in [weg-payload](https://github.com/jobsac/weg-payload)):
+type LayoutData = {
+  header?: {
+    dropdowns?: { label: string; items: { label: string; href: string }[] }[];
+    links?: { label: string; href: string }[];
+    signIn?: { label: string; href: string };
+    signOut?: { label: string; href?: string };
+  };
+};
+
+export function Header({
+  layout,
+  signedIn,
+  onSignedInChange,
+}: {
+  layout: LayoutData;
+  signedIn: boolean;
+  onSignedInChange?: (signedIn: boolean) => void;
+}) {
+  const onAuthClick = useCallback(
+    (event: CustomEvent<{ action: 'sign-in' | 'sign-out' }>) => {
+      event.preventDefault();
+
+      if (event.detail.action === 'sign-out') {
+        // your logout(), then:
+        onSignedInChange?.(false);
+        return;
+      }
+
+      window.location.href = layout.header?.signIn?.href ?? '/account/login';
+    },
+    [layout, onSignedInChange],
+  );
+
+  return (
+    <weg-header
+      layout={JSON.stringify(layout)}
+      signed-in={signedIn}
+      suppressHydrationWarning
+      // @ts-expect-error Stencil custom event
+      onWegAuthClick={onAuthClick}
+    />
+  );
+}
+```
 
 ```tsx
 // src/components/layout/Footer.tsx
 'use client';
 
-import layout from 'weg-shared-layout/dummy-data.json';
 import { defineCustomElements } from 'weg-shared-layout/loader';
 import 'weg-shared-layout/weg-footer';
 
 defineCustomElements();
 
-export function Footer() {
+export function Footer({ layout }: { layout: unknown }) {
+  return <weg-footer layout={JSON.stringify(layout)} suppressHydrationWarning />;
+}
+```
+
+```tsx
+// src/components/layout/SiteChrome.tsx — optional wrapper
+'use client';
+
+import { useState } from 'react';
+import { Header } from './Header';
+import { Footer } from './Footer';
+
+export function SiteChrome({
+  layout,
+  children,
+}: {
+  layout: unknown;
+  children: React.ReactNode;
+}) {
+  const [signedIn, setSignedIn] = useState(false);
+
   return (
-    <weg-footer layout={JSON.stringify(layout)} suppressHydrationWarning />
+    <>
+      <Header layout={layout} signedIn={signedIn} onSignedInChange={setSignedIn} />
+      {children}
+      <Footer layout={layout} />
+    </>
   );
 }
 ```
 
-### Why each line matters
+### Why `JSON.stringify` and `suppressHydrationWarning`
 
 | Line | Purpose |
 | --- | --- |
-| `'use client'` | Allows `defineCustomElements`, custom element upgrade, and DOM property updates |
-| `defineCustomElements()` | Registers `<weg-footer>` in the browser (module runs once per client bundle) |
-| `import 'weg-shared-layout/weg-footer'` | Ensures the component definition is bundled |
-| `layout={JSON.stringify(layout)}` | Sets a string attribute/property Next/React can pass through SSR → client; component parses JSON |
-| `suppressHydrationWarning` | Server renders empty tag; client fills content — avoids React hydration mismatch noise |
+| `layout={JSON.stringify(layout)}` | Serializable across RSC → client; component parses JSON |
+| `suppressHydrationWarning` | Server renders empty tag; client fills shadow DOM |
+| `'use client'` | Registration and auth handlers need the browser |
 
-Do **not** pass `layout={layoutObject}` in Next — it will not hydrate correctly.
+Do **not** pass `layout={layoutObject}` directly on the custom elements in Next.
 
-## 3. Server layout: import the client footer
+## 3. Server layout
 
 ```tsx
-// app/layout.tsx (Server Component — no "use client")
-import { Footer } from '@/components/layout/Footer';
+// app/layout.tsx (Server Component)
+import { SiteChrome } from '@/components/layout/SiteChrome';
+import layout from 'weg-shared-layout/dummy-data.json';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
-        {children}
-        <Footer />
+        <SiteChrome layout={layout}>{children}</SiteChrome>
       </body>
     </html>
   );
 }
 ```
 
-Fetch layout on the server and pass it into `<Footer layout={...} />` when you wire production data (see below).
-
-## 4. Production: fetch on the server, stringify for the client
+## 4. Production: fetch layout on the server
 
 ```tsx
 // app/layout.tsx
-import { Footer } from '@/components/layout/Footer';
+import { SiteChrome } from '@/components/layout/SiteChrome';
 
 const LAYOUT_URL = 'https://weg-payload-test.vercel.app/api/layout';
 
@@ -119,62 +196,50 @@ export default async function RootLayout({ children }: { children: React.ReactNo
   return (
     <html lang="en">
       <body>
-        {children}
-        <Footer layout={layout} />
+        <SiteChrome layout={layout}>{children}</SiteChrome>
       </body>
     </html>
   );
 }
 ```
 
-```tsx
-// src/components/layout/Footer.tsx
-'use client';
+Pass the plain object into the Client Component; **stringify inside** the header/footer wrappers.
 
-import { defineCustomElements } from 'weg-shared-layout/loader';
-import 'weg-shared-layout/weg-footer';
+Wire **`signedIn`** from your auth provider (e.g. session from a client context populated after mount, or a client-only wrapper around `<Header />`).
 
-defineCustomElements();
-
-type LayoutData = {
-  footer?: {
-    social?: { platform: string; href: string }[];
-    columns?: { links: { label: string; href: string }[] }[];
-    credits?: string;
-    copyright?: string;
-  };
-};
+## Header auth reference
 
-export function Footer({ layout }: { layout: LayoutData }) {
-  return (
-    <weg-footer layout={JSON.stringify(layout)} suppressHydrationWarning />
-  );
-}
-```
+| API | Usage |
+| --- | --- |
+| `layout.header.signIn` | `{ label, href }` — shown when `signed-in` is false |
+| `layout.header.signOut` | `{ label, href? }` — shown when `signed-in` is true |
+| `signed-in` prop | Boolean session flag from host app |
+| `wegAuthClick` event | `event.detail.action`: `'sign-in'` \| `'sign-out'` |
+| `event.preventDefault()` | Skip default link navigation / redirect |
 
-**Rule:** whatever crosses the Server → Client boundary must be **serializable**. Pass the plain object into the Client Component, then **`JSON.stringify` inside the client** before setting it on `<weg-footer>`.
+Logo is bundled in the component — not in `layout`.
 
 ## Passing `layout` — quick reference
 
-| Approach | Server Component | Client Component | Works in Next? |
-| --- | --- | --- | --- |
-| `layout={object}` on `<weg-footer>` | No (don’t use CE directly) | Tried often | **No** |
-| `layout={JSON.stringify(obj)}` on `<weg-footer>` | No | Yes | **Yes** (recommended) |
-| Pass `layout` object to `<Footer />`, stringify inside | Fetch/await JSON | `JSON.stringify` in JSX | **Yes** (recommended for CMS) |
-| `ref` + `el.layout = obj` in `useEffect` | No | Yes | Yes (escape hatch) |
-| `prop:layout={obj}` | No | Unreliable | **Avoid** |
+| Approach | Works in Next? |
+| --- | --- |
+| `layout={object}` on `<weg-header>` / `<weg-footer>` | **No** |
+| `layout={JSON.stringify(obj)}` in client wrapper | **Yes** (recommended) |
+| Pass object to `<SiteChrome layout={...} />`, stringify in child | **Yes** |
+| `ref` + `el.layout = obj` in `useEffect` | Yes (escape hatch) |
 
 ## TypeScript
 
-Use **module augmentation** (not triple-slash references in every file). Example `src/types/weg-shared-layout-jsx.d.ts`:
-
 ```ts
+// src/types/weg-shared-layout-jsx.d.ts
 import type { JSX as WegSharedLayoutJSX } from 'weg-shared-layout';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
 declare module 'react' {
   namespace JSX {
     interface IntrinsicElements extends WegSharedLayoutJSX.IntrinsicElements {
+      'weg-header': WegSharedLayoutJSX.IntrinsicElements['weg-header'] &
+        DetailedHTMLProps<HTMLAttributes<HTMLWegHeaderElement>, HTMLWegHeaderElement>;
       'weg-footer': WegSharedLayoutJSX.IntrinsicElements['weg-footer'] &
         DetailedHTMLProps<HTMLAttributes<HTMLWegFooterElement>, HTMLWegFooterElement>;
     }
@@ -182,62 +247,31 @@ declare module 'react' {
 }
 ```
 
-Enable `resolveJsonModule` if you import `weg-shared-layout/dummy-data.json` in the client footer.
-
 ## Troubleshooting
 
 | Symptom | Likely cause | Fix |
 | --- | --- | --- |
-| `document is not defined` | `defineCustomElements()` in a Server Component | Move registration to `"use client"` `Footer.tsx` only. |
-| Empty `<weg-footer>` in Elements panel | SSR placeholder before hydration | Expected until client JS runs; confirm client bundle loads and `defineCustomElements()` ran. |
-| Empty footer after hydration | `layout={object}` or missing stringify | Use `layout={JSON.stringify(layout)}` in the client component. |
-| Hydration warning on `<weg-footer>` | Server HTML ≠ client DOM | Add `suppressHydrationWarning`; ensure `layout` JSON is identical server vs client props. |
-| Build error importing package | Package not transpiled | Add `transpilePackages: ['weg-shared-layout']`. |
-| `'weg-footer' is not a known element` (TS) | Missing JSX types | Add module augmentation file above. |
-| Footer never upgrades | Loader/tag not imported on client | `import 'weg-shared-layout/weg-footer'` + `defineCustomElements()` in client file. |
-
-### DevTools tips
-
-1. **Elements:** Before hydration, `<weg-footer>` is often empty. After hydration, expand the shadow root — links should appear inside `#shadow-root`.
-2. **Console:** Log `document.querySelector('weg-footer')?.layout` in the browser — should be a **string** (JSON) or object, not `undefined`.
-3. **Network:** Confirm your layout API returns the same shape as [`dummy-data.json`](../src/assets/dummy-data.json).
-4. **React DevTools:** `Footer` should show under a Client Component boundary; parent `layout.tsx` stays a Server Component.
-
-### Ref fallback (if stringify still fails)
-
-```tsx
-'use client';
-
-import { useEffect, useRef } from 'react';
-import { defineCustomElements } from 'weg-shared-layout/loader';
-import 'weg-shared-layout/weg-footer';
-
-defineCustomElements();
-
-export function Footer({ layout }: { layout: unknown }) {
-  const ref = useRef<HTMLWegFooterElement>(null);
-
-  useEffect(() => {
-    if (ref.current) ref.current.layout = layout as object;
-  }, [layout]);
-
-  return <weg-footer ref={ref} suppressHydrationWarning />;
-}
-```
+| `document is not defined` | Loader in Server Component | Keep registration in `"use client"` files only. |
+| Empty after hydration | Object passed to CE without stringify | `JSON.stringify` in client wrapper. |
+| Logo missing | Stale package | Logo is inlined in `logo-data.ts`; rebuild / upgrade. |
+| Auth not updating | `signed-in` only on server | Manage session in client state / context. |
+| Hydration warning | Shadow DOM mismatch | `suppressHydrationWarning` on both tags. |
+| Build error | Package not transpiled | `transpilePackages: ['weg-shared-layout']`. |
 
 ## Integration checklist
 
 - [ ] `weg-shared-layout` installed
-- [ ] `transpilePackages: ['weg-shared-layout']` in `next.config`
-- [ ] `Footer.tsx` with `'use client'`, loader, tag import, `JSON.stringify`, `suppressHydrationWarning`
-- [ ] Root `app/layout.tsx` imports `<Footer />` (no `defineCustomElements` on server)
-- [ ] Layout data fetched server-side (or static import) and passed as serializable props
-- [ ] TypeScript module augmentation for `'weg-footer'`
-- [ ] Verified in browser after hydration (not only view-source HTML)
+- [ ] `transpilePackages` in `next.config`
+- [ ] Client `Header.tsx` / `Footer.tsx` with loader, tag imports, `JSON.stringify`, `suppressHydrationWarning`
+- [ ] Auth: `signed-in` + `wegAuthClick` handler on header
+- [ ] Server `layout.tsx` imports client chrome only (no `defineCustomElements` on server)
+- [ ] Layout fetched or imported server-side, passed as serializable props
+- [ ] TypeScript augmentation for `'weg-header'` and `'weg-footer'`
+- [ ] Verified in browser after hydration
 
 ## See also
 
-- **[React SPA](./react.md)** — object `layout={...}` on React 19 without SSR
+- **[React SPA](./react.md)**
 - **[Angular](./angular.md)**
 - **[Plain HTML / vanilla JS](./vanilla.md)**
 - **[Package readme](../readme.md)**