@xforge-dev/forge-kit 0.19.1 → 0.21.0

package/dist/forge-header.d.ts

@@ -6,14 +6,21 @@ export type ForgeNavLink = {
     href: string;
     label: string;
     icon?: LucideIcon;
+    /** Full-colour art (e.g. a game icon) in place of `icon`: drawn in a 20px box and left untinted. */
+    media?: ReactNode;
     active?: boolean;
     description?: string;
 };
-/** A run of links inside a nav group, under an optional heading (text, or e.g. an avatar and a name). */
+/**
+ * A run of links inside a nav group, under an optional heading (text, or e.g. an avatar and a name). `rail` indents
+ * the links behind a line, kept within the heading's width, to show they all belong to it (e.g. one character's
+ * pages); the active link lights its stretch of the line.
+ */
 export type ForgeNavSection = {
     key?: string;
     title?: ReactNode;
     items: ForgeNavLink[];
+    rail?: boolean;
 };
 /** A header menu of related pages; active when one of its links is. */
 export type ForgeNavGroup = {
@@ -68,6 +75,8 @@ export declare function ForgePanelSection({ title, description, children, }: {
 }): import("react").JSX.Element;
 export type ForgePanelItemProps = {
     icon?: LucideIcon;
+    /** Full-colour art in place of `icon` (see ForgeNavLink). */
+    media?: ReactNode;
     label: ReactNode;
     description?: ReactNode;
     /** In-app path (client navigation) or, with `external`, a full URL. */
@@ -81,7 +90,7 @@ export type ForgePanelItemProps = {
     keepOpen?: boolean;
 } & Omit<ComponentPropsWithRef<'button'>, 'children' | 'onClick' | 'disabled'>;
 /** A row in the account panel: a link or a button that closes the panel. */
-export declare function ForgePanelItem({ icon: Icon, label, description, href, external, onClick, disabled, active, tone, keepOpen, className: extraClassName, ...buttonProps }: ForgePanelItemProps): import("react").JSX.Element;
+export declare function ForgePanelItem({ icon, media, label, description, href, external, onClick, disabled, active, tone, keepOpen, className: extraClassName, ...buttonProps }: ForgePanelItemProps): import("react").JSX.Element;
 /** A labelled on/off switch row for panel sections. */
 export declare function ForgeSwitchRow({ icon: Icon, label, description, checked, onCheckedChange, }: {
     icon?: LucideIcon;

package/dist/forge-header.js

@@ -12,10 +12,18 @@ import { ForgeSupporterBadge } from './support-button.js';
 import { FORGE_COLOR_THEMES } from './theme.js';
 import { useForgeTheme } from './theme-provider.js';
 import { useCurrentUrl } from './use-current-url.js';
+/** The active link's stretch of a section's rail, on a `relative` row inset 4px from a 2px line. */
+const railMark = 'before:absolute before:inset-y-1 before:-left-1.5 before:w-0.5 before:rounded-full before:bg-primary';
+/** A link's leading art or icon; `icon` keeps the 16px tinted look, `media` gets a 20px untinted box. */
+function LinkLead({ icon: Icon, media, tint }) {
+    if (media)
+        return _jsx("span", { "aria-hidden": true, className: "flex size-5 shrink-0 items-center justify-center", children: media });
+    return Icon ? _jsx(Icon, { "aria-hidden": true, className: `mt-0.5 h-4 w-4 shrink-0 ${tint ? 'text-muted-foreground' : ''}` }) : null;
+}
 export const isNavGroup = (item) => 'sections' in item;
 const navPill = (active) => active
-    ? 'rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground'
-    : 'rounded-md px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground';
+    ? 'rounded-lg bg-primary-tint px-3 py-1.5 text-sm font-semibold text-primary-text'
+    : 'rounded-lg px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground';
 /**
  * The header every xForge app shares: app switcher, page links, app buttons,
  * and an avatar that opens the account panel with the theme settings.
@@ -28,7 +36,7 @@ const menuItem = 'flex cursor-pointer select-none items-start gap-3 rounded-sm p
 /** A nav group on desktop: a pill that opens its links, sections split by a seam. */
 function NavMenu({ group }) {
     const sections = group.sections.filter((s) => s.items.length > 0);
-    return (_jsxs(Menu.Root, { modal: false, children: [_jsxs(Menu.Trigger, { className: `group flex items-center gap-1 ${navPill(group.active)} focus-visible:outline-2 focus-visible:outline-ring`, children: [group.label, _jsx(ChevronDown, { "aria-hidden": true, className: "h-3.5 w-3.5 opacity-70 transition-transform duration-200 group-data-[state=open]:rotate-180" })] }), _jsx(Menu.Portal, { children: _jsx(Menu.Content, { align: "start", sideOffset: 6, className: "z-50 max-h-[var(--radix-dropdown-menu-content-available-height)] w-64 overflow-y-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md", children: sections.map((section, i) => (_jsxs(Menu.Group, { children: [i > 0 && _jsx(Menu.Separator, { className: "-mx-1 my-1 h-px bg-border" }), section.title && (_jsx(Menu.Label, { className: "px-2 pb-1 pt-1.5 text-xs font-medium text-muted-foreground", children: section.title })), section.items.map(({ href, label, icon: Icon, active, description }) => (_jsx(Menu.Item, { asChild: true, children: _jsxs(Link, { href: href, "aria-current": active ? 'page' : undefined, className: `${menuItem} ${active ? 'bg-accent font-medium' : ''}`, children: [Icon && _jsx(Icon, { "aria-hidden": true, className: "mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), active && _jsx(Check, { "aria-hidden": true, className: "mt-0.5 h-4 w-4 shrink-0" })] }) }, href)))] }, section.key ?? i))) }) })] }));
+    return (_jsxs(Menu.Root, { modal: false, children: [_jsxs(Menu.Trigger, { className: `group flex items-center gap-1 ${navPill(group.active)} focus-visible:outline-2 focus-visible:outline-ring`, children: [group.label, _jsx(ChevronDown, { "aria-hidden": true, className: "h-3.5 w-3.5 opacity-70 transition-transform duration-200 group-data-[state=open]:rotate-180" })] }), _jsx(Menu.Portal, { children: _jsx(Menu.Content, { align: "start", sideOffset: 6, className: "z-50 max-h-[var(--radix-dropdown-menu-content-available-height)] w-64 overflow-y-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md", children: sections.map((section, i) => (_jsxs(Menu.Group, { children: [i > 0 && _jsx(Menu.Separator, { className: "-mx-1 my-1 h-px bg-border" }), section.title && (_jsx(Menu.Label, { className: "px-2 pb-1 pt-1.5 text-xs font-medium text-muted-foreground", children: section.title })), _jsx("div", { className: section.rail ? 'ml-3.5 mr-2 border-l-2 pl-1' : undefined, children: section.items.map(({ href, label, icon, media, active, description }) => (_jsx(Menu.Item, { asChild: true, children: _jsxs(Link, { href: href, "aria-current": active ? 'page' : undefined, className: `${menuItem} ${active ? 'bg-accent font-medium' : ''} ${section.rail ? `relative ${active ? railMark : ''}` : ''}`, children: [_jsx(LinkLead, { icon: icon, media: media, tint: true }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), active && _jsx(Check, { "aria-hidden": true, className: "mt-0.5 h-4 w-4 shrink-0" })] }) }, href))) })] }, section.key ?? i))) }) })] }));
 }
 function initials(name) {
     return name.slice(0, 2).toUpperCase();
@@ -65,7 +73,7 @@ function PanelNavGroup({ group }) {
     return (_jsxs("div", { role: "group", "aria-label": group.label, className: "pt-2", children: [_jsxs("p", { className: "flex items-center gap-2 px-2 pb-1 text-xs font-medium text-muted-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": true, className: "h-3.5 w-3.5" }), group.label] }), group.sections.map((section, i) => (_jsxs("div", { className: "space-y-1", children: [section.title && section.items.length > 0 && (
                     // A text title sits over the links' labels; a rich one (an avatar and name) brings its own leading
                     // media, so it lines up with their icons instead.
-                    _jsx("div", { className: `px-2 pb-0.5 pt-1.5 text-xs text-muted-foreground ${typeof section.title === 'string' ? 'pl-9' : ''}`, children: section.title })), section.items.map(({ href, label, icon, active }) => (_jsx(ForgePanelItem, { icon: icon, label: label, href: href, active: active }, href)))] }, section.key ?? i)))] }));
+                    _jsx("div", { className: `px-2 pb-0.5 pt-1.5 text-xs text-muted-foreground ${typeof section.title === 'string' ? 'pl-9' : ''}`, children: section.title })), _jsx("div", { className: section.rail ? 'ml-4 mr-2 space-y-1 border-l-2 pl-1' : 'space-y-1', children: section.items.map(({ href, label, icon, media, active }) => (_jsx(ForgePanelItem, { icon: icon, media: media, label: label, href: href, active: active, className: section.rail ? `relative ${active ? railMark : ''}` : '' }, href))) })] }, section.key ?? i)))] }));
 }
 /** Discord's mark in `currentColor`; give it Discord's blurple (`text-[#5865F2]`) next to a Discord name. */
 export function DiscordIcon({ className }) {
@@ -80,9 +88,9 @@ export function ForgePanelSection({ title, description, children, }) {
     return (_jsxs("section", { className: "space-y-2", children: [_jsxs("div", { children: [_jsx("h3", { className: "text-xs font-semibold uppercase tracking-wide text-muted-foreground", children: title }), description && _jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: description })] }), _jsx("div", { className: "space-y-1", children: children })] }));
 }
 /** A row in the account panel: a link or a button that closes the panel. */
-export function ForgePanelItem({ icon: Icon, label, description, href, external, onClick, disabled, active, tone = 'default', keepOpen, className: extraClassName = '', ...buttonProps }) {
+export function ForgePanelItem({ icon, media, label, description, href, external, onClick, disabled, active, tone = 'default', keepOpen, className: extraClassName = '', ...buttonProps }) {
     const className = `flex w-full items-start gap-3 rounded-md px-2 py-2 text-left text-sm transition-colors hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 ${tone === 'destructive' ? 'text-destructive' : ''} ${active ? 'bg-accent font-medium' : ''} ${extraClassName}`;
-    const body = (_jsxs(_Fragment, { children: [Icon && _jsx(Icon, { className: "mt-0.5 h-4 w-4 shrink-0" }), _jsxs("span", { className: "flex-1", children: [_jsx("span", { className: "block font-medium", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), external && href?.startsWith('http') && tone === 'default' && (_jsx(ExternalLink, { className: "mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" }))] }));
+    const body = (_jsxs(_Fragment, { children: [_jsx(LinkLead, { icon: icon, media: media }), _jsxs("span", { className: "flex-1", children: [_jsx("span", { className: "block font-medium", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), external && href?.startsWith('http') && tone === 'default' && (_jsx(ExternalLink, { className: "mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" }))] }));
     const element = href ? (external ? (_jsx("a", { href: href, className: className, "aria-current": active ? 'page' : undefined, children: body })) : (_jsx(Link, { href: href, className: className, "aria-current": active ? 'page' : undefined, children: body }))) : (_jsx("button", { type: "button", ...buttonProps, onClick: onClick, disabled: disabled, className: className, children: body }));
     return keepOpen ? element : _jsx(Dialog.Close, { asChild: true, children: element });
 }

package/dist/tokens.css

@@ -46,6 +46,16 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-primary-text: var(--primary-text);
+  --color-primary-muted: var(--primary-muted);
+  --color-primary-tint: var(--primary-tint);
+  --color-primary-border: var(--primary-border);
+  --color-primary-surface: var(--primary-surface);
+  --color-primary-surface-border: var(--primary-surface-border);
+  --color-inset: var(--inset);
+  --color-divider: var(--divider);
+  --color-chip: var(--chip);
+  --color-track: var(--track);
 
   --radius-lg: var(--radius);
   --radius-md: calc(var(--radius) - 2px);
@@ -75,6 +85,14 @@
   --border: hsl(0 0% 89.8%);
   --input: hsl(0 0% 89.8%);
   --ring: hsl(38 100% 65%);
+  /* The accent as small text (11–14px): at least 4.5:1 on --card. Each theme tunes it per mode below;
+     big bold figures can use it too. Gold on white needs it far darker than the swatch. */
+  --primary-text: hsl(38 100% 29%);
+  /* Neutral roles inside panels: rows set into a card, the rules between rows, chips, empty meter tracks. */
+  --inset: hsl(0 0% 96.1%);
+  --divider: hsl(0 0% 92%);
+  --chip: hsl(0 0% 93%);
+  --track: hsl(0 0% 89.8%);
   --radius: 0.5rem;
   /* Explicit Tailwind v4 utility vars (ensures runtime overrides work) */
   --color-primary: hsl(38 100% 65%);
@@ -103,24 +121,51 @@
   --border: hsl(0 0% 20%);
   --input: hsl(0 0% 20%);
   --ring: hsl(38 100% 65%);
+  --primary-text: hsl(38 100% 65%);
+  --inset: hsl(0 0% 10.5%);
+  --divider: hsl(0 0% 17%);
+  --chip: hsl(0 0% 19%);
+  --track: hsl(0 0% 18%);
   --color-primary: hsl(38 100% 65%);
   --color-primary-foreground: hsl(38 100% 10%);
   --color-ring: hsl(38 100% 65%);
 }
 
-/* ── Solid colour themes (one per FORGE_COLOR_THEMES entry; see theme.ts) ── */
-html[data-color="blue"] { --primary: hsl(217 91% 60%); --color-primary: hsl(217 91% 60%); --ring: hsl(217 91% 60%); --color-ring: hsl(217 91% 60%); }
-html[data-color="green"] { --primary: hsl(142 71% 45%); --color-primary: hsl(142 71% 45%); --ring: hsl(142 71% 45%); --color-ring: hsl(142 71% 45%); }
-html[data-color="rose"] { --primary: hsl(346 72% 58%); --color-primary: hsl(346 72% 58%); --ring: hsl(346 72% 58%); --color-ring: hsl(346 72% 58%); }
-html[data-color="violet"] { --primary: hsl(262 83% 58%); --color-primary: hsl(262 83% 58%); --ring: hsl(262 83% 58%); --color-ring: hsl(262 83% 58%); }
-html[data-color="sunset"] { --primary: hsl(27 100% 74%); --color-primary: hsl(27 100% 74%); --ring: hsl(27 100% 74%); --color-ring: hsl(27 100% 74%); }
-html[data-color="ocean"] { --primary: hsl(209 100% 50%); --color-primary: hsl(209 100% 50%); --ring: hsl(209 100% 50%); --color-ring: hsl(209 100% 50%); }
-html[data-color="lush"] { --primary: hsl(130 52% 52%); --color-primary: hsl(130 52% 52%); --ring: hsl(130 52% 52%); --color-ring: hsl(130 52% 52%); }
-html[data-color="passion"] { --primary: hsl(7 99% 62%); --color-primary: hsl(7 99% 62%); --ring: hsl(7 99% 62%); --color-ring: hsl(7 99% 62%); }
-html[data-color="royal"] { --primary: hsl(276 86% 57%); --color-primary: hsl(276 86% 57%); --ring: hsl(276 86% 57%); --color-ring: hsl(276 86% 57%); }
-html[data-color="steel"] { --primary: hsl(0 0% 60%); --color-primary: hsl(0 0% 60%); --ring: hsl(0 0% 60%); --color-ring: hsl(0 0% 60%); }
-html[data-color="mono"]:not(.dark) { --primary: hsl(0 0% 9%); --color-primary: hsl(0 0% 9%); --primary-foreground: hsl(0 0% 98%); --color-primary-foreground: hsl(0 0% 98%); --ring: hsl(0 0% 9%); --color-ring: hsl(0 0% 9%); }
-html[data-color="mono"].dark { --primary: hsl(0 0% 98%); --color-primary: hsl(0 0% 98%); --primary-foreground: hsl(0 0% 9%); --color-primary-foreground: hsl(0 0% 9%); --ring: hsl(0 0% 98%); --color-ring: hsl(0 0% 98%); }
+/* Everything else accent-coloured derives from --primary / --primary-text, so a theme is one swatch. */
+:root {
+  --primary-muted: color-mix(in oklab, var(--primary-text) 65%, var(--muted-foreground));
+  --primary-tint: color-mix(in oklab, var(--primary) 12%, transparent);
+  --primary-border: color-mix(in oklab, var(--primary) 35%, transparent);
+  --primary-surface: color-mix(in oklab, var(--primary) 7%, var(--card));
+  --primary-surface-border: color-mix(in oklab, var(--primary) 25%, var(--border));
+}
+
+/* ── Solid colour themes (one per FORGE_COLOR_THEMES entry; see theme.ts) ──
+   Each sets the swatch, the ink on a solid fill of it (--primary-foreground: dark ink, or white where that reads
+   better), and --primary-text per mode, stepped until it reaches 4.5:1 on --card. Gradient themes use one solid
+   representative colour here: never put a gradient on text or a thin bar. */
+html[data-color="blue"] { --primary: hsl(217 91% 60%); --color-primary: hsl(217 91% 60%); --ring: hsl(217 91% 60%); --color-ring: hsl(217 91% 60%); --primary-foreground: hsl(0 0% 4%); --color-primary-foreground: hsl(0 0% 4%); --primary-text: hsl(217 91% 49%); }
+html[data-color="blue"].dark { --primary-text: hsl(217 91% 65%); }
+html[data-color="green"] { --primary: hsl(142 71% 45%); --color-primary: hsl(142 71% 45%); --ring: hsl(142 71% 45%); --color-ring: hsl(142 71% 45%); --primary-text: hsl(142 71% 27%); }
+html[data-color="green"].dark { --primary-text: hsl(142 71% 47%); }
+html[data-color="rose"] { --primary: hsl(346 72% 58%); --color-primary: hsl(346 72% 58%); --ring: hsl(346 72% 58%); --color-ring: hsl(346 72% 58%); --primary-foreground: hsl(0 0% 4%); --color-primary-foreground: hsl(0 0% 4%); --primary-text: hsl(346 72% 49%); }
+html[data-color="rose"].dark { --primary-text: hsl(346 72% 66%); }
+html[data-color="violet"] { --primary: hsl(262 83% 58%); --color-primary: hsl(262 83% 58%); --ring: hsl(262 83% 58%); --color-ring: hsl(262 83% 58%); --primary-foreground: hsl(0 0% 98%); --color-primary-foreground: hsl(0 0% 98%); --primary-text: hsl(262 83% 55%); }
+html[data-color="violet"].dark { --primary-text: hsl(262 83% 72%); }
+html[data-color="sunset"] { --primary: hsl(27 100% 74%); --color-primary: hsl(27 100% 74%); --ring: hsl(27 100% 74%); --color-ring: hsl(27 100% 74%); --primary-text: hsl(27 100% 34%); }
+html[data-color="sunset"].dark { --primary-text: hsl(27 100% 74%); }
+html[data-color="ocean"] { --primary: hsl(209 100% 50%); --color-primary: hsl(209 100% 50%); --ring: hsl(209 100% 50%); --color-ring: hsl(209 100% 50%); --primary-foreground: hsl(0 0% 4%); --color-primary-foreground: hsl(0 0% 4%); --primary-text: hsl(209 100% 40%); }
+html[data-color="ocean"].dark { --primary-text: hsl(209 100% 56%); }
+html[data-color="lush"] { --primary: hsl(130 52% 52%); --color-primary: hsl(130 52% 52%); --ring: hsl(130 52% 52%); --color-ring: hsl(130 52% 52%); --primary-text: hsl(130 52% 31%); }
+html[data-color="lush"].dark { --primary-text: hsl(130 52% 54%); }
+html[data-color="passion"] { --primary: hsl(7 99% 62%); --color-primary: hsl(7 99% 62%); --ring: hsl(7 99% 62%); --color-ring: hsl(7 99% 62%); --primary-text: hsl(7 99% 42%); }
+html[data-color="passion"].dark { --primary-text: hsl(7 99% 64%); }
+html[data-color="royal"] { --primary: hsl(276 86% 57%); --color-primary: hsl(276 86% 57%); --ring: hsl(276 86% 57%); --color-ring: hsl(276 86% 57%); --primary-foreground: hsl(0 0% 98%); --color-primary-foreground: hsl(0 0% 98%); --primary-text: hsl(276 86% 54%); }
+html[data-color="royal"].dark { --primary-text: hsl(276 86% 70%); }
+html[data-color="steel"] { --primary: hsl(0 0% 60%); --color-primary: hsl(0 0% 60%); --ring: hsl(0 0% 60%); --color-ring: hsl(0 0% 60%); --primary-text: hsl(0 0% 42%); }
+html[data-color="steel"].dark { --primary-text: hsl(0 0% 62%); }
+html[data-color="mono"]:not(.dark) { --primary: hsl(0 0% 9%); --color-primary: hsl(0 0% 9%); --primary-foreground: hsl(0 0% 98%); --color-primary-foreground: hsl(0 0% 98%); --ring: hsl(0 0% 9%); --color-ring: hsl(0 0% 9%); --primary-text: hsl(0 0% 9%); }
+html[data-color="mono"].dark { --primary: hsl(0 0% 98%); --color-primary: hsl(0 0% 98%); --primary-foreground: hsl(0 0% 9%); --color-primary-foreground: hsl(0 0% 9%); --ring: hsl(0 0% 98%); --color-ring: hsl(0 0% 98%); --primary-text: hsl(0 0% 98%); }
 
 /* ── Gradient themes: replace the accent fill with a gradient ──
    Unlayered on purpose: in Tailwind 4, cascade layers beat specificity, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xforge-dev/forge-kit",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Shared auth, app registry and UI for xForge apps",
   "license": "MIT",
   "repository": {