@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/async-resource.ts

@@ -0,0 +1,190 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Lifecycle state of an asynchronous resource. */
+export type AsyncResourceStatus = "idle" | "pending" | "success" | "error" | "cancelled";
+
+/** Context supplied to an asynchronous resource loader. */
+export interface AsyncResourceContext {
+  /** Signal aborted by cancellation, reset, scope disposal, or a newer execution. */
+  readonly signal: AbortSignal;
+}
+
+/** Explicit result of one asynchronous resource execution. */
+export type AsyncResourceExecution<Data, Failure> =
+  | { readonly status: "success"; readonly data: Data }
+  | { readonly status: "error"; readonly error: Failure }
+  | { readonly status: "cancelled"; readonly reason: unknown }
+  | { readonly status: "superseded" };
+
+/** Options for {@link useAsyncResource}. */
+export interface UseAsyncResourceOptions<Data> {
+  /**
+   * Initial data restored by {@link AsyncResource.reset}.
+   *
+   * @default undefined
+   */
+  readonly initialData?: Data;
+
+  /**
+   * Abort the active execution when a newer execution starts.
+   *
+   * @default true
+   */
+  readonly cancelPrevious?: boolean;
+
+  /**
+   * Retain the current data while a new execution is pending.
+   *
+   * @default true
+   */
+  readonly keepData?: boolean;
+
+  /**
+   * Cancel an active execution when the current reactive scope is disposed.
+   *
+   * @default true
+   */
+  readonly scope?: boolean;
+}
+
+/** Reactive state and controls for an asynchronous loader. */
+export interface AsyncResource<Data, Arguments extends readonly unknown[], Failure> {
+  /** Data of the newest successful execution, retained according to `keepData`. */
+  readonly data: Readonly<ShallowRef<Data | undefined>>;
+
+  /** Failure of the newest settled execution, cleared when a new one starts. */
+  readonly error: Readonly<ShallowRef<Failure | undefined>>;
+
+  /** Current lifecycle status, driven only by the newest execution. */
+  readonly status: Readonly<Ref<AsyncResourceStatus>>;
+
+  /** Whether an execution is currently pending. */
+  readonly pending: ComputedRef<boolean>;
+
+  /**
+   * Run the loader. The returned promise never rejects: loader failures,
+   * cancellation, and supersession are reported as the discriminated result,
+   * and stale executions leave the reactive state untouched.
+   */
+  readonly execute: (...arguments_: Arguments) => Promise<AsyncResourceExecution<Data, Failure>>;
+
+  /**
+   * Abort the active execution and mark the resource cancelled.
+   *
+   * @param reason Abort reason forwarded to the loader's signal.
+   * @default reason DOMException("AbortError")
+   * @returns Whether an active execution was cancelled.
+   */
+  readonly cancel: (reason?: unknown) => boolean;
+
+  /** Cancel any active execution and restore the initial idle state. */
+  readonly reset: () => void;
+}
+
+interface ActiveExecution {
+  readonly generation: number;
+  readonly controller: AbortController;
+  superseded: boolean;
+}
+
+/**
+ * Create a scoped, abortable asynchronous resource with latest-result-wins
+ * state. Every execution returns a discriminated result, so cancellation,
+ * supersession, loader failure, and successful `undefined` data stay distinct.
+ *
+ * When created inside an active reactive scope (and `scope` is enabled), the
+ * active execution is aborted when that scope stops; outside a scope,
+ * cancellation ownership stays with the caller. The execute promise never
+ * rejects — synchronous and asynchronous loader failures both settle into
+ * the `"error"` result. Safe during server rendering: no browser globals are
+ * read and abort reasons use the runtime-native `DOMException`.
+ *
+ * @param loader Asynchronous loader receiving the abort context first.
+ * @param options Data retention, supersession, and scope behavior.
+ * @default options {}
+ * @returns Reactive state and controls for the loader.
+ */
+export function useAsyncResource<Data, Arguments extends readonly unknown[], Failure = unknown>(
+  loader: (context: AsyncResourceContext, ...arguments_: Arguments) => Promise<Data>,
+  options: UseAsyncResourceOptions<Data> = {},
+): AsyncResource<Data, Arguments, Failure> {
+  const data = shallowRef<Data | undefined>(options.initialData);
+  const error = shallowRef<Failure | undefined>(undefined);
+  const status = shallowRef<AsyncResourceStatus>("idle");
+  const pending = computed(() => status.value === "pending");
+  let generation = 0;
+  let active: ActiveExecution | undefined;
+
+  const cancel = (reason: unknown = createAbortReason("The execution was cancelled.")) => {
+    if (active === undefined) return false;
+    generation += 1;
+    active.controller.abort(reason);
+    active = undefined;
+    status.value = "cancelled";
+    return true;
+  };
+
+  const execute = async (
+    ...arguments_: Arguments
+  ): Promise<AsyncResourceExecution<Data, Failure>> => {
+    if ((options.cancelPrevious ?? true) && active !== undefined) {
+      active.superseded = true;
+      active.controller.abort(createAbortReason("A newer execution started."));
+    }
+    const record: ActiveExecution = {
+      generation: ++generation,
+      controller: new AbortController(),
+      superseded: false,
+    };
+    active = record;
+    error.value = undefined;
+    status.value = "pending";
+    if (!(options.keepData ?? true)) data.value = undefined;
+
+    try {
+      const result = await loader({ signal: record.controller.signal }, ...arguments_);
+      if (record.generation !== generation) return executionAfterInvalidation(record);
+      data.value = result;
+      status.value = "success";
+      return { status: "success", data: result } as const;
+    } catch (cause) {
+      if (record.generation !== generation || record.controller.signal.aborted) {
+        return executionAfterInvalidation(record);
+      }
+      error.value = cause as Failure;
+      status.value = "error";
+      return { status: "error", error: cause as Failure } as const;
+    } finally {
+      if (active === record) active = undefined;
+    }
+  };
+
+  const reset = () => {
+    cancel(createAbortReason("The resource was reset."));
+    data.value = options.initialData;
+    error.value = undefined;
+    status.value = "idle";
+  };
+
+  if (options.scope ?? true) {
+    tryOnScopeDispose(() => cancel(createAbortReason("The reactive scope was disposed.")));
+  }
+
+  return { data, error, status, pending, execute, cancel, reset };
+}
+
+function executionAfterInvalidation<Data, Failure>(
+  execution: ActiveExecution,
+): AsyncResourceExecution<Data, Failure> {
+  if (execution.superseded || !execution.controller.signal.aborted) {
+    return { status: "superseded" };
+  }
+  return { status: "cancelled", reason: execution.controller.signal.reason };
+}
+
+function createAbortReason(message: string): DOMException {
+  return new DOMException(message, "AbortError");
+}

package/registry/files/battery.ts

@@ -0,0 +1,166 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Subset of the Battery Status API `BatteryManager`. */
+export interface BatteryManagerLike extends EventTarget {
+  /** Whether the battery is charging. */
+  readonly charging: boolean;
+  /** Seconds until fully charged (`Infinity` when discharging). */
+  readonly chargingTime: number;
+  /** Seconds until empty (`Infinity` when charging). */
+  readonly dischargingTime: number;
+  /** Charge level in `[0, 1]`. */
+  readonly level: number;
+}
+
+/** Navigator-like capability used by {@link useBattery}. */
+export interface BatteryHost {
+  /** Resolve the battery manager, where supported. */
+  readonly getBattery?: () => Promise<BatteryManagerLike>;
+}
+
+/** Options for {@link useBattery}. */
+export interface UseBatteryOptions {
+  /**
+   * Reactive navigator capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window.navigator when available
+   */
+  readonly host?: MaybeRefOrGetter<BatteryHost | null | undefined>;
+}
+
+/** Reactive battery state returned by {@link useBattery}. */
+export interface BatteryControls {
+  /** Whether the host exposes `getBattery`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the battery manager has resolved. */
+  readonly isReady: Readonly<Ref<boolean>>;
+  /** Whether the battery is charging. */
+  readonly charging: Readonly<Ref<boolean>>;
+  /** Seconds until fully charged. */
+  readonly chargingTime: Readonly<Ref<number>>;
+  /** Seconds until empty. */
+  readonly dischargingTime: Readonly<Ref<number>>;
+  /** Charge level in `[0, 1]`. */
+  readonly level: Readonly<Ref<number>>;
+  /** Rejection from `getBattery`, if any (for example a permissions policy). */
+  readonly error: Readonly<ShallowRef<unknown>>;
+}
+
+const batteryEvents = [
+  "chargingchange",
+  "chargingtimechange",
+  "dischargingtimechange",
+  "levelchange",
+] as const;
+
+/**
+ * Track the device battery with the Battery Status API.
+ *
+ * Server renders (and unsupported browsers) expose a full, charging battery
+ * (`level: 1`, `charging: true`, times `0`/`Infinity`), which is the
+ * least alarming deterministic default. Late resolutions after the host
+ * changed or the scope stopped are ignored, and listeners are removed with
+ * the owning reactive scope.
+ *
+ * @param options Navigator capability.
+ * @default options {}
+ * @returns Reactive battery state.
+ */
+export function useBattery(options: UseBatteryOptions = {}): BatteryControls {
+  const isSupported = ref(false);
+  const isReady = ref(false);
+  const charging = ref(true);
+  const chargingTime = ref(0);
+  const dischargingTime = ref(Number.POSITIVE_INFINITY);
+  const level = ref(1);
+  const error = shallowRef<unknown>(undefined);
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+
+  const stop = watch(
+    () =>
+      !mounted.value
+        ? undefined
+        : options.host === undefined
+          ? browserBatteryHost()
+          : toValue(options.host),
+    (host, _previous, onCleanup) => {
+      const getBattery = host?.getBattery;
+      isSupported.value = typeof getBattery === "function";
+      isReady.value = false;
+      if (!host || typeof getBattery !== "function") return;
+      let cancelled = false;
+      let release = (): void => undefined;
+      onCleanup(() => {
+        cancelled = true;
+        release();
+      });
+      getBattery.call(host).then(
+        (battery) => {
+          if (cancelled) return;
+          const update = (): void => {
+            charging.value = battery.charging;
+            chargingTime.value = battery.chargingTime;
+            dischargingTime.value = battery.dischargingTime;
+            level.value = battery.level;
+          };
+          update();
+          isReady.value = true;
+          for (const type of batteryEvents) battery.addEventListener(type, update);
+          release = () => {
+            for (const type of batteryEvents) battery.removeEventListener(type, update);
+          };
+        },
+        (cause: unknown) => {
+          if (!cancelled) error.value = cause;
+        },
+      );
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    isSupported: readonly(isSupported),
+    isReady: readonly(isReady),
+    charging: readonly(charging),
+    chargingTime: readonly(chargingTime),
+    dischargingTime: readonly(dischargingTime),
+    level: readonly(level),
+    error,
+  };
+}
+
+function browserBatteryHost(): BatteryHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const navigator: object = window.navigator;
+  if (!("getBattery" in navigator) || typeof navigator.getBattery !== "function") return {};
+  const request = navigator.getBattery;
+  return {
+    getBattery: async () => {
+      const battery: unknown = await Reflect.apply(request, navigator, []);
+      if (isBatteryManager(battery)) return battery;
+      throw new TypeError("navigator.getBattery() resolved to an unexpected value.");
+    },
+  };
+}
+
+function isBatteryManager(value: unknown): value is BatteryManagerLike {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "level" in value &&
+    "charging" in value &&
+    "addEventListener" in value
+  );
+}

package/registry/files/breakpoints.ts

@@ -0,0 +1,166 @@
+import { computed } from "vue";
+import type { ComputedRef, Ref } from "vue";
+
+import { useMediaQuery } from "./media-query.ts";
+import type { UseMediaQueryOptions } from "./media-query.ts";
+
+/** Breakpoint width: pixels as a number, or a CSS length in `px`, `rem`, or `em`. */
+export type BreakpointValue = number | `${number}px` | `${number}rem` | `${number}em`;
+
+/** Named breakpoint map. */
+export type Breakpoints<Name extends string = string> = Readonly<Record<Name, BreakpointValue>>;
+
+/** Tailwind CSS default breakpoints. */
+export const breakpointsTailwind = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+} as const satisfies Breakpoints;
+
+/** Bootstrap 5 default breakpoints. */
+export const breakpointsBootstrapV5 = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+  xxl: 1400,
+} as const satisfies Breakpoints;
+
+/** Names reserved for the helper methods returned by {@link useBreakpoints}. */
+export type ReservedBreakpointName =
+  | "greaterOrEqual"
+  | "greater"
+  | "smaller"
+  | "smallerOrEqual"
+  | "between"
+  | "current"
+  | "active";
+
+/** Options for {@link useBreakpoints}. */
+export interface UseBreakpointsOptions extends Omit<UseMediaQueryOptions, "ssrValue"> {
+  /**
+   * Viewport width assumed during server rendering (and whenever no media
+   * capability exists). Queries are evaluated against it arithmetically, so
+   * the server output matches a client of that width.
+   *
+   * @default undefined (every query is `false` on the server)
+   */
+  readonly ssrWidth?: number;
+
+  /**
+   * Root font size used to convert `rem`/`em` values for `ssrWidth`.
+   *
+   * @default 16
+   */
+  readonly rootFontSize?: number;
+}
+
+/** Reactive breakpoint helpers returned by {@link useBreakpoints}. */
+export type BreakpointsControls<Name extends string> = {
+  /** `true` when the viewport is at least this breakpoint (mobile-first). */
+  readonly [Key in Name]: Readonly<Ref<boolean>>;
+} & {
+  /** Viewport width ≥ breakpoint. */
+  readonly greaterOrEqual: (name: Name) => Readonly<Ref<boolean>>;
+  /** Viewport width > breakpoint. */
+  readonly greater: (name: Name) => Readonly<Ref<boolean>>;
+  /** Viewport width < breakpoint. */
+  readonly smaller: (name: Name) => Readonly<Ref<boolean>>;
+  /** Viewport width ≤ breakpoint. */
+  readonly smallerOrEqual: (name: Name) => Readonly<Ref<boolean>>;
+  /** `lower` ≤ width < `upper`. */
+  readonly between: (lower: Name, upper: Name) => ComputedRef<boolean>;
+  /** Every breakpoint currently matched (mobile-first), in ascending order. */
+  readonly current: ComputedRef<readonly Name[]>;
+  /** Largest matched breakpoint, or `null` below the smallest one. */
+  readonly active: ComputedRef<Name | null>;
+};
+
+/**
+ * Reactive, typed breakpoint helpers built on media queries.
+ *
+ * Breakpoint names are inferred from the map, so typos are compile errors.
+ * `greater` and `smaller` use fractional offsets (`width > 767.98px`) so
+ * adjacent breakpoints never overlap. With `ssrWidth`, the server evaluates
+ * each query arithmetically for deterministic, hydration-stable output.
+ * Subscriptions are released with the owning reactive scope.
+ *
+ * @param breakpoints Named breakpoint map, e.g. {@link breakpointsTailwind}.
+ * @param options SSR width, font size, and media capability.
+ * @default options {}
+ * @returns Per-breakpoint refs plus comparison helpers.
+ */
+export function useBreakpoints<const Name extends string>(
+  breakpoints: Breakpoints<Name> & { readonly [Reserved in ReservedBreakpointName]?: never },
+  options: UseBreakpointsOptions = {},
+): BreakpointsControls<Name> {
+  const rootFontSize = options.rootFontSize ?? 16;
+  const isName = (key: string): key is Name => Object.hasOwn(breakpoints, key);
+  const names = Object.keys(breakpoints).filter(isName);
+  names.sort(
+    (left, right) =>
+      toPixels(breakpoints[left], rootFontSize) - toPixels(breakpoints[right], rootFontSize),
+  );
+  const cache = new Map<string, Readonly<Ref<boolean>>>();
+
+  const query = (feature: "min-width" | "max-width", pixels: number): Readonly<Ref<boolean>> => {
+    const text = `(${feature}: ${pixels}px)`;
+    const cached = cache.get(text);
+    if (cached) return cached;
+    const ssrWidth = options.ssrWidth;
+    const ssrValue =
+      ssrWidth === undefined
+        ? false
+        : feature === "min-width"
+          ? ssrWidth >= pixels
+          : ssrWidth <= pixels;
+    const matches = useMediaQuery(
+      text,
+      options.host === undefined ? { ssrValue } : { ssrValue, host: options.host },
+    );
+    cache.set(text, matches);
+    return matches;
+  };
+  const px = (name: Name): number => toPixels(breakpoints[name], rootFontSize);
+  const greaterOrEqual = (name: Name): Readonly<Ref<boolean>> => query("min-width", px(name));
+  const greater = (name: Name): Readonly<Ref<boolean>> => query("min-width", px(name) + 0.02);
+  const smaller = (name: Name): Readonly<Ref<boolean>> => query("max-width", px(name) - 0.02);
+  const smallerOrEqual = (name: Name): Readonly<Ref<boolean>> => query("max-width", px(name));
+
+  // Every key is assigned by the loop below before the record is read.
+  const perName = {} as Record<Name, Readonly<Ref<boolean>>>;
+  for (const name of names) perName[name] = greaterOrEqual(name);
+  const current = computed<readonly Name[]>(() => names.filter((name) => perName[name].value));
+
+  return {
+    ...perName,
+    greaterOrEqual,
+    greater,
+    smaller,
+    smallerOrEqual,
+    between: (lower, upper) => {
+      const above = greaterOrEqual(lower);
+      const below = smaller(upper);
+      return computed(() => above.value && below.value);
+    },
+    current,
+    active: computed(() => current.value.at(-1) ?? null),
+  };
+}
+
+/**
+ * Convert a {@link BreakpointValue} to CSS pixels.
+ *
+ * @param value Number of pixels or a `px`/`rem`/`em` length.
+ * @param rootFontSize Pixels per `rem`/`em`.
+ * @default rootFontSize 16
+ * @returns Width in CSS pixels.
+ */
+export function toPixels(value: BreakpointValue, rootFontSize = 16): number {
+  if (typeof value === "number") return value;
+  const amount = Number.parseFloat(value);
+  return value.endsWith("px") ? amount : amount * rootFontSize;
+}

package/registry/files/capability.ts

@@ -0,0 +1,171 @@
+/** Runtime families understood by composable capability metadata and adapters. */
+export type CapabilityTarget = "web" | "server" | "worker" | "native" | "desktop" | "terminal";
+
+/** Built-in origins from which a capability value can be resolved. */
+export type CapabilitySource = "runtime" | "adapter" | "fallback";
+
+/**
+ * Standard reasons why a capability cannot currently provide a value.
+ *
+ * Adapters may extend this vocabulary with a narrower string-literal union;
+ * consumers should preserve unknown extension reasons when crossing process
+ * or version boundaries.
+ */
+export type CapabilityUnavailableReason =
+  | "unsupported"
+  | "unavailable"
+  | "permission-denied"
+  | "insecure-context"
+  | "not-active"
+  | "not-ready"
+  | "cancelled"
+  | "adapter-missing"
+  | "adapter-error";
+
+/** A capability value that is ready for use. */
+export interface AvailableCapability<Value, Source extends string = CapabilitySource> {
+  /** Stable discriminant for serialization and exhaustive matching. */
+  readonly status: "available";
+
+  /** Boolean discriminant for ergonomic guards in templates and JavaScript. */
+  readonly available: true;
+
+  /** Resolved capability implementation or value. */
+  readonly value: Value;
+
+  /** Origin that supplied the value, preserved as a string literal. */
+  readonly source: Source;
+}
+
+/** A capability that cannot currently provide a value. */
+export interface UnavailableCapability<
+  Reason extends string = CapabilityUnavailableReason,
+  Details = undefined,
+> {
+  /** Stable discriminant for serialization and exhaustive matching. */
+  readonly status: "unavailable";
+
+  /** Boolean discriminant for ergonomic guards in templates and JavaScript. */
+  readonly available: false;
+
+  /** Typed, machine-readable explanation of the unavailable state. */
+  readonly reason: Reason;
+
+  /** Structured diagnostic or recovery information supplied by the adapter. */
+  readonly details: Details;
+}
+
+/** Explicit result of capability discovery or adapter negotiation. */
+export type CapabilityResult<
+  Value,
+  Reason extends string = CapabilityUnavailableReason,
+  Details = undefined,
+  Source extends string = CapabilitySource,
+> = AvailableCapability<Value, Source> | UnavailableCapability<Reason, Details>;
+
+/**
+ * Create an available capability supplied directly by the current runtime.
+ *
+ * The value and source retain literal types. The helper performs no global
+ * access and is safe during server rendering and module evaluation.
+ *
+ * @param value Resolved capability implementation or value.
+ * @returns An available result whose source is `"runtime"`.
+ */
+export function availableCapability<const Value>(
+  value: Value,
+): AvailableCapability<Value, "runtime">;
+
+/**
+ * Create an available capability with an explicit, literal-preserving source.
+ *
+ * @param value Resolved capability implementation or value.
+ * @param source Runtime, adapter, fallback, or adapter-specific source name.
+ * @returns An available capability result.
+ */
+export function availableCapability<const Value, const Source extends string>(
+  value: Value,
+  source: Source,
+): AvailableCapability<Value, Source>;
+
+export function availableCapability<const Value, const Source extends string>(
+  value: Value,
+  source?: Source,
+): AvailableCapability<Value, Source | "runtime"> {
+  return {
+    status: "available",
+    available: true,
+    value,
+    source: source ?? "runtime",
+  };
+}
+
+/**
+ * Create an unavailable capability without additional details.
+ *
+ * The reason retains its string-literal type. Capability absence is returned
+ * as data rather than thrown, making unsupported server, worker, native,
+ * desktop, and terminal environments deterministic.
+ *
+ * @param reason Machine-readable unavailability reason.
+ * @returns An unavailable result with `undefined` details.
+ */
+export function unavailableCapability<const Reason extends string>(
+  reason: Reason,
+): UnavailableCapability<Reason, undefined>;
+
+/**
+ * Create an unavailable capability with typed recovery or diagnostic details.
+ *
+ * Passing `undefined` explicitly is distinct at the call boundary and still
+ * preserves the exact `undefined` details type.
+ *
+ * @param reason Machine-readable unavailability reason.
+ * @param details Structured diagnostic or recovery information.
+ * @returns An unavailable capability result.
+ */
+export function unavailableCapability<const Reason extends string, const Details>(
+  reason: Reason,
+  details: Details,
+): UnavailableCapability<Reason, Details>;
+
+export function unavailableCapability<const Reason extends string, const Details>(
+  reason: Reason,
+  details?: Details,
+): UnavailableCapability<Reason, Details | undefined> {
+  return {
+    status: "unavailable",
+    available: false,
+    reason,
+    details,
+  };
+}
+
+/**
+ * Narrow a capability result to its available branch.
+ *
+ * @param result Capability discovery or negotiation result.
+ * @returns Whether `result.value` is ready for use.
+ */
+export function isCapabilityAvailable<Value, Reason extends string, Details, Source extends string>(
+  result: CapabilityResult<Value, Reason, Details, Source>,
+): result is AvailableCapability<Value, Source> {
+  return result.available;
+}
+
+/**
+ * Narrow a capability result to its unavailable branch.
+ *
+ * @param result Capability discovery or negotiation result.
+ * @returns Whether the capability has a typed unavailability reason.
+ */
+export function isCapabilityUnavailable<
+  Value,
+  Reason extends string,
+  Details,
+  Source extends string,
+>(
+  result: CapabilityResult<Value, Reason, Details, Source>,
+): result is UnavailableCapability<Reason, Details> {
+  return !result.available;
+}