add ribbon + test + docs

packages/core/pattern.mjs

@@ -2028,6 +2028,16 @@ export const bypass = register('bypass', function (on, pat) {
   return on ? silence : pat;
 });
 
+/**
+ * Loops the pattern inside at `offset` for `cycles`.
+ * @param {number} offset start point of loop in cycles
+ * @param {number} cycles loop length in cycles
+ * @example
+ * // Looping a portion of randomness
+ * note(irand(8).segment(4).scale('C3 minor')).ribbon(1337, 2)
+ */
+export const ribbon = register('ribbon', (offset, cycles, pat) => pat.early(offset).restart(pure(1).slow(cycles)));
+
 // sets absolute duration of haps
 // TODO - fix
 export const duration = register('duration', function (value, pat) {

packages/core/test/pattern.test.mjs

@@ -914,6 +914,13 @@ describe('Pattern', () => {
       expect(run(4).firstCycle()).toStrictEqual(sequence(0, 1, 2, 3).firstCycle());
     });
   });
+  describe('ribbon', () => {
+    it('Can ribbon', () => {
+      expect(cat(0, 1, 2, 3, 4, 5, 6, 7).ribbon(2, 4).fast(4).firstCycle()).toStrictEqual(
+        sequence(2, 3, 4, 5).firstCycle(),
+      );
+    });
+  });
   describe('linger', () => {
     it('Can linger on the first quarter of a cycle', () => {
       expect(sequence(0, 1, 2, 3, 4, 5, 6, 7).linger(0.25).firstCycle()).toStrictEqual(

test/__snapshots__/examples.test.mjs.snap

@@ -3066,6 +3066,27 @@ exports[`runs examples > example "rev" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "ribbon" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:C3 ]",
+  "[ 1/4 → 1/2 | note:G3 ]",
+  "[ 1/2 → 3/4 | note:Eb3 ]",
+  "[ 3/4 → 1/1 | note:Bb3 ]",
+  "[ 1/1 → 5/4 | note:C3 ]",
+  "[ 5/4 → 3/2 | note:D3 ]",
+  "[ 3/2 → 7/4 | note:G3 ]",
+  "[ 7/4 → 2/1 | note:Eb3 ]",
+  "[ 2/1 → 9/4 | note:C3 ]",
+  "[ 9/4 → 5/2 | note:G3 ]",
+  "[ 5/2 → 11/4 | note:Eb3 ]",
+  "[ 11/4 → 3/1 | note:Bb3 ]",
+  "[ 3/1 → 13/4 | note:C3 ]",
+  "[ 13/4 → 7/2 | note:D3 ]",
+  "[ 7/2 → 15/4 | note:G3 ]",
+  "[ 15/4 → 4/1 | note:Eb3 ]",
+]
+`;
+
 exports[`runs examples > example "room" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd room:0 ]",

website/src/pages/learn/time-modifiers.mdx

@@ -101,3 +101,7 @@ Some of these have equivalent operators in the Mini Notation:
 ## cpm
 
 <JsDoc client:idle name="cpm" h={0} />
+
+## ribbon
+
+<JsDoc client:idle name="ribbon" h={0} />