@estiva-app/ui 0.21.1 → 0.22.0

package/src/registry/cli.ts

@@ -0,0 +1,141 @@
+/// <reference types="node" />
+/**
+ * `estiva-ui` — the catalogue as a command (UIG-12; docs/GATES.md §23 for why
+ * it ships in the package rather than as a script pasted into each repo).
+ *
+ *   estiva-ui find <words…> [--json] [--limit n]   what do we have for this?
+ *   estiva-ui build [--out <path>]                 write registry.json
+ *   estiva-ui check                                rebuild and compare; CI runs this
+ *
+ * `find` reads the committed `registry.json`: the one in the folder it is run
+ * from, else the one shipped inside the installed package. So an app can ask
+ * the question without a checkout of this repo. `build` and `check` read the
+ * source, so they only mean anything inside the library they describe.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findInRegistry, formatFindings } from './find'
+import { validateRegistry, type Registry } from './schema'
+
+/**
+ * The builder, loaded only when it is used.
+ *
+ * It reads 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. `find` needs none of it: it reads a JSON file.
+ * 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 builder = () => import('./build')
+
+const [command, ...rest] = process.argv.slice(2)
+const flag = (name: string) => rest.includes(`--${name}`)
+const value = (name: string) => {
+  const at = rest.indexOf(`--${name}`)
+  return at === -1 ? undefined : rest[at + 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 (rest[i] === '--limit' || rest[i] === '--out' || rest[i] === '--file') i += 1
+      continue
+    }
+    out.push(rest[i])
+  }
+  return out
+}
+
+/** The committed file: where it is run, else the copy inside the installed package. */
+function registryPath(): string {
+  const named = value('file')
+  if (named) return resolve(named)
+  const here = resolve(process.cwd(), 'registry.json')
+  if (existsSync(here)) return here
+  // dist/registry/cli.js → the package's own root.
+  return fileURLToPath(new URL('../../registry.json', import.meta.url))
+}
+
+function readRegistry(): Registry {
+  const path = registryPath()
+  if (!existsSync(path)) throw new Error(`no registry.json at ${path} — run "estiva-ui build" in the library 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 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 registry = readRegistry()
+      const limit = Number(value('limit') ?? 5)
+      const findings = findInRegistry(registry, 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(registry, 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 { buildRegistry, serializeRegistry } = await builder()
+      const out = resolve(value('out') ?? 'registry.json')
+      const registry = buildRegistry()
+      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
+    }
+
+    case 'check': {
+      const { buildRegistry, serializeRegistry } = await builder()
+      const path = registryPath()
+      const built = buildRegistry()
+      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,195 @@
+/**
+ * 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[] {
+  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[] = []
+  for (const entry of registry.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] })
+  }
+
+  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || 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 the command prints: the import line first, because that is what the reader came for. */
+export function formatFindings(registry: Registry, findings: Finding[], query: string): string {
+  if (findings.length === 0) {
+    return [
+      `Nothing in ${registry.builtFrom.repo} matches "${query}".`,
+      'If nothing here does what you need, say so and ask — do not invent a component.',
+    ].join('\n')
+  }
+
+  const blocks = findings.map((finding) => {
+    const { entry } = finding
+    const lines = [
+      `${entry.name}  ·  ${entry.kind}  ·  ${entry.repo}  (matched ${finding.where.join(', ')})`,
+      `  ${entry.purpose}`,
+      `  import { ${entry.name} } from '${entry.importPath}'`,
+    ]
+    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 the page for the rest`)
+    const link = docsLink(registry, entry)
+    if (link) lines.push(`  ${link}`)
+    return lines.join('\n')
+  })
+
+  return blocks.join('\n\n')
+}

package/src/registry/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@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.
+ */
+export { buildRegistry, readIndexExports, serializeRegistry, type BuildOptions } from './build'
+export { docsLink, findInRegistry, formatFindings, type Finding } from './find'
+export {
+  SCHEMA_VERSION,
+  validateRegistry,
+  type EntryBehaviour,
+  type EntryKind,
+  type EntryStatus,
+  type EntryVariant,
+  type PurposeSource,
+  type Registry,
+  type RegistryEntry,
+  type RegistryExclusion,
+} from './schema'