@skewedaspect/sleekspace-ui 0.8.0 → 0.9.0

package/src/static/components/spinner.ts

@@ -0,0 +1,94 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Spinner Static Helper
+//
+// Emits the full spinner DOM structure matching the Vue component's rendered output:
+//   <div class="sk-spinner sk-<kind> sk-<size> sk-variant-<variant>"
+//        role="status" aria-live="polite" aria-label="Loading">
+//     <!-- circular (default) -->
+//     <div class="sk-spinner-circular">
+//       <div class="sk-arc sk-arc-large"></div>
+//       <div class="sk-arc sk-arc-small"></div>
+//     </div>
+//     <!-- dots -->
+//     <div class="sk-spinner-dots">
+//       <div class="sk-dot"></div><div class="sk-dot"></div><div class="sk-dot"></div>
+//     </div>
+//     <!-- crosshair -->
+//     <div class="sk-crosshair-loader"></div>
+//   </div>
+//
+// Variant defaults to 'circular'. Kind defaults to 'primary'. Size defaults to 'md'.
+// These must match Vue's withDefaults() so parity tests pass when explicit defaults are passed.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { ComponentKind, SpinnerSize, SpinnerVariant } from '../types';
+
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface SpinnerStaticProps
+{
+    kind ?: ComponentKind;
+    size ?: SpinnerSize;
+    variant ?: SpinnerVariant;
+
+    /**
+     * Custom color override — maps to `--sk-spinner-color` CSS variable.
+     * Optional; omit to use the kind-derived color.
+     */
+    color ?: string;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+// Inner HTML per variant — mirrors Vue's v-if/v-else-if blocks.
+function innerHtml(variant : SpinnerVariant) : string
+{
+    switch (variant)
+    {
+        case 'circular':
+            return '<div class="sk-spinner-circular">'
+                + '<div class="sk-arc sk-arc-large"></div>'
+                + '<div class="sk-arc sk-arc-small"></div>'
+                + '</div>';
+
+        case 'dots':
+            return '<div class="sk-spinner-dots">'
+                + '<div class="sk-dot"></div>'
+                + '<div class="sk-dot"></div>'
+                + '<div class="sk-dot"></div>'
+                + '</div>';
+
+        case 'crosshair':
+            return '<div class="sk-crosshair-loader"></div>';
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function spinner(props : SpinnerStaticProps = {}) : string
+{
+    const kind = props.kind ?? 'primary';
+    const size = props.size ?? 'md';
+    const variant = props.variant ?? 'circular';
+
+    const classes = [ 'sk-spinner', `sk-${ kind }`, `sk-${ size }`, `sk-variant-${ variant }` ];
+
+    const attrs : string[] = [
+        `class="${ escapeAttr(classes.join(' ')) }"`,
+        'role="status"',
+        'aria-live="polite"',
+        'aria-label="Loading"',
+    ];
+
+    // Custom color var — emitted as inline style when `color` prop is provided.
+    if(typeof props.color === 'string')
+    {
+        attrs.push(`style="--sk-spinner-color: ${ escapeAttr(props.color) };"`);
+    }
+
+    return `<div ${ attrs.join(' ') }>${ innerHtml(variant) }</div>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/switchInput.ts

@@ -0,0 +1,49 @@
+//----------------------------------------------------------------------------------------------------------------------
+// SwitchInput Static Helper
+//
+// File is named switchInput.ts because `switch` is a reserved word in TypeScript/JavaScript.
+// Emits a compound <label class="sk-switch"><input type="checkbox" name="..." />
+// <span class="sk-switch-track"><span class="sk-switch-thumb"></span></span>
+// <span class="sk-switch-label">children</span></label> structure for pure-CSS usage.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { ComponentKind, ComponentSize } from '../types';
+
+import { composeClasses } from '../classes';
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface SwitchStaticProps
+{
+    kind ?: ComponentKind;
+    size ?: ComponentSize;
+    name ?: string;
+    checked ?: boolean;
+    disabled ?: boolean;
+    required ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function switchInput(props : SwitchStaticProps = {}, children = '') : string
+{
+    const classes = composeClasses({ base: 'sk-switch', kind: true, size: true }, props as Record<string, unknown>);
+
+    const inputAttrs : string[] = [ 'type="checkbox"' ];
+    if(props.name)
+    {
+        inputAttrs.push(`name="${ escapeAttr(props.name) }"`);
+    }
+    if(props.checked === true) { inputAttrs.push('checked'); }
+    if(props.disabled === true) { inputAttrs.push('disabled'); }
+    if(props.required === true) { inputAttrs.push('required'); }
+
+    const inputEl = `<input ${ inputAttrs.join(' ') } />`;
+    const trackEl = `<span class="sk-switch-track"><span class="sk-switch-thumb"></span></span>`;
+    const labelEl = `<span class="sk-switch-label">${ children }</span>`;
+
+    return `<label class="${ escapeAttr(classes) }">${ inputEl }${ trackEl }${ labelEl }</label>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/table.ts

@@ -0,0 +1,88 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Table Static Helper
+//
+// Emits the full table DOM structure matching the Vue component's rendered output:
+//   <div class="sk-table-wrapper sk-table-wrapper-<kind> [sk-dark-background] [sk-subtle]">
+//     <table class="sk-table sk-<kind> sk-<variant> [sk-striped] [sk-hoverable] [sk-bordered]
+//                  [sk-no-inner-borders] [sk-subtle]" [style="..."]>
+//       CHILDREN
+//     </table>
+//   </div>
+//
+// Defaults match Vue's withDefaults():
+//   kind='neutral', variant='default', striped=false, hoverable=true, bordered=true,
+//   innerBorders=false, darkBackground=false, subtle=false.
+// These must be passed explicitly when using parity tests so both sides emit the same classes.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { StaticCustomColors, TableKind, TableVariant } from '../types';
+
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface TableStaticProps extends StaticCustomColors
+{
+    kind ?: TableKind;
+    variant ?: TableVariant;
+    striped ?: boolean;
+    hoverable ?: boolean;
+    bordered ?: boolean;
+    innerBorders ?: boolean;
+    darkBackground ?: boolean;
+    subtle ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function table(props : TableStaticProps = {}, children = '') : string
+{
+    const kind = props.kind ?? 'neutral';
+    const variant = props.variant ?? 'default';
+
+    // Prop defaults match Vue's withDefaults()
+    const hoverable = props.hoverable !== false; // default true
+    const bordered = props.bordered !== false; // default true
+    const innerBorders = props.innerBorders === true; // default false
+    const subtle = props.subtle === true;
+    const darkBackground = props.darkBackground === true;
+    const striped = props.striped === true;
+
+    // Wrapper classes (mirrors Vue's wrapperClasses)
+    const wrapperClasses : string[] = [ 'sk-table-wrapper', `sk-table-wrapper-${ kind }` ];
+    if(darkBackground) { wrapperClasses.push('sk-dark-background'); }
+    if(subtle) { wrapperClasses.push('sk-subtle'); }
+
+    // Table classes (mirrors Vue's tableClasses)
+    const tableClasses : string[] = [ 'sk-table', `sk-${ kind }`, `sk-${ variant }` ];
+    if(striped) { tableClasses.push('sk-striped'); }
+    if(hoverable) { tableClasses.push('sk-hoverable'); }
+    if(bordered) { tableClasses.push('sk-bordered'); }
+    if(!innerBorders) { tableClasses.push('sk-no-inner-borders'); }
+    if(subtle) { tableClasses.push('sk-subtle'); }
+
+    const tableAttrs : string[] = [ `class="${ escapeAttr(tableClasses.join(' ')) }"` ];
+
+    // Custom color vars — match Vue's useCustomColors('table', ...) output
+    const styleParts : string[] = [];
+    if(typeof props.baseColor === 'string')
+    {
+        styleParts.push(`--sk-table-color-base: ${ escapeAttr(props.baseColor) };`);
+    }
+    if(typeof props.textColor === 'string')
+    {
+        styleParts.push(`--sk-table-fg: ${ escapeAttr(props.textColor) };`);
+    }
+    if(styleParts.length > 0)
+    {
+        tableAttrs.push(`style="${ styleParts.join(' ') }"`);
+    }
+
+    const wrapperAttr = `class="${ escapeAttr(wrapperClasses.join(' ')) }"`;
+
+    return `<div ${ wrapperAttr }>`
+        + `<table ${ tableAttrs.join(' ') }>${ children }</table>`
+        + '</div>';
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/tag.ts

@@ -0,0 +1,76 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Tag Static Helper
+//
+// Emits the full tag DOM structure matching the Vue component's rendered output:
+//   <span class="sk-tag sk-<kind> sk-<variant> sk-<size> [sk-removable]" [style="..."]>
+//     <span class="sk-tag-content">CHILDREN</span>
+//     [<button type="button" class="sk-tag-remove" aria-label="Remove">
+//       <svg ...>X</svg>
+//     </button>]
+//   </span>
+//
+// The remove button is only emitted when `removable: true`, matching Vue's v-if block.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { ComponentKind, StaticCustomColors, TagSize, TagVariant } from '../types';
+
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface TagStaticProps extends StaticCustomColors
+{
+    kind ?: ComponentKind;
+    variant ?: TagVariant;
+    size ?: TagSize;
+    removable ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+// Remove button SVG — exact content from SkTag.vue
+const REMOVE_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"'
+    + ' viewBox="0 0 24 24" fill="none" stroke="currentColor"'
+    + ' stroke-width="2" stroke-linecap="round" stroke-linejoin="round">'
+    + '<line x1="18" y1="6" x2="6" y2="18"></line>'
+    + '<line x1="6" y1="6" x2="18" y2="18"></line>'
+    + '</svg>';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function tag(props : TagStaticProps = {}, children = '') : string
+{
+    const kind = props.kind ?? 'neutral';
+    const variant = props.variant ?? 'solid';
+    const size = props.size ?? 'md';
+
+    const classes : string[] = [ 'sk-tag', `sk-${ kind }`, `sk-${ variant }`, `sk-${ size }` ];
+    if(props.removable) { classes.push('sk-removable'); }
+
+    const attrs : string[] = [ `class="${ escapeAttr(classes.join(' ')) }"` ];
+
+    // Custom color vars — match Vue's useCustomColors('tag', ...) output
+    const styleParts : string[] = [];
+    if(typeof props.baseColor === 'string')
+    {
+        styleParts.push(`--sk-tag-color-base: ${ escapeAttr(props.baseColor) };`);
+    }
+    if(typeof props.textColor === 'string')
+    {
+        styleParts.push(`--sk-tag-fg: ${ escapeAttr(props.textColor) };`);
+    }
+    if(styleParts.length > 0)
+    {
+        attrs.push(`style="${ styleParts.join(' ') }"`);
+    }
+
+    const contentSpan = `<span class="sk-tag-content">${ children }</span>`;
+
+    const removeButton = props.removable
+        ? `<button type="button" class="sk-tag-remove" aria-label="Remove">${ REMOVE_SVG }</button>`
+        : '';
+
+    return `<span ${ attrs.join(' ') }>${ contentSpan }${ removeButton }</span>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/tagsInput.ts

@@ -0,0 +1,35 @@
+//----------------------------------------------------------------------------------------------------------------------
+// TagsInput Static Helper
+//
+// Emits a <div class="sk-tags-input">children</div> container. Children are hand-composed
+// tag chip elements by the caller — the dynamic add/remove behavior requires Vue/JS and
+// cannot be replicated in a static helper.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { ComponentKind, ComponentSize } from '../types';
+
+import { composeClasses } from '../classes';
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface TagsInputStaticProps
+{
+    kind ?: ComponentKind;
+    size ?: ComponentSize;
+    disabled ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function tagsInput(props : TagsInputStaticProps = {}, children = '') : string
+{
+    const classes = composeClasses(
+        { base: 'sk-tags-input', kind: true, size: true },
+        props as Record<string, unknown>
+    );
+
+    return `<div class="${ escapeAttr(classes) }">${ children }</div>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/textarea.ts

@@ -0,0 +1,53 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Textarea Static Helper
+//
+// Emits a non-void <textarea class="sk-textarea">children</textarea> with passthrough attrs for
+// value, placeholder, name, id, and boolean attrs (disabled, readonly, required).
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { ComponentKind, ComponentSize } from '../types';
+
+import { composeClasses } from '../classes';
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface TextareaStaticProps
+{
+    kind ?: ComponentKind;
+    size ?: ComponentSize;
+    placeholder ?: string;
+    name ?: string;
+    id ?: string;
+    disabled ?: boolean;
+    readonly ?: boolean;
+    required ?: boolean;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function textarea(props : TextareaStaticProps = {}, children = '') : string
+{
+    const classes = composeClasses({ base: 'sk-textarea', kind: true, size: true }, props as Record<string, unknown>);
+    const attrs : string[] = [ `class="${ escapeAttr(classes) }"` ];
+
+    const passthroughString = [ 'placeholder', 'name', 'id' ] as const;
+    for(const key of passthroughString)
+    {
+        const val = props[key];
+        if(typeof val === 'string')
+        {
+            attrs.push(`${ key }="${ escapeAttr(val) }"`);
+        }
+    }
+
+    const passthroughBool = [ 'disabled', 'readonly', 'required' ] as const;
+    for(const key of passthroughBool)
+    {
+        if(props[key] === true) { attrs.push(key); }
+    }
+
+    return `<textarea ${ attrs.join(' ') }>${ children }</textarea>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/toolbar.ts

@@ -0,0 +1,74 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Toolbar Static Helper
+//
+// Emits a class-API toolbar element matching the Vue component's class structure. The Vue
+// component uses reka-ui ToolbarRoot, which injects runtime attributes (aria-orientation,
+// data-orientation, dir, tabindex, outline style) that have no static equivalent. The parity
+// harness filters these reka-ui-injected attributes — only the class structure is compared.
+//
+// Corners default to all four (matching Vue's `corners: () => ['top-left', 'top-right',
+// 'bottom-right', 'bottom-left']` default) so the sk-cut-* classes are emitted by default.
+//
+// Orientation: Vue emits sk-horizontal / sk-vertical directly (not sk-orientation-horizontal),
+// so the class is composed manually here rather than using the singleChoiceFlags mechanism.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { StaticCustomColors, ToolbarCorner, ToolbarKind, ToolbarOrientation } from '../types';
+
+import { escapeAttr } from '../escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface ToolbarStaticProps extends StaticCustomColors
+{
+    kind ?: ToolbarKind;
+    orientation ?: ToolbarOrientation;
+
+    /**
+     * Corner cuts. Defaults to all four corners, matching the Vue component's default.
+     * Pass an empty array to suppress all cuts.
+     * @default ['top-left', 'top-right', 'bottom-right', 'bottom-left']
+     */
+    corners ?: ToolbarCorner[];
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const DEFAULT_CORNERS : ToolbarCorner[] = [ 'top-left', 'top-right', 'bottom-right', 'bottom-left' ];
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function toolbar(props : ToolbarStaticProps = {}, children = '') : string
+{
+    const kind = props.kind;
+    const orientation = props.orientation ?? 'horizontal';
+    const corners = props.corners ?? DEFAULT_CORNERS;
+
+    // Build class list in the same order as Vue's computed classes object:
+    // sk-toolbar → sk-<kind> → sk-<orientation> → sk-cut-*
+    const parts : string[] = [ 'sk-toolbar' ];
+    if(typeof kind === 'string') { parts.push(`sk-${ kind }`); }
+    parts.push(`sk-${ orientation }`);
+    for(const corner of corners) { parts.push(`sk-cut-${ corner }`); }
+
+    const attrs : string[] = [ `class="${ escapeAttr(parts.join(' ')) }"`, 'role="toolbar"' ];
+
+    // Custom color vars
+    const styleParts : string[] = [];
+    if(typeof props.baseColor === 'string')
+    {
+        styleParts.push(`--sk-toolbar-color-base: ${ escapeAttr(props.baseColor) };`);
+    }
+    if(typeof props.textColor === 'string')
+    {
+        styleParts.push(`--sk-toolbar-fg: ${ escapeAttr(props.textColor) };`);
+    }
+    if(styleParts.length > 0)
+    {
+        attrs.push(`style="${ styleParts.join(' ') }"`);
+    }
+
+    return `<div ${ attrs.join(' ') }>${ children }</div>`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/components/tooltip.ts

@@ -0,0 +1,29 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Tooltip Static Helper
+//
+// Thin typed wrapper over the generic render() core. Emits a class-API <div role="tooltip">
+// with sk-tooltip modifier classes derived from props.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { StaticCustomColors, TooltipKind, TooltipSide, TooltipVariant } from '../types';
+
+import { render } from '../render';
+import { SPECS } from '../specs';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface TooltipStaticProps extends StaticCustomColors
+{
+    kind ?: TooltipKind;
+    variant ?: TooltipVariant;
+    placement ?: TooltipSide;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function tooltip(props : TooltipStaticProps = {}, children = '') : string
+{
+    return render(SPECS.tooltip, props as Record<string, unknown>, children);
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/escape.test.ts

@@ -0,0 +1,53 @@
+//----------------------------------------------------------------------------------------------------------------------
+// HTML Escape Tests
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+
+import { escapeAttr, text } from './escape';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('escapeAttr', () =>
+{
+    it('escapes double quotes', () =>
+    {
+        expect(escapeAttr('say "hi"')).toBe('say "hi"');
+    });
+
+    it('escapes ampersands', () =>
+    {
+        expect(escapeAttr('a & b')).toBe('a & b');
+    });
+
+    it('escapes less-than and greater-than', () =>
+    {
+        expect(escapeAttr('<x>')).toBe('&lt;x&gt;');
+    });
+
+    it('handles empty string', () =>
+    {
+        expect(escapeAttr('')).toBe('');
+    });
+
+    it('passes plain text through', () =>
+    {
+        expect(escapeAttr('hello world')).toBe('hello world');
+    });
+});
+
+describe('text', () =>
+{
+    it('escapes all entity characters', () =>
+    {
+        expect(text('<div class="x" & y>'))
+            .toBe('&lt;div class=&quot;x&quot; &amp; y&gt;');
+    });
+
+    it('escapes single quotes', () =>
+    {
+        expect(text("it's")).toBe('it&#39;s');
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/escape.ts

@@ -0,0 +1,28 @@
+//----------------------------------------------------------------------------------------------------------------------
+// HTML Escape Utilities
+//
+// `escapeAttr` escapes values destined for HTML attribute context: &, <, >, and double quotes.
+// `text` escapes values destined for HTML text content — same set plus single quotes for
+// defensive double-escaping when interpolated into single-quoted attributes.
+//----------------------------------------------------------------------------------------------------------------------
+
+export function escapeAttr(value : string) : string
+{
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+export function text(value : string) : string
+{
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+//----------------------------------------------------------------------------------------------------------------------