@aceshooting/lyra-ui 3.7.0 → 3.8.0

package/dist/internal/anchor-target.js

@@ -0,0 +1,255 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from './lyra-element.js';
+import { normalizeQuoteText, scopeFromElement, buildQuoteAnchor } from './text-quote.js';
+export const ANCHOR_RETRY_INTERVAL_MS = 250;
+export const ANCHOR_TIMEOUT_MS = 5000;
+function selectionRange(root) {
+    const shadowRoot = root.renderRoot instanceof ShadowRoot ? root.renderRoot : undefined;
+    const globalSelection = (typeof window !== 'undefined' ? window.getSelection() : null);
+    if (globalSelection?.getComposedRanges && shadowRoot) {
+        const [composed] = globalSelection.getComposedRanges({ shadowRoots: [shadowRoot] });
+        if (!composed)
+            return null;
+        if (composed.startContainer === composed.endContainer && composed.startOffset === composed.endOffset)
+            return null;
+        const range = document.createRange();
+        range.setStart(composed.startContainer, composed.startOffset);
+        range.setEnd(composed.endContainer, composed.endOffset);
+        return range;
+    }
+    const shadowSelection = shadowRoot?.getSelection?.();
+    const selection = shadowSelection ?? globalSelection;
+    if (!selection || selection.rangeCount === 0 || selection.isCollapsed)
+        return null;
+    return selection.getRangeAt(0);
+}
+/**
+ * Mixin that turns a `LyraElement` subclass into an anchor-target viewer: adds
+ * `highlights`/`activeHighlightId`/`anchor`/`anchorKinds`, `scrollToAnchor()` with a generation-
+ * guarded retry-until-loaded loop, `lyra-highlight-activate`/`lyra-text-select`/`lyra-anchor-result`
+ * event plumbing, and `bindTextSelection()` for selection->anchor emission. Same `Constructor<T>`
+ * mixin shape as `internal/strip-host-title.ts`; bound to `LyraElement` (not plain `LitElement`)
+ * because this mixin needs `this.emit()`/`this.localize()`/`this.scheduleAfterUpdate()`.
+ *
+ * Per-viewer hooks a subclass overrides: `applyAnchor(anchor)` (default declines everything) and
+ * `computeSelectionAnchor(range, text)` (default: a `text-quote` anchor built from the whole render
+ * root's text via `internal/text-quote.ts` -- a viewer with a narrower/paginated content root, e.g.
+ * pdf, overrides this for a page-scoped scope).
+ *
+ * The return type's trailing `{ renderAnchorLiveRegion(): unknown }` intersection member is the one
+ * mixin hook every real adopting viewer calls but none needs to *override* (`applyAnchor`/
+ * `computeSelectionAnchor`/`bindTextSelection` are only ever overridden, never called directly by a
+ * subclass, so a subclass's own `protected` re-declaration of one of those is a brand-new member as
+ * far as this narrowed return type is concerned -- no conflict). Without it, a real subclass's own
+ * `render()` calling `this.renderAnchorLiveRegion()` fails to type-check with "property does not
+ * exist", since TypeScript can't emit a `.d.ts` declaration for this generic function's *inferred*
+ * return type (a class expression with `protected` members, TS4094) and this annotation is what
+ * replaces that inference -- narrowed to just the public `LyraAnchorTarget` contract plus this one
+ * called-not-overridden method.
+ */
+export function DocumentAnchorTarget(Base) {
+    class DocumentAnchorTargetElement extends Base {
+        constructor() {
+            super(...arguments);
+            this.highlights = [];
+            this.activeHighlightId = null;
+            // `hasChanged: () => true` -- re-assigning the SAME anchor (e.g. re-clicking the same citation
+            // badge twice) must still re-run scrollToAnchor/re-flash; Lit's default reference-equality
+            // `hasChanged` would otherwise silently swallow the second, identical assignment.
+            this.anchor = null;
+            /** Instance capability mirror; overridden per adopting viewer (e.g. pdf-viewer sets `['page',
+             *  'text-quote', 'region']`) so a standalone element is feature-detectable without the
+             *  document-viewer registry. */
+            this.anchorKinds = [];
+            /** Real-timer thresholds for the retry loop, exposed as overridable instance fields (not module
+             *  constants) so tests can shrink them instead of waiting out the real 5s timeout. */
+            this.anchorRetryIntervalMs = ANCHOR_RETRY_INTERVAL_MS;
+            this.anchorTimeoutMs = ANCHOR_TIMEOUT_MS;
+            this.anchorAnnouncementText = '';
+            this.anchorGeneration = 0;
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            if (changed.has('anchor') && this.anchor !== null) {
+                void this.scrollToAnchor(this.anchor);
+            }
+        }
+        disconnectedCallback() {
+            // Bump the generation first so an in-flight retry loop's post-cancel generation check (see
+            // `resolveWithRetry`) reliably observes staleness and stops instead of scheduling another
+            // retry against a detached element.
+            this.anchorGeneration++;
+            this.cancelAnchorRetry();
+            this.selectionCleanup?.();
+            this.selectionCleanup = undefined;
+            super.disconnectedCallback();
+        }
+        /** Per-viewer hook: attempts to resolve+scroll to one raw anchor, returning whether it
+         *  succeeded. Default declines everything -- every real adopting viewer overrides this. */
+        async applyAnchor(_anchor) {
+            return false;
+        }
+        /** Per-viewer hook building a `LyraAnchor` from an ended selection. Default: a `text-quote`
+         *  anchor from the whole render root's rendered text. */
+        computeSelectionAnchor(range, _text) {
+            const scope = scopeFromElement(this.renderRoot);
+            return buildQuoteAnchor(range, scope);
+        }
+        /** Clears any outstanding retry wait, both the underlying timer and (crucially) the `Promise`
+         *  a `resolveWithRetry()` loop is currently suspended on -- `clearTimeout()` alone would stop
+         *  the timer from firing without ever settling that `Promise`, leaving the suspended loop
+         *  (and the `scrollToAnchor()` call awaiting it) hung forever instead of observing the
+         *  generation guard and unwinding. */
+        cancelAnchorRetry() {
+            if (this.anchorRetryHandle !== undefined) {
+                clearTimeout(this.anchorRetryHandle);
+                this.anchorRetryHandle = undefined;
+            }
+            const resolveWait = this.anchorRetryResolve;
+            if (resolveWait) {
+                this.anchorRetryResolve = undefined;
+                resolveWait();
+            }
+        }
+        async scrollToAnchor(target) {
+            // Bump the generation *before* cancelling the previous retry wait -- cancellation resolves
+            // a suspended `resolveWithRetry()` loop's pending Promise from a superseded call, scheduling
+            // that loop's continuation (a microtask) to re-check the generation next. Bumping first
+            // guarantees that check always sees the new value: it can only run after this call's own
+            // synchronous statements finish, by which point the bump has already happened either way.
+            const generation = ++this.anchorGeneration;
+            this.cancelAnchorRetry();
+            await this.updateComplete;
+            if (generation !== this.anchorGeneration)
+                return false;
+            const highlightId = typeof target === 'string' ? target : undefined;
+            const anchor = typeof target === 'string' ? this.highlights.find((h) => h.id === target)?.anchor : target;
+            if (!anchor) {
+                // An unresolvable highlight id still reports a definite (negative) result instead of
+                // leaving a caller's `lyra-anchor-result` listener waiting indefinitely.
+                this.announceAnchorResult(undefined, false);
+                this.emit('lyra-anchor-result', { found: false });
+                return false;
+            }
+            const ok = await this.resolveWithRetry(anchor, generation);
+            if (generation !== this.anchorGeneration)
+                return false;
+            if (ok && highlightId)
+                this.activeHighlightId = highlightId;
+            this.announceAnchorResult(anchor, ok);
+            this.emit('lyra-anchor-result', { found: ok });
+            return ok;
+        }
+        async resolveWithRetry(anchor, generation) {
+            const deadline = Date.now() + this.anchorTimeoutMs;
+            for (;;) {
+                if (generation !== this.anchorGeneration)
+                    return false;
+                const ok = await this.applyAnchor(anchor);
+                if (generation !== this.anchorGeneration)
+                    return false;
+                if (ok)
+                    return true;
+                if (Date.now() >= deadline)
+                    return false;
+                await new Promise((resolve) => {
+                    this.anchorRetryResolve = resolve;
+                    this.anchorRetryHandle = setTimeout(() => {
+                        this.anchorRetryHandle = undefined;
+                        this.anchorRetryResolve = undefined;
+                        resolve();
+                    }, this.anchorRetryIntervalMs);
+                });
+            }
+        }
+        announceAnchorResult(anchor, found) {
+            if (!found || !anchor) {
+                this.announce(this.localize('anchorNotFound'));
+                return;
+            }
+            const page = 'page' in anchor ? anchor.page : undefined;
+            this.announce(page != null ? this.localize('anchorJumpedToPage', undefined, { page }) : this.localize('anchorJumped'));
+        }
+        announce(text) {
+            // Force a DOM text change even for an identical back-to-back announcement (e.g. re-activating
+            // the same citation) -- a live region only announces on text *change*.
+            this.anchorAnnouncementText = this.anchorAnnouncementText === text ? `${text}​` : text;
+        }
+        /** Renders the visually-hidden live region carrying anchor-jump announcements. Adopting viewers
+         *  include this once in their own `render()` output -- the mixin doesn't own `render()` itself,
+         *  matching how `components/graph/graph.class.ts` hand-rolls its own equivalent
+         *  `[part="live-region"]` without a mixin. Deliberately not `protected`: unlike the other mixin
+         *  hooks, a real adopting viewer's own `render()` *calls* this directly rather than overriding it,
+         *  and the mixin's exported return-type annotation needs it visible for that call to type-check
+         *  (see this file's `DocumentAnchorTarget` doc comment). */
+        renderAnchorLiveRegion() {
+            return html `<div
+        part="anchor-live-region"
+        class="sr-only"
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+      >${this.anchorAnnouncementText}</div>`;
+        }
+        /** Attaches selection-end listeners to `contentRoot` and emits `lyra-text-select` on a
+         *  non-collapsed selection ending inside it. Reads the selection shadow-aware: composed ranges
+         *  where `Selection.getComposedRanges()` exists, `ShadowRoot.getSelection()` next, else
+         *  `document.getSelection()`. Collapsed selections never fire. */
+        bindTextSelection(contentRoot) {
+            this.selectionCleanup?.();
+            const onSelectionEnd = () => {
+                const range = selectionRange(this);
+                if (!range)
+                    return;
+                if (!contentRoot.contains(range.commonAncestorContainer) && range.commonAncestorContainer !== contentRoot)
+                    return;
+                const text = normalizeQuoteText(range.toString());
+                if (!text)
+                    return;
+                const anchor = this.computeSelectionAnchor(range, text);
+                const rects = Array.from(range.getClientRects());
+                this.emit('lyra-text-select', { text, anchor, rects });
+            };
+            let debounceHandle;
+            const onSelectionChange = () => {
+                if (debounceHandle !== undefined)
+                    cancelAnimationFrame(debounceHandle);
+                debounceHandle = requestAnimationFrame(() => {
+                    debounceHandle = undefined;
+                    onSelectionEnd();
+                });
+            };
+            contentRoot.addEventListener('pointerup', onSelectionEnd);
+            contentRoot.addEventListener('keyup', onSelectionEnd);
+            document.addEventListener('selectionchange', onSelectionChange);
+            this.selectionCleanup = () => {
+                contentRoot.removeEventListener('pointerup', onSelectionEnd);
+                contentRoot.removeEventListener('keyup', onSelectionEnd);
+                document.removeEventListener('selectionchange', onSelectionChange);
+                if (debounceHandle !== undefined)
+                    cancelAnimationFrame(debounceHandle);
+            };
+        }
+    }
+    __decorate([
+        property({ attribute: false })
+    ], DocumentAnchorTargetElement.prototype, "highlights", void 0);
+    __decorate([
+        property({ attribute: 'active-highlight-id' })
+    ], DocumentAnchorTargetElement.prototype, "activeHighlightId", void 0);
+    __decorate([
+        property({ attribute: false, hasChanged: () => true })
+    ], DocumentAnchorTargetElement.prototype, "anchor", void 0);
+    __decorate([
+        state()
+    ], DocumentAnchorTargetElement.prototype, "anchorAnnouncementText", void 0);
+    return DocumentAnchorTargetElement;
+}
+//# sourceMappingURL=anchor-target.js.map

package/dist/internal/anchor-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor-target.js","sourceRoot":"","sources":["../../src/internal/anchor-target.ts"],"names":[],"mappings":"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"}

package/dist/internal/ansi.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Dependency-free ANSI/SGR (`CSI … m`) parser for rendering streamed console/terminal output as
+ * styled text segments — shared by any component that needs to turn raw ANSI-colored text into
+ * styled segments, rather than re-implementing this per consumer. Handles only SGR color/style
+ * codes; every other CSI final byte and every OSC sequence is stripped and never interpreted.
+ * Cursor/line-buffer control characters (`\r`/`\b`/`\t`/`\n`) are deliberately out of scope here —
+ * they are a terminal-emulation concern owned by the consuming component, not this parser.
+ */
+export interface AnsiStyles {
+    bold: boolean;
+    dim: boolean;
+    italic: boolean;
+    underline: boolean;
+    inverse: boolean;
+    /** A CSS color value: `var(--lyra-terminal-color-*)` for the 16 named colors (including the
+     *  16-named subset of 256-color mode), or a literal `rgb()` for 256-color indices 16-255 and
+     *  truecolor. These colors are driven by arbitrary terminal output content, not the design-token
+     *  palette, so a literal CSS color value here is intentional rather than a hardcoded default. */
+    fg?: string;
+    bg?: string;
+}
+export interface AnsiSegment {
+    text: string;
+    styles: AnsiStyles;
+}
+export interface AnsiParser {
+    /** Feeds `chunk` through the parser, returning the styled text segments it produced. A partial
+     *  escape sequence at the end of `chunk` is buffered internally and completed by a later `push()`
+     *  call rather than emitted as literal text. */
+    push(chunk: string): AnsiSegment[];
+    /** Clears style state and any buffered partial sequence — call alongside a full scrollback reset. */
+    reset(): void;
+}
+export declare function createAnsiParser(): AnsiParser;
+//# sourceMappingURL=ansi.d.ts.map

package/dist/internal/ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../../src/internal/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB;;;qGAGiG;IACjG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB;;oDAEgD;IAChD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACnC,qGAAqG;IACrG,KAAK,IAAI,IAAI,CAAC;CACf;AAuED,wBAAgB,gBAAgB,IAAI,UAAU,CA8H7C"}

package/dist/internal/ansi.js

@@ -0,0 +1,210 @@
+/**
+ * Dependency-free ANSI/SGR (`CSI … m`) parser for rendering streamed console/terminal output as
+ * styled text segments — shared by any component that needs to turn raw ANSI-colored text into
+ * styled segments, rather than re-implementing this per consumer. Handles only SGR color/style
+ * codes; every other CSI final byte and every OSC sequence is stripped and never interpreted.
+ * Cursor/line-buffer control characters (`\r`/`\b`/`\t`/`\n`) are deliberately out of scope here —
+ * they are a terminal-emulation concern owned by the consuming component, not this parser.
+ */
+const RESET_STYLES = {
+    bold: false,
+    dim: false,
+    italic: false,
+    underline: false,
+    inverse: false,
+};
+const ANSI_16_VAR_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',
+];
+function ansiVar(index) {
+    return `var(--lyra-terminal-color-${ANSI_16_VAR_NAMES[index]})`;
+}
+const FG_VARS = {};
+const BG_VARS = {};
+for (let i = 0; i < 8; i++) {
+    FG_VARS[30 + i] = ansiVar(i);
+    FG_VARS[90 + i] = ansiVar(8 + i);
+    BG_VARS[40 + i] = ansiVar(i);
+    BG_VARS[100 + i] = ansiVar(8 + i);
+}
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+function clampByte(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.min(255, Math.max(0, Math.round(n)));
+}
+/** xterm 256-color palette: 0-15 resolve to the same 16 named/retheme-able vars as the base SGR
+ *  codes (so an extended-color sequence picking "red" still retheme with the palette); 16-231 are
+ *  the 6x6x6 color cube; 232-255 are the grayscale ramp. */
+function ansi256ToColor(n) {
+    if (!Number.isInteger(n) || n < 0)
+        return ansiVar(0);
+    if (n < 16)
+        return ansiVar(n);
+    if (n <= 231) {
+        const i = n - 16;
+        const r = CUBE_LEVELS[Math.floor(i / 36) % 6];
+        const g = CUBE_LEVELS[Math.floor(i / 6) % 6];
+        const b = CUBE_LEVELS[i % 6];
+        return `rgb(${r}, ${g}, ${b})`;
+    }
+    if (n <= 255) {
+        const v = 8 + (n - 232) * 10;
+        return `rgb(${v}, ${v}, ${v})`;
+    }
+    return ansiVar(0);
+}
+const CSI_FINAL_BYTE = /[\x40-\x7e]/;
+export function createAnsiParser() {
+    let styles = { ...RESET_STYLES };
+    /** A partial escape sequence (starting at its ESC byte) left over from a previous `push()` whose
+     *  terminator hadn't arrived yet. */
+    let carry = '';
+    function applySgr(params) {
+        const list = params.length === 0 ? [0] : params;
+        let i = 0;
+        while (i < list.length) {
+            const p = list[i];
+            if (p === 0)
+                styles = { ...RESET_STYLES };
+            else if (p === 1)
+                styles = { ...styles, bold: true };
+            else if (p === 2)
+                styles = { ...styles, dim: true };
+            else if (p === 3)
+                styles = { ...styles, italic: true };
+            else if (p === 4)
+                styles = { ...styles, underline: true };
+            else if (p === 7)
+                styles = { ...styles, inverse: true };
+            else if (p === 22)
+                styles = { ...styles, bold: false, dim: false };
+            else if (p === 23)
+                styles = { ...styles, italic: false };
+            else if (p === 24)
+                styles = { ...styles, underline: false };
+            else if (p === 27)
+                styles = { ...styles, inverse: false };
+            else if (p === 39)
+                styles = { ...styles, fg: undefined };
+            else if (p === 49)
+                styles = { ...styles, bg: undefined };
+            else if (FG_VARS[p] !== undefined)
+                styles = { ...styles, fg: FG_VARS[p] };
+            else if (BG_VARS[p] !== undefined)
+                styles = { ...styles, bg: BG_VARS[p] };
+            else if (p === 38 || p === 48) {
+                const isFg = p === 38;
+                const mode = list[i + 1];
+                if (mode === 5 && list[i + 2] !== undefined) {
+                    const color = ansi256ToColor(list[i + 2]);
+                    styles = isFg ? { ...styles, fg: color } : { ...styles, bg: color };
+                    i += 2;
+                }
+                else if (mode === 2 && list[i + 4] !== undefined) {
+                    const color = `rgb(${clampByte(list[i + 2])}, ${clampByte(list[i + 3])}, ${clampByte(list[i + 4])})`;
+                    styles = isFg ? { ...styles, fg: color } : { ...styles, bg: color };
+                    i += 4;
+                }
+                // An unrecognized extended-color mode (anything other than 5 or 2) is left unapplied and
+                // simply falls through to the next param, same as any other unrecognized SGR code below.
+            }
+            // Any other numeric param (e.g. blink, unsupported codes) has no mapped style and is skipped.
+            i++;
+        }
+    }
+    function push(chunk) {
+        const input = carry + chunk;
+        carry = '';
+        const segments = [];
+        let textStart = 0;
+        let i = 0;
+        while (i < input.length) {
+            if (input.charCodeAt(i) !== 0x1b) {
+                i++;
+                continue;
+            }
+            if (i > textStart)
+                segments.push({ text: input.slice(textStart, i), styles });
+            const next = input[i + 1];
+            if (next === undefined) {
+                // ESC is the last byte of this chunk -- whether a '[' or ']' follows isn't knowable
+                // until the next push(), so buffer it rather than dropping it as an unrecognized
+                // sequence (matches the incomplete-CSI/OSC buffering below).
+                carry = input.slice(i);
+                return segments;
+            }
+            if (next === '[') {
+                let j = i + 2;
+                while (j < input.length && !CSI_FINAL_BYTE.test(input[j]))
+                    j++;
+                if (j >= input.length) {
+                    carry = input.slice(i);
+                    return segments;
+                }
+                if (input[j] === 'm') {
+                    const paramText = input.slice(i + 2, j);
+                    const params = paramText === '' ? [0] : paramText.split(';').map((s) => (s === '' ? 0 : Number(s)));
+                    applySgr(params);
+                }
+                // Any other CSI final byte (cursor move, erase, scroll, ...) is stripped without being
+                // interpreted -- the consuming component owns cursor/line-buffer control on its own.
+                i = j + 1;
+                textStart = i;
+                continue;
+            }
+            if (next === ']') {
+                let j = i + 2;
+                let terminated = false;
+                while (j < input.length) {
+                    if (input.charCodeAt(j) === 0x07) {
+                        j++;
+                        terminated = true;
+                        break;
+                    }
+                    if (input.charCodeAt(j) === 0x1b && input[j + 1] === '\\') {
+                        j += 2;
+                        terminated = true;
+                        break;
+                    }
+                    j++;
+                }
+                if (!terminated) {
+                    carry = input.slice(i);
+                    return segments;
+                }
+                i = j;
+                textStart = i;
+                continue;
+            }
+            // An ESC not followed by '[' or ']' isn't a sequence this parser recognizes -- drop just the
+            // ESC byte and resume scanning plain text right after it.
+            i += 1;
+            textStart = i;
+        }
+        if (textStart < input.length)
+            segments.push({ text: input.slice(textStart), styles });
+        return segments;
+    }
+    function reset() {
+        styles = { ...RESET_STYLES };
+        carry = '';
+    }
+    return { push, reset };
+}
+//# sourceMappingURL=ansi.js.map

package/dist/internal/ansi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.js","sourceRoot":"","sources":["../../src/internal/ansi.ts"],"names":[],"mappings":"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"}

package/dist/internal/cell-range.d.ts

@@ -0,0 +1,19 @@
+/** A parsed A1-notation cell range. Rows/columns are 0-based and normalized so `start <= end`. */
+export interface ParsedCellRange {
+    sheet?: string;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+/**
+ * Parses an A1-notation cell or cell-range reference, tolerating an optional `Sheet name!` prefix
+ * (quoted with single quotes when the name contains a space), `$` absolute markers, and lowercase
+ * column letters. Whole-row (`3:7`) and whole-column (`A:A`) references are unsupported this round
+ * and return `null` -- a bare `parseCellRef()` failure on either half of the range means neither
+ * looks like a real single-cell reference.
+ */
+export declare function parseCellRange(input: string): ParsedCellRange | null;
+/** Inverse of `parseCellRange()` -- builds an A1-notation string for a `LyraAnchor` of kind `cell-range`. */
+export declare function formatCellRange(range: ParsedCellRange): string;
+//# sourceMappingURL=cell-range.d.ts.map

package/dist/internal/cell-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-range.d.ts","sourceRoot":"","sources":["../../src/internal/cell-range.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AA8BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA2BpE;AAED,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAK9D"}

package/dist/internal/cell-range.js

@@ -0,0 +1,69 @@
+const CELL_REF_RE = /^\$?([A-Za-z]+)\$?(\d+)$/;
+/** Bijective base-26 column letters ('A' = 0, 'Z' = 25, 'AA' = 26, ...) to a 0-based index. */
+function columnToIndex(letters) {
+    let n = 0;
+    for (const ch of letters.toUpperCase()) {
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    }
+    return n - 1;
+}
+function indexToColumn(index) {
+    let n = index + 1;
+    let letters = '';
+    while (n > 0) {
+        const remainder = (n - 1) % 26;
+        letters = String.fromCharCode(65 + remainder) + letters;
+        n = Math.floor((n - 1) / 26);
+    }
+    return letters;
+}
+function parseCellRef(ref) {
+    const match = CELL_REF_RE.exec(ref.trim());
+    if (!match)
+        return null;
+    return { row: Number(match[2]) - 1, col: columnToIndex(match[1]) };
+}
+/**
+ * Parses an A1-notation cell or cell-range reference, tolerating an optional `Sheet name!` prefix
+ * (quoted with single quotes when the name contains a space), `$` absolute markers, and lowercase
+ * column letters. Whole-row (`3:7`) and whole-column (`A:A`) references are unsupported this round
+ * and return `null` -- a bare `parseCellRef()` failure on either half of the range means neither
+ * looks like a real single-cell reference.
+ */
+export function parseCellRange(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    let sheet;
+    let rest = trimmed;
+    const bangIndex = rest.lastIndexOf('!');
+    if (bangIndex !== -1) {
+        const rawSheet = rest.slice(0, bangIndex).trim();
+        sheet = rawSheet.startsWith("'") && rawSheet.endsWith("'") ? rawSheet.slice(1, -1) : rawSheet;
+        rest = rest.slice(bangIndex + 1);
+    }
+    const parts = rest.split(':');
+    if (parts.length > 2)
+        return null;
+    const first = parseCellRef(parts[0]);
+    if (!first)
+        return null;
+    const second = parts.length === 2 ? parseCellRef(parts[1]) : first;
+    if (!second)
+        return null;
+    return {
+        ...(sheet ? { sheet } : {}),
+        startRow: Math.min(first.row, second.row),
+        endRow: Math.max(first.row, second.row),
+        startCol: Math.min(first.col, second.col),
+        endCol: Math.max(first.col, second.col),
+    };
+}
+/** Inverse of `parseCellRange()` -- builds an A1-notation string for a `LyraAnchor` of kind `cell-range`. */
+export function formatCellRange(range) {
+    const start = `${indexToColumn(range.startCol)}${range.startRow + 1}`;
+    const end = `${indexToColumn(range.endCol)}${range.endRow + 1}`;
+    const body = start === end ? start : `${start}:${end}`;
+    return range.sheet ? `${range.sheet}!${body}` : body;
+}
+//# sourceMappingURL=cell-range.js.map

package/dist/internal/cell-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-range.js","sourceRoot":"","sources":["../../src/internal/cell-range.ts"],"names":[],"mappings":"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"}