react-msaview 8.1.0 → 8.2.0

package/dist/expandSpec.d.ts

@@ -0,0 +1,46 @@
+import type { ColumnTrackSpec, Highlight, Region } from './types.ts';
+/**
+ * `row: null` opts one entry out of the spec's `query` row, back to alignment
+ * columns.
+ */
+type RowChoice = {
+    row?: string | null;
+};
+export type HighlightShorthand = number | string | (Omit<Highlight, 'row'> & RowChoice);
+export type RegionShorthand = string | (Omit<Region, 'row'> & RowChoice);
+export type ColumnTrackShorthand = Omit<ColumnTrackSpec, 'id' | 'kind' | 'row'> & RowChoice & {
+    id?: string;
+    kind?: ColumnTrackSpec['kind'];
+    /** the 1-based position `values` or `data` begins at */
+    start?: number;
+};
+/**
+ * The short forms a hand-written or generated link can use. Every long form
+ * passes through unchanged, so a snapshot is also a valid spec.
+ */
+export interface MsaSpec {
+    /**
+     * The row the spec is about: sets `relativeTo`, and is the `row` of every
+     * highlight, region and column track that names none
+     */
+    query?: string;
+    /** a url, or the alignment itself when it spans more than one line */
+    msa?: string;
+    /** a url, or a newick string when it starts with "(" */
+    tree?: string;
+    highlights?: HighlightShorthand[];
+    region?: RegionShorthand;
+    columnTracks?: ColumnTrackShorthand[];
+    [key: string]: unknown;
+}
+/**
+ * The label a single-residue shorthand highlight gets, filled in from the
+ * sequence when drawn: `175` on a row reading R there becomes "R175".
+ */
+export declare const residueLabel = "{residue}{position}";
+/**
+ * Expand the short forms of an MsaView spec into the snapshot the model takes.
+ * Idempotent, and a no-op on a spec that uses none of them.
+ */
+export declare function expandSpec(spec: MsaSpec): Record<string, unknown>;
+export {};

package/dist/expandSpec.js

@@ -0,0 +1,127 @@
+/**
+ * The label a single-residue shorthand highlight gets, filled in from the
+ * sequence when drawn: `175` on a row reading R there becomes "R175".
+ */
+export const residueLabel = '{residue}{position}';
+const span = /^(\d+)(?:-(\d+))?(?:\s+(.+))?$/;
+function parseSpan(text, what) {
+    const match = span.exec(text.trim());
+    if (!match) {
+        throw new Error(`${what} "${text}" is not "start", "start-end" or either followed by a label`);
+    }
+    const start = Number(match[1]);
+    const end = match[2] === undefined ? start : Number(match[2]);
+    return { start, end, label: match[3] };
+}
+function withRow(entry, query) {
+    const { row, ...rest } = entry;
+    const resolved = row === undefined ? query : (row ?? undefined);
+    return resolved === undefined ? rest : { ...rest, row: resolved };
+}
+function expandHighlight(entry, query) {
+    if (typeof entry === 'object') {
+        return (entry.rows
+            ? entry
+            : withRow(entry, entry.start === undefined ? undefined : query));
+    }
+    const { start, end, label } = parseSpan(String(entry), 'highlight');
+    const single = start === end && query !== undefined;
+    return {
+        ...(query === undefined ? {} : { row: query }),
+        start,
+        end,
+        ...(label ? { label } : single ? { label: residueLabel } : {}),
+    };
+}
+function expandRegion(region, query) {
+    if (typeof region === 'string') {
+        const { start, end } = parseSpan(region, 'region');
+        const parsed = { start, end };
+        return withRow(parsed, query);
+    }
+    return withRow(region, query);
+}
+function slug(name) {
+    return name
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, '-')
+        .replaceAll(/^-|-$/g, '');
+}
+function kindOf(track) {
+    if (track.kind) {
+        return track.kind;
+    }
+    if (track.values) {
+        return 'bar';
+    }
+    if (track.data !== undefined) {
+        return 'text';
+    }
+    if (track.arcs) {
+        return 'arc';
+    }
+    throw new Error(`column track "${track.name}" has no values, data or arcs to take its kind from`);
+}
+function expandTrack(track, query, ids) {
+    const { start, ...rest } = track;
+    const pad = start && start > 1 ? start - 1 : 0;
+    let id = track.id ?? (slug(track.name) || 'track');
+    for (let n = 2; !track.id && ids.has(id); n++) {
+        id = `${slug(track.name) || 'track'}-${n}`;
+    }
+    ids.add(id);
+    return {
+        ...withRow(rest, query),
+        id,
+        kind: kindOf(track),
+        ...(pad && track.values
+            ? { values: [...Array(pad).fill(0), ...track.values] }
+            : {}),
+        ...(pad && track.data !== undefined
+            ? { data: ' '.repeat(pad) + track.data }
+            : {}),
+    };
+}
+function isInlineMsa(msa) {
+    return msa.includes('\n');
+}
+function isInlineTree(tree) {
+    return tree.trimStart().startsWith('(');
+}
+function uri(location) {
+    return { uri: location, locationType: 'UriLocation' };
+}
+/**
+ * Expand the short forms of an MsaView spec into the snapshot the model takes.
+ * Idempotent, and a no-op on a spec that uses none of them.
+ */
+export function expandSpec(spec) {
+    const { query, msa, tree, highlights, region, columnTracks, ...rest } = spec;
+    const data = {
+        ...rest.data,
+        ...(msa !== undefined && isInlineMsa(msa) ? { msa } : {}),
+        ...(tree !== undefined && isInlineTree(tree) ? { tree } : {}),
+    };
+    const ids = new Set((columnTracks ?? []).map(t => t.id).filter(id => id !== undefined));
+    return {
+        ...rest,
+        ...(msa !== undefined && !isInlineMsa(msa)
+            ? { msaFilehandle: uri(msa) }
+            : {}),
+        ...(tree !== undefined && !isInlineTree(tree)
+            ? { treeFilehandle: uri(tree) }
+            : {}),
+        ...(Object.keys(data).length > 0 ? { data } : {}),
+        ...(query !== undefined && rest.relativeTo === undefined
+            ? { relativeTo: query }
+            : {}),
+        ...(highlights
+            ? { highlights: highlights.map(h => expandHighlight(h, query)) }
+            : {}),
+        ...(region === undefined ? {} : { region: expandRegion(region, query) }),
+        ...(columnTracks
+            ? { columnTracks: columnTracks.map(t => expandTrack(t, query, ids)) }
+            : {}),
+    };
+}
+//# sourceMappingURL=expandSpec.js.map

package/dist/expandSpec.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { renderToSvg } from './renderToSvg.tsx';
 export type { ExportSvgOptions } from './renderToSvg.tsx';
 export { CHAR_WIDTH_RATIO, installHeadlessRenderEnv, } from './headlessRenderEnv.ts';
 export { maxNeighborJoiningRows } from './constants.ts';
+export { expandSpec, residueLabel } from './expandSpec.ts';
+export type { ColumnTrackShorthand, HighlightShorthand, MsaSpec, RegionShorthand, } from './expandSpec.ts';
 export { default as MSAView } from './components/Loading.tsx';
 export { default as MSAViewer } from './components/MSAViewer.tsx';
 export type { MSAViewerProps } from './components/MSAViewer.tsx';

package/dist/index.js

@@ -14,6 +14,8 @@ export { CHAR_WIDTH_RATIO, installHeadlessRenderEnv, } from './headlessRenderEnv
 // the row count above which calculateNeighborJoiningTreeFromMSA throws, for
 // hosts gating their own menu item
 export { maxNeighborJoiningRows } from './constants.js';
+// the short forms a link or a script can write a view in; see docs/layers.md
+export { expandSpec, residueLabel } from './expandSpec.js';
 export { default as MSAView } from './components/Loading.js';
 export { default as MSAViewer } from './components/MSAViewer.js';
 export { mount } from './mount.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,yDAAyD;AACzD,6EAA6E;AAC7E,+DAA+D;AAC/D,gFAAgF;AAChF,0EAA0E;AAC1E,yEAAyE;AACzE,8EAA8E;AAC9E,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAmB,CAAA;AAE/C,8EAA8E;AAC9E,yDAAyD;AACzD,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA;AAC/B,4EAA4E;AAC5E,mCAAmC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,yBAA0B,CAAA;AAC7D,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,2BAA4B,CAAA;AAEjE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAa,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAGtD,OAAO,EAAqB,OAAO,IAAI,SAAS,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,yDAAyD;AACzD,6EAA6E;AAC7E,+DAA+D;AAC/D,gFAAgF;AAChF,0EAA0E;AAC1E,yEAAyE;AACzE,8EAA8E;AAC9E,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAmB,CAAA;AAE/C,8EAA8E;AAC9E,yDAAyD;AACzD,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA;AAC/B,4EAA4E;AAC5E,mCAAmC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,6EAA6E;AAC7E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAO1D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,yBAA0B,CAAA;AAC7D,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,2BAA4B,CAAA;AAEjE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAa,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAGtD,OAAO,EAAqB,OAAO,IAAI,SAAS,EAAE,MAAM,YAAY,CAAA"}

package/dist/model.d.ts

@@ -57,7 +57,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     colorSchemeName: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     showColumnStats: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     msaFormat: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<import("msa-parsers").MSAFormat>>;
-}, "allowedGappyness" | "clades" | "colWidth" | "collapsed" | "columnTracks" | "currentAlignment" | "data" | "drawMsaLetters" | "encodings" | "gffFilehandle" | "height" | "hideGaps" | "highlightColumns" | "highlights" | "id" | "msaFilehandle" | "relativeTo" | "residueMappings" | "rowHeight" | "rowPanels" | "scrollX" | "scrollY" | "scrollZoom" | "scrollZoomAxis" | "showDomainLegend" | "showDomains" | "showOnly" | "subFeatureRows" | "trackHeights" | "treeFilehandle" | "treeMetadataFilehandle" | "turnedOffFeatures" | "turnedOffTracks" | "type"> & {
+}, "allowedGappyness" | "clades" | "colWidth" | "collapsed" | "columnTracks" | "currentAlignment" | "data" | "drawMsaLetters" | "encodings" | "gffFilehandle" | "height" | "hideGaps" | "highlightColumns" | "highlights" | "id" | "msaFilehandle" | "region" | "relativeTo" | "residueMappings" | "rowHeight" | "rowPanels" | "scrollX" | "scrollY" | "scrollZoom" | "scrollZoomAxis" | "showDomainLegend" | "showDomains" | "showOnly" | "subFeatureRows" | "trackHeights" | "treeFilehandle" | "treeMetadataFilehandle" | "turnedOffFeatures" | "turnedOffTracks" | "type"> & {
     /**
      * #property
      * id of view, randomly generated if not provided
@@ -616,6 +616,14 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * Persists in the snapshot and the URL.
      */
     highlights: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IType<Highlight, Highlight, Highlight>>, [undefined]>;
+    /**
+     * #property
+     * where the view opens, in `highlights` coordinates: `{row, start,
+     * end}` zooms onto residues of that row, `{start, end}` onto alignment
+     * columns. Applied once the alignment and any tree file have loaded,
+     * then cleared, so a reloaded session keeps the reader's own scroll.
+     */
+    region: import("@jbrowse/mobx-state-tree").IType<Region | undefined, Region | undefined, Region | undefined>;
     /**
      * #property
      * clades of the tree with a mark drawn over them. `mrca` names tips
@@ -866,6 +874,10 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
      * through it.
      */
     setHighlightedColumns(columns?: number[]): void;
+    /**
+     * #action
+     */
+    setRegion(region?: Region): void;
     /**
      * #action
      */
@@ -1946,6 +1958,12 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         start: number;
         end: number;
     }[];
+    /**
+     * #method
+     * a highlight label with `{residue}` and `{position}` filled in from the
+     * row's letter at `start`, which is how the `175` shorthand draws "R175"
+     */
+    fillHighlightLabel(label: string, row?: string, start?: number): string;
     /**
      * #getter
      * `highlights` projected onto what is on screen: residue spans go
@@ -2203,6 +2221,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     relativeTo: string | undefined;
     highlightColumns: number[] | undefined;
     highlights: Highlight[];
+    region: Region | undefined;
     clades: Clade[];
     encodings: Encoding[];
     rowPanels: RowPanelSpec[];
@@ -2334,6 +2353,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
     relativeTo: string | undefined;
     highlightColumns: number[] | undefined;
     highlights: Highlight[];
+    region: Region | undefined;
     clades: Clade[];
     encodings: Encoding[];
     rowPanels: RowPanelSpec[];

package/dist/model.js

@@ -606,6 +606,14 @@ function stateModelFactory() {
          * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * where the view opens, in `highlights` coordinates: `{row, start,
+         * end}` zooms onto residues of that row, `{start, end}` onto alignment
+         * columns. Applied once the alignment and any tree file have loaded,
+         * then cleared, so a reloaded session keeps the reader's own scroll.
+         */
+        region: types.frozen(),
         /**
          * #property
          * clades of the tree with a mark drawn over them. `mrca` names tips
@@ -859,6 +867,12 @@ function stateModelFactory() {
         setHighlightedColumns(columns) {
             self.highlightedColumns = columns;
         },
+        /**
+         * #action
+         */
+        setRegion(region) {
+            self.region = region;
+        },
         /**
          * #action
          */
@@ -3064,6 +3078,23 @@ function stateModelFactory() {
             }
             return runs;
         },
+        /**
+         * #method
+         * a highlight label with `{residue}` and `{position}` filled in from the
+         * row's letter at `start`, which is how the `175` shorthand draws "R175"
+         */
+        fillHighlightLabel(label, row, start) {
+            if (!label.includes('{')) {
+                return label;
+            }
+            const col = row && start !== undefined
+                ? self.seqPosIndex(row)?.[start - 1]
+                : undefined;
+            const residue = row && col !== undefined ? (self.MSA?.getRow(row)[col] ?? '') : '';
+            return label
+                .replaceAll('{residue}', residue)
+                .replaceAll('{position}', start === undefined ? '' : String(start));
+        },
         /**
          * #getter
          * `highlights` projected onto what is on screen: residue spans go
@@ -3079,7 +3110,10 @@ function stateModelFactory() {
                 ...Object.values(transientHighlights).flat(),
             ];
             return all.flatMap(({ row, rows, start, end, label, color }) => {
-                const base = { label, color };
+                const base = {
+                    label: label && this.fillHighlightLabel(label, row, start),
+                    color,
+                };
                 if (rows) {
                     const rowIndices = rows
                         .map(name => rowNamesSet.get(name))
@@ -3460,6 +3494,19 @@ function stateModelFactory() {
                     }
                 }
             }));
+            // zoomToRegion needs a width and resolves residues through the visible
+            // columns, so this waits for both, and for a tree file whose collapsed
+            // clades would hide columns and move the target after the zoom
+            addDisposer(self, autorun(() => {
+                const { region } = self;
+                if (region &&
+                    self.viewInitialized &&
+                    self.numColumns > 0 &&
+                    !(self.treeFilehandle && !self.data.tree)) {
+                    this.zoomToRegion(region);
+                    self.setRegion(undefined);
+                }
+            }));
             // the matchMedia query is pinned to the current device pixel ratio, so
             // each change re-registers against the new one
             if (typeof window !== 'undefined' &&