cubing 0.23.0 → 0.24.0-pre1

package/docs/main.css

@@ -1,193 +0,0 @@
-@import url("https://fonts.googleapis.com/css2?family=Ubuntu+Mono&family=Ubuntu:ital,wght@0,400;0,700;1,400&display=swap");
-
-html,
-body {
-  margin: 0;
-  font-family: Ubuntu, Tahoma, sans-serif;
-  line-height: 1.25em;
-}
-
-body {
-  background-color: #eaeaea;
-  background-image: linear-gradient(
-      45deg,
-      #ddd 25%,
-      transparent 25%,
-      transparent 75%,
-      #ddd 75%,
-      #ddd
-    ),
-    linear-gradient(
-      45deg,
-      #ddd 25%,
-      transparent 25%,
-      transparent 75%,
-      #ddd 75%,
-      #ddd
-    );
-  background-size: 32px 32px;
-  background-position: 0 0, 16px 16px;
-}
-
-body {
-  padding: 1rem;
-  box-sizing: border-box;
-}
-
-@media (max-width: 500px) {
-  body {
-    padding: 0;
-  }
-}
-
-code {
-  font-family: "Ubuntu Mono", monospace;
-}
-
-content {
-  margin: auto;
-  display: block;
-  box-sizing: border-box;
-  width: 1200px;
-  max-width: 100%;
-  background: white;
-  box-shadow: 0 0 1rem rgba(0, 0, 0, 0.25);
-}
-
-#heading {
-  padding: 0.75em;
-  background: #4285f4;
-  color: white;
-  font-size: 2em;
-}
-
-#heading a {
-  color: currentColor;
-}
-
-#heading.heading-with-player {
-  padding: 0.25em 0.5em;
-}
-
-section {
-  padding: 2rem 2rem;
-}
-
-section.no-header {
-  padding-top: 1rem;
-  padding-bottom: 1rem;
-}
-
-section:not(:first-child) {
-  border-top: 1px solid #4285f466;
-}
-
-section:target,
-div:target {
-  background: #00448811;
-}
-
-section :is(h1, h2, h3) {
-  margin-top: 0;
-}
-
-section :is(h1, h2, h3) a:hover::before {
-  position: absolute;
-  transform: translateX(-1.25em);
-  font-size: 0.75em;
-  content: "🔗";
-}
-
-section :is(h1, h2, h3) a {
-  color: inherit;
-}
-
-section :is(h1, h2, h3) a:not(:hover) {
-  text-decoration: none;
-}
-
-code.sample {
-  display: block;
-  padding: 1em;
-  margin: 0.5rem 0;
-  background: #4285f422;
-  line-height: 1.25em;
-  overflow: hidden;
-  overflow-x: auto;
-}
-
-code.output {
-  display: block;
-  padding: 1em;
-  margin: 0.5rem 0;
-  background: #4285f422;
-  line-height: 1.25em;
-  overflow: hidden;
-  overflow-x: auto;
-}
-
-code.sample.output {
-  background: #4285f4;
-  color: white;
-}
-
-code.sample.output > span::before {
-  content: "⇒ ";
-  opacity: 0.3;
-  font-size: 2em;
-  vertical-align: -20%;
-}
-
-code.sample > span {
-  display: block;
-}
-
-code.sample > span:not(:first-child) {
-  margin-top: 0.5em;
-}
-
-twisty-player {
-  max-width: 100%;
-}
-
-.code-demo {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 0.5em;
-  padding: 0.5em;
-  border: 1px solid #00000022;
-  overflow-x: hidden;
-  box-sizing: border-box;
-}
-
-.code-demo > div:first-child {
-  overflow-x: hidden;
-}
-
-.code-demo code.sample {
-  margin: 0;
-}
-
-.code-demo twisty-player {
-  width: 100%;
-  height: 100%;
-  min-height: 256px;
-}
-
-@media (max-width: 768px) {
-  .code-demo {
-    grid-template-columns: 1fr;
-  }
-}
-
-code.sample span.js-object {
-  background: rgba(0, 0, 0, 0.05);
-  border: 2px solid rgba(255, 255, 255, 0.25);
-  padding: 0.2em;
-  margin: -0.2em -0.1em;
-  border-radius: 0.3em;
-}
-
-.boilerplate {
-  color: #559bd4;
-}

package/src/cubing/alg/Alg.spec.ts

@@ -1,10 +0,0 @@
-import { Alg } from "./Alg";
-import "./test/alg-comparison";
-
-describe("operation", () => {
-  it("can be constructed from a string", () => {
-    expect(new Alg("R U R'").toString()).toEqual("R U R'");
-
-    // expect(Array.from(new Alg("R U R'").units)).toHaveLength(3);
-  });
-});

package/src/cubing/alg/Alg.ts

@@ -1,290 +0,0 @@
-import { AlgCommon, Comparable } from "./common";
-import { experimentalIs, experimentalIsUnit } from "./is";
-import { direct, IterationDirection, reverse } from "./iteration";
-import { parseAlg } from "./parse";
-import { simplify, SimplifyOptions } from "./traversal";
-import { LineComment } from "./units/leaves/LineComment";
-import { Move } from "./units/leaves/Move";
-import { Newline } from "./units/leaves/Newline";
-import type { LeafUnit, Unit } from "./units/Unit";
-import { warnOnce } from "./warnOnce";
-
-export type FlexibleAlgSource = string | Iterable<Unit> | Alg;
-
-// TODO: validate
-function toIterable(input?: FlexibleAlgSource): Iterable<Unit> {
-  if (!input) {
-    return [];
-  }
-
-  if (experimentalIs(input, Alg)) {
-    return (input as Alg).units();
-  }
-
-  if (typeof input === "string") {
-    return parseAlg(input).units(); // TODO: something more direct?
-  }
-
-  // const seq = inputUnits as Sequence;
-  // if (seq.type === "sequence" && seq.nestedUnits) {
-  //   throw new Error("unimplemented");
-  //   // return seq.nestedUnits;
-  // }
-
-  const iter = input as Iterable<Unit>;
-  if (typeof iter[Symbol.iterator] === "function") {
-    return iter; // TODO: avoid allocations
-  }
-
-  throw "Invalid unit";
-}
-
-// Preserves the alg if it's already an `Alg`.
-export function experimentalEnsureAlg(alg: FlexibleAlgSource): Alg {
-  if (experimentalIs(alg, Alg)) {
-    return alg as Alg;
-  }
-  return new Alg(alg);
-}
-
-/**
- * Alg is a class that encapsulated a structured alg. To create an alg from a string, use:
- *
- *     new Alg("R U R'"); // Convenient
- *     Alg.fromString(dynamicString); // Recommended when handling dynamic input.
- *
- * Once you have an Alg, you can call methods to transform it:
- *
- *     new Alg("[[R: U], R U R2']").expand().simplify().invert();
- *
- * To convert an Alg to a string, use .toString():
- *
- *     new Alg("R U F").invert().toString();
- *
- * If you need to debug, you may also find it convenient to use .log():
- *
- *     if (alg.isIdentical(alg.invert())) {
- *       alg.log("A self-inverse!")
- *     }
- *
- * For more information, see: {@link https://js.cubing.net/cubing/alg/}
- *
- */
-export class Alg extends AlgCommon<Alg> {
-  // #debugString: string;
-  #units: Iterable<Unit>; // TODO: freeze?
-  constructor(alg?: FlexibleAlgSource) {
-    super();
-    this.#units = Array.from(toIterable(alg)); // TODO: can we avoid array-casting?
-    // this.#debugString = this.toString();
-
-    for (const unit of this.#units) {
-      if (!experimentalIsUnit(unit)) {
-        throw new Error("An alg can only contain units.");
-      }
-    }
-  }
-
-  /**
-   * Checks whether this Alg is structurally identical to another Alg. This
-   * essentially means that they are written identically apart from whitespace.
-   *
-   *     const alg1 = new Alg("R U L'");
-   *     const alg2 = new Alg("L U' R'").invert();
-   *     // true
-   *     alg1.isIdentical(alg2);
-   *
-   *     // false
-   *     new Alg("[R, U]").isIdentical(new Alg("R U R' U'"));
-   *     // true
-   *     new Alg("[R, U]").expand().isIdentical(new Alg("R U R' U'"));
-   *
-   * Note that .isIdentical() efficiently compares algorithms, but mainly exists
-   * to help optimize code when the structure of an algorithm hasn't changed.
-   * There are many ways to write the "same" alg on most puzzles, but is
-   * *highly* recommended to avoid expanding two Alg instances to compare them,
-   * since that can easily slow your program to a crawl if someone inputs an alg
-   * containing a large repetition. In general, you should use `cubing/kpuzzle`
-   * to compare if two algs have the same effect on a puzzle.
-   *
-   * Also note that parser annotations are not take into account while comparing
-   * algs:
-   *
-   *     const alg = new Alg([new Move("R"), new Move("U2")]);
-   *     // true, even though one of the algs has parser annotations
-   *     alg.isIdentical(new Alg("R U2"))
-   *
-   */
-  isIdentical(other: Comparable): boolean {
-    const otherAsAlg = other as Alg;
-    if (!other.is(Alg)) {
-      return false;
-    }
-
-    // TODO: avoid converting to array
-    const l1 = Array.from(this.#units);
-    const l2 = Array.from(otherAsAlg.#units);
-    if (l1.length !== l2.length) {
-      return false;
-    }
-    for (let i = 0; i < l1.length; i++) {
-      if (!l1[i].isIdentical(l2[i])) {
-        return false;
-      }
-    }
-    return true;
-  }
-
-  /**
-   * Returns the inverse of the given alg.
-   *
-   * Note that that this does not make any assumptions about what puzzle the alg
-   * is for. For example, U2 is its own inverse on a cube, but U2' has the same
-   * effect U3 (and not U2) on Megaminx:
-   *
-   *     // Outputs: R U2' L'
-   *     new Alg("L U2 R'").invert().log();
-   */
-  invert(): Alg {
-    // TODO: Handle newLines and comments correctly
-    // TODO: Make more efficient.
-    return new Alg(reverse(Array.from(this.#units).map((u) => u.invert())));
-  }
-
-  /** @deprecated Use {@link Alg.expand} instead. */
-  *experimentalExpand(
-    iterDir: IterationDirection = IterationDirection.Forwards,
-    depth?: number,
-  ): Generator<LeafUnit> {
-    depth ??= Infinity;
-    for (const unit of direct(this.#units, iterDir)) {
-      yield* unit.experimentalExpand(iterDir, depth);
-    }
-  }
-
-  /**
-   * Expands all Grouping, Commutator, and Conjugate parts nested inside the
-   * alg.
-   *
-   *     // F R U R' U' F'
-   *     new Alg("[F: [R, U]]").expand().log();
-   *
-   *     // F [R, U] F'
-   *     new Alg("[F: [R, U]]").expand(({ depth: 1 }).log();
-   *
-   * Avoid calling this on a user-provided alg unless the user explicitly asks
-   * to see the expanded alg. Otherwise, it's easy to make your program freeze
-   * when someone passes in an alg like: (R U)10000000
-   *
-   * Generally, if you want to perform an operation on an entire alg, you'll
-   * want to use something based on the `Traversal` mechanism, like countMoves()
-   * from `cubing/notation`.
-   */
-  expand(options?: { depth?: number }): Alg {
-    return new Alg(
-      this.experimentalExpand(
-        IterationDirection.Forwards,
-        options?.depth ?? Infinity,
-      ),
-    );
-  }
-
-  /** @deprecated */
-  *experimentalLeafMoves(): Generator<Move> {
-    for (const leaf of this.experimentalExpand()) {
-      if (leaf.is(Move)) {
-        yield leaf as Move;
-      }
-    }
-  }
-
-  concat(input: FlexibleAlgSource): Alg {
-    return new Alg(
-      Array.from(this.#units).concat(Array.from(toIterable(input))),
-    );
-  }
-
-  /** @deprecated */
-  experimentalIsEmpty(): boolean {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    for (const _ of this.#units) {
-      return false;
-    }
-    return true;
-  }
-
-  static fromString(s: string): Alg {
-    return parseAlg(s);
-  }
-
-  *units(): Generator<Unit> {
-    for (const unit of this.#units) {
-      yield unit;
-    }
-  }
-
-  experimentalNumUnits(): number {
-    return Array.from(this.#units).length;
-  }
-
-  /** @deprecated */
-  get type(): string {
-    warnOnce("deprecated: type");
-    return "sequence";
-  }
-
-  // toJSON(): AlgJSON {
-  //   return {
-  //     type: "alg",
-  //     units: Array.from(this.#units) as UnitJSON[],
-  //   };
-  // }
-
-  /**
-   * Converts the Alg to a string:
-   *
-   *     const alg = new Alg([new Move("R"), new Move("U2"), new Move("L")])
-   *     // R U2 L
-   *     console.log(alg.toString())
-   */
-  toString(): string {
-    let output = "";
-    let previousUnit: Unit | null = null;
-    for (const unit of this.#units) {
-      if (previousUnit) {
-        output += spaceBetween(previousUnit, unit);
-        // console.log("l", previousUnit.toString(), unit.toString(), output);
-      }
-      output += unit.toString();
-      previousUnit = unit;
-    }
-    return output;
-  }
-
-  // *experimentalExpand(options: ExperimentalExpandOptions): Generator<Unit> {
-  //   // if (options.depth === 0) {
-  //   //   yield* this.units();
-  //   //   return;
-  //   // }
-  //   // const newOptions = {
-  //   //   depth: options.depth ? options.depth - 1 : null,
-  //   // }; // TODO: avoid allocations?
-  //   // for (const unit of this.#units) {
-  //   //   yield* unit.experimentalExpandIntoAlg(newOptions);
-  //   // }
-  // }
-
-  simplify(options?: SimplifyOptions): Alg {
-    return new Alg(simplify(this, options ?? {}));
-  }
-}
-
-function spaceBetween(u1: Unit, u2: Unit): string {
-  if (u1.is(Newline) || u2.is(Newline)) {
-    return "";
-  }
-  if (u1.is(LineComment) && !u2.is(Newline)) {
-    return "\n"; /// TODO
-  }
-  return " ";
-}

package/src/cubing/alg/AlgBuilder.ts

@@ -1,33 +0,0 @@
-import { Alg } from "./Alg";
-import type { Unit } from "./units/Unit";
-
-export class AlgBuilder {
-  #units: Unit[] = [];
-
-  push(u: Unit): void {
-    this.#units.push(u);
-  }
-
-  // TODO: Allow FlexibleAlgSource?
-  /** @deprecated */
-  experimentalPushAlg(alg: Alg): void {
-    // TODO: Optimize?
-    for (const u of alg.units()) {
-      this.push(u);
-    }
-  }
-
-  // TODO: can we guarantee this to be fast in the permanent API?
-  experimentalNumUnits(): number {
-    return this.#units.length;
-  }
-
-  // can be called multiple times, even if you push units inbetween.
-  toAlg(): Alg {
-    return new Alg(this.#units);
-  }
-
-  reset(): void {
-    this.#units = [];
-  }
-}

package/src/cubing/alg/Serializable.ts

@@ -1,29 +0,0 @@
-// export interface MoveJSON {
-//   type: "move";
-//   family: string;
-//   innerLayer?: number;
-//   outerLayer?: number;
-// }
-
-// export interface GroupingJSON {
-//   type: "grouping";
-//   alg: AlgJSON;
-// }
-
-// export interface LineCommentJSON {
-//   type: "comment";
-//   text: string;
-// }
-
-// export interface CommutatorJSON {
-//   type: "commutator";
-//   A: AlgJSON;
-//   B: AlgJSON;
-// }
-
-// export type UnitJSON = MoveJSON | GroupingJSON;
-
-// export interface AlgJSON {
-//   type: "alg";
-//   units: UnitJSON[];
-// }

package/src/cubing/alg/common.ts

@@ -1,59 +0,0 @@
-import type { Alg } from "./Alg";
-import type { IterationDirection } from "./iteration";
-import type { LeafUnit, Unit } from "./units/Unit";
-
-let writeAlgDebugField = false;
-export function setAlgDebugField(debug: boolean): void {
-  writeAlgDebugField = debug;
-}
-
-export abstract class Comparable {
-  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-  is(c: any): boolean {
-    return this instanceof c;
-  }
-
-  as<T>(c: new (...args: any) => T): T | null {
-    return this instanceof c ? this : null;
-  }
-
-  abstract isIdentical(other: Comparable): boolean;
-}
-
-export interface Repeatable extends Comparable {
-  experimentalExpand(
-    iterDir?: IterationDirection,
-    depth?: number,
-  ): Generator<LeafUnit>;
-}
-
-// Common to algs or units
-export abstract class AlgCommon<T extends Alg | Unit>
-  extends Comparable
-  implements Repeatable
-{
-  constructor() {
-    super();
-    if (writeAlgDebugField) {
-      Object.defineProperty(this, "_debugStr", {
-        get: () => {
-          return this.toString();
-        },
-      });
-    }
-  }
-
-  get log(): (message?: any) => void {
-    // By returning a (bound) version of `console.log`, we ensure that DevTools
-    // logs the call site instead of this function.
-    return console.log.bind(console, this, this.toString()) as (
-      message?: any,
-    ) => void;
-  }
-
-  abstract toString(): string;
-
-  abstract invert(): T;
-
-  abstract experimentalExpand(iterDir: IterationDirection): Generator<LeafUnit>;
-}

package/src/cubing/alg/debug.ts

@@ -1,27 +0,0 @@
-type ReportingLevel = "none" | "warn" | "error";
-let currentReportingLevel = "warn";
-
-const MAX_NUMBER_OF_TIMES_TO_WARN = 10;
-let numWarned = 0;
-
-// TODO: Avoid creating the string message if it won't be used (e.g. by taking a function?).
-export function reportTypeMismatch(msg: string): void {
-  switch (currentReportingLevel) {
-    case "error":
-      throw new Error(msg);
-    case "warn":
-      numWarned++;
-      if (numWarned < MAX_NUMBER_OF_TIMES_TO_WARN) {
-        if (numWarned + 1 === MAX_NUMBER_OF_TIMES_TO_WARN) {
-          console.warn(msg);
-        }
-      }
-      return;
-  }
-}
-
-export function setAlgPartTypeMismatchReportingLevel(
-  level: ReportingLevel,
-): void {
-  currentReportingLevel = level;
-}