@texuli/spec 0.0.0-stage → 0.1.0-next.1

package/dist/generated/typescript/vocabulary.js

@@ -0,0 +1,140 @@
+// Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
+// Spec 0.2.0, digest d9eccaba1826e7d87648a4a33787d873245592dda843607a10b2c68a77f1806f
+/** The built catalog this vocabulary was projected from. */
+export const SPEC_CATALOG_HASH = 'b073e30b4c8b1a30b3ef3ccb372e552d2d88e584616b74591c6c32923b471376';
+/** Every closed component id, sorted. */
+export const SPEC_COMPONENT_IDS = [
+    'alert',
+    'alert-dialog',
+    'analytics-grid',
+    'app-nav',
+    'badge',
+    'banner',
+    'blocks-code',
+    'blocks-data',
+    'blocks-diagram',
+    'blocks-embed',
+    'blocks-interactive',
+    'blocks-map',
+    'blocks-media',
+    'blocks-structure',
+    'blocks-text',
+    'breadcrumb',
+    'button',
+    'button-group',
+    'callout',
+    'card',
+    'charts-area',
+    'charts-bar',
+    'charts-bubble',
+    'charts-bullet',
+    'charts-canvas-renderer',
+    'charts-cartesian',
+    'charts-combo',
+    'charts-donut',
+    'charts-funnel',
+    'charts-gauge',
+    'charts-geo-map',
+    'charts-geo-point-map',
+    'charts-heatmap',
+    'charts-line',
+    'charts-network',
+    'charts-pie',
+    'charts-progress-ring',
+    'charts-sankey',
+    'charts-scatter',
+    'charts-sparkline',
+    'charts-stacked-bar',
+    'charts-sunburst',
+    'charts-treemap',
+    'checkbox',
+    'chip',
+    'code',
+    'combobox',
+    'command-palette',
+    'content-layout',
+    'context-menu',
+    'context-menu-trigger',
+    'deck-slide',
+    'description',
+    'detail-panel',
+    'dialog',
+    'drawer',
+    'dropdown-menu',
+    'dropdown-menu-content',
+    'dropdown-menu-item',
+    'dropdown-menu-trigger',
+    'empty-state',
+    'error-state',
+    'field',
+    'field-error',
+    'form',
+    'hover-card',
+    'hover-card-content',
+    'icon-button',
+    'inline-text',
+    'input',
+    'input-group',
+    'kbd',
+    'kpi',
+    'label',
+    'layout-auth-split',
+    'layout-blog',
+    'layout-card',
+    'layout-chrome',
+    'layout-dashboard-grid',
+    'layout-deck',
+    'layout-doc',
+    'layout-docs',
+    'layout-drawer',
+    'layout-dual-sidebar',
+    'layout-editorial',
+    'layout-grid',
+    'layout-host',
+    'layout-landing',
+    'layout-marketing',
+    'layout-page',
+    'layout-pricing',
+    'layout-settings',
+    'layout-sidebar',
+    'layout-top-nav',
+    'layout-wizard',
+    'media-composition-canvas',
+    'media-composition-svg',
+    'media-image',
+    'menubar',
+    'menubar-trigger',
+    'multi-select',
+    'nav-icon',
+    'navigation-menu',
+    'pagination',
+    'popover',
+    'popover-content',
+    'radio',
+    'radio-group',
+    'responsive-modal',
+    'screen-outlet',
+    'select',
+    'select-content',
+    'select-group',
+    'select-item',
+    'select-label',
+    'select-portal',
+    'select-separator',
+    'select-trigger',
+    'select-value',
+    'select-viewport',
+    'sheet',
+    'sidebar',
+    'split-view',
+    'stat',
+    'stepper',
+    'switch',
+    'table',
+    'tag',
+    'text-counter',
+    'textarea',
+    'timeline',
+    'toaster',
+    'tooltip',
+];

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
+ * B1), runtime half: the generated types and vocabulary, the dialect
+ * validator, the target-neutral blueprint validator and deterministic
+ * hashing. Build-time generation and the conformance harness live in
+ * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ */
+export type * from './generated/typescript/blueprint.js';
+export type * from './generated/typescript/catalog-schema.js';
+export type * from './generated/typescript/diagnostics.js';
+export type * from './generated/typescript/manifest.js';
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, type SpecComponentId, type SpecComponentProps, } from './generated/typescript/vocabulary.js';
+export { canonicalJson, sha256 } from './canonical.js';
+export { CAPABILITIES, type Capability, type SpecPropKind, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from './catalog.js';
+export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';
+export { type SpecDocuments, validateBlueprint, validateTree, } from './validate.js';
+export { SPEC_VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
+ * B1), runtime half: the generated types and vocabulary, the dialect
+ * validator, the target-neutral blueprint validator and deterministic
+ * hashing. Build-time generation and the conformance harness live in
+ * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ */
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, } from "./generated/typescript/vocabulary.js";
+export { canonicalJson, sha256 } from "./canonical.js";
+export { CAPABILITIES, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from "./catalog.js";
+export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, validateInstance, } from "./dialect.js";
+export { validateBlueprint, validateTree, } from "./validate.js";
+export { SPEC_VERSION } from "./version.js";

package/dist/validate.d.ts

@@ -0,0 +1,27 @@
+import type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation } from './generated/typescript/diagnostics.js';
+import type { SpecCatalog } from './catalog.js';
+import { type Schema } from './dialect.js';
+export type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation };
+export interface SpecDocuments {
+    blueprintSchema: Schema;
+    catalog: SpecCatalog;
+}
+/**
+ * Validate a blueprint envelope against the spec alone: the envelope schema,
+ * then every node against the catalog vocabulary (closed ids, closed prop
+ * names, prop kinds and enum values, required props, no platform-extension
+ * props from data, a `slot` that names a slot prop of the parent) and the
+ * declared profile. A `when` condition is checked for shape only; the
+ * runtime formula parser checks its operands. With `catalogHash`, an envelope
+ * bound to another catalog is refused. This is the shared, target-neutral
+ * contract; URL policy, limits, grammar and rendering stay in the runtime
+ * validators (`@texuli/catalog/validate`).
+ */
+export declare function validateBlueprint(input: unknown, documents: SpecDocuments, options?: {
+    catalogHash?: string;
+}): SpecValidation;
+/** Check one catalog tree against the vocabulary. See {@link validateBlueprint}. */
+export declare function validateTree(tree: unknown, catalog: SpecCatalog, options?: {
+    portable?: boolean;
+    path?: string;
+}): SpecDiagnostic[];

package/dist/validate.js

@@ -0,0 +1,143 @@
+import { isRecord, validateInstance } from "./dialect.js";
+const MAX_TREE_DEPTH = 64;
+/**
+ * Validate a blueprint envelope against the spec alone: the envelope schema,
+ * then every node against the catalog vocabulary (closed ids, closed prop
+ * names, prop kinds and enum values, required props, no platform-extension
+ * props from data, a `slot` that names a slot prop of the parent) and the
+ * declared profile. A `when` condition is checked for shape only; the
+ * runtime formula parser checks its operands. With `catalogHash`, an envelope
+ * bound to another catalog is refused. This is the shared, target-neutral
+ * contract; URL policy, limits, grammar and rendering stay in the runtime
+ * validators (`@texuli/catalog/validate`).
+ */
+export function validateBlueprint(input, documents, options = {}) {
+    const diagnostics = validateInstance(documents.blueprintSchema, input).map((issue) => ({ code: 'schema', path: issue.path, message: `${issue.code}: ${issue.message}` }));
+    if (!isRecord(input))
+        return { ok: false, diagnostics };
+    if (options.catalogHash !== undefined && input.catalog !== options.catalogHash) {
+        diagnostics.push({
+            code: 'catalog-mismatch',
+            path: '$.catalog',
+            message: 'The blueprint is bound to another catalog.',
+        });
+    }
+    const portable = input.profile === 'portable';
+    if (isRecord(input.tree)) {
+        diagnostics.push(...validateTree(input.tree, documents.catalog, { portable, path: '$.tree' }));
+    }
+    return { ok: diagnostics.length === 0, diagnostics };
+}
+/** Check one catalog tree against the vocabulary. See {@link validateBlueprint}. */
+export function validateTree(tree, catalog, options = {}) {
+    const byId = new Map(catalog.components.map((c) => [c.id, c]));
+    const out = [];
+    const visit = (node, path, depth, parent) => {
+        if (!isRecord(node) || typeof node.id !== 'string' || depth > MAX_TREE_DEPTH)
+            return;
+        checkSlot(node.slot, parent, node.id, path, out);
+        const component = byId.get(node.id);
+        if (!component) {
+            out.push({
+                code: 'unknown-id',
+                path: `${path}.id`,
+                id: node.id,
+                message: `"${node.id}" is not in the catalog.`,
+            });
+        }
+        else {
+            if (options.portable && component.capability !== 'portable-core') {
+                out.push({
+                    code: 'unsupported-profile',
+                    path,
+                    id: node.id,
+                    message: `"${node.id}" is ${component.capability}, not portable core.`,
+                });
+            }
+            checkProps(node.props, component, `${path}.props`, out);
+        }
+        if (Array.isArray(node.children)) {
+            node.children.forEach((child, index) => {
+                visit(child, `${path}.children[${index}]`, depth + 1, component);
+            });
+        }
+    };
+    visit(tree, options.path ?? '$', 0, null);
+    return out;
+}
+/**
+ * A node's `slot` (audit G04) must name a slot prop of its parent; omitted
+ * or `children` is the default slot. A root fills no slot. An unknown
+ * parent was already reported, so its children's slots are not judged.
+ */
+function checkSlot(slot, parent, id, path, out) {
+    if (slot === undefined || slot === 'children' || parent === undefined)
+        return;
+    const named = parent !== null &&
+        typeof slot === 'string' &&
+        parent.props.some((prop) => prop.kind === 'slot' && prop.name === slot);
+    if (named)
+        return;
+    out.push({
+        code: 'unknown-slot',
+        path: `${path}.slot`,
+        id,
+        message: parent === null
+            ? 'A root node fills no slot.'
+            : `"${String(slot)}" is not a slot of "${parent.id}".`,
+    });
+}
+function checkProps(props, component, path, out) {
+    const given = isRecord(props) ? props : {};
+    const id = component.id;
+    const declared = new Map(component.props.map((p) => [p.name, p]));
+    for (const [name, value] of Object.entries(given)) {
+        const here = `${path}.${name}`;
+        const prop = declared.get(name);
+        if (!prop) {
+            out.push({ code: 'unknown-prop', path: here, id, message: `"${id}" has no "${name}" prop.` });
+            continue;
+        }
+        if (prop.extension) {
+            out.push({
+                code: 'extension-prop',
+                path: here,
+                id,
+                message: `"${name}" is a ${prop.extension} extension (${prop.kind}) and cannot come from data.`,
+            });
+            continue;
+        }
+        const kindOk = prop.kind === 'string' || prop.kind === 'enum'
+            ? typeof value === 'string'
+            : prop.kind === 'number'
+                ? typeof value === 'number' && Number.isFinite(value)
+                : prop.kind === 'boolean'
+                    ? typeof value === 'boolean'
+                    : prop.kind === 'array'
+                        ? Array.isArray(value)
+                        : prop.kind === 'object'
+                            ? isRecord(value)
+                            : false;
+        if (!kindOk) {
+            out.push({ code: 'prop-type', path: here, id, message: `"${name}" must be ${prop.kind}.` });
+        }
+        else if (prop.kind === 'enum' && !(prop.enumValues ?? []).includes(value)) {
+            out.push({
+                code: 'enum-value',
+                path: here,
+                id,
+                message: `"${name}" must be one of ${(prop.enumValues ?? []).join(', ')}.`,
+            });
+        }
+    }
+    for (const prop of component.props) {
+        if (prop.required && !prop.extension && !Object.hasOwn(given, prop.name)) {
+            out.push({
+                code: 'missing-required',
+                path: `${path}.${prop.name}`,
+                id,
+                message: `"${id}" needs "${prop.name}".`,
+            });
+        }
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The semantic version of the spec documents in this package. */
+export declare const SPEC_VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The semantic version of the spec documents in this package. */
+export const SPEC_VERSION = '0.2.0';

package/dist/versioning.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The spec's version history (`versions.json`): every released spec version
+ * pinned to the digest of its normative files, so the digest and the semantic
+ * version cannot drift apart. A normative change (schema, catalog projection,
+ * capability claim or fixture) changes the digest; it needs a new version
+ * and a new pin, with the change class the policy assigns to it.
+ */
+/** What a release changes, by the policy in the package README. */
+export type SpecChangeClass = 'patch' | 'minor' | 'major';
+export interface SpecVersionPin {
+    specVersion: string;
+    /** The spec digest of that release, or `null` for a release pinned retroactively without one. */
+    specDigest: string | null;
+    change: SpecChangeClass | 'initial';
+    summary: string;
+}
+export interface SpecVersionHistory {
+    releases: readonly SpecVersionPin[];
+}
+export interface VersionIssue {
+    version: string;
+    message: string;
+}
+/**
+ * The version that must follow `previous` for a change of `change` class.
+ * Before 1.0.0 any change to accepted data (minor or major class) bumps the
+ * minor number and a patch-class change bumps the patch; from 1.0.0 each
+ * class bumps its own number.
+ */
+export declare function nextSpecVersion(previous: string, change: SpecChangeClass): string;
+/**
+ * Check the history and that the newest release is the spec as built now:
+ * the same version and the same digest. Returns every problem; empty means
+ * the version and the digest agree.
+ */
+export declare function checkVersionHistory(history: SpecVersionHistory, current: {
+    specVersion: string;
+    specDigest: string;
+}): VersionIssue[];

package/dist/versioning.js

@@ -0,0 +1,87 @@
+/**
+ * The spec's version history (`versions.json`): every released spec version
+ * pinned to the digest of its normative files, so the digest and the semantic
+ * version cannot drift apart. A normative change (schema, catalog projection,
+ * capability claim or fixture) changes the digest; it needs a new version
+ * and a new pin, with the change class the policy assigns to it.
+ */
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+function parts(version) {
+    const match = SEMVER.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+/**
+ * The version that must follow `previous` for a change of `change` class.
+ * Before 1.0.0 any change to accepted data (minor or major class) bumps the
+ * minor number and a patch-class change bumps the patch; from 1.0.0 each
+ * class bumps its own number.
+ */
+export function nextSpecVersion(previous, change) {
+    const p = parts(previous);
+    if (!p)
+        throw new Error(`${previous}: not a semantic version`);
+    const [major, minor, patch] = p;
+    if (change === 'patch')
+        return `${major}.${minor}.${patch + 1}`;
+    if (major === 0 || change === 'minor')
+        return `${major}.${minor + 1}.0`;
+    return `${major + 1}.0.0`;
+}
+/**
+ * Check the history and that the newest release is the spec as built now:
+ * the same version and the same digest. Returns every problem; empty means
+ * the version and the digest agree.
+ */
+export function checkVersionHistory(history, current) {
+    const issues = [];
+    const releases = history.releases;
+    if (releases.length === 0) {
+        return [{ version: current.specVersion, message: 'versions.json lists no release.' }];
+    }
+    releases.forEach((release, index) => {
+        const { specVersion: version } = release;
+        if (!parts(version))
+            issues.push({ version, message: 'not a semantic version' });
+        if (release.specDigest !== null && !DIGEST.test(release.specDigest)) {
+            issues.push({ version, message: 'the digest is not a SHA-256 hex string' });
+        }
+        if (index === 0) {
+            if (release.change !== 'initial') {
+                issues.push({ version, message: 'the first release must have change "initial"' });
+            }
+            return;
+        }
+        const previous = releases[index - 1];
+        if (release.change === 'initial') {
+            issues.push({ version, message: 'only the first release is "initial"' });
+            return;
+        }
+        if (release.specDigest === null) {
+            issues.push({ version, message: 'only the first release may lack a digest' });
+        }
+        if (parts(previous.specVersion)) {
+            const expected = nextSpecVersion(previous.specVersion, release.change);
+            if (version !== expected) {
+                issues.push({
+                    version,
+                    message: `a ${release.change} change after ${previous.specVersion} is ${expected}`,
+                });
+            }
+        }
+    });
+    const newest = releases[releases.length - 1];
+    if (newest.specVersion !== current.specVersion) {
+        issues.push({
+            version: current.specVersion,
+            message: `the newest release in versions.json is ${newest.specVersion}, the spec is ${current.specVersion}`,
+        });
+    }
+    else if (newest.specDigest !== current.specDigest) {
+        issues.push({
+            version: current.specVersion,
+            message: 'the normative files changed without a new version: classify the change, bump SPEC_VERSION, regenerate, and append a release pinning the new digest',
+        });
+    }
+    return issues;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@texuli/spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.1",
+  "description": "The schema-first blueprint contract: JSON schemas, the catalog vocabulary, deterministic TypeScript and Kotlin projections, and the conformance harness.",
+  "keywords": [
+    "svelte",
+    "svelte-5",
+    "components",
+    "design-system",
+    "texuli"
+  ],
+  "homepage": "https://github.com/DailybotHQ/texuli#readme",
+  "bugs": "https://github.com/DailybotHQ/texuli/issues",
+  "license": "MIT",
+  "author": "Dailybot, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DailybotHQ/texuli.git",
+    "directory": "packages/spec"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen/index.d.ts",
+      "default": "./dist/codegen/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ]
+}