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

package/skills/studiometa-js-toolkit/references/utils/strings.md

@@ -0,0 +1,176 @@
+# Strings
+
+```js
+import { camelCase, kebabCase, pascalCase } from '@studiometa/js-toolkit/utils';
+```
+
+## Case
+
+```js
+import { camelCase, kebabCase, pascalCase } from '@studiometa/js-toolkit/utils';
+
+pascalCase('drag-threshold'); // 'DragThreshold'
+camelCase('drag-threshold'); // 'dragThreshold'
+kebabCase('dragThreshold'); // 'drag-threshold'
+```
+
+These are the functions the framework itself uses: `kebabCase` turns `dragThreshold` into `data-option-drag-threshold`, and `pascalCase` turns an option name into `optionDragThresholdChanged`.
+
+**Four of them are memoised**
+
+`pascalCase`, `camelCase`, `kebabCase` and `snakeCase` are `memo`-wrapped, because the framework converts the **same** names on every option read and every handler resolution. `lowerCase`, `upperCase` and `capitalize` are not — they are single-pass and there is nothing to cache.
+
+### lowerCase
+
+```ts
+lowerCase(string: string): string
+```
+
+### upperCase
+
+```ts
+upperCase(string: string): string
+```
+
+### capitalize
+
+```ts
+capitalize(string: string): string
+```
+
+### pascalCase
+
+```ts
+pascalCase(string: string): string
+```
+
+`'foo bar'` → `'FooBar'`. Memoised.
+
+### camelCase
+
+```ts
+camelCase(string: string): string
+```
+
+`'foo bar'` → `'fooBar'`. Memoised.
+
+### kebabCase
+
+```ts
+kebabCase(string: string): string
+```
+
+`'fooBar'` → `'foo-bar'`. Memoised.
+
+### snakeCase
+
+```ts
+snakeCase(string: string): string
+```
+
+`'fooBar'` → `'foo_bar'`. Memoised.
+
+## Leading and trailing characters
+
+```js
+import {
+  withLeadingCharacters,
+  withoutTrailingCharactersRecursive,
+} from '@studiometa/js-toolkit/utils';
+
+withLeadingCharacters('bar', 'foo'); // 'foobar'
+withLeadingCharacters('foobar', 'foo'); // 'foobar' — already there
+withoutTrailingCharactersRecursive('path///', '/'); // 'path'
+```
+
+The **recursive** pair exists because a URL joined from parts collects separators, and removing one is not the same as removing them all.
+
+### withLeadingCharacters
+
+```ts
+withLeadingCharacters(string: string, characters: string): string
+```
+
+Adds them if absent.
+
+### withoutLeadingCharacters
+
+```ts
+withoutLeadingCharacters(string: string, characters: string): string
+```
+
+Removes them once.
+
+### withoutLeadingCharactersRecursive
+
+```ts
+withoutLeadingCharactersRecursive(string: string, characters: string): string
+```
+
+Removes them as long as they are there.
+
+### withTrailingCharacters
+
+```ts
+withTrailingCharacters(string: string, characters: string): string
+```
+
+Adds them if absent.
+
+### withoutTrailingCharacters
+
+```ts
+withoutTrailingCharacters(string: string, characters: string): string
+```
+
+Removes them once.
+
+### withoutTrailingCharactersRecursive
+
+```ts
+withoutTrailingCharactersRecursive(string: string, characters: string): string
+```
+
+Removes them as long as they are there.
+
+## Slashes
+
+The four named cases, for the one separator every path uses. Each is the matching `*Characters` function with `'/'` filled in, which is what makes a call site readable at a glance.
+
+```js
+import {
+  withLeadingSlash,
+  withoutLeadingSlash,
+  withoutTrailingSlash,
+  withTrailingSlash,
+} from '@studiometa/js-toolkit/utils';
+
+withLeadingSlash('about'); // '/about'
+withoutLeadingSlash('/about'); // 'about'
+withTrailingSlash('/about'); // '/about/'
+withoutTrailingSlash('/about/'); // '/about'
+```
+
+### withLeadingSlash
+
+```ts
+withLeadingSlash(string: string): string
+```
+
+### withoutLeadingSlash
+
+```ts
+withoutLeadingSlash(string: string): string
+```
+
+### withTrailingSlash
+
+```ts
+withTrailingSlash(string: string): string
+```
+
+### withoutTrailingSlash
+
+```ts
+withoutTrailingSlash(string: string): string
+```

package/skills/studiometa-js-toolkit/references/utils/timing.md

@@ -0,0 +1,111 @@
+# Timing
+
+```js
+import { debounce, memo, throttle, wait } from '@studiometa/js-toolkit/utils';
+```
+
+## Rate limiting
+
+```js
+import { debounce, throttle } from '@studiometa/js-toolkit/utils';
+
+const search = debounce((term) => console.log(term), 300); // after the last call
+const track = throttle((y) => console.log(y), 100); // at most once per delay
+```
+
+**Not for scroll, resize, pointer or frame work**
+
+The services already coalesce: the scroll service batches its events into **one `read` per frame**, and the resize service is a `ResizeObserver`. A `throttle` on top of that is a second, worse rate limiter.
+
+Reach for these for what the framework does not own — a `fetch` per keystroke, an analytics call, a `localStorage` write.
+
+### debounce
+
+```ts
+debounce<Args>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void
+```
+
+Runs once, after the calls stop.
+
+### throttle
+
+```ts
+throttle<Args>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void
+```
+
+Runs at most once per `delay`.
+
+## Waiting
+
+### wait
+
+```ts
+wait(delay?: number): Promise<void>
+```
+
+```js
+import { wait } from '@studiometa/js-toolkit/utils';
+
+async function pause() {
+  await wait(300);
+}
+```
+
+`await wait()` with no argument is one turn of the event loop.
+
+For a frame rather than a timer, use [`nextFrame()`](../api/scheduler/nextFrame.md). For "the framework has caught up", use [`whenDOMSettled()`](../api/dom/whenDOMSettled.md) — a timer is the wrong tool for both, and the reason the [test helpers](../api/test/index.md) exist at all.
+
+## Memoisation
+
+### memo
+
+```ts
+memo<Args extends [] | [key: unknown], Value>(fn: (...args: Args) => Value): Memo<Args, Value>
+```
+
+```js
+import { memo } from '@studiometa/js-toolkit/utils';
+
+const expensive = memo((key) => key.toString().repeat(2));
+
+expensive('a'); // computed
+expensive('a'); // cached
+```
+
+**Zero or one argument, and that argument is the key.** That is the whole surface, and it is deliberate: a memo keyed on several arguments needs a key strategy, and a key strategy is a decision the caller should make visibly rather than inherit.
+
+It is what the four memoised [string converters](strings.md) are built on, and what memoises the active breakpoint name for the length of one task.
+
+`cache` and `memoize` from v3 are not shipped — this covers the one case core needed.
+
+## Placeholders
+
+They earn their place as **defaults**: a parameter defaulting to `noop` removes an `if` from every call site, and one defaulting to `noopValue` removes it from a transform pipeline. Both are one shared function, so a default costs no allocation per call.
+
+```js
+import { noop, noopValue } from '@studiometa/js-toolkit/utils';
+
+const onDone = noop; // a callback that does nothing
+const identity = noopValue; // a transform that changes nothing
+```
+
+### noop
+
+```ts
+noop(): void
+```
+
+### noopValue
+
+```ts
+noopValue<T>(value: T): T
+```
+
+## What is not here
+
+| Not shipped                    | Write                                                      |
+| ------------------------------ | ---------------------------------------------------------- |
+| `nextTick`                     | `await Promise.resolve()`                                  |
+| `nextMicrotask`                | `queueMicrotask(fn)`                                       |
+| `Queue`, `SmartQueue`          | the [scheduler](../api/scheduler/index.md)'s lanes                   |
+| `domScheduler`, `useScheduler` | [`defaultScheduler`](../api/scheduler/defaultScheduler.md) |

package/skills/studiometa-js-toolkit/references/utils/transitions.md

@@ -0,0 +1,122 @@
+# Transitions
+
+```js
+import { enterTransition, leaveTransition, transition } from '@studiometa/js-toolkit/utils';
+```
+
+Promoted into core from the migration set, beside the easings, `spring()` and `smoothTo()`.
+
+## transition
+
+```ts
+transition(
+  el: HTMLElement,
+  nameOrStyles: string | TransitionStyles,
+  mode?: 'keep' | 'remove',
+): Promise<void>
+```
+
+```ts
+interface TransitionStyles {
+  from?: string | string[] | Partial<CSSStyleDeclaration>;
+  active?: string | string[] | Partial<CSSStyleDeclaration>;
+  to?: string | string[] | Partial<CSSStyleDeclaration>;
+}
+```
+
+The three-state dance every CSS transition needs, with the frame boundaries in the right places:
+
+```js
+import { transition } from '@studiometa/js-toolkit/utils';
+
+const el = document.body;
+
+async function run() {
+  // The class form: `fade-from`, `fade-active`, `fade-to`.
+  await transition(el, 'fade');
+
+  // The inline-style form.
+  await transition(el, {
+    from: { opacity: '0' },
+    active: { transition: 'opacity 300ms' },
+    to: { opacity: '1' },
+  });
+
+  // Keep the `to` state when it ends.
+  await transition(el, 'fade', 'keep');
+}
+```
+
+`mode` decides what happens at the end: `'remove'` (the default) clears the states, `'keep'` leaves the `to` state applied.
+
+Each of the three states takes a class name, an array of class names, or an inline-style object — [`setClassesOrStyles()`](css.md#setclassesorstyles) is what makes that work.
+
+## The two directions
+
+```ts
+type TransitionOptions = {
+  enterFrom: string;
+  enterActive: string;
+  enterTo: string;
+  enterKeep: boolean;
+  leaveFrom: string;
+  leaveActive: string;
+  leaveTo: string;
+  leaveKeep: boolean;
+};
+```
+
+One option object, so a component declares eight options once and both calls read the same thing:
+
+```js
+await enterTransition(this.$el, this.$options);
+await leaveTransition(this.$el, this.$options);
+```
+
+### enterTransition
+
+```ts
+enterTransition(el: HTMLElement, options: TransitionOptions): Promise<void>
+```
+
+### leaveTransition
+
+```ts
+leaveTransition(el: HTMLElement, options: TransitionOptions): Promise<void>
+```
+
+### TRANSITION_OPTIONS
+
+```ts
+const TRANSITION_OPTIONS: Record<string, OptionDefinition>;
+```
+
+That option set as a `config.options` fragment, ready to spread:
+
+```js
+static config = {
+  name: 'Panel',
+  options: {
+    ...TRANSITION_OPTIONS,
+    open: Boolean,
+  },
+};
+```
+
+Which means the eight names, their types and their defaults are declared in **one** place, and a component that wants them writes one line.
+
+## Testing them
+
+**A transition's end state is asserted by polling, never by `settle()`**
+
+A method that starts a transition does not hand it back, and a kept end state lands only after `nextFrame()`, the `from` and `active` states, and either a `transitionend` or one more frame. `settle()` is generous rather than deterministic, which is a flake that passes alone and fails under load.
+
+**Polling for an _absence_ is wrong** for the mirror-image reason: `leaveTransition()` clears the other direction's `to` state **synchronously**, so the poll passes before anything has happened.
+
+See [`waitFor()`](../api/test/index.md#waitfor).
+
+## What is not here
+
+Time-based playback, stagger, sequencing, morphing and text splitting are the separate `ui-animation` package. `tween` and `animate` are not shipped.
+
+`exit`, `layout` and `layoutId` are not an engine's job — [`viewTransition()`](../api/scheduler/viewTransition.md) solves them, and it is in core.