@clay-design-system/registry 0.0.0-stage → 0.14.1

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import type { DatabaseSync } from 'node:sqlite';
+
+export declare const allowedChildren: (sectionIdOrAlias: string) => {
+    itemTypes: CompactRecord[];
+    components: CompactRecord[];
+    mediaSlots: unknown[];
+};
+
+export declare const assetUrl: (idOrAlias: string, opts?: {
+    format?: "svg" | "png";
+    variant?: string;
+}) => string | null;
+
+export declare const assetVariants: (idOrAlias: string) => {
+    variant: string;
+    id: string;
+}[];
+
+export declare interface CompactHit extends CompactRecord {
+    score: number;
+    /** K11: file-level asset twins folded into this hit. */
+    folded?: string[];
+}
+
+export declare interface CompactLinks {
+    /** `<import_path>#<export_name>` */
+    import?: string;
+    story?: string;
+    /**
+     * A Figma url. Prefers a link of the record itself (`variant ''`), then any variant's link; within each, role order
+     * desktop → showcase → component-set → node (lowest variant, then ref, first). Absent when the record has no figma link with a url.
+     */
+    figma?: string;
+    /** The Figma variable id (`VariableID:2751:137`) of a token's `''` (else first) variable link. Tokens' variable links carry no url. */
+    figmaVariable?: string;
+    /** default svg ?? png */
+    cdn?: string;
+}
+
+export declare interface CompactRecord {
+    id: string;
+    kind: string;
+    subkind?: string;
+    name: string;
+    scope: string;
+    status: string;
+    summary: string;
+    links?: CompactLinks;
+}
+
+export declare const componentsUsingToken: (tokenIdOrAlias: string) => CompactRecord[];
+
+/** Absolute path of the shipped SQLite database. */
+export declare const DB_PATH: string;
+
+export declare interface FullRecord extends Omit<RecordRow, 'rid'> {
+    aliases: {
+        alias: string;
+        type: string;
+    }[];
+    links: LinkRow[];
+    relations: {
+        out: (Omit<RelationRow, 'from_id'> & {
+            target?: CompactRecord;
+        })[];
+        in: (Omit<RelationRow, 'to_id' | 'to_ref'> & {
+            target: CompactRecord;
+        })[];
+    };
+    renders: Omit<RenderRow, 'html'>[] | RenderRow[];
+}
+
+export declare function get(idOrAlias: string, opts: GetOptions & {
+    as: 'unit';
+}): KbUnitLike | null;
+
+export declare function get(idOrAlias: string, opts: GetOptions & {
+    detail: true;
+}): FullRecord | null;
+
+export declare function get(idOrAlias: string, opts?: GetOptions): CompactRecord | FullRecord | KbUnitLike | null;
+
+export declare interface GetOptions {
+    detail?: boolean;
+    /** Return the KB unit exactly as `knowledge/clay-kb.json` holds it (round-trip contract). */
+    as?: 'unit';
+    /** With detail: include render HTML. */
+    html?: boolean;
+}
+
+/** A KB unit as the compiled KB holds it (`file` = the hand-written unit file). */
+export declare type KbUnitLike = Unit & {
+    file?: string;
+};
+
+export declare type LinkRow = {    record_id: string;    type: string;    role: string;    variant: string;    ref: string;    url: string | null;    name: string | null;    status: string;    verified_at: string | null;    confidence: string | null;    source: string;    note: string | null;    file_key: string | null;    node_id: string | null;    node_type: string | null;    variable_id: string | null;    collection: string | null;    mode: string | null;    story_id: string | null;    export_name: string | null;    import_path: string | null;    path: string | null;    anchor: string | null;    public_id: string | null;    brand: string | null;    format: string | null;    width: number | null;    height: number | null;    bytes: number | null;    content_hash: string | null;}
+
+export declare const list: (kind: string, filter?: ListFilter) => CompactRecord[];
+
+export declare interface ListFilter {
+    scope?: string;
+    status?: string;
+    limit?: number;
+}
+
+/** The package's registry (or the database at `path`), opened once. */
+export declare function openRegistry(path?: string): Registry;
+
+export declare const pageRecipe: (idOrAlias: string) => {
+    ord: number;
+    ref: string;
+    record: CompactRecord | null;
+}[];
+
+export declare type RecordRow = {    rid: number;    id: string;    entity_id: string | null;    kind: string;    subkind: string | null;    name: string;    scope: string;    status: string;    visibility: string;    authority: string;    topic: string;    summary: string;    when_to_use: string | null;    when_not_to_use: string | null;    body: string;    stages: ('design' | 'structure' | 'mapping' | 'assets' | 'copy' | 'page-file' | 'ux' | 'qa' | 'static' | 'fidelity')[];    modes: string[] | null;    entities: string[];    severity: string | null;    enforcement: string[] | null;    tags: string[];    facts: unknown;    data: unknown;    handbook_id: string | null;    source_path: string;    source_anchor: string | null;    generated_by: string | null;    unit_file: string | null;    verified_at: string;    content_hash: string;}
+
+/** Absolute path of the shipped records dump (JSON lines, links and outgoing relations inlined). */
+export declare const RECORDS_PATH: string;
+
+/** A read-only handle on a registry database; opens the package's own database unless given a path. */
+export declare class Registry extends Registry_2 {
+    constructor(path?: string);
+}
+
+declare class Registry_2 {
+    readonly path: string;
+    readonly db: DatabaseSync;
+    private stats?;
+    private entityNames?;
+    constructor(path?: string);
+    close(): void;
+    meta(key: string): string | undefined;
+    /** Record id for an id or alias (entity id, handbook id), or null. */
+    resolve(idOrAlias: string): string | null;
+    /**
+     * Every record as the KB unit it was built from (`get(id, { as: 'unit' })` for all of them), sorted by id, in two queries.
+     * The `clay` CLI and the MCP server read their knowledge base from here.
+     */
+    allUnits(): KbUnitLike[];
+    private row;
+    private linksOf;
+    private compactLinks;
+    compact(r: Pick<RecordRow, 'id' | 'kind' | 'subkind' | 'name' | 'scope' | 'status' | 'summary'>): CompactRecord;
+    search(query: string, opts?: SearchOptions): CompactHit[];
+    /** Raw hits, the same shape `clay search` returns (parity tests compare these). */
+    searchHits(query: string, opts?: SearchOptions): SearchHit[];
+    get(idOrAlias: string, opts: GetOptions & {
+        as: 'unit';
+    }): KbUnitLike | null;
+    get(idOrAlias: string, opts: GetOptions & {
+        detail: true;
+    }): FullRecord | null;
+    get(idOrAlias: string, opts?: GetOptions): CompactRecord | FullRecord | KbUnitLike | null;
+    private compactOf;
+    list(kind: string, filter?: ListFilter): CompactRecord[];
+    related(idOrAlias: string, opts?: RelatedOptions): {
+        direction: 'out' | 'in';
+        type: string;
+        ord: number;
+        record: CompactRecord;
+    }[];
+    /** The variants a logo family offers, read from each file's `data` (customer: the key after the brand; integration: `default`; product: the whole key). */
+    assetVariants(idOrAlias: string): {
+        variant: string;
+        id: string;
+    }[];
+    /** The cdn URL of an asset. A logo family resolves to its file in `variant` (none given: `default`, then the first file; an unmatched variant: null). */
+    assetUrl(idOrAlias: string, opts?: {
+        format?: 'svg' | 'png';
+        variant?: string;
+    }): string | null;
+    /** The record's own cdn file in `variant` (the cdn rows' `variant` column; '' = the record itself). */
+    private ownCdnUrl;
+    componentsUsingToken(tokenIdOrAlias: string): CompactRecord[];
+    /** What a section can hold: its item types, the components its layouts nest, and its media slots (from handbook data). */
+    allowedChildren(sectionIdOrAlias: string): {
+        itemTypes: CompactRecord[];
+        components: CompactRecord[];
+        mediaSlots: unknown[];
+    };
+    /** The ordered sections / layouts a recipe (or, from 1B, a page) is composed of. */
+    pageRecipe(idOrAlias: string): {
+        ord: number;
+        ref: string;
+        record: CompactRecord | null;
+    }[];
+}
+
+export declare const related: (idOrAlias: string, opts?: RelatedOptions) => {
+    direction: "out" | "in";
+    type: string;
+    ord: number;
+    record: CompactRecord;
+}[];
+
+export declare interface RelatedOptions {
+    type?: string | string[];
+    direction?: 'out' | 'in' | 'both';
+    kind?: string[];
+}
+
+export declare type RelationRow = {    from_id: string;    type: string;    to_id: string | null;    to_ref: string;    ord: number;    source: string;}
+
+export declare type RenderRow = {    record_id: unknown;    variant: unknown;    theme: unknown;    engine: unknown;    story_id: unknown;    html: unknown;    html_hash: unknown;    input_hash: unknown;    css_refs: unknown;    png_1440: unknown;    png_375: unknown;    mirror_url: unknown;    interactive: number;    version: unknown;    checked_at: unknown;}
+
+export declare const search: (query: string, opts?: SearchOptions) => CompactHit[];
+
+export declare interface SearchHit {
+    id: string;
+    score: number;
+    kind: string;
+    authority: string;
+    summary: string;
+    /** K11: near-duplicate asset units folded into this hit (file-level variants of one registry entry). */
+    aliases?: string[];
+}
+
+export declare interface SearchOptions {
+    k?: number;
+    kind?: string[];
+    scope?: string[];
+    stage?: string[];
+    mode?: 'A' | 'B';
+    /** Entity ids (`section:FeaturesSection`); a unit matches when it carries any of them. */
+    entity?: string[];
+    authority?: string[];
+    includeBackground?: boolean;
+}
+
+declare type Unit = {    id: string;    kind: 'section' | 'layout' | 'rule' | 'component' | 'limit' | 'item-type' | 'token' | 'breakpoint' | 'page' | 'skill' | 'asset' | 'recipe' | 'policy' | 'gotcha' | 'procedure' | 'brand-fact' | 'stat' | 'background';    scope: 'web' | 'email' | 'ds' | 'shared';    topic: string;    authority: 'background' | 'canonical' | 'derived' | 'guidance';    stages: ('design' | 'structure' | 'mapping' | 'assets' | 'copy' | 'page-file' | 'ux' | 'qa' | 'static' | 'fidelity')[];    entities: string[];    summary: string;    body: string;    source: {        path: string;        anchor?: string | undefined;        generatedBy?: string | undefined;    };    status: 'deprecated' | 'active';    verifiedAt: string;    subkind?: 'agent' | 'shape' | 'atom' | 'molecule' | 'primitive' | 'icon' | 'logo' | 'logo-file' | 'badge' | 'image' | 'token-group' | undefined;    modes?: ('A' | 'B')[] | undefined;    when?: string | undefined;    notWhen?: string | undefined;    severity?: 'Critical' | 'Major' | 'Minor' | undefined;    enforcement?: ('qa' | 'lint' | 'script' | 'test' | 'review' | 'types')[] | undefined;    relations?: {        supersedes?: string[] | undefined;        conflictsWith?: string[] | undefined;        seeAlso?: string[] | undefined;        precedence?: string[] | undefined;    } | undefined;    visibility?: 'public' | 'internal' | undefined;    handbookId?: string | undefined;    data?: unknown;    facts?: unknown;}
+
+export { }