npm - @nebutra/fonts - Versions diffs - 0.1.0 - Mend

@nebutra/fonts 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Wuxi Nebutra Intelligence Technology Co., Ltd.
+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 ADDED Viewed

@@ -0,0 +1,60 @@
+# @nebutra/fonts
+Status: WIP — Not yet integrated into any production app.
+Self-hosted OSS font registry for Nebutra themes and imported DESIGN.md font
+families.
+The package has two entries:
+- `@nebutra/fonts` is client-safe and maps a CSS font-family stack to the
+  registry CSS variable that should be prepended.
+- `@nebutra/fonts/next` is server-only and declares build-time `next/font`
+  faces plus the combined registry class name.
+## Installation
+```bash
+pnpm add @nebutra/fonts
+```
+## Usage
+Apply registry font variables at the application root:
+```tsx
+import { fontRegistryClassName } from "@nebutra/fonts/next";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={fontRegistryClassName}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+Resolve theme or DESIGN.md stacks on the client-safe path:
+```ts
+import { withRegistryFont } from "@nebutra/fonts";
+const stack = withRegistryFont("Space Grotesk, sans-serif");
+// "var(--font-space-grotesk), Space Grotesk, sans-serif"
+```
+## Registered Families
+The registry includes Geist, Inter, Space Grotesk, Playfair Display, JetBrains
+Mono, Manrope, Sora, Work Sans, DM Sans, Plus Jakarta Sans, Outfit, Figtree,
+Montserrat, Lexend, Fira Code, Roboto Mono, and Source Code Pro.
+## Runtime Model
+`next/font` downloads and self-hosts Google fonts at build time. At runtime,
+the browser requests fonts from the application origin only when an element
+uses the corresponding CSS variable.
+## License
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,50 @@
+{
+  "name": "@nebutra/fonts",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Self-hosted OSS font registry — build-time next/font faces + a name→CSS-var resolver so theme / DESIGN.md fonts render with zero runtime external requests",
+  "private": false,
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "surface": "support-contract",
+    "featureId": "fonts",
+    "category": "design",
+    "summary": "Self-hosted OSS font registry for next/font + CSS-var resolution",
+    "gaps": [
+      "First intentional public publish not yet cut — workspace-only until release surface includes fonts"
+    ]
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/design/fonts"
+  },
+  "files": [
+    "src/index.ts",
+    "src/next.ts"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./next": "./src/next.ts"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": "^19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,72 @@
+/**
+ * @nebutra/fonts — self-hosted OSS font registry (client-safe entry).
+ *
+ * Maps a normalized theme / DESIGN.md font-family name to the CSS variable that
+ * the build-time self-hosted face defines (declared with next/font in
+ * `@nebutra/fonts/next`, applied to <html> via `fontRegistryClassName`).
+ *
+ * WHY: next/font registers each face under a HASHED family name reachable ONLY
+ * via its CSS variable — `font-family: 'Inter'` does NOT use the self-hosted
+ * Inter. So when a theme / imported DESIGN.md font's primary family matches an
+ * entry here, callers prepend `var(--font-…)` to the stack, making the
+ * self-hosted font actually render — with ZERO runtime external requests
+ * (next/font self-hosts at build time) and next/font's automatic metric-matched
+ * fallback (no layout shift). Unmatched families keep their declared stack.
+ *
+ * This entry is FREE of `next/font` imports so client modules can use it.
+ * The `./next` subpath holds the (server-only) next/font declarations and MUST
+ * keep its CSS-variable names in sync with FONT_REGISTRY below.
+ */
+export const FONT_REGISTRY: Record<string, string> = {
+  // Self-hosted via geist/font (default brand faces, loaded by the app shell)
+  geist: "--font-geist-sans",
+  "geist sans": "--font-geist-sans",
+  "geist mono": "--font-geist-mono",
+  // Self-hosted via next/font/google (see ./next)
+  inter: "--font-inter",
+  "space grotesk": "--font-space-grotesk",
+  "playfair display": "--font-playfair-display",
+  "jetbrains mono": "--font-jetbrains-mono",
+  manrope: "--font-reg-manrope",
+  sora: "--font-reg-sora",
+  "work sans": "--font-reg-work-sans",
+  "dm sans": "--font-reg-dm-sans",
+  "plus jakarta sans": "--font-reg-plus-jakarta-sans",
+  outfit: "--font-reg-outfit",
+  figtree: "--font-reg-figtree",
+  montserrat: "--font-reg-montserrat",
+  lexend: "--font-reg-lexend",
+  "fira code": "--font-reg-fira-code",
+  "roboto mono": "--font-reg-roboto-mono",
+  "source code pro": "--font-reg-source-code-pro",
+};
+/** Normalize a single font-family token: strip quotes/whitespace, lowercase. */
+function normalizeFamily(name: string): string {
+  // Strip ALL quotes with a quantifier-free global replace (quotes only appear
+  // at token boundaries in a font-family value). Avoids the end-anchored /['"]+$/
+  // form, which CodeQL flags as polynomial ReDoS (scanned from every position).
+  return name.replace(/['"]/g, "").trim().toLowerCase();
+}
+/** The first (primary) family in a CSS font-family list, normalized. */
+export function primaryFamily(stack: string): string {
+  return normalizeFamily(stack.split(",")[0] ?? "");
+}
+/** Registry CSS variable for a stack's primary family, or undefined. */
+export function resolveRegistryVar(stack: string): string | undefined {
+  return FONT_REGISTRY[primaryFamily(stack)];
+}
+/**
+ * Return `stack` with the self-hosted registry font prepended when its primary
+ * family is registered; otherwise return it unchanged.
+ * e.g. "Space Grotesk, sans-serif" → "var(--font-space-grotesk), Space Grotesk, sans-serif"
+ */
+export function withRegistryFont(stack: string | undefined): string | undefined {
+  if (!stack) return stack;
+  const variable = resolveRegistryVar(stack);
+  return variable ? `var(${variable}), ${stack}` : stack;
+}

package/src/next.ts ADDED Viewed

@@ -0,0 +1,117 @@
+/**
+ * @nebutra/fonts/next — build-time self-hosted OSS font faces (server-only).
+ *
+ * Each face is loaded via next/font/google, which downloads the font AT BUILD
+ * TIME and self-hosts it from the app's own origin — there are ZERO runtime
+ * requests to Google (no IP leak / GDPR concern, no third-party runtime
+ * dependency). Each face exposes a CSS variable; the browser only fetches a
+ * given font file when an element actually uses that variable, so declaring the
+ * whole registry is cheap.
+ *
+ * Apply `fontRegistryClassName` to <html> so the `--font-*` variables exist;
+ * the appearance layer then prepends the matching `var(--font-*)` (see the
+ * client-safe map in `@nebutra/fonts`) when a theme / DESIGN.md font matches.
+ *
+ * All declarations use a literal options object — next/font statically analyses
+ * the call, so the config must NOT be computed. Variable fonts omit `weight`.
+ * Keep the `variable` names in sync with FONT_REGISTRY in `../index.ts`.
+ */
+import {
+  DM_Sans,
+  Figtree,
+  Fira_Code,
+  Inter,
+  JetBrains_Mono,
+  Lexend,
+  Manrope,
+  Montserrat,
+  Outfit,
+  Playfair_Display,
+  Plus_Jakarta_Sans,
+  Roboto_Mono,
+  Sora,
+  Source_Code_Pro,
+  Space_Grotesk,
+  Work_Sans,
+} from "next/font/google";
+const inter = Inter({ subsets: ["latin"], display: "swap", variable: "--font-inter" });
+const spaceGrotesk = Space_Grotesk({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-space-grotesk",
+});
+const playfairDisplay = Playfair_Display({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-playfair-display",
+});
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-jetbrains-mono",
+});
+const manrope = Manrope({ subsets: ["latin"], display: "swap", variable: "--font-reg-manrope" });
+const sora = Sora({ subsets: ["latin"], display: "swap", variable: "--font-reg-sora" });
+const workSans = Work_Sans({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-work-sans",
+});
+const dmSans = DM_Sans({ subsets: ["latin"], display: "swap", variable: "--font-reg-dm-sans" });
+const plusJakartaSans = Plus_Jakarta_Sans({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-plus-jakarta-sans",
+});
+const outfit = Outfit({ subsets: ["latin"], display: "swap", variable: "--font-reg-outfit" });
+const figtree = Figtree({ subsets: ["latin"], display: "swap", variable: "--font-reg-figtree" });
+const montserrat = Montserrat({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-montserrat",
+});
+const lexend = Lexend({ subsets: ["latin"], display: "swap", variable: "--font-reg-lexend" });
+const firaCode = Fira_Code({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-fira-code",
+});
+const robotoMono = Roboto_Mono({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-roboto-mono",
+});
+const sourceCodePro = Source_Code_Pro({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-reg-source-code-pro",
+});
+/** All registry faces, in declaration order. */
+export const FONT_REGISTRY_FACES = [
+  inter,
+  spaceGrotesk,
+  playfairDisplay,
+  jetbrainsMono,
+  manrope,
+  sora,
+  workSans,
+  dmSans,
+  plusJakartaSans,
+  outfit,
+  figtree,
+  montserrat,
+  lexend,
+  firaCode,
+  robotoMono,
+  sourceCodePro,
+] as const;
+/**
+ * Space-joined `.variable` classNames for every registry face. Apply to <html>
+ * so all `--font-*` registry variables are defined (font files lazy-load on
+ * first use). Combine with the app's own Geist faces.
+ */
+export const fontRegistryClassName = FONT_REGISTRY_FACES.map((face) => face.variable).join(" ");