docs: update portal for WRNexusJS 0.2.57
This commit is contained in:
@@ -10,12 +10,12 @@ 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="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.56</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.2.57</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="/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="page package-page">
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Frontend</span><h2>@wrnexus/styles</h2><p>CSS pipeline, themes, fonts, profiles, and application config.</p><span class="status status-beta">Private preview · 0.2.56</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Frontend · Preview</span><h1>@wrnexus/styles</h1><p>CSS pipeline, themes, fonts, profiles, and application config.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/styles@0.2.56</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" class="prose"><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>
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Frontend</span><h2>@wrnexus/styles</h2><p>CSS pipeline, themes, fonts, profiles, and application config.</p><span class="status status-beta">Private preview · 0.2.57</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Frontend · Preview</span><h1>@wrnexus/styles</h1><p>CSS pipeline, themes, fonts, profiles, and application config.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/styles@0.2.57</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" class="prose"><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>
|
||||
@@ -64,6 +64,7 @@ interface StyleProcessContext {
|
||||
<pre data-language="ts"><code>type ThemeTokens = Record<string, string>;
|
||||
|
||||
interface ThemeConfig {
|
||||
palette?: ThemePaletteName | CustomThemePalette;
|
||||
default?: string; // theme used when no cookie is present
|
||||
themes?: Record<string, ThemeTokens>; // deep-merged over built-in light/dark
|
||||
}
|
||||
@@ -73,7 +74,22 @@ interface ResolvedTheme {
|
||||
names: string[];
|
||||
themes: Record<string, ThemeTokens>;
|
||||
}</code></pre>
|
||||
<p>Built-in token keys (both <code>light</code> and <code>dark</code>): <code>color-scheme</code>, <code>color-bg</code>, <code>color-surface</code>, <code>color-surface-2</code>, <code>color-text</code>, <code>color-muted</code>, <code>color-border</code>, <code>color-primary</code>, <code>color-primary-hover</code>, <code>color-primary-contrast</code>, <code>color-danger</code>, <code>color-success</code>, <code>color-warning</code>, <code>radius</code>, <code>radius-sm</code>, <code>font-sans</code>, <code>shadow-1</code>.</p>
|
||||
<p>Built-in palettes are <code>blue</code>, <code>indigo</code>, <code>violet</code>, <code>emerald</code>, <code>cyan</code>, <code>rose</code>, <code>amber</code>, and <code>slate</code>. Each supplies primary, secondary, info, success, warning, danger/error, hover, and contrast colors to every light/dark theme. Built-in token keys also include surfaces, text, borders, radii, fonts, and shadows.</p>
|
||||
<p>A custom palette is intentionally complete, so components never fall back to an unrelated blue status or action color:</p>
|
||||
<pre data-language="ts"><code>theme: {
|
||||
palette: {
|
||||
primary: "#7c3aed",
|
||||
primaryHover: "#6d28d9",
|
||||
primaryContrast: "#ffffff",
|
||||
secondary: "#db2777",
|
||||
secondaryHover: "#be185d",
|
||||
secondaryContrast: "#ffffff",
|
||||
info: "#2563eb",
|
||||
success: "#059669",
|
||||
warning: "#d97706",
|
||||
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>
|
||||
<h3 id="usage">Usage</h3>
|
||||
<h4 id="wrnexus-config-ts"><code>wrnexus.config.ts</code></h4>
|
||||
@@ -86,6 +102,7 @@ export default {
|
||||
port: 3000,
|
||||
db: { driver: "sqlite", url: "app.db" },
|
||||
theme: {
|
||||
palette: "violet",
|
||||
default: "dark",
|
||||
themes: {
|
||||
light: { "color-primary": "#7c3aed" }, // override one token; rest inherited
|
||||
@@ -175,7 +192,24 @@ import { StorageConfig } from '@wrnexus/uploader';
|
||||
* controls and scrollbars match the theme.
|
||||
*/
|
||||
type ThemeTokens = Record<string, string>;
|
||||
declare const THEME_PALETTE_NAMES: readonly ["blue", "indigo", "violet", "emerald", "cyan", "rose", "amber", "slate"];
|
||||
type ThemePaletteName = (typeof THEME_PALETTE_NAMES)[number];
|
||||
/** Required semantic colors for a custom application palette. */
|
||||
interface CustomThemePalette {
|
||||
primary: string;
|
||||
primaryHover: string;
|
||||
primaryContrast: string;
|
||||
secondary: string;
|
||||
secondaryHover: string;
|
||||
secondaryContrast: string;
|
||||
info: string;
|
||||
success: string;
|
||||
warning: string;
|
||||
danger: string;
|
||||
}
|
||||
interface ThemeConfig {
|
||||
/** Built-in palette name, or a complete custom semantic color palette. */
|
||||
palette?: ThemePaletteName | CustomThemePalette;
|
||||
/** 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. */
|
||||
@@ -190,6 +224,7 @@ interface ResolvedTheme {
|
||||
declare const THEME_COOKIE = "wire-theme";
|
||||
declare const THEME_CSS_HREF = "/__wrnexus/theme.css";
|
||||
declare const THEME_JS_HREF = "/__wrnexus/theme.js";
|
||||
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. */
|
||||
@@ -508,7 +543,7 @@ declare function bundleCss(entryPath: string, mode: Mode): Promise<string>
|
||||
*/
|
||||
declare function renderStyles(ctx: StyleProcessContext, styles?: StylesConfig): Promise<string>;
|
||||
|
||||
export { type AppConfig, DEFAULT_THEMES, type FontConfig, type FontDisplay, type GoogleFont, type LocalFontFace, type MobileConfig, type Mode, type PwaConfig, type ResolvedTheme, type StyleProcessContext, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_JS_HREF, type ThemeConfig, type ThemeTokens, bundleCss, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveProfile, resolveThemeConfig, resolveThemeName };
|
||||
export { type AppConfig, type CustomThemePalette, DEFAULT_THEMES, type FontConfig, type FontDisplay, type GoogleFont, type LocalFontFace, type MobileConfig, type Mode, type PwaConfig, type ResolvedTheme, type StyleProcessContext, type StylesConfig, type Mode as StylesMode, THEME_COOKIE, THEME_CSS_HREF, THEME_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type ThemeConfig, type ThemePaletteName, type ThemeTokens, bundleCss, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveProfile, resolveThemeConfig, resolveThemeName };
|
||||
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Examples are taken from this package's installed documentation and must be evaluated with its requirements and stability notes.</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 {
|
||||
@@ -518,6 +553,7 @@ export default {
|
||||
port: 3000,
|
||||
db: { driver: "sqlite", url: "app.db" },
|
||||
theme: {
|
||||
palette: "violet",
|
||||
default: "dark",
|
||||
themes: {
|
||||
light: { "color-primary": "#7c3aed" }, // override one token; rest inherited
|
||||
@@ -580,7 +616,7 @@ const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pr
|
||||
<button data-wire-theme-set="brand">Brand theme</button></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>WRNexusJS 0.2.56 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
<footer>WRNexusJS 0.2.57 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
</div>
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user