keyframekit 1.0.0

package/src/KeyframeKit.ts

@@ -0,0 +1,508 @@
+//
+// KeyframeKit
+// Ben Hatsor
+// 
+// See README.md for usage.
+//
+
+
+const CHARS = {
+  PERCENT_SIGN: '%',
+  HYPHEN_MINUS: '-',
+  DOUBLE_HYPHEN_MINUS: '--',
+  WEBKIT_PREFIX: '-webkit-'
+} as const;
+
+
+export type KeyframesFactorySource = StyleSheetList | CSSStyleSheet;
+
+class KeyframesFactory {
+
+  readonly Error = {
+    KeyframesRuleNameTypeError: class KeyframesRuleNameTypeError extends TypeError {
+      message = `Keyframes rule name must be a string.`;
+    },
+    SourceTypeError: class SourceTypeError extends TypeError {
+      message = `Source must be either a Document, a ShadowRoot or a CSSStyleSheet instance.`;
+    },
+    StyleSheetImportError: class StyleSheetImportError extends Error {
+      message = `The stylesheet could not be imported.`;
+    }
+  } as const;
+
+
+  async getDocumentStyleSheetsOnLoad({ document = window.document }: {
+    document?: Document
+  } = {}) {
+
+    await waitForDocumentLoad({
+      document: document
+    });
+
+    return document.styleSheets;
+
+  }
+
+  
+  /** @remarks
+   *  Note: `@import` rules won't be resolved in imported stylesheets.  
+   *  See https://github.com/WICG/construct-stylesheets/issues/119#issuecomment-588352418. */
+  async importStyleSheet(url: string) {
+
+    const resp = await fetch(url);
+
+    if (!resp.ok) {
+      throw new this.Error.StyleSheetImportError();
+    }
+
+    const respText = await resp.text();
+
+    // remove file name from URL to get base URL
+    const baseURL = url.split('/').slice(0, -1).join('/');
+
+    const styleSheet = new CSSStyleSheet({
+      baseURL: baseURL
+    });
+
+    await styleSheet.replace(respText);
+
+    return styleSheet;
+
+  }
+  
+  
+  /** @param obj.of The name of the `@keyframes` rule to get keyframes from. */
+  getStyleSheetKeyframes({ of: ruleName, in: source }: {
+    of: string,
+    in: KeyframesFactorySource
+  }): ParsedKeyframes | undefined {
+
+    if (typeof ruleName !== 'string') {
+      throw new this.Error.KeyframesRuleNameTypeError();
+    }
+
+    if (source instanceof StyleSheetList) {
+
+      return this.#getStyleSheetKeyframesInStyleSheetList({
+        of: ruleName,
+        styleSheetList: source
+      });
+
+    } else if (source instanceof CSSStyleSheet) {
+
+      return this.#getStyleSheetKeyframesInStyleSheet({
+        of: ruleName,
+        styleSheet: source
+      });
+
+    } else {
+
+      throw new this.Error.SourceTypeError();
+
+    }
+
+  }
+
+  #getStyleSheetKeyframesInStyleSheetList({ of: ruleName, styleSheetList }: {
+    of: string,
+    styleSheetList: StyleSheetList
+  }): ParsedKeyframes | undefined {
+
+    for (const styleSheet of styleSheetList) {
+
+      const keyframesRule = this.#getStyleSheetKeyframesInStyleSheet({
+        of: ruleName,
+        styleSheet: styleSheet
+      });
+
+      if (keyframesRule !== undefined) {
+        return keyframesRule;
+      }
+
+    }
+
+  }
+
+  #getStyleSheetKeyframesInStyleSheet({ of: ruleName, styleSheet }: {
+    of: string,
+    styleSheet: CSSStyleSheet
+  }): ParsedKeyframes | undefined {
+
+    for (const rule of styleSheet.cssRules) {
+
+      if (!(rule instanceof CSSKeyframesRule)) {
+        continue;
+      }
+
+      if (rule.name === ruleName) {
+
+        const keyframes = this.parseKeyframesRule({
+          rule: rule
+        });
+
+        return keyframes;
+
+      }
+
+    }
+
+  }
+
+
+  getAllStyleSheetKeyframesRules({ in: source }: {
+    in: KeyframesFactorySource
+  }): ParsedKeyframesRules {
+
+    if (source instanceof StyleSheetList) {
+
+      return this.#getAllStyleSheetKeyframesRulesInStyleSheetList({
+        styleSheetList: source
+      });
+
+    } else if (source instanceof CSSStyleSheet) {
+
+      return this.#getAllStyleSheetKeyframesRulesInStyleSheet({
+        styleSheet: source
+      });
+
+    } else {
+
+      throw new this.Error.SourceTypeError();
+
+    }
+
+  }
+
+  #getAllStyleSheetKeyframesRulesInStyleSheetList({ styleSheetList }: {
+    styleSheetList: StyleSheetList
+  }): ParsedKeyframesRules {
+
+    let keyframesRules: ParsedKeyframesRules = {};
+
+    for (const styleSheet of styleSheetList) {
+
+      const styleSheetKeyframesRules = this.#getAllStyleSheetKeyframesRulesInStyleSheet({
+        styleSheet: styleSheet
+      });
+
+      keyframesRules = {
+        ...keyframesRules,
+        ...styleSheetKeyframesRules
+      };
+
+    }
+
+    return keyframesRules;
+
+  }
+
+  #getAllStyleSheetKeyframesRulesInStyleSheet({ styleSheet }: {
+    styleSheet: CSSStyleSheet
+  }): ParsedKeyframesRules {
+
+    let keyframesRules: ParsedKeyframesRules = {};
+
+    for (const rule of styleSheet.cssRules) {
+
+      if (!(rule instanceof CSSKeyframesRule)) {
+        continue;
+      }
+
+      const keyframes = this.parseKeyframesRule({
+        rule: rule
+      });
+
+      keyframesRules[rule.name] = keyframes;
+
+    }
+
+    return keyframesRules;
+
+  }
+
+
+  parseKeyframesRule({ rule: keyframes }: {
+    rule: CSSKeyframesRule
+  }): ParsedKeyframes {
+
+    let parsedKeyframes: Keyframe[] = [];
+
+    for (const keyframe of keyframes) {
+
+      // remove trailing '%'
+      /// https://drafts.csswg.org/css-animations/#dom-csskeyframerule-keytext
+      const percentString = removeSuffix({
+        of: keyframe.keyText,
+        suffix: CHARS.PERCENT_SIGN
+      });
+      
+      const percent = Number(percentString);
+
+      const offset = percent / 100;
+
+
+      let parsedProperties: KeyframeProperties = {};
+
+      for (const propertyName of keyframe.style) {
+
+        /// https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/getPropertyValue
+        const propertyValue = keyframe.style.getPropertyValue(propertyName);
+        
+        /// https://drafts.csswg.org/web-animations-1/#ref-for-animation-property-name-to-idl-attribute-name%E2%91%A0
+        const attributeName = this.#animationPropertyNameToIDLAttributeName(
+          propertyName
+        );
+
+        parsedProperties[attributeName] = propertyValue;
+
+      }
+
+
+      const parsedKeyframe: Keyframe = {
+        ...parsedProperties,
+        offset: offset
+      };
+
+      parsedKeyframes.push(parsedKeyframe);
+      
+    }
+
+    const parsedKeyframesInstance = new ParsedKeyframes(parsedKeyframes);
+
+    return parsedKeyframesInstance;
+
+  }
+  
+
+  /** https://drafts.csswg.org/web-animations-1/#animation-property-name-to-idl-attribute-name */
+  #animationPropertyNameToIDLAttributeName(property: string) {
+
+    if (this.#isCustomPropertyName(property)) return property;
+
+    if (property === 'float') return 'cssFloat';
+
+    if (property === 'offset') return 'cssOffset';
+
+    // https://drafts.csswg.org/cssom/#ref-for-supported-css-property%E2%91%A2
+    const lowercaseFirst = this.#isWebkitCasedAttribute(property);
+
+    return this.#cssPropertyToIDLAttribute(property, lowercaseFirst);
+
+  }
+
+  /** https://drafts.csswg.org/cssom/#css-property-to-idl-attribute */
+  #cssPropertyToIDLAttribute(property: string, lowercaseFirst: boolean = false) {
+
+    let output = '';
+
+    let uppercaseNext = false;
+
+    if (lowercaseFirst) {
+      property = property.slice(1);
+    }
+
+    for (const c of property) {
+
+      if (c === CHARS.HYPHEN_MINUS) {
+
+        uppercaseNext = true;
+
+      } else if (uppercaseNext) {
+
+        uppercaseNext = false;
+
+        output += c.toUpperCase();
+
+      } else {
+
+        output += c;
+
+      }
+
+    }
+
+    return output;
+
+  }
+
+  /** https://drafts.csswg.org/css-variables-2/#typedef-custom-property-name */
+  #isCustomPropertyName(property: string) {
+    return property.startsWith(CHARS.DOUBLE_HYPHEN_MINUS) &&
+           property !== CHARS.DOUBLE_HYPHEN_MINUS;
+  }
+
+  /** https://drafts.csswg.org/cssom/#ref-for-supported-css-property%E2%91%A2 */
+  #isWebkitCasedAttribute(property: string) {
+    return property.startsWith(CHARS.WEBKIT_PREFIX);
+  }
+
+}
+
+export default new KeyframesFactory();
+export type { KeyframesFactory };
+
+/** https://drafts.csswg.org/web-animations-1/#processing-a-keyframes-argument */
+type KeyframeProperties = { [propertyName: string]: string };
+
+
+/** https://drafts.csswg.org/web-animations-1/#processing-a-keyframes-argument */
+export type KeyframeArgument = Keyframe[] | PropertyIndexedKeyframes;
+
+/** https://drafts.csswg.org/web-animations-1/#the-keyframeeffect-interface */
+export class KeyframeEffectParameters {
+
+  keyframes: KeyframeArgument;
+  options: KeyframeEffectOptions;
+
+  /**
+   * @param obj.keyframes [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats)
+   * @param obj.options [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#options)
+   */
+  constructor({ keyframes, options = {} }: {
+    keyframes: KeyframeArgument,
+    options?: number | KeyframeEffectOptions
+  }) {
+    this.keyframes = keyframes;
+    this.options = this.#parseOptionsArg(options);
+  }
+
+  /** 
+   * @param obj.target An element to attach the animation to.
+   * @param obj.options Additional keyframe effect options. Can override existing keys.
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#options)
+   * 
+   * @see Specifications:
+   * - https://drafts.csswg.org/web-animations-1/#the-keyframeeffect-interface
+   * - https://drafts.csswg.org/web-animations-1/#the-animation-interface
+   */
+  toAnimation({ target, options: additionalOptions = {}, timeline = document.timeline }: {
+    target: Element | null,
+    options?: number | KeyframeEffectOptions,
+    timeline?: AnimationTimeline
+  }): Animation {
+
+    additionalOptions = this.#parseOptionsArg(additionalOptions);
+
+    // override existing option keys with additional options
+    const options: KeyframeEffectOptions = {
+      ...this.options, ...additionalOptions
+    };
+
+
+    const keyframeEffect = new KeyframeEffect(
+      target,
+      this.keyframes,
+      options
+    );
+
+    const animation = new Animation(
+      keyframeEffect,
+      timeline
+    );
+
+    return animation;
+
+  }
+
+  /** https://drafts.csswg.org/web-animations-1/#dom-keyframeeffect-keyframeeffect-target-keyframes-options-options
+      https://drafts.csswg.org/web-animations-1/#dom-effecttiming-duration */
+  #parseOptionsArg(options: number | KeyframeEffectOptions) {
+
+    if (typeof options === 'number') {
+      return { duration: options };
+    }
+
+    return options;
+
+  }
+  
+}
+
+
+export class ParsedKeyframes {
+
+  keyframes: Keyframe[];
+
+  constructor(keyframes: Keyframe[]) {
+    this.keyframes = keyframes;
+  }
+
+  /** 
+   * @param options
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#options)
+   */
+  toKeyframeEffect(
+    options: number | KeyframeEffectOptions | null
+  ): KeyframeEffectParameters {
+
+    let keyframeEffect: KeyframeEffectParameters;
+
+    // convert (required) nullable to optional
+    if (options !== null) {
+      
+      keyframeEffect = new KeyframeEffectParameters({
+        keyframes: this.keyframes,
+        options: options
+      });
+    
+    } else {
+
+      keyframeEffect = new KeyframeEffectParameters({
+        keyframes: this.keyframes
+      });
+
+    }
+
+    return keyframeEffect;
+
+  }
+
+}
+
+
+export type ParsedKeyframesRules = {
+  [ruleName: string]: ParsedKeyframes
+};
+
+
+
+// MARK: - Util
+
+function removeSuffix({ of: string, suffix }: {
+  of: string,
+  suffix: string
+}) {
+
+  return string.slice(0, -suffix.length);
+
+}
+
+
+async function waitForDocumentLoad({ document }: {
+  document: Document
+}) {
+
+  if (document.readyState === 'complete') {
+    return;
+  }
+
+  const { promise, resolve } = Promise.withResolvers();
+
+  function onReadyStateChange() {
+    if (document.readyState === 'complete') {
+      resolve(null);
+    }
+  }
+
+  const listener = [
+    'readystatechange',
+    onReadyStateChange
+  ] as const;
+
+  document.addEventListener(...listener);
+
+  await promise;
+
+  document.removeEventListener(...listener);
+
+}

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [],
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "src",
+    "outDir": "dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "esnext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}

package/vercel.json

@@ -0,0 +1,13 @@
+{
+  "headers": [
+    {
+      "source": "/assets/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "max-age=31536000, immutable"
+        }
+      ]
+    }
+  ]
+}