simplestyle-js 3.3.0 → 3.4.0

package/src/createStyles.ts

@@ -0,0 +1,251 @@
+import { Properties } from 'csstype';
+import merge from 'deepmerge';
+
+import { generateClassName } from './generateClassName.js';
+import { getPosthooks } from './plugins.js';
+import { SimpleStyleRules } from './types.js';
+
+export type CreateStylesOptions = Partial<{
+  /**
+   * If true, automatically renders generated styles
+   * to the DOM in an injected <style /> tag
+   */
+  flush: boolean;
+
+  /**
+   * If set, along with flush: true,
+   * will render the injected <style /> after this element
+   */
+  insertAfter?: HTMLElement;
+  /**
+   * If set, along with flush: true,
+   * will render the injects <style /> before this element
+   */
+  insertBefore?: HTMLElement;
+}>;
+
+function isNestedSelector(r: string): boolean {
+  return /&/g.test(r);
+}
+
+function isMedia(r: string): boolean {
+  return r.toLowerCase().startsWith('@media');
+}
+
+function formatCSSRuleName(rule: string): string {
+  return rule.replaceAll(/([A-Z])/g, p1 => `-${p1.toLowerCase()}`);
+}
+
+function formatCSSRules(cssRules: Properties): string {
+  return Object.entries(cssRules).reduce(
+    (prev, [cssProp, cssVal]) => `${prev}${formatCSSRuleName(cssProp)}:${String(cssVal)};`,
+    '',
+  );
+}
+
+function execCreateStyles<T extends SimpleStyleRules, K extends keyof T, O extends Record<K, string>>(
+  rules: T,
+  options: CreateStylesOptions,
+  parentSelector: string | null,
+  noGenerateClassName = false,
+): { classes: O; sheetBuffer: string; mediaQueriesBuffer: string } {
+  const out = {} as O;
+  let sheetBuffer = '';
+  let mediaQueriesBuffer = '';
+  const styleEntries = Object.entries(rules);
+  let ruleWriteOpen = false;
+  const guardCloseRuleWrite = () => {
+    if (ruleWriteOpen) sheetBuffer += '}';
+    ruleWriteOpen = false;
+  };
+  for (const [classNameOrCSSRule, classNameRules] of styleEntries) {
+    // if the classNameRules is a string, we are dealing with a display: none; type rule
+    if (isMedia(classNameOrCSSRule)) {
+      if (typeof classNameRules !== 'object')
+        throw new Error('Unable to map @media query because rules / props are an invalid type');
+      guardCloseRuleWrite();
+      mediaQueriesBuffer += `${classNameOrCSSRule}{`;
+      const { mediaQueriesBuffer: mediaQueriesOutput, sheetBuffer: regularOutput } = execCreateStyles(
+        classNameRules as T,
+        options,
+        parentSelector,
+      );
+      mediaQueriesBuffer += regularOutput;
+      mediaQueriesBuffer += '}';
+      mediaQueriesBuffer += mediaQueriesOutput;
+    } else if (isNestedSelector(classNameOrCSSRule)) {
+      if (!parentSelector) throw new Error('Unable to generate nested rule because parentSelector is missing');
+      guardCloseRuleWrite();
+      // format of { '& > span': { display: 'none' } } (or further nesting)
+      const replaced = classNameOrCSSRule.replaceAll('&', parentSelector);
+      for (const selector of replaced.split(/,\s*/)) {
+        const { mediaQueriesBuffer: mediaQueriesOutput, sheetBuffer: regularOutput } = execCreateStyles(
+          classNameRules as T,
+          options,
+          selector,
+        );
+        sheetBuffer += regularOutput;
+        mediaQueriesBuffer += mediaQueriesOutput;
+      }
+    } else if (!parentSelector && typeof classNameRules === 'object') {
+      guardCloseRuleWrite();
+      const generated = noGenerateClassName ? classNameOrCSSRule : generateClassName(classNameOrCSSRule);
+      // @ts-expect-error - yes, we can index this object here, so be quiet
+      out[classNameOrCSSRule] = generated;
+      const generatedSelector = `${noGenerateClassName ? '' : '.'}${generated}`;
+      const { mediaQueriesBuffer: mediaQueriesOutput, sheetBuffer: regularOutput } = execCreateStyles(
+        classNameRules as T,
+        options,
+        generatedSelector,
+      );
+      sheetBuffer += regularOutput;
+      mediaQueriesBuffer += mediaQueriesOutput;
+    } else {
+      if (!parentSelector) throw new Error('Unable to write css props because parent selector is null');
+      if (ruleWriteOpen) {
+        sheetBuffer += formatCSSRules({ [classNameOrCSSRule]: classNameRules });
+      } else {
+        sheetBuffer += `${parentSelector}{${formatCSSRules({ [classNameOrCSSRule]: classNameRules })}`;
+        ruleWriteOpen = true;
+      }
+    }
+  }
+  guardCloseRuleWrite();
+  return {
+    classes: out,
+    sheetBuffer,
+    mediaQueriesBuffer,
+  };
+}
+
+function replaceBackReferences<O extends Record<string, string>>(out: O, sheetContents: string): string {
+  let outputSheetContents = sheetContents;
+  const toReplace: string[] = [];
+  const toReplaceRegex = /\$\w([a-zA-Z0-9_-]+)?/gm;
+  let matches = toReplaceRegex.exec(outputSheetContents);
+  while (matches) {
+    toReplace.push(matches[0].valueOf());
+    matches = toReplaceRegex.exec(outputSheetContents);
+  }
+  for (const r of toReplace) {
+    outputSheetContents = outputSheetContents.replace(r, `.${out[r.slice(1)] ?? ''}`);
+  }
+  return getPosthooks().reduce((prev, hook) => hook(prev), outputSheetContents);
+}
+
+function createSheet(sheetContents: string) {
+  const doc = globalThis.document as Partial<typeof globalThis.document> | null | undefined;
+  if (doc === undefined) return null;
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  if (typeof doc?.head?.appendChild !== 'function' || typeof doc.createElement !== 'function') return null;
+  const styleTag = doc.createElement('style');
+  styleTag.innerHTML = sheetContents;
+  return styleTag;
+}
+
+function flushSheetContents(sheetContents: string, options?: CreateStylesOptions) {
+  // In case we're in come weird test environment that doesn't support JSDom
+  const styleTag = createSheet(sheetContents);
+  if (styleTag) {
+    if (options?.insertAfter && options.insertBefore) {
+      throw new Error('Both insertAfter and insertBefore were provided. Please choose only one.');
+    }
+    if (options?.insertAfter?.after) options.insertAfter.after(styleTag as Node);
+    else if (options?.insertBefore?.before) options.insertBefore.before(styleTag as Node);
+    else document.head.append(styleTag);
+  }
+  return styleTag;
+}
+
+function coerceCreateStylesOptions(options?: CreateStylesOptions): CreateStylesOptions {
+  return {
+    flush: options && typeof options.flush === 'boolean' ? options.flush : true,
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function rawStyles<T extends SimpleStyleRules, K extends keyof T, O extends Record<K, string>>(
+  rules: T,
+  options?: Partial<CreateStylesOptions>,
+) {
+  const coerced = coerceCreateStylesOptions(options);
+  const { sheetBuffer: sheetContents, mediaQueriesBuffer: mediaQueriesContents } = execCreateStyles(
+    rules,
+    coerced,
+    null,
+    true,
+  );
+
+  const mergedContents = `${sheetContents}${mediaQueriesContents}`;
+
+  if (coerced.flush) flushSheetContents(mergedContents, options);
+  return mergedContents;
+}
+
+export function keyframes<T extends Record<string, Properties>>(
+  frames: T,
+  options?: CreateStylesOptions,
+): [string, string] {
+  const coerced = coerceCreateStylesOptions(options);
+  const keyframeName = generateClassName('keyframes_');
+  const { sheetBuffer: keyframesContents } = execCreateStyles(frames, coerced, null, true);
+  const sheetContents = `@keyframes ${keyframeName}{${keyframesContents}}`;
+  if (coerced.flush) flushSheetContents(sheetContents);
+  return [keyframeName, sheetContents];
+}
+
+export default function createStyles<T extends SimpleStyleRules, K extends keyof T, O extends Record<K, string>>(
+  rules: T,
+  options?: Partial<CreateStylesOptions>,
+) {
+  const coerced = coerceCreateStylesOptions(options);
+  const {
+    classes: out,
+    sheetBuffer: sheetContents,
+    mediaQueriesBuffer: mediaQueriesContents,
+  } = execCreateStyles(rules, coerced, null);
+
+  const mergedContents = `${sheetContents}${mediaQueriesContents}`;
+
+  const replacedSheetContents = replaceBackReferences(out, mergedContents);
+
+  let sheet: ReturnType<typeof flushSheetContents> = null;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const updateSheet = <T2 extends SimpleStyleRules, K2 extends keyof T2, O2 extends Record<K2, string>>(
+    updatedRules: Partial<T2>,
+  ) => {
+    if ((options?.flush && sheet) || !options?.flush) {
+      // We prefer the first set, and then we shallow merge
+      const {
+        classes: updatedOut,
+        sheetBuffer: updatedSheetContents,
+        mediaQueriesBuffer: updatedMediaQueriesContents,
+      } = execCreateStyles(merge(rules, updatedRules), { flush: false }, null);
+
+      const updatedMergedContents = `${updatedSheetContents}${updatedMediaQueriesContents}`;
+
+      const updatedReplacedSheetContents = replaceBackReferences(out, updatedMergedContents);
+      if (sheet) sheet.innerHTML = updatedReplacedSheetContents;
+      return { classes: updatedOut, stylesheet: updatedSheetContents } as {
+        classes: typeof updatedOut;
+        stylesheet: string;
+      };
+    }
+    return null;
+  };
+
+  if (coerced.flush) sheet = flushSheetContents(replacedSheetContents, options);
+  // Need this TS cast to get solid code assist from the consumption-side
+  return {
+    classes: out as unknown,
+    stylesheet: replacedSheetContents,
+    updateSheet,
+  } as {
+    classes: O;
+    stylesheet: string;
+    updateSheet: typeof updateSheet;
+  };
+}
+
+export type CreateStylesArgs = Parameters<typeof createStyles>;

package/src/generateClassName.ts

@@ -0,0 +1,43 @@
+import numToAlpha from './numToAlpha.js';
+
+let inc = Date.now();
+
+export function setSeed(seed: number | null): void {
+  if (seed === null) {
+    inc = Date.now();
+    return;
+  }
+  if (typeof seed !== 'number') throw new Error('Unable to setSeed as provided seed was not a valid number');
+  if (seed === Number.MAX_SAFE_INTEGER)
+    throw new Error('Unable to setSeed because the seed was already the maximum safe JavaScript number allowed');
+  if (seed === Number.POSITIVE_INFINITY || seed === Number.NEGATIVE_INFINITY)
+    throw new Error('Unable to setSeed. Positive or negative infinity is not allowed');
+  if (seed < 0) throw new Error('Unable to setSeed. Seed must be a number >= 0');
+  inc = seed;
+}
+
+const numPairsRegex = /(\d{1,2})/g;
+
+export function getUniqueSuffix(): string {
+  const numPairs: string[] = [];
+  const incStr = inc.toString();
+  let result = numPairsRegex.exec(incStr);
+  while (result) {
+    numPairs.push(result[0]);
+    result = numPairsRegex.exec(incStr);
+  }
+  let out = '_';
+  for (const pair of numPairs) {
+    const val = +pair;
+    if (val > 25) {
+      const [first, second] = pair.split('');
+      out += `${numToAlpha(Number(first))}${numToAlpha(Number(second))}`;
+    } else out += numToAlpha(val);
+  }
+  inc += 1;
+  return out;
+}
+
+export function generateClassName(c: string): string {
+  return `${c}${getUniqueSuffix()}`;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type { CreateStylesArgs, CreateStylesOptions } from './createStyles.js';
+export { default as createStyles, keyframes, rawStyles } from './createStyles.js';
+export { setSeed } from './generateClassName.js';
+export type { PosthookPlugin } from './plugins.js';
+export { registerPosthook } from './plugins.js';
+export type { SimpleStyleRules } from './types.js';

package/src/numToAlpha.ts

@@ -0,0 +1,5 @@
+const alphas = 'abcdefghijklmnopqrstuvwxyz'.split('');
+
+export default function numToAlpha(num: number): string {
+  return String(alphas[num]);
+}

package/src/plugins.ts

@@ -0,0 +1,11 @@
+export type PosthookPlugin = (sheetContents: string) => string;
+
+const posthooks: PosthookPlugin[] = [];
+
+export function getPosthooks(): PosthookPlugin[] {
+  return posthooks;
+}
+
+export function registerPosthook(posthook: PosthookPlugin) {
+  posthooks.push(posthook);
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export * from './useCreateStyles.js';

package/src/react/useCreateStyles.ts

@@ -0,0 +1,58 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import createStyles, { CreateStylesOptions } from '../createStyles.js';
+import { SimpleStyleRules } from '../types.js';
+import { deepEqual } from '../util/index.js';
+
+export function useCreateStyles<T extends SimpleStyleRules, K extends keyof T, O extends Record<K, string>>(
+  rules: T,
+  options?: Partial<Omit<CreateStylesOptions, 'flush'>>,
+) {
+  // cache rules to compare later
+  const [cachedRules, setCachedRules] = useState(() => rules);
+
+  // memoize options but keep them live
+  const cachedOptions = useMemo(() => ({ ...options }) as Partial<Omit<CreateStylesOptions, 'flush'>>, [options]);
+
+  const didFirstWriteRef = useRef(false);
+  const styleTagRef = useRef(typeof document === 'undefined' ? null : document.createElement('style'));
+
+  // initialize styles
+  const [styleState, setStyleState] = useState(() => createStyles<T, K, O>(rules, { ...cachedOptions, flush: false }));
+
+  const { classes, stylesheet, updateSheet } = styleState;
+
+  // mount/unmount style tag
+  useEffect(() => {
+    if (!styleTagRef.current) return;
+    const { current: s } = styleTagRef;
+    document.head.append(s);
+    return () => {
+      s.remove();
+    };
+  }, []);
+
+  // update stylesheet when rules change
+  useEffect(() => {
+    if (!styleTagRef.current) return;
+
+    if (!didFirstWriteRef.current) {
+      didFirstWriteRef.current = true;
+      styleTagRef.current.innerHTML = stylesheet;
+      return;
+    }
+
+    if (!deepEqual(rules, cachedRules)) {
+      setCachedRules(rules);
+      const updated = updateSheet(rules);
+      if (updated) {
+        styleTagRef.current.innerHTML = updated.stylesheet;
+        // use the fresh updateSheet from updated
+        // @ts-expect-error - this cast is safe and is only for us, internally, anyways
+        setStyleState({ ...updated, updateSheet });
+      }
+    }
+  }, [cachedRules, rules, stylesheet, updateSheet]); // only depend on rules + updater
+
+  return classes;
+}

package/src/types.ts

@@ -0,0 +1,7 @@
+import { Properties } from 'csstype';
+
+export type SimpleStyleRules = {
+  [key: string]: Properties | SimpleStyleRules;
+};
+
+export type RenderableSimpleStyleRules = SimpleStyleRules & Record<string, Properties[]>;

package/src/util/deepEqual.ts

@@ -0,0 +1,20 @@
+export function deepEqual<
+  O1 extends Record<string | number | symbol, any>,
+  O2 extends Record<string | number | symbol, any>,
+>(o1: O1, o2: O2): boolean {
+  // We'll sort the keys, just in case the user kept things the same but the object is all wonky, order-wise
+  const o1Keys = Object.keys(o1).sort();
+  const o2Keys = Object.keys(o2).sort();
+  if (o1Keys.length !== o2Keys.length) return false;
+  if (o1Keys.some((key, i) => o2Keys[i] !== key)) return false;
+  // Okay, the keys SHOULD be the same
+  // so we need to test their values, recursively, to verify equality
+  return o1Keys.reduce<boolean>((prev, key) => {
+    if (!prev) return prev; // we've already failed equality checks here
+    if (!(key in o2)) return false;
+    if (typeof o1[key] !== 'object') {
+      return o1[key] === o2[key];
+    }
+    return deepEqual(o1[key], o2[key]);
+  }, true);
+}

package/src/util/index.ts

@@ -0,0 +1 @@
+export * from './deepEqual.js';