@artstorefronts/arthelper-nav 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,266 @@
+# @artstorefronts/arthelper-nav
+
+The ArtHelper suite navigation bar — a config-driven, cross-origin app switcher for the
+satellite apps in the ArtHelper suite.
+
+This document is for an engineer wiring the bar into a host app that lives **outside**
+this monorepo. If you're working inside this repo, see `docs/llms/suite-nav.md` for how
+the pieces fit together end to end.
+
+## Architecture in one line
+
+Configure in data, render in code. The bar's content — theme, logo, and the app catalog
+— lives in a single database row, served as JSON over a public HTTP endpoint. Every
+mounted host fetches that JSON on load. An edit made in the admin editor is live for
+every app in the suite on their next page load — no deploy, no version bump, no
+coordinated release across repos.
+
+## Install
+
+```bash
+npm install @artstorefronts/arthelper-nav
+```
+
+Peer dependencies (from `package.json` — install these yourself, they are not bundled):
+
+```json
+{
+  "lucide-react": ">=0.446.0",
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0"
+}
+```
+
+> **Not yet on npm.** Publishing is automatic: `.github/workflows/release-nav.yml` runs on
+> any push to `develop` that touches `packages/nav`, and publishes when the version in
+> `packages/nav/package.json` is not already on the registry. There is no tag and no
+> manual release step — **bumping that version in your PR is what ships the package**, and
+> a PR that changes the published surface without bumping it fails CI.
+>
+> The `@artstorefronts` scope already exists (it publishes `@artstorefronts/ui` and
+> `@artstorefronts/cli`). What is still missing is a **trusted publisher** configured on
+> npm for this package, pointing at this repository and the workflow filename
+> `release-nav.yml`. Authentication is OIDC, so there is no token to create or rotate.
+> Until that is configured, `npm install @artstorefronts/arthelper-nav` has nothing to
+> resolve.
+>
+> To develop against it before the first publish, use a workspace link or a path
+> dependency from the satellite repo:
+>
+> ```bash
+> cd packages/nav && yarn link
+> cd ../../../<satellite> && yarn link @artstorefronts/arthelper-nav
+> ```
+>
+> `react` and `react-dom` are peer dependencies, so make sure the satellite's bundler
+> resolves a single copy of React — a linked package pulling in its own is the usual
+> cause of the duplicate-React hooks error.
+
+## Minimal mounting example
+
+```tsx
+// Import the stylesheet by its deep path — it is not re-exported from the package root.
+import '@artstorefronts/arthelper-nav/dist/index.css';
+import { NavProvider, NavBar, NavTrigger } from '@artstorefronts/arthelper-nav';
+
+function AppRoot() {
+  return (
+    <NavProvider activeAppId="my-app" configUrl="https://api.arthelper.com/rest/nav-config">
+      {/* NavBar first, so it occupies real layout space at the top of the shell. */}
+      <NavBar />
+      <AppHeader />
+      <AppContent />
+    </NavProvider>
+  );
+}
+
+function AppHeader() {
+  return (
+    <header>
+      <Logo />
+      {/* NavTrigger is the RESTORE control. Omit it and a viewer who collapses the
+          bar has no way to bring it back. */}
+      <NavTrigger />
+    </header>
+  );
+}
+```
+
+`NavProvider` renders no DOM of its own — `NavBar` and whatever else you nest inside it
+stay direct children of your own layout, so the 56px the bar reserves comes purely from
+`NavBar` itself, not from a wrapper.
+
+## Components and props
+
+### `NavProvider`
+
+The context host. Fetches config, resolves the app list, and owns collapsed state. Must
+wrap `NavBar`, `NavTrigger`, and any component calling `useNav()`.
+
+| Prop               | Type                              | Required | Description                                                                                                                                                                    |
+| ------------------ | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `configUrl`        | `string`                          | yes      | Full URL of the public nav-config endpoint. See [Deriving `configUrl`](#deriving-configurl) below.                                                                             |
+| `activeAppId`      | `string`                          | yes      | The catalog id of the app the host itself is. Never inferred from the URL or the payload — the host always declares it.                                                        |
+| `onAppClick`       | `(args: NavAppClickArgs) => void` | no       | Fired immediately before navigation. The package's only analytics seam — see [`onAppClick`](#onappclick-the-analytics-seam).                                                   |
+| `fallbackConfig`   | `NavConfigPayload`                | no       | Overrides the package's compiled-in fallback, e.g. for a satellite with a different first-party destination set.                                                               |
+| `initialCollapsed` | `boolean`                         | no       | The collapsed cookie value a server-rendered host already read, so the first byte paints the correct state. See [SSR and the collapsed cookie](#ssr-and-the-collapsed-cookie). |
+| `children`         | `ReactNode`                       | no       | —                                                                                                                                                                              |
+
+### `NavBar`
+
+Renders the bar itself: waffle toggle, wordmark/logo, the desktop tile row (or, below the
+768px breakpoint, a labelled dropdown trigger and panel with the same entries as rows).
+
+| Prop        | Type      | Default | Description                                                                            |
+| ----------- | --------- | ------- | -------------------------------------------------------------------------------------- |
+| `sticky`    | `boolean` | `false` | Opt in only for a host whose document actually scrolls. See [`sticky`](#sticky) below. |
+| `className` | `string`  | —       | Appended to the bar's root class list.                                                 |
+
+### `NavTrigger`
+
+The docked waffle-plus-active-app chip a host places in its own header, next to its own
+logo. This is the **restore** control: while the bar is collapsed (`NavBar` reserves
+nothing and is out of the accessibility tree), `NavTrigger` is the only way back. It is
+`display: none` while the bar is expanded. A host that mounts `NavBar` without also
+mounting `NavTrigger` ships a bar a viewer can collapse and never recover.
+
+| Prop        | Type     | Default | Description                                |
+| ----------- | -------- | ------- | ------------------------------------------ |
+| `className` | `string` | —       | Appended to the trigger's root class list. |
+
+### Exported types
+
+`NavContextValue`, `NavBarProps`, `NavTriggerProps`, `NavProviderProps`, `NavAlignment`,
+`NavApp`, `NavAppClickArgs`, `NavConfigPayload`, `NavLogo`, `NavTheme`, `NavThemeMode`,
+`ResolvedNavApp` — all exported from the package root (`src/index.ts`), also useful if
+you're typing `fallbackConfig` or `onAppClick` yourself.
+
+`useNav()` is also exported, for a component nested under `NavProvider` that needs
+`collapsed`, `toggle`, `activeApp`, or `apps` directly — the two host mounts in this
+monorepo use it, for example, to publish the bar's live height as a CSS variable.
+
+## `activeAppId`
+
+The host is always the one source of truth for which app it is. `NavProvider` never
+infers this from the current URL and never reads it from the config payload — you pass
+it explicitly, and it must match one of the `id`s in the nav-config app catalog (ask the
+ArtHelper team for your app's id, or check the payload at `GET /rest/nav-config`).
+
+That entry is always rendered and indicated (its tile carries the active styling) even if
+the payload has it disabled or omits a destination for it. If your own app has no `href`
+in the catalog yet, its tile renders as an inert indicator instead of a link — it never
+disappears from the bar.
+
+## Deriving `configUrl`
+
+No new environment variable is needed. Derive it from whatever ArtHelper API base URL
+your app already has, by swapping the `graphql` path segment for `rest` and appending
+`/nav-config`:
+
+```ts
+const NAV_CONFIG_URL = `${ARTHELPER_API_BASE.replace('graphql', 'rest')}/nav-config`;
+// e.g. https://api.arthelper.com/graphql -> https://api.arthelper.com/rest/nav-config
+```
+
+This is the same derivation both in-monorepo hosts (`client/`, `town-square/`) use.
+
+## `onAppClick`: the analytics seam
+
+The package imports no analytics library of any kind. `onAppClick` is the one hook
+through which a host wires its own analytics — it fires immediately before navigation,
+from **both** the desktop tile row and the mobile dropdown, so one callback covers both
+surfaces:
+
+```ts
+<NavProvider
+  activeAppId="my-app"
+  configUrl={NAV_CONFIG_URL}
+  onAppClick={({ app, activeAppId, collapsed }) => {
+    myAnalytics.track('suite_nav_app_clicked', { targetAppId: app.id, activeAppId, collapsed });
+  }}
+>
+```
+
+Navigation itself happens via a real `<a href>` the browser follows natively —
+`onAppClick` never intercepts or prevents it.
+
+## SSR and the collapsed cookie
+
+The collapsed flag lives in a **cookie** (`arthelper_suite_nav_collapsed`), not
+`localStorage`. That's deliberate: a server-rendered host can read the cookie during SSR
+and pass its value in as `initialCollapsed`, so the very first byte the browser paints
+already has the bar in the right state — no expanded-then-collapsed jump after
+hydration.
+
+```tsx
+// Next.js App Router example
+import { cookies } from 'next/headers';
+import { COLLAPSED_COOKIE } from '@artstorefronts/arthelper-nav';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const cookieStore = await cookies();
+  const initialCollapsed = cookieStore.get(COLLAPSED_COOKIE)?.value === 'true';
+
+  return (
+    <NavProvider activeAppId="my-app" configUrl={NAV_CONFIG_URL} initialCollapsed={initialCollapsed}>
+      {children}
+    </NavProvider>
+  );
+}
+```
+
+The cookie is **per-origin**. `app.example.com` and `www.example.com` are different
+registrable domains and share no cookie scope, so collapsing the bar on one origin does
+not sync to another — each origin's viewer sets their own collapsed state independently.
+
+## Theming
+
+`theme.mode` (`'dark' | 'light'`), `theme.accent_color`, and `theme.alignment`
+(`'left' | 'centered'`) all come from the config payload, set by an admin in the nav
+editor. Changing any of them is a config edit, not a package release or a host
+deployment — every mounted app picks it up on its next fetch.
+
+## The layout contract
+
+`NavBar` reserves exactly 56px from first paint, using the package's compiled-in
+fallback config while the real payload is in flight — so config arrival never shifts the
+page. Collapsing the bar (`toggle()`, or the waffle button, or `NavTrigger`) removes it
+from layout **entirely**: height goes to 0 and the 56px is handed back to the page, not
+just visually hidden.
+
+## `sticky`
+
+Pass `sticky` only when your host's own document actually scrolls (e.g. a normal page
+layout) — in that case the bar should stick to the top of the viewport as the page
+scrolls beneath it. Leave it `false` (the default) for a host that is a fixed-height flex
+column whose document itself never scrolls (only an inner pane does) — sticky
+positioning there is dead weight.
+
+If your host is `sticky` and also has its own sticky header below the bar, that header's
+top offset has to account for the bar's height — **and that offset has to react to
+collapse**, or a viewer who collapses the bar is left with a 56px void at the top of the
+page where your header no longer starts. Read `collapsed` from `useNav()` and publish the
+live height (0 collapsed, 56px expanded) as a CSS variable your header's `top` reads,
+rather than hardcoding 56px once.
+
+## Degradation
+
+The bar is designed to never render blank and never block first paint:
+
+- **Endpoint outage or timeout** — the fetch has a hard 2.5s timeout; on any failure
+  (network error, timeout, non-2xx, unparseable body) the bar falls back to its
+  compiled-in config and keeps whatever it was already showing. No visible error, no
+  console noise by default.
+- **Unknown fields** — anything in the payload the renderer doesn't recognize is dropped
+  during normalization, never carried through and never thrown on.
+- **A higher `schema_version` than this renderer understands** — ignored the same way;
+  the renderer keeps working on the fields it does know.
+
+## The `schema_version` contract
+
+Changes to the wire payload are **additive within a version**: fields are only ever
+added, never removed or repurposed, for a given `schema_version`. A renderer must ignore
+fields it doesn't recognize rather than throw. That's what lets the suite's
+asynchronously-deployed satellite fleet run mixed renderer versions against one shared
+payload — an older `@artstorefronts/arthelper-nav` keeps working after a newer field ships on the
+config row. The version number itself is bumped only for a genuinely breaking change.

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+import type { NavConfigPayload } from './types.js';
+/**
+ * Coerces an arbitrary JSON body into the payload shape. Never throws: a missing,
+ * malformed or newer-versioned field falls back to the embedded default so the
+ * bar degrades instead of blanking.
+ *
+ * `null` is reserved for a body that could not be used, because that is the signal
+ * the caller reads as "keep showing what you have". An empty `apps` array is NOT such
+ * a body: it is what the endpoint serves when an operator has disabled every
+ * destination, and treating it as a failure discarded the operator's `theme` and
+ * `logo` edits along with it and reverted every host to the compiled-in fallback —
+ * the exact inverse of the instruction.
+ */
+declare function normalize(raw: unknown): NavConfigPayload | null;
+declare function cached(url: string): NavConfigPayload | undefined;
+/**
+ * Fetches the config with a hard timeout. Resolves to null on any failure —
+ * network, timeout, non-2xx, or an unparseable body — and the caller keeps
+ * whatever it is already showing.
+ */
+declare function fetchConfig(url: string, timeoutMs?: number): Promise<NavConfigPayload | null>;
+export { cached, fetchConfig, normalize };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAwB,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAsEvF;;;;;;;;;;;GAWG;AACH,iBAAS,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAuBxD;AAED,iBAAS,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEzD;AAED;;;;GAIG;AACH,iBAAe,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA0BxG;AAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC"}

package/dist/config.js

@@ -0,0 +1,134 @@
+import { FALLBACK_CONFIG } from './fallback.js';
+/** Short enough that a slow endpoint never delays the bar past first paint. */
+const TIMEOUT_MS = 2500;
+/** Last good payload per URL, so a remount paints the fresh config, not the fallback. */
+const memo = new Map();
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value, fallback) {
+    return typeof value === 'string' ? value : fallback;
+}
+function mode(value) {
+    return value === 'light' ? 'light' : 'dark';
+}
+function alignment(value) {
+    return value === 'centered' ? 'centered' : 'left';
+}
+function accent(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+// Unknown fields are dropped rather than carried, so a newer payload can never
+// reach the renderer as a shape it does not understand.
+function app(raw) {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    if (typeof raw.id !== 'string' || raw.id.length === 0) {
+        return null;
+    }
+    return {
+        id: raw.id,
+        label: text(raw.label, raw.id),
+        icon: text(raw.icon, ''),
+        href: text(raw.href, ''),
+        enabled: raw.enabled === true,
+    };
+}
+/**
+ * Parses the catalog, keeping an EMPTY-BUT-VALID list distinguishable from an
+ * unusable body. `[]` is a legitimate instruction — an operator who disabled every
+ * destination — and must be honoured; `null` means the body could not be read at all
+ * and the caller should keep whatever it is already showing.
+ *
+ * A non-empty array from which not one entry parsed counts as unusable, not as empty:
+ * the operator sent apps, we understood none of them, and rendering an empty bar off
+ * that is guessing.
+ */
+function apps(raw) {
+    if (!Array.isArray(raw)) {
+        return null;
+    }
+    const parsed = raw.reduce((memoized, entry) => {
+        const item = app(entry);
+        return item ? [...memoized, item] : memoized;
+    }, []);
+    if (raw.length > 0 && parsed.length === 0) {
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Coerces an arbitrary JSON body into the payload shape. Never throws: a missing,
+ * malformed or newer-versioned field falls back to the embedded default so the
+ * bar degrades instead of blanking.
+ *
+ * `null` is reserved for a body that could not be used, because that is the signal
+ * the caller reads as "keep showing what you have". An empty `apps` array is NOT such
+ * a body: it is what the endpoint serves when an operator has disabled every
+ * destination, and treating it as a failure discarded the operator's `theme` and
+ * `logo` edits along with it and reverted every host to the compiled-in fallback —
+ * the exact inverse of the instruction.
+ */
+function normalize(raw) {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    const theme = isRecord(raw.theme) ? raw.theme : {};
+    const logo = isRecord(raw.logo) ? raw.logo : {};
+    const parsed = apps(raw.apps);
+    if (!parsed) {
+        return null;
+    }
+    return {
+        schema_version: typeof raw.schema_version === 'number' ? raw.schema_version : FALLBACK_CONFIG.schema_version,
+        theme: {
+            mode: mode(theme.mode),
+            accent_color: accent(theme.accent_color),
+            alignment: alignment(theme.alignment),
+        },
+        logo: {
+            label: text(logo.label, FALLBACK_CONFIG.logo.label),
+            href: text(logo.href, FALLBACK_CONFIG.logo.href),
+        },
+        apps: parsed,
+    };
+}
+function cached(url) {
+    return memo.get(url);
+}
+/**
+ * Fetches the config with a hard timeout. Resolves to null on any failure —
+ * network, timeout, non-2xx, or an unparseable body — and the caller keeps
+ * whatever it is already showing.
+ */
+async function fetchConfig(url, timeoutMs = TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        // NEVER set credentials to 'include' or 'same-origin'. The endpoint is served
+        // through a bare cors() and returns the LITERAL `Access-Control-Allow-Origin: *`,
+        // not a reflected origin. `*` and credentials are mutually exclusive in the
+        // browser, so credentialed requests would have every cross-origin response
+        // rejected — stranding the bar on the embedded fallback forever, silently, with
+        // no console error and no visible failure. 'omit' is the only safe value.
+        const response = await fetch(url, { signal: controller.signal, credentials: 'omit' });
+        if (!response.ok) {
+            return null;
+        }
+        const next = normalize(await response.json());
+        if (!next) {
+            return null;
+        }
+        memo.set(url, next);
+        return next;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export { cached, fetchConfig, normalize };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,21 @@
+import type { NavConfigPayload, ResolvedNavApp } from './types.js';
+interface NavContextValue {
+    /** The config currently being rendered — the embedded fallback until the fetch lands. */
+    config: NavConfigPayload;
+    /** The catalog id of the app the host itself is. Always supplied by the host. */
+    activeAppId: string;
+    /** Enabled-and-has-destination entries, plus the host's own app. */
+    apps: ResolvedNavApp[];
+    /** The host's own entry, always present unless the catalog has never heard of it. */
+    activeApp: ResolvedNavApp | undefined;
+    collapsed: boolean;
+    setCollapsed: (collapsed: boolean) => void;
+    toggle: () => void;
+    /** Fires the host's onAppClick seam. Navigation itself is the anchor's own. */
+    activate: (app: ResolvedNavApp) => void;
+}
+declare const NavContext: import("react").Context<NavContextValue | null>;
+declare function useNav(): NavContextValue;
+export { NavContext, useNav };
+export type { NavContextValue };
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnE,UAAU,eAAe;IACvB,yFAAyF;IACzF,MAAM,EAAE,gBAAgB,CAAC;IACzB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,qFAAqF;IACrF,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;CACzC;AAED,QAAA,MAAM,UAAU,iDAA8C,CAAC;AAE/D,iBAAS,MAAM,IAAI,eAAe,CAMjC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/context.js

@@ -0,0 +1,12 @@
+'use client';
+import { createContext, useContext } from 'react';
+const NavContext = createContext(null);
+function useNav() {
+    const value = useContext(NavContext);
+    if (!value) {
+        throw new Error('useNav must be used inside <NavProvider>');
+    }
+    return value;
+}
+export { NavContext, useNav };
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAmBlD,MAAM,UAAU,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AAE/D,SAAS,MAAM;IACb,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC"}

package/dist/cookie.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The collapsed flag lives in a cookie, not localStorage, so a server-rendered
+ * host can read it and paint the first byte already collapsed — no expanded ->
+ * collapsed 56px jump after hydration.
+ *
+ * Per-origin by design: app.arthelper.ai and www.arthelper.com are different
+ * registrable domains and share no cookie scope. There is no cross-origin sync.
+ */
+declare const COLLAPSED_COOKIE = "arthelper_suite_nav_collapsed";
+declare function readCollapsed(): boolean | null;
+declare function writeCollapsed(collapsed: boolean): void;
+export { COLLAPSED_COOKIE, readCollapsed, writeCollapsed };
+//# sourceMappingURL=cookie.d.ts.map

package/dist/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../src/cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,QAAA,MAAM,gBAAgB,kCAAkC,CAAC;AAIzD,iBAAS,aAAa,IAAI,OAAO,GAAG,IAAI,CASvC;AAED,iBAAS,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAKhD;AAED,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

package/dist/cookie.js

@@ -0,0 +1,28 @@
+/**
+ * The collapsed flag lives in a cookie, not localStorage, so a server-rendered
+ * host can read it and paint the first byte already collapsed — no expanded ->
+ * collapsed 56px jump after hydration.
+ *
+ * Per-origin by design: app.arthelper.ai and www.arthelper.com are different
+ * registrable domains and share no cookie scope. There is no cross-origin sync.
+ */
+const COLLAPSED_COOKIE = 'arthelper_suite_nav_collapsed';
+const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
+function readCollapsed() {
+    if (typeof document === 'undefined') {
+        return null;
+    }
+    const match = document.cookie.split('; ').find((entry) => entry.startsWith(`${COLLAPSED_COOKIE}=`));
+    if (!match) {
+        return null;
+    }
+    return match.slice(COLLAPSED_COOKIE.length + 1) === 'true';
+}
+function writeCollapsed(collapsed) {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    document.cookie = `${COLLAPSED_COOKIE}=${collapsed}; path=/; max-age=${ONE_YEAR_SECONDS}; SameSite=Lax`;
+}
+export { COLLAPSED_COOKIE, readCollapsed, writeCollapsed };
+//# sourceMappingURL=cookie.js.map

package/dist/cookie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.js","sourceRoot":"","sources":["../src/cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAEzD,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;AAE5C,SAAS,aAAa;IACpB,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,gBAAgB,GAAG,CAAC,CAAC,CAAC;IACpG,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC;AAC7D,CAAC;AAED,SAAS,cAAc,CAAC,SAAkB;IACxC,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO;IACT,CAAC;IACD,QAAQ,CAAC,MAAM,GAAG,GAAG,gBAAgB,IAAI,SAAS,qBAAqB,gBAAgB,gBAAgB,CAAC;AAC1G,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

package/dist/fallback.d.ts

@@ -0,0 +1,13 @@
+import type { NavConfigPayload } from './types.js';
+/**
+ * The static config compiled into the package. Used whenever the fetch fails,
+ * times out, or has not resolved yet, so the bar reserves its final 56px from
+ * first paint and never renders blank.
+ *
+ * It carries ONLY entries that have a destination. Changing it requires a
+ * package release, which is exactly why it holds the stable first-party
+ * destination and never the satellites — those arrive over the wire.
+ */
+declare const FALLBACK_CONFIG: NavConfigPayload;
+export { FALLBACK_CONFIG };
+//# sourceMappingURL=fallback.d.ts.map

package/dist/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;GAQG;AACH,QAAA,MAAM,eAAe,EAAE,gBAKtB,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/fallback.js

@@ -0,0 +1,17 @@
+/**
+ * The static config compiled into the package. Used whenever the fetch fails,
+ * times out, or has not resolved yet, so the bar reserves its final 56px from
+ * first paint and never renders blank.
+ *
+ * It carries ONLY entries that have a destination. Changing it requires a
+ * package release, which is exactly why it holds the stable first-party
+ * destination and never the satellites — those arrive over the wire.
+ */
+const FALLBACK_CONFIG = {
+    schema_version: 1,
+    theme: { mode: 'dark', accent_color: '#2aa34f', alignment: 'left' },
+    logo: { label: 'ArtHelper', href: 'https://www.arthelper.com' },
+    apps: [{ id: 'home', label: 'Home', icon: 'house', href: 'https://www.arthelper.com', enabled: true }],
+};
+export { FALLBACK_CONFIG };
+//# sourceMappingURL=fallback.js.map

package/dist/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAqB;IACxC,cAAc,EAAE,CAAC;IACjB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE;IACnE,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,2BAA2B,EAAE;IAC/D,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;CACvG,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/icons.d.ts

@@ -0,0 +1,14 @@
+interface NavIconProps {
+    name: string;
+    size?: number;
+    className?: string;
+}
+/** An unrecognised icon name degrades to a neutral circle rather than an empty chip. */
+declare function NavIcon({ name, size, className }: NavIconProps): import("react/jsx-runtime").JSX.Element;
+/** The waffle: hide control in the bar, restore affordance in NavTrigger. */
+declare function WaffleIcon({ size, className }: {
+    size?: number;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export { NavIcon, WaffleIcon };
+//# sourceMappingURL=icons.d.ts.map

package/dist/icons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../src/icons.tsx"],"names":[],"mappings":"AA+BA,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wFAAwF;AACxF,iBAAS,OAAO,CAAC,EAAE,IAAI,EAAE,IAAS,EAAE,SAA0B,EAAE,EAAE,YAAY,2CAG7E;AAED,6EAA6E;AAC7E,iBAAS,UAAU,CAAC,EAAE,IAAS,EAAE,SAA0B,EAAE,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,2CAEnG;AAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/icons.js

@@ -0,0 +1,29 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BookOpen, Circle, Frame, House, LayoutGrid, Megaphone, Sparkles, Star, Sunrise, } from 'lucide-react';
+/**
+ * The catalog's icon names, keyed exactly as the seed spells them. lucide emits
+ * inline stroke SVGs with viewBox="0 0 24 24", stroke-width 2 and round caps,
+ * which is the icon contract verbatim — nothing here draws its own paths.
+ */
+const ICONS = {
+    house: House,
+    sunrise: Sunrise,
+    star: Star,
+    sparkles: Sparkles,
+    frame: Frame,
+    'book-open': BookOpen,
+    megaphone: Megaphone,
+    'layout-grid': LayoutGrid,
+};
+/** An unrecognised icon name degrades to a neutral circle rather than an empty chip. */
+function NavIcon({ name, size = 16, className = 'ahsuite-icon' }) {
+    const Icon = ICONS[name] ?? Circle;
+    return _jsx(Icon, { "aria-hidden": "true", className: className, width: size, height: size, strokeWidth: 2 });
+}
+/** The waffle: hide control in the bar, restore affordance in NavTrigger. */
+function WaffleIcon({ size = 24, className = 'ahsuite-icon' }) {
+    return _jsx(LayoutGrid, { "aria-hidden": "true", className: className, width: size, height: size, strokeWidth: 2 });
+}
+export { NavIcon, WaffleIcon };
+//# sourceMappingURL=icons.js.map

package/dist/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.js","sourceRoot":"","sources":["../src/icons.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EACL,QAAQ,EACR,MAAM,EACN,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,OAAO,GAER,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,MAAM,KAAK,GAA+B;IACxC,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,IAAI;IACV,QAAQ,EAAE,QAAQ;IAClB,KAAK,EAAE,KAAK;IACZ,WAAW,EAAE,QAAQ;IACrB,SAAS,EAAE,SAAS;IACpB,aAAa,EAAE,UAAU;CAC1B,CAAC;AAQF,wFAAwF;AACxF,SAAS,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,GAAG,cAAc,EAAgB;IAC5E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IACnC,OAAO,KAAC,IAAI,mBAAa,MAAM,EAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,GAAI,CAAC;AACtG,CAAC;AAED,6EAA6E;AAC7E,SAAS,UAAU,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,GAAG,cAAc,EAAyC;IAClG,OAAO,KAAC,UAAU,mBAAa,MAAM,EAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,GAAI,CAAC;AAC5G,CAAC;AAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}