@naturaldesign/dev 0.0.0-stage → 0.0.12

package/dist/types/ast.d.ts

@@ -0,0 +1,24 @@
+export interface Node {
+    type: string;
+    start?: number | null;
+    end?: number | null;
+    loc?: {
+        start: {
+            line: number;
+            column: number;
+        };
+    } | null;
+    [key: string]: unknown;
+}
+/** Parses JS/TS with JSX; null when the file does not parse at all (errorRecovery keeps most broken files). */
+export declare function parseModule(code: string): Node | null;
+/** The Program node of a parsed File. */
+export declare function programOf(file: Node): Node;
+/** Depth-first walk over every child node. `enter` returning false skips the node's children. */
+export declare function walk(node: Node | null | undefined, enter: (node: Node, parent: Node | null) => boolean | void, parent?: Node | null): void;
+/** `Foo`, `Foo.Bar`, `ns:tag` for a JSX element name node. */
+export declare function jsxName(name: Node): string;
+/** Whether a file's directive prologue says 'use client'. */
+export declare function hasUseClient(file: Node): boolean;
+/** A literal's static value (string, number, boolean, null, negative numbers, plain template strings); undefined when not static. */
+export declare function staticValue(node: Node | null | undefined): string | number | boolean | null | undefined;

package/dist/types/babel.d.ts

@@ -0,0 +1,50 @@
+import { type ComponentDecl } from './owners';
+import { type Node } from './ast';
+interface BabelApi {
+    types: {
+        jsxAttribute: (name: unknown, value: unknown) => unknown;
+        jsxIdentifier: (name: string) => unknown;
+        stringLiteral: (value: string) => unknown;
+    };
+}
+interface PluginOptions {
+    root?: string;
+    always?: boolean;
+    calls?: boolean;
+    owners?: boolean;
+    exclude?: string[];
+}
+interface Attribute {
+    type: string;
+    name?: {
+        type: string;
+        name?: string;
+    };
+}
+interface OpeningPath {
+    node: {
+        start?: number | null;
+        name: Node;
+        attributes: Attribute[];
+        loc?: {
+            start: {
+                line: number;
+                column: number;
+            };
+        } | null;
+    };
+}
+interface PluginState {
+    filename?: string;
+    ndComponents?: ComponentDecl[];
+}
+export default function naturalDesignBabel(api: BabelApi, options?: PluginOptions): {
+    name: string;
+    visitor: {
+        Program(path: {
+            node: Node;
+        }, state: PluginState): void;
+        JSXOpeningElement(path: OpeningPath, state: PluginState): void;
+    };
+};
+export {};

package/dist/types/component-index/babel-props.d.ts

@@ -0,0 +1,35 @@
+import { type Node } from '../ast';
+import type { PropDefault, PropEntry, PropKind } from './types';
+export type TypeScope = Map<string, Node>;
+/**
+ * Top-level interfaces and type aliases of a script, exported or not; and (keyed `value:<name>`)
+ * the cva / tailwind-variants calls `VariantProps<typeof name>` reads its props from.
+ */
+export declare function typeScope(program: Node): TypeScope;
+/** Type arguments of a call or type reference (Babel 7 says typeParameters, Babel 8 typeArguments). */
+export declare function typeArguments(node: Node | null | undefined): Node[];
+interface Kind {
+    type: PropKind;
+    options?: string[];
+}
+/** Classifies one prop's type node. */
+export declare function classifyType(type: Node | null | undefined, scope: TypeScope, depth?: number): Kind;
+/** One kind for a union: all string literals → enum, all booleans → boolean, strings and literals → text, a slot anywhere → slot. */
+export declare function mergeKinds(kinds: Kind[]): Kind;
+/** Props of a type node (literal, local interface/alias, intersection, `PropsWithChildren<…>`); null when nothing about it resolves locally. */
+export declare function propsFromType(type: Node | null | undefined, scope: TypeScope, depth?: number): PropEntry[] | null;
+/** Later lists win on a name clash, as an interface's own members override what it extends. */
+export declare function mergeProps(lists: PropEntry[][]): PropEntry[];
+/** `{ size = 'md', title, ...rest }`: names and static defaults, in order. */
+export declare function patternDefaults(pattern: Node | null | undefined): {
+    name: string;
+    default?: PropDefault;
+}[];
+/** A prop's kind guessed from its default, for untyped code. */
+export declare function kindOfValue(value: PropDefault | undefined): PropKind;
+/** Typed props with destructuring defaults laid over them; untyped names become props of their default's kind. */
+export declare function withDefaults(typed: PropEntry[] | null, defaults: {
+    name: string;
+    default?: PropDefault;
+}[]): PropEntry[];
+export {};

package/dist/types/component-index/react-babel.d.ts

@@ -0,0 +1,6 @@
+import { type ComponentDecl } from '../owners';
+import { type TypeScope } from './babel-props';
+import type { ComponentEntry, PropEntry } from './types';
+export declare function reactPropsFromBabel(component: ComponentDecl, scope: TypeScope): PropEntry[];
+/** Exported React components of one module, from its source text. */
+export declare function indexReactWithBabel(code: string, file: string, rel: string): ComponentEntry[];

package/dist/types/component-index/react-ts.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentEntry } from './types';
+export interface TsIndexer {
+    index(files: string[]): Map<string, ComponentEntry[]>;
+    /** The React components an installed package exports, from its type declarations. */
+    indexPackage(name: string): ComponentEntry[];
+}
+/** The project's TypeScript, wrapped; null when the project has no `typescript` package. */
+export declare function tsIndexerFor(root: string): TsIndexer | null;

package/dist/types/component-index/scan.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentEntry } from './types';
+export declare const COMPONENT_FOLDERS: string[];
+export interface IndexOptions {
+    /** Folders to scan, relative to the root (default COMPONENT_FOLDERS). */
+    folders?: string[];
+    /** Use the project's `typescript` for React props (default true). */
+    typescript?: boolean;
+    /** Installed npm packages whose exported React components join the index (read from their type declarations). */
+    packages?: string[];
+}
+export declare function isComponentSource(file: string): boolean;
+/** Whether a file is inside one of the component folders (and so belongs in the index). */
+export declare function inComponentFolder(root: string, file: string, folders?: string[]): boolean;
+/** Every component file under the root's component folders, absolute and sorted. */
+export declare function componentFiles(root: string, folders?: string[]): string[];
+/** Indexes the given files (absolute). React files share one TypeScript program. */
+export declare function indexFiles(root: string, files: string[], options?: IndexOptions): Map<string, ComponentEntry[]>;
+/** The project's components: one entry per exported component in the component folders, then the listed packages'. */
+export declare function indexComponents(projectRoot: string, options?: IndexOptions): ComponentEntry[];

package/dist/types/component-index/sfc.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentEntry } from './types';
+export declare function indexSvelte(source: string, file: string, rel: string): ComponentEntry[];
+export declare function indexVue(source: string, file: string, rel: string): ComponentEntry[];
+export declare function indexAstro(source: string, file: string, rel: string): ComponentEntry[];

package/dist/types/component-index/types.d.ts

@@ -0,0 +1,24 @@
+export type Framework = 'react' | 'svelte' | 'vue' | 'astro';
+/** How the inspector edits a prop: enum (a menu of options), text, number, boolean, slot (children-like content), other (read-only "from code"). */
+export type PropKind = 'enum' | 'text' | 'number' | 'boolean' | 'slot' | 'other';
+export type PropDefault = string | number | boolean | null;
+export interface PropEntry {
+    name: string;
+    type: PropKind;
+    /** The string literals of an enum prop, in declaration order. */
+    options?: string[];
+    optional: boolean;
+    /** A static default from the source (destructuring default, withDefaults, `export let x = …`). */
+    default?: PropDefault;
+}
+export interface ComponentEntry {
+    name: string;
+    /** Path relative to the project root, `/`-separated. */
+    file: string;
+    /** `default` or the exported name. Svelte, Vue and Astro components are always `default`. */
+    exportName: string;
+    framework: Framework;
+    props: PropEntry[];
+    /** Set for a component an installed npm package exports: `file` is then the package name (read-only). */
+    package?: string;
+}

package/dist/types/derive/entry.d.ts

@@ -0,0 +1,19 @@
+import type { Framework } from '../component-index/types';
+export interface EntryOptions {
+    /** Absolute path of the component file. */
+    file: string;
+    exportName: string;
+    framework: Framework;
+    /** Absolute paths (or bare specifiers) of global stylesheets to bundle. */
+    stylesheets: string[];
+    /** Absolute path of natural.config.*, whose `decorator` wraps the component (React only). */
+    configFile: string | null;
+    /** Props merged under the ones `mount` receives. */
+    props: Record<string, unknown>;
+    /** Meta exported as-is, for the app's bookkeeping. */
+    meta: Record<string, unknown>;
+}
+/** The entry module for one component; null for frameworks that cannot mount in a browser (Astro). */
+export declare function entryModule(options: EntryOptions): string | null;
+/** The framework runtime packages an entry imports: if one of these is stubbed, nothing can render. */
+export declare const RUNTIME_PACKAGES: Record<Framework, string[]>;

package/dist/types/derive/esbuild.d.ts

@@ -0,0 +1,23 @@
+import type { BundleOutput } from './vite';
+export interface Esbuild {
+    build: (options: Record<string, unknown>) => Promise<{
+        outputFiles?: {
+            path: string;
+            contents: Uint8Array;
+        }[];
+        warnings: {
+            text: string;
+        }[];
+    }>;
+    version?: string;
+}
+export interface EsbuildDeriveInput {
+    root: string;
+    out: string;
+    entryCode: string;
+    /** Extra folders to resolve bare imports from (the app's bundled react/react-dom at the partial rung). */
+    nodePaths: string[];
+}
+export declare function bundleWithEsbuild(esbuild: Esbuild, input: EsbuildDeriveInput): Promise<BundleOutput & {
+    stubs: string[];
+}>;

package/dist/types/derive/index.d.ts

@@ -0,0 +1,34 @@
+import type { Framework } from '../component-index/types';
+export interface DeriveOptions {
+    /** Project root (the folder with package.json). */
+    root: string;
+    /** Component file, absolute or relative to the root. */
+    file: string;
+    /** `default` or the exported name. */
+    exportName: string;
+    /** Output folder; receives component.js and component.css. */
+    out: string;
+    /** Props baked in as `defaultProps` (mount's props are laid over them). */
+    props?: Record<string, unknown>;
+    /** An esbuild package folder (or a folder whose node_modules has one): the app's sidecar. */
+    esbuild?: string;
+    /** Extra folders to resolve bare imports from in the esbuild path (the app's bundled react and react-dom). */
+    nodePaths?: string[];
+    /** Force a bundler (default: Vite when the project has it, esbuild otherwise). */
+    bundler?: 'auto' | 'vite' | 'esbuild';
+    /** Global stylesheets to bundle, root-relative (default: found from the app's entry). */
+    styles?: string[];
+}
+export interface DeriveResult {
+    ok: boolean;
+    /** Built without the project's dependencies, or with imports stubbed: the `partial` rung. */
+    partial: boolean;
+    js: string | null;
+    css: string | null;
+    warnings: string[];
+    bundler: 'vite' | 'esbuild' | null;
+    framework: Framework | null;
+    /** Specifiers replaced by stubs. */
+    stubs: string[];
+}
+export declare function derive(options: DeriveOptions): Promise<DeriveResult>;

package/dist/types/derive/postcss.d.ts

@@ -0,0 +1,4 @@
+type Process = (css: string, from: string) => Promise<string>;
+/** A function running the project's PostCSS config over a stylesheet, or null when the project has none. */
+export declare function projectPostcss(root: string, warnings: string[]): Promise<Process | null>;
+export {};

package/dist/types/derive/shims.d.ts

@@ -0,0 +1,10 @@
+export declare const NEXT_SHIMS: string[];
+export declare function isShimmed(specifier: string): boolean;
+/** Every specifier a module imports or re-exports from, with the names it takes: `import { A, B as C } from 'x'` → A, B; `import D from 'x'` → default. */
+export declare function importsOf(code: string): Map<string, Set<string>>;
+/** The names a module file takes from a specifier (cached by mtime). */
+export declare function importedNames(importer: string, specifier: string): string[];
+/** An ES module whose default and named exports are all the same forgiving stub. */
+export declare function stubModule(names: string[], label: string): string;
+/** Module code for a shimmed `next/*` (or `server-only`) specifier; `names` are what the importer takes from it (for next/font). */
+export declare function nextShim(specifier: string, names: string[]): string;

package/dist/types/derive/vite.d.ts

@@ -0,0 +1,15 @@
+export interface ViteDeriveInput {
+    root: string;
+    out: string;
+    entryCode: string;
+}
+export interface BundleOutput {
+    js: string;
+    css: string;
+    warnings: string[];
+}
+interface ViteModule {
+    build: (config: Record<string, unknown>) => Promise<unknown>;
+}
+export declare function bundleWithVite(vite: ViteModule, input: ViteDeriveInput): Promise<BundleOutput>;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export { stampJsx, stampable, parseStamp, parseOwner, relativeTo, registrationCode, callExcluded, STAMP_ATTRIBUTE, CALL_ATTRIBUTE, OWNER_ATTRIBUTE } from './stamp';
+export type { StampOptions, StampResult } from './stamp';
+export { exportedComponents, ownerAt, componentNameFromFile } from './owners';
+export type { ComponentDecl } from './owners';
+export { indexComponents, indexFiles, componentFiles, COMPONENT_FOLDERS } from './component-index/scan';
+export type { IndexOptions } from './component-index/scan';
+export type { ComponentEntry, PropEntry, PropKind, PropDefault, Framework } from './component-index/types';
+export { writeDescriptors, descriptorName, NEXT_INDEX_DIR } from './next-index';
+export type { NextDescriptor } from './next-index';
+export { REGISTRY_ID, HOST_ID, HOST_PATH, INDEX_PATH } from './registry';
+export { derive } from './derive/index';
+export type { DeriveOptions, DeriveResult } from './derive/index';

package/dist/types/loader.d.ts

@@ -0,0 +1,24 @@
+export interface NaturalDesignLoaderOptions {
+    root?: string;
+    /** Component names that must not receive data-nd-call. */
+    exclude?: string[];
+    /** Call-site stamps on component elements (default true). */
+    calls?: boolean;
+    /** Owner stamps on host elements (default true). */
+    owners?: boolean;
+    /** Register exported components of 'use client' files with `window.__nd` (default true). */
+    register?: boolean;
+    /** Write component descriptors to `.next/natural/index/` (default true). */
+    index?: boolean;
+    /** Folders the index covers, relative to the root (default: the usual component folders). */
+    indexFolders?: string[];
+}
+interface LoaderContext {
+    resourcePath: string;
+    rootContext?: string;
+    mode?: string;
+    getOptions?: () => NaturalDesignLoaderOptions;
+    callback: (error: Error | null, code?: string, map?: unknown) => void;
+}
+export default function naturalDesignLoader(this: LoaderContext, source: string, map?: unknown): void;
+export {};

package/dist/types/next-index.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentEntry } from './component-index/types';
+export declare const NEXT_INDEX_DIR = ".next/natural/index";
+export interface NextDescriptor {
+    file: string;
+    framework: 'react';
+    components: ComponentEntry[];
+}
+/** The descriptor's file name for a project-relative source path: the path, URI-encoded, plus `.json`. */
+export declare function descriptorName(rel: string): string;
+/** Writes (or removes) the descriptors for these files now. */
+export declare function writeDescriptors(root: string, files: string[]): void;
+/** Queues a file the loader just compiled; component files in the component folders get a descriptor shortly after. */
+export declare function scheduleDescriptor(root: string, file: string, folders?: string[]): void;

package/dist/types/owners.d.ts

@@ -0,0 +1,26 @@
+import { type Node } from './ast';
+export interface ComponentDecl {
+    /** Display name: the binding's name, or one made from the file name for an anonymous default export. */
+    name: string;
+    /** `default` or the exported name; what the index calls `exportName` and the owner stamp carries. */
+    exportName: string;
+    /** A binding that names the component at the end of the module; null for anonymous default exports. */
+    localName: string | null;
+    /** Source range of the declaration whose body JSX belongs to this component. */
+    start: number;
+    end: number;
+    /** The component function, when there is one (props are its first parameter). */
+    fn: Node | null;
+    /** The declaring node: a FunctionDeclaration, a VariableDeclarator (for `FC<Props>` annotations) or the default export's expression. */
+    node: Node;
+    kind: 'function' | 'class';
+}
+export declare function isComponentName(name: string): boolean;
+/** `button-group.tsx` → ButtonGroup; `index.tsx` and `page.tsx` take their folder's name when it says more. */
+export declare function componentNameFromFile(file: string): string;
+/** Exported components of a module, in source order. `file` names anonymous default exports. */
+export declare function exportedComponents(ast: Node, file: string): ComponentDecl[];
+/** The component whose declaration contains a source offset. */
+export declare function ownerAt(components: ComponentDecl[], offset: number): ComponentDecl | null;
+/** One entry per exported component (the owner list can hold a wrapped implementation's range twice). */
+export declare function uniqueComponents(components: ComponentDecl[]): ComponentDecl[];

package/dist/types/project.d.ts

@@ -0,0 +1,12 @@
+export declare function projectRequire(root: string): NodeRequire;
+/** Resolves a package's entry from the project, or null. `esm` prefers the `import` condition
+ * (vite's CJS entry is deprecated and hides its named exports from `import()`). */
+export declare function resolveFromProject(root: string, name: string, esm?: boolean): string | null;
+/** `require` for CommonJS packages (typescript), null when the project does not have it. */
+export declare function requireFromProject<T = unknown>(root: string, name: string): T | null;
+/** `import()` for packages that may be ESM-only (vite), null when the project does not have it. */
+export declare function importFromProject<T = unknown>(root: string, name: string): Promise<T | null>;
+export declare function hasPackage(root: string, name: string): boolean;
+export declare function readJson<T>(file: string): T | null;
+/** The project's version of a package (`18.3.1`), or null. */
+export declare function packageVersion(root: string, name: string): string | null;

package/dist/types/registry.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentEntry, Framework } from './component-index/types';
+export declare const REGISTRY_ID = "virtual:natural-design/registry";
+export declare const HOST_ID = "virtual:natural-design/host";
+export declare const HOST_PATH = "/__natural/host";
+export declare const INDEX_PATH = "/__natural/components.json";
+/** A URL Vite serves for a project file: root-relative inside the root, `/@fs/` outside it. */
+export declare function serveUrl(root: string, file: string): string;
+/** The project's `natural.config.*`, whose `decorator` wraps every rendered component in the app's providers. */
+export declare function naturalConfigFile(root: string): string | null;
+/** The registry module's code. `frameworks` lists those whose runtime the project can resolve. */
+export declare function registryModule(root: string, components: ComponentEntry[], frameworks: Set<Framework>, packages?: string[]): string;
+/** The host page's module: global styles, the registry, the decorator, and `?component=Name&props={…}` for a direct render. */
+export declare function hostModule(root: string, stylesheets: string[], configFile: string | null): string;
+/** The bare host document, before Vite's transformIndexHtml adds its client and the React refresh preamble. */
+export declare function hostHtml(root: string, base: string): string;

package/dist/types/stamp.d.ts

@@ -0,0 +1,56 @@
+import MagicString from 'magic-string';
+import { type Node } from './ast';
+export declare const STAMP_ATTRIBUTE = "data-nd-source";
+export declare const CALL_ATTRIBUTE = "data-nd-call";
+export declare const OWNER_ATTRIBUTE = "data-nd-owner";
+export interface StampOptions {
+    /** Absolute path of the file being compiled. */
+    file: string;
+    /** Project root the stamp's path is relative to (the webframe's `root`). */
+    root: string;
+    /** Give component elements a data-nd-call stamp (default true). */
+    calls?: boolean;
+    /** Give host elements a data-nd-owner stamp (default true). */
+    owners?: boolean;
+    /** Components that must not receive the call stamp (they iterate their props, or use exact prop-types). `Foo.Bar` or a bare name, which also matches the last segment. */
+    exclude?: string[];
+    /** Append a render-registry registration for each exported component, in 'use client' files only (Next, plan 7.1). */
+    register?: boolean;
+}
+export interface StampResult {
+    code: string;
+    map: ReturnType<MagicString['generateMap']>;
+    /** How many host elements got a source stamp. */
+    count: number;
+    /** How many component elements got a call stamp. */
+    calls: number;
+    /** Names registered with the render registry. */
+    registered: string[];
+}
+export declare function relativeTo(root: string, file: string): string;
+/** Whether this is a production build: read at run time (a bundler would otherwise bake its own build-time value in). */
+export declare function productionBuild(): boolean;
+/** Files the plugin may stamp: project JSX/TSX outside node_modules. */
+export declare function stampable(file: string): boolean;
+/** Whether a component element is excluded from call stamps: fragments always, then the user's list. */
+export declare function callExcluded(name: string, exclude?: readonly string[]): boolean;
+/** Component element names: a capitalised identifier or any member expression (`ui.Card`, `motion.div`). */
+export declare function isComponentElement(name: Node): boolean;
+/** The registration statement the Next loader appends to a 'use client' module (plan 7.1, render registry). */
+export declare function registrationCode(entries: {
+    name: string;
+    local: string;
+    exportName: string;
+}[], file: string): string;
+export declare function stampJsx(code: string, options: StampOptions): StampResult | null;
+/** Parses a source or call stamp back into its parts (the agent and the mirror share this shape). */
+export declare function parseStamp(value: string | null | undefined): {
+    file: string;
+    line: number;
+    column: number;
+} | null;
+/** Parses an owner stamp (`file:ExportName`). */
+export declare function parseOwner(value: string | null | undefined): {
+    file: string;
+    exportName: string;
+} | null;

package/dist/types/styles.d.ts

@@ -0,0 +1,7 @@
+/** Absolute paths of the global stylesheets, in import order. `explicit` (root-relative) wins when given. */
+export declare function globalStylesheets(root: string, explicit?: string[]): string[];
+/** `<html …>` and `<body …>` attributes of the project's index.html (theme classes, fonts), for the host page. */
+export declare function documentAttributes(root: string): {
+    html: string;
+    body: string;
+};

package/dist/types/vite.d.ts

@@ -0,0 +1,58 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface NaturalDesignViteOptions {
+    root?: string;
+    /** Component names that must not receive data-nd-call. */
+    exclude?: string[];
+    /** Call-site stamps on component elements (default true). */
+    calls?: boolean;
+    /** Owner stamps on host elements (default true). */
+    owners?: boolean;
+    /** Serve the component index at /__natural/components.json (default true). */
+    index?: boolean;
+    /** Folders the index covers, relative to the root (default: src/components, components, src/lib/components, app/components, src/ui). */
+    indexFolders?: string[];
+    /** The render registry: virtual module, `window.__nd` in the app's pages, and /__natural/host (default true). */
+    registry?: boolean;
+    /** Global stylesheets for the host page, root-relative (default: found from index.html and the entry's CSS imports). */
+    styles?: string[];
+    /** Installed npm packages (`@acme/ui`) whose React components join the index and the registry, read-only. */
+    packages?: string[];
+}
+interface ViteServer {
+    middlewares: {
+        use: (handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void) => void;
+    };
+    watcher: {
+        on: (event: 'all', listener: (event: string, file: string) => void) => void;
+    };
+    moduleGraph: {
+        getModuleById: (id: string) => unknown;
+        invalidateModule: (module: never) => void;
+    };
+    transformIndexHtml: (url: string, html: string, originalUrl?: string) => Promise<string>;
+}
+export default function naturalDesign(options?: NaturalDesignViteOptions): {
+    name: string;
+    apply: "serve";
+    enforce: "pre";
+    configResolved(config: {
+        root: string;
+        base?: string;
+    }): void;
+    transform(code: string, id: string): {
+        code: string;
+        map: import("magic-string").SourceMap;
+    };
+    resolveId(id: string): string;
+    load(id: string): string;
+    transformIndexHtml(): {
+        tag: string;
+        attrs: {
+            type: string;
+            src: string;
+        };
+        injectTo: "head";
+    }[];
+    configureServer(server: ViteServer): void;
+};
+export {};