@zccz14/ux 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zheng Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @zccz14/ux
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@zccz14/ux` provides the shared `AppLayout` shell for the NTNL app family (Cybion, NormAI, CTX, Linkit, Midas, HIT, 1Exchange, DeepSeek-LB, OpenAI-LB). One implementation of the sidebar, the AppHeader, and the Linkit account control keeps the interaction identical across apps and replaces the per-app copies of that chrome.
+
+## What the shell owns
+
+- **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.
+- **Logo** — you pass the light and dark logo marks; the shell renders the active variant inside a fixed 1.75rem box and controls the display size itself, so the logo size is identical everywhere. The title beside the logo disappears while collapsed.
+- **Linkit integration** — the signed-in viewer's `resolvedTheme` picks the logo variant, the viewer's language selects the shell copy (中文/English), and theme, language and account controls all live in the `LinkitMyInfo` dialog.
+
+## Installation
+
+```sh
+npm install @zccz14/ux
+```
+
+Peer dependencies: `react` (18 or 19), `react-dom`, `react-router-dom` 7, `@base-ui/react` ≥ 1.6, `linkit-react-components` ≥ 0.5.1 (older versions do not publish `resolvedTheme`).
+
+## Usage
+
+```tsx
+import { AuthMiniProvider } from "auth-mini-react-components";
+import { LinkitProvider } from "linkit-react-components";
+import { AppLayout } from "@zccz14/ux";
+import { MessagesSquareIcon, ServerIcon } from "lucide-react";
+import { HashRouter, Navigate, Route, Routes } from "react-router-dom";
+
+import "@zccz14/ux/styles.css";
+import "linkit-react-components/styles.css";
+import { CybionMark } from "./cybion-mark";
+
+export function App() {
+  return (
+    <AuthMiniProvider
+      authMiniBaseUrl="https://auth.ntnl.io"
+      audiences={["cybion.ntnl.io", "linkit.ntnl.io"]}
+      autoRedirectToLogin
+    >
+      <LinkitProvider linkitBaseUrl="https://linkit.ntnl.io" lang="zh-CN">
+        <HashRouter>
+          <AppLayout
+            logo={{ light: <CybionMark />, dark: <CybionMark /> }}
+            title="Cybion"
+            nav={[
+              {
+                label: "工作台",
+                items: [
+                  { to: "/threads", label: "对话", icon: <MessagesSquareIcon /> },
+                  { to: "/system", label: "系统资源", icon: <ServerIcon /> },
+                ],
+              },
+            ]}
+            headerSlot={<RefreshButton />}
+          >
+            <Routes>
+              <Route path="/threads" element={<ThreadsPage />} />
+              <Route path="*" element={<Navigate replace to="/threads" />} />
+            </Routes>
+          </AppLayout>
+        </HashRouter>
+      </LinkitProvider>
+    </AuthMiniProvider>
+  );
+}
+```
+
+`AppLayout` must render below `AuthMiniProvider → LinkitProvider` (it renders `LinkitMyInfo` and reads `useLinkit()`), and inside a router (navigation items render router links).
+
+## API
+
+### `AppLayout` props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `logo` | `{ light: ReactNode; dark: ReactNode }` | yes | The two logo variants. The shell renders the one that matches `useLinkit().resolvedTheme` at its own fixed size. |
+| `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. |
+| `pageTitle` | `ReactNode` | no | Overrides the page title derived from the active navigation item. Use it for detail routes with their own title. |
+| `children` | `ReactNode` | yes | Page content, rendered in the scrollable main region. |
+
+### Navigation types
+
+```ts
+type AppNavItem = { to: string; label: string; icon: ReactNode };
+type AppNavGroup = { label: string; items: AppNavItem[] };
+```
+
+`to` is a router path. Each item renders a `NavLink`, so active items receive `aria-current="page"` and the standard active styling. Route matching uses longest-prefix wins, and `/` matches only exactly.
+
+## Behavior
+
+- **Page title** — the AppHeader shows the active navigation item's `label`, matched from `location.pathname`. `pageTitle` wins when supplied.
+- **Collapse** — the header trigger or `⌘B` / `Ctrl+B` toggles the sidebar; the choice persists in the `sidebar_state` cookie.
+- **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.
+- **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
+
+Import `@zccz14/ux/styles.css` once. It consumes the app's shadcn theme tokens with built-in fallbacks: `--background`, `--foreground`, `--border`, `--accent`, `--muted`, `--ring`, `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`.
+
+## Migrating an app from its local shell
+
+1. Replace the local `SidebarProvider` / `Sidebar` / `AppHeader` copy with one `AppLayout` at the top of `App.tsx`.
+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.5+).
+3. Move any sidebar footer item (settings, environment status) into the last navigation group.
+4. Pass the logo pair and delete per-call sizes; the shell normalizes every mark to its 1.75rem box.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run pack:check
+```

package/dist/app-layout.d.ts

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

package/dist/copy.d.ts

@@ -0,0 +1,6 @@
+export type AppLayoutCopy = {
+    closeNavigation: string;
+    navigation: string;
+    toggleSidebar: string;
+};
+export declare function copyForLang(lang: string): AppLayoutCopy;

package/dist/icons.d.ts

@@ -0,0 +1,2 @@
+export declare function CloseIcon(): import("react").JSX.Element;
+export declare function PanelLeftIcon(): import("react").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AppLayout } from "./app-layout.js";
+export type { AppLayoutProps, AppLogo, AppNavGroup, AppNavItem } from "./types.js";

package/dist/index.js

@@ -0,0 +1,247 @@
+import { jsxs as s, jsx as e, Fragment as _ } from "react/jsx-runtime";
+import { useState as f, useCallback as g, useEffect as y, useSyncExternalStore as w } from "react";
+import { Dialog as h } from "@base-ui/react/dialog";
+import { Tooltip as p } from "@base-ui/react/tooltip";
+import { useLinkit as v, LinkitMyInfo as M } from "linkit-react-components";
+import { useLocation as L, NavLink as S } from "react-router-dom";
+const C = {
+  closeNavigation: "Close navigation",
+  navigation: "Navigation",
+  toggleSidebar: "Toggle sidebar"
+}, O = {
+  closeNavigation: "关闭导航",
+  navigation: "导航",
+  toggleSidebar: "切换侧边栏"
+};
+function P(n) {
+  return n.toLowerCase().startsWith("zh") ? O : C;
+}
+function T() {
+  return /* @__PURE__ */ s(
+    "svg",
+    {
+      "aria-hidden": "true",
+      fill: "none",
+      stroke: "currentColor",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      strokeWidth: "2",
+      viewBox: "0 0 24 24",
+      children: [
+        /* @__PURE__ */ e("path", { d: "M18 6 6 18" }),
+        /* @__PURE__ */ e("path", { d: "m6 6 12 12" })
+      ]
+    }
+  );
+}
+function E() {
+  return /* @__PURE__ */ s(
+    "svg",
+    {
+      "aria-hidden": "true",
+      fill: "none",
+      stroke: "currentColor",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      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" })
+      ]
+    }
+  );
+}
+const m = "sidebar_state", I = 3600 * 24 * 7, N = "(max-width: 767px)";
+function W() {
+  const n = document.cookie.split("; ").find((a) => a.startsWith(`${m}=`));
+  return n ? n.slice(m.length + 1) !== "false" : !0;
+}
+function $(n) {
+  document.cookie = `${m}=${n}; path=/; max-age=${I}`;
+}
+function j(n) {
+  const a = window.matchMedia(N);
+  return a.addEventListener("change", n), () => a.removeEventListener("change", n);
+}
+function B() {
+  return w(
+    j,
+    () => window.matchMedia(N).matches,
+    () => !1
+  );
+}
+function A() {
+  const n = B(), [a, t] = f(W), [c, r] = f(!1), d = g((i) => {
+    t(i), $(i);
+  }, []), u = g(() => {
+    if (n) {
+      r((i) => !i);
+      return;
+    }
+    d(!a);
+  }, [n, a, d]);
+  return y(() => {
+    function i(o) {
+      (o.metaKey || o.ctrlKey) && o.key === "b" && (o.preventDefault(), u());
+    }
+    return window.addEventListener("keydown", i), () => window.removeEventListener("keydown", i);
+  }, [u]), { isMobile: n, open: a, openMobile: c, setOpenMobile: r, toggleSidebar: u };
+}
+function D(n, a) {
+  let t;
+  for (const c of n)
+    for (const r of c.items)
+      (r.to === "/" ? a === "/" : a === r.to || a.startsWith(`${r.to}/`)) && (!t || r.to.length > t.to.length) && (t = r);
+  return t;
+}
+function K({
+  collapsed: n,
+  item: a,
+  onNavigate: t
+}) {
+  return /* @__PURE__ */ s(p.Root, { children: [
+    /* @__PURE__ */ s(
+      p.Trigger,
+      {
+        render: /* @__PURE__ */ e(
+          S,
+          {
+            className: "ux-nav-item",
+            end: a.to === "/",
+            onClick: t,
+            to: a.to
+          }
+        ),
+        children: [
+          /* @__PURE__ */ e("span", { className: "ux-nav-item__icon", children: a.icon }),
+          /* @__PURE__ */ e("span", { className: "ux-nav-item__text", children: a.label })
+        ]
+      }
+    ),
+    /* @__PURE__ */ e(p.Portal, { children: /* @__PURE__ */ e(
+      p.Positioner,
+      {
+        className: "ux-tooltip-positioner",
+        side: "right",
+        sideOffset: 6,
+        children: /* @__PURE__ */ e(p.Popup, { className: "ux-tooltip", hidden: !n, children: a.label })
+      }
+    ) })
+  ] });
+}
+function x({
+  copy: n,
+  logo: a,
+  nav: t,
+  onNavigate: c,
+  state: r,
+  title: d
+}) {
+  const { resolvedTheme: u } = v();
+  return /* @__PURE__ */ s(_, { children: [
+    /* @__PURE__ */ s("div", { className: "ux-sidebar__header", children: [
+      /* @__PURE__ */ e("span", { className: "ux-sidebar__logo", children: u === "dark" ? a.dark : a.light }),
+      /* @__PURE__ */ e("span", { className: "ux-sidebar__title", children: d })
+    ] }),
+    /* @__PURE__ */ e("nav", { "aria-label": n.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__ */ e(
+        K,
+        {
+          collapsed: r === "collapsed",
+          item: o,
+          onNavigate: c
+        },
+        o.to
+      ))
+    ] }, i.label)) })
+  ] });
+}
+function H({
+  children: n,
+  headerSlot: a,
+  logo: t,
+  nav: c,
+  pageTitle: r,
+  title: d
+}) {
+  var b;
+  const { pathname: u } = L(), { lang: i } = v(), o = P(i), l = A(), k = r ?? ((b = D(c, u)) == null ? void 0 : b.label);
+  return /* @__PURE__ */ e(p.Provider, { delay: 0, children: /* @__PURE__ */ s(
+    "div",
+    {
+      className: "ux-app-layout",
+      "data-state": l.open ? "expanded" : "collapsed",
+      children: [
+        /* @__PURE__ */ e("aside", { className: "ux-sidebar", children: /* @__PURE__ */ e(
+          x,
+          {
+            copy: o,
+            logo: t,
+            nav: c,
+            state: l.open ? "expanded" : "collapsed",
+            title: d
+          }
+        ) }),
+        l.isMobile ? /* @__PURE__ */ e(
+          h.Root,
+          {
+            open: l.openMobile,
+            onOpenChange: l.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: o.navigation }),
+                /* @__PURE__ */ e(
+                  "button",
+                  {
+                    "aria-label": o.closeNavigation,
+                    className: "ux-drawer__close",
+                    type: "button",
+                    onClick: () => l.setOpenMobile(!1),
+                    children: /* @__PURE__ */ e(T, {})
+                  }
+                ),
+                /* @__PURE__ */ e(
+                  x,
+                  {
+                    copy: o,
+                    logo: t,
+                    nav: c,
+                    onNavigate: () => l.setOpenMobile(!1),
+                    state: "expanded",
+                    title: d
+                  }
+                )
+              ] })
+            ] })
+          }
+        ) : null,
+        /* @__PURE__ */ s("div", { className: "ux-shell", children: [
+          /* @__PURE__ */ s("header", { className: "ux-app-header", children: [
+            /* @__PURE__ */ e(
+              "button",
+              {
+                "aria-expanded": l.isMobile ? l.openMobile : l.open,
+                "aria-label": o.toggleSidebar,
+                className: "ux-app-header__trigger",
+                type: "button",
+                onClick: l.toggleSidebar,
+                children: /* @__PURE__ */ e(E, {})
+              }
+            ),
+            /* @__PURE__ */ e("span", { "aria-hidden": "true", className: "ux-app-header__separator" }),
+            /* @__PURE__ */ e("p", { className: "ux-app-header__title", children: k }),
+            /* @__PURE__ */ e("div", { className: "ux-app-header__slot", children: a }),
+            /* @__PURE__ */ e(M, {})
+          ] }),
+          /* @__PURE__ */ e("main", { className: "ux-main", children: n })
+        ] })
+      ]
+    }
+  ) });
+}
+export {
+  H as AppLayout
+};

package/dist/styles.css

@@ -0,0 +1,418 @@
+/* @zccz14/ux — unified AppLayout shell. Include this file once from the consuming application. */
+
+.ux-app-layout {
+  display: flex;
+  height: 100svh;
+  overflow: hidden;
+  color: var(--foreground, #0f172a);
+  background: var(--background, #fff);
+}
+
+/* --- Sidebar --- */
+
+.ux-sidebar {
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  width: 16rem;
+  overflow: hidden;
+  color: var(--sidebar-foreground, var(--foreground, #0f172a));
+  background: var(--sidebar, #fafafa);
+  border-right: 1px solid var(--sidebar-border, #e2e8f0);
+  transition: width 200ms linear;
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-sidebar {
+  width: 3rem;
+}
+
+.ux-sidebar__header {
+  box-sizing: border-box;
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 0.5rem;
+  height: 3.5rem;
+  padding: 0 0.75rem;
+  transition: padding 200ms linear;
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-sidebar__header {
+  justify-content: center;
+  padding: 0;
+}
+
+.ux-drawer .ux-sidebar__header {
+  padding-right: 3rem;
+}
+
+/* The framework owns the logo display size: both logo variants render inside a fixed 1.75rem box. */
+.ux-sidebar__logo {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+}
+
+.ux-sidebar__logo svg,
+.ux-sidebar__logo img {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.ux-sidebar__title {
+  min-width: 0;
+  overflow: hidden;
+  font-size: 0.875rem;
+  font-weight: 600;
+  line-height: 1.25;
+  white-space: nowrap;
+  transition: opacity 150ms linear;
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-sidebar__title {
+  opacity: 0;
+}
+
+.ux-sidebar__nav {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 0.25rem;
+  min-height: 0;
+  padding: 0.5rem;
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+.ux-nav-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.ux-nav-group__label {
+  display: flex;
+  flex: none;
+  align-items: center;
+  height: 2rem;
+  padding: 0 0.5rem;
+  overflow: hidden;
+  font-size: 0.75rem;
+  font-weight: 500;
+  white-space: nowrap;
+  opacity: 0.7;
+  transition: margin-top 200ms linear, opacity 200ms linear;
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-nav-group__label {
+  margin-top: -2rem;
+  opacity: 0;
+}
+
+.ux-nav-item {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  height: 2rem;
+  padding: 0 0.5rem;
+  overflow: hidden;
+  color: inherit;
+  font-size: 0.875rem;
+  line-height: 1.25;
+  text-decoration: none;
+  border-radius: 0.375rem;
+  outline: none;
+  transition:
+    background-color 150ms ease-out,
+    color 150ms ease-out,
+    padding 200ms linear;
+}
+
+.ux-nav-item:hover {
+  color: var(--sidebar-accent-foreground, #0f172a);
+  background: var(--sidebar-accent, #f1f5f9);
+}
+
+.ux-nav-item:focus-visible {
+  outline: 2px solid var(--sidebar-ring, #2563eb);
+  outline-offset: -2px;
+}
+
+.ux-nav-item[aria-current="page"] {
+  color: var(--sidebar-accent-foreground, #0f172a);
+  font-weight: 500;
+  background: var(--sidebar-accent, #f1f5f9);
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-nav-item {
+  justify-content: center;
+  gap: 0;
+  width: 2rem;
+  padding: 0;
+}
+
+.ux-nav-item__icon {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+}
+
+.ux-nav-item__icon svg {
+  display: block;
+  width: 1rem;
+  height: 1rem;
+}
+
+.ux-nav-item__text {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  transition: opacity 150ms linear;
+}
+
+.ux-app-layout[data-state="collapsed"] .ux-nav-item__text {
+  opacity: 0;
+}
+
+@media (max-width: 767px) {
+  .ux-sidebar {
+    display: none;
+  }
+}
+
+/* --- App header and main content --- */
+
+.ux-shell {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.ux-app-header {
+  box-sizing: border-box;
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 0.75rem;
+  height: 3.5rem;
+  padding: 0 1rem;
+  background: var(--background, #fff);
+  border-bottom: 1px solid var(--border, #e2e8f0);
+}
+
+.ux-app-header__trigger {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  border-radius: 0.375rem;
+  outline: none;
+  transition: background-color 150ms ease-out;
+}
+
+.ux-app-header__trigger:hover {
+  background: var(--accent, var(--muted, #f1f5f9));
+}
+
+.ux-app-header__trigger:focus-visible {
+  outline: 2px solid var(--ring, #2563eb);
+  outline-offset: 2px;
+}
+
+.ux-app-header__trigger svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+.ux-app-header__separator {
+  flex: none;
+  width: 1px;
+  height: 1.25rem;
+  background: var(--border, #e2e8f0);
+}
+
+.ux-app-header__title {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1.25;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ux-app-header__slot {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.ux-main {
+  box-sizing: border-box;
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+  padding: 1rem;
+  overflow-y: auto;
+}
+
+/* --- Mobile navigation drawer --- */
+
+.ux-drawer-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  background: rgb(0 0 0 / 0.45);
+  transition: opacity 200ms ease-out;
+}
+
+.ux-drawer-backdrop[data-starting-style],
+.ux-drawer-backdrop[data-ending-style] {
+  opacity: 0;
+}
+
+.ux-drawer {
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  width: 18rem;
+  max-width: calc(100vw - 3rem);
+  overflow: hidden;
+  color: var(--sidebar-foreground, var(--foreground, #0f172a));
+  background: var(--sidebar, #fafafa);
+  border-right: 1px solid var(--sidebar-border, #e2e8f0);
+  outline: none;
+  transition: transform 200ms ease-out, opacity 200ms ease-out;
+}
+
+.ux-drawer[data-starting-style],
+.ux-drawer[data-ending-style] {
+  opacity: 0;
+  transform: translateX(-2.5rem);
+}
+
+.ux-drawer__close {
+  position: absolute;
+  top: 0.75rem;
+  right: 0.75rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  border-radius: 0.375rem;
+  transition: background-color 150ms ease-out;
+}
+
+.ux-drawer__close:hover {
+  background: var(--sidebar-accent, #f1f5f9);
+}
+
+.ux-drawer__close:focus-visible {
+  outline: 2px solid var(--sidebar-ring, #2563eb);
+  outline-offset: 2px;
+}
+
+.ux-drawer__close svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+/* --- Collapsed navigation tooltip --- */
+
+.ux-tooltip-positioner {
+  z-index: 60;
+}
+
+.ux-tooltip {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  max-width: 16rem;
+  padding: 0.375rem 0.75rem;
+  color: var(--background, #fff);
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1.25;
+  white-space: nowrap;
+  background: var(--foreground, #0f172a);
+  border-radius: 0.375rem;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 0.12);
+  transition: opacity 120ms ease-out, transform 120ms ease-out;
+}
+
+.ux-tooltip[hidden] {
+  display: none;
+}
+
+.ux-tooltip[data-starting-style],
+.ux-tooltip[data-ending-style] {
+  opacity: 0;
+  transform: scale(0.96);
+}
+
+.ux-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (min-width: 768px) {
+  .ux-app-header {
+    padding: 0 1.5rem;
+  }
+
+  .ux-main {
+    padding: 1.5rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ux-sidebar,
+  .ux-sidebar__header,
+  .ux-sidebar__title,
+  .ux-nav-group__label,
+  .ux-nav-item,
+  .ux-nav-item__text,
+  .ux-drawer,
+  .ux-drawer-backdrop,
+  .ux-tooltip {
+    transition: none;
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+export type AppLogo = {
+    light: ReactNode;
+    dark: ReactNode;
+};
+export type AppNavItem = {
+    to: string;
+    label: string;
+    icon: ReactNode;
+};
+export type AppNavGroup = {
+    label: string;
+    items: AppNavItem[];
+};
+export type AppLayoutProps = {
+    logo: AppLogo;
+    title: string;
+    nav: AppNavGroup[];
+    headerSlot?: ReactNode;
+    pageTitle?: ReactNode;
+    children: ReactNode;
+};

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@zccz14/ux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Unified AppLayout shell for the NTNL app family: one animated icon sidebar, a fixed-size dark/light logo, and the Linkit-integrated AppHeader.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zccz14/ux.git"
+  },
+  "homepage": "https://github.com/zccz14/ux#readme",
+  "bugs": {
+    "url": "https://github.com/zccz14/ux/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && cp src/styles.css dist/styles.css",
+    "test": "vitest run && node scripts/check-styles.mjs",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "linkit-react-components": "^0.5.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "auth-mini-react-components": "^0.6.10",
+    "jsdom": "^26.1.0",
+    "linkit-react-components": "^0.5.1",
+    "lucide-react": "^1.31.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-router-dom": "^7.18.1",
+    "typescript": "^5.9.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4"
+  }
+}