@studiometa/js-toolkit 3.9.0 → 4.0.0-alpha.1

package/dist/utils/selectors.d.ts

@@ -0,0 +1,19 @@
+//#region src/utils/selectors.d.ts
+/**
+ * The registry selector for a component name.
+ *
+ * `~=` gives whitespace-token matching, so `data-component="Action Dialog"`
+ * declares several components on one element. Scoped attributes are included
+ * as discovery candidates, so this selector deliberately over-matches: an
+ * element that declares a name only above a breakpoint matches it below one
+ * too. The narrowing is the caller's read of the element's instance map, not
+ * a mount check — an inactive declaration has no instance, because a
+ * breakpoint-withdrawn component is destroyed and deleted from that map. Do
+ * not re-add an `$isMounted` filter here or at a call site to "fix" the
+ * over-matching: it would also hide every instance a reversible `in-view` or
+ * `media:` strategy has legitimately stood down.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/dom.html#selectorfor
+ */
+declare function selectorFor(name: string): string;
+//#endregion
+export { selectorFor };

package/dist/utils/selectors.js

@@ -0,0 +1,25 @@
+import { COMPONENT_ATTRIBUTE } from "../attributes.js";
+import { responsiveAttributeNames } from "../responsive-options.js";
+//#region src/utils/selectors.ts
+/**
+* The registry selector for a component name.
+*
+* `~=` gives whitespace-token matching, so `data-component="Action Dialog"`
+* declares several components on one element. Scoped attributes are included
+* as discovery candidates, so this selector deliberately over-matches: an
+* element that declares a name only above a breakpoint matches it below one
+* too. The narrowing is the caller's read of the element's instance map, not
+* a mount check — an inactive declaration has no instance, because a
+* breakpoint-withdrawn component is destroyed and deleted from that map. Do
+* not re-add an `$isMounted` filter here or at a call site to "fix" the
+* over-matching: it would also hide every instance a reversible `in-view` or
+* `media:` strategy has legitimately stood down.
+* @link https://js-toolkit-v4.studiometa.dev/utils/dom.html#selectorfor
+*/
+function selectorFor(name) {
+	return [COMPONENT_ATTRIBUTE, ...responsiveAttributeNames(COMPONENT_ATTRIBUTE)].map((attribute) => `[${CSS.escape(attribute)}~="${name}"]`).join(",");
+}
+//#endregion
+export { selectorFor };
+
+//# sourceMappingURL=selectors.js.map

package/dist/utils/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","names":[],"sources":["../../src/utils/selectors.ts"],"sourcesContent":["import { COMPONENT_ATTRIBUTE } from '../attributes.js';\nimport { responsiveAttributeNames } from '../responsive-options.js';\n\n/**\n * The registry selector for a component name.\n *\n * `~=` gives whitespace-token matching, so `data-component=\"Action Dialog\"`\n * declares several components on one element. Scoped attributes are included\n * as discovery candidates, so this selector deliberately over-matches: an\n * element that declares a name only above a breakpoint matches it below one\n * too. The narrowing is the caller's read of the element's instance map, not\n * a mount check — an inactive declaration has no instance, because a\n * breakpoint-withdrawn component is destroyed and deleted from that map. Do\n * not re-add an `$isMounted` filter here or at a call site to \"fix\" the\n * over-matching: it would also hide every instance a reversible `in-view` or\n * `media:` strategy has legitimately stood down.\n * @link https://js-toolkit-v4.studiometa.dev/utils/dom.html#selectorfor\n */\nexport function selectorFor(name: string): string {\n  return [COMPONENT_ATTRIBUTE, ...responsiveAttributeNames(COMPONENT_ATTRIBUTE)]\n    .map((attribute) => `[${CSS.escape(attribute)}~=\"${name}\"]`)\n    .join(',');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,SAAgB,YAAY,MAAsB;CAChD,OAAO,CAAC,qBAAqB,GAAG,yBAAyB,mBAAmB,CAAC,CAAC,CAC3E,KAAK,cAAc,IAAI,IAAI,OAAO,SAAS,EAAE,KAAK,KAAK,GAAG,CAAC,CAC3D,KAAK,GAAG;AACb"}

package/dist/utils/smoothTo.d.ts

@@ -0,0 +1,77 @@
+import { SpringOptions } from "./maths.js";
+//#region src/utils/smoothTo.d.ts
+interface SmoothToOptions extends Omit<SpringOptions, 'damping'> {
+  /**
+   * Damping factor, or spring friction in spring mode. Defaults to `0.6`.
+   *
+   * A function is read on **every frame, for every channel**, which is what a
+   * consumer whose factor is an option needs: `$options` is a live view over
+   * attributes, so a value captured once would freeze an attribute the
+   * framework keeps live. It is also how a factor that depends on the
+   * direction of travel is expressed — read the current value and decide — and
+   * how a record gives one channel a different rate from its neighbour. A
+   * single value is asked about under the key `value`.
+   */
+  damping?: number | ((key: string) => number);
+  /**
+   * Spring physics instead of damping. Implied by `stiffness` or `mass`.
+   *
+   * The mode belongs to the instance, not to a channel: a record that wants a
+   * spring for one value and damping for another is two instances, and pays
+   * for two frame subscriptions to get it.
+   */
+  spring?: boolean;
+}
+interface SmoothTo {
+  /** Read the smoothed value, or set a new target and get the smoothed value. */
+  (value?: number): number;
+  /** Called with the smoothed value on every frame it moves. @returns Unsubscribe. */
+  subscribe(callback: (value: number) => unknown): () => void;
+  /** The target, unsmoothed. */
+  raw(): number;
+  /** Move the target by `delta`. */
+  add(delta: number): number;
+  /** Set the value and its target at once, with no travel and no frame. */
+  jump(value: number): number;
+  /** Whether the value is still travelling. */
+  readonly isMoving: boolean;
+  /** Release the frame subscription and remove all subscribers. */
+  destroy(): void;
+}
+/**
+ * Several named values on one frame subscription.
+ *
+ * The record handed to a reader or a subscriber is the **same object every
+ * frame**, as a service hands the same props: a 60 fps primitive should not
+ * allocate per frame, and a consumer reads it synchronously. Treat it as
+ * read-only.
+ */
+interface SmoothToRecord<K extends string> {
+  /** Read every smoothed value, or set some targets and read them back. */
+  (values?: Partial<Record<K, number>>): Record<K, number>;
+  /** Called on every frame any channel moves. @returns Unsubscribe. */
+  subscribe(callback: (values: Record<K, number>) => unknown): () => void;
+  /** The targets, unsmoothed. */
+  raw(): Record<K, number>;
+  /** Move some targets by a delta each. */
+  add(deltas: Partial<Record<K, number>>): Record<K, number>;
+  /** Set some values and their targets at once, with no travel and no frame. */
+  jump(values: Partial<Record<K, number>>): Record<K, number>;
+  /** Whether any channel is still travelling. */
+  readonly isMoving: boolean;
+  /** Release the frame subscription and remove all subscribers. */
+  destroy(): void;
+}
+/**
+ * Smooth a value toward a target with one shared frame subscription.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#smoothto
+ */
+declare function smoothTo(start?: number, options?: SmoothToOptions): SmoothTo;
+/**
+ * Smooth several named values toward their targets, on one frame subscription,
+ * with one settled state and one subscriber call per frame. The keys are the
+ * consumer's own — a scale, an opacity or a progress as readily as a coordinate.
+ */
+declare function smoothTo<K extends string>(start: Record<K, number>, options?: SmoothToOptions): SmoothToRecord<K>;
+//#endregion
+export { SmoothTo, SmoothToOptions, SmoothToRecord, smoothTo };

package/dist/utils/smoothTo.js

@@ -0,0 +1,93 @@
+import { damp, spring } from "./maths.js";
+import { toggle } from "../services/toggle.js";
+import { useRaf } from "../services/raf.js";
+//#region src/utils/smoothTo.ts
+/** The key a single value is held under, and the one its `damping` hook is asked about. */
+const SCALAR_KEY = "value";
+function smoothTo(start = 0, options = {}) {
+	const { spring: useSpring, stiffness, mass, damping = .6 } = options;
+	const isSpring = useSpring === true || stiffness !== void 0 || mass !== void 0;
+	const { precision = isSpring ? 1 / 1e4 : .01 } = options;
+	const dampingNow = typeof damping === "function" ? damping : () => damping;
+	const isRecord = typeof start === "object";
+	const initial = isRecord ? start : { [SCALAR_KEY]: start };
+	const keys = Object.keys(initial);
+	const callbacks = /* @__PURE__ */ new Set();
+	const targets = { ...initial };
+	const values = { ...initial };
+	const velocities = {};
+	/** The reading a caller gets: the number itself, or the one shared record. */
+	const read = () => isRecord ? values : values[SCALAR_KEY];
+	const frame = toggle(() => useRaf().subscribe(({ delta }) => {
+		let isTravelling = false;
+		for (const key of keys) {
+			if (values[key] === targets[key]) continue;
+			if (isSpring) [values[key], velocities[key]] = spring(targets[key], values[key], velocities[key] ?? 0, delta, {
+				stiffness,
+				mass,
+				damping: dampingNow(key),
+				precision
+			});
+			else values[key] = damp(targets[key], values[key], dampingNow(key), delta, precision);
+			if (values[key] === targets[key]) velocities[key] = 0;
+			else isTravelling = true;
+		}
+		if (!isTravelling) frame.stop();
+		const batch = [...callbacks];
+		const reading = read();
+		for (const callback of batch) callback(reading);
+	}));
+	/** Set the named targets, leaving every channel this call does not name alone. */
+	function setTargets(next) {
+		let hasSomewhereToGo = false;
+		for (const key of keys) {
+			const value = next[key];
+			if (value !== void 0) targets[key] = value;
+			if (values[key] !== targets[key]) hasSomewhereToGo = true;
+		}
+		if (hasSomewhereToGo) frame.start();
+	}
+	function update(next) {
+		if (next !== void 0) setTargets(typeof next === "object" ? next : { [SCALAR_KEY]: next });
+		return read();
+	}
+	const api = Object.assign(update, {
+		subscribe(callback) {
+			callbacks.add(callback);
+			return () => {
+				callbacks.delete(callback);
+			};
+		},
+		raw: () => isRecord ? targets : targets[SCALAR_KEY],
+		add: (deltas) => {
+			const named = typeof deltas === "object" ? deltas : { [SCALAR_KEY]: deltas };
+			const moved = {};
+			for (const [key, delta] of Object.entries(named)) if (delta !== void 0) moved[key] = targets[key] + delta;
+			setTargets(moved);
+			return read();
+		},
+		jump: (next) => {
+			const named = typeof next === "object" ? next : { [SCALAR_KEY]: next };
+			for (const [key, value] of Object.entries(named)) if (value !== void 0) {
+				targets[key] = value;
+				values[key] = value;
+				velocities[key] = 0;
+			}
+			if (keys.every((key) => values[key] === targets[key])) frame.stop();
+			return read();
+		},
+		destroy() {
+			frame.stop();
+			callbacks.clear();
+		}
+	});
+	Object.defineProperty(api, "isMoving", {
+		get: () => frame.isActive,
+		enumerable: true
+	});
+	return api;
+}
+//#endregion
+export { smoothTo };
+
+//# sourceMappingURL=smoothTo.js.map

package/dist/utils/smoothTo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoothTo.js","names":[],"sources":["../../src/utils/smoothTo.ts"],"sourcesContent":["import { useRaf } from '../services/raf.js';\nimport { toggle } from '../services/toggle.js';\nimport { damp, spring, type SpringOptions } from './maths.js';\n\n/** The key a single value is held under, and the one its `damping` hook is asked about. */\nconst SCALAR_KEY = 'value';\n\nexport interface SmoothToOptions extends Omit<SpringOptions, 'damping'> {\n  /**\n   * Damping factor, or spring friction in spring mode. Defaults to `0.6`.\n   *\n   * A function is read on **every frame, for every channel**, which is what a\n   * consumer whose factor is an option needs: `$options` is a live view over\n   * attributes, so a value captured once would freeze an attribute the\n   * framework keeps live. It is also how a factor that depends on the\n   * direction of travel is expressed — read the current value and decide — and\n   * how a record gives one channel a different rate from its neighbour. A\n   * single value is asked about under the key `value`.\n   */\n  damping?: number | ((key: string) => number);\n  /**\n   * Spring physics instead of damping. Implied by `stiffness` or `mass`.\n   *\n   * The mode belongs to the instance, not to a channel: a record that wants a\n   * spring for one value and damping for another is two instances, and pays\n   * for two frame subscriptions to get it.\n   */\n  spring?: boolean;\n}\n\nexport interface SmoothTo {\n  /** Read the smoothed value, or set a new target and get the smoothed value. */\n  (value?: number): number;\n  /** Called with the smoothed value on every frame it moves. @returns Unsubscribe. */\n  subscribe(callback: (value: number) => unknown): () => void;\n  /** The target, unsmoothed. */\n  raw(): number;\n  /** Move the target by `delta`. */\n  add(delta: number): number;\n  /** Set the value and its target at once, with no travel and no frame. */\n  jump(value: number): number;\n  /** Whether the value is still travelling. */\n  readonly isMoving: boolean;\n  /** Release the frame subscription and remove all subscribers. */\n  destroy(): void;\n}\n\n/**\n * Several named values on one frame subscription.\n *\n * The record handed to a reader or a subscriber is the **same object every\n * frame**, as a service hands the same props: a 60 fps primitive should not\n * allocate per frame, and a consumer reads it synchronously. Treat it as\n * read-only.\n */\nexport interface SmoothToRecord<K extends string> {\n  /** Read every smoothed value, or set some targets and read them back. */\n  (values?: Partial<Record<K, number>>): Record<K, number>;\n  /** Called on every frame any channel moves. @returns Unsubscribe. */\n  subscribe(callback: (values: Record<K, number>) => unknown): () => void;\n  /** The targets, unsmoothed. */\n  raw(): Record<K, number>;\n  /** Move some targets by a delta each. */\n  add(deltas: Partial<Record<K, number>>): Record<K, number>;\n  /** Set some values and their targets at once, with no travel and no frame. */\n  jump(values: Partial<Record<K, number>>): Record<K, number>;\n  /** Whether any channel is still travelling. */\n  readonly isMoving: boolean;\n  /** Release the frame subscription and remove all subscribers. */\n  destroy(): void;\n}\n\n/**\n * Smooth a value toward a target with one shared frame subscription.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#smoothto\n */\nexport function smoothTo(start?: number, options?: SmoothToOptions): SmoothTo;\n/**\n * Smooth several named values toward their targets, on one frame subscription,\n * with one settled state and one subscriber call per frame. The keys are the\n * consumer's own — a scale, an opacity or a progress as readily as a coordinate.\n */\nexport function smoothTo<K extends string>(\n  start: Record<K, number>,\n  options?: SmoothToOptions,\n): SmoothToRecord<K>;\nexport function smoothTo(\n  start: number | Record<string, number> = 0,\n  options: SmoothToOptions = {},\n): SmoothTo | SmoothToRecord<string> {\n  const { spring: useSpring, stiffness, mass, damping = 0.6 } = options;\n  // A spring parameter enables spring mode.\n  const isSpring = useSpring === true || stiffness !== undefined || mass !== undefined;\n  // Each mode keeps the default of the function it wraps, so converting a raw\n  // `damp()` or `spring()` call to this helper does not change where it snaps.\n  const { precision = isSpring ? 1 / 1e4 : 0.01 } = options;\n  const dampingNow = typeof damping === 'function' ? damping : () => damping;\n\n  const isRecord = typeof start === 'object';\n  const initial: Record<string, number> = isRecord ? start : { [SCALAR_KEY]: start };\n  const keys = Object.keys(initial);\n\n  const callbacks = new Set<(values: never) => unknown>();\n  const targets = { ...initial };\n  const values = { ...initial };\n  const velocities: Record<string, number> = {};\n\n  /** The reading a caller gets: the number itself, or the one shared record. */\n  const read = () => (isRecord ? values : values[SCALAR_KEY]);\n\n  const frame = toggle(() =>\n    useRaf().subscribe(({ delta }) => {\n      let isTravelling = false;\n\n      for (const key of keys) {\n        if (values[key] === targets[key]) {\n          continue;\n        }\n\n        if (isSpring) {\n          [values[key], velocities[key]] = spring(\n            targets[key],\n            values[key],\n            velocities[key] ?? 0,\n            delta,\n            // Read per frame and per channel, so an option that changed since\n            // the last frame counts, and one channel can travel at its own rate.\n            { stiffness, mass, damping: dampingNow(key), precision },\n          );\n        } else {\n          values[key] = damp(targets[key], values[key], dampingNow(key), delta, precision);\n        }\n\n        if (values[key] === targets[key]) {\n          velocities[key] = 0;\n        } else {\n          isTravelling = true;\n        }\n      }\n\n      // Release the shared frame subscription as soon as every channel arrives.\n      if (!isTravelling) {\n        frame.stop();\n      }\n\n      // Use a snapshot so subscription changes do not alter the current batch.\n      const batch = [...callbacks];\n      const reading = read() as never;\n      for (const callback of batch) {\n        callback(reading);\n      }\n    }),\n  );\n\n  /** Set the named targets, leaving every channel this call does not name alone. */\n  function setTargets(next: Partial<Record<string, number>>) {\n    let hasSomewhereToGo = false;\n\n    for (const key of keys) {\n      const value = next[key];\n      if (value !== undefined) {\n        targets[key] = value;\n      }\n      if (values[key] !== targets[key]) {\n        hasSomewhereToGo = true;\n      }\n    }\n\n    // `start()` is idempotent, so target updates share one subscription.\n    if (hasSomewhereToGo) {\n      frame.start();\n    }\n  }\n\n  function update(next?: number | Partial<Record<string, number>>) {\n    if (next !== undefined) {\n      setTargets(typeof next === 'object' ? next : { [SCALAR_KEY]: next });\n    }\n    return read();\n  }\n\n  const api = Object.assign(update, {\n    subscribe(callback: (values: never) => unknown) {\n      callbacks.add(callback);\n      return () => {\n        callbacks.delete(callback);\n      };\n    },\n    raw: () => (isRecord ? targets : targets[SCALAR_KEY]),\n    add: (deltas: number | Partial<Record<string, number>>) => {\n      const named = typeof deltas === 'object' ? deltas : { [SCALAR_KEY]: deltas };\n      const moved: Record<string, number> = {};\n      for (const [key, delta] of Object.entries(named)) {\n        if (delta !== undefined) {\n          moved[key] = targets[key] + delta;\n        }\n      }\n      setTargets(moved);\n      return read();\n    },\n    jump: (next: number | Partial<Record<string, number>>) => {\n      const named = typeof next === 'object' ? next : { [SCALAR_KEY]: next };\n      for (const [key, value] of Object.entries(named)) {\n        if (value !== undefined) {\n          targets[key] = value;\n          values[key] = value;\n          velocities[key] = 0;\n        }\n      }\n      // A channel this call did not name may still be travelling.\n      if (keys.every((key) => values[key] === targets[key])) {\n        frame.stop();\n      }\n      return read();\n    },\n    destroy() {\n      frame.stop();\n      callbacks.clear();\n    },\n  });\n\n  // `Object.assign` would evaluate and copy a getter value.\n  Object.defineProperty(api, 'isMoving', {\n    get: () => frame.isActive,\n    enumerable: true,\n  });\n\n  // The implementation signature is wider than either overload — every method\n  // takes and returns \"a number or a record\" — so the narrowing the overloads\n  // promise cannot be checked from in here. The two forms are asserted at the\n  // type level in the spec instead.\n  return api as unknown as SmoothTo | SmoothToRecord<string>;\n}\n"],"mappings":"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"}

package/dist/utils/strings.d.ts

@@ -0,0 +1,101 @@
+import { Memo } from "./memo.js";
+//#region src/utils/strings.d.ts
+/**
+ * String shapes the framework converts between: an option or handler name in
+ * source, and the `data-` attribute or event type it corresponds to.
+ */
+/**
+ * Convert a string to lowercase.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#lowercase
+ */
+declare function lowerCase(string: string): string;
+/**
+ * Convert a string to UPPERCASE.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#uppercase
+ */
+declare function upperCase(string: string): string;
+/**
+ * Capitalize the first character and leave the rest alone: a `data-ref="btn"`
+ * name becomes the `Btn` of an `onBtnClick` handler.
+ *
+ * This is not {@link pascalCase} — it never splits words, so it round-trips a
+ * name the framework read from source.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#capitalize
+ */
+declare function capitalize(string: string): string;
+/**
+ * Convert a string to `PascalCase`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#pascalcase
+ */
+declare const pascalCase: Memo<[string: string], string>;
+/**
+ * Convert a string to `camelCase`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#camelcase
+ */
+declare const camelCase: Memo<[string: string], string>;
+/**
+ * Convert a string to `kebab-case`, the shape of a `data-` attribute.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#kebabcase
+ */
+declare const kebabCase: Memo<[string: string], string>;
+/**
+ * Convert a string to `snake_case`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#snakecase
+ */
+declare const snakeCase: Memo<[string: string], string>;
+/**
+ * Add the given characters to the start of a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingcharacters
+ */
+declare function withLeadingCharacters(string: string, characters: string): string;
+/**
+ * Remove the given characters from the start of a string, once.
+ *
+ * No characters is nothing to remove: every helper here returns the string
+ * unchanged rather than treating the empty match every string starts and ends
+ * with as a hit.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharacters
+ */
+declare function withoutLeadingCharacters(string: string, characters: string): string;
+/**
+ * Remove the given characters from the start of a string, as often as they repeat.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharactersrecursive
+ */
+declare function withoutLeadingCharactersRecursive(string: string, characters: string): string;
+/**
+ * Add the given characters to the end of a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingcharacters
+ */
+declare function withTrailingCharacters(string: string, characters: string): string;
+/**
+ * Remove the given characters from the end of a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharacters
+ */
+declare function withoutTrailingCharacters(string: string, characters: string): string;
+/**
+ * Remove the given characters from the end of a string, as often as they repeat.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharactersrecursive
+ */
+declare function withoutTrailingCharactersRecursive(string: string, characters: string): string;
+/**
+ * Add a leading slash to a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingslash
+ */
+declare function withLeadingSlash(string: string): string;
+/**
+ * Remove the leading slash from a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingslash
+ */
+declare function withoutLeadingSlash(string: string): string;
+/**
+ * Add a trailing slash to a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingslash
+ */
+declare function withTrailingSlash(string: string): string;
+/**
+ * Remove the trailing slash from a string, once.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingslash
+ */
+declare function withoutTrailingSlash(string: string): string;
+//#endregion
+export { camelCase, capitalize, kebabCase, lowerCase, pascalCase, snakeCase, upperCase, withLeadingCharacters, withLeadingSlash, withTrailingCharacters, withTrailingSlash, withoutLeadingCharacters, withoutLeadingCharactersRecursive, withoutLeadingSlash, withoutTrailingCharacters, withoutTrailingCharactersRecursive, withoutTrailingSlash };

package/dist/utils/strings.js

@@ -0,0 +1,169 @@
+import { memo } from "./memo.js";
+//#region src/utils/strings.ts
+/**
+* String shapes the framework converts between: an option or handler name in
+* source, and the `data-` attribute or event type it corresponds to.
+*/
+const SPLIT_LOWER_UPPER_RE = /([\p{Ll}\d])(\p{Lu})/gu;
+const SPLIT_UPPER_UPPER_RE = /(\p{Lu})([\p{Lu}][\p{Ll}])/gu;
+const STRIP_RE = /[^\p{L}\d]+/giu;
+const SPLIT_REPLACE_VALUE = "$1\0$2";
+/**
+* Split a string into words, on case boundaries and on anything which is
+* neither a letter nor a digit.
+*
+* @link https://github.com/blakeembrey/change-case
+*/
+function split(value) {
+	let result = value.trim().replace(SPLIT_LOWER_UPPER_RE, SPLIT_REPLACE_VALUE).replace(SPLIT_UPPER_UPPER_RE, SPLIT_REPLACE_VALUE).replace(STRIP_RE, "\0");
+	let start = 0;
+	let end = result.length;
+	while (result.charAt(start) === "\0") start++;
+	if (start === end) return [];
+	while (result.charAt(end - 1) === "\0") end--;
+	return result.slice(start, end).split("\0");
+}
+/** Join the words of a string in lowercase, with the given delimiter. */
+function delimitedCase(string, delimiter) {
+	return split(string).map(lowerCase).join(delimiter);
+}
+/**
+* Convert a string to lowercase.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#lowercase
+*/
+function lowerCase(string) {
+	return string.toLowerCase();
+}
+/**
+* Convert a string to UPPERCASE.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#uppercase
+*/
+function upperCase(string) {
+	return string.toUpperCase();
+}
+/**
+* Capitalize the first character and leave the rest alone: a `data-ref="btn"`
+* name becomes the `Btn` of an `onBtnClick` handler.
+*
+* This is not {@link pascalCase} — it never splits words, so it round-trips a
+* name the framework read from source.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#capitalize
+*/
+function capitalize(string) {
+	return upperCase(string.charAt(0)) + string.slice(1);
+}
+/**
+* Convert a string to `PascalCase`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#pascalcase
+*/
+const pascalCase = /* @__PURE__ */ memo(function pascalCase(string) {
+	return split(string).map((word) => upperCase(word.charAt(0)) + lowerCase(word.slice(1))).join("");
+});
+/**
+* Convert a string to `camelCase`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#camelcase
+*/
+const camelCase = /* @__PURE__ */ memo(function camelCase(string) {
+	const result = pascalCase(string);
+	return lowerCase(result.charAt(0)) + result.slice(1);
+});
+/**
+* Convert a string to `kebab-case`, the shape of a `data-` attribute.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#kebabcase
+*/
+const kebabCase = /* @__PURE__ */ memo(function kebabCase(string) {
+	return delimitedCase(string, "-");
+});
+/**
+* Convert a string to `snake_case`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#snakecase
+*/
+const snakeCase = /* @__PURE__ */ memo(function snakeCase(string) {
+	return delimitedCase(string, "_");
+});
+/**
+* Add the given characters to the start of a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingcharacters
+*/
+function withLeadingCharacters(string, characters) {
+	return `${characters}${withoutLeadingCharacters(string, characters)}`;
+}
+/**
+* Remove the given characters from the start of a string, once.
+*
+* No characters is nothing to remove: every helper here returns the string
+* unchanged rather than treating the empty match every string starts and ends
+* with as a hit.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharacters
+*/
+function withoutLeadingCharacters(string, characters) {
+	if (characters.length === 0) return string;
+	return string.startsWith(characters) ? string.slice(characters.length) : string;
+}
+/**
+* Remove the given characters from the start of a string, as often as they repeat.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharactersrecursive
+*/
+function withoutLeadingCharactersRecursive(string, characters) {
+	if (characters.length === 0) return string;
+	let result = string;
+	while (result.startsWith(characters)) result = result.slice(characters.length);
+	return result;
+}
+/**
+* Add the given characters to the end of a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingcharacters
+*/
+function withTrailingCharacters(string, characters) {
+	return `${withoutTrailingCharacters(string, characters)}${characters}`;
+}
+/**
+* Remove the given characters from the end of a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharacters
+*/
+function withoutTrailingCharacters(string, characters) {
+	if (characters.length === 0) return string;
+	return string.endsWith(characters) ? string.slice(0, -characters.length) : string;
+}
+/**
+* Remove the given characters from the end of a string, as often as they repeat.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharactersrecursive
+*/
+function withoutTrailingCharactersRecursive(string, characters) {
+	if (characters.length === 0) return string;
+	let result = string;
+	while (result.endsWith(characters)) result = result.slice(0, -characters.length);
+	return result;
+}
+/**
+* Add a leading slash to a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingslash
+*/
+function withLeadingSlash(string) {
+	return withLeadingCharacters(string, "/");
+}
+/**
+* Remove the leading slash from a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingslash
+*/
+function withoutLeadingSlash(string) {
+	return withoutLeadingCharacters(string, "/");
+}
+/**
+* Add a trailing slash to a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingslash
+*/
+function withTrailingSlash(string) {
+	return withTrailingCharacters(string, "/");
+}
+/**
+* Remove the trailing slash from a string, once.
+* @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingslash
+*/
+function withoutTrailingSlash(string) {
+	return withoutTrailingCharacters(string, "/");
+}
+//#endregion
+export { camelCase, capitalize, kebabCase, lowerCase, pascalCase, snakeCase, upperCase, withLeadingCharacters, withLeadingSlash, withTrailingCharacters, withTrailingSlash, withoutLeadingCharacters, withoutLeadingCharactersRecursive, withoutLeadingSlash, withoutTrailingCharacters, withoutTrailingCharactersRecursive, withoutTrailingSlash };
+
+//# sourceMappingURL=strings.js.map

package/dist/utils/strings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.js","names":[],"sources":["../../src/utils/strings.ts"],"sourcesContent":["/**\n * String shapes the framework converts between: an option or handler name in\n * source, and the `data-` attribute or event type it corresponds to.\n */\n\nimport { memo } from './memo.js';\n\nconst SPLIT_LOWER_UPPER_RE = /([\\p{Ll}\\d])(\\p{Lu})/gu;\nconst SPLIT_UPPER_UPPER_RE = /(\\p{Lu})([\\p{Lu}][\\p{Ll}])/gu;\nconst STRIP_RE = /[^\\p{L}\\d]+/giu;\nconst SPLIT_REPLACE_VALUE = '$1\\0$2';\n\n/**\n * Split a string into words, on case boundaries and on anything which is\n * neither a letter nor a digit.\n *\n * @link https://github.com/blakeembrey/change-case\n */\nfunction split(value: string): string[] {\n  let result = value\n    .trim()\n    .replace(SPLIT_LOWER_UPPER_RE, SPLIT_REPLACE_VALUE)\n    .replace(SPLIT_UPPER_UPPER_RE, SPLIT_REPLACE_VALUE)\n    .replace(STRIP_RE, '\\0');\n\n  let start = 0;\n  let end = result.length;\n\n  // Trim the delimiter from around the output.\n  while (result.charAt(start) === '\\0') start++;\n  if (start === end) return [];\n  while (result.charAt(end - 1) === '\\0') end--;\n\n  return result.slice(start, end).split('\\0');\n}\n\n/** Join the words of a string in lowercase, with the given delimiter. */\nfunction delimitedCase(string: string, delimiter: string): string {\n  return split(string).map(lowerCase).join(delimiter);\n}\n\n/**\n * Convert a string to lowercase.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#lowercase\n */\nexport function lowerCase(string: string): string {\n  return string.toLowerCase();\n}\n\n/**\n * Convert a string to UPPERCASE.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#uppercase\n */\nexport function upperCase(string: string): string {\n  return string.toUpperCase();\n}\n\n/**\n * Capitalize the first character and leave the rest alone: a `data-ref=\"btn\"`\n * name becomes the `Btn` of an `onBtnClick` handler.\n *\n * This is not {@link pascalCase} — it never splits words, so it round-trips a\n * name the framework read from source.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#capitalize\n */\nexport function capitalize(string: string): string {\n  return upperCase(string.charAt(0)) + string.slice(1);\n}\n\n/**\n * Convert a string to `PascalCase`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#pascalcase\n */\nexport const pascalCase = /* @__PURE__ */ memo(function pascalCase(string: string): string {\n  return split(string)\n    .map((word) => upperCase(word.charAt(0)) + lowerCase(word.slice(1)))\n    .join('');\n});\n\n/**\n * Convert a string to `camelCase`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#camelcase\n */\nexport const camelCase = /* @__PURE__ */ memo(function camelCase(string: string): string {\n  const result = pascalCase(string);\n  return lowerCase(result.charAt(0)) + result.slice(1);\n});\n\n/**\n * Convert a string to `kebab-case`, the shape of a `data-` attribute.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#kebabcase\n */\nexport const kebabCase = /* @__PURE__ */ memo(function kebabCase(string: string): string {\n  return delimitedCase(string, '-');\n});\n\n/**\n * Convert a string to `snake_case`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#snakecase\n */\nexport const snakeCase = /* @__PURE__ */ memo(function snakeCase(string: string): string {\n  return delimitedCase(string, '_');\n});\n/**\n * Add the given characters to the start of a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingcharacters\n */\nexport function withLeadingCharacters(string: string, characters: string): string {\n  return `${characters}${withoutLeadingCharacters(string, characters)}`;\n}\n\n/**\n * Remove the given characters from the start of a string, once.\n *\n * No characters is nothing to remove: every helper here returns the string\n * unchanged rather than treating the empty match every string starts and ends\n * with as a hit.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharacters\n */\nexport function withoutLeadingCharacters(string: string, characters: string): string {\n  if (characters.length === 0) {\n    return string;\n  }\n  return string.startsWith(characters) ? string.slice(characters.length) : string;\n}\n\n/**\n * Remove the given characters from the start of a string, as often as they repeat.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingcharactersrecursive\n */\nexport function withoutLeadingCharactersRecursive(string: string, characters: string): string {\n  if (characters.length === 0) {\n    return string;\n  }\n  let result = string;\n  while (result.startsWith(characters)) {\n    result = result.slice(characters.length);\n  }\n  return result;\n}\n\n/**\n * Add the given characters to the end of a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingcharacters\n */\nexport function withTrailingCharacters(string: string, characters: string): string {\n  return `${withoutTrailingCharacters(string, characters)}${characters}`;\n}\n\n/**\n * Remove the given characters from the end of a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharacters\n */\nexport function withoutTrailingCharacters(string: string, characters: string): string {\n  if (characters.length === 0) {\n    return string;\n  }\n  return string.endsWith(characters) ? string.slice(0, -characters.length) : string;\n}\n\n/**\n * Remove the given characters from the end of a string, as often as they repeat.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingcharactersrecursive\n */\nexport function withoutTrailingCharactersRecursive(string: string, characters: string): string {\n  if (characters.length === 0) {\n    return string;\n  }\n  let result = string;\n  while (result.endsWith(characters)) {\n    result = result.slice(0, -characters.length);\n  }\n  return result;\n}\n\n/**\n * Add a leading slash to a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withleadingslash\n */\nexport function withLeadingSlash(string: string): string {\n  return withLeadingCharacters(string, '/');\n}\n\n/**\n * Remove the leading slash from a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withoutleadingslash\n */\nexport function withoutLeadingSlash(string: string): string {\n  return withoutLeadingCharacters(string, '/');\n}\n\n/**\n * Add a trailing slash to a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withtrailingslash\n */\nexport function withTrailingSlash(string: string): string {\n  return withTrailingCharacters(string, '/');\n}\n\n/**\n * Remove the trailing slash from a string, once.\n * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingslash\n */\nexport function withoutTrailingSlash(string: string): string {\n  return withoutTrailingCharacters(string, '/');\n}\n"],"mappings":"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"}

package/dist/utils/timing.d.ts

@@ -0,0 +1,21 @@
+//#region src/utils/timing.d.ts
+/** Rate limiting and delays, for the callbacks a component hands to the DOM. */
+/**
+ * Delay a function until it stops being called for the given milliseconds.
+ * Only the last call's arguments are used.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#debounce
+ */
+declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void;
+/**
+ * Run a function at most once per given milliseconds, on the leading edge.
+ * A call inside the window is dropped, not deferred.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#throttle
+ */
+declare function throttle<Args extends unknown[]>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void;
+/**
+ * Resolve after the given milliseconds.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#wait
+ */
+declare function wait(delay?: number): Promise<void>;
+//#endregion
+export { debounce, throttle, wait };

package/dist/utils/timing.js

@@ -0,0 +1,41 @@
+//#region src/utils/timing.ts
+/** Rate limiting and delays, for the callbacks a component hands to the DOM. */
+/**
+* Delay a function until it stops being called for the given milliseconds.
+* Only the last call's arguments are used.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#debounce
+*/
+function debounce(fn, delay = 300) {
+	let timeout;
+	return function debounced(...args) {
+		clearTimeout(timeout);
+		timeout = setTimeout(() => fn(...args), delay);
+	};
+}
+/**
+* Run a function at most once per given milliseconds, on the leading edge.
+* A call inside the window is dropped, not deferred.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#throttle
+*/
+function throttle(fn, delay = 16) {
+	let lastCall = Number.NEGATIVE_INFINITY;
+	return function throttled(...args) {
+		const now = performance.now();
+		if (now - lastCall < delay) return;
+		lastCall = now;
+		fn(...args);
+	};
+}
+/**
+* Resolve after the given milliseconds.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#wait
+*/
+function wait(delay = 0) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, delay);
+	});
+}
+//#endregion
+export { debounce, throttle, wait };
+
+//# sourceMappingURL=timing.js.map

package/dist/utils/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","names":[],"sources":["../../src/utils/timing.ts"],"sourcesContent":["/** Rate limiting and delays, for the callbacks a component hands to the DOM. */\n\n/**\n * Delay a function until it stops being called for the given milliseconds.\n * Only the last call's arguments are used.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#debounce\n */\nexport function debounce<Args extends unknown[]>(\n  fn: (...args: Args) => void,\n  delay = 300,\n): (...args: Args) => void {\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n\n  return function debounced(...args: Args): void {\n    clearTimeout(timeout);\n    timeout = setTimeout(() => fn(...args), delay);\n  };\n}\n\n/**\n * Run a function at most once per given milliseconds, on the leading edge.\n * A call inside the window is dropped, not deferred.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#throttle\n */\nexport function throttle<Args extends unknown[]>(\n  fn: (...args: Args) => void,\n  delay = 16,\n): (...args: Args) => void {\n  // Not `0`: `performance.now()` starts there, so a first call at page load\n  // would fall inside its own window.\n  let lastCall = Number.NEGATIVE_INFINITY;\n\n  return function throttled(...args: Args): void {\n    const now = performance.now();\n    if (now - lastCall < delay) {\n      return;\n    }\n    lastCall = now;\n    fn(...args);\n  };\n}\n\n/**\n * Resolve after the given milliseconds.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#wait\n */\nexport function wait(delay = 0): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, delay);\n  });\n}\n"],"mappings":";;;;;;;AAOA,SAAgB,SACd,IACA,QAAQ,KACiB;CACzB,IAAI;CAEJ,OAAO,SAAS,UAAU,GAAG,MAAkB;EAC7C,aAAa,OAAO;EACpB,UAAU,iBAAiB,GAAG,GAAG,IAAI,GAAG,KAAK;CAC/C;AACF;;;;;;AAOA,SAAgB,SACd,IACA,QAAQ,IACiB;CAGzB,IAAI,WAAW,OAAO;CAEtB,OAAO,SAAS,UAAU,GAAG,MAAkB;EAC7C,MAAM,MAAM,YAAY,IAAI;EAC5B,IAAI,MAAM,WAAW,OACnB;EAEF,WAAW;EACX,GAAG,GAAG,IAAI;CACZ;AACF;;;;;AAMA,SAAgB,KAAK,QAAQ,GAAkB;CAC7C,OAAO,IAAI,SAAS,YAAY;EAC9B,WAAW,SAAS,KAAK;CAC3B,CAAC;AACH"}