@estiva-app/ui 0.21.1 → 0.23.0

package/dist/registry/schema.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The catalogue's shape (UIG-12, seam S2 in docs/GATES.md §16).
+ *
+ * A **data source read by machines first** and rendered second — not a
+ * documentation generator. The skill (UIG-20), the copy detector (UIG-25) and
+ * the merged search (UIG-19) all read this and nothing else, so the field
+ * names are the contract and `schemaVersion` is what makes a change to them
+ * detectable.
+ *
+ * Names are plain and ours. Open-sourcing is far off; when it comes, a
+ * renaming pass is one version bump, and guessing at a public vocabulary now
+ * would cost every reader between here and there.
+ */
+/**
+ * Raise this whenever a field is added, removed or given a new meaning. A
+ * reader that knows version N and is handed N+1 must be able to say so rather
+ * than silently read a field that moved.
+ */
+export declare const SCHEMA_VERSION = 2;
+/** What a name is, which decides how a reader offers it. */
+export type EntryKind = 
+/** Draws something. Used in JSX. */
+'component'
+/** A React hook: `use…`, callable only inside a component. */
+ | 'hook'
+/** A function or a constant. Neither of the above. */
+ | 'helper';
+/** Where an entry's one-line purpose was read from. */
+export type PurposeSource = 
+/** The `.mdx` page's opening paragraph — the name has a page of its own. */
+'page'
+/** The doc comment above the export — the name is documented on a sibling's page. */
+ | 'comment'
+/** An app's file that holds this one part: the comment at the top of the file (UIG-13). */
+ | 'file'
+/** An app's pass-on: the part is the package's, and says so (UIG-13). */
+ | 'package';
+/**
+ * Which of four kinds an app's part is (UIG-13), or that nothing uses it.
+ *
+ * Worked out from the code, never from the folder a file sits in: Peek's
+ * `components/ui` holds one-line pass-ons beside 187-line components.
+ */
+export type EntryClass = 
+/** Its file only hands a package part on, so the app keeps its own import path. */
+'re-export'
+/** Used in two or more places in the app. Gets a usage page (UIG-17, UIG-18). */
+ | 'reusable'
+/** Used in one place. Needs only its purpose line. */
+ | 'one-off'
+/** Reusable, and everything it uses is already in the package: it could move there. Katerina rules. */
+ | 'promote-candidate'
+/** No file of the app uses it: only its stories or tests, or nothing. Listed, never deleted by the catalogue. */
+ | 'unused';
+/**
+ * What the catalogue knows about a part that lives in an app (UIG-13). `null`
+ * on the package's own entries.
+ */
+export interface AppFacts {
+    class: EntryClass;
+    /** Why it has that class, in words: the evidence, or the written reason. */
+    reason: string;
+    /**
+     * `true` when the class is written beside the part (`@registry <class>: <reason>`
+     * in its comment) rather than worked out — "general, though one screen uses it yet".
+     */
+    written: boolean;
+    /** A pass-on's part, as `Name` for the package's and `Name from <package>` for another's. `null` otherwise. */
+    handsOn: string | null;
+    /**
+     * The app's files that use it, relative to the app: every file that imports it,
+     * and its own file when something else there draws it. Stories and tests are not
+     * uses — a part only they reach is unused.
+     */
+    usedIn: string[];
+    /**
+     * What ties it to this app: each import that is neither in the package's own
+     * dependencies nor an app file that is itself untied. Empty means it could
+     * live in the package as it is.
+     */
+    tiedTo: string[];
+    /** The package part with the same name, when there is one: the reader should see both. */
+    packageNamesake: string | null;
+    /** Imported as `import X from …` rather than `import { X } from …`. */
+    defaultExport: boolean;
+}
+/** A file in an app's target set that holds no part, and why, in words. */
+export interface FileWithoutPart {
+    file: string;
+    reason: string;
+}
+export type EntryStatus = 'stable' | 'migrating' | 'deprecated';
+/** A prop that takes one of a known set of words, and the set. */
+export interface EntryVariant {
+    prop: string;
+    values: string[];
+}
+/**
+ * One prop a component declares itself.
+ *
+ * **Itself**, not what it inherits: a component that extends
+ * `ComponentPropsWithRef<'div'>` would otherwise drag in every DOM attribute,
+ * which is noise in a catalogue whose whole point is a short answer.
+ */
+export interface EntryProp {
+    name: string;
+    /**
+     * What it takes, in a word a person reads: `true/false`, `number`, `text`,
+     * `anything`, `a handler`, the words themselves for a set (`left | right`),
+     * or the type as written where none of those fit.
+     */
+    takes: string;
+    required: boolean;
+    /** The first sentence of the prop's own comment, where it has one. */
+    note: string | null;
+}
+/** A behaviour this component owns, from UIG-8's enumeration. */
+export interface EntryBehaviour {
+    /** `OwnedBehaviour.id` — `portal`, `walking`, `scroll`… */
+    id: string;
+    /** What a person notices it doing, in words. */
+    behaviour: string;
+}
+export interface RegistryEntry {
+    /** The exported name, exactly as `index.ts` exports it. */
+    name: string;
+    /** Which library it came from: `estiva-ui`, or the app that owns it. */
+    repo: string;
+    kind: EntryKind;
+    /** What a caller actually types. */
+    importPath: string;
+    /** The file the name is declared in, relative to the repo. Several names share one file. */
+    sourceFile: string;
+    /** One line: what it is for. Never empty — the build fails instead. */
+    purpose: string;
+    purposeFrom: PurposeSource;
+    /**
+     * Every prop it declares itself — what it can do. This is the field a reader
+     * asks "does it already do X?" of, before writing X by hand.
+     */
+    props: EntryProp[];
+    /**
+     * The subset of `props` that takes one of a known set of words, structured.
+     * Kept beside `props` because it is what a search ranks well on, and what a
+     * caller most often needs named back at them.
+     */
+    variants: EntryVariant[];
+    /** What it owns, so a caller never rebuilds it (UIG-8). Empty for most. */
+    ownsBehaviours: EntryBehaviour[];
+    status: EntryStatus;
+    /**
+     * Which migration stage plans to change it.
+     *
+     * Always `null` here. The migration's plan lives in `K:/Estiva/migration
+     * docs`, which is not in this repo and is not in CI — and a copy kept here by
+     * hand is the drifting list this whole project exists to remove. The field
+     * stays in the schema because a later ticket may have a source a build can
+     * read; until then a reader gets an honest `null` rather than a stale number.
+     */
+    migrationStage: number | null;
+    /** The `.mdx` page's Storybook id, or `null` where the name has no page of its own. */
+    docsId: string | null;
+    /** A story that shows it, by Storybook id. `null` where nothing renders it alone. */
+    storyId: string | null;
+    /** The `.mdx` path, relative to the repo, or `null`. */
+    docPage: string | null;
+    /** An app's part: its class and the evidence for it (UIG-13). `null` on the package's own entries. */
+    app: AppFacts | null;
+}
+/** A name that is exported and deliberately not an entry. Empty today; the count still has to reconcile. */
+export interface RegistryExclusion {
+    name: string;
+    reason: string;
+}
+export interface Registry {
+    schemaVersion: number;
+    builtFrom: {
+        /**
+         * `package`: the package's catalogue, committed and shipped. `app`: one app's,
+         * built fresh from its code each time and never committed — Peek and Ship are
+         * private, the package is public (Katerina, 18 September 2026).
+         */
+        kind: 'package' | 'app';
+        repo: string;
+        /** The package the entries are imported from, or the app's own name. */
+        package: string;
+        packageVersion: string;
+        /**
+         * The package: value exports counted in `index.ts`. An app: parts found in its
+         * files. `entries + excluded` must equal it.
+         */
+        exports: number;
+        /** Type-only exports, which are not entries. Recorded so the count reconciles. `0` for an app. */
+        typeExports: number;
+        /**
+         * An app only: its `.tsx` files outside stories and tests. Each one either holds
+         * an entry or is in `filesWithoutParts`. `null` for the package.
+         */
+        files: number | null;
+    };
+    /**
+     * How to turn an id into a link. There is no Storybook on the internet yet
+     * (UIG-19), so an absolute URL committed here would resolve nowhere: the
+     * reader joins its own base to these.
+     */
+    storybook: {
+        docsPath: string;
+        storyPath: string;
+        devUrl: string;
+    };
+    entries: RegistryEntry[];
+    excluded: RegistryExclusion[];
+    /** An app's `.tsx` files that hold no part, each with its reason. Empty for the package. */
+    filesWithoutParts: FileWithoutPart[];
+}
+export declare const CLASSES: EntryClass[];
+/**
+ * Check a registry against this schema. Returns every problem, not the first:
+ * a build that reports one missing purpose per run costs one run per entry.
+ *
+ * An empty list is the only pass. CI runs this on the committed file.
+ */
+export declare function validateRegistry(value: unknown): string[];
+//# sourceMappingURL=schema.d.ts.map

package/dist/registry/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/registry/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -8,6 +8,7 @@
     "dist",
     "src",
     "stories",
+    "registry.json",
     "tailwind-preset.js",
     "tokens.css",
     "base.css",
@@ -27,6 +28,11 @@
       "types": "./dist/gates/index.d.ts",
       "default": "./dist/gates/index.js"
     },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "default": "./dist/registry/index.js"
+    },
+    "./registry.json": "./registry.json",
     "./tailwind-preset": "./tailwind-preset.js",
     "./tokens.css": "./tokens.css",
     "./package.json": "./package.json",
@@ -34,7 +40,8 @@
   },
   "bin": {
     "create-estiva-app": "dist/gates/create-app.js",
-    "estiva-gates": "dist/gates/cli.js"
+    "estiva-gates": "dist/gates/cli.js",
+    "estiva-ui": "dist/registry/cli.js"
   },
   "scripts": {
     "build": "node build.mjs && tsc -p tsconfig.build.json",
@@ -54,6 +61,12 @@
     "gates:status": "node dist/gates/cli.js status",
     "pregates:compare": "node build.mjs",
     "gates:compare": "node scripts/gates-compare.mjs",
+    "preregistry": "node build.mjs",
+    "registry": "node dist/registry/cli.js build",
+    "preregistry:check": "node build.mjs",
+    "registry:check": "node dist/registry/cli.js check",
+    "preui:find": "node build.mjs",
+    "ui:find": "node dist/registry/cli.js find --also peek=../peek --also ship=../ship/web",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {