@oddkin/workbench 0.0.0-stage → 1.0.0-beta.1

package/dist/data/theme-studio.js

@@ -0,0 +1,112 @@
+import { presets, registrationOf } from '../panels/model.js';
+import { DATA_VERSION, PAGE_FORMAT, } from './types.js';
+/** The default `theme-specimen` recipe's roles, in display order, with their captions. */
+export const SPECIMEN_ROLES = {
+    surface: 'Surface',
+    heading: 'Heading',
+    bodyText: 'Body text',
+    link: 'Link',
+    badge: 'Badge',
+    textInput: 'Text input',
+    checkbox: 'Checkbox',
+    switch: 'Switch',
+    primaryAction: 'Primary action',
+    secondaryAction: 'Secondary action',
+    navigation: 'Navigation',
+};
+const roleId = (value) => value.replace(/^role:/, '');
+export function themeStudioPage(id, components, config, input, out) {
+    const role = (name, page, exampleName, source) => {
+        const entry = registrationOf(page);
+        const all = presets(page);
+        const example = exampleName
+            ? all.find((p) => p.name === exampleName)
+            : (all.find((p) => p.name === 'default') ?? all.find((p) => p.state && !p.incorrect));
+        if (!entry || !example?.state)
+            return undefined;
+        return {
+            role: name,
+            label: SPECIMEN_ROLES[name] ?? name,
+            tag: page.tag,
+            registration: entry,
+            example: example.id,
+            properties: example.state.properties,
+            attributes: example.state.attributes,
+            slots: example.state.slots,
+            source,
+        };
+    };
+    // Roles claimed by examples; a role claimed by two components stays unmapped.
+    const claims = new Map();
+    for (const page of components)
+        for (const example of page.examples) {
+            const roles = example['previewRoles'];
+            const name = example['name'];
+            if (!Array.isArray(roles) || typeof name !== 'string')
+                continue;
+            for (const r of roles)
+                if (typeof r === 'string')
+                    claims.set(roleId(r), [...(claims.get(roleId(r)) ?? []), { page, example: name }]);
+        }
+    const missing = [];
+    const byTag = new Map(components.map((page) => [page.tag, page]));
+    const mapped = new Map();
+    for (const [name, target] of Object.entries(config.themeStudio.preview.roles ?? {})) {
+        const tag = typeof target === 'string' ? target : target.component;
+        const page = byTag.get(tag);
+        const resolved = page && role(name, page, typeof target === 'string' ? undefined : target.example, 'config');
+        if (resolved)
+            mapped.set(name, resolved);
+        else
+            out.warn('data.themeStudio.role', `themeStudio.preview.roles.${name}: <${tag}> is not a documented component with a registration entry and that example.`, `/themeStudio/preview/roles/${name}`);
+    }
+    for (const [name, claimants] of claims) {
+        if (mapped.has(name))
+            continue;
+        const tags = [...new Set(claimants.map((c) => c.page.tag))];
+        const only = claimants[0];
+        if (tags.length === 1 && claimants.length === 1 && only) {
+            const resolved = role(name, only.page, only.example, 'example');
+            if (resolved)
+                mapped.set(name, resolved);
+        }
+        else
+            missing.push({
+                item: `role:${name}`,
+                supply: `themeStudio.preview.roles.${name} (claimed by ${claimants.map((c) => `${c.page.tag}/${c.example}`).join(', ')})`,
+            });
+    }
+    const order = Object.keys(SPECIMEN_ROLES);
+    const rank = (name) => (order.includes(name) ? order.indexOf(name) : order.length);
+    const roles = [...mapped.values()].sort((a, b) => rank(a.role) - rank(b.role) || a.role.localeCompare(b.role));
+    for (const name of order)
+        if (!mapped.has(name) && !claims.has(name))
+            missing.push({
+                item: `role:${name}`,
+                supply: `an example with previewRoles: ['${name}'], or themeStudio.preview.roles.${name}`,
+            });
+    if (!input.config)
+        missing.unshift({
+            item: 'config',
+            supply: 'themeStudio.themeConfig (a theme configuration file)',
+        });
+    if (!input.worker)
+        missing.unshift({
+            item: 'generator',
+            supply: 'a documented package that depends on @oddkin/tokens (its ./generate export)',
+        });
+    return {
+        format: PAGE_FORMAT,
+        version: DATA_VERSION,
+        id,
+        kind: 'tool',
+        studio: {
+            ...(input.config ? { config: input.config } : {}),
+            ...(input.source ? { source: input.source } : {}),
+            ...(input.worker ? { worker: input.worker } : {}),
+            roles,
+            missing,
+        },
+    };
+}
+//# sourceMappingURL=theme-studio.js.map

package/dist/data/theme-studio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-studio.js","sourceRoot":"","sources":["../../src/data/theme-studio.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EACL,YAAY,EACZ,WAAW,GAKZ,MAAM,YAAY,CAAC;AAEpB,0FAA0F;AAC1F,MAAM,CAAC,MAAM,cAAc,GAAqC;IAC9D,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,WAAW;IACrB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,YAAY;IACvB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,aAAa,EAAE,gBAAgB;IAC/B,eAAe,EAAE,kBAAkB;IACnC,UAAU,EAAE,YAAY;CACzB,CAAC;AAYF,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAE9D,MAAM,UAAU,eAAe,CAC7B,EAAU,EACV,UAAwC,EACxC,MAA+B,EAC/B,KAAuB,EACvB,GAAmB;IAEnB,MAAM,IAAI,GAAG,CACX,IAAY,EACZ,IAAuB,EACvB,WAA+B,EAC/B,MAA8B,EACJ,EAAE;QAC5B,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,OAAO,GAAG,WAAW;YACzB,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC;YACzC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACxF,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,EAAE,KAAK;YAAE,OAAO,SAAS,CAAC;QAChD,OAAO;YACL,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,IAAI;YACnC,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,YAAY,EAAE,KAAK;YACnB,OAAO,EAAE,OAAO,CAAC,EAA6B;YAC9C,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,UAAU;YACpC,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,UAAU;YACpC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;YAC1B,MAAM;SACP,CAAC;IACJ,CAAC,CAAC;IAEF,8EAA8E;IAC9E,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0D,CAAC;IACjF,KAAK,MAAM,IAAI,IAAI,UAAU;QAC3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;YACtC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAChE,KAAK,MAAM,CAAC,IAAI,KAAK;gBACnB,IAAI,OAAO,CAAC,KAAK,QAAQ;oBACvB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACzF,CAAC;IAEH,MAAM,OAAO,GAAuC,EAAE,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QACpF,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;QACnE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,QAAQ,GACZ,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9F,IAAI,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;;YAEvC,GAAG,CAAC,IAAI,CACN,uBAAuB,EACvB,6BAA6B,IAAI,MAAM,GAAG,6EAA6E,EACvH,8BAA8B,IAAI,EAAE,CACrC,CAAC;IACN,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/B,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAChE,IAAI,QAAQ;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC3C,CAAC;;YACC,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,QAAQ,IAAI,EAAE;gBACpB,MAAM,EAAE,6BAA6B,IAAI,gBAAgB,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aAC1H,CAAC,CAAC;IACP,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CACtE,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK;QACtB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,QAAQ,IAAI,EAAE;gBACpB,MAAM,EAAE,mCAAmC,IAAI,oCAAoC,IAAI,EAAE;aAC1F,CAAC,CAAC;IACP,IAAI,CAAC,KAAK,CAAC,MAAM;QACf,OAAO,CAAC,OAAO,CAAC;YACd,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,sDAAsD;SAC/D,CAAC,CAAC;IACL,IAAI,CAAC,KAAK,CAAC,MAAM;QACf,OAAO,CAAC,OAAO,CAAC;YACd,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,6EAA6E;SACtF,CAAC,CAAC;IAEL,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,OAAO,EAAE,YAAY;QACrB,EAAE;QACF,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE;YACN,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,KAAK;YACL,OAAO;SACR;KACF,CAAC;AACJ,CAAC"}

package/dist/data/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Workbench data files (workbench.md §2.1): a small index the shell loads first, and one data
+ * file per page that its route loads lazily. Internal formats shared by the Node tooling and the
+ * browser shell of the same Workbench version; `version` changes when a shape changes.
+ */
+import type { WorkbenchDiagnostic } from '../internal/diagnostics.js';
+import type { JsonValue } from '../protocol/index.js';
+import type { CemPackage, OddkinMetadataLike, PageKind, PageRegistry } from '../pages/types.js';
+export declare const INDEX_FORMAT = "oddkin.workbench-index";
+export declare const PAGE_FORMAT = "oddkin.workbench-page";
+export declare const DATA_VERSION = 1;
+/** A JSON object as read from a published file. */
+export type JsonObject = {
+    readonly [key: string]: unknown;
+};
+/** One documented package and its published outputs. */
+export interface LibraryInput {
+    readonly name: string;
+    readonly version: string;
+    /** Its standard Custom Elements Manifest (`customElements`). */
+    readonly cem?: CemPackage;
+    /** Its `oddkin.metadata.json`, when the package publishes Oddkin enrichment. */
+    readonly metadata?: OddkinMetadataLike;
+    /** Authored example sets as data (`toExamplesJSON()` of each `defineExamples` module). */
+    readonly examples?: readonly ExampleSetLike[];
+    /**
+     * Tag → the import specifier of the module that registers it, from the standard CEM: the module
+     * whose exports hold the tag's `custom-element-definition`, as the package's `exports` reach it.
+     * Used when the Oddkin enrichment names no `registration`.
+     */
+    readonly registrations?: Readonly<Record<string, string>>;
+}
+/** One component's examples as plain data (`@oddkin/workbench/examples` `ExamplesJSON`). */
+export interface ExampleSetLike {
+    readonly component: string;
+    readonly examples: Readonly<Record<string, JsonObject>>;
+}
+/** A token as published by a token inspection (`@oddkin/tokens/inspect/*.json`). */
+export interface InspectedTokenLike {
+    readonly name: string;
+    readonly cssVariable?: string;
+    readonly category?: string;
+    readonly type?: string;
+    readonly origin?: string;
+    readonly definition?: unknown;
+    readonly value?: unknown;
+    readonly description?: string;
+}
+export interface TokenInspectionLike {
+    readonly theme?: string;
+    readonly tokens: readonly InspectedTokenLike[];
+}
+export interface WorkbenchBranding {
+    readonly name: string;
+    readonly logo?: string;
+    readonly links: readonly {
+        readonly label: string;
+        readonly href: string;
+    }[];
+}
+export interface WorkbenchIndex {
+    readonly format: typeof INDEX_FORMAT;
+    readonly version: typeof DATA_VERSION;
+    readonly branding: WorkbenchBranding;
+    /** The documented packages, in configuration order. */
+    readonly libraries: readonly {
+        readonly name: string;
+        readonly version: string;
+        readonly prefix?: string;
+    }[];
+    readonly registry: PageRegistry;
+    /** Page id → its data file, relative to the index. Visible pages only. */
+    readonly pages: Readonly<Record<string, string>>;
+    /** Component pages whose element has a registration: the catalog shows each live in its card. */
+    readonly previews?: readonly string[];
+    readonly diagnostics: readonly WorkbenchDiagnostic[];
+}
+interface PageDataBase {
+    readonly format: typeof PAGE_FORMAT;
+    readonly version: typeof DATA_VERSION;
+    readonly id: string;
+}
+/** A component page: its published facts, verbatim, for the detail panels to present. */
+export interface ComponentPageData extends PageDataBase {
+    readonly kind: 'component';
+    readonly tag: string;
+    /** The package whose manifest declares the element. */
+    readonly package: string;
+    /** The CEM module that declares it. */
+    readonly module: string;
+    /** The CEM declaration, verbatim. */
+    readonly declaration: JsonObject;
+    /** The Oddkin enrichment entry, verbatim, when published. */
+    readonly enrichment?: JsonObject;
+    /**
+     * The module that registers the element, as an import specifier, when the enrichment names none:
+     * from the standard CEM's `custom-element-definition` export (`LibraryInput.registrations`).
+     */
+    readonly registration?: string;
+    /**
+     * Authored examples for the element (metadata `examples`), verbatim, with their ids. When the
+     * example set was loaded, `definition` holds its values (label, props, attributes, slots,
+     * preset, guidance, incorrect, `hasFixture`).
+     */
+    readonly examples: readonly JsonObject[];
+    /**
+     * URL of the element's example module as preview frames load it, when its examples have
+     * fixtures and their source was found: frames run the fixture of the example they mount.
+     */
+    readonly exampleModule?: string;
+    /**
+     * The tokens the component reads (`tokenReads`), resolved from the token inspection in their
+     * order. A token missing from the inspection keeps only its name (`missing: true`).
+     */
+    readonly tokens?: readonly (InspectedTokenLike & {
+        readonly missing?: true;
+    })[];
+    /**
+     * Authored content for the page (`oddkin.docs.ts`): intended use and section guidance. Absent
+     * when nothing is authored.
+     */
+    readonly authored?: {
+        readonly useFor?: readonly string[];
+        readonly notFor?: readonly string[];
+        readonly guidance?: string;
+    };
+}
+/** A foundation page: its metadata and the referenced tokens from the token inspection. */
+export interface FoundationPageData extends PageDataBase {
+    readonly kind: 'foundation';
+    /** The foundation's metadata entry, verbatim. */
+    readonly foundation: JsonObject;
+    /**
+     * The tokens the foundation lists, in its order. A token missing from the inspection keeps
+     * only its name (`missing: true`); its value is never guessed.
+     */
+    readonly tokens: readonly (InspectedTokenLike & {
+        readonly missing?: true;
+    })[];
+}
+/** Overview, tool, products, and home pages: their content comes from the index for now. */
+export interface BasicPageData extends PageDataBase {
+    readonly kind: Exclude<PageKind, 'component' | 'foundation'>;
+}
+/** A specimen role played by a documented component in one of its examples. */
+export interface SpecimenRole {
+    readonly role: string;
+    /** Visible caption. */
+    readonly label: string;
+    readonly tag: string;
+    /** The component's published registration entry. */
+    readonly registration: string;
+    /** The example whose values the specimen uses. */
+    readonly example: `example:${string}/${string}`;
+    readonly properties: Readonly<Record<string, JsonValue>>;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly slots: Readonly<Record<string, string>>;
+    /** Mapped by `themeStudio.preview.roles` or claimed by the example (`previewRoles`). */
+    readonly source: 'config' | 'example';
+}
+/** Theme Studio (workbench.md ?6): the baseline configuration, its generator, and specimens. */
+export interface ThemeStudioPageData extends PageDataBase {
+    readonly kind: 'tool';
+    readonly studio: {
+        /** The baseline theme configuration's JSON model. */
+        readonly config?: JsonObject;
+        /** The configuration file, as `themeStudio.themeConfig` names it. */
+        readonly source?: string;
+        /** URL of the generation worker (the library's own `@oddkin/tokens/generate`). */
+        readonly worker?: string;
+        readonly roles: readonly SpecimenRole[];
+        /** Absent inputs, each with what supplies it; shown on the page, never guessed. */
+        readonly missing: readonly {
+            readonly item: string;
+            readonly supply: string;
+        }[];
+    };
+}
+export type PageData = ComponentPageData | FoundationPageData | ThemeStudioPageData | BasicPageData;
+export interface WorkbenchData {
+    readonly index: WorkbenchIndex;
+    /** Page id → data, for every entry of `index.pages`. */
+    readonly pages: Readonly<Record<string, PageData>>;
+}
+/** Re-exported for callers that build the registry input themselves. */
+export type { CemPackage, OddkinMetadataLike };
+//# sourceMappingURL=types.d.ts.map

package/dist/data/types.d.ts.map

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

package/dist/data/types.js

@@ -0,0 +1,4 @@
+export const INDEX_FORMAT = 'oddkin.workbench-index';
+export const PAGE_FORMAT = 'oddkin.workbench-page';
+export const DATA_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/data/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/data/types.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC"}

package/dist/examples/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `@oddkin/workbench/examples` — authored examples, defined once and reused by Workbench,
+ * documentation, browser tests, Theme Studio, and agents (ADR 0021). DOM-free: importing
+ * this entry never touches the DOM; fixtures run only inside preview frames and tests.
+ */
+import type { Scope } from '@oddkin/core';
+import { type WorkbenchDiagnostic } from '../internal/diagnostics.js';
+export type { WorkbenchDiagnostic } from '../internal/diagnostics.js';
+type DataKeys<E> = {
+    [K in keyof E]-?: E[K] extends (...args: never[]) => unknown ? never : K;
+}[keyof E];
+/** Public data properties of an element type, excluding those every `HTMLElement` has. */
+export type ElementProps<E> = Partial<Pick<E, Exclude<DataKeys<E>, keyof HTMLElement>>>;
+/** The element type for a tag: from `HTMLElementTagNameMap` when registered there. */
+export type ElementFor<T extends string> = T extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[T] : HTMLElement & {
+    [property: string]: unknown;
+};
+export interface ExampleFixtureContext<E extends Element = Element> {
+    /** Owns listeners, timers, and effects; disposed when the preview or test ends. */
+    readonly scope: Scope;
+    /** The example's element, already created with its props, attributes, and slots. */
+    readonly element: E;
+    /** Render more content into the preview root; returns its first element. */
+    mount(content: unknown): Element;
+}
+/**
+ * Marks an example as a common mistake. It is never offered as a preset or recommendation; it
+ * explains what goes wrong, names the diagnostic `validateUsage` reports for it, and points at
+ * the correct example in the same set.
+ */
+export interface IncorrectUsage {
+    readonly explanation: string;
+    /** Diagnostic code `validateUsage` reports, e.g. `usage.attribute.propertyOnly`. */
+    readonly diagnostic: string;
+    /** Name of the correct example in the same set. */
+    readonly correct: string;
+}
+export interface ExampleDefinition<E extends Element = HTMLElement> {
+    readonly label?: string;
+    /** Property values, checked against the element type (TypeScript) or metadata (checkExamples). */
+    readonly props?: ElementProps<E>;
+    readonly attributes?: Readonly<Record<string, string | null>>;
+    /** Plain-text slot content keyed by slot name; `default` is the default slot. */
+    readonly slots?: Readonly<Record<string, string>>;
+    readonly previewRoles?: readonly string[];
+    /** Offered as a preset on the component page. */
+    readonly preset?: boolean;
+    readonly recommended?: boolean;
+    readonly guidance?: string;
+    /** A common mistake, explained (see `IncorrectUsage`). */
+    readonly incorrect?: IncorrectUsage;
+    /** Owned setup code; runs only in preview frames and tests. */
+    readonly fixture?: (context: ExampleFixtureContext<E>) => void | Promise<void>;
+}
+export interface ExampleSet<E extends Element = HTMLElement> {
+    readonly component: string;
+    readonly examples: Readonly<Record<string, ExampleDefinition<E>>>;
+}
+/**
+ * Define the examples for one component. With TypeScript and a registered tag
+ * (`HTMLElementTagNameMap`), unknown property keys and wrong value types are compile errors.
+ */
+export declare function defineExamples<T extends string>(tag: T, examples: Readonly<Record<string, ExampleDefinition<ElementFor<T>>>>): ExampleSet<ElementFor<T>>;
+export declare const EXAMPLES_SCHEMA = "https://oddkin.dev/schemas/examples/v1.json";
+/** The serializable layer (`examples.v1`); fixtures appear only as `hasFixture`. */
+export interface ExamplesJSON {
+    readonly schema: typeof EXAMPLES_SCHEMA;
+    readonly component: string;
+    readonly examples: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+export declare function toExamplesJSON<E extends Element>(set: ExampleSet<E>): ExamplesJSON;
+/** Example id shared with metadata, docs content, and agents: `example:<tag>/<name>`. */
+export declare const exampleId: (tag: string, name: string) => string;
+/** The parts of a component contract that examples are checked against (e.g. from CEM). */
+export interface ExampleContract {
+    readonly properties?: readonly string[];
+    readonly slots?: readonly string[];
+}
+/**
+ * Check names and, when a contract is given, property keys and slot names. Plain JavaScript
+ * authors get the same checks TypeScript gives at compile time.
+ */
+export declare function checkExamples<E extends Element>(set: ExampleSet<E>, contract?: ExampleContract): WorkbenchDiagnostic[];
+/** What `validateUsage` checks examples against: the published contract of the element. */
+export interface UsageContract {
+    /** Public writable properties; `attribute` is absent for property-only ones (`.items`). */
+    readonly properties: readonly {
+        name: string;
+        type?: string | undefined;
+        attribute?: string | undefined;
+    }[];
+    readonly slots: readonly string[];
+}
+/**
+ * Diagnostics for how each example uses the element, from its published contract: rich data
+ * written as an attribute, `"false"` on a boolean attribute, values outside an enum, unknown
+ * attributes, and unknown slots. Correct examples produce none; an incorrect example produces
+ * the diagnostic it declares.
+ */
+export declare function validateUsage<E extends Element>(set: ExampleSet<E>, contract: UsageContract): WorkbenchDiagnostic[];
+//# sourceMappingURL=index.d.ts.map

package/dist/examples/index.d.ts.map

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

package/dist/examples/index.js

@@ -0,0 +1,106 @@
+import { DiagnosticList } from '../internal/diagnostics.js';
+/**
+ * Define the examples for one component. With TypeScript and a registered tag
+ * (`HTMLElementTagNameMap`), unknown property keys and wrong value types are compile errors.
+ */
+export function defineExamples(tag, examples) {
+    return Object.freeze({ component: tag, examples: Object.freeze({ ...examples }) });
+}
+export const EXAMPLES_SCHEMA = 'https://oddkin.dev/schemas/examples/v1.json';
+export function toExamplesJSON(set) {
+    const examples = {};
+    for (const [name, example] of Object.entries(set.examples)) {
+        const { fixture, ...rest } = example;
+        examples[name] = {
+            ...JSON.parse(JSON.stringify(rest)),
+            ...(fixture ? { hasFixture: true } : {}),
+        };
+    }
+    return { schema: EXAMPLES_SCHEMA, component: set.component, examples };
+}
+/** Example id shared with metadata, docs content, and agents: `example:<tag>/<name>`. */
+export const exampleId = (tag, name) => `example:${tag}/${name}`;
+const TAG = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+const NAME = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+/**
+ * Check names and, when a contract is given, property keys and slot names. Plain JavaScript
+ * authors get the same checks TypeScript gives at compile time.
+ */
+export function checkExamples(set, contract) {
+    const out = new DiagnosticList();
+    if (!TAG.test(set.component)) {
+        out.error('examples.component.invalid', `"${set.component}" is not a valid custom element name.`, '/component');
+    }
+    const properties = contract?.properties ? new Set(contract.properties) : undefined;
+    const slots = contract?.slots ? new Set(contract.slots.map((s) => s || 'default')) : undefined;
+    for (const [name, example] of Object.entries(set.examples)) {
+        const path = `/examples/${name}`;
+        if (!NAME.test(name)) {
+            out.error('examples.name.invalid', `Example name "${name}" must start with a letter and use letters, digits, and hyphens.`, path);
+        }
+        // An incorrect example breaks the contract on purpose; validateUsage reports how.
+        const checked = example.incorrect ? {} : example;
+        for (const key of Object.keys(checked.props ?? {})) {
+            if (properties && !properties.has(key)) {
+                out.error('examples.prop.unknown', `<${set.component}> has no public property "${key}" (example "${name}").`, `${path}/props/${key}`);
+            }
+        }
+        for (const slot of Object.keys(checked.slots ?? {})) {
+            if (slots && !slots.has(slot)) {
+                out.error('examples.slot.unknown', `<${set.component}> declares no slot "${slot}" (example "${name}").`, `${path}/slots/${slot}`);
+            }
+        }
+        const incorrect = example.incorrect;
+        if (incorrect) {
+            const correct = set.examples[incorrect.correct];
+            if (!correct || correct.incorrect)
+                out.error('examples.incorrect.correct', `Incorrect example "${name}" must name a correct example of <${set.component}>, not "${incorrect.correct}".`, `${path}/incorrect/correct`);
+            if (!incorrect.explanation.trim() || !/^[a-z]+(\.[a-zA-Z-]+)+$/.test(incorrect.diagnostic))
+                out.error('examples.incorrect.explanation', `Incorrect example "${name}" needs an explanation and a diagnostic code.`, `${path}/incorrect`);
+            if (example.preset || example.recommended || example.previewRoles?.length)
+                out.error('examples.incorrect.recommended', `Incorrect example "${name}" cannot be a preset, a recommendation, or a preview role.`, path);
+        }
+    }
+    return out.items;
+}
+// Attributes every element accepts.
+const GLOBAL_ATTRIBUTE = /^(?:id|class|style|slot|part|lang|dir|title|hidden|inert|tabindex|role|autofocus|exportparts|data-.+|aria-.+)$/;
+const unionOf = (type) => type && /^"[^"]*"( \| "[^"]*")*$/.test(type)
+    ? [...type.matchAll(/"([^"]*)"/g)].map((m) => m[1])
+    : undefined;
+/**
+ * Diagnostics for how each example uses the element, from its published contract: rich data
+ * written as an attribute, `"false"` on a boolean attribute, values outside an enum, unknown
+ * attributes, and unknown slots. Correct examples produce none; an incorrect example produces
+ * the diagnostic it declares.
+ */
+export function validateUsage(set, contract) {
+    const out = new DiagnosticList();
+    const byAttribute = new Map(contract.properties.filter((p) => p.attribute).map((p) => [p.attribute, p]));
+    const slots = new Set(contract.slots.map((s) => s || 'default'));
+    const tag = set.component;
+    for (const [name, example] of Object.entries(set.examples)) {
+        const path = `/examples/${name}`;
+        for (const [attribute, value] of Object.entries(example.attributes ?? {})) {
+            const at = `${path}/attributes/${attribute}`;
+            const property = byAttribute.get(attribute);
+            const named = contract.properties.find((p) => p.name === attribute);
+            if (!property && named && !named.attribute)
+                out.error('usage.attribute.propertyOnly', `<${tag}> reads "${attribute}" only as a property; set .${attribute} with a value, not an attribute string.`, at);
+            else if (!property && !GLOBAL_ATTRIBUTE.test(attribute))
+                out.error('usage.attribute.unknown', `<${tag}> has no attribute "${attribute}"${named ? `; use "${named.attribute}"` : ''}.`, at);
+            else if (property?.type === 'boolean' && value === 'false')
+                out.error('usage.boolean.false', `[${attribute}="false"] still turns ${property.name} on: the attribute's presence means true. Remove the attribute instead.`, at);
+            else {
+                const allowed = unionOf(property?.type);
+                if (value !== null && allowed && !allowed.includes(value))
+                    out.error('usage.attribute.value', `<${tag}> ${attribute}="${value}" is not one of ${allowed.join(', ')}; the default is used.`, at);
+            }
+        }
+        for (const slot of Object.keys(example.slots ?? {}))
+            if (!slots.has(slot))
+                out.error('usage.slot.unknown', `<${tag}> declares no slot "${slot}"; the content is not shown.`, `${path}/slots/${slot}`);
+    }
+    return out.items;
+}
+//# sourceMappingURL=index.js.map

package/dist/examples/index.js.map

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

package/dist/frame/index.d.ts

@@ -0,0 +1,9 @@
+import { type JsonValue } from '../protocol/index.js';
+/**
+ * A plain-JSON summary of an event detail: cycles, DOM nodes, functions, `Map`/`Set`, errors,
+ * and class instances are described rather than transferred, and the result is size-capped.
+ */
+export declare function summarizeDetail(value: unknown): JsonValue;
+/** Install the runtime on a frame's own Window. Exported for controlled browser tests. */
+export declare function installFrameRuntime(win?: Window): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/frame/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/frame/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAYL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AA8N9B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAuDzD;AAiHD,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAe,GAAG,IAAI,CAwG9D"}