@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/cadence/cadence-web/app/utils/use-query-state.ts

@@ -0,0 +1,629 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import { useLocation, useNavigation, useSearchParams as useSearchParamsRR } from 'react-router'
+import { dateFns, dateTimeFns, durationFns, type Iso } from 'iso-fns'
+import React from 'react'
+import { useStableAccessor } from './use-stable-accessor'
+
+// ────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────
+
+interface QueryStateNavigateOptions {
+  replace?: boolean
+  preventScrollReset?: boolean
+  /** When true, updates the URL via `history.pushState`/`replaceState` without triggering a React Router navigation. */
+  shallow?: boolean
+}
+
+interface CodecDef<T> {
+  name: string
+  defaultValue?: T
+  ['~type']: T
+  /** When true, the param is removed from the URL when the value matches `defaultValue`. */
+  clearOnDefault?: boolean
+}
+
+interface Codec<Def extends CodecDef<any>> {
+  _def: Def
+  encode(value: Def['~type']): string | null
+  decode(value: string | null): Def['~type']
+}
+
+interface CodecConfigurator<Def extends CodecDef<any>> extends Codec<Def> {
+  default(defaultValue: Def['~type']): CodecConfigurator<Def>
+  clearOnDefault(clear: boolean): CodecConfigurator<Def>
+}
+
+function makeConfigurator<Def extends CodecDef<any>>(codec: Codec<Def>): CodecConfigurator<Def> {
+  return {
+    ...codec,
+    default(defaultValue) {
+      return makeConfigurator({ ...codec, _def: { ...codec._def, defaultValue } })
+    },
+    clearOnDefault(clear) {
+      return makeConfigurator({ ...codec, _def: { ...codec._def, clearOnDefault: clear } })
+    }
+  }
+}
+
+// ────────────────────────────────────────────────────────────────
+// Codec defs
+// ────────────────────────────────────────────────────────────────
+
+interface NoopDef extends CodecDef<string | null> {
+  name: 'noop'
+  ['~type']: string | null
+}
+
+interface StringDef extends CodecDef<string | null> {
+  name: 'string'
+  ['~type']: string | null
+}
+
+interface ValidatedDef<T extends string> extends CodecDef<T | null> {
+  name: string
+  ['~type']: T | null
+  isValid: (v: string) => v is T
+}
+
+interface RelativeDateTimeRangeDef extends CodecDef<Iso.Duration | { start: Iso.DateTime; end: Iso.DateTime } | null> {
+  name: 'relativeDateTimeRange'
+  ['~type']: Iso.Duration | { start: Iso.DateTime; end: Iso.DateTime } | null
+}
+
+interface IntDef extends CodecDef<number | null> {
+  name: 'int'
+  ['~type']: number | null
+}
+
+interface FloatDef extends CodecDef<number | null> {
+  name: 'float'
+  ['~type']: number | null
+}
+
+interface HexDef extends CodecDef<number | null> {
+  name: 'hex'
+  ['~type']: number | null
+}
+
+interface IndexDef extends CodecDef<number | null> {
+  name: 'index'
+  ['~type']: number | null
+}
+
+interface BooleanDef extends CodecDef<boolean | null> {
+  name: 'boolean'
+  ['~type']: boolean | null
+}
+
+interface EnumDef<T extends string> extends CodecDef<T | null> {
+  name: 'enum'
+  ['~type']: T | null
+  values: readonly T[]
+}
+
+interface EnumArrayDef<T extends string> extends CodecDef<T[]> {
+  name: 'enumArray'
+  ['~type']: T[]
+  values: readonly T[]
+}
+
+// ────────────────────────────────────────────────────────────────
+// Codec factories
+// ────────────────────────────────────────────────────────────────
+
+/** Pass-through — no transformation, value is `string | null`. */
+function noop(def: Omit<NoopDef, '~type'>): Codec<NoopDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => value,
+    decode: (value) => value
+  }
+}
+
+/** String codec — pass-through with `string | null` type. */
+function string(def: Omit<StringDef, '~type'>): Codec<StringDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => value,
+    decode: (value) => value
+  }
+}
+
+/** Validates a string against a guard function. Used for date, dateTime, duration. */
+function validated<T extends string>(def: Omit<ValidatedDef<T>, '~type'>): Codec<ValidatedDef<T>> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (value != null && def.isValid(value) ? value : null),
+    decode: (value) => (value !== null && def.isValid(value) ? value : null)
+  }
+}
+
+/**
+ * Either an ISO duration (relative range) or a `start~end` pair of ISO
+ * date-times (absolute range). Useful for "last 7 days" vs a custom window.
+ */
+function relativeDateTimeRange(def: Omit<RelativeDateTimeRangeDef, '~type'>): Codec<RelativeDateTimeRangeDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => {
+      if (value == null) return null
+      if (durationFns.isValid(value)) return value
+      if (typeof value === 'object' && 'start' in value && 'end' in value) {
+        return dateTimeFns.isValid(value.start) && dateTimeFns.isValid(value.end) ? `${value.start}~${value.end}` : null
+      }
+      return null
+    },
+    decode: (value) => {
+      if (value === null) return null
+      if (durationFns.isValid(value)) return value
+      const [start, end] = value.split('~')
+      return dateTimeFns.isValid(start) && dateTimeFns.isValid(end) ? { start, end } : null
+    }
+  }
+}
+
+/** Integer (base-10). Non-integer or missing values decode to `null`. */
+function int(def: Omit<IntDef, '~type'>): Codec<IntDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (value != null && Number.isInteger(value) ? value.toString() : null),
+    decode: (value) => {
+      if (value === null) return null
+      const num = Number(value)
+      return Number.isInteger(num) ? num : null
+    }
+  }
+}
+
+/** Finite floating-point number. `NaN` / `Infinity` decode to `null`. */
+function float(def: Omit<FloatDef, '~type'>): Codec<FloatDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (value != null && Number.isFinite(value) ? value.toString() : null),
+    decode: (value) => {
+      if (value === null) return null
+      const num = Number(value)
+      return Number.isFinite(num) ? num : null
+    }
+  }
+}
+
+/** Hexadecimal integer (with or without `0x` prefix). Stored without prefix. */
+function hex(def: Omit<HexDef, '~type'>): Codec<HexDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (typeof value === 'number' && Number.isFinite(value) ? value.toString(16) : null),
+    decode: (value) => {
+      if (value === null) return null
+      const body = value.trim().toLowerCase().replace(/^0x/, '')
+      if (body.length === 0 || /[^0-9a-f]/i.test(body)) return null
+      const num = parseInt(body, 16)
+      return Number.isFinite(num) ? num : null
+    }
+  }
+}
+
+/**
+ * Zero-based index stored as a **1-based** number in the URL.
+ * `?page=1` decodes to `0`, `0` encodes to `"1"`.
+ */
+function index(def: Omit<IndexDef, '~type'>): Codec<IndexDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (typeof value === 'number' && Number.isInteger(value) && value >= 0 ? (value + 1).toString() : null),
+    decode: (value) => {
+      if (value === null) return null
+      const num = Number(value)
+      return Number.isInteger(num) && num >= 1 ? num - 1 : null
+    }
+  }
+}
+
+/** Boolean accepting common truthy/falsy strings (`1`, `true`, `yes`, `on`, etc). Encodes as `"1"` / `"0"`. */
+function boolean(def: Omit<BooleanDef, '~type'>): Codec<BooleanDef> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => (value == null ? null : value ? '1' : '0'),
+    decode: (value) => {
+      if (value === null) return null
+      const v = value.trim().toLowerCase()
+      if (v === '1' || v === 'true' || v === 't' || v === 'yes' || v === 'y' || v === 'on') return true
+      if (v === '0' || v === 'false' || v === 'f' || v === 'no' || v === 'n' || v === 'off') return false
+      return null
+    }
+  }
+}
+
+/** Constrained to one of the provided `values`. Anything else decodes to `null`. */
+function enumCodec<T extends string>(def: Omit<EnumDef<T>, '~type'>): Codec<EnumDef<T>> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => value ?? null,
+    decode: (value) => {
+      if (value === null) return null
+      return (def.values as readonly string[]).includes(value) ? (value as T) : null
+    }
+  }
+}
+
+/**
+ * Comma-separated list constrained to the provided `values`.
+ * Decodes to `T[]` (empty array when missing). Encodes in the canonical
+ * order of `values` so the same selection always produces the same URL.
+ */
+function enumArray<T extends string>(def: Omit<EnumArrayDef<T>, '~type'>): Codec<EnumArrayDef<T>> {
+  return {
+    _def: { ...def, ['~type']: null as any },
+    encode: (value) => {
+      if (!value.length) return null
+      return value
+        .sort((v1, v2) => def.values.indexOf(v1) - def.values.indexOf(v2))
+        .map((v) => encodeURIComponent(v))
+        .join(',')
+    },
+    decode: (value) => {
+      if (value === null) return []
+      return value
+        .split(',')
+        .map((v) => decodeURIComponent(v))
+        .filter((v) => def.values.includes(v as T)) as T[]
+    }
+  }
+}
+
+// ────────────────────────────────────────────────────────────────
+// Serialize / Deserialize
+// ────────────────────────────────────────────────────────────────
+
+/** Extract the serializable def from a codec. */
+function serializeCodec<Def extends CodecDef<any>>(codec: Codec<Def>): Def {
+  return codec._def
+}
+
+type CodecFactory = (def: any) => Codec<any>
+
+const defaultFactories: Record<string, CodecFactory> = {
+  noop,
+  string,
+  date: validated,
+  dateTime: validated,
+  duration: validated,
+  relativeDateTimeRange,
+  int,
+  float,
+  hex,
+  index,
+  boolean,
+  enum: enumCodec,
+  enumArray
+}
+
+/** Reconstruct a codec from a serialized def. */
+function deserializeCodec<Def extends CodecDef<any>>(
+  def: Def,
+  factories: Record<string, CodecFactory> = defaultFactories
+): Codec<Def> {
+  const factory = factories[def.name]
+  if (!factory) throw new Error(`Unknown codec: ${def.name}`)
+  return factory(def) as Codec<Def>
+}
+
+type SerializedCodec<C extends Codec<CodecDef<any>>> = C['_def']
+
+type SerializedLoader<L extends QueryStateLoader> = { [K in keyof L]: SerializedCodec<L[K]> }
+
+/** Serialize a loader into a plain object of defs, keyed by param name. */
+function serializeLoader<L extends QueryStateLoader>(loader: L): SerializedLoader<L> {
+  return Object.fromEntries(
+    Object.entries(loader).map(([name, codec]) => [name, serializeCodec(codec)])
+  ) as SerializedLoader<L>
+}
+
+/** Reconstruct a loader from a serialized object of defs. */
+function deserializeLoader<L extends QueryStateLoader>(
+  defs: SerializedLoader<L>,
+  factories: Record<string, CodecFactory> = defaultFactories
+): L {
+  return Object.fromEntries(
+    Object.entries(defs).map(([name, def]) => [name, deserializeCodec(def as CodecDef<any>, factories)])
+  ) as L
+}
+
+// ────────────────────────────────────────────────────────────────
+// Built-in codecs
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Library of built-in codecs for common URL search-param types.
+ *
+ * Each codec converts between a URL string and a typed value, returning `null`
+ * for missing or invalid params. Chain `.default(v)` to substitute a
+ * fallback, or `.clearOnDefault(true)` to remove the param when it matches the default.
+ */
+const codecs = {
+  /** Pass-through — no transformation, value is `string | null`. */
+  noop: () => makeConfigurator(noop({ name: 'noop' })),
+
+  /** String codec — pass-through defaulting to `''` (never null). */
+  string: () => makeConfigurator(string({ name: 'string' })).default(''),
+
+  /** ISO date (`YYYY-MM-DD`). Invalid strings decode to `null`. */
+  date: () => makeConfigurator(validated({ name: 'date', isValid: dateFns.isValid })),
+
+  /** ISO date-time (`YYYY-MM-DDTHH:mm:ss`). Invalid strings decode to `null`. */
+  dateTime: () => makeConfigurator(validated({ name: 'dateTime', isValid: dateTimeFns.isValid })),
+
+  /** ISO duration (`P1DT2H`, etc). Invalid strings decode to `null`. */
+  duration: () => makeConfigurator(validated({ name: 'duration', isValid: durationFns.isValid })),
+
+  /**
+   * Either an ISO duration (relative range) or a `start~end` pair of ISO
+   * date-times (absolute range). Useful for "last 7 days" vs a custom window.
+   */
+  relativeDateTimeRange: () => makeConfigurator(relativeDateTimeRange({ name: 'relativeDateTimeRange' })),
+
+  /** Integer (base-10). Non-integer or missing values decode to `null`. */
+  int: () => makeConfigurator(int({ name: 'int' })),
+
+  /** Finite floating-point number. `NaN` / `Infinity` decode to `null`. */
+  float: () => makeConfigurator(float({ name: 'float' })),
+
+  /** Hexadecimal integer (with or without `0x` prefix). Stored without prefix. */
+  hex: () => makeConfigurator(hex({ name: 'hex' })),
+
+  /**
+   * Zero-based index stored as a **1-based** number in the URL.
+   * `?page=1` decodes to `0`, `0` encodes to `"1"`.
+   */
+  index: () => makeConfigurator(index({ name: 'index' })),
+
+  /** Boolean accepting common truthy/falsy strings (`1`, `true`, `yes`, `on`, etc). Encodes as `"1"` / `"0"`. */
+  boolean: () => makeConfigurator(boolean({ name: 'boolean' })),
+
+  /** Constrained to one of the provided `values`. Anything else decodes to `null`. */
+  enum: <T extends string>(values: readonly T[]) => makeConfigurator(enumCodec({ name: 'enum', values })),
+
+  /**
+   * Comma-separated list constrained to the provided `values`.
+   * Decodes to `T[]` (empty array when missing). Encodes in the canonical
+   * order of `values` so the same selection always produces the same URL.
+   */
+  enumArray: <T extends string>(values: readonly T[]) => makeConfigurator(enumArray({ name: 'enumArray', values }))
+}
+
+// ────────────────────────────────────────────────────────────────
+// Loader types
+// ────────────────────────────────────────────────────────────────
+
+/** A map of param names to codecs, defining the shape of search-param state. */
+type QueryStateLoader<T extends { [key: string]: any } = { [key: string]: any }> = {
+  [key in keyof T]: Codec<CodecDef<T[key]>>
+}
+
+type ExtractTypeFromLoader<L extends QueryStateLoader> = {
+  [key in keyof L]: L[key] extends Codec<infer S> ? S['~type'] : never
+}
+
+// ────────────────────────────────────────────────────────────────
+// Internal helpers
+// ────────────────────────────────────────────────────────────────
+
+function getQueryParam<T>(naturalValue: string | null, codec: Codec<CodecDef<T>>): T {
+  try {
+    const decoded = codec.decode(naturalValue)
+    return (decoded ?? codec?._def?.defaultValue ?? null) as T
+  } catch {
+    return (codec?._def?.defaultValue ?? null) as T
+  }
+}
+
+function setQueryParam<V>({
+  searchParams,
+  name,
+  value,
+  codec
+}: {
+  searchParams: URLSearchParams
+  name: string
+  value: V
+  codec: Codec<CodecDef<V>>
+}): void {
+  const encoded = codec.encode(value)
+  if (
+    encoded === null ||
+    (codec._def?.defaultValue != null && codec._def?.clearOnDefault && encoded === codec.encode(codec._def?.defaultValue))
+  ) {
+    searchParams.delete(name)
+  } else {
+    searchParams.set(name, encoded)
+  }
+}
+
+function queryParamsToObject<L extends QueryStateLoader>(params: URLSearchParams, loader: L) {
+  return Object.fromEntries(
+    Object.entries(loader).map(([name, codec]) => [name, getQueryParam(params.get(name), codec)])
+  ) as ExtractTypeFromLoader<L>
+}
+
+// ────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Decode search params from various sources (URL string, `Request`, `URLSearchParams`, or
+ * an object with a `.search` property) using a loader. Useful in loaders/actions on the server side.
+ */
+function getSearchParamsState<L extends QueryStateLoader>(
+  searchParams: URLSearchParams | string | Request | { search: string },
+  loader: L
+) {
+  if (typeof searchParams === 'string') {
+    return queryParamsToObject(new URL(searchParams).searchParams, loader)
+  } else if ('url' in searchParams) {
+    return queryParamsToObject(new URL(searchParams.url).searchParams, loader)
+  } else if ('search' in searchParams) {
+    return queryParamsToObject(new URLSearchParams(searchParams.search), loader)
+  } else {
+    return queryParamsToObject(searchParams, loader)
+  }
+}
+
+/**
+ * React hook that binds a single search param to component state via a codec.
+ * Returns `[value, setValue]` like `React.useState`. The setter accepts a value
+ * or updater function and optional {@link QueryStateNavigateOptions}.
+ *
+ * Reads from the pending navigation location when one is in flight so the UI
+ * reflects optimistic state during transitions.
+ */
+function useState<S>(name: string, codec: Codec<CodecDef<S>>): [S, (val: S | ((prevState: S) => S), navigateOpts?: QueryStateNavigateOptions) => void] {
+  const [searchParamsRaw, setSearchParams] = useSearchParamsRR()
+  const navigation = useNavigation()
+
+  const naturalValue = React.useMemo(
+    () => (navigation.location?.search ? new URLSearchParams(navigation.location.search) : searchParamsRaw).get(name),
+    [name, searchParamsRaw, navigation.location]
+  )
+  const value = React.useMemo(
+    () => getQueryParam<S>(naturalValue, codec),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [naturalValue]
+  )
+
+  const setValue = React.useCallback(
+    (val: S | ((prevState: S) => S), navigateOpts?: QueryStateNavigateOptions) => {
+      const { replace = true, preventScrollReset = false, shallow = false } = { ...codec, ...navigateOpts }
+
+      function updateParams(params: URLSearchParams) {
+        const newParams = new URLSearchParams(params)
+        const oldValue = getQueryParam(newParams.get(name), codec)
+        const newValue = typeof val === 'function' ? (val as (prevState: S) => S)(oldValue) : val
+        setQueryParam({ searchParams: newParams, name, value: newValue, codec })
+        return newParams
+      }
+      if (shallow) {
+        const params = new URLSearchParams(window.location.search)
+        const newUrl = [
+          [window.location.pathname, updateParams(params).toString()].filter(Boolean).join('?'),
+          window.location.hash
+        ].join('#')
+        if (replace) {
+          window.history.replaceState(null, '', newUrl)
+        } else {
+          window.history.pushState(null, '', newUrl)
+        }
+      } else {
+        setSearchParams(updateParams, { replace, preventScrollReset })
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [name, setSearchParams]
+  )
+
+  return [value, setValue] as const
+}
+
+/**
+ * React hook that decodes *all* search params defined by a loader into a typed object.
+ * Read-only — for read/write access to individual params, use {@link useState}.
+ *
+ * Reads from the pending navigation location when one is in flight.
+ */
+function useSearchParams<L extends QueryStateLoader>(
+  loader: L
+): [
+  state: ExtractTypeFromLoader<L>,
+  setState: (
+    val: ExtractTypeFromLoader<L> | ((prevState: ExtractTypeFromLoader<L>) => ExtractTypeFromLoader<L>),
+    navigateOpts?: QueryStateNavigateOptions
+  ) => void
+] {
+  const location = useLocation()
+  const { location: pendingLocation } = useNavigation()
+
+  const search = pendingLocation?.search ?? location.search
+
+  const getLoader = useStableAccessor(loader)
+  const [_, setSearchParamsRaw] = useSearchParamsRR()
+
+  const setSearchParam = React.useCallback(
+    (
+      val: ExtractTypeFromLoader<L> | ((prevState: ExtractTypeFromLoader<L>) => ExtractTypeFromLoader<L>),
+      navigateOpts?: QueryStateNavigateOptions
+    ) => {
+      const loader = getLoader()
+      const { replace = true, preventScrollReset = false, shallow = false } = { ...navigateOpts }
+
+      function updateParams(params: URLSearchParams) {
+        const newParams = new URLSearchParams(params)
+        const oldValue = queryParamsToObject(new URLSearchParams(search), loader)
+        const newValue = typeof val === 'function' ? val(oldValue) : val
+        Object.entries(loader).forEach(([name, codec]) =>
+          setQueryParam({ searchParams: newParams, name, value: newValue[name], codec })
+        )
+        return newParams
+      }
+      if (shallow) {
+        const params = new URLSearchParams(window.location.search)
+        const newUrl = [
+          [window.location.pathname, updateParams(params).toString()].filter(Boolean).join('?'),
+          window.location.hash
+        ].join('#')
+        if (replace) {
+          window.history.replaceState(null, '', newUrl)
+        } else {
+          window.history.pushState(null, '', newUrl)
+        }
+      } else {
+        setSearchParamsRaw(updateParams, { replace, preventScrollReset })
+      }
+    },
+    [getLoader, setSearchParamsRaw]
+  )
+
+  const searchParams = React.useMemo(() => queryParamsToObject(new URLSearchParams(search), loader), [search, loader])
+
+  return [searchParams, setSearchParam]
+}
+
+/**
+ * Identity function that provides type inference for a loader definition.
+ *
+ * @example
+ * ```ts
+ * const loader = SearchParams.createLoader({
+ *   page: SearchParams.codecs.int.withDefaultValue(0),
+ *   sort: SearchParams.codecs.enum(['name', 'date'] as const)
+ * })
+ * ```
+ */
+function createLoader<L extends QueryStateLoader>(loader: L): L {
+  return loader
+}
+
+export const SearchParams = {
+  codecs,
+  serializeCodec,
+  deserializeCodec,
+  serializeLoader,
+  deserializeLoader,
+  createLoader,
+  getSearchParamsState,
+  useState,
+  useSearchParams
+}
+
+export declare namespace SearchParams {
+  export {
+    Codec,
+    CodecDef,
+    QueryStateLoader,
+    ExtractTypeFromLoader,
+    QueryStateNavigateOptions,
+    SerializedCodec,
+    SerializedLoader
+  }
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/utils/use-render-props.ts

@@ -0,0 +1,42 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-render-props --directory app
+
+import React from 'react'
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+type DefaultRenderPropKeys<Props> = Extract<'children' | 'className' | 'style', keyof Props>
+
+type MaybeRenderProp<Value, RenderProps> = Value | ((renderProps: RenderProps) => Value)
+
+export type WithRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+> = Prettify<{
+  [K in keyof Props]: K extends Keys ? MaybeRenderProp<Props[K], RenderProps> : Props[K]
+}>
+
+export function useRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+>(props: Props, renderProps: RenderProps, keys: Keys[]) {
+  const withRenderProps = React.useMemo(
+    () =>
+      Object.fromEntries(
+        keys
+          .map((key) => {
+            if (key in props && typeof props[key] === 'function') {
+              return [key, props[key](renderProps)]
+            } else {
+              return []
+            }
+          })
+          .filter((k) => k.length)
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...keys, renderProps, props, ...keys.map((key) => props[key])]
+  )
+  return { ...props, ...withRenderProps }
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/utils/use-spin-delay.ts

@@ -0,0 +1,27 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-spin-delay --directory app
+
+import React from 'react'
+
+export function useSpinDelay(loading: boolean, { delay = 500, minDuration = 200 } = {}) {
+  const [show, setShow] = React.useState(false)
+  const delayTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+  const minTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  React.useEffect(() => {
+    if (loading) {
+      delayTimer.current = setTimeout(() => setShow(true), delay)
+    } else {
+      clearTimeout(delayTimer.current)
+      if (show) {
+        minTimer.current = setTimeout(() => setShow(false), minDuration)
+      }
+    }
+    return () => {
+      clearTimeout(delayTimer.current)
+      clearTimeout(minTimer.current)
+    }
+  }, [loading, delay, minDuration, show])
+
+  return show
+}