@tuicomponents/gauge 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,270 @@
+import * as zod from 'zod';
+import { z } from 'zod';
+import { BaseTuiComponent, ComponentMetadata, RenderContext, RenderResult, TuiTheme } from '@tuicomponents/core';
+
+/**
+ * Semantic color options for gauge zones.
+ */
+declare const gaugeZoneColorSchema: z.ZodEnum<["success", "warning", "error"]>;
+type GaugeZoneColor = z.infer<typeof gaugeZoneColorSchema>;
+/**
+ * Schema for a zone in the gauge.
+ * Zones define colored threshold regions.
+ */
+declare const gaugeZoneSchema: z.ZodObject<{
+    /**
+     * Upper bound of this zone (inclusive).
+     * Value must be greater than the previous zone's threshold.
+     */
+    threshold: z.ZodNumber;
+    /**
+     * Optional semantic color for this zone.
+     * If not specified, uses default bar appearance.
+     */
+    color: z.ZodOptional<z.ZodEnum<["success", "warning", "error"]>>;
+}, "strip", z.ZodTypeAny, {
+    threshold: number;
+    color?: "success" | "warning" | "error" | undefined;
+}, {
+    threshold: number;
+    color?: "success" | "warning" | "error" | undefined;
+}>;
+type GaugeZone = z.infer<typeof gaugeZoneSchema>;
+/**
+ * Style options for gauge bar characters.
+ */
+declare const gaugeStyleSchema: z.ZodEnum<["bar", "segments", "blocks"]>;
+type GaugeStyle = z.infer<typeof gaugeStyleSchema>;
+/**
+ * Schema for gauge component input.
+ */
+declare const gaugeInputSchema: z.ZodObject<{
+    /**
+     * Current gauge value.
+     */
+    value: z.ZodNumber;
+    /**
+     * Minimum value on the scale.
+     * @default 0
+     */
+    min: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Maximum value on the scale.
+     * @default 100
+     */
+    max: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Optional zones for colored thresholds.
+     * Zones should be ordered by increasing threshold.
+     */
+    zones: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /**
+         * Upper bound of this zone (inclusive).
+         * Value must be greater than the previous zone's threshold.
+         */
+        threshold: z.ZodNumber;
+        /**
+         * Optional semantic color for this zone.
+         * If not specified, uses default bar appearance.
+         */
+        color: z.ZodOptional<z.ZodEnum<["success", "warning", "error"]>>;
+    }, "strip", z.ZodTypeAny, {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }, {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }>, "many">>;
+    /**
+     * Width of the gauge bar in characters.
+     * @default 20
+     */
+    width: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Style for gauge bar characters.
+     * @default "bar"
+     */
+    style: z.ZodDefault<z.ZodEnum<["bar", "segments", "blocks"]>>;
+    /**
+     * Optional label to display before the gauge.
+     */
+    label: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether to show the current value.
+     * @default true
+     */
+    showValue: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Unit string to display after the value (e.g., "%", "°C").
+     * @default ""
+     */
+    unit: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    min: number;
+    max: number;
+    width: number;
+    style: "bar" | "segments" | "blocks";
+    showValue: boolean;
+    unit: string;
+    zones?: {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }[] | undefined;
+    label?: string | undefined;
+}, {
+    value: number;
+    min?: number | undefined;
+    max?: number | undefined;
+    zones?: {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }[] | undefined;
+    width?: number | undefined;
+    style?: "bar" | "segments" | "blocks" | undefined;
+    label?: string | undefined;
+    showValue?: boolean | undefined;
+    unit?: string | undefined;
+}>;
+type GaugeInput = z.input<typeof gaugeInputSchema>;
+type GaugeInputWithDefaults = z.output<typeof gaugeInputSchema>;
+
+/**
+ * Gauge component for rendering meters with threshold zones.
+ */
+declare class GaugeComponent extends BaseTuiComponent<GaugeInput, typeof gaugeInputSchema> {
+    readonly metadata: ComponentMetadata<GaugeInput>;
+    readonly schema: zod.ZodObject<{
+        value: zod.ZodNumber;
+        min: zod.ZodDefault<zod.ZodNumber>;
+        max: zod.ZodDefault<zod.ZodNumber>;
+        zones: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+            threshold: zod.ZodNumber;
+            color: zod.ZodOptional<zod.ZodEnum<["success", "warning", "error"]>>;
+        }, "strip", zod.ZodTypeAny, {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }, {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }>, "many">>;
+        width: zod.ZodDefault<zod.ZodNumber>;
+        style: zod.ZodDefault<zod.ZodEnum<["bar", "segments", "blocks"]>>;
+        label: zod.ZodOptional<zod.ZodString>;
+        showValue: zod.ZodDefault<zod.ZodBoolean>;
+        unit: zod.ZodDefault<zod.ZodString>;
+    }, "strip", zod.ZodTypeAny, {
+        value: number;
+        min: number;
+        max: number;
+        width: number;
+        style: "bar" | "segments" | "blocks";
+        showValue: boolean;
+        unit: string;
+        zones?: {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }[] | undefined;
+        label?: string | undefined;
+    }, {
+        value: number;
+        min?: number | undefined;
+        max?: number | undefined;
+        zones?: {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }[] | undefined;
+        width?: number | undefined;
+        style?: "bar" | "segments" | "blocks" | undefined;
+        label?: string | undefined;
+        showValue?: boolean | undefined;
+        unit?: string | undefined;
+    }>;
+    /**
+     * Override getJsonSchema to use direct schema generation.
+     */
+    getJsonSchema(): object;
+    render(input: GaugeInput, context: RenderContext): RenderResult;
+}
+/**
+ * Factory function to create a gauge component.
+ */
+declare function createGauge(): GaugeComponent;
+
+/**
+ * Characters used for gauge rendering.
+ */
+interface GaugeChars {
+    /** Filled portion character */
+    filled: string;
+    /** Empty portion character */
+    empty: string;
+}
+/**
+ * Get gauge characters for a given style.
+ */
+declare function getGaugeChars(style: GaugeStyle): GaugeChars;
+
+/**
+ * A segment of the gauge bar with its color.
+ */
+interface GaugeSegment {
+    /** Number of characters in this segment */
+    length: number;
+    /** Whether this segment is filled */
+    filled: boolean;
+    /** Optional zone color for this segment */
+    color?: GaugeZoneColor | undefined;
+}
+/**
+ * Pre-computed layout for the gauge.
+ */
+interface GaugeLayout {
+    /** Label to display (empty string if none) */
+    label: string;
+    /** Segments of the gauge bar (filled and empty portions with colors) */
+    segments: GaugeSegment[];
+    /** Character for filled portions */
+    filledChar: string;
+    /** Character for empty portions */
+    emptyChar: string;
+    /** Current value (clamped to min/max) */
+    displayValue: number;
+    /** Formatted value string (e.g., "75%") */
+    valueStr: string;
+    /** Total width of the bar */
+    barWidth: number;
+    /** Percentage (0-100) of fill */
+    percentage: number;
+}
+/**
+ * Compute the layout for a gauge.
+ *
+ * @param input - Validated gauge input with defaults applied
+ * @param chars - Character set to use
+ * @returns Computed layout ready for rendering
+ */
+declare function computeGaugeLayout(input: GaugeInputWithDefaults, chars: GaugeChars): GaugeLayout;
+
+/**
+ * Render a gauge using ANSI escape codes for rich terminal output.
+ *
+ * @param layout - Pre-computed gauge layout
+ * @param input - Original input with defaults
+ * @param theme - Optional theme for colors
+ * @returns ANSI-formatted gauge string
+ */
+declare function renderGaugeAnsi(layout: GaugeLayout, input: GaugeInputWithDefaults, theme?: TuiTheme): string;
+/**
+ * Render a gauge using markdown-friendly output.
+ *
+ * Consolidates adjacent emphasized segments to avoid double-backtick issues
+ * (e.g., `warning``error` renders incorrectly as two adjacent inline code spans).
+ *
+ * @param layout - Pre-computed gauge layout
+ * @param input - Original input with defaults
+ * @returns Markdown-friendly gauge string
+ */
+declare function renderGaugeMarkdown(layout: GaugeLayout, input: GaugeInputWithDefaults): string;
+
+export { type GaugeChars, GaugeComponent, type GaugeInput, type GaugeInputWithDefaults, type GaugeLayout, type GaugeSegment, type GaugeStyle, type GaugeZone, type GaugeZoneColor, computeGaugeLayout, createGauge, gaugeInputSchema, gaugeStyleSchema, gaugeZoneColorSchema, gaugeZoneSchema, getGaugeChars, renderGaugeAnsi, renderGaugeMarkdown };

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import * as zod from 'zod';
+import { z } from 'zod';
+import { BaseTuiComponent, ComponentMetadata, RenderContext, RenderResult, TuiTheme } from '@tuicomponents/core';
+
+/**
+ * Semantic color options for gauge zones.
+ */
+declare const gaugeZoneColorSchema: z.ZodEnum<["success", "warning", "error"]>;
+type GaugeZoneColor = z.infer<typeof gaugeZoneColorSchema>;
+/**
+ * Schema for a zone in the gauge.
+ * Zones define colored threshold regions.
+ */
+declare const gaugeZoneSchema: z.ZodObject<{
+    /**
+     * Upper bound of this zone (inclusive).
+     * Value must be greater than the previous zone's threshold.
+     */
+    threshold: z.ZodNumber;
+    /**
+     * Optional semantic color for this zone.
+     * If not specified, uses default bar appearance.
+     */
+    color: z.ZodOptional<z.ZodEnum<["success", "warning", "error"]>>;
+}, "strip", z.ZodTypeAny, {
+    threshold: number;
+    color?: "success" | "warning" | "error" | undefined;
+}, {
+    threshold: number;
+    color?: "success" | "warning" | "error" | undefined;
+}>;
+type GaugeZone = z.infer<typeof gaugeZoneSchema>;
+/**
+ * Style options for gauge bar characters.
+ */
+declare const gaugeStyleSchema: z.ZodEnum<["bar", "segments", "blocks"]>;
+type GaugeStyle = z.infer<typeof gaugeStyleSchema>;
+/**
+ * Schema for gauge component input.
+ */
+declare const gaugeInputSchema: z.ZodObject<{
+    /**
+     * Current gauge value.
+     */
+    value: z.ZodNumber;
+    /**
+     * Minimum value on the scale.
+     * @default 0
+     */
+    min: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Maximum value on the scale.
+     * @default 100
+     */
+    max: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Optional zones for colored thresholds.
+     * Zones should be ordered by increasing threshold.
+     */
+    zones: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /**
+         * Upper bound of this zone (inclusive).
+         * Value must be greater than the previous zone's threshold.
+         */
+        threshold: z.ZodNumber;
+        /**
+         * Optional semantic color for this zone.
+         * If not specified, uses default bar appearance.
+         */
+        color: z.ZodOptional<z.ZodEnum<["success", "warning", "error"]>>;
+    }, "strip", z.ZodTypeAny, {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }, {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }>, "many">>;
+    /**
+     * Width of the gauge bar in characters.
+     * @default 20
+     */
+    width: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Style for gauge bar characters.
+     * @default "bar"
+     */
+    style: z.ZodDefault<z.ZodEnum<["bar", "segments", "blocks"]>>;
+    /**
+     * Optional label to display before the gauge.
+     */
+    label: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether to show the current value.
+     * @default true
+     */
+    showValue: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Unit string to display after the value (e.g., "%", "°C").
+     * @default ""
+     */
+    unit: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    min: number;
+    max: number;
+    width: number;
+    style: "bar" | "segments" | "blocks";
+    showValue: boolean;
+    unit: string;
+    zones?: {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }[] | undefined;
+    label?: string | undefined;
+}, {
+    value: number;
+    min?: number | undefined;
+    max?: number | undefined;
+    zones?: {
+        threshold: number;
+        color?: "success" | "warning" | "error" | undefined;
+    }[] | undefined;
+    width?: number | undefined;
+    style?: "bar" | "segments" | "blocks" | undefined;
+    label?: string | undefined;
+    showValue?: boolean | undefined;
+    unit?: string | undefined;
+}>;
+type GaugeInput = z.input<typeof gaugeInputSchema>;
+type GaugeInputWithDefaults = z.output<typeof gaugeInputSchema>;
+
+/**
+ * Gauge component for rendering meters with threshold zones.
+ */
+declare class GaugeComponent extends BaseTuiComponent<GaugeInput, typeof gaugeInputSchema> {
+    readonly metadata: ComponentMetadata<GaugeInput>;
+    readonly schema: zod.ZodObject<{
+        value: zod.ZodNumber;
+        min: zod.ZodDefault<zod.ZodNumber>;
+        max: zod.ZodDefault<zod.ZodNumber>;
+        zones: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+            threshold: zod.ZodNumber;
+            color: zod.ZodOptional<zod.ZodEnum<["success", "warning", "error"]>>;
+        }, "strip", zod.ZodTypeAny, {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }, {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }>, "many">>;
+        width: zod.ZodDefault<zod.ZodNumber>;
+        style: zod.ZodDefault<zod.ZodEnum<["bar", "segments", "blocks"]>>;
+        label: zod.ZodOptional<zod.ZodString>;
+        showValue: zod.ZodDefault<zod.ZodBoolean>;
+        unit: zod.ZodDefault<zod.ZodString>;
+    }, "strip", zod.ZodTypeAny, {
+        value: number;
+        min: number;
+        max: number;
+        width: number;
+        style: "bar" | "segments" | "blocks";
+        showValue: boolean;
+        unit: string;
+        zones?: {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }[] | undefined;
+        label?: string | undefined;
+    }, {
+        value: number;
+        min?: number | undefined;
+        max?: number | undefined;
+        zones?: {
+            threshold: number;
+            color?: "success" | "warning" | "error" | undefined;
+        }[] | undefined;
+        width?: number | undefined;
+        style?: "bar" | "segments" | "blocks" | undefined;
+        label?: string | undefined;
+        showValue?: boolean | undefined;
+        unit?: string | undefined;
+    }>;
+    /**
+     * Override getJsonSchema to use direct schema generation.
+     */
+    getJsonSchema(): object;
+    render(input: GaugeInput, context: RenderContext): RenderResult;
+}
+/**
+ * Factory function to create a gauge component.
+ */
+declare function createGauge(): GaugeComponent;
+
+/**
+ * Characters used for gauge rendering.
+ */
+interface GaugeChars {
+    /** Filled portion character */
+    filled: string;
+    /** Empty portion character */
+    empty: string;
+}
+/**
+ * Get gauge characters for a given style.
+ */
+declare function getGaugeChars(style: GaugeStyle): GaugeChars;
+
+/**
+ * A segment of the gauge bar with its color.
+ */
+interface GaugeSegment {
+    /** Number of characters in this segment */
+    length: number;
+    /** Whether this segment is filled */
+    filled: boolean;
+    /** Optional zone color for this segment */
+    color?: GaugeZoneColor | undefined;
+}
+/**
+ * Pre-computed layout for the gauge.
+ */
+interface GaugeLayout {
+    /** Label to display (empty string if none) */
+    label: string;
+    /** Segments of the gauge bar (filled and empty portions with colors) */
+    segments: GaugeSegment[];
+    /** Character for filled portions */
+    filledChar: string;
+    /** Character for empty portions */
+    emptyChar: string;
+    /** Current value (clamped to min/max) */
+    displayValue: number;
+    /** Formatted value string (e.g., "75%") */
+    valueStr: string;
+    /** Total width of the bar */
+    barWidth: number;
+    /** Percentage (0-100) of fill */
+    percentage: number;
+}
+/**
+ * Compute the layout for a gauge.
+ *
+ * @param input - Validated gauge input with defaults applied
+ * @param chars - Character set to use
+ * @returns Computed layout ready for rendering
+ */
+declare function computeGaugeLayout(input: GaugeInputWithDefaults, chars: GaugeChars): GaugeLayout;
+
+/**
+ * Render a gauge using ANSI escape codes for rich terminal output.
+ *
+ * @param layout - Pre-computed gauge layout
+ * @param input - Original input with defaults
+ * @param theme - Optional theme for colors
+ * @returns ANSI-formatted gauge string
+ */
+declare function renderGaugeAnsi(layout: GaugeLayout, input: GaugeInputWithDefaults, theme?: TuiTheme): string;
+/**
+ * Render a gauge using markdown-friendly output.
+ *
+ * Consolidates adjacent emphasized segments to avoid double-backtick issues
+ * (e.g., `warning``error` renders incorrectly as two adjacent inline code spans).
+ *
+ * @param layout - Pre-computed gauge layout
+ * @param input - Original input with defaults
+ * @returns Markdown-friendly gauge string
+ */
+declare function renderGaugeMarkdown(layout: GaugeLayout, input: GaugeInputWithDefaults): string;
+
+export { type GaugeChars, GaugeComponent, type GaugeInput, type GaugeInputWithDefaults, type GaugeLayout, type GaugeSegment, type GaugeStyle, type GaugeZone, type GaugeZoneColor, computeGaugeLayout, createGauge, gaugeInputSchema, gaugeStyleSchema, gaugeZoneColorSchema, gaugeZoneSchema, getGaugeChars, renderGaugeAnsi, renderGaugeMarkdown };