linked-rolls 0.37.0 → 0.38.0

package/lib/EditionView.d.ts

@@ -4,7 +4,7 @@ import { AnySymbol, Expression, Note } from "./Symbol";
 import { Version } from "./Version";
 import { NegotiatedEvent } from "./ReproducingSystem";
 import { TrackerBar } from "./TrackerBar";
-import { RollCopy } from "./RollCopy";
+import { Modification, ProductionEvent, RollCopy } from "./RollCopy";
 import { Millimeters } from "./Quantity";
 export type Path = (string | number)[];
 export declare const getAt: <T>(path: Path, obj: unknown) => T | undefined;
@@ -37,6 +37,15 @@ export declare class EditionView {
     carriersOf(symbol: AnySymbol): Readonly<FeatureOrPatch>[];
     /** The copy a feature sits on, a patch and everything it bears included. */
     copyOf(featureId: string): Readonly<RollCopy> | undefined;
+    /**
+     * The act a copy states a feature in: the production event that
+     * punched it, or the modification that brought it about. A feature
+     * a patch bears came onto the copy with the patch, so the act is
+     * the one that glued the patch on. Two features stand in one act
+     * where this returns the very same object, which is what
+     * `mergeFeatures` asks before it reads them as one.
+     */
+    actOf(featureId: string): Readonly<ProductionEvent | Modification> | undefined;
     /**
      * How a place on the edition's shared axis relates to the paper of
      * this version: place × factor = millimetres of its own paper.

package/lib/EditionView.js

@@ -1,7 +1,7 @@
 import { withBorneFeatures } from "./Feature";
 import { deletedBy, insertedBy, principalDerivationOf } from "./Version";
 import { systemIdOf } from "./TrackerBar";
-import { featuresOf, isPaperStretch } from "./RollCopy";
+import { featuresMadeBy, featuresOf, isPaperStretch } from "./RollCopy";
 import { idOf, idsOf } from "./Assumption";
 import { mean } from "./Quantity";
 export const getAt = (path, obj) => {
@@ -161,6 +161,23 @@ export class EditionView {
         }
         return this.copiesByFeature.get(featureId);
     }
+    /**
+     * The act a copy states a feature in: the production event that
+     * punched it, or the modification that brought it about. A feature
+     * a patch bears came onto the copy with the patch, so the act is
+     * the one that glued the patch on. Two features stand in one act
+     * where this returns the very same object, which is what
+     * `mergeFeatures` asks before it reads them as one.
+     */
+    actOf(featureId) {
+        const copy = this.copyOf(featureId);
+        if (!copy)
+            return undefined;
+        const states = (features) => features.flatMap(withBorneFeatures).some(feature => feature.id === featureId);
+        if (states(copy.production?.produced ?? []))
+            return copy.production;
+        return copy.modifications.find(act => states(featuresMadeBy(act)));
+    }
     /**
      * How a place on the edition's shared axis relates to the paper of
      * this version: place × factor = millimetres of its own paper.

package/lib/RollCopy.d.ts

@@ -346,6 +346,10 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      */
     carries?: ReferenceAssumption[];
 }
+/** What an act brought onto the copy: what it produced or glued on, a removal nothing. */
+export declare const featuresMadeBy: (modification: Modification) => FeatureOrPatch[];
+/** Whether the act is one that modified the copy, rather than the production that punched it. */
+export declare const isModification: (act: ProductionEvent | Modification) => act is Modification;
 /** Whether the act is left stating nothing: it produced, added or removed nothing. */
 export declare const statesNothing: (modification: Modification) => boolean;
 /**

package/lib/RollCopy.js

@@ -17,20 +17,22 @@ export const modificationPurposes = [
     'glossing'
 ];
 /** What an act brought onto the copy: what it produced or glued on, a removal nothing. */
-const madeBy = (modification) => {
+export const featuresMadeBy = (modification) => {
     if (modification.type === 'Alteration')
         return modification.produced;
     return modification.type === 'Attachment' ? modification.added : [];
 };
+/** Whether the act is one that modified the copy, rather than the production that punched it. */
+export const isModification = (act) => 'type' in act;
 /** Whether the act is left stating nothing: it produced, added or removed nothing. */
-export const statesNothing = (modification) => modification.type === 'Removal' ? modification.removed.length === 0 : madeBy(modification).length === 0;
+export const statesNothing = (modification) => modification.type === 'Removal' ? modification.removed.length === 0 : featuresMadeBy(modification).length === 0;
 /**
  * The features of the copy act by act: what the punching produced
  * first, then what each modification produced or glued on. A feature a
  * patch bears states no place of its own and is not among them;
  * `withBorneFeatures` reaches those.
  */
-export const featuresByAct = (copy) => [copy.production?.produced ?? [], ...copy.modifications.map(madeBy)];
+export const featuresByAct = (copy) => [copy.production?.produced ?? [], ...copy.modifications.map(featuresMadeBy)];
 /** Every feature the copy states at a place of its own, whichever act made it. */
 export const featuresOf = (copy) => featuresByAct(copy).flat();
 /**

package/lib/editionOps.d.ts

@@ -4,10 +4,10 @@ import { Edition } from "./Edition";
 import { AnySymbol, PlacementRelation } from "./Symbol";
 import { CollationTolerance } from "./Collation";
 import { Edit } from "./Edit";
-import { GeneralRollCondition, RollCopy, ScaleReading, Shift } from "./RollCopy";
+import { GeneralRollCondition, ModificationPurpose, RollCopy, ScaleReading, Shift } from "./RollCopy";
 import { FeatureSource } from "./FeatureSource";
 import { AnyArgumentation, Belief, Certainty, ObjectAssumption } from "./Assumption";
-import { FeatureConditionAssignment, FeatureOrPatch } from "./Feature";
+import { FeatureConditionAssignment, FeatureOrPatch, NestedFeature } from "./Feature";
 /**
  * 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
@@ -70,6 +70,34 @@ export declare const addGeneralCondition: (copyId: string, condition: ObjectAssu
 export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
 /** The symbols of the versions that no other copy carries. */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
+/**
+ * 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 was punched with it, which is where a reading of a scan puts every hole. */
+    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:

package/lib/editionOps.js

@@ -379,6 +379,66 @@ const rewriteFeatures = (copy, rewrite) => {
     }
     copy.modifications = pruned(state.modifications, rewritingAct(rewrite), statesNothing);
 };
+/** The features of the act that brought the named feature about, where that act produces features. */
+const producedBeside = (copy, featureId) => {
+    const names = (features) => features.some(feature => feature.id === featureId);
+    const punched = copy.production?.produced;
+    if (punched && names(punched))
+        return punched;
+    const act = copy.modifications.find(act => act.type === 'Alteration' && names(act.produced));
+    return act?.type === 'Alteration' ? act.produced : undefined;
+};
+/** The patches of the attachment that glued the named one on. */
+const gluedBeside = (copy, patchId) => {
+    const act = copy.modifications.find(act => act.type === 'Attachment' && act.added.some(patch => patch.id === patchId));
+    return act?.type === 'Attachment' ? act.added : undefined;
+};
+/** The list the copy states a new feature in, making the act it belongs to where there is none. */
+const actFor = (copy, patch, act) => {
+    const beside = act.beside !== undefined
+        ? (patch ? gluedBeside(copy, act.beside) : producedBeside(copy, act.beside))
+        : undefined;
+    if (beside)
+        return beside;
+    if (patch) {
+        const added = [];
+        copy.modifications.push({ type: 'Attachment', added, ...(act.purpose && { purpose: act.purpose }) });
+        return added;
+    }
+    if (act.punched) {
+        if (!copy.production)
+            copy.production = {};
+        if (!copy.production.produced)
+            copy.production.produced = [];
+        return copy.production.produced;
+    }
+    const produced = [];
+    copy.modifications.push({ type: 'Alteration', produced, ...(act.purpose && { purpose: act.purpose }) });
+    return produced;
+};
+/**
+ * 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 const addFeature = (copyId, feature, act = {}) => onCopy(copyId, copy => {
+    actFor(copy, isGluedOn(feature), act).push(feature);
+});
+/**
+ * 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 const addBorneFeature = (copyId, patchId, feature) => onCopy(copyId, copy => {
+    const patch = featuresOf(copy).flatMap(withBorneFeatures).find(borne => borne.id === patchId);
+    if (!patch || !isGluedOn(patch))
+        return;
+    if (!patch.features)
+        patch.features = [];
+    patch.features.push(feature);
+});
 /**
  * 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {