linked-rolls 0.38.0 → 0.39.1

package/README.md

@@ -78,12 +78,17 @@ derivation loads as a list of one.
 ## What brought a feature about
 
 A copy states no list of features. Each feature stands in the act that
-brought it about: the perforations in the copy's own production, a
-writing or a mark in the `Alteration` that made it, a patch in the
-`Attachment` that glued it on. A `Removal` names by id what was taken
-off, which stood there before the act. A feature no later act is known
-to have made belongs to the punching, which is where a reading of a
-scan puts every hole it finds.
+brought it about: the copy's own production for what the punching made,
+an `Alteration` for what a later hand made, an `Attachment` for a patch
+glued on. A `Removal` names by id what was taken off, which stood there
+before the act.
+
+Which act a feature stands in says when it came about and by whose
+hand, and says nothing about what kind of feature it is. A hole may be
+punched by hand long after the roll was cut, and a mark may come from
+the factory, rarely though that happens. A feature no later act is
+known to have made belongs to the punching, which is where a reading of
+a scan puts every hole it finds.
 
 Three kinds of act rather than two, because the CRM tells them apart.
 E79 Part Addition asks that what is added be "a separate identifiable

package/lib/Feature.d.ts

@@ -2,7 +2,7 @@ import { ObjectAssumption } from "./Assumption";
 import { ConditionState } from "./ConditionState";
 import { Text } from "./Symbol";
 import { PartialBy, WithId, WithType } from "./utils";
-import { Millimeters, Track } from "./Quantity";
+import { Measure, Millimeters, Track } from "./Quantity";
 /**
  * Describes the horizontal extent of a feature on the roll,
  * measured in millimeters from the beginning of the roll.
@@ -119,11 +119,23 @@ export interface Hole extends RollFeature<'Hole', typeof conditions.Hole[number]
      */
     pattern?: 'regular' | 'accelerating' | 'staggering';
 }
+/**
+ * Something that lies on a face of the paper rather than through it. A
+ * hole is not one: it goes through, and is on both faces at once.
+ */
+export interface OnAFace {
+    /**
+     * The face of the roll it lies on: the side that faces the reader
+     * as the roll plays, or the back of it.
+     * @see reo:side
+     */
+    side?: 'recto' | 'verso';
+}
 /**
  * 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[T][number]> {
+export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions[T][number]>, OnAFace {
 }
 export declare const writingMethods: readonly ['print', 'handwriting', 'stamp'];
 /**
@@ -156,6 +168,15 @@ export interface Writing extends Trace<'Writing'> {
      * @see crm:P128 carries
      */
     transcription: ObjectAssumption<Transcription>;
+    /**
+     * How far the writing stands askew. At zero it reads across the
+     * roll, from the bass side towards the treble, and the angle turns
+     * that reading direction towards the end of the roll, so that a
+     * right angle leaves it reading along the roll. A stamp pressed
+     * crooked and a label written lengthwise are both stated here.
+     * @see reo:rotation
+     */
+    rotation?: Measure<'deg'>;
 }
 /**
  * A visible mark on the roll, such as a pencil circle, an ink stroke,
@@ -178,12 +199,19 @@ export interface Mark extends Trace<'Mark'> {
  * such as writings or additional holes.
  * @see reo:GluedOn
  */
-export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedOn[number]> {
+export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedOn[number]>, OnAFace {
     /**
      * The material of the glued-on feature.
      * @see crm:P45 consists of
      */
     material: 'paper' | 'tape';
+    /**
+     * How far the patch was stuck on askew. At zero its edges stand
+     * square to the roll, and the angle turns them towards the end of
+     * it, as a writing's reading direction turns.
+     * @see reo:rotation
+     */
+    rotation?: Measure<'deg'>;
     /**
      * A glued-on feature itself may carry other features.
      * Nested features do not need to be positioned explicitly.

package/lib/Quantity.d.ts

@@ -11,7 +11,7 @@ declare const unit: unique symbol;
  * The units a record may state. A `Measure` is limited to these, since
  * they are what the `unit` field is allowed to say.
  */
-export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in';
+export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in' | 'deg';
 export type Quantity<U extends string> = number & {
     readonly [unit]: U;
 };
@@ -28,6 +28,8 @@ export type FeetPerMinute = Quantity<'ft/min'>;
 export type MetersPerMinute = Quantity<'m/min'>;
 /** How finely a scan was read: pixels of the image per inch of paper. */
 export type Resolution = Quantity<'px/in'>;
+/** An angle on the roll, turning from the line across the paper towards the end of the roll. */
+export type Degrees = Quantity<'deg'>;
 /** Names a number in a unit. Partially apply it to make a constructor. */
 export declare const quantity: <U extends string>(value: number) => Quantity<U>;
 export declare const mm: (value: number) => Quantity<"mm">;
@@ -39,6 +41,7 @@ export declare const milliseconds: (value: number) => Quantity<"ms">;
 export declare const feetPerMinute: (value: number) => Quantity<"ft/min">;
 export declare const metersPerMinute: (value: number) => Quantity<"m/min">;
 export declare const pixelsPerInch: (value: number) => Quantity<"px/in">;
+export declare const degrees: (value: number) => Quantity<"deg">;
 /**
  * A value together with the unit it was measured in, as a record
  * states it.

package/lib/Quantity.js

@@ -9,6 +9,7 @@ export const milliseconds = quantity;
 export const feetPerMinute = quantity;
 export const metersPerMinute = quantity;
 export const pixelsPerInch = quantity;
+export const degrees = quantity;
 // The second operand takes its unit from the first. Inferred from both,
 // TypeScript would unite two units rather than reject them.
 export const add = (a, b) => quantity(a + b);

package/lib/RollCopy.d.ts

@@ -115,10 +115,12 @@ export interface ProductionEvent {
      */
     speed?: ObjectAssumption<PaperSpeed>;
     /**
-     * The features the punching brought into being, which are the note
-     * and expression perforations. A reading of a scan finds every hole
-     * on the paper at once and states it here. A hole an editor reads as
-     * punched later belongs in the act that made it.
+     * The features the copy came from its punching with: the note and
+     * expression perforations, and now and then a mark the perforator
+     * left. A reading of a scan finds every hole on the paper at once
+     * and states it here, and a feature an editor reads as the work of
+     * a later hand belongs in the act that made it, whichever kind of
+     * feature it is.
      * @see crm:P108 has produced
      */
     produced?: AnyFeature[];
@@ -161,7 +163,9 @@ export type Modification = Partial<{
     type: 'Alteration';
     /**
      * The features the act brought into being: a date written on the
-     * paper, a circle in pencil, a hole punched by hand.
+     * paper, a circle in pencil, a hole punched by hand. Any kind of
+     * feature may come of a later act, as any kind may come of the
+     * punching.
      * @see crm:P108 has produced
      */
     produced: AnyFeature[];

package/lib/editionOps.d.ts

@@ -77,7 +77,7 @@ export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) =>
  * 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. */
+    /** The copy came from its punching 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;
@@ -123,6 +123,14 @@ export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tr
  * 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.

package/lib/editionOps.js

@@ -511,6 +511,32 @@ export const mergeObstacle = (features) => {
         return 'differing-conditions';
     return undefined;
 };
+/** The acts of the copy that state any of the named features. */
+const actsHolding = (copy, named) => featuresByAct(copy).filter(features => features.some(feature => named.has(feature.id)));
+/**
+ * What stands in the way of reading the named features of the copy as
+ * one, which is the whole of what `mergeFeatures` asks: whether one act
+ * brought them all about, and what the features themselves say. An id
+ * the copy does not bear at a place of its own is passed over.
+ */
+const obstacleIn = (copy, featureIds) => {
+    const named = new Set(featureIds);
+    const acts = actsHolding(copy, named);
+    return acts.length > 1
+        ? 'different-acts'
+        : mergeObstacle((acts[0] ?? []).filter(feature => named.has(feature.id)));
+};
+/**
+ * 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 const mergeObstacleIn = (view, featureIds) => {
+    const copy = featureIds.map(id => view.copyOf(id)).find(copy => copy !== undefined);
+    return copy ? obstacleIn(copy, featureIds) : 'fewer-than-two';
+};
 /** The items with the replacement in the place of the first it stands for, the others dropped. */
 const standingFor = (items, stands, replacement) => {
     const first = items.findIndex(stands);
@@ -576,14 +602,13 @@ const carryOver = (draft, replaced, mergedId) => {
  * says beforehand whether they can.
  */
 export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
-    const named = new Set(featureIds);
-    const holds = (features) => features.some(feature => named.has(feature.id));
-    const acts = featuresByAct(stateOf(copy)).filter(holds);
-    const toMerge = (acts[0] ?? []).filter(feature => named.has(feature.id));
-    const obstacle = acts.length > 1 ? 'different-acts' : mergeObstacle(toMerge);
+    const state = stateOf(copy);
+    const obstacle = obstacleIn(state, featureIds);
     if (obstacle) {
         throw new Error(`The features of copy ${copyId} cannot be merged: ${obstacle}`);
     }
+    const named = new Set(featureIds);
+    const toMerge = (actsHolding(state, named)[0] ?? []).filter(feature => named.has(feature.id));
     const replaced = new Set(toMerge.map(feature => feature.id));
     const mergedId = v4();
     rewriteFeatures(copy, (stated) => {

package/lib/schema.json

@@ -780,6 +780,20 @@
                     "type": "string",
                     "ontology": "crm:P45 consists of"
                 },
+                "rotation": {
+                    "$ref": "#/definitions/Measure%3C%22deg%22%3E",
+                    "description": "How far the patch was stuck on askew. At zero its edges stand square to the roll, and the angle turns them towards the end of it, as a writing's reading direction turns.",
+                    "ontology": "reo:rotation"
+                },
+                "side": {
+                    "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                    "enum": [
+                        "recto",
+                        "verso"
+                    ],
+                    "type": "string",
+                    "ontology": "reo:side"
+                },
                 "vertical": {
                     "$ref": "#/definitions/VerticalSpan",
                     "description": "Vertical span of the feature on the roll.",
@@ -1015,6 +1029,15 @@
                     "description": "The medium the mark was drawn in, where it can be told.",
                     "ontology": "reo:method"
                 },
+                "side": {
+                    "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                    "enum": [
+                        "recto",
+                        "verso"
+                    ],
+                    "type": "string",
+                    "ontology": "reo:side"
+                },
                 "vertical": {
                     "$ref": "#/definitions/VerticalSpan",
                     "description": "Vertical span of the feature on the roll.",
@@ -1084,6 +1107,28 @@
             "type": "object",
             "ontology": "crminf:I16 Meaning Comprehension"
         },
+        "Measure<\"deg\">": {
+            "description": "A value together with the unit it was measured in, as a record states it.",
+            "properties": {
+                "unit": {
+                    "const": "deg",
+                    "description": "The unit of measurement.",
+                    "type": "string",
+                    "ontology": "crm:P91 has unit"
+                },
+                "value": {
+                    "$ref": "#/definitions/Quantity%3C%22deg%22%3E",
+                    "description": "The measured value.",
+                    "ontology": "crm:P90 has value"
+                }
+            },
+            "required": [
+                "value",
+                "unit"
+            ],
+            "type": "object",
+            "ontology": "crm:E54 Dimension"
+        },
         "Measure<\"mm\">": {
             "description": "A value together with the unit it was measured in, as a record states it.",
             "properties": {
@@ -1219,7 +1264,7 @@
                             "ontology": "crm:P4 has time-span"
                         },
                         "produced": {
-                            "description": "The features the act brought into being: a date written on the paper, a circle in pencil, a hole punched by hand.",
+                            "description": "The features the act brought into being: a date written on the paper, a circle in pencil, a hole punched by hand. Any kind of feature may come of a later act, as any kind may come of the punching.",
                             "items": {
                                 "$ref": "#/definitions/AnyFeature"
                             },
@@ -1411,6 +1456,20 @@
                             "description": "The method by which this writing was produced (e.g. through print, handwriting, or stamping).",
                             "ontology": "reo:method"
                         },
+                        "rotation": {
+                            "$ref": "#/definitions/Measure%3C%22deg%22%3E",
+                            "description": "How far the writing stands askew. At zero it reads across the roll, from the bass side towards the treble, and the angle turns that reading direction towards the end of the roll, so that a right angle leaves it reading along the roll. A stamp pressed crooked and a label written lengthwise are both stated here.",
+                            "ontology": "reo:rotation"
+                        },
+                        "side": {
+                            "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                            "enum": [
+                                "recto",
+                                "verso"
+                            ],
+                            "type": "string",
+                            "ontology": "reo:side"
+                        },
                         "transcription": {
                             "$ref": "#/definitions/ObjectAssumption%3CTranscription%3E",
                             "description": "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.",
@@ -1462,6 +1521,15 @@
                             "description": "The medium the mark was drawn in, where it can be told.",
                             "ontology": "reo:method"
                         },
+                        "side": {
+                            "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                            "enum": [
+                                "recto",
+                                "verso"
+                            ],
+                            "type": "string",
+                            "ontology": "reo:side"
+                        },
                         "vertical": {
                             "$ref": "#/definitions/VerticalSpan",
                             "description": "Vertical span of the feature on the roll. Left out by a feature a patch bears.",
@@ -1518,6 +1586,20 @@
                             "type": "string",
                             "ontology": "crm:P45 consists of"
                         },
+                        "rotation": {
+                            "$ref": "#/definitions/Measure%3C%22deg%22%3E",
+                            "description": "How far the patch was stuck on askew. At zero its edges stand square to the roll, and the angle turns them towards the end of it, as a writing's reading direction turns.",
+                            "ontology": "reo:rotation"
+                        },
+                        "side": {
+                            "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                            "enum": [
+                                "recto",
+                                "verso"
+                            ],
+                            "type": "string",
+                            "ontology": "reo:side"
+                        },
                         "vertical": {
                             "$ref": "#/definitions/VerticalSpan",
                             "description": "Vertical span of the feature on the roll. Left out by a feature a patch bears.",
@@ -2385,7 +2467,7 @@
                     "ontology": "crm:P126 employed"
                 },
                 "produced": {
-                    "description": "The features the punching brought into being, which are the note and expression perforations. A reading of a scan finds every hole on the paper at once and states it here. A hole an editor reads as punched later belongs in the act that made it.",
+                    "description": "The features the copy came from its punching with: the note and expression perforations, and now and then a mark the perforator left. A reading of a scan finds every hole on the paper at once and states it here, and a feature an editor reads as the work of a later hand belongs in the act that made it, whichever kind of feature it is.",
                     "items": {
                         "$ref": "#/definitions/AnyFeature"
                     },
@@ -2406,6 +2488,9 @@
             "type": "object",
             "ontology": "lrmoo:F32 Item Production Event"
         },
+        "Quantity<\"deg\">": {
+            "type": "number"
+        },
         "Quantity<\"ft/min\">": {
             "type": "number"
         },
@@ -3005,6 +3090,20 @@
                     "description": "The method by which this writing was produced (e.g. through print, handwriting, or stamping).",
                     "ontology": "reo:method"
                 },
+                "rotation": {
+                    "$ref": "#/definitions/Measure%3C%22deg%22%3E",
+                    "description": "How far the writing stands askew. At zero it reads across the roll, from the bass side towards the treble, and the angle turns that reading direction towards the end of the roll, so that a right angle leaves it reading along the roll. A stamp pressed crooked and a label written lengthwise are both stated here.",
+                    "ontology": "reo:rotation"
+                },
+                "side": {
+                    "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
+                    "enum": [
+                        "recto",
+                        "verso"
+                    ],
+                    "type": "string",
+                    "ontology": "reo:side"
+                },
                 "transcription": {
                     "$ref": "#/definitions/ObjectAssumption%3CTranscription%3E",
                     "description": "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.",

package/lib/spec/context.json

@@ -247,6 +247,15 @@
             "@context": { "@vocab": "https://w3id.org/reo/type/" }
         },
         "transcription": "crm:P128_carries",
+        "side": {
+            "@id": "reo:side",
+            "@type": "@vocab",
+            "@context": { "@vocab": "https://w3id.org/reo/type/" }
+        },
+        "rotation": {
+            "@id": "reo:rotation",
+            "@context": { "value": "crm:P90_has_value" }
+        },
         "material": {
             "@id": "crm:P45_consists_of",
             "@type": "@vocab",

package/package.json

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