@skewedaspect/sleekspace-ui 0.8.1 → 0.9.1

package/src/styles/mixins/dualSelector.test.ts

@@ -0,0 +1,151 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Dual-Selector Mixin Tests
+//
+// Compiles small SCSS snippets against the `dual-selector` mixins and asserts the emitted
+// selectors contain both class and attribute forms.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+import { compileString } from 'sass';
+import { dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// Utils
+import { attrValueRe, dualSelectorRe } from '../__tests__/testHelpers';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function emit(snippet : string) : string
+{
+    const source = `@use 'dual-selector' as *;\n\n${ snippet }`;
+    const { css } = compileString(source, {
+        loadPaths: [ here ],
+        url: pathToFileURL(`${ here }/dualSelector.test.scss`),
+    });
+    return css;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+// Sass strips quotes from attribute-selector values that don't need them for CSS validity,
+// so `[kind="primary"]` is emitted as `[kind=primary]`. `attrValueRe` and `dualSelectorRe`
+// (imported from testHelpers) build regex fragments that accept both forms.
+
+describe('dual-selector mixins (SCSS)', () =>
+{
+    describe('kind-variant', () =>
+    {
+        it('emits both .sk-foo.sk-primary and sk-foo[kind=primary]', () =>
+        {
+            const css = emit(`@include kind-variant('foo', 'primary') { color: red; }`);
+            expect(css).toMatch(new RegExp(dualSelectorRe('foo', 'primary', 'kind', 'primary')));
+            expect(css).toMatch(/color:\s*red/);
+        });
+    });
+
+    describe('size-variant', () =>
+    {
+        it('emits .sk-foo.sk-lg, .sk-foo.sk-size-lg, and sk-foo[size=lg]', () =>
+        {
+            const css = emit(`@include size-variant('foo', 'lg') { padding: 2rem; }`);
+            expect(css).toMatch(/\.sk-foo\.sk-lg,/);
+            expect(css).toMatch(/\.sk-foo\.sk-size-lg,/);
+            expect(css).toMatch(new RegExp(`sk-foo\\[size=${ attrValueRe('lg') }\\]`));
+        });
+    });
+
+    describe('variant-variant', () =>
+    {
+        it('emits both .sk-foo.sk-solid and sk-foo[variant=solid]', () =>
+        {
+            const css = emit(`@include variant-variant('foo', 'solid') { background: blue; }`);
+            expect(css).toMatch(new RegExp(dualSelectorRe('foo', 'solid', 'variant', 'solid')));
+        });
+    });
+
+    describe('bool-modifier', () =>
+    {
+        it('emits both .sk-foo.sk-no-border and sk-foo[no-border]', () =>
+        {
+            const css = emit(`@include bool-modifier('foo', 'no-border') { border: 0; }`);
+            expect(css).toMatch(/\.sk-foo\.sk-no-border,\s*sk-foo\[no-border\]/);
+        });
+    });
+
+    describe('list-modifier', () =>
+    {
+        it('emits class + ~= attribute selector for a single list value (explicit $attr)', () =>
+        {
+            const css = emit(
+                `@include list-modifier('foo', 'cut', 'top-left', 'corners') { --cut-tl: 8px; }`
+            );
+            expect(css).toMatch(new RegExp(
+                dualSelectorRe('foo', 'cut-top-left', 'corners', 'top-left', { attrOp: '~=' })
+            ));
+        });
+
+        it('uses family as attribute name when $attr is omitted', () =>
+        {
+            const css = emit(`@include list-modifier('foo', 'item', 'alpha') { color: red; }`);
+            expect(css).toMatch(new RegExp(
+                dualSelectorRe('foo', 'item-alpha', 'item', 'alpha', { attrOp: '~=' })
+            ));
+        });
+    });
+
+    describe('single-choice-modifier', () =>
+    {
+        it('emits class + exact-match attribute selector (explicit $attr)', () =>
+        {
+            const css = emit(
+                `@include single-choice-modifier('foo', 'orient', 'vertical', 'orientation') { height: 100%; }`
+            );
+            expect(css).toMatch(new RegExp(
+                dualSelectorRe('foo', 'orient-vertical', 'orientation', 'vertical')
+            ));
+        });
+
+        it('uses family as attribute name when $attr is omitted', () =>
+        {
+            const css = emit(
+                `@include single-choice-modifier('foo', 'mode', 'compact') { padding: 0.5rem; }`
+            );
+            expect(css).toMatch(new RegExp(dualSelectorRe('foo', 'mode-compact', 'mode', 'compact')));
+        });
+    });
+
+    describe('defaults-when-absent', () =>
+    {
+        it('emits :where(:not([class*=sk-cut-])) selector with zero specificity', () =>
+        {
+            const css = emit(`@include defaults-when-absent('foo', 'sk-cut-') { --default: 1; }`);
+            // Sass may or may not quote the [class*=] value; match both forms.
+            expect(css).toMatch(new RegExp(
+                `\\.sk-foo:where\\(:not\\(\\[class\\*=${ attrValueRe('sk-cut-') }\\]\\)\\)`
+            ));
+            expect(css).toMatch(/--default:\s*1/);
+        });
+    });
+
+    describe('defaults-when-no-attr', () =>
+    {
+        it('emits sk-<component>:where(:not([<attr>])) selector with zero specificity', () =>
+        {
+            const css = emit(`@include defaults-when-no-attr('foo', 'kind') { --default: 2; }`);
+            expect(css).toMatch(/sk-foo:where\(:not\(\[kind\]\)\)/);
+            expect(css).toMatch(/--default:\s*2/);
+        });
+
+        it('works with hyphenated attribute names', () =>
+        {
+            const css = emit(
+                `@include defaults-when-no-attr('panel', 'decoration-corner') { color: red; }`
+            );
+            expect(css).toMatch(/sk-panel:where\(:not\(\[decoration-corner\]\)\)/);
+        });
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/themes/_colorful.scss

@@ -5,6 +5,18 @@
  * This swaps the primary/neutral colors from greyscale for a bolder look.
  */
 
+@use 'shade-scale' as *;
+
+$colorful-semantic-map: (
+    'neutral': 'blue',
+    'primary': 'orange',
+    'accent':  'blue',
+    'info':    'cyan',
+    'success': 'green',
+    'warning': 'yellow',
+    'danger':  'red',
+);
+
 [data-scheme="colorful"]
 {
     /* Neutral Kind */
@@ -55,4 +67,17 @@
     --sk-info-active: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
     --sk-info-text: oklch(1 0 0);
     --sk-info-text-contrast: var(--sk-color-gray-95);
+
+    /* Short aliases for the semantic kinds defined above. Must live inside the theme block so
+     * that `var(--sk-<kind>-base)` resolves on this element's cascade. */
+    --sk-neutral: var(--sk-neutral-base);
+    --sk-primary: var(--sk-primary-base);
+    --sk-accent: var(--sk-accent-base);
+    --sk-info: var(--sk-info-base);
+    --sk-success: var(--sk-success-base);
+    --sk-warning: var(--sk-warning-base);
+    --sk-danger: var(--sk-danger-base);
+
+    /* Tailwind-style shade scale (`--sk-primary-50`..`--sk-primary-950`, and so on). */
+    @include semantic-shades($colorful-semantic-map);
 }

package/src/styles/themes/_greyscale.scss

@@ -5,6 +5,18 @@
  * This is the default, more subdued theme.
  */
 
+@use 'shade-scale' as *;
+
+$greyscale-semantic-map: (
+    'neutral': 'gray',
+    'primary': 'blue',
+    'accent':  'orange',
+    'info':    'cyan',
+    'success': 'green',
+    'warning': 'yellow',
+    'danger':  'red',
+);
+
 [data-scheme="greyscale"]
 {
     /* Neutral Kind */
@@ -55,4 +67,17 @@
     --sk-info-active: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
     --sk-info-text: oklch(1 0 0);
     --sk-info-text-contrast: var(--sk-color-gray-95);
+
+    /* Short aliases for the semantic kinds defined above. Must live inside the theme block so
+     * that `var(--sk-<kind>-base)` resolves on this element's cascade. */
+    --sk-neutral: var(--sk-neutral-base);
+    --sk-primary: var(--sk-primary-base);
+    --sk-accent: var(--sk-accent-base);
+    --sk-info: var(--sk-info-base);
+    --sk-success: var(--sk-success-base);
+    --sk-warning: var(--sk-warning-base);
+    --sk-danger: var(--sk-danger-base);
+
+    /* Tailwind-style shade scale (`--sk-primary-50`..`--sk-primary-950`, and so on). */
+    @include semantic-shades($greyscale-semantic-map);
 }

package/src/styles/themes/_shade-scale.scss

@@ -0,0 +1,39 @@
+/**
+ * Theme shade-scale helper
+ *
+ * Shared map + mixin that each theme uses to emit Tailwind-style shade aliases
+ * (`--sk-primary-50`, `--sk-primary-200`, ..., `--sk-primary-950`) for the semantic kinds.
+ * The aliases point at foundation primitives (`--sk-color-<family>-05..95`) so they always
+ * follow the theme's chosen color family.
+ */
+
+@use 'sass:map';
+
+// Tailwind-style shade names mapped to the SleekSpace primitive scale (05 / 10 / ... / 95).
+$shade-map: (
+    50:  '05',
+    100: '10',
+    200: '20',
+    300: '30',
+    400: '40',
+    500: '50',
+    600: '60',
+    700: '70',
+    800: '80',
+    900: '90',
+    950: '95',
+);
+
+/// Emit `--sk-<kind>-{50..950}` aliases for every (kind -> primitive-family) pair in $map.
+/// Call from inside a theme's `[data-scheme="..."]` block so the aliases land on the same
+/// element as the semantic `-base` tokens they pair with.
+@mixin semantic-shades($map)
+{
+    @each $kind, $primitive-family in $map
+    {
+        @each $shade, $primitive-step in $shade-map
+        {
+            --sk-#{ $kind }-#{ $shade }: var(--sk-color-#{ $primitive-family }-#{ $primitive-step });
+        }
+    }
+}

package/src/styles/tokens/_semantic-color-kinds.scss

@@ -8,6 +8,37 @@
  * color kinds always reference the same foundation color.
  */
 
+@use 'sass:map';
+
+// Tailwind-style shade names mapped to the SleekSpace primitive scale (05 / 10 / ... / 95).
+$sk-shade-map: (
+    50:  '05',
+    100: '10',
+    200: '20',
+    300: '30',
+    400: '40',
+    500: '50',
+    600: '60',
+    700: '70',
+    800: '80',
+    900: '90',
+    950: '95',
+);
+
+// Each color kind's alias name paired with the foundation primitive family it draws from.
+$sk-color-kinds: (
+    'boulder':      'gray',
+    'neon-blue':    'blue',
+    'light-blue':   'cyan',
+    'neon-orange':  'orange',
+    'neon-purple':  'purple',
+    'neon-green':   'green',
+    'neon-mint':    'mint',
+    'neon-pink':    'pink',
+    'yellow':       'yellow',
+    'red':          'red',
+);
+
 :root
 {
     /* ===================================================================
@@ -109,4 +140,39 @@
     --sk-red-active: color-mix(in oklch, var(--sk-red-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
     --sk-red-text: oklch(1 0 0);
     --sk-red-text-contrast: var(--sk-color-gray-95);
+
+    /* ===================================================================
+     * Short Aliases
+     *
+     * Shorthand names so consumers can write `var(--sk-neon-pink)` directly
+     * instead of `var(--sk-neon-pink-base)`. Semantic kinds (primary, accent,
+     * etc.) are aliased inside each theme block so `var(--sk-<kind>-base)`
+     * resolves against the theme's actual values.
+     * =================================================================== */
+
+    --sk-boulder: var(--sk-boulder-base);
+    --sk-neon-blue: var(--sk-neon-blue-base);
+    --sk-light-blue: var(--sk-light-blue-base);
+    --sk-neon-orange: var(--sk-neon-orange-base);
+    --sk-neon-purple: var(--sk-neon-purple-base);
+    --sk-neon-green: var(--sk-neon-green-base);
+    --sk-neon-mint: var(--sk-neon-mint-base);
+    --sk-neon-pink: var(--sk-neon-pink-base);
+    --sk-yellow: var(--sk-yellow-base);
+    --sk-red: var(--sk-red-base);
+
+    /* ===================================================================
+     * Tailwind-style shade scale for color kinds
+     *
+     * `--sk-neon-pink-500` = palette 50 (= base); `--sk-neon-pink-200` is two steps lighter,
+     * `--sk-neon-pink-800` is much darker, etc. Full scale: 50, 100..900, 950.
+     * =================================================================== */
+
+    @each $kind, $primitive-family in $sk-color-kinds
+    {
+        @each $shade, $primitive-step in $sk-shade-map
+        {
+            --sk-#{ $kind }-#{ $shade }: var(--sk-color-#{ $primitive-family }-#{ $primitive-step });
+        }
+    }
 }

package/src/{types.ts → types/index.ts}

@@ -22,29 +22,37 @@ export type ComponentVariant = 'solid' | 'outline' | 'subtle' | 'ghost' | 'link'
 
 /**
  * Custom color props interface for components.
- * Allows overriding component colors with any valid CSS color value.
+ * Allows overriding component colors with either a SleekSpace kind name or any CSS color value.
  */
 export interface ComponentCustomColors
 {
     /**
-     * Base color for the component.
-     * Accepts any valid CSS color value including:
-     * - Hex colors: "#8B5CF6"
-     * - OKLCH colors: "oklch(0.7 0.25 300)"
-     * - RGB/HSL: "rgb(139, 92, 246)", "hsl(258, 90%, 66%)"
-     * - CSS variables: "var(--color-neon-green-200)"
-     * - Named colors: "rebeccapurple"
+     * Base color for the component. Accepts either:
+     * - A SleekSpace kind name: `"neutral"`, `"primary"`, `"accent"`, `"info"`, `"success"`,
+     *   `"warning"`, `"danger"`, `"neon-blue"`, `"light-blue"`, `"neon-orange"`,
+     *   `"neon-purple"`, `"neon-green"`, `"neon-mint"`, `"neon-pink"`, `"yellow"`, `"red"`,
+     *   `"boulder"` — resolves to the matching `--sk-<kind>-base` token.
+     * - Any CSS color value: hex (`"#8B5CF6"`), oklch (`"oklch(0.7 0.25 300)"`),
+     *   rgb/hsl (`"rgb(139, 92, 246)"`), a CSS variable (`"var(--my-color)"`), or a
+     *   named color (`"rebeccapurple"`).
      *
      * When provided, this overrides the color from the `kind` prop.
      */
     baseColor ?: string;
 
     /**
-     * Text/foreground color for the component.
-     * If not provided, automatically calculated for optimal contrast with the base color.
-     * Accepts the same CSS color formats as baseColor.
+     * Text/foreground color for the component. Accepts the same kind names and CSS color values
+     * as `baseColor`. If not provided, falls back to the theme's neutral text color for legibility
+     * on arbitrary custom backgrounds.
      */
     textColor ?: string;
+
+    /**
+     * Border color for the component. Accepts the same kind names and CSS color values as
+     * `baseColor`. Only honoured by components that render a visible border (panels, cards,
+     * inputs, etc.); ignored elsewhere.
+     */
+    borderColor ?: string;
 }
 
 //----------------------------------------------------------------------------------------------------------------------

package/src/utils/slots.ts

@@ -0,0 +1,75 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Slot Utilities
+//
+// Helpers for inspecting Vue slot content. The common case: a component renders a wrapper div (or gates a
+// fallback) based on whether a slot was passed. Checking `slots.foo` truthy only tells you a slot *function*
+// exists; it doesn't tell you whether calling it produces anything. A slot whose content resolves to only
+// comments, whitespace text, or a falsy `v-if` still evaluates truthy but renders nothing, which leaves
+// behind empty wrappers that pick up gap/padding and distort layout.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { Comment, Fragment, Text, type VNode } from 'vue';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+// Accepts any slot-shaped callable. Covers both `Slot` (from useSlots) and the narrower
+// `(props) => unknown` signatures that `defineSlots<...>()` produces for typed slots.
+type SlotLike = (...args : any[]) => unknown;
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function hasRenderableContent(vnodes : VNode[]) : boolean
+{
+    return vnodes.some((vnode) =>
+    {
+        if(vnode.type === Comment) { return false; }
+
+        if(vnode.type === Text)
+        {
+            return typeof vnode.children === 'string' && vnode.children.trim().length > 0;
+        }
+
+        if(vnode.type === Fragment && Array.isArray(vnode.children))
+        {
+            return hasRenderableContent(vnode.children as VNode[]);
+        }
+
+        return true;
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function hasSlotContent(slot : SlotLike | undefined, props ?: Record<string, unknown>) : boolean
+{
+    if(!slot) { return false; }
+    return hasRenderableContent(slot(props) as VNode[]);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export function filterRenderableVNodes(vnodes : VNode[]) : VNode[]
+{
+    return vnodes.flatMap((vnode) =>
+    {
+        if(vnode.type === Comment) { return []; }
+
+        if(vnode.type === Text)
+        {
+            if(typeof vnode.children === 'string' && vnode.children.trim().length > 0)
+            {
+                return [ vnode ];
+            }
+            return [];
+        }
+
+        if(vnode.type === Fragment && Array.isArray(vnode.children))
+        {
+            return filterRenderableVNodes(vnode.children as VNode[]);
+        }
+
+        return [ vnode ];
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------