Datastar
v0.21.4
GuideReferenceExamplesEssaysMemesBundler
Bundler
While Datastar is still one of the smallest frameworks available, you can bundle only the plugins you need to reduce the size even further.
Plugins
fficial/backend/actions
SSE
Use a GET request to fetch data from a server using Server-Sent Events matching the Datastar SDK interface
NameSSE
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/actions/sse.ts
Source
import { DATASTAR, DATASTAR_REQUEST } from '~/engine/consts'
import { dsErr } from '~/engine/errors'
import { type ActionPlugin, PluginType } from '~/engine/types'
import {
  type FetchEventSourceInit,
  fetchEventSource,
} from '~/vendored/fetch-event-source'
import {
  DATASTAR_SSE_EVENT,
  type DatastarSSEEvent,
  ERROR,
  FINISHED,
  STARTED,
} from '../shared'
type METHOD = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
function dispatchSSE(type: string, argsRaw: Record<string, string>) {
  document.dispatchEvent(
    new CustomEvent<DatastarSSEEvent>(DATASTAR_SSE_EVENT, {
      detail: { type, argsRaw },
    }),
  )
}
const isWrongContent = (err: any) => `${err}`.includes('text/event-stream')
export type SSEArgs = {
  method: METHOD
  headers?: Record<string, string>
  openWhenHidden?: boolean
  retryInterval?: number
  retryScaler?: number
  retryMaxWaitMs?: number
  retryMaxCount?: number
  abort?: AbortSignal
} & (
  | {
      contentType: 'json'
      includeLocal?: boolean
    }
  | {
      contentType: 'form'
      selector?: string
    }
)
export const SSE: ActionPlugin = {
  type: PluginType.Action,
  name: 'sse',
  fn: async (ctx, url: string, args: SSEArgs) => {
    const {
      el: { id: elId },
      el,
      signals,
    } = ctx
    const {
      method: methodAnyCase,
      headers: userHeaders,
      contentType,
      includeLocal,
      selector,
      openWhenHidden,
      retryInterval,
      retryScaler,
      retryMaxWaitMs,
      retryMaxCount,
      abort,
    } = Object.assign(
      {
        method: 'GET',
        headers: {},
        contentType: 'json',
        includeLocal: false,
        selector: null,
        openWhenHidden: false, // will keep the request open even if the document is hidden.
        retryInterval: 1_000, // the retry interval in milliseconds
        retryScaler: 2, // the amount to multiply the retry interval by each time
        retryMaxWaitMs: 30_000, // the maximum retry interval in milliseconds
        retryMaxCount: 10, // the maximum number of retries before giving up
        abort: undefined,
      },
      args,
    )
    const method = methodAnyCase.toUpperCase()
    let cleanupFn = (): void => {}
    try {
      dispatchSSE(STARTED, { elId })
      if (!url?.length) {
        throw dsErr('NoUrlProvided')
      }
      const initialHeaders: Record<string, any> = {}
      initialHeaders[DATASTAR_REQUEST] = true
      // We ignore the content-type header if using form data
      // if missing the boundary will be set automatically
      if (contentType === 'json') {
        initialHeaders['Content-Type'] = 'application/json'
      }
      const headers = Object.assign({}, initialHeaders, userHeaders)
      const req: FetchEventSourceInit = {
        method,
        headers,
        openWhenHidden,
        retryInterval,
        retryScaler,
        retryMaxWaitMs,
        retryMaxCount,
        signal: abort,
        onopen: async (response: Response) => {
          if (response.status >= 400) {
            const status = response.status.toString()
            dispatchSSE(ERROR, { status })
          }
        },
        onmessage: (evt) => {
          if (!evt.event.startsWith(DATASTAR)) {
            return
          }
          const type = evt.event
          const argsRawLines: Record<string, string[]> = {}
          const lines = evt.data.split('\n')
          for (const line of lines) {
            const colonIndex = line.indexOf(' ')
            const key = line.slice(0, colonIndex)
            let argLines = argsRawLines[key]
            if (!argLines) {
              argLines = []
              argsRawLines[key] = argLines
            }
            const value = line.slice(colonIndex + 1).trim()
            argLines.push(value)
          }
          const argsRaw: Record<string, string> = {}
          for (const [key, lines] of Object.entries(argsRawLines)) {
            argsRaw[key] = lines.join('\n')
          }
          // if you aren't seeing your event you can debug by using this line in the console
          // document.addEventListener("datastar-sse",(e) => console.log(e));
          dispatchSSE(type, argsRaw)
        },
        onerror: (error) => {
          if (isWrongContent(error)) {
            // don't retry if the content-type is wrong
            throw dsErr('InvalidContentType', { url, error })
          }
          // do nothing and it will retry
          if (error) {
            console.error(error.message)
          }
        },
      }
      const urlInstance = new URL(url, window.location.origin)
      const queryParams = new URLSearchParams(urlInstance.search)
      if (contentType === 'json') {
        const json = signals.JSON(false, !includeLocal)
        if (method === 'GET') {
          queryParams.set(DATASTAR, json)
        } else {
          req.body = json
        }
      } else if (contentType === 'form') {
        const formEl = selector
          ? document.querySelector(selector)
          : el.closest('form')
        if (formEl === null) {
          if (selector) {
            throw dsErr('SseFormNotFound', { selector })
          }
          throw dsErr('SseClosestFormNotFound')
        }
        if (el !== formEl) {
          const preventDefault = (evt: Event) => evt.preventDefault()
          formEl.addEventListener('submit', preventDefault)
          cleanupFn = (): void =>
            formEl.removeEventListener('submit', preventDefault)
        }
        if (!formEl.checkValidity()) {
          formEl.reportValidity()
          cleanupFn()
          return
        }
        const formData = new FormData(formEl)
        if (method === 'GET') {
          const formParams = new URLSearchParams(formData as any)
          for (const [key, value] of formParams) {
            queryParams.set(key, value)
          }
        } else {
          req.body = formData
        }
      } else {
        throw dsErr('SseInvalidContentType', { contentType })
      }
      urlInstance.search = queryParams.toString()
      try {
        await fetchEventSource(urlInstance.toString(), req)
      } catch (error) {
        if (!isWrongContent(error)) {
          throw dsErr('SseFetchFailed', { method, url, error })
        }
        // exit gracefully and do nothing if the content-type is wrong
        // this can happen if the client is sending a request
        // where no response is expected, and they haven't
        // set the content-type to text/event-stream
      }
    } finally {
      dispatchSSE(FINISHED, { elId })
      cleanupFn()
    }
  },
}
fficial/backend/attributes
 
Indicator
Sets the indicator signal used when fetching data via SSE
NameIndicator
Descriptionmust be a valid signal name
Authors
Pathfficial/backend/attributes/indicator.ts
Source
import { DATASTAR } from '~/engine/consts'
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
import {
  DATASTAR_SSE_EVENT,
  type DatastarSSEEvent,
  FINISHED,
  STARTED,
} from '../shared'
export const INDICATOR_CLASS = `${DATASTAR}-indicator`
export const INDICATOR_LOADING_CLASS = `${INDICATOR_CLASS}-loading`
export const Indicator: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'indicator',
  keyReq: Requirement.Exclusive,
  valReq: Requirement.Exclusive,
  onLoad: ({ value, signals, el, key }) => {
    const signalName = key ? key : value
    const signal = signals.upsert(signalName, false)
    const watcher = (event: CustomEvent<DatastarSSEEvent>) => {
      const {
        type,
        argsRaw: { elId },
      } = event.detail
      if (elId !== el.id) return
      switch (type) {
        case STARTED:
          signal.value = true
          break
        case FINISHED:
          signal.value = false
          break
      }
    }
    document.addEventListener(DATASTAR_SSE_EVENT, watcher)
    return () => {
      document.removeEventListener(DATASTAR_SSE_EVENT, watcher)
    }
  },
}
fficial/backend/watchers
 
ExecuteScript
Execute JavaScript using a Server-Sent Event
NameExecuteScript
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/watchers/executeScript.ts
Source
import {
  DefaultExecuteScriptAttributes,
  DefaultExecuteScriptAutoRemove,
  EventTypes,
} from '~/engine/consts'
import { dsErr } from '~/engine/errors'
import { PluginType, type WatcherPlugin } from '~/engine/types'
import { isBoolString } from '~/utils/text'
import { datastarSSEEventWatcher } from '../shared'
export const ExecuteScript: WatcherPlugin = {
  type: PluginType.Watcher,
  name: EventTypes.ExecuteScript,
  onGlobalInit: async () => {
    datastarSSEEventWatcher(
      EventTypes.ExecuteScript,
      ({
        autoRemove: autoRemoveRaw = `${DefaultExecuteScriptAutoRemove}`,
        attributes: attributesRaw = DefaultExecuteScriptAttributes,
        script,
      }) => {
        const autoRemove = isBoolString(autoRemoveRaw)
        if (!script?.length) {
          throw dsErr('NoScriptProvided')
        }
        const scriptEl = document.createElement('script')
        for (const attr of attributesRaw.split('\n')) {
          const pivot = attr.indexOf(' ')
          const key = pivot ? attr.slice(0, pivot) : attr
          const value = pivot ? attr.slice(pivot) : ''
          scriptEl.setAttribute(key.trim(), value.trim())
        }
        scriptEl.text = script
        document.head.appendChild(scriptEl)
        if (autoRemove) {
          scriptEl.remove()
        }
      },
    )
  },
}
 
MergeFragments
Merge fragments into the DOM using a Server-Sent Event
NameMergeFragments
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/watchers/mergeFragments.ts
Source
import {
  DefaultFragmentMergeMode,
  DefaultFragmentsSettleDurationMs,
  DefaultFragmentsUseViewTransitions,
  EventTypes,
  FragmentMergeModes,
} from '~/engine/consts'
import { dsErr } from '~/engine/errors'
import {
  type InitContext,
  PluginType,
  type WatcherPlugin,
} from '~/engine/types'
import { isBoolString } from '~/utils/text'
import {
  docWithViewTransitionAPI,
  supportsViewTransitions,
} from '~/utils/view-transtions'
import { idiomorph } from '~/vendored/idiomorph'
import {
  SETTLING_CLASS,
  SWAPPING_CLASS,
  datastarSSEEventWatcher,
} from '../shared'
export const MergeFragments: WatcherPlugin = {
  type: PluginType.Watcher,
  name: EventTypes.MergeFragments,
  onGlobalInit: async (ctx) => {
    const fragmentContainer = document.createElement('template')
    datastarSSEEventWatcher(
      EventTypes.MergeFragments,
      ({
        fragments: fragmentsRaw = '<div></div>',
        selector = '',
        mergeMode = DefaultFragmentMergeMode,
        settleDuration:
          settleDurationRaw = `${DefaultFragmentsSettleDurationMs}`,
        useViewTransition:
          useViewTransitionRaw = `${DefaultFragmentsUseViewTransitions}`,
      }) => {
        const settleDuration = Number.parseInt(settleDurationRaw)
        const useViewTransition = isBoolString(useViewTransitionRaw)
        fragmentContainer.innerHTML = fragmentsRaw.trim()
        const fragments = [...fragmentContainer.content.children]
        for (const fragment of fragments) {
          if (!(fragment instanceof Element)) {
            throw dsErr('NoFragmentsFound')
          }
          const selectorOrID = selector || `#${fragment.getAttribute('id')}`
          const targets = [...(document.querySelectorAll(selectorOrID) || [])]
          if (!targets.length) {
            throw dsErr('NoTargetsFound', { selectorOrID })
          }
          if (supportsViewTransitions && useViewTransition) {
            docWithViewTransitionAPI.startViewTransition(() =>
              applyToTargets(ctx, mergeMode, settleDuration, fragment, targets),
            )
          } else {
            applyToTargets(ctx, mergeMode, settleDuration, fragment, targets)
          }
        }
      },
    )
  },
}
function applyToTargets(
  ctx: InitContext,
  mergeMode: string,
  settleDuration: number,
  fragment: Element,
  capturedTargets: Element[],
) {
  for (const initialTarget of capturedTargets) {
    initialTarget.classList.add(SWAPPING_CLASS)
    const originalHTML = initialTarget.outerHTML
    let modifiedTarget = initialTarget
    switch (mergeMode) {
      case FragmentMergeModes.Morph: {
        const result = idiomorph(modifiedTarget, fragment, {
          callbacks: {
            beforeNodeRemoved: (oldNode: Element, _: Element) => {
              ctx.cleanup(oldNode)
              return true
            },
          },
        })
        if (!result?.length) {
          throw dsErr('MorphFailed')
        }
        modifiedTarget = result[0] as Element
        break
      }
      case FragmentMergeModes.Inner:
        // Replace the contents of the target element with the response
        modifiedTarget.innerHTML = fragment.innerHTML
        break
      case FragmentMergeModes.Outer:
        // Replace the entire target element with the response
        modifiedTarget.replaceWith(fragment)
        break
      case FragmentMergeModes.Prepend:
        // Insert the response before the first child of the target element
        modifiedTarget.prepend(fragment)
        break
      case FragmentMergeModes.Append:
        // Insert the response after the last child of the target element
        modifiedTarget.append(fragment)
        break
      case FragmentMergeModes.Before:
        // Insert the response before the target element
        modifiedTarget.before(fragment)
        break
      case FragmentMergeModes.After:
        // Insert the response after the target element
        modifiedTarget.after(fragment)
        break
      case FragmentMergeModes.UpsertAttributes:
        // Upsert the attributes of the target element
        for (const attrName of fragment.getAttributeNames()) {
          const value = fragment.getAttribute(attrName)!
          modifiedTarget.setAttribute(attrName, value)
        }
        break
      default:
        throw dsErr('InvalidMergeMode', { mergeMode })
    }
    ctx.cleanup(modifiedTarget)
    const cl = modifiedTarget.classList
    cl.add(SWAPPING_CLASS)
    ctx.apply(document.body)
    setTimeout(() => {
      initialTarget.classList.remove(SWAPPING_CLASS)
      cl.remove(SWAPPING_CLASS)
    }, settleDuration)
    const revisedHTML = modifiedTarget.outerHTML
    if (originalHTML !== revisedHTML) {
      cl.add(SETTLING_CLASS)
      setTimeout(() => {
        cl.remove(SETTLING_CLASS)
      }, settleDuration)
    }
  }
}
 
MergeSignals
Merge signals using a Server-Sent Event
NameMergeSignals
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/watchers/mergeSignals.ts
Source
import { DefaultMergeSignalsOnlyIfMissing, EventTypes } from '~/engine/consts'
import { PluginType, type WatcherPlugin } from '~/engine/types'
import { isBoolString, jsStrToObject } from '~/utils/text'
import { datastarSSEEventWatcher } from '../shared'
export const MergeSignals: WatcherPlugin = {
  type: PluginType.Watcher,
  name: EventTypes.MergeSignals,
  onGlobalInit: async (ctx) => {
    datastarSSEEventWatcher(
      EventTypes.MergeSignals,
      ({
        signals: raw = '{}',
        onlyIfMissing: onlyIfMissingRaw = `${DefaultMergeSignalsOnlyIfMissing}`,
      }) => {
        const { signals } = ctx
        const onlyIfMissing = isBoolString(onlyIfMissingRaw)
        signals.merge(jsStrToObject(raw), onlyIfMissing)
        ctx.apply(document.body)
      },
    )
  },
}
 
RemoveFragments
Remove fragments from the DOM using a Server-Sent Event
NameRemoveFragments
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/watchers/removeFragments.ts
Source
import {
  DefaultFragmentsSettleDurationMs,
  DefaultFragmentsUseViewTransitions,
  EventTypes,
} from '~/engine/consts'
import { dsErr } from '~/engine/errors'
import { PluginType, type WatcherPlugin } from '~/engine/types'
import { isBoolString } from '~/utils/text'
import {
  docWithViewTransitionAPI,
  supportsViewTransitions,
} from '~/utils/view-transtions'
import { SWAPPING_CLASS, datastarSSEEventWatcher } from '../shared'
export const RemoveFragments: WatcherPlugin = {
  type: PluginType.Watcher,
  name: EventTypes.RemoveFragments,
  onGlobalInit: async () => {
    datastarSSEEventWatcher(
      EventTypes.RemoveFragments,
      ({
        selector,
        settleDuration:
          settleDurationRaw = `${DefaultFragmentsSettleDurationMs}`,
        useViewTransition:
          useViewTransitionRaw = `${DefaultFragmentsUseViewTransitions}`,
      }) => {
        if (!selector.length) {
          throw dsErr('NoSelectorProvided')
        }
        const settleDuration = Number.parseInt(settleDurationRaw)
        const useViewTransition = isBoolString(useViewTransitionRaw)
        const removeTargets = document.querySelectorAll(selector)
        const applyToTargets = () => {
          for (const target of removeTargets) {
            target.classList.add(SWAPPING_CLASS)
          }
          setTimeout(() => {
            for (const target of removeTargets) {
              target.remove()
            }
          }, settleDuration)
        }
        if (supportsViewTransitions && useViewTransition) {
          docWithViewTransitionAPI.startViewTransition(() => applyToTargets())
        } else {
          applyToTargets()
        }
      },
    )
  },
}
 
RemoveSignals
Remove signals using a Server-Sent Event
NameRemoveSignals
DescriptionRemember, SSE is just a regular SSE request but with the ability to send 0-inf messages to the client.
Authors
Pathfficial/backend/watchers/removeSignals.ts
Source
import { EventTypes } from '~/engine/consts'
import { dsErr } from '~/engine/errors'
import { PluginType, type WatcherPlugin } from '~/engine/types'
import { datastarSSEEventWatcher } from '../shared'
export const RemoveSignals: WatcherPlugin = {
  type: PluginType.Watcher,
  name: EventTypes.RemoveSignals,
  onGlobalInit: async (ctx) => {
    datastarSSEEventWatcher(
      EventTypes.RemoveSignals,
      ({ paths: pathsRaw = '' }) => {
        const paths = pathsRaw.split('\n').map((p) => p.trim())
        if (!paths?.length) {
          throw dsErr('NoPathsProvided')
        }
        ctx.signals.remove(...paths)
        ctx.apply(document.body)
      },
    )
  },
}
fficial/browser/actions
 
Clipboard
Copy text to the clipboard
NameClipboard
DescriptionThis action copies text to the clipboard using the Clipboard API.
AuthorsDelaney Gillilan
Pathfficial/browser/actions/clipboard.ts
Source
import { dsErr } from '~/engine/errors'
import { type ActionPlugin, PluginType } from '~/engine/types'
export const Clipboard: ActionPlugin = {
  type: PluginType.Action,
  name: 'clipboard',
  fn: (_, text) => {
    if (!navigator.clipboard) {
      throw dsErr('ClipboardNotAvailable')
    }
    navigator.clipboard.writeText(text)
  },
}
fficial/browser/attributes
 
Intersects
Run expression when element intersects with viewport
NameIntersects
DescriptionAn attribute that runs an expression when the element intersects with the viewport.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/intersects.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
const ONCE = 'once'
const HALF = 'half'
const FULL = 'full'
export const Intersects: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'intersects',
  keyReq: Requirement.Denied,
  mods: new Set([ONCE, HALF, FULL]),
  onLoad: ({ el, rawKey, mods, genRX }) => {
    const options = { threshold: 0 }
    if (mods.has(FULL)) options.threshold = 1
    else if (mods.has(HALF)) options.threshold = 0.5
    const rx = genRX()
    const observer = new IntersectionObserver((entries) => {
      for (const entry of entries) {
        if (entry.isIntersecting) {
          rx()
          if (mods.has(ONCE)) {
            observer.disconnect()
            delete el.dataset[rawKey]
          }
        }
      }
    }, options)
    observer.observe(el)
    return () => observer.disconnect()
  },
}
 
Persist
Persist data to local storage or session storage
NamePersist
DescriptionThis plugin allows you to persist data to local storage or session storage.  Once you add this attribute the data will be persisted to local storage or session storage.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/persist.ts
Source
import { DATASTAR } from '~/engine/consts'
import {
  type AttributePlugin,
  type NestedValues,
  PluginType,
} from '~/engine/types'
const SESSION = 'session'
export const Persist: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'persist',
  mods: new Set([SESSION]),
  onLoad: ({ key, value, signals, effect, mods }) => {
    if (key === '') {
      key = DATASTAR
    }
    const storage = mods.has(SESSION) ? sessionStorage : localStorage
    const paths = value.split(/\s+/).filter((p) => p !== '')
    const storageToSignals = () => {
      const data = storage.getItem(key) || '{}'
      const nestedValues = JSON.parse(data)
      signals.merge(nestedValues)
    }
    const signalsToStorage = () => {
      let nv: NestedValues
      if (!paths.length) {
        nv = signals.values()
      } else {
        nv = signals.subset(...paths)
      }
      storage.setItem(key, JSON.stringify(nv))
    }
    storageToSignals()
    return effect(() => {
      signalsToStorage()
    })
  },
}
 
ReplaceUrl
Replace the current URL with a new URL
NameReplaceUrl
DescriptionThis plugin allows you to replace the current URL with a new URL.  Once you add this attribute the current URL will be replaced with the new URL.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/replaceUrl.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
export const ReplaceUrl: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'replaceUrl',
  keyReq: Requirement.Denied,
  valReq: Requirement.Must,
  onLoad: ({ effect, genRX }) => {
    const rx = genRX()
    return effect(() => {
      const url = rx<string>()
      const baseUrl = window.location.href
      const fullUrl = new URL(url, baseUrl).toString()
      window.history.replaceState({}, '', fullUrl)
    })
  },
}
 
ScrollIntoView
Scroll an element into view
NameScrollIntoView
DescriptionThis attribute scrolls the element into view.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/scrollIntoView.ts
Source
import { dsErr } from '~/engine/errors'
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
const SMOOTH = 'smooth'
const INSTANT = 'instant'
const AUTO = 'auto'
const HSTART = 'hstart'
const HCENTER = 'hcenter'
const HEND = 'hend'
const HNEAREST = 'hnearest'
const VSTART = 'vstart'
const VCENTER = 'vcenter'
const VEND = 'vend'
const VNEAREST = 'vnearest'
const FOCUS = 'focus'
const CENTER = 'center'
const START = 'start'
const END = 'end'
const NEAREST = 'nearest'
export const ScrollIntoView: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'scrollIntoView',
  keyReq: Requirement.Denied,
  valReq: Requirement.Denied,
  mods: new Set([
    SMOOTH,
    INSTANT,
    AUTO,
    HSTART,
    HCENTER,
    HEND,
    HNEAREST,
    VSTART,
    VCENTER,
    VEND,
    VNEAREST,
    FOCUS,
  ]),
  onLoad: ({ el, mods, rawKey }) => {
    if (!el.tabIndex) el.setAttribute('tabindex', '0')
    const opts: ScrollIntoViewOptions = {
      behavior: SMOOTH,
      block: CENTER,
      inline: CENTER,
    }
    if (mods.has(SMOOTH)) opts.behavior = SMOOTH
    if (mods.has(INSTANT)) opts.behavior = INSTANT
    if (mods.has(AUTO)) opts.behavior = AUTO
    if (mods.has(HSTART)) opts.inline = START
    if (mods.has(HCENTER)) opts.inline = CENTER
    if (mods.has(HEND)) opts.inline = END
    if (mods.has(HNEAREST)) opts.inline = NEAREST
    if (mods.has(VSTART)) opts.block = START
    if (mods.has(VCENTER)) opts.block = CENTER
    if (mods.has(VEND)) opts.block = END
    if (mods.has(VNEAREST)) opts.block = NEAREST
    if (!(el instanceof HTMLElement || el instanceof SVGElement)) {
      throw dsErr('NotHtmlSvgElement, el')
    }
    if (!el.tabIndex) {
      el.setAttribute('tabindex', '0')
    }
    el.scrollIntoView(opts)
    if (mods.has('focus')) {
      el.focus()
    }
    delete el.dataset[rawKey]
    return () => {}
  },
}
 
Show
Show or hide an element
NameShow
DescriptionThis attribute shows or hides an element based on the value of the expression. If the expression is true, the element is shown. If the expression is false, the element is hidden. The element is hidden by setting the display property to none.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/show.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
const NONE = 'none'
const DISPLAY = 'display'
export const Show: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'show',
  keyReq: Requirement.Denied,
  valReq: Requirement.Must,
  onLoad: ({ el: { style: s }, genRX, effect }) => {
    const rx = genRX()
    return effect(async () => {
      const shouldShow = rx<boolean>()
      if (shouldShow) {
        if (s.display === NONE) {
          s.removeProperty(DISPLAY)
        }
      } else {
        s.setProperty(DISPLAY, NONE)
      }
    })
  },
}
 
ViewTransition
Setup view transitions
NameViewTransition
DescriptionThis attribute plugin sets up view transitions for the current view. This plugin requires the view transition API to be enabled in the browser. If the browser does not support view transitions, an error will be logged to the console.
AuthorsDelaney Gillilan
Pathfficial/browser/attributes/viewTransition.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
import { supportsViewTransitions } from '~/utils/view-transtions'
const VIEW_TRANSITION = 'view-transition'
export const ViewTransition: AttributePlugin = {
  type: PluginType.Attribute,
  name: VIEW_TRANSITION,
  keyReq: Requirement.Denied,
  valReq: Requirement.Must,
  onGlobalInit() {
    let hasViewTransitionMeta = false
    for (const node of document.head.childNodes) {
      if (node instanceof HTMLMetaElement && node.name === VIEW_TRANSITION) {
        hasViewTransitionMeta = true
      }
    }
    if (!hasViewTransitionMeta) {
      const meta = document.createElement('meta')
      meta.name = VIEW_TRANSITION
      meta.content = 'same-origin'
      document.head.appendChild(meta)
    }
  },
  onLoad: ({ effect, el, genRX }) => {
    if (!supportsViewTransitions) {
      console.error('Browser does not support view transitions')
      return
    }
    const rx = genRX()
    return effect(() => {
      const name = rx<string>()
      if (!name?.length) return
      const elVTASTyle = el.style as unknown as CSSStyleDeclaration
      elVTASTyle.viewTransitionName = name
    })
  },
}
fficial/dom/attributes
 
Attributes
Bind attributes to expressions
NameAttributes
DescriptionAny attribute can be bound to an expression. The attribute will be updated reactively whenever the expression signal changes.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/attributes.ts
Source
import {
  type AttributePlugin,
  type NestedValues,
  PluginType,
  Requirement,
} from '~/engine/types'
import { kebabize } from '~/utils/text'
export const Attributes: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'attributes',
  valReq: Requirement.Must,
  onLoad: ({ el, genRX, key, effect }) => {
    const rx = genRX()
    if (key === '') {
      return effect(async () => {
        const binds = rx<NestedValues>()
        for (const [attr, val] of Object.entries(binds)) {
          el.setAttribute(attr, val)
        }
      })
    }
    key = kebabize(key)
    return effect(async () => {
      let value = false
      try {
        value = rx()
      } catch (e) {} //
      let v: string
      if (typeof value === 'string') {
        v = value
      } else {
        v = JSON.stringify(value)
      }
      if (!v || v === 'false' || v === 'null' || v === 'undefined') {
        el.removeAttribute(key)
      } else {
        el.setAttribute(key, v)
      }
    })
  },
}
 
Bind
Bind attributes to expressions
NameBind
DescriptionAny attribute can be bound to an expression. The attribute will be updated reactively whenever the expression signal changes.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/bind.ts
Source
import { dsErr } from '~/engine/errors'
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
const dataURIRegex = /^data:(?<mime>[^;]+);base64,(?<contents>.*)$/
const updateEvents = ['change', 'input', 'keydown']
export const Bind: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'bind',
  keyReq: Requirement.Exclusive,
  valReq: Requirement.Exclusive,
  onLoad: (ctx) => {
    const { el, value, key, signals, effect } = ctx
    const signalName = key ? key : value
    let setFromSignal = () => {}
    let el2sig = () => {}
    // I better be tied to a signal
    if (typeof signalName !== 'string') {
      throw dsErr('InvalidExpression')
    }
    const tnl = el.tagName.toLowerCase()
    let signalDefault: string | boolean | number | File = ''
    const isInput = tnl.includes('input')
    const type = el.getAttribute('type')
    const isCheckbox =
      tnl.includes('checkbox') || (isInput && type === 'checkbox')
    if (isCheckbox) {
      signalDefault = false
    }
    const isNumber = isInput && type === 'number'
    if (isNumber) {
      signalDefault = 0
    }
    const isSelect = tnl.includes('select')
    const isRadio = tnl.includes('radio') || (isInput && type === 'radio')
    const isFile = isInput && type === 'file'
    if (isFile) {
      // can't set a default value for a file input, yet
    }
    if (isRadio) {
      const name = el.getAttribute('name')
      if (!name?.length) {
        el.setAttribute('name', signalName)
      }
    }
    signals.upsert(signalName, signalDefault)
    setFromSignal = () => {
      const hasValue = 'value' in el
      const v = signals.value(signalName)
      const vStr = `${v}`
      if (isCheckbox || isRadio) {
        const input = el as HTMLInputElement
        if (isCheckbox) {
          input.checked = !!v || v === 'true'
        } else if (isRadio) {
          // evaluate the value as string to handle any type casting
          // automatically since the attribute has to be a string anyways
          input.checked = vStr === input.value
        }
      } else if (isFile) {
        // File input reading from a signal is not supported yet
      } else if (isSelect) {
        const select = el as HTMLSelectElement
        if (select.multiple) {
          for (const opt of select.options) {
            if (opt?.disabled) return
            if (Array.isArray(v) || typeof v === 'string') {
              opt.selected = v.includes(opt.value)
            } else if (typeof v === 'number') {
              opt.selected = v === Number(opt.value)
            } else {
              opt.selected = v as boolean
            }
          }
        } else {
          select.value = vStr
        }
      } else if (hasValue) {
        el.value = vStr
      } else {
        el.setAttribute('value', vStr)
      }
    }
    el2sig = async () => {
      if (isFile) {
        const files = [...((el as HTMLInputElement)?.files || [])]
        const allContents: string[] = []
        const allMimes: string[] = []
        const allNames: string[] = []
        await Promise.all(
          files.map((f) => {
            return new Promise<void>((resolve) => {
              const reader = new FileReader()
              reader.onload = () => {
                if (typeof reader.result !== 'string') {
                  throw dsErr('InvalidFileResultType', {
                    type: typeof reader.result,
                  })
                }
                const match = reader.result.match(dataURIRegex)
                if (!match?.groups) {
                  throw dsErr('InvalidDataUri', {
                    result: reader.result,
                  })
                }
                allContents.push(match.groups.contents)
                allMimes.push(match.groups.mime)
                allNames.push(f.name)
              }
              reader.onloadend = () => resolve(void 0)
              reader.readAsDataURL(f)
            })
          }),
        )
        signals.setValue(signalName, allContents)
        const mimeName = `${signalName}Mimes`
        const nameName = `${signalName}Names`
        if (mimeName in signals) {
          signals.upsert(mimeName, allMimes)
        }
        if (nameName in signals) {
          signals.upsert(nameName, allNames)
        }
        return
      }
      const current = signals.value(signalName)
      const input = (el as HTMLInputElement) || (el as HTMLElement)
      if (typeof current === 'number') {
        const v = Number(input.value || input.getAttribute('value'))
        signals.setValue(signalName, v)
      } else if (typeof current === 'string') {
        const v = input.value || input.getAttribute('value') || ''
        signals.setValue(signalName, v)
      } else if (typeof current === 'boolean') {
        if (isCheckbox) {
          const v = input.checked || input.getAttribute('checked') === 'true'
          signals.setValue(signalName, v)
        } else {
          const v = Boolean(input.value || input.getAttribute('value'))
          signals.setValue(signalName, v)
        }
      } else if (typeof current === 'undefined') {
      } else if (Array.isArray(current)) {
        // check if the input is a select element
        if (isSelect) {
          const select = el as HTMLSelectElement
          const selectedOptions = [...select.selectedOptions]
          const selectedValues = selectedOptions
            .filter((opt) => opt.selected)
            .map((opt) => opt.value)
          signals.setValue(signalName, selectedValues)
        } else {
          // assume it's a comma-separated string
          const v = JSON.stringify(input.value.split(','))
          signals.setValue(signalName, v)
        }
      } else {
        throw dsErr('UnsupportedSignalType', {
          current: typeof current,
        })
      }
    }
    for (const event of updateEvents) {
      el.addEventListener(event, el2sig)
    }
    const elSigClean = effect(() => setFromSignal())
    return () => {
      elSigClean()
      for (const event of updateEvents) {
        el.removeEventListener(event, el2sig)
      }
    }
  },
}
 
Class
Add or remove classes from an element reactively
NameClass
DescriptionThis action adds or removes classes from an element reactively based on the expression provided. The expression should be an object where the keys are the class names and the values are booleans. If the value is true, the class is added. If the value is false, the class is removed.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/class.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
import { kebabize } from '~/utils/text'
export const Class: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'class',
  valReq: Requirement.Must,
  onLoad: ({ key, el, genRX, effect }) => {
    const cl = el.classList
    const rx = genRX()
    return effect(() => {
      if (key === '') {
        const classes = rx<Record<string, boolean>>()
        for (const [k, v] of Object.entries(classes)) {
          const classNames = k.split(/\s+/)
          if (v) {
            cl.add(...classNames)
          } else {
            cl.remove(...classNames)
          }
        }
      } else {
        const shouldInclude = rx<boolean>()
        const cls = kebabize(key)
        if (shouldInclude) {
          cl.add(cls)
        } else {
          cl.remove(cls)
        }
      }
    })
  },
}
 
On
Add an event listener to an element
NameOn
DescriptionThis action adds an event listener to an element. The event listener can be triggered by a variety of events, such as clicks, keypresses, and more. The event listener can also be set to trigger only once, or to be passive or capture. The event listener can also be debounced or throttled. The event listener can also be set to trigger only when the event target is outside the element.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/on.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
import { onElementRemoved } from '~/utils/dom'
import { tagHas, tagToMs } from '~/utils/tags'
import { kebabize } from '~/utils/text'
import { debounce, throttle } from '~/utils/timing'
const lastSignalsMarshalled = new Map<string, any>()
const EVT = 'evt'
export const On: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'on',
  keyReq: Requirement.Must,
  valReq: Requirement.Must,
  argNames: [EVT],
  macros: {
    pre: [
      {
        // We need to escape the evt in case .value is used
        type: PluginType.Macro,
        name: 'evtEsc',
        fn: (original) => {
          return original.replaceAll(/evt.([\w\.]+)value/gm, 'EVT_$1_VALUE')
        },
      },
    ],
    post: [
      {
        // We need to unescape the evt in case .value is used
        type: PluginType.Macro,
        name: 'evtUnesc',
        fn: (original) => {
          return original.replaceAll(/EVT_([\w\.]+)_VALUE/gm, 'evt.$1value')
        },
      },
    ],
  },
  onLoad: ({ el, key, genRX, mods, signals, effect }) => {
    const rx = genRX()
    let target: Element | Window | Document = el
    if (mods.has('window')) target = window
    let callback = (evt?: Event) => {
      if (evt) {
        // Always prevent default on submit events (because forms)
        if (mods.has('prevent') || key === 'submit') evt.preventDefault()
        if (mods.has('stop')) evt.stopPropagation()
      }
      rx(evt)
    }
    const debounceArgs = mods.get('debounce')
    if (debounceArgs) {
      const wait = tagToMs(debounceArgs)
      const leading = tagHas(debounceArgs, 'leading', false)
      const trailing = !tagHas(debounceArgs, 'notrail', false)
      callback = debounce(callback, wait, leading, trailing)
    }
    const throttleArgs = mods.get('throttle')
    if (throttleArgs) {
      const wait = tagToMs(throttleArgs)
      const leading = !tagHas(throttleArgs, 'noleading', false)
      const trailing = tagHas(throttleArgs, 'trail', false)
      callback = throttle(callback, wait, leading, trailing)
    }
    const evtListOpts: AddEventListenerOptions = {
      capture: true,
      passive: false,
      once: false,
    }
    if (!mods.has('capture')) evtListOpts.capture = false
    if (mods.has('passive')) evtListOpts.passive = true
    if (mods.has('once')) evtListOpts.once = true
    const eventName = kebabize(key).toLowerCase()
    switch (eventName) {
      case 'load': {
        callback()
        delete el.dataset.onLoad
        return () => {}
      }
      case 'raf': {
        let rafId: number | undefined
        const raf = () => {
          callback()
          rafId = requestAnimationFrame(raf)
        }
        rafId = requestAnimationFrame(raf)
        return () => {
          if (rafId) cancelAnimationFrame(rafId)
        }
      }
      case 'signals-change': {
        onElementRemoved(el, () => {
          lastSignalsMarshalled.delete(el.id)
        })
        return effect(() => {
          const onlyRemoteSignals = mods.has('remote')
          const current = signals.JSON(false, onlyRemoteSignals)
          const last = lastSignalsMarshalled.get(el.id) || ''
          if (last !== current) {
            lastSignalsMarshalled.set(el.id, current)
            callback()
          }
        })
      }
      default: {
        const testOutside = mods.has('outside')
        if (testOutside) {
          target = document
          const cb = callback
          let called = false
          const targetOutsideCallback = (e?: Event) => {
            const targetHTML = e?.target as HTMLElement
            if (!targetHTML) return
            const isEl = el.id === targetHTML.id
            if (isEl && called) {
              called = false
            }
            if (!isEl && !called) {
              cb(e)
              called = true
            }
          }
          callback = targetOutsideCallback
        }
        target.addEventListener(eventName, callback, evtListOpts)
        return () => {
          target.removeEventListener(eventName, callback)
        }
      }
    }
  },
}
 
Ref
Create a reference to an element
NameRef
DescriptionThis attribute creates a reference to an element that can be used in other expressions.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/ref.ts
Source
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
export const Ref: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'ref',
  keyReq: Requirement.Exclusive,
  valReq: Requirement.Exclusive,
  onLoad: ({ el, key, value, signals }) => {
    const signalName = key ? key : value
    signals.upsert(signalName, el)
    return () => signals.setValue(signalName, null)
  },
}
 
Text
Set the text content of an element
NameText
DescriptionThis attribute sets the text content of an element to the result of the expression.
AuthorsDelaney Gillilan
Pathfficial/dom/attributes/text.ts
Source
import { dsErr } from '~/engine/errors'
import { type AttributePlugin, PluginType, Requirement } from '~/engine/types'
export const Text: AttributePlugin = {
  type: PluginType.Attribute,
  name: 'text',
  keyReq: Requirement.Denied,
  valReq: Requirement.Must,
  onLoad: (ctx) => {
    const { el, genRX, effect } = ctx
    const rx = genRX()
    if (!(el instanceof HTMLElement)) {
      dsErr('NotHtmlElement')
    }
    return effect(() => {
      const res = rx(ctx)
      el.textContent = `${res}`
    })
  },
}
fficial/logic/actions
 
Fit
Clamp a value to a new range
NameFit
DescriptionThis action clamps a value to a new range. The value is first scaled to the new range, then clamped to the new range. This is useful for scaling a value to a new range, then clamping it to that range.
AuthorsDelaney Gillilan
Pathfficial/logic/actions/fit.ts
Source
import {
  type ActionPlugin,
  PluginType,
  type RuntimeContext,
} from '~/engine/types'
const { round, max, min } = Math
export const Fit: ActionPlugin = {
  type: PluginType.Action,
  name: 'fit',
  fn: (
    _: RuntimeContext,
    v: number,
    oldMin: number,
    oldMax: number,
    newMin: number,
    newMax: number,
    shouldClamp = false,
    shouldRound = false,
  ) => {
    let fitted = ((v - oldMin) / (oldMax - oldMin)) * (newMax - newMin) + newMin
    if (shouldRound) {
      fitted = round(fitted)
    }
    if (shouldClamp) {
      fitted = max(newMin, min(newMax, fitted))
    }
    return fitted
  },
}
 
SetAll
Set all signals that match a regular expression
NameSetAll
AuthorsDelaney Gillilan
Pathfficial/logic/actions/setAll.ts
Source
import { type ActionPlugin, PluginType } from '~/engine/types'
export const SetAll: ActionPlugin = {
  type: PluginType.Action,
  name: 'setAll',
  fn: ({ signals }, prefix: string, newValue) => {
    signals.walk((path, signal) => {
      if (!path.startsWith(prefix)) return
      signal.value = newValue
    })
  },
}
 
ToggleAll
Toggle all signals that match a regular expression
NameToggleAll
AuthorsDelaney Gillilan
Pathfficial/logic/actions/toggleAll.ts
Source
import { type ActionPlugin, PluginType } from '~/engine/types'
export const ToggleAll: ActionPlugin = {
  type: PluginType.Action,
  name: 'toggleAll',
  fn: ({ signals }, prefix: string) => {
    signals.walk((path, signal) => {
      if (!path.startsWith(prefix)) return
      signal.value = !signal.value
    })
  },
}