@skewedaspect/sleekspace-ui 0.8.1 → 0.9.0

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

@@ -0,0 +1,717 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Vue <-> Static Parity Tests
+//
+// For each in-scope component, mount the Vue component with specific props, invoke the matching
+// static helper with the same props, and verify the emitted DOM trees match. Fails loudly when
+// Vue and static drift apart.
+//
+// Props must be passed explicitly (including defaults) so both the Vue component and the static
+// helper see the same values — Vue applies withDefaults() internally, but the static helper only
+// adds modifier classes for props that are explicitly provided.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+
+import SkPanel from '../../components/Panel/SkPanel.vue';
+import SkAlert from '../../components/Alert/SkAlert.vue';
+import SkNavBar from '../../components/NavBar/SkNavBar.vue';
+import SkToolbar from '../../components/Toolbar/SkToolbar.vue';
+import SkSidebar from '../../components/Sidebar/SkSidebar.vue';
+import SkDivider from '../../components/Divider/SkDivider.vue';
+import SkSkeleton from '../../components/Skeleton/SkSkeleton.vue';
+import SkSpinner from '../../components/Spinner/SkSpinner.vue';
+import SkTag from '../../components/Tag/SkTag.vue';
+import SkAvatar from '../../components/Avatar/SkAvatar.vue';
+import SkField from '../../components/Field/SkField.vue';
+import SkTable from '../../components/Table/SkTable.vue';
+
+import { panel } from '../components/panel';
+import { skeleton } from '../components/skeleton';
+import { alert } from '../components/alert';
+import { navBar } from '../components/navBar';
+import { toolbar } from '../components/toolbar';
+import { sidebar } from '../components/sidebar';
+import { divider } from '../components/divider';
+import { spinner } from '../components/spinner';
+import { tag } from '../components/tag';
+import { avatar } from '../components/avatar';
+import { field } from '../components/field';
+import { table } from '../components/table';
+
+import { compareParity } from './parityHarness';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+type StaticFn = (p : Record<string, unknown>, c ?: string) => string;
+
+function expectParity(result : ReturnType<typeof compareParity>) : void
+{
+    if(!result.match)
+    {
+        throw new Error(`Parity failed:\n${ result.diff }`);
+    }
+    expect(result.match).toBe(true);
+}
+
+// Document an intentional Vue/static non-parity. Renders as a skipped test so the
+// reason shows up in test output without ever executing.
+function skipNonParity(reason : string) : void
+{
+    it.skip(`parity not asserted — ${ reason }`, () =>
+    {
+        // intentionally not run; description above documents the divergence
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('parity', () =>
+{
+    //------------------------------------------------------------------------------------------------------------------
+    // Panel
+    //
+    // Simple <div> container that directly matches the static helper. Props must be spelled out
+    // explicitly (including withDefaults values) so both sides emit the same modifier classes.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('panel', () =>
+    {
+        it('default props', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkPanel,
+                staticHelper: panel as StaticFn,
+                // Spell out Panel's withDefaults values so static receives the same prop values.
+                props: { kind: 'neutral', size: 'md', corners: [ 'bottom-right' ], decorationCorner: 'bottom-right' },
+                children: 'content',
+            }));
+        });
+
+        it('kind variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkPanel,
+                staticHelper: panel as StaticFn,
+                props: { kind: 'primary', size: 'md', corners: [ 'bottom-right' ], decorationCorner: 'bottom-right' },
+                children: 'x',
+            }));
+        });
+
+        it('size variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkPanel,
+                staticHelper: panel as StaticFn,
+                props: { kind: 'neutral', size: 'lg', corners: [ 'bottom-right' ], decorationCorner: 'bottom-right' },
+                children: 'x',
+            }));
+        });
+
+        it('corners + decoration combo', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkPanel,
+                staticHelper: panel as StaticFn,
+                props: {
+                    kind: 'accent',
+                    size: 'sm',
+                    corners: [ 'top-left', 'bottom-right' ],
+                    decorationCorner: 'top-left',
+                },
+                children: 'x',
+            }));
+        });
+
+        it('noBorder flag', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkPanel,
+                staticHelper: panel as StaticFn,
+                props: {
+                    kind: 'neutral',
+                    size: 'md',
+                    noBorder: true,
+                    corners: [ 'bottom-right' ],
+                    decorationCorner: 'bottom-right',
+                },
+                children: 'x',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Card
+    //
+    // SKIP: SkCard wraps SkPanel — Vue emits a nested SkPanel structure with sk-card added to its
+    // class, while the static helper emits a plain <div class="sk-card">. These are structurally
+    // divergent by design (static layer intentionally flattens the panel hierarchy).
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('card', () =>
+    {
+        skipNonParity('SkCard wraps SkPanel; static emits a flat <div class="sk-card"> with no inner panel structure');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Alert
+    //
+    // The static helper now emits the full alert structure: kind-appropriate icon div (for
+    // feedback kinds) + sk-alert-content wrapper, matching what SkAlert.vue renders.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('alert', () =>
+    {
+        it('info kind (has icon)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAlert,
+                staticHelper: alert as StaticFn,
+                props: { kind: 'info', subtle: false },
+                children: 'Check this out.',
+            }));
+        });
+
+        it('neutral kind (no icon)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAlert,
+                staticHelper: alert as StaticFn,
+                props: { kind: 'neutral', subtle: false },
+                children: 'Neutral message.',
+            }));
+        });
+
+        it('warning kind (has icon)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAlert,
+                staticHelper: alert as StaticFn,
+                props: { kind: 'warning', subtle: false },
+                children: 'Watch out.',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Divider
+    //
+    // The static helper now emits <hr> with the same class structure as SkDivider.vue:
+    // sk-divider, sk-<orientation>, sk-<kind>, sk-<size>. The aria-orientation attribute is
+    // filtered by the parity harness (it's in REKA_UI_INJECTED_ATTRS) so only the tag name
+    // and class list are compared.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('divider', () =>
+    {
+        it('horizontal (default)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkDivider,
+                staticHelper: divider as StaticFn,
+                props: { orientation: 'horizontal', kind: 'neutral', size: 'md' },
+            }));
+        });
+
+        it('vertical orientation', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkDivider,
+                staticHelper: divider as StaticFn,
+                props: { orientation: 'vertical', kind: 'neutral', size: 'md' },
+            }));
+        });
+
+        it('primary kind', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkDivider,
+                staticHelper: divider as StaticFn,
+                props: { orientation: 'horizontal', kind: 'primary', size: 'md' },
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Page
+    //
+    // SKIP: SkPage is a complex multi-slot layout shell with sidebars, drawers, headers, footers,
+    // and responsive behavior. The static helper emits a plain <div class="sk-page"> — there is no
+    // practical parity between the two at this level.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('page', () =>
+    {
+        skipNonParity('SkPage is a full layout shell; static emits a bare container');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Group
+    //
+    // SKIP: SkGroup emits `sk-${orientation}` (e.g. sk-horizontal) via a template literal, while
+    // the static spec correctly targets the CSS class family `sk-orientation-horizontal` used by
+    // the SCSS single-choice-modifier mixin. These diverge at the class name level. The static
+    // spec matches the CSS — Vue is applying the wrong class name (it works only because
+    // defaults-when-absent catches the unclassed case). Do not modify Vue; document this drift.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('group', () =>
+    {
+        skipNonParity('Vue emits sk-horizontal; static emits sk-orientation-horizontal (matches CSS selector)');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Skeleton
+    //
+    // The static helper now emits the same class names as Vue: sk-<variant> (e.g. sk-text) and
+    // sk-<animation> (e.g. sk-shimmer) when animation is not 'none'. Width/height are forwarded
+    // as inline style so the style attribute also matches. Pass all props explicitly (including
+    // Vue defaults) to ensure both sides emit the same output.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('skeleton', () =>
+    {
+        it('text variant, shimmer animation (Vue defaults)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSkeleton,
+                staticHelper: skeleton as StaticFn,
+                // Vue defaults: variant='text', animation='shimmer', width='100%'
+                props: { variant: 'text', animation: 'shimmer', width: '100%' },
+            }));
+        });
+
+        it('circular variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSkeleton,
+                staticHelper: skeleton as StaticFn,
+                props: { variant: 'circular', animation: 'shimmer', width: '100%' },
+            }));
+        });
+
+        it('pulse animation', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSkeleton,
+                staticHelper: skeleton as StaticFn,
+                props: { variant: 'text', animation: 'pulse', width: '100%' },
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Progress
+    //
+    // SKIP: SkProgress uses reka-ui ProgressRoot which renders as a role="progressbar" div
+    // with aria-valuenow/aria-valuemin/aria-valuemax. The static helper emits a void <progress />
+    // element — different tag, different ARIA model.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('progress', () =>
+    {
+        skipNonParity('Vue uses reka-ui ProgressRoot with aria-value* attrs; static emits <progress />');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Spinner
+    //
+    // The static helper now emits the full inner DOM structure for each variant, matching
+    // SkSpinner.vue's v-if/v-else-if template blocks. ARIA attributes (role, aria-live,
+    // aria-label) are emitted on the root element. Pass all props explicitly including defaults.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('spinner', () =>
+    {
+        it('circular variant (default)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSpinner,
+                staticHelper: spinner as StaticFn,
+                props: { kind: 'primary', size: 'md', variant: 'circular' },
+            }));
+        });
+
+        it('dots variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSpinner,
+                staticHelper: spinner as StaticFn,
+                props: { kind: 'primary', size: 'md', variant: 'dots' },
+            }));
+        });
+
+        it('crosshair variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSpinner,
+                staticHelper: spinner as StaticFn,
+                props: { kind: 'primary', size: 'md', variant: 'crosshair' },
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // NavBar
+    //
+    // The static helper now emits the sk-navbar-content wrapper and conditional slot divs,
+    // matching SkNavBar's rendered output. Sticky defaults to true on both sides.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('navBar', () =>
+    {
+        it('default kind with nav children', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkNavBar,
+                staticHelper: navBar as StaticFn,
+                props: { kind: 'neutral', sticky: true },
+                children: 'Nav Links',
+            }));
+        });
+
+        it('primary kind, sticky', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkNavBar,
+                staticHelper: navBar as StaticFn,
+                props: { kind: 'primary', sticky: true },
+                children: 'x',
+            }));
+        });
+
+        it('accent kind, non-sticky', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkNavBar,
+                staticHelper: navBar as StaticFn,
+                props: { kind: 'accent', sticky: false },
+                children: 'Link A',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Toolbar
+    //
+    // The static helper now emits the full class structure matching SkToolbar (sk-toolbar,
+    // sk-<kind>, sk-<orientation>, sk-cut-* for all corners). The parity harness filters
+    // reka-ui runtime attributes (aria-orientation, data-orientation, dir, tabindex, and the
+    // outline-reset inline style) since these are injected by ToolbarRoot and have no static
+    // equivalent. Only the class structure is compared — which is what the CSS consumes.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('toolbar', () =>
+    {
+        it('default props (all four corners, horizontal)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkToolbar,
+                staticHelper: toolbar as StaticFn,
+                props: {
+                    kind: 'neutral',
+                    orientation: 'horizontal',
+                    corners: [ 'top-left', 'top-right', 'bottom-right', 'bottom-left' ],
+                },
+                children: 'content',
+            }));
+        });
+
+        it('primary kind, vertical', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkToolbar,
+                staticHelper: toolbar as StaticFn,
+                props: {
+                    kind: 'primary',
+                    orientation: 'vertical',
+                    corners: [ 'top-left', 'top-right', 'bottom-right', 'bottom-left' ],
+                },
+                children: 'x',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Sidebar
+    //
+    // The static helper now emits the full nested structure: aside → sk-panel (sk-sidebar-panel)
+    // → sk-panel-scroll-content → sk-sidebar-nav. The panel corner/decoration corner is computed
+    // from the `side` prop, matching SkSidebar's computed panelCorners/panelDecorationCorner.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('sidebar', () =>
+    {
+        it('left side (default)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSidebar,
+                staticHelper: sidebar as StaticFn,
+                props: { kind: 'neutral', side: 'left', dense: false },
+                children: 'nav-content',
+            }));
+        });
+
+        it('right side', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSidebar,
+                staticHelper: sidebar as StaticFn,
+                props: { kind: 'neutral', side: 'right', dense: false },
+                children: 'x',
+            }));
+        });
+
+        it('primary kind', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkSidebar,
+                staticHelper: sidebar as StaticFn,
+                props: { kind: 'primary', side: 'left', dense: false },
+                children: 'x',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Breadcrumbs
+    //
+    // SKIP: SkBreadcrumbs wraps slot content in <ol class="sk-breadcrumbs-list"> and inserts
+    // SkBreadcrumbSeparator components between items. The static helper emits a bare <nav>
+    // with no inner list structure.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('breadcrumbs', () =>
+    {
+        skipNonParity('Vue wraps items in <ol class="sk-breadcrumbs-list"> with separators; static emits bare <nav>');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Pagination
+    //
+    // SKIP: SkPagination renders SkPaginationItem children (first/prev/page numbers/next/last)
+    // and requires a `total` prop to compute its item list. The static helper emits only the
+    // <nav class="sk-pagination ..."> container with no inner items.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('pagination', () =>
+    {
+        skipNonParity('Vue renders pagination items (prev/page/next); static emits bare <nav> container');
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Tag
+    //
+    // The static helper now wraps children in <span class="sk-tag-content"> and conditionally
+    // emits the remove button when `removable: true`, matching SkTag.vue's template structure.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('tag', () =>
+    {
+        it('default (neutral, solid, md)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTag,
+                staticHelper: tag as StaticFn,
+                props: { kind: 'neutral', variant: 'solid', size: 'md', removable: false },
+                children: 'Label',
+            }));
+        });
+
+        it('primary kind, outline variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTag,
+                staticHelper: tag as StaticFn,
+                props: { kind: 'primary', variant: 'outline', size: 'md', removable: false },
+                children: 'Feature',
+            }));
+        });
+
+        it('removable: true emits remove button', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTag,
+                staticHelper: tag as StaticFn,
+                props: { kind: 'neutral', variant: 'solid', size: 'md', removable: true },
+                children: 'Close me',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Avatar
+    //
+    // The static helper now emits the correct inner content based on src/initials props:
+    //   - src provided → <img class="sk-avatar-image" src="..." alt="...">
+    //   - initials provided (no src) → <span class="sk-avatar-initials">AB</span>
+    //   - neither → default SVG icon <svg class="sk-avatar-icon">...</svg>
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('avatar', () =>
+    {
+        it('default (no src, no initials — SVG icon)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAvatar,
+                staticHelper: avatar as StaticFn,
+                props: { kind: 'neutral', size: 'md' },
+            }));
+        });
+
+        it('with src and alt — img element', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAvatar,
+                staticHelper: avatar as StaticFn,
+                props: { kind: 'neutral', size: 'md', src: '/test.jpg', alt: 'Test User' },
+            }));
+        });
+
+        it('initials fallback', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkAvatar,
+                staticHelper: avatar as StaticFn,
+                props: { kind: 'primary', size: 'lg', initials: 'JD' },
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Field
+    //
+    // The static helper now emits the full field structure matching SkField.vue: sk-label-top
+    // default, sk-field-input-wrapper always wrapping children, and optional label/description/
+    // error elements. An explicit `id` prop is passed so that Vue's `for`/`id` attrs are
+    // deterministic and match the static output (Vue would otherwise auto-generate a random ID).
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('field', () =>
+    {
+        it('no label, no error (input wrapper only)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkField,
+                staticHelper: field as StaticFn,
+                props: { labelPosition: 'top', id: 'f1' },
+                children: '<input class="sk-input" />',
+            }));
+        });
+
+        it('with label', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkField,
+                staticHelper: field as StaticFn,
+                props: { label: 'Email', labelPosition: 'top', id: 'f2' },
+                children: '<input class="sk-input" />',
+            }));
+        });
+
+        it('with error', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkField,
+                staticHelper: field as StaticFn,
+                props: { error: 'Required', labelPosition: 'top', id: 'f3' },
+                children: '<input class="sk-input" />',
+            }));
+        });
+
+        it('with description (no error)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkField,
+                staticHelper: field as StaticFn,
+                props: { description: 'Help text', labelPosition: 'top', id: 'f4' },
+                children: '<input class="sk-input" />',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Table
+    //
+    // The static helper now emits the wrapper div + table, matching SkTable.vue's rendered output.
+    // Vue defaults (hoverable=true, bordered=true, innerBorders=false, variant='default') must be
+    // passed explicitly so both sides emit the same class sets.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('table', () =>
+    {
+        it('default props (neutral, default variant, hoverable, bordered)', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTable,
+                staticHelper: table as StaticFn,
+                props: {
+                    kind: 'neutral',
+                    variant: 'default',
+                    striped: false,
+                    hoverable: true,
+                    bordered: true,
+                    innerBorders: false,
+                    darkBackground: false,
+                    subtle: false,
+                },
+                children: '<thead><tr><th>Name</th></tr></thead>',
+            }));
+        });
+
+        it('primary kind', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTable,
+                staticHelper: table as StaticFn,
+                props: {
+                    kind: 'primary',
+                    variant: 'default',
+                    striped: false,
+                    hoverable: true,
+                    bordered: true,
+                    innerBorders: false,
+                    darkBackground: false,
+                    subtle: false,
+                },
+                children: 'x',
+            }));
+        });
+
+        it('striped + compact variant', () =>
+        {
+            expectParity(compareParity({
+                vueComponent: SkTable,
+                staticHelper: table as StaticFn,
+                props: {
+                    kind: 'neutral',
+                    variant: 'compact',
+                    striped: true,
+                    hoverable: true,
+                    bordered: true,
+                    innerBorders: false,
+                    darkBackground: false,
+                    subtle: false,
+                },
+                children: 'x',
+            }));
+        });
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Tooltip
+    //
+    // SKIP: SkTooltip uses reka-ui's portal (TooltipPortal) — the tooltip content is rendered
+    // outside the component tree in a separate DOM node. The static helper emits a plain
+    // <div role="tooltip"> inline. These are fundamentally different rendering models.
+    //------------------------------------------------------------------------------------------------------------------
+
+    describe('tooltip', () =>
+    {
+        skipNonParity(
+            'Vue uses reka-ui portal (tooltip content is teleported);'
+            + ' static emits inline <div role="tooltip">'
+        );
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------