docs: update portal for WRNexusJS 0.8.0
This commit is contained in:
@@ -10,11 +10,18 @@ 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.7.0</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.0</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.7.0</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.7.0</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.8.0</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.0</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>
|
||||
<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>
|
||||
@@ -176,7 +183,7 @@ const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pr
|
||||
<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>
|
||||
</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 } from '@wrnexus/plugin';
|
||||
import { PluginInput, PluginPermission } from '@wrnexus/plugin';
|
||||
import { StorageConfig } from '@wrnexus/uploader';
|
||||
|
||||
/**
|
||||
@@ -191,7 +198,12 @@ import { StorageConfig } from '@wrnexus/uploader';
|
||||
* 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<string, string>;
|
||||
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-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";
|
||||
/** 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;
|
||||
declare function themeVar(token: ThemeToken, fallback?: 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. */
|
||||
@@ -345,6 +357,26 @@ 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`).
|
||||
*
|
||||
@@ -453,6 +485,15 @@ interface PwaConfig {
|
||||
cacheUrls?: string[];
|
||||
/** Service-worker cache key. Change it to invalidate existing PWA caches. */
|
||||
cacheName?: string;
|
||||
/** Ordered URL rules for runtime caching. Patterns are regular-expression source strings. */
|
||||
runtimeCaching?: Array<{
|
||||
pattern: string;
|
||||
strategy: "network-first" | "cache-first" | "stale-while-revalidate";
|
||||
cacheName?: string;
|
||||
methods?: string[];
|
||||
}>;
|
||||
/** Background Sync tag used by the offline mutation queue. */
|
||||
backgroundSyncTag?: string;
|
||||
}
|
||||
type DevToolbarPosition = "bottom-center" | "bottom-left" | "bottom-right";
|
||||
interface DevToolbarConfig {
|
||||
@@ -548,9 +589,16 @@ interface CompatibilityConfig {
|
||||
legacyComponentDiscovery?: boolean;
|
||||
stringLayouts?: boolean;
|
||||
}
|
||||
interface AppConfig {
|
||||
interface AppConfig extends CompatibilityPolicy {
|
||||
/** Ordered reusable configuration layers; the application always has final precedence. */
|
||||
extends?: string | string[];
|
||||
/** Compiler/dev/build plugins, resolved in deterministic pre/normal/post order. */
|
||||
plugins?: PluginInput;
|
||||
/** Optional least-privilege enforcement for automatically discovered packages. */
|
||||
pluginPermissions?: {
|
||||
enforce?: boolean;
|
||||
grants?: Record<string, PluginPermission[]>;
|
||||
};
|
||||
/** WRN v0.6 explicit import and compatibility resolution. */
|
||||
imports?: ImportsConfig;
|
||||
/** TypeScript-backed .wrn type checking and declaration generation. */
|
||||
@@ -598,6 +646,17 @@ interface AppConfig {
|
||||
i18n?: {
|
||||
default?: string;
|
||||
locales?: string[];
|
||||
labels?: Record<string, string>;
|
||||
fallbacks?: Record<string, string[]>;
|
||||
direction?: Record<string, "ltr" | "rtl">;
|
||||
cookie?: {
|
||||
name?: string;
|
||||
maxAge?: number;
|
||||
path?: string;
|
||||
sameSite?: "Strict" | "Lax" | "None";
|
||||
secure?: boolean;
|
||||
};
|
||||
strict?: boolean;
|
||||
};
|
||||
/** Default database connection (driver + url); reached with `getDb()`. */
|
||||
db?: {
|
||||
@@ -647,6 +706,11 @@ declare function resolveProfile(options?: {
|
||||
explicit?: string;
|
||||
mode?: Mode;
|
||||
}): string;
|
||||
interface ResolvedConfigLayers {
|
||||
config: AppConfig;
|
||||
sources: string[];
|
||||
}
|
||||
declare function resolveConfigLayers(appRoot: string, application: AppConfig): Promise<ResolvedConfigLayers>;
|
||||
/** 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. */
|
||||
@@ -746,7 +810,7 @@ declare function auditCssPerformance(source: string): CssPerformanceAuditIssue[]
|
||||
*/
|
||||
declare function renderStyles(ctx: StyleProcessContext, styles?: StylesConfig): Promise<string>;
|
||||
|
||||
export { ACCENT_COOKIE, type AppConfig, 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 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, auditCssPerformance, auditWireTokens, bundleCss, contrast, defineConfig, explainAppConfig, findStyleEntry, fontCspSources, headToString, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveAccentName, resolveProfile, resolveThemeConfig, resolveThemeName, tailwindSourceDirectives, validateAppConfig };
|
||||
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_JS_HREF, THEME_PALETTES, THEME_PALETTE_NAMES, type TenancyConfig, type ThemeAccentConfig, type ThemeConfig, type ThemePaletteName, type ThemeSemanticColor, type ThemeToken, type ThemeTokens, auditCssPerformance, auditWireTokens, bundleCss, contrast, defineConfig, defineThemeTokens, explainAppConfig, findStyleEntry, fontCspSources, headToString, isCompatibilityDate, loadAppConfig, loadEnv, loadRawConfig, normalizeStyleSources, renderFontHead, renderProductionFontHead, renderStyles, renderThemeCss, renderThemeRuntime, resolveAccentName, resolveCompatibility, 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 {
|
||||
@@ -817,9 +881,9 @@ const themeJs = renderThemeRuntime(theme); // served at THEME_JS_HREF</code></pr
|
||||
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>
|
||||
<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>
|
||||
<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>
|
||||
</main>
|
||||
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.7.0</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.0</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>
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user