@roblawn/devtool-runtime 0.1.0-alpha.0

package/dist/ak/index.js

@@ -0,0 +1,16 @@
+export * from './ak.cssState.types.js';
+export * from './ak.cssState.transform.js';
+export * from './ak.responsive.types.js';
+export * from './ak.tokens.registry.js';
+export * from './ak.tokens.js';
+export * from './authoring-surface.shared.js';
+export * from './configured-core.shared.js';
+export * from './configured-surfaces.shared.js';
+export * from './project-entry.js';
+export * from './project-surface-adapters.shared.js';
+export * from './public-entry.shared.js';
+export * from './resolved-layout-marker.shared.js';
+export * from './style-schema.js';
+export * from './runtime-surface.shared.js';
+export * from './style-execution.js';
+export * from './useAk.shared.js';

package/dist/ak/project-entry.d.ts

@@ -0,0 +1,57 @@
+import type { Ref } from 'vue';
+import { type SnapshotTokenSource } from './ak.tokens.js';
+import { type RuntimeSurfaceFactory } from './configured-surfaces.shared.js';
+import { type AuthorKitMode, type PublicAkEntry } from './public-entry.shared.js';
+type ResponsiveTokenOverrides = Partial<Record<string, Record<string, Record<string, string>>>>;
+export interface ProjectAkOpConfigEntry {
+    readonly tokenFamily?: string;
+    readonly responsive?: boolean;
+    readonly addNoneasOmit?: boolean;
+    readonly authoringValue?: {
+        readonly kind: 'number';
+        readonly min?: number;
+        readonly max?: number;
+        readonly step?: number;
+    };
+    readonly useAlias?: (value: string) => string;
+}
+export interface ProjectAkDesignSystemBridge {
+    readonly ops: readonly string[];
+    readonly opConfig: Readonly<Record<string, ProjectAkOpConfigEntry | undefined>>;
+    readonly tokenFamilies: readonly string[];
+    readonly nonCompositeOps: readonly string[];
+    readonly responsiveOps: readonly string[];
+    readonly breakpointOrder: readonly string[];
+    readonly responsiveTokenOverrides: ResponsiveTokenOverrides;
+    readonly snapshot: SnapshotTokenSource;
+    resolve(op: string, value: string | number): string;
+    resolveForCompute(op: string, value: string | number): string;
+}
+export interface ProjectAkRuntimeTokensBridge {
+    readonly registryFamilies: Record<string, unknown>;
+    readonly registryTokens: Record<string, Record<string, unknown>>;
+    readonly coreFamilies: Record<string, readonly string[]>;
+    readonly opToFamily: Readonly<Record<string, string>>;
+    readonly tokenFamilies: readonly string[];
+}
+export interface ProjectAkAdapterBridge {
+    readonly getBoundValue: (layoutRef: Ref<unknown>) => (field: string) => unknown;
+    readonly createBoundStyleApi: RuntimeSurfaceFactory<unknown>;
+    readonly createBoundWrapperApi: RuntimeSurfaceFactory<unknown>;
+    readonly createRuntimeStyleApi: RuntimeSurfaceFactory<unknown>;
+    readonly createRuntimeWrapperApi: RuntimeSurfaceFactory<unknown>;
+}
+export interface ProjectAkBridge {
+    readonly mode: AuthorKitMode;
+    readonly designSystem: ProjectAkDesignSystemBridge;
+    readonly runtimeTokens: ProjectAkRuntimeTokensBridge;
+    readonly adapters: ProjectAkAdapterBridge;
+}
+export declare function createProjectAkImplementation<TReturn>(bridge: ProjectAkBridge, layoutInput?: unknown): TReturn;
+export declare function defineProjectAk<TReturn>(bridge: ProjectAkBridge): PublicAkEntry<TReturn>;
+export declare function resolveProjectAkMode(env?: {
+    readonly MODE?: string;
+    readonly DEV?: boolean;
+    readonly VITE_DEVTOOL_MODE?: string;
+}): AuthorKitMode;
+export {};

package/dist/ak/project-entry.js

@@ -0,0 +1,260 @@
+import { buildResponsiveClassString } from '../design-system/index.js';
+import { createAkTokensFromRegistry } from './ak.tokens.registry.js';
+import { createAkTokensFromSnapshot } from './ak.tokens.js';
+import { createConfiguredAkCore } from './configured-core.shared.js';
+import { createConfiguredResponsiveAuthorKitSurface, createConfiguredRuntimeAuthorKitSurface, } from './configured-surfaces.shared.js';
+import { isMarkedResolvedLayout } from './resolved-layout-marker.shared.js';
+import { createAkPublicEntry } from './public-entry.shared.js';
+import { resolveLayoutRef } from './useAk.shared.js';
+function sanitizeClassToken(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+}
+function makeBuilderFailureClass(args) {
+    const base = 'outline outline-2 outline-dashed outline-red-500 bg-red-50 text-red-900';
+    const sig = ['ak-builder-fail', `ak-op-${sanitizeClassToken(args.op)}`, `ak-field-${sanitizeClassToken(args.field)}`, `ak-reason-${sanitizeClassToken(args.reason)}`]
+        .filter(Boolean)
+        .join(' ');
+    return `${base} ${sig}`.trim();
+}
+const didWarnMissing = new Set();
+function warnMissingOnce(args) {
+    const isDev = Boolean(import.meta.env?.DEV);
+    if (!isDev)
+        return;
+    const key = `${args.op}:${args.field}`;
+    if (didWarnMissing.has(key))
+        return;
+    didWarnMissing.add(key);
+    console.warn(`[ak.builder] missing layout value`, { op: args.op, field: args.field });
+}
+function createResponsiveWiring(source, mode) {
+    if (mode === 'lookup') {
+        return {
+            mode: 'lookup',
+            enabledOps: source.responsiveOps,
+        };
+    }
+    return {
+        mode,
+        enabledOps: source.responsiveOps,
+        breakpointOrder: source.breakpointOrder,
+        getOverrides(op, baseToken) {
+            const family = source.opConfig[op]?.tokenFamily;
+            if (!family)
+                return {};
+            const familyOverrides = source.responsiveTokenOverrides[family];
+            if (!familyOverrides)
+                return {};
+            return familyOverrides[baseToken] ?? {};
+        },
+        buildClassString(args) {
+            return buildResponsiveClassString({
+                op: args.op,
+                baseToken: args.baseToken,
+                breakpointOrder: args.breakpointOrder,
+                overrides: args.overrides,
+                resolveTokenToClasses: args.resolveTokenToClasses,
+            });
+        },
+    };
+}
+function createBuilderSurface(layoutRef, bridge) {
+    const getValue = bridge.adapters.getBoundValue(layoutRef);
+    const responsiveWiring = createResponsiveWiring(bridge.designSystem, 'compute');
+    const computeCore = createConfiguredAkCore({
+        layoutRef,
+        ops: bridge.designSystem.ops,
+        resolve: (op, value) => bridge.designSystem.resolveForCompute(op, value),
+    });
+    const canonicalCore = createConfiguredAkCore({
+        layoutRef,
+        ops: bridge.designSystem.ops,
+        resolve: (op, value) => bridge.designSystem.resolve(op, value),
+    });
+    return createConfiguredResponsiveAuthorKitSurface({
+        core: computeCore,
+        computeCanonical: canonicalCore,
+        layoutRef,
+        getValue,
+        tokenFamilies: bridge.designSystem.tokenFamilies,
+        tokens: createAkTokensFromSnapshot(bridge.designSystem.snapshot),
+        responsiveWiring,
+        resolveCssValue: ({ op, field, def, raw, resolver }) => {
+            if (isMarkedResolvedLayout(layoutRef.value) && typeof raw === 'string') {
+                return raw.trim();
+            }
+            if (raw === null || raw === undefined) {
+                warnMissingOnce({ op: String(op), field });
+            }
+            const rawValue = typeof raw === 'string' ? raw.trim() : typeof raw === 'number' ? raw : undefined;
+            const tokenKey = rawValue === '' || rawValue === undefined ? def : rawValue;
+            if (tokenKey === undefined || tokenKey === '') {
+                return makeBuilderFailureClass({
+                    op: String(op),
+                    field,
+                    reason: 'missing-value-and-default',
+                });
+            }
+            return resolver(field, tokenKey) ?? '';
+        },
+        resolveResponsiveCssValue: ({ op, field, def, raw, computeResolver, wiring }) => {
+            if (isMarkedResolvedLayout(layoutRef.value) && typeof raw === 'string') {
+                return raw.trim();
+            }
+            if (wiring.mode === 'lookup') {
+                return typeof raw === 'string' ? raw.trim() : '';
+            }
+            if (raw === null || raw === undefined) {
+                warnMissingOnce({ op: String(op), field });
+            }
+            const rawString = typeof raw === 'string' ? raw.trim() : '';
+            const baseToken = rawString.length > 0 ? rawString : def;
+            if (!baseToken) {
+                return makeBuilderFailureClass({
+                    op: String(op),
+                    field,
+                    reason: 'missing-value-and-default',
+                });
+            }
+            const overrides = wiring.getOverrides(op, baseToken);
+            return wiring.buildClassString({
+                op,
+                baseToken,
+                overrides,
+                breakpointOrder: wiring.breakpointOrder,
+                resolveTokenToClasses: (_op, token) => computeResolver(field, token),
+            });
+        },
+        cssStateEnabledOps: bridge.designSystem.nonCompositeOps,
+        mode: 'reactive',
+        createStyleApi: bridge.adapters.createBoundStyleApi,
+        createWrapperApi: bridge.adapters.createBoundWrapperApi,
+        createDeclareOptions: {
+            enumPassthroughUnknownString: () => isMarkedResolvedLayout(layoutRef.value),
+            parseBooleanStrings: false,
+        },
+        acceptPlainResolvedObject: false,
+    });
+}
+function createDevSurface(layoutRef, bridge) {
+    const getValue = bridge.adapters.getBoundValue(layoutRef);
+    const responsiveWiring = createResponsiveWiring(bridge.designSystem, 'hybrid');
+    const computeCore = createConfiguredAkCore({
+        layoutRef,
+        ops: bridge.designSystem.ops,
+        resolve: (op, value) => bridge.designSystem.resolveForCompute(op, value),
+    });
+    const canonicalCore = createConfiguredAkCore({
+        layoutRef,
+        ops: bridge.designSystem.ops,
+        resolve: (op, value) => bridge.designSystem.resolve(op, value),
+    });
+    return createConfiguredResponsiveAuthorKitSurface({
+        core: computeCore,
+        computeCanonical: canonicalCore,
+        layoutRef,
+        getValue,
+        tokenFamilies: bridge.designSystem.tokenFamilies,
+        tokens: createAkTokensFromSnapshot(bridge.designSystem.snapshot),
+        responsiveWiring,
+        resolveCssValue: ({ field, def, raw, resolver }) => {
+            if (isMarkedResolvedLayout(layoutRef.value) && typeof raw === 'string') {
+                return raw.trim();
+            }
+            if (typeof raw === 'string' || typeof raw === 'number') {
+                return String(raw);
+            }
+            if (raw !== null && raw !== undefined) {
+                return '';
+            }
+            if (def === undefined || def === '') {
+                return '';
+            }
+            return resolver(field, def) ?? '';
+        },
+        resolveResponsiveCssValue: ({ op, field, def, raw, computeResolver, wiring }) => {
+            if (isMarkedResolvedLayout(layoutRef.value) && typeof raw === 'string') {
+                return raw.trim();
+            }
+            if (typeof raw === 'string') {
+                return raw;
+            }
+            if (raw !== null && raw !== undefined) {
+                return '';
+            }
+            if (!def) {
+                return '';
+            }
+            if (wiring.mode === 'lookup') {
+                return '';
+            }
+            const overrides = wiring.getOverrides(op, def);
+            return wiring.buildClassString({
+                op,
+                baseToken: def,
+                overrides,
+                breakpointOrder: wiring.breakpointOrder,
+                resolveTokenToClasses: (_op, token) => computeResolver(field, token),
+            });
+        },
+        cssStateEnabledOps: bridge.designSystem.nonCompositeOps,
+        mode: 'reactive',
+        createStyleApi: bridge.adapters.createBoundStyleApi,
+        createWrapperApi: bridge.adapters.createBoundWrapperApi,
+        createDeclareOptions: {
+            enumPassthroughUnknownString: true,
+            parseBooleanStrings: true,
+        },
+        acceptPlainResolvedObject: true,
+    });
+}
+function createRuntimeSurface(layoutRef, bridge) {
+    return createConfiguredRuntimeAuthorKitSurface({
+        layoutRef,
+        tokenFamilies: bridge.runtimeTokens.tokenFamilies,
+        tokens: createAkTokensFromRegistry({
+            registryFamilies: bridge.runtimeTokens.registryFamilies,
+            registryTokens: bridge.runtimeTokens.registryTokens,
+            coreFamilies: bridge.runtimeTokens.coreFamilies,
+            opToFamily: bridge.runtimeTokens.opToFamily,
+        }),
+        cssStateEnabledOps: bridge.designSystem.nonCompositeOps,
+        mode: 'static',
+        createStyleApi: bridge.adapters.createRuntimeStyleApi,
+        createWrapperApi: bridge.adapters.createRuntimeWrapperApi,
+    });
+}
+export function createProjectAkImplementation(bridge, layoutInput) {
+    const layoutRef = resolveLayoutRef(layoutInput);
+    switch (bridge.mode) {
+        case 'builder':
+            return createBuilderSurface(layoutRef, bridge);
+        case 'dev':
+            return createDevSurface(layoutRef, bridge);
+        case 'prod':
+            return createRuntimeSurface(layoutRef, bridge);
+    }
+}
+export function defineProjectAk(bridge) {
+    return createAkPublicEntry({
+        mode: bridge.mode,
+        useAkImpl: (layoutInput) => createProjectAkImplementation(bridge, layoutInput),
+    });
+}
+export function resolveProjectAkMode(env) {
+    const explicitMode = env?.VITE_DEVTOOL_MODE;
+    if (explicitMode === 'builder' || explicitMode === 'dev' || explicitMode === 'prod') {
+        return explicitMode;
+    }
+    if (env?.MODE === 'builder') {
+        return 'builder';
+    }
+    if (env?.MODE === 'development' || env?.DEV === true) {
+        return 'dev';
+    }
+    return 'prod';
+}

package/dist/ak/project-surface-adapters.shared.d.ts

@@ -0,0 +1,33 @@
+import type { Ref } from 'vue';
+import type { RuntimeAkMode, RuntimeAkValue } from './runtime-surface.shared.js';
+export interface ProjectWrapperSurfaceAdapter<TName extends string = string, TResolved extends Record<string, unknown> = Record<string, unknown>> {
+    readonly names: readonly TName[];
+    resolve(args: {
+        readonly wrapperName: TName;
+        readonly raw: unknown;
+        readonly acceptPlainResolvedObject: boolean;
+    }): TResolved | null;
+}
+export interface ProjectStyleSurfaceAdapter<TName extends string = string> {
+    readonly names: readonly TName[];
+    resolve(args: {
+        readonly styleName: TName;
+        readonly raw: unknown;
+        readonly acceptPlainResolvedObject: boolean;
+    }): Record<string, unknown> | null;
+}
+export type ProjectWrapperSurfaceApi<TName extends string, TResolved extends Record<string, unknown>> = Record<TName, (key?: string) => Ref<TResolved>>;
+export type ProjectStyleSurfaceSeed = Record<string, RuntimeAkValue<string>>;
+export type ProjectStyleSurfaceApi<TName extends string> = Record<TName, (key?: string) => ProjectStyleSurfaceSeed>;
+export declare function createProjectWrapperApi<TName extends string, TResolved extends Record<string, unknown>>(args: {
+    readonly mode: RuntimeAkMode;
+    readonly getRoot: () => Record<string, unknown>;
+    readonly acceptPlainResolvedObject: () => boolean;
+    readonly adapter: ProjectWrapperSurfaceAdapter<TName, TResolved>;
+}): ProjectWrapperSurfaceApi<TName, TResolved>;
+export declare function createProjectStyleApi<TName extends string>(args: {
+    readonly mode: RuntimeAkMode;
+    readonly getRoot: () => Record<string, unknown>;
+    readonly acceptPlainResolvedObject: () => boolean;
+    readonly adapter: ProjectStyleSurfaceAdapter<TName>;
+}): ProjectStyleSurfaceApi<TName>;

package/dist/ak/project-surface-adapters.shared.js

@@ -0,0 +1,83 @@
+import { makeRuntimeAkRef, makeRuntimeAkValue } from './runtime-surface.shared.js';
+function normalizeStyleClassValue(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => String(entry ?? '').trim())
+            .filter((entry) => entry.length > 0)
+            .join(' ');
+    }
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    return '';
+}
+export function createProjectWrapperApi(args) {
+    const factoryCache = new Map();
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            let factory = factoryCache.get(prop);
+            if (!factory) {
+                const wrapperName = prop;
+                factory = (key) => {
+                    const sliceKey = key ?? wrapperName;
+                    return makeRuntimeAkRef(args.mode, () => {
+                        const root = args.getRoot();
+                        const raw = root[sliceKey];
+                        return args.adapter.resolve({
+                            wrapperName,
+                            raw,
+                            acceptPlainResolvedObject: args.acceptPlainResolvedObject(),
+                        }) ?? {};
+                    });
+                };
+                factoryCache.set(prop, factory);
+            }
+            return factory;
+        },
+    });
+}
+export function createProjectStyleApi(args) {
+    const factoryCache = new Map();
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            let factory = factoryCache.get(prop);
+            if (!factory) {
+                const styleName = prop;
+                factory = (key) => {
+                    const sliceKey = key ?? styleName;
+                    const slotCache = new Map();
+                    return new Proxy({}, {
+                        get(_target, prop) {
+                            if (typeof prop !== 'string') {
+                                return undefined;
+                            }
+                            let slot = slotCache.get(prop);
+                            if (!slot) {
+                                slot = makeRuntimeAkValue(args.mode, () => {
+                                    const root = args.getRoot();
+                                    const raw = root[sliceKey];
+                                    const resolved = args.adapter.resolve({
+                                        styleName,
+                                        raw,
+                                        acceptPlainResolvedObject: args.acceptPlainResolvedObject(),
+                                    });
+                                    return normalizeStyleClassValue(resolved?.[prop]);
+                                });
+                                slotCache.set(prop, slot);
+                            }
+                            return slot;
+                        },
+                    });
+                };
+                factoryCache.set(prop, factory);
+            }
+            return factory;
+        },
+    });
+}

package/dist/ak/public-entry.shared.d.ts

@@ -0,0 +1,16 @@
+import type { Ref } from 'vue';
+export type AuthorKitMode = 'builder' | 'dev' | 'prod';
+export type PublicAkUseAk<TReturn> = {
+    (): TReturn;
+    (_layout: never): never;
+};
+export type PublicAkUseAkForLayout<TReturn> = (layoutRef: Ref<unknown>) => TReturn;
+export type PublicAkEntry<TReturn> = {
+    readonly AK_MODE: AuthorKitMode;
+    readonly useAk: PublicAkUseAk<TReturn>;
+    readonly useAkForLayout: PublicAkUseAkForLayout<TReturn>;
+};
+export declare function createAkPublicEntry<TReturn>(args: {
+    readonly mode: AuthorKitMode;
+    readonly useAkImpl: (layoutInput?: unknown) => TReturn;
+}): PublicAkEntry<TReturn>;

package/dist/ak/public-entry.shared.js

@@ -0,0 +1,18 @@
+export function createAkPublicEntry(args) {
+    const useAk = ((arg) => {
+        if (arg !== undefined) {
+            throw new Error(`useAk() does not accept arguments.\n` +
+                `You likely passed a layout prop snapshot.\n` +
+                `Fix: call useAk() with no args (preferred), or use useAkForLayout(toRef(props, 'layout')).`);
+        }
+        return args.useAkImpl(undefined);
+    });
+    const useAkForLayout = (layoutRef) => {
+        return args.useAkImpl(layoutRef);
+    };
+    return {
+        AK_MODE: args.mode,
+        useAk,
+        useAkForLayout,
+    };
+}

package/dist/ak/resolved-layout-marker.shared.d.ts

@@ -0,0 +1,3 @@
+export declare function isMarkedResolvedLayout(value: unknown): value is Record<string, unknown>;
+export declare function markResolvedLayout<T extends Record<string, unknown>>(value: T): T;
+export declare function cloneMarkedResolvedLayout<T extends Record<string, unknown>>(value: T): T;

package/dist/ak/resolved-layout-marker.shared.js

@@ -0,0 +1,19 @@
+const RESOLVED_LAYOUT_MARKER = Symbol.for('devtool-runtime:resolved-layout');
+export function isMarkedResolvedLayout(value) {
+    return typeof value === 'object' && value !== null && value[RESOLVED_LAYOUT_MARKER] === true;
+}
+export function markResolvedLayout(value) {
+    if (isMarkedResolvedLayout(value)) {
+        return value;
+    }
+    Object.defineProperty(value, RESOLVED_LAYOUT_MARKER, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return value;
+}
+export function cloneMarkedResolvedLayout(value) {
+    return markResolvedLayout({ ...value });
+}

package/dist/ak/runtime-surface.shared.d.ts

@@ -0,0 +1,31 @@
+import { type Ref } from 'vue';
+import type { AkCssStateInput } from './ak.cssState.types.js';
+export type RuntimeAkMode = 'static' | 'reactive';
+export type RuntimeAkValue<T> = T | Ref<T>;
+export type RuntimeAkClass = RuntimeAkValue<string>;
+export type RuntimeLayoutGetter = (field: string) => unknown;
+export type RuntimeCssOpFn = <Field extends string>(field: Field, def?: string, meta?: unknown) => RuntimeAkClass;
+export type RuntimeCssApi = Record<string, RuntimeCssOpFn>;
+export interface RuntimeDeclareFor {
+    for<F extends string>(kind: F, field: string, defaultKey: string, resolver: (value: string) => string, meta?: unknown): RuntimeAkValue<string>;
+}
+export type RuntimeDeclareFamilies = Record<string, (field: string, defaultKey: string, resolver: (value: string) => string, meta?: unknown) => RuntimeAkValue<string>>;
+export interface RuntimeDeclareEnumBoolean {
+    enum<const Values extends readonly string[]>(field: string, values: Values, defaultValue: Values[number], resolver: (value: Values[number]) => string, meta?: unknown): RuntimeAkValue<string>;
+    boolean(field: string, defaultValue: boolean, resolver: (value: boolean) => string, meta?: unknown): RuntimeAkValue<string>;
+}
+export type RuntimeDeclareApi = RuntimeDeclareFor & RuntimeDeclareFamilies & RuntimeDeclareEnumBoolean;
+export interface RuntimeValueApi {
+    boolean(field: string, defaultValue: boolean, meta?: unknown): Ref<boolean>;
+    string(field: string, defaultValue: string, meta?: unknown): Ref<string>;
+    number(field: string, defaultValue: number, meta?: unknown): Ref<number>;
+    enum<const Values extends readonly string[]>(field: string, values: Values, defaultValue: Values[number], meta?: unknown): Ref<Values[number]>;
+}
+export declare function makeRuntimeLayoutGetter(layoutRef: Ref<unknown>): RuntimeLayoutGetter;
+export declare function makeRuntimeAkValue<T>(mode: RuntimeAkMode, getter: () => T): RuntimeAkValue<T>;
+export declare function makeRuntimeAkRef<T>(mode: RuntimeAkMode, getter: () => T): Ref<T>;
+export declare function cx(...parts: Array<RuntimeAkClass | false | null | undefined>): string;
+export declare function createCssApiRuntime(getValue: RuntimeLayoutGetter, mode: RuntimeAkMode): RuntimeCssApi;
+export declare function createCssStateApiRuntime(css: RuntimeCssApi, mode: RuntimeAkMode, enabledOps?: readonly string[]): (state: AkCssStateInput) => RuntimeCssApi;
+export declare function makeDeclare(getValue: RuntimeLayoutGetter, tokenFamilies: readonly string[], mode: RuntimeAkMode): RuntimeDeclareApi;
+export declare function makeValue(getValue: RuntimeLayoutGetter, mode: RuntimeAkMode): RuntimeValueApi;