docs: update portal for WRNexusJS 0.8.72
- Bump every @wrnexus/* dependency to its latest release (ui 0.8.88, styles 0.8.26, cli 0.8.72, core 0.8.16, i18n 0.8.12, ...) and refresh bun.lock and package-lock.json. graphql/native 0.8.8 were republished, so their stale lockfile integrity entries were re-resolved. - wrnexus.config.ts: drop `functions` and `compatibility`, both removed from the framework. - Regenerate package, portal and discovery docs from the installed packages, including the new 0.8.72 release page. - Package pages now install each package's own released version (ui 0.8.88, core 0.8.16) instead of stamping the CLI version on all. - llms.txt / llms-full.txt: the generator kept every earlier run's CLI reference and appended another; it now replaces it, so the guide holds one current reference and no longer advertises the removed `wrnexus compatibility` command. - docs.test.ts: compileWireFile was renamed compileWrnFile; tests follow the per-package install versions and the removed command. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
ClintchizandClaude Opus 5.5 committed
1 parent
5c591ab7de
commit
b536b57447
105 files changed
+24822
-12503
No files matched your search
+138
-71
@@ -10,7 +10,7 @@ page wrnexusstyles {
|
||||
<header class="topbar">
|
||||
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
||||
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.8</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.72</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
||||
</header>
|
||||
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
||||
<main id="main" class="portal-main docs-layout docs-layout--navigation"><aside class="docs-section-menu" aria-label="Documentation sections"><nav>
|
||||
@@ -20,18 +20,20 @@ page wrnexusstyles {
|
||||
<section><strong>Reference</strong><a href="/packages">Packages overview</a><a href="/packages/cli">CLI</a><a href="/language">.wrn language</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/examples">Examples</a></section>
|
||||
<section class="package-menu"><strong>Packages</strong><a href="/packages/ai">@wrnexus/ai</a><a href="/packages/auth">@wrnexus/auth</a><a href="/packages/authz">@wrnexus/authz</a><a href="/packages/benchmark">@wrnexus/benchmark</a><a href="/packages/cache">@wrnexus/cache</a><a href="/packages/captcha">@wrnexus/captcha</a><a href="/packages/cli">@wrnexus/cli</a><a href="/packages/compiler">@wrnexus/compiler</a><a href="/packages/content">@wrnexus/content</a><a href="/packages/core">@wrnexus/core</a><a href="/packages/csr">@wrnexus/csr</a><a href="/packages/db">@wrnexus/db</a><a href="/packages/dev-server">@wrnexus/dev-server</a><a href="/packages/dev-toolbar">@wrnexus/dev-toolbar</a><a href="/packages/encryption">@wrnexus/encryption</a><a href="/packages/graphql">@wrnexus/graphql</a><a href="/packages/helpers">@wrnexus/helpers</a><a href="/packages/i18n">@wrnexus/i18n</a><a href="/packages/identity">@wrnexus/identity</a><a href="/packages/image">@wrnexus/image</a><a href="/packages/jwt">@wrnexus/jwt</a><a href="/packages/language-server">@wrnexus/language-server</a><a href="/packages/mcp">@wrnexus/mcp</a><a href="/packages/mobile">@wrnexus/mobile</a><a href="/packages/native">@wrnexus/native</a><a href="/packages/oauth">@wrnexus/oauth</a><a href="/packages/observability">@wrnexus/observability</a><a href="/packages/playground">@wrnexus/playground</a><a href="/packages/plugin">@wrnexus/plugin</a><a href="/packages/pubsub">@wrnexus/pubsub</a><a href="/packages/pwa">@wrnexus/pwa</a><a href="/packages/queue">@wrnexus/queue</a><a href="/packages/reactive">@wrnexus/reactive</a><a href="/packages/realtime">@wrnexus/realtime</a><a href="/packages/router">@wrnexus/router</a><a href="/packages/security">@wrnexus/security</a><a href="/packages/ssr">@wrnexus/ssr</a><a href="/packages/store">@wrnexus/store</a><a href="/packages/styles">@wrnexus/styles</a><a href="/packages/syntax">@wrnexus/syntax</a><a href="/packages/test">@wrnexus/test</a><a href="/packages/tracking">@wrnexus/tracking</a><a href="/packages/typecheck">@wrnexus/typecheck</a><a href="/packages/ui">@wrnexus/ui</a><a href="/packages/uploader">@wrnexus/uploader</a><a href="/packages/validation">@wrnexus/validation</a></section>
|
||||
</nav></aside><div class="docs-reading-column">
|
||||
<article class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/styles</span></nav><section class="doc-intro"><span class="eyebrow">Frontend · Package reference</span><h1>@wrnexus/styles</h1><p>CSS pipeline, themes, fonts, profiles, and application config.</p><div class="doc-meta"><span>v0.8.8</span><span>Private registry</span><span>Frontend</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/styles@0.8.8</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><h3 id="reusable-layers-and-presets">Reusable layers and presets</h3>
|
||||
<article class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/styles</span></nav><section class="doc-intro"><span class="eyebrow">Frontend · Package reference</span><h1>@wrnexus/styles</h1><p>CSS pipeline, themes, fonts, profiles, and application config.</p><div class="doc-meta"><span>v0.8.26</span><span>Private registry</span><span>Frontend</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the package:</p><pre><code>bun add @wrnexus/styles@0.8.26</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><h3 id="reusable-layers-and-presets">Reusable layers and presets</h3>
|
||||
<p>Compose local or package foundations in order; later layers override earlier ones and the application has final base-config precedence:</p>
|
||||
<pre data-language="ts"><code>export default defineConfig({
|
||||
extends: ["@workroot/wrnexus-enterprise", "./layers/company"],
|
||||
profiles: { production: { port: 8080 } },
|
||||
});</code></pre>
|
||||
<p>A directory layer exports <code>wrnexus.layer.ts</code> (JavaScript/MJS are supported). A package can provide that conventional file or declare <code>wrnexus.layer</code> in its <code>package.json</code>. Layers may extend other layers and carry the complete app configuration, including plugins that contribute layouts, components, routes, middleware, and migrations. <code>plugins</code> and <code>head</code> compose; other arrays intentionally replace earlier values. Cycles and missing/invalid entries fail with stable <code>WRN-CONFIG-LAYER-*</code> diagnostics. <code>wrnexus config --explain</code> lists every resolved layer source.</p>
|
||||
<blockquote>Global CSS bundling, the <code>--wire-*</code> design-token theme system, and the <code>wrnexus.config.ts</code> app-config loader for WRNexusJS apps.</blockquote>
|
||||
<blockquote>Global CSS bundling, the <code>--wrn-*</code> design-token theme system, and the <code>wrnexus.config.ts</code> app-config loader for WRNexusJS apps.</blockquote>
|
||||
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
|
||||
<h3 id="overview">Overview</h3>
|
||||
<h4 id="production-css-inlining">Production CSS inlining</h4>
|
||||
<p><code>styles.inlineMaxBytes</code> controls the maximum uncompressed size of the combined production stylesheet to embed in the document. The default is 4096 bytes; <code>0</code> disables inlining. A measured first-visit optimization can use, for example, <code>styles: { inlineMaxBytes: 128 * 1024 }</code>. Larger limits remove a blocking stylesheet request but repeat the CSS in each HTML response. Stylesheets containing relative asset URLs stay external so their URL base does not change. Theme switching and the separately served stylesheet remain available.</p>
|
||||
<p>This package owns three server-side concerns that shape every page a WRNexusJS app renders:</p>
|
||||
<p>1. <strong>Global stylesheet pipeline</strong> — finds <code>app/styles/global.css</code> (or aggregates <code>app/styles/*.css</code>), bundles it with Bun's CSS bundler (which resolves <code>@import</code>, including from <code>node_modules</code>), and produces one stylesheet that is <code><link></code>ed into every page's <code><head></code>. Because it is a plain global sheet, it styles server-rendered markup and hydrated client islands identically. A custom <code>process</code> hook lets you swap in Tailwind / PostCSS / Sass. 2. <strong>Theme system</strong> — design tokens exposed as CSS custom properties (<code>--wire-<key></code>), with built-in <code>light</code>/<code>dark</code> sets, deep-merged user overrides, an SSR <code><html data-theme></code> render (no flash), and a tiny client runtime to toggle/persist the choice. 3. <strong>App config</strong> — loads <code>wrnexus.config.ts</code> (the <code>AppConfig</code> type), applies named profile overrides, and loads the <code>.env</code> cascade.</p>
|
||||
<p>1. <strong>Global stylesheet pipeline</strong> — finds <code>app/styles/global.css</code> (or aggregates <code>app/styles/*.css</code>), bundles it with Bun's CSS bundler (which resolves <code>@import</code>, including from <code>node_modules</code>), and produces one stylesheet that is <code><link></code>ed into every page's <code><head></code>. Because it is a plain global sheet, it styles server-rendered markup and hydrated client islands identically. A custom <code>process</code> hook lets you swap in Tailwind / PostCSS / Sass. 2. <strong>Theme system</strong> — design tokens exposed as CSS custom properties (<code>--wrn-<key></code>), with built-in <code>light</code>/<code>dark</code> sets, deep-merged user overrides, an SSR <code><html data-theme></code> render (no flash), and a tiny client runtime to toggle/persist the choice. 3. <strong>App config</strong> — loads <code>wrnexus.config.ts</code> (the <code>AppConfig</code> type), applies named profile overrides, and loads the <code>.env</code> cascade.</p>
|
||||
<p>It runs server-side / at build time. Reach for it when configuring an app, defining themes, or customising how global CSS is produced.</p>
|
||||
<pre data-language="bash"><code>bun add @wrnexus/styles</code></pre>
|
||||
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
|
||||
@@ -70,8 +72,8 @@ interface StyleProcessContext {
|
||||
<h4 id="theme-system">Theme system</h4>
|
||||
<div class="table-wrap"><table>
|
||||
<thead><tr><th>Export</th><th>Type / Signature</th><th>Purpose</th></tr></thead>
|
||||
<tbody><tr><td><code>DEFAULT_THEMES</code></td><td><code>Record<string, ThemeTokens></code></td><td>Built-in <code>light</code> and <code>dark</code> token maps.</td></tr><tr><td><code>THEME_COOKIE</code></td><td><code>"wire-theme"</code></td><td>Cookie the resolved theme is read from / persisted to.</td></tr><tr><td><code>THEME_CSS_HREF</code></td><td><code>"/__wrnexus/theme.css"</code></td><td>URL the generated theme stylesheet is served at.</td></tr><tr><td><code>THEME_JS_HREF</code></td><td><code>"/__wrnexus/theme.js"</code></td><td>URL the client theme runtime is served at.</td></tr><tr><td><code>resolveThemeConfig</code></td><td><code>(config?: ThemeConfig) => ResolvedTheme</code></td><td>Deep-merge the user's <code>theme</code> config over the defaults; pick the default theme (config's <code>default</code> if valid, else <code>dark</code>, else the first).</td></tr><tr><td><code>resolveThemeName</code></td><td>`(cookieValue: string \</td><td>undefined, theme: ResolvedTheme) => string`</td><td>Pick a valid theme name from a cookie, falling back to <code>theme.default</code>.</td></tr><tr><td><code>renderThemeCss</code></td><td><code>(theme: ResolvedTheme) => string</code></td><td>Generate the theme stylesheet: a <code>:root{…}</code> default plus one <code>[data-theme="<name>"]{…}</code> block per theme.</td></tr><tr><td><code>renderThemeRuntime</code></td><td><code>(theme: ResolvedTheme) => string</code></td><td>Generate the client runtime (see below).</td></tr></tbody></table></div>
|
||||
<p>Tokens are emitted as <code>--wire-<key></code> custom properties, <strong>except</strong> the reserved key <code>color-scheme</code>, which is emitted as the native <code>color-scheme</code> CSS property so form controls and scrollbars match the theme.</p>
|
||||
<tbody><tr><td><code>DEFAULT_THEMES</code></td><td><code>Record<string, ThemeTokens></code></td><td>Built-in <code>light</code> and <code>dark</code> token maps.</td></tr><tr><td><code>THEME_COOKIE</code></td><td><code>"wrn-theme"</code></td><td>Cookie the resolved theme is read from / persisted to.</td></tr><tr><td><code>THEME_CSS_HREF</code></td><td><code>"/__wrnexus/theme.css"</code></td><td>URL the generated theme stylesheet is served at.</td></tr><tr><td><code>THEME_JS_HREF</code></td><td><code>"/__wrnexus/theme.js"</code></td><td>URL the client theme runtime is served at.</td></tr><tr><td><code>resolveThemeConfig</code></td><td><code>(config?: ThemeConfig) => ResolvedTheme</code></td><td>Deep-merge the user's <code>theme</code> config over the defaults; pick the default theme (config's <code>default</code> if valid, else <code>dark</code>, else the first).</td></tr><tr><td><code>resolveThemeName</code></td><td>`(cookieValue: string \</td><td>undefined, theme: ResolvedTheme) => string`</td><td>Pick a valid theme name from a cookie, falling back to <code>theme.default</code>.</td></tr><tr><td><code>renderThemeCss</code></td><td><code>(theme: ResolvedTheme) => string</code></td><td>Generate the theme stylesheet: a <code>:root{…}</code> default plus one <code>[data-theme="<name>"]{…}</code> block per theme.</td></tr><tr><td><code>renderThemeRuntime</code></td><td><code>(theme: ResolvedTheme) => string</code></td><td>Generate the client runtime (see below).</td></tr></tbody></table></div>
|
||||
<p>Tokens are emitted as <code>--wrn-<key></code> custom properties, <strong>except</strong> the reserved key <code>color-scheme</code>, which is emitted as the native <code>color-scheme</code> CSS property so form controls and scrollbars match the theme.</p>
|
||||
<p><code>ThemeConfig</code> / <code>ThemeTokens</code> / <code>ResolvedTheme</code>:</p>
|
||||
<pre data-language="ts"><code>type ThemeTokens = Record<string, string>;
|
||||
|
||||
@@ -102,7 +104,26 @@ interface ResolvedTheme {
|
||||
danger: "#dc2626",
|
||||
},
|
||||
}</code></pre>
|
||||
<p>The client runtime (<code>renderThemeRuntime</code>) exposes <code>window.wireTheme</code> with <code>{ get, set, toggle, bind, themes }</code>, wires up any <code>[data-wire-theme-toggle]</code> and <code>[data-wire-theme-set]</code> elements on load, and persists the choice to the <code>wire-theme</code> cookie (<code>max-age</code> 1 year, <code>samesite=lax</code>). <code>toggle()</code> cycles through the configured theme names in order.</p>
|
||||
<p>The client runtime (<code>renderThemeRuntime</code>) exposes <code>window.wrnTheme</code> with <code>{ get, set, toggle, bind, themes }</code>, connects up any <code>[data-wrn-theme-toggle]</code> and <code>[data-wrn-theme-set]</code> elements on load, and persists the choice to the <code>wrn-theme</code> cookie (<code>max-age</code> 1 year, <code>samesite=lax</code>). <code>toggle()</code> cycles through the configured theme names in order.</p>
|
||||
<h4 id="shared-browser-cookies">Shared browser cookies</h4>
|
||||
<p>Set one cookie policy for theme, accent, language, and application cookies:</p>
|
||||
<pre data-language="ts"><code>export default {
|
||||
cookies: {
|
||||
defaults: {
|
||||
domain: "example.com",
|
||||
path: "/",
|
||||
maxAge: 31_536_000,
|
||||
sameSite: "Lax",
|
||||
secure: true,
|
||||
},
|
||||
language: { maxAge: 2_592_000 },
|
||||
},
|
||||
} satisfies AppConfig;</code></pre>
|
||||
<p>The theme, accent, and language switchers use this policy automatically. Client functions can use the same resolved policy for other values:</p>
|
||||
<pre data-language="ts"><code>window.wrnCookies.set("dashboard-view", "compact");
|
||||
window.wrnCookies.set("locale-preview", "hi", "language");
|
||||
const value = window.wrnCookies.get("dashboard-view");
|
||||
window.wrnCookies.remove("dashboard-view");</code></pre>
|
||||
<h3 id="usage">Usage</h3>
|
||||
<h4 id="wrnexus-config-ts"><code>wrnexus.config.ts</code></h4>
|
||||
<pre data-language="ts"><code>import type { AppConfig } from "@wrnexus/styles";
|
||||
@@ -174,20 +195,20 @@ const themeCss = renderThemeCss(theme); // served at THEME_CSS_HREF
|
||||
const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pre>
|
||||
<p>In templates, consume tokens via the custom properties:</p>
|
||||
<pre data-language="css"><code>.card {
|
||||
background: var(--wire-color-surface);
|
||||
color: var(--wire-color-text);
|
||||
border: 1px solid var(--wire-color-border);
|
||||
border-radius: var(--wire-radius);
|
||||
box-shadow: var(--wire-shadow-1);
|
||||
background: var(--wrn-color-surface);
|
||||
color: var(--wrn-color-text);
|
||||
border: 1px solid var(--wrn-color-border);
|
||||
border-radius: var(--wrn-radius);
|
||||
box-shadow: var(--wrn-shadow-1);
|
||||
}</code></pre>
|
||||
<pre data-language="html"><code><button data-wire-theme-toggle>Toggle theme</button>
|
||||
<button data-wire-theme-set="brand">Brand theme</button></code></pre>
|
||||
<pre data-language="html"><code><button data-wrn-theme-toggle>Toggle theme</button>
|
||||
<button data-wrn-theme-set="brand">Brand theme</button></code></pre>
|
||||
<h3 id="requirements-notes">Requirements / Notes</h3>
|
||||
<ul>
|
||||
<li><strong>Bun-only.</strong> <code>bundleCss</code> uses <code>Bun.build</code>'s CSS bundler for <code>@import</code> resolution, nesting, and minification. Node is not supported.</li>
|
||||
<li>Config and env loading use <code>node:fs</code> / <code>node:path</code> / <code>node:url</code> and read from <code>process.env</code>.</li>
|
||||
<li>Peer package: <code>@wrnexus/core</code> supplies the <code>SeoConfig</code> and <code>SecurityConfig</code> types referenced by <code>AppConfig</code>.</li>
|
||||
<li>The bundled global stylesheet, the theme stylesheet (<code>THEME_CSS_HREF</code>), and the theme runtime (<code>THEME_JS_HREF</code>) are wired into pages by the framework's server; this package only produces their contents.</li>
|
||||
<li>The bundled global stylesheet, the theme stylesheet (<code>THEME_CSS_HREF</code>), and the theme runtime (<code>THEME_JS_HREF</code>) are connected into pages by the framework's server; this package only produces their contents.</li>
|
||||
</ul></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>import { PerformanceBudgets, SeoConfig, SecurityConfig } from '@wrnexus/core';
|
||||
import { PluginInput, PluginPermission } from '@wrnexus/plugin';
|
||||
import { StorageConfig } from '@wrnexus/uploader';
|
||||
@@ -195,7 +216,7 @@ import { StorageConfig } from '@wrnexus/uploader';
|
||||
/**
|
||||
* Theme system - design tokens that work SSR and client-side.
|
||||
*
|
||||
* Tokens are plain CSS custom properties (`--wire-<key>`) so they cascade and
|
||||
* Tokens are plain CSS custom properties (`--wrn-<key>`) so they cascade and
|
||||
* can be overridden by user CSS. Each theme is a flat token map; the framework
|
||||
* ships default `light`/`dark` sets and the user's config deep-merges over them.
|
||||
*
|
||||
@@ -205,7 +226,7 @@ import { StorageConfig } from '@wrnexus/uploader';
|
||||
* emitted as the native CSS property instead of a custom property.
|
||||
*/
|
||||
type ThemeSemanticColor = "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "error";
|
||||
type ThemeToken = "color-scheme" | "color-bg" | "color-background" | "color-foreground" | "color-surface" | "color-surface-2" | "color-surface-raised" | "color-surface-muted" | "color-surface-soft" | "color-text" | "color-text-muted" | "color-text-subtle" | "color-muted" | "color-border" | "color-border-strong" | "color-code-background" | "color-code-surface" | "color-code-text" | "color-code-muted" | "color-code-border" | `color-${ThemeSemanticColor}` | `color-${ThemeSemanticColor}-${"hover" | "active" | "contrast" | "soft" | "muted" | "text"}` | `color-on-${"primary" | "secondary"}` | "radius" | "radius-sm" | "shadow-1" | "shadow-sm" | "shadow-md" | "shadow-lg" | "space-section" | "space-section-sm" | "container-max" | "font-sans";
|
||||
type ThemeToken = "color-scheme" | "color-bg" | "color-background" | "color-foreground" | "color-surface" | "color-surface-2" | "color-surface-raised" | "color-surface-muted" | "color-surface-soft" | "color-text" | "color-text-muted" | "color-text-subtle" | "color-muted" | "color-border" | "color-border-strong" | "color-code-background" | "color-code-surface" | "color-code-text" | "color-code-muted" | "color-code-border" | `color-${ThemeSemanticColor}` | `color-${ThemeSemanticColor}-${"hover" | "active" | "contrast" | "soft" | "muted" | "text"}` | `color-on-${"primary" | "secondary"}` | "radius" | "radius-sm" | "radius-md" | "radius-lg" | "control-height-sm" | "control-height" | "control-height-lg" | "space-panel" | "font-size-ui" | "shadow-1" | "shadow-2" | "shadow-3" | "shadow-sm" | "shadow-md" | "shadow-lg" | "space-section" | "space-section-sm" | "container-max" | "font-sans";
|
||||
/** Known tokens get autocomplete while applications may add namespaced custom tokens. */
|
||||
type ThemeTokens = Partial<Record<ThemeToken, string>> & Record<string, string>;
|
||||
declare function defineThemeTokens<T extends ThemeTokens>(tokens: T): T;
|
||||
@@ -227,7 +248,7 @@ interface CustomThemePalette {
|
||||
}
|
||||
interface ThemeAccentConfig {
|
||||
/**
|
||||
* Accent used when no `wire-accent` cookie is present.
|
||||
* Accent used when no `wrn-accent` cookie is present.
|
||||
*
|
||||
* - Omitted: use the named `palette`, or `blue` when no palette is configured.
|
||||
* - `false`: keep the configured base palette until the user explicitly picks an accent.
|
||||
@@ -235,13 +256,49 @@ interface ThemeAccentConfig {
|
||||
default?: ThemePaletteName | false;
|
||||
/** Runtime-selectable accent names. Defaults to every built-in THEME_PALETTE. */
|
||||
options?: ThemePaletteName[];
|
||||
/** Cookie scope used to persist the selected accent across related applications. */
|
||||
cookie?: ThemeCookieConfig;
|
||||
}
|
||||
interface ThemeCookieConfig {
|
||||
/** Parent domain shared by related applications, for example `localhost` or `.example.com`. */
|
||||
domain?: string;
|
||||
/** Cookie path. Defaults to `/`. */
|
||||
path?: string;
|
||||
/** SameSite policy. Defaults to `Lax`. */
|
||||
sameSite?: "Strict" | "Lax" | "None";
|
||||
/** Force or disable Secure. When omitted it follows the current protocol. */
|
||||
secure?: boolean;
|
||||
/** Cookie lifetime in seconds. Defaults to one year. */
|
||||
maxAge?: number;
|
||||
}
|
||||
type BrowserCookieOptions = ThemeCookieConfig;
|
||||
/** Shared browser-cookie policy with optional per-preference overrides. */
|
||||
interface BrowserCookiesConfig {
|
||||
defaults?: BrowserCookieOptions;
|
||||
theme?: BrowserCookieOptions;
|
||||
accent?: BrowserCookieOptions;
|
||||
language?: BrowserCookieOptions;
|
||||
}
|
||||
type BrowserCookiePreference = "theme" | "accent" | "language";
|
||||
interface BrowserCookieApi {
|
||||
readonly config: BrowserCookiesConfig;
|
||||
get(name: string): string | null;
|
||||
options(preference?: BrowserCookiePreference | BrowserCookieOptions, override?: BrowserCookieOptions): BrowserCookieOptions;
|
||||
set(name: string, value: string, preference?: BrowserCookiePreference | BrowserCookieOptions, override?: BrowserCookieOptions): void;
|
||||
remove(name: string, preference?: BrowserCookiePreference | BrowserCookieOptions, override?: BrowserCookieOptions): void;
|
||||
}
|
||||
declare global {
|
||||
interface Window {
|
||||
wrnCookies: BrowserCookieApi;
|
||||
}
|
||||
}
|
||||
declare function resolveBrowserCookieOptions(config: BrowserCookiesConfig | undefined, preference: BrowserCookiePreference, override?: BrowserCookieOptions): BrowserCookieOptions;
|
||||
interface ThemeConfig {
|
||||
/** Built-in palette name, or a complete custom semantic color palette. */
|
||||
palette?: ThemePaletteName | CustomThemePalette;
|
||||
/** Runtime accent/palette switcher configuration. */
|
||||
accent?: ThemeAccentConfig;
|
||||
/** Name of the theme used when no `wire-theme` cookie is present. */
|
||||
/** Name of the theme used when no `wrn-theme` cookie is present. */
|
||||
default?: string;
|
||||
/** Named token maps. Deep-merged over the framework's built-in light/dark. */
|
||||
themes?: Record<string, ThemeTokens>;
|
||||
@@ -252,10 +309,13 @@ interface ResolvedTheme {
|
||||
themes: Record<string, ThemeTokens>;
|
||||
defaultAccent?: ThemePaletteName;
|
||||
accentNames: ThemePaletteName[];
|
||||
accentCookie?: ThemeCookieConfig;
|
||||
themeCookie?: ThemeCookieConfig;
|
||||
cookies?: BrowserCookiesConfig;
|
||||
}
|
||||
/** Cookies used by the SSR renderer and client runtime. */
|
||||
declare const THEME_COOKIE = "wire-theme";
|
||||
declare const ACCENT_COOKIE = "wire-accent";
|
||||
declare const THEME_COOKIE = "wrn-theme";
|
||||
declare const ACCENT_COOKIE = "wrn-accent";
|
||||
declare const THEME_CSS_HREF = "/__wrnexus/theme.css";
|
||||
declare const THEME_CSS_PREFIX = "/__wrnexus/theme/";
|
||||
declare const THEME_JS_HREF = "/__wrnexus/theme.js";
|
||||
@@ -267,7 +327,7 @@ declare const THEME_PALETTES: Record<ThemePaletteName, CustomThemePalette>
|
||||
/** Built-in themes so components have tokens out of the box. */
|
||||
declare const DEFAULT_THEMES: Record<string, ThemeTokens>;
|
||||
/** Merge the user's theme config over the built-in defaults. */
|
||||
declare function resolveThemeConfig(config?: ThemeConfig): ResolvedTheme;
|
||||
declare function resolveThemeConfig(config?: ThemeConfig, cookies?: BrowserCookiesConfig): ResolvedTheme;
|
||||
/** Pick a valid theme name from a cookie value, falling back to the default. */
|
||||
declare function resolveThemeName(cookieValue: string | undefined, theme: ResolvedTheme): string;
|
||||
/** Pick a valid accent name from a cookie value, falling back to the configured default. */
|
||||
@@ -285,8 +345,8 @@ declare function renderActiveThemeCss(theme: ResolvedTheme, themeName: string, a
|
||||
*/
|
||||
declare function renderThemeCss(theme: ResolvedTheme): string;
|
||||
/**
|
||||
* Generate the client theme runtime. It exposes `window.wireTheme` and
|
||||
* `window.wireAccent`, and binds theme/accent controls.
|
||||
* Generate the client theme runtime. It exposes `window.wrnTheme` and
|
||||
* `window.wrnAccent`, and binds theme/accent controls.
|
||||
*
|
||||
* The runtime changes only data attributes and cookies. It never writes inline
|
||||
* CSS variables and never uses localStorage, so CSS and SSR remain the single
|
||||
@@ -368,26 +428,6 @@ declare function fontCspSources(fonts?: FontConfig): {
|
||||
font: string[];
|
||||
};
|
||||
|
||||
declare const CURRENT_COMPATIBILITY_DATE = "2026-08-02";
|
||||
declare const CURRENT_FRAMEWORK_BEHAVIOUR = 1;
|
||||
interface CompatibilityPolicy {
|
||||
compatibilityDate?: string;
|
||||
frameworkBehaviour?: number;
|
||||
}
|
||||
interface CompatibilityReport {
|
||||
configuredDate?: string;
|
||||
effectiveDate: string;
|
||||
currentDate: string;
|
||||
configuredBehaviour?: number;
|
||||
effectiveBehaviour: number;
|
||||
currentBehaviour: number;
|
||||
needsUpgrade: boolean;
|
||||
future: boolean;
|
||||
messages: string[];
|
||||
}
|
||||
declare function isCompatibilityDate(value: string): boolean;
|
||||
declare function resolveCompatibility(policy: CompatibilityPolicy): CompatibilityReport;
|
||||
|
||||
/**
|
||||
* App configuration loader (`wrnexus.config.ts`).
|
||||
*
|
||||
@@ -416,6 +456,8 @@ interface StylesConfig {
|
||||
entry?: string;
|
||||
/** Include the complete @wrnexus/ui component catalog stylesheet. Default true. */
|
||||
includeUi?: boolean;
|
||||
/** Maximum uncompressed production CSS bytes to inline in the document. Default 4096; 0 disables inlining. Larger limits trade repeat HTML bytes for one fewer blocking request. */
|
||||
inlineMaxBytes?: number;
|
||||
/**
|
||||
* Optional custom processor. Return the final CSS string. Use this to run
|
||||
* Tailwind, PostCSS, Sass, etc. When omitted, the built-in Bun CSS bundler is
|
||||
@@ -589,20 +631,11 @@ interface TypesConfig {
|
||||
generateDeclarations?: boolean;
|
||||
globalTypes?: string;
|
||||
}
|
||||
interface FunctionsConfig {
|
||||
legacyDefaultRuntime?: "current" | "client" | "server" | "shared";
|
||||
}
|
||||
interface StoresConfig {
|
||||
strictMutations?: boolean;
|
||||
persistence?: boolean;
|
||||
}
|
||||
interface CompatibilityConfig {
|
||||
legacyEmit?: boolean;
|
||||
legacyEventProps?: boolean;
|
||||
legacyComponentDiscovery?: boolean;
|
||||
stringLayouts?: boolean;
|
||||
}
|
||||
interface AppConfig extends CompatibilityPolicy {
|
||||
interface AppConfig {
|
||||
/** Ordered reusable configuration layers; the application always has final precedence. */
|
||||
extends?: string | string[];
|
||||
/** Compiler/dev/build plugins, resolved in deterministic pre/normal/post order. */
|
||||
@@ -616,12 +649,8 @@ interface AppConfig extends CompatibilityPolicy {
|
||||
imports?: ImportsConfig;
|
||||
/** TypeScript-backed .wrn type checking and declaration generation. */
|
||||
types?: TypesConfig;
|
||||
/** Legacy function runtime behavior for existing applications. */
|
||||
functions?: FunctionsConfig;
|
||||
/** Typed global/page store behavior. */
|
||||
stores?: StoresConfig;
|
||||
/** Temporary v0.5 syntax compatibility switches. */
|
||||
compatibility?: CompatibilityConfig;
|
||||
/** Opt-in APIs that are not yet covered by stable compatibility guarantees. */
|
||||
experimental?: ExperimentalConfig;
|
||||
/** Route and asset budgets plus build analyzer behavior. */
|
||||
@@ -655,6 +684,8 @@ interface AppConfig extends CompatibilityPolicy {
|
||||
fonts?: FontConfig;
|
||||
/** Design-token themes (deep-merged over the built-in light/dark). */
|
||||
theme?: ThemeConfig;
|
||||
/** Shared client cookie policy used by theme, accent, language, and window.wrnCookies. */
|
||||
cookies?: BrowserCookiesConfig;
|
||||
/** i18n: default language + supported locales (strings live in app/locales/*.json). */
|
||||
i18n?: {
|
||||
default?: string;
|
||||
@@ -665,6 +696,7 @@ interface AppConfig extends CompatibilityPolicy {
|
||||
cookie?: {
|
||||
name?: string;
|
||||
maxAge?: number;
|
||||
domain?: string;
|
||||
path?: string;
|
||||
sameSite?: "Strict" | "Lax" | "None";
|
||||
secure?: boolean;
|
||||
@@ -676,6 +708,34 @@ interface AppConfig extends CompatibilityPolicy {
|
||||
driver: "sqlite" | "postgres" | "mysql" | "mongo";
|
||||
url: string;
|
||||
};
|
||||
/** Background-job persistence. Defaults to durable `.wrnexus/queue.sqlite`. */
|
||||
queue?: {
|
||||
storage?: "sqlite" | "database" | "memory";
|
||||
databaseName?: string;
|
||||
table?: string;
|
||||
dashboard?: {
|
||||
enabled?: boolean;
|
||||
path?: string;
|
||||
permission?: string;
|
||||
};
|
||||
};
|
||||
/** Driver-neutral mail defaults consumed by @wrnexus/mail/application drivers. */
|
||||
mail?: {
|
||||
from?: string;
|
||||
queue?: string | boolean;
|
||||
sandbox?: {
|
||||
enabled?: boolean;
|
||||
allowlist?: string[];
|
||||
};
|
||||
};
|
||||
/** Payment gateway configuration consumed by @wrnexus/payment. */
|
||||
payment?: {
|
||||
default: string;
|
||||
currency?: string;
|
||||
sandbox?: boolean;
|
||||
databaseName?: string;
|
||||
gateways?: Record<string, Record<string, unknown>>;
|
||||
};
|
||||
/**
|
||||
* File-upload storage. Declare named stores (local dir or S3-compatible),
|
||||
* upload with `handleUpload`/`upload` from `@wrnexus/uploader`, and serve
|
||||
@@ -711,6 +771,13 @@ interface AppConfig extends CompatibilityPolicy {
|
||||
*/
|
||||
profiles?: Record<string, Partial<Omit<AppConfig, "profiles">>>;
|
||||
}
|
||||
/** User-authored configuration; retained as an explicit name for API clarity. */
|
||||
type AppConfigInput = AppConfig;
|
||||
/** Configuration after profile/layer resolution. Required input fields stay required. */
|
||||
type ResolvedAppConfig<T extends AppConfig = AppConfig> = Omit<AppConfig, "extends" | "profiles"> & Omit<T, "extends" | "profiles"> & {
|
||||
readonly extends?: undefined;
|
||||
readonly profiles?: undefined;
|
||||
};
|
||||
/**
|
||||
* Resolve the active profile name: explicit argument > `WRNEXUS_PROFILE` env var
|
||||
* > a mode-based default ("production" in prod, else "development").
|
||||
@@ -727,7 +794,7 @@ declare function resolveConfigLayers(appRoot: string, application: AppConfig): P
|
||||
/** Load the raw `wrnexus.config.*` (with the `profiles` map intact), or `{}`. */
|
||||
declare function loadRawConfig(appRoot: string): Promise<AppConfig>;
|
||||
/** Load `wrnexus.config.*`, applying the active profile's overrides. */
|
||||
declare function loadAppConfig(appRoot: string, profile?: string): Promise<AppConfig>;
|
||||
declare function loadAppConfig(appRoot: string, profile?: string): Promise<ResolvedAppConfig>;
|
||||
/**
|
||||
* Load the `.env` cascade for a profile into `process.env`, WITHOUT clobbering
|
||||
* variables already set in the real environment (which always win). Order, low
|
||||
@@ -740,7 +807,7 @@ interface ConfigIssue {
|
||||
severity: "error" | "warning";
|
||||
message: string;
|
||||
}
|
||||
declare function defineConfig(config: AppConfig): AppConfig;
|
||||
declare function defineConfig<const T extends AppConfig>(config: T): T;
|
||||
declare function validateAppConfig(config: AppConfig): ConfigIssue[];
|
||||
interface ExplainedConfig {
|
||||
profile: string;
|
||||
@@ -783,7 +850,7 @@ interface CssTokenAudit {
|
||||
unused: string[];
|
||||
}
|
||||
/** Audit framework design-token declarations and var() references. */
|
||||
declare function auditWireTokens(css: string): CssTokenAudit;
|
||||
declare function auditWrnTokens(css: string): CssTokenAudit;
|
||||
interface StyleSource {
|
||||
path: string;
|
||||
reason?: string;
|
||||
@@ -823,7 +890,7 @@ declare function auditCssPerformance(source: string): CssPerformanceAuditIssue[]
|
||||
*/
|
||||
declare function renderStyles(ctx: StyleProcessContext, styles?: StylesConfig): Promise<string>;
|
||||
|
||||
export { ACCENT_COOKIE, type AppConfig, type BuildConfig, CURRENT_COMPATIBILITY_DATE, CURRENT_FRAMEWORK_BEHAVIOUR, type CompatibilityPolicy, type CompatibilityReport, type ConfigIssue, type ContrastResult, type CssPerformanceAuditIssue, type CssTokenAudit, type CustomThemePalette, DEFAULT_THEMES, type DevToolbarConfig, type ExperimentalConfig, type ExplainedConfig, type FontConfig, type FontDisplay, type GoogleFont, type LocalFontFace, type MobileConfig, type Mode, type NavigationConfig, type ObservabilityConfig, type PerformanceConfig, type PwaConfig, type ResolvedConfigLayers, type ResolvedTheme, type StyleProcessContext, type StyleSource, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_CSS_PREFIX, THEME_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type TenancyConfig, type ThemeAccentConfig, type ThemeConfig, type ThemePaletteName, type ThemeSemanticColor, type ThemeToken, type ThemeTokens, activeThemeCssHref, auditCssPerformance, auditWireTokens, bundleCss, contrast, defineConfig, defineThemeTokens, explainAppConfig, findStyleEntry, fontCspSources, headToString, isCompatibilityDate, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderActiveThemeCss, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveAccentName, resolveCompatibility, resolveConfigLayers, resolveProfile, resolveThemeConfig, resolveThemeName, tailwindSourceDirectives, themeVar, validateAppConfig };
|
||||
export { ACCENT_COOKIE, type AppConfig, type AppConfigInput, type BrowserCookieApi, type BrowserCookieOptions, type BrowserCookiePreference, type BrowserCookiesConfig, type BuildConfig, type ConfigIssue, type ContrastResult, type CssPerformanceAuditIssue, type CssTokenAudit, type CustomThemePalette, DEFAULT_THEMES, type DevToolbarConfig, type ExperimentalConfig, type ExplainedConfig, type FontConfig, type FontDisplay, type GoogleFont, type LocalFontFace, type MobileConfig, type Mode, type NavigationConfig, type ObservabilityConfig, type PerformanceConfig, type PwaConfig, type ResolvedAppConfig, type ResolvedConfigLayers, type ResolvedTheme, type StyleProcessContext, type StyleSource, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_CSS_PREFIX, THEME_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type TenancyConfig, type ThemeAccentConfig, type ThemeConfig, type ThemeCookieConfig, type ThemePaletteName, type ThemeSemanticColor, type ThemeToken, type ThemeTokens, activeThemeCssHref, auditCssPerformance, auditWrnTokens, bundleCss, contrast, defineConfig, defineThemeTokens, explainAppConfig, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderActiveThemeCss, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveAccentName, resolveBrowserCookieOptions, resolveConfigLayers, resolveProfile, resolveThemeConfig, resolveThemeName, tailwindSourceDirectives, themeVar, validateAppConfig };
|
||||
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>wrnexus.config.ts</h3><pre data-language="ts"><code>import type { AppConfig } from "@wrnexus/styles";
|
||||
|
||||
export default {
|
||||
@@ -887,16 +954,16 @@ const active = resolveThemeName(cookies[THEME_COOKIE], theme);
|
||||
|
||||
const themeCss = renderThemeCss(theme); // served at THEME_CSS_HREF
|
||||
const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pre></article><article class="example-card"><h3>Rendering the theme</h3><pre data-language="css"><code>.card {
|
||||
background: var(--wire-color-surface);
|
||||
color: var(--wire-color-text);
|
||||
border: 1px solid var(--wire-color-border);
|
||||
border-radius: var(--wire-radius);
|
||||
box-shadow: var(--wire-shadow-1);
|
||||
}</code></pre></article><article class="example-card"><h3>Rendering the theme</h3><pre data-language="html"><code><button data-wire-theme-toggle>Toggle theme</button>
|
||||
<button data-wire-theme-set="brand">Brand theme</button></code></pre></article></div></section></article></div>
|
||||
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#reusable-layers-and-presets">Reusable layers and presets</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#config-loading">Config loading</a><a class="toc-level-4" href="#appconfig">AppConfig</a><a class="toc-level-4" href="#styles-pipeline">Styles pipeline</a><a class="toc-level-4" href="#theme-system">Theme system</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#wrnexus-config-ts">wrnexus.config.ts</a><a class="toc-level-4" href="#loading-config-producing-css">Loading config + producing CSS</a><a class="toc-level-4" href="#rendering-the-theme">Rendering the theme</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
||||
background: var(--wrn-color-surface);
|
||||
color: var(--wrn-color-text);
|
||||
border: 1px solid var(--wrn-color-border);
|
||||
border-radius: var(--wrn-radius);
|
||||
box-shadow: var(--wrn-shadow-1);
|
||||
}</code></pre></article><article class="example-card"><h3>Rendering the theme</h3><pre data-language="html"><code><button data-wrn-theme-toggle>Toggle theme</button>
|
||||
<button data-wrn-theme-set="brand">Brand theme</button></code></pre></article></div></section></article></div>
|
||||
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#reusable-layers-and-presets">Reusable layers and presets</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-4" href="#production-css-inlining">Production CSS inlining</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#config-loading">Config loading</a><a class="toc-level-4" href="#appconfig">AppConfig</a><a class="toc-level-4" href="#styles-pipeline">Styles pipeline</a><a class="toc-level-4" href="#theme-system">Theme system</a><a class="toc-level-4" href="#shared-browser-cookies">Shared browser cookies</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#wrnexus-config-ts">wrnexus.config.ts</a><a class="toc-level-4" href="#loading-config-producing-css">Loading config + producing CSS</a><a class="toc-level-4" href="#rendering-the-theme">Rendering the theme</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
||||
</main>
|
||||
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.8</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
||||
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.72</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
||||
</div>
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user