@fusion.dev/helix-headless 0.199.1 → 0.201.0

package/dist/element-events.generated.js

@@ -177,6 +177,8 @@ registerElementEvents({
         'helix-reorder',
         'input',
     ],
+    'helix-headless-log': ['helix-before-pin', 'helix-expand', 'helix-pin'],
+    'helix-headless-log-group': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-map': [
         'change',
         'helix-activate',

package/dist/index.d.ts

@@ -61,6 +61,7 @@ export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';
 export * from './loader/index.js';
+export * from './log/index.js';
 export * from './map/index.js';
 export * from './megamenu/index.js';
 export * from './menu/filter/index.js';

package/dist/index.js

@@ -52,6 +52,7 @@ export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';
 export * from './loader/index.js';
+export * from './log/index.js';
 export * from './map/index.js';
 export * from './megamenu/index.js';
 export * from './menu/filter/index.js';

package/dist/log/ansi.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The color and weight a run of a log line is drawn in, read from the ANSI
+ * escape codes a terminal program writes.
+ *
+ * **Only Select Graphic Rendition is drawn.** Every other escape sequence, a
+ * cursor move, a line erase, a window title, is taken out of the text and
+ * dropped, because a log is a record of what was written and has no cursor
+ * to move. A sequence cut off at the end of the text is dropped too.
+ */
+/** How one run of text is drawn. Absent fields are the log's own defaults. */
+export interface LogStyle {
+    /** The background: one of `ANSI_NAMES`, or a CSS color. */
+    background?: string;
+    /** Bold, or bright on a terminal that draws it that way. */
+    bold?: boolean;
+    /** The text color: one of `ANSI_NAMES`, or a CSS color. */
+    color?: string;
+    /** Faint. */
+    dim?: boolean;
+    /** Foreground and background swapped. */
+    inverse?: boolean;
+    /** Italic. */
+    italic?: boolean;
+    /** Struck through. */
+    strike?: boolean;
+    /** Underlined. */
+    underline?: boolean;
+}
+/** A stretch of a line drawn one way. */
+export interface LogRun extends LogStyle {
+    /** The text, with every escape sequence taken out. */
+    text: string;
+}
+/**
+ * The sixteen colors a terminal names, in the order SGR numbers them: the
+ * eight at `30` to `37`, then their bright forms at `90` to `97`.
+ *
+ * A run in one of them carries the name, and is drawn in the `--log-ansi-`
+ * color of that name, so the stylesheet says what red is in its theme. The
+ * palette's own index above fifteen is a fact about the color and is carried
+ * as the color itself.
+ */
+export declare const ANSI_NAMES: readonly ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'bright-black', 'bright-red', 'bright-green', 'bright-yellow', 'bright-blue', 'bright-magenta', 'bright-cyan', 'bright-white'];
+/**
+ * Entry `index` of the 256-color palette: a name below 16, and the CSS color
+ * of the cube to 231 and of the ramp of grays from 232 to 255.
+ */
+export declare const paletteColor: (index: number) => string | undefined;
+/** The style `codes` leave behind, applied over `style`. */
+export declare const applySgr: (style: LogStyle, codes: readonly number[]) => LogStyle;
+/**
+ * Splits one line of text into runs, starting from `style`, and says what
+ * style the line ends in, which is where the next line starts.
+ *
+ * A run with no style left is plain. Adjacent runs that draw the same are
+ * merged, so a line that resets to the style it already had stays one run.
+ */
+export declare const parseAnsi: (text: string, style?: LogStyle) => {
+    runs: LogRun[];
+    style: LogStyle;
+};
+/** The text of a line with every escape sequence taken out. */
+export declare const stripAnsi: (text: string) => string;

package/dist/log/ansi.js

@@ -0,0 +1,163 @@
+export const ANSI_NAMES = [
+    'black',
+    'red',
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'white',
+    'bright-black',
+    'bright-red',
+    'bright-green',
+    'bright-yellow',
+    'bright-blue',
+    'bright-magenta',
+    'bright-cyan',
+    'bright-white',
+];
+const named = (index) => ANSI_NAMES[index] ?? 'white';
+const CUBE = [0, 95, 135, 175, 215, 255];
+export const paletteColor = (index) => {
+    if (!Number.isInteger(index) || index < 0 || index > 255) {
+        return undefined;
+    }
+    if (index < 16) {
+        return named(index);
+    }
+    if (index < 232) {
+        const cube = index - 16;
+        const red = CUBE[Math.floor(cube / 36)];
+        const green = CUBE[Math.floor(cube / 6) % 6];
+        const blue = CUBE[cube % 6];
+        return `rgb(${red} ${green} ${blue})`;
+    }
+    const gray = 8 + (index - 232) * 10;
+    return `rgb(${gray} ${gray} ${gray})`;
+};
+const extended = (codes, at) => {
+    const form = codes[at];
+    if (form === 5) {
+        return { color: paletteColor(codes[at + 1] ?? -1), used: 2 };
+    }
+    if (form === 2) {
+        const [red, green, blue] = [codes[at + 1], codes[at + 2], codes[at + 3]];
+        const valid = [red, green, blue].every((value) => value !== undefined && Number.isInteger(value) && value >= 0 && value <= 255);
+        return { color: valid ? `rgb(${red} ${green} ${blue})` : undefined, used: 4 };
+    }
+    return { color: undefined, used: 1 };
+};
+export const applySgr = (style, codes) => {
+    const next = { ...style };
+    const list = codes.length === 0 ? [0] : codes;
+    for (let at = 0; at < list.length; at += 1) {
+        const code = list[at] ?? 0;
+        if (code === 0) {
+            for (const key of Object.keys(next)) {
+                delete next[key];
+            }
+        }
+        else if (code === 1) {
+            next.bold = true;
+        }
+        else if (code === 2) {
+            next.dim = true;
+        }
+        else if (code === 3) {
+            next.italic = true;
+        }
+        else if (code === 4) {
+            next.underline = true;
+        }
+        else if (code === 7) {
+            next.inverse = true;
+        }
+        else if (code === 9) {
+            next.strike = true;
+        }
+        else if (code === 22) {
+            delete next.bold;
+            delete next.dim;
+        }
+        else if (code === 23) {
+            delete next.italic;
+        }
+        else if (code === 24) {
+            delete next.underline;
+        }
+        else if (code === 27) {
+            delete next.inverse;
+        }
+        else if (code === 29) {
+            delete next.strike;
+        }
+        else if (code >= 30 && code <= 37) {
+            next.color = named(code - 30);
+        }
+        else if (code === 38 || code === 48) {
+            const { color, used } = extended(list, at + 1);
+            if (color !== undefined) {
+                next[code === 38 ? 'color' : 'background'] = color;
+            }
+            at += used;
+        }
+        else if (code === 39) {
+            delete next.color;
+        }
+        else if (code >= 40 && code <= 47) {
+            next.background = named(code - 40);
+        }
+        else if (code === 49) {
+            delete next.background;
+        }
+        else if (code >= 90 && code <= 97) {
+            next.color = named(code - 90 + 8);
+        }
+        else if (code >= 100 && code <= 107) {
+            next.background = named(code - 100 + 8);
+        }
+    }
+    return next;
+};
+const plain = (style) => Object.keys(style).length === 0;
+const same = (a, b) => {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    keys.delete('text');
+    for (const key of keys) {
+        if (a[key] !== b[key]) {
+            return false;
+        }
+    }
+    return true;
+};
+const SEQUENCE = /(?:\x1b\[|\x9b)([0-?]*)[ -/]*([@-~])|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+const UNFINISHED = /(?:\x1b(?:\[[0-?]*[ -/]*|\][^\x07]*)?|\x9b[0-?]*[ -/]*)$/;
+export const parseAnsi = (text, style = {}) => {
+    const runs = [];
+    let current = style;
+    let from = 0;
+    const push = (chunk) => {
+        if (chunk === '') {
+            return;
+        }
+        const last = runs.at(-1);
+        if (last && same(last, current)) {
+            last.text += chunk;
+        }
+        else {
+            runs.push(plain(current) ? { text: chunk } : { ...current, text: chunk });
+        }
+    };
+    const body = text.replace(UNFINISHED, '');
+    for (const match of body.matchAll(SEQUENCE)) {
+        push(body.slice(from, match.index));
+        from = match.index + match[0].length;
+        const [, parameters, final] = match;
+        if (final === 'm' && parameters !== undefined && !/[<=>?]/.test(parameters)) {
+            current = applySgr(current, parameters === '' ? [] : parameters.split(/[;:]/).map((code) => Number(code || 0)));
+        }
+    }
+    push(body.slice(from));
+    return { runs, style: current };
+};
+export const stripAnsi = (text) => text.replace(UNFINISHED, '').replace(SEQUENCE, '');

package/dist/log/buffer.d.ts

@@ -0,0 +1,99 @@
+import { type LogRun } from './ansi.js';
+/** How much a line matters, which a stylesheet draws and a screen reader may hear. */
+export type LogLevel = 'debug' | 'error' | 'info' | 'warn';
+/** Where a step of the run stands. */
+export type LogStatus = 'done' | 'failed' | 'pending' | 'running' | 'skipped';
+/** One line of output, as `lines` holds it and `parse` returns it. */
+export interface LogLine {
+    /** When it was written: milliseconds since the epoch, or anything `Date` parses. */
+    at?: number | string;
+    /** The `id` of the group in `groups` the line belongs to. */
+    group?: string;
+    /** How much it matters. Absent is `info`. */
+    level?: LogLevel;
+    /** What was written, with any ANSI escape codes still in it. */
+    text: string;
+}
+/** One step of the run, which folds the lines that name its `id`. */
+export interface LogGroup {
+    /** How long the step took, as it should read, such as `12s`. */
+    duration?: string;
+    /** What the step is called. */
+    heading: string;
+    /** What its lines name in `group`. */
+    id: string;
+    /**
+     * Whether it is open. Read the first time the log sees the group, and again
+     * whenever it changes, so a page can open the step that failed.
+     */
+    open?: boolean;
+    /** Where it stands. */
+    status?: LogStatus;
+}
+/**
+ * Reads one finished line of written text and says what it is.
+ *
+ * Return the fields to set, such as a `level` read off a prefix or a `group`
+ * read off a marker, and `text` to show something else. Return `null` to drop
+ * the line, such as a marker that only opens a group.
+ */
+export type LogParser = (text: string) => Partial<LogLine> | null | undefined;
+/**
+ * The text of a run, kept as lines.
+ *
+ * **Written text arrives in pieces that do not end at line breaks**, so the
+ * line still being written is held apart and shown as it stands, the way a
+ * terminal shows a prompt or a progress bar before its line ends. A line is
+ * finished by `\n` or `\r\n`.
+ *
+ * **A carriage return on its own starts the line over.** A progress bar is
+ * one line rewritten a hundred times, and drawing each rewrite as a line of
+ * its own is the failure every log viewer is judged by. The text after the
+ * last `\r` replaces the line. A terminal overwrites only as many characters
+ * as were written, so `abc\rxy` reads `xyc` there and `xy` here; a program
+ * that redraws a line writes the whole line, which reads the same in both.
+ *
+ * **Color carries from line to line**, as it does in a terminal, so a block
+ * that opens with green and closes many lines later is green throughout. It
+ * carries through text a carriage return replaced as well.
+ */
+export declare class LogBuffer {
+    /** The finished lines kept, oldest first. */
+    lines: LogLine[];
+    /** How many finished lines were let go from the start to stay within `limit`. */
+    dropped: number;
+    /** The most finished lines kept, or 0 to keep them all. */
+    limit: number;
+    /** Reads each finished line of written text. */
+    parse: LogParser | undefined;
+    /** The line still being written, as it reads now. */
+    private partial;
+    /** Whether the next text written starts the line over. */
+    private returned;
+    /** The style the line being written started in. */
+    private lineStyle;
+    /** The runs of each line, read once. */
+    private readonly runs;
+    /** The line `current` last returned, which stands until the text changes. */
+    private shown;
+    /**
+     * Adds text, finishing a line at every line break, and returns how many
+     * lines it finished.
+     */
+    write(chunk: string): number;
+    /** Replaces every line, starting a fresh buffer that keeps its `parse` and `limit`. */
+    replace(lines: readonly LogLine[]): void;
+    /** Lets every line go. */
+    clear(): void;
+    /** The line still being written, or undefined where the last line ended. */
+    current(): LogLine | undefined;
+    /**
+     * The runs a line is drawn in. A written line was read with the color the
+     * line before it left; a line handed over in `lines` starts plain.
+     */
+    runsOf(line: LogLine): LogRun[];
+    /** Finishes the line being written. */
+    private finish;
+    /** Lets the oldest lines go past `limit`, all at once. */
+    private trim;
+}

package/dist/log/buffer.js

@@ -0,0 +1,92 @@
+import { parseAnsi } from './ansi.js';
+export class LogBuffer {
+    constructor() {
+        this.lines = [];
+        this.dropped = 0;
+        this.limit = 0;
+        this.parse = undefined;
+        this.partial = '';
+        this.returned = false;
+        this.lineStyle = {};
+        this.runs = new WeakMap();
+        this.shown = undefined;
+    }
+    write(chunk) {
+        let finished = 0;
+        for (const token of chunk.split(/(\r\n|\n|\r)/)) {
+            if (token === '\n' || token === '\r\n') {
+                this.finish();
+                finished += 1;
+            }
+            else if (token === '\r') {
+                this.returned = true;
+            }
+            else if (token !== '') {
+                if (this.returned) {
+                    this.lineStyle = parseAnsi(this.partial, this.lineStyle).style;
+                    this.partial = token;
+                    this.returned = false;
+                }
+                else {
+                    this.partial += token;
+                }
+            }
+        }
+        this.trim();
+        return finished;
+    }
+    replace(lines) {
+        this.lines = [...lines];
+        this.dropped = 0;
+        this.partial = '';
+        this.returned = false;
+        this.lineStyle = {};
+        this.shown = undefined;
+        this.trim();
+    }
+    clear() {
+        this.replace([]);
+    }
+    current() {
+        if (this.partial === '') {
+            return undefined;
+        }
+        const group = this.lines.at(-1)?.group;
+        if (this.shown?.text !== this.partial || this.shown.group !== group) {
+            this.shown = group === undefined ? { text: this.partial } : { group, text: this.partial };
+        }
+        return this.shown;
+    }
+    runsOf(line) {
+        if (line === this.shown) {
+            return parseAnsi(line.text, this.lineStyle).runs;
+        }
+        const known = this.runs.get(line);
+        if (known) {
+            return known;
+        }
+        const { runs } = parseAnsi(line.text);
+        this.runs.set(line, runs);
+        return runs;
+    }
+    finish() {
+        const raw = this.partial;
+        const flow = parseAnsi(raw, this.lineStyle);
+        this.partial = '';
+        this.returned = false;
+        const read = this.parse?.(raw);
+        if (read !== null) {
+            const line = { ...read, text: read?.text ?? raw };
+            this.runs.set(line, line.text === raw ? flow.runs : parseAnsi(line.text, this.lineStyle).runs);
+            this.lines.push(line);
+        }
+        this.lineStyle = flow.style;
+    }
+    trim() {
+        const over = this.limit > 0 ? this.lines.length - this.limit : 0;
+        if (over > 0) {
+            this.lines.splice(0, over);
+            this.dropped += over;
+        }
+    }
+}

package/dist/log/group/log-group.d.ts

@@ -0,0 +1,78 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+import type { LogStatus } from '../buffer.js';
+declare const HelixHeadlessLogGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary One step of a log, which folds its lines under a heading with its status and how long it took.
+ *
+ * @description
+ * A group is a disclosure: its heading is a button that shows and hides the
+ * lines inside it, and says whether they are shown with `aria-expanded`. Put
+ * `Log.Line` elements inside it, and nest groups for steps within steps.
+ *
+ * `status` draws a mark before the heading, and a screen reader hears the
+ * status after the heading (`status-label`). `duration` stands at the end of
+ * the heading, as you write it, such as `12s`.
+ *
+ * A group starts shut. Write `default-open` on the step a reader should see,
+ * such as the one that failed.
+ *
+ * @since 0.199.0
+ * @status experimental
+ * @documentation https://fusion.dev/helix/components/log
+ *
+ * @slot - The lines of the step, and any groups inside it.
+ * @slot heading - The heading, where it holds more than text. Defaults to `heading`.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the group closes. Cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the group opens. Cancelable.
+ * @event {ToggleEvent} toggle - Fired after the group opens or closes, with `newState` and `oldState`.
+ *
+ * @csspart content - The lines, hidden while the group is shut.
+ * @csspart duration - How long the step took.
+ * @csspart heading - The heading.
+ * @csspart mark - The caret that turns as the group opens, an `<svg>` you size.
+ * @csspart status - The mark for the status, an `<svg>` you size.
+ * @csspart summary - The button that opens and closes the group.
+ *
+ * @cssstate open - The group shows its lines.
+ */
+export declare class HelixHeadlessLogGroup extends HelixHeadlessLogGroup_base {
+    protected static markRules: string[];
+    /** The key this family's words are registered under, its styled tag. */
+    static words: string;
+    /** How long the step took, as it should read, such as `12s`. */
+    duration: string;
+    /** What the step is called. The `heading` slot replaces it. */
+    heading: string;
+    /**
+     * @internal Set by a log that draws the group from data: the group stands
+     * for a heading alone, its lines being drawn beside it.
+     */
+    logDrawn: boolean;
+    /** Where the step stands, which draws a mark before the heading. */
+    status?: LogStatus;
+    /**
+     * @internal Read by the log to find its groups among its children, which is
+     * cheaper than `instanceof`.
+     */
+    readonly isLogGroup = true;
+    /**
+     * What a screen reader hears for the status, after the heading.
+     * `{status}` is one of `pending`, `running`, `done`, `failed`, and `skipped`.
+     */
+    statusLabel: string;
+    private readonly handlePress;
+    /**
+     * The words in the button are separated by spaces in the markup, since a
+     * name is read off inline boxes with nothing between them: without them a
+     * screen reader heard "Installfailed12s". A flex row draws none of them.
+     */
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-log-group': HelixHeadlessLogGroup;
+    }
+}
+export {};

package/dist/log/group/log-group.js

@@ -0,0 +1,76 @@
+import { __decorate } from "tslib";
+import { customElement, formatWords, HelixElement, MixinControllerOpen, SPOKEN_RULE, words, } from '@fusion.dev/helix-core';
+import { caretDown, checkCircleFill, circle, clock, minus, xCircleFill, } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+const MARKS = {
+    done: checkCircleFill,
+    failed: xCircleFill,
+    pending: circle,
+    running: clock,
+    skipped: minus,
+};
+let HelixHeadlessLogGroup = class HelixHeadlessLogGroup extends MixinControllerOpen(HelixElement) {
+    constructor() {
+        super(...arguments);
+        this.duration = '';
+        this.heading = '';
+        this.logDrawn = false;
+        this.isLogGroup = true;
+        this.statusLabel = '{status, select, pending {waiting} running {running} done {finished} failed {failed} skipped {skipped} other {}}';
+        this.handlePress = () => {
+            this.toggleOpen();
+        };
+    }
+    static { this.markRules = [SPOKEN_RULE]; }
+    static { this.words = 'helix-log'; }
+    render() {
+        const status = this.status;
+        return html `<button
+        part="summary"
+        id="summary"
+        type="button"
+        aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls=${this.logDrawn ? nothing : 'content'}
+        @click=${this.handlePress}
+      ><svg part="mark" aria-hidden="true" fill="currentColor" viewBox=${caretDown.viewBox}>
+          ${unsafeSVG(caretDown.content)}
+        </svg>${status && Object.hasOwn(MARKS, status)
+            ? html `<svg part="status" aria-hidden="true" fill="currentColor" viewBox=${MARKS[status].viewBox}>
+                ${unsafeSVG(MARKS[status].content)}
+              </svg>`
+            : nothing}<span part="heading"><slot name="heading">${this.heading}</slot></span>${status
+            ? html ` <span data-spoken>${formatWords(this, 'statusLabel', { status })}</span>`
+            : nothing}${this.duration === '' ? nothing : html ` <span part="duration">${this.duration}</span>`}</button
+      >${this.logDrawn
+            ? nothing
+            : html `<div
+              part="content"
+              id="content"
+              role="group"
+              aria-labelledby="summary"
+              ?hidden=${!this.open}
+            ><slot></slot></div>`}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessLogGroup.prototype, "duration", void 0);
+__decorate([
+    property()
+], HelixHeadlessLogGroup.prototype, "heading", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessLogGroup.prototype, "logDrawn", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessLogGroup.prototype, "status", void 0);
+__decorate([
+    words,
+    property({ attribute: 'status-label' })
+], HelixHeadlessLogGroup.prototype, "statusLabel", void 0);
+HelixHeadlessLogGroup = __decorate([
+    customElement('helix-headless-log-group')
+], HelixHeadlessLogGroup);
+export { HelixHeadlessLogGroup };

package/dist/log/index.d.ts

@@ -0,0 +1,5 @@
+export { type LogRun, type LogStyle, parseAnsi, stripAnsi } from './ansi.js';
+export type { LogGroup, LogLevel, LogLine, LogParser, LogStatus } from './buffer.js';
+export { HelixHeadlessLogGroup } from './group/log-group.js';
+export { HelixHeadlessLogLine, type LogTimes } from './line/log-line.js';
+export { HelixHeadlessLog, type LogScrollOptions, type LogSource } from './root/log-root.js';

package/dist/log/index.js

@@ -0,0 +1,4 @@
+export { parseAnsi, stripAnsi } from './ansi.js';
+export { HelixHeadlessLogGroup } from './group/log-group.js';
+export { HelixHeadlessLogLine } from './line/log-line.js';
+export { HelixHeadlessLog } from './root/log-root.js';