@estiva-app/ui 0.21.1 → 0.23.0

package/src/registry/cli.ts

@@ -0,0 +1,204 @@
+/// <reference types="node" />
+/**
+ * `estiva-ui` — the catalogue as a command (UIG-12, UIG-13; docs/GATES.md §23
+ * for why it ships in the package rather than as a script pasted into each repo).
+ *
+ *   estiva-ui find <words…> [--also [name=]<folder>]… [--json] [--limit n]
+ *   estiva-ui build [--out <path>]
+ *   estiva-ui check
+ *
+ * Every command takes `--root <folder>` (the library it reads; default: here)
+ * and `--repo <name>` (what an app's entries are called; default: its package name).
+ *
+ * **In the package** (`@estiva-app/ui` itself): `build` writes the committed
+ * `registry.json`, and `check` rebuilds it and fails on a single byte of drift.
+ *
+ * **In an app**: nothing is committed (Katerina, 18 September 2026 — the
+ * package is public, the apps are private). `check` builds the app's catalogue
+ * and fails when a part has no one-line description or cannot be sorted; CI's
+ * `gate` job runs it. `build` writes the catalogue to a file only when asked.
+ *
+ * `find` searches the package's catalogue — the one shipped inside the installed
+ * package, or this repo's own in the package — plus, in an app, the app's own,
+ * built fresh, plus each `--also` app that sits beside it.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findInRegistries, formatFindings } from './find'
+import { CLASSES, validateRegistry, type Registry } from './schema'
+
+/**
+ * The builders, loaded only when they are used.
+ *
+ * They read TypeScript with TypeScript, and `typescript` is a dev dependency of
+ * the app that installs this package — a real one in Peek, Ship and this repo,
+ * and possibly absent elsewhere. A static import made the bundler put the whole
+ * builder in the same chunk as `find`, so `npx estiva-ui find …` died with
+ * ERR_MODULE_NOT_FOUND before opening the file it needed.
+ */
+const packageBuilder = () => import('./build')
+const appBuilder = () => import('./app')
+
+const [command, ...rest] = process.argv.slice(2)
+const VALUED = ['--limit', '--out', '--file', '--root', '--repo', '--also']
+const flag = (name: string) => rest.includes(`--${name}`)
+const value = (name: string) => {
+  const at = rest.indexOf(`--${name}`)
+  return at === -1 ? undefined : rest[at + 1]
+}
+const values = (name: string) => rest.flatMap((word, i) => (word === `--${name}` && rest[i + 1] !== undefined ? [rest[i + 1]] : []))
+/** Everything that is not a flag or a flag's value: the words of the question. */
+const plain = () => {
+  const out: string[] = []
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i].startsWith('--')) {
+      if (VALUED.includes(rest[i])) i += 1
+      continue
+    }
+    out.push(rest[i])
+  }
+  return out
+}
+
+const root = resolve(value('root') ?? '.')
+const manifestAt = (folder: string) => JSON.parse(readFileSync(resolve(folder, 'package.json'), 'utf8')) as { name?: string }
+/** The package itself, or an app that installs it. */
+const isPackage = existsSync(resolve(root, 'package.json')) && manifestAt(root).name === '@estiva-app/ui'
+
+/** The package's committed catalogue: `--file`, this repo's own in the package, else the copy inside the installed package. */
+function packageRegistryPath(): string {
+  const named = value('file')
+  if (named) return resolve(named)
+  if (isPackage) return resolve(root, 'registry.json')
+  // dist/registry/cli.js → the package's own root. Never an app's own folder:
+  // a registry.json there is the app's, written by `estiva-ui build`.
+  return fileURLToPath(new URL('../../registry.json', import.meta.url))
+}
+
+function readPackageRegistry(): Registry {
+  const path = packageRegistryPath()
+  if (!existsSync(path)) throw new Error(`no registry.json at ${path} — run "estiva-ui build" in the package first`)
+  const registry = JSON.parse(readFileSync(path, 'utf8')) as Registry
+  const problems = validateRegistry(registry)
+  // A malformed catalogue is worse than none: it would answer, wrongly.
+  if (problems.length) throw new Error(`${path} does not match the schema:\n  ${problems.join('\n  ')}`)
+  return registry
+}
+
+async function buildApp(folder: string, repo: string | undefined): Promise<Registry> {
+  const { buildAppRegistry } = await appBuilder()
+  const registry = buildAppRegistry({ root: folder, repo })
+  const problems = validateRegistry(registry)
+  if (problems.length) throw new Error(`the catalogue of ${registry.builtFrom.repo} does not match its own schema:\n  ${problems.join('\n  ')}`)
+  return registry
+}
+
+/** One line per kind, in a fixed order, so two runs read the same. */
+function summary(registry: Registry): string {
+  const count = (cls: string) => registry.entries.filter((entry) => entry.app?.class === cls).length
+  const kinds = CLASSES.map((cls) => `${count(cls)} ${cls}`).join(', ')
+  const files = registry.builtFrom.files ?? 0
+  return `${registry.builtFrom.repo}: ${registry.entries.length} parts in ${files - registry.filesWithoutParts.length} files (${registry.filesWithoutParts.length} more hold none) — ${kinds}. Every part is described and sorted.`
+}
+
+async function main(): Promise<number> {
+  switch (command) {
+    case 'find': {
+      const query = plain().join(' ')
+      if (!query.trim()) {
+        process.stderr.write('estiva-ui find <words…> — what the thing you need does, in words\n')
+        return 1
+      }
+      const registries: Registry[] = [readPackageRegistry()]
+      // An app that cannot be read is said out loud, and the rest still answer.
+      const add = async (folder: string, repo: string | undefined) => {
+        try {
+          registries.push(await buildApp(folder, repo))
+        } catch (error) {
+          const [first, ...more] = String(error instanceof Error ? error.message : error).split('\n')
+          process.stderr.write(`not searched: ${first}${more.length ? `\n${more.slice(0, 3).join('\n')}${more.length > 3 ? `\n  …and ${more.length - 3} more — run "estiva-ui check" there` : ''}` : ''}\n`)
+        }
+      }
+      if (!isPackage) await add(root, value('repo'))
+      for (const also of values('also')) {
+        const [name, folder] = also.includes('=') ? [also.slice(0, also.indexOf('=')), also.slice(also.indexOf('=') + 1)] : [undefined, also]
+        const at = resolve(root, folder)
+        if (!existsSync(resolve(at, 'package.json'))) {
+          process.stderr.write(`not searched: ${name ?? basename(at)} — nothing at ${at}\n`)
+          continue
+        }
+        await add(at, name)
+      }
+      const limit = Number(value('limit') ?? 5)
+      const findings = findInRegistries(registries, query, { limit: Number.isFinite(limit) && limit > 0 ? limit : 5 })
+      if (flag('json')) {
+        process.stdout.write(`${JSON.stringify(findings.map((finding) => finding.entry), null, 2)}\n`)
+        return 0
+      }
+      process.stdout.write(`${formatFindings(registries, findings, query)}\n`)
+      // Nothing found is not a failure — it is the answer that sends a session
+      // to ask rather than to invent.
+      return 0
+    }
+
+    case 'build': {
+      const out = resolve(root, value('out') ?? 'registry.json')
+      if (isPackage) {
+        const { buildRegistry, serializeRegistry } = await packageBuilder()
+        const registry = buildRegistry({ root })
+        const problems = validateRegistry(registry)
+        if (problems.length) {
+          process.stderr.write(`the registry this build produced does not match its own schema:\n  ${problems.join('\n  ')}\n`)
+          return 1
+        }
+        writeFileSync(out, serializeRegistry(registry), 'utf8')
+        process.stdout.write(`${out}: ${registry.entries.length} entries from ${registry.builtFrom.exports} exports\n`)
+        return 0
+      }
+      const { serializeRegistry } = await packageBuilder()
+      const registry = await buildApp(root, value('repo'))
+      writeFileSync(out, serializeRegistry(registry), 'utf8')
+      process.stdout.write(`${out}: ${summary(registry)}\n`)
+      return 0
+    }
+
+    case 'check': {
+      if (!isPackage) {
+        process.stdout.write(`${summary(await buildApp(root, value('repo')))}\n`)
+        return 0
+      }
+      const { buildRegistry, serializeRegistry } = await packageBuilder()
+      const path = packageRegistryPath()
+      const built = buildRegistry({ root })
+      const problems = validateRegistry(built)
+      if (problems.length) {
+        process.stderr.write(`the registry does not match its own schema:\n  ${problems.join('\n  ')}\n`)
+        return 1
+      }
+      if (!existsSync(path)) {
+        process.stderr.write(`${path} is missing — run "npm run registry"\n`)
+        return 1
+      }
+      // Byte for byte. The point of the check is that the committed file cannot
+      // drift from the code; "near enough" is drift.
+      if (readFileSync(path, 'utf8').replace(/\r\n/g, '\n') !== serializeRegistry(built)) {
+        process.stderr.write(`${path} is not what the code produces — run "npm run registry" and commit the result\n`)
+        return 1
+      }
+      process.stdout.write(`${path}: current, ${built.entries.length} entries from ${built.builtFrom.exports} exports\n`)
+      return 0
+    }
+
+    default:
+      process.stderr.write('estiva-ui <find | build | check>\n')
+      return 1
+  }
+}
+
+try {
+  process.exitCode = await main()
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+}

package/src/registry/find.ts

@@ -0,0 +1,232 @@
+/**
+ * The catalogue's reader (UIG-12): `ui:find <words>`.
+ *
+ * It exists to prove the format. A schema nobody consumes is a schema nobody
+ * has tested, and the questions it has to answer are regression tests, not the
+ * scope: "floating panel" must find `Popover`, "scrolling" `ScrollArea`,
+ * "empty" `EmptyState`.
+ *
+ * It is also the answer to "what do we have for this?", which is the question
+ * the wall cannot answer: a lint rule refuses the wrong thing, and this is
+ * where the right one is named (UIG-20 makes a session ask it first).
+ */
+import type { Registry, RegistryEntry } from './schema'
+
+export interface Finding {
+  entry: RegistryEntry
+  /** How many of the query's words matched anywhere. Ranked on this first. */
+  matched: number
+  score: number
+  /** Which fields matched, for the reader to say why. */
+  where: string[]
+  /**
+   * The props the query named **by name**, so the answer shows those rather
+   * than all of them. A prop whose note merely carries one of the words counts
+   * towards the score and is not shown: on "floating panel", six of `Popover`'s
+   * notes say "panel", and printing all six buries the answer.
+   */
+  props: string[]
+}
+
+/**
+ * Words that are in nearly every sentence, and so tell a search nothing.
+ *
+ * Measured: `ui:find "truncate a long link"` printed `Link`'s `external` prop,
+ * because its note says "in **a** new tab" and the one-letter word matched
+ * itself exactly. The minimum length in `alike` only guards a *prefix* match;
+ * an exact match short-circuits it, which is right for `tab` and useless for `a`.
+ */
+const STOP = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'can', 'do', 'for', 'from', 'how', 'i', 'if', 'in', 'is', 'it', 'its', 'me', 'my', 'no', 'not', 'of',
+  'on', 'or', 'our', 'so', 'that', 'the', 'their', 'them', 'then', 'there', 'they', 'this', 'to', 'up', 'was', 'we', 'what', 'when', 'which', 'with', 'you', 'your',
+])
+
+/**
+ * The words of a piece of text, with names taken apart.
+ *
+ * `CommandPalette` is kept whole *and* split, so "palette" reaches it and
+ * "commandpalette" still does. Prose is already words; this costs it nothing.
+ */
+function words(text: string): string[] {
+  const found: string[] = []
+  for (const token of text.match(/[A-Za-z0-9]+/g) ?? []) {
+    found.push(token.toLowerCase())
+    const parts = token.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/)
+    if (parts.length > 1) found.push(...parts.map((part) => part.toLowerCase()))
+  }
+  return found
+}
+
+/**
+ * Whether a word of the query means a word of the text.
+ *
+ * Either being a prefix of the other covers "scroll" against "scrolling"; the
+ * five-letter key covers "scrolls" against "scrolling", where neither is. Crude
+ * on purpose — a stemmer is a dependency and a surprise, and the failure here
+ * is an extra row in a list of five, not a wrong answer.
+ *
+ * **Three letters at least**, or a prefix match is no match at all: `person's`
+ * puts the word "s" in the text, and every query on earth starts with some
+ * letter. Measured — before this, "scrolling" found `Avatar`.
+ */
+function alike(query: string, text: string): boolean {
+  if (query === text) return true
+  if (Math.min(query.length, text.length) < 3) return false
+  if (text.startsWith(query) || query.startsWith(text)) return true
+  return query.slice(0, 5) === text.slice(0, 5)
+}
+
+const hit = (query: string, text: string) => words(text).some((word) => alike(query, word))
+
+/**
+ * Search name, purpose, behaviours and variants.
+ *
+ * A row that answers more of the question comes first, whatever it scored:
+ * "floating panel" has to reach `Popover`, whose purpose carries both words,
+ * over `MenuPanel`, whose name carries one of them loudly.
+ */
+export function findInRegistry(registry: Registry, query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
+  return findInRegistries([registry], query, { limit })
+}
+
+/**
+ * Search several catalogues as one: the package's, the app's own, and any app
+ * beside it (UIG-13).
+ *
+ * An app's pass-on is not a result of its own — it is the package's part, and
+ * the package's entry answers for it, saying which apps hand it on. At the
+ * same strength the package's part comes first: it is the one to reach for.
+ */
+export function findInRegistries(registries: Registry[], query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
+  const all = words(query)
+  // Drop the words that mean nothing. If the question was only those, keep them
+  // rather than answer nothing at all.
+  const carrying = all.filter((word) => word.length >= 3 && !STOP.has(word))
+  const asked = carrying.length ? carrying : all
+  if (asked.length === 0) return []
+
+  const findings: Finding[] = []
+  const entries = registries.flatMap((registry) => registry.entries).filter((entry) => entry.app?.class !== 're-export')
+  for (const entry of entries) {
+    let score = 0
+    let matched = 0
+    const where = new Set<string>()
+    const byName = new Set<string>()
+    const byNote = new Set<string>()
+    for (const word of asked) {
+      let best = 0
+      if (entry.name.toLowerCase() === word) {
+        best = 100
+        where.add('name')
+      } else if (hit(word, entry.name)) {
+        best = 40
+        where.add('name')
+      }
+      if (hit(word, entry.purpose)) {
+        best = Math.max(best, 20)
+        where.add('purpose')
+      }
+      for (const owned of entry.ownsBehaviours) {
+        if (hit(word, owned.behaviour) || hit(word, owned.id)) {
+          best = Math.max(best, 15)
+          where.add('behaviour')
+        }
+      }
+      for (const variant of entry.variants) {
+        if (variant.values.some((value) => hit(word, value)) || hit(word, variant.prop)) {
+          best = Math.max(best, 8)
+          where.add('variant')
+          byName.add(variant.prop)
+        }
+      }
+      // What it can do. "does Link already truncate?" is the question this
+      // answers, and answering it is what stops the thing being built twice.
+      for (const prop of entry.props) {
+        // A prop the question named by name is the answer; one whose note
+        // happens to carry the word is a hint. Named ones go first, so a short
+        // answer shows the right lines.
+        if (hit(word, prop.name)) {
+          best = Math.max(best, 14)
+          where.add('prop')
+          byName.add(prop.name)
+        } else if (prop.note !== null && hit(word, prop.note)) {
+          best = Math.max(best, 10)
+          where.add('prop')
+          byNote.add(prop.name)
+        }
+      }
+      if (best > 0) matched += 1
+      score += best
+    }
+    if (matched > 0) findings.push({ entry, matched, score, where: [...where], props: [...byName] })
+  }
+
+  const fromPackage = (finding: Finding) => (finding.entry.app === null ? 0 : 1)
+  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name))
+  return findings.slice(0, limit)
+}
+
+/** `http://localhost:6008/?path=/docs/overlays-popover--docs`, or `null` where the entry has no page. */
+export function docsLink(registry: Registry, entry: RegistryEntry): string | null {
+  if (!entry.docsId) return null
+  return registry.storybook.devUrl + registry.storybook.docsPath.replace('{docsId}', entry.docsId)
+}
+
+/** What an app's part is, in the words the search prints. */
+const CLASS_WORDS: Record<string, string> = {
+  'one-off': 'used in one place',
+  reusable: 'used in several places',
+  'promote-candidate': 'used in several places; could move into the package',
+  unused: 'used nowhere in the app',
+}
+
+/** What the command prints: the import line first, because that is what the reader came for. */
+export function formatFindings(searched: Registry | Registry[], findings: Finding[], query: string): string {
+  const registries = Array.isArray(searched) ? searched : [searched]
+  if (findings.length === 0) {
+    return [
+      `Nothing in ${registries.map((registry) => registry.builtFrom.repo).join(', ')} matches "${query}".`,
+      'If nothing here does what you need, say so and ask — do not invent a component.',
+    ].join('\n')
+  }
+  const registryOf = (entry: RegistryEntry) => registries.find((registry) => registry.builtFrom.repo === entry.repo) ?? registries[0]
+  // Which apps hand a package part on, and from where: in Peek, `Button` is
+  // imported from `@/components/ui/Button`, and the answer should say so.
+  const handedOn = new Map<string, string[]>()
+  for (const registry of registries) {
+    for (const entry of registry.entries) {
+      if (entry.app?.class !== 're-export' || entry.app.handsOn === null) continue
+      handedOn.set(entry.app.handsOn, [...(handedOn.get(entry.app.handsOn) ?? []), `${entry.repo} hands it on${entry.name === entry.app.handsOn ? '' : ` as ${entry.name}`} from ${entry.importPath}`])
+    }
+  }
+
+  const blocks = findings.map((finding) => {
+    const { entry } = finding
+    const facts = entry.app
+    const lines = [
+      `${entry.name}  ·  ${facts ? CLASS_WORDS[facts.class] ?? facts.class : entry.kind}  ·  ${entry.repo}  (matched ${finding.where.join(', ')})`,
+      `  ${entry.purpose}`,
+      facts?.defaultExport ? `  import ${entry.name} from '${entry.importPath}'` : `  import { ${entry.name} } from '${entry.importPath}'`,
+    ]
+    if (!facts) for (const said of handedOn.get(entry.name) ?? []) lines.push(`  ${said}`)
+    if (facts?.packageNamesake) lines.push(`  the package has a ${facts.packageNamesake} too: check it first`)
+    if (facts && facts.usedIn.length) lines.push(`  used in ${facts.usedIn.slice(0, 2).join(', ')}${facts.usedIn.length > 2 ? ` and ${facts.usedIn.length - 2} more` : ''}`)
+    if (entry.ownsBehaviours.length) lines.push(`  owns: ${entry.ownsBehaviours.map((owned) => owned.behaviour).join(' · ')}`)
+    if (entry.variants.length) lines.push(`  ${entry.variants.map((variant) => `${variant.prop}: ${variant.values.join(' | ')}`).join('   ')}`)
+    // The props the question named, with their own line — not all of them. A
+    // component with twenty props would bury its own answer.
+    const shown = finding.props
+      .filter((name) => !entry.variants.some((variant) => variant.prop === name))
+      .slice(0, 3)
+      .map((name) => entry.props.find((prop) => prop.name === name))
+    for (const prop of shown) {
+      if (prop) lines.push(`  ${prop.name}: ${prop.takes}${prop.note ? ` — ${prop.note}` : ''}`)
+    }
+    if (entry.props.length) lines.push(`  ${entry.props.length} props in all; see ${entry.docsId ? 'the page' : entry.sourceFile} for the rest`)
+    const link = docsLink(registryOf(entry), entry)
+    if (link) lines.push(`  ${link}`)
+    return lines.join('\n')
+  })
+
+  return blocks.join('\n\n')
+}

package/src/registry/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `@estiva-app/ui/registry` — the component catalogue (UIG-12, seam S2).
+ *
+ * The one copy, here, as every gate piece is (docs/GATES.md §23): the skill
+ * (UIG-20), the copy detector (UIG-25) and the merged search (UIG-19) read
+ * this, and no repo keeps a parser of its own.
+ *
+ * The data itself is `registry.json` at the package's root, committed and
+ * shipped. Read it with `estiva-ui find`, or import these to read it yourself.
+ * An app's own catalogue (UIG-13) is built from its code with
+ * `buildAppRegistry` each time it is read, and never committed.
+ */
+export { buildRegistry, readIndexExports, serializeRegistry, type BuildOptions } from './build'
+export { buildAppRegistry, type AppBuildOptions } from './app'
+export { docsLink, findInRegistries, findInRegistry, formatFindings, type Finding } from './find'
+export {
+  CLASSES,
+  SCHEMA_VERSION,
+  validateRegistry,
+  type AppFacts,
+  type EntryBehaviour,
+  type EntryClass,
+  type FileWithoutPart,
+  type EntryKind,
+  type EntryStatus,
+  type EntryVariant,
+  type PurposeSource,
+  type Registry,
+  type RegistryEntry,
+  type RegistryExclusion,
+} from './schema'