@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/tokens.ts

@@ -0,0 +1,234 @@
+import { existsSync, readdirSync, writeFileSync } from '@prestack/thread/core/files'
+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 } from '@prestack/thread/core/tree'
+
+const here = 'thread/ui/tokens.ts'
+
+const said = [
+  {
+    on: '2026-08-24',
+    said: 'What I wanted is tokens be a list of variables. Not that tokens are the list of variables with values. The list of variables with default values is the style guide. So, tokens declare colour is a variable that can be used. A token is a row.',
+  },
+  {
+    on: '2026-08-24',
+    said: 'We want to do something more we declare a new variable row (which should also be able to be a function, I don\'t want this to be a limiting factor).',
+  },
+  {
+    on: '2026-08-28',
+    said: 'Fonts now are SSOT for fonts. So font is not a token anymore.',
+  },
+]
+
+const one = <Id extends string>(id: Id, describes: string): Omit<Threaded, 'at'> & { readonly id: Id } => ({
+  id,
+  describes,
+  version: 1,
+})
+
+const written = <Id extends string>(
+  id: Id,
+  describes: string,
+  at: string,
+): Threaded & { readonly id: Id } => ({ id, at, describes, version: 1 })
+
+export const holds = [
+  one('colour', 'Something that can be painted — a surface, a word, a line, a veil. The style guide says which colours an app has and what each one is; this only says an app may have them.'),
+  one('gradient', 'A fill that changes across the thing it fills. One value however many colours and stops it is made from, so a surface can be lit or shaded without a material writing the ramp itself.'),
+  one('texture', 'A pattern that repeats across a surface — stripes, dots, a weave, a grid. Structured and deliberate, which is what tells it from noise.'),
+  one('noise', 'Grain scattered across a surface with no pattern to it, which is what keeps a large flat area from reading as dead. Made by a filter rather than by a ramp.'),
+  one('img', 'A picture used as a surface rather than as content — a backdrop, a scan, anything too irregular to be generated.'),
+  one('space', 'Room, wherever room is measured: inside a thing, between two things, around a region. One scale answers all three so a gap and a padding cannot drift apart.'),
+  one('radius', 'How far a corner is turned. Ranges from square, which is a decision rather than an omission, to fully round.'),
+  one('ratio', 'The proportion a box keeps whatever its width, so a picture or a video holds its shape before it has loaded.'),
+  one('edge', 'How thick a boundary line is drawn, from the thinnest a screen can show to one doing deliberate work.'),
+  one('line', 'How a boundary line is drawn — unbroken, broken, or not drawn at all. Held apart from how thick it is, because a border can change manner without changing weight.'),
+  one('type', 'How large type is set. The one scale a reader judges every other size against.'),
+  one('weight', 'How heavy type is drawn, from unemphasised running text to the one line that must be read first.'),
+  one('leading', 'How far apart lines of type sit. Large type needs less than small type, which is why it is its own scale.'),
+  one('tracking', 'How far apart letters sit. The one scale that reverses: large type is set tighter and small type wider.'),
+  one('case', 'Whether wording is drawn as it was written or forced to one case. A visual choice, so it sits with the type it changes rather than with the words themselves.'),
+  one('blur', 'How much what lies behind a surface is softened. Saturation rides along with it, because a blur without it reads grey.'),
+  one('filter', 'What is done to a thing’s own pixels once it is drawn — dimmed, drained of colour, brightened. The sibling of blur, which does the same to whatever is behind it.'),
+  one('transform', 'How a thing is moved, scaled or turned from where it would otherwise sit. What a press or a lift is made of.'),
+  one('motion', 'How long a change takes. Ranges from none, which is a decision, to long enough that the movement is what tells a reader what happened.'),
+  one('ease', 'How a change is paced across its duration — where it hurries, where it settles, whether it overshoots.'),
+  one('layer', 'What sits in front of what, where two things occupy the same place on a screen.'),
+  one('cursor', 'What the pointer becomes over a thing, which is how a screen says what pressing will do before anybody presses.'),
+  one('animation', 'Which movement a thing plays. A value of this kind names an animation the app declares, and the name is the whole of it — how long it takes and how it is paced belong to the animation rather than to the naming of one.'),
+  one('icon', 'How large a pictogram is drawn, from one sitting inside a line of text to one standing on its own as the content.'),
+  one('control', 'How tall something pressable is. The floor here is what makes a target reachable by a thumb rather than only by a cursor.'),
+  one('opacity', 'How present a thing is without being removed — faded because it is unavailable, or receded because it is not being attended to.'),
+  one('layout', 'How a thing arranges what is inside it. Founder, 2026-08-31: "Seems like they might be tokens right? Like...tokens of the layout kind? ANd then styleguide holds rows for them, and variant names the rows instead of values." Until this existed a variant wrote the CSS word itself, checked against a list of four properties and seven words that carried no reasoning and no citation — the last place in a variant where a value was not a row.'),
+  one('flow', 'Which way the children run — across, or down. Held apart from `layout` because an arrangement and its direction change independently: the same row of things becomes a column at a narrow width without ceasing to be an arrangement.'),
+  one('align', 'How the children line up across the flow — centred, gathered at the start or the end, or stretched to fill. The axis `flow` does not speak for.'),
+  one('wrap', 'Whether the children spill onto another line when they run out of room, or stay on one and let it overflow.'),
+
+  one('position', 'What a thing is placed against, and whether the page keeps its room once it moves. Nearly everything is laid where the page put it and takes its own space; the rest lift out of that in one of three ways, and lifting out is what makes covering something else possible at all.'),
+  one('visibility', 'Whether a thing is rendered, as against how present it looks. Held apart from `opacity` because they differ in what a person can still do: something faded to nothing is reachable and still read aloud, something hidden is neither, and both keep the room they were given.'),
+  one('reach', 'Whether a pointer can touch a thing at all — whether a press, a hover or a drag lands on it or falls through to what is behind. What a decoration drawn over a control needs, so the control underneath stays pressable.'),
+  one('picking', 'Whether the wording inside can be taken — selected, dragged across, copied. Prose wants this and a control does not: a label that selects itself mid-drag is how a button turns into a smear of highlight.'),
+  one('touch', 'What a finger dragged across a thing does — scrolls the page past it, scrolls along one axis only, or is the thing\'s own to interpret. What lets a thing be dragged on a phone without the page sliding away underneath it.'),
+  one('readying', 'What a thing warns the browser it is about to change, so the preparing happens before the movement rather than inside its first frame. A hint and nothing else: it changes no appearance, and a thing that names one and never changes has asked for work nobody uses.'),
+  one('origin', 'The point a thing turns, scales and skews about. Nothing at all until something is transformed, and then the difference between a menu growing out of the corner it was opened from and one growing out of its own middle.'),
+  one('overflow', 'What becomes of whatever does not fit — shown past the edge anyway, cut off at it, or reached by scrolling.'),
+] as const satisfies readonly Omit<Threaded, 'at'>[]
+
+export const declares = [
+  written(
+    'shadow',
+    'Light a thing interrupts. Written as a rule rather than a list, so the style guide says how far a thing is lifted and how soft the light is, and the rule turns that into CSS.',
+    'thread/ui/tokens/shadow.ts',
+  ),
+] as const satisfies readonly Threaded[]
+
+export const TOKENS = {
+  id: 'token',
+  at: here,
+  describes:
+    'A sort of variable an app may have, named and never valued — colour, space, shadow. It says such a variable can exist; the style guide says which ones there are and what each holds. Where the thing is better stated as a rule than as a list, the token carries that rule and a style guide row hands it arguments instead of a value. An app adds one to bring a new sort of variable into being, and may not remove what the framework put there.',
+  version: 1,
+  cites: said,
+  declares,
+  holds,
+} as const satisfies Threaded & { readonly holds: readonly Omit<Threaded, 'at'>[] }
+
+export function nameOf(id: string): string {
+  return id.replace(/-/g, '_').toUpperCase()
+}
+
+function starter(row: Threaded): string {
+  const name = nameOf(row.id)
+  return `import type { Token } from './token.ts'
+
+export const ${name}: Token = {
+  id: '${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) }))
+}
+
+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 token = await loader(row)
+    if (token === 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 (token.id !== row.id) {
+      found.push(
+        `\`${row.at}\` declares itself \`${String(token.id)}\`, and the row that names it calls it \`${row.id}\`. ` +
+          'A token file and the row that names it have to be the same token — 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)
+}
+
+export function orphaned(rows: readonly Threaded[], listing: (dir: string) => readonly string[]): readonly string[] {
+  const named = new Set(rows.map((row) => row.at))
+  const acceptedByDir = new Map<string, Set<string>>()
+  for (const row of rows) {
+    const dir = dirname(row.at)
+    const held = acceptedByDir.get(dir) ?? new Set<string>()
+    held.add(extensionOf(row.at))
+    acceptedByDir.set(dir, held)
+  }
+  const found: string[] = []
+  for (const [dir, accepted] of acceptedByDir) {
+    for (const file of listing(dir)) {
+      if (named.has(file)) continue
+      if (!accepted.has(extensionOf(file))) continue
+      found.push(
+        `\`${file}\` is under tokens and no row names it — not a token, a file somebody wrote. ` +
+          'Add a row for it, or delete the file.',
+      )
+    }
+  }
+  return found
+}
+
+async function run(): Promise<number> {
+  const tree = findTree()
+  const at = inTree(tree, 'tokens.ts')
+  if (!existsSync(at)) {
+    stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no token and there is nothing to seed or check.\n`)
+    return 0
+  }
+  const held = (await import(pathToFileURL(at).href)) as { TOKEN?: { readonly declares?: readonly Threaded[] } }
+
+  if (held.TOKEN === undefined) {
+    stdout.write(`thread: ${tree.name}/tokens.ts exports no \`TOKEN\`, so nothing declares a token here.\n`)
+    return 1
+  }
+
+  const rows = held.TOKEN.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 tokens` and commit what it seeds.\n',
+      )
+      return 1
+    }
+  } else {
+    for (const seed of made) {
+      writeFileSync(join(tree.at, seed.path), seed.content, 'utf8')
+      stdout.write(`thread: seeded ${seed.path}\n`)
+    }
+  }
+
+  const wrong = (
+    await mismatched(rows, async (row) => {
+      const module = (await import(pathToFileURL(join(tree.at, row.at)).href)) as Record<string, unknown>
+      const held = module[nameOf(row.id)]
+      if (held === undefined) return undefined
+      return held as { readonly id: string }
+    })
+  )[0]
+  if (wrong !== undefined) {
+    stdout.write(`thread: ${wrong}\n`)
+    return 1
+  }
+
+  const stray = orphaned(rows, (dir) => readdirSync(join(tree.at, dir)).map((name) => join(dir, name)))[0]
+  if (stray !== undefined) {
+    stdout.write(`thread: ${stray}\n`)
+    return 1
+  }
+
+  stdout.write(
+    checking
+      ? `thread: ${String(rows.length)} token(s) declared, all seeded\n`
+      : `thread: ${String(rows.length)} token(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/validators.ts

@@ -0,0 +1,232 @@
+import {
+  ENTRY_MODES,
+  FORMATS,
+  KEYBOARDS,
+  formatNamed,
+  showValue,
+  type EntryMode,
+  type Facts,
+  type Format,
+  type Keyboard,
+} from '@prestack/thread/core/types'
+
+export { ENTRY_MODES, KEYBOARDS }
+export type { EntryMode, Keyboard }
+
+export type ValidateResult = { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly errorKey: string }
+
+export const valid = (value: unknown): ValidateResult => ({ ok: true, value })
+export const invalid = (errorKey: string): ValidateResult => ({ ok: false, errorKey })
+
+export interface ValidatorContext {
+  readonly [key: string]: unknown
+}
+
+export function validators(): readonly Format[] {
+  return [...FORMATS].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+}
+
+export function hasValidator(name: string): boolean {
+  return formatNamed(name) !== undefined
+}
+
+export function validatorFor(name: string): Format {
+  const one = formatNamed(name)
+  if (one === undefined) {
+    throw new Error(`unknown validator "${name}". Declared: ${FORMATS.map((entry) => entry.name).join(', ')}`)
+  }
+  return one
+}
+
+function factsFrom(context: ValidatorContext): Facts {
+  const text = (key: string): string | undefined => (typeof context[key] === 'string' ? (context[key] as string) : undefined)
+  const count = (key: string): number | undefined => (typeof context[key] === 'number' ? (context[key] as number) : undefined)
+  const locale = text('locale')
+  const currency = text('currency')
+  const max = count('max')
+  const now = count('now')
+  return {
+    ...(locale === undefined ? {} : { locale }),
+    ...(currency === undefined ? {} : { currency }),
+    ...(max === undefined ? {} : { max }),
+    ...(now === undefined ? {} : { now }),
+  }
+}
+
+export function runValidator(name: string, raw: unknown, context: ValidatorContext = {}): ValidateResult {
+  const one = formatNamed(name)
+  if (one === undefined) return invalid(`format.unknown.${name}`)
+  const outcome = one.check(raw, factsFrom(context))
+  return outcome.ok ? valid(outcome.value) : invalid(outcome.because)
+}
+
+export function formatValue(name: string, value: unknown, context: ValidatorContext = {}): string {
+  const one = formatNamed(name)
+  return one === undefined ? String(value) : showValue(one.type, name, value, factsFrom(context))
+}
+
+export interface EntryConstraints {
+  readonly keyboard: Keyboard
+  readonly accepts?: RegExp
+  readonly maxChars?: number
+  readonly entry: EntryMode
+  readonly mask?: string
+  readonly secret: boolean
+  readonly autocomplete?: string
+}
+
+export function entryConstraints(name: string, context: ValidatorContext = {}): EntryConstraints {
+  const one = validatorFor(name)
+  for (const key of one.requires ?? []) {
+    if (context[key] === undefined) {
+      throw new Error(`validator "${name}" requires "${key}" to render an entry field, and it was not provided`)
+    }
+  }
+  return {
+    keyboard: one.keyboard ?? 'text',
+    ...(one.accepts === undefined ? {} : { accepts: one.accepts }),
+    ...(one.maxChars === undefined ? {} : { maxChars: one.maxChars }),
+    entry: one.entry ?? 'plain',
+    ...(one.mask === undefined ? {} : { mask: one.mask }),
+    secret: one.secret === true,
+    ...(one.autocomplete === undefined ? {} : { autocomplete: one.autocomplete }),
+  }
+}
+
+export function acceptsKeystroke(name: string, current: string, key: string): boolean {
+  const one = validatorFor(name)
+  if (one.maxChars !== undefined && current.length >= one.maxChars) return false
+  if (one.accepts === undefined) return true
+  return new RegExp(one.accepts.source, one.accepts.flags.replace('g', '')).test(key)
+}
+
+export function applyMask(name: string, raw: string): string {
+  const one = validatorFor(name)
+  if (one.entry !== 'masked' || one.mask === undefined) return raw
+
+  const literals = new Set([...one.mask].filter((character) => character !== '0'))
+  const source = [...raw].filter((character) => !literals.has(character))
+
+  let out = ''
+  let taken = 0
+  for (const slot of one.mask) {
+    if (taken >= source.length) break
+    if (slot === '0') {
+      out += source[taken] as string
+      taken += 1
+      continue
+    }
+    out += slot
+  }
+  return out
+}
+
+interface Exact {
+  readonly n: bigint
+  readonly d: bigint
+}
+
+export function minorUnits(currency: string): number {
+
+  const { maximumFractionDigits } = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions()
+
+  if (maximumFractionDigits === undefined) throw new Error(`no minor-unit exponent for currency "${currency}"`)
+  return maximumFractionDigits
+}
+
+const ZERO: Exact = { n: BigInt(0), d: BigInt(1) }
+
+function add(a: Exact, b: Exact): Exact {
+  return { n: a.n * b.d + b.n * a.d, d: a.d * b.d }
+}
+function sub(a: Exact, b: Exact): Exact {
+  return { n: a.n * b.d - b.n * a.d, d: a.d * b.d }
+}
+function mul(a: Exact, b: Exact): Exact {
+  return { n: a.n * b.n, d: a.d * b.d }
+}
+function div(a: Exact, b: Exact): Exact | undefined {
+
+  return b.n === BigInt(0) ? undefined : { n: a.n * b.d, d: a.d * b.n }
+}
+
+function literal(text: string): Exact | undefined {
+  if (!/^\d+(\.\d+)?$/.test(text)) return undefined
+  const [whole, fraction = ''] = text.split('.')
+  return { n: BigInt(`${whole}${fraction}`), d: BigInt(10) ** BigInt(fraction.length) }
+}
+
+type Token = { readonly kind: 'number'; readonly value: Exact } | { readonly kind: 'op'; readonly op: string }
+
+function tokenize(input: string): readonly Token[] | undefined {
+  const out: Token[] = []
+  for (const raw of input.replace(/\s+/g, '').split(/([+\-×÷*/])/).filter(Boolean)) {
+    if (/^[+\-×÷*/]$/.test(raw)) {
+      out.push({ kind: 'op', op: raw === '*' ? '×' : raw === '/' ? '÷' : raw })
+      continue
+    }
+    const value = literal(raw)
+    if (value === undefined) return undefined
+    out.push({ kind: 'number', value })
+  }
+  return out
+}
+
+export function evaluateMoney(input: string, currency: string): { readonly amount: number } | undefined {
+  const tokens = tokenize(input)
+  if (tokens === undefined || tokens.length === 0) return undefined
+  if (tokens[0]?.kind !== 'number' || tokens[tokens.length - 1]?.kind !== 'number') return undefined
+
+  const terms: Exact[] = []
+  const adders: string[] = []
+  let current = (tokens[0] as { value: Exact }).value
+
+  for (let i = 1; i < tokens.length; i += 2) {
+    const operator = tokens[i]
+    const operand = tokens[i + 1]
+    if (operator?.kind !== 'op' || operand?.kind !== 'number') return undefined
+    if (operator.op === '×') {
+      current = mul(current, operand.value)
+      continue
+    }
+    if (operator.op === '÷') {
+      const next = div(current, operand.value)
+      if (next === undefined) return undefined
+      current = next
+      continue
+    }
+    terms.push(current)
+    adders.push(operator.op)
+    current = operand.value
+  }
+  terms.push(current)
+
+  let total = terms[0] ?? ZERO
+  adders.forEach((op, i) => {
+    const term = terms[i + 1] ?? ZERO
+    total = op === '+' ? add(total, term) : sub(total, term)
+  })
+
+  const scale = BigInt(10) ** BigInt(minorUnits(currency))
+  const scaled = (total.n * scale) / total.d
+  const remainder = (total.n * scale) % total.d
+  const half = total.d / BigInt(2)
+  const away = remainder < BigInt(0) ? -BigInt(1) : BigInt(1)
+  const magnitude = remainder < BigInt(0) ? -remainder : remainder
+  const rounded = magnitude * BigInt(2) >= total.d && half >= BigInt(0) ? scaled + away : scaled
+
+  return { amount: Number(rounded) / Number(scale) }
+}
+
+export function limited(name: string | undefined): Readonly<Record<string, number | string>> {
+  if (name === undefined) return {}
+  try {
+    const held = entryConstraints(name, {})
+    return {
+      ...(held.maxChars === undefined ? {} : { maxLength: held.maxChars }),
+      ...(held.keyboard === undefined ? {} : { inputMode: held.keyboard }),
+    }
+  } catch {
+    return {}
+  }
+}

package/dist/ui/variant.d.ts

@@ -107,6 +107,7 @@ export declare const variant: <const T extends Variant>(one: T & {
     } : unknown; };
 } : unknown)) => T;
 export declare function boundHeld(): Readonly<Record<string, readonly string[]>>;
+export declare function camel(id: string): string;
 export declare function classOf(id: string): string;
 export declare function classOfElement(id: string): string;
 export declare function classOfComposition(id: string): string;

package/dist/ui/variant.js

@@ -52,6 +52,9 @@ export const variant = (one) => one;
 export function boundHeld() {
     return BOUND;
 }
+export function camel(id) {
+    return id.replace(/-([a-z0-9])/g, (_, one) => one.toUpperCase());
+}
 export function classOf(id) {
     return `thread-${id}`;
 }