@skewedaspect/sleekspace-ui 0.8.1 → 0.9.1

package/src/composables/useCustomColors.ts

@@ -4,117 +4,126 @@
 
 import { type Ref, computed } from 'vue';
 
+//----------------------------------------------------------------------------------------------------------------------
+// Kind name resolution
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Kind names that the color props accept as shortcuts. Typing `baseColor="neon-pink"` resolves
+ * to `var(--sk-neon-pink-base)`; typing `borderColor="primary"` resolves to `var(--sk-primary-base)`.
+ * Any string not in this set is passed through verbatim as a CSS color value.
+ */
+const KIND_NAMES = new Set<string>([
+    // Semantic
+    'neutral',
+    'primary',
+    'accent',
+    'info',
+    'success',
+    'warning',
+    'danger',
+    // Color
+    'boulder',
+    'neon-blue',
+    'light-blue',
+    'neon-orange',
+    'neon-purple',
+    'neon-green',
+    'neon-mint',
+    'neon-pink',
+    'yellow',
+    'red',
+]);
+
+type ColorPart = 'base' | 'text';
+
+function resolveColor(value : string | undefined, part : ColorPart) : string | undefined
+{
+    if(!value) { return undefined; }
+    const trimmed = value.trim();
+    if(KIND_NAMES.has(trimmed))
+    {
+        return `var(--sk-${ trimmed }-${ part })`;
+    }
+    return value;
+}
+
+function unwrap(input : Ref<string | undefined> | string | undefined) : string | undefined
+{
+    return typeof input === 'string' ? input : input?.value;
+}
+
 //----------------------------------------------------------------------------------------------------------------------
 
 /**
  * Composable for handling custom color props in components.
  *
- * This composable provides a consistent way to apply custom colors to components by generating
- * CSS variables that override the component's default color tokens. It supports any CSS color
- * format including hex, rgb, hsl, oklch, named colors, and CSS variables.
+ * Generates CSS custom properties that override a component's default color tokens. Props accept
+ * either a kind name (e.g. `"neon-pink"`, `"primary"`), which resolves to the matching
+ * `--sk-<kind>-base/-text` token, or any raw CSS color value (hex, rgb, oklch, named, or
+ * `var(...)`), which is passed through unchanged. This lets consumers use SleekSpace's palette
+ * by name without having to remember the token syntax.
  *
  * Works with any component that follows the CSS variable naming convention:
  * - `--sk-{componentName}-color-base` for the base/background color
  * - `--sk-{componentName}-fg` for the foreground/text color
+ * - `--sk-{componentName}-border-base` / `--sk-{componentName}-border-color` for the border (optional)
  *
- * @param componentName - The component name used in CSS variable naming
- *                        (e.g., 'button', 'panel', 'my-custom-component')
- * @param baseColor - The base/background color (any CSS color value, including CSS variables)
- * @param textColor - Optional foreground/text color. If not provided, falls back to `--sk-neutral-text`
+ * @param componentName - The component name used in CSS variable naming (e.g., 'button', 'panel')
+ * @param baseColor - Kind name or CSS color value for the base/background color
+ * @param textColor - Kind name or CSS color value for the foreground/text color. Falls back to
+ *                    `--sk-neutral-text` when only `baseColor` is provided.
+ * @param borderColor - Optional kind name or CSS color value for the border. When provided,
+ *                      both `--sk-<component>-border-base` and `--sk-<component>-border-color`
+ *                      are emitted so the border takes precedence over any kind's default.
  *
  * @returns Computed style object with CSS variables ready to bind to a component's style attribute
  *
- * @example Basic usage with base color only
+ * @example Kind name shortcut
  * ```vue
- * <script setup>
- * import { useCustomColors } from '@/composables/useCustomColors';
- *
- * const props = defineProps<{ baseColor?: string }>();
- * const customColors = useCustomColors('button', toRef(() => props.baseColor), undefined);
- * </script>
- *
- * <template>
- *   <button :style="customColors">Click me</button>
- * </template>
+ * <SkPanel base-color="neon-pink" text-color="primary" border-color="neon-purple">...</SkPanel>
  * ```
  *
- * @example With both base and text colors
+ * @example Raw CSS values
  * ```vue
- * <SkButton base-color="oklch(0.7 0.25 300)" text-color="white">
- *   Custom Purple Button
- * </SkButton>
+ * <SkButton base-color="oklch(0.7 0.25 300)" text-color="white">Click me</SkButton>
  * ```
- *
- * @example Using CSS variables
- * ```vue
- * <SkPanel base-color="var(--my-custom-color)" text-color="var(--my-text-color)">
- *   Content
- * </SkPanel>
- * ```
- *
- * @example Custom component
- * ```vue
- * <script setup>
- * import { useCustomColors } from '@/composables/useCustomColors';
- *
- * const props = defineProps<{ baseColor?: string; textColor?: string }>();
- * const customColors = useCustomColors('my-widget', toRef(() => props.baseColor), toRef(() => props.textColor));
- * </script>
- *
- * <template>
- *   <div class="my-widget" :style="customColors">
- *     <!-- Will generate: --sk-my-widget-color-base and --sk-my-widget-fg -->
- *   </div>
- * </template>
- * ```
- *
- * Generated CSS variables:
- * - `--sk-{componentName}-color-base` - The base color for backgrounds and accents
- * - `--sk-{componentName}-fg` - The foreground/text color
- *
- * @remarks
- * - If `textColor` is not provided, components will use `--sk-neutral-text` from the active theme
- * - For best contrast, always provide `textColor` when using custom `baseColor`
- * - The generated CSS variables integrate with the component's existing token system
- * - Works with any component name - no need to register components beforehand
  */
 export function useCustomColors(
     componentName : string,
     baseColor : Ref<string | undefined> | string | undefined,
-    textColor : Ref<string | undefined> | string | undefined
+    textColor : Ref<string | undefined> | string | undefined,
+    borderColor ?: Ref<string | undefined> | string | undefined
 ) : Ref<Record<string, string>>
 {
     return computed(() =>
     {
         const styles : Record<string, string> = {};
 
-        // Resolve refs to values
-        const baseColorValue = typeof baseColor === 'string' ? baseColor : baseColor?.value;
-        const textColorValue = typeof textColor === 'string' ? textColor : textColor?.value;
+        const baseResolved = resolveColor(unwrap(baseColor), 'base');
+        const textResolved = resolveColor(unwrap(textColor), 'text');
+        const borderResolved = resolveColor(unwrap(borderColor), 'base');
 
-        // Only apply custom colors if baseColor is provided
-        if(!baseColorValue)
+        if(baseResolved)
         {
-            return styles;
-        }
-
-        // Set the base color CSS variable
-        const baseVarName = `--sk-${ componentName }-color-base`;
-        styles[baseVarName] = baseColorValue;
+            styles[`--sk-${ componentName }-color-base`] = baseResolved;
 
-        // Set or calculate text color
-        const fgVarName = `--sk-${ componentName }-fg`;
-
-        if(textColorValue)
+            // Keep historical contract: when a caller sets baseColor without textColor, fall back
+            // to --sk-neutral-text so text remains legible on arbitrary custom backgrounds.
+            styles[`--sk-${ componentName }-fg`] = textResolved ?? 'var(--sk-neutral-text)';
+        }
+        else if(textResolved)
         {
-            // Use provided text color
-            styles[fgVarName] = textColorValue;
+            styles[`--sk-${ componentName }-fg`] = textResolved;
         }
-        else
+
+        if(borderResolved)
         {
-            // Fallback to the theme's default text color
-            // Users should provide textColor for optimal contrast
-            styles[fgVarName] = 'var(--sk-neutral-text)';
+            // Set both tokens so the override wins regardless of which one the component's
+            // SCSS consults (`--*-border-base` usually drives decorations; `--*-border-color`
+            // drives the actual border).
+            styles[`--sk-${ componentName }-border-base`] = borderResolved;
+            styles[`--sk-${ componentName }-border-color`] = borderResolved;
         }
 
         return styles;

package/src/composables/usePortalContext.test.ts

@@ -2,8 +2,6 @@
 // Portal Context Composable Tests
 //----------------------------------------------------------------------------------------------------------------------
 
-/* eslint-disable vue/one-component-per-file */
-
 import { describe, expect, it } from 'vitest';
 import { defineComponent, h, inject, provide, ref } from 'vue';
 import { mount } from '@vue/test-utils';

package/src/shims.d.ts

@@ -0,0 +1,10 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Module shims
+//
+// Type declarations for side-effect imports and asset modules that TypeScript can't resolve natively.
+//----------------------------------------------------------------------------------------------------------------------
+
+declare module '*.css';
+declare module '*.scss';
+
+//----------------------------------------------------------------------------------------------------------------------