coldwired 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Chavard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @coldwired/actions [![npm package][npm-badge]][npm]
+
+[npm-badge]: https://img.shields.io/npm/v/coldwired.svg
+[npm]: https://www.npmjs.com/package/coldwired
+
+## Why?
+
+Initial inspiration was [turbo-stream](https://turbo.hotwired.dev/handbook/streams), which allows
+for the application of incremental changes to the page. The problem we faced was that applying
+changes wiped out client changes and it was not always practical to propagate the client state
+necessary for rendering to the server. We wanted to be able to preserve some state, such as open
+dialogs an menus or input values.
+
+## How?
+
+`Actions` will create a `MutationObserver` and a `WeakMap` of some of the DOM state, such as class
+names, aria attributes, and input values. This allows it to preserve state across morph changes. You
+always have the possibility to force a state update through the attribute `data-turbo-force`.
+
+## Usage
+
+### Action
+
+An action is an object describing a DOM operation. Actions can be fully serialized to carry them
+over the wire ([turbo-stream](https://turbo.hotwired.dev/handbook/streams)).
+
+```ts
+type Action = {
+  action:
+    | 'after'
+    | 'before'
+    | 'append'
+    | 'prepend'
+    | 'replace'
+    | 'update'
+    | 'remove'
+    | 'focus'
+    | 'enable'
+    | 'disable'
+    | 'hide'
+    | 'show';
+  targets: Element[] | string;
+  fragment?: DocumentFragment | string;
+  delay?: number;
+  pin?: boolean;
+};
+```
+
+### Setup
+
+Before you start working with actions, you need to create and register an instance of `Actions`.
+After that, actions can be applied through the `Actions` instance or dispatched as events. We also
+provide an implementation of [turbo-stream](https://turbo.hotwired.dev/handbook/streams) on top of
+`Actions` through the [coldwired/turbo-stream](https://www.npmjs.com/package/coldwired)
+package.
+
+```ts
+import { Actions } from 'coldwired/actions';
+
+const actions = new Actions({ element: document.body });
+actions.observe();
+```
+
+### DOM manipulation
+
+```ts
+// Insert a fragment after each target element
+actions.after({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Insert a fragment before each target element
+actions.before({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Append a fragment after the last child of each target element
+actions.append({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Prepend a fragment before the first child of each target element
+actions.prepend({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Replace every target element with the fragment.
+// Uses morph to preserve interactive state
+actions.replace({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Update every target inner with the fragment.
+// Uses morph to preserve interactive state
+actions.update({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Remove all target elements
+actions.remove({ targets: '.item' });
+
+// Focus first target element
+actions.focus({ targets: '.item' });
+
+// Disable all target elements
+actions.disable({ targets: '.item' });
+
+// Enable all target elements
+actions.enable({ targets: '.item' });
+
+// Hide all target elements
+actions.hide({ targets: '.item' });
+
+// Show all target elements
+actions.show({ targets: '.item' });
+
+// Apply actions in batch. This is the low level API
+actions.applyActions([
+  {
+    action: 'update',
+    targets: '.item-to-update',
+    fragment: '<p>Hello World</p>',
+  },
+  {
+    action: 'remove',
+    targets: '.item-to-remove',
+  },
+]);
+```
+
+### Dispatch from anywhere
+
+If you want to dispatch actions from places where you don't have access to the `Actions` instance,
+you can use global API.
+
+```ts
+import * as Actions from 'coldwired/actions';
+
+Actions.after({ targets: '.item', fragment: '<p>Hello World</p>' });
+
+// Same as `applyActions` but you don't need access to the instance
+Actions.dispatchActions([
+  {
+    action: 'update',
+    targets: '.item-to-update',
+    fragment: '<p>Hello World</p>',
+  },
+  {
+    action: 'remove',
+    targets: '.item-to-remove',
+  },
+]);
+```
+
+### Delayed actions
+
+You can add a delay to any action, which is useful for hiding flash messages after a short period of
+time, for example.
+
+```ts
+// Hide targets after 2 seconds delay
+actions.hide({ targets: '.item', delay: 2000 });
+```
+
+### Pinned actions
+
+An action can be pinned — this is mostly useful in combination with full-page morph.
+
+```ts
+// In some client code append a new warning
+actions.append({ targets: '.warnings', fragment: '<p>Warning !</p>', pin: true });
+
+// Later, refresh the whole page. It will wipe out the warning added earlier.
+// By running `applyPinnedActions`, you can restore previous changes
+actions.morph(document, newDocument);
+actions.applyPinnedActions();
+
+// When you navigate to a new page, you might want to reset any pinned actions
+actions.reset();
+```

package/dist/actions-CQVSvZlC.d.mts

@@ -0,0 +1,134 @@
+//#region src/actions/plugin.d.ts
+interface Plugin {
+  ready(): Promise<void>;
+  init(element: Element): void;
+  validate?(element: Element | Document): void;
+  onCreateElement?(element: Element): boolean;
+  onBeforeUpdateElement?(element: Element, toElement: Element | DocumentFragment): boolean;
+  onBeforeDestroyElement?(element: Element): boolean;
+}
+//#endregion
+//#region src/actions/schema.d.ts
+type Schema = {
+  forceAttribute: string;
+  focusGroupAttribute: string;
+  focusDirectionAttribute: string;
+  hiddenClassName: string;
+};
+declare const defaultSchema: Schema;
+//#endregion
+//#region src/actions/actions.d.ts
+declare const voidActionNames: readonly ['remove', 'focus', 'enable', 'disable', 'hide', 'show', 'reset', 'refresh'];
+declare const fragmentActionNames: readonly ['after', 'before', 'append', 'prepend', 'replace', 'update'];
+type VoidActionName = (typeof voidActionNames)[number];
+type FragmentActionName = (typeof fragmentActionNames)[number];
+type ActionName = VoidActionName | FragmentActionName;
+type VoidAction = {
+  action: VoidActionName;
+  delay?: number;
+  pin?: boolean | 'last';
+  targets: string;
+};
+type FragmentAction = {
+  action: FragmentActionName;
+  delay?: number;
+  pin?: boolean | 'last';
+  targets: string;
+  fragment: DocumentFragment | string;
+};
+type MaterializedVoidAction = Pick<VoidAction, 'action'> & {
+  targets: Element[];
+};
+type MaterializedFragmentAction = Pick<FragmentAction, 'action' | 'fragment'> & {
+  targets: Element[];
+};
+type Action = VoidAction | FragmentAction;
+type MaterializedAction = MaterializedVoidAction | MaterializedFragmentAction;
+type ActionsOptions = {
+  element?: Element;
+  schema?: Partial<Schema>;
+  debug?: boolean;
+  plugins?: Plugin[];
+};
+declare class Actions {
+  #private;
+  constructor(options?: ActionsOptions);
+  ready(): Promise<void>;
+  get element(): Element;
+  get plugins(): Plugin[];
+  observe(): void;
+  disconnect(): void;
+  clear(): void;
+  applyActions(actions: (Action | MaterializedAction)[]): void;
+  applyPinnedActions(element: Element): void;
+  after(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  before(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  append(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  prepend(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  replace(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  update(params: Omit<FragmentAction, 'action'> | Omit<MaterializedFragmentAction, 'action'>): void;
+  remove(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  focus(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  disable(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  enable(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  hide(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  show(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  reset(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  refresh(params: Omit<VoidAction, 'action'> | Omit<MaterializedVoidAction, 'action'>): void;
+  morph(from: Element | Document, to: string | Element | Document | DocumentFragment, options?: {
+    childrenOnly?: boolean;
+  }): void;
+  private scheduleActions;
+  private scheduleMaterializedActions;
+  private materializeActions;
+  private _scheduleActions;
+  private _applyActionsInContext;
+  private _applyActions;
+  private _debugMaterializeActions;
+  private _debugApplyActions;
+  private pinAction;
+  _morph(from: Element | Document, to: string | Element | Document | DocumentFragment, options?: {
+    childrenOnly?: boolean;
+  }): void;
+  private _after;
+  private _before;
+  private _append;
+  private _prepend;
+  private _replace;
+  private _update;
+  private _remove;
+  private _focus;
+  private _show;
+  private _hide;
+  private _enable;
+  private _disable;
+  private _reset;
+  private _refresh;
+  private handleEvent;
+  private classListChanged;
+  private attributeChanged;
+}
+declare function isValidActionName(actionName: unknown): actionName is ActionName;
+declare function dispatchActions(actions: (Action | MaterializedAction)[]): void;
+declare function dispatchAction({
+  targets,
+  ...action
+}: (Pick<VoidAction, 'action'> | Pick<FragmentAction, 'action' | 'fragment'>) & {
+  targets?: Element | Element[] | string | null;
+}): void;
+//#endregion
+//#region src/actions.d.ts
+type Targets = Element | Element[] | string | null;
+declare function hide(targets?: Targets): void;
+declare function show(targets?: Targets): void;
+declare function disable(targets?: Targets): void;
+declare function enable(targets?: Targets): void;
+declare function remove(targets?: Targets): void;
+declare function append(targets: Targets, fragment: string | DocumentFragment): void;
+declare function prepend(targets: Targets, fragment: string | DocumentFragment): void;
+declare function after(targets: Targets, fragment: string | DocumentFragment): void;
+declare function before(targets: Targets, fragment: string | DocumentFragment): void;
+declare function update(targets: Targets, fragment: string | DocumentFragment): void;
+declare function replace(targets: Targets, fragment: string | DocumentFragment): void;
+//#endregion
+export { Plugin as S, dispatchAction as _, enable as a, Schema as b, remove as c, update as d, Action as f, MaterializedAction as g, ActionsOptions as h, disable as i, replace as l, Actions as m, append as n, hide as o, ActionName as p, before as r, prepend as s, after as t, show as u, dispatchActions as v, defaultSchema as x, isValidActionName as y };