@skewedaspect/sleekspace-ui 0.8.0 → 0.9.0

package/src/static/specs.test.ts

@@ -0,0 +1,58 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Spec Coverage Test
+//
+// Ensures every component directory under src/components/ has an entry in SPECS (or is
+// explicitly noted as compound/hand-written). Catches drift when new Vue components are added.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { SPECS } from './specs';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const here = dirname(fileURLToPath(import.meta.url));
+const componentsDir = join(here, '..', 'components');
+
+// Components that are out-of-scope per the design spec (Vue-only, not pure-CSS-eligible)
+const OUT_OF_SCOPE = new Set([
+    'Accordion',
+    'Collapsible',
+    'ContextMenu',
+    'Listbox',
+    'Modal',
+    'Popover',
+    'ScrollArea',
+    'Splitter',
+    'Tabs',
+    'Theme',
+    'Toast',
+    'TreeView',
+]);
+
+// Components with hand-written helpers (compound structure beyond the generic renderer's reach)
+const HAND_WRITTEN = new Set([ 'Button', 'Checkbox', 'Radio', 'Switch', 'NumberInput', 'TagsInput' ]);
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('spec coverage', () =>
+{
+    const componentDirs = readdirSync(componentsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((dir) => !OUT_OF_SCOPE.has(dir) && !HAND_WRITTEN.has(dir));
+
+    for(const dir of componentDirs)
+    {
+        it(`${ dir } has a spec`, () =>
+        {
+            const key = dir.charAt(0).toLowerCase() + dir.slice(1);
+            expect(SPECS[key], `SPECS["${ key }"] should exist for ${ dir }`).toBeDefined();
+        });
+    }
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/specs.ts

@@ -0,0 +1,230 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Per-Component Spec Registry
+//
+// Maps each component name to its RenderSpec. Used by helper functions to render the right
+// HTML structure with the right modifier-class composition and custom-color handling.
+//
+// Hand-maintained. When adding a component, add its spec here. The codegen covers prop types
+// and defaults but not the render shape — that's this file's job.
+//----------------------------------------------------------------------------------------------------------------------
+
+import type { RenderSpec } from './render';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export const SPECS : Record<string, RenderSpec> = {
+    panel: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-panel',
+            kind: true,
+            size: true,
+            booleanFlags: [ 'no-border', 'no-decoration' ],
+            listFlags: [ { prop: 'corners', family: 'cut' } ],
+            singleChoiceFlags: [ { prop: 'decorationCorner', family: 'decoration' } ],
+        },
+        customColorVars: { base: '--sk-panel-color-base', text: '--sk-panel-fg' },
+    },
+
+    card: {
+        tag: 'div',
+        classSpec: { base: 'sk-card', kind: true },
+        customColorVars: { base: '--sk-panel-color-base', text: '--sk-panel-fg' },
+    },
+
+    alert: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-alert',
+            kind: true,
+            booleanFlags: [ 'subtle' ],
+        },
+        extraAttrs: { role: 'alert' },
+        customColorVars: { base: '--sk-alert-color-base', text: '--sk-alert-fg' },
+    },
+
+    divider: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-divider',
+            kind: true,
+            booleanFlags: [ 'subtle' ],
+            singleChoiceFlags: [ { prop: 'orientation', family: 'orientation' } ],
+        },
+        extraAttrs: { role: 'separator' },
+    },
+
+    page: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-page',
+            booleanFlags: [ 'flush', 'fixed-header', 'fixed-footer' ],
+        },
+    },
+
+    group: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-group',
+            singleChoiceFlags: [ { prop: 'orientation', family: 'orientation' } ],
+        },
+    },
+
+    // `prop: 'variant'` matches Vue's prop name; CSS family `shape` (sk-shape-*) is unchanged.
+    skeleton: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-skeleton',
+            singleChoiceFlags: [ { prop: 'variant', family: 'shape' } ],
+            booleanFlags: [ 'shimmer', 'pulse' ],
+        },
+    },
+
+    progress: {
+        tag: 'progress',
+        classSpec: {
+            base: 'sk-progress',
+            kind: true,
+            size: true,
+            booleanFlags: [ 'indeterminate' ],
+        },
+        void: true,
+    },
+
+    spinner: {
+        tag: 'div',
+        classSpec: { base: 'sk-spinner', kind: true, size: true },
+    },
+
+    // NavBar dir → camelCase key "navBar" (consistent with the test's key-derivation pattern)
+    navBar: {
+        tag: 'nav',
+        classSpec: { base: 'sk-navbar', kind: true, booleanFlags: [ 'sticky' ] },
+    },
+
+    toolbar: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-toolbar',
+            kind: true,
+            singleChoiceFlags: [ { prop: 'orientation', family: 'orientation' } ],
+        },
+        extraAttrs: { role: 'toolbar' },
+    },
+
+    sidebar: {
+        tag: 'aside',
+        classSpec: { base: 'sk-sidebar', kind: true, booleanFlags: [ 'dense' ] },
+    },
+
+    breadcrumbs: {
+        tag: 'nav',
+        classSpec: { base: 'sk-breadcrumbs', kind: true },
+        extraAttrs: { 'aria-label': 'Breadcrumbs' },
+    },
+
+    pagination: {
+        tag: 'nav',
+        classSpec: { base: 'sk-pagination', kind: true },
+        extraAttrs: { 'aria-label': 'Pagination' },
+    },
+
+    tag: {
+        tag: 'span',
+        classSpec: {
+            base: 'sk-tag',
+            kind: true,
+            size: true,
+            variant: true,
+            booleanFlags: [ 'removable' ],
+        },
+    },
+
+    avatar: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-avatar',
+            kind: true,
+            size: true,
+            singleChoiceFlags: [ { prop: 'shape', family: 'shape' } ],
+        },
+    },
+
+    field: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-field',
+            booleanFlags: [ 'has-error' ],
+            singleChoiceFlags: [ { prop: 'labelPosition', family: 'label-position' } ],
+        },
+    },
+
+    table: {
+        tag: 'table',
+        classSpec: {
+            base: 'sk-table',
+            kind: true,
+            variant: true,
+            booleanFlags: [ 'striped', 'bordered', 'compact', 'comfortable' ],
+        },
+    },
+
+    tooltip: {
+        tag: 'div',
+        classSpec: {
+            base: 'sk-tooltip',
+            kind: true,
+            variant: true,
+            singleChoiceFlags: [ { prop: 'placement', family: 'placement' } ],
+        },
+        extraAttrs: { role: 'tooltip' },
+    },
+
+    // Class-only form controls — class-API HTML on native elements
+    input: {
+        tag: 'input',
+        classSpec: { base: 'sk-input', kind: true, size: true },
+        void: true,
+    },
+
+    textarea: {
+        tag: 'textarea',
+        classSpec: { base: 'sk-textarea', kind: true, size: true },
+    },
+
+    select: {
+        tag: 'select',
+        classSpec: { base: 'sk-select', kind: true, size: true },
+    },
+
+    slider: {
+        tag: 'input',
+        classSpec: {
+            base: 'sk-slider',
+            kind: true,
+            size: true,
+            singleChoiceFlags: [ { prop: 'orientation', family: 'orientation' } ],
+        },
+        void: true,
+        extraAttrs: { type: 'range' },
+    },
+
+    colorPicker: {
+        tag: 'input',
+        classSpec: { base: 'sk-color-picker', size: true },
+        void: true,
+        extraAttrs: { type: 'color' },
+    },
+
+    // Compound components (checkbox/radio/switch/numberInput/tagsInput) are hand-written — see
+    // respective component files. They compose multiple inner elements the generic renderer
+    // can't express.
+
+    // Dropdown: disclosure via <details> + <summary>
+    dropdown: {
+        tag: 'details',
+        classSpec: { base: 'sk-dropdown', kind: true, size: true },
+    },
+};
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/static/types.ts

@@ -0,0 +1,176 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Static Helpers — Shared Types
+//
+// All types are declared directly here — no imports from outside `src/static/`. This keeps
+// TypeScript's computed common source root at `src/static/` so vite-plugin-dts emits
+// declarations directly to `dist/static/` without any post-build file shuffling.
+//
+// The token types (SemanticKind, ColorKind, ComponentKind, ComponentSize, ComponentVariant) are
+// copied from `src/types.ts`. They must be kept in sync manually if the canonical definitions
+// change. Static module consumers can import these types from `@skewedaspect/sleekspace-ui/static`
+// without pulling in the Vue package.
+//----------------------------------------------------------------------------------------------------------------------
+
+// Semantic kinds (themeable, colors with meaning)
+export type SemanticKind = 'neutral' | 'primary' | 'accent' | 'danger' | 'info' | 'success' | 'warning';
+
+// Color kinds (non-themeable, direct palette access)
+export type ColorKind = 'boulder' | 'neon-blue' | 'light-blue' | 'neon-orange' | 'neon-purple' | 'neon-green'
+    | 'neon-mint' | 'neon-pink' | 'yellow' | 'red';
+
+// All component kinds (semantic + color)
+export type ComponentKind = SemanticKind | ColorKind;
+
+// Common component sizes
+export type ComponentSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+// Common button/interactive variants
+export type ComponentVariant = 'solid' | 'outline' | 'subtle' | 'ghost' | 'link';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Custom-color props (mirror of ComponentCustomColors from src/types.ts)
+//
+// Defined directly so the `./static` subpath doesn't pull in Vue-adjacent code.
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface StaticCustomColors
+{
+    baseColor ?: string;
+    textColor ?: string;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Common helper signature
+//----------------------------------------------------------------------------------------------------------------------
+
+export type HtmlString = string;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Alert
+//----------------------------------------------------------------------------------------------------------------------
+
+export type AlertKind = ComponentKind;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Avatar
+//----------------------------------------------------------------------------------------------------------------------
+
+export type AvatarSize = ComponentSize;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Breadcrumbs
+//----------------------------------------------------------------------------------------------------------------------
+
+export type BreadcrumbsKind = ComponentKind;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Button
+//----------------------------------------------------------------------------------------------------------------------
+
+export type ButtonKind = ComponentKind;
+export type ButtonSize = ComponentSize;
+export type ButtonVariant = ComponentVariant;
+export type ButtonType = 'button' | 'submit' | 'reset';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Card
+//----------------------------------------------------------------------------------------------------------------------
+
+export type CardKind = ComponentKind;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Divider
+//----------------------------------------------------------------------------------------------------------------------
+
+export type DividerOrientation = 'horizontal' | 'vertical';
+export type DividerVariant = 'subtle';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Field
+//----------------------------------------------------------------------------------------------------------------------
+
+export type FieldLabelPosition = 'top' | 'left';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Group
+//----------------------------------------------------------------------------------------------------------------------
+
+export type GroupOrientation = 'horizontal' | 'vertical';
+
+//----------------------------------------------------------------------------------------------------------------------
+// NavBar
+//----------------------------------------------------------------------------------------------------------------------
+
+export type NavBarKind = ComponentKind;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Page
+//----------------------------------------------------------------------------------------------------------------------
+
+export type PagePanelMode = 'auto' | 'persistent' | 'drawer';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Pagination
+//----------------------------------------------------------------------------------------------------------------------
+
+export type PaginationKind = ComponentKind;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Panel
+//----------------------------------------------------------------------------------------------------------------------
+
+export type PanelKind = ComponentKind;
+export type PanelSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type PanelCorner = 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Progress
+//----------------------------------------------------------------------------------------------------------------------
+
+export type ProgressSize = ComponentSize;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Sidebar
+//----------------------------------------------------------------------------------------------------------------------
+
+export type SidebarKind = ComponentKind;
+export type SidebarSide = 'left' | 'right';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Spinner
+//----------------------------------------------------------------------------------------------------------------------
+
+export type SpinnerSize = ComponentSize;
+export type SpinnerVariant = 'circular' | 'dots' | 'crosshair';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Table
+//----------------------------------------------------------------------------------------------------------------------
+
+export type TableKind = ComponentKind;
+export type TableVariant = 'default' | 'compact' | 'comfortable';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Tag
+//----------------------------------------------------------------------------------------------------------------------
+
+export type TagVariant = 'solid' | 'outline' | 'subtle' | 'ghost';
+export type TagSize = 'sm' | 'md' | 'lg' | 'xl';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Toolbar
+//----------------------------------------------------------------------------------------------------------------------
+
+export type ToolbarKind = ComponentKind;
+export type ToolbarOrientation = 'horizontal' | 'vertical';
+export type ToolbarCorner = 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Tooltip
+//----------------------------------------------------------------------------------------------------------------------
+
+export type TooltipKind = ComponentKind;
+export type TooltipVariant = ComponentVariant;
+export type TooltipSide = 'top' | 'right' | 'bottom' | 'left';
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/__tests__/testHelpers.ts

@@ -0,0 +1,97 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Shared SCSS Test Helpers
+//
+// Parses the canonical kinds/sizes/variants lists from `src/styles/theme/_variables.scss` so
+// test files can iterate over them without hardcoding. Also exports a small regex helper for
+// matching Sass's unquoted attribute values (Sass strips quotes from attribute selectors when
+// CSS allows it, so `[kind="primary"]` can be emitted as `[kind=primary]`).
+//----------------------------------------------------------------------------------------------------------------------
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const here = dirname(fileURLToPath(import.meta.url));
+const variablesPath = resolve(here, '..', 'theme', '_variables.scss');
+const variablesSource = readFileSync(variablesPath, 'utf8');
+
+function extractList(name : string) : string[]
+{
+    const pattern = new RegExp(`\\$${ name }\\s*:\\s*([^;]+);`, 'm');
+    const match = variablesSource.match(pattern);
+    if(!match)
+    {
+        throw new Error(`Could not find $${ name } in ${ variablesPath }`);
+    }
+    return match[1]
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export const SEMANTIC_KINDS : readonly string[] = extractList('semantic-kinds');
+export const COLOR_KINDS : readonly string[] = extractList('color-kinds');
+export const KINDS : readonly string[] = extractList('kinds');
+export const VARIANTS : readonly string[] = extractList('variants');
+export const SIZES : readonly string[] = extractList('sizes');
+
+//----------------------------------------------------------------------------------------------------------------------
+// Regex escape helpers
+//
+// `escapeRe` escapes hyphens in a value so it slots into a regex char class safely (only
+// hyphens matter for the kinds/sizes/modifiers the selector tests assert on). `attrValueRe`
+// wraps the escaped value in optional quotes so it matches both Sass's quoted and unquoted
+// attribute-selector emissions. Use both inside `new RegExp(...)` template literals to keep
+// dual-selector assertions short.
+//----------------------------------------------------------------------------------------------------------------------
+
+export function escapeRe(value : string) : string
+{
+    return value.replace(/-/g, '\\-');
+}
+
+export function attrValueRe(value : string) : string
+{
+    return `"?${ escapeRe(value) }"?`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Dual-selector regex builder
+//
+// Builds the regex fragment matching a dual-selector pair of the form:
+//   .sk-<component>.sk-<classModifier><suffix>, sk-<component>[<attr><op><attrValue>]<suffix>
+// Pass `attrValue` undefined for boolean attributes (just `[attr]`).
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface DualSelectorOptions
+{
+    attrOp ?: string;
+    suffix ?: string;
+    // Regex fragment appended after `\s+` to both the class and attribute forms (e.g. for
+    // a descendant combinator like `\.sk-page-header`).
+    descendant ?: string;
+}
+
+export function dualSelectorRe(
+    component : string,
+    classModifier : string,
+    attr : string,
+    attrValue ?: string,
+    opts : DualSelectorOptions = {}
+) : string
+{
+    const op = opts.attrOp ?? '=';
+    const suffix = opts.suffix ?? '';
+    const tail = opts.descendant ? `${ suffix }\\s+${ opts.descendant }` : suffix;
+    const cls = `\\.sk-${ component }\\.sk-${ escapeRe(classModifier) }${ tail }`;
+    const attrFrag = attrValue === undefined
+        ? `sk-${ component }\\[${ attr }\\]${ tail }`
+        : `sk-${ component }\\[${ attr }${ op }${ attrValueRe(attrValue) }\\]${ tail }`;
+    return `${ cls },\\s*${ attrFrag }`;
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/base/_custom-elements.scss

@@ -0,0 +1,51 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Custom Element Base Styles
+//
+// Unknown elements default to `display: inline` in HTML. For the light-DOM custom-element forms
+// of in-scope container components (`<sk-panel>`, `<sk-card>`, etc.), we want `display: block`
+// (or an appropriate alternative) so they behave like their `<div>`-based class-API
+// counterparts without authors having to add `display:block` themselves.
+//
+// This file ONLY applies to custom-element TAG names. The class API (`<div class="sk-panel">`)
+// inherits display from the underlying element and is unaffected.
+//----------------------------------------------------------------------------------------------------------------------
+
+@layer base
+{
+    // Block-level containers + separators
+    sk-panel,
+    sk-card,
+    sk-alert,
+    sk-page,
+    sk-navbar,
+    sk-toolbar,
+    sk-sidebar,
+    sk-breadcrumbs,
+    sk-pagination,
+    sk-field,
+    sk-table,
+    sk-progress,
+    sk-divider
+    {
+        display: block;
+    }
+
+    // Inline-flex containers (layout helpers, badges)
+    sk-group,
+    sk-tag,
+    sk-avatar,
+    sk-spinner,
+    sk-skeleton
+    {
+        display: inline-flex;
+    }
+
+    // Tooltip container — positioning handled by the component's CSS; the tag itself is a wrapper
+    sk-tooltip
+    {
+        display: inline-block;
+        position: relative;
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/base/_index.scss

@@ -19,6 +19,10 @@
 
     // 4. Typography
     @include meta.load-css('typography');
+
+    // 5. Custom Element Display Defaults (must come after reset so the reset's
+    //    element-level `display: inline` defaults don't override these rules)
+    @include meta.load-css('custom-elements');
 }
 
 //----------------------------------------------------------------------------------------------------------------------