@ship-it-ui/next 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ship-it-ops
+
+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/dist/index.cjs

@@ -0,0 +1,118 @@
+'use client';
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  THEME_COOKIE_MAX_AGE: () => THEME_COOKIE_MAX_AGE,
+  THEME_COOKIE_NAME: () => THEME_COOKIE_NAME,
+  ThemeBootstrap: () => ThemeBootstrap,
+  ThemeToggle: () => ThemeToggle,
+  buildBootstrapScript: () => buildBootstrapScript,
+  getThemeFromCookies: () => getThemeFromCookies,
+  parseThemeCookie: () => parseThemeCookie,
+  readThemeCookie: () => readThemeCookie,
+  writeThemeCookie: () => writeThemeCookie
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/theme-cookie.ts
+var THEME_COOKIE_NAME = "ship-it-theme";
+var THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+function parseThemeCookie(value) {
+  if (value === "dark" || value === "light") return value;
+  return void 0;
+}
+function getThemeFromCookies(cookieStore) {
+  return parseThemeCookie(cookieStore.get(THEME_COOKIE_NAME)?.value);
+}
+function writeThemeCookie(theme) {
+  if (typeof document === "undefined") return;
+  document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; samesite=lax`;
+}
+function readThemeCookie() {
+  if (typeof document === "undefined") return void 0;
+  const match = document.cookie.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${THEME_COOKIE_NAME}=`));
+  if (!match) return void 0;
+  return parseThemeCookie(match.slice(THEME_COOKIE_NAME.length + 1));
+}
+
+// src/ThemeBootstrap.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function ThemeBootstrap() {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "script",
+    {
+      dangerouslySetInnerHTML: { __html: buildBootstrapScript() }
+    }
+  );
+}
+ThemeBootstrap.displayName = "ThemeBootstrap";
+function buildBootstrapScript() {
+  return `(function(){try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE_NAME}=(dark|light)/);var t=m&&m[1];if(t==='light'){document.documentElement.setAttribute('data-theme','light');}else if(t==='dark'){document.documentElement.removeAttribute('data-theme');}}catch(_){}})();`;
+}
+
+// src/ThemeToggle.tsx
+var import_ui = require("@ship-it-ui/ui");
+var import_react = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function ThemeToggle({
+  label,
+  "aria-label": ariaLabel,
+  onThemeChange
+}) {
+  const { theme, setTheme } = (0, import_ui.useTheme)();
+  const handleChange = (0, import_react.useCallback)(
+    (next) => {
+      const target = next ? "light" : "dark";
+      setTheme(target);
+      writeThemeCookie(target);
+      onThemeChange?.(target);
+    },
+    [setTheme, onThemeChange]
+  );
+  const accessibleName = ariaLabel ?? (typeof label === "string" ? label : "Toggle theme");
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { className: "inline-flex items-center gap-2", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      import_ui.Switch,
+      {
+        checked: theme === "light",
+        onCheckedChange: handleChange,
+        "aria-label": accessibleName
+      }
+    ),
+    label && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "text-text-muted text-[12px]", children: label })
+  ] });
+}
+ThemeToggle.displayName = "ThemeToggle";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  THEME_COOKIE_MAX_AGE,
+  THEME_COOKIE_NAME,
+  ThemeBootstrap,
+  ThemeToggle,
+  buildBootstrapScript,
+  getThemeFromCookies,
+  parseThemeCookie,
+  readThemeCookie,
+  writeThemeCookie
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/theme-cookie.ts","../src/ThemeBootstrap.tsx","../src/ThemeToggle.tsx"],"sourcesContent":["/**\n * @ship-it-ui/next — Next.js (App Router) helpers for the Ship-It design\n * system. SSR-safe theme persistence with FOUC prevention, cookie helpers,\n * and a token-styled theme toggle that reuses `useTheme` from\n * `@ship-it-ui/ui`.\n */\n\nexport { ThemeBootstrap, buildBootstrapScript } from './ThemeBootstrap';\nexport { ThemeToggle, type ThemeToggleProps } from './ThemeToggle';\nexport {\n  getThemeFromCookies,\n  parseThemeCookie,\n  readThemeCookie,\n  writeThemeCookie,\n  THEME_COOKIE_NAME,\n  THEME_COOKIE_MAX_AGE,\n  type CookieGetter,\n} from './theme-cookie';\n","/**\n * Theme cookie helpers shared between the server-side `getThemeFromCookies`\n * and the client-side `ThemeBootstrap` / `ThemeToggle`. The cookie value is\n * the literal string `'dark'` or `'light'`; anything else falls back to\n * undefined and the consumer's default (typically dark) applies.\n */\n\nimport type { Theme } from '@ship-it-ui/ui';\n\nexport const THEME_COOKIE_NAME = 'ship-it-theme';\n\n/** One year. The cookie is non-sensitive, so a long lifetime is fine. */\nexport const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;\n\n/** Parse a raw cookie string value into a `Theme` or `undefined`. */\nexport function parseThemeCookie(value: string | null | undefined): Theme | undefined {\n  if (value === 'dark' || value === 'light') return value;\n  return undefined;\n}\n\n/**\n * Server helper for the App Router `cookies()` API. Pass `cookies()` (or any\n * object with `.get(name)` that returns `{ value: string }`) and receive the\n * stored theme.\n *\n * ```ts\n * import { cookies } from 'next/headers';\n * const theme = getThemeFromCookies(await cookies());\n * ```\n */\nexport interface CookieGetter {\n  get(name: string): { value: string } | undefined;\n}\n\nexport function getThemeFromCookies(cookieStore: CookieGetter): Theme | undefined {\n  return parseThemeCookie(cookieStore.get(THEME_COOKIE_NAME)?.value);\n}\n\n/**\n * Client-side cookie writer. Sets a path-`/` cookie with a year-long TTL and\n * `SameSite=Lax`, which is safe for theme preferences (non-sensitive, not\n * cross-site). No-op on the server.\n */\nexport function writeThemeCookie(theme: Theme): void {\n  if (typeof document === 'undefined') return;\n  document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; samesite=lax`;\n}\n\n/** Read the theme cookie from `document.cookie`. No-op on the server. */\nexport function readThemeCookie(): Theme | undefined {\n  if (typeof document === 'undefined') return undefined;\n  const match = document.cookie\n    .split(';')\n    .map((part) => part.trim())\n    .find((part) => part.startsWith(`${THEME_COOKIE_NAME}=`));\n  if (!match) return undefined;\n  return parseThemeCookie(match.slice(THEME_COOKIE_NAME.length + 1));\n}\n","import { THEME_COOKIE_NAME } from './theme-cookie';\n\n/**\n * ThemeBootstrap — render inside the `<head>` of your App Router root layout.\n * Injects a synchronous inline script that reads the theme cookie and sets\n * `<html data-theme>` *before* the first paint, which kills the dark→light\n * flash of unstyled content for users on the light theme.\n *\n * Pair with `getThemeFromCookies(cookies())` to seed the server-rendered\n * `data-theme` on `<html>` for the very first frame.\n *\n * ```tsx\n * import { cookies } from 'next/headers';\n * import { ThemeBootstrap, getThemeFromCookies } from '@ship-it-ui/next';\n *\n * export default function RootLayout({ children }) {\n *   const theme = getThemeFromCookies(cookies());\n *   return (\n *     <html lang=\"en\" data-theme={theme}>\n *       <head><ThemeBootstrap /></head>\n *       <body>{children}</body>\n *     </html>\n *   );\n * }\n * ```\n */\nexport function ThemeBootstrap(): JSX.Element {\n  return (\n    <script\n      // The script must be synchronous and inline — there's no place else to\n      // intercept the document before paint. Build the cookie name into the\n      // script so consumers don't have to mirror it.\n      dangerouslySetInnerHTML={{ __html: buildBootstrapScript() }}\n    />\n  );\n}\n\nThemeBootstrap.displayName = 'ThemeBootstrap';\n\n/**\n * Returns the inline-script body that `ThemeBootstrap` injects. Exported so\n * tests (and consumers with a custom layout) can inspect or reuse the source.\n */\nexport function buildBootstrapScript(): string {\n  return `(function(){try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE_NAME}=(dark|light)/);var t=m&&m[1];if(t==='light'){document.documentElement.setAttribute('data-theme','light');}else if(t==='dark'){document.documentElement.removeAttribute('data-theme');}}catch(_){}})();`;\n}\n","'use client';\n\nimport { Switch, useTheme, type Theme } from '@ship-it-ui/ui';\nimport { useCallback, type ReactNode } from 'react';\n\nimport { writeThemeCookie } from './theme-cookie';\n\n/**\n * ThemeToggle — token-styled `Switch` bound to the active theme. Reuses the\n * shared `useTheme` hook from `@ship-it-ui/ui` for in-page state and writes\n * a year-long cookie so the next request's `ThemeBootstrap` can render the\n * correct theme synchronously.\n *\n * Pass `label` for a visible labelled control, or supply your own wrapper if\n * you want a chip / menu-item layout.\n */\n\nexport interface ThemeToggleProps {\n  /** Visible label rendered next to the switch. */\n  label?: ReactNode;\n  /** Override the accessible name. Falls back to `label` when it is a string. */\n  'aria-label'?: string;\n  /** Fires after the theme has been persisted. Useful for analytics. */\n  onThemeChange?: (next: Theme) => void;\n}\n\nexport function ThemeToggle({\n  label,\n  'aria-label': ariaLabel,\n  onThemeChange,\n}: ThemeToggleProps): JSX.Element {\n  const { theme, setTheme } = useTheme();\n\n  const handleChange = useCallback(\n    (next: boolean) => {\n      const target: Theme = next ? 'light' : 'dark';\n      setTheme(target);\n      writeThemeCookie(target);\n      onThemeChange?.(target);\n    },\n    [setTheme, onThemeChange],\n  );\n\n  const accessibleName = ariaLabel ?? (typeof label === 'string' ? label : 'Toggle theme');\n\n  return (\n    <span className=\"inline-flex items-center gap-2\">\n      <Switch\n        checked={theme === 'light'}\n        onCheckedChange={handleChange}\n        aria-label={accessibleName}\n      />\n      {label && <span className=\"text-text-muted text-[12px]\">{label}</span>}\n    </span>\n  );\n}\n\nThemeToggle.displayName = 'ThemeToggle';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,oBAAoB;AAG1B,IAAM,uBAAuB,KAAK,KAAK,KAAK;AAG5C,SAAS,iBAAiB,OAAqD;AACpF,MAAI,UAAU,UAAU,UAAU,QAAS,QAAO;AAClD,SAAO;AACT;AAgBO,SAAS,oBAAoB,aAA8C;AAChF,SAAO,iBAAiB,YAAY,IAAI,iBAAiB,GAAG,KAAK;AACnE;AAOO,SAAS,iBAAiB,OAAoB;AACnD,MAAI,OAAO,aAAa,YAAa;AACrC,WAAS,SAAS,GAAG,iBAAiB,IAAI,KAAK,qBAAqB,oBAAoB;AAC1F;AAGO,SAAS,kBAAqC;AACnD,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,QAAQ,SAAS,OACpB,MAAM,GAAG,EACT,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,EACzB,KAAK,CAAC,SAAS,KAAK,WAAW,GAAG,iBAAiB,GAAG,CAAC;AAC1D,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,iBAAiB,MAAM,MAAM,kBAAkB,SAAS,CAAC,CAAC;AACnE;;;AC7BI;AAFG,SAAS,iBAA8B;AAC5C,SACE;AAAA,IAAC;AAAA;AAAA,MAIC,yBAAyB,EAAE,QAAQ,qBAAqB,EAAE;AAAA;AAAA,EAC5D;AAEJ;AAEA,eAAe,cAAc;AAMtB,SAAS,uBAA+B;AAC7C,SAAO,wDAAwD,iBAAiB;AAClF;;;AC3CA,gBAA6C;AAC7C,mBAA4C;AA2CxC,IAAAA,sBAAA;AApBG,SAAS,YAAY;AAAA,EAC1B;AAAA,EACA,cAAc;AAAA,EACd;AACF,GAAkC;AAChC,QAAM,EAAE,OAAO,SAAS,QAAI,oBAAS;AAErC,QAAM,mBAAe;AAAA,IACnB,CAAC,SAAkB;AACjB,YAAM,SAAgB,OAAO,UAAU;AACvC,eAAS,MAAM;AACf,uBAAiB,MAAM;AACvB,sBAAgB,MAAM;AAAA,IACxB;AAAA,IACA,CAAC,UAAU,aAAa;AAAA,EAC1B;AAEA,QAAM,iBAAiB,cAAc,OAAO,UAAU,WAAW,QAAQ;AAEzE,SACE,8CAAC,UAAK,WAAU,kCACd;AAAA;AAAA,MAAC;AAAA;AAAA,QACC,SAAS,UAAU;AAAA,QACnB,iBAAiB;AAAA,QACjB,cAAY;AAAA;AAAA,IACd;AAAA,IACC,SAAS,6CAAC,UAAK,WAAU,+BAA+B,iBAAM;AAAA,KACjE;AAEJ;AAEA,YAAY,cAAc;","names":["import_jsx_runtime"]}

package/dist/index.d.cts

@@ -0,0 +1,97 @@
+import { Theme } from '@ship-it-ui/ui';
+import { ReactNode } from 'react';
+
+/**
+ * ThemeBootstrap — render inside the `<head>` of your App Router root layout.
+ * Injects a synchronous inline script that reads the theme cookie and sets
+ * `<html data-theme>` *before* the first paint, which kills the dark→light
+ * flash of unstyled content for users on the light theme.
+ *
+ * Pair with `getThemeFromCookies(cookies())` to seed the server-rendered
+ * `data-theme` on `<html>` for the very first frame.
+ *
+ * ```tsx
+ * import { cookies } from 'next/headers';
+ * import { ThemeBootstrap, getThemeFromCookies } from '@ship-it-ui/next';
+ *
+ * export default function RootLayout({ children }) {
+ *   const theme = getThemeFromCookies(cookies());
+ *   return (
+ *     <html lang="en" data-theme={theme}>
+ *       <head><ThemeBootstrap /></head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function ThemeBootstrap(): JSX.Element;
+declare namespace ThemeBootstrap {
+    var displayName: string;
+}
+/**
+ * Returns the inline-script body that `ThemeBootstrap` injects. Exported so
+ * tests (and consumers with a custom layout) can inspect or reuse the source.
+ */
+declare function buildBootstrapScript(): string;
+
+/**
+ * ThemeToggle — token-styled `Switch` bound to the active theme. Reuses the
+ * shared `useTheme` hook from `@ship-it-ui/ui` for in-page state and writes
+ * a year-long cookie so the next request's `ThemeBootstrap` can render the
+ * correct theme synchronously.
+ *
+ * Pass `label` for a visible labelled control, or supply your own wrapper if
+ * you want a chip / menu-item layout.
+ */
+interface ThemeToggleProps {
+    /** Visible label rendered next to the switch. */
+    label?: ReactNode;
+    /** Override the accessible name. Falls back to `label` when it is a string. */
+    'aria-label'?: string;
+    /** Fires after the theme has been persisted. Useful for analytics. */
+    onThemeChange?: (next: Theme) => void;
+}
+declare function ThemeToggle({ label, 'aria-label': ariaLabel, onThemeChange, }: ThemeToggleProps): JSX.Element;
+declare namespace ThemeToggle {
+    var displayName: string;
+}
+
+/**
+ * Theme cookie helpers shared between the server-side `getThemeFromCookies`
+ * and the client-side `ThemeBootstrap` / `ThemeToggle`. The cookie value is
+ * the literal string `'dark'` or `'light'`; anything else falls back to
+ * undefined and the consumer's default (typically dark) applies.
+ */
+
+declare const THEME_COOKIE_NAME = "ship-it-theme";
+/** One year. The cookie is non-sensitive, so a long lifetime is fine. */
+declare const THEME_COOKIE_MAX_AGE: number;
+/** Parse a raw cookie string value into a `Theme` or `undefined`. */
+declare function parseThemeCookie(value: string | null | undefined): Theme | undefined;
+/**
+ * Server helper for the App Router `cookies()` API. Pass `cookies()` (or any
+ * object with `.get(name)` that returns `{ value: string }`) and receive the
+ * stored theme.
+ *
+ * ```ts
+ * import { cookies } from 'next/headers';
+ * const theme = getThemeFromCookies(await cookies());
+ * ```
+ */
+interface CookieGetter {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}
+declare function getThemeFromCookies(cookieStore: CookieGetter): Theme | undefined;
+/**
+ * Client-side cookie writer. Sets a path-`/` cookie with a year-long TTL and
+ * `SameSite=Lax`, which is safe for theme preferences (non-sensitive, not
+ * cross-site). No-op on the server.
+ */
+declare function writeThemeCookie(theme: Theme): void;
+/** Read the theme cookie from `document.cookie`. No-op on the server. */
+declare function readThemeCookie(): Theme | undefined;
+
+export { type CookieGetter, THEME_COOKIE_MAX_AGE, THEME_COOKIE_NAME, ThemeBootstrap, ThemeToggle, type ThemeToggleProps, buildBootstrapScript, getThemeFromCookies, parseThemeCookie, readThemeCookie, writeThemeCookie };

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { Theme } from '@ship-it-ui/ui';
+import { ReactNode } from 'react';
+
+/**
+ * ThemeBootstrap — render inside the `<head>` of your App Router root layout.
+ * Injects a synchronous inline script that reads the theme cookie and sets
+ * `<html data-theme>` *before* the first paint, which kills the dark→light
+ * flash of unstyled content for users on the light theme.
+ *
+ * Pair with `getThemeFromCookies(cookies())` to seed the server-rendered
+ * `data-theme` on `<html>` for the very first frame.
+ *
+ * ```tsx
+ * import { cookies } from 'next/headers';
+ * import { ThemeBootstrap, getThemeFromCookies } from '@ship-it-ui/next';
+ *
+ * export default function RootLayout({ children }) {
+ *   const theme = getThemeFromCookies(cookies());
+ *   return (
+ *     <html lang="en" data-theme={theme}>
+ *       <head><ThemeBootstrap /></head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function ThemeBootstrap(): JSX.Element;
+declare namespace ThemeBootstrap {
+    var displayName: string;
+}
+/**
+ * Returns the inline-script body that `ThemeBootstrap` injects. Exported so
+ * tests (and consumers with a custom layout) can inspect or reuse the source.
+ */
+declare function buildBootstrapScript(): string;
+
+/**
+ * ThemeToggle — token-styled `Switch` bound to the active theme. Reuses the
+ * shared `useTheme` hook from `@ship-it-ui/ui` for in-page state and writes
+ * a year-long cookie so the next request's `ThemeBootstrap` can render the
+ * correct theme synchronously.
+ *
+ * Pass `label` for a visible labelled control, or supply your own wrapper if
+ * you want a chip / menu-item layout.
+ */
+interface ThemeToggleProps {
+    /** Visible label rendered next to the switch. */
+    label?: ReactNode;
+    /** Override the accessible name. Falls back to `label` when it is a string. */
+    'aria-label'?: string;
+    /** Fires after the theme has been persisted. Useful for analytics. */
+    onThemeChange?: (next: Theme) => void;
+}
+declare function ThemeToggle({ label, 'aria-label': ariaLabel, onThemeChange, }: ThemeToggleProps): JSX.Element;
+declare namespace ThemeToggle {
+    var displayName: string;
+}
+
+/**
+ * Theme cookie helpers shared between the server-side `getThemeFromCookies`
+ * and the client-side `ThemeBootstrap` / `ThemeToggle`. The cookie value is
+ * the literal string `'dark'` or `'light'`; anything else falls back to
+ * undefined and the consumer's default (typically dark) applies.
+ */
+
+declare const THEME_COOKIE_NAME = "ship-it-theme";
+/** One year. The cookie is non-sensitive, so a long lifetime is fine. */
+declare const THEME_COOKIE_MAX_AGE: number;
+/** Parse a raw cookie string value into a `Theme` or `undefined`. */
+declare function parseThemeCookie(value: string | null | undefined): Theme | undefined;
+/**
+ * Server helper for the App Router `cookies()` API. Pass `cookies()` (or any
+ * object with `.get(name)` that returns `{ value: string }`) and receive the
+ * stored theme.
+ *
+ * ```ts
+ * import { cookies } from 'next/headers';
+ * const theme = getThemeFromCookies(await cookies());
+ * ```
+ */
+interface CookieGetter {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}
+declare function getThemeFromCookies(cookieStore: CookieGetter): Theme | undefined;
+/**
+ * Client-side cookie writer. Sets a path-`/` cookie with a year-long TTL and
+ * `SameSite=Lax`, which is safe for theme preferences (non-sensitive, not
+ * cross-site). No-op on the server.
+ */
+declare function writeThemeCookie(theme: Theme): void;
+/** Read the theme cookie from `document.cookie`. No-op on the server. */
+declare function readThemeCookie(): Theme | undefined;
+
+export { type CookieGetter, THEME_COOKIE_MAX_AGE, THEME_COOKIE_NAME, ThemeBootstrap, ThemeToggle, type ThemeToggleProps, buildBootstrapScript, getThemeFromCookies, parseThemeCookie, readThemeCookie, writeThemeCookie };

package/dist/index.js

@@ -0,0 +1,83 @@
+'use client';
+
+// src/theme-cookie.ts
+var THEME_COOKIE_NAME = "ship-it-theme";
+var THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+function parseThemeCookie(value) {
+  if (value === "dark" || value === "light") return value;
+  return void 0;
+}
+function getThemeFromCookies(cookieStore) {
+  return parseThemeCookie(cookieStore.get(THEME_COOKIE_NAME)?.value);
+}
+function writeThemeCookie(theme) {
+  if (typeof document === "undefined") return;
+  document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; samesite=lax`;
+}
+function readThemeCookie() {
+  if (typeof document === "undefined") return void 0;
+  const match = document.cookie.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${THEME_COOKIE_NAME}=`));
+  if (!match) return void 0;
+  return parseThemeCookie(match.slice(THEME_COOKIE_NAME.length + 1));
+}
+
+// src/ThemeBootstrap.tsx
+import { jsx } from "react/jsx-runtime";
+function ThemeBootstrap() {
+  return /* @__PURE__ */ jsx(
+    "script",
+    {
+      dangerouslySetInnerHTML: { __html: buildBootstrapScript() }
+    }
+  );
+}
+ThemeBootstrap.displayName = "ThemeBootstrap";
+function buildBootstrapScript() {
+  return `(function(){try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE_NAME}=(dark|light)/);var t=m&&m[1];if(t==='light'){document.documentElement.setAttribute('data-theme','light');}else if(t==='dark'){document.documentElement.removeAttribute('data-theme');}}catch(_){}})();`;
+}
+
+// src/ThemeToggle.tsx
+import { Switch, useTheme } from "@ship-it-ui/ui";
+import { useCallback } from "react";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function ThemeToggle({
+  label,
+  "aria-label": ariaLabel,
+  onThemeChange
+}) {
+  const { theme, setTheme } = useTheme();
+  const handleChange = useCallback(
+    (next) => {
+      const target = next ? "light" : "dark";
+      setTheme(target);
+      writeThemeCookie(target);
+      onThemeChange?.(target);
+    },
+    [setTheme, onThemeChange]
+  );
+  const accessibleName = ariaLabel ?? (typeof label === "string" ? label : "Toggle theme");
+  return /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-2", children: [
+    /* @__PURE__ */ jsx2(
+      Switch,
+      {
+        checked: theme === "light",
+        onCheckedChange: handleChange,
+        "aria-label": accessibleName
+      }
+    ),
+    label && /* @__PURE__ */ jsx2("span", { className: "text-text-muted text-[12px]", children: label })
+  ] });
+}
+ThemeToggle.displayName = "ThemeToggle";
+export {
+  THEME_COOKIE_MAX_AGE,
+  THEME_COOKIE_NAME,
+  ThemeBootstrap,
+  ThemeToggle,
+  buildBootstrapScript,
+  getThemeFromCookies,
+  parseThemeCookie,
+  readThemeCookie,
+  writeThemeCookie
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme-cookie.ts","../src/ThemeBootstrap.tsx","../src/ThemeToggle.tsx"],"sourcesContent":["/**\n * Theme cookie helpers shared between the server-side `getThemeFromCookies`\n * and the client-side `ThemeBootstrap` / `ThemeToggle`. The cookie value is\n * the literal string `'dark'` or `'light'`; anything else falls back to\n * undefined and the consumer's default (typically dark) applies.\n */\n\nimport type { Theme } from '@ship-it-ui/ui';\n\nexport const THEME_COOKIE_NAME = 'ship-it-theme';\n\n/** One year. The cookie is non-sensitive, so a long lifetime is fine. */\nexport const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;\n\n/** Parse a raw cookie string value into a `Theme` or `undefined`. */\nexport function parseThemeCookie(value: string | null | undefined): Theme | undefined {\n  if (value === 'dark' || value === 'light') return value;\n  return undefined;\n}\n\n/**\n * Server helper for the App Router `cookies()` API. Pass `cookies()` (or any\n * object with `.get(name)` that returns `{ value: string }`) and receive the\n * stored theme.\n *\n * ```ts\n * import { cookies } from 'next/headers';\n * const theme = getThemeFromCookies(await cookies());\n * ```\n */\nexport interface CookieGetter {\n  get(name: string): { value: string } | undefined;\n}\n\nexport function getThemeFromCookies(cookieStore: CookieGetter): Theme | undefined {\n  return parseThemeCookie(cookieStore.get(THEME_COOKIE_NAME)?.value);\n}\n\n/**\n * Client-side cookie writer. Sets a path-`/` cookie with a year-long TTL and\n * `SameSite=Lax`, which is safe for theme preferences (non-sensitive, not\n * cross-site). No-op on the server.\n */\nexport function writeThemeCookie(theme: Theme): void {\n  if (typeof document === 'undefined') return;\n  document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; samesite=lax`;\n}\n\n/** Read the theme cookie from `document.cookie`. No-op on the server. */\nexport function readThemeCookie(): Theme | undefined {\n  if (typeof document === 'undefined') return undefined;\n  const match = document.cookie\n    .split(';')\n    .map((part) => part.trim())\n    .find((part) => part.startsWith(`${THEME_COOKIE_NAME}=`));\n  if (!match) return undefined;\n  return parseThemeCookie(match.slice(THEME_COOKIE_NAME.length + 1));\n}\n","import { THEME_COOKIE_NAME } from './theme-cookie';\n\n/**\n * ThemeBootstrap — render inside the `<head>` of your App Router root layout.\n * Injects a synchronous inline script that reads the theme cookie and sets\n * `<html data-theme>` *before* the first paint, which kills the dark→light\n * flash of unstyled content for users on the light theme.\n *\n * Pair with `getThemeFromCookies(cookies())` to seed the server-rendered\n * `data-theme` on `<html>` for the very first frame.\n *\n * ```tsx\n * import { cookies } from 'next/headers';\n * import { ThemeBootstrap, getThemeFromCookies } from '@ship-it-ui/next';\n *\n * export default function RootLayout({ children }) {\n *   const theme = getThemeFromCookies(cookies());\n *   return (\n *     <html lang=\"en\" data-theme={theme}>\n *       <head><ThemeBootstrap /></head>\n *       <body>{children}</body>\n *     </html>\n *   );\n * }\n * ```\n */\nexport function ThemeBootstrap(): JSX.Element {\n  return (\n    <script\n      // The script must be synchronous and inline — there's no place else to\n      // intercept the document before paint. Build the cookie name into the\n      // script so consumers don't have to mirror it.\n      dangerouslySetInnerHTML={{ __html: buildBootstrapScript() }}\n    />\n  );\n}\n\nThemeBootstrap.displayName = 'ThemeBootstrap';\n\n/**\n * Returns the inline-script body that `ThemeBootstrap` injects. Exported so\n * tests (and consumers with a custom layout) can inspect or reuse the source.\n */\nexport function buildBootstrapScript(): string {\n  return `(function(){try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE_NAME}=(dark|light)/);var t=m&&m[1];if(t==='light'){document.documentElement.setAttribute('data-theme','light');}else if(t==='dark'){document.documentElement.removeAttribute('data-theme');}}catch(_){}})();`;\n}\n","'use client';\n\nimport { Switch, useTheme, type Theme } from '@ship-it-ui/ui';\nimport { useCallback, type ReactNode } from 'react';\n\nimport { writeThemeCookie } from './theme-cookie';\n\n/**\n * ThemeToggle — token-styled `Switch` bound to the active theme. Reuses the\n * shared `useTheme` hook from `@ship-it-ui/ui` for in-page state and writes\n * a year-long cookie so the next request's `ThemeBootstrap` can render the\n * correct theme synchronously.\n *\n * Pass `label` for a visible labelled control, or supply your own wrapper if\n * you want a chip / menu-item layout.\n */\n\nexport interface ThemeToggleProps {\n  /** Visible label rendered next to the switch. */\n  label?: ReactNode;\n  /** Override the accessible name. Falls back to `label` when it is a string. */\n  'aria-label'?: string;\n  /** Fires after the theme has been persisted. Useful for analytics. */\n  onThemeChange?: (next: Theme) => void;\n}\n\nexport function ThemeToggle({\n  label,\n  'aria-label': ariaLabel,\n  onThemeChange,\n}: ThemeToggleProps): JSX.Element {\n  const { theme, setTheme } = useTheme();\n\n  const handleChange = useCallback(\n    (next: boolean) => {\n      const target: Theme = next ? 'light' : 'dark';\n      setTheme(target);\n      writeThemeCookie(target);\n      onThemeChange?.(target);\n    },\n    [setTheme, onThemeChange],\n  );\n\n  const accessibleName = ariaLabel ?? (typeof label === 'string' ? label : 'Toggle theme');\n\n  return (\n    <span className=\"inline-flex items-center gap-2\">\n      <Switch\n        checked={theme === 'light'}\n        onCheckedChange={handleChange}\n        aria-label={accessibleName}\n      />\n      {label && <span className=\"text-text-muted text-[12px]\">{label}</span>}\n    </span>\n  );\n}\n\nThemeToggle.displayName = 'ThemeToggle';\n"],"mappings":";AASO,IAAM,oBAAoB;AAG1B,IAAM,uBAAuB,KAAK,KAAK,KAAK;AAG5C,SAAS,iBAAiB,OAAqD;AACpF,MAAI,UAAU,UAAU,UAAU,QAAS,QAAO;AAClD,SAAO;AACT;AAgBO,SAAS,oBAAoB,aAA8C;AAChF,SAAO,iBAAiB,YAAY,IAAI,iBAAiB,GAAG,KAAK;AACnE;AAOO,SAAS,iBAAiB,OAAoB;AACnD,MAAI,OAAO,aAAa,YAAa;AACrC,WAAS,SAAS,GAAG,iBAAiB,IAAI,KAAK,qBAAqB,oBAAoB;AAC1F;AAGO,SAAS,kBAAqC;AACnD,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,QAAQ,SAAS,OACpB,MAAM,GAAG,EACT,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,EACzB,KAAK,CAAC,SAAS,KAAK,WAAW,GAAG,iBAAiB,GAAG,CAAC;AAC1D,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,iBAAiB,MAAM,MAAM,kBAAkB,SAAS,CAAC,CAAC;AACnE;;;AC7BI;AAFG,SAAS,iBAA8B;AAC5C,SACE;AAAA,IAAC;AAAA;AAAA,MAIC,yBAAyB,EAAE,QAAQ,qBAAqB,EAAE;AAAA;AAAA,EAC5D;AAEJ;AAEA,eAAe,cAAc;AAMtB,SAAS,uBAA+B;AAC7C,SAAO,wDAAwD,iBAAiB;AAClF;;;AC3CA,SAAS,QAAQ,gBAA4B;AAC7C,SAAS,mBAAmC;AA2CxC,SACE,OAAAA,MADF;AApBG,SAAS,YAAY;AAAA,EAC1B;AAAA,EACA,cAAc;AAAA,EACd;AACF,GAAkC;AAChC,QAAM,EAAE,OAAO,SAAS,IAAI,SAAS;AAErC,QAAM,eAAe;AAAA,IACnB,CAAC,SAAkB;AACjB,YAAM,SAAgB,OAAO,UAAU;AACvC,eAAS,MAAM;AACf,uBAAiB,MAAM;AACvB,sBAAgB,MAAM;AAAA,IACxB;AAAA,IACA,CAAC,UAAU,aAAa;AAAA,EAC1B;AAEA,QAAM,iBAAiB,cAAc,OAAO,UAAU,WAAW,QAAQ;AAEzE,SACE,qBAAC,UAAK,WAAU,kCACd;AAAA,oBAAAA;AAAA,MAAC;AAAA;AAAA,QACC,SAAS,UAAU;AAAA,QACnB,iBAAiB;AAAA,QACjB,cAAY;AAAA;AAAA,IACd;AAAA,IACC,SAAS,gBAAAA,KAAC,UAAK,WAAU,+BAA+B,iBAAM;AAAA,KACjE;AAEJ;AAEA,YAAY,cAAc;","names":["jsx"]}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@ship-it-ui/next",
+  "version": "0.0.2",
+  "description": "Next.js (App Router) helpers for the Ship-It design system: SSR-safe theme persistence with FOUC prevention, cookie helpers, and a token-styled theme toggle.",
+  "license": "MIT",
+  "homepage": "https://ship-it-ops.github.io/ship-it-design/",
+  "bugs": {
+    "url": "https://github.com/ship-it-ops/ship-it-design/issues"
+  },
+  "author": "Ship-It Ops",
+  "keywords": [
+    "design-system",
+    "next",
+    "next.js",
+    "app-router",
+    "theme",
+    "shipit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ship-it-ops/ship-it-design.git",
+    "directory": "packages/next"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "next": "^14.0.0 || ^15.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@ship-it-ui/ui": "0.0.4"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.0.1",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "axe-core": "^4.10.2",
+    "esbuild-plugin-preserve-directives": "^0.0.11",
+    "jsdom": "^29.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3",
+    "vitest-axe": "^0.1.0",
+    "@ship-it-ui/eslint-config": "0.0.1",
+    "@ship-it-ui/tokens": "0.0.4",
+    "@ship-it-ui/tsconfig": "0.0.1",
+    "@ship-it-ui/ui": "0.0.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}