@prestack/thread-ui 0.0.1 → 0.0.2

package/dist/ui/materials.ts

@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { argv, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { exit, invoked } from '@prestack/thread/core/invoked'
+import type { Threaded } from '@prestack/thread/core/thread'
+import { findTree, inTree, strayFiles } from '@prestack/thread/core/tree'
+
+export const MATERIALS = {
+  id: 'material',
+  at: 'thread/ui/materials.ts',
+  files: 'ui/mat_*.ts',
+  describes:
+    'A combination of style guide values that gives one specific appearance, worn by any variant that names it: glass, clay, a glaze. It composes and never computes, because every value it sets is a name the style guide holds and never a raw one, which is what lets one material be worn by many variants. Each row names a file prefixed `mat_`, and that file is the material; a file under it that no row names is not a material but a file somebody wrote. An app adds its own to this same list, and a row that goes missing breaks the build, because what the framework offers is not an app’s to withdraw. These are materials and not aesthetics: Neumorphism, Claymorphism and Cyberpunk are templates, and a template is what picks a material.',
+  version: 1,
+  cites: [
+    {
+      on: '2026-08-25',
+      said: 'Style guides they can be used for simple pickings that need no thinking. We can pick colours and basic effects for using the app. Materials however are for more complex and detailed work. Materials.ts is a declaration sheet, SSOT, and each row is a file, mat_',
+    },
+  ],
+  declares: [
+    { id: 'glass', at: 'thread/ui/materials/mat_glass.ts', describes: 'A pane you can see through, with what is behind it softened and desaturation corrected for.' },
+    { id: 'flat', at: 'thread/ui/materials/mat_flat.ts', describes: 'Paper. A plain filled panel with a hairline and almost no lift — the same tokens as glass, asked more quietly.' },
+    { id: 'elevated', at: 'thread/ui/materials/mat_elevated.ts', describes: 'Something lifted off the page, reading by its shadow rather than by any outline.' },
+    { id: 'bordered', at: 'thread/ui/materials/mat_bordered.ts', describes: 'Ink on paper — a hard outline and a shadow with no blur, offset like a stamp.' },
+    { id: 'moulded', at: 'thread/ui/materials/mat_moulded.ts', describes: 'Pressed out of the page rather than laid on it. Its fill is the page itself, and its relief is one shadow cast twice in opposite directions.' },
+    { id: 'clay', at: 'thread/ui/materials/mat_clay.ts', describes: 'Something soft and inflated, lit from above — an outer shadow it sits in and an inset highlight along its top edge.' },
+    { id: 'lit', at: 'thread/ui/materials/mat_lit.ts', describes: 'Something that emits rather than reflects. Its glow is a shadow cast from nowhere in particular, and it names no colour of its own.' },
+    { id: 'ceramic', at: 'thread/ui/materials/mat_ceramic.ts', describes: 'A glazed surface with the light falling down its face. The one material that asks for a gradient rather than a fill.' },
+  ],
+} as const satisfies Threaded & { readonly files: string }
+
+export function nameOf(id: string): string {
+  return id.replace(/-/g, '_').toUpperCase()
+}
+
+function starter(row: Threaded): string {
+  const name = nameOf(row.id)
+  return `import { material } from './material.ts'
+
+export const ${name} = material({
+  id: '${row.id}',
+  sets: [],
+} as const)
+`
+}
+
+export function seeds(rows: readonly Threaded[], held: (at: string) => boolean): readonly { readonly path: string; readonly content: string }[] {
+  return rows.filter((row) => !held(row.at)).map((row) => ({ path: row.at, content: starter(row) }))
+}
+
+export async function mismatched(
+  rows: readonly Threaded[],
+  loader: (row: Threaded) => Promise<{ readonly id?: string } | undefined>,
+): Promise<readonly string[]> {
+  const found: string[] = []
+  for (const row of rows) {
+    const material = await loader(row)
+    if (material === undefined) {
+      found.push(
+        `\`${row.id}\` is declared at \`${row.at}\`, and that file exports no \`${nameOf(row.id)}\`. ` +
+          'A row names a file, and the file is the thing.',
+      )
+      continue
+    }
+    if (material.id !== row.id) {
+      found.push(
+        `\`${row.at}\` declares itself \`${String(material.id)}\`, and the row that names it calls it \`${row.id}\`. ` +
+          "A material file and the row that names it have to be the same material — make the file's `id` match the row, or fix the row.",
+      )
+    }
+  }
+  return found
+}
+
+function extensionOf(path: string): string {
+  const name = basename(path)
+  const at = name.lastIndexOf('.')
+  return at === -1 ? '' : name.slice(at)
+}
+
+const MAT_PREFIX = /^mat_/
+
+export function orphaned(rows: readonly Threaded[], strays: readonly string[]): readonly string[] {
+  const named = new Set(rows.map((row) => row.at))
+  return strays
+    .filter((one) => !named.has(one))
+    .map(
+      (one) =>
+        `\`${one}\` is under materials and no row names it — not a material, a file somebody wrote. ` +
+        'Add a row for it, or delete the file.',
+    )
+}
+
+const GUARDED = /=\s*material\s*\(/
+
+const TYPED = /import type \{ Material \} from '([^']*)'/
+
+const OPENS = /export const ([A-Z0-9_]+) = \{/
+
+const CLOSES = /\} as const satisfies Material/
+
+export function unguarded(rows: readonly Threaded[], read: (at: string) => string): readonly string[] {
+  return rows
+    .filter((row) => !GUARDED.test(read(row.at)))
+    .map(
+      (row) =>
+        `\`${row.at}\` declares \`${row.id}\` with \`satisfies Material\`, which accepts a value no ` +
+        'row holds — `satisfies` checks against `string`, so `8px` and `var(--x)` compile. Run ' +
+        '`thread materials` and it rewrites the two lines that wrap the declaration, leaving what is ' +
+        'between them alone.',
+    )
+}
+
+export function guarding(source: string): string | undefined {
+  if (GUARDED.test(source)) return undefined
+  const typed = TYPED.exec(source)
+  const opens = OPENS.exec(source)
+  if (typed === null || opens === null || !CLOSES.test(source)) return undefined
+  return source
+    .replace(typed[0], `import { material } from '${typed[1] ?? ''}'`)
+    .replace(opens[0], `export const ${opens[1] ?? ''} = material({`)
+    .replace(CLOSES, '} as const)')
+}
+
+async function run(): Promise<number> {
+  const tree = findTree()
+  const at = inTree(tree, 'materials.ts')
+  if (!existsSync(at)) {
+    stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no material and there is nothing to seed or check.\n`)
+    return 0
+  }
+  const held = (await import(pathToFileURL(at).href)) as { MATERIAL?: { readonly declares?: readonly Threaded[] } }
+
+  if (held.MATERIAL === undefined) {
+    stdout.write(`thread: ${tree.name}/materials.ts exports no \`MATERIAL\`, so nothing declares a material here.\n`)
+    return 1
+  }
+
+  const rows = held.MATERIAL.declares ?? []
+  const checking = argv.includes('--check')
+  const exists = (where: string): boolean => existsSync(join(tree.at, where))
+  const made = seeds(rows, exists)
+
+  if (checking) {
+    const unseeded = rows.find((row) => !exists(row.at))
+    if (unseeded !== undefined) {
+      stdout.write(
+        `thread: \`${unseeded.id}\` is declared at \`${unseeded.at}\`, and the file is not there yet. ` +
+          'A row names a file, and `--check` never writes one — run `thread materials` and commit what it seeds.\n',
+      )
+      return 1
+    }
+  } else {
+    for (const one of made) {
+      mkdirSync(dirname(join(tree.at, one.path)), { recursive: true })
+      writeFileSync(join(tree.at, one.path), one.content, 'utf8')
+      stdout.write(`thread: seeded ${one.path}\n`)
+    }
+  }
+
+  const wrong = (
+    await mismatched(rows, async (row) => {
+      const module = (await import(pathToFileURL(join(tree.at, row.at)).href)) as Record<string, unknown>
+      return module[nameOf(row.id)] as { readonly id?: string } | undefined
+    })
+  )[0]
+  if (wrong !== undefined) {
+    stdout.write(`thread: ${wrong}\n`)
+    return 1
+  }
+
+  const read = (at: string): string => readFileSync(join(tree.at, at), 'utf8')
+  if (checking) {
+    const loose = unguarded(rows, read)[0]
+    if (loose !== undefined) {
+      stdout.write(`thread: ${loose}\n`)
+      return 1
+    }
+  } else {
+    for (const row of rows) {
+      const written = guarding(read(row.at))
+      if (written === undefined) continue
+      writeFileSync(join(tree.at, row.at), written, 'utf8')
+      stdout.write(`thread: ${row.at} now declares through \`material(...)\`\n`)
+    }
+  }
+
+  const stray = orphaned(rows, strayFiles(tree.at, 'mat_', '.' + 'ts'))[0]
+  if (stray !== undefined) {
+    stdout.write(`thread: ${stray}\n`)
+    return 1
+  }
+
+  stdout.write(
+    checking
+      ? `thread: ${String(rows.length)} material(s) declared, all seeded\n`
+      : `thread: ${String(rows.length)} material(s) declared, ${String(made.length)} seeded, ` +
+        `${String(rows.length - made.length)} already written\n`,
+  )
+  return 0
+}
+
+if (invoked(import.meta.url)) exit(await run())

package/dist/ui/modes.ts

@@ -0,0 +1,44 @@
+import type { Threaded } from '@prestack/thread/core/thread'
+
+const here = 'thread/ui/modes.ts'
+
+const said = [
+  {
+    on: '2026-08-25',
+    said: 'themes can have dark and light modes too. So they are not at all the same.',
+  },
+]
+
+const one = <Id extends string>(
+  id: Id,
+  is: string,
+  describes: string,
+): Omit<Threaded, 'at'> & { readonly id: Id; readonly is: string } => ({
+  id,
+  is,
+  describes,
+  version: 1,
+})
+
+export const holds = [
+  one(
+    'dark',
+    '(prefers-color-scheme: dark)',
+    'The reader has asked their device for a dark interface. Nothing about the app chooses this and nothing about the app can override it.',
+  ),
+  one(
+    'light',
+    '(prefers-color-scheme: light)',
+    'The reader has asked their device for a light interface. Stated rather than assumed, because the resting values are not the same thing as an answer to the question.',
+  ),
+] as const satisfies readonly (Omit<Threaded, 'at'> & { readonly is: string })[]
+
+export const MODES = {
+  id: 'mode',
+  at: here,
+  describes:
+    'Every way a reader’s own device can ask for a different look, and the query that answers it. A mode is chosen for the app rather than by it, which is what tells it from a theme — and a theme has its own modes, so the two are dimensions rather than one list. A mode changes what the variables hold, never what a material or a variant says.',
+  version: 1,
+  cites: said,
+  holds,
+} as const satisfies Threaded & { readonly holds: readonly (Omit<Threaded, 'at'> & { readonly is: string })[] }

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 });