@prestack/thread-ui 0.0.1 → 0.0.2

package/dist/ui/series.ts

@@ -0,0 +1,97 @@
+import { contrast, CONTRAST_LARGE } from './contrast.ts'
+
+const GOLDEN_ANGLE = 137.508
+
+const toLinear = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const toSrgb = (c: number): number => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)
+
+function parseHex(hex: string): [number, number, number] {
+  const clean = hex.replace('#', '')
+  const full = clean.length === 3 ? clean.split('').map((c) => c + c).join('') : clean.slice(0, 6)
+  const n = Number.parseInt(full, 16)
+  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255]
+}
+
+function toHex(r: number, g: number, b: number): string {
+  const channel = (v: number): string =>
+    Math.round(Math.min(1, Math.max(0, v)) * 255)
+      .toString(16)
+      .padStart(2, '0')
+  return `#${channel(r)}${channel(g)}${channel(b)}`
+}
+
+export interface Oklch {
+
+  readonly l: number
+
+  readonly c: number
+
+  readonly h: number
+}
+
+export function hexToOklch(hex: string): Oklch {
+  const [r8, g8, b8] = parseHex(hex)
+  const r = toLinear(r8)
+  const g = toLinear(g8)
+  const b = toLinear(b8)
+
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+
+  const lab = {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  }
+
+  const hue = (Math.atan2(lab.b, lab.a) * 180) / Math.PI
+  return { l: lab.L, c: Math.hypot(lab.a, lab.b), h: hue < 0 ? hue + 360 : hue }
+}
+
+export function oklchToHex({ l: L, c: C, h }: Oklch): string {
+  const rad = (h * Math.PI) / 180
+  const a = C * Math.cos(rad)
+  const b = C * Math.sin(rad)
+
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3
+
+  return toHex(
+    toSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    toSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    toSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+  )
+}
+
+export function seriesRamp(accent: string, surface: string, count: number): readonly string[] {
+  const base = hexToOklch(accent)
+  const out: string[] = []
+
+  for (let i = 0; i < count; i += 1) {
+    const hue = (base.h + GOLDEN_ANGLE * i) % 360
+    out.push(oklchToHex(readable({ ...base, h: hue }, surface)))
+  }
+  return out
+}
+
+function readable(colour: Oklch, surface: string): Oklch {
+  if (contrast(oklchToHex(colour), surface) >= CONTRAST_LARGE) return colour
+
+  const surfaceL = hexToOklch(surface).l
+
+  const direction = surfaceL > 0.5 ? -1 : 1
+
+  let best = colour
+  for (let step = 1; step <= 24; step += 1) {
+    const candidate = { ...colour, l: Math.min(0.98, Math.max(0.02, colour.l + direction * step * 0.02)) }
+    best = candidate
+    if (contrast(oklchToHex(candidate), surface) >= CONTRAST_LARGE) return candidate
+  }
+  return best
+}
+
+export function seriesColour(ramp: readonly string[], index: number): string {
+  return ramp[index % ramp.length] ?? ramp[0] ?? '#888888'
+}

package/dist/ui/signals.ts

@@ -0,0 +1,386 @@
+
+
+import type { Threaded } from '@prestack/thread/core/thread'
+
+export interface SignalEntry {
+
+  readonly name: (typeof holds)[number]['id']
+
+  readonly means: string
+}
+
+const here = 'thread/ui/signals.ts'
+
+const kebab = (id: string): string => id.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+
+const raised = <Id extends string>(
+  id: Id,
+  describes: string,
+  selector?: string,
+): Omit<Threaded, 'at' | 'id'> & { readonly id: Id; readonly selector: string } => ({
+  id,
+  describes,
+  version: 1,
+  selector: selector ?? `[data-${kebab(id)}]`,
+})
+
+export const holds = [
+  raised('hover', 'A pointer is over this element with no button held. The browser knows this one and sets it itself.', ':hover'),
+  raised('active', 'A pointer is held down on this element. The browser sets it, and it is NOT the press gesture, which has to survive a dwell.', ':active'),
+  raised('focus', 'Keyboard focus is on this element and the browser judges it worth showing a ring for. Uses focus-visible, so a mouse click does not draw one.', ':focus-visible'),
+  raised('disabled', 'This element refuses interaction. The browser sets it from the disabled attribute, which also takes it out of the focus order.', ':disabled'),
+  raised('invalid', 'The value in this element is wrong, and the browser or the validator has said so.', ':invalid'),
+  raised('loading', 'A read this element depends on has not answered yet.'),
+  raised('leaving', 'This element has been dismissed and is still on the page while it goes. The one signal nothing outside sets: whatever removes the thing raises it, keeps the element mounted for exactly as long as its exit takes, and then lets go. Without it an exit can be declared and can never run, because a thing already removed from the page has nothing left to animate.'),
+  raised('arriving', 'This element has just been made and its entrance has not finished. The mirror of `leaving`, and it exists for the same reason that one does: an entrance was emitted as a plain `animation` on the class, on the stated grounds that "a class carrying an `animation` plays it the moment the element exists, which is exactly once". That is not what a browser does. It plays it every time the node is inserted — and React reorders keyed children by moving the existing nodes, which the DOM performs as a remove and an insert — so moving one card in a board replayed the entrance of every card that shifted under it. It also replays whenever a state rule stops winning and the resting `animation` declaration becomes the one in force again, which happens the instant a drag ends. Nothing raises this but the element itself: it is on from the moment it is made until its own entrance ends, and it is never set again, so a node that is moved afterwards has nothing left to play.'),
+  raised('carrying', 'This hit box is the SOURCE of the drag in progress. What "it lifted off the page" reads.'),
+  raised('draggedOver', 'A drag is over this hit box and this hit box accepts what is being carried. What the glow, the border and the gap-opening read.'),
+  raised('refusing', 'A drag is over this hit box and it does NOT accept the subject. The half every app hand-writes, so "you cannot drop here" is shown rather than merely not working.'),
+  raised('tapped', 'A tap completed on this hit box — true for the one frame that recognised it.'),
+  raised('doubleTapped', 'A second tap landed inside the gap — true for the one frame that recognised it.'),
+  raised('pressing', 'A press has been recognised on this hit box — held past its dwell, not merely touched.'),
+  raised('dragging', 'A drag has been recognised on this hit box and the pointer is still down.'),
+  raised('swiping', 'A swipe is under way — far enough to count, not yet released.'),
+  raised('pinching', 'Two pointers on this hit box are changing their distance.'),
+  raised('rotating', 'Two pointers on this hit box are changing their angle.'),
+
+  raised('spinner', 'This element is a turning indicator, for as long as it is on screen. Held rather than raised — nothing starts it and nothing stops it.'),
+  raised('empty', 'This element is what a surface says when its read answered with nothing. Held rather than raised, like `spinner` — it is what the thing IS, not something that happened to it.'),
+
+  raised('scrolling', 'This grouping scrolls its own content rather than growing to fit it. Held rather than raised: it is how the box was declared, not something that happens to it.'),
+] as const satisfies readonly (Omit<Threaded, 'at'> & { readonly selector: string })[]
+
+export function selectorOf(name: string): string | undefined {
+  const shipped = holds.find((one) => one.id === name)
+  if (shipped !== undefined) return shipped.selector
+  if (name === '') return undefined
+  return `[data-${kebab(name)}]`
+}
+
+export const SIGNALS: Threaded & {
+  readonly holds: readonly (Omit<Threaded, 'at'> & { readonly selector: string })[]
+} = {
+  id: 'signal',
+  at: here,
+  describes:
+    'Every truth an element can be in, in one sheet. A signal is a yes-or-no fact — being pressed, loading, dragged over — and a variant declares how it looks when one is true, or when several are true at once. A signal is declared here before anything may name it; nothing brings one into existence by running.',
+  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.',
+    },
+  ],
+  holds,
+}
+
+export const EXCLUSIVE: readonly (readonly string[])[] = [
+  ['carrying', 'draggedOver', 'refusing'],
+  ['disabled', 'pressing'],
+
+  ['disabled', 'focus'],
+
+  ['disabled', 'active'],
+
+  ['tapped', 'doubleTapped', 'pressing', 'dragging', 'swiping', 'pinching', 'rotating'],
+
+  ['carrying', 'tapped'],
+  ['carrying', 'doubleTapped'],
+]
+
+export function coexist(one: string, other: string): boolean {
+  return !EXCLUSIVE.some((group) => group.includes(one) && group.includes(other))
+}
+
+const declaredByApp = new Set<string>()
+
+export function knowSignals(names: readonly string[]): void {
+  for (const one of names) if (!holds.some((each) => each.id === one)) declaredByApp.add(one)
+}
+
+export function signalNames(): readonly string[] {
+  return [...holds.map((one) => one.id), ...declaredByApp]
+}
+
+export function isSignal(name: string): boolean {
+  return holds.some((one) => one.id === name) || declaredByApp.has(name)
+}
+
+export interface PointerSample {
+
+  readonly id: number
+
+  readonly x: number
+  readonly y: number
+
+  readonly startX: number
+  readonly startY: number
+
+  readonly held: number
+
+  readonly down: boolean
+}
+
+export interface GestureFrame {
+
+  readonly pointers: readonly PointerSample[]
+
+  readonly t: number
+
+  readonly sinceRelease: number
+
+  readonly params: Readonly<Record<string, number>>
+}
+
+export type GesturePhase = 'idle' | 'active' | 'done'
+
+export interface Recognition {
+  readonly phase: GesturePhase
+
+  readonly values?: Readonly<Record<string, number>>
+}
+
+export const IDLE: Recognition = { phase: 'idle' }
+
+export interface GestureEntry {
+  readonly name: string
+
+  readonly means: string
+
+  readonly pointers: number
+
+  readonly raises: readonly SignalEntry[]
+
+  readonly produces?: readonly string[]
+
+  readonly recognise: (frame: GestureFrame) => Recognition
+}
+
+const GESTURES = new Map<string, GestureEntry>()
+
+export function defineGesture(entry: GestureEntry): GestureEntry {
+  if (GESTURES.has(entry.name)) throw new Error(`gesture "${entry.name}" is already defined`)
+  if (entry.raises.length === 0) {
+    throw new Error(
+      `gesture "${entry.name}" raises no signal, so nothing could react to it. Give it at least one — ` +
+        'that signal is its entire contract with the style system.',
+    )
+  }
+  if (entry.pointers < 1) throw new Error(`gesture "${entry.name}" needs at least one pointer`)
+
+  for (const signal of entry.raises) {
+    if (isSignal(signal.name)) continue
+    throw new Error(
+      `gesture "${entry.name}" raises "${signal.name}", and no signal by that name is declared. ` +
+        `Declared: ${signalNames().join(' · ')}. Add the row to the sheet first.`,
+    )
+  }
+  GESTURES.set(entry.name, entry)
+  return entry
+}
+
+export function gestures(): readonly GestureEntry[] {
+  return [...GESTURES.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+}
+
+export function gestureFor(name: string): GestureEntry | undefined {
+  return GESTURES.get(name)
+}
+
+export function isGesture(name: string): boolean {
+  return GESTURES.has(name)
+}
+
+export function gestureNames(): readonly string[] {
+  return gestures().map((g) => g.name)
+}
+
+export function recognise(name: string, frame: GestureFrame): Recognition {
+  const entry = GESTURES.get(name)
+  if (entry === undefined) {
+    throw new Error(`unknown gesture "${name}". Registered: ${gestureNames().join(' · ') || '(none)'}`)
+  }
+  if (frame.pointers.length < entry.pointers) return IDLE
+
+  for (const p of frame.pointers) {
+    if (!Number.isFinite(p.x) || !Number.isFinite(p.y) || !Number.isFinite(p.startX) || !Number.isFinite(p.startY) || !Number.isFinite(p.held)) {
+      return IDLE
+    }
+  }
+  return entry.recognise(frame)
+}
+
+const distance = (dx: number, dy: number): number => Math.sqrt(dx * dx + dy * dy)
+
+const PRESS_SLOP = 10
+
+const PRESS_DWELL = 0.4
+
+const DRAG_THRESHOLD = 8
+
+const TAP_WITHIN = PRESS_DWELL
+
+const DOUBLE_TAP_GAP = 0.3
+
+const SWIPE_DISTANCE = 24
+const SWIPE_SPEED = 300
+
+function registerBuiltinGestures(): void {
+  defineGesture({
+    name: 'tap',
+    means: 'One pointer, down and up quickly without moving. The gesture people perform most.',
+    pointers: 1,
+    produces: ['tapHeld'],
+    raises: [{ name: 'tapped', means: 'A tap completed on this hit box — true for the one frame that recognised it.' }],
+    recognise: ({ pointers, params }) => {
+      const p = pointers[0]
+      if (p === undefined) return IDLE
+      if (distance(p.x - p.startX, p.y - p.startY) > (params['slop'] ?? PRESS_SLOP)) return IDLE
+
+      if (p.down) return IDLE
+      return p.held <= (params['within'] ?? TAP_WITHIN) ? { phase: 'done', values: { tapHeld: p.held } } : IDLE
+    },
+  })
+
+  defineGesture({
+    name: 'doubleTap',
+    means: 'A tap whose predecessor was inside the gap. Zoom-to-fit, like, expand.',
+    pointers: 1,
+    produces: ['tapGap'],
+    raises: [{ name: 'doubleTapped', means: 'A second tap landed inside the gap — true for the one frame that recognised it.' }],
+    recognise: ({ pointers, params, sinceRelease }) => {
+      const p = pointers[0]
+      if (p === undefined || p.down) return IDLE
+      if (distance(p.x - p.startX, p.y - p.startY) > (params['slop'] ?? PRESS_SLOP)) return IDLE
+      if (p.held > (params['within'] ?? TAP_WITHIN)) return IDLE
+
+      return sinceRelease <= (params['gap'] ?? DOUBLE_TAP_GAP) ? { phase: 'done', values: { tapGap: sinceRelease } } : IDLE
+    },
+  })
+
+  defineGesture({
+    name: 'press',
+    means: 'One pointer, held in place past a dwell. Long-press is this with a longer `after`.',
+    pointers: 1,
+    produces: ['held'],
+    raises: [{ name: 'pressing', means: 'A press has been recognised on this hit box — held past its dwell, not merely touched.' }],
+    recognise: ({ pointers, params }) => {
+      const p = pointers[0]
+      if (p === undefined) return IDLE
+
+      if (distance(p.x - p.startX, p.y - p.startY) > (params['slop'] ?? PRESS_SLOP)) return IDLE
+      if (p.held < (params['after'] ?? PRESS_DWELL)) return IDLE
+      return { phase: p.down ? 'active' : 'done', values: { held: p.held } }
+    },
+  })
+
+  defineGesture({
+    name: 'drag',
+    means: 'One pointer, down and moved past a threshold. Stays active until it lifts.',
+    pointers: 1,
+    produces: ['dragX', 'dragY', 'dragDistance'],
+    raises: [{ name: 'dragging', means: 'A drag has been recognised on this hit box and the pointer is still down.' }],
+    recognise: ({ pointers, params }) => {
+      const p = pointers[0]
+      if (p === undefined) return IDLE
+      const dx = p.x - p.startX
+      const dy = p.y - p.startY
+      const moved = distance(dx, dy)
+
+      if (moved < (params['threshold'] ?? DRAG_THRESHOLD)) return IDLE
+      return { phase: p.down ? 'active' : 'done', values: { dragX: dx, dragY: dy, dragDistance: moved } }
+    },
+  })
+
+  defineGesture({
+    name: 'swipe',
+    means: 'One pointer, moved far and released FAST. Commits on velocity, so it needs no target.',
+    pointers: 1,
+    produces: ['swipeX', 'swipeY', 'swipeSpeed'],
+    raises: [{ name: 'swiping', means: 'A swipe is under way — far enough to count, not yet released.' }],
+    recognise: ({ pointers, params }) => {
+      const p = pointers[0]
+      if (p === undefined) return IDLE
+      const dx = p.x - p.startX
+      const dy = p.y - p.startY
+      const travelled = distance(dx, dy)
+      if (travelled < (params['threshold'] ?? SWIPE_DISTANCE)) return IDLE
+      const speed = p.held > 0 ? travelled / p.held : 0
+      const values = { swipeX: dx, swipeY: dy, swipeSpeed: speed }
+      if (p.down) return { phase: 'active', values }
+
+      return speed >= (params['speed'] ?? SWIPE_SPEED) ? { phase: 'done', values } : IDLE
+    },
+  })
+
+  defineGesture({
+    name: 'pinch',
+    means: 'Two pointers changing their distance. Produces a scale relative to where they started.',
+    pointers: 2,
+    produces: ['pinchScale'],
+    raises: [{ name: 'pinching', means: 'Two pointers on this hit box are changing their distance.' }],
+    recognise: ({ pointers }) => {
+      const [a, b] = pointers
+      if (a === undefined || b === undefined) return IDLE
+      const began = distance(a.startX - b.startX, a.startY - b.startY)
+
+      if (began === 0) return IDLE
+      const now = distance(a.x - b.x, a.y - b.y)
+      return { phase: a.down && b.down ? 'active' : 'done', values: { pinchScale: now / began } }
+    },
+  })
+
+  defineGesture({
+    name: 'rotate',
+    means: 'Two pointers changing their angle. Produces radians turned since they went down.',
+    pointers: 2,
+    produces: ['rotateAngle'],
+    raises: [{ name: 'rotating', means: 'Two pointers on this hit box are changing their angle.' }],
+    recognise: ({ pointers }) => {
+      const [a, b] = pointers
+      if (a === undefined || b === undefined) return IDLE
+      const began = Math.atan2(a.startY - b.startY, a.startX - b.startX)
+      const now = Math.atan2(a.y - b.y, a.x - b.x)
+
+      let turned = now - began
+      while (turned > Math.PI) turned -= 2 * Math.PI
+      while (turned <= -Math.PI) turned += 2 * Math.PI
+      return { phase: a.down && b.down ? 'active' : 'done', values: { rotateAngle: turned } }
+    },
+  })
+}
+
+registerBuiltinGestures()
+
+export interface SignalIssue {
+  readonly path: string
+  readonly message: string
+}
+
+export function checkInteractions(): readonly SignalIssue[] {
+  const issues: SignalIssue[] = []
+  const producers = new Map<string, string>()
+
+  for (const gesture of gestures()) {
+    for (const value of gesture.produces ?? []) {
+      const owner = producers.get(value)
+      if (owner !== undefined) {
+        issues.push({
+          path: `gestures.${gesture.name}.produces`,
+          message: `"${value}" is produced by both "${owner}" and "${gesture.name}" — a driver reading it would get whichever recognised last`,
+        })
+      }
+      producers.set(value, gesture.name)
+    }
+
+    for (const signal of gesture.raises) {
+      if (isSignal(signal.name)) continue
+      issues.push({
+        path: `gestures.${gesture.name}.raises`,
+        message: `"${signal.name}" is raised by "${gesture.name}" and no row on the signal sheet declares it`,
+      })
+    }
+  }
+
+  return issues
+}