@prestack/thread-ui 0.0.1 → 0.0.2

package/dist/ui/animations.ts

@@ -0,0 +1,317 @@
+import { existsSync, mkdirSync, readdirSync, 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'
+
+import { held, sheeted, type Holds, type Token } from './token.ts'
+
+const here = 'thread/ui/animations.ts'
+
+export const BOUND = {
+  opacity: ['opacity'],
+  transform: ['transform'],
+  filter: ['filter'],
+  backdropFilter: ['blur'],
+  background: ['colour', 'gradient'],
+  color: ['colour'],
+  borderColor: ['colour'],
+  boxShadow: ['shadow'],
+} as const
+
+type Property = keyof typeof BOUND
+
+type SettingFor<P extends Property> = {
+  readonly property: P
+  readonly is?: string
+  readonly token?: (typeof BOUND)[P][number]
+  readonly asks?: Readonly<Record<string, string | number>>
+}
+
+export type AnimationSetting = { [P in Property]: SettingFor<P> }[Property]
+
+export interface Animation {
+  readonly id: string
+
+  readonly runs: string
+
+  readonly eases: string
+
+  readonly repeats?: number | 'infinite'
+
+  readonly fills?: 'none' | 'forwards' | 'backwards' | 'both'
+
+  readonly stops: Readonly<Record<string, readonly AnimationSetting[]>>
+}
+
+export function keyframeName(id: string): string {
+  return `anm-${id}`
+}
+
+function resolve(
+  animation: Animation,
+  set: AnimationSetting,
+  value: string,
+  named: ReadonlySet<string>,
+  kinds: Readonly<Record<string, string>>,
+): string {
+  if (!named.has(value)) {
+    throw new Error(
+      `\`${animation.id}\` sets ${set.property} to "${value}", and the style guide holds no row by ` +
+        'that name. An animation composes what the style guide holds, or it composes nothing.',
+    )
+  }
+  const kind = kinds[value]
+  const accepted: readonly string[] = BOUND[set.property]
+  if (kind !== undefined && !accepted.includes(kind)) {
+    throw new Error(
+      `\`${animation.id}\` sets ${set.property} to \`${value}\`, and that row is a \`${kind}\`. ` +
+        `${set.property} takes ${accepted.map((one) => `\`${one}\``).join(' or ')}.`,
+    )
+  }
+  return `var(--${value})`
+}
+
+function valued(
+  animation: Animation,
+  set: AnimationSetting,
+  named: ReadonlySet<string>,
+  tokens: Readonly<Record<string, Token>>,
+  kinds: Readonly<Record<string, string>>,
+): Holds {
+  if (set.token !== undefined) {
+    const token = tokens[set.token]
+    if (token?.makes === undefined) {
+      throw new Error(
+        `\`${animation.id}\` asks \`${set.token}\` for ${set.property}, and that token carries no rule ` +
+          'to make a value from. Name a style guide row instead, or give the token a rule.',
+      )
+    }
+    return sheeted(set.token, token.makes(set.asks ?? {}))
+  }
+  if (set.is === undefined) {
+    throw new Error(
+      `\`${animation.id}\` states ${set.property} with neither a value nor a token to make one from.`,
+    )
+  }
+  return held(named, resolve(animation, set, set.is, named, kinds), animation.id)
+}
+
+export function stopsOf(
+  animation: Animation,
+  named: ReadonlySet<string>,
+  tokens: Readonly<Record<string, Token>>,
+  kinds: Readonly<Record<string, string>>,
+): readonly { readonly stop: string; readonly made: Readonly<Record<string, Holds>> }[] {
+  return Object.keys(animation.stops).map((stop) => {
+    const made: Record<string, Holds> = {}
+    for (const set of animation.stops[stop] ?? []) made[set.property] = valued(animation, set, named, tokens, kinds)
+    return { stop, made }
+  })
+}
+
+export function shorthandOf(animation: Animation, named: ReadonlySet<string>): string {
+  for (const [what, row] of [
+    ['runs', animation.runs],
+    ['eases', animation.eases],
+  ] as const) {
+    if (named.has(row)) continue
+    throw new Error(
+      `\`${animation.id}\` ${what} \`${row}\`, and the style guide holds no row by that name. ` +
+        'How long an animation takes and how it is paced are style guide values, named here rather than written.',
+    )
+  }
+  return [
+    keyframeName(animation.id),
+    `var(--${animation.runs})`,
+    `var(--${animation.eases})`,
+    ...(animation.repeats === undefined ? [] : [String(animation.repeats)]),
+    ...(animation.fills === undefined ? [] : [animation.fills]),
+  ].join(' ')
+}
+
+const one = (id: string, describes: string): Threaded => ({
+  id,
+  at: `thread/ui/animations/anm_${id.replace(/-/g, '_')}.ts`,
+  describes,
+  version: 1,
+})
+
+export const declares: readonly Threaded[] = [
+  one('press', 'A thing shrinking very slightly and coming back, which is what makes a press feel like it landed rather than like a value changed.'),
+  one('appear', 'Something arriving in place — faded up from nothing, without moving, for a thing that was always going to be there.'),
+  one('dismiss', 'Something leaving — faded away and shrunk a little, so the eye is not asked to follow it out.'),
+  one('rise', 'Something arriving from below, faded up as it comes. What a sheet, a toast or a menu does on its way in.'),
+  one('fall', 'Something leaving downward, the exit that answers a rise.'),
+  one('pulse', 'A thing breathing in place, repeated without end, for something waiting rather than working.'),
+  one('spin', 'A full turn, repeated without end. What says a thing is working and cannot say how far along it is.'),
+  one('drop', 'Something arriving from above, faded in as it comes. The entrance that answers a rise.'),
+  one('slide-in-left', 'Something coming in from the left, for a panel or a step arriving from off-stage rather than growing in place.'),
+  one('slide-in-right', 'Something coming in from the right.'),
+  one('slide-out-left', 'Something leaving to the left.'),
+  one('slide-out-right', 'Something leaving to the right.'),
+  one('zoom-in', 'Something arriving from nearer the reader and settling back to its true size.'),
+  one('zoom-out', 'Something leaving toward the reader as it fades.'),
+  one('pop-in', 'Something arriving past its own size and coming back — the overshoot is what reads as physical rather than as a value changing.'),
+  one('pop-out', 'Something swelling once before it goes, the exit that answers a pop.'),
+  one('blur-in', 'Something sharpening into place out of softness, without moving at all.'),
+  one('blur-out', 'Something dissolving rather than leaving.'),
+  one('lift', 'A thing raised a little off the page while it is pointed at. The plainest way a surface says it is reachable.'),
+  one('swell', 'A thing grown very slightly while pointed at, for where lifting it would move its neighbours.'),
+  one('nudge', 'A marker leaning the way it would take you, played while the wording beside it is pointed at.'),
+  one('wobble', 'A thing turned one way and back to be noticed. Says look at me without saying something is wrong.'),
+  one('flash', 'A thing dipping and returning, for a value that changed underneath the reader.'),
+  one('glow', 'The light around a thing swelling and settling, for something lit rather than framed.'),
+  one('shake', 'A short refusal — a thing pushed off centre and back twice, for an answer that was not accepted.'),
+]
+
+export const ANIMATIONS = {
+  id: 'animation',
+  at: here,
+  files: 'ui/anm_*.ts',
+  describes:
+    'Every animation an app may play, and the only place one may be brought into existence. A row names a file prefixed `anm_`, and that file is the animation: the stops it moves through, how long it takes and how it is paced — all of it naming style guide rows rather than holding values, so an animation moves when the rows move. Naming one is the whole of using one: a variant that plays `press` says `press`, and states no duration, no easing and no keyframes. The style guide picks which animation is the default for a thing, the way it picks every other value. A file under animations that no row names is not an animation but a file somebody wrote.',
+  version: 1,
+  cites: [
+    {
+      on: '2026-08-28',
+      said: 'Animations.ts, declares rows (through threaded) that names animations files at a path, with a prefix anm_ or ani_ or we do motions.ts with mot_, don\'t know. These define a bunch of animations that style guide will pick for a bunch of things as defaults. Like these template animations we see in video editors, we just name them and it\'s done.',
+    },
+  ],
+  declares,
+} satisfies Threaded & { readonly files: string; readonly declares: readonly Threaded[] }
+
+export function nameOf(id: string): string {
+  return id.replace(/-/g, '_').toUpperCase()
+}
+
+function starter(row: Threaded): string {
+  return `import type { Animation } from './animations.ts'
+
+export const ${nameOf(row.id)} = {
+  id: '${row.id}',
+  runs: 'motion-normal',
+  eases: 'ease-out',
+  stops: {},
+} as const satisfies Animation
+`
+}
+
+export function seeds(
+  rows: readonly Threaded[],
+  has: (at: string) => boolean,
+): readonly { readonly path: string; readonly content: string }[] {
+  return rows.filter((row) => !has(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 animation = await loader(row)
+    if (animation === 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 (animation.id !== row.id) {
+      found.push(
+        `\`${row.at}\` declares itself \`${String(animation.id)}\`, and the row that names it calls it \`${row.id}\`. ` +
+          "An animation file and the row that names it have to be the same animation — 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 ANM_PREFIX = /^anm_/
+
+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 animations and no row names it — not a animation, a file somebody wrote. ` +
+        'Add a row for it, or delete the file.',
+    )
+}
+
+async function run(): Promise<number> {
+  const tree = findTree()
+  const at = inTree(tree, 'animations.ts')
+  if (!existsSync(at)) {
+    stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no animation and there is nothing to seed or check.\n`)
+    return 0
+  }
+  const sheet = (await import(pathToFileURL(at).href)) as {
+    ANIMATION?: { readonly declares?: readonly Threaded[] }
+  }
+
+  if (sheet.ANIMATION === undefined) {
+    stdout.write(`thread: ${tree.name}/animations.ts exports no \`ANIMATION\`, so nothing declares an animation here.\n`)
+    return 1
+  }
+
+  const rows = sheet.ANIMATION.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 animations` and commit what it seeds.\n',
+      )
+      return 1
+    }
+  } else {
+    for (const seed of made) {
+      mkdirSync(dirname(join(tree.at, seed.path)), { recursive: true })
+      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>
+      return module[nameOf(row.id)] as { readonly id?: string } | undefined
+    })
+  )[0]
+  if (wrong !== undefined) {
+    stdout.write(`thread: ${wrong}\n`)
+    return 1
+  }
+
+  const stray = orphaned(rows, strayFiles(tree.at, 'anm_', '.' + 'ts'))[0]
+  if (stray !== undefined) {
+    stdout.write(`thread: ${stray}\n`)
+    return 1
+  }
+
+  stdout.write(
+    checking
+      ? `thread: ${String(rows.length)} animation(s) declared, all seeded\n`
+      : `thread: ${String(rows.length)} animation(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/attach.js

@@ -102,7 +102,7 @@ const SHIPPED = [
         into: 'ui.ts',
         list: 'GENERATORS',
         id: 'compositions-generator',
-        source: "  {\n    id: 'compositions-generator',\n    at: 'node_modules/@prestack/thread-ui/dist/ui/compositions.js',\n    describes: 'The seeder of composition files — it reads the compositions an app declares and writes the `cmp_` file each row names when that file is not there yet, so a composition begins by being declared rather than by somebody remembering to add a file beside the row. Run with `--check`, the mode the gate runs it in, it writes nothing and refuses instead: a row whose file is absent, a `cmp_` file no row names, and an import that is not a declared element, a declared composition or the door — so a composition that did not come from the CLI, or that reaches something nothing declares, stops the build rather than rendering.',\n    version: 1,\n    by: 'thread compositions',\n    runs: 'thread compositions --check',\n  },",
+        source: "  {\n    id: 'compositions-generator',\n    at: 'node_modules/@prestack/thread-ui/dist/ui/compositions.js',\n    describes: 'The seeder of composition files — it reads the compositions an app declares and writes the `cmp_` file each row names when that file is not there yet, so a composition begins by being declared rather than by somebody remembering to add a file beside the row. Run with `--check`, the mode the gate runs it in, it writes nothing and refuses instead: a row whose file is absent, a `cmp_` file no row names, and an import that is not a declared element, a declared composition or the door — so a composition that did not come from the CLI, or that reaches something nothing declares, stops the build rather than rendering. It also writes each of them compiled, into `app/_generated/compiled` — a variant worn as a tag becomes the class it resolves to and a named place becomes the class its arrangement declares, so a page imports a file this framework wrote rather than one a bundler plugin rewrites on the way past.',\n    version: 1,\n    by: 'thread compositions',\n    runs: 'thread compositions --check',\n    derives: [\n      {\n        id: 'compiled',\n        at: 'app/_generated/compiled',\n        describes: 'Every composition and screen as React runs them, written from the files a person wrote: a variant worn as a tag has become the class it resolves to, and a named place has become the class its arrangement declares. Nobody edits anything here, and nothing reads the sources at run time — this is what a page imports, which is why no compiler of this framework has to be installed for the app to build.',\n        version: 1,\n        by: 'thread compositions',\n        runs: 'thread compositions --check',\n      },\n    ],\n  },",
     },
     {
         into: 'ui.ts',
@@ -222,7 +222,7 @@ function quoted(value) {
     return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 function installed(at) {
-    return at.replace(/^thread\/ui\/(.*)\.tsx?$/, `${ATTACH_HOME}/$1.js`);
+    return at.replace(/^thread\/(.*)\.tsx?$/, `${ATTACH_HOME}/$1.js`);
 }
 function literal(value) {
     return typeof value === 'number' ? String(value) : quoted(value);
@@ -246,7 +246,7 @@ function themed(held) {
     return `{ ${each.join(', ')} }`;
 }
 const WRITTEN = new Set([
-    'id', 'at', 'describes', 'version', 'derives', 'holds',
+    'id', 'at', 'describes', 'version', 'derives', 'holds', 'runs',
     'section', 'token', 'is', 'asks', 'sets', 'modes', 'places', 'themes', 'wears', 'selector',
     'arranges', 'plays',
 ]);
@@ -309,6 +309,7 @@ function row(one, file, sheet) {
                 '      ],',
             ]),
         ...(held ? [] : [`      at: ${quoted(installed(one.at ?? ''))},`]),
+        ...(one.runs === undefined ? [] : [`      runs: ${quoted(one.runs.split(' --own').join(''))},`]),
         `      describes: ${quoted(one.describes)},`,
         '      version: 1,',
         '    },',
@@ -320,8 +321,13 @@ const ARRANGES = {
     styleguide: ['themes'],
     element: ['tag', 'raises', 'carries', 'always', 'places', 'works', 'measures', 'reads', 'gives', 'keeps', 'animates', 'shows', 'called', 'wires', 'dresses'],
 };
+const TEACHING = {
+    composition: `export { TEACHES, catalogue } from '${named('ui')}/compositions'`,
+    screen: `export { TEACHES, screening as catalogue } from '${named('ui')}/compositions'`,
+};
 function source(node, file, rows) {
     const extra = stated(rows, ARRANGES[node.id] ?? []).map((key) => SHAPES[key] ?? '');
+    const taught = TEACHING[node.id];
     const authors = node.declares !== undefined || rows.some((one) => one.at !== undefined && one.at !== node.at);
     const values = node.holds !== undefined || rows.some((one) => one.at === undefined || one.at === node.at);
     const own = node.id
@@ -356,7 +362,7 @@ export const ${node.id.toUpperCase()}: ${bespoke ? own : 'Threaded'} = {
   version: 1,
 ${held.join('\n')}
 }
-`;
+${taught === undefined ? '' : `\n${taught}\n`}`;
 }
 const LISTS = [
     { node: TOKENS, file: 'tokens.ts' },
@@ -463,11 +469,14 @@ export const ATTACH = {
     attaches: SEEDED.attaches,
     id: SEEDED.id,
     needs: {
+        '@floating-ui/dom': '^1.7.0',
+        '@floating-ui/react-dom': '^2.1.0',
         '@types/react': '^19.0.0',
         '@types/react-dom': '^19.0.0',
         next: '^16.0.0',
         react: '^19.0.0',
         'react-dom': '^19.0.0',
+        zod: '^4.5.4',
     },
     rows: [
         ...CONCEPTS.map((one) => ({