@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/navigation.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import type { MapIsland, Screen } from './islands/map.ts'
+
+import { Link } from './elements/link.tsx'
+
+export type ScreenName = Screen['id']
+import { element, useSurface } from './wrappers.tsx'
+
+export function trailTo(map: MapIsland, to: ScreenName): readonly ScreenName[] {
+  const entries = map.screens.filter((s) => s.entry).map((s) => s.id)
+  if (entries.includes(to)) return [to]
+
+  const seen = new Set<ScreenName>(entries)
+  let frontier: readonly (readonly ScreenName[])[] = entries.map((id) => [id])
+
+  while (frontier.length > 0) {
+    const next: (readonly ScreenName[])[] = []
+    for (const path of frontier) {
+      const here = path[path.length - 1] as ScreenName
+      for (const link of map.links.filter((l) => l.from === here)) {
+        if (link.to === to) return [...path, link.to]
+        if (seen.has(link.to)) continue
+        seen.add(link.to)
+        next.push([...path, link.to])
+      }
+    }
+    frontier = next
+  }
+  return []
+}
+

package/dist/ui/positioning.ts

@@ -0,0 +1,90 @@
+'use client'
+
+import {
+  arrow as arrowMiddleware,
+  computePosition,
+  flip,
+  offset,
+  shift,
+  size,
+  type Middleware,
+  type Placement,
+  type Platform,
+} from '@floating-ui/dom'
+import { useFloating, autoUpdate } from '@floating-ui/react-dom'
+import type { RefObject } from 'react'
+
+export interface AnchorOptions {
+  readonly placement?: Placement
+
+  readonly gap?: number
+
+  readonly padding?: number
+  readonly arrowRef?: RefObject<HTMLElement | null>
+}
+
+export interface Position {
+  readonly x: number
+  readonly y: number
+
+  readonly placement: Placement
+
+  readonly maxWidth?: number
+  readonly maxHeight?: number
+  readonly arrow?: { readonly x?: number; readonly y?: number }
+}
+
+const DEFAULT_GAP = 4
+const DEFAULT_PADDING = 8
+
+function middleware(options: AnchorOptions): Middleware[] {
+  const padding = options.padding ?? DEFAULT_PADDING
+  const list: Middleware[] = [
+    offset(options.gap ?? DEFAULT_GAP),
+    flip({ padding }),
+    shift({ padding }),
+    size({
+      padding,
+      apply({ availableWidth, availableHeight, elements }) {
+
+        Object.assign(elements.floating.style, {
+          maxWidth: `${Math.max(0, availableWidth)}px`,
+          maxHeight: `${Math.max(0, availableHeight)}px`,
+          overflow: 'auto',
+        })
+      },
+    }),
+  ]
+
+  if (options.arrowRef !== undefined) {
+    list.push(arrowMiddleware({ element: options.arrowRef.current as Element, padding }))
+  }
+  return list
+}
+
+export async function positionOf(
+  reference: Element,
+  floating: HTMLElement,
+  options: AnchorOptions & { readonly platform?: Platform } = {},
+): Promise<Position> {
+  const result = await computePosition(reference, floating, {
+    placement: options.placement ?? 'bottom',
+    middleware: middleware(options),
+    ...(options.platform === undefined ? {} : { platform: options.platform }),
+  })
+  const arrowData = result.middlewareData.arrow
+  return {
+    x: result.x,
+    y: result.y,
+    placement: result.placement,
+    ...(arrowData === undefined ? {} : { arrow: { ...(arrowData.x === undefined ? {} : { x: arrowData.x }), ...(arrowData.y === undefined ? {} : { y: arrowData.y }) } }),
+  }
+}
+
+export function useAnchored(options: AnchorOptions = {}): ReturnType<typeof useFloating> {
+  return useFloating({
+    placement: options.placement ?? 'bottom',
+    middleware: middleware(options),
+    whileElementsMounted: autoUpdate,
+  })
+}

package/dist/ui/presented.tsx

@@ -0,0 +1,119 @@
+'use client'
+
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+
+import { PRESENTATION_BEHAVIOUR, type Presentation } from './door.ts'
+import { useDismissLayer } from './dismiss-layer.ts'
+import { useFocusScope } from './focus-scope.ts'
+import { lockScroll } from './scroll-lock.ts'
+
+export interface PresentedProps {
+  readonly presentation: Presentation
+
+  readonly open?: boolean
+  readonly onDismiss?: () => void
+  readonly className?: string
+  readonly children: ReactNode
+}
+
+export function Presented(props: PresentedProps): ReactNode {
+  const behaviour = PRESENTATION_BEHAVIOUR[props.presentation]
+  const open = props.open ?? true
+  const ref = useRef<HTMLDivElement>(null)
+  const [leaving, setLeaving] = useState(false)
+  const [was, setWas] = useState(open)
+  const labelId = useId()
+
+  useFocusScope(ref, {
+    active: open,
+    trapFocus: behaviour.trapFocus,
+    returnFocus: behaviour.returnFocus,
+  })
+
+  useDismissLayer(ref, {
+    active: open && (behaviour.dismissOnEscape || behaviour.dismissOnOutside),
+    dismissOnEscape: behaviour.dismissOnEscape,
+    dismissOnOutside: behaviour.dismissOnOutside,
+    onDismiss: props.onDismiss ?? (() => undefined),
+  })
+
+  useEffect(() => {
+    if (!open || !behaviour.backdrop) return
+    return lockScroll()
+  }, [open, behaviour.backdrop])
+
+  if (was !== open) {
+    setWas(open)
+    setLeaving(!open)
+  }
+
+  useEffect(() => {
+    if (!leaving) return undefined
+    const node = ref.current
+    if (node === null) {
+      setLeaving(false)
+      return undefined
+    }
+    const running =
+      typeof globalThis.getComputedStyle === 'function' &&
+      globalThis.getComputedStyle(node).animationName !== 'none'
+    if (!running) {
+      setLeaving(false)
+      return undefined
+    }
+    const done = (): void => setLeaving(false)
+    node.addEventListener('animationend', done)
+
+    const style = globalThis.getComputedStyle(node)
+    const seconds = (one: string): number =>
+      one.split(',').reduce((most, part) => Math.max(most, Number.parseFloat(part) || 0), 0)
+    const after = (seconds(style.animationDuration) + seconds(style.animationDelay)) * 1000 + 50
+    const timer = setTimeout(done, after)
+
+    return () => {
+      node.removeEventListener('animationend', done)
+      clearTimeout(timer)
+    }
+  }, [leaving])
+
+  useEffect(() => {
+    if (!open) return
+    const root = ref.current
+    if (root === null) return
+    const title = root.querySelector('[data-screen-title], h1, h2, h3, h4, h5, h6')
+    if (title === null) return
+    if (title.id === '') title.id = labelId
+    root.setAttribute('aria-labelledby', title.id)
+  }, [open, labelId])
+
+  if (!open && !leaving) return null
+
+  const surface = (
+    <div
+      ref={ref}
+      className={props.className}
+      data-presentation={props.presentation}
+      {...(leaving ? { 'data-leaving': '' } : {})}
+
+      {...(behaviour.trapFocus ? { role: 'dialog', 'aria-modal': true } : {})}
+      {...(props.presentation === 'toast' ? { role: 'status', 'aria-live': 'polite' as const } : {})}
+    >
+      {props.children}
+    </div>
+  )
+
+  const content = behaviour.backdrop ? (
+    <>
+      {}
+      <div data-backdrop="true" aria-hidden="true" />
+      {surface}
+    </>
+  ) : (
+    surface
+  )
+
+  if (!behaviour.portal) return content
+
+  return createPortal(content, document.body)
+}

package/dist/ui/provider.d.ts

@@ -17,7 +17,9 @@ export interface ThreadUiProps {
     readonly asking?: readonly {
         readonly id: string;
         readonly selector: string;
+        readonly when?: string;
     }[];
+    readonly permits?: (action: string) => boolean;
     readonly platform?: string;
     readonly telemetry?: {
         readonly endpoint?: string;

package/dist/ui/provider.js

@@ -83,6 +83,11 @@ export function ThreadUi(props) {
         });
     }, [telemetryOff, props.telemetry?.endpoint, props.telemetry?.sample, props.telemetry?.allowed]);
     useEffect(() => () => collector.stop(), [collector]);
+    const gate = props.permits;
+    const asked = props.asking;
+    const holding = useMemo(() => gate === undefined
+        ? []
+        : (asked ?? []).filter((one) => one.when !== undefined && !gate(one.when)).map((one) => one.id), [gate, asked]);
     const derived = useMemo(() => ({
         palette: props.palette ?? readPalette(),
         appearance,
@@ -92,12 +97,13 @@ export function ThreadUi(props) {
         edgeScroll: readEdgeScroll(),
         ...(props.actor === undefined ? {} : { actor: props.actor }),
         ...(props.asking === undefined ? {} : { asking: props.asking }),
+        ...(holding.length === 0 ? {} : { holding }),
         ...(props.platform === undefined ? {} : { platform: props.platform }),
         ...(props.dispatch === undefined ? {} : { dispatch: props.dispatch }),
         ...(props.navigateTo === undefined ? {} : { navigateTo: props.navigateTo }),
         collector,
         translate: (key, params) => translate(key, params),
-    }), [props.actor, props.asking, props.palette, props.platform, props.dispatch, props.navigateTo, appearance.mode, appearance.reduceMotion, clock, ticker, collector, translate]);
+    }), [props.actor, props.asking, props.palette, props.platform, props.dispatch, props.navigateTo, holding, appearance.mode, appearance.reduceMotion, clock, ticker, collector, translate]);
     if (existing !== null && !opinionated)
         return props.children;
     return _jsx(UiProvider, { config: props.config ?? derived, children: props.children });

package/dist/ui/provider.tsx

@@ -0,0 +1,182 @@
+'use client'
+
+import { useCallback, useContext, useEffect, useMemo, useSyncExternalStore, type ReactNode } from 'react'
+
+import { en } from './i18n/catalogs/en.ts'
+import { createTranslator } from './i18n/translator.ts'
+import { EDGE_SCROLL_DEFAULTS } from './drag.ts'
+
+import { createCollector, INERT_COLLECTOR } from './collector.ts'
+import { Clock, Ticker } from './door.ts'
+import { UiContext, UiProvider, type Appearance, type UiConfig } from './wrappers.tsx'
+
+export interface ThreadUiProps {
+  readonly children: ReactNode
+
+  readonly palette?: { readonly accent: string; readonly surface: string }
+
+  readonly mode?: 'light' | 'dark'
+  readonly locale?: string
+
+  readonly wording?: Readonly<Record<string, Readonly<Record<string, string>>>>
+
+  readonly actor?: { readonly id: string | null; readonly roles: readonly string[]; readonly entitlements: readonly string[] }
+
+  readonly asking?: readonly { readonly id: string; readonly selector: string; readonly when?: string }[]
+
+  readonly permits?: (action: string) => boolean
+
+  readonly platform?: string
+
+  readonly telemetry?: {
+
+    readonly endpoint?: string
+    readonly allowed: () => boolean
+
+    readonly sample?: number
+  }
+
+  readonly dispatch?: (name: string, input?: Readonly<Record<string, unknown>>) => Promise<unknown>
+
+  readonly navigateTo?: (screen: string) => void
+
+  readonly config?: UiConfig
+}
+
+function useMedia(query: string, fallback: boolean): boolean {
+
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof globalThis.matchMedia !== 'function') return () => {}
+      const list = globalThis.matchMedia(query)
+      list.addEventListener('change', onChange)
+      return () => list.removeEventListener('change', onChange)
+    },
+    [query],
+  )
+
+  const read = useCallback(
+    () => (typeof globalThis.matchMedia === 'function' ? globalThis.matchMedia(query).matches : fallback),
+    [query, fallback],
+  )
+
+  return useSyncExternalStore(subscribe, read, () => fallback)
+}
+
+function readPalette(): { accent: string; surface: string } {
+  if (typeof globalThis.getComputedStyle !== 'function' || typeof globalThis.document !== 'object') {
+    return { accent: '', surface: '' }
+  }
+  const style = globalThis.getComputedStyle(globalThis.document.documentElement)
+  const read = (name: string): string => style.getPropertyValue(name).trim()
+  return {
+    accent: read('--thread-palette-accent'),
+    surface: read('--thread-palette-surface'),
+  }
+}
+
+function readEdgeScroll(): { band: number; speed: number } {
+  if (typeof globalThis.getComputedStyle !== 'function' || typeof globalThis.document !== 'object') return { ...EDGE_SCROLL_DEFAULTS }
+  const style = globalThis.getComputedStyle(globalThis.document.documentElement)
+  const read = (name: string, fallback: number): number => {
+    const value = Number.parseFloat(style.getPropertyValue(name))
+    return Number.isFinite(value) ? value : fallback
+  }
+  return {
+    band: read('--thread-edge-scroll-band', EDGE_SCROLL_DEFAULTS.band),
+    speed: read('--thread-edge-scroll-speed', EDGE_SCROLL_DEFAULTS.speed),
+  }
+}
+
+export function ThreadUi(props: ThreadUiProps): ReactNode {
+
+  const existing = useContext(UiContext)
+  const opinionated =
+    props.mode !== undefined ||
+    props.locale !== undefined ||
+    props.palette !== undefined ||
+    props.platform !== undefined ||
+    props.telemetry !== undefined ||
+    props.wording !== undefined ||
+    props.config !== undefined
+
+  const prefersDark = useMedia('(prefers-color-scheme: dark)', false)
+  const reduceMotion = useMedia('(prefers-reduced-motion: reduce)', false)
+
+  const appearance: Appearance = {
+    mode: props.mode ?? (prefersDark ? 'dark' : 'light'),
+    reduceMotion,
+  }
+
+  const language = props.locale ?? 'en'
+  const translate = useMemo(() => {
+    const held = props.wording?.[language]
+    if (props.wording !== undefined && held === undefined) {
+      throw new Error(
+        `This app was handed wording and none of it is in "${language}". It has ` +
+          `${Object.keys(props.wording).sort().join(', ')} — declare the language in ` +
+          '`_threads/localizations.ts` and run `thread i18n`, or ask for one it is in.',
+      )
+    }
+    return createTranslator(held ?? en, { locale: language })
+  }, [language, props.wording])
+
+  const clock = useMemo(() => new Clock(), [])
+
+  const ticker = useMemo(() => new Ticker(), [])
+
+  const telemetryOff = props.telemetry === undefined
+
+  const collector = useMemo(() => {
+    if (props.telemetry === undefined) return INERT_COLLECTOR
+    return createCollector({
+      endpoint: props.telemetry.endpoint ?? '/obs/client',
+      allowed: props.telemetry.allowed,
+      ...(props.telemetry.sample === undefined ? {} : { sample: props.telemetry.sample }),
+      ...(typeof navigator === 'object' && typeof navigator.sendBeacon === 'function'
+        ? { beacon: (url: string, body: string) => navigator.sendBeacon(url, new Blob([body], { type: 'application/json' })) }
+        : {}),
+    })
+
+  }, [telemetryOff, props.telemetry?.endpoint, props.telemetry?.sample, props.telemetry?.allowed])
+
+  useEffect(() => () => collector.stop(), [collector])
+
+  const gate = props.permits
+  const asked = props.asking
+
+  const holding = useMemo(
+    () =>
+      gate === undefined
+        ? []
+        : (asked ?? []).filter((one) => one.when !== undefined && !gate(one.when)).map((one) => one.id),
+    [gate, asked],
+  )
+
+  const derived: UiConfig = useMemo(
+    () => ({
+      palette: props.palette ?? readPalette(),
+      appearance,
+      clock,
+      ticker,
+
+      now: () => Date.now(),
+      edgeScroll: readEdgeScroll(),
+
+      ...(props.actor === undefined ? {} : { actor: props.actor }),
+      ...(props.asking === undefined ? {} : { asking: props.asking }),
+      ...(holding.length === 0 ? {} : { holding }),
+      ...(props.platform === undefined ? {} : { platform: props.platform }),
+      ...(props.dispatch === undefined ? {} : { dispatch: props.dispatch }),
+      ...(props.navigateTo === undefined ? {} : { navigateTo: props.navigateTo }),
+      collector,
+      translate: (key, params) => translate(key as never, params as never),
+    }),
+
+    [props.actor, props.asking, props.palette, props.platform, props.dispatch, props.navigateTo, holding, appearance.mode, appearance.reduceMotion, clock, ticker, collector, translate],
+  )
+
+  if (existing !== null && !opinionated) return props.children
+
+  return <UiProvider config={props.config ?? derived}>{props.children}</UiProvider>
+}

package/dist/ui/render-loop.ts

@@ -0,0 +1,133 @@
+'use client'
+
+import { useRef } from 'react'
+
+const RENDER_LIMIT = 40
+
+const WINDOW_MS = 1000
+
+const COMPARE_DEPTH = 3
+
+function armed(): boolean {
+
+  return process.env.NODE_ENV !== 'production'
+}
+
+export interface RenderLoop {
+
+  readonly component: string
+  readonly renders: number
+  readonly withinMs: number
+
+  readonly unstable: readonly string[]
+
+  readonly differing: readonly string[]
+}
+
+export class RenderLoopError extends Error {
+  readonly loop: RenderLoop
+
+  constructor(loop: RenderLoop) {
+    super(describe(loop))
+    this.name = 'RenderLoopError'
+    this.loop = loop
+  }
+}
+
+function describe(loop: RenderLoop): string {
+  const head = `${loop.component} rendered ${loop.renders} times in ${loop.withinMs}ms, which is a render loop.`
+
+  if (loop.unstable.length > 0) {
+    const props = loop.unstable.join(', ')
+    return (
+      `${head} ${props} arrived with a new identity every render while its value stayed equal, so ` +
+      `every render caused the next one. Return the same object for the same answer — that is the ` +
+      `read layer's job (ADR-180 rule 10), not the component's — or compute the value inside render ` +
+      `instead of syncing it into state from an effect (rule 11).`
+    )
+  }
+
+  if (loop.differing.length > 0) {
+    return (
+      `${head} ${loop.differing.join(', ')} changed VALUE on every render, so this is not an identity ` +
+      `problem: something is writing during render. Move the write to an event or an action.`
+    )
+  }
+
+  return (
+    `${head} No prop changed at all, so the re-render comes from state or context inside the ` +
+    `component — look for a setter called from an effect body (ADR-180 rule 11).`
+  )
+}
+
+function equalValue(a: unknown, b: unknown, depth = 0): boolean {
+  if (Object.is(a, b)) return true
+  if (depth >= COMPARE_DEPTH) return false
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((item, index) => equalValue(item, b[index], depth + 1))
+  }
+
+  const left = a as Record<string, unknown>
+  const right = b as Record<string, unknown>
+  const keys = Object.keys(left)
+  if (keys.length !== Object.keys(right).length) return false
+  return keys.every((key) => key in right && equalValue(left[key], right[key], depth + 1))
+}
+
+function compare(
+  previous: Record<string, unknown>,
+  next: Record<string, unknown>,
+): { unstable: string[]; differing: string[] } {
+  const unstable: string[] = []
+  const differing: string[] = []
+
+  for (const key of [...new Set([...Object.keys(previous), ...Object.keys(next)])].sort()) {
+    if (Object.is(previous[key], next[key])) continue
+    if (equalValue(previous[key], next[key])) unstable.push(key)
+    else differing.push(key)
+  }
+
+  return { unstable, differing }
+}
+
+export function useRenderLoopDetector(component: string, props: Record<string, unknown>): void {
+  const renders = useRef(0)
+  const openedAt = useRef(0)
+  const previous = useRef<Record<string, unknown> | undefined>(undefined)
+  const tripped = useRef<RenderLoop | undefined>(undefined)
+
+  if (armed()) {
+
+    if (tripped.current !== undefined) throw new RenderLoopError(tripped.current)
+
+    const now = Date.now()
+    const elapsed = now - openedAt.current
+
+    if (openedAt.current === 0 || elapsed > WINDOW_MS) {
+      openedAt.current = now
+      renders.current = 0
+    }
+
+    renders.current += 1
+
+    if (renders.current > RENDER_LIMIT) {
+      const loop: RenderLoop = {
+        component,
+        renders: renders.current,
+
+        withinMs: now - openedAt.current,
+        ...compare(previous.current ?? {}, props),
+      }
+
+      tripped.current = loop
+      renders.current = 0
+      openedAt.current = now
+      throw new RenderLoopError(loop)
+    }
+  }
+
+  previous.current = props
+}