@zccz14/ux 0.2.1 → 0.3.0

package/README.md

@@ -7,6 +7,7 @@
 - **Sidebar** — one animated icon-collapse sidebar: 16rem expanded, 3rem collapsed, 200 ms width transition. Midas, 1Exchange and 1earn-style shells without animation are replaced by this behavior.
 - **Navigation groups only** — the sidebar has no separate bottom section. Settings and status destinations live in the navigation groups like every other destination, so the bottom edge of every app's sidebar looks the same.
 - **AppHeader** — sidebar trigger, current page title, your `headerSlot`, and the Linkit account control (`LinkitMyInfo`), in that order. Role badges such as 超级管理员 stay out of the shell: administrator affordances live in the administrator navigation group and pages.
+- **Favicon** — the same mark becomes the page favicon: the shell serialises the rendered logo into `link[rel="icon"]`, pins the colour the mark currently shows (a favicon has no app stylesheet, so `currentColor` would otherwise fall back to black), and re-renders it whenever the theme changes. Pass `favicon={false}` to keep an app-owned icon.
 - **Logo** — you pass one mark; the shell renders it inside a fixed 1.75rem box and controls the display size itself, so the logo size is identical everywhere. Pass a mark that follows the current colour (an icon using `currentColor`, or an SVG with mode-aware fills) so it keeps working in both themes. The title beside the logo disappears while collapsed.
 - **Linkit integration** — the viewer's language selects the shell copy (中文/English), and theme, language and account controls all live in the `LinkitMyInfo` dialog. The shell never reads the theme itself: it renders whatever colour scheme its own CSS resolves (see [Styling](#styling)).
 
@@ -74,7 +75,8 @@ export function App() {
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| `logo` | `ReactNode` | yes | The logo mark. The shell renders it at its own fixed 1.75rem size; pass a mark that follows the current colour. |
+| `logo` | `ReactNode` | yes | The logo mark. The shell renders it at its own fixed 1.75rem size and mirrors it into the page favicon; pass a mark that follows the current colour. |
+| `favicon` | `boolean` | no | Defaults to `true`: the logo mark is written to `link[rel="icon"]` and re-rendered on theme changes. Set `false` to leave the app's own icon alone. |
 | `title` | `string` | yes | App name beside the logo. Hidden while the sidebar is collapsed. |
 | `nav` | `AppNavGroup[]` | yes | Navigation groups rendered in the sidebar. |
 | `headerSlot` | `ReactNode` | no | Rendered immediately left of `LinkitMyInfo` in the AppHeader. Use it for page-level actions such as refresh. |
@@ -97,6 +99,7 @@ type AppNavGroup = { label: string; items: AppNavItem[] };
 - **Mobile** — below 768px the sidebar becomes a modal navigation drawer: the trigger opens it, tapping a link or the backdrop closes it.
 - **Collapsed tooltips** — icon-only items reveal their label in a tooltip on hover and focus.
 - **Reduced motion** — `prefers-reduced-motion: reduce` disables the animations.
+- **Favicon** — an `<svg>` logo is serialised to a `data:image/svg+xml` icon with its rendered colour pinned; an `<img>` logo reuses the image URL. The icon is rewritten when `.dark` flips, when `prefers-color-scheme` changes, and when the mark itself is swapped.
 - **Layout contract** — the shell is viewport-locked (`100svh`); the main region is the page's only scroll container and applies the standard `1rem` / `1.5rem` padding. Pages own their inner layout.
 
 ## Styling
@@ -113,6 +116,7 @@ Theme state itself is not the shell's business: whatever toggles `.dark` on `<ht
 2. Move legacy header buttons (refresh, settings, language, theme) into `headerSlot`. Role badges are dropped: administrator affordances belong to the administrator navigation group and pages, and theme/language preferences live in the `LinkitMyInfo` profile dialog (`linkit-react-components` 0.6+).
 3. Move any sidebar footer item (settings, environment status) into the last navigation group.
 4. Pass the single logo mark and delete per-call sizes; the shell normalizes every mark to its 1.75rem box.
+5. Delete the app's own `applyFavicon` / favicon effect: the shell now owns `link[rel="icon"]`. Keep a hand-written favicon only by passing `favicon={false}`.
 
 ## Development
 

package/dist/app-layout.d.ts

@@ -1,2 +1,2 @@
 import type { AppLayoutProps } from "./types.js";
-export declare function AppLayout({ children, headerSlot, logo, nav, pageTitle, title, }: AppLayoutProps): import("react").JSX.Element;
+export declare function AppLayout({ children, favicon, headerSlot, logo, nav, pageTitle, title, }: AppLayoutProps): import("react").JSX.Element;

package/dist/favicon.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+/**
+ * Mirrors the rendered logo into the page favicon: the tab shows the same mark
+ * as the sidebar, including its current colour, and follows theme changes.
+ */
+export declare function useLogoFavicon(logo: RefObject<HTMLElement | null>, enabled: boolean): void;

package/dist/index.js

@@ -1,23 +1,65 @@
-import { jsxs as s, jsx as e, Fragment as y } from "react/jsx-runtime";
-import { useState as f, useCallback as g, useEffect as w, useSyncExternalStore as M } from "react";
+import { jsxs as d, jsx as n, Fragment as L } from "react/jsx-runtime";
+import { useEffect as k, useRef as M, useState as v, useCallback as x, useSyncExternalStore as C } from "react";
 import { Dialog as h } from "@base-ui/react/dialog";
-import { Tooltip as p } from "@base-ui/react/tooltip";
-import { useLinkit as L, LinkitMyInfo as S } from "linkit-react-components";
-import { useLocation as v, NavLink as C } from "react-router-dom";
-const O = {
+import { Tooltip as m } from "@base-ui/react/tooltip";
+import { useLinkit as E, LinkitMyInfo as O } from "linkit-react-components";
+import { useLocation as y, NavLink as I } from "react-router-dom";
+const P = {
   closeNavigation: "Close navigation",
   navigation: "Navigation",
   toggleSidebar: "Toggle sidebar"
-}, P = {
+}, T = {
   closeNavigation: "关闭导航",
   navigation: "导航",
   toggleSidebar: "切换侧边栏"
 };
-function I(a) {
-  return a.toLowerCase().startsWith("zh") ? P : O;
+function A(e) {
+  return e.toLowerCase().startsWith("zh") ? T : P;
 }
-function E() {
-  return /* @__PURE__ */ s(
+const $ = 'link[rel~="icon"]';
+function R(e) {
+  const t = e.cloneNode(!0);
+  return t.setAttribute("xmlns", "http://www.w3.org/2000/svg"), t.style.color = getComputedStyle(e).color, new XMLSerializer().serializeToString(t);
+}
+function W(e) {
+  if (e instanceof SVGSVGElement)
+    return {
+      href: `data:image/svg+xml,${encodeURIComponent(R(e))}`,
+      type: "image/svg+xml"
+    };
+  const { currentSrc: t, src: o } = e, i = t || o;
+  return /\.svg([?#]|$)/i.test(i) ? { href: i, type: "image/svg+xml" } : { href: i };
+}
+function j() {
+  const e = document.querySelector($);
+  if (e)
+    return e;
+  const t = document.createElement("link");
+  return t.rel = "icon", document.head.append(t), t;
+}
+function z(e, t) {
+  k(() => {
+    if (!t)
+      return;
+    const o = () => {
+      var l;
+      const p = (l = e.current) == null ? void 0 : l.querySelector("svg, img");
+      if (!p)
+        return;
+      const { href: u, type: s } = W(p), c = j();
+      s ? c.type = s : c.removeAttribute("type"), c.getAttribute("href") !== u && c.setAttribute("href", u);
+    };
+    o();
+    const i = new MutationObserver(o);
+    i.observe(document.documentElement, { attributes: !0, attributeFilter: ["class", "style"] }), e.current && i.observe(e.current, { childList: !0, subtree: !0 });
+    const r = window.matchMedia("(prefers-color-scheme: dark)");
+    return r.addEventListener("change", o), () => {
+      i.disconnect(), r.removeEventListener("change", o);
+    };
+  }, [t, e]);
+}
+function B() {
+  return /* @__PURE__ */ d(
     "svg",
     {
       "aria-hidden": "true",
@@ -28,14 +70,14 @@ function E() {
       strokeWidth: "2",
       viewBox: "0 0 24 24",
       children: [
-        /* @__PURE__ */ e("path", { d: "M18 6 6 18" }),
-        /* @__PURE__ */ e("path", { d: "m6 6 12 12" })
+        /* @__PURE__ */ n("path", { d: "M18 6 6 18" }),
+        /* @__PURE__ */ n("path", { d: "m6 6 12 12" })
       ]
     }
   );
 }
-function T() {
-  return /* @__PURE__ */ s(
+function F() {
+  return /* @__PURE__ */ d(
     "svg",
     {
       "aria-hidden": "true",
@@ -46,209 +88,212 @@ function T() {
       strokeWidth: "2",
       viewBox: "0 0 24 24",
       children: [
-        /* @__PURE__ */ e("rect", { height: "18", rx: "2", width: "18", x: "3", y: "3" }),
-        /* @__PURE__ */ e("path", { d: "M9 3v18" })
+        /* @__PURE__ */ n("rect", { height: "18", rx: "2", width: "18", x: "3", y: "3" }),
+        /* @__PURE__ */ n("path", { d: "M9 3v18" })
       ]
     }
   );
 }
-const m = "sidebar_state", W = 3600 * 24 * 7, N = "(max-width: 767px)";
-function $() {
-  const a = document.cookie.split("; ").find((n) => n.startsWith(`${m}=`));
-  return a ? a.slice(m.length + 1) !== "false" : !0;
+const f = "sidebar_state", q = 3600 * 24 * 7, w = "(max-width: 767px)";
+function D() {
+  const e = document.cookie.split("; ").find((t) => t.startsWith(`${f}=`));
+  return e ? e.slice(f.length + 1) !== "false" : !0;
 }
-function j(a) {
-  document.cookie = `${m}=${a}; path=/; max-age=${W}`;
+function K(e) {
+  document.cookie = `${f}=${e}; path=/; max-age=${q}`;
 }
-function B(a) {
-  const n = window.matchMedia(N);
-  return n.addEventListener("change", a), () => n.removeEventListener("change", a);
+function G(e) {
+  const t = window.matchMedia(w);
+  return t.addEventListener("change", e), () => t.removeEventListener("change", e);
 }
-function A() {
-  return M(
-    B,
-    () => window.matchMedia(N).matches,
+function V() {
+  return C(
+    G,
+    () => window.matchMedia(w).matches,
     () => !1
   );
 }
-function D() {
-  const a = A(), [n, t] = f($), [l, r] = f(!1), d = g((c) => {
-    t(c), j(c);
-  }, []), u = g(() => {
-    if (a) {
-      r((c) => !c);
+function Q() {
+  const e = V(), [t, o] = v(D), [i, r] = v(!1), p = x((s) => {
+    o(s), K(s);
+  }, []), u = x(() => {
+    if (e) {
+      r((s) => !s);
       return;
     }
-    d(!n);
-  }, [a, n, d]);
-  return w(() => {
-    function c(i) {
-      (i.metaKey || i.ctrlKey) && i.key === "b" && (i.preventDefault(), u());
+    p(!t);
+  }, [e, t, p]);
+  return k(() => {
+    function s(c) {
+      (c.metaKey || c.ctrlKey) && c.key === "b" && (c.preventDefault(), u());
     }
-    return window.addEventListener("keydown", c), () => window.removeEventListener("keydown", c);
-  }, [u]), { isMobile: a, open: n, openMobile: l, setOpenMobile: r, toggleSidebar: u };
-}
-function k(a, n) {
-  let t;
-  for (const l of a)
-    for (const r of l.items)
-      (r.to === "/" ? n === "/" : n === r.to || n.startsWith(`${r.to}/`)) && (!t || r.to.length > t.to.length) && (t = r);
-  return t;
-}
-function K({
-  collapsed: a,
-  end: n,
-  item: t,
-  onNavigate: l
+    return window.addEventListener("keydown", s), () => window.removeEventListener("keydown", s);
+  }, [u]), { isMobile: e, open: t, openMobile: i, setOpenMobile: r, toggleSidebar: u };
+}
+function _(e, t) {
+  let o;
+  for (const i of e)
+    for (const r of i.items)
+      (r.to === "/" ? t === "/" : t === r.to || t.startsWith(`${r.to}/`)) && (!o || r.to.length > o.to.length) && (o = r);
+  return o;
+}
+function U({
+  collapsed: e,
+  end: t,
+  item: o,
+  onNavigate: i
 }) {
-  return /* @__PURE__ */ s(p.Root, { children: [
-    /* @__PURE__ */ s(
-      p.Trigger,
+  return /* @__PURE__ */ d(m.Root, { children: [
+    /* @__PURE__ */ d(
+      m.Trigger,
       {
-        render: /* @__PURE__ */ e(
-          C,
+        render: /* @__PURE__ */ n(
+          I,
           {
             className: "ux-nav-item",
-            end: n,
-            onClick: l,
-            to: t.to
+            end: t,
+            onClick: i,
+            to: o.to
           }
         ),
         children: [
-          /* @__PURE__ */ e("span", { className: "ux-nav-item__icon", children: t.icon }),
-          /* @__PURE__ */ e("span", { className: "ux-nav-item__text", children: t.label })
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__icon", children: o.icon }),
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__text", children: o.label })
         ]
       }
     ),
-    /* @__PURE__ */ e(p.Portal, { children: /* @__PURE__ */ e(
-      p.Positioner,
+    /* @__PURE__ */ n(m.Portal, { children: /* @__PURE__ */ n(
+      m.Positioner,
       {
         className: "ux-tooltip-positioner",
         side: "right",
         sideOffset: 6,
-        children: /* @__PURE__ */ e(p.Popup, { className: "ux-tooltip", hidden: !a, children: t.label })
+        children: /* @__PURE__ */ n(m.Popup, { className: "ux-tooltip", hidden: !e, children: o.label })
       }
     ) })
   ] });
 }
-function x({
-  copy: a,
-  logo: n,
-  nav: t,
-  onNavigate: l,
-  state: r,
-  title: d
+function N({
+  copy: e,
+  logo: t,
+  logoRef: o,
+  nav: i,
+  onNavigate: r,
+  state: p,
+  title: u
 }) {
-  const { pathname: u } = v(), c = k(t, u);
-  return /* @__PURE__ */ s(y, { children: [
-    /* @__PURE__ */ s("div", { className: "ux-sidebar__header", children: [
-      /* @__PURE__ */ e("span", { className: "ux-sidebar__logo", children: n }),
-      /* @__PURE__ */ e("span", { className: "ux-sidebar__title", children: d })
+  const { pathname: s } = y(), c = _(i, s);
+  return /* @__PURE__ */ d(L, { children: [
+    /* @__PURE__ */ d("div", { className: "ux-sidebar__header", children: [
+      /* @__PURE__ */ n("span", { className: "ux-sidebar__logo", ref: o, children: t }),
+      /* @__PURE__ */ n("span", { className: "ux-sidebar__title", children: u })
     ] }),
-    /* @__PURE__ */ e("nav", { "aria-label": a.navigation, className: "ux-sidebar__nav", children: t.map((i) => /* @__PURE__ */ s("div", { className: "ux-nav-group", children: [
-      /* @__PURE__ */ e("div", { className: "ux-nav-group__label", children: i.label }),
-      i.items.map((o) => (
+    /* @__PURE__ */ n("nav", { "aria-label": e.navigation, className: "ux-sidebar__nav", children: i.map((l) => /* @__PURE__ */ d("div", { className: "ux-nav-group", children: [
+      /* @__PURE__ */ n("div", { className: "ux-nav-group__label", children: l.label }),
+      l.items.map((a) => (
         // NavLink would mark a parent section current on its children's
         // routes; follow matchActiveItem instead so only the deepest
         // match (or the exact path) stays marked.
-        /* @__PURE__ */ e(
-          K,
+        /* @__PURE__ */ n(
+          U,
           {
-            collapsed: r === "collapsed",
-            end: o !== c || o.to === u,
-            item: o,
-            onNavigate: l
+            collapsed: p === "collapsed",
+            end: a !== c || a.to === s,
+            item: a,
+            onNavigate: r
           },
-          o.to
+          a.to
         )
       ))
-    ] }, i.label)) })
+    ] }, l.label)) })
   ] });
 }
-function H({
-  children: a,
-  headerSlot: n,
-  logo: t,
-  nav: l,
-  pageTitle: r,
-  title: d
+function te({
+  children: e,
+  favicon: t = !0,
+  headerSlot: o,
+  logo: i,
+  nav: r,
+  pageTitle: p,
+  title: u
 }) {
-  var b;
-  const { pathname: u } = v(), { lang: c } = L(), i = I(c), o = D(), _ = r ?? ((b = k(l, u)) == null ? void 0 : b.label);
-  return /* @__PURE__ */ e(p.Provider, { delay: 0, children: /* @__PURE__ */ s(
+  var g;
+  const { pathname: s } = y(), { lang: c } = E(), l = A(c), a = Q(), b = M(null), S = p ?? ((g = _(r, s)) == null ? void 0 : g.label);
+  return z(b, t), /* @__PURE__ */ n(m.Provider, { delay: 0, children: /* @__PURE__ */ d(
     "div",
     {
       className: "ux-app-layout",
-      "data-state": o.open ? "expanded" : "collapsed",
+      "data-state": a.open ? "expanded" : "collapsed",
       children: [
-        /* @__PURE__ */ e("aside", { className: "ux-sidebar", children: /* @__PURE__ */ e(
-          x,
+        /* @__PURE__ */ n("aside", { className: "ux-sidebar", children: /* @__PURE__ */ n(
+          N,
           {
-            copy: i,
-            logo: t,
-            nav: l,
-            state: o.open ? "expanded" : "collapsed",
-            title: d
+            copy: l,
+            logo: i,
+            logoRef: b,
+            nav: r,
+            state: a.open ? "expanded" : "collapsed",
+            title: u
           }
         ) }),
-        o.isMobile ? /* @__PURE__ */ e(
+        a.isMobile ? /* @__PURE__ */ n(
           h.Root,
           {
-            open: o.openMobile,
-            onOpenChange: o.setOpenMobile,
-            children: /* @__PURE__ */ s(h.Portal, { children: [
-              /* @__PURE__ */ e(h.Backdrop, { className: "ux-drawer-backdrop" }),
-              /* @__PURE__ */ s(h.Popup, { className: "ux-drawer", children: [
-                /* @__PURE__ */ e(h.Title, { className: "ux-visually-hidden", children: i.navigation }),
-                /* @__PURE__ */ e(
+            open: a.openMobile,
+            onOpenChange: a.setOpenMobile,
+            children: /* @__PURE__ */ d(h.Portal, { children: [
+              /* @__PURE__ */ n(h.Backdrop, { className: "ux-drawer-backdrop" }),
+              /* @__PURE__ */ d(h.Popup, { className: "ux-drawer", children: [
+                /* @__PURE__ */ n(h.Title, { className: "ux-visually-hidden", children: l.navigation }),
+                /* @__PURE__ */ n(
                   "button",
                   {
-                    "aria-label": i.closeNavigation,
+                    "aria-label": l.closeNavigation,
                     className: "ux-drawer__close",
                     type: "button",
-                    onClick: () => o.setOpenMobile(!1),
-                    children: /* @__PURE__ */ e(E, {})
+                    onClick: () => a.setOpenMobile(!1),
+                    children: /* @__PURE__ */ n(B, {})
                   }
                 ),
-                /* @__PURE__ */ e(
-                  x,
+                /* @__PURE__ */ n(
+                  N,
                   {
-                    copy: i,
-                    logo: t,
-                    nav: l,
-                    onNavigate: () => o.setOpenMobile(!1),
+                    copy: l,
+                    logo: i,
+                    nav: r,
+                    onNavigate: () => a.setOpenMobile(!1),
                     state: "expanded",
-                    title: d
+                    title: u
                   }
                 )
               ] })
             ] })
           }
         ) : null,
-        /* @__PURE__ */ s("div", { className: "ux-shell", children: [
-          /* @__PURE__ */ s("header", { className: "ux-app-header", children: [
-            /* @__PURE__ */ e(
+        /* @__PURE__ */ d("div", { className: "ux-shell", children: [
+          /* @__PURE__ */ d("header", { className: "ux-app-header", children: [
+            /* @__PURE__ */ n(
               "button",
               {
-                "aria-expanded": o.isMobile ? o.openMobile : o.open,
-                "aria-label": i.toggleSidebar,
+                "aria-expanded": a.isMobile ? a.openMobile : a.open,
+                "aria-label": l.toggleSidebar,
                 className: "ux-app-header__trigger",
                 type: "button",
-                onClick: o.toggleSidebar,
-                children: /* @__PURE__ */ e(T, {})
+                onClick: a.toggleSidebar,
+                children: /* @__PURE__ */ n(F, {})
               }
             ),
-            /* @__PURE__ */ e("span", { "aria-hidden": "true", className: "ux-app-header__separator" }),
-            /* @__PURE__ */ e("p", { className: "ux-app-header__title", children: _ }),
-            /* @__PURE__ */ e("div", { className: "ux-app-header__slot", children: n }),
-            /* @__PURE__ */ e(S, {})
+            /* @__PURE__ */ n("span", { "aria-hidden": "true", className: "ux-app-header__separator" }),
+            /* @__PURE__ */ n("p", { className: "ux-app-header__title", children: S }),
+            /* @__PURE__ */ n("div", { className: "ux-app-header__slot", children: o }),
+            /* @__PURE__ */ n(O, {})
           ] }),
-          /* @__PURE__ */ e("main", { className: "ux-main", children: a })
+          /* @__PURE__ */ n("main", { className: "ux-main", children: e })
         ] })
       ]
     }
   ) });
 }
 export {
-  H as AppLayout
+  te as AppLayout
 };

package/dist/types.d.ts

@@ -9,6 +9,7 @@ export type AppNavGroup = {
     items: AppNavItem[];
 };
 export type AppLayoutProps = {
+    favicon?: boolean;
     logo: ReactNode;
     title: string;
     nav: AppNavGroup[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zccz14/ux",
-  "version": "0.2.1",
-  "description": "Unified AppLayout shell for the NTNL app family: one animated icon sidebar, a fixed-size logo box, and the Linkit-integrated AppHeader.",
+  "version": "0.3.0",
+  "description": "Unified AppLayout shell for the NTNL app family: one animated icon sidebar, a fixed-size logo that doubles as the page favicon, and the Linkit-integrated AppHeader.",
   "license": "MIT",
   "repository": {
     "type": "git",