@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/animations/anm_wobble.ts

@@ -0,0 +1,24 @@
+import type { Animation } from '../animations.ts'
+
+export const WOBBLE = {
+  id: 'wobble',
+  runs: 'motion-slow',
+  eases: 'ease-in-out',
+  stops: {
+    '0%': [
+      { property: 'transform', is: 'transform-rest' },
+    ],
+    '25%': [
+      { property: 'transform', is: 'transform-tilt' },
+    ],
+    '50%': [
+      { property: 'transform', is: 'transform-rest' },
+    ],
+    '75%': [
+      { property: 'transform', is: 'transform-tilt-back' },
+    ],
+    '100%': [
+      { property: 'transform', is: 'transform-rest' },
+    ],
+  },
+} as const satisfies Animation

package/dist/ui/animations/anm_zoom_in.ts

@@ -0,0 +1,19 @@
+import type { Animation } from '../animations.ts'
+
+export const ZOOM_IN = {
+  id: 'zoom-in',
+  runs: 'motion-normal',
+  eases: 'ease-out',
+
+  fills: 'backwards',
+  stops: {
+    '0%': [
+      { property: 'opacity', is: 'opacity-none' },
+      { property: 'transform', is: 'transform-grow' },
+    ],
+    '100%': [
+      { property: 'opacity', is: 'opacity-full' },
+      { property: 'transform', is: 'transform-rest' },
+    ],
+  },
+} as const satisfies Animation

package/dist/ui/animations/anm_zoom_out.ts

@@ -0,0 +1,18 @@
+import type { Animation } from '../animations.ts'
+
+export const ZOOM_OUT = {
+  id: 'zoom-out',
+  runs: 'motion-quick',
+  eases: 'ease-in',
+  fills: 'forwards',
+  stops: {
+    '0%': [
+      { property: 'opacity', is: 'opacity-full' },
+      { property: 'transform', is: 'transform-rest' },
+    ],
+    '100%': [
+      { property: 'opacity', is: 'opacity-none' },
+      { property: 'transform', is: 'transform-grow' },
+    ],
+  },
+} as const satisfies Animation

package/dist/ui/animations.js

@@ -6,8 +6,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { existsSync, writeFileSync } from "@prestack/thread/core/files";
+import { basename, join } from 'node:path';
 import { argv, stdout } from 'node:process';
 import { pathToFileURL } from 'node:url';
 import { exit, invoked } from "@prestack/thread/core/invoked";
@@ -199,7 +199,6 @@ async function run() {
     }
     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`);
         }

package/dist/ui/animations.ts

@@ -0,0 +1,316 @@
+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, 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) {
+      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

@@ -62,12 +62,6 @@ const SHIPPED = [
         id: 'dev-generator',
         source: "  {\n    id: 'dev-generator',\n    at: 'node_modules/@prestack/thread-ui/dist/ui/generators/dev.js',\n    describes: 'The command that runs the app, and the only one here that puts a pixel on a screen — until it existed the framework could build an interface nothing in it could start, because a gate answers whether declarations agree with files and cannot answer whether a button is where somebody says it is not. It is two halves in one word. First it settles this tree: every generator the declarations name is run until the checks stop complaining, which is what `thread create` and `thread run trial` already did and what starting the app was alone in not doing — an app had `thread gate` in front of `next dev`, and a gate refuses a stale file rather than writing it. Then it runs the entry the manifest declares, which is where the gate hook fires and Next is reached. Neither half is written down here: the generators are read off the rows, and `next dev` appears nowhere, so a package attached tomorrow is run by this without this changing and an app served by something else needs no edit. `--ship` swaps the entry for the build. Alone among the generators it carries no `runs:`, because a server stays up until it is stopped and a gate step that never returns is a gate that hangs.',\n    version: 1,\n    by: 'thread dev',\n  },",
     },
-    {
-        into: 'ui.ts',
-        list: 'GENERATORS',
-        id: 'message-maker',
-        source: "  {\n    id: 'message-maker',\n    at: 'node_modules/@prestack/thread-ui/dist/ui/makers/message.js',\n    describes: 'The maker of a message — asked for in every declared language at the moment the key is made, and refused while any answer is blank, so a key cannot be brought into existence half translated. It is also the only safe way to rename one: a rename moves the wording in every language and rewrites every file in the interface that names it, in one run, where doing it by hand leaves a key half moved and one sentence missing at run time.',\n    version: 1,\n    by: 'thread create message',\n  },",
-    },
     {
         into: 'ui.ts',
         list: 'GENERATORS',
@@ -102,7 +96,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 +216,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 +240,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 +303,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 +315,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 +356,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 +463,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) => ({