@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/roving-focus.ts

@@ -0,0 +1,161 @@
+'use client'
+
+import { useCallback, useEffect, useRef, type RefObject } from 'react'
+
+export const ITEM_ATTR = 'data-roving-item'
+
+export interface RovingOptions {
+  readonly orientation: 'vertical' | 'horizontal'
+
+  readonly wrap?: boolean
+  readonly active?: boolean
+}
+
+interface Item {
+  readonly element: HTMLElement
+  readonly disabled: boolean
+  readonly text: string
+}
+
+function items(root: HTMLElement | null): readonly Item[] {
+  if (root === null) return []
+  return [...root.querySelectorAll<HTMLElement>(`[${ITEM_ATTR}]`)].map((element) => ({
+    element,
+
+    disabled: element.hasAttribute('disabled') || element.getAttribute('aria-disabled') === 'true',
+    text: (element.textContent ?? '').trim().toLowerCase(),
+  }))
+}
+
+function step(list: readonly Item[], from: number, direction: 1 | -1, wrap: boolean): number {
+  const count = list.length
+  if (count === 0) return -1
+  let index = from
+  for (let moved = 0; moved < count; moved += 1) {
+    const next = index + direction
+    if (next < 0 || next >= count) {
+      if (!wrap) return from
+      index = direction === 1 ? 0 : count - 1
+    } else {
+      index = next
+    }
+    if (!(list[index] as Item).disabled) return index
+  }
+  return from
+}
+
+function firstEnabled(list: readonly Item[], from = 0): number {
+  for (let i = from; i < list.length; i += 1) if (!(list[i] as Item).disabled) return i
+  return -1
+}
+
+function lastEnabled(list: readonly Item[]): number {
+  for (let i = list.length - 1; i >= 0; i -= 1) if (!(list[i] as Item).disabled) return i
+  return -1
+}
+
+function isRtl(element: HTMLElement): boolean {
+  const declared = element.closest('[dir]')?.getAttribute('dir')?.toLowerCase()
+  if (declared === 'rtl') return true
+  if (declared === 'ltr') return false
+  return getComputedStyle(element).direction === 'rtl'
+}
+
+const TYPEAHEAD_MS = 1000
+
+export function typeaheadMatch(list: readonly Item[], buffer: string, current: number): number {
+  const enabled = list.map((item, index) => ({ item, index })).filter(({ item }) => !item.disabled)
+  if (enabled.length === 0 || buffer.length === 0) return -1
+
+  const repeated = buffer.length > 1 && [...buffer].every((c) => c === buffer[0])
+  const prefix = repeated ? (buffer[0] as string) : buffer
+
+  const startAt = enabled.findIndex(({ index }) => index === current)
+  for (let i = 0; i < enabled.length; i += 1) {
+    const candidate = enabled[(startAt + 1 + i) % enabled.length] as { item: Item; index: number }
+    if (candidate.item.text.startsWith(prefix)) return candidate.index
+  }
+  return -1
+}
+
+export function useRovingFocus(ref: RefObject<HTMLElement | null>, options: RovingOptions): void {
+  const { orientation, wrap = false, active = true } = options
+  const indexRef = useRef(0)
+  const bufferRef = useRef('')
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  const applyTabIndex = useCallback(
+    (list: readonly Item[], index: number): void => {
+      list.forEach((item, i) => {
+        item.element.setAttribute('tabindex', i === index ? '0' : '-1')
+      })
+    },
+    [],
+  )
+
+  useEffect(() => {
+    if (!active) return
+    const root = ref.current
+    if (root === null) return
+
+    const list = items(root)
+    const start = firstEnabled(list)
+    indexRef.current = start === -1 ? 0 : start
+    applyTabIndex(list, indexRef.current)
+
+    const move = (to: number): void => {
+      const current = items(root)
+      if (to < 0 || to >= current.length) return
+      indexRef.current = to
+      applyTabIndex(current, to)
+      ;(current[to] as Item).element.focus()
+    }
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      const current = items(root)
+      if (current.length === 0) return
+
+      const rtl = isRtl(root)
+      const forward = orientation === 'horizontal' ? (rtl ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown'
+      const backward = orientation === 'horizontal' ? (rtl ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp'
+
+      if (event.key === forward) {
+        event.preventDefault()
+        move(step(current, indexRef.current, 1, wrap))
+        return
+      }
+      if (event.key === backward) {
+        event.preventDefault()
+        move(step(current, indexRef.current, -1, wrap))
+        return
+      }
+      if (event.key === 'Home') {
+        event.preventDefault()
+        move(firstEnabled(current))
+        return
+      }
+      if (event.key === 'End') {
+        event.preventDefault()
+        move(lastEnabled(current))
+        return
+      }
+
+      if (event.key.length !== 1 || event.ctrlKey || event.metaKey || event.altKey) return
+      event.preventDefault()
+      bufferRef.current += event.key.toLowerCase()
+      if (timerRef.current !== undefined) clearTimeout(timerRef.current)
+      timerRef.current = setTimeout(() => {
+        bufferRef.current = ''
+      }, TYPEAHEAD_MS)
+
+      const found = typeaheadMatch(current, bufferRef.current, indexRef.current)
+      if (found !== -1) move(found)
+    }
+
+    root.addEventListener('keydown', onKeyDown)
+    return () => {
+      root.removeEventListener('keydown', onKeyDown)
+      if (timerRef.current !== undefined) clearTimeout(timerRef.current)
+    }
+  }, [active, orientation, wrap, ref, applyTabIndex])
+}

package/dist/ui/screens.js

@@ -1,18 +1,10 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
-import { stdout } from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { existsSync, readFileSync, writeFileSync } from "@prestack/thread/core/files";
+import { basename, join } from 'node:path';
+import { argv, stdout } from 'node:process';
 import { exit, invoked } from "@prestack/thread/core/invoked";
+import { valuesIn } from "@prestack/thread/core/rows";
 import { findTree, inTree } from "@prestack/thread/core/tree";
-import { undeclared } from "./compositions.js";
+import { HOME, settled, undeclared } from "./compositions.js";
 import { PRESENTATIONS } from "./door.js";
 const here = 'thread/ui/screens.ts';
 const said = [
@@ -70,7 +62,7 @@ function starter(row) {
     const name = nameOf(row.at);
     return `'use client'
 
-import { screen } from './wrappers.tsx'
+import { screen } from '${HOME}/wrappers'
 
 export const ${name} = screen('${row.id}', {}, () => (
   <>
@@ -81,26 +73,34 @@ export const ${name} = screen('${row.id}', {}, () => (
 export function seeds(rows, held) {
     return rows.filter((row) => !held(row.at)).map((row) => ({ path: row.at, content: starter(row) }));
 }
-async function run() {
+function run() {
     const tree = findTree();
     const at = inTree(tree, 'screens.ts');
     if (!existsSync(at)) {
         stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no screen and there is nothing to seed or check.\n`);
         return 0;
     }
-    const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+    const held = valuesIn(readFileSync(at));
     if (held.SCREEN === undefined) {
         stdout.write(`thread: ${tree.name}/screens.ts exports no \`SCREEN\`, so nothing declares a screen here.\n`);
         return 1;
     }
     const rows = held.SCREEN.declares ?? [];
+    const checking = argv.includes('--check');
     const made = seeds(rows, (where) => existsSync(join(tree.at, where)));
-    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 unseeded = made[0];
+    if (checking && unseeded !== undefined) {
+        stdout.write(`thread: ${unseeded.path} is declared and the file is not there yet. A row names a file, and ` +
+            '`--check` never writes one — run `thread screens` and commit what it seeds.\n');
+        return 1;
+    }
+    if (!checking) {
+        for (const one of made) {
+            writeFileSync(join(tree.at, one.path), one.content, 'utf8');
+            stdout.write(`thread: seeded ${one.path}\n`);
+        }
     }
-    const loose = await undeclared(tree, rows);
+    const loose = [...undeclared(tree, rows), ...settled(tree.at, rows, checking, 'thread screens', new Set())];
     for (const one of loose)
         stdout.write(`thread: ${one}\n`);
     stdout.write(`thread: ${String(rows.length)} screen(s) declared, ${String(made.length)} seeded, ` +
@@ -109,4 +109,4 @@ async function run() {
     return loose.length === 0 ? 0 : 1;
 }
 if (invoked(import.meta.url))
-    exit(await run());
+    exit(run());

package/dist/ui/screens.ts

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, writeFileSync } from '@prestack/thread/core/files'
+import { basename, dirname, join } from 'node:path'
+import { argv, stdout } from 'node:process'
+
+import { exit, invoked } from '@prestack/thread/core/invoked'
+import { valuesIn } from '@prestack/thread/core/rows'
+import type { Threaded } from '@prestack/thread/core/thread'
+import { findTree, inTree } from '@prestack/thread/core/tree'
+
+import { HOME, settled, undeclared } from './compositions.ts'
+import { PRESENTATIONS } from './door.ts'
+
+const here = 'thread/ui/screens.ts'
+
+const said = [
+  {
+    on: '2026-08-25',
+    said: 'Screens are basically compositions arranged in a screen. And this is where we have breakpoint, etc. Compositions maybe also have breakpoints.',
+  },
+  {
+    on: '2026-08-25',
+    said: 'Arrangement is a real fucking thing. IT IS HOW THE STUFF LOOKS IN A SCREEN',
+  },
+  {
+    on: '2026-08-25',
+    said: 'Both',
+  },
+  {
+    on: '2026-09-09',
+    said: 'We have one screen or more. A button navigates to other screen. From THAT the routes are generated.',
+  },
+]
+
+export const declares: readonly Threaded[] = []
+
+export const SCREENS: Threaded & { readonly files: string } = {
+  id: 'screen',
+  at: here,
+  files: 'screens/scr_*.tsx',
+  describes:
+    'Compositions arranged, and the way it is presented: page, sheet, popover, overlay or toast. Where it lives is never typed. The first page an app declares answers `/`, every other page answers its own name, and a sheet, popover, overlay or toast has no route, because a press opens it where somebody already is. The arrangement is the whole of what a screen adds, because how things sit on a screen is declared rather than markup written twice. Each row names a file prefixed `scr_`, sets the properties that lay its compositions out, and may set them differently under a mode, which is where a breakpoint lives: a width is a media query the same way dark is. A composition may set its own arrangement too. The framework ships none, because what an app is made of is the app’s, and this row says what a screen is, never what is inside it.',
+  version: 1,
+  cites: said,
+  declares,
+}
+
+const PASCAL = (id: string): string =>
+  id
+    .split(/[-_]/)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('')
+
+export function nameOf(at: string): string {
+  const file = at.split('\\').join('/').split('/').at(-1) ?? at
+  return PASCAL(file.replace(/^scr_/, '').replace(/\.[^.]+$/, ''))
+}
+
+export const PAGE = PRESENTATIONS[0]
+
+const PRESENTED = /screen\(\s*'[^']*'\s*,\s*\{[^}]*as:\s*'([^']*)'/
+
+export function presentedIn(source: string): string {
+  return PRESENTED.exec(source)?.[1] ?? PAGE
+}
+
+export function routeFor(id: string, entry: boolean): string {
+  return entry ? '/' : `/${id}`
+}
+
+export function pageAt(route: string): string {
+  const trimmed = route.replace(/^\/+|\/+$/g, '')
+  return trimmed === '' ? `app/page.${'tsx'}` : `app/${trimmed}/page.${'tsx'}`
+}
+
+export function entryAmong(rows: readonly { readonly id: string }[], shownAs: (id: string) => string): string | undefined {
+  return rows.find((row) => shownAs(row.id) === PAGE)?.id
+}
+
+function starter(row: Threaded): string {
+  const name = nameOf(row.at)
+  return `'use client'
+
+import { screen } from '${HOME}/wrappers'
+
+export const ${name} = screen('${row.id}', {}, () => (
+  <>
+  </>
+))
+`
+}
+
+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) }))
+}
+
+function run(): number {
+  const tree = findTree()
+  const at = inTree(tree, 'screens.ts')
+  if (!existsSync(at)) {
+    stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no screen and there is nothing to seed or check.\n`)
+    return 0
+  }
+  const held = valuesIn(readFileSync(at)) as { SCREEN?: { readonly declares?: readonly Threaded[] } }
+
+  if (held.SCREEN === undefined) {
+    stdout.write(`thread: ${tree.name}/screens.ts exports no \`SCREEN\`, so nothing declares a screen here.\n`)
+    return 1
+  }
+
+  const rows = held.SCREEN.declares ?? []
+  const checking = argv.includes('--check')
+  const made = seeds(rows, (where) => existsSync(join(tree.at, where)))
+
+  const unseeded = made[0]
+  if (checking && unseeded !== undefined) {
+    stdout.write(
+      `thread: ${unseeded.path} is declared and the file is not there yet. A row names a file, and ` +
+        '`--check` never writes one — run `thread screens` and commit what it seeds.\n',
+    )
+    return 1
+  }
+
+  if (!checking) {
+    for (const one of made) {
+      writeFileSync(join(tree.at, one.path), one.content, 'utf8')
+      stdout.write(`thread: seeded ${one.path}\n`)
+    }
+  }
+
+  const loose = [...undeclared(tree, rows), ...settled(tree.at, rows, checking, 'thread screens', new Set<string>())]
+  for (const one of loose) stdout.write(`thread: ${one}\n`)
+
+  stdout.write(
+    `thread: ${String(rows.length)} screen(s) declared, ${String(made.length)} seeded, ` +
+      `${String(rows.length - made.length)} already written, ` +
+      `${loose.length === 0 ? 'none reaching anything undeclared' : `${String(loose.length)} reaching something undeclared`}\n`,
+  )
+  return loose.length === 0 ? 0 : 1
+}
+
+if (invoked(import.meta.url)) exit(run())

package/dist/ui/scroll-lock.ts

@@ -0,0 +1,28 @@
+import { nameOf } from './token.ts'
+
+
+
+let held = 0
+let previous: string | null = null
+
+export function lockScroll(): () => void {
+  if (held === 0) {
+    previous = document.body.style.overflow
+    document.body.style.overflow = `var(${nameOf('overflow-hidden')})`
+  }
+  held += 1
+
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    held -= 1
+    if (held > 0) return
+    document.body.style.overflow = previous ?? ''
+    previous = null
+  }
+}
+
+export function scrollLocks(): number {
+  return held
+}

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'
+}