@prestack/thread-ui 0.1.10 → 0.1.12

package/dist/ui/variants.ts

@@ -1,64 +0,0 @@
-import type { Threaded } from '@prestack/thread/core/thread'
-
-interface Worn extends Threaded {
-  readonly section: string
-  readonly wears: readonly string[]
-}
-
-interface Catalogue extends Threaded {
-  readonly files: string
-  readonly declares: readonly Worn[]
-}
-
-const at = (id: string): string => `thread/ui/variants/var_${id}.ts`
-
-export const VARIANTS = {
-  id: 'variant',
-  at: 'thread/ui/variants.ts',
-  files: 'ui/var_*.ts',
-  describes:
-    'How a thing looks: a material plus the style guide values it names directly, never raw ones, and how that look changes under a state. It says nothing about type, because typography belongs to the role the wording states; what is left here is the look of the box and the colour of what sits in it. Each row names a file prefixed `var_`, and that file is the variant: what it looks like, what it looks like under a state, and which states it reacts to. The row states which elements accept it, and it is worn as the tag, so a variant `button-fill` is written `<Button.buttonFill>` and an element nothing declares is refused. A state is the set of signals holding at once, and two states that can both hold and both set one property must have their combination declared, or which one wins is an accident of file order. 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.',
-  version: 1,
-  cites: [
-    {
-      on: '2026-08-24',
-      said: 'Variants define lots of things. Including how they look in different states. Including how they look in multiple states at once. (hover, pressed) is one variant that covers both hover and pressed, so they look the same when they are simultaneous. (hover) (pressed) (hover, pressed) however have different states for the three situations.',
-    },
-    {
-      on: '2026-08-25',
-      said: 'Variants basically say: This is how I look. These are the elements that accept me. These are my behaviours under different states. These are the states I can react to.',
-    },
-    {
-      on: '2026-08-28',
-      said: 'fonts.ts as SSOT for everything related to fonts and easy to change fonts throughout the app like tokens, like....the exact same reason for existing that tokens+styleguide have is the same reason we have fonts.ts',
-    },
-  ],
-  declares: [
-    { id: 'card', section: 'surface', at: at('card'), wears: ['Accordion', 'Bars', 'Box', 'Donut', 'Empty', 'Funnel', 'Heatmap', 'LineChart', 'Media', 'Menu', 'Scatter', 'Sparkline', 'Surface', 'Table', 'Tooltip'], describes: 'A surface holding other content, and the shape every unregistered variant falls back to.' },
-    { id: 'list-row', section: 'surface', at: at('list-row'), wears: ['Box'], describes: 'One row of a list — square, quiet, and separated by its neighbours rather than by a shadow.' },
-    { id: 'framed', section: 'surface', at: at('framed'), wears: ['Image', 'Media', 'AspectRatio'], describes: 'A picture given the same corners as a panel, on a sunken ground so the gap before it loads is not a white hole.' },
-    { id: 'bubble-them', section: 'surface', at: at('bubble-them'), wears: ['Box'], describes: 'A message somebody else sent. The plain half of a conversation.' },
-    { id: 'bubble-me', section: 'surface', at: at('bubble-me'), wears: ['Box'], describes: 'A message the current person sent. Takes the accent, which is how a conversation reads as two voices without a second colour role.' },
-    { id: 'button-fill', section: 'button', at: at('button-fill'), wears: ['Button'], describes: 'The one action a screen is asking for. The accent behind it, and the only button on a screen that should carry it.' },
-    { id: 'button-normal', section: 'button', at: at('button-normal'), wears: ['Button'], describes: 'The ordinary button. A surface with a hairline round it — pressable, and asking for nothing in particular.' },
-    { id: 'button-ghost', section: 'button', at: at('button-ghost'), wears: ['Button'], describes: 'Wording that acts. No ground and no line until a pointer is over it, which is what keeps a row of them from reading as a wall of boxes.' },
-    { id: 'button-border', section: 'button', at: at('button-border'), wears: ['Button'], describes: 'An action offered beside a filled one. The accent as an edge rather than a ground, so the shape says pressable and the colour says not this one.' },
-    { id: 'button-destructive', section: 'button', at: at('button-destructive'), wears: ['Button'], describes: 'Something that cannot be undone. The same shape as the asking button, in the colour reserved for consequence.' },
-    { id: 'button-destructive-ghost', section: 'button', at: at('button-destructive-ghost'), wears: ['Button'], describes: 'A destructive action that is not the point of the screen — delete, sitting quietly at the end of a menu. Carries the negative as ink and gains a ground only under a pointer.' },
-    { id: 'button-cta', section: 'button', at: at('button-cta'), wears: ['Button'], describes: 'The one thing a landing screen exists to get pressed. Taller than every other button and set in running type rather than label type, which is what makes it read from across the page.' },
-    { id: 'button-quiet', section: 'button', at: at('button-quiet'), wears: ['Button'], describes: 'An action that is available and is not being suggested — cancel, skip, dismiss. Ink that supports rather than states, and a smaller symbol beside it.' },
-    { id: 'button-glass', section: 'button', at: at('button-glass'), wears: ['Button'], describes: 'A button over a picture or a video, where a solid fill would hide what it is sitting on. What is behind shows through, softened.' },
-    { id: 'input', section: 'entry', at: at('input'), wears: ['Field', 'Select', 'Slider', 'Textarea', 'Toggle'], describes: 'Anything a person types into. Tighter vertical room than a surface, so the text baseline sits where a label expects it.' },
-    { id: 'choice', section: 'entry', at: at('choice'), wears: ['RadioGroup'], describes: 'A set of options laid out to be chosen between. A group is not a control — it cannot be focused or invalid itself, only the radios inside it can — so it takes arrangement and a ground and states nothing it cannot be in.' },
-    { id: 'tab-bar', section: 'navigation', at: at('tab-bar'), wears: ['Breadcrumb', 'Pagination', 'Tabs'], describes: 'The strip of destinations along one edge. Rounder and less padded than a surface, because it holds pressable things rather than content.' },
-    { id: 'link-inline', section: 'navigation', at: at('link-inline'), wears: ['Link'], describes: 'Wording that takes you somewhere. Carries the accent so it reads as reachable without an underline, and draws a real ring when a keyboard reaches it.' },
-    { id: 'chip', section: 'marker', at: at('chip'), wears: ['Badge'], describes: 'A small token standing for a value. The tightest room in the set, and pill-shaped like the buttons.' },
-    { id: 'glyph-plain', section: 'marker', at: at('glyph-plain'), wears: ['Glyph'], describes: 'A pictogram at the size most controls use, drawn in the ink of whatever it sits beside.' },
-    { id: 'avatar-round', section: 'marker', at: at('avatar-round'), wears: ['Avatar'], describes: 'A person, standing for themselves. Fully round, sunken so it reads as a well rather than a card, and sized to be recognised at a glance.' },
-    { id: 'rule', section: 'marker', at: at('rule'), wears: ['Separator'], describes: 'The line between two things. The thinnest a screen can draw, in the colour that separates without asking to be seen.' },
-    { id: 'skeleton-block', section: 'marker', at: at('skeleton-block'), wears: ['Skeleton'], describes: 'The shape of something that has not arrived. Sunken and breathing, which is what says waiting rather than empty.' },
-    { id: 'spinner-turning', section: 'marker', at: at('spinner-turning'), wears: ['Spinner'], describes: 'Work with no measurable end. Turns without stopping, in the accent, so it reads as the app doing something rather than the app stuck.' },
-    { id: 'stat-tile', section: 'figure', at: at('stat-tile'), wears: ['Gauge', 'Progress', 'Stat'], describes: 'A single figure given room to be read at a glance, so its type role is the display one rather than body.' },
-    { id: 'tap-target', section: 'gesture', at: at('tap-target'), wears: ['HitBox'], describes: 'Anything a finger acts on directly rather than through a control — the one variant a hit box wears. It is where a tap, a press and a carry are answered, because a hit box is the only thing that raises those and nothing accepted it before.' },
-  ],
-} as const satisfies Catalogue

package/dist/ui/wrappers.tsx

@@ -1,429 +0,0 @@
-'use client'
-
-import { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
-
-import type { Collector } from './collector.ts'
-import type { ArrangementElement, Dispatching, VariantsFor, Wearing } from './checked.ts'
-
-import { PRESENTATION_BEHAVIOUR, type Clock, type Presentation, type Surface, type Ticker } from './door.ts'
-import { holds as declared, selectorOf } from './signals.ts'
-
-declare module 'react' {
-  interface HTMLAttributes<T> {
-    readonly at?: string
-  }
-  interface SVGAttributes<T> {
-    readonly at?: string
-  }
-}
-import { Presented } from './presented.tsx'
-import { useRenderLoopDetector } from './render-loop.ts'
-
-export interface Appearance {
-  readonly mode: 'light' | 'dark'
-
-  readonly reduceMotion: boolean
-}
-
-export interface UiConfig {
-
-  readonly palette: { readonly accent: string; readonly surface: string }
-
-  readonly translate: (key: string, params?: Readonly<Record<string, unknown>>) => string
-  readonly appearance: Appearance
-  readonly clock: Clock
-
-  readonly ticker?: Ticker
-
-  readonly now?: () => number
-
-  readonly edgeScroll?: { readonly band?: number; readonly speed?: number }
-
-  readonly collector?: Collector
-
-  readonly platform?: string
-
-  readonly dispatch?: (name: keyof Dispatching, input?: Readonly<Record<string, unknown>>) => Promise<unknown>
-
-  readonly navigateTo?: (screen: string) => void
-
-  readonly actor?: { readonly id: string | null; readonly roles: readonly string[]; readonly entitlements: readonly string[] }
-
-  readonly asking?: readonly { readonly id: string; readonly selector: string }[]
-
-  readonly holding?: readonly string[]
-}
-
-export const UiContext = createContext<UiConfig | null>(null)
-
-const MISSING =
-  'No UI context. Every element resolves its look, its text and its clock through the door, so it ' +
-  'must render inside <UiProvider>. An element rendering without one would silently have no theme ' +
-  'and no locale — which looks like a styling bug and is a wiring bug.'
-
-export function UiProvider({ config, children }: { config: UiConfig; children: ReactNode }): ReactNode {
-  return <UiContext.Provider value={config}>{children}</UiContext.Provider>
-}
-
-export function useUi(): UiConfig {
-  const config = useContext(UiContext)
-  if (config === null) throw new Error(MISSING)
-  return config
-}
-
-export interface SurfaceRequest {
-
-  readonly className?: string
-
-  readonly invokes?: { readonly dispatch?: keyof Dispatching; readonly input?: Readonly<Record<string, unknown>>; readonly on?: 'press' | 'shown' }
-
-  readonly holds?: readonly ((typeof declared)[number]['id'] | (string & {}))[]
-
-  readonly raises?: readonly ((typeof declared)[number]['id'] | (string & {}))[]
-
-  readonly animates?: boolean
-
-  readonly measures?: Readonly<Record<string, string | number>>
-}
-
-export function useSurface(request: SurfaceRequest = {}): Surface {
-  const { translate, appearance, clock, asking, holding, dispatch: run } = useUi()
-  const [t, setT] = useState(0)
-
-  const animates = request.animates === true && !appearance.reduceMotion
-
-  useEffect(() => {
-    if (!animates) return undefined
-    return clock.subscribe(setT)
-  }, [animates, clock])
-
-  const gated = (request.raises ?? []).filter((one) => (holding ?? []).includes(one))
-  const holds = gated.length === 0 ? (request.holds ?? []) : [...new Set([...(request.holds ?? []), ...gated])]
-
-  const held = new Set<string>(holds)
-  const raised = (signal: string): boolean => held.has(signal)
-
-  const a11y: Record<string, string | boolean | number> = {}
-  if (raised('loading') || raised('pending')) a11y['aria-busy'] = true
-
-  const marks: Record<string, boolean> = {}
-  for (const one of holds) {
-    const selector = selectorOf(one) ?? (asking ?? []).find((row) => row.id === one)?.selector
-    if (selector === undefined || !selector.startsWith('[data-')) continue
-    marks[selector.slice(1, -1)] = true
-  }
-
-  const [arriving, setArriving] = useState(true)
-  if (arriving) marks['data-arriving'] = true
-
-  const began = useRef(false)
-  useEffect(() => {
-    if (!arriving) return undefined
-    let live = true
-    const outer = requestAnimationFrame(() => {
-      requestAnimationFrame(() => {
-        if (live && !began.current) setArriving(false)
-      })
-    })
-    return () => {
-      live = false
-      cancelAnimationFrame(outer)
-    }
-  }, [arriving])
-
-  const measures: Record<string, string | number> = {}
-  for (const [name, value] of Object.entries(request.measures ?? {})) measures[`--${name}`] = value
-
-  const asked = request.invokes
-  const named: keyof Dispatching | undefined = asked?.dispatch
-  const carried = asked?.input
-  const when = asked?.on ?? 'press'
-
-  useEffect(() => {
-    if (named === undefined || when !== 'shown') return
-    if (asking === undefined) return
-    void run?.(named, carried)
-  }, [named, when, carried, run, asking])
-
-  const invokes: Record<string, unknown> = {
-
-    onAnimationStart: (event: { readonly target: unknown; readonly currentTarget: unknown }) => {
-      if (event.target !== event.currentTarget) return
-      began.current = true
-    },
-    onAnimationEnd: (event: { readonly target: unknown; readonly currentTarget: unknown }) => {
-      if (event.target !== event.currentTarget) return
-      setArriving(false)
-    },
-    ...(named === undefined || when === 'shown'
-      ? {}
-      : {
-          onClick: () => {
-            if (run === undefined) throw new Error(`\`${named}\` cannot be invoked from here — no dispatch is wired`)
-            void run(named, carried)
-          },
-        }),
-  }
-
-  return {
-    ...(request.className === undefined ? {} : { className: request.className }),
-    holds,
-    marks,
-    measures,
-    invokes,
-
-    marked: raised,
-    text: translate,
-    a11y,
-    t: animates ? t : 0,
-  }
-}
-
-export type Press =
-  | { readonly dispatch: keyof Dispatching; readonly input?: Readonly<Record<string, unknown>>; readonly navigateTo?: never; readonly onPress?: never }
-  | { readonly navigateTo: string; readonly dispatch?: never; readonly input?: never; readonly onPress?: never }
-  | { readonly onPress: () => void; readonly dispatch?: never; readonly navigateTo?: never; readonly input?: never }
-  | { readonly dispatch?: never; readonly navigateTo?: never; readonly input?: never; readonly onPress?: never }
-
-export function pressOf(props: {
-  readonly dispatch?: keyof Dispatching
-  readonly input?: Readonly<Record<string, unknown>>
-  readonly navigateTo?: string
-  readonly onPress?: () => void
-}): Press {
-  if (props.onPress !== undefined) return { onPress: props.onPress }
-  if (props.navigateTo !== undefined) return { navigateTo: props.navigateTo }
-  if (props.dispatch === undefined) return {}
-  return props.input === undefined ? { dispatch: props.dispatch } : { dispatch: props.dispatch, input: props.input }
-}
-
-export interface PressOrigin {
-
-  readonly element: string
-
-  readonly name?: string
-}
-
-const NO_DISPATCH =
-  'No dispatch. An operation runs one way here and that way is `dispatch`, handed the name, so a thing that names ' +
-  'one must render inside a <UiProvider> whose config supplies it. Without it the press has nowhere to go, which ' +
-  'reads as a dead control and is a wiring gap.'
-
-const NO_NAVIGATE =
-  'No navigateTo. Moving between screens is its own thing, supplied beside dispatch rather than through it, so a ' +
-  'thing that names a screen must render inside a <UiProvider> whose config supplies it.'
-
-export function pressing(ui: ReturnType<typeof useUi>, press: Press, origin?: PressOrigin): (() => void) | undefined {
-  const { collector, dispatch, navigateTo } = ui
-  const asked: keyof Dispatching | undefined = press.dispatch
-  const carried = press.input
-
-  const reported = (run: () => void): (() => void) => {
-    if (collector === undefined || origin === undefined) return run
-    return () => {
-      collector.record({
-        property: 'interaction',
-        element: origin.element,
-        ...(origin.name === undefined ? {} : { name: origin.name }),
-        action: 'pressed',
-      })
-      run()
-    }
-  }
-
-  if (press.onPress !== undefined) return reported(press.onPress)
-
-  if (press.navigateTo !== undefined) {
-    const where = press.navigateTo
-    return reported(() => {
-      if (navigateTo === undefined) throw new Error(NO_NAVIGATE)
-      navigateTo(where)
-    })
-  }
-
-  if (asked !== undefined) {
-    return reported(() => {
-      if (dispatch === undefined) throw new Error(NO_DISPATCH)
-      void dispatch(asked, carried)
-    })
-  }
-
-  return undefined
-}
-
-export function usePress(press: Press, origin?: PressOrigin): (() => void) | undefined {
-  return pressing(useUi(), press, origin)
-}
-
-export function useVisibility(active: boolean): (node: HTMLElement | null) => void {
-  const { clock } = useUi()
-  return useMemo(() => {
-    return (node: HTMLElement | null): void => {
-      if (!active || node === null || typeof IntersectionObserver !== 'function') return
-
-      const observer = new IntersectionObserver(([entry]) => {
-        clock.setVisible(entry?.isIntersecting ?? true)
-      })
-      observer.observe(node)
-    }
-  }, [active, clock])
-}
-
-export interface ScreenOptions {
-  readonly as?: Presentation
-  readonly views?: readonly (keyof Dispatching)[]
-
-  readonly unreachable?: boolean
-}
-
-type Component<P> = (props: P) => ReactNode
-
-export type ElementBody<P> = (props: P, className?: string) => ReactNode
-
-function wearing(held: string | undefined, added: string | undefined): string | undefined {
-  if (added === undefined) return held
-  return held === undefined || held === '' ? added : `${held} ${added}`
-}
-
-type Members<N extends string, P> = {
-  readonly [K in
-    | VariantsFor<N>
-    | { [W in keyof Wearing]: N extends Wearing[W] ? W : never }[keyof Wearing]]: Component<
-    P & { readonly at?: string }
-  >
-}
-
-export type Element<N extends string, P> = [keyof Members<N, P>] extends [never]
-  ? Component<P & { readonly at?: string }>
-  : N extends ArrangementElement
-    ? Component<P & { readonly at?: string }> & Members<N, P>
-    : Members<N, P>
-
-export function element<N extends string, P>(
-  name: N,
-  fn: ElementBody<P>,
-  own: string,
-  wears: Readonly<Record<string, string>>,
-): Element<N, P> {
-
-  const Made = (props: P & { readonly className?: string }): ReactNode => fn(props, wearing(own, props.className))
-  named(Made, name)
-
-  for (const [member, dressed] of Object.entries(wears)) {
-    const worn = wearing(own, dressed)
-    const Worn = (props: P & { readonly className?: string }): ReactNode =>
-      fn(props, wearing(worn, props.className))
-    named(Worn, `${name}.${member}`)
-    Object.defineProperty(Made, member, { value: Worn, enumerable: false, configurable: true })
-  }
-
-  return Made as unknown as Element<N, P>
-}
-
-function named(component: unknown, value: string): void {
-  Object.defineProperty(component, 'displayName', { value, enumerable: false, configurable: true })
-}
-
-export function composition<P>(
-  own: string,
-  fn: (props: P) => ReactNode,
-): Component<P & { readonly at?: string; readonly className?: string }> {
-
-  const Made = (props: P & { readonly className?: string }): ReactNode => (
-    <div className={wearing(own, props.className)}>{fn(props)}</div>
-  )
-  named(Made, own)
-  return Made
-}
-
-export interface ScreenControls {
-
-  readonly open?: boolean
-  readonly onDismiss?: () => void
-
-  readonly at?: string
-}
-
-const ViewsContext = createContext<Readonly<Record<string, unknown>> | null>(null)
-
-const NO_SCREEN =
-  'No screen. A view is read for the screen that binds it, so anything reading one renders inside a screen, ' +
-  'and a body outside every screen has nothing to read from.'
-
-export function useView<T>(id: string): T | undefined {
-  const held = useContext(ViewsContext)
-  if (held === null) throw new Error(NO_SCREEN)
-  const named = Object.keys(held)
-  if (!named.includes(id)) {
-    throw new Error(
-      `"${id}" is not a view this screen shows. A screen states every read it binds in its own views list, ` +
-        `and this one states ${named.length === 0 ? 'none' : named.join(', ')}. Name it there — nothing fetches on its own.`,
-    )
-  }
-  return held[id] as T | undefined
-}
-
-function useViews(views: readonly (keyof Dispatching)[]): Readonly<Record<string, unknown>> {
-  const { dispatch } = useUi()
-  const named = views.join(' ')
-  const [held, setHeld] = useState<Readonly<Record<string, unknown>>>({})
-  const [wrong, setWrong] = useState<Error | undefined>(undefined)
-
-  useEffect(() => {
-    if (views.length === 0) return undefined
-    if (dispatch === undefined) throw new Error(NO_DISPATCH)
-    let live = true
-    void Promise.all(views.map(async (one: keyof Dispatching) => [one, await dispatch(one)] as const))
-      .then((all) => {
-        if (live) setHeld(Object.fromEntries(all))
-      })
-      .catch((thrown: unknown) => {
-        if (live) setWrong(thrown instanceof Error ? thrown : new Error(String(thrown)))
-      })
-    return () => {
-      live = false
-    }
-  }, [named, dispatch])
-
-  const all = useMemo(() => {
-    const found: Record<string, unknown> = {}
-    for (const one of views) found[one] = held[one]
-    return found
-  }, [named, held])
-
-  if (wrong !== undefined) throw wrong
-  return all
-}
-
-export function screen<P>(own: string, options: ScreenOptions, fn: Component<P>): Component<P & ScreenControls> {
-  const Screen = (props: P & ScreenControls): ReactNode => {
-
-    useRenderLoopDetector(own, props as Record<string, unknown>)
-
-    const shown = useViews(options.views ?? [])
-
-    const laid = (
-      <ViewsContext.Provider value={shown}>
-        <div className={own}>{fn(props)}</div>
-      </ViewsContext.Provider>
-    )
-
-    if (options.as === undefined) return laid
-
-    return (
-      <Presented
-        presentation={options.as}
-        {...(props.open === undefined ? {} : { open: props.open })}
-        {...(props.onDismiss === undefined ? {} : { onDismiss: props.onDismiss })}
-      >
-        {laid}
-      </Presented>
-    )
-  }
-  Screen.displayName = own
-  return Screen
-}
-
-export function behaviourOf(presentation: Presentation): (typeof PRESENTATION_BEHAVIOUR)[Presentation] {
-  return PRESENTATION_BEHAVIOUR[presentation]
-}