WorkRoot/WRNexusJSDoc
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update portal for WRNexusJS 0.5.11

Browse Source
This commit is contained in:
Clintchiz
2026-07-30 15:13:14 +05:30
parent 2a21cd9cdc
commit 9f10fff4bb
82 changed files with 707 additions and 604 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/pages/packages/styles.wrn
+45 -14
View File
@@ -10,11 +10,11 @@ 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.5.10</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.5.11</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 class="portal-main docs-layout">
<article id="main" 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.5.10</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.5.10</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"><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>
<article id="main" 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.5.11</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.5.11</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"><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>
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
<h3 id="overview">Overview</h3>
<p>This package owns three server-side concerns that shape every page a WRNexusJS app renders:</p>
@@ -180,16 +180,16 @@ import &#123; PluginInput &#125; from '@wrnexus/plugin';
import &#123; StorageConfig &#125; from '@wrnexus/uploader';
/**
* Theme system — design tokens that work SSR and client-side.
* Theme system - design tokens that work SSR and client-side.
*
* Tokens are plain CSS custom properties (`--wire-&lt;key&gt;`) 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.
*
* The server renders `&lt;html data-theme=&quot;…&quot;&gt;` from the `wire-theme` cookie (no
* flash), and a tiny client runtime toggles/persists it. The reserved token key
* `color-scheme` is emitted as the native CSS property (not a variable) so form
* controls and scrollbars match the theme.
* The server renders both `&lt;html data-theme=&quot;...&quot;&gt;` and
* `&lt;html data-accent=&quot;...&quot;&gt;` from cookies, so the correct theme and accent are
* present before the first paint. The reserved token key `color-scheme` is
* emitted as the native CSS property instead of a custom property.
*/
type ThemeTokens = Record&lt;string, string&gt;;
declare const THEME_PALETTE_NAMES: readonly [&quot;blue&quot;, &quot;indigo&quot;, &quot;violet&quot;, &quot;emerald&quot;, &quot;cyan&quot;, &quot;rose&quot;, &quot;amber&quot;, &quot;slate&quot;];
@@ -207,9 +207,22 @@ interface CustomThemePalette &#123;
warning: string;
danger: string;
&#125;
interface ThemeAccentConfig &#123;
/**
* Accent used when no `wire-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.
*/
default?: ThemePaletteName | false;
/** Runtime-selectable accent names. Defaults to every built-in THEME_PALETTE. */
options?: ThemePaletteName[];
&#125;
interface ThemeConfig &#123;
/** 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. */
default?: string;
/** Named token maps. Deep-merged over the framework's built-in light/dark. */
@@ -219,11 +232,18 @@ interface ResolvedTheme &#123;
default: string;
names: string[];
themes: Record&lt;string, ThemeTokens&gt;;
defaultAccent?: ThemePaletteName;
accentNames: ThemePaletteName[];
&#125;
/** Cookie the resolved theme is read from / persisted to. */
/** Cookies used by the SSR renderer and client runtime. */
declare const THEME_COOKIE = &quot;wire-theme&quot;;
declare const ACCENT_COOKIE = &quot;wire-accent&quot;;
declare const THEME_CSS_HREF = &quot;/__wrnexus/theme.css&quot;;
declare const THEME_JS_HREF = &quot;/__wrnexus/theme.js&quot;;
/**
* Single source of truth for both configured palettes and runtime accents.
* Do not create a second hard-coded ACCENTS map in the browser runtime.
*/
declare const THEME_PALETTES: Record&lt;ThemePaletteName, CustomThemePalette&gt;;
/** Built-in themes so components have tokens out of the box. */
declare const DEFAULT_THEMES: Record&lt;string, ThemeTokens&gt;;
@@ -231,12 +251,23 @@ declare const DEFAULT_THEMES: Record&lt;string, ThemeTokens&gt;;
declare function resolveThemeConfig(config?: ThemeConfig): ResolvedTheme;
/** Pick a valid theme name from a cookie value, falling back to the default. */
declare function resolveThemeName(cookieValue: string | undefined, theme: ResolvedTheme): string;
/** Generate the theme stylesheet: a `:root` default plus one block per theme. */
/** Pick a valid accent name from a cookie value, falling back to the configured default. */
declare function resolveAccentName(cookieValue: string | undefined, theme: ResolvedTheme): ThemePaletteName | undefined;
/**
* Generate the theme stylesheet.
*
* Theme selectors are emitted first. Accent selectors are emitted afterwards,
* so a selected accent consistently overrides every semantic palette token,
* including soft/muted/text variants, before the first paint.
*/
declare function renderThemeCss(theme: ResolvedTheme): string;
/**
* Generate the client theme runtime. It exposes `window.wireTheme` and binds
* `[data-wire-theme-toggle]` / `[data-wire-theme-set]` elements. The configured
* theme names are baked in so `toggle()` cycles through them in order.
* Generate the client theme runtime. It exposes `window.wireTheme` and
* `window.wireAccent`, 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
* source of truth.
*/
declare function renderThemeRuntime(theme: ResolvedTheme): string;
@@ -664,7 +695,7 @@ declare function contrast(foreground: string, background: string): ContrastResul
*/
declare function renderStyles(ctx: StyleProcessContext, styles?: StylesConfig): Promise&lt;string&gt;;
export &#123; type AppConfig, type BuildConfig, type ConfigIssue, type ContrastResult, 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 ResolvedTheme, type StyleProcessContext, type StyleSource, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type TenancyConfig, type ThemeConfig, type ThemePaletteName, type ThemeTokens, auditWireTokens, bundleCss, contrast, defineConfig, explainAppConfig, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveProfile, resolveThemeConfig, resolveThemeName, tailwindSourceDirectives, validateAppConfig &#125;;
export &#123; ACCENT_COOKIE, type AppConfig, type BuildConfig, type ConfigIssue, type ContrastResult, 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 ResolvedTheme, type StyleProcessContext, type StyleSource, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type TenancyConfig, type ThemeAccentConfig, type ThemeConfig, type ThemePaletteName, type ThemeTokens, auditWireTokens, bundleCss, contrast, defineConfig, explainAppConfig, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveAccentName, resolveProfile, resolveThemeConfig, resolveThemeName, tailwindSourceDirectives, validateAppConfig &#125;;
</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 &#123; AppConfig &#125; from &quot;@wrnexus/styles&quot;;
export default &#123;
@@ -737,7 +768,7 @@ const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pr
&lt;button data-wire-theme-set=&quot;brand&quot;&gt;Brand theme&lt;/button&gt;</code></pre></article></div></section></article>
<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="#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>
</main>
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.5.10</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.5.11</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>
<BackToTop />
</div>
}