linked-rolls 0.57.0 → 0.59.0

package/lib/ops/copies.js

@@ -0,0 +1,135 @@
+import { v4 } from "uuid";
+import { asSymbols, barOf, featuresOf, isPaperStretch } from "../model/RollCopy.js";
+import { systemOf } from "../systems/TrackerBar.js";
+import { applyShift, applyScale, revertShift, revertScale, revertShortening, shortenChains } from "../collation/alignment.js";
+import { idOf } from "../model/Assumption.js";
+import { onCopy, stateOf, insertion, insertedIn, referenceHeld, withoutReferences } from "./draft.js";
+import { without } from "./immutable.js";
+import { featureIdsOf, carriedOnlyOn, forgetFeatures } from "./forget.js";
+/**
+ * Puts the copy into the edition with a version of its own, which
+ * inserts every symbol the copy's own tracker bar reads on it. The
+ * version is a reading in that system's words, so it is coded for the
+ * system the copy was cut for.
+ */
+export const createVersion = (copy) => draft => {
+    const bar = barOf(copy);
+    draft.copies.push(copy);
+    draft.versions.push({
+        id: v4(),
+        system: systemOf(bar),
+        edits: asSymbols(featuresOf(copy), bar).map(insertion),
+        motivations: []
+    });
+};
+/**
+ * Puts the copy into the edition without a version of its own, as for a
+ * copy whose features are not read into symbols: one known only from a
+ * recording states instead which versions it carries.
+ */
+export const addCopy = (copy) => draft => {
+    draft.copies.push(copy);
+};
+/** States what the scale is put down to, in place of an earlier reading. */
+const readScale = (copy, reading) => {
+    if (reading.cause === 'paper') {
+        copy.conditions = [...copy.conditions.filter(condition => !isPaperStretch(condition)), reading.condition];
+        return;
+    }
+    if (!copy.production)
+        copy.production = {};
+    copy.production.speed = reading.speed;
+};
+/**
+ * Shifts and then scales the copy's features into line with another
+ * copy's, and puts the scale down to what the reading says: the paper,
+ * or the speed the copy was cut for.
+ */
+export const alignCopy = (copyId, shift, scale, reading) => onCopy(copyId, copy => {
+    applyShift(shift, copy);
+    applyScale(scale, copy);
+    if (reading)
+        readScale(copy, reading);
+});
+/**
+ * Puts the copy's features back where they were measured. A paper
+ * stretch read off the alignment goes with it; a speed stated stays,
+ * being a fact about the copy.
+ */
+export const unalignCopy = (copyId) => onCopy(copyId, copy => {
+    revertScale(copy);
+    revertShift(copy);
+    copy.conditions = without(copy.conditions, isPaperStretch);
+});
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's chains of holes, and records how much was taken, so that their lengths
+ * can be compared with a scanned copy's at all.
+ */
+export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenChains(extension, copy, leaving));
+/** Puts the reader's extension back on the copy's chains of holes. */
+export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
+/** States what the copy's features were read from, in place of any earlier statement. */
+export const stateSource = (copyId, source) => onCopy(copyId, copy => {
+    copy.readFrom = source;
+});
+/** Takes back the statement, leaving the copy silent about its source again. */
+export const clearSource = (copyId) => onCopy(copyId, copy => {
+    copy.readFrom = undefined;
+});
+/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+export const nameCopy = (copyId, siglum) => onCopy(copyId, copy => {
+    const trimmed = siglum.trim();
+    if (trimmed)
+        copy.siglum = trimmed;
+    else
+        delete copy.siglum;
+});
+/** Takes out the copy's statements that match, and the list itself where none is left. */
+export const dropStatements = (copy, matches) => {
+    const statements = stateOf(copy).carries;
+    if (!statements?.some(matches))
+        return;
+    const kept = withoutReferences(statements, matches);
+    if (kept)
+        copy.carries = kept;
+    else
+        delete copy.carries;
+};
+/**
+ * States that the copy carries the version, under the belief given. It
+ * is meant for a copy whose features are not read into symbols, such as
+ * one known only from a recording, and `carriageProblems` reports it
+ * where features carry symbols already. A second statement about one
+ * version is none.
+ */
+export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy => {
+    const statements = stateOf(copy).carries ?? [];
+    if (statements.some(statement => idOf(statement) === versionId))
+        return;
+    copy.carries = [...statements, referenceHeld(versionId, belief)];
+});
+/** Takes back the copy's statement that it carries the version. */
+export const clearCarriage = (copyId, versionId) => onCopy(copyId, copy => dropStatements(copy, statement => idOf(statement) === versionId));
+/**
+ * Adds a general condition to the copy, beside whatever is stated of it
+ * already. The other condition a copy may be in, a paper stretch, is
+ * read off an alignment and stated by `alignCopy`.
+ */
+export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy => {
+    copy.conditions.push(condition);
+});
+/** The symbols of the versions that no other copy carries. */
+export const symbolsCarriedOnlyBy = (edition, copyId) => {
+    const copy = edition.copies.find(c => c.id === copyId);
+    return copy ? insertedIn(edition.versions).filter(carriedOnlyOn(featureIdsOf(copy))) : [];
+};
+/**
+ * Takes the copy out of the edition together with the symbols only it
+ * carries, and with every reference the versions and the argumentations
+ * made to those symbols.
+ */
+export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
+    forgetFeatures(draft, featureIdsOf(copy));
+    draft.copies = draft.copies.filter(c => c.id !== copyId);
+});

package/lib/ops/draft.d.ts

@@ -0,0 +1,59 @@
+import { EditionView } from "../view/EditionView.js";
+/** What the operations are built from: the type of an operation, how one finds what it writes to on the draft, and the edits it writes. */
+import { Draft } from "immer";
+import { Edition } from "../model/Edition.js";
+import { AnySymbol } from "../model/Symbol.js";
+import { Edit } from "../model/Edit.js";
+import { Motivation, Version } from "../model/Version.js";
+import { RollCopy } from "../model/RollCopy.js";
+import { Belief, ReferenceAssumption } from "../model/Assumption.js";
+import { FeatureOrPatch } from "../model/Feature.js";
+import { WithId } from "../shared/utils.js";
+/**
+ * A change to an edition, written onto an immer draft of it. One
+ * operation is one undo step, so an operation that has to read the
+ * edition first takes an `EditionView` of the state it will be
+ * applied to and does all its writing in the one function it returns.
+ * Where operations run one after another on one draft, the ones after
+ * the first read a view of the draft as it then stands (`reading`).
+ */
+export type EditionOp = (draft: Draft<Edition>) => void;
+export declare const noChange: EditionOp;
+export declare const onCopy: (copyId: string, op: (copy: Draft<RollCopy>, draft: Draft<Edition>) => void) => EditionOp;
+export declare const onVersion: (versionId: string, op: (version: Draft<Version>, draft: Draft<Edition>) => void) => EditionOp;
+export declare const onFeature: (copyId: string, featureId: string, op: (feature: Draft<FeatureOrPatch>) => void) => EditionOp;
+/**
+ * The operation built from a view of the state it is applied to. The
+ * view given is used where the draft still stands as the view saw it,
+ * and a fresh one is taken of the draft where an operation run before
+ * on the same draft has changed it: a path or an index read off the
+ * view would otherwise name what stood there before.
+ */
+export declare const reading: (view: EditionView, build: (view: EditionView) => EditionOp) => EditionOp;
+/**
+ * The state a draft stands at, as plain data. Reading a draft proxies
+ * everything it touches, so what is only read is read from this.
+ */
+export declare const stateOf: <T>(draft: Draft<T>) => T;
+/** The ids of the items the rewriting left out. */
+export declare const droppedIds: (before: readonly WithId[], after: readonly WithId[]) => string[];
+export type Ids = ReadonlySet<string>;
+export declare const insertion: (symbol: AnySymbol) => Edit;
+export declare const deletion: (symbolId: string) => Edit;
+/** The edit as a collation leaves it: made by rule, and not yet read by anybody. */
+export declare const asUnchecked: (edit: Edit) => Edit;
+/**
+ * The motivations with the unchecked one declared, where any edit
+ * names it and the version does not state it yet. An edit naming a
+ * motivation the version leaves undeclared points at nothing.
+ */
+export declare const declaring: (motivations: Motivation[], edits: readonly Edit[]) => Motivation[];
+export declare const insertedIn: (versions: readonly Version[]) => AnySymbol[];
+/** The edits with the change applied, less those it emptied; the very same array where it changed none. */
+export declare const edited: (edits: Edit[], change: (edit: Edit) => Edit) => Edit[];
+/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+export declare const dropInsertions: (version: Draft<Version>, symbolIds: Ids) => void;
+/** A reference under the belief given, where one is given. */
+export declare const referenceHeld: (id: string, belief?: Belief) => ReferenceAssumption;
+/** The references less those that match, or nothing where none is left. */
+export declare const withoutReferences: <R extends ReferenceAssumption>(references: readonly R[], matches: (reference: Readonly<R>) => boolean) => R[] | undefined;

package/lib/ops/draft.js

@@ -0,0 +1,81 @@
+import { EditionView } from "../view/EditionView.js";
+/** What the operations are built from: the type of an operation, how one finds what it writes to on the draft, and the edits it writes. */
+import { current, isDraft } from "immer";
+import { v4 } from "uuid";
+import { unchecked, uncheckedMotivation } from "../collation/Collation.js";
+import { insertedBy } from "../model/Version.js";
+import { featuresOf } from "../model/RollCopy.js";
+import { assignReference } from "../model/Assumption.js";
+import { without, pruned } from "./immutable.js";
+export const noChange = () => undefined;
+export const onCopy = (copyId, op) => draft => {
+    const copy = draft.copies.find(c => c.id === copyId);
+    if (copy)
+        op(copy, draft);
+};
+export const onVersion = (versionId, op) => draft => {
+    const version = draft.versions.find(v => v.id === versionId);
+    if (version)
+        op(version, draft);
+};
+export const onFeature = (copyId, featureId, op) => onCopy(copyId, copy => {
+    const feature = featuresOf(copy).find(f => f.id === featureId);
+    if (feature)
+        op(feature);
+});
+/**
+ * The operation built from a view of the state it is applied to. The
+ * view given is used where the draft still stands as the view saw it,
+ * and a fresh one is taken of the draft where an operation run before
+ * on the same draft has changed it: a path or an index read off the
+ * view would otherwise name what stood there before.
+ */
+export const reading = (view, build) => draft => {
+    const state = stateOf(draft);
+    build(state === view.edition ? view : new EditionView(state))(draft);
+};
+/**
+ * The state a draft stands at, as plain data. Reading a draft proxies
+ * everything it touches, so what is only read is read from this.
+ */
+export const stateOf = (draft) => isDraft(draft) ? current(draft) : draft;
+/** The ids of the items the rewriting left out. */
+export const droppedIds = (before, after) => {
+    const kept = new Set(after.map(item => item.id));
+    return before.flatMap(item => kept.has(item.id) ? [] : [item.id]);
+};
+export const insertion = (symbol) => ({ type: 'edit', id: v4(), insert: [symbol] });
+export const deletion = (symbolId) => ({ type: 'edit', id: v4(), delete: [symbolId] });
+/** The edit as a collation leaves it: made by rule, and not yet read by anybody. */
+export const asUnchecked = (edit) => ({ ...edit, motivation: unchecked });
+/**
+ * The motivations with the unchecked one declared, where any edit
+ * names it and the version does not state it yet. An edit naming a
+ * motivation the version leaves undeclared points at nothing.
+ */
+export const declaring = (motivations, edits) => edits.some(edit => edit.motivation === unchecked)
+    && !motivations.some(motivation => motivation.id === unchecked)
+    ? [...motivations, uncheckedMotivation]
+    : motivations;
+const isEmpty = (edit) => !edit.insert?.length && !edit.delete?.length;
+export const insertedIn = (versions) => versions.flatMap(insertedBy);
+/** The edits with the change applied, less those it emptied; the very same array where it changed none. */
+export const edited = (edits, change) => pruned(edits, change, isEmpty);
+/** The edit without the symbols among its insertions, or the very same edit where it inserts none of them. */
+const droppingInsertions = (symbolIds) => (edit) => {
+    const insert = edit.insert && without(edit.insert, symbol => symbolIds.has(symbol.id));
+    return insert === edit.insert ? edit : { ...edit, insert };
+};
+/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+export const dropInsertions = (version, symbolIds) => {
+    const edits = stateOf(version).edits;
+    if (edits)
+        version.edits = edited(edits, droppingInsertions(symbolIds));
+};
+/** A reference under the belief given, where one is given. */
+export const referenceHeld = (id, belief) => ({ ...assignReference(id), ...(belief && { '@annotation': { id: v4(), belief } }) });
+/** The references less those that match, or nothing where none is left. */
+export const withoutReferences = (references, matches) => {
+    const kept = references.filter(reference => !matches(reference));
+    return kept.length > 0 ? kept : undefined;
+};

package/lib/ops/edits.d.ts

@@ -0,0 +1,10 @@
+import { EditionView } from "../view/EditionView.js";
+import { Edit } from "../model/Edit.js";
+import { EditionOp } from "./draft.js";
+/**
+ * Replaces the edits with a single one carrying all their insertions
+ * and deletions, classified by a guess at what the exchange does.
+ */
+export declare const mergeEdits: (given: EditionView, versionId: string, toMerge: readonly Edit[]) => EditionOp;
+/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+export declare const splitEdit: (versionId: string, toSplit: Edit) => EditionOp;

package/lib/ops/edits.js

@@ -0,0 +1,82 @@
+/** Merging and splitting the edits of a version. */
+import { v4 } from "uuid";
+import { editsOf } from "../model/Version.js";
+import { trackerBarOf } from "../systems/index.js";
+import { distance, mm, subtract } from "../model/Quantity.js";
+import { noChange, onVersion, insertion, deletion, reading } from "./draft.js";
+const sameSequence = (a, b) => a.length === b.length && a.every((value, i) => value === b[i]);
+const expressionTypesOf = (symbols) => symbols.filter((symbol) => symbol.type === 'expression').map(symbol => symbol.expressionType);
+/** The spellings of a single added accent the bar offers, none where no bar is known. */
+const accentsOn = (bar) => bar?.accents ?? [];
+const lengthOf = (span) => subtract(span.to, span.from);
+/** How far apart two onsets may lie for the one symbol to count as a replacement of the other. */
+const REPLACEMENT_TOLERANCE = mm(5);
+/** Shorten or prolong, where the inserted symbol starts about where the deleted one did. */
+const replacementType = (view, inserted, deleted) => {
+    const after = view.placeOf(inserted);
+    const before = view.placeOf(deleted);
+    if (!after || !before || distance(after.from, before.from) >= REPLACEMENT_TOLERANCE)
+        return undefined;
+    return lengthOf(after) < lengthOf(before) ? 'shorten' : 'prolong';
+};
+/**
+ * A guess at what an edit does, from the symbols it exchanges and from
+ * the systems the version and the one it is based on are coded for.
+ */
+const guessEditType = (view, versionId, edit) => {
+    const inserts = edit.insert ?? [];
+    const deletes = view.symbols(edit.delete ?? []);
+    const inserted = expressionTypesOf(inserts);
+    const deleted = expressionTypesOf(deletes);
+    const bar = trackerBarOf(view.version(versionId)?.system);
+    const parentBar = trackerBarOf(view.predecessorOf(versionId)?.system);
+    /**
+     * Where the version is coded for another system than its parent, an
+     * exchange of expression matter is the transfer being carried out:
+     * a red ForzandoOn and ForzandoOff pair giving way to one held green
+     * SforzandoForte says the same thing in the other system's words,
+     * which is what 'replace-with-equivalent' is for. Calling it a
+     * corrected error would say the editor made a mistake.
+     */
+    if (bar && parentBar && bar.id !== parentBar.id && inserted.length > 0 && deleted.length > 0) {
+        return 'replace-with-equivalent';
+    }
+    if (deleted.length === 0 && accentsOn(bar).some(accent => sameSequence(inserted, accent)))
+        return 'additional-accent';
+    if (inserted.length > 1 && sameSequence(inserted, deleted))
+        return 'shift';
+    if (inserted.length === 0 && deleted.length === 1)
+        return 'remove-redundancy';
+    if (inserts.length === 1 && deletes.length === 1)
+        return replacementType(view, inserts[0], deletes[0]) ?? 'correct-error';
+    return 'correct-error';
+};
+/**
+ * Replaces the edits with a single one carrying all their insertions
+ * and deletions, classified by a guess at what the exchange does.
+ */
+export const mergeEdits = (given, versionId, toMerge) => reading(given, view => {
+    if (toMerge.length === 0)
+        return noChange;
+    const merged = {
+        ...toMerge[0],
+        id: v4(),
+        insert: toMerge.flatMap(edit => edit.insert ?? []),
+        delete: toMerge.flatMap(edit => edit.delete ?? [])
+    };
+    merged.editType = guessEditType(view, versionId, merged);
+    const mergedIds = new Set(toMerge.map(edit => edit.id));
+    return onVersion(versionId, version => {
+        version.edits = [...editsOf(version).filter(edit => !mergedIds.has(edit.id)), merged];
+    });
+});
+/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+export const splitEdit = (versionId, toSplit) => {
+    const parts = [
+        ...(toSplit.insert ?? []).map(insertion),
+        ...(toSplit.delete ?? []).map(deletion)
+    ];
+    return onVersion(versionId, version => {
+        version.edits = [...editsOf(version).filter(edit => edit.id !== toSplit.id), ...parts];
+    });
+};

package/lib/ops/features.d.ts

@@ -0,0 +1,84 @@
+import { EditionView } from "../view/EditionView.js";
+import { ModificationPurpose } from "../model/RollCopy.js";
+import { FeatureConditionAssignment, FeatureOrPatch, NestedFeature } from "../model/Feature.js";
+import { EditionOp } from "./draft.js";
+/**
+ * States the condition of the feature, in place of any earlier
+ * statement. Throws where the kind of feature is in no such condition;
+ * `conditions` says which conditions each kind of feature may be in.
+ */
+export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
+/**
+ * The act a feature an editor states belongs to: the punching of the
+ * copy, the act that brought another feature about, or, where neither
+ * is said, an act of its own for the purpose given. A patch is never
+ * punched, being glued on, so `punched` says nothing of one.
+ */
+export interface FeatureAct {
+    /** The copy came from its punching with it, which is where a reading of a scan puts every chain of holes. */
+    punched?: boolean;
+    /** The act that brought this feature about brought the new one about as well. */
+    beside?: string;
+    /** What the act was for, where a new one is made for the feature. */
+    purpose?: ModificationPurpose;
+}
+/**
+ * States that the copy bears the feature, in the act that brought it
+ * about: a patch was glued on by an attachment, anything else was
+ * produced, by the punching or by a later act. Which act, `FeatureAct`
+ * says; a `beside` that names nothing the copy bears is passed over and
+ * the feature goes into an act of its own.
+ */
+export declare const addFeature: (copyId: string, feature: FeatureOrPatch, act?: FeatureAct) => EditionOp;
+/**
+ * States that the patch bears the feature. What a patch bears came onto
+ * the copy with the patch, so it belongs to no act of its own and
+ * states no place: it stands where the patch stands.
+ */
+export declare const addBorneFeature: (copyId: string, patchId: string, feature: NestedFeature) => EditionOp;
+/**
+ * Takes the features off the copy, and out of the versions with what
+ * only they carried. A feature may be named wherever the copy bears it:
+ * a patch goes with everything glued onto it, and a feature of a patch
+ * may be taken back on its own, the patch staying where it is. An act
+ * left having produced or added nothing goes as well.
+ */
+export declare const removeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
+/** Why several features cannot be replaced by one. */
+export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features' | 'different-acts';
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export declare const mergeObstacle: (features: readonly FeatureOrPatch[]) => MergeObstacle | undefined;
+/**
+ * What stands in the way of reading the features the ids name as one,
+ * as `mergeFeatures` will find it. `mergeObstacle` asks only what the
+ * features themselves say, which cannot reach `different-acts`: one
+ * feature is the work of one act, and where the features stand is the
+ * edition's business rather than theirs.
+ */
+export declare const mergeObstacleIn: (view: EditionView, featureIds: readonly string[]) => MergeObstacle | undefined;
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one, and
+ * whatever else named them, a modification or a comprehension, names
+ * the merged one in their stead.
+ *
+ * Only the features the copy bears itself are merged. A feature of a
+ * patch states no place along the roll of its own, so there is nothing
+ * for a merge to span, and an id naming one is passed over as an id the
+ * copy does not bear is. Features of two different acts are not merged
+ * either: one feature is the work of one act.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;