@skewedaspect/sleekspace-ui 0.8.0 → 0.9.0

package/src/static/__tests__/parityHarness.test.ts

@@ -0,0 +1,98 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Parity Harness Sanity Tests
+//
+// Verify the harness detects matches and mismatches correctly using minimal synthetic
+// Vue components and helpers. If the harness can't detect a contrived mismatch, it can't
+// detect a real one.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from 'vue';
+
+import { compareParity } from './parityHarness';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('compareParity', () =>
+{
+    it('matches identical trivial output', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="foo">hi</div>' });
+        const staticFn = () : string => '<div class="foo">hi</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(true);
+    });
+
+    it('detects tag mismatch', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="foo">hi</div>' });
+        const staticFn = () : string => '<span class="foo">hi</span>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(false);
+        if(!result.match) { expect(result.diff).toMatch(/tag mismatch/); }
+    });
+
+    it('detects class-token mismatch regardless of order', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="a b c">x</div>' });
+        const staticFn = () : string => '<div class="a b d">x</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(false);
+        if(!result.match) { expect(result.diff).toMatch(/class mismatch/); }
+    });
+
+    it('treats different class ordering as equal', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="a b c">x</div>' });
+        const staticFn = () : string => '<div class="c a b">x</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(true);
+    });
+
+    it('ignores data-v-* scoped-style attributes on the Vue side', () =>
+    {
+        const Vue = defineComponent({
+            template: '<div class="foo" data-v-abc123="">x</div>',
+        });
+        const staticFn = () : string => '<div class="foo">x</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(true);
+    });
+
+    it('detects attribute value mismatch', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="foo" role="alert">x</div>' });
+        const staticFn = () : string => '<div class="foo" role="warning">x</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(false);
+        if(!result.match) { expect(result.diff).toMatch(/role.*mismatch/); }
+    });
+
+    it('compares style attribute entries order-independently', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="foo" style="color: red; width: 10px;">x</div>' });
+        const staticFn = () : string => '<div class="foo" style="width: 10px; color: red;">x</div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(true);
+    });
+
+    it('detects child count mismatch', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="x"><span>a</span><span>b</span></div>' });
+        const staticFn = () : string => '<div class="x"><span>a</span></div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(false);
+        if(!result.match) { expect(result.diff).toMatch(/child count/); }
+    });
+
+    it('recurses into children', () =>
+    {
+        const Vue = defineComponent({ template: '<div class="x"><span class="y">a</span></div>' });
+        const staticFn = () : string => '<div class="x"><span class="z">a</span></div>';
+        const result = compareParity({ vueComponent: Vue, staticHelper: staticFn, props: {} });
+        expect(result.match).toBe(false);
+        if(!result.match) { expect(result.diff).toMatch(/class mismatch/); }
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/__tests__/parityHarness.ts

@@ -0,0 +1,260 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Vue ↔ Static Parity Harness
+//
+// Mount a Vue component in happy-dom, invoke the equivalent static helper, and compare the
+// resulting DOM trees. Returns either a match result or a human-readable diff describing the
+// first divergence encountered.
+//
+// Used by parity tests to detect drift between the Vue and static implementations. If a prop
+// is added to a Vue component without updating the static helper (or vice versa), parity
+// tests fail loudly.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { mount } from '@vue/test-utils';
+import type { Component } from 'vue';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface ParityInput
+{
+    vueComponent : Component;
+    staticHelper : (props : Record<string, unknown>, children ?: string) => string;
+    props : Record<string, unknown>;
+    children ?: string;
+}
+
+export type ParityResult = { match : true } | { match : false; diff : string };
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+
+// Attributes that Vue injects for scoped styles; ignore them when comparing.
+function isVueScopedAttr(name : string) : boolean
+{
+    return name.startsWith('data-v-');
+}
+
+// Attributes injected at runtime by reka-ui primitives (ToolbarRoot, RovingFocusGroup, etc.)
+// that have no meaningful static equivalent. These are accessibility/interaction attributes set
+// by reka-ui's JS initialization and cannot be reproduced in a static string without running
+// the library. We skip them from the Vue side only — if the static helper were to hard-code
+// them, they'd carry the wrong values (e.g. dir="ltr" is locale-dependent).
+//
+// Covered attrs:
+//   data-orientation  — reka-ui state attribute mirroring the orientation prop
+//   aria-orientation  — set by ToolbarRoot's Primitive as an ARIA attribute
+//   dir               — set by reka-ui's useDirection() composable
+//   tabindex          — set by RovingFocusGroup's focus management
+//   style             — reka-ui injects `outline-color: none; ...` as a focus-ring reset; the
+//                       static helper only emits style for custom color vars, so skip style
+//                       entirely when the Vue side has the reka-ui outline reset fingerprint.
+const REKA_UI_INJECTED_ATTRS = new Set([ 'data-orientation', 'aria-orientation', 'dir', 'tabindex' ]);
+
+function isRekaUiAttr(name : string, value : string) : boolean
+{
+    if(REKA_UI_INJECTED_ATTRS.has(name)) { return true; }
+    // reka-ui's RovingFocusGroup injects an outline reset style; filter `style` when it contains
+    // this fingerprint so it doesn't pollute the diff for non-custom-color toolbars.
+    if(name === 'style' && value.includes('outline-color')) { return true; }
+    return false;
+}
+
+// Class tokens that the static helper emits for CSS-default-detection purposes but that Vue
+// never emits. The `sk-size-*` tokens are added by the static layer so that the SCSS
+// `defaults-when-absent('sk-size-')` mechanism can detect whether a size was explicitly set.
+// Vue's JS-driven rendering doesn't need this sentinel class. Filtering it from the static side
+// before comparison avoids a known structural non-equivalence that is not a real drift signal.
+function isStaticOnlyToken(token : string) : boolean
+{
+    return token.startsWith('sk-size-');
+}
+
+// Split a class attribute into a sorted array of non-empty tokens.
+function classTokens(value : string | null, filterStaticOnly = false) : string[]
+{
+    if(!value) { return []; }
+    const tokens = value.split(/\s+/).filter(Boolean);
+    return (filterStaticOnly ? tokens.filter((token) => !isStaticOnlyToken(token)) : tokens).sort();
+}
+
+// Parse a style attribute into a sorted array of "prop:value" entries.
+function styleEntries(value : string | null) : string[]
+{
+    if(!value) { return []; }
+    return value
+        .split(';')
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .sort();
+}
+
+// True for an element node, or a text node with non-whitespace content. Whitespace-only text
+// nodes get ignored when walking children since Vue/happy-dom and the parsed static HTML often
+// disagree on layout whitespace.
+function isMeaningfulNode(node : ChildNode) : boolean
+{
+    if(node.nodeType === ELEMENT_NODE) { return true; }
+    if(node.nodeType !== TEXT_NODE) { return false; }
+    return Boolean(node.textContent && node.textContent.trim().length > 0);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+function collectVueAttrs(element : Element) : Record<string, string>
+{
+    const attrs : Record<string, string> = {};
+    for(const attr of element.attributes)
+    {
+        const skip = attr.name === 'class'
+            || isVueScopedAttr(attr.name)
+            || isRekaUiAttr(attr.name, attr.value);
+        if(!skip)
+        {
+            attrs[attr.name] = attr.name === 'style' ? styleEntries(attr.value).join('; ') : attr.value;
+        }
+    }
+    return attrs;
+}
+
+function collectStaticAttrs(element : Element) : Record<string, string>
+{
+    const attrs : Record<string, string> = {};
+    for(const attr of element.attributes)
+    {
+        if(attr.name !== 'class')
+        {
+            attrs[attr.name] = attr.name === 'style' ? styleEntries(attr.value).join('; ') : attr.value;
+        }
+    }
+    return attrs;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+function compareTags(vueEl : Element, staticEl : Element, path : string) : string | null
+{
+    if(vueEl.tagName === staticEl.tagName) { return null; }
+    const vueTag = vueEl.tagName.toLowerCase();
+    const staticTag = staticEl.tagName.toLowerCase();
+    return `${ path }: tag mismatch — Vue emits <${ vueTag }>, static emits <${ staticTag }>`;
+}
+
+function compareClasses(vueEl : Element, staticEl : Element, path : string) : string | null
+{
+    const vueClasses = classTokens(vueEl.getAttribute('class'));
+    const staticClasses = classTokens(staticEl.getAttribute('class'), true);
+    if(vueClasses.join(' ') === staticClasses.join(' ')) { return null; }
+    return `${ path }: class mismatch\n  Vue:    ${ vueClasses.join(' ') }`
+        + `\n  static: ${ staticClasses.join(' ') }`;
+}
+
+function compareAttrs(vueEl : Element, staticEl : Element, path : string) : string | null
+{
+    const vueAttrs = collectVueAttrs(vueEl);
+    const staticAttrs = collectStaticAttrs(staticEl);
+    const vueKeys = Object.keys(vueAttrs).sort();
+    const staticKeys = Object.keys(staticAttrs).sort();
+
+    if(vueKeys.join(',') !== staticKeys.join(','))
+    {
+        return `${ path }: attribute set mismatch`
+            + `\n  Vue:    ${ vueKeys.join(', ') || '(none)' }`
+            + `\n  static: ${ staticKeys.join(', ') || '(none)' }`;
+    }
+    for(const key of vueKeys)
+    {
+        if(vueAttrs[key] !== staticAttrs[key])
+        {
+            return `${ path }: attribute ${ key } mismatch`
+                + ` — Vue: "${ vueAttrs[key] }", static: "${ staticAttrs[key] }"`;
+        }
+    }
+    return null;
+}
+
+function compareElements(vueEl : Element, staticEl : Element, path : string) : string | null
+{
+    return compareTags(vueEl, staticEl, path)
+        ?? compareClasses(vueEl, staticEl, path)
+        ?? compareAttrs(vueEl, staticEl, path)
+        // compareChildren is mutually recursive with this function; declared below.
+        // eslint-disable-next-line no-use-before-define
+        ?? compareChildren(vueEl, staticEl, path);
+}
+
+function compareChildren(vueEl : Element, staticEl : Element, path : string) : string | null
+{
+    const vueChildren = Array.from(vueEl.childNodes).filter(isMeaningfulNode);
+    const staticChildren = Array.from(staticEl.childNodes).filter(isMeaningfulNode);
+
+    if(vueChildren.length !== staticChildren.length)
+    {
+        return `${ path }: child count mismatch — Vue: ${ vueChildren.length }`
+            + `, static: ${ staticChildren.length }`;
+    }
+
+    for(let idx = 0; idx < vueChildren.length; idx++)
+    {
+        const vueChild = vueChildren[idx];
+        const staticChild = staticChildren[idx];
+        const childPath = `${ path }>child[${ idx }]`;
+
+        if(vueChild.nodeType !== staticChild.nodeType)
+        {
+            return `${ childPath }: node-type mismatch — Vue: ${ vueChild.nodeType }`
+                + `, static: ${ staticChild.nodeType }`;
+        }
+
+        if(vueChild.nodeType === ELEMENT_NODE)
+        {
+            const diff = compareElements(vueChild as Element, staticChild as Element, childPath);
+            if(diff) { return diff; }
+        }
+        else if(vueChild.nodeType === TEXT_NODE)
+        {
+            const vueText = (vueChild.textContent ?? '').trim();
+            const staticText = (staticChild.textContent ?? '').trim();
+            if(vueText !== staticText)
+            {
+                return `${ childPath }: text mismatch — Vue: "${ vueText }", static: "${ staticText }"`;
+            }
+        }
+    }
+    return null;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function compareParity(input : ParityInput) : ParityResult
+{
+    const wrapper = mount(input.vueComponent, {
+        props: input.props,
+        slots: input.children !== undefined ? { default: input.children } : undefined,
+    });
+    const vueHtml = wrapper.html();
+
+    const staticHtml = input.staticHelper(input.props, input.children);
+
+    const parser = new DOMParser();
+    const vueDoc = parser.parseFromString(`<div>${ vueHtml }</div>`, 'text/html');
+    const staticDoc = parser.parseFromString(`<div>${ staticHtml }</div>`, 'text/html');
+
+    const vueRoot = vueDoc.body.firstElementChild?.firstElementChild;
+    const staticRoot = staticDoc.body.firstElementChild?.firstElementChild;
+
+    if(!vueRoot || !staticRoot)
+    {
+        wrapper.unmount();
+        return { match: false, diff: 'Could not parse Vue or static output' };
+    }
+
+    const diff = compareElements(vueRoot, staticRoot, 'root');
+    wrapper.unmount();
+
+    if(diff === null) { return { match: true }; }
+    return { match: false, diff };
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/classes.test.ts

@@ -0,0 +1,82 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Class Composition Tests
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+
+import { type ClassSpec, composeClasses } from './classes';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const PANEL_SPEC : ClassSpec
+    = {
+        base: 'sk-panel',
+        kind: true, // maps props.kind -> `sk-${kind}` if present
+        size: true, // maps props.size -> `sk-${size}` AND `sk-size-${size}` if present
+        booleanFlags: [ 'no-border', 'no-decoration' ], // if prop = true, emit `sk-${name}`
+        listFlags: // props.<key> as array -> `sk-<family>-${value}` per value
+    [
+        { prop: 'corners', family: 'cut' },
+    ],
+        singleChoiceFlags: // props.<key> as string -> `sk-<family>-${value}`
+    [
+        { prop: 'decorationCorner', family: 'decoration' },
+    ],
+    };
+
+describe('composeClasses', () =>
+{
+    it('returns just the base when no props are given', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, {})).toBe('sk-panel');
+    });
+
+    it('emits kind when provided', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, { kind: 'primary' })).toBe('sk-panel sk-primary');
+    });
+
+    it('emits size as both bare and prefixed', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, { size: 'lg' })).toBe('sk-panel sk-lg sk-size-lg');
+    });
+
+    it('emits boolean flags when true, skips when false or undefined', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, { noBorder: true })).toBe('sk-panel sk-no-border');
+        expect(composeClasses(PANEL_SPEC, { noBorder: false })).toBe('sk-panel');
+        expect(composeClasses(PANEL_SPEC, {})).toBe('sk-panel');
+    });
+
+    it('emits list-flag entries per array value', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, { corners: [ 'top-left', 'bottom-right' ] }))
+            .toBe('sk-panel sk-cut-top-left sk-cut-bottom-right');
+    });
+
+    it('emits single-choice flag when value is present', () =>
+    {
+        expect(composeClasses(PANEL_SPEC, { decorationCorner: 'top-left' }))
+            .toBe('sk-panel sk-decoration-top-left');
+    });
+
+    it('composes multiple families in stable order', () =>
+    {
+        const result = composeClasses(PANEL_SPEC, {
+            kind: 'primary',
+            size: 'lg',
+            corners: [ 'top-left' ],
+            decorationCorner: 'top-left',
+            noBorder: true,
+        });
+        expect(result).toBe('sk-panel sk-primary sk-lg sk-size-lg sk-no-border sk-cut-top-left sk-decoration-top-left');
+    });
+
+    it('converts camelCase boolean prop keys to kebab-case class names', () =>
+    {
+        // boolean flag "no-border" corresponds to camelCase prop "noBorder" per the convention
+        expect(composeClasses(PANEL_SPEC, { noBorder: true })).toBe('sk-panel sk-no-border');
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/classes.ts

@@ -0,0 +1,111 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Class Composition
+//
+// Given a spec describing how a component's props map to CSS class modifiers, and a props
+// object with actual values, compose the space-separated class string that would be emitted
+// onto the component's root element.
+//
+// Stable output order: base → kind → size → variant → booleans → list flags → single-choice
+// flags. Match the Vue component's emission order to keep diffs minimal during parity checks.
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface ListFlagSpec
+{
+    prop : string; // camelCase prop name (e.g. "corners")
+    family : string; // class family prefix (e.g. "cut" -> sk-cut-top-left)
+}
+
+export interface SingleChoiceFlagSpec
+{
+    prop : string; // camelCase prop name (e.g. "decorationCorner")
+    family : string; // class family prefix (e.g. "decoration")
+}
+
+export interface ClassSpec
+{
+    base : string; // e.g. "sk-panel"
+    kind ?: boolean; // maps props.kind -> sk-${kind}
+    size ?: boolean; // maps props.size -> sk-${size} + sk-size-${size}
+    variant ?: boolean; // maps props.variant -> sk-${variant}
+    booleanFlags ?: readonly string[]; // kebab-case class-name list (the prop name is camelCased equivalent)
+    listFlags ?: readonly ListFlagSpec[];
+    singleChoiceFlags ?: readonly SingleChoiceFlagSpec[];
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+// Convert a kebab-case class name to its camelCase prop-name equivalent.
+// "no-border" -> "noBorder", "fixed-header" -> "fixedHeader"
+function kebabToCamel(kebab : string) : string
+{
+    return kebab.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function composeClasses(spec : ClassSpec, props : Record<string, unknown>) : string
+{
+    const parts : string[] = [ spec.base ];
+
+    if(spec.kind && typeof props.kind === 'string')
+    {
+        parts.push(`sk-${ props.kind }`);
+    }
+
+    if(spec.size && typeof props.size === 'string')
+    {
+        parts.push(`sk-${ props.size }`);
+        parts.push(`sk-size-${ props.size }`);
+    }
+
+    if(spec.variant && typeof props.variant === 'string')
+    {
+        parts.push(`sk-${ props.variant }`);
+    }
+
+    if(spec.booleanFlags)
+    {
+        for(const kebab of spec.booleanFlags)
+        {
+            const propName = kebabToCamel(kebab);
+            if(props[propName] === true)
+            {
+                parts.push(`sk-${ kebab }`);
+            }
+        }
+    }
+
+    if(spec.listFlags)
+    {
+        for(const { prop, family } of spec.listFlags)
+        {
+            const value = props[prop];
+            if(Array.isArray(value))
+            {
+                for(const entry of value)
+                {
+                    if(typeof entry === 'string')
+                    {
+                        parts.push(`sk-${ family }-${ entry }`);
+                    }
+                }
+            }
+        }
+    }
+
+    if(spec.singleChoiceFlags)
+    {
+        for(const { prop, family } of spec.singleChoiceFlags)
+        {
+            const value = props[prop];
+            if(typeof value === 'string')
+            {
+                parts.push(`sk-${ family }-${ value }`);
+            }
+        }
+    }
+
+    return parts.join(' ');
+}
+
+//----------------------------------------------------------------------------------------------------------------------