@flyingrobots/bijou 0.10.0 → 1.0.0

package/dist/adapters/test/style.js

@@ -1,14 +1,68 @@
+/**
+ * Create a no-op {@link StylePort} that returns text unchanged.
+ *
+ * Use in tests where color output is irrelevant; all methods act as
+ * identity functions so string equality assertions work without
+ * stripping ANSI escape codes.
+ *
+ * @returns A {@link StylePort} whose methods pass text through unmodified.
+ */
 export function plainStyle() {
     return {
+        /**
+         * Return text unchanged, ignoring the design token.
+         * @param _token - Ignored design-token value.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
         styled(_token, text) {
             return text;
         },
+        /**
+         * Return text unchanged, ignoring RGB color channels.
+         * @param _r - Ignored red channel.
+         * @param _g - Ignored green channel.
+         * @param _b - Ignored blue channel.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
         rgb(_r, _g, _b, text) {
             return text;
         },
+        /**
+         * Return text unchanged, ignoring the hex color.
+         * @param _color - Ignored hex color string.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
         hex(_color, text) {
             return text;
         },
+        /**
+         * Return text unchanged, ignoring RGB background color.
+         * @param _r - Ignored red channel.
+         * @param _g - Ignored green channel.
+         * @param _b - Ignored blue channel.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
+        bgRgb(_r, _g, _b, text) {
+            return text;
+        },
+        /**
+         * Return text unchanged, ignoring the hex background color.
+         * @param _color - Ignored hex color string.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
+        bgHex(_color, text) {
+            return text;
+        },
+        /**
+         * Return text unchanged, ignoring bold decoration.
+         * @param text - The text to return.
+         * @returns The original text.
+         */
         bold(text) {
             return text;
         },

package/dist/adapters/test/style.js.map

@@ -1 +1 @@
-{"version":3,"file":"style.js","sourceRoot":"","sources":["../../../src/adapters/test/style.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,MAAM,CAAC,MAAkB,EAAE,IAAY;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,IAAY;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,MAAc,EAAE,IAAY;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,IAAY;YACf,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"style.js","sourceRoot":"","sources":["../../../src/adapters/test/style.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO;QACL;;;;;WAKG;QACH,MAAM,CAAC,MAAkB,EAAE,IAAY;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QAED;;;;;;;WAOG;QACH,GAAG,CAAC,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,IAAY;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;QAED;;;;;WAKG;QACH,GAAG,CAAC,MAAc,EAAE,IAAY;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED;;;;;;;WAOG;QACH,KAAK,CAAC,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,IAAY;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,MAAc,EAAE,IAAY;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAED;;;;WAIG;QACH,IAAI,CAAC,IAAY;YACf,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/context.d.ts

@@ -1,5 +1,26 @@
 import type { BijouContext } from './ports/context.js';
+/**
+ * Retrieve the global default {@link BijouContext}.
+ *
+ * @returns The currently configured default context.
+ * @throws {Error} If no context has been set via {@link setDefaultContext}
+ *   or by importing `@flyingrobots/bijou-node`.
+ */
 export declare function getDefaultContext(): BijouContext;
+/**
+ * Set the global default {@link BijouContext}.
+ *
+ * Typically called once at startup by an adapter package (e.g. bijou-node).
+ * After this call, components that omit the optional `ctx` parameter will
+ * use the context provided here.
+ *
+ * @param ctx - The context to set as the global default.
+ */
 export declare function setDefaultContext(ctx: BijouContext): void;
+/**
+ * Reset the default context to `null`.
+ *
+ * **Test-only** — ensures isolation between test cases.
+ */
 export declare function _resetDefaultContextForTesting(): void;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,wBAAgB,iBAAiB,IAAI,YAAY,CAShD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAShD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/dist/context.js

@@ -1,4 +1,11 @@
 let defaultContext = null;
+/**
+ * Retrieve the global default {@link BijouContext}.
+ *
+ * @returns The currently configured default context.
+ * @throws {Error} If no context has been set via {@link setDefaultContext}
+ *   or by importing `@flyingrobots/bijou-node`.
+ */
 export function getDefaultContext() {
     if (defaultContext === null) {
         throw new Error('[bijou] No default context configured. ' +
@@ -7,9 +14,23 @@ export function getDefaultContext() {
     }
     return defaultContext;
 }
+/**
+ * Set the global default {@link BijouContext}.
+ *
+ * Typically called once at startup by an adapter package (e.g. bijou-node).
+ * After this call, components that omit the optional `ctx` parameter will
+ * use the context provided here.
+ *
+ * @param ctx - The context to set as the global default.
+ */
 export function setDefaultContext(ctx) {
     defaultContext = ctx;
 }
+/**
+ * Reset the default context to `null`.
+ *
+ * **Test-only** — ensures isolation between test cases.
+ */
 export function _resetDefaultContextForTesting() {
     defaultContext = null;
 }

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,IAAI,cAAc,GAAwB,IAAI,CAAC;AAE/C,MAAM,UAAU,iBAAiB;IAC/B,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,qDAAqD;YACrD,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,IAAI,cAAc,GAAwB,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,qDAAqD;YACrD,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B;IAC5C,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}

package/dist/core/bg-fill.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared background-fill utility for components that support `bgToken`.
+ *
+ * Centralises the guard logic (noColor, pipe, accessible) so every call site
+ * stays in sync.
+ *
+ * @module
+ */
+import type { BijouContext } from '../ports/context.js';
+import type { TokenValue } from './theme/tokens.js';
+/**
+ * Determine whether background color should be applied in the current context.
+ *
+ * Returns `false` when the context is missing, `noColor` is enabled, or the
+ * output mode is `pipe` or `accessible`.
+ *
+ * @param ctx - Bijou context (may be undefined).
+ * @returns `true` when it is safe to emit background ANSI sequences.
+ */
+export declare function shouldApplyBg(ctx: BijouContext | undefined): boolean;
+/**
+ * Create a background-fill wrapper function that routes through StylePort.
+ *
+ * Returns `undefined` when the background should not be applied (missing
+ * token/bg, missing context, noColor, pipe mode, or accessible mode).
+ *
+ * @param token - Token with optional `bg` hex color.
+ * @param ctx - Bijou context for styled output.
+ * @returns Wrapper function, or `undefined` if bg should not be applied.
+ */
+export declare function makeBgFill(token: TokenValue | undefined, ctx: BijouContext | undefined): ((text: string) => string) | undefined;
+//# sourceMappingURL=bg-fill.d.ts.map

package/dist/core/bg-fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bg-fill.d.ts","sourceRoot":"","sources":["../../src/core/bg-fill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAKpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,GAAG,EAAE,YAAY,GAAG,SAAS,GAC5B,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAGxC"}

package/dist/core/bg-fill.js

@@ -0,0 +1,42 @@
+/**
+ * Shared background-fill utility for components that support `bgToken`.
+ *
+ * Centralises the guard logic (noColor, pipe, accessible) so every call site
+ * stays in sync.
+ *
+ * @module
+ */
+/**
+ * Determine whether background color should be applied in the current context.
+ *
+ * Returns `false` when the context is missing, `noColor` is enabled, or the
+ * output mode is `pipe` or `accessible`.
+ *
+ * @param ctx - Bijou context (may be undefined).
+ * @returns `true` when it is safe to emit background ANSI sequences.
+ */
+export function shouldApplyBg(ctx) {
+    if (!ctx)
+        return false;
+    if (ctx.theme.noColor)
+        return false;
+    if (ctx.mode === 'pipe' || ctx.mode === 'accessible')
+        return false;
+    return true;
+}
+/**
+ * Create a background-fill wrapper function that routes through StylePort.
+ *
+ * Returns `undefined` when the background should not be applied (missing
+ * token/bg, missing context, noColor, pipe mode, or accessible mode).
+ *
+ * @param token - Token with optional `bg` hex color.
+ * @param ctx - Bijou context for styled output.
+ * @returns Wrapper function, or `undefined` if bg should not be applied.
+ */
+export function makeBgFill(token, ctx) {
+    if (!token?.bg || !shouldApplyBg(ctx))
+        return undefined;
+    return (text) => ctx.style.bgHex(token.bg, text);
+}
+//# sourceMappingURL=bg-fill.js.map

package/dist/core/bg-fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bg-fill.js","sourceRoot":"","sources":["../../src/core/bg-fill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,GAA6B;IACzD,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,KAA6B,EAC7B,GAA6B;IAE7B,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,GAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAG,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC"}

package/dist/core/components/accordion.d.ts

@@ -1,14 +1,34 @@
 import type { BijouContext } from '../../ports/context.js';
 import type { TokenValue } from '../theme/tokens.js';
+/** Represent a single collapsible section within an accordion. */
 export interface AccordionSection {
+    /** Section heading text. */
     title: string;
+    /** Body content shown when the section is expanded. */
     content: string;
+    /** Whether the section is expanded. Defaults to `false`. */
     expanded?: boolean;
 }
+/** Configuration options for the {@link accordion} component. */
 export interface AccordionOptions {
+    /** Token used to style the expand/collapse indicator arrows. */
     indicatorToken?: TokenValue;
+    /** Token used to style section titles. */
     titleToken?: TokenValue;
+    /** Bijou context for rendering mode and theme resolution. */
     ctx?: BijouContext;
 }
+/**
+ * Render a collapsible accordion with expand/collapse indicators.
+ *
+ * Adapts output by mode:
+ * - `pipe`: sections rendered as `# title` headings with content.
+ * - `accessible`: sections tagged `[expanded]` or `[collapsed]`.
+ * - `interactive`/`static`: styled `▼`/`▶` indicators with themed titles.
+ *
+ * @param sections - Array of accordion sections to render.
+ * @param options - Rendering options including indicator/title tokens and context.
+ * @returns The formatted accordion string.
+ */
 export declare function accordion(sections: AccordionSection[], options?: AccordionOptions): string;
 //# sourceMappingURL=accordion.d.ts.map

package/dist/core/components/accordion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../../src/core/components/accordion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAOD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAwC9F"}
+{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../../src/core/components/accordion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAwC9F"}

package/dist/core/components/accordion.js

@@ -1,9 +1,16 @@
-import { getDefaultContext } from '../../context.js';
-function resolveCtx(ctx) {
-    if (ctx)
-        return ctx;
-    return getDefaultContext();
-}
+import { resolveCtx } from '../resolve-ctx.js';
+/**
+ * Render a collapsible accordion with expand/collapse indicators.
+ *
+ * Adapts output by mode:
+ * - `pipe`: sections rendered as `# title` headings with content.
+ * - `accessible`: sections tagged `[expanded]` or `[collapsed]`.
+ * - `interactive`/`static`: styled `▼`/`▶` indicators with themed titles.
+ *
+ * @param sections - Array of accordion sections to render.
+ * @param options - Rendering options including indicator/title tokens and context.
+ * @returns The formatted accordion string.
+ */
 export function accordion(sections, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const mode = ctx.mode;

package/dist/core/components/accordion.js.map

@@ -1 +1 @@
-{"version":3,"file":"accordion.js","sourceRoot":"","sources":["../../../src/core/components/accordion.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAcrD,SAAS,UAAU,CAAC,GAAkB;IACpC,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,OAAO,iBAAiB,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAA4B,EAAE,UAA4B,EAAE;IACpF,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAEtB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACxC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBACf,OAAO,cAAc,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/C,CAAC;YACD,OAAO,eAAe,CAAC,CAAC,KAAK,EAAE,CAAC;QAClC,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IACjF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;IAE1E,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;YACpD,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO;iBACvB,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;iBAC1B,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO,GAAG,SAAS,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACpD,OAAO,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;IACjC,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"accordion.js","sourceRoot":"","sources":["../../../src/core/components/accordion.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAsB/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,QAA4B,EAAE,UAA4B,EAAE;IACpF,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAEtB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACxC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBACf,OAAO,cAAc,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/C,CAAC;YACD,OAAO,eAAe,CAAC,CAAC,KAAK,EAAE,CAAC;QAClC,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IACjF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;IAE1E,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;YACpD,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO;iBACvB,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;iBAC1B,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO,GAAG,SAAS,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACpD,OAAO,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;IACjC,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}

package/dist/core/components/alert.d.ts

@@ -1,8 +1,24 @@
 import type { BijouContext } from '../../ports/context.js';
+/** Alert severity level. */
 export type AlertVariant = 'success' | 'error' | 'warning' | 'info';
+/** Configuration for rendering an alert box. */
 export interface AlertOptions {
+    /** Severity variant (defaults to `'info'`). */
     variant?: AlertVariant;
+    /** Bijou context for I/O, styling, and mode detection. */
     ctx?: BijouContext;
 }
+/**
+ * Render an alert box with an icon and message.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — bordered box with a colored status icon.
+ * - `pipe` — bracketed label like `[ERROR] message`.
+ * - `accessible` — plain label like `Error: message`.
+ *
+ * @param message - Alert body text.
+ * @param options - Alert configuration.
+ * @returns The rendered alert string.
+ */
 export declare function alert(message: string, options?: AlertOptions): string;
 //# sourceMappingURL=alert.d.ts.map

package/dist/core/components/alert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAK3D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAmCD,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAkBzE"}
+{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAK3D,4BAA4B;AAC5B,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAkBzE"}

package/dist/core/components/alert.js

@@ -1,34 +1,45 @@
-import { getDefaultContext } from '../../context.js';
+import { resolveCtx } from '../resolve-ctx.js';
 import { box } from './box.js';
+/** Unicode icon characters for each alert variant. */
 const ICONS = {
     success: '\u2713',
     error: '\u2717',
     warning: '\u26A0',
     info: '\u2139',
 };
+/** Uppercase labels used in pipe mode output. */
 const PIPE_LABELS = {
     success: 'SUCCESS',
     error: 'ERROR',
     warning: 'WARNING',
     info: 'INFO',
 };
+/** Title-cased labels used in accessible mode output. */
 const ACCESSIBLE_LABELS = {
     success: 'Success',
     error: 'Error',
     warning: 'Warning',
     info: 'Info',
 };
+/** Mapping from alert variant to the corresponding border theme token key. */
 const BORDER_TOKENS = {
     success: 'success',
     error: 'error',
     warning: 'warning',
     info: 'primary',
 };
-function resolveCtx(ctx) {
-    if (ctx)
-        return ctx;
-    return getDefaultContext();
-}
+/**
+ * Render an alert box with an icon and message.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — bordered box with a colored status icon.
+ * - `pipe` — bracketed label like `[ERROR] message`.
+ * - `accessible` — plain label like `Error: message`.
+ *
+ * @param message - Alert body text.
+ * @param options - Alert configuration.
+ * @returns The rendered alert string.
+ */
 export function alert(message, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const mode = ctx.mode;

package/dist/core/components/alert.js.map

@@ -1 +1 @@
-{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAS/B,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,WAAW,GAAiC;IAChD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,iBAAiB,GAAiC;IACtD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,aAAa,GAAyE;IAC1F,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF,SAAS,UAAU,CAAC,GAAkB;IACpC,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,OAAO,iBAAiB,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAAwB,EAAE;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAE1C,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,OAAO,EAAE,CAAC;IACnE,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,OAAO,EAAE,CAAC;IAE9E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,aAAa,GAAe,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAClG,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAE1D,OAAO,GAAG,CAAC,WAAW,GAAG,GAAG,GAAG,OAAO,EAAE;QACtC,WAAW;QACX,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAC9B,GAAG;KACJ,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAa/B,sDAAsD;AACtD,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,GAAiC;IAChD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,yDAAyD;AACzD,MAAM,iBAAiB,GAAiC;IACtD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,8EAA8E;AAC9E,MAAM,aAAa,GAAyE;IAC1F,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAAwB,EAAE;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAE1C,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,OAAO,EAAE,CAAC;IACnE,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,OAAO,EAAE,CAAC;IAE9E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,aAAa,GAAe,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAClG,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAE1D,OAAO,GAAG,CAAC,WAAW,GAAG,GAAG,GAAG,OAAO,EAAE;QACtC,WAAW;QACX,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAC9B,GAAG;KACJ,CAAC,CAAC;AACL,CAAC"}

package/dist/core/components/badge.d.ts

@@ -1,9 +1,27 @@
 import type { BijouContext } from '../../ports/context.js';
 import type { BaseStatusKey } from '../theme/tokens.js';
+/** Badge color variant — any status key, plus `'accent'` and `'primary'`. */
 export type BadgeVariant = BaseStatusKey | 'accent' | 'primary';
+/** Configuration for rendering a badge. */
 export interface BadgeOptions {
+    /** Color variant (defaults to `'info'`). */
     variant?: BadgeVariant;
+    /** Bijou context for I/O, styling, and mode detection. */
     ctx?: BijouContext;
 }
+/**
+ * Render an inline badge (pill-shaped label) for the given text.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — inverse-colored pill using the variant token.
+ * - `pipe` — bracketed text like `[OK]`.
+ * - `accessible` — plain text.
+ *
+ * Falls back to a plain space-padded string when no context or theme is available.
+ *
+ * @param text - Label to display inside the badge.
+ * @param options - Badge configuration.
+ * @returns The rendered badge string.
+ */
 export declare function badge(text: string, options?: BadgeOptions): string;
 //# sourceMappingURL=badge.d.ts.map

package/dist/core/components/badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGpE,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAWD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CA2BtE"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGpE,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CA2BtE"}

package/dist/core/components/badge.js

@@ -1,14 +1,18 @@
-import { getDefaultContext } from '../../context.js';
-function resolveCtx(ctx) {
-    if (ctx)
-        return ctx;
-    try {
-        return getDefaultContext();
-    }
-    catch {
-        return undefined;
-    }
-}
+import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
+/**
+ * Render an inline badge (pill-shaped label) for the given text.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — inverse-colored pill using the variant token.
+ * - `pipe` — bracketed text like `[OK]`.
+ * - `accessible` — plain text.
+ *
+ * Falls back to a plain space-padded string when no context or theme is available.
+ *
+ * @param text - Label to display inside the badge.
+ * @param options - Badge configuration.
+ * @returns The rendered badge string.
+ */
 export function badge(text, options = {}) {
     const ctx = resolveCtx(options.ctx);
     if (!ctx)

package/dist/core/components/badge.js.map

@@ -1 +1 @@
-{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AASrD,SAAS,UAAU,CAAC,GAAkB;IACpC,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,iBAAiB,EAAE,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,UAAwB,EAAE;IAC5D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IAE7B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IACxC,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAEvC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;IAC3B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IAE3B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAQ,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAQ,CAAC;IAE3C,IAAI,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC;IAEpE,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpD,SAAS,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,YAAY,GAAe;QAC/B,GAAG,EAAE,SAAS,CAAC,GAAG;QAClB,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC;KACvD,CAAC;IAEF,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAajE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,UAAwB,EAAE;IAC5D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IAE7B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IACxC,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAEvC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;IAC3B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IAE3B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAQ,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAQ,CAAC;IAE3C,IAAI,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC;IAEpE,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpD,SAAS,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,YAAY,GAAe;QAC/B,GAAG,EAAE,SAAS,CAAC,GAAG;QAClB,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC;KACvD,CAAC;IAEF,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;AACrD,CAAC"}

package/dist/core/components/box.d.ts

@@ -1,7 +1,12 @@
 import type { BijouContext } from '../../ports/context.js';
 import type { TokenValue } from '../theme/tokens.js';
+/** Configuration for rendering a bordered box. */
 export interface BoxOptions {
+    /** Theme token applied to border characters. */
     borderToken?: TokenValue;
+    /** Background fill token. Interior spaces are styled with this token's bg color. */
+    bgToken?: TokenValue;
+    /** Inner padding between the border and content (in characters/lines). */
     padding?: {
         top?: number;
         bottom?: number;
@@ -10,12 +15,38 @@ export interface BoxOptions {
     };
     /** Lock outer width (including borders). Content is clipped/padded to fit. */
     width?: number;
+    /** Bijou context for I/O, styling, and mode detection. */
     ctx?: BijouContext;
 }
+/**
+ * Render content inside a bordered box.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — unicode box with themed border color.
+ * - `pipe` / `accessible` — raw content without borders.
+ *
+ * @param content - Text to display inside the box (may contain newlines).
+ * @param options - Box configuration.
+ * @returns The rendered box string, or plain content in non-visual modes.
+ */
 export declare function box(content: string, options?: BoxOptions): string;
+/** Configuration for {@link headerBox}, extending {@link BoxOptions} with label support. */
 export interface HeaderBoxOptions extends BoxOptions {
+    /** Optional detail text displayed after the label in a muted style. */
     detail?: string;
+    /** Theme token applied to the label text. */
     labelToken?: TokenValue;
 }
+/**
+ * Render a labeled box with an optional detail line.
+ *
+ * In visual modes the label is styled with `options.labelToken` (defaults to
+ * the primary semantic token) and wrapped in a {@link box}. Pipe mode returns
+ * plain text; accessible mode uses a colon separator.
+ *
+ * @param label - Primary heading text.
+ * @param options - Header box configuration.
+ * @returns The rendered header box string.
+ */
 export declare function headerBox(label: string, options?: HeaderBoxOptions): string;
 //# sourceMappingURL=box.d.ts.map

package/dist/core/components/box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../../src/core/components/box.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAKrD,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AA8DD,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAmBrE;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAkB/E"}
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../../src/core/components/box.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMrD,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,oFAAoF;IACpF,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AA0ED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAqBrE;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAkB/E"}

package/dist/core/components/box.js

@@ -1,8 +1,24 @@
-import { getDefaultContext } from '../../context.js';
+import { resolveCtx } from '../resolve-ctx.js';
+import { makeBgFill } from '../bg-fill.js';
 import { graphemeWidth } from '../text/grapheme.js';
 import { clipToWidth } from '../text/clip.js';
+/** Unicode box-drawing characters for single-line borders. */
 const BORDER = { tl: '\u250c', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2500', v: '\u2502' };
-function drawBox(content, borderColor, padding, fixedWidth) {
+/**
+ * Draw a unicode box around the given content string.
+ *
+ * Supports both auto-width (measured from content) and fixed-width modes.
+ * Content lines wider than the available space are hard-truncated via
+ * `clipToWidth` (no ellipsis is appended).
+ *
+ * @param content - Multiline string to place inside the box.
+ * @param borderColor - Function that wraps border characters with color styling.
+ * @param padding - Resolved padding values (top, bottom, left, right).
+ * @param fixedWidth - If provided, lock the outer width and clip/pad content to fit.
+ * @param bgFill - Optional function to wrap interior content with background color styling.
+ * @returns The rendered box as a multiline string.
+ */
+function drawBox(content, borderColor, padding, fixedWidth, bgFill) {
     const contentLines = content.split('\n');
     let innerWidth;
     let contentWidth;
@@ -31,25 +47,32 @@ function drawBox(content, borderColor, padding, fixedWidth) {
         const rightPad = ' '.repeat(effectiveRight + Math.max(0, contentWidth - processedVisible));
         return leftPad + processed + rightPad;
     };
+    const fill = bgFill ?? ((s) => s);
     const top = borderColor(BORDER.tl + BORDER.h.repeat(innerWidth) + BORDER.tr);
     const bottom = borderColor(BORDER.bl + BORDER.h.repeat(innerWidth) + BORDER.br);
-    const emptyLine = borderColor(BORDER.v) + ' '.repeat(innerWidth) + borderColor(BORDER.v);
+    const emptyLine = borderColor(BORDER.v) + fill(' '.repeat(innerWidth)) + borderColor(BORDER.v);
     const lines = [top];
     for (let i = 0; i < padding.top; i++)
         lines.push(emptyLine);
     for (const line of contentLines) {
-        lines.push(borderColor(BORDER.v) + pad(line) + borderColor(BORDER.v));
+        lines.push(borderColor(BORDER.v) + fill(pad(line)) + borderColor(BORDER.v));
     }
     for (let i = 0; i < padding.bottom; i++)
         lines.push(emptyLine);
     lines.push(bottom);
     return lines.join('\n');
 }
-function resolveCtx(ctx) {
-    if (ctx)
-        return ctx;
-    return getDefaultContext();
-}
+/**
+ * Render content inside a bordered box.
+ *
+ * Output adapts to the current output mode:
+ * - `interactive` / `static` — unicode box with themed border color.
+ * - `pipe` / `accessible` — raw content without borders.
+ *
+ * @param content - Text to display inside the box (may contain newlines).
+ * @param options - Box configuration.
+ * @returns The rendered box string, or plain content in non-visual modes.
+ */
 export function box(content, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const mode = ctx.mode;
@@ -64,8 +87,20 @@ export function box(content, options = {}) {
         right: options.padding?.right ?? 1,
     };
     const colorize = (s) => ctx.style.styled(borderToken, s);
-    return drawBox(content, colorize, padding, options.width);
+    const bgFill = makeBgFill(options.bgToken, ctx);
+    return drawBox(content, colorize, padding, options.width, bgFill);
 }
+/**
+ * Render a labeled box with an optional detail line.
+ *
+ * In visual modes the label is styled with `options.labelToken` (defaults to
+ * the primary semantic token) and wrapped in a {@link box}. Pipe mode returns
+ * plain text; accessible mode uses a colon separator.
+ *
+ * @param label - Primary heading text.
+ * @param options - Header box configuration.
+ * @returns The rendered header box string.
+ */
 export function headerBox(label, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const mode = ctx.mode;