@naeil/ui 0.3.0 → 0.5.0

package/dist/source/components/ui/navigation.js

@@ -0,0 +1,347 @@
+"use client";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Dialog, Popover } from "radix-ui";
+import { Check, ChevronDown, Menu, X } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+const NativeLink = React.forwardRef(
+  function NativeLink2(props, ref) {
+    return /* @__PURE__ */ jsx("a", __spreadValues({ ref }, props));
+  }
+);
+function DesktopGroup({
+  item,
+  active,
+  open,
+  anotherGroupOpen,
+  onOpenChange,
+  children
+}) {
+  var _a;
+  const hoverOpened = React.useRef(false);
+  const closeTimer = React.useRef(
+    void 0
+  );
+  const panel = React.useRef(null);
+  const trigger = React.useRef(null);
+  const pointerType = React.useRef("");
+  const cancelClose = React.useCallback(() => {
+    clearTimeout(closeTimer.current);
+  }, []);
+  React.useEffect(() => {
+    return cancelClose;
+  }, [open, cancelClose]);
+  const leave = (event) => {
+    if (event.pointerType !== "mouse") return;
+    cancelClose();
+    const duration = getComputedStyle(event.currentTarget).getPropertyValue("--ui-motion-standard").trim();
+    closeTimer.current = setTimeout(
+      () => {
+        if (hoverOpened.current) onOpenChange(false);
+      },
+      parseFloat(duration) * (duration.endsWith("ms") ? 1 : 1e3)
+    );
+  };
+  return /* @__PURE__ */ jsxs(
+    Popover.Root,
+    {
+      open,
+      onOpenChange: (next) => {
+        cancelClose();
+        if (next) hoverOpened.current = false;
+        onOpenChange(next);
+      },
+      children: [
+        /* @__PURE__ */ jsxs(
+          Popover.Trigger,
+          {
+            ref: trigger,
+            className: "ui-navigation-link ui-focus",
+            "data-active": active || void 0,
+            onPointerEnter: (event) => {
+              if (event.pointerType !== "mouse") return;
+              cancelClose();
+              if (!open) {
+                hoverOpened.current = true;
+                onOpenChange(true);
+              }
+            },
+            onPointerLeave: leave,
+            onPointerDown: (event) => {
+              pointerType.current = event.pointerType;
+            },
+            onClick: (event) => {
+              var _a2, _b;
+              if (event.detail > 0 && pointerType.current === "mouse") {
+                event.preventDefault();
+                cancelClose();
+                hoverOpened.current = true;
+                onOpenChange(true);
+                return;
+              }
+              if (open && hoverOpened.current) {
+                event.preventDefault();
+                hoverOpened.current = false;
+                cancelClose();
+                (_b = (_a2 = panel.current) == null ? void 0 : _a2.querySelector("a[href]")) == null ? void 0 : _b.focus();
+              }
+            },
+            children: [
+              item.label,
+              /* @__PURE__ */ jsx(ChevronDown, { size: 16, "aria-hidden": "true" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(
+          Popover.Content,
+          {
+            ref: panel,
+            "data-slot": "navigation-popover",
+            className: "ui-navigation-popover ui-popup",
+            "data-columns": (_a = item.columns) != null ? _a : 1,
+            align: "start",
+            sideOffset: 8,
+            "aria-label": item.label,
+            onPointerEnter: cancelClose,
+            onPointerLeave: leave,
+            onFocusCapture: () => {
+              hoverOpened.current = false;
+              cancelClose();
+            },
+            onOpenAutoFocus: (event) => {
+              if (hoverOpened.current) event.preventDefault();
+            },
+            onCloseAutoFocus: (event) => {
+              if (hoverOpened.current || anotherGroupOpen) event.preventDefault();
+            },
+            onInteractOutside: (event) => {
+              var _a2;
+              if ((_a2 = trigger.current) == null ? void 0 : _a2.contains(event.target))
+                event.preventDefault();
+            },
+            children: /* @__PURE__ */ jsx("nav", { "aria-label": item.label, className: "ui-navigation-menu-grid", children })
+          }
+        ) })
+      ]
+    }
+  );
+}
+function Navigation(_a) {
+  var _b = _a, {
+    brand,
+    items,
+    labels,
+    Link = NativeLink,
+    currentHref,
+    toolbar,
+    mobileToolbar,
+    mobileFooter,
+    containerClassName,
+    onNavigate,
+    className
+  } = _b, props = __objRest(_b, [
+    "brand",
+    "items",
+    "labels",
+    "Link",
+    "currentHref",
+    "toolbar",
+    "mobileToolbar",
+    "mobileFooter",
+    "containerClassName",
+    "onNavigate",
+    "className"
+  ]);
+  const [mobileOpen, setMobileOpen] = React.useState(false);
+  const [openGroup, setOpenGroup] = React.useState(null);
+  const trigger = React.useRef(null);
+  const desktop = React.useRef(null);
+  React.useEffect(() => {
+    setMobileOpen(false);
+    setOpenGroup(null);
+  }, [currentHref]);
+  React.useEffect(() => {
+    const element = desktop.current;
+    if (!element || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      if (element.getBoundingClientRect().width > 0) setMobileOpen(false);
+      else setOpenGroup(null);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  const active = (item) => {
+    var _a2;
+    return (_a2 = item.active) != null ? _a2 : !item.external && item.href === currentHref;
+  };
+  function link(item, close, entry = false) {
+    const Component = item.external ? NativeLink : Link;
+    return /* @__PURE__ */ jsxs(
+      Component,
+      {
+        href: item.href,
+        target: item.target,
+        rel: item.target === "_blank" ? "noopener noreferrer" : void 0,
+        "aria-current": active(item) ? "page" : void 0,
+        className: cn(
+          "ui-navigation-link ui-focus",
+          entry && "ui-navigation-entry"
+        ),
+        onClick: (event) => {
+          onNavigate == null ? void 0 : onNavigate(event, item);
+          if (event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey)
+            close == null ? void 0 : close();
+        },
+        children: [
+          item.icon && /* @__PURE__ */ jsx("span", { className: "ui-navigation-icon", "aria-hidden": "true", children: item.icon }),
+          /* @__PURE__ */ jsxs("span", { className: "ui-navigation-copy", children: [
+            /* @__PURE__ */ jsxs("span", { className: "ui-navigation-title", children: [
+              /* @__PURE__ */ jsx("span", { children: item.label }),
+              item.badge,
+              entry && active(item) && /* @__PURE__ */ jsx(Check, { size: 16, className: "shrink-0", "aria-hidden": "true" })
+            ] }),
+            item.description && /* @__PURE__ */ jsx("span", { className: "ui-navigation-description", children: item.description })
+          ] })
+        ]
+      },
+      item.id
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "header",
+    __spreadProps(__spreadValues({
+      "data-slot": "navigation",
+      className: cn("ui-navigation", className)
+    }, props), {
+      children: /* @__PURE__ */ jsx("div", { className: cn("ui-navigation-frame", containerClassName), children: /* @__PURE__ */ jsxs("div", { className: "ui-navigation-row", children: [
+        /* @__PURE__ */ jsx("div", { className: "ui-navigation-brand", children: brand }),
+        /* @__PURE__ */ jsx(
+          "nav",
+          {
+            ref: desktop,
+            "aria-label": labels.navigation,
+            className: "ui-navigation-desktop",
+            children: items.map(
+              (item) => "items" in item ? /* @__PURE__ */ jsx(
+                DesktopGroup,
+                {
+                  item,
+                  active: item.items.some(active),
+                  open: openGroup === item.id,
+                  anotherGroupOpen: openGroup !== null && openGroup !== item.id,
+                  onOpenChange: (open) => setOpenGroup(
+                    (current) => open ? item.id : current === item.id ? null : current
+                  ),
+                  children: item.items.map(
+                    (child) => link(child, () => setOpenGroup(null), true)
+                  )
+                },
+                item.id
+              ) : link(item)
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx("div", { className: "ui-navigation-toolbar", children: toolbar }),
+        /* @__PURE__ */ jsxs(Dialog.Root, { open: mobileOpen, onOpenChange: setMobileOpen, children: [
+          /* @__PURE__ */ jsx(
+            Dialog.Trigger,
+            {
+              ref: trigger,
+              className: "ui-navigation-toggle ui-navigation-link ui-focus",
+              "aria-label": labels.menu,
+              children: /* @__PURE__ */ jsx(Menu, { "aria-hidden": "true", size: 20 })
+            }
+          ),
+          /* @__PURE__ */ jsxs(Dialog.Portal, { children: [
+            /* @__PURE__ */ jsx(
+              Dialog.Overlay,
+              {
+                "data-slot": "navigation-overlay",
+                className: "ui-navigation-overlay ui-popup"
+              }
+            ),
+            /* @__PURE__ */ jsxs(
+              Dialog.Content,
+              {
+                "data-slot": "navigation-sheet",
+                className: "ui-navigation-sheet ui-popup",
+                "aria-describedby": void 0,
+                onCloseAutoFocus: (event) => {
+                  var _a2, _b2;
+                  if (trigger.current && trigger.current.getBoundingClientRect().width === 0) {
+                    event.preventDefault();
+                    (_b2 = (_a2 = desktop.current) == null ? void 0 : _a2.querySelector("button, a")) == null ? void 0 : _b2.focus();
+                  }
+                },
+                children: [
+                  /* @__PURE__ */ jsxs("div", { className: "ui-navigation-sheet-heading", children: [
+                    /* @__PURE__ */ jsx(Dialog.Title, { className: "text-xl font-semibold", children: labels.menu }),
+                    /* @__PURE__ */ jsx(
+                      Dialog.Close,
+                      {
+                        className: "ui-navigation-link ui-focus",
+                        "aria-label": labels.close,
+                        children: /* @__PURE__ */ jsx(X, { size: 20, "aria-hidden": "true" })
+                      }
+                    )
+                  ] }),
+                  /* @__PURE__ */ jsx(
+                    "nav",
+                    {
+                      "aria-label": labels.navigation,
+                      className: "ui-navigation-mobile-links",
+                      children: items.map(
+                        (item) => "items" in item ? /* @__PURE__ */ jsxs("section", { "aria-label": item.label, children: [
+                          /* @__PURE__ */ jsx("h3", { className: "ui-navigation-group-label", children: item.label }),
+                          item.items.map(
+                            (child) => link(child, () => setMobileOpen(false), true)
+                          )
+                        ] }, item.id) : link(item, () => setMobileOpen(false))
+                      )
+                    }
+                  ),
+                  (mobileToolbar != null ? mobileToolbar : toolbar) && /* @__PURE__ */ jsx("div", { className: "ui-navigation-mobile-toolbar", children: mobileToolbar != null ? mobileToolbar : toolbar }),
+                  mobileFooter && /* @__PURE__ */ jsx("div", { className: "ui-navigation-mobile-footer", children: mobileFooter })
+                ]
+              }
+            )
+          ] })
+        ] })
+      ] }) })
+    })
+  );
+}
+export {
+  Navigation
+};

package/dist/source/components/ui/site-footer.d.ts

@@ -0,0 +1,21 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { NavigationLink, NavigationLinkComponent } from './navigation.js';
+
+interface SiteFooterProps extends react.ComponentPropsWithoutRef<"footer"> {
+    brand?: react.ReactNode;
+    description?: react.ReactNode;
+    groups?: Array<{
+        id: string;
+        label: string;
+        links: NavigationLink[];
+    }>;
+    Link?: NavigationLinkComponent;
+    meta?: react.ReactNode;
+    containerClassName?: string;
+    variant?: "full" | "compact";
+}
+/** Product content and translations belong to the consumer, including legal copy. */
+declare function SiteFooter({ brand, description, groups, Link, meta, children, containerClassName, className, variant, ...props }: SiteFooterProps): react_jsx_runtime.JSX.Element;
+
+export { SiteFooter, type SiteFooterProps };

package/dist/source/components/ui/site-footer.js

@@ -0,0 +1,93 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/utils.js";
+function SiteFooter(_a) {
+  var _b = _a, {
+    brand,
+    description,
+    groups = [],
+    Link,
+    meta,
+    children,
+    containerClassName,
+    className,
+    variant = "full"
+  } = _b, props = __objRest(_b, [
+    "brand",
+    "description",
+    "groups",
+    "Link",
+    "meta",
+    "children",
+    "containerClassName",
+    "className",
+    "variant"
+  ]);
+  return /* @__PURE__ */ jsx(
+    "footer",
+    __spreadProps(__spreadValues({
+      "data-slot": "site-footer",
+      "data-variant": variant,
+      className: cn("ui-site-footer", className)
+    }, props), {
+      children: /* @__PURE__ */ jsxs("div", { className: cn("ui-site-footer-frame", containerClassName), children: [
+        /* @__PURE__ */ jsxs("div", { className: "ui-site-footer-brand", children: [
+          brand,
+          description && /* @__PURE__ */ jsx("div", { className: "ui-site-footer-description", children: description }),
+          children
+        ] }),
+        groups.map((group) => /* @__PURE__ */ jsxs("nav", { "aria-label": group.label, children: [
+          /* @__PURE__ */ jsx("h2", { className: "ui-site-footer-label", children: group.label }),
+          group.links.map((item) => {
+            const Component = !item.external && Link ? Link : "a";
+            return /* @__PURE__ */ jsx(
+              Component,
+              {
+                href: item.href,
+                target: item.target,
+                rel: item.target === "_blank" ? "noopener noreferrer" : void 0,
+                className: "ui-site-footer-link ui-focus",
+                children: item.label
+              },
+              item.id
+            );
+          })
+        ] }, group.id)),
+        meta && /* @__PURE__ */ jsx("div", { className: "ui-site-footer-meta", children: meta })
+      ] })
+    })
+  );
+}
+export {
+  SiteFooter
+};

package/docs/components/README.md

@@ -1,6 +1,6 @@
 # Component usage guides
 
-Prepared `@naeil/ui@0.3.0` (unpublished). [Setup, themes, fonts and shared responsibilities](common.md). Run `pnpm storybook` and choose each family’s Docs or Usage entry. Select chooses a value; DropdownMenu chooses an action.
+These guides target the **@naeil/ui 0.5.0 release candidate**; final archive verification and publication are pending. [Setup, themes, fonts and shared responsibilities](common.md). Run `pnpm storybook` for the current 17 Docs pages (15 UI and 2 Brand) and choose Docs or Usage. The [hosted Storybook](https://naeil-dev.github.io/naeil-ui/) was last verified for [0.4.0 on 2026-10-11](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.4.0); this candidate does not establish a new hosted deployment. Select chooses a value; DropdownMenu chooses an action.
 
 | Family | Guide | Runnable story |
 | --- | --- | --- |
@@ -17,5 +17,10 @@ Prepared `@naeil/ui@0.3.0` (unpublished). [Setup, themes, fonts and shared respo
 | Checkbox | [Checkbox](./checkbox.md) | UI / Checkbox / Usage |
 | Tabs | [Tabs](./tabs.md) | UI / Tabs / Usage |
 | Textarea | [Textarea](./textarea.md) | UI / Textarea / Usage |
+| Navigation | [Navigation](./navigation.md) | UI / Navigation / Usage |
+| SiteFooter | [SiteFooter](./navigation.md) | UI / SiteFooter / Usage |
+| NaeilHeader | [NaeilHeader](./naeil-header.md) | Brand / NaeilHeader / Usage, JapaneseApplication |
 
 [Field, native radio, Select and action composition](./composition.md) explains consumer state and semantic choices. [Demand decision](../design/component-demand.md) records why these two families were added.
+
+Use opt-in `@naeil/ui/naeil-header` for the actual naeil.dev branded header, with official artwork URL references and consumer-owned routing, theme provider and authentication. Use generic `Navigation` from `/ui` for different product menus. [Navigation / SiteFooter](navigation.md) also documents the compatibility adapters.

package/docs/components/common.md

@@ -1,6 +1,6 @@
 # Shared usage contract
 
-These guides describe the prepared **0.3.0, unpublished** package. Start with the [consumer setup and migration](../design/v2-migration.md). All listed exports are available from `@naeil/ui/ui`; the legacy root needs the optional Next/next-intl peers. Examples import real wrappers; product state, validation and network requests belong to consumers.
+These guides target the **@naeil/ui 0.5.0 release candidate**; final archive verification and registry publication are pending. The [hosted Docs](https://naeil-dev.github.io/naeil-ui/) were last verified for [0.4.0 on 2026-10-11](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.4.0), while `pnpm storybook` shows the current candidate. Start with the [consumer setup and migration](../design/v2-migration.md). Primitives and generic Navigation/SiteFooter are exported from `@naeil/ui/ui`; the actual branded whole header uses the opt-in [NaeilHeader](naeil-header.md) entry `@naeil/ui/naeil-header`. Both are React-only. The legacy root needs the optional Next/next-intl peers. Examples import real wrappers; product state, validation and network requests belong to consumers.
 
 ## Styling, themes and overrides
 

package/docs/components/naeil-header.md

@@ -0,0 +1,50 @@
+# NaeilHeader — branded whole-header composition
+
+This guide targets the **@naeil/ui 0.5.0 release candidate**. Final archive verification and registry publication are pending. Import this opt-in React-only entry when an application inherits the actual naeil.dev header. Generic `Navigation` from `/ui` remains available for different product menus.
+
+```tsx
+import { NaeilHeader } from '@naeil/ui/naeil-header';
+import '@naeil/ui/globals.css';
+
+// Inside the consumer's existing next-themes ThemeProvider:
+<NaeilHeader locale="ja" Link={GuardedLink} currentHref={pathname}
+  authSlot={<LogoutButton />} />
+```
+
+Load shared styles once. Apps that already own their Tailwind/base styles may import both `@naeil/ui/theme.css` and `@naeil/ui/components.css` instead of globals. Tailwind 4 consumers must register the installed `dist` with `@source`; see [setup](../design/v2-migration.md#시작하기).
+
+The module owns the brand, five-project catalog and header-only translations, project artwork references/status, theme/optional locale controls, toolbar order, fixed positioning, branded frame and Radix desktop/mobile behavior. Do not copy menu JSX or styles into a consumer. The website's `NavWrapper` imports this same module and supplies locale/router/auth state; estimate consumes the built package entry. Legacy `Nav` retains its Next/next-intl compatibility API.
+
+## Consumer contract
+
+Consumers provide an existing next-themes provider, routing/dirty-save guard, current locale and real authentication behavior. Default destinations point to `https://naeil.dev/{locale}`; the site's localized Link instead uses `resolveHref={path => path}`. A supplied `Link` handles default official destinations, including cross-origin URLs. `onNavigate` can intercept brand and menu links; honor modified clicks and target behavior. Explicit `external: true` project overrides and `projectsExternal` use native anchors, so intercept them with `onNavigate` when a dirty guard is required.
+
+Only provide `onLocaleChange` when the application's interface supports all three canonical locales (`en`, `ko`, `ja`). Omitting it removes the locale control; the component does not create application translations or shared preferences. `authSlot` contains the consumer's real session action and must retain at least 44px touch targets. It does not integrate site SSO, share credentials or create accounts. Theme preferences remain consumer-origin state. Without a working provider, rendering alone does not establish theme switching.
+
+| Prop | Contract |
+| --- | --- |
+| `locale` | Required `en`, `ko` or `ja`; selects header-only copy. |
+| `resolveHref` | Resolves canonical unlocalized paths; defaults to the official localized site. |
+| `Link`, `currentHref`, `onNavigate` | Routing adapter, active destination and navigation interception inherited from Navigation. |
+| `onLocaleChange` | Optional supported-language callback; omit for a single-language application. |
+| `authSlot` | Consumer-owned authentication action in the default toolbar. |
+| `brandHref`, `brandSlot`, `brandLinkProps`, `brandLinkComponent` | Explicit brand destination/content/anchor overrides; default accessible brand name is `.naeil`. |
+| `projects`, `projectsExternal`, `showProjects`, `showBlog` | Legacy catalog/visibility/native-link overrides; defaults use the complete canonical catalog. |
+| `subNav`, `currentProjectKey`, `currentProjectHref` | Legacy extra links and current-project destination. |
+| `translations`, `labels` | Legacy header/project lookup overrides and navigation/menu/close accessible labels. |
+| `toolbarSlot` | Replaces the complete default theme/locale/auth toolbar. |
+| `mobileFooter`, `className`, `containerClassName` | Inherited mobile slot and style overrides; recheck frame/behavior after changes. |
+
+Standard header attributes and the remaining inherited [Navigation props](navigation.md) remain available. Compatibility overrides preserve existing consumers; new applications normally use the canonical composition.
+
+## Frame and content clearance
+
+The fixed header is 65px: the current 64px navigation token plus a 1px border. Clear it in the application's main, sticky regions and focus/anchor scroll margins with `calc(var(--ui-navigation-height) + 1px)`. The branded header uses the actual site's 1280px cap and 24px gutters; body/footer widths belong to the product. A 1600px workspace body does not change this header cap or create a new shared foundation token.
+
+## Artwork and package boundary
+
+The five decorative images reference `https://naeil.dev/images/{coral,jellyfish,whale,fish,turtle}.png`. Rendering those images requires network access to the official origin. Their bytes are not redistributed in npm; [third-party notices](../../THIRD_PARTY_NOTICES.md) retain unresolved artwork provenance and redistribution limits. Brand marks are not relicensed by the repository MIT license. Captions and links remain usable when images fail.
+
+This entry requires no Next.js, next-intl, site session/auth backend, full application message catalog, hero or site public folder. Generic `/ui` imports do not import its catalog. The local Storybook provides **Brand / NaeilHeader / Docs, Usage, JapaneseApplication**; the Japanese example omits unsupported locale switching and uses a consumer-owned auth slot. Candidate examples do not establish hosted deployment.
+
+Verify actual packed consumption, Storybook behavior and rendered comparisons at matching viewport/language/theme. Source imports alone do not prove visual parity. Native Safari, devices, assistive technology, full OAuth and unresolved accessibility observations retain the [documented support limits](../design/public-ui-support.md).

package/docs/components/navigation.md

@@ -0,0 +1,59 @@
+# Navigation and SiteFooter
+
+This guide targets the **0.5.0 release candidate**; final archive verification and publication are pending. These are generic product-menu primitives. Applications inheriting the actual naeil.dev brand/catalog/control composition use the canonical opt-in [NaeilHeader](naeil-header.md) from `@naeil/ui/naeil-header`, with its fixed 65px/1280px frame and official artwork URL dependency.
+
+`Navigation` and `SiteFooter` are React-only exports from `@naeil/ui/ui` (also `@naeil/ui/components/ui/navigation` and `@naeil/ui/components/ui/site-footer`). They require shared theme/components CSS and the normal consumer font/Tailwind setup. They do not import Next, next-intl, authentication, product routes or message dictionaries.
+
+```tsx
+import { Navigation, SiteFooter } from "@naeil/ui/ui";
+
+<Navigation
+  brand={<a href="/">My product</a>}
+  labels={{ navigation: "Main navigation", menu: "Menu", close: "Close menu" }}
+  items={[{ id: "ai", label: "AI", items: [
+    { id: "dashboard", label: "Dashboard", href: "/", description: "Usage and balance" },
+    { id: "keys", label: "API keys", href: "/keys" },
+  ] }]}
+  currentHref={pathname}
+  containerClassName="product-frame"
+  toolbar={<ProductControls />}
+  onNavigate={(event, item) => {
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    guardedNavigate(item.href);
+  }}
+/>
+<main className="product-frame">
+  <section data-ui-layout="settings">{/* narrow form inside stable frame */}</section>
+</main>
+<SiteFooter
+  brand={<ProductBrand />}
+  variant="compact"
+  meta="Product information"
+  containerClassName="product-frame"
+/>
+```
+
+These are composition snippets: `pathname`, controls, brand, frame and `guardedNavigate` belong to the application. Keep its unsaved-change guard and modified-click behavior. Alternatively supply a `Link` adapter which forwards anchor props, `onClick`, `aria-current`, `className`, target and children. Links explicitly marked `external: true` render native anchors; an absolute URL alone does not bypass the supplied `Link`. `active` overrides exact `currentHref` matching when a route family needs custom matching.
+
+`Navigation` accepts links and one level of labeled groups, optional description/icon/badge, `toolbar`, `mobileToolbar` and `mobileFooter`. Brand is a slot; the component does not invent a home destination or label. Groups use Radix Popover with actual links (Tab navigation, Escape and focus return); they are not action menus. Mobile uses a modal Radix Dialog with scroll locking, trapped focus and a labeled close control. The sheet closes on destination selection, currentHref changes or a return to desktop.
+
+Desktop groups open on mouse hover without moving keyboard focus. Leaving both the trigger and panel closes the hover preview after the standard 180ms token duration, allowing travel across the portal gap. Entering the panel cancels the pending close. Mouse clicks keep the menu open while the pointer remains in the trigger/panel and do not pin it: leaving still dismisses it. Keyboard-activating a hovered trigger takes over the open menu and focuses its first link; subsequent keyboard activation, Escape, outside interaction or navigation dismisses it. A menu being used with keyboard focus remains open when the pointer leaves. Mouse dismissal preserves the previous focus; keyboard activation retains Radix focus return. Touch uses click/tap, and the mobile sheet behavior is unchanged. Reduced motion disables visual transitions while retaining pointer travel tolerance.
+
+Container queries select desktop layout at 48rem of available header content width. Product frame classes control max width and gutters. Header height uses `ui.navigation-height` (64px); toolbar controls should remain short, with volatile counts in the content area. Navigation itself is in document flow; `className` can make it sticky or fixed. Fixed consumers must reserve its height in page composition. A narrow form must not constrain the header. Explicit className/style remain consumer overrides.
+
+`SiteFooter` supports `brand`, `description`, `groups: [{ id, label, links }]`, `meta`, children, `Link`, `containerClassName` and `variant="full|compact"`. Each link group is a labeled navigation landmark. Translated titles, destinations, legal/version text and social links belong to the consumer. A product may place a compact footer in its mobile sheet; a full marketing footer is not mandatory in a dashboard.
+
+Desktop reserves `ui.navigation-brand-width` (160px) for the brand, followed by the existing 16px row gap. With matching frame, viewport and font conditions, `.naeil` and `.naeil Home` therefore start their first menu at the same position. Mobile keeps intrinsic brand width. For a larger custom brand, override `--ui-navigation-brand-width` on the header or shared product frame; use the same value across related compositions and ensure the brand fits the reserved area.
+
+## Compatibility
+
+Menu groups accept `columns?: 1 | 2` (default 1). The candidate sample uses 2 for the website project catalog and 1 for Home's functional menu; the mobile sheet remains one column. Menu widths use `ui.navigation-menu-width` (320px) and `ui.navigation-menu-wide-width` (640px), capped by available space. Group links share a 40px icon area, 16px icon-to-copy gap, title/description hierarchy and badges beside the title. Supply decorated brand artwork through `icon`; the shared package does not own product illustrations. Current group links use background, semibold title and a check indicator, retaining `aria-current` and keyboard focus without underlining descriptions.
+
+Existing `Nav` and `Footer` imports and props remain. `Nav` adapts the canonical NaeilHeader, which renders this generic core; `Footer` composes SiteFooter. `Nav` retains its fixed positioning and max-w-7xl site frame; menus gain keyboard/focus support, an opaque shared surface, 16px labels and a 64px minimum row. Its `projects` prop replaces the old default inventory; the old naeil projects remain the fallback for existing consumers. Optional `labels`, `className` and `containerClassName` support localization and frame overrides.
+
+`Footer` adds `brandSlot`, `description`, `groups`, `socialSlot`, `meta`, `variant`, `className` and `containerClassName`. Use empty groups or null description/socialSlot to omit defaults. Existing linksExternal behavior remains for the default naeil links. Custom groups define their own absolute destinations and external/target settings.
+
+`Nav`/`Footer` continue to need Next/next-intl as documented. React-only services use this core for their own product menus or `/naeil-header` for the canonical branded composition. ThemeProvider, ThemeToggleIcon, LocaleSwitcher and Logo remain available through their existing React-safe deep imports. Reusing controls does not synchronize theme/language/authentication between origins.
+
+Storybook: `UI/Navigation` (website, Home composition, long labels), `UI/SiteFooter` (full and compact). Naeil Home is a synthetic composition based on the inspected live menu, not proof of a deployed migration. The repository task note `docs/design/navigation-footer-integration.md` tracks rollout; it is not included in the npm package.

package/docs/design/public-ui-support.md

@@ -1,10 +1,25 @@
 # Public UI support and manual acceptance
 
-This support matrix targets `@naeil/ui@0.3.0`; it does not assert registry or hosted Docs availability. Current documentation covers 13 families. This matrix describes the current examples/checks, not every consumer or every allowed dependency version. [Dated Stage 3 results](public-ui-stage3-verification.md) identify commands, source hashes and local limitations. [Stage 4 extension results](public-ui-stage4-verification.md) separately cover Tabs/Textarea and native field/choice composition.
+This support matrix targets published `@naeil/ui@0.4.0` (2026-10-11); the [release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.4.0) and [publication report](https://github.com/naeil-dev/naeil-ui/blob/main/docs/design/naeil-brand-0.4.0-publication.md) identify its source, npm archive, independent brand 1.1.1 and deployed Docs/site. Current documentation covers 13 component families plus Brand / Logo. Coverage describes the checked examples and dependency versions; native/manual acceptance remains open.
+
+## 0.4.0 publication coverage
+
+- Source `e8fe5afc13788a0cac0244b72e78975812f4a2ee`: 46 local unit tests passed. [Merged Linux CI](https://github.com/naeil-dev/naeil-ui/actions/runs/38113742370) passed package/site checks and 233 browser tests with 4 expected forced-colors skips; the [Docs deployment workflow](https://github.com/naeil-dev/naeil-ui/actions/runs/38114879574) also passed that browser suite.
+- [Registry/consumer receipt](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/npm-publication-verification.json): fresh actual npm installs with separate empty caches passed React/Next types and production builds, SSR/deep imports, exact notices, production fonts/fallback, mixed-import ownership/StrictMode and Chromium/WebKit Tabs/Textarea contracts. The React fixture contains no Next dependency. Fixtures do not establish real-product adoption.
+- [Hosted Docs receipt](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/hosted-docs-verification.json): Chromium 153.0.8010.12 and Playwright WebKit 26.6 passed 28 Docs visits, 28 actual Docs-to-Usage transitions, 4 brand light/dark checks, canonical artwork, exact notices, local fonts and pinned links at the deployed `/naeil-ui/` URL.
+- [Production receipt](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/production-verification.json): the same engines passed 24 homepage/login conditions across three locales, two viewport sizes and two themes; header/footer/login logos, mobile menu and 3 deployed icons were checked. These observations cover page rendering and navigation; full OAuth authentication was not exercised.
+
+The environment matrix below retains dated foundation coverage. The 0.4.0 checks above add evidence for their exact source and do not close the native/manual items below.
+
+## Foundation evidence — 0.3.0
+
+Version 0.3.0 was published on 2026-10-03; its [registry/consumer receipt](https://github.com/naeil-dev/naeil-ui/releases/download/v0.3.0/npm-publication-verification.json) and [release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0) remain historical evidence. [Dated Stage 3 results](public-ui-stage3-verification.md) identify commands, source hashes and local limitations. [Stage 4 extension results](public-ui-stage4-verification.md) separately cover Tabs/Textarea and native field/choice composition.
 
 Linux CI at `bcf99fca3467ae2b1cd29d54fa24f2569fb6001c` passed package-and-site in both the [push run](https://github.com/naeil-dev/naeil-ui/actions/runs/36945564443) and [PR run](https://github.com/naeil-dev/naeil-ui/actions/runs/36945943651). Their browser jobs failed: respectively 207 passed/4 skipped/2 failed (axe scan collision and Avatar Docs ambiguity), and 208 passed/4 skipped/1 failed (Avatar Docs ambiguity). Firefox application tests passed in both Linux runs. These failed baseline results remain historical evidence in the [final correction follow-up](public-ui-final-verification.md).
 
-The corrected source `9f90493abb4fb1186c948084026c3f4c04074013` passed independent scoped review with no actionable findings and both actual Linux workflows: [push](https://github.com/naeil-dev/naeil-ui/actions/runs/36948276767) and [PR](https://github.com/naeil-dev/naeil-ui/actions/runs/36948280881). The PR browser suite passed **209 tests with 4 expected forced-colors skips** (two each in Firefox/WebKit); package-and-site and optional helper checks also passed. Root verified the downloaded PR Storybook artifact and its `/naeil-ui/` navigation/fonts in Chromium/WebKit. This evidence applies to that exact source; [live PR checks](https://github.com/naeil-dev/naeil-ui/pull/1/checks) report later documentation-head status. Review/CI acceptance applies to its recorded source and does not complete native/manual platform coverage. Publication authorization is a separate decision; unrun checks remain limitations rather than completed results.
+The corrected source `9f90493abb4fb1186c948084026c3f4c04074013` passed independent scoped review with no actionable findings and both actual Linux workflows: [push](https://github.com/naeil-dev/naeil-ui/actions/runs/36948276767) and [PR](https://github.com/naeil-dev/naeil-ui/actions/runs/36948280881). The PR browser suite passed **209 tests with 4 expected forced-colors skips** (two each in Firefox/WebKit); package-and-site and optional helper checks also passed. Root verified the downloaded PR Storybook artifact and its `/naeil-ui/` navigation/fonts in Chromium/WebKit. This evidence applies to that exact source; [merged PR checks](https://github.com/naeil-dev/naeil-ui/pull/1/checks) retain the release-preparation checks. Subsequent documentation changes require their own verification. Review/CI acceptance applies to its recorded source and does not complete native/manual platform coverage. Publication completed separately on 2026-10-03; unrun checks remain limitations rather than completed results.
+
+Fresh npm-registry installs in clean-cache React/Next apps passed types/build, production fonts and blocked-font fallback, mixed-import ownership/StrictMode, Chromium/WebKit Tabs/Textarea contracts and Next 16.1.7 root/deep prerender; the [publication receipt](https://github.com/naeil-dev/naeil-ui/releases/download/v0.3.0/npm-publication-verification.json) gives their scope. The development overlay replay probe retains 34 Vite font allowlist warnings; it certifies overlay replay only, and font success applies to production. These fixtures do not establish adoption in a real consumer product.
 
 | Environment / capability | Contract and evidence |
 | --- | --- |