linked-rolls 0.0.1 → 0.1.0

package/lib/Feature.d.ts

@@ -1,37 +1,158 @@
+import { ObjectAssumption } from "./Assumption";
 import { ConditionState } from "./ConditionState";
-import { EditorialAssumption } from "./EditorialAssumption";
-import { WithId } from "./WithId";
-export interface FeatureCondition extends ConditionState<'missing-perforation' | 'damaged-perforation' | 'illegible'> {
-}
-export type FeatureConditionAssignment = EditorialAssumption<'conditionAssignment', FeatureCondition>;
+import { Text } from "./Symbol";
+import { PartialBy, WithId, WithType } from "./utils";
+/**
+ * Describes the horizontal extent of a feature on the roll,
+ * measured in millimeters from the beginning of the roll.
+ * The `from` value is the start position and `to` is the end position.
+ */
 export interface HorizontalSpan {
+    /**
+     * The unit of measurement for horizontal positions.
+     * Always 'mm' (millimeters).
+     * @see crm:P91 has unit
+     */
     unit: 'mm';
+    /**
+     * The start position of the feature in millimeters
+     * from the beginning of the roll.
+     */
     from: number;
+    /**
+     * The end position of the feature in millimeters
+     * from the beginning of the roll.
+     */
     to: number;
 }
+/**
+ * Describes the vertical extent of a feature on the roll,
+ * measured in track numbers. Track numbers correspond to
+ * positions on the tracker bar.
+ */
 export interface VerticalSpan {
+    /**
+     * The unit of measurement for horizontal positions.
+     * @see crm:P91 has unit
+     */
     unit: 'track';
+    /**
+     * The start track number of the feature.
+     */
     from: number;
+    /**
+     * The end track number, if the feature spans multiple tracks.
+     * If omitted, the feature occupies a single track.
+     */
     to?: number;
 }
-export interface RollFeature extends WithId {
+export declare const featureTypes: readonly ["Hole", "Writing", "Mark", "GluedOn"];
+export type FeatureType = typeof featureTypes[number];
+/**
+ * A physical feature on the roll, e.g. a perforation, a tear, a mark, etc.,
+ * defined by its horizontal and vertical position and extent.
+ * @see reo:C2 Feature
+ */
+export interface RollFeature<T extends FeatureType, DamageT extends string> extends WithId, WithType<T> {
+    /**
+     * IIIF region pointing to a depiction of this feature in the scan.
+     * @see crm:P62 is depicted by
+     */
+    depiction?: string;
     /**
-     * IIIF region in string form.
+     * Horizontal span of the feature on the roll.
+     * @see crm:P43 has dimension
      */
-    annotates?: string;
     horizontal: HorizontalSpan;
-    vertical: VerticalSpan;
     /**
-     * Describes whether the event takes place
-     * on the verso or recto side of the roll.
-     * Since the same perforation is present on both
-     * sides, this property is left optional for now.
+     * Vertical span of the feature on the roll.
+     * @see crm:P43 has dimension
      */
-    side?: 'verso' | 'recto';
+    vertical: VerticalSpan;
     /**
      * This can be used e.g. to indicate a perforation
      * which is torn out or in any other way damaged.
      */
-    condition?: FeatureConditionAssignment;
+    condition?: ObjectAssumption<ConditionState<DamageT>>;
+}
+export declare const conditions: {
+    readonly Hole: readonly ["partially-torn", "missing-perforation"];
+    readonly Writing: readonly ["illegible"];
+    readonly Mark: readonly ["faded"];
+    readonly GluedOn: readonly ["detaching", "ripped"];
+};
+/**
+ * A hole (perforation) in the roll paper. Holes are the primary
+ * carriers of musical information on piano rolls, as they trigger
+ * notes and expression controls when passing over the tracker bar.
+ */
+export interface Hole extends RollFeature<'Hole', typeof conditions.Hole[number]> {
+    /**
+     * The punching pattern of the hole. Regular holes have evenly-spaced
+     * bridges, accelerating holes have decreasing bridge widths, and
+     * staggering holes alternate between adjacent tracks (cf. Phillips).
+     */
+    pattern?: 'regular' | 'accelerating' | 'staggering';
+}
+/**
+ * A trace is a visible mark or writing on the roll surface.
+ * Traces may fade over time.
+ */
+export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions.Mark[number]> {
+}
+export declare const writingMethods: readonly ["Print", "Handwriting", "Stamp"];
+/**
+ * The method by which a writing was produced on the roll:
+ * printed, handwritten, or stamped.
+ */
+export type WritingMethod = typeof writingMethods[number];
+/**
+ * A piece of writing found on the roll, such as a label,
+ * catalogue number, or annotation. Writings have a method
+ * of production and a transcription of their content.
+ */
+export interface Writing extends Trace<'Writing'> {
+    /**
+     * The method by which this writing was produced
+     * (e.g. through print, handwriting, or stamping).
+     */
+    method: WritingMethod;
+    /**
+     * A transcription of the text content of the writing.
+     * This is an object assumption so that the transcription
+     * can be annotated with a belief about its correctness.
+     */
+    transcription: ObjectAssumption<Omit<Text, 'carriers'>>;
+}
+/**
+ * A visible mark on the roll, such as a pencil mark,
+ * ink mark, or other non-textual annotation.
+ */
+export interface Mark extends Trace<'Mark'> {
+}
+/**
+ * A piece of material (paper or tape) glued onto the roll surface.
+ * Glued-on features are typically used to cover perforations (for corrections)
+ * or to reinforce damaged areas. They may themselves carry other features
+ * such as writings or additional holes.
+ */
+export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedOn[number]> {
+    /**
+     * The material of the glued-on feature.
+     * @see crm:P45 consists of
+     */
+    material: 'Paper' | 'Tape';
+    /**
+     * A glued-on feature itself may carry other features.
+     * Nested features do not need to be positioned explicitly.
+     * @see crm:P56 bears feature
+     */
+    features?: PartialBy<AnyFeature, 'horizontal' | 'vertical'>[];
 }
-export declare const isRollFeature: (obj: object) => obj is RollFeature;
+/**
+ * The union of all physical feature types that can appear on a roll:
+ * holes (perforations), writings (labels, annotations), marks (pencil, ink),
+ * and glued-on patches (paper, tape).
+ */
+export type AnyFeature = Hole | Writing | Mark | GluedOn;
+export declare const isRollFeature: (obj: object) => obj is AnyFeature;

package/lib/Feature.js

@@ -1,3 +1,11 @@
+export const featureTypes = ['Hole', 'Writing', 'Mark', 'GluedOn'];
+export const conditions = {
+    Hole: ['partially-torn', 'missing-perforation'],
+    Writing: ['illegible'],
+    Mark: ['faded'],
+    GluedOn: ['detaching', 'ripped']
+};
+export const writingMethods = ['Print', 'Handwriting', 'Stamp'];
 export const isRollFeature = (obj) => {
-    return 'horizontal' in obj && 'vertical' in obj;
+    return 'type' in obj && featureTypes.includes(obj.type);
 };

package/lib/Plan.d.ts

@@ -0,0 +1,190 @@
+import { Draft } from "immer";
+import { EditionView } from "./EditionView";
+import { Edition } from "./Edition";
+import { CollationTolerance } from "./Collation";
+import { Edit } from "./Edit";
+import { RollCopy } from "./RollCopy";
+export type EditionOp = (d: Draft<Edition>) => void;
+export interface Plan {
+    build(): EditionOp[];
+    setView: (view: EditionView) => void;
+}
+export declare const isPlan: (obj: any) => obj is Plan;
+export declare abstract class BasePlan implements Plan {
+    protected view: EditionView | null;
+    setView: (view: EditionView) => void;
+    abstract build(): EditionOp[];
+}
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export declare class ConnectVersions extends BasePlan {
+    private childId;
+    private parentId;
+    private tolerance;
+    constructor(childId: string, parentId: string, tolerance?: CollationTolerance);
+    build(): EditionOp[];
+}
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export declare class CreateVersion extends BasePlan {
+    private siglum;
+    private copy;
+    constructor(siglum: string, copy: RollCopy);
+    build(): EditionOp[];
+}
+/**
+ * Creates a new version based on the given version
+ * calculating the effect of a cover on existing symbols.
+ 
+export class CoverPerforation extends BasePlan {
+    constructor(
+        private copyId: string,
+        private versionId: string,
+        private coverDimension: { horizontal: HorizontalSpan, vertical: VerticalSpan },
+        private material: string | undefined = undefined,
+    ) {
+        super()
+    }
+
+    build(): EditionOp[] {
+        const view = this.view
+        if (!view) return []
+
+        return [
+            (draft: Draft<Edition>): void => {
+                const version = draft.versions.find(v => v.id === this.versionId)
+                const copy = draft.copies.find(c => c.id === this.copyId)
+                if (!version || !copy) return
+
+                // find perforations in the snapshot that
+                // overlap with the cover
+                const overlappingSymbols =
+                    view.snapshot(this.versionId)
+                        .filter(symbol => {
+                            const dimension = view.dimensionOf(symbol)
+                            if (!dimension) return false
+
+                            return (
+                                (symbol.type === 'note' || symbol.type === 'expression') &&
+                                overlaps(dimension, this.coverDimension)
+                            )
+                        })
+
+                if (!overlappingSymbols.length) return undefined
+
+                const deepClone = JSON.parse(JSON.stringify(overlappingSymbols)) as AnySymbol[]
+
+                for (const symbol of deepClone) {
+                    //symbol.id = v4();
+                    const dimension = structuredClone(view.dimensionOf(symbol))
+                    if (!dimension) continue
+
+                    // check if the cover partially covers the beginning
+                    if (dimension.horizontal.from >= this.coverDimension.horizontal.from &&
+                        dimension.horizontal.from <= this.coverDimension.horizontal.to
+                    ) {
+                        dimension.horizontal.from = this.coverDimension.horizontal.to
+                    }
+
+                    // check if the cover partially covers the ending
+                    if (dimension.horizontal.to >= this.coverDimension.horizontal.from &&
+                        dimension.horizontal.to <= this.coverDimension.horizontal.to
+                    ) {
+                        dimension.horizontal.to = this.coverDimension.horizontal.from
+                    }
+
+                    const newFeature: RollFeature = {
+                        ...dimension,
+                        id: v4(),
+                    }
+
+                    copy.features.push(newFeature)
+                    symbol.id = `symbol-${v4().slice(0, 8)}`
+                    symbol.carriers = [assignReference(newFeature.id)]
+                }
+
+                const coverId = `cover-${v4().slice(0, 8)}`
+                copy.features.push({
+                    ...this.coverDimension,
+                    id: coverId,
+                })
+
+                const edit: Edit = {
+                    type: 'edit',
+                    id: v4(),
+                    delete: overlappingSymbols.map(s => s.id),
+                    insert: deepClone,
+                    intentionOf: [{
+                        type: 'cover',
+                        id: v4(),
+                        note: this.material,
+                        carriers: [assignReference(coverId)],
+                    }]
+                }
+
+                draft.versions.push({
+                    edits: [edit],
+                    id: v4(),
+                    basedOn: assignReference(version.id),
+                    siglum: version.siglum + ' rev',
+                    type: 'authorised-revision',
+                    motivations: [
+                        {
+                            type: 'motivation',
+                            note: 'Stanzfehler korrigiert',
+                            id: v4(),
+                        }
+                    ],
+                })
+            }]
+    }
+}
+    */
+export declare class DetachVersion extends BasePlan {
+    private versionId;
+    constructor(versionId: string);
+    build(): EditionOp[];
+}
+export declare class RemoveFeature extends BasePlan {
+    private copyID;
+    private featureIDs;
+    constructor(copyID: string, featureIDs: string[]);
+    build(): EditionOp[];
+}
+export declare class MergeEdits extends BasePlan {
+    private versionId;
+    private toMerge;
+    constructor(versionId: string, toMerge: Edit[]);
+    private guessMotivation;
+    build(): EditionOp[];
+}
+export declare class SplitEdit extends BasePlan {
+    private versionId;
+    private toSplit;
+    constructor(versionId: string, toSplit: Edit);
+    build(): EditionOp[];
+}