@seamapi/react 5.0.0 → 5.1.1

package/src/lib/seam/components/SupportedDevices/SupportedDevices.tsx

@@ -0,0 +1,382 @@
+import classNames from 'classnames'
+import { useDeferredValue, useMemo, useState } from 'react'
+
+import {
+  applyEmbedExclusions,
+  capabilityLabels,
+  filterDeviceModels,
+  getCapabilityOptions,
+  getDeviceTypeOptions,
+  getManufacturerName,
+  getManufacturerOptions,
+  groupDeviceModelsByManufacturer,
+} from 'lib/seam/components/SupportedDevices/device-models.js'
+import { FilterSelect } from 'lib/seam/components/SupportedDevices/FilterSelect.js'
+import { ManufacturerSection } from 'lib/seam/components/SupportedDevices/ManufacturerSection.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type { Manufacturer } from 'lib/seam/ecosystem/types.js'
+import { useEcosystemDeviceModelSummaries } from 'lib/seam/ecosystem/use-ecosystem-device-model-summaries.js'
+import { useEcosystemManufacturers } from 'lib/seam/ecosystem/use-ecosystem-manufacturers.js'
+import {
+  getEmbedKeyManufacturer,
+  useEmbedKeyResolution,
+} from 'lib/seam/ecosystem/use-embed-key-resolution.js'
+import { getEcosystemErrorMessage } from 'lib/ui/ecosystem/errors.js'
+import { SearchField } from 'lib/ui/ecosystem/SearchField.js'
+import { StateMessage } from 'lib/ui/ecosystem/StateMessage.js'
+import {
+  type EcosystemTheme,
+  getEcosystemThemeClassName,
+} from 'lib/ui/ecosystem/theme.js'
+
+export interface SupportedDevicesProps {
+  /**
+   * DeviceDB manufacturer slug, e.g., `schlage`.
+   * Defaults to the manufacturer of a manufacturer embed key.
+   */
+  manufacturer?: string | undefined
+  /** DeviceDB device type slug, e.g., `smartlock` or `thermostat`. */
+  deviceType?: string | undefined
+  /** Only devices supporting this capability, e.g., `can_program_online_access_codes`. */
+  capability?: string | undefined
+  hideSearch?: boolean | undefined
+  hideFilters?: boolean | undefined
+  hideTitle?: boolean | undefined
+  /** Color theme. `auto` follows the visitor's color scheme. */
+  theme?: EcosystemTheme | undefined
+  className?: string | undefined
+}
+
+/**
+ * Device models that work with Seam, grouped by manufacturer,
+ * with device type and capability badges.
+ */
+export function SupportedDevices({
+  manufacturer,
+  deviceType,
+  capability,
+  hideSearch = false,
+  hideFilters = false,
+  hideTitle = false,
+  theme = 'light',
+  className,
+}: SupportedDevicesProps): JSX.Element {
+  const { embedKey } = useEcosystemContext()
+  const explicitManufacturer = normalizeSlug(manufacturer)
+  const fixedDeviceType = normalizeSlug(deviceType)
+  const fixedCapability = normalizeSlug(capability)
+
+  const {
+    embedResolution,
+    isError: isResolutionError,
+    error: resolutionError,
+    refetch: refetchResolution,
+  } = useEmbedKeyResolution({ capability: fixedCapability ?? '' })
+
+  const isResolved = embedKey == null || embedResolution != null
+  const scopeManufacturer =
+    explicitManufacturer ?? getEmbedKeyManufacturer(embedResolution)
+
+  const {
+    deviceModels,
+    isError: isDeviceModelsError,
+    error: deviceModelsError,
+    refetch: refetchDeviceModels,
+  } = useEcosystemDeviceModelSummaries({
+    manufacturer: scopeManufacturer ?? '',
+    deviceType: fixedDeviceType ?? '',
+    capability:
+      fixedCapability != null && fixedCapability in capabilityLabels
+        ? fixedCapability
+        : '',
+    enabled: (explicitManufacturer != null || isResolved) && !isResolutionError,
+  })
+
+  const availableDeviceModels = useMemo(
+    () => applyEmbedExclusions(deviceModels ?? [], embedResolution?.exclusions),
+    [deviceModels, embedResolution]
+  )
+
+  const manufacturerSlugs = useMemo(
+    () =>
+      availableDeviceModels
+        .map((m) => m.manufacturer?.slug)
+        .filter((slug): slug is string => slug != null),
+    [availableDeviceModels]
+  )
+
+  const { manufacturers } = useEcosystemManufacturers({
+    slugs: manufacturerSlugs,
+    enabled: manufacturerSlugs.length > 0,
+  })
+
+  const manufacturersBySlug = useMemo(
+    () =>
+      new Map<string, Manufacturer>(
+        (manufacturers ?? []).map((m) => [m.slug, m])
+      ),
+    [manufacturers]
+  )
+
+  const [searchValue, setSearchValue] = useState('')
+  const [selectedManufacturer, setSelectedManufacturer] = useState<
+    string | null
+  >(null)
+  const [selectedDeviceType, setSelectedDeviceType] = useState<string | null>(
+    null
+  )
+  const [selectedCapability, setSelectedCapability] = useState<string | null>(
+    null
+  )
+  const search = useDeferredValue(searchValue)
+
+  const filteredDeviceModels = useMemo(
+    () =>
+      filterDeviceModels(availableDeviceModels, {
+        manufacturer: scopeManufacturer ?? selectedManufacturer,
+        deviceType: fixedDeviceType ?? selectedDeviceType,
+        capability: fixedCapability ?? selectedCapability,
+        search,
+      }),
+    [
+      availableDeviceModels,
+      scopeManufacturer,
+      selectedManufacturer,
+      fixedDeviceType,
+      selectedDeviceType,
+      fixedCapability,
+      selectedCapability,
+      search,
+    ]
+  )
+
+  const groups = useMemo(
+    () => groupDeviceModelsByManufacturer(filteredDeviceModels),
+    [filteredDeviceModels]
+  )
+
+  const manufacturerOptions = useMemo(
+    () => getManufacturerOptions(availableDeviceModels),
+    [availableDeviceModels]
+  )
+  const deviceTypeOptions = useMemo(
+    () => getDeviceTypeOptions(availableDeviceModels),
+    [availableDeviceModels]
+  )
+  const capabilityOptions = useMemo(
+    () => getCapabilityOptions(availableDeviceModels),
+    [availableDeviceModels]
+  )
+
+  const showManufacturerFilter =
+    scopeManufacturer == null && manufacturerOptions.length > 1
+  const showDeviceTypeFilter =
+    fixedDeviceType == null && deviceTypeOptions.length > 1
+  const showCapabilityFilter =
+    fixedCapability == null && capabilityOptions.length > 1
+
+  const hasUserFilters =
+    searchValue.trim().length > 0 ||
+    selectedManufacturer != null ||
+    selectedDeviceType != null ||
+    selectedCapability != null
+
+  const resetFilters = (): void => {
+    setSearchValue('')
+    setSelectedManufacturer(null)
+    setSelectedDeviceType(null)
+    setSelectedCapability(null)
+  }
+
+  const isError = isResolutionError || isDeviceModelsError
+  const isLoading = !isError && (!isResolved || deviceModels == null)
+
+  const scopedManufacturerName =
+    scopeManufacturer == null
+      ? null
+      : getScopedManufacturerName(
+          scopeManufacturer,
+          manufacturersBySlug.get(scopeManufacturer),
+          availableDeviceModels[0]?.manufacturer?.display_name
+        )
+
+  const title =
+    scopedManufacturerName == null
+      ? t.title
+      : t.manufacturerTitle(scopedManufacturerName)
+
+  const content = (() => {
+    if (isError) {
+      const { message, canRetry } = getEcosystemErrorMessage(
+        isResolutionError ? resolutionError : deviceModelsError,
+        t.error
+      )
+      return (
+        <StateMessage
+          role='alert'
+          {...(canRetry
+            ? {
+                actionLabel: t.retry,
+                onAction: () => {
+                  if (isResolutionError) void refetchResolution()
+                  if (isDeviceModelsError) void refetchDeviceModels()
+                },
+              }
+            : {})}
+        >
+          {message}
+        </StateMessage>
+      )
+    }
+
+    if (isLoading) return <LoadingRows />
+
+    if (availableDeviceModels.length === 0) {
+      return <StateMessage>{t.noDevices}</StateMessage>
+    }
+
+    if (filteredDeviceModels.length === 0) {
+      return (
+        <StateMessage
+          {...(hasUserFilters
+            ? { actionLabel: t.clearFilters, onAction: resetFilters }
+            : {})}
+        >
+          {hasUserFilters ? t.noMatches : t.noDevices}
+        </StateMessage>
+      )
+    }
+
+    return (
+      <div className='seam-supported-devices-sections'>
+        {groups.map((group) => (
+          <ManufacturerSection
+            key={group.key}
+            group={group}
+            manufacturer={manufacturersBySlug.get(group.key) ?? null}
+            collapsible={groups.length > 1}
+          />
+        ))}
+      </div>
+    )
+  })()
+
+  const showFilters =
+    !hideFilters &&
+    (showManufacturerFilter || showDeviceTypeFilter || showCapabilityFilter)
+  const controlsDisabled = isLoading || isError
+
+  return (
+    <div
+      className={classNames(
+        'seam-ecosystem',
+        'seam-supported-devices',
+        getEcosystemThemeClassName(theme),
+        className
+      )}
+    >
+      {(!hideTitle || !hideSearch || showFilters) && (
+        <div className='seam-ecosystem-header'>
+          {!hideTitle && <h2 className='seam-ecosystem-title'>{title}</h2>}
+          <div className='seam-ecosystem-controls'>
+            {showFilters && showManufacturerFilter && (
+              <FilterSelect
+                label={t.manufacturer}
+                allLabel={t.allManufacturers}
+                options={manufacturerOptions}
+                value={selectedManufacturer}
+                onChange={setSelectedManufacturer}
+                disabled={controlsDisabled}
+              />
+            )}
+            {showFilters && showDeviceTypeFilter && (
+              <FilterSelect
+                label={t.deviceType}
+                allLabel={t.allDeviceTypes}
+                options={deviceTypeOptions}
+                value={selectedDeviceType}
+                onChange={setSelectedDeviceType}
+                disabled={controlsDisabled}
+              />
+            )}
+            {showFilters && showCapabilityFilter && (
+              <FilterSelect
+                label={t.capability}
+                allLabel={t.allCapabilities}
+                options={capabilityOptions}
+                value={selectedCapability}
+                onChange={setSelectedCapability}
+                disabled={controlsDisabled}
+              />
+            )}
+            {!hideSearch && (
+              <SearchField
+                label={t.search}
+                value={searchValue}
+                onChange={setSearchValue}
+                disabled={controlsDisabled}
+              />
+            )}
+          </div>
+        </div>
+      )}
+      {content}
+    </div>
+  )
+}
+
+function LoadingRows(): JSX.Element {
+  return (
+    <div className='seam-supported-devices-sections' aria-busy='true'>
+      <section className='seam-supported-devices-section'>
+        <div className='seam-supported-devices-section-header'>
+          <div className='seam-ecosystem-skeleton seam-supported-devices-logo' />
+          <div className='seam-ecosystem-skeleton seam-ecosystem-skeleton-line-short' />
+        </div>
+        <ul className='seam-supported-devices-rows'>
+          {Array.from({ length: 3 }, (_, index) => (
+            <li key={index} className='seam-supported-devices-row'>
+              <div className='seam-ecosystem-skeleton seam-supported-devices-image' />
+              <div className='seam-supported-devices-info'>
+                <div className='seam-ecosystem-skeleton seam-ecosystem-skeleton-line' />
+                <div className='seam-ecosystem-skeleton seam-ecosystem-skeleton-line-short' />
+              </div>
+            </li>
+          ))}
+        </ul>
+      </section>
+    </div>
+  )
+}
+
+const normalizeSlug = (value: string | undefined): string | null => {
+  const slug = value?.trim()
+  if (slug == null || slug.length === 0) return null
+  return slug
+}
+
+const getScopedManufacturerName = (
+  slug: string,
+  manufacturer: Manufacturer | undefined,
+  fallback: string | null | undefined
+): string => {
+  if (manufacturer != null) return getManufacturerName(manufacturer)
+  return fallback ?? slug
+}
+
+const t = {
+  title: 'Supported devices',
+  manufacturerTitle: (name: string) => `Supported ${name} devices`,
+  search: 'Search devices',
+  manufacturer: 'Manufacturer',
+  allManufacturers: 'All manufacturers',
+  deviceType: 'Device type',
+  allDeviceTypes: 'All device types',
+  capability: 'Capability',
+  allCapabilities: 'All capabilities',
+  error: 'An error occurred while loading supported devices.',
+  retry: 'Retry',
+  noDevices: 'No supported devices found.',
+  noMatches: 'No devices match your search or filters.',
+  clearFilters: 'Clear filters',
+}

package/src/lib/seam/components/SupportedDevices/device-models.ts

@@ -0,0 +1,326 @@
+import type {
+  CapabilityName,
+  CapabilitySummary,
+  DeviceModelSummary,
+  EmbedExclusions,
+  Manufacturer,
+  ManufacturerRef,
+} from 'lib/seam/ecosystem/types.js'
+
+export interface DeviceModelFilters {
+  manufacturer?: string | null
+  deviceType?: string | null
+  capability?: string | null
+  search?: string
+}
+
+export interface SupportedCapability {
+  name: CapabilityName
+  supported: 'yes' | 'conditionally'
+  details: string | null
+}
+
+export interface ManufacturerGroup {
+  key: string
+  manufacturer: ManufacturerRef | null
+  deviceModels: DeviceModelSummary[]
+}
+
+export interface FilterOption {
+  value: string
+  label: string
+}
+
+/** Capabilities shown as badges, in display order. */
+export const capabilityLabels: Partial<Record<CapabilityName, string>> = {
+  can_remotely_unlock: 'Remote unlock',
+  can_remotely_lock: 'Remote lock',
+  can_program_online_access_codes: 'Access codes',
+  can_program_offline_access_codes: 'Offline access codes',
+  can_provision_mobile_keys: 'Mobile keys',
+  can_provision_wallet_keys: 'Wallet keys',
+  can_encode_plastic_cards: 'Key cards',
+  can_hvac_heat: 'Heat',
+  can_hvac_cool: 'Cool',
+  can_hvac_auto: 'Heat and cool',
+  can_hvac_fan: 'Fan',
+  can_program_thermostat_weekly_programs: 'Weekly programs',
+  can_monitor: 'Monitoring',
+}
+
+const capabilityOrder = Object.keys(capabilityLabels)
+
+export const getCapabilityLabel = (name: string): string =>
+  capabilityLabels[name as CapabilityName] ??
+  name.replace(/^can_/, '').replaceAll('_', ' ')
+
+/**
+ * Removes what a partner's embed key says its widgets must not show
+ * (Ecosystem `embed/resolve`): excluded manufacturers and device types,
+ * unsupported providers, and the provider combinations excluded for the
+ * resolved capability. A model left with no provider is removed.
+ */
+export const applyEmbedExclusions = (
+  deviceModels: DeviceModelSummary[],
+  exclusions: EmbedExclusions | null | undefined
+): DeviceModelSummary[] => {
+  if (exclusions == null) return deviceModels
+
+  const excludedManufacturers = new Set(exclusions.excluded_manufacturers)
+  const excludedDeviceTypes = new Set(exclusions.excluded_device_types)
+  const unsupportedProviders = new Set(exclusions.unsupported_providers)
+  const { capability } = exclusions
+
+  const result: DeviceModelSummary[] = []
+  for (const deviceModel of deviceModels) {
+    const manufacturerSlug = deviceModel.manufacturer?.slug ?? ''
+    const deviceTypeSlug = deviceModel.device_type?.slug ?? ''
+
+    if (excludedManufacturers.has(manufacturerSlug)) continue
+    if (excludedDeviceTypes.has(deviceTypeSlug)) continue
+
+    const capabilityExclusions = exclusions.capability_exclusions.filter(
+      (exclusion) =>
+        capability.length > 0 &&
+        exclusion.device_category === deviceTypeSlug &&
+        (exclusion.manufacturer_slug === '' ||
+          exclusion.manufacturer_slug === manufacturerSlug)
+    )
+
+    if (capabilityExclusions.some((e) => e.provider_slug === '')) continue
+
+    const capabilityExcludedProviders = new Set(
+      capabilityExclusions.map((e) => e.provider_slug)
+    )
+
+    const providers = deviceModel.providers.filter(
+      (provider) => !unsupportedProviders.has(provider.slug)
+    )
+
+    if (deviceModel.providers.length > 0 && providers.length === 0) continue
+
+    const capabilitiesByProvider = deviceModel.capabilities_by_provider
+      .filter(({ provider }) => !unsupportedProviders.has(provider.slug))
+      .map((entry) =>
+        capabilityExcludedProviders.has(entry.provider.slug)
+          ? {
+              ...entry,
+              capabilities: entry.capabilities.filter(
+                (c) => c.name !== capability
+              ),
+            }
+          : entry
+      )
+
+    result.push({
+      ...deviceModel,
+      providers,
+      capabilities_by_provider: capabilitiesByProvider,
+    })
+  }
+  return result
+}
+
+/** The best support for each capability across the model's providers. */
+export const getSupportedCapabilities = (
+  deviceModel: DeviceModelSummary
+): SupportedCapability[] => {
+  const best = new Map<CapabilityName, SupportedCapability>()
+  for (const { capabilities } of deviceModel.capabilities_by_provider) {
+    for (const capability of capabilities) {
+      const supported = toSupported(capability)
+      if (supported == null) continue
+      const current = best.get(capability.name)
+      if (current?.supported === 'yes') continue
+      best.set(capability.name, {
+        name: capability.name,
+        supported,
+        details: capability.report?.details ?? null,
+      })
+    }
+  }
+  return [...best.values()].sort(
+    (a, b) => capabilityRank(a.name) - capabilityRank(b.name)
+  )
+}
+
+export const supportsCapability = (
+  deviceModel: DeviceModelSummary,
+  capability: string
+): boolean =>
+  getSupportedCapabilities(deviceModel).some((c) => c.name === capability)
+
+export const filterDeviceModels = (
+  deviceModels: DeviceModelSummary[],
+  { manufacturer, deviceType, capability, search = '' }: DeviceModelFilters
+): DeviceModelSummary[] => {
+  const terms = search.toLowerCase().trim().split(/\s+/).filter(Boolean)
+  return deviceModels.filter((deviceModel) => {
+    if (manufacturer != null && deviceModel.manufacturer?.slug !== manufacturer)
+      return false
+    if (deviceType != null && deviceModel.device_type?.slug !== deviceType)
+      return false
+    if (capability != null && !supportsCapability(deviceModel, capability))
+      return false
+    if (terms.length === 0) return true
+    const haystack = getSearchText(deviceModel)
+    return terms.every((term) => haystack.includes(term))
+  })
+}
+
+const getSearchText = (deviceModel: DeviceModelSummary): string =>
+  [
+    deviceModel.display_name,
+    deviceModel.slug,
+    deviceModel.manufacturer?.display_name,
+    deviceModel.device_type?.display_name,
+    ...deviceModel.providers.map((p) => p.display_name),
+    ...deviceModel.variants.map((v) => v.manufacturer_model_id),
+  ]
+    .filter((value): value is string => value != null)
+    .join(' ')
+    .toLowerCase()
+
+export const groupDeviceModelsByManufacturer = (
+  deviceModels: DeviceModelSummary[]
+): ManufacturerGroup[] => {
+  const groups = new Map<string, ManufacturerGroup>()
+  for (const deviceModel of deviceModels) {
+    const key = deviceModel.manufacturer?.slug ?? ''
+    const group = groups.get(key) ?? {
+      key,
+      manufacturer: deviceModel.manufacturer,
+      deviceModels: [],
+    }
+    group.deviceModels.push(deviceModel)
+    groups.set(key, group)
+  }
+  for (const group of groups.values()) {
+    group.deviceModels.sort((a, b) =>
+      getDeviceModelName(a).localeCompare(getDeviceModelName(b))
+    )
+  }
+  return [...groups.values()].sort((a, b) => {
+    if (a.manufacturer == null) return 1
+    if (b.manufacturer == null) return -1
+    return getManufacturerName(a.manufacturer).localeCompare(
+      getManufacturerName(b.manufacturer)
+    )
+  })
+}
+
+export const getManufacturerOptions = (
+  deviceModels: DeviceModelSummary[]
+): FilterOption[] =>
+  uniqueOptions(
+    deviceModels.map((m) =>
+      m.manufacturer == null
+        ? null
+        : {
+            value: m.manufacturer.slug,
+            label: getManufacturerName(m.manufacturer),
+          }
+    )
+  )
+
+export const getDeviceTypeOptions = (
+  deviceModels: DeviceModelSummary[]
+): FilterOption[] =>
+  uniqueOptions(
+    deviceModels.map((m) =>
+      m.device_type == null
+        ? null
+        : { value: m.device_type.slug, label: m.device_type.display_name }
+    )
+  )
+
+export const getCapabilityOptions = (
+  deviceModels: DeviceModelSummary[]
+): FilterOption[] => {
+  const names = new Set<CapabilityName>()
+  for (const deviceModel of deviceModels) {
+    for (const { name } of getSupportedCapabilities(deviceModel)) {
+      if (capabilityLabels[name] != null) names.add(name)
+    }
+  }
+  return [...names]
+    .sort((a, b) => capabilityRank(a) - capabilityRank(b))
+    .map((name) => ({ value: name, label: getCapabilityLabel(name) }))
+}
+
+export const getDeviceModelName = (deviceModel: DeviceModelSummary): string =>
+  deviceModel.display_name ?? deviceModel.slug
+
+export const getManufacturerName = (
+  manufacturer: ManufacturerRef | Manufacturer
+): string => manufacturer.display_name ?? manufacturer.slug
+
+/** The best available image URL for a device model. */
+export const getDeviceModelImageUrl = (
+  deviceModel: DeviceModelSummary,
+  manufacturer?: Manufacturer | null
+): string | null => {
+  const image =
+    deviceModel.featured_image ??
+    deviceModel.variants.flatMap((variant) => variant.images)[0] ??
+    manufacturer?.default_device_images.find(
+      (d) => d.device_type.slug === deviceModel.device_type?.slug
+    )?.asset ??
+    null
+  if (image == null) return null
+  return (
+    image.formats.thumbnail?.url ??
+    image.formats.small?.url ??
+    image.formats.medium?.url ??
+    image.url
+  )
+}
+
+/** The manufacturer's logo, preferring a square logo. */
+export const getManufacturerLogoUrl = (
+  manufacturer: Manufacturer | null | undefined,
+  { mono = false }: { mono?: boolean } = {}
+): string | null => {
+  if (manufacturer == null) return null
+  const kinds = mono
+    ? ([
+        'square_logo_mono',
+        'horizontal_logo_mono',
+        'square_logo',
+        'horizontal_logo',
+      ] as const)
+    : ([
+        'square_logo',
+        'horizontal_logo',
+        'square_logo_mono',
+        'horizontal_logo_mono',
+      ] as const)
+  for (const kind of kinds) {
+    const logo = manufacturer.logos.find((l) => l.kind === kind)
+    if (logo != null) return logo.formats.small?.url ?? logo.url
+  }
+  return null
+}
+
+const toSupported = (
+  capability: CapabilitySummary
+): SupportedCapability['supported'] | null => {
+  if (capability.supported === 'yes') return 'yes'
+  if (capability.supported === 'conditionally') return 'conditionally'
+  return null
+}
+
+const capabilityRank = (name: string): number => {
+  const index = capabilityOrder.indexOf(name)
+  return index === -1 ? capabilityOrder.length : index
+}
+
+const uniqueOptions = (options: Array<FilterOption | null>): FilterOption[] => {
+  const byValue = new Map<string, FilterOption>()
+  for (const option of options) {
+    if (option != null && !byValue.has(option.value)) {
+      byValue.set(option.value, option)
+    }
+  }
+  return [...byValue.values()].sort((a, b) => a.label.localeCompare(b.label))
+}

package/src/lib/seam/components/ecosystem-elements.ts

@@ -0,0 +1,2 @@
+export * as CompatibleApps from './CompatibleApps/CompatibleApps.element.js'
+export * as SupportedDevices from './SupportedDevices/SupportedDevices.element.js'